4grayandClaude Opus 4.7 7478ea8665 docs(embedded-mpv): document renderer architecture and reactivity rules ...

Capture the audit findings and refactor outcome in the canonical embedded-mpv
architecture doc so the next person to extend the player does not re-introduce
the same class of regression.

New "Renderer Architecture And Reactivity" section covers:

- The post-refactor file layout (format utils, shortcuts, overlay-visibility,
  ui-state, session-controller, view component) and what each owns.
- The bounds compositing strategy: HIDDEN_BOUNDS for modal overlays,
  partial bottom cutout for control popovers, full host rect otherwise —
  plus why (NSView paints over WebContents, z-index is unwinnable).
- The reactivity rule learned from the audit: any signal read inside an
  effect that feeds a one-shot side effect must be wrapped in untracked().
  Only re-trigger sources stay tracked.
- A short ledger of the four bugs from the audit (support write loop,
  volume-tracked session restart, scheduleControlsHide transitive deps,
  stalled-tracker 2 Hz no-op) so they do not get reintroduced.
- IPC safety notes: gate on sessionId() not session()?.id; guardIpc
  swallows addon-side throws.
- Pointer to the powerSaveBlocker integration.

Also documents the bundle 3 native surface additions (sid, speed,
video-aspect-override observers and exports, capability probe via
EmbeddedMpvSupport.capabilities) so renderers can feature-detect against
older addon binaries.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Entire-Checkpoint: f957cd9849e0

2026-05-05 16:45:17 +02:00

..

architecture

docs(embedded-mpv): document renderer architecture and reactivity rules

2026-05-05 16:45:17 +02:00