From 76359fa29d49b5f6a7331568a5c904364341b629 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 21 Apr 2026 06:17:04 -0700
Subject: [PATCH 1/2] refactor(producer): extract HDR compositing helpers and
 rename media metadata

---
 notes/player-perf-proposal-final.md           | 743 +++++++++++++++
 notes/teaser-learnings.md                     | 857 ++++++++++++++++++
 packages/engine/src/index.ts                  |   1 +
 .../src/services/videoFrameExtractor.ts       |  10 +-
 packages/engine/src/utils/ffprobe.test.ts     |   6 +-
 packages/engine/src/utils/ffprobe.ts          |  17 +-
 packages/producer/src/regression-harness.ts   |   4 +-
 .../producer/src/services/htmlCompiler.ts     |   6 +-
 .../src/services/renderOrchestrator.ts        | 620 ++++++++-----
 packages/producer/src/utils/ffprobe.ts        |   1 +
 .../tests/hdr-hlg-regression/README.md        |   2 +-
 .../tests/hdr-hlg-regression/meta.json        |   2 +-
 plans/hdr-followups.md                        | 396 ++++++++
 13 files changed, 2409 insertions(+), 256 deletions(-)
 create mode 100644 notes/player-perf-proposal-final.md
 create mode 100644 notes/teaser-learnings.md
 create mode 100644 plans/hdr-followups.md

diff --git a/notes/player-perf-proposal-final.md b/notes/player-perf-proposal-final.md
new file mode 100644
index 000000000..0af36b1a5
--- /dev/null
+++ b/notes/player-perf-proposal-final.md
@@ -0,0 +1,743 @@
+# HyperFrames Player — Performance Review & Architecture Proposal
+
+**Author:** James Russo
+**Revised by:** Vance Ingalls
+**Date:** 2026-04-20
+**Scope:** `packages/player` + `packages/core/src/runtime` + studio consumer
+**Status:** Final draft
+
+---
+
+## TL;DR
+
+The preview player's dominant perf costs for video/image-heavy compositions are (1) a non-vsync 50 ms `setInterval` as the runtime master clock, (2) `el.currentTime` drift correction that thrashes video decoders, (3) parent-proxy promotion that creates `<video>` elements where `<audio>` elements may suffice — potentially doubling decoder pressure (needs validation), and (4) asynchronous postMessage seek that forces studio to bypass the official bridge entirely.
+
+The iframe boundary is **not** the bottleneck and remains the right choice for **public embeds** (untrusted hosts). For the **studio preview**, we should add a second `mode="inline"` that mounts compositions directly into the player's Shadow DOM — making seek synchronous, eliminating the audio-owner protocol for same-origin, and collapsing two compositor layer trees into one.
+
+> **Caveat:** This analysis is code-reading, not profiling. Before landing any fix, validate with the traces specified in the Validation Plan. Each phase has concrete pass/fail SLOs — don't proceed to the next phase without hitting them.
+
+---
+
+## How the current pipeline works
+
+1. `<hyperframes-player>` custom element creates a Shadow DOM containing an `<iframe sandbox="allow-scripts allow-same-origin">` with the composition HTML.
+
+2. Inside the iframe, the core runtime installs a `setInterval(…, 50)` poll (`core/src/runtime/init.ts:1502-1561`) that:
+   - Calls `syncCurrentTimeFromTimeline()` — reads the GSAP timeline position.
+   - Calls `syncMediaForCurrentState()` (if playing) — iterates all `<video>`/`<audio>` elements, compares `el.currentTime` to expected, corrects drift.
+   - Calls `postState(false)` — sends `window.parent.postMessage({source:"hf-preview", type:"state", …})`, throttled by `bridgeMaxPostIntervalMs: 80` (`core/src/runtime/state.ts:67`).
+   - Calls `postTimeline()` every 20th tick (~once per second).
+
+3. Parent listens for state messages, throttles UI updates to ~12 Hz, dispatches a `timeupdate` event.
+
+4. Control flows (play/pause/seek) are **asynchronous**: parent `postMessage` → iframe bridge (`bridge.ts:22-71`) dispatches to handlers → next 50 ms tick → parent receives `state` → UI updates. Round-trip >= 50–100 ms.
+
+5. The outer iframe is scaled with `transform: translate(-50%, -50%) scale(S)` to fit the container (`player/src/hyperframes-player.ts:530`).
+
+6. Studio (same-origin) **bypasses postMessage entirely** and reads `iframe.contentWindow.__player` directly (with fallback to `__timelines`) for its own rAF loop (`studio/src/player/hooks/useTimelinePlayer.ts:233-239`). This is a strong signal that the official bridge is too slow for tight UI.
+
+7. When autoplay is blocked, the runtime sends a `media-autoplay-blocked` message. The parent responds by "promoting" to parent-proxy ownership: it creates mirror `<video>`/`<audio>` elements for every `<video data-start>`/`<audio data-start>` in the iframe, preloaded at iframe-ready time (`player/src/hyperframes-player.ts:703-718`). The iframe runtime mutes its output; the parent proxies handle audible playback. **Both** the iframe video and the parent video decode simultaneously.
+
+---
+
+## Concrete bottlenecks
+
+### 1. `setInterval(50 ms)` as the master clock
+
+`core/src/runtime/init.ts:1502-1561`. Not vsync-aligned — on 60/120 Hz displays, ticks land at arbitrary points in the frame, producing beat-frequency stutter. Every tick unconditionally runs `syncCurrentTimeFromTimeline()`; `syncMediaForCurrentState()` is gated on `isPlaying` (line 1557). The per-tick media iteration is the dominant cost for 10-video grids because each clip's `currentTime` read/compare runs on every active element.
+
+**Backgrounding concern:** When replacing with rAF, note that `requestAnimationFrame` stops firing when the tab is hidden (Page Visibility API). The current `setInterval` also throttles to ~1 Hz when backgrounded, but it doesn't stop entirely. The fix must include a fallback interval for keep-alive when the page is not visible.
+
+### 2. Drift correction thrashes decoders
+
+`core/src/runtime/media.ts:160-174`. The correction logic has three thresholds:
+- **0.5 s "hard" threshold** (line 166): `offsetJumped = Math.abs(offset - prevOffset!) > 0.5`
+- **`firstTickOfClip`** (line 165): forces a resync when `prevOffset === undefined` — painful for compositions with many sub-compositions that activate/deactivate clips frequently.
+- **3 s "catastrophic" threshold** (line 167): forces correction regardless of other conditions.
+
+Repeated `el.currentTime = relTime` writes (line 170) trigger decode-pipeline flushes. The 0.5 s threshold helps steady-state, but `firstTickOfClip` fires on every sub-composition entry.
+
+### 3. Seek is async through postMessage
+
+No same-frame UI feedback on a scrub. Studio works around it with direct `__player` access (`useTimelinePlayer.ts:233`), which only works same-origin. External embeds using the public API will feel laggy.
+
+### 4. Parent-proxy `<video>` doubles decoders unnecessarily
+
+`_adoptIframeMedia` (`player/src/hyperframes-player.ts:725-756`) mirrors `<video data-start>` into a parent `<video>`. The proxy exists **only for audio output** — the visual stays in the iframe. But creating a `<video>` element forces a second video decoder even though only the audio track is needed.
+
+For a 5-video composition promoted to parent ownership, that's 10 simultaneous video decoders when 5 video + 5 audio would suffice.
+
+**Note:** The proxy system itself is well-designed — preloading at iframe-ready time gives tight audio cut-in on promotion, one-way ownership prevents thrashing, and the 50 ms mirror drift threshold is ITU-compliant. The fix is narrow: use `<audio>` elements for video-source proxies.
+
+### 5. MutationObserver on full iframe body subtree
+
+`player/src/hyperframes-player.ts:803` — `obs.observe(doc.body, { childList: true, subtree: true })`. For image/video-heavy compositions with dynamic CSS/DOM, this fires constantly for mutations unrelated to media adoption.
+
+### 6. `postState` fires at up to ~12–15 Hz during playback
+
+`bridgeMaxPostIntervalMs: 80` (`core/src/runtime/state.ts:67`). Each hop serializes/deserializes, wakes the parent event loop, runs `_mirrorParentMediaTime` which loops through all proxies. Cost scales linearly with proxy count.
+
+### 7. `document.querySelectorAll("video[data-start], audio[data-start]")` re-run frequently
+
+`core/src/runtime/media.ts:23`. Cached in state but invalidated on sub-composition activation. Not catastrophic, but unnecessary churn in compositions with many clips.
+
+### 8. Per-instance shadow stylesheet
+
+`PLAYER_STYLES` is a raw CSS string (`player/src/styles.ts:1-198`) injected via `style.textContent = PLAYER_STYLES` per player instance (`player/src/hyperframes-player.ts:88`). In studio panels with thumbnails (multiple `<hyperframes-player>` nodes), this creates N duplicate `<style>` elements. `adoptedStyleSheets` with a shared `CSSStyleSheet` would eliminate the copies.
+
+### 9. Full iframe reload on every composition switch
+
+Setting `iframe.src` triggers a fresh HTML parse + script load + runtime bootstrap + full teardown of prior state (`player/src/hyperframes-player.ts:385-410`). Studio mounts a separate iframe per thumbnail — the expensive path repeated N times per project.
+
+### 10. Outer `transform: scale()` — likely a non-issue
+
+The iframe is scaled with `transform: translate(-50%, -50%) scale(S)` (`player/src/hyperframes-player.ts:530`). The original draft speculated this might inhibit hardware video overlay promotion. However, Chromium's `OverlayProcessor` promotes when the transform decomposes to a 2D axis-aligned translate/scale, which this transform does. Overlay promotion is more commonly blocked by non-axis-aligned transforms, blend modes, filters, or clip-path — none of which apply here.
+
+**Recommendation:** Verify with a `chrome://gpu` trace in Phase 0. If confirmed as a non-issue (expected), remove from the action list. If the trace shows unexpected layer behavior, revisit.
+
+---
+
+## Recommended actions (ordered by impact-per-effort)
+
+### 1. Replace the 50 ms `setInterval` with `requestAnimationFrame`
+
+During `isPlaying`, use rAF for vsync-aligned ticks. Add a 250 ms `setInterval` fallback for:
+- **Paused keep-alives** — the player still needs to post state occasionally.
+- **Hidden-tab fallback** — rAF stops firing when `document.hidden === true`. Listen for `visibilitychange` to swap between rAF and interval.
+- **Headless capture** — the producer package runs under Puppeteer's virtual time and already replaces `window.requestAnimationFrame` wholesale with a virtual-time queue (`producer/src/services/fileServer.ts:104-117`). Guard with `window.__HF_VIRTUAL_TIME__ === undefined` and fall back to the existing `setInterval` path. This makes the rAF swap safer than it might seem — producer intercepts rAF at a higher level — but the guard ensures the runtime's own fallback is explicit.
+
+**Interaction with Action #2:** Moving from 20 Hz (50 ms interval) to 60 Hz (rAF) means 3x more ticks. This is fine because Action #2 removes the expensive per-tick work (drift polling). Without Action #2, rAF alone would *increase* per-tick cost. **These two actions must ship together in Phase 2.**
+
+### 2. Use `requestVideoFrameCallback()` to measure drift, not per-tick polling
+
+RVFC fires when a video frame has been composited, exposing `metadata.mediaTime` — the actual presented media time. Replace the per-tick `el.currentTime` read/compare with an RVFC-driven observation:
+
+```
+function onVideoFrame(now, metadata) {
+  const drift = Math.abs(metadata.mediaTime - expectedMediaTime);
+  if (drift > 0.5) el.currentTime = expectedMediaTime;
+  el.requestVideoFrameCallback(onVideoFrame);
+}
+```
+
+This cuts per-tick media iteration cost to zero for RVFC-capable elements during active playback. `<audio>` elements and older browsers fall back to the existing per-tick path.
+
+**State-transition gap:** RVFC only fires while the video is actively playing and presenting frames. It does **not** fire during pause, seek-while-paused, clip activation/deactivation, or pre-start. The per-tick polling path must remain active for these state transitions — RVFC replaces steady-state drift observation, not the full media sync loop. Specifically: `firstTickOfClip` resyncs and seek corrections still run through the interval/rAF tick path.
+
+**Browser support:** RVFC is available in Chrome 83+, Edge 83+, Safari 15.4+, Firefox 132+. No iOS Safari support below 15.4. Check the player's browser support baseline — if it includes older Safari, the fallback path must remain robust.
+
+### 3. Use `<audio>` for video-source proxies (hypothesis — gated on Phase 0)
+
+**Hypothesis:** In `_createParentMedia` (`player/src/hyperframes-player.ts:656-675`), parent proxies for `<video>` sources could use `<audio>` elements instead of `<video>` elements, since the proxy only needs audio output — the visual stays in the iframe. If browsers reliably decode audio from video containers (MP4/H.264+AAC, WebM/VP9+Opus) via `<audio>`, this would halve decoder pressure under parent-proxy promotion.
+
+**Why this needs validation, not assumption:** The current proxy system is an intentional separation of concerns — the iframe video handles visuals, the parent video handles audio. The `<video>` tag in the parent ensures decoder-state parity with the iframe's media timeline. On mobile, video codec state can be tightly coupled with power management, and `<audio src="video.mp4">` may not reliably extract the audio track on all platforms. If A/V sync regresses or decoder-count reduction doesn't materialize, keep the current design.
+
+**Phase 0 gate:** Test `<audio src="video.mp4">` playback on Chrome desktop, Chrome Android, Safari desktop, and Safari iOS with 5 representative composition videos. Measure decoder count (`webkitDecodedFrameCount`) and A/V sync drift. Only proceed if decoder count drops and sync holds within 50 ms on all platforms.
+
+**Do NOT use `document.adoptNode` to transfer `<video>` elements from the iframe.** Adopting a playing `<video>` into a different document resets the decoder pipeline, causing a rebuffer.
+
+### 4. Share the player stylesheet via `adoptedStyleSheets`
+
+One `CSSStyleSheet` constructed with `new CSSStyleSheet()`, populated with `PLAYER_STYLES`, assigned to every player shadow root via `shadowRoot.adoptedStyleSheets = [sharedSheet]`. Eliminates N duplicate `<style>` elements in studio's thumbnail grid.
+
+### 5. Scope the MutationObserver to `[data-composition-id]` host nodes
+
+Instead of `doc.body` with `{ childList: true, subtree: true }`, observe only the composition host elements. This reduces mutation callbacks to composition-relevant DOM changes.
+
+In inline mode (Phase 4), the MutationObserver for media adoption becomes unnecessary — media elements are already in the parent document.
+
+### 6. Expose a synchronous `seek()` on the public player API
+
+Studio already does this privately via `iframe.contentWindow.__player`. Formalize it:
+
+```
+// On the <hyperframes-player> element
+player.seek(frame)  // synchronous when same-origin
+player.seek(frame)  // async fallback when cross-origin (postMessage bridge)
+```
+
+Detect same-origin access with a try/catch on `iframe.contentWindow` access. External cross-origin embeds fall back to the async bridge transparently.
+
+### 7. Fast composition switching
+
+Two complementary strategies:
+
+**7a. `srcdoc` for studio (no network round-trip):** Studio already has composition HTML as a string. Use `iframe.srcdoc = compositionHtml` instead of `iframe.src = url`. This eliminates the network fetch and is faster than a pool for single-composition switches.
+
+**7b. Warm iframe pool (optional, for rapid switching):** For cases where the user rapidly switches between compositions (project browser), maintain a pool of up to **3 warm iframes** (LRU by composition-id). **Exclude thumbnail grids** — thumbnails should use static screenshots, not live iframes.
+
+Each warm iframe retains a full runtime + adapters + GSAP (+ potentially Three/Lottie), so memory pressure is real. Enforce a hard cap and evict the least-recently-used iframe when the cap is hit. Monitor total iframe memory in Phase 0 to validate the cap.
+
+### 8. Coalesce `_mirrorParentMediaTime` writes
+
+Tighten the threshold: only write `el.currentTime` when drift is *trending* (consecutive readings above threshold), not on a single spike. This reduces seek thrash during transient jitter without loosening the steady-state sync guarantee.
+
+---
+
+## Architectural alternative: two-mode player
+
+The iframe exists for two reasons — **CSS isolation** (composition CSS doesn't leak to host) and **script isolation** (composition `<script>` doesn't touch host globals). In 2026, Shadow DOM handles CSS isolation fully; ES-module scoping handles script isolation for format-constrained compositions.
+
+### `mode="isolated"` (iframe — current default)
+
+What public embeds use. Keeps untrusted composition scripts sandboxed in a separate realm. The iframe's `window` global is distinct from the host page's.
+
+### `mode="inline"` (shadow DOM, no iframe)
+
+What studio and first-party hosts use.
+
+- Composition HTML is parsed into a `<template>`, cloned into the player's shadow root.
+- Runtime runs in the parent realm — **no postMessage, synchronous** `play`/`pause`/`seek`.
+- `<video>` elements are real siblings of the host page — user activation propagates same-frame, eliminating the autoplay-gate and the entire parent-proxy promotion path.
+- GSAP timelines are reached directly — studio's `__player` pattern becomes the public API.
+- Compositing is one layer tree, not two.
+
+### Security model
+
+**The trust boundary must be explicit.** A same-origin iframe is a separate realm-of-scripts — it prevents a composition from accidentally calling `window.location.assign` or accessing host cookies. Inline mode removes that boundary.
+
+Three trust levels:
+
+| Level | Mode | When |
+|-------|------|------|
+| **Untrusted** | `isolated` (iframe) | Third-party embeds, user-shared compositions |
+| **Format-constrained** | `inline` with validation gate | Studio preview of compositions that pass the linter and contain only registered adapters (GSAP, Lottie, Three.js) — no arbitrary `<script>` tags |
+| **Fully trusted** | `inline` without gate | First-party compositions authored by the studio's own generator pipeline |
+
+**Implementation:** Add a `canRunInline(compositionHtml): boolean` gate. Parse the HTML with linkedom (already a dependency via `htmlBundler.ts`) and reject if any of these fail:
+
+1. **Script allowlist:** Every `<script src>` URL must match the registered CDN allowlist (GSAP `cdn.jsdelivr.net/npm/gsap@3`, Lottie, Three.js — enumerated, not pattern-matched). Unknown external scripts → reject.
+2. **Inline script denylist check:** Scan each inline `<script>` body for dangerous patterns. This is a denylist approach (reject known-bad) rather than an allowlist AST parse, because compositions legitimately use `addEventListener`, `IntersectionObserver`, `requestAnimationFrame`, `MutationObserver`, `CustomEvent`, and dynamic `document.createElement` for Three.js scenes, scroll-linked animations, and Lottie setup. Reject scripts containing: `fetch(`, `XMLHttpRequest`, `import(`, `eval(`, `Function(`, `document.cookie`, `localStorage`, `sessionStorage`, `window.location`, `window.parent`, `window.top`, `window.opener`, `postMessage(` (outside the runtime bridge). Use a regex scan — adding a JS parser dependency (no JS parser exists in the project today) is not justified for a denylist.
+3. **No inline event handlers:** Reject elements with `on*` attributes (`onclick`, `onerror`, `onload`, etc.).
+4. **Linter pass:** No `external_script_dependency` warnings on unknown scripts.
+
+Compositions that fail the gate fall back to `isolated` mode automatically. This makes inline mode safe-by-default. The gate runs at composition-load time, not per-frame — the cost is a single parse per composition switch.
+
+**Composition scripts also need IIFE wrapping at compile time** — the bundler already does this (`core/src/runtime/compositionLoader.ts:206`), but inline mode must ensure the wrapping applies in the parent realm too, preventing global leakage.
+
+### Runtime refactoring scope
+
+The runtime currently makes **30+ `document.*` queries, sets 7 `window.*` globals, registers 5 window event listeners, and communicates via `window.parent.postMessage`** across ~12 source files (`init.ts`, `bridge.ts`, `media.ts`, `state.ts`, `timeline.ts`, `entry.ts`, `picker.ts`, `compositionLoader.ts`, and 5 adapter files`).
+
+Making the runtime realm-agnostic requires:
+
+1. **Scope injection** — every `document.querySelector*` call takes a `root` parameter (either `document` or a `ShadowRoot`). Every `window.*` global becomes a property on a context object passed at init time.
+
+2. **Bridge abstraction** — `postRuntimeMessage` calls a callback instead of `window.parent.postMessage`. In iframe mode, the callback is postMessage. In inline mode, it's a direct function call.
+
+3. **Adapter scoping** — CSS adapter's `document.querySelectorAll("*")` and WAAPI adapter's `document.getAnimations()` must scope to the composition root. Lottie and Three.js adapters read `window.__hfLottie` / `window.__hfThreeTime` — these become context properties.
+
+4. **Picker machinery** — the picker uses `document.elementsFromPoint()`, `document.body.classList`, and captures document-level mouse/keyboard events. In inline mode, these must scope to the shadow root. `elementsFromPoint` specifically needs to be called on the shadow root (`shadowRoot.elementsFromPoint`), which is supported in modern browsers.
+
+5. **Multi-instance isolation** — multiple inline players on the same page must not collide. The current `window.__timelines` registry is keyed by composition ID — but in studio, the same composition can be open in multiple panels (preview + scene editor). Same composition ID, two inline players, one `__timelines` registry = the second instance overwrites the first's timeline. **`__timelines` must move out of the global scope and into the per-instance `RuntimeContext`.** This is load-bearing for Phase 4.
+
+**Estimated scope:** ~500-800 LOC of refactoring across 12 files to introduce a `RuntimeContext` interface, plus adapter updates and picker scoping. The heaviest lift is `init.ts` (~1650 lines) which concentrates most of the `window.*` and `document.*` references. The picker machinery (`picker.ts`) is the second-heaviest due to its `elementsFromPoint`, event capture, and style injection patterns.
+
+---
+
+## What not to do (yet)
+
+- **Full WebCodecs + OffscreenCanvas rewrite.** Throws away the "HTML *is* the composition" premise. CSS animations, nested iframes, Lottie, Three.js, and text layout stop working in a canvas. Reserve for a separate rendering backend used only for export (producer already lives there).
+
+- **`AudioContext` mixer for all audio.** A `MediaElementAudioSourceNode` wrapper could aggregate cleanly for the asset-URL case. But don't aggregate until profiling confirms per-element decoder count is actually the bottleneck after Action #3 (audio-only proxies) ships.
+
+---
+
+## Proposed rollout order
+
+### Phase 0 — Measure and establish baselines (~0.5 week)
+
+Capture the traces listed in the Validation Plan on a representative 10-video composition. **Do not start Phase 1 until the traces confirm the bottleneck claims.**
+
+**Pass/fail SLOs for each subsequent phase:**
+
+Phase 0 will establish current baselines (the "est." column below). Absolute targets are UX-motivated and hold regardless of baseline.
+
+| Metric | Current (est.) | Phase 2 target | Phase 4 target |
+|--------|---------------|----------------|----------------|
+| Scrub latency (same-origin) | ~100 ms | p50 < 50 ms, p95 < 80 ms | p50 < 16 ms, p95 < 33 ms |
+| Scrub latency (cross-origin) | ~100 ms | p50 < 80 ms, p95 < 120 ms | p50 < 50 ms, p95 < 80 ms |
+| Composition switch (warm) | ~1500 ms | < 800 ms | < 300 ms |
+| Composition switch (cold) | ~2000 ms | < 1500 ms | < 1500 ms (< 2000 ms for heavy*) |
+| Sustained fps (10-video) | ~30-45 fps | 60 fps | 60 fps |
+| Decoder count under promotion | 2N | N (if Action #3 validates) | 0 (no promotion) |
+| Dropped frames (10s playback) | TBD | < 5 | < 2 |
+
+\* "Heavy" = compositions with Three.js + Lottie + WebGL context + >5 MB total assets. These have irreducible cold-start costs (WebGL context init, large asset decode) that inline mode doesn't eliminate.
+
+### Phase 1 — Low-risk wins (~1 week, no API change)
+
+- `adoptedStyleSheets` for shared player styles
+- Scoped MutationObserver
+- Audio-only proxy prototype (`<audio>` for video-source parent media) — validate on 4 browser/OS combos. Ship only if decoder count drops and A/V sync holds.
+- Coalesced `_mirrorParentMediaTime` writes
+- Verify outer-transform overlay-promotion hypothesis via `chrome://gpu` trace (expected: non-issue, close the item)
+
+**Phase 1 validation:** Mirror write frequency drops by >50%. If audio-only proxy validates, decoder count under promotion drops to N.
+
+### Phase 2 — Runtime clock + RVFC (~1–2 weeks)
+
+- Replace `setInterval` with rAF (with visibility-change fallback and headless guard)
+- RVFC-driven drift observation (ships together with rAF — see interaction note in Action #1)
+- Producer parity regression suite run on day one
+
+**Phase 2 validation:** 60 fps sustained on 10-video comp. Dropped frames < 5 per 10s. Producer parity harness green.
+
+### Phase 3 — Synchronous seek + fast switching (~1–2 weeks)
+
+- Synchronous `seek()` API on the player element (same-origin detection)
+- `srcdoc` composition switching for studio
+- Optional warm iframe pool (cap at 3, LRU, exclude thumbnails)
+
+**Phase 3 validation:** Scrub latency < 50 ms same-origin. Composition switch < 800 ms warm.
+
+### Phase 4a — Inline mode behind flag, studio-only (~5–7 weeks for 1 engineer, ~3–4 weeks for 2)
+
+**Staffing assumption:** The scope splits naturally into (A) runtime/adapters (RuntimeContext, bridge abstraction, adapter scoping — concentrated in `core/`) and (B) player/gate/studio (inline player mode, `canRunInline()`, studio wiring — concentrated in `player/` and `studio/`). Two engineers with clear file-ownership can parallelize.
+
+- `RuntimeContext` interface: scope injection for all `document.*` / `window.*` references
+- Bridge abstraction (direct callback in inline mode)
+- Adapter scoping (GSAP, Lottie, Three.js, CSS, WAAPI)
+- Multi-instance isolation: move `window.__timelines` into per-instance `RuntimeContext` (same composition ID in two inline players must not collide)
+- `canRunInline()` composition validation gate
+- Shadow DOM CSS compatibility validation:
+  - `@font-face` declarations — Chrome requires these in the document, not the shadow root. Compositions using custom fonts need font-face rules hoisted to the document at mount time.
+  - `vh`/`vw` units resolve against the viewport, not the composition container. Compositions using viewport-relative units need transformation to container-relative units (or CSS `cqi`/`cqb` with container queries).
+  - `:root` selectors target the document root, not the shadow host. Compositions using `:root { --custom-prop: ... }` need selector rewriting to `:host`.
+- Inline player mode wired up behind `__HF_INLINE_PLAYER` feature flag
+- Studio opts in for preview panel only (not thumbnails)
+
+**Phase 4a validation:** Studio preview works in inline mode for 5 representative compositions (including at least one with custom fonts and one with viewport-relative units). Scrub latency p50 < 16 ms. No autoplay-proxy path triggered. Feature flag can be toggled without reload.
+
+### Phase 4b — Inline mode as studio default (~2–3 weeks)
+
+- Remove feature flag, inline is default for studio
+- Migrate all studio call sites (preview, scene editor, export preview)
+- Thumbnails remain iframe-based (static screenshot preferred)
+- Producer compat shim (producer continues using iframe/headless path, unaffected)
+- Public API stabilization: `<hyperframes-player mode="inline|isolated">`
+
+**Phase 4b validation:** All studio E2E tests pass. No regressions in public embed path. Memory usage in studio < 1.2x current with 10+ compositions open.
+
+---
+
+## Producer impact
+
+`packages/producer` consumes `@hyperframes/core`'s runtime for headless rendering via Puppeteer. `producer/src/services/renderOrchestrator.ts` and the parity harness (`producer/src/parity-harness.ts`) both bind against `__timelines`.
+
+**What's affected:**
+
+- **Phase 2 (rAF clock):** Headless rendering drives time virtually (seek-per-frame). rAF firing semantics under Puppeteer's virtual time differ from live playback. Producer already replaces `window.requestAnimationFrame` with a virtual-time queue (`fileServer.ts:104-117`), but the runtime's own `__HF_VIRTUAL_TIME__` guard provides an explicit fallback to `setInterval`.
+- **Phase 4 (`RuntimeContext`):** Producer imports the IIFE runtime bundle. The `RuntimeContext` refactor must preserve the existing default export where `root = document` and `globals = window`. Producer never uses inline mode.
+
+**Mitigation:** Run the producer parity harness as a CI gate on every Phase 2+ PR. If the harness doesn't cover the clock/media-sync paths (verify in Phase 0), extend it before starting Phase 2.
+
+---
+
+## Validation plan (run before landing fixes)
+
+### Pre-land traces (Phase 0)
+
+1. **Chrome Performance profile** on a representative 10-video composition during 10s of playback. Confirm the 50 ms tick is actually hot and that drift-correction `currentTime` writes show up as decoder flushes. Record CPU time in the setInterval callback.
+
+2. **Decoder-count trace** — log `video.webkitDecodedFrameCount` and `video.webkitDroppedFrameCount` per-clip before and after promotion to parent-proxy audio ownership. Confirms the "double decoder" claim under autoplay-block. Test with `<audio src="video.mp4">` to validate the audio-only proxy approach.
+
+3. **Composited-layers dump** (`chrome://gpu` + `chrome://tracing` with `cc,viz` categories) to confirm or reject the outer-transform overlay-promotion hypothesis. **Expected result: non-issue.** Document and close.
+
+4. **Scrub latency** — record timestamp from `mousedown` on scrubber to first frame update in the preview, under both cross-origin (public) and same-origin (studio) paths. Establishes the "synchronous seek" benefit numerically.
+
+5. **Composition-switch time** — record iframe `load` → `ready` for 5 representative compositions. Baseline for the fast-switch proposal. Compare `iframe.src` vs `iframe.srcdoc` for studio's case.
+
+6. **Memory profile** — measure per-iframe memory overhead with a representative composition (runtime + GSAP + adapters). Establishes the memory cap for the warm iframe pool. If per-iframe cost is >50 MB, pool size may need to be capped at 2 instead of 3.
+
+7. **RVFC browser coverage** — verify `requestVideoFrameCallback` availability across the player's supported browser matrix. Identify which browsers fall back to per-tick polling and ensure the fallback path remains correct.
+
+8. **Composition corpus audit for `canRunInline()`** — run the proposed denylist gate against 20 representative shipped compositions (GSAP-only, GSAP+Lottie, Three.js scenes, audio-reactive, etc.). Report the pass/fail rate. If fewer than 70% of studio-authored compositions pass, the denylist is too aggressive and needs tuning before Phase 4a.
+
+9. **Producer parity harness coverage check** — the existing parity harness (`producer/src/parity-harness.ts`) uses synchronous `renderSeek()` per-frame, which bypasses the interval/rAF clock entirely. It proves frame-accurate rendering but does **not** validate live-playback timing, media sync cadence, or state posting under the new clock. Phase 2 requires a separate **live-playback regression test**: play a 10-second composition end-to-end, assert dropped frames < 5 and A/V sync drift < 50 ms. Build this test in Phase 0 so it's ready when Phase 2 starts.
+
+Store raw Phase 0 traces alongside this doc under `notes/traces/player-perf-2026-04/`.
+
+---
+
+## Automated performance tests
+
+PostHog telemetry catches regressions in production after deploy. Automated perf tests catch them in CI before merge. We need both.
+
+### What exists today
+
+The producer already has a perf gate pattern we can follow:
+
+- **`producer/src/benchmark.ts`** — runs each test fixture multiple times, records per-stage timing, saves to `tests/perf/benchmark-results.json`.
+- **`producer/src/perf-gate.ts`** — compares measured time against `tests/perf/baseline.json` (currently 90s max, 15% regression tolerance). Fails CI if exceeded.
+- **`producer/src/parity-harness.ts`** — synchronous seek-per-frame rendering. Proves frame accuracy but doesn't exercise live-playback timing.
+
+The player has no perf tests of any kind.
+
+### Proposed test suite
+
+All tests run in headless Chromium via Playwright (already a dev dependency for studio E2E). Each test loads a composition in a `<hyperframes-player>` element, exercises a specific operation, and asserts timing against a baseline.
+
+#### Test 1: Playback frame rate (`player-perf-fps`)
+
+```
+Load 10-video composition → play for 5 seconds → collect rAF tick count + dropped frames
+Assert: fps >= 55 (allow 8% drop from 60), dropped frames < 3
+```
+
+**What it catches:** rAF clock regressions, per-tick work bloat, media sync overhead.
+
+Runs in both `isolated` (iframe) and `inline` (shadow DOM, Phase 4+) modes.
+
+#### Test 2: Scrub latency (`player-perf-scrub`)
+
+```
+Load composition → seek to 10 positions in sequence → measure time from seek() call to state update callback
+Assert: p95 < 80ms (isolated), p95 < 33ms (inline, Phase 4+)
+```
+
+**What it catches:** Bridge latency regressions, seek path overhead, state posting delays.
+
+#### Test 3: Composition load time (`player-perf-load`)
+
+```
+Set player src to 5 different compositions in sequence → measure per-composition load → ready time
+Assert: p95 < 2000ms cold, p95 < 1000ms warm (with srcdoc, Phase 3+)
+```
+
+**What it catches:** Runtime bootstrap regressions, iframe pool issues, srcdoc path regressions.
+
+#### Test 4: Media sync drift (`player-perf-drift`)
+
+```
+Load 5-video composition → play for 10 seconds → on each RVFC callback, record drift between expected and actual media time
+Assert: max drift < 500ms, p95 drift < 100ms
+```
+
+**What it catches:** RVFC fallback regressions, drift correction threshold issues, clock/media desync.
+
+#### Test 5: Live-playback parity (`player-perf-live-parity`)
+
+This is the test missing from the producer harness. It exercises the **live clock path** (rAF/interval), not the synchronous seek-per-frame path:
+
+```
+Load composition → play from start to end (10s) → compare final frame against producer's reference screenshot
+Assert: SSIM > 0.95 (structural similarity), A/V drift < 50ms at end
+```
+
+**What it catches:** Any divergence between the live-playback clock and the producer's deterministic clock. This is the Phase 2 safety net.
+
+### Test fixtures
+
+Create `player/tests/perf/fixtures/` with 3 representative compositions:
+
+| Fixture | Content | Purpose |
+|---------|---------|---------|
+| `10-video-grid` | 10 overlapping video clips, GSAP stagger | Stress test for decoder count, media sync, fps |
+| `gsap-heavy` | 50+ animated elements, timeline with 200 tweens, no media | Stress test for GSAP seek performance |
+| `sub-compositions` | 3 nested sub-compositions with their own timelines | Stress test for `firstTickOfClip` resync, MutationObserver |
+
+### Baselines
+
+Follow the producer's pattern: store baselines in `player/tests/perf/baseline.json`:
+
+```json
+{
+  "fps_min": 55,
+  "scrub_latency_p95_isolated_ms": 80,
+  "scrub_latency_p95_inline_ms": 33,
+  "comp_load_cold_p95_ms": 2000,
+  "comp_load_warm_p95_ms": 1000,
+  "drift_max_ms": 500,
+  "drift_p95_ms": 100,
+  "allowed_regression_ratio": 0.10
+}
+```
+
+The perf gate script compares each measured value against `baseline * (1 + allowed_regression_ratio)`. Update baselines after each phase lands (Phase 0 establishes the first set, each subsequent phase tightens them).
+
+### CI integration
+
+Add a `player:perf` script to the root `package.json`:
+
+```
+bun run player:perf   # runs all 5 tests, outputs JSON, exits non-zero on regression
+```
+
+Run in CI on every PR that touches `packages/player/` or `packages/core/src/runtime/`. Not on every PR — Playwright + Chromium is ~30s overhead that shouldn't gate unrelated changes.
+
+### When to update baselines
+
+- **After Phase 0:** Initial baselines from measured current state.
+- **After each phase lands:** Tighten baselines to the new measured values (the improvement becomes the new floor).
+- **Never loosen baselines** without an explicit decision and comment in the baseline file explaining why.
+
+### Implementation: PR P0-1 (revised)
+
+PR P0-1 now covers both the live-playback parity test AND the full perf test suite:
+
+1. `player/tests/perf/` — test runner, 5 test files, 3 fixtures, baseline.json
+2. `player/tests/perf/perf-gate.ts` — baseline comparison (same pattern as `producer/src/perf-gate.ts`)
+3. Root `package.json` — add `player:perf` script
+4. CI config — gate on `packages/player/**` and `packages/core/src/runtime/**` changes
+
+---
+
+## Performance observability
+
+### Current state
+
+Two telemetry paths exist today, neither covers player performance:
+
+1. **CLI telemetry** (`cli/src/telemetry/client.ts`) — lightweight PostHog client using the HTTP batch API directly (no SDK). Anonymous, opt-in, fire-and-forget. Tracks CLI command usage only. Uses PostHog project key `phc_zjjb…`.
+
+2. **Runtime analytics bridge** (`core/src/runtime/analytics.ts`) — vendor-agnostic. The runtime emits structured events via postMessage (`{ source: "hf-preview", type: "analytics", event, properties }`). The host app listens and forwards to its own analytics provider. Today this covers 6 discrete events: `composition_loaded`, `composition_played`, `composition_paused`, `composition_seeked`, `composition_ended`, `element_picked`. No performance metrics.
+
+3. **Player package** — no telemetry of any kind.
+
+### What we need
+
+Continuous performance metrics flowing to PostHog so we can:
+- Verify each phase actually improved the target metric
+- Detect regressions after deploy
+- Compare performance across browser/OS/hardware segments
+- Track inline mode adoption and its impact (Phase 4+)
+
+### Architecture
+
+Extend the existing runtime analytics bridge with a `performance` message type. The player (as the host) listens, aggregates per-session, and flushes to PostHog using the same lightweight HTTP batch pattern as the CLI — no PostHog SDK needed.
+
+```
+                    ┌─────────────────────────────────┐
+                    │  iframe (core/runtime)           │
+                    │                                  │
+                    │  performance.mark("hf:seek:start")
+                    │  performance.measure(...)        │
+                    │  postMessage({ type: "perf" })  ─┼──┐
+                    └─────────────────────────────────┘  │
+                                                         │ postMessage
+                    ┌─────────────────────────────────┐  │
+                    │  player (host)                   │◄─┘
+                    │                                  │
+                    │  Aggregates per-session metrics  │
+                    │  Flushes to PostHog on:          │
+                    │    - composition_ended            │
+                    │    - page unload (sendBeacon)     │
+                    │    - 60s idle timeout             │
+                    └──────────────┬──────────────────┘
+                                   │ HTTP POST (batch API)
+                    ┌──────────────▼──────────────────┐
+                    │  PostHog (us.i.posthog.com)      │
+                    │  Same project as CLI telemetry   │
+                    └─────────────────────────────────┘
+```
+
+In inline mode (Phase 4), there's no iframe boundary — the runtime emits directly to the player's aggregator via the `RuntimeContext.bridge` callback.
+
+### Metrics
+
+| Metric | Event name | Collection point | When emitted | Phase |
+|--------|-----------|-----------------|--------------|-------|
+| Scrub latency | `player_scrub_latency` | Player: `mousedown` → first state update | End of each scrub gesture | 1+ |
+| Playback fps | `player_playback_fps` | Runtime: rAF tick count / elapsed time | Every 5s during playback, and on pause/end | 2+ |
+| Dropped frames | `player_dropped_frames` | Runtime: `video.webkitDroppedFrameCount` delta | On composition_ended | 2+ |
+| Decoder count | `player_decoder_count` | Player: count of active `<video>` + `<audio>` elements | On promotion to parent-proxy | 1+ |
+| Composition load time | `player_comp_load` | Player: iframe `load` → runtime `ready` | On each composition load | 1+ |
+| Media sync drift | `player_sync_drift_max` | Runtime: max observed drift during session | On composition_ended | 2+ |
+| Inline mode used | `player_inline_mode` | Player: boolean, which mode was selected | On composition load | 4a+ |
+| `canRunInline` result | `player_inline_gate` | Player: pass/fail + failure reason | On composition load (inline-capable hosts only) | 4a+ |
+
+### Properties on every event
+
+```
+{
+  // anonymous session (no PII)
+  distinct_id: <anonymous_session_id>,  // random UUID per browser session
+  $ip: null,                            // tell PostHog to discard IP
+
+  // context
+  player_version: "0.4.12",
+  player_mode: "isolated" | "inline",
+  composition_id: <hash>,               // hashed, not raw
+  media_count: 5,                        // number of timed media elements
+
+  // environment
+  browser: "Chrome 126",
+  os: "macOS 15.1",
+  viewport_width: 1920,
+  screen_refresh_rate: 60,               // from screen.refreshRate if available
+  device_memory: 8,                      // navigator.deviceMemory (Chrome only)
+  hardware_concurrency: 8,               // navigator.hardwareConcurrency
+}
+```
+
+No user IDs, no file paths, no composition content, no cookies. Same privacy posture as the CLI telemetry.
+
+### Opt-in / opt-out
+
+The player doesn't have its own opt-in flow today. Two approaches:
+
+1. **Host-controlled:** The `<hyperframes-player>` element accepts a `telemetry` attribute. Default: `off`. Studio sets it to `on` (respecting the user's existing CLI telemetry preference if available). Public embeds stay off unless the host explicitly opts in.
+
+2. **Respect `DO_NOT_TRACK`:** Check `navigator.doNotTrack === "1"` or `navigator.globalPrivacyControl === true`. If either is set, no metrics are collected regardless of the attribute.
+
+### Before/after methodology
+
+Each PR that targets a specific metric must:
+
+1. **Tag the deploy.** PostHog events include `player_version`. Bump the patch version on each phase's final PR so we can filter by version range.
+
+2. **Wait for sample size.** Don't declare victory on <1000 sessions. PostHog's trend graphs with version-based cohorts give us the before/after comparison without manual work.
+
+3. **Segment by environment.** Studio vs. public embed, browser, device memory, media count. A 50% improvement on Chrome desktop that regresses Safari mobile is not a win.
+
+4. **One phase at a time.** Don't overlap Phase 1 and Phase 2 deploys. Each phase gets at least 1 week of production data before the next ships. This is the only way to attribute improvements to specific changes.
+
+### Regression alerting
+
+PostHog doesn't have built-in metric alerting, but it supports webhooks on cohort changes. Set up:
+
+1. **PostHog insight:** `player_playback_fps` p10 by `player_version`, 7-day rolling window.
+2. **PostHog action:** trigger when p10 fps drops below 45 for any version cohort with >100 sessions.
+3. **Webhook:** fire to the team's Slack channel.
+
+Same pattern for `player_scrub_latency` p95 (alert if >150ms) and `player_dropped_frames` p90 (alert if >10).
+
+### Dashboard
+
+Create a PostHog dashboard: **"HyperFrames Player Performance"** with these panels:
+
+| Panel | Visualization | Breakdown |
+|-------|--------------|-----------|
+| Scrub latency p50/p95 | Line chart, 7-day rolling | by `player_version` |
+| Playback fps p10/p50 | Line chart, 7-day rolling | by `player_version` |
+| Dropped frames p50/p90 | Line chart, 7-day rolling | by `browser` |
+| Composition load time p50/p95 | Line chart, 7-day rolling | by `player_mode` |
+| Decoder count distribution | Bar chart | by `media_count` bucket |
+| Inline mode adoption | Stacked area | by `player_inline_gate` result |
+| Session volume | Counter | total sessions this week |
+
+### Implementation: PR X-1 scope (revised)
+
+PR X-1 (`feat(core,player): player performance telemetry`) now covers:
+
+1. **Runtime side** (`core/src/runtime/analytics.ts`): add `emitPerformanceMetric(name, value, tags)` that sends `{ source: "hf-preview", type: "perf", name, value, tags }` through the bridge. Uses `performance.mark`/`performance.measure` internally for DevTools visibility. No PostHog dependency in core.
+
+2. **Player side** (`player/src/hyperframes-player.ts`): listen for `type: "perf"` messages. Aggregate per-session (hold metrics in memory, compute p50/p95 on flush). Flush to PostHog via `fetch` + `navigator.sendBeacon` fallback on page unload. Same HTTP batch API pattern as CLI. Gated on `telemetry` attribute + DNT check.
+
+3. **Studio side**: set `telemetry="on"` on the preview player, respecting the user's existing telemetry preference.
+
+No PostHog SDK. No new dependencies. ~150 LOC.
+
+---
+
+## Planned PRs
+
+Each PR is independently reviewable and shippable. Dependencies are noted — don't merge out of order.
+
+### Phase 0 — Measurement infrastructure
+
+| PR | Title | Packages | Files | Depends on |
+|----|-------|----------|-------|------------|
+| **P0-1** | feat(player): automated perf test suite + live-playback parity test | `player`, root | `player/tests/perf/` (runner, 5 tests, 3 fixtures, baseline.json, perf-gate.ts), root `package.json` | — |
+| **P0-2** | chore: Phase 0 trace results and baseline doc | `notes/` | `notes/traces/player-perf-2026-04/*.json`, update baseline.json with measured values, update this proposal with measured baselines | P0-1 |
+
+P0-1 creates the perf test infrastructure: 5 Playwright-based tests (fps, scrub latency, composition load, media sync drift, live-playback parity), 3 representative fixtures, baseline comparison gate, and CI integration for `packages/player/` and `packages/core/src/runtime/` changes. P0-2 is the manual trace capture — Chrome Performance profile, decoder-count trace, compositor-layers dump, memory profile, RVFC browser matrix, composition corpus audit for `canRunInline()`. Documented as raw traces + a summary addendum to this proposal. Also populates the initial baseline.json with measured values.
+
+### Phase 1 — Low-risk wins (4 independent PRs, can land in any order)
+
+| PR | Title | Packages | Key files | Depends on |
+|----|-------|----------|-----------|------------|
+| **P1-1** | perf(player): share PLAYER_STYLES via adoptedStyleSheets | `player` | `player/src/hyperframes-player.ts`, `player/src/styles.ts` | — |
+| **P1-2** | perf(player): scope MutationObserver to composition hosts | `player` | `player/src/hyperframes-player.ts` (~line 803) | — |
+| **P1-3** | perf(player): audio-only proxy for video-source parent media | `player` | `player/src/hyperframes-player.ts` (`_createParentMedia` ~line 656) | P0-2 (gated on trace #2 results) |
+| **P1-4** | perf(player): coalesce _mirrorParentMediaTime writes | `player` | `player/src/hyperframes-player.ts` (`_mirrorParentMediaTime` ~line 604) | — |
+
+P1-1 and P1-2 are the safest — pure player-internal changes with no API surface. P1-3 only ships if the Phase 0 audio-only proxy validation passes on all 4 browser/OS targets. P1-4 changes sync behavior so it needs a manual A/V sync check.
+
+### Phase 2 — Runtime clock + RVFC (1 PR — must ship together)
+
+| PR | Title | Packages | Key files | Depends on |
+|----|-------|----------|-----------|------------|
+| **P2-1** | perf(core): replace setInterval with rAF + RVFC drift observation | `core` | `core/src/runtime/init.ts` (~line 1502), `core/src/runtime/media.ts` (~line 160) | P0-1 (live-playback test exists), P0-2 (baselines established) |
+
+This is one PR because rAF without RVFC increases per-tick cost (3x more ticks with the same drift-polling work). The PR includes:
+- rAF loop during `isPlaying` with `visibilitychange` fallback to 250ms interval
+- `__HF_VIRTUAL_TIME__` guard for headless capture
+- RVFC-driven drift observation for `<video>` elements, with per-tick fallback retained for `<audio>`, state transitions (pause, seek, clip activation), and non-RVFC browsers
+- 250ms paused keep-alive interval
+
+**CI gate:** Producer parity harness + new live-playback regression test must both pass.
+
+### Phase 3 — Synchronous seek + fast switching (2-3 PRs)
+
+| PR | Title | Packages | Key files | Depends on |
+|----|-------|----------|-----------|------------|
+| **P3-1** | feat(player): synchronous seek() API with same-origin detection | `player` | `player/src/hyperframes-player.ts` | — |
+| **P3-2** | perf(player): srcdoc composition switching for studio | `player`, `studio` | `player/src/hyperframes-player.ts` (~line 146), studio composition-switch call sites | — |
+| **P3-3** | perf(player): warm iframe pool with LRU eviction | `player` | `player/src/hyperframes-player.ts` (new pool manager) | P0-2 (memory profile validates cap) |
+
+P3-1 formalizes studio's existing `__player` direct-access pattern as a public API. P3-2 adds `srcdoc` as an alternative to `src` for studio's case. P3-3 is optional — only ship if memory profiling confirms per-iframe cost allows a pool of 3. Thumbnail grids are explicitly excluded (use static screenshots instead).
+
+### Phase 4a — Inline mode behind flag (5 PRs with dependency chain)
+
+**Staffing:** PRs P4a-1 through P4a-3 are `core/` work (engineer A). PRs P4a-4 and P4a-5 are `player/`+`studio/` work (engineer B, can start after P4a-1 lands).
+
+| PR | Title | Packages | Key files | Depends on |
+|----|-------|----------|-----------|------------|
+| **P4a-1** | refactor(core): RuntimeContext interface + scope injection | `core` | `core/src/runtime/init.ts`, `core/src/runtime/media.ts`, `core/src/runtime/state.ts`, `core/src/runtime/timeline.ts`, `core/src/runtime/entry.ts`, `core/src/runtime/bridge.ts`, `core/src/runtime/compositionLoader.ts` | — |
+| **P4a-2** | refactor(core): adapter scoping + multi-instance __timelines | `core` | `core/src/runtime/adapters/gsap.ts`, `css.ts`, `waapi.ts`, `lottie.ts`, `three.ts` | P4a-1 |
+| **P4a-3** | refactor(core): picker shadow-root scoping | `core` | `core/src/runtime/picker.ts` | P4a-1 |
+| **P4a-4** | feat(core): canRunInline() validation gate + Shadow DOM CSS transforms | `core` | new `core/src/compiler/canRunInline.ts`, `core/src/compiler/htmlBundler.ts` (CSS transforms) | — |
+| **P4a-5** | feat(player): inline player mode behind __HF_INLINE_PLAYER flag | `player`, `studio` | `player/src/hyperframes-player.ts`, studio preview panel hook | P4a-1, P4a-2, P4a-3, P4a-4 |
+
+**P4a-1** is the biggest PR (~300-400 LOC). It introduces `RuntimeContext` with `root` (Document or ShadowRoot), `globals` (context object replacing window properties), and `bridge` (callback replacing postMessage). All `document.*` queries and `window.*` globals are parameterized. The default context is `{ root: document, globals: window, bridge: postMessage }` so the iframe path is unchanged.
+
+**P4a-2** scopes all 5 adapters to use `RuntimeContext` and moves `__timelines` from `window` into the per-instance context. This fixes the multi-instance collision where the same composition in two panels would overwrite each other's timeline.
+
+**P4a-3** is the picker refactor — `elementsFromPoint` on ShadowRoot, event capture scoped to the composition root, style injection into the shadow root instead of `document.head`.
+
+**P4a-4** is independent of the runtime refactor. It adds the `canRunInline()` denylist gate (linkedom HTML parse + regex script scan + CDN allowlist + `on*` attribute check) and the Shadow DOM CSS transforms (`@font-face` hoisting, `vh`/`vw` → container units, `:root` → `:host` selector rewriting).
+
+**P4a-5** wires everything together: the player's `mode="inline"` attribute, template-based composition mounting into shadow DOM, RuntimeContext instantiation with shadow root, and studio's preview panel opt-in behind the feature flag.
+
+### Phase 4b — Inline mode as default (2 PRs)
+
+| PR | Title | Packages | Key files | Depends on |
+|----|-------|----------|-----------|------------|
+| **P4b-1** | feat(player): inline mode default for studio + studio migration | `player`, `studio` | `player/src/hyperframes-player.ts`, all studio player call sites | P4a-5 |
+| **P4b-2** | feat(player): public API stabilization (mode="inline\|isolated") | `player` | `player/src/hyperframes-player.ts`, docs | P4b-1 |
+
+P4b-1 removes the feature flag and makes inline the default for studio. Migrates all studio call sites (preview, scene editor, export preview). Thumbnails stay iframe-based. P4b-2 stabilizes the public API surface and documents the mode attribute for external consumers.
+
+### Cross-cutting (ships alongside Phase 1+)
+
+| PR | Title | Packages | Key files | Depends on |
+|----|-------|----------|-----------|------------|
+| **X-1** | feat(core): emitPerformanceMetric bridge for post-land instrumentation | `core` | `core/src/runtime/analytics.ts`, `core/src/runtime/bridge.ts` | — |
+
+The existing `RuntimeAnalyticsEvent` union type covers discrete events (composition_loaded, composition_played, etc.). Performance counters (scrub latency, dropped frames, decoder count, load time) don't fit that shape. X-1 adds `emitPerformanceMetric(name, value, tags)` using `performance.mark`/`performance.measure` for client-side collection, with a bridge message for cross-frame reporting. Ship early so each phase can instrument its improvements.
+
+### PR summary
+
+| Phase | PRs | Total | Parallel tracks |
+|-------|-----|-------|-----------------|
+| 0 | P0-1, P0-2 | 2 | 1 |
+| 1 | P1-1, P1-2, P1-3, P1-4 | 4 | all independent |
+| 2 | P2-1 | 1 | 1 |
+| 3 | P3-1, P3-2, P3-3 | 3 | all independent |
+| 4a | P4a-1 → P4a-2, P4a-3 → P4a-5; P4a-4 independent | 5 | 2 (core + player/gate) |
+| 4b | P4b-1 → P4b-2 | 2 | 1 |
+| Cross-cutting | X-1 | 1 | independent |
+| **Total** | | **18** | |
+
+---
+
+## References
+
+- [requestVideoFrameCallback — MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestVideoFrameCallback)
+- [Perform efficient per-video-frame operations — web.dev](https://web.dev/articles/requestvideoframecallback-rvfc)
+- [Shadow DOM vs. iframes — HackerNoon](https://hackernoon.com/shadow-dom-vs-iframes-which-one-actually-works)
+- [adoptedStyleSheets — MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets)
+- [Page Visibility API — MDN](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)
+- [ShadowRoot.elementsFromPoint — MDN](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/elementsFromPoint)
diff --git a/notes/teaser-learnings.md b/notes/teaser-learnings.md
new file mode 100644
index 000000000..d7b0f6016
--- /dev/null
+++ b/notes/teaser-learnings.md
@@ -0,0 +1,857 @@
+# Teaser → HyperFrames Learnings
+
+Patterns extracted from `~/Desktop/teaser.html` (the standalone build of the
+"Claude Design Teaser") that are worth porting, codifying, or just naming
+inside HyperFrames. The teaser is a single-file React+Babel app with a
+hand-rolled animation engine; we are not adopting its architecture, but it
+contains real ideas that would improve HF.
+
+22 patterns total, grouped by area, then ranked by effort/impact at the end.
+
+---
+
+## Framing: LLMs are the primary authors
+
+HyperFrames compositions are written by LLM agents, not humans. A human
+might inspect the output in Studio and request changes, but the markup is
+LLM-generated. This changes which benefits matter.
+
+What's different about LLM authors vs human authors:
+
+1. **Lint and `validate` are the only feedback channel.** LLMs can't watch
+   a render and notice stutter. They can't tab to Studio, scrub, and feel
+   that the timing is off. Their entire awareness of correctness comes
+   from `hf lint` output, `hf validate` headless errors, and whether the
+   composition runs at all. Anything not caught by these is shipped broken.
+2. **Every regeneration costs tokens, latency, and money.** First-try
+   correctness is the only metric that matters at scale. APIs that are
+   harder to misuse beat APIs that are easier to read.
+3. **LLMs are bad at arithmetic.** Asking an LLM to "make sure all inner
+   tweens sum to less than `data-duration`" is asking for hallucinated
+   timings. Anything that lets the framework compute timings instead of
+   the LLM is a major reliability win.
+4. **LLMs only know patterns that are in skills.** A pattern that isn't
+   documented in `~/.claude/skills/hyperframes*` won't be used reliably,
+   even if the framework supports it. Skills are the system prompt;
+   patterns outside skills are invisible.
+5. **Constrained surfaces beat expressive ones.** 6 brand colors as
+   tokens beat 16M hex codes — the LLM can't hallucinate a wrong hex if
+   there's no hex to hallucinate. Same with eases, durations, etc.
+6. **Error messages are read by LLMs, not humans.** They need to be
+   specific and actionable enough that the LLM can fix the bug from the
+   message alone, without scrolling source.
+7. **Studio is for human reviewers.** Studio UX wins (sidebar relevance,
+   widgets, click-to-select) help the human reviewing the LLM's output,
+   but they don't make the LLM author better.
+
+The benefit sections below are reframed accordingly: each one estimates
+**effect on first-try LLM correctness** and **whether it needs a skill**
+to land.
+
+---
+
+## 1. Time & Duration
+
+### 1.1 Derived scene durations (`computeDur`)
+
+Each scene exposes a static function that computes its duration from raw
+tweak values, so editing one number resizes the scene and pushes everything
+downstream — no manual bookkeeping.
+
+```javascript
+scene1Intro.computeDur = function (T) {
+  const typeDur = T.s1_typeDur ?? 1.6;
+  const holdDur = T.s1_holdDur ?? 1.2;
+  const tail    = T.s1_tail    ?? 0.7;
+  return typeDur + holdDur + tail;
+};
+```
+
+**HF analogue:** clip durations should optionally be a function of attributes
+on the clip, not a constant `data-duration`.
+
+**Real-world benefit (LLM-authored):** Today, an LLM writing a clip has to
+do this:
+1. Decide the typing animation runs 1.6s
+2. Decide the hold runs 1.2s
+3. Decide the tail runs 0.7s
+4. **Manually sum to 3.5s and write `data-duration="3.5"`**
+5. Hope nothing in the inner tweens silently exceeds that
+
+LLMs are bad at step 4 — they hallucinate sums (off by 0.1–0.5s often),
+or pad pessimistically with `data-duration="6"` (creating dead frames),
+or under-pad and clip the animation. **A typical multi-clip composition
+has ≥1 timing arithmetic error per generation.** Each error means a
+human notices the dead frame or the cut-off, sends it back, LLM
+regenerates.
+
+With `computeDur`: the LLM declares the inner timings and the framework
+sums them. **Removes an entire class of LLM arithmetic errors.** The
+generation succeeds on first try at a much higher rate.
+
+Ripple effect: re-generating one clip with new timing no longer requires
+the LLM to also rewrite all downstream clip start times — the framework
+shifts them. That means a human request like "make scene 2 longer" turns
+into a single-clip edit, not a full-composition rewrite.
+
+**Skill needed:** yes — `hyperframes/compose-video` skill needs to teach
+the LLM "do not compute durations; declare timings and let the framework
+sum."
+
+---
+
+### 1.2 Probe pass / render pass separation
+
+Before render, a cheap arithmetic-only pass walks every scene's `computeDur`
+and lays out scene start times.
+
+```javascript
+const T = ctx.__rawStore || {};
+const durs = SCENE_FNS.map(fn => fn.computeDur ? fn.computeDur(T) : 5);
+const starts = [0];
+for (let i = 0; i < 7; i++) starts.push(starts[i] + durs[i]);
+const totalDur = starts[7];
+```
+
+**HF analogue:** add a probe phase to the parser that resolves dynamic
+durations before any rendering decisions are made.
+
+**Real-world benefit (LLM-authored):** Required infrastructure to make
+1.1 work. Without it, the renderer can't know total duration up front,
+which breaks `hf validate`'s ability to report "this composition is 47s
+long, expected ≤30s" — exactly the kind of structured error message an
+LLM uses to course-correct.
+
+**Skill needed:** no — invisible plumbing.
+
+---
+
+### 1.3 Explicit scene-time contract
+
+Every scene function takes the same args:
+
+```javascript
+function scene1Intro(ctx, t, t0, sceneDur) { ... }
+```
+
+Local time is always `t - t0`, progress is always `(t - t0) / sceneDur`.
+Consistent across all 7 scenes.
+
+**HF analogue:** a small `hf.sceneTime(el)` helper returning `{ t, lt, dur, p }`.
+
+**Real-world benefit (LLM-authored):** Every clip currently begins with
+`const t = window.__hfTime; const clipStart = ...; const lt = t - clipStart;`
+or some variation. LLMs get this slightly wrong constantly:
+- Forget to clamp `lt` to `[0, dur]` → animation runs negative
+- Use `Date.now()` instead of `window.__hfTime` → non-deterministic render
+- Divide by wrong duration → progress drifts
+- Compute `clipStart` by hand from the parent `<scene>` instead of reading it
+
+Each of these is a silent bug at preview time and a broken render at
+output time. With `hf.sceneTime(el)` returning `{ lt, dur, p }`, the LLM
+writes one line, can't get it wrong. **Removes the second-most-common
+class of LLM clip-script errors** (after timing arithmetic).
+
+**Skill needed:** yes — every code example in the compose skill should
+use `hf.sceneTime(el)` instead of hand-rolled time math, so it becomes
+the default pattern.
+
+---
+
+### 1.4 Self-referencing `at` metadata
+
+A tweak's "where it lives on the timeline" can be a function of its own value:
+
+```
+ at: v => sceneStart + v
+```
+
+So a "click delay" tweak's editor position follows the value as you drag it.
+
+**HF analogue:** if Studio adds richer property panels, this is the right model.
+
+**Real-world benefit (LLM-authored):** Effectively zero in the LLM-author
+context. This is a Studio editor feature for humans dragging values around.
+Park indefinitely.
+
+---
+
+## 2. Animation Primitives
+
+### 2.1 Easings as pure functions
+
+```javascript
+const twEase = {
+  smooth: t => { t = Math.max(0, Math.min(1, t)); return t * t * t * (t * (t * 6 - 15) + 10); },
+  back:   t => { /* overshoot */ },
+  // ...
+};
+```
+
+`twEase.smooth(p)` returns 0..1, callable from anywhere — not bound to a
+GSAP `gsap.to({ ease: "..." })` call.
+
+**HF analogue:** ship `hf.ease.{smooth, in, out, back, linear}`.
+
+**Real-world benefit (LLM-authored):** When an LLM needs an eased value
+outside a GSAP tween (canvas drawing, audio-reactive math, SVG morph,
+manual `clip-path` math) it currently does one of:
+1. **Hand-rolls easing math.** ~70% of the time it gets the curve wrong
+   (writes `t * t * (3 - 2*t)` thinking it's smootherstep, etc.) → render
+   looks subtly off, human reviewer can't articulate why.
+2. **Pulls in another easing lib.** Adds a dependency, inconsistency with
+   the rest of the composition.
+3. **Sets up a paused dummy GSAP tween just to read `progress`.** Works
+   but is grotesque — no LLM does this without prompting.
+
+With `hf.ease.smooth(p)`: one function call, can't be wrong, matches the
+curve used elsewhere in the composition. **Eliminates the "hand-rolled
+easing math" failure mode entirely.**
+
+**Skill needed:** yes — list canonical ease names in the compose skill so
+the LLM uses `hf.ease.smooth` instead of hallucinating a Penner formula.
+
+---
+
+### 2.2 `seq` and `hold` declarative keyframes
+
+```javascript
+function seq(now, stops) {
+  if (now <= stops[0][0]) return stops[0][1];
+  for (let i = 0; i < stops.length - 1; i++) {
+    const [t0, v0, e0] = stops[i];
+    const [t1, v1] = stops[i + 1];
+    if (now >= t0 && now < t1) {
+      const raw = (now - t0) / (t1 - t0);
+      return twLerp(v0, v1, (twEase[e0 || "smooth"] || twEase.smooth)(raw));
+    }
+  }
+  return stops[stops.length - 1][1];
+}
+```
+
+**HF analogue:** `hf.seq(t, [...])`.
+
+**Real-world benefit (LLM-authored):** Compare what the LLM has to
+generate today vs with `seq`/`hold`.
+
+**Today** ("fade in, hold, change to red, fade out" on one element):
+
+```javascript
+const tl = gsap.timeline({ paused: true });
+tl.set(el, { opacity: 0, color: "white" });
+tl.to(el,  { opacity: 1, duration: 0.5 });
+tl.to(el,  { color: "red", duration: 0 }, 2.5);
+tl.to(el,  { opacity: 0, duration: 0.5 }, 3.0);
+window.__timelines.set("el-7", tl);
+tl.seek(window.__hfTime - clipStart);
+```
+
+7 lines, requires:
+- correct delay arithmetic (LLM gets `2.5` wrong if any earlier tween changes)
+- correct registration on `window.__timelines` (LLM forgets the registration on ~20% of generations)
+- correct `seek` math (`window.__hfTime - clipStart`, easy to mess up)
+
+**With `seq`/`hold`:**
+
+```javascript
+el.style.opacity = seq(t, [[0, 0], [0.5, 1], [3, 1], [3.5, 0]]);
+el.style.color   = hold(t, [[0, "white"], [2.5, "red"]]);
+```
+
+2 lines, no timeline registration, no seek math, no delay arithmetic
+(the keyframe times are absolute, not relative). **Eliminates three
+common LLM error sources at once.** First-try correctness for "fade in
+hold change fade out" patterns probably goes from ~70% to ~95%.
+
+**Skill needed:** yes — feature `seq` prominently in the compose skill,
+demote raw GSAP timelines for simple keyframe sequences.
+
+---
+
+### 2.3 `envS` show/hide envelope
+
+```javascript
+function envS(now, t0, t1, t2 = Infinity, t3 = Infinity) {
+  // fade-in t0→t1, hold, fade-out t2→t3
+}
+```
+
+**HF analogue:** `hf.env(t, in, holdEnd, fadeStart, fadeEnd)`.
+
+**Real-world benefit (LLM-authored):** "Fade in, hold, fade out" appears
+in essentially every composition — every caption, lower-third, callout,
+overlay. Today the LLM generates a paused GSAP timeline with three
+tweens for each one (see 2.2 for the exact 5–7 lines).
+
+A 60s caption-heavy composition has 20+ envelopes per minute. **At 5–7
+lines each, that's 100–140 lines just for opacity envelopes.** Every
+line is a chance for the LLM to mis-register, mis-seek, or mis-time.
+
+With `envS`:
+
+```javascript
+el.style.opacity = envS(t, 1.0, 1.4, 3.4, 3.8);
+```
+
+20 envelopes × 1 line = 20 lines, each one impossible to mis-register.
+**~80% reduction in code volume for the most common animation pattern,
+correlated drop in error rate.** Also: shorter generated code = more
+context budget for the *next* clip in the same conversation.
+
+**Skill needed:** yes — make `envS` the canonical opacity-envelope
+pattern in skills.
+
+---
+
+## 3. Tweak System
+
+### 3.1 Tweak with metadata
+
+Every animated value is registered with rich metadata (`label`, `at`
+lifespan, `el` ownership, `step`/`min` widget hints).
+
+**HF analogue:** `data-*` attributes already do most of this for clips.
+
+**Real-world benefit (LLM-authored):** No action — HF's data-attribute
+model already captures this. Documented for context.
+
+---
+
+### 3.2 Manifest as render byproduct
+
+The teaser rebuilds the editor manifest fresh on every render.
+
+**HF analogue:** HF extracts metadata at parse time, which is correct for
+headless rendering.
+
+**Real-world benefit (LLM-authored):** Confirms HF's current architecture.
+No action.
+
+---
+
+### 3.3 Typed tweak helpers
+
+```javascript
+ctx.num   ("s1_size",    54,           { ... });
+ctx.point ("s2_ing_pos", [300, 230],   { ... });
+ctx.color ("s3_accent",  "#FF6B35",    { ... });
+```
+
+The editor renders the right widget (slider, XY pad, color picker).
+
+**HF analogue:** add `data-tweak-type="number|point|color|select"` so Studio
+can pick widgets instead of inferring.
+
+**Real-world benefit (LLM-authored):** Largely a Studio (human-reviewer)
+feature — the LLM doesn't care if Studio renders a color picker vs a text
+field. **One LLM-relevant angle though:** if `data-tweak-type="color"`
+constrains values to a palette declared on the parent `<theme>`, it
+prevents the LLM from generating a brand-conflicting hex. Same for
+`data-tweak-type="duration"` clamping to project-wide max. So this is
+mostly a Studio win, with a smaller "constrain LLM choices" win on top.
+
+Lower priority than the items targeting LLM correctness directly.
+
+**Skill needed:** marginal.
+
+---
+
+### 3.4 Globally unique tween IDs
+
+`s1_typeDur`, `s2_ing_pos`, `s3_accent` — scene-prefixed names.
+
+**HF analogue:** if HF ever adds a flat tweak namespace (export to JSON
+config), use this convention.
+
+**Real-world benefit (LLM-authored):** Niche. Park.
+
+---
+
+### 3.5 Quadratic relevance falloff in Studio
+
+Editor only shows tweaks "near" the playhead, with quadratic fade.
+
+**HF analogue:** Studio sidebar polish.
+
+**Real-world benefit (LLM-authored):** Pure human-reviewer UX. Helps the
+person reviewing the LLM's output find the knob to tweak. Nice but does
+not affect LLM correctness. Lower priority.
+
+---
+
+## 4. Element & Layer Model
+
+### 4.1 One identifier, three roles (`el`)
+
+A single string serves three purposes (tweak ownership, timing metadata,
+DOM selection target).
+
+**HF analogue:** `data-el` (or just element ID) linking clip attributes ↔
+DOM ↔ Studio inspector.
+
+**Real-world benefit (LLM-authored):** Studio-side benefit (select-to-edit,
+hover-to-highlight) is for human reviewers. **LLM-side benefit:** if `data-el`
+becomes the canonical "name this element" attribute, the LLM has one place
+to attach metadata instead of inventing IDs/classes/data-name ad hoc. Reduces
+naming hallucination. Skill could mandate "every animated element gets a
+unique `data-el`."
+
+Modest win. Mostly a Studio polish item.
+
+**Skill needed:** yes if adopted — single naming convention.
+
+---
+
+### 4.2 Per-element culling, post-registration
+
+Tweaks register before culling — manifest stays stable across timeline.
+
+**HF analogue:** when HF adds dynamic clips, ensure metadata extraction is
+independent of "is this clip currently visible".
+
+**Real-world benefit (LLM-authored):** Future-proofing. No code today, just
+a principle. Worth naming so a future LLM-generated conditional-clip
+pattern doesn't break inspectability.
+
+---
+
+## 5. Visual Polish
+
+### 5.1 Two-layer crossfade
+
+Background color/scene transitions stack two divs with opacity.
+
+**HF analogue:** ship as a registry block.
+
+**Real-world benefit (LLM-authored):** Every registry block is one fewer
+thing the LLM has to author from scratch. A blessed `bg-crossfade` block
+that the LLM can `hyperframes add` and reference means:
+- LLM doesn't have to invent the two-layer pattern itself
+- LLM doesn't accidentally use `transition: background 0.5s` (scrub-unsafe)
+- LLM doesn't write a one-layer GSAP `to({ background })` that flickers
+  on color interpolation
+
+**Every registry block raises the floor on LLM-authored quality.**
+`bg-crossfade` is one of the highest-leverage blocks because background
+transitions are universal in multi-scene videos and the wrong way to do
+them is the most natural way for an LLM (CSS transitions).
+
+**Skill needed:** the registry skill should list this block as the
+canonical answer to "I need a background transition."
+
+---
+
+### 5.2 Per-scene "tone" tracks
+
+Scalar values defined per-scene that interpolate during crossfades
+(texture/grain/vignette/color-grade/audio level).
+
+**HF analogue:** a "scene tracks" concept — global per-scene scalars that
+interpolate on transitions.
+
+**Real-world benefit (LLM-authored):** Today, when an LLM tries to add
+"grain stronger in the dark scene, lighter in the closing scene" it has
+to: write per-scene CSS variables, animate them on scene boundaries with
+GSAP, register the timelines, get the crossfade timing to match the
+scene's actual transition. Roughly 30 lines of correct, fragile code per
+"tone" axis.
+
+With scene tracks: declare `data-grain="0.3"` per scene, framework
+interpolates. **One attribute per scene replaces 30 lines of GSAP.**
+
+LLMs almost never produce cinematic-look compositions today because the
+mechanics are too error-prone — they default to flat scenes. Scene
+tracks change the default: with the right skill, the LLM adds grain,
+vignette, audio ducking by reflex because it's one attribute.
+
+**Raises baseline production quality of LLM-generated videos.**
+
+**Skill needed:** yes — give the LLM a list of conventional tone tracks
+it can set per scene.
+
+---
+
+### 5.3 `RevealText` progress-normalized stagger
+
+Word-by-word reveal that always finishes at p=1, regardless of word count.
+
+```javascript
+const gap = n > 1 ? (1 - stagger) / (n - 1) : 0;
+```
+
+**HF analogue:** any text-stagger block in the registry should follow this
+math.
+
+**Real-world benefit (LLM-authored):** When the LLM regenerates a clip
+because the human reviewer asked for different copy, the timing must
+remain correct. Today: LLM writes a 4-word reveal with stagger such that
+total = 1.5s. Human says "make it say [longer thing]". LLM regenerates
+the text but doesn't recompute stagger → text overflows the clip.
+
+This is **the most common failure mode of LLM-driven copy iteration on
+text-heavy compositions.** With normalized stagger, the LLM doesn't have
+to do the math: total time is constant by construction. Copy edits stop
+breaking timing.
+
+Note: this isn't "save marketers time on iteration" anymore — it's "the
+LLM doesn't ship broken timing when re-prompted with different copy."
+
+**Skill needed:** yes — `RevealText` and similar text-stagger blocks
+should be the canonical answer in skills, with a note that stagger is
+normalized.
+
+---
+
+### 5.4 `TypeText` caret discipline
+
+Caret stays solid while typing, blinks after typing completes.
+
+**HF analogue:** any typewriter component in the registry should do this.
+
+**Real-world benefit (LLM-authored):** Free quality bump in the registry
+component. The LLM doesn't have to know about caret behavior — it just
+uses `<type-text>` and gets the right behavior. This is what blocks are
+for: encoding designer-grade details so the LLM doesn't have to.
+
+**Skill needed:** no — registry block handles it transparently.
+
+---
+
+## 6. Embedding & Lifecycle
+
+### 6.1 `postMessage({type: "finished"})` host contract
+
+```javascript
+if (next >= duration) {
+  if (!doneRef.current) {
+    doneRef.current = true;
+    try { window.parent.postMessage({ type: "finished" }, "*"); } catch {}
+  }
+}
+```
+
+**HF analogue:** documented `postMessage` protocol for `<hyperframes-player>`
+(`{type: "ready" | "frame" | "finished" | "error"}`).
+
+**Real-world benefit (LLM-authored):** Distribution unlock. Once the
+protocol exists, an LLM can generate not just the composition but also
+the integration code for embedding it in a docs page, marketing email,
+or app — including the host-side "swap to CTA on finish" logic. Without
+the protocol, the LLM has to invent an ad-hoc signal (timer, polling)
+that's almost always wrong.
+
+Concrete pattern an LLM can emit reliably:
+
+```html
+<iframe src="https://hf.example.com/embed/abc"></iframe>
+<script>
+  window.addEventListener("message", e => {
+    if (e.data?.type === "finished") showCta();
+  });
+</script>
+```
+
+**Without the protocol, the LLM produces broken embed code at high rate.**
+With it, the LLM has a single canonical pattern to emit. Distribution
+becomes a one-shot LLM task.
+
+**Skill needed:** yes — add to compose-video skill or a new "embed"
+skill.
+
+---
+
+### 6.2 Two builds from one source
+
+Standalone player vs editor build, same scenes, different chrome.
+
+**HF analogue:** HF already has this split (`engine`, `studio`, `player`).
+
+**Real-world benefit (LLM-authored):** Audit task. The LLM-relevant angle:
+if `core` accidentally imports Studio code, the player bundle bloats and
+embed performance suffers — which makes the postMessage embed unlock
+(6.1) less attractive. Worth an audit before 6.1 ships.
+
+**Skill needed:** no.
+
+---
+
+### 6.3 dt clamp on tab-hidden
+
+```javascript
+const dt = Math.min((now - lastRef.current) / 1000, 0.1);
+```
+
+**HF analogue:** Studio preview should clamp dt.
+
+**Real-world benefit (LLM-authored):** Pure human-reviewer UX. Helps the
+person previewing the LLM's output not lose their place when alt-tabbing.
+Cheap to do, but the benefit is for the human, not the LLM. Lower
+priority than items that affect LLM correctness.
+
+---
+
+## 7. Discipline / Invariants
+
+### 7.1 No CSS transitions — scrub-safe
+
+Stated in the file header as a core invariant.
+
+**HF analogue:**
+- Document loudly in `hyperframes/SKILL.md` and `core/AGENTS.md`.
+- Add a `hyperframes lint` rule that flags `transition` / `animation` CSS
+  inside `.clip` elements.
+
+**Real-world benefit (LLM-authored):** **The single most important item
+in this entire document.**
+
+LLMs will write `transition: opacity 0.3s ease` constantly, because:
+- It's the most common pattern in their training data
+- It's the answer to most "how do I animate X in CSS" Stack Overflow posts
+- It looks correct in any browser preview the LLM might be evaluating
+  against
+- It's shorter than the GSAP equivalent
+
+The LLM has **no way to know this is wrong** unless lint catches it.
+Studio preview will look fine. The LLM cannot watch the rendered video
+and notice stutter — that's a human reviewer's job. Without lint, this
+bug ships, every time, on every composition.
+
+The cycle without lint:
+1. LLM generates composition with `transition: opacity 0.3s`
+2. LLM runs `hf lint` — passes
+3. LLM runs `hf validate` — passes (no JS errors, transition is valid CSS)
+4. Human renders → output is broken
+5. Human writes back "the fade looks stuttery"
+6. LLM has no way to localize the bug from that description, churns
+
+The cycle with lint:
+1. LLM generates composition with `transition: opacity 0.3s`
+2. `hf lint` errors: `Found CSS transition on .clip element. Transitions
+   are scrub-unsafe and produce stuttery renders. Use GSAP timelines or
+   hf.envS instead.`
+3. LLM reads the error, rewrites with `envS`, lint passes
+4. Render works first time
+
+**This single lint rule is the difference between LLM-authored HF being
+production-ready and being unreliable.** Probably the highest-leverage
+change in the whole codebase.
+
+**Skill needed:** lint rule + skill mention. Skill should explicitly say
+"never use CSS transition or animation properties on clips — use GSAP
+timelines or hf.envS."
+
+---
+
+### 7.2 Deterministic pseudo-randomness
+
+`Math.random()` in animation logic = different "random" values every render
+= snow/jitter that wasn't in preview.
+
+**HF analogue:** already an invariant; add lint enforcement.
+
+**Real-world benefit (LLM-authored):** Same class as 7.1 — invisible to
+the LLM, breaks the render. LLM writes `Math.random() * 100` for
+particle X position because it's the natural way to express "random
+position." Lint catches it pre-render.
+
+Without this lint rule, the LLM ships particle/shimmer effects that
+flicker chaotically in the rendered output and look fine in preview.
+LLM cannot diagnose this from a human bug report ("particles look
+weird") because it has no way to inspect frame-by-frame.
+
+**Skill needed:** lint rule + skill mention. Skill should provide a
+seeded-random helper as the blessed alternative.
+
+---
+
+### 7.3 Constrained design system
+
+Six color tokens, one serif font, one sans, one mono.
+
+**HF analogue:** registry blocks should consume CSS variables (`var(--hf-color-bg)`),
+not hardcoded hex.
+
+**Real-world benefit (LLM-authored):** **Hallucination reduction by
+constraint.** When the palette is 6 named tokens, the LLM can't pick
+`#FF6B35` when the brand color is `#FF7B30` — the option literally
+doesn't exist in the namespace. Same for fonts, eases, durations
+(if duration tokens exist).
+
+This is the framework version of "give the LLM a multiple choice
+question instead of a fill-in-the-blank." LLMs are dramatically more
+accurate on constrained-choice problems.
+
+Concrete:
+- Today, generating "5 social media videos in the brand palette" results
+  in 3-4 of them having one or two off-brand hex codes (LLM
+  approximated by eye).
+- With tokens: LLM emits `var(--brand-primary)`. Either the token
+  exists and is correct, or lint errors. **Brand consistency goes from
+  ~70% to 100%.**
+
+For an org producing dozens of customer-templated videos per quarter,
+this is the difference between "manually QA every video for brand
+compliance" and "trust the framework."
+
+**Skill needed:** yes — list the available tokens in the project's
+context so the LLM uses `var(--…)` references. Lint rule to forbid
+hex codes in `.clip` elements would close the loop.
+
+---
+
+### 7.4 Doc comments explain WHY, not WHAT
+
+Cultural pattern in `teaser.html` — comments justify design choices,
+constraints, tradeoffs.
+
+**HF analogue:** add to `AGENTS.md`.
+
+**Real-world benefit (LLM-authored):** When future LLMs (and humans)
+modify HF source, "why" comments prevent the "this looks redundant, let
+me remove it" refactor that breaks production. Concrete: 6.3's dt clamp
+is a one-liner that looks deletable — without the comment explaining
+tab-switch behavior, the next LLM cleaning up the file removes it.
+**LLMs are aggressive simplifiers without context.** "Why" comments
+are the only defense.
+
+**Skill needed:** add to internal contributor docs (`AGENTS.md`).
+
+---
+
+## 8. Anti-patterns observed (do not adopt)
+
+- **Shipping the toolchain in the page.** Babel standalone, React DOM dev,
+  duplicated transformed code all live inline. Fine for a one-off marketing
+  artifact, wrong for any framework. HF's compile-time approach is correct.
+- **Single 17000-line HTML file.** Authoring works for one person; doesn't
+  scale. HF's package boundary is correct. Note: also makes the file
+  unreadable to LLMs (exceeds typical context budgets).
+- **Inline `blob:` URLs for fonts.** Die the moment the file leaves the
+  original origin. Use proper font files.
+
+---
+
+## Prioritization (LLM-author lens)
+
+Re-ranked: items that improve **LLM first-try correctness** or **LLM
+distribution-code generation** rise. Pure Studio UX items fall.
+
+| # | What | Effort | LLM first-try gain | Notes |
+|---|------|--------|--------------------|-------|
+| **7.1** | Lint `transition`/`animation` inside `.clip` | ~1 day | **Massive** — closes the #1 invisible-to-LLM bug class. | LLM cannot diagnose this without lint. Highest leverage in the doc. |
+| **7.2** | Lint `Math.random`/`Date.now` in clips | ~30 min | **Massive** — same bug class as 7.1. | Pair with 7.1 in same PR. |
+| **2.1–2.3** | `hf.utils` (`ease`, `seq`, `hold`, `envS`, `lerp`) | ~1 day | **Large** — replaces the 5–7-line GSAP boilerplate where LLMs make 3+ classes of error. | Code volume drops ~80% on opacity envelopes. |
+| **1.1 + 1.2** | `computeDur` + probe pass | ~1 week | **Large** — removes the LLM's timing-arithmetic burden entirely. | Bigger architectural change but eliminates the most common LLM error class. |
+| **7.3** | Tokenize registry blocks (CSS variables) + lint hex in clips | ~3 days* | **Large for branded work** — turns brand consistency into a framework guarantee. | *~1 hour per existing block to retrofit. |
+| **5.3** | Audit registry text components for progress-normalized stagger | ~2 hours | **Medium** — kills "copy regen breaks timing" failure mode. | Cheap, do alongside other registry work. |
+| **5.1** | Background crossfade as registry block | ~4 hours | **Medium** — every block raises the floor on LLM output. | Pair with skill update so LLM uses it by default. |
+| **6.1** | `postMessage` embed protocol | ~1–2 days | **Medium for distribution** — LLM can emit working embed code. | Distribution unlock; complements composition authoring. |
+| **5.2** | Per-scene tone tracks (grain/vignette/audio) | ~1 week | **Medium** — raises baseline production quality of LLM output. | LLMs will use this if the skill teaches them to. |
+| **1.3** | `hf.sceneTime(el)` helper | ~1 hour | **Medium** — kills second-most-common clip-script error class. | Trivial to ship. |
+| **5.4** | Typewriter caret discipline in registry | ~30 min | **Small** — handled by registry block transparently. | LLM gets the win for free. |
+| **4.1** | `data-el` unifying inspector ↔ stage ↔ attrs | ~2 days | **Small for LLM, large for human reviewers** — naming convention helps slightly. | Mostly a Studio UX upgrade. |
+| **6.2** | Audit `core`/`engine`/`studio`/`player` boundary | ~1 day | **Small** — supports 6.1 by keeping player bundle small. | Run before 6.1 ships. |
+| **3.3** | `data-tweak-type` widget hints | ~3 days | **Small for LLM, large for Studio** | Mostly a human-reviewer feature. |
+| **6.3** | `dt` clamp on tab-hidden in Studio | ~10 min | **Zero** — pure human-reviewer benefit. | Still cheap and worth doing. |
+| **3.5** | Quadratic relevance falloff in Studio | ~2 hours | **Zero** — human-reviewer UX. | Defer until human-reviewer flow is the bottleneck. |
+| **7.4** | Doc comment philosophy in `AGENTS.md` | ~30 min | **Indirect** — protects LLM-authored code from over-aggressive future LLM refactors. | Cultural; cheap. |
+| **4.2** | Per-element culling discipline | — | **Indirect** — future-proofing for LLM-authored conditional clips. | Principle, no code today. |
+| **3.1, 3.2** | Already in HF | — | — | No action. |
+| **3.4, 1.4** | Niche; only matters if Studio expands | — | — | Park. |
+
+The pattern: **lint rules and `hf.utils` are the highest-leverage items
+because they directly affect what the LLM can ship without human
+intervention.** Studio polish items still matter, but only after the
+LLM-authoring path is reliable.
+
+---
+
+## Suggested first PRs
+
+**Optimize for the LLM authoring loop**, not the human review loop.
+Order:
+
+### PR 1: Lint rules for `transition`/`animation` and `Math.random`/`Date.now` in clips (#7.1, #7.2)
+
+Extend `packages/cli/src/commands/lint.ts` with two regex/AST-based rules.
+~50 LOC each. Critical: **error messages must be specific enough that an
+LLM can fix from the message alone**, e.g.:
+
+```
+error: hf/no-css-transitions
+  notes/example.html:42:5
+  CSS `transition: opacity 0.3s ease` found on a `.clip` element.
+
+  Renders capture frames at independent timestamps; CSS transitions are
+  not scrub-safe and produce stuttery output that looks correct in
+  Studio preview.
+
+  Fix: use a paused GSAP timeline registered on `window.__timelines`,
+  or `hf.envS(t, fadeIn, holdEnd, fadeOut, end)` for opacity envelopes.
+```
+
+**Pitch:** "These two lint rules are the difference between LLM-authored
+HF being shippable and being unreliable. They catch the bug classes the
+LLM literally cannot see. Half a day of work, pays back the first time
+they fire."
+
+### PR 2: `hf.utils` module (#2.1–2.3, #1.3)
+
+`packages/core/src/utils/{ease,seq,env,lerp,sceneTime}.ts`. ~100 LOC,
+zero risk. Bundle includes:
+
+- `hf.ease.{linear, smooth, in, out, back}`
+- `hf.lerp(a, b, t)`
+- `hf.seq(t, [[t0, v0, ease?], [t1, v1, ease?], ...])`
+- `hf.hold(t, [[t0, v0], [t1, v1], ...])`
+- `hf.envS(t, fadeIn, holdEnd, fadeOut, end)`
+- `hf.sceneTime(el) → { t, lt, dur, p }`
+
+**Pitch:** "Replaces 5–7-line GSAP timeline boilerplate with single
+expressions for the patterns that appear in every composition. LLM
+generates fewer lines, makes fewer of the three common mistakes
+(timing-registration, seek math, delay arithmetic). First-try
+correctness goes up, token spend goes down."
+
+### PR 3: Skills update — make the new utils + lint rules canonical
+
+The skills currently teach LLMs to use raw GSAP timelines. After PRs 1
+and 2 ship, the `hyperframes/compose-video` and `hyperframes-cli`
+skills should:
+
+- Demote raw GSAP timeline patterns for opacity envelopes
+- Teach `hf.envS` / `hf.seq` / `hf.hold` as the canonical answers
+- Document the new lint errors and how to satisfy them
+- Mandate `hf.sceneTime(el)` over hand-rolled time math
+- Provide explicit "do not use" examples for `transition`, `animation`,
+  `Math.random`, `Date.now` inside clips
+
+**Pitch:** "PRs 1 and 2 are useless without this. Skills are the
+LLM's system prompt — patterns outside skills don't get used reliably."
+
+### PR 4: `computeDur` convention (#1.1, #1.2)
+
+Bigger architectural change. Deserves its own design doc before code.
+Touches the parser, the runtime, Studio's scrubber, and the render
+pipeline.
+
+**Pitch:** "Removes the LLM's burden of summing inner timings. Eliminates
+a major arithmetic-error class that currently requires human review to
+catch. High-impact but bigger change — design separately."
+
+### PR 5: Tokenize registry blocks + lint hex in clips (#7.3)
+
+Constrained palette beats freeform hex. Retrofit existing blocks to
+consume CSS variables, add a lint rule against literal hex/rgb in clip
+elements, document the project's token namespace in skills.
+
+**Pitch:** "Brand consistency stops being a 'manually QA every video'
+problem and becomes a framework guarantee. Especially valuable for
+HeyGen's customer-templated work."
+
+---
+
+PRs 1–3 are tightly coupled and should ship together as the
+"LLM-authoring reliability" patch. PR 4 is high-leverage but bigger;
+plan separately. PR 5 is independent and can ship anytime.
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index 01c897981..041418527 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -152,6 +152,7 @@ export {
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 
 export {
+  extractMediaMetadata,
   extractVideoMetadata,
   extractAudioMetadata,
   analyzeKeyframeIntervals,
diff --git a/packages/engine/src/services/videoFrameExtractor.ts b/packages/engine/src/services/videoFrameExtractor.ts
index 3980e3a1c..480238880 100644
--- a/packages/engine/src/services/videoFrameExtractor.ts
+++ b/packages/engine/src/services/videoFrameExtractor.ts
@@ -9,7 +9,7 @@ import { spawn } from "child_process";
 import { existsSync, mkdirSync, readdirSync, rmSync } from "fs";
 import { join } from "path";
 import { parseHTML } from "linkedom";
-import { extractVideoMetadata, type VideoMetadata } from "../utils/ffprobe.js";
+import { extractMediaMetadata, type VideoMetadata } from "../utils/ffprobe.js";
 import {
   analyzeCompositionHdr,
   isHdrColorSpace as isHdrColorSpaceUtil,
@@ -158,7 +158,7 @@ export async function extractVideoFramesRange(
   const videoOutputDir = join(outputDir, videoId);
   if (!existsSync(videoOutputDir)) mkdirSync(videoOutputDir, { recursive: true });
 
-  const metadata = await extractVideoMetadata(videoPath);
+  const metadata = await extractMediaMetadata(videoPath);
   const framePattern = `frame_%05d.${format}`;
   const outputPattern = join(videoOutputDir, framePattern);
 
@@ -407,7 +407,7 @@ export async function extractAllVideoFrames(
   // Phase 2: Probe color spaces and normalize if mixed HDR/SDR
   const videoColorSpaces = await Promise.all(
     resolvedVideos.map(async ({ videoPath }) => {
-      const metadata = await extractVideoMetadata(videoPath);
+      const metadata = await extractMediaMetadata(videoPath);
       return metadata.colorSpace;
     }),
   );
@@ -453,7 +453,7 @@ export async function extractAllVideoFrames(
     if (signal?.aborted) break;
     const entry = resolvedVideos[i];
     if (!entry) continue;
-    const metadata = await extractVideoMetadata(entry.videoPath);
+    const metadata = await extractMediaMetadata(entry.videoPath);
     if (!metadata.isVFR) continue;
 
     let segDuration = entry.video.end - entry.video.start;
@@ -499,7 +499,7 @@ export async function extractAllVideoFrames(
         // Fallback: if no data-duration/data-end was specified (end is Infinity or 0),
         // probe the actual video file to get its natural duration.
         if (!Number.isFinite(videoDuration) || videoDuration <= 0) {
-          const metadata = await extractVideoMetadata(videoPath);
+          const metadata = await extractMediaMetadata(videoPath);
           const sourceDuration = metadata.durationSeconds - video.mediaStart;
           videoDuration = sourceDuration > 0 ? sourceDuration : metadata.durationSeconds;
           video.end = video.start + videoDuration;
diff --git a/packages/engine/src/utils/ffprobe.test.ts b/packages/engine/src/utils/ffprobe.test.ts
index 20ebd5887..7d3a66781 100644
--- a/packages/engine/src/utils/ffprobe.test.ts
+++ b/packages/engine/src/utils/ffprobe.test.ts
@@ -1,7 +1,7 @@
 import { readFileSync } from "fs";
 import { resolve } from "path";
 import { describe, expect, it } from "vitest";
-import { extractPngMetadataFromBuffer, extractVideoMetadata } from "./ffprobe.js";
+import { extractMediaMetadata, extractPngMetadataFromBuffer } from "./ffprobe.js";
 
 function crc32(buf: Buffer): number {
   let crc = 0xffffffff;
@@ -51,14 +51,14 @@ function buildMinimalPng(options?: {
     : buildPngWithChunks([ihdr, cicp, idat, iend]);
 }
 
-describe("extractVideoMetadata", () => {
+describe("extractMediaMetadata", () => {
   it("reads HDR PNG cICP metadata when ffprobe color fields are absent", async () => {
     const fixturePath = resolve(
       __dirname,
       "../../../producer/tests/hdr-regression/src/hdr-photo-pq.png",
     );
 
-    const metadata = await extractVideoMetadata(fixturePath);
+    const metadata = await extractMediaMetadata(fixturePath);
 
     expect(metadata.colorSpace).toEqual({
       colorPrimaries: "bt2020",
diff --git a/packages/engine/src/utils/ffprobe.ts b/packages/engine/src/utils/ffprobe.ts
index d72befc35..929405b52 100644
--- a/packages/engine/src/utils/ffprobe.ts
+++ b/packages/engine/src/utils/ffprobe.ts
@@ -210,7 +210,14 @@ function parseFrameRate(frameRateStr: string | undefined): number {
   return parseFloat(frameRateStr) || 0;
 }
 
-export async function extractVideoMetadata(filePath: string): Promise<VideoMetadata> {
+/**
+ * Probe a media file (video, image, or container) and return normalized metadata.
+ *
+ * Despite the legacy name `extractVideoMetadata` (still exported as a
+ * deprecated alias below), this also handles still images such as PNG so it
+ * can be used uniformly for any visual asset the HDR pipeline encounters.
+ */
+export async function extractMediaMetadata(filePath: string): Promise<VideoMetadata> {
   const cached = videoMetadataCache.get(filePath);
   if (cached) return cached;
 
@@ -286,6 +293,14 @@ export async function extractVideoMetadata(filePath: string): Promise<VideoMetad
   return probePromise;
 }
 
+/**
+ * @deprecated Use `extractMediaMetadata` — this name is kept for backward
+ * compatibility with consumers that imported the original video-only name
+ * before still-image (PNG) support was added. New callers should prefer
+ * `extractMediaMetadata`.
+ */
+export const extractVideoMetadata = extractMediaMetadata;
+
 export async function extractAudioMetadata(filePath: string): Promise<AudioMetadata> {
   const cached = audioMetadataCache.get(filePath);
   if (cached) return cached;
diff --git a/packages/producer/src/regression-harness.ts b/packages/producer/src/regression-harness.ts
index 96662df72..c7fdc7e44 100644
--- a/packages/producer/src/regression-harness.ts
+++ b/packages/producer/src/regression-harness.ts
@@ -17,7 +17,7 @@ import process from "node:process";
 import { createRenderJob, executeRenderJob } from "./services/renderOrchestrator.js";
 import { compileForRender } from "./services/htmlCompiler.js";
 import { validateCompilation } from "./services/compilationTester.js";
-import { extractVideoMetadata } from "./utils/ffprobe.js";
+import { extractMediaMetadata } from "./utils/ffprobe.js";
 import { buildRmsEnvelope, compareAudioEnvelopes } from "./utils/audioRegression.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
@@ -625,7 +625,7 @@ async function runTestSuite(
 
     // Visual comparison (100 frames, 1 per 1% of video duration)
     logPretty("Comparing visual quality (100 checkpoints)...", "🔍");
-    const videoMetadata = await extractVideoMetadata(renderedOutputPath);
+    const videoMetadata = await extractMediaMetadata(renderedOutputPath);
     const videoDuration = videoMetadata.durationSeconds;
 
     const visualCheckpoints: Array<{ time: number; psnr: number; passed: boolean }> = [];
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index 892c292de..5e1418135 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -23,7 +23,7 @@ import {
   rewriteAssetPaths,
   rewriteCssAssetUrls,
 } from "@hyperframes/core";
-import { extractVideoMetadata, extractAudioMetadata } from "../utils/ffprobe.js";
+import { extractMediaMetadata, extractAudioMetadata } from "../utils/ffprobe.js";
 import { isPathInside, toExternalAssetKey } from "../utils/paths.js";
 import {
   parseVideoElements,
@@ -152,7 +152,7 @@ async function resolveMediaDuration(
 
   const metadata =
     tagName === "video"
-      ? await extractVideoMetadata(filePath)
+      ? await extractMediaMetadata(filePath)
       : await extractAudioMetadata(filePath);
 
   const fileDuration = metadata.durationSeconds;
@@ -1033,7 +1033,7 @@ export async function compileForRender(
     if (isHttpUrl(video.src)) continue;
     const videoPath = resolve(projectDir, video.src);
     const reencode = `ffmpeg -i "${video.src}" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4`;
-    Promise.all([analyzeKeyframeIntervals(videoPath), extractVideoMetadata(videoPath)])
+    Promise.all([analyzeKeyframeIntervals(videoPath), extractMediaMetadata(videoPath)])
       .then(([analysis, metadata]) => {
         if (analysis.isProblematic) {
           console.warn(
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index c372539a0..54fcea821 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -42,6 +42,7 @@ import {
   prepareCaptureSessionForReuse,
   type CaptureOptions,
   type CaptureSession,
+  type BeforeCaptureHook,
   createVideoFrameInjector,
   encodeFramesFromDir,
   encodeFramesChunkedConcat,
@@ -61,7 +62,7 @@ import {
   analyzeCompositionHdr,
   isHdrColorSpace,
   runFfmpeg,
-  extractVideoMetadata,
+  extractMediaMetadata,
   type VideoColorSpace,
   initTransparentBackground,
   captureAlphaPng,
@@ -149,6 +150,34 @@ function getMaxFrameIndex(frameDir: string): number {
   return max;
 }
 
+// Diagnostic helpers used by the HDR layered compositor when KEEP_TEMP=1
+// is set. They are pure (capture no state), so we keep them at module scope
+// to avoid re-creating closures per frame and to make them callable from
+// any future composite path that needs to log non-zero pixel counts.
+function countNonZeroAlpha(rgba: Uint8Array): number {
+  let n = 0;
+  for (let p = 3; p < rgba.length; p += 4) {
+    if (rgba[p] !== 0) n++;
+  }
+  return n;
+}
+
+function countNonZeroRgb48(buf: Uint8Array): number {
+  let n = 0;
+  for (let p = 0; p < buf.length; p += 6) {
+    if (
+      buf[p] !== 0 ||
+      buf[p + 1] !== 0 ||
+      buf[p + 2] !== 0 ||
+      buf[p + 3] !== 0 ||
+      buf[p + 4] !== 0 ||
+      buf[p + 5] !== 0
+    )
+      n++;
+  }
+  return n;
+}
+
 /**
  * Metadata for a shader transition between two scenes, extracted from
  * `window.__hf.transitions`. Re-exported from the engine so the producer
@@ -572,6 +601,269 @@ function blitHdrImageLayer(
   }
 }
 
+/**
+ * Dependencies passed to `compositeHdrFrame`.
+ *
+ * Every field except the per-frame arguments is captured once when the HDR
+ * render path opens its `try { ... }` block and reused across every frame —
+ * extracting them into an explicit struct lets the helper live at module
+ * scope (no closure-over-renderJob) and keeps the per-call signature small.
+ */
+interface HdrCompositeContext {
+  log: ProducerLogger;
+  domSession: CaptureSession;
+  beforeCaptureHook: BeforeCaptureHook | null;
+  width: number;
+  height: number;
+  fps: number;
+  effectiveHdr: { transfer: HdrTransfer };
+  nativeHdrImageIds: Set<string>;
+  hdrImageBuffers: Map<string, HdrImageBuffer>;
+  hdrFrameDirs: Map<string, string>;
+  hdrVideoStartTimes: Map<string, number>;
+  imageTransfers: Map<string, HdrTransfer>;
+  videoTransfers: Map<string, HdrTransfer>;
+  debugDumpEnabled: boolean;
+  debugDumpDir: string | null;
+}
+
+/**
+ * Composite a single HDR frame into a pre-allocated `rgb48le` canvas.
+ *
+ * Bottom-to-top z-order: HDR layers are blitted directly from cached image
+ * buffers / extracted video frames; DOM layers are screenshotted with a
+ * mass-hide mask (so each layer paints only its own elements) and then
+ * blended into the canvas via `blitRgba8OverRgb48le` in the active HDR
+ * transfer space.
+ *
+ * The `elementFilter` parameter exists so the transition path can composite
+ * each scene independently; pass `undefined` for whole-stack rendering.
+ *
+ * @param ctx - Long-lived dependencies (logger, browser session, dimensions,
+ *              HDR layer maps). Captured once per render — see
+ *              {@link HdrCompositeContext}.
+ * @param canvas - Pre-allocated `width * height * 6` byte buffer. Caller must
+ *                 zero-fill before every frame (this helper does not).
+ * @param time - Seek time in seconds.
+ * @param fullStacking - Stacking info for ALL elements at this time. Even when
+ *                       filtering, every other element id is needed to build
+ *                       the DOM-layer hide-list.
+ * @param elementFilter - When set, only elements whose id is in the set are
+ *                        composited.
+ * @param debugFrameIndex - Frame index used to label per-layer diagnostic
+ *                          dumps. Pass `-1` to disable per-layer dumps even
+ *                          when `KEEP_TEMP=1` (e.g. for warmup frames).
+ */
+async function compositeHdrFrame(
+  ctx: HdrCompositeContext,
+  canvas: Buffer,
+  time: number,
+  fullStacking: ElementStackingInfo[],
+  elementFilter?: Set<string>,
+  debugFrameIndex: number = -1,
+): Promise<void> {
+  const {
+    log,
+    domSession,
+    beforeCaptureHook,
+    width,
+    height,
+    fps,
+    effectiveHdr,
+    nativeHdrImageIds,
+    hdrImageBuffers,
+    hdrFrameDirs,
+    hdrVideoStartTimes,
+    imageTransfers,
+    videoTransfers,
+    debugDumpEnabled,
+    debugDumpDir,
+  } = ctx;
+
+  const filteredStacking = elementFilter
+    ? fullStacking.filter((e) => elementFilter.has(e.id))
+    : fullStacking;
+
+  const layers = groupIntoLayers(filteredStacking);
+
+  const shouldLog = debugDumpEnabled && debugFrameIndex >= 0;
+  if (shouldLog) {
+    log.info("[diag] compositeToBuffer plan", {
+      frame: debugFrameIndex,
+      time: time.toFixed(3),
+      filterSize: elementFilter?.size,
+      fullStackingCount: fullStacking.length,
+      filteredCount: filteredStacking.length,
+      layerCount: layers.length,
+      layers: layers.map((l) =>
+        l.type === "hdr"
+          ? {
+              type: "hdr",
+              id: l.element.id,
+              z: l.element.zIndex,
+              visible: l.element.visible,
+              opacity: l.element.opacity,
+              bounds: `${Math.round(l.element.x)},${Math.round(l.element.y)} ${Math.round(l.element.width)}x${Math.round(l.element.height)}`,
+            }
+          : { type: "dom", ids: l.elementIds },
+      ),
+    });
+  }
+
+  for (const [layerIdx, layer] of layers.entries()) {
+    if (layer.type === "hdr") {
+      const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
+      const isHdrImage = nativeHdrImageIds.has(layer.element.id);
+      if (isHdrImage) {
+        blitHdrImageLayer(
+          canvas,
+          layer.element,
+          hdrImageBuffers,
+          width,
+          height,
+          log,
+          imageTransfers.get(layer.element.id),
+          effectiveHdr.transfer,
+        );
+      } else {
+        blitHdrVideoLayer(
+          canvas,
+          layer.element,
+          time,
+          fps,
+          hdrFrameDirs,
+          hdrVideoStartTimes,
+          width,
+          height,
+          log,
+          videoTransfers.get(layer.element.id),
+          effectiveHdr.transfer,
+        );
+      }
+      if (shouldLog) {
+        const after = countNonZeroRgb48(canvas);
+        if (isHdrImage) {
+          const buf = hdrImageBuffers.get(layer.element.id);
+          log.info("[diag] hdr layer blit", {
+            frame: debugFrameIndex,
+            layerIdx,
+            id: layer.element.id,
+            kind: "image",
+            pixelsAdded: after - before,
+            totalNonZero: after,
+            bufferDecoded: !!buf,
+            bufferDims: buf ? `${buf.width}x${buf.height}` : null,
+          });
+        } else {
+          const frameDir = hdrFrameDirs.get(layer.element.id);
+          const startTime = hdrVideoStartTimes.get(layer.element.id) ?? 0;
+          const localTime = time - startTime;
+          const frameNum = Math.floor(localTime * fps) + 1;
+          const expectedFrame = frameDir
+            ? join(frameDir, `frame_${String(frameNum).padStart(4, "0")}.png`)
+            : null;
+          log.info("[diag] hdr layer blit", {
+            frame: debugFrameIndex,
+            layerIdx,
+            id: layer.element.id,
+            kind: "video",
+            pixelsAdded: after - before,
+            totalNonZero: after,
+            startTime,
+            localTime: localTime.toFixed(3),
+            hdrFrameNum: frameNum,
+            expectedFrame,
+            expectedFrameExists: expectedFrame ? existsSync(expectedFrame) : false,
+          });
+        }
+      }
+    } else {
+      // DOM layer: capture only elements in this layer.
+      //
+      // Each layer gets a fresh seek + inject cycle to guarantee correct
+      // visibility state — avoids fragile interactions between the frame
+      // injector, applyDomLayerMask, removeDomLayerMask, and GSAP re-seek.
+      //
+      // The mask:
+      //   - mass-hides every body descendant via stylesheet
+      //   - re-shows the layer's elements (and their descendants and
+      //     their injected `__render_frame_*` siblings) so deep-nested
+      //     content stays visible even though intermediate ancestors
+      //     are hidden
+      //   - inline-hides every other data-start element so they don't
+      //     paint when they happen to be descendants of a layer element
+      //     (most importantly: HDR videos and other-layer SDR videos
+      //     that live inside `#root` when capturing the root DOM layer)
+      //
+      // Without the mask, every DOM screenshot captures the full page
+      // (root background, sibling scenes' static content, the painted
+      // border/box-shadow of cards, etc.) and the resulting opaque
+      // pixels overwrite previously composited HDR content beneath.
+      const allElementIds = fullStacking.map((e) => e.id);
+      const layerIds = new Set(layer.elementIds);
+      const hideIds = allElementIds.filter((id) => !layerIds.has(id));
+
+      // 1. Seek GSAP to restore all animated properties from clean state
+      await domSession.page.evaluate((t: number) => {
+        if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+      }, time);
+
+      // 2. Run frame injector to set correct SDR video visibility
+      if (beforeCaptureHook) {
+        await beforeCaptureHook(domSession.page, time);
+      }
+
+      // 3. Install the mask (mass-hide stylesheet + inline-hide non-layer ids)
+      await applyDomLayerMask(domSession.page, layer.elementIds, hideIds);
+
+      // 4. Screenshot
+      const domPng = await captureAlphaPng(domSession.page, width, height);
+
+      // 5. Tear down the mask
+      await removeDomLayerMask(domSession.page, hideIds);
+
+      try {
+        const { data: domRgba } = decodePng(domPng);
+        const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
+        const alphaPixels = shouldLog ? countNonZeroAlpha(domRgba) : 0;
+        blitRgba8OverRgb48le(domRgba, canvas, width, height, effectiveHdr.transfer);
+        if (shouldLog && debugDumpDir) {
+          const after = countNonZeroRgb48(canvas);
+          const dumpName = `frame_${String(debugFrameIndex).padStart(4, "0")}_layer_${String(layerIdx).padStart(2, "0")}_dom.png`;
+          const dumpPath = join(debugDumpDir, dumpName);
+          writeFileSync(dumpPath, domPng);
+          log.info("[diag] dom layer blit", {
+            frame: debugFrameIndex,
+            layerIdx,
+            layerIds: layer.elementIds,
+            hideCount: hideIds.length,
+            pngBytes: domPng.length,
+            alphaPixels,
+            pixelsAdded: after - before,
+            totalNonZero: after,
+            dumpPath,
+          });
+        }
+      } catch (err) {
+        log.warn("DOM layer decode/blit failed; skipping overlay", {
+          layerIds: layer.elementIds,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  if (shouldLog && debugDumpDir) {
+    const finalNonZero = countNonZeroRgb48(canvas);
+    log.info("[diag] compositeToBuffer end", {
+      frame: debugFrameIndex,
+      finalNonZeroPixels: finalNonZero,
+      totalPixels: width * height,
+      coverage: ((finalNonZero / (width * height)) * 100).toFixed(1) + "%",
+    });
+  }
+}
+
 export function createRenderJob(config: RenderConfig): RenderJob {
   return {
     id: randomUUID(),
@@ -1011,7 +1303,7 @@ export async function executeRenderJob(
             videoPath = fromCompiled;
           }
           if (!existsSync(videoPath)) return;
-          const meta = await extractVideoMetadata(videoPath);
+          const meta = await extractMediaMetadata(videoPath);
           if (isHdrColorSpace(meta.colorSpace)) {
             nativeHdrVideoIds.add(v.id);
             videoTransfers.set(v.id, detectTransfer(meta.colorSpace));
@@ -1038,7 +1330,7 @@ export async function executeRenderJob(
             imgPath = fromCompiled;
           }
           if (!existsSync(imgPath)) return null;
-          const meta = await extractVideoMetadata(imgPath);
+          const meta = await extractMediaMetadata(imgPath);
           if (isHdrColorSpace(meta.colorSpace)) {
             nativeHdrImageIds.add(img.id);
             imageTransfers.set(img.id, detectTransfer(meta.colorSpace));
@@ -1172,6 +1464,19 @@ export async function executeRenderJob(
       quality: needsAlpha ? undefined : job.config.quality === "draft" ? 80 : 95,
     };
 
+    // Native HDR videos (e.g. HEVC) may be undecodable by Chrome on the current
+    // platform — Linux headless-shell ships without HEVC support. Their pixels
+    // come from out-of-band ffmpeg extraction, so the DOM `<video>` element is
+    // only kept around for layout. Skip the per-page readiness wait for these
+    // IDs in every capture session we open during HDR rendering; otherwise the
+    // render hangs 45s and throws "video metadata not ready" even though we
+    // never asked the browser to decode the video. Encapsulating the spread
+    // here avoids drifting copies across the five capture call sites below.
+    const buildHdrCaptureOptions = (): CaptureOptions => ({
+      ...captureOptions,
+      skipReadinessVideoIds: Array.from(nativeHdrVideoIds),
+    });
+
     const workerCount = calculateOptimalWorkers(totalFrames, job.config.workers, cfg);
 
     const FORMAT_EXT: Record<string, string> = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
@@ -1262,7 +1567,7 @@ export async function executeRenderJob(
       const domSession = await createCaptureSession(
         fileServer.url,
         framesDir,
-        { ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
+        buildHdrCaptureOptions(),
         createVideoFrameInjector(frameLookup),
         cfg,
       );
@@ -1409,6 +1714,36 @@ export async function executeRenderJob(
           }
         }
 
+        // Fallback probe for HDR images that weren't captured above.
+        // When an image's `data-start` aligns with the exact visibility
+        // boundary (or precedes a GSAP `from` tween that animates it in
+        // later), Chrome reports 0 layout dimensions at that instant.
+        // Re-probe slightly into the element's visible range so the
+        // resample path gets real layout dims.
+        for (const [imageId, startTime] of hdrImageStartTimes) {
+          if (hdrExtractionDims.has(imageId)) continue;
+          const img = composition.images.find((i) => i.id === imageId);
+          if (!img) continue;
+          const duration = img.end - img.start;
+          const retryTime = startTime + Math.min(0.5, duration * 0.1);
+          await domSession.page.evaluate((t: number) => {
+            if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+          }, retryTime);
+          if (domSession.onBeforeCapture) {
+            await domSession.onBeforeCapture(domSession.page, retryTime);
+          }
+          const retryStacking = await queryElementStacking(domSession.page, nativeHdrIds);
+          for (const el of retryStacking) {
+            if (el.id === imageId && el.isHdr && el.layoutWidth > 0 && el.layoutHeight > 0) {
+              hdrExtractionDims.set(el.id, { width: el.layoutWidth, height: el.layoutHeight });
+              if (!hdrImageFitInfo.has(el.id)) {
+                hdrImageFitInfo.set(el.id, { fit: el.objectFit, position: el.objectPosition });
+              }
+              break;
+            }
+          }
+        }
+
         // ── Pre-extract all HDR video frames in a single FFmpeg pass ──────
         // hdrFrameDirs is declared above the try block so the outer finally
         // can clear matching frameDirMaxIndexCache entries on any exit path.
@@ -1529,243 +1864,41 @@ export async function executeRenderJob(
             }
           }
 
-          // ── compositeToBuffer: layer compositing helper ────────────────────
-          // Extracted so the transition path can composite each scene independently.
-          // Closes over domSession, hdrFrameDirs, composition, nativeHdrVideoIds, etc.
-          //
-          // @param canvas       - Pre-allocated rgb48le buffer (width * height * 6 bytes)
-          // @param time         - Seek time in seconds
-          // @param fullStacking - Complete stacking info for ALL elements (used for hideIds)
-          // @param elementFilter - When set, only composite elements whose IDs are in this set.
-          //                        When undefined, all elements are included (non-transition frame).
-          // @param debugFrameIndex - Frame index used to label diagnostic dumps. -1 disables
-          //                        per-layer dumps even when KEEP_TEMP=1 (for warmup calls).
+          // ── HDR composite helper context ───────────────────────────────────
+          // The actual layer-compositing logic lives at module scope in
+          // `compositeHdrFrame`; we just pre-bind its long-lived dependencies
+          // here so call sites stay short.
           const debugDumpEnabled = process.env.KEEP_TEMP === "1";
           const debugDumpDir = debugDumpEnabled ? join(framesDir, "debug-composite") : null;
           if (debugDumpDir && !existsSync(debugDumpDir)) {
             mkdirSync(debugDumpDir, { recursive: true });
           }
-          function countNonZeroAlpha(rgba: Uint8Array): number {
-            let n = 0;
-            for (let p = 3; p < rgba.length; p += 4) {
-              if (rgba[p] !== 0) n++;
-            }
-            return n;
-          }
-          function countNonZeroRgb48(buf: Uint8Array): number {
-            let n = 0;
-            for (let p = 0; p < buf.length; p += 6) {
-              if (
-                buf[p] !== 0 ||
-                buf[p + 1] !== 0 ||
-                buf[p + 2] !== 0 ||
-                buf[p + 3] !== 0 ||
-                buf[p + 4] !== 0 ||
-                buf[p + 5] !== 0
-              )
-                n++;
-            }
-            return n;
-          }
-          async function compositeToBuffer(
-            canvas: Buffer,
-            time: number,
-            fullStacking: ElementStackingInfo[],
-            elementFilter?: Set<string>,
-            debugFrameIndex: number = -1,
-          ): Promise<void> {
-            // Filter stacking info when rendering a single scene
-            const filteredStacking = elementFilter
-              ? fullStacking.filter((e) => elementFilter.has(e.id))
-              : fullStacking;
-
-            // Group filtered elements into z-ordered layers
-            const layers = groupIntoLayers(filteredStacking);
-
-            const shouldLog = debugDumpEnabled && debugFrameIndex >= 0;
-            if (shouldLog) {
-              log.info("[diag] compositeToBuffer plan", {
-                frame: debugFrameIndex,
-                time: time.toFixed(3),
-                filterSize: elementFilter?.size,
-                fullStackingCount: fullStacking.length,
-                filteredCount: filteredStacking.length,
-                layerCount: layers.length,
-                layers: layers.map((l) =>
-                  l.type === "hdr"
-                    ? {
-                        type: "hdr",
-                        id: l.element.id,
-                        z: l.element.zIndex,
-                        visible: l.element.visible,
-                        opacity: l.element.opacity,
-                        bounds: `${Math.round(l.element.x)},${Math.round(l.element.y)} ${Math.round(l.element.width)}x${Math.round(l.element.height)}`,
-                      }
-                    : { type: "dom", ids: l.elementIds },
-                ),
-              });
-            }
-
-            // Composite layers bottom-to-top
-            for (const [layerIdx, layer] of layers.entries()) {
-              if (layer.type === "hdr") {
-                const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
-                const isHdrImage = nativeHdrImageIds.has(layer.element.id);
-                if (isHdrImage) {
-                  blitHdrImageLayer(
-                    canvas,
-                    layer.element,
-                    hdrImageBuffers,
-                    width,
-                    height,
-                    log,
-                    imageTransfers.get(layer.element.id),
-                    effectiveHdr?.transfer,
-                  );
-                } else {
-                  blitHdrVideoLayer(
-                    canvas,
-                    layer.element,
-                    time,
-                    job.config.fps,
-                    hdrFrameDirs,
-                    hdrVideoStartTimes,
-                    width,
-                    height,
-                    log,
-                    videoTransfers.get(layer.element.id),
-                    effectiveHdr?.transfer,
-                  );
-                }
-                if (shouldLog) {
-                  const after = countNonZeroRgb48(canvas);
-                  if (isHdrImage) {
-                    const buf = hdrImageBuffers.get(layer.element.id);
-                    log.info("[diag] hdr layer blit", {
-                      frame: debugFrameIndex,
-                      layerIdx,
-                      id: layer.element.id,
-                      kind: "image",
-                      pixelsAdded: after - before,
-                      totalNonZero: after,
-                      bufferDecoded: !!buf,
-                      bufferDims: buf ? `${buf.width}x${buf.height}` : null,
-                    });
-                  } else {
-                    const frameDir = hdrFrameDirs.get(layer.element.id);
-                    const startTime = hdrVideoStartTimes.get(layer.element.id) ?? 0;
-                    const localTime = time - startTime;
-                    const frameNum = Math.floor(localTime * job.config.fps) + 1;
-                    const expectedFrame = frameDir
-                      ? join(frameDir, `frame_${String(frameNum).padStart(4, "0")}.png`)
-                      : null;
-                    log.info("[diag] hdr layer blit", {
-                      frame: debugFrameIndex,
-                      layerIdx,
-                      id: layer.element.id,
-                      kind: "video",
-                      pixelsAdded: after - before,
-                      totalNonZero: after,
-                      startTime,
-                      localTime: localTime.toFixed(3),
-                      hdrFrameNum: frameNum,
-                      expectedFrame,
-                      expectedFrameExists: expectedFrame ? existsSync(expectedFrame) : false,
-                    });
-                  }
-                }
-              } else {
-                // DOM layer: capture only elements in this layer.
-                //
-                // Each layer gets a fresh seek + inject cycle to guarantee correct
-                // visibility state — avoids fragile interactions between the frame
-                // injector, applyDomLayerMask, removeDomLayerMask, and GSAP re-seek.
-                //
-                // The mask:
-                //   - mass-hides every body descendant via stylesheet
-                //   - re-shows the layer's elements (and their descendants and
-                //     their injected `__render_frame_*` siblings) so deep-nested
-                //     content stays visible even though intermediate ancestors
-                //     are hidden
-                //   - inline-hides every other data-start element so they don't
-                //     paint when they happen to be descendants of a layer element
-                //     (most importantly: HDR videos and other-layer SDR videos
-                //     that live inside `#root` when capturing the root DOM layer)
-                //
-                // Without the mask, every DOM screenshot captures the full page
-                // (root background, sibling scenes' static content, the painted
-                // border/box-shadow of cards, etc.) and the resulting opaque
-                // pixels overwrite previously composited HDR content beneath.
-                const allElementIds = fullStacking.map((e) => e.id);
-                const layerIds = new Set(layer.elementIds);
-                const hideIds = allElementIds.filter((id) => !layerIds.has(id));
-
-                // 1. Seek GSAP to restore all animated properties from clean state
-                await domSession.page.evaluate((t: number) => {
-                  if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-                }, time);
-
-                // 2. Run frame injector to set correct SDR video visibility
-                if (beforeCaptureHook) {
-                  await beforeCaptureHook(domSession.page, time);
-                }
-
-                // 3. Install the mask (mass-hide stylesheet + inline-hide non-layer ids)
-                await applyDomLayerMask(domSession.page, layer.elementIds, hideIds);
-
-                // 4. Screenshot
-                const domPng = await captureAlphaPng(domSession.page, width, height);
-
-                // 5. Tear down the mask
-                await removeDomLayerMask(domSession.page, hideIds);
-
-                try {
-                  const { data: domRgba } = decodePng(domPng);
-                  // Invariant: this branch is only reached when HDR output is active.
-                  if (!effectiveHdr) {
-                    throw new Error(
-                      "Invariant violation: effectiveHdr is undefined inside HDR layer branch",
-                    );
-                  }
-                  const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
-                  const alphaPixels = shouldLog ? countNonZeroAlpha(domRgba) : 0;
-                  blitRgba8OverRgb48le(domRgba, canvas, width, height, effectiveHdr.transfer);
-                  if (shouldLog && debugDumpDir) {
-                    const after = countNonZeroRgb48(canvas);
-                    const dumpName = `frame_${String(debugFrameIndex).padStart(4, "0")}_layer_${String(layerIdx).padStart(2, "0")}_dom.png`;
-                    const dumpPath = join(debugDumpDir, dumpName);
-                    writeFileSync(dumpPath, domPng);
-                    log.info("[diag] dom layer blit", {
-                      frame: debugFrameIndex,
-                      layerIdx,
-                      layerIds: layer.elementIds,
-                      hideCount: hideIds.length,
-                      pngBytes: domPng.length,
-                      alphaPixels,
-                      pixelsAdded: after - before,
-                      totalNonZero: after,
-                      dumpPath,
-                    });
-                  }
-                } catch (err) {
-                  log.warn("DOM layer decode/blit failed; skipping overlay", {
-                    layerIds: layer.elementIds,
-                    error: err instanceof Error ? err.message : String(err),
-                  });
-                }
-              }
-            }
-
-            if (shouldLog && debugDumpDir) {
-              const finalNonZero = countNonZeroRgb48(canvas);
-              log.info("[diag] compositeToBuffer end", {
-                frame: debugFrameIndex,
-                finalNonZeroPixels: finalNonZero,
-                totalPixels: width * height,
-                coverage: ((finalNonZero / (width * height)) * 100).toFixed(1) + "%",
-              });
-            }
+          // INVARIANT: this entire `try` block is reachable only when HDR
+          // output is enabled (`if (effectiveHdr) { ... try { ... } }`), so
+          // narrowing here is safe even though `effectiveHdr` is typed as
+          // `... | undefined` at the outer scope.
+          if (!effectiveHdr) {
+            throw new Error(
+              "Internal: HDR render path entered without effectiveHdr — this is a bug.",
+            );
           }
+          const hdrCompositeCtx: HdrCompositeContext = {
+            log,
+            domSession,
+            beforeCaptureHook,
+            width,
+            height,
+            fps: job.config.fps,
+            effectiveHdr,
+            nativeHdrImageIds,
+            hdrImageBuffers,
+            hdrFrameDirs,
+            hdrVideoStartTimes,
+            imageTransfers,
+            videoTransfers,
+            debugDumpEnabled,
+            debugDumpDir,
+          };
 
           // ── Pre-allocate transition buffers ─────────────────────────────────
           // Each buffer is width * height * 6 bytes (~37 MB at 1080p). Reused
@@ -1932,7 +2065,14 @@ export async function executeRenderJob(
             } else {
               // ── Normal frame: full layer composite (no transition) ─────────
               normalCanvas.fill(0);
-              await compositeToBuffer(normalCanvas, time, stackingInfo, undefined, i);
+              await compositeHdrFrame(
+                hdrCompositeCtx,
+                normalCanvas,
+                time,
+                stackingInfo,
+                undefined,
+                i,
+              );
               if (debugDumpEnabled && debugDumpDir && i % 30 === 0) {
                 const previewPath = join(
                   debugDumpDir,
@@ -2086,7 +2226,7 @@ export async function executeRenderJob(
               fileServer.url,
               workDir,
               tasks,
-              { ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
+              buildHdrCaptureOptions(),
               () => createVideoFrameInjector(frameLookup),
               abortSignal,
               (progress) => {
@@ -2125,7 +2265,7 @@ export async function executeRenderJob(
               (await createCaptureSession(
                 fileServer.url,
                 framesDir,
-                { ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
+                buildHdrCaptureOptions(),
                 videoInjector,
                 cfg,
               ));
@@ -2188,7 +2328,7 @@ export async function executeRenderJob(
               fileServer.url,
               workDir,
               tasks,
-              { ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
+              buildHdrCaptureOptions(),
               () => createVideoFrameInjector(frameLookup),
               abortSignal,
               (progress) => {
@@ -2228,7 +2368,7 @@ export async function executeRenderJob(
               (await createCaptureSession(
                 fileServer.url,
                 framesDir,
-                { ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
+                buildHdrCaptureOptions(),
                 videoInjector,
                 cfg,
               ));
diff --git a/packages/producer/src/utils/ffprobe.ts b/packages/producer/src/utils/ffprobe.ts
index b356bac01..9912cd082 100644
--- a/packages/producer/src/utils/ffprobe.ts
+++ b/packages/producer/src/utils/ffprobe.ts
@@ -3,6 +3,7 @@
  * @see engine/src/utils/ffprobe.ts for implementation.
  */
 export {
+  extractMediaMetadata,
   extractVideoMetadata,
   extractAudioMetadata,
   type VideoMetadata,
diff --git a/packages/producer/tests/hdr-hlg-regression/README.md b/packages/producer/tests/hdr-hlg-regression/README.md
index 1ce0abdca..a1c08a120 100644
--- a/packages/producer/tests/hdr-hlg-regression/README.md
+++ b/packages/producer/tests/hdr-hlg-regression/README.md
@@ -13,7 +13,7 @@ so the HLG-specific encoder/metadata path stays tested in isolation.
 
 The test pins the contract that:
 
-- `extractVideoMetadata` reports `bt2020/arib-std-b67/limited` for the HLG
+- `extractMediaMetadata` reports `bt2020/arib-std-b67/limited` for the HLG
   source (i.e. HLG is detected and not silently coerced to PQ).
 - `isHdrColorSpace` flips the orchestrator into the layered HDR path on the
   HLG signal.
diff --git a/packages/producer/tests/hdr-hlg-regression/meta.json b/packages/producer/tests/hdr-hlg-regression/meta.json
index 95c16379a..ab251c1ee 100644
--- a/packages/producer/tests/hdr-hlg-regression/meta.json
+++ b/packages/producer/tests/hdr-hlg-regression/meta.json
@@ -1,6 +1,6 @@
 {
   "name": "hdr-hlg-regression",
-  "description": "Regression test for HDR HLG (BT.2020 ARIB STD-B67) video pass-through. Two windows: (A) baseline HLG video + SDR DOM overlay, (B) wrapper-opacity fade applied to an HLG video. Verifies that an HLG HEVC source drives the layered HDR pipeline end-to-end (extractVideoMetadata reports hlg, ffmpegFrameSource decodes correctly, hdrEncoder writes HEVC Main10 / yuv420p10le / BT.2020 HLG with the appropriate mastering metadata) and that opacity composition does not break HLG signal pass-through.",
+  "description": "Regression test for HDR HLG (BT.2020 ARIB STD-B67) video pass-through. Two windows: (A) baseline HLG video + SDR DOM overlay, (B) wrapper-opacity fade applied to an HLG video. Verifies that an HLG HEVC source drives the layered HDR pipeline end-to-end (extractMediaMetadata reports hlg, ffmpegFrameSource decodes correctly, hdrEncoder writes HEVC Main10 / yuv420p10le / BT.2020 HLG with the appropriate mastering metadata) and that opacity composition does not break HLG signal pass-through.",
   "tags": ["regression", "hdr"],
   "minPsnr": 28,
   "maxFrameFailures": 0,
diff --git a/plans/hdr-followups.md b/plans/hdr-followups.md
new file mode 100644
index 000000000..1b1f33cac
--- /dev/null
+++ b/plans/hdr-followups.md
@@ -0,0 +1,396 @@
+# HDR Follow-ups — Work Plan
+
+Source: [Hyperframes HDR follow-ups](https://www.notion.so/347449792c6980ae8ac6f93b9ddd4610)
+
+Organized into chunks that can be branched, tested, and merged independently.
+Items are prioritized: critical bugs first, then correctness, then hardening, then cleanup.
+
+---
+
+## Chunk 0: Comprehensive HDR Regression Test
+
+**Why first:** The existing HDR tests (`hdr-pq` and `hdr-image-only`) are trivial — a single full-bleed video or image with a static text label. They don't exercise any of the features that the HDR pipeline must explicitly handle differently from SDR: opacity animation, z-ordered multi-layer compositing, transforms, border-radius clipping, shader transitions, multiple HDR sources, object-fit modes, or mixed HDR+SDR layering. Every subsequent chunk in this plan needs a regression test that can prove the fix works *and* that nothing else broke. This chunk builds that test.
+
+### What the current tests cover
+
+| Test | Elements | Animations | Layers | Transitions |
+|------|----------|-----------|--------|-------------|
+| `hdr-pq` | 1 HDR video + 1 static label | None | 1 HDR + 1 DOM | None |
+| `hdr-image-only` | 1 HDR PNG + 1 static label | None | 1 HDR + 1 DOM | None |
+
+### What the HDR pipeline must support (complete feature inventory)
+
+Found by auditing `renderOrchestrator.ts`, `videoFrameInjector.ts`, `layerCompositor.ts`, `alphaBlit.ts`, `shaderTransitions.ts`, `streamingEncoder.ts`, `hdrCapture.ts`, and `hyper-shader.ts`:
+
+| # | Feature | HDR-specific behavior | Current coverage |
+|---|---------|----------------------|-----------------|
+| 1 | **Wrapper-opacity animation** | `getEffectiveOpacity()` walks ancestors, multiplies opacity chain. HDR path must read this and apply during compositing (Chrome can't do it — video is extracted separately). | None |
+| 2 | **Direct-on-element opacity animation** | GSAP tween on `<video>` itself. HDR path skips element's own opacity because engine forces `opacity: 0 !important` to hide it. Known bug (Chunk 1A). | None |
+| 3 | **Z-ordered multi-layer compositing** | `groupIntoLayers()` interleaves DOM and HDR layers by z-index. DOM layers get masked screenshots; HDR layers get native-pixel compositing. Adjacent DOM layers merge. | Trivial (1 HDR behind 1 DOM) |
+| 4 | **DOM behind HDR behind DOM** ("sandwich") | Requires at least 3 layers: DOM(z:1) → HDR(z:5) → DOM(z:10). Tests that masking correctly shows/hides elements per layer. | None |
+| 5 | **Multiple HDR video sources** | Fixed in PR #289 (was single-HDR-only in #288). No regression pins the fix. Two HDR videos composited in same frame. | None |
+| 6 | **Mixed HDR video + HDR image** | Both `isHdr` in the stacking query. Different extraction paths (FFmpeg frames vs PNG decode). Same compositing path. | None (separate tests) |
+| 7 | **CSS transforms (rotate, scale, translate)** | `el.transform` computed by `queryElementStacking()` / `getViewportMatrix()`. Must be applied via `blitRgb48leAffine()`. Currently dead — compositing only uses scale+translate (Chunk 4A). | None |
+| 8 | **GSAP `force3D: true` (matrix3d)** | GSAP's default. `parseTransformMatrix()` only handles `matrix()`, returns null for `matrix3d()` (Chunk 4B). | None |
+| 9 | **Border-radius clipping** | `el.borderRadius` computed from nearest `overflow:hidden` ancestor. Must be applied as pixel mask during HDR compositing. Currently dead (Chunk 4A). | None |
+| 10 | **Shader transitions (15 effects)** | Operate on rgb48le buffers in PQ/HLG signal space. `hdrToLinear` → shader → `linearToHdr`. Cross-scene compositing uses both scene A and scene B HDR captures. | None (unit tests only) |
+| 11 | **`object-fit` modes** | `resampleRgb48leObjectFit()` handles cover/contain/fill/none/scale-down. `ElementStackingInfo.objectFit` + `objectPosition` passed through. | None (`cover` only, implicitly) |
+| 12 | **sRGB-to-BT.2020 conversion** | DOM screenshots are sRGB. HDR compositor converts via `srgbToHdr16()` matrix before blitting over HDR content. Incorrect conversion = color shift on text/graphics. | Implicit only (label color not validated) |
+| 13 | **PQ transfer function** | SMPTE ST 2084. 65536-entry LUT. PQ OETF/EOTF constants (M1, M2, C1, C2, C3). | Implicit (hdr-pq test) |
+| 14 | **HLG transfer function** | ARIB STD-B67. Separate LUT. HLG OETF coefficients. Entirely different code path from PQ. | **None — zero coverage** |
+| 15 | **Cross-transfer conversion (HLG↔PQ)** | `convertTransfer()` for mixed-source compositions. HLG OOTF with Lw=1000, gamma=1.2. | **None** |
+| 16 | **HDR10 mastering metadata** | `mdcv` box (G,B,R primary order per ISO 23001-8), `stco`/`co64` offset shifting, `max-cll`/`max-fall`. | Implicit (metadata not validated by harness) |
+| 17 | **Captions over HDR content** | DOM text at high z-index over HDR layers. sRGB caption → BT.2020 conversion must preserve legibility. | Trivial (static label only) |
+| 18 | **Audio sync with HDR** | Both current tests set `minAudioCorrelation: 0` — audio sync is **not enforced**. HDR path could drop/reorder audio silently. | **Not enforced** |
+| 19 | **`layoutWidth`/`layoutHeight` for extraction** | Untransformed dims for FFmpeg extraction sizing. Currently unused — extraction uses `el.width`/`el.height` from getBoundingClientRect (Chunk 4C). | None |
+| 20 | **Scene initial-state** | Non-first scenes should start at `opacity: 0`. If not, all scenes composite simultaneously at t=0 (Chunk 4D). | None |
+
+### Design: time-sequenced test card
+
+The regression harness samples 100 PSNR checkpoints evenly across the video. By giving each feature its own **time window**, a regression at a specific checkpoint immediately identifies which feature broke — no per-zone PSNR support needed.
+
+Two compositions required: PQ and HLG use entirely separate code paths (different LUTs, different OETF/EOTF, different FFmpeg tagging). They cannot share a single composition. The fixture layout is identical; only the source assets and transfer function differ.
+
+**Composition: `hdr-regression` (PQ variant, ~20s, 1920x1080)**
+
+| Window | Time | Feature exercised | Elements |
+|--------|------|-------------------|----------|
+| A | 0.0–2.0s | Static baseline — HDR video + DOM overlay | Full-bleed HDR video, white text label at z:10. Sanity check: if this fails, everything else is meaningless. |
+| B | 2.0–4.5s | Wrapper-opacity fade | HDR video inside a `<div>` wrapper. GSAP tweens wrapper from `opacity: 1` → `0.15` → `1`. Tests `getEffectiveOpacity()` ancestor walk. |
+| C | 4.5–7.0s | Direct-on-element opacity | GSAP tweens `opacity` directly on `<video>` element. Same tween as (B). **Expected to fail until Chunk 1A lands** — proves the bug exists. |
+| D | 7.0–9.5s | Z-order sandwich: DOM → HDR → DOM | Three layers: colored rect at z:1 (DOM), HDR video at z:5, semi-transparent overlay at z:10 (DOM). Tests `groupIntoLayers()` with interleaved types. |
+| E | 9.5–12.0s | Multiple HDR sources | Two HDR videos side-by-side (left half, right half) at different z-indices with a DOM label between them. Pins the PR #289 multi-video fix. |
+| F | 12.0–14.5s | Transform + border-radius | HDR video with `rotation: 15deg`, `scale: 0.8` via GSAP. Container has `border-radius: 24px; overflow: hidden`. **Expected to fail until Chunk 4 lands.** |
+| G | 14.5–17.0s | Object-fit: contain | HDR video in a container that doesn't match its aspect ratio. `object-fit: contain` should produce letterboxing, not stretching. |
+| H | 17.0–20.0s | Shader transition (crossfade) | Two-scene composition with `crossfade` transition at t=18.5s. Tests signal-space blending of HDR pixels. Scene A = HDR video, Scene B = HDR image. |
+
+**Composition: `hdr-hlg-regression` (HLG variant, ~5s, 1920x1080)**
+
+Shorter composition — HLG exercises the separate LUT/OETF code path, not a different compositing pipeline.
+
+| Window | Time | Feature exercised | Elements |
+|--------|------|-------------------|----------|
+| A | 0.0–2.5s | HLG video + DOM overlay | Full-bleed HLG video with text label. Validates HLG OETF, `arib-std-b67` encoder tagging. |
+| B | 2.5–5.0s | HLG opacity animation | Wrapper-opacity fade on HLG video. Validates HLG-specific LUT used during compositing. |
+
+### Assets needed
+
+| Asset | Format | Source | Notes |
+|-------|--------|--------|-------|
+| `hdr-bars-pq.mp4` | HEVC Main10, BT.2020 PQ | Synthesized via FFmpeg SMPTE bars / color ramp | Deterministic, OSS-safe. Replaces third-party `hdr-clip.mp4` (also addresses Chunk 11A). |
+| `hdr-bars-hlg.mp4` | HEVC Main10, BT.2020 HLG | Synthesized via FFmpeg | Same pattern, HLG transfer. |
+| `hdr-photo-pq.png` | 16-bit RGB, BT.2020 PQ, cICP tagged | Synthesized via FFmpeg + ImageMagick | Gradient with known reference values for color accuracy checks. Can reuse or replace existing `hdr-photo.png`. |
+
+Synthesized assets solve fixture provenance (Chunk 11A) simultaneously.
+
+### Known-failing windows
+
+Some windows will fail against their golden snapshot until the corresponding chunk lands. This is intentional — the test documents the bug.
+
+| Window | Fails because | Fixed by |
+|--------|--------------|----------|
+| C (direct opacity) | HDR path ignores direct-on-element opacity | Chunk 1 |
+| F (transforms) | Transform/border-radius data not wired into compositing | Chunk 4 |
+
+Use `maxFrameFailures` to accommodate these known failures. As chunks land, regenerate the golden and tighten the threshold. Alternatively, we can use GSAP-conditional guards to make known-broken windows produce a deterministic fallback (e.g. skip the animation) until the fix lands — this keeps `maxFrameFailures: 0` but weakens the "proves the bug" property.
+
+### Replaces
+
+- `hdr-pq` — functionality covered by window A
+- `hdr-image-only` — functionality covered by window H (scene B uses an HDR image) plus can add a dedicated image-only window if needed
+
+Both old tests are removed. CI shard updated to run `hdr-regression hdr-hlg-regression` instead.
+
+### Gaps NOT covered by this regression test (out of scope)
+
+These need separate unit/integration tests (addressed in Chunk 9):
+
+- `hdrEncoder` error/cleanup path (unit test, Chunk 5A)
+- `frameDirMaxIndexCache` cross-job isolation (unit test, Chunk 5B)
+- Abort mid-transition (integration test, Chunk 5C)
+- `ffprobe` unavailable fallback (unit test, Chunk 9B)
+- `chunkEncoder` HDR metadata (separate encoder path, Chunk 3)
+- Cross-transfer conversion HLG↔PQ in a single composition (would need a mixed-source fixture — consider as a follow-up)
+- HDR10 mastering metadata validation (ffprobe post-render check, can be added to the harness)
+- Audio sync enforcement (requires setting `minAudioCorrelation` > 0 on a composition with audio)
+
+### Deliverables
+
+1. `packages/producer/tests/hdr-regression/` — composition, meta.json, synthesized assets, golden snapshot
+2. `packages/producer/tests/hdr-hlg-regression/` — HLG variant
+3. Remove `packages/producer/tests/hdr-pq/` and `packages/producer/tests/hdr-image-only/`
+4. Update CI workflow shard from `hdr-pq hdr-image-only` to `hdr-regression hdr-hlg-regression`
+5. FFmpeg asset synthesis scripts (checked into `scripts/` or documented in README)
+
+---
+
+## Chunk 1: Opacity Pipeline Bugs
+
+**Why first:** Two live correctness bugs produce wrong pixels. The HDR direct-on-video opacity bug is the most user-visible issue in the entire list.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | HDR compositor ignores direct-on-video opacity animation | `videoFrameInjector.ts:437-439` | Standalone bug report |
+| B | `queryVideoElementBounds` opacity fallback: `parseFloat("0") \|\| 1` treats opacity:0 as opacity:1 | `videoFrameInjector.ts:~202` | PR #288 I4 (unfixed residual) |
+| C | `as HTMLElement` cast — use `instanceof` guard instead | `videoFrameInjector.ts:309` | PR #290 I1 |
+| D | Opacity walk starts from parent — fragile ordering coupling with `hideVideoElements` | `videoFrameInjector.ts:426-428` | PR #290 M1 |
+
+**Approach for (A):** The doc suggests three fix options. Option 3 (use `visibility: hidden` instead of `opacity: 0 !important`) is cleanest — needs verification that native `<video>` won't leak through. Option 1 (read opacity before engine forces it to 0) is the safe fallback.
+
+**How to verify:**
+- Render a composition with GSAP animating `opacity` directly on a `<video>` element (no wrapper)
+- Compare SDR and HDR output at a mid-tween frame (e.g. t=3.5s, expected opacity ~0.15)
+- Both paths should produce visibly dim video — not full brightness
+- Regression: existing compositions with wrapper-based opacity animation must still work
+
+---
+
+## Chunk 2: Transition Duration Defaults
+
+**Why:** Causes a visible ~0.3s brightness dropout on any transition without explicit `duration`. Preview and render also produce different blending curves due to ease mismatch.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | Duration default mismatch: `1.0` in meta write, `0.7` in browser/engine mode | `hyper-shader.ts:130, 238, 361` | PR #268 C1 |
+| B | Ease mismatch: `"none"` in meta vs `"power2.inOut"` in browser | Same file | PR #268 C1 |
+
+**Fix:** Extract `DEFAULT_DURATION = 0.7` and `DEFAULT_EASE = "power2.inOut"` as shared constants. Use in all three sites.
+
+**How to verify:**
+- Render a composition with a transition that omits `duration` and `ease`
+- No brightness dip in the last ~0.3s of the transition
+- Preview (browser mode) and render (engine mode) produce matching blending curves
+- Render with explicit `duration: 1.5` still works (not overridden by default)
+
+---
+
+## Chunk 3: chunkEncoder HDR — Live Bug
+
+**Why:** Disk-based HDR encodes silently produce BT.709-tagged output. The streaming encoder is correct but chunkEncoder never reads `options.hdr`.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | `buildEncoderArgs` hard-codes BT.709 color params, ignores `options.hdr` | `chunkEncoder.ts` | PR #265 I1 |
+| B | `convertSdrToHdr` docstring says "zscale with 600 nit peak" but code uses FFmpeg colorspace filter; output hard-coded to HLG | `videoFrameExtractor.ts` | PR #265 I3 |
+| C | HDR config type: `{ transfer: ... } | false` but IIFE returns `undefined` | `config.ts` | PR #265 I4 |
+
+**How to verify:**
+- Render an HDR composition using the chunk encoder path
+- `ffprobe` the output: should show `bt2020nc` color matrix, `smpte2084` transfer, mastering display metadata
+- Compare against streaming encoder output — metadata should match
+
+---
+
+## Chunk 4: Transform & Clipping Pipeline
+
+**Why:** Transform extraction and border-radius computation exist but are dead — an HDR video with `rotation: 45` renders un-rotated, `border-radius: 50%` renders with sharp corners.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | Wire `el.transform`, `el.borderRadius`, `el.layoutWidth`/`layoutHeight` into compositing loop | `renderOrchestrator.ts` | PR #290 C1 |
+| B | `parseTransformMatrix` returns null for `matrix3d` (GSAP `force3D: true` default) | `alphaBlit.ts:634-643`, `videoFrameInjector.ts:370-407` | PR #290 I2 |
+| C | HDR extraction dims use `el.width`/`el.height` (transform-affected) instead of `el.layoutWidth`/`layoutHeight` | `renderOrchestrator.ts:~996-1008` | PR #290 M3 |
+| D | Scene initial-state: all non-first scenes should start at `opacity: 0` | `hyper-shader.ts:355-369` | PR #290 I3 |
+
+**How to verify:**
+- Render a composition with a rotated HDR video (`rotation: 45`) — should appear rotated
+- Render a composition with `border-radius: 50%` on an HDR video container — should clip to circle
+- Render a 3-scene composition — no overlapping at t=0
+- `blitRgb48leAffine` should receive the full affine matrix, not just scale+translate
+
+---
+
+## Chunk 5: Resource Management & Resilience
+
+**Why:** Leaked processes, unbounded memory growth, and missing abort checks. Each is independently fixable and testable.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | `hdrEncoder.close()` not called on non-abort errors (orphaned FFmpeg) | `renderOrchestrator.ts` | PR #268 I1 |
+| B | Module-scoped `frameDirMaxIndexCache` grows monotonically, never cleared | `renderOrchestrator.ts:~128` | PR #268 I2 |
+| C | No abort signal between scene A and scene B compositing | `renderOrchestrator.ts:~1500` | PR #290 I4 |
+| D | Per-frame `Buffer.alloc(width * height * 6)` — ~37 MB at 1080p, ~11 GB GC pressure for 10s/30fps | `renderOrchestrator.ts:~1082` | PR #290 M2 |
+| E | File server lacks `isPathInside()` guard — relative path segments can escape project dir | `fileServer.ts` | PR #288 M1 (unfixed across stack) |
+
+**How to verify:**
+- (A) Kill a render mid-flight with a non-abort error; confirm no orphaned `ffmpeg` processes
+- (B) Run two render jobs back-to-back; confirm cache is cleared between jobs
+- (C) Abort during a transition frame; confirm it stops promptly (not after scene B capture completes)
+- (D) Memory profiling: heap snapshots during a 10s render should show flat buffer allocation
+- (E) Attempt `GET /../../../etc/passwd` against the local file server; should 403/404
+
+---
+
+## Chunk 6: Non-null Assertions & Type Safety
+
+**Why:** Violates project policy. Straightforward mechanical fixes — good chunk for a single PR.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | ~12 `!` assertions on M709_TO_2020 matrix rows | `alphaBlit.ts` | PR hdr-image-support C2 |
+| B | `stack.pop()!` | `mp4HdrBoxes.ts:504` | PR hdr-image-support C2 |
+| C | `layers[layerIdx]!` | `renderOrchestrator.ts` | PR #268 C2 |
+| D | Duplicate `HfTransitionMeta` interface (rebase artifact) | `types.ts` (lines 42 and 68) | PR #268 I1 |
+| E | Locally-redeclared `HfTransitionMeta` in browser shim (add sync comment) | `hyper-shader.ts:116-123` | PR #268 I2 |
+| F | Dead code: `buildSrgbToHdrLut` / `getSrgbToHdrLut` if no external callers | `alphaBlit.ts` | PR hdr-image-support I4 |
+
+**How to verify:**
+- `grep -r '!\.' packages/engine/src packages/producer/src` — no new non-null assertions
+- TypeScript compiles clean
+- Existing tests pass unchanged
+
+---
+
+## Chunk 7: Refactoring — Compositing Helpers
+
+**Why:** Reduces complexity and duplication in the render orchestrator. Do after correctness fixes so the refactored code is already correct.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | Extract HDR compositing closure into top-level `compositeHdrFrame` helper | `renderOrchestrator.ts` | Deferred #1 |
+| B | Factor `skipReadinessVideoIds` capture-option spread into `buildHdrCaptureOptions()` | Multiple files | Deferred #9 |
+| C | Rename `extractVideoMetadata()` to `extractMediaMetadata()` (handles PNG too) | Engine utils | Deferred #8 |
+| D | Hoist `countNonZeroAlpha`/`countNonZeroRgb48` debug helpers to module scope | `renderOrchestrator.ts` | PR #268 M1 |
+
+**How to verify:**
+- All existing tests pass without modification (pure refactor)
+- No behavioral changes — diff should be structural only
+- New `compositeHdrFrame` helper has explicit typed context object
+
+---
+
+## Chunk 8: Performance
+
+**Why:** Potential perf regression from the layered HDR path. Measure first, then optimize.
+
+| # | Item | File(s) | Source | Status |
+|---|------|---------|--------|--------|
+| A | Benchmark HDR-PQ wall-clock + peak heap/RSS, `--tags` filter, `bench:hdr` script | `benchmark.ts`, `renderOrchestrator.ts`, `tests/perf/README.md` | Deferred #2 | **Done** (PR `vance/hdr-benchmark-harness`) |
+| B | Cache per-image transfer-converted HDR buffers per `(imageId, targetTransfer)` | Engine HDR path | Deferred #3 | **Done** (PR `vance/hdr-image-transfer-cache`) |
+| C | Debug logging does JSON serialization every 30 frames regardless of log level | `renderOrchestrator.ts`, `logger.ts` | PR #289 M4 | **Done** (PR `vance/logger-level-gating`) |
+| D | Diagnostic `countNonZeroAlpha`/`countNonZeroRgb48` iterate all pixels every frame (gated by KEEP_TEMP but check evaluates always) | Engine hot path | PR hdr-image-support M2 | **Already gated** — calls live behind `shouldLog = debugDumpEnabled && debugFrameIndex >= 0`, where `debugDumpEnabled` is itself driven by `KEEP_TEMP=1`, so the pixel iteration is fully skipped on production runs. No code change required; verified during 8C work. |
+
+**Ordering:** Do (A) first to establish a baseline. Then (B)-(D) as optimizations. Re-measure after.
+
+**8C resolution:** Added optional `isLevelEnabled(level)` to `ProducerLogger` and a `createConsoleLogger` implementation. The hot-loop call site in `renderOrchestrator.ts` (per-frame HDR composite snapshot every 30 frames) is now gated by `i % 30 === 0 && (log.isLevelEnabled?.("debug") ?? true)`, so the meta-object construction (`Array.find`, `toFixed`, conditional struct) is fully skipped at `level=info`. The `?? true` fallback preserves prior behavior for custom logger implementations that don't define the method. Covered by `packages/producer/src/logger.test.ts` (17 tests including a hot-loop call-site simulation that asserts zero builder invocations at info level).
+
+**8B resolution:** Added `packages/producer/src/services/hdrImageTransferCache.ts` — a per-render-job bounded LRU keyed by `(imageId, targetTransfer)` that owns the converted HDR rgb48 buffer for static HDR image layers. Same-transfer requests return the source buffer untouched; cross-transfer requests pay one `Buffer.from` + `convertTransfer` on first miss and reuse the cached copy on every subsequent frame instead of re-converting per composite. Wired into `renderOrchestrator.ts` via `HdrCompositeContext.hdrImageTransferCache`, instantiated once per render job and consumed by `blitHdrImageLayer` for both the main composite path and the transition path. Covered by `packages/producer/src/services/hdrImageTransferCache.test.ts` (12 tests: hit/miss, distinct keys per image and per target transfer, LRU eviction + promotion, `maxEntries=0` passthrough, source-buffer immutability for cached entries, invalid options).
+
+**How to verify:**
+- Wall-clock timing on `hdr-pq` fixture: before vs after, at least 3 runs each
+- Image cache hit rate logged (should be 100% for static images after first frame)
+- No JSON.stringify calls in hot path unless log level is debug
+
+---
+
+## Chunk 9: Test Coverage
+
+**Why:** Gaps identified across multiple PR reviews. Can be done in parallel with other chunks.
+
+| # | Item | File(s) | Source | Status |
+|---|------|---------|--------|--------|
+| A | ~~Restore mixed SDR/HDR and HDR+captions regression fixtures/tests~~ | ~~Test fixtures~~ | ~~Deferred #5~~ | **Absorbed by Chunk 0** (windows D, E, H) |
+| B | Add explicit ffprobe-unavailable fallback test (mock missing ffprobe) | Unit test | Deferred #10 | Open |
+| C | ~~CI-wired integration test for the full HDR composite pipeline~~ | ~~Integration test~~ | ~~PR hdr-image-support test gaps~~ | **Absorbed by Chunk 0** |
+| D | Test `hdrEncoder` error/cleanup path | Unit test | PR hdr-image-support test gaps | Open |
+| E | Test `frameDirMaxIndexCache` cross-job isolation | Unit test | PR hdr-image-support test gaps | Open |
+| F | alphaBlit: add known sRGB-to-BT.2020 reference values for matrix path | `alphaBlit.test.ts` | PR hdr-image-support test gaps | Open |
+| G | Shader smoke tests at p=0.5 (midpoint regressions) | `shaderTransitions.test.ts` | PR #268 M2 | Open |
+
+**How to verify:**
+- `bun run test` — all new tests pass
+- Coverage report shows the previously-uncovered branches are now hit
+
+---
+
+## Chunk 10: CLI — Restore Removed Flags
+
+**Why:** Breaking change for existing users. Needs user-facing communication.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | Restore `--crf` and `--video-bitrate` CLI flags alongside `--hdr` (or add deprecation) | `packages/cli/src/commands/render.ts` | PR #268 I3, PR hdr-image-support I3 |
+
+**How to verify:**
+- `hyperframes render --crf 18 ...` works (or prints deprecation warning)
+- `hyperframes render --hdr ...` still works
+- `hyperframes render --help` shows all flags
+
+---
+
+## Chunk 11: OSS & CI Hygiene
+
+**Why:** Fixture provenance, CI stability, repo bloat prevention. Independent of code correctness.
+
+| # | Item | File(s) | Source | Status |
+|---|------|---------|--------|--------|
+| A | ~~Replace third-party `hdr-pq` fixture with synthesized HDR source (FFmpeg test patterns)~~ | ~~Test fixtures~~ | ~~Deferred #4~~ | **Absorbed by Chunk 0** (synthesized assets) |
+| B | ~~Relax HDR fixture `maxFrameFailures` from 0 to 2~~ | ~~Test config~~ | ~~Deferred #7~~ | **Absorbed by Chunk 0** (accommodates known-failing windows) |
+| C | Add `tests/*/src/*.png` to LFS tracking in `.gitattributes` | `.gitattributes` | Deferred #11 | Open |
+
+**How to verify:**
+- (C) `git lfs ls-files` includes HDR PNG fixtures after commit
+
+---
+
+## Chunk 12: Investigation — `__name` Polyfill
+
+**Why:** Investigation item — outcome determines whether there's a code change or just a polyfill removal.
+
+| # | Item | File(s) | Source |
+|---|------|---------|--------|
+| A | Investigate the bundler/runtime boundary causing the `__name` issue; remove polyfill if fixable | Runtime | Deferred #6 |
+
+**How to verify:**
+- If root cause found: polyfill removed, `bun run test` passes, `bun run build` clean
+- If root cause is upstream: document why polyfill is necessary, add a test that detects if the upstream fix lands
+
+**Status: Done — keeping polyfill, documented + regression-tested.**
+
+Empirical findings (probe in `/tmp/hf-name-probe`):
+
+| Runtime / build | Injects `__name(fn, "name")` wrappers in `Function.prototype.toString()`? |
+|-----------------|---------------------------------------------------------------------------|
+| `bun` (TS loader) | No — verified for top-level and nested named functions / arrow expressions. |
+| `tsx` (esbuild loader, `keepNames=true`) | Yes for nested named functions / arrows; observed crash mode in dev/test. |
+| `tsc` (`noEmit` and emit) | No — does not inject the helper. |
+| `tsup` for `@hyperframes/cli` (`noExternal: ["@hyperframes/engine"]`) | Polyfill *definition* is bundled, but `__name(...)` *call sites* are absent in `packages/cli/dist/cli.js` (grepped). |
+
+Root cause: `@hyperframes/engine`'s `package.json` exports raw TypeScript (`main`/`exports` → `./src/index.ts`), so every consumer's transpiler decides whether to inject `__name`. Anything that runs through `tsx` (producer parity-harness, ad-hoc dev scripts, `bun run --filter @hyperframes/engine test` via Vitest's loader) will serialize wrapped function bodies into `page.evaluate(...)` and crash with `ReferenceError: __name is not defined`.
+
+Decision: keep the no-op `window.__name` shim in `frameCapture.ts`. Cost is one `evaluateOnNewDocument` call; alternative (rewriting every `page.evaluate(fn)` site to `page.addScriptTag({ content: "..." })` like `packages/cli/src/commands/contrast-audit.browser.js`) is far more invasive and easy to regress.
+
+What landed:
+- Expanded the inline comment in `packages/engine/src/services/frameCapture.ts` to explain the per-runtime matrix above and point to the script-tag alternative.
+- Added `packages/engine/src/services/frameCapture-namePolyfill.test.ts` — a pure unit-test (matches the rest of the engine package's convention, no browser launch) that:
+  1. Asserts the polyfill is wired up via `evaluateOnNewDocument` and runs before the first awaited `browser.version()` call.
+  2. Probes the active Vitest transpiler for `__name(...)` injection so the next maintainer can see at a glance whether the upstream behavior has shifted.
+
+Verification:
+- `bun run --filter @hyperframes/engine test` → 408/408 pass (3 new tests in this file).
+- `bunx tsc --noEmit -p packages/engine` clean.
+- `bunx oxlint` and `bunx oxfmt --check` clean on edited files.
+
+---
+
+## Suggested Merge Order
+
+```
+Chunk 0  (regression test)     — FIRST. Establishes the safety net. Known-failing windows accepted initially.
+Chunk 6  (type safety)         — mechanical, zero risk, unblocks nothing but cleans the diff
+Chunk 2  (transition defaults) — small, high-value correctness fix
+Chunk 1  (opacity pipeline)    — highest-impact bug; regenerate golden for window C after merge
+Chunk 3  (chunkEncoder HDR)    — live bug, independent code path
+Chunk 5  (resource management) — independent fixes, each small
+Chunk 10 (CLI flags)           — user-facing, small
+Chunk 7  (refactoring)         — after correctness fixes land
+Chunk 4  (transform pipeline)  — largest chunk, depends on Chunk 1; regenerate golden for window F after merge
+Chunk 11 (OSS/CI hygiene)      — anytime (11A already addressed by Chunk 0's synthesized assets)
+Chunk 9  (test coverage)       — anytime, pairs well with any chunk (9A partially addressed by Chunk 0)
+Chunk 8  (performance)         — after refactoring lands (cleaner code to benchmark)
+Chunk 12 (investigation)       — anytime, independent
+```
+
+Chunk 0 lands first to establish the regression safety net. Windows C and F will fail until Chunks 1 and 4 land — set `maxFrameFailures` accordingly and tighten as fixes merge.
+
+Chunks 6, 9, 11, and 12 can run in parallel with anything. Chunks 1 and 4 share `videoFrameInjector.ts` so should be sequenced. Chunk 7 (refactoring) should land after Chunks 1-3 so you're refactoring correct code.

From 71e67e2f053cbacd522b595da13441775ae20149 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 22 Apr 2026 22:08:47 -0700
Subject: [PATCH 2/2] chore: remove accidentally committed working docs

notes/ and plans/ are working documents, not project docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 notes/player-perf-proposal-final.md | 743 ------------------------
 notes/teaser-learnings.md           | 857 ----------------------------
 plans/hdr-followups.md              | 396 -------------
 3 files changed, 1996 deletions(-)
 delete mode 100644 notes/player-perf-proposal-final.md
 delete mode 100644 notes/teaser-learnings.md
 delete mode 100644 plans/hdr-followups.md

diff --git a/notes/player-perf-proposal-final.md b/notes/player-perf-proposal-final.md
deleted file mode 100644
index 0af36b1a5..000000000
--- a/notes/player-perf-proposal-final.md
+++ /dev/null
@@ -1,743 +0,0 @@
-# HyperFrames Player — Performance Review & Architecture Proposal
-
-**Author:** James Russo
-**Revised by:** Vance Ingalls
-**Date:** 2026-04-20
-**Scope:** `packages/player` + `packages/core/src/runtime` + studio consumer
-**Status:** Final draft
-
----
-
-## TL;DR
-
-The preview player's dominant perf costs for video/image-heavy compositions are (1) a non-vsync 50 ms `setInterval` as the runtime master clock, (2) `el.currentTime` drift correction that thrashes video decoders, (3) parent-proxy promotion that creates `<video>` elements where `<audio>` elements may suffice — potentially doubling decoder pressure (needs validation), and (4) asynchronous postMessage seek that forces studio to bypass the official bridge entirely.
-
-The iframe boundary is **not** the bottleneck and remains the right choice for **public embeds** (untrusted hosts). For the **studio preview**, we should add a second `mode="inline"` that mounts compositions directly into the player's Shadow DOM — making seek synchronous, eliminating the audio-owner protocol for same-origin, and collapsing two compositor layer trees into one.
-
-> **Caveat:** This analysis is code-reading, not profiling. Before landing any fix, validate with the traces specified in the Validation Plan. Each phase has concrete pass/fail SLOs — don't proceed to the next phase without hitting them.
-
----
-
-## How the current pipeline works
-
-1. `<hyperframes-player>` custom element creates a Shadow DOM containing an `<iframe sandbox="allow-scripts allow-same-origin">` with the composition HTML.
-
-2. Inside the iframe, the core runtime installs a `setInterval(…, 50)` poll (`core/src/runtime/init.ts:1502-1561`) that:
-   - Calls `syncCurrentTimeFromTimeline()` — reads the GSAP timeline position.
-   - Calls `syncMediaForCurrentState()` (if playing) — iterates all `<video>`/`<audio>` elements, compares `el.currentTime` to expected, corrects drift.
-   - Calls `postState(false)` — sends `window.parent.postMessage({source:"hf-preview", type:"state", …})`, throttled by `bridgeMaxPostIntervalMs: 80` (`core/src/runtime/state.ts:67`).
-   - Calls `postTimeline()` every 20th tick (~once per second).
-
-3. Parent listens for state messages, throttles UI updates to ~12 Hz, dispatches a `timeupdate` event.
-
-4. Control flows (play/pause/seek) are **asynchronous**: parent `postMessage` → iframe bridge (`bridge.ts:22-71`) dispatches to handlers → next 50 ms tick → parent receives `state` → UI updates. Round-trip >= 50–100 ms.
-
-5. The outer iframe is scaled with `transform: translate(-50%, -50%) scale(S)` to fit the container (`player/src/hyperframes-player.ts:530`).
-
-6. Studio (same-origin) **bypasses postMessage entirely** and reads `iframe.contentWindow.__player` directly (with fallback to `__timelines`) for its own rAF loop (`studio/src/player/hooks/useTimelinePlayer.ts:233-239`). This is a strong signal that the official bridge is too slow for tight UI.
-
-7. When autoplay is blocked, the runtime sends a `media-autoplay-blocked` message. The parent responds by "promoting" to parent-proxy ownership: it creates mirror `<video>`/`<audio>` elements for every `<video data-start>`/`<audio data-start>` in the iframe, preloaded at iframe-ready time (`player/src/hyperframes-player.ts:703-718`). The iframe runtime mutes its output; the parent proxies handle audible playback. **Both** the iframe video and the parent video decode simultaneously.
-
----
-
-## Concrete bottlenecks
-
-### 1. `setInterval(50 ms)` as the master clock
-
-`core/src/runtime/init.ts:1502-1561`. Not vsync-aligned — on 60/120 Hz displays, ticks land at arbitrary points in the frame, producing beat-frequency stutter. Every tick unconditionally runs `syncCurrentTimeFromTimeline()`; `syncMediaForCurrentState()` is gated on `isPlaying` (line 1557). The per-tick media iteration is the dominant cost for 10-video grids because each clip's `currentTime` read/compare runs on every active element.
-
-**Backgrounding concern:** When replacing with rAF, note that `requestAnimationFrame` stops firing when the tab is hidden (Page Visibility API). The current `setInterval` also throttles to ~1 Hz when backgrounded, but it doesn't stop entirely. The fix must include a fallback interval for keep-alive when the page is not visible.
-
-### 2. Drift correction thrashes decoders
-
-`core/src/runtime/media.ts:160-174`. The correction logic has three thresholds:
-- **0.5 s "hard" threshold** (line 166): `offsetJumped = Math.abs(offset - prevOffset!) > 0.5`
-- **`firstTickOfClip`** (line 165): forces a resync when `prevOffset === undefined` — painful for compositions with many sub-compositions that activate/deactivate clips frequently.
-- **3 s "catastrophic" threshold** (line 167): forces correction regardless of other conditions.
-
-Repeated `el.currentTime = relTime` writes (line 170) trigger decode-pipeline flushes. The 0.5 s threshold helps steady-state, but `firstTickOfClip` fires on every sub-composition entry.
-
-### 3. Seek is async through postMessage
-
-No same-frame UI feedback on a scrub. Studio works around it with direct `__player` access (`useTimelinePlayer.ts:233`), which only works same-origin. External embeds using the public API will feel laggy.
-
-### 4. Parent-proxy `<video>` doubles decoders unnecessarily
-
-`_adoptIframeMedia` (`player/src/hyperframes-player.ts:725-756`) mirrors `<video data-start>` into a parent `<video>`. The proxy exists **only for audio output** — the visual stays in the iframe. But creating a `<video>` element forces a second video decoder even though only the audio track is needed.
-
-For a 5-video composition promoted to parent ownership, that's 10 simultaneous video decoders when 5 video + 5 audio would suffice.
-
-**Note:** The proxy system itself is well-designed — preloading at iframe-ready time gives tight audio cut-in on promotion, one-way ownership prevents thrashing, and the 50 ms mirror drift threshold is ITU-compliant. The fix is narrow: use `<audio>` elements for video-source proxies.
-
-### 5. MutationObserver on full iframe body subtree
-
-`player/src/hyperframes-player.ts:803` — `obs.observe(doc.body, { childList: true, subtree: true })`. For image/video-heavy compositions with dynamic CSS/DOM, this fires constantly for mutations unrelated to media adoption.
-
-### 6. `postState` fires at up to ~12–15 Hz during playback
-
-`bridgeMaxPostIntervalMs: 80` (`core/src/runtime/state.ts:67`). Each hop serializes/deserializes, wakes the parent event loop, runs `_mirrorParentMediaTime` which loops through all proxies. Cost scales linearly with proxy count.
-
-### 7. `document.querySelectorAll("video[data-start], audio[data-start]")` re-run frequently
-
-`core/src/runtime/media.ts:23`. Cached in state but invalidated on sub-composition activation. Not catastrophic, but unnecessary churn in compositions with many clips.
-
-### 8. Per-instance shadow stylesheet
-
-`PLAYER_STYLES` is a raw CSS string (`player/src/styles.ts:1-198`) injected via `style.textContent = PLAYER_STYLES` per player instance (`player/src/hyperframes-player.ts:88`). In studio panels with thumbnails (multiple `<hyperframes-player>` nodes), this creates N duplicate `<style>` elements. `adoptedStyleSheets` with a shared `CSSStyleSheet` would eliminate the copies.
-
-### 9. Full iframe reload on every composition switch
-
-Setting `iframe.src` triggers a fresh HTML parse + script load + runtime bootstrap + full teardown of prior state (`player/src/hyperframes-player.ts:385-410`). Studio mounts a separate iframe per thumbnail — the expensive path repeated N times per project.
-
-### 10. Outer `transform: scale()` — likely a non-issue
-
-The iframe is scaled with `transform: translate(-50%, -50%) scale(S)` (`player/src/hyperframes-player.ts:530`). The original draft speculated this might inhibit hardware video overlay promotion. However, Chromium's `OverlayProcessor` promotes when the transform decomposes to a 2D axis-aligned translate/scale, which this transform does. Overlay promotion is more commonly blocked by non-axis-aligned transforms, blend modes, filters, or clip-path — none of which apply here.
-
-**Recommendation:** Verify with a `chrome://gpu` trace in Phase 0. If confirmed as a non-issue (expected), remove from the action list. If the trace shows unexpected layer behavior, revisit.
-
----
-
-## Recommended actions (ordered by impact-per-effort)
-
-### 1. Replace the 50 ms `setInterval` with `requestAnimationFrame`
-
-During `isPlaying`, use rAF for vsync-aligned ticks. Add a 250 ms `setInterval` fallback for:
-- **Paused keep-alives** — the player still needs to post state occasionally.
-- **Hidden-tab fallback** — rAF stops firing when `document.hidden === true`. Listen for `visibilitychange` to swap between rAF and interval.
-- **Headless capture** — the producer package runs under Puppeteer's virtual time and already replaces `window.requestAnimationFrame` wholesale with a virtual-time queue (`producer/src/services/fileServer.ts:104-117`). Guard with `window.__HF_VIRTUAL_TIME__ === undefined` and fall back to the existing `setInterval` path. This makes the rAF swap safer than it might seem — producer intercepts rAF at a higher level — but the guard ensures the runtime's own fallback is explicit.
-
-**Interaction with Action #2:** Moving from 20 Hz (50 ms interval) to 60 Hz (rAF) means 3x more ticks. This is fine because Action #2 removes the expensive per-tick work (drift polling). Without Action #2, rAF alone would *increase* per-tick cost. **These two actions must ship together in Phase 2.**
-
-### 2. Use `requestVideoFrameCallback()` to measure drift, not per-tick polling
-
-RVFC fires when a video frame has been composited, exposing `metadata.mediaTime` — the actual presented media time. Replace the per-tick `el.currentTime` read/compare with an RVFC-driven observation:
-
-```
-function onVideoFrame(now, metadata) {
-  const drift = Math.abs(metadata.mediaTime - expectedMediaTime);
-  if (drift > 0.5) el.currentTime = expectedMediaTime;
-  el.requestVideoFrameCallback(onVideoFrame);
-}
-```
-
-This cuts per-tick media iteration cost to zero for RVFC-capable elements during active playback. `<audio>` elements and older browsers fall back to the existing per-tick path.
-
-**State-transition gap:** RVFC only fires while the video is actively playing and presenting frames. It does **not** fire during pause, seek-while-paused, clip activation/deactivation, or pre-start. The per-tick polling path must remain active for these state transitions — RVFC replaces steady-state drift observation, not the full media sync loop. Specifically: `firstTickOfClip` resyncs and seek corrections still run through the interval/rAF tick path.
-
-**Browser support:** RVFC is available in Chrome 83+, Edge 83+, Safari 15.4+, Firefox 132+. No iOS Safari support below 15.4. Check the player's browser support baseline — if it includes older Safari, the fallback path must remain robust.
-
-### 3. Use `<audio>` for video-source proxies (hypothesis — gated on Phase 0)
-
-**Hypothesis:** In `_createParentMedia` (`player/src/hyperframes-player.ts:656-675`), parent proxies for `<video>` sources could use `<audio>` elements instead of `<video>` elements, since the proxy only needs audio output — the visual stays in the iframe. If browsers reliably decode audio from video containers (MP4/H.264+AAC, WebM/VP9+Opus) via `<audio>`, this would halve decoder pressure under parent-proxy promotion.
-
-**Why this needs validation, not assumption:** The current proxy system is an intentional separation of concerns — the iframe video handles visuals, the parent video handles audio. The `<video>` tag in the parent ensures decoder-state parity with the iframe's media timeline. On mobile, video codec state can be tightly coupled with power management, and `<audio src="video.mp4">` may not reliably extract the audio track on all platforms. If A/V sync regresses or decoder-count reduction doesn't materialize, keep the current design.
-
-**Phase 0 gate:** Test `<audio src="video.mp4">` playback on Chrome desktop, Chrome Android, Safari desktop, and Safari iOS with 5 representative composition videos. Measure decoder count (`webkitDecodedFrameCount`) and A/V sync drift. Only proceed if decoder count drops and sync holds within 50 ms on all platforms.
-
-**Do NOT use `document.adoptNode` to transfer `<video>` elements from the iframe.** Adopting a playing `<video>` into a different document resets the decoder pipeline, causing a rebuffer.
-
-### 4. Share the player stylesheet via `adoptedStyleSheets`
-
-One `CSSStyleSheet` constructed with `new CSSStyleSheet()`, populated with `PLAYER_STYLES`, assigned to every player shadow root via `shadowRoot.adoptedStyleSheets = [sharedSheet]`. Eliminates N duplicate `<style>` elements in studio's thumbnail grid.
-
-### 5. Scope the MutationObserver to `[data-composition-id]` host nodes
-
-Instead of `doc.body` with `{ childList: true, subtree: true }`, observe only the composition host elements. This reduces mutation callbacks to composition-relevant DOM changes.
-
-In inline mode (Phase 4), the MutationObserver for media adoption becomes unnecessary — media elements are already in the parent document.
-
-### 6. Expose a synchronous `seek()` on the public player API
-
-Studio already does this privately via `iframe.contentWindow.__player`. Formalize it:
-
-```
-// On the <hyperframes-player> element
-player.seek(frame)  // synchronous when same-origin
-player.seek(frame)  // async fallback when cross-origin (postMessage bridge)
-```
-
-Detect same-origin access with a try/catch on `iframe.contentWindow` access. External cross-origin embeds fall back to the async bridge transparently.
-
-### 7. Fast composition switching
-
-Two complementary strategies:
-
-**7a. `srcdoc` for studio (no network round-trip):** Studio already has composition HTML as a string. Use `iframe.srcdoc = compositionHtml` instead of `iframe.src = url`. This eliminates the network fetch and is faster than a pool for single-composition switches.
-
-**7b. Warm iframe pool (optional, for rapid switching):** For cases where the user rapidly switches between compositions (project browser), maintain a pool of up to **3 warm iframes** (LRU by composition-id). **Exclude thumbnail grids** — thumbnails should use static screenshots, not live iframes.
-
-Each warm iframe retains a full runtime + adapters + GSAP (+ potentially Three/Lottie), so memory pressure is real. Enforce a hard cap and evict the least-recently-used iframe when the cap is hit. Monitor total iframe memory in Phase 0 to validate the cap.
-
-### 8. Coalesce `_mirrorParentMediaTime` writes
-
-Tighten the threshold: only write `el.currentTime` when drift is *trending* (consecutive readings above threshold), not on a single spike. This reduces seek thrash during transient jitter without loosening the steady-state sync guarantee.
-
----
-
-## Architectural alternative: two-mode player
-
-The iframe exists for two reasons — **CSS isolation** (composition CSS doesn't leak to host) and **script isolation** (composition `<script>` doesn't touch host globals). In 2026, Shadow DOM handles CSS isolation fully; ES-module scoping handles script isolation for format-constrained compositions.
-
-### `mode="isolated"` (iframe — current default)
-
-What public embeds use. Keeps untrusted composition scripts sandboxed in a separate realm. The iframe's `window` global is distinct from the host page's.
-
-### `mode="inline"` (shadow DOM, no iframe)
-
-What studio and first-party hosts use.
-
-- Composition HTML is parsed into a `<template>`, cloned into the player's shadow root.
-- Runtime runs in the parent realm — **no postMessage, synchronous** `play`/`pause`/`seek`.
-- `<video>` elements are real siblings of the host page — user activation propagates same-frame, eliminating the autoplay-gate and the entire parent-proxy promotion path.
-- GSAP timelines are reached directly — studio's `__player` pattern becomes the public API.
-- Compositing is one layer tree, not two.
-
-### Security model
-
-**The trust boundary must be explicit.** A same-origin iframe is a separate realm-of-scripts — it prevents a composition from accidentally calling `window.location.assign` or accessing host cookies. Inline mode removes that boundary.
-
-Three trust levels:
-
-| Level | Mode | When |
-|-------|------|------|
-| **Untrusted** | `isolated` (iframe) | Third-party embeds, user-shared compositions |
-| **Format-constrained** | `inline` with validation gate | Studio preview of compositions that pass the linter and contain only registered adapters (GSAP, Lottie, Three.js) — no arbitrary `<script>` tags |
-| **Fully trusted** | `inline` without gate | First-party compositions authored by the studio's own generator pipeline |
-
-**Implementation:** Add a `canRunInline(compositionHtml): boolean` gate. Parse the HTML with linkedom (already a dependency via `htmlBundler.ts`) and reject if any of these fail:
-
-1. **Script allowlist:** Every `<script src>` URL must match the registered CDN allowlist (GSAP `cdn.jsdelivr.net/npm/gsap@3`, Lottie, Three.js — enumerated, not pattern-matched). Unknown external scripts → reject.
-2. **Inline script denylist check:** Scan each inline `<script>` body for dangerous patterns. This is a denylist approach (reject known-bad) rather than an allowlist AST parse, because compositions legitimately use `addEventListener`, `IntersectionObserver`, `requestAnimationFrame`, `MutationObserver`, `CustomEvent`, and dynamic `document.createElement` for Three.js scenes, scroll-linked animations, and Lottie setup. Reject scripts containing: `fetch(`, `XMLHttpRequest`, `import(`, `eval(`, `Function(`, `document.cookie`, `localStorage`, `sessionStorage`, `window.location`, `window.parent`, `window.top`, `window.opener`, `postMessage(` (outside the runtime bridge). Use a regex scan — adding a JS parser dependency (no JS parser exists in the project today) is not justified for a denylist.
-3. **No inline event handlers:** Reject elements with `on*` attributes (`onclick`, `onerror`, `onload`, etc.).
-4. **Linter pass:** No `external_script_dependency` warnings on unknown scripts.
-
-Compositions that fail the gate fall back to `isolated` mode automatically. This makes inline mode safe-by-default. The gate runs at composition-load time, not per-frame — the cost is a single parse per composition switch.
-
-**Composition scripts also need IIFE wrapping at compile time** — the bundler already does this (`core/src/runtime/compositionLoader.ts:206`), but inline mode must ensure the wrapping applies in the parent realm too, preventing global leakage.
-
-### Runtime refactoring scope
-
-The runtime currently makes **30+ `document.*` queries, sets 7 `window.*` globals, registers 5 window event listeners, and communicates via `window.parent.postMessage`** across ~12 source files (`init.ts`, `bridge.ts`, `media.ts`, `state.ts`, `timeline.ts`, `entry.ts`, `picker.ts`, `compositionLoader.ts`, and 5 adapter files`).
-
-Making the runtime realm-agnostic requires:
-
-1. **Scope injection** — every `document.querySelector*` call takes a `root` parameter (either `document` or a `ShadowRoot`). Every `window.*` global becomes a property on a context object passed at init time.
-
-2. **Bridge abstraction** — `postRuntimeMessage` calls a callback instead of `window.parent.postMessage`. In iframe mode, the callback is postMessage. In inline mode, it's a direct function call.
-
-3. **Adapter scoping** — CSS adapter's `document.querySelectorAll("*")` and WAAPI adapter's `document.getAnimations()` must scope to the composition root. Lottie and Three.js adapters read `window.__hfLottie` / `window.__hfThreeTime` — these become context properties.
-
-4. **Picker machinery** — the picker uses `document.elementsFromPoint()`, `document.body.classList`, and captures document-level mouse/keyboard events. In inline mode, these must scope to the shadow root. `elementsFromPoint` specifically needs to be called on the shadow root (`shadowRoot.elementsFromPoint`), which is supported in modern browsers.
-
-5. **Multi-instance isolation** — multiple inline players on the same page must not collide. The current `window.__timelines` registry is keyed by composition ID — but in studio, the same composition can be open in multiple panels (preview + scene editor). Same composition ID, two inline players, one `__timelines` registry = the second instance overwrites the first's timeline. **`__timelines` must move out of the global scope and into the per-instance `RuntimeContext`.** This is load-bearing for Phase 4.
-
-**Estimated scope:** ~500-800 LOC of refactoring across 12 files to introduce a `RuntimeContext` interface, plus adapter updates and picker scoping. The heaviest lift is `init.ts` (~1650 lines) which concentrates most of the `window.*` and `document.*` references. The picker machinery (`picker.ts`) is the second-heaviest due to its `elementsFromPoint`, event capture, and style injection patterns.
-
----
-
-## What not to do (yet)
-
-- **Full WebCodecs + OffscreenCanvas rewrite.** Throws away the "HTML *is* the composition" premise. CSS animations, nested iframes, Lottie, Three.js, and text layout stop working in a canvas. Reserve for a separate rendering backend used only for export (producer already lives there).
-
-- **`AudioContext` mixer for all audio.** A `MediaElementAudioSourceNode` wrapper could aggregate cleanly for the asset-URL case. But don't aggregate until profiling confirms per-element decoder count is actually the bottleneck after Action #3 (audio-only proxies) ships.
-
----
-
-## Proposed rollout order
-
-### Phase 0 — Measure and establish baselines (~0.5 week)
-
-Capture the traces listed in the Validation Plan on a representative 10-video composition. **Do not start Phase 1 until the traces confirm the bottleneck claims.**
-
-**Pass/fail SLOs for each subsequent phase:**
-
-Phase 0 will establish current baselines (the "est." column below). Absolute targets are UX-motivated and hold regardless of baseline.
-
-| Metric | Current (est.) | Phase 2 target | Phase 4 target |
-|--------|---------------|----------------|----------------|
-| Scrub latency (same-origin) | ~100 ms | p50 < 50 ms, p95 < 80 ms | p50 < 16 ms, p95 < 33 ms |
-| Scrub latency (cross-origin) | ~100 ms | p50 < 80 ms, p95 < 120 ms | p50 < 50 ms, p95 < 80 ms |
-| Composition switch (warm) | ~1500 ms | < 800 ms | < 300 ms |
-| Composition switch (cold) | ~2000 ms | < 1500 ms | < 1500 ms (< 2000 ms for heavy*) |
-| Sustained fps (10-video) | ~30-45 fps | 60 fps | 60 fps |
-| Decoder count under promotion | 2N | N (if Action #3 validates) | 0 (no promotion) |
-| Dropped frames (10s playback) | TBD | < 5 | < 2 |
-
-\* "Heavy" = compositions with Three.js + Lottie + WebGL context + >5 MB total assets. These have irreducible cold-start costs (WebGL context init, large asset decode) that inline mode doesn't eliminate.
-
-### Phase 1 — Low-risk wins (~1 week, no API change)
-
-- `adoptedStyleSheets` for shared player styles
-- Scoped MutationObserver
-- Audio-only proxy prototype (`<audio>` for video-source parent media) — validate on 4 browser/OS combos. Ship only if decoder count drops and A/V sync holds.
-- Coalesced `_mirrorParentMediaTime` writes
-- Verify outer-transform overlay-promotion hypothesis via `chrome://gpu` trace (expected: non-issue, close the item)
-
-**Phase 1 validation:** Mirror write frequency drops by >50%. If audio-only proxy validates, decoder count under promotion drops to N.
-
-### Phase 2 — Runtime clock + RVFC (~1–2 weeks)
-
-- Replace `setInterval` with rAF (with visibility-change fallback and headless guard)
-- RVFC-driven drift observation (ships together with rAF — see interaction note in Action #1)
-- Producer parity regression suite run on day one
-
-**Phase 2 validation:** 60 fps sustained on 10-video comp. Dropped frames < 5 per 10s. Producer parity harness green.
-
-### Phase 3 — Synchronous seek + fast switching (~1–2 weeks)
-
-- Synchronous `seek()` API on the player element (same-origin detection)
-- `srcdoc` composition switching for studio
-- Optional warm iframe pool (cap at 3, LRU, exclude thumbnails)
-
-**Phase 3 validation:** Scrub latency < 50 ms same-origin. Composition switch < 800 ms warm.
-
-### Phase 4a — Inline mode behind flag, studio-only (~5–7 weeks for 1 engineer, ~3–4 weeks for 2)
-
-**Staffing assumption:** The scope splits naturally into (A) runtime/adapters (RuntimeContext, bridge abstraction, adapter scoping — concentrated in `core/`) and (B) player/gate/studio (inline player mode, `canRunInline()`, studio wiring — concentrated in `player/` and `studio/`). Two engineers with clear file-ownership can parallelize.
-
-- `RuntimeContext` interface: scope injection for all `document.*` / `window.*` references
-- Bridge abstraction (direct callback in inline mode)
-- Adapter scoping (GSAP, Lottie, Three.js, CSS, WAAPI)
-- Multi-instance isolation: move `window.__timelines` into per-instance `RuntimeContext` (same composition ID in two inline players must not collide)
-- `canRunInline()` composition validation gate
-- Shadow DOM CSS compatibility validation:
-  - `@font-face` declarations — Chrome requires these in the document, not the shadow root. Compositions using custom fonts need font-face rules hoisted to the document at mount time.
-  - `vh`/`vw` units resolve against the viewport, not the composition container. Compositions using viewport-relative units need transformation to container-relative units (or CSS `cqi`/`cqb` with container queries).
-  - `:root` selectors target the document root, not the shadow host. Compositions using `:root { --custom-prop: ... }` need selector rewriting to `:host`.
-- Inline player mode wired up behind `__HF_INLINE_PLAYER` feature flag
-- Studio opts in for preview panel only (not thumbnails)
-
-**Phase 4a validation:** Studio preview works in inline mode for 5 representative compositions (including at least one with custom fonts and one with viewport-relative units). Scrub latency p50 < 16 ms. No autoplay-proxy path triggered. Feature flag can be toggled without reload.
-
-### Phase 4b — Inline mode as studio default (~2–3 weeks)
-
-- Remove feature flag, inline is default for studio
-- Migrate all studio call sites (preview, scene editor, export preview)
-- Thumbnails remain iframe-based (static screenshot preferred)
-- Producer compat shim (producer continues using iframe/headless path, unaffected)
-- Public API stabilization: `<hyperframes-player mode="inline|isolated">`
-
-**Phase 4b validation:** All studio E2E tests pass. No regressions in public embed path. Memory usage in studio < 1.2x current with 10+ compositions open.
-
----
-
-## Producer impact
-
-`packages/producer` consumes `@hyperframes/core`'s runtime for headless rendering via Puppeteer. `producer/src/services/renderOrchestrator.ts` and the parity harness (`producer/src/parity-harness.ts`) both bind against `__timelines`.
-
-**What's affected:**
-
-- **Phase 2 (rAF clock):** Headless rendering drives time virtually (seek-per-frame). rAF firing semantics under Puppeteer's virtual time differ from live playback. Producer already replaces `window.requestAnimationFrame` with a virtual-time queue (`fileServer.ts:104-117`), but the runtime's own `__HF_VIRTUAL_TIME__` guard provides an explicit fallback to `setInterval`.
-- **Phase 4 (`RuntimeContext`):** Producer imports the IIFE runtime bundle. The `RuntimeContext` refactor must preserve the existing default export where `root = document` and `globals = window`. Producer never uses inline mode.
-
-**Mitigation:** Run the producer parity harness as a CI gate on every Phase 2+ PR. If the harness doesn't cover the clock/media-sync paths (verify in Phase 0), extend it before starting Phase 2.
-
----
-
-## Validation plan (run before landing fixes)
-
-### Pre-land traces (Phase 0)
-
-1. **Chrome Performance profile** on a representative 10-video composition during 10s of playback. Confirm the 50 ms tick is actually hot and that drift-correction `currentTime` writes show up as decoder flushes. Record CPU time in the setInterval callback.
-
-2. **Decoder-count trace** — log `video.webkitDecodedFrameCount` and `video.webkitDroppedFrameCount` per-clip before and after promotion to parent-proxy audio ownership. Confirms the "double decoder" claim under autoplay-block. Test with `<audio src="video.mp4">` to validate the audio-only proxy approach.
-
-3. **Composited-layers dump** (`chrome://gpu` + `chrome://tracing` with `cc,viz` categories) to confirm or reject the outer-transform overlay-promotion hypothesis. **Expected result: non-issue.** Document and close.
-
-4. **Scrub latency** — record timestamp from `mousedown` on scrubber to first frame update in the preview, under both cross-origin (public) and same-origin (studio) paths. Establishes the "synchronous seek" benefit numerically.
-
-5. **Composition-switch time** — record iframe `load` → `ready` for 5 representative compositions. Baseline for the fast-switch proposal. Compare `iframe.src` vs `iframe.srcdoc` for studio's case.
-
-6. **Memory profile** — measure per-iframe memory overhead with a representative composition (runtime + GSAP + adapters). Establishes the memory cap for the warm iframe pool. If per-iframe cost is >50 MB, pool size may need to be capped at 2 instead of 3.
-
-7. **RVFC browser coverage** — verify `requestVideoFrameCallback` availability across the player's supported browser matrix. Identify which browsers fall back to per-tick polling and ensure the fallback path remains correct.
-
-8. **Composition corpus audit for `canRunInline()`** — run the proposed denylist gate against 20 representative shipped compositions (GSAP-only, GSAP+Lottie, Three.js scenes, audio-reactive, etc.). Report the pass/fail rate. If fewer than 70% of studio-authored compositions pass, the denylist is too aggressive and needs tuning before Phase 4a.
-
-9. **Producer parity harness coverage check** — the existing parity harness (`producer/src/parity-harness.ts`) uses synchronous `renderSeek()` per-frame, which bypasses the interval/rAF clock entirely. It proves frame-accurate rendering but does **not** validate live-playback timing, media sync cadence, or state posting under the new clock. Phase 2 requires a separate **live-playback regression test**: play a 10-second composition end-to-end, assert dropped frames < 5 and A/V sync drift < 50 ms. Build this test in Phase 0 so it's ready when Phase 2 starts.
-
-Store raw Phase 0 traces alongside this doc under `notes/traces/player-perf-2026-04/`.
-
----
-
-## Automated performance tests
-
-PostHog telemetry catches regressions in production after deploy. Automated perf tests catch them in CI before merge. We need both.
-
-### What exists today
-
-The producer already has a perf gate pattern we can follow:
-
-- **`producer/src/benchmark.ts`** — runs each test fixture multiple times, records per-stage timing, saves to `tests/perf/benchmark-results.json`.
-- **`producer/src/perf-gate.ts`** — compares measured time against `tests/perf/baseline.json` (currently 90s max, 15% regression tolerance). Fails CI if exceeded.
-- **`producer/src/parity-harness.ts`** — synchronous seek-per-frame rendering. Proves frame accuracy but doesn't exercise live-playback timing.
-
-The player has no perf tests of any kind.
-
-### Proposed test suite
-
-All tests run in headless Chromium via Playwright (already a dev dependency for studio E2E). Each test loads a composition in a `<hyperframes-player>` element, exercises a specific operation, and asserts timing against a baseline.
-
-#### Test 1: Playback frame rate (`player-perf-fps`)
-
-```
-Load 10-video composition → play for 5 seconds → collect rAF tick count + dropped frames
-Assert: fps >= 55 (allow 8% drop from 60), dropped frames < 3
-```
-
-**What it catches:** rAF clock regressions, per-tick work bloat, media sync overhead.
-
-Runs in both `isolated` (iframe) and `inline` (shadow DOM, Phase 4+) modes.
-
-#### Test 2: Scrub latency (`player-perf-scrub`)
-
-```
-Load composition → seek to 10 positions in sequence → measure time from seek() call to state update callback
-Assert: p95 < 80ms (isolated), p95 < 33ms (inline, Phase 4+)
-```
-
-**What it catches:** Bridge latency regressions, seek path overhead, state posting delays.
-
-#### Test 3: Composition load time (`player-perf-load`)
-
-```
-Set player src to 5 different compositions in sequence → measure per-composition load → ready time
-Assert: p95 < 2000ms cold, p95 < 1000ms warm (with srcdoc, Phase 3+)
-```
-
-**What it catches:** Runtime bootstrap regressions, iframe pool issues, srcdoc path regressions.
-
-#### Test 4: Media sync drift (`player-perf-drift`)
-
-```
-Load 5-video composition → play for 10 seconds → on each RVFC callback, record drift between expected and actual media time
-Assert: max drift < 500ms, p95 drift < 100ms
-```
-
-**What it catches:** RVFC fallback regressions, drift correction threshold issues, clock/media desync.
-
-#### Test 5: Live-playback parity (`player-perf-live-parity`)
-
-This is the test missing from the producer harness. It exercises the **live clock path** (rAF/interval), not the synchronous seek-per-frame path:
-
-```
-Load composition → play from start to end (10s) → compare final frame against producer's reference screenshot
-Assert: SSIM > 0.95 (structural similarity), A/V drift < 50ms at end
-```
-
-**What it catches:** Any divergence between the live-playback clock and the producer's deterministic clock. This is the Phase 2 safety net.
-
-### Test fixtures
-
-Create `player/tests/perf/fixtures/` with 3 representative compositions:
-
-| Fixture | Content | Purpose |
-|---------|---------|---------|
-| `10-video-grid` | 10 overlapping video clips, GSAP stagger | Stress test for decoder count, media sync, fps |
-| `gsap-heavy` | 50+ animated elements, timeline with 200 tweens, no media | Stress test for GSAP seek performance |
-| `sub-compositions` | 3 nested sub-compositions with their own timelines | Stress test for `firstTickOfClip` resync, MutationObserver |
-
-### Baselines
-
-Follow the producer's pattern: store baselines in `player/tests/perf/baseline.json`:
-
-```json
-{
-  "fps_min": 55,
-  "scrub_latency_p95_isolated_ms": 80,
-  "scrub_latency_p95_inline_ms": 33,
-  "comp_load_cold_p95_ms": 2000,
-  "comp_load_warm_p95_ms": 1000,
-  "drift_max_ms": 500,
-  "drift_p95_ms": 100,
-  "allowed_regression_ratio": 0.10
-}
-```
-
-The perf gate script compares each measured value against `baseline * (1 + allowed_regression_ratio)`. Update baselines after each phase lands (Phase 0 establishes the first set, each subsequent phase tightens them).
-
-### CI integration
-
-Add a `player:perf` script to the root `package.json`:
-
-```
-bun run player:perf   # runs all 5 tests, outputs JSON, exits non-zero on regression
-```
-
-Run in CI on every PR that touches `packages/player/` or `packages/core/src/runtime/`. Not on every PR — Playwright + Chromium is ~30s overhead that shouldn't gate unrelated changes.
-
-### When to update baselines
-
-- **After Phase 0:** Initial baselines from measured current state.
-- **After each phase lands:** Tighten baselines to the new measured values (the improvement becomes the new floor).
-- **Never loosen baselines** without an explicit decision and comment in the baseline file explaining why.
-
-### Implementation: PR P0-1 (revised)
-
-PR P0-1 now covers both the live-playback parity test AND the full perf test suite:
-
-1. `player/tests/perf/` — test runner, 5 test files, 3 fixtures, baseline.json
-2. `player/tests/perf/perf-gate.ts` — baseline comparison (same pattern as `producer/src/perf-gate.ts`)
-3. Root `package.json` — add `player:perf` script
-4. CI config — gate on `packages/player/**` and `packages/core/src/runtime/**` changes
-
----
-
-## Performance observability
-
-### Current state
-
-Two telemetry paths exist today, neither covers player performance:
-
-1. **CLI telemetry** (`cli/src/telemetry/client.ts`) — lightweight PostHog client using the HTTP batch API directly (no SDK). Anonymous, opt-in, fire-and-forget. Tracks CLI command usage only. Uses PostHog project key `phc_zjjb…`.
-
-2. **Runtime analytics bridge** (`core/src/runtime/analytics.ts`) — vendor-agnostic. The runtime emits structured events via postMessage (`{ source: "hf-preview", type: "analytics", event, properties }`). The host app listens and forwards to its own analytics provider. Today this covers 6 discrete events: `composition_loaded`, `composition_played`, `composition_paused`, `composition_seeked`, `composition_ended`, `element_picked`. No performance metrics.
-
-3. **Player package** — no telemetry of any kind.
-
-### What we need
-
-Continuous performance metrics flowing to PostHog so we can:
-- Verify each phase actually improved the target metric
-- Detect regressions after deploy
-- Compare performance across browser/OS/hardware segments
-- Track inline mode adoption and its impact (Phase 4+)
-
-### Architecture
-
-Extend the existing runtime analytics bridge with a `performance` message type. The player (as the host) listens, aggregates per-session, and flushes to PostHog using the same lightweight HTTP batch pattern as the CLI — no PostHog SDK needed.
-
-```
-                    ┌─────────────────────────────────┐
-                    │  iframe (core/runtime)           │
-                    │                                  │
-                    │  performance.mark("hf:seek:start")
-                    │  performance.measure(...)        │
-                    │  postMessage({ type: "perf" })  ─┼──┐
-                    └─────────────────────────────────┘  │
-                                                         │ postMessage
-                    ┌─────────────────────────────────┐  │
-                    │  player (host)                   │◄─┘
-                    │                                  │
-                    │  Aggregates per-session metrics  │
-                    │  Flushes to PostHog on:          │
-                    │    - composition_ended            │
-                    │    - page unload (sendBeacon)     │
-                    │    - 60s idle timeout             │
-                    └──────────────┬──────────────────┘
-                                   │ HTTP POST (batch API)
-                    ┌──────────────▼──────────────────┐
-                    │  PostHog (us.i.posthog.com)      │
-                    │  Same project as CLI telemetry   │
-                    └─────────────────────────────────┘
-```
-
-In inline mode (Phase 4), there's no iframe boundary — the runtime emits directly to the player's aggregator via the `RuntimeContext.bridge` callback.
-
-### Metrics
-
-| Metric | Event name | Collection point | When emitted | Phase |
-|--------|-----------|-----------------|--------------|-------|
-| Scrub latency | `player_scrub_latency` | Player: `mousedown` → first state update | End of each scrub gesture | 1+ |
-| Playback fps | `player_playback_fps` | Runtime: rAF tick count / elapsed time | Every 5s during playback, and on pause/end | 2+ |
-| Dropped frames | `player_dropped_frames` | Runtime: `video.webkitDroppedFrameCount` delta | On composition_ended | 2+ |
-| Decoder count | `player_decoder_count` | Player: count of active `<video>` + `<audio>` elements | On promotion to parent-proxy | 1+ |
-| Composition load time | `player_comp_load` | Player: iframe `load` → runtime `ready` | On each composition load | 1+ |
-| Media sync drift | `player_sync_drift_max` | Runtime: max observed drift during session | On composition_ended | 2+ |
-| Inline mode used | `player_inline_mode` | Player: boolean, which mode was selected | On composition load | 4a+ |
-| `canRunInline` result | `player_inline_gate` | Player: pass/fail + failure reason | On composition load (inline-capable hosts only) | 4a+ |
-
-### Properties on every event
-
-```
-{
-  // anonymous session (no PII)
-  distinct_id: <anonymous_session_id>,  // random UUID per browser session
-  $ip: null,                            // tell PostHog to discard IP
-
-  // context
-  player_version: "0.4.12",
-  player_mode: "isolated" | "inline",
-  composition_id: <hash>,               // hashed, not raw
-  media_count: 5,                        // number of timed media elements
-
-  // environment
-  browser: "Chrome 126",
-  os: "macOS 15.1",
-  viewport_width: 1920,
-  screen_refresh_rate: 60,               // from screen.refreshRate if available
-  device_memory: 8,                      // navigator.deviceMemory (Chrome only)
-  hardware_concurrency: 8,               // navigator.hardwareConcurrency
-}
-```
-
-No user IDs, no file paths, no composition content, no cookies. Same privacy posture as the CLI telemetry.
-
-### Opt-in / opt-out
-
-The player doesn't have its own opt-in flow today. Two approaches:
-
-1. **Host-controlled:** The `<hyperframes-player>` element accepts a `telemetry` attribute. Default: `off`. Studio sets it to `on` (respecting the user's existing CLI telemetry preference if available). Public embeds stay off unless the host explicitly opts in.
-
-2. **Respect `DO_NOT_TRACK`:** Check `navigator.doNotTrack === "1"` or `navigator.globalPrivacyControl === true`. If either is set, no metrics are collected regardless of the attribute.
-
-### Before/after methodology
-
-Each PR that targets a specific metric must:
-
-1. **Tag the deploy.** PostHog events include `player_version`. Bump the patch version on each phase's final PR so we can filter by version range.
-
-2. **Wait for sample size.** Don't declare victory on <1000 sessions. PostHog's trend graphs with version-based cohorts give us the before/after comparison without manual work.
-
-3. **Segment by environment.** Studio vs. public embed, browser, device memory, media count. A 50% improvement on Chrome desktop that regresses Safari mobile is not a win.
-
-4. **One phase at a time.** Don't overlap Phase 1 and Phase 2 deploys. Each phase gets at least 1 week of production data before the next ships. This is the only way to attribute improvements to specific changes.
-
-### Regression alerting
-
-PostHog doesn't have built-in metric alerting, but it supports webhooks on cohort changes. Set up:
-
-1. **PostHog insight:** `player_playback_fps` p10 by `player_version`, 7-day rolling window.
-2. **PostHog action:** trigger when p10 fps drops below 45 for any version cohort with >100 sessions.
-3. **Webhook:** fire to the team's Slack channel.
-
-Same pattern for `player_scrub_latency` p95 (alert if >150ms) and `player_dropped_frames` p90 (alert if >10).
-
-### Dashboard
-
-Create a PostHog dashboard: **"HyperFrames Player Performance"** with these panels:
-
-| Panel | Visualization | Breakdown |
-|-------|--------------|-----------|
-| Scrub latency p50/p95 | Line chart, 7-day rolling | by `player_version` |
-| Playback fps p10/p50 | Line chart, 7-day rolling | by `player_version` |
-| Dropped frames p50/p90 | Line chart, 7-day rolling | by `browser` |
-| Composition load time p50/p95 | Line chart, 7-day rolling | by `player_mode` |
-| Decoder count distribution | Bar chart | by `media_count` bucket |
-| Inline mode adoption | Stacked area | by `player_inline_gate` result |
-| Session volume | Counter | total sessions this week |
-
-### Implementation: PR X-1 scope (revised)
-
-PR X-1 (`feat(core,player): player performance telemetry`) now covers:
-
-1. **Runtime side** (`core/src/runtime/analytics.ts`): add `emitPerformanceMetric(name, value, tags)` that sends `{ source: "hf-preview", type: "perf", name, value, tags }` through the bridge. Uses `performance.mark`/`performance.measure` internally for DevTools visibility. No PostHog dependency in core.
-
-2. **Player side** (`player/src/hyperframes-player.ts`): listen for `type: "perf"` messages. Aggregate per-session (hold metrics in memory, compute p50/p95 on flush). Flush to PostHog via `fetch` + `navigator.sendBeacon` fallback on page unload. Same HTTP batch API pattern as CLI. Gated on `telemetry` attribute + DNT check.
-
-3. **Studio side**: set `telemetry="on"` on the preview player, respecting the user's existing telemetry preference.
-
-No PostHog SDK. No new dependencies. ~150 LOC.
-
----
-
-## Planned PRs
-
-Each PR is independently reviewable and shippable. Dependencies are noted — don't merge out of order.
-
-### Phase 0 — Measurement infrastructure
-
-| PR | Title | Packages | Files | Depends on |
-|----|-------|----------|-------|------------|
-| **P0-1** | feat(player): automated perf test suite + live-playback parity test | `player`, root | `player/tests/perf/` (runner, 5 tests, 3 fixtures, baseline.json, perf-gate.ts), root `package.json` | — |
-| **P0-2** | chore: Phase 0 trace results and baseline doc | `notes/` | `notes/traces/player-perf-2026-04/*.json`, update baseline.json with measured values, update this proposal with measured baselines | P0-1 |
-
-P0-1 creates the perf test infrastructure: 5 Playwright-based tests (fps, scrub latency, composition load, media sync drift, live-playback parity), 3 representative fixtures, baseline comparison gate, and CI integration for `packages/player/` and `packages/core/src/runtime/` changes. P0-2 is the manual trace capture — Chrome Performance profile, decoder-count trace, compositor-layers dump, memory profile, RVFC browser matrix, composition corpus audit for `canRunInline()`. Documented as raw traces + a summary addendum to this proposal. Also populates the initial baseline.json with measured values.
-
-### Phase 1 — Low-risk wins (4 independent PRs, can land in any order)
-
-| PR | Title | Packages | Key files | Depends on |
-|----|-------|----------|-----------|------------|
-| **P1-1** | perf(player): share PLAYER_STYLES via adoptedStyleSheets | `player` | `player/src/hyperframes-player.ts`, `player/src/styles.ts` | — |
-| **P1-2** | perf(player): scope MutationObserver to composition hosts | `player` | `player/src/hyperframes-player.ts` (~line 803) | — |
-| **P1-3** | perf(player): audio-only proxy for video-source parent media | `player` | `player/src/hyperframes-player.ts` (`_createParentMedia` ~line 656) | P0-2 (gated on trace #2 results) |
-| **P1-4** | perf(player): coalesce _mirrorParentMediaTime writes | `player` | `player/src/hyperframes-player.ts` (`_mirrorParentMediaTime` ~line 604) | — |
-
-P1-1 and P1-2 are the safest — pure player-internal changes with no API surface. P1-3 only ships if the Phase 0 audio-only proxy validation passes on all 4 browser/OS targets. P1-4 changes sync behavior so it needs a manual A/V sync check.
-
-### Phase 2 — Runtime clock + RVFC (1 PR — must ship together)
-
-| PR | Title | Packages | Key files | Depends on |
-|----|-------|----------|-----------|------------|
-| **P2-1** | perf(core): replace setInterval with rAF + RVFC drift observation | `core` | `core/src/runtime/init.ts` (~line 1502), `core/src/runtime/media.ts` (~line 160) | P0-1 (live-playback test exists), P0-2 (baselines established) |
-
-This is one PR because rAF without RVFC increases per-tick cost (3x more ticks with the same drift-polling work). The PR includes:
-- rAF loop during `isPlaying` with `visibilitychange` fallback to 250ms interval
-- `__HF_VIRTUAL_TIME__` guard for headless capture
-- RVFC-driven drift observation for `<video>` elements, with per-tick fallback retained for `<audio>`, state transitions (pause, seek, clip activation), and non-RVFC browsers
-- 250ms paused keep-alive interval
-
-**CI gate:** Producer parity harness + new live-playback regression test must both pass.
-
-### Phase 3 — Synchronous seek + fast switching (2-3 PRs)
-
-| PR | Title | Packages | Key files | Depends on |
-|----|-------|----------|-----------|------------|
-| **P3-1** | feat(player): synchronous seek() API with same-origin detection | `player` | `player/src/hyperframes-player.ts` | — |
-| **P3-2** | perf(player): srcdoc composition switching for studio | `player`, `studio` | `player/src/hyperframes-player.ts` (~line 146), studio composition-switch call sites | — |
-| **P3-3** | perf(player): warm iframe pool with LRU eviction | `player` | `player/src/hyperframes-player.ts` (new pool manager) | P0-2 (memory profile validates cap) |
-
-P3-1 formalizes studio's existing `__player` direct-access pattern as a public API. P3-2 adds `srcdoc` as an alternative to `src` for studio's case. P3-3 is optional — only ship if memory profiling confirms per-iframe cost allows a pool of 3. Thumbnail grids are explicitly excluded (use static screenshots instead).
-
-### Phase 4a — Inline mode behind flag (5 PRs with dependency chain)
-
-**Staffing:** PRs P4a-1 through P4a-3 are `core/` work (engineer A). PRs P4a-4 and P4a-5 are `player/`+`studio/` work (engineer B, can start after P4a-1 lands).
-
-| PR | Title | Packages | Key files | Depends on |
-|----|-------|----------|-----------|------------|
-| **P4a-1** | refactor(core): RuntimeContext interface + scope injection | `core` | `core/src/runtime/init.ts`, `core/src/runtime/media.ts`, `core/src/runtime/state.ts`, `core/src/runtime/timeline.ts`, `core/src/runtime/entry.ts`, `core/src/runtime/bridge.ts`, `core/src/runtime/compositionLoader.ts` | — |
-| **P4a-2** | refactor(core): adapter scoping + multi-instance __timelines | `core` | `core/src/runtime/adapters/gsap.ts`, `css.ts`, `waapi.ts`, `lottie.ts`, `three.ts` | P4a-1 |
-| **P4a-3** | refactor(core): picker shadow-root scoping | `core` | `core/src/runtime/picker.ts` | P4a-1 |
-| **P4a-4** | feat(core): canRunInline() validation gate + Shadow DOM CSS transforms | `core` | new `core/src/compiler/canRunInline.ts`, `core/src/compiler/htmlBundler.ts` (CSS transforms) | — |
-| **P4a-5** | feat(player): inline player mode behind __HF_INLINE_PLAYER flag | `player`, `studio` | `player/src/hyperframes-player.ts`, studio preview panel hook | P4a-1, P4a-2, P4a-3, P4a-4 |
-
-**P4a-1** is the biggest PR (~300-400 LOC). It introduces `RuntimeContext` with `root` (Document or ShadowRoot), `globals` (context object replacing window properties), and `bridge` (callback replacing postMessage). All `document.*` queries and `window.*` globals are parameterized. The default context is `{ root: document, globals: window, bridge: postMessage }` so the iframe path is unchanged.
-
-**P4a-2** scopes all 5 adapters to use `RuntimeContext` and moves `__timelines` from `window` into the per-instance context. This fixes the multi-instance collision where the same composition in two panels would overwrite each other's timeline.
-
-**P4a-3** is the picker refactor — `elementsFromPoint` on ShadowRoot, event capture scoped to the composition root, style injection into the shadow root instead of `document.head`.
-
-**P4a-4** is independent of the runtime refactor. It adds the `canRunInline()` denylist gate (linkedom HTML parse + regex script scan + CDN allowlist + `on*` attribute check) and the Shadow DOM CSS transforms (`@font-face` hoisting, `vh`/`vw` → container units, `:root` → `:host` selector rewriting).
-
-**P4a-5** wires everything together: the player's `mode="inline"` attribute, template-based composition mounting into shadow DOM, RuntimeContext instantiation with shadow root, and studio's preview panel opt-in behind the feature flag.
-
-### Phase 4b — Inline mode as default (2 PRs)
-
-| PR | Title | Packages | Key files | Depends on |
-|----|-------|----------|-----------|------------|
-| **P4b-1** | feat(player): inline mode default for studio + studio migration | `player`, `studio` | `player/src/hyperframes-player.ts`, all studio player call sites | P4a-5 |
-| **P4b-2** | feat(player): public API stabilization (mode="inline\|isolated") | `player` | `player/src/hyperframes-player.ts`, docs | P4b-1 |
-
-P4b-1 removes the feature flag and makes inline the default for studio. Migrates all studio call sites (preview, scene editor, export preview). Thumbnails stay iframe-based. P4b-2 stabilizes the public API surface and documents the mode attribute for external consumers.
-
-### Cross-cutting (ships alongside Phase 1+)
-
-| PR | Title | Packages | Key files | Depends on |
-|----|-------|----------|-----------|------------|
-| **X-1** | feat(core): emitPerformanceMetric bridge for post-land instrumentation | `core` | `core/src/runtime/analytics.ts`, `core/src/runtime/bridge.ts` | — |
-
-The existing `RuntimeAnalyticsEvent` union type covers discrete events (composition_loaded, composition_played, etc.). Performance counters (scrub latency, dropped frames, decoder count, load time) don't fit that shape. X-1 adds `emitPerformanceMetric(name, value, tags)` using `performance.mark`/`performance.measure` for client-side collection, with a bridge message for cross-frame reporting. Ship early so each phase can instrument its improvements.
-
-### PR summary
-
-| Phase | PRs | Total | Parallel tracks |
-|-------|-----|-------|-----------------|
-| 0 | P0-1, P0-2 | 2 | 1 |
-| 1 | P1-1, P1-2, P1-3, P1-4 | 4 | all independent |
-| 2 | P2-1 | 1 | 1 |
-| 3 | P3-1, P3-2, P3-3 | 3 | all independent |
-| 4a | P4a-1 → P4a-2, P4a-3 → P4a-5; P4a-4 independent | 5 | 2 (core + player/gate) |
-| 4b | P4b-1 → P4b-2 | 2 | 1 |
-| Cross-cutting | X-1 | 1 | independent |
-| **Total** | | **18** | |
-
----
-
-## References
-
-- [requestVideoFrameCallback — MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestVideoFrameCallback)
-- [Perform efficient per-video-frame operations — web.dev](https://web.dev/articles/requestvideoframecallback-rvfc)
-- [Shadow DOM vs. iframes — HackerNoon](https://hackernoon.com/shadow-dom-vs-iframes-which-one-actually-works)
-- [adoptedStyleSheets — MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets)
-- [Page Visibility API — MDN](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)
-- [ShadowRoot.elementsFromPoint — MDN](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/elementsFromPoint)
diff --git a/notes/teaser-learnings.md b/notes/teaser-learnings.md
deleted file mode 100644
index d7b0f6016..000000000
--- a/notes/teaser-learnings.md
+++ /dev/null
@@ -1,857 +0,0 @@
-# Teaser → HyperFrames Learnings
-
-Patterns extracted from `~/Desktop/teaser.html` (the standalone build of the
-"Claude Design Teaser") that are worth porting, codifying, or just naming
-inside HyperFrames. The teaser is a single-file React+Babel app with a
-hand-rolled animation engine; we are not adopting its architecture, but it
-contains real ideas that would improve HF.
-
-22 patterns total, grouped by area, then ranked by effort/impact at the end.
-
----
-
-## Framing: LLMs are the primary authors
-
-HyperFrames compositions are written by LLM agents, not humans. A human
-might inspect the output in Studio and request changes, but the markup is
-LLM-generated. This changes which benefits matter.
-
-What's different about LLM authors vs human authors:
-
-1. **Lint and `validate` are the only feedback channel.** LLMs can't watch
-   a render and notice stutter. They can't tab to Studio, scrub, and feel
-   that the timing is off. Their entire awareness of correctness comes
-   from `hf lint` output, `hf validate` headless errors, and whether the
-   composition runs at all. Anything not caught by these is shipped broken.
-2. **Every regeneration costs tokens, latency, and money.** First-try
-   correctness is the only metric that matters at scale. APIs that are
-   harder to misuse beat APIs that are easier to read.
-3. **LLMs are bad at arithmetic.** Asking an LLM to "make sure all inner
-   tweens sum to less than `data-duration`" is asking for hallucinated
-   timings. Anything that lets the framework compute timings instead of
-   the LLM is a major reliability win.
-4. **LLMs only know patterns that are in skills.** A pattern that isn't
-   documented in `~/.claude/skills/hyperframes*` won't be used reliably,
-   even if the framework supports it. Skills are the system prompt;
-   patterns outside skills are invisible.
-5. **Constrained surfaces beat expressive ones.** 6 brand colors as
-   tokens beat 16M hex codes — the LLM can't hallucinate a wrong hex if
-   there's no hex to hallucinate. Same with eases, durations, etc.
-6. **Error messages are read by LLMs, not humans.** They need to be
-   specific and actionable enough that the LLM can fix the bug from the
-   message alone, without scrolling source.
-7. **Studio is for human reviewers.** Studio UX wins (sidebar relevance,
-   widgets, click-to-select) help the human reviewing the LLM's output,
-   but they don't make the LLM author better.
-
-The benefit sections below are reframed accordingly: each one estimates
-**effect on first-try LLM correctness** and **whether it needs a skill**
-to land.
-
----
-
-## 1. Time & Duration
-
-### 1.1 Derived scene durations (`computeDur`)
-
-Each scene exposes a static function that computes its duration from raw
-tweak values, so editing one number resizes the scene and pushes everything
-downstream — no manual bookkeeping.
-
-```javascript
-scene1Intro.computeDur = function (T) {
-  const typeDur = T.s1_typeDur ?? 1.6;
-  const holdDur = T.s1_holdDur ?? 1.2;
-  const tail    = T.s1_tail    ?? 0.7;
-  return typeDur + holdDur + tail;
-};
-```
-
-**HF analogue:** clip durations should optionally be a function of attributes
-on the clip, not a constant `data-duration`.
-
-**Real-world benefit (LLM-authored):** Today, an LLM writing a clip has to
-do this:
-1. Decide the typing animation runs 1.6s
-2. Decide the hold runs 1.2s
-3. Decide the tail runs 0.7s
-4. **Manually sum to 3.5s and write `data-duration="3.5"`**
-5. Hope nothing in the inner tweens silently exceeds that
-
-LLMs are bad at step 4 — they hallucinate sums (off by 0.1–0.5s often),
-or pad pessimistically with `data-duration="6"` (creating dead frames),
-or under-pad and clip the animation. **A typical multi-clip composition
-has ≥1 timing arithmetic error per generation.** Each error means a
-human notices the dead frame or the cut-off, sends it back, LLM
-regenerates.
-
-With `computeDur`: the LLM declares the inner timings and the framework
-sums them. **Removes an entire class of LLM arithmetic errors.** The
-generation succeeds on first try at a much higher rate.
-
-Ripple effect: re-generating one clip with new timing no longer requires
-the LLM to also rewrite all downstream clip start times — the framework
-shifts them. That means a human request like "make scene 2 longer" turns
-into a single-clip edit, not a full-composition rewrite.
-
-**Skill needed:** yes — `hyperframes/compose-video` skill needs to teach
-the LLM "do not compute durations; declare timings and let the framework
-sum."
-
----
-
-### 1.2 Probe pass / render pass separation
-
-Before render, a cheap arithmetic-only pass walks every scene's `computeDur`
-and lays out scene start times.
-
-```javascript
-const T = ctx.__rawStore || {};
-const durs = SCENE_FNS.map(fn => fn.computeDur ? fn.computeDur(T) : 5);
-const starts = [0];
-for (let i = 0; i < 7; i++) starts.push(starts[i] + durs[i]);
-const totalDur = starts[7];
-```
-
-**HF analogue:** add a probe phase to the parser that resolves dynamic
-durations before any rendering decisions are made.
-
-**Real-world benefit (LLM-authored):** Required infrastructure to make
-1.1 work. Without it, the renderer can't know total duration up front,
-which breaks `hf validate`'s ability to report "this composition is 47s
-long, expected ≤30s" — exactly the kind of structured error message an
-LLM uses to course-correct.
-
-**Skill needed:** no — invisible plumbing.
-
----
-
-### 1.3 Explicit scene-time contract
-
-Every scene function takes the same args:
-
-```javascript
-function scene1Intro(ctx, t, t0, sceneDur) { ... }
-```
-
-Local time is always `t - t0`, progress is always `(t - t0) / sceneDur`.
-Consistent across all 7 scenes.
-
-**HF analogue:** a small `hf.sceneTime(el)` helper returning `{ t, lt, dur, p }`.
-
-**Real-world benefit (LLM-authored):** Every clip currently begins with
-`const t = window.__hfTime; const clipStart = ...; const lt = t - clipStart;`
-or some variation. LLMs get this slightly wrong constantly:
-- Forget to clamp `lt` to `[0, dur]` → animation runs negative
-- Use `Date.now()` instead of `window.__hfTime` → non-deterministic render
-- Divide by wrong duration → progress drifts
-- Compute `clipStart` by hand from the parent `<scene>` instead of reading it
-
-Each of these is a silent bug at preview time and a broken render at
-output time. With `hf.sceneTime(el)` returning `{ lt, dur, p }`, the LLM
-writes one line, can't get it wrong. **Removes the second-most-common
-class of LLM clip-script errors** (after timing arithmetic).
-
-**Skill needed:** yes — every code example in the compose skill should
-use `hf.sceneTime(el)` instead of hand-rolled time math, so it becomes
-the default pattern.
-
----
-
-### 1.4 Self-referencing `at` metadata
-
-A tweak's "where it lives on the timeline" can be a function of its own value:
-
-```
- at: v => sceneStart + v
-```
-
-So a "click delay" tweak's editor position follows the value as you drag it.
-
-**HF analogue:** if Studio adds richer property panels, this is the right model.
-
-**Real-world benefit (LLM-authored):** Effectively zero in the LLM-author
-context. This is a Studio editor feature for humans dragging values around.
-Park indefinitely.
-
----
-
-## 2. Animation Primitives
-
-### 2.1 Easings as pure functions
-
-```javascript
-const twEase = {
-  smooth: t => { t = Math.max(0, Math.min(1, t)); return t * t * t * (t * (t * 6 - 15) + 10); },
-  back:   t => { /* overshoot */ },
-  // ...
-};
-```
-
-`twEase.smooth(p)` returns 0..1, callable from anywhere — not bound to a
-GSAP `gsap.to({ ease: "..." })` call.
-
-**HF analogue:** ship `hf.ease.{smooth, in, out, back, linear}`.
-
-**Real-world benefit (LLM-authored):** When an LLM needs an eased value
-outside a GSAP tween (canvas drawing, audio-reactive math, SVG morph,
-manual `clip-path` math) it currently does one of:
-1. **Hand-rolls easing math.** ~70% of the time it gets the curve wrong
-   (writes `t * t * (3 - 2*t)` thinking it's smootherstep, etc.) → render
-   looks subtly off, human reviewer can't articulate why.
-2. **Pulls in another easing lib.** Adds a dependency, inconsistency with
-   the rest of the composition.
-3. **Sets up a paused dummy GSAP tween just to read `progress`.** Works
-   but is grotesque — no LLM does this without prompting.
-
-With `hf.ease.smooth(p)`: one function call, can't be wrong, matches the
-curve used elsewhere in the composition. **Eliminates the "hand-rolled
-easing math" failure mode entirely.**
-
-**Skill needed:** yes — list canonical ease names in the compose skill so
-the LLM uses `hf.ease.smooth` instead of hallucinating a Penner formula.
-
----
-
-### 2.2 `seq` and `hold` declarative keyframes
-
-```javascript
-function seq(now, stops) {
-  if (now <= stops[0][0]) return stops[0][1];
-  for (let i = 0; i < stops.length - 1; i++) {
-    const [t0, v0, e0] = stops[i];
-    const [t1, v1] = stops[i + 1];
-    if (now >= t0 && now < t1) {
-      const raw = (now - t0) / (t1 - t0);
-      return twLerp(v0, v1, (twEase[e0 || "smooth"] || twEase.smooth)(raw));
-    }
-  }
-  return stops[stops.length - 1][1];
-}
-```
-
-**HF analogue:** `hf.seq(t, [...])`.
-
-**Real-world benefit (LLM-authored):** Compare what the LLM has to
-generate today vs with `seq`/`hold`.
-
-**Today** ("fade in, hold, change to red, fade out" on one element):
-
-```javascript
-const tl = gsap.timeline({ paused: true });
-tl.set(el, { opacity: 0, color: "white" });
-tl.to(el,  { opacity: 1, duration: 0.5 });
-tl.to(el,  { color: "red", duration: 0 }, 2.5);
-tl.to(el,  { opacity: 0, duration: 0.5 }, 3.0);
-window.__timelines.set("el-7", tl);
-tl.seek(window.__hfTime - clipStart);
-```
-
-7 lines, requires:
-- correct delay arithmetic (LLM gets `2.5` wrong if any earlier tween changes)
-- correct registration on `window.__timelines` (LLM forgets the registration on ~20% of generations)
-- correct `seek` math (`window.__hfTime - clipStart`, easy to mess up)
-
-**With `seq`/`hold`:**
-
-```javascript
-el.style.opacity = seq(t, [[0, 0], [0.5, 1], [3, 1], [3.5, 0]]);
-el.style.color   = hold(t, [[0, "white"], [2.5, "red"]]);
-```
-
-2 lines, no timeline registration, no seek math, no delay arithmetic
-(the keyframe times are absolute, not relative). **Eliminates three
-common LLM error sources at once.** First-try correctness for "fade in
-hold change fade out" patterns probably goes from ~70% to ~95%.
-
-**Skill needed:** yes — feature `seq` prominently in the compose skill,
-demote raw GSAP timelines for simple keyframe sequences.
-
----
-
-### 2.3 `envS` show/hide envelope
-
-```javascript
-function envS(now, t0, t1, t2 = Infinity, t3 = Infinity) {
-  // fade-in t0→t1, hold, fade-out t2→t3
-}
-```
-
-**HF analogue:** `hf.env(t, in, holdEnd, fadeStart, fadeEnd)`.
-
-**Real-world benefit (LLM-authored):** "Fade in, hold, fade out" appears
-in essentially every composition — every caption, lower-third, callout,
-overlay. Today the LLM generates a paused GSAP timeline with three
-tweens for each one (see 2.2 for the exact 5–7 lines).
-
-A 60s caption-heavy composition has 20+ envelopes per minute. **At 5–7
-lines each, that's 100–140 lines just for opacity envelopes.** Every
-line is a chance for the LLM to mis-register, mis-seek, or mis-time.
-
-With `envS`:
-
-```javascript
-el.style.opacity = envS(t, 1.0, 1.4, 3.4, 3.8);
-```
-
-20 envelopes × 1 line = 20 lines, each one impossible to mis-register.
-**~80% reduction in code volume for the most common animation pattern,
-correlated drop in error rate.** Also: shorter generated code = more
-context budget for the *next* clip in the same conversation.
-
-**Skill needed:** yes — make `envS` the canonical opacity-envelope
-pattern in skills.
-
----
-
-## 3. Tweak System
-
-### 3.1 Tweak with metadata
-
-Every animated value is registered with rich metadata (`label`, `at`
-lifespan, `el` ownership, `step`/`min` widget hints).
-
-**HF analogue:** `data-*` attributes already do most of this for clips.
-
-**Real-world benefit (LLM-authored):** No action — HF's data-attribute
-model already captures this. Documented for context.
-
----
-
-### 3.2 Manifest as render byproduct
-
-The teaser rebuilds the editor manifest fresh on every render.
-
-**HF analogue:** HF extracts metadata at parse time, which is correct for
-headless rendering.
-
-**Real-world benefit (LLM-authored):** Confirms HF's current architecture.
-No action.
-
----
-
-### 3.3 Typed tweak helpers
-
-```javascript
-ctx.num   ("s1_size",    54,           { ... });
-ctx.point ("s2_ing_pos", [300, 230],   { ... });
-ctx.color ("s3_accent",  "#FF6B35",    { ... });
-```
-
-The editor renders the right widget (slider, XY pad, color picker).
-
-**HF analogue:** add `data-tweak-type="number|point|color|select"` so Studio
-can pick widgets instead of inferring.
-
-**Real-world benefit (LLM-authored):** Largely a Studio (human-reviewer)
-feature — the LLM doesn't care if Studio renders a color picker vs a text
-field. **One LLM-relevant angle though:** if `data-tweak-type="color"`
-constrains values to a palette declared on the parent `<theme>`, it
-prevents the LLM from generating a brand-conflicting hex. Same for
-`data-tweak-type="duration"` clamping to project-wide max. So this is
-mostly a Studio win, with a smaller "constrain LLM choices" win on top.
-
-Lower priority than the items targeting LLM correctness directly.
-
-**Skill needed:** marginal.
-
----
-
-### 3.4 Globally unique tween IDs
-
-`s1_typeDur`, `s2_ing_pos`, `s3_accent` — scene-prefixed names.
-
-**HF analogue:** if HF ever adds a flat tweak namespace (export to JSON
-config), use this convention.
-
-**Real-world benefit (LLM-authored):** Niche. Park.
-
----
-
-### 3.5 Quadratic relevance falloff in Studio
-
-Editor only shows tweaks "near" the playhead, with quadratic fade.
-
-**HF analogue:** Studio sidebar polish.
-
-**Real-world benefit (LLM-authored):** Pure human-reviewer UX. Helps the
-person reviewing the LLM's output find the knob to tweak. Nice but does
-not affect LLM correctness. Lower priority.
-
----
-
-## 4. Element & Layer Model
-
-### 4.1 One identifier, three roles (`el`)
-
-A single string serves three purposes (tweak ownership, timing metadata,
-DOM selection target).
-
-**HF analogue:** `data-el` (or just element ID) linking clip attributes ↔
-DOM ↔ Studio inspector.
-
-**Real-world benefit (LLM-authored):** Studio-side benefit (select-to-edit,
-hover-to-highlight) is for human reviewers. **LLM-side benefit:** if `data-el`
-becomes the canonical "name this element" attribute, the LLM has one place
-to attach metadata instead of inventing IDs/classes/data-name ad hoc. Reduces
-naming hallucination. Skill could mandate "every animated element gets a
-unique `data-el`."
-
-Modest win. Mostly a Studio polish item.
-
-**Skill needed:** yes if adopted — single naming convention.
-
----
-
-### 4.2 Per-element culling, post-registration
-
-Tweaks register before culling — manifest stays stable across timeline.
-
-**HF analogue:** when HF adds dynamic clips, ensure metadata extraction is
-independent of "is this clip currently visible".
-
-**Real-world benefit (LLM-authored):** Future-proofing. No code today, just
-a principle. Worth naming so a future LLM-generated conditional-clip
-pattern doesn't break inspectability.
-
----
-
-## 5. Visual Polish
-
-### 5.1 Two-layer crossfade
-
-Background color/scene transitions stack two divs with opacity.
-
-**HF analogue:** ship as a registry block.
-
-**Real-world benefit (LLM-authored):** Every registry block is one fewer
-thing the LLM has to author from scratch. A blessed `bg-crossfade` block
-that the LLM can `hyperframes add` and reference means:
-- LLM doesn't have to invent the two-layer pattern itself
-- LLM doesn't accidentally use `transition: background 0.5s` (scrub-unsafe)
-- LLM doesn't write a one-layer GSAP `to({ background })` that flickers
-  on color interpolation
-
-**Every registry block raises the floor on LLM-authored quality.**
-`bg-crossfade` is one of the highest-leverage blocks because background
-transitions are universal in multi-scene videos and the wrong way to do
-them is the most natural way for an LLM (CSS transitions).
-
-**Skill needed:** the registry skill should list this block as the
-canonical answer to "I need a background transition."
-
----
-
-### 5.2 Per-scene "tone" tracks
-
-Scalar values defined per-scene that interpolate during crossfades
-(texture/grain/vignette/color-grade/audio level).
-
-**HF analogue:** a "scene tracks" concept — global per-scene scalars that
-interpolate on transitions.
-
-**Real-world benefit (LLM-authored):** Today, when an LLM tries to add
-"grain stronger in the dark scene, lighter in the closing scene" it has
-to: write per-scene CSS variables, animate them on scene boundaries with
-GSAP, register the timelines, get the crossfade timing to match the
-scene's actual transition. Roughly 30 lines of correct, fragile code per
-"tone" axis.
-
-With scene tracks: declare `data-grain="0.3"` per scene, framework
-interpolates. **One attribute per scene replaces 30 lines of GSAP.**
-
-LLMs almost never produce cinematic-look compositions today because the
-mechanics are too error-prone — they default to flat scenes. Scene
-tracks change the default: with the right skill, the LLM adds grain,
-vignette, audio ducking by reflex because it's one attribute.
-
-**Raises baseline production quality of LLM-generated videos.**
-
-**Skill needed:** yes — give the LLM a list of conventional tone tracks
-it can set per scene.
-
----
-
-### 5.3 `RevealText` progress-normalized stagger
-
-Word-by-word reveal that always finishes at p=1, regardless of word count.
-
-```javascript
-const gap = n > 1 ? (1 - stagger) / (n - 1) : 0;
-```
-
-**HF analogue:** any text-stagger block in the registry should follow this
-math.
-
-**Real-world benefit (LLM-authored):** When the LLM regenerates a clip
-because the human reviewer asked for different copy, the timing must
-remain correct. Today: LLM writes a 4-word reveal with stagger such that
-total = 1.5s. Human says "make it say [longer thing]". LLM regenerates
-the text but doesn't recompute stagger → text overflows the clip.
-
-This is **the most common failure mode of LLM-driven copy iteration on
-text-heavy compositions.** With normalized stagger, the LLM doesn't have
-to do the math: total time is constant by construction. Copy edits stop
-breaking timing.
-
-Note: this isn't "save marketers time on iteration" anymore — it's "the
-LLM doesn't ship broken timing when re-prompted with different copy."
-
-**Skill needed:** yes — `RevealText` and similar text-stagger blocks
-should be the canonical answer in skills, with a note that stagger is
-normalized.
-
----
-
-### 5.4 `TypeText` caret discipline
-
-Caret stays solid while typing, blinks after typing completes.
-
-**HF analogue:** any typewriter component in the registry should do this.
-
-**Real-world benefit (LLM-authored):** Free quality bump in the registry
-component. The LLM doesn't have to know about caret behavior — it just
-uses `<type-text>` and gets the right behavior. This is what blocks are
-for: encoding designer-grade details so the LLM doesn't have to.
-
-**Skill needed:** no — registry block handles it transparently.
-
----
-
-## 6. Embedding & Lifecycle
-
-### 6.1 `postMessage({type: "finished"})` host contract
-
-```javascript
-if (next >= duration) {
-  if (!doneRef.current) {
-    doneRef.current = true;
-    try { window.parent.postMessage({ type: "finished" }, "*"); } catch {}
-  }
-}
-```
-
-**HF analogue:** documented `postMessage` protocol for `<hyperframes-player>`
-(`{type: "ready" | "frame" | "finished" | "error"}`).
-
-**Real-world benefit (LLM-authored):** Distribution unlock. Once the
-protocol exists, an LLM can generate not just the composition but also
-the integration code for embedding it in a docs page, marketing email,
-or app — including the host-side "swap to CTA on finish" logic. Without
-the protocol, the LLM has to invent an ad-hoc signal (timer, polling)
-that's almost always wrong.
-
-Concrete pattern an LLM can emit reliably:
-
-```html
-<iframe src="https://hf.example.com/embed/abc"></iframe>
-<script>
-  window.addEventListener("message", e => {
-    if (e.data?.type === "finished") showCta();
-  });
-</script>
-```
-
-**Without the protocol, the LLM produces broken embed code at high rate.**
-With it, the LLM has a single canonical pattern to emit. Distribution
-becomes a one-shot LLM task.
-
-**Skill needed:** yes — add to compose-video skill or a new "embed"
-skill.
-
----
-
-### 6.2 Two builds from one source
-
-Standalone player vs editor build, same scenes, different chrome.
-
-**HF analogue:** HF already has this split (`engine`, `studio`, `player`).
-
-**Real-world benefit (LLM-authored):** Audit task. The LLM-relevant angle:
-if `core` accidentally imports Studio code, the player bundle bloats and
-embed performance suffers — which makes the postMessage embed unlock
-(6.1) less attractive. Worth an audit before 6.1 ships.
-
-**Skill needed:** no.
-
----
-
-### 6.3 dt clamp on tab-hidden
-
-```javascript
-const dt = Math.min((now - lastRef.current) / 1000, 0.1);
-```
-
-**HF analogue:** Studio preview should clamp dt.
-
-**Real-world benefit (LLM-authored):** Pure human-reviewer UX. Helps the
-person previewing the LLM's output not lose their place when alt-tabbing.
-Cheap to do, but the benefit is for the human, not the LLM. Lower
-priority than items that affect LLM correctness.
-
----
-
-## 7. Discipline / Invariants
-
-### 7.1 No CSS transitions — scrub-safe
-
-Stated in the file header as a core invariant.
-
-**HF analogue:**
-- Document loudly in `hyperframes/SKILL.md` and `core/AGENTS.md`.
-- Add a `hyperframes lint` rule that flags `transition` / `animation` CSS
-  inside `.clip` elements.
-
-**Real-world benefit (LLM-authored):** **The single most important item
-in this entire document.**
-
-LLMs will write `transition: opacity 0.3s ease` constantly, because:
-- It's the most common pattern in their training data
-- It's the answer to most "how do I animate X in CSS" Stack Overflow posts
-- It looks correct in any browser preview the LLM might be evaluating
-  against
-- It's shorter than the GSAP equivalent
-
-The LLM has **no way to know this is wrong** unless lint catches it.
-Studio preview will look fine. The LLM cannot watch the rendered video
-and notice stutter — that's a human reviewer's job. Without lint, this
-bug ships, every time, on every composition.
-
-The cycle without lint:
-1. LLM generates composition with `transition: opacity 0.3s`
-2. LLM runs `hf lint` — passes
-3. LLM runs `hf validate` — passes (no JS errors, transition is valid CSS)
-4. Human renders → output is broken
-5. Human writes back "the fade looks stuttery"
-6. LLM has no way to localize the bug from that description, churns
-
-The cycle with lint:
-1. LLM generates composition with `transition: opacity 0.3s`
-2. `hf lint` errors: `Found CSS transition on .clip element. Transitions
-   are scrub-unsafe and produce stuttery renders. Use GSAP timelines or
-   hf.envS instead.`
-3. LLM reads the error, rewrites with `envS`, lint passes
-4. Render works first time
-
-**This single lint rule is the difference between LLM-authored HF being
-production-ready and being unreliable.** Probably the highest-leverage
-change in the whole codebase.
-
-**Skill needed:** lint rule + skill mention. Skill should explicitly say
-"never use CSS transition or animation properties on clips — use GSAP
-timelines or hf.envS."
-
----
-
-### 7.2 Deterministic pseudo-randomness
-
-`Math.random()` in animation logic = different "random" values every render
-= snow/jitter that wasn't in preview.
-
-**HF analogue:** already an invariant; add lint enforcement.
-
-**Real-world benefit (LLM-authored):** Same class as 7.1 — invisible to
-the LLM, breaks the render. LLM writes `Math.random() * 100` for
-particle X position because it's the natural way to express "random
-position." Lint catches it pre-render.
-
-Without this lint rule, the LLM ships particle/shimmer effects that
-flicker chaotically in the rendered output and look fine in preview.
-LLM cannot diagnose this from a human bug report ("particles look
-weird") because it has no way to inspect frame-by-frame.
-
-**Skill needed:** lint rule + skill mention. Skill should provide a
-seeded-random helper as the blessed alternative.
-
----
-
-### 7.3 Constrained design system
-
-Six color tokens, one serif font, one sans, one mono.
-
-**HF analogue:** registry blocks should consume CSS variables (`var(--hf-color-bg)`),
-not hardcoded hex.
-
-**Real-world benefit (LLM-authored):** **Hallucination reduction by
-constraint.** When the palette is 6 named tokens, the LLM can't pick
-`#FF6B35` when the brand color is `#FF7B30` — the option literally
-doesn't exist in the namespace. Same for fonts, eases, durations
-(if duration tokens exist).
-
-This is the framework version of "give the LLM a multiple choice
-question instead of a fill-in-the-blank." LLMs are dramatically more
-accurate on constrained-choice problems.
-
-Concrete:
-- Today, generating "5 social media videos in the brand palette" results
-  in 3-4 of them having one or two off-brand hex codes (LLM
-  approximated by eye).
-- With tokens: LLM emits `var(--brand-primary)`. Either the token
-  exists and is correct, or lint errors. **Brand consistency goes from
-  ~70% to 100%.**
-
-For an org producing dozens of customer-templated videos per quarter,
-this is the difference between "manually QA every video for brand
-compliance" and "trust the framework."
-
-**Skill needed:** yes — list the available tokens in the project's
-context so the LLM uses `var(--…)` references. Lint rule to forbid
-hex codes in `.clip` elements would close the loop.
-
----
-
-### 7.4 Doc comments explain WHY, not WHAT
-
-Cultural pattern in `teaser.html` — comments justify design choices,
-constraints, tradeoffs.
-
-**HF analogue:** add to `AGENTS.md`.
-
-**Real-world benefit (LLM-authored):** When future LLMs (and humans)
-modify HF source, "why" comments prevent the "this looks redundant, let
-me remove it" refactor that breaks production. Concrete: 6.3's dt clamp
-is a one-liner that looks deletable — without the comment explaining
-tab-switch behavior, the next LLM cleaning up the file removes it.
-**LLMs are aggressive simplifiers without context.** "Why" comments
-are the only defense.
-
-**Skill needed:** add to internal contributor docs (`AGENTS.md`).
-
----
-
-## 8. Anti-patterns observed (do not adopt)
-
-- **Shipping the toolchain in the page.** Babel standalone, React DOM dev,
-  duplicated transformed code all live inline. Fine for a one-off marketing
-  artifact, wrong for any framework. HF's compile-time approach is correct.
-- **Single 17000-line HTML file.** Authoring works for one person; doesn't
-  scale. HF's package boundary is correct. Note: also makes the file
-  unreadable to LLMs (exceeds typical context budgets).
-- **Inline `blob:` URLs for fonts.** Die the moment the file leaves the
-  original origin. Use proper font files.
-
----
-
-## Prioritization (LLM-author lens)
-
-Re-ranked: items that improve **LLM first-try correctness** or **LLM
-distribution-code generation** rise. Pure Studio UX items fall.
-
-| # | What | Effort | LLM first-try gain | Notes |
-|---|------|--------|--------------------|-------|
-| **7.1** | Lint `transition`/`animation` inside `.clip` | ~1 day | **Massive** — closes the #1 invisible-to-LLM bug class. | LLM cannot diagnose this without lint. Highest leverage in the doc. |
-| **7.2** | Lint `Math.random`/`Date.now` in clips | ~30 min | **Massive** — same bug class as 7.1. | Pair with 7.1 in same PR. |
-| **2.1–2.3** | `hf.utils` (`ease`, `seq`, `hold`, `envS`, `lerp`) | ~1 day | **Large** — replaces the 5–7-line GSAP boilerplate where LLMs make 3+ classes of error. | Code volume drops ~80% on opacity envelopes. |
-| **1.1 + 1.2** | `computeDur` + probe pass | ~1 week | **Large** — removes the LLM's timing-arithmetic burden entirely. | Bigger architectural change but eliminates the most common LLM error class. |
-| **7.3** | Tokenize registry blocks (CSS variables) + lint hex in clips | ~3 days* | **Large for branded work** — turns brand consistency into a framework guarantee. | *~1 hour per existing block to retrofit. |
-| **5.3** | Audit registry text components for progress-normalized stagger | ~2 hours | **Medium** — kills "copy regen breaks timing" failure mode. | Cheap, do alongside other registry work. |
-| **5.1** | Background crossfade as registry block | ~4 hours | **Medium** — every block raises the floor on LLM output. | Pair with skill update so LLM uses it by default. |
-| **6.1** | `postMessage` embed protocol | ~1–2 days | **Medium for distribution** — LLM can emit working embed code. | Distribution unlock; complements composition authoring. |
-| **5.2** | Per-scene tone tracks (grain/vignette/audio) | ~1 week | **Medium** — raises baseline production quality of LLM output. | LLMs will use this if the skill teaches them to. |
-| **1.3** | `hf.sceneTime(el)` helper | ~1 hour | **Medium** — kills second-most-common clip-script error class. | Trivial to ship. |
-| **5.4** | Typewriter caret discipline in registry | ~30 min | **Small** — handled by registry block transparently. | LLM gets the win for free. |
-| **4.1** | `data-el` unifying inspector ↔ stage ↔ attrs | ~2 days | **Small for LLM, large for human reviewers** — naming convention helps slightly. | Mostly a Studio UX upgrade. |
-| **6.2** | Audit `core`/`engine`/`studio`/`player` boundary | ~1 day | **Small** — supports 6.1 by keeping player bundle small. | Run before 6.1 ships. |
-| **3.3** | `data-tweak-type` widget hints | ~3 days | **Small for LLM, large for Studio** | Mostly a human-reviewer feature. |
-| **6.3** | `dt` clamp on tab-hidden in Studio | ~10 min | **Zero** — pure human-reviewer benefit. | Still cheap and worth doing. |
-| **3.5** | Quadratic relevance falloff in Studio | ~2 hours | **Zero** — human-reviewer UX. | Defer until human-reviewer flow is the bottleneck. |
-| **7.4** | Doc comment philosophy in `AGENTS.md` | ~30 min | **Indirect** — protects LLM-authored code from over-aggressive future LLM refactors. | Cultural; cheap. |
-| **4.2** | Per-element culling discipline | — | **Indirect** — future-proofing for LLM-authored conditional clips. | Principle, no code today. |
-| **3.1, 3.2** | Already in HF | — | — | No action. |
-| **3.4, 1.4** | Niche; only matters if Studio expands | — | — | Park. |
-
-The pattern: **lint rules and `hf.utils` are the highest-leverage items
-because they directly affect what the LLM can ship without human
-intervention.** Studio polish items still matter, but only after the
-LLM-authoring path is reliable.
-
----
-
-## Suggested first PRs
-
-**Optimize for the LLM authoring loop**, not the human review loop.
-Order:
-
-### PR 1: Lint rules for `transition`/`animation` and `Math.random`/`Date.now` in clips (#7.1, #7.2)
-
-Extend `packages/cli/src/commands/lint.ts` with two regex/AST-based rules.
-~50 LOC each. Critical: **error messages must be specific enough that an
-LLM can fix from the message alone**, e.g.:
-
-```
-error: hf/no-css-transitions
-  notes/example.html:42:5
-  CSS `transition: opacity 0.3s ease` found on a `.clip` element.
-
-  Renders capture frames at independent timestamps; CSS transitions are
-  not scrub-safe and produce stuttery output that looks correct in
-  Studio preview.
-
-  Fix: use a paused GSAP timeline registered on `window.__timelines`,
-  or `hf.envS(t, fadeIn, holdEnd, fadeOut, end)` for opacity envelopes.
-```
-
-**Pitch:** "These two lint rules are the difference between LLM-authored
-HF being shippable and being unreliable. They catch the bug classes the
-LLM literally cannot see. Half a day of work, pays back the first time
-they fire."
-
-### PR 2: `hf.utils` module (#2.1–2.3, #1.3)
-
-`packages/core/src/utils/{ease,seq,env,lerp,sceneTime}.ts`. ~100 LOC,
-zero risk. Bundle includes:
-
-- `hf.ease.{linear, smooth, in, out, back}`
-- `hf.lerp(a, b, t)`
-- `hf.seq(t, [[t0, v0, ease?], [t1, v1, ease?], ...])`
-- `hf.hold(t, [[t0, v0], [t1, v1], ...])`
-- `hf.envS(t, fadeIn, holdEnd, fadeOut, end)`
-- `hf.sceneTime(el) → { t, lt, dur, p }`
-
-**Pitch:** "Replaces 5–7-line GSAP timeline boilerplate with single
-expressions for the patterns that appear in every composition. LLM
-generates fewer lines, makes fewer of the three common mistakes
-(timing-registration, seek math, delay arithmetic). First-try
-correctness goes up, token spend goes down."
-
-### PR 3: Skills update — make the new utils + lint rules canonical
-
-The skills currently teach LLMs to use raw GSAP timelines. After PRs 1
-and 2 ship, the `hyperframes/compose-video` and `hyperframes-cli`
-skills should:
-
-- Demote raw GSAP timeline patterns for opacity envelopes
-- Teach `hf.envS` / `hf.seq` / `hf.hold` as the canonical answers
-- Document the new lint errors and how to satisfy them
-- Mandate `hf.sceneTime(el)` over hand-rolled time math
-- Provide explicit "do not use" examples for `transition`, `animation`,
-  `Math.random`, `Date.now` inside clips
-
-**Pitch:** "PRs 1 and 2 are useless without this. Skills are the
-LLM's system prompt — patterns outside skills don't get used reliably."
-
-### PR 4: `computeDur` convention (#1.1, #1.2)
-
-Bigger architectural change. Deserves its own design doc before code.
-Touches the parser, the runtime, Studio's scrubber, and the render
-pipeline.
-
-**Pitch:** "Removes the LLM's burden of summing inner timings. Eliminates
-a major arithmetic-error class that currently requires human review to
-catch. High-impact but bigger change — design separately."
-
-### PR 5: Tokenize registry blocks + lint hex in clips (#7.3)
-
-Constrained palette beats freeform hex. Retrofit existing blocks to
-consume CSS variables, add a lint rule against literal hex/rgb in clip
-elements, document the project's token namespace in skills.
-
-**Pitch:** "Brand consistency stops being a 'manually QA every video'
-problem and becomes a framework guarantee. Especially valuable for
-HeyGen's customer-templated work."
-
----
-
-PRs 1–3 are tightly coupled and should ship together as the
-"LLM-authoring reliability" patch. PR 4 is high-leverage but bigger;
-plan separately. PR 5 is independent and can ship anytime.
diff --git a/plans/hdr-followups.md b/plans/hdr-followups.md
deleted file mode 100644
index 1b1f33cac..000000000
--- a/plans/hdr-followups.md
+++ /dev/null
@@ -1,396 +0,0 @@
-# HDR Follow-ups — Work Plan
-
-Source: [Hyperframes HDR follow-ups](https://www.notion.so/347449792c6980ae8ac6f93b9ddd4610)
-
-Organized into chunks that can be branched, tested, and merged independently.
-Items are prioritized: critical bugs first, then correctness, then hardening, then cleanup.
-
----
-
-## Chunk 0: Comprehensive HDR Regression Test
-
-**Why first:** The existing HDR tests (`hdr-pq` and `hdr-image-only`) are trivial — a single full-bleed video or image with a static text label. They don't exercise any of the features that the HDR pipeline must explicitly handle differently from SDR: opacity animation, z-ordered multi-layer compositing, transforms, border-radius clipping, shader transitions, multiple HDR sources, object-fit modes, or mixed HDR+SDR layering. Every subsequent chunk in this plan needs a regression test that can prove the fix works *and* that nothing else broke. This chunk builds that test.
-
-### What the current tests cover
-
-| Test | Elements | Animations | Layers | Transitions |
-|------|----------|-----------|--------|-------------|
-| `hdr-pq` | 1 HDR video + 1 static label | None | 1 HDR + 1 DOM | None |
-| `hdr-image-only` | 1 HDR PNG + 1 static label | None | 1 HDR + 1 DOM | None |
-
-### What the HDR pipeline must support (complete feature inventory)
-
-Found by auditing `renderOrchestrator.ts`, `videoFrameInjector.ts`, `layerCompositor.ts`, `alphaBlit.ts`, `shaderTransitions.ts`, `streamingEncoder.ts`, `hdrCapture.ts`, and `hyper-shader.ts`:
-
-| # | Feature | HDR-specific behavior | Current coverage |
-|---|---------|----------------------|-----------------|
-| 1 | **Wrapper-opacity animation** | `getEffectiveOpacity()` walks ancestors, multiplies opacity chain. HDR path must read this and apply during compositing (Chrome can't do it — video is extracted separately). | None |
-| 2 | **Direct-on-element opacity animation** | GSAP tween on `<video>` itself. HDR path skips element's own opacity because engine forces `opacity: 0 !important` to hide it. Known bug (Chunk 1A). | None |
-| 3 | **Z-ordered multi-layer compositing** | `groupIntoLayers()` interleaves DOM and HDR layers by z-index. DOM layers get masked screenshots; HDR layers get native-pixel compositing. Adjacent DOM layers merge. | Trivial (1 HDR behind 1 DOM) |
-| 4 | **DOM behind HDR behind DOM** ("sandwich") | Requires at least 3 layers: DOM(z:1) → HDR(z:5) → DOM(z:10). Tests that masking correctly shows/hides elements per layer. | None |
-| 5 | **Multiple HDR video sources** | Fixed in PR #289 (was single-HDR-only in #288). No regression pins the fix. Two HDR videos composited in same frame. | None |
-| 6 | **Mixed HDR video + HDR image** | Both `isHdr` in the stacking query. Different extraction paths (FFmpeg frames vs PNG decode). Same compositing path. | None (separate tests) |
-| 7 | **CSS transforms (rotate, scale, translate)** | `el.transform` computed by `queryElementStacking()` / `getViewportMatrix()`. Must be applied via `blitRgb48leAffine()`. Currently dead — compositing only uses scale+translate (Chunk 4A). | None |
-| 8 | **GSAP `force3D: true` (matrix3d)** | GSAP's default. `parseTransformMatrix()` only handles `matrix()`, returns null for `matrix3d()` (Chunk 4B). | None |
-| 9 | **Border-radius clipping** | `el.borderRadius` computed from nearest `overflow:hidden` ancestor. Must be applied as pixel mask during HDR compositing. Currently dead (Chunk 4A). | None |
-| 10 | **Shader transitions (15 effects)** | Operate on rgb48le buffers in PQ/HLG signal space. `hdrToLinear` → shader → `linearToHdr`. Cross-scene compositing uses both scene A and scene B HDR captures. | None (unit tests only) |
-| 11 | **`object-fit` modes** | `resampleRgb48leObjectFit()` handles cover/contain/fill/none/scale-down. `ElementStackingInfo.objectFit` + `objectPosition` passed through. | None (`cover` only, implicitly) |
-| 12 | **sRGB-to-BT.2020 conversion** | DOM screenshots are sRGB. HDR compositor converts via `srgbToHdr16()` matrix before blitting over HDR content. Incorrect conversion = color shift on text/graphics. | Implicit only (label color not validated) |
-| 13 | **PQ transfer function** | SMPTE ST 2084. 65536-entry LUT. PQ OETF/EOTF constants (M1, M2, C1, C2, C3). | Implicit (hdr-pq test) |
-| 14 | **HLG transfer function** | ARIB STD-B67. Separate LUT. HLG OETF coefficients. Entirely different code path from PQ. | **None — zero coverage** |
-| 15 | **Cross-transfer conversion (HLG↔PQ)** | `convertTransfer()` for mixed-source compositions. HLG OOTF with Lw=1000, gamma=1.2. | **None** |
-| 16 | **HDR10 mastering metadata** | `mdcv` box (G,B,R primary order per ISO 23001-8), `stco`/`co64` offset shifting, `max-cll`/`max-fall`. | Implicit (metadata not validated by harness) |
-| 17 | **Captions over HDR content** | DOM text at high z-index over HDR layers. sRGB caption → BT.2020 conversion must preserve legibility. | Trivial (static label only) |
-| 18 | **Audio sync with HDR** | Both current tests set `minAudioCorrelation: 0` — audio sync is **not enforced**. HDR path could drop/reorder audio silently. | **Not enforced** |
-| 19 | **`layoutWidth`/`layoutHeight` for extraction** | Untransformed dims for FFmpeg extraction sizing. Currently unused — extraction uses `el.width`/`el.height` from getBoundingClientRect (Chunk 4C). | None |
-| 20 | **Scene initial-state** | Non-first scenes should start at `opacity: 0`. If not, all scenes composite simultaneously at t=0 (Chunk 4D). | None |
-
-### Design: time-sequenced test card
-
-The regression harness samples 100 PSNR checkpoints evenly across the video. By giving each feature its own **time window**, a regression at a specific checkpoint immediately identifies which feature broke — no per-zone PSNR support needed.
-
-Two compositions required: PQ and HLG use entirely separate code paths (different LUTs, different OETF/EOTF, different FFmpeg tagging). They cannot share a single composition. The fixture layout is identical; only the source assets and transfer function differ.
-
-**Composition: `hdr-regression` (PQ variant, ~20s, 1920x1080)**
-
-| Window | Time | Feature exercised | Elements |
-|--------|------|-------------------|----------|
-| A | 0.0–2.0s | Static baseline — HDR video + DOM overlay | Full-bleed HDR video, white text label at z:10. Sanity check: if this fails, everything else is meaningless. |
-| B | 2.0–4.5s | Wrapper-opacity fade | HDR video inside a `<div>` wrapper. GSAP tweens wrapper from `opacity: 1` → `0.15` → `1`. Tests `getEffectiveOpacity()` ancestor walk. |
-| C | 4.5–7.0s | Direct-on-element opacity | GSAP tweens `opacity` directly on `<video>` element. Same tween as (B). **Expected to fail until Chunk 1A lands** — proves the bug exists. |
-| D | 7.0–9.5s | Z-order sandwich: DOM → HDR → DOM | Three layers: colored rect at z:1 (DOM), HDR video at z:5, semi-transparent overlay at z:10 (DOM). Tests `groupIntoLayers()` with interleaved types. |
-| E | 9.5–12.0s | Multiple HDR sources | Two HDR videos side-by-side (left half, right half) at different z-indices with a DOM label between them. Pins the PR #289 multi-video fix. |
-| F | 12.0–14.5s | Transform + border-radius | HDR video with `rotation: 15deg`, `scale: 0.8` via GSAP. Container has `border-radius: 24px; overflow: hidden`. **Expected to fail until Chunk 4 lands.** |
-| G | 14.5–17.0s | Object-fit: contain | HDR video in a container that doesn't match its aspect ratio. `object-fit: contain` should produce letterboxing, not stretching. |
-| H | 17.0–20.0s | Shader transition (crossfade) | Two-scene composition with `crossfade` transition at t=18.5s. Tests signal-space blending of HDR pixels. Scene A = HDR video, Scene B = HDR image. |
-
-**Composition: `hdr-hlg-regression` (HLG variant, ~5s, 1920x1080)**
-
-Shorter composition — HLG exercises the separate LUT/OETF code path, not a different compositing pipeline.
-
-| Window | Time | Feature exercised | Elements |
-|--------|------|-------------------|----------|
-| A | 0.0–2.5s | HLG video + DOM overlay | Full-bleed HLG video with text label. Validates HLG OETF, `arib-std-b67` encoder tagging. |
-| B | 2.5–5.0s | HLG opacity animation | Wrapper-opacity fade on HLG video. Validates HLG-specific LUT used during compositing. |
-
-### Assets needed
-
-| Asset | Format | Source | Notes |
-|-------|--------|--------|-------|
-| `hdr-bars-pq.mp4` | HEVC Main10, BT.2020 PQ | Synthesized via FFmpeg SMPTE bars / color ramp | Deterministic, OSS-safe. Replaces third-party `hdr-clip.mp4` (also addresses Chunk 11A). |
-| `hdr-bars-hlg.mp4` | HEVC Main10, BT.2020 HLG | Synthesized via FFmpeg | Same pattern, HLG transfer. |
-| `hdr-photo-pq.png` | 16-bit RGB, BT.2020 PQ, cICP tagged | Synthesized via FFmpeg + ImageMagick | Gradient with known reference values for color accuracy checks. Can reuse or replace existing `hdr-photo.png`. |
-
-Synthesized assets solve fixture provenance (Chunk 11A) simultaneously.
-
-### Known-failing windows
-
-Some windows will fail against their golden snapshot until the corresponding chunk lands. This is intentional — the test documents the bug.
-
-| Window | Fails because | Fixed by |
-|--------|--------------|----------|
-| C (direct opacity) | HDR path ignores direct-on-element opacity | Chunk 1 |
-| F (transforms) | Transform/border-radius data not wired into compositing | Chunk 4 |
-
-Use `maxFrameFailures` to accommodate these known failures. As chunks land, regenerate the golden and tighten the threshold. Alternatively, we can use GSAP-conditional guards to make known-broken windows produce a deterministic fallback (e.g. skip the animation) until the fix lands — this keeps `maxFrameFailures: 0` but weakens the "proves the bug" property.
-
-### Replaces
-
-- `hdr-pq` — functionality covered by window A
-- `hdr-image-only` — functionality covered by window H (scene B uses an HDR image) plus can add a dedicated image-only window if needed
-
-Both old tests are removed. CI shard updated to run `hdr-regression hdr-hlg-regression` instead.
-
-### Gaps NOT covered by this regression test (out of scope)
-
-These need separate unit/integration tests (addressed in Chunk 9):
-
-- `hdrEncoder` error/cleanup path (unit test, Chunk 5A)
-- `frameDirMaxIndexCache` cross-job isolation (unit test, Chunk 5B)
-- Abort mid-transition (integration test, Chunk 5C)
-- `ffprobe` unavailable fallback (unit test, Chunk 9B)
-- `chunkEncoder` HDR metadata (separate encoder path, Chunk 3)
-- Cross-transfer conversion HLG↔PQ in a single composition (would need a mixed-source fixture — consider as a follow-up)
-- HDR10 mastering metadata validation (ffprobe post-render check, can be added to the harness)
-- Audio sync enforcement (requires setting `minAudioCorrelation` > 0 on a composition with audio)
-
-### Deliverables
-
-1. `packages/producer/tests/hdr-regression/` — composition, meta.json, synthesized assets, golden snapshot
-2. `packages/producer/tests/hdr-hlg-regression/` — HLG variant
-3. Remove `packages/producer/tests/hdr-pq/` and `packages/producer/tests/hdr-image-only/`
-4. Update CI workflow shard from `hdr-pq hdr-image-only` to `hdr-regression hdr-hlg-regression`
-5. FFmpeg asset synthesis scripts (checked into `scripts/` or documented in README)
-
----
-
-## Chunk 1: Opacity Pipeline Bugs
-
-**Why first:** Two live correctness bugs produce wrong pixels. The HDR direct-on-video opacity bug is the most user-visible issue in the entire list.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | HDR compositor ignores direct-on-video opacity animation | `videoFrameInjector.ts:437-439` | Standalone bug report |
-| B | `queryVideoElementBounds` opacity fallback: `parseFloat("0") \|\| 1` treats opacity:0 as opacity:1 | `videoFrameInjector.ts:~202` | PR #288 I4 (unfixed residual) |
-| C | `as HTMLElement` cast — use `instanceof` guard instead | `videoFrameInjector.ts:309` | PR #290 I1 |
-| D | Opacity walk starts from parent — fragile ordering coupling with `hideVideoElements` | `videoFrameInjector.ts:426-428` | PR #290 M1 |
-
-**Approach for (A):** The doc suggests three fix options. Option 3 (use `visibility: hidden` instead of `opacity: 0 !important`) is cleanest — needs verification that native `<video>` won't leak through. Option 1 (read opacity before engine forces it to 0) is the safe fallback.
-
-**How to verify:**
-- Render a composition with GSAP animating `opacity` directly on a `<video>` element (no wrapper)
-- Compare SDR and HDR output at a mid-tween frame (e.g. t=3.5s, expected opacity ~0.15)
-- Both paths should produce visibly dim video — not full brightness
-- Regression: existing compositions with wrapper-based opacity animation must still work
-
----
-
-## Chunk 2: Transition Duration Defaults
-
-**Why:** Causes a visible ~0.3s brightness dropout on any transition without explicit `duration`. Preview and render also produce different blending curves due to ease mismatch.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | Duration default mismatch: `1.0` in meta write, `0.7` in browser/engine mode | `hyper-shader.ts:130, 238, 361` | PR #268 C1 |
-| B | Ease mismatch: `"none"` in meta vs `"power2.inOut"` in browser | Same file | PR #268 C1 |
-
-**Fix:** Extract `DEFAULT_DURATION = 0.7` and `DEFAULT_EASE = "power2.inOut"` as shared constants. Use in all three sites.
-
-**How to verify:**
-- Render a composition with a transition that omits `duration` and `ease`
-- No brightness dip in the last ~0.3s of the transition
-- Preview (browser mode) and render (engine mode) produce matching blending curves
-- Render with explicit `duration: 1.5` still works (not overridden by default)
-
----
-
-## Chunk 3: chunkEncoder HDR — Live Bug
-
-**Why:** Disk-based HDR encodes silently produce BT.709-tagged output. The streaming encoder is correct but chunkEncoder never reads `options.hdr`.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | `buildEncoderArgs` hard-codes BT.709 color params, ignores `options.hdr` | `chunkEncoder.ts` | PR #265 I1 |
-| B | `convertSdrToHdr` docstring says "zscale with 600 nit peak" but code uses FFmpeg colorspace filter; output hard-coded to HLG | `videoFrameExtractor.ts` | PR #265 I3 |
-| C | HDR config type: `{ transfer: ... } | false` but IIFE returns `undefined` | `config.ts` | PR #265 I4 |
-
-**How to verify:**
-- Render an HDR composition using the chunk encoder path
-- `ffprobe` the output: should show `bt2020nc` color matrix, `smpte2084` transfer, mastering display metadata
-- Compare against streaming encoder output — metadata should match
-
----
-
-## Chunk 4: Transform & Clipping Pipeline
-
-**Why:** Transform extraction and border-radius computation exist but are dead — an HDR video with `rotation: 45` renders un-rotated, `border-radius: 50%` renders with sharp corners.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | Wire `el.transform`, `el.borderRadius`, `el.layoutWidth`/`layoutHeight` into compositing loop | `renderOrchestrator.ts` | PR #290 C1 |
-| B | `parseTransformMatrix` returns null for `matrix3d` (GSAP `force3D: true` default) | `alphaBlit.ts:634-643`, `videoFrameInjector.ts:370-407` | PR #290 I2 |
-| C | HDR extraction dims use `el.width`/`el.height` (transform-affected) instead of `el.layoutWidth`/`layoutHeight` | `renderOrchestrator.ts:~996-1008` | PR #290 M3 |
-| D | Scene initial-state: all non-first scenes should start at `opacity: 0` | `hyper-shader.ts:355-369` | PR #290 I3 |
-
-**How to verify:**
-- Render a composition with a rotated HDR video (`rotation: 45`) — should appear rotated
-- Render a composition with `border-radius: 50%` on an HDR video container — should clip to circle
-- Render a 3-scene composition — no overlapping at t=0
-- `blitRgb48leAffine` should receive the full affine matrix, not just scale+translate
-
----
-
-## Chunk 5: Resource Management & Resilience
-
-**Why:** Leaked processes, unbounded memory growth, and missing abort checks. Each is independently fixable and testable.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | `hdrEncoder.close()` not called on non-abort errors (orphaned FFmpeg) | `renderOrchestrator.ts` | PR #268 I1 |
-| B | Module-scoped `frameDirMaxIndexCache` grows monotonically, never cleared | `renderOrchestrator.ts:~128` | PR #268 I2 |
-| C | No abort signal between scene A and scene B compositing | `renderOrchestrator.ts:~1500` | PR #290 I4 |
-| D | Per-frame `Buffer.alloc(width * height * 6)` — ~37 MB at 1080p, ~11 GB GC pressure for 10s/30fps | `renderOrchestrator.ts:~1082` | PR #290 M2 |
-| E | File server lacks `isPathInside()` guard — relative path segments can escape project dir | `fileServer.ts` | PR #288 M1 (unfixed across stack) |
-
-**How to verify:**
-- (A) Kill a render mid-flight with a non-abort error; confirm no orphaned `ffmpeg` processes
-- (B) Run two render jobs back-to-back; confirm cache is cleared between jobs
-- (C) Abort during a transition frame; confirm it stops promptly (not after scene B capture completes)
-- (D) Memory profiling: heap snapshots during a 10s render should show flat buffer allocation
-- (E) Attempt `GET /../../../etc/passwd` against the local file server; should 403/404
-
----
-
-## Chunk 6: Non-null Assertions & Type Safety
-
-**Why:** Violates project policy. Straightforward mechanical fixes — good chunk for a single PR.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | ~12 `!` assertions on M709_TO_2020 matrix rows | `alphaBlit.ts` | PR hdr-image-support C2 |
-| B | `stack.pop()!` | `mp4HdrBoxes.ts:504` | PR hdr-image-support C2 |
-| C | `layers[layerIdx]!` | `renderOrchestrator.ts` | PR #268 C2 |
-| D | Duplicate `HfTransitionMeta` interface (rebase artifact) | `types.ts` (lines 42 and 68) | PR #268 I1 |
-| E | Locally-redeclared `HfTransitionMeta` in browser shim (add sync comment) | `hyper-shader.ts:116-123` | PR #268 I2 |
-| F | Dead code: `buildSrgbToHdrLut` / `getSrgbToHdrLut` if no external callers | `alphaBlit.ts` | PR hdr-image-support I4 |
-
-**How to verify:**
-- `grep -r '!\.' packages/engine/src packages/producer/src` — no new non-null assertions
-- TypeScript compiles clean
-- Existing tests pass unchanged
-
----
-
-## Chunk 7: Refactoring — Compositing Helpers
-
-**Why:** Reduces complexity and duplication in the render orchestrator. Do after correctness fixes so the refactored code is already correct.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | Extract HDR compositing closure into top-level `compositeHdrFrame` helper | `renderOrchestrator.ts` | Deferred #1 |
-| B | Factor `skipReadinessVideoIds` capture-option spread into `buildHdrCaptureOptions()` | Multiple files | Deferred #9 |
-| C | Rename `extractVideoMetadata()` to `extractMediaMetadata()` (handles PNG too) | Engine utils | Deferred #8 |
-| D | Hoist `countNonZeroAlpha`/`countNonZeroRgb48` debug helpers to module scope | `renderOrchestrator.ts` | PR #268 M1 |
-
-**How to verify:**
-- All existing tests pass without modification (pure refactor)
-- No behavioral changes — diff should be structural only
-- New `compositeHdrFrame` helper has explicit typed context object
-
----
-
-## Chunk 8: Performance
-
-**Why:** Potential perf regression from the layered HDR path. Measure first, then optimize.
-
-| # | Item | File(s) | Source | Status |
-|---|------|---------|--------|--------|
-| A | Benchmark HDR-PQ wall-clock + peak heap/RSS, `--tags` filter, `bench:hdr` script | `benchmark.ts`, `renderOrchestrator.ts`, `tests/perf/README.md` | Deferred #2 | **Done** (PR `vance/hdr-benchmark-harness`) |
-| B | Cache per-image transfer-converted HDR buffers per `(imageId, targetTransfer)` | Engine HDR path | Deferred #3 | **Done** (PR `vance/hdr-image-transfer-cache`) |
-| C | Debug logging does JSON serialization every 30 frames regardless of log level | `renderOrchestrator.ts`, `logger.ts` | PR #289 M4 | **Done** (PR `vance/logger-level-gating`) |
-| D | Diagnostic `countNonZeroAlpha`/`countNonZeroRgb48` iterate all pixels every frame (gated by KEEP_TEMP but check evaluates always) | Engine hot path | PR hdr-image-support M2 | **Already gated** — calls live behind `shouldLog = debugDumpEnabled && debugFrameIndex >= 0`, where `debugDumpEnabled` is itself driven by `KEEP_TEMP=1`, so the pixel iteration is fully skipped on production runs. No code change required; verified during 8C work. |
-
-**Ordering:** Do (A) first to establish a baseline. Then (B)-(D) as optimizations. Re-measure after.
-
-**8C resolution:** Added optional `isLevelEnabled(level)` to `ProducerLogger` and a `createConsoleLogger` implementation. The hot-loop call site in `renderOrchestrator.ts` (per-frame HDR composite snapshot every 30 frames) is now gated by `i % 30 === 0 && (log.isLevelEnabled?.("debug") ?? true)`, so the meta-object construction (`Array.find`, `toFixed`, conditional struct) is fully skipped at `level=info`. The `?? true` fallback preserves prior behavior for custom logger implementations that don't define the method. Covered by `packages/producer/src/logger.test.ts` (17 tests including a hot-loop call-site simulation that asserts zero builder invocations at info level).
-
-**8B resolution:** Added `packages/producer/src/services/hdrImageTransferCache.ts` — a per-render-job bounded LRU keyed by `(imageId, targetTransfer)` that owns the converted HDR rgb48 buffer for static HDR image layers. Same-transfer requests return the source buffer untouched; cross-transfer requests pay one `Buffer.from` + `convertTransfer` on first miss and reuse the cached copy on every subsequent frame instead of re-converting per composite. Wired into `renderOrchestrator.ts` via `HdrCompositeContext.hdrImageTransferCache`, instantiated once per render job and consumed by `blitHdrImageLayer` for both the main composite path and the transition path. Covered by `packages/producer/src/services/hdrImageTransferCache.test.ts` (12 tests: hit/miss, distinct keys per image and per target transfer, LRU eviction + promotion, `maxEntries=0` passthrough, source-buffer immutability for cached entries, invalid options).
-
-**How to verify:**
-- Wall-clock timing on `hdr-pq` fixture: before vs after, at least 3 runs each
-- Image cache hit rate logged (should be 100% for static images after first frame)
-- No JSON.stringify calls in hot path unless log level is debug
-
----
-
-## Chunk 9: Test Coverage
-
-**Why:** Gaps identified across multiple PR reviews. Can be done in parallel with other chunks.
-
-| # | Item | File(s) | Source | Status |
-|---|------|---------|--------|--------|
-| A | ~~Restore mixed SDR/HDR and HDR+captions regression fixtures/tests~~ | ~~Test fixtures~~ | ~~Deferred #5~~ | **Absorbed by Chunk 0** (windows D, E, H) |
-| B | Add explicit ffprobe-unavailable fallback test (mock missing ffprobe) | Unit test | Deferred #10 | Open |
-| C | ~~CI-wired integration test for the full HDR composite pipeline~~ | ~~Integration test~~ | ~~PR hdr-image-support test gaps~~ | **Absorbed by Chunk 0** |
-| D | Test `hdrEncoder` error/cleanup path | Unit test | PR hdr-image-support test gaps | Open |
-| E | Test `frameDirMaxIndexCache` cross-job isolation | Unit test | PR hdr-image-support test gaps | Open |
-| F | alphaBlit: add known sRGB-to-BT.2020 reference values for matrix path | `alphaBlit.test.ts` | PR hdr-image-support test gaps | Open |
-| G | Shader smoke tests at p=0.5 (midpoint regressions) | `shaderTransitions.test.ts` | PR #268 M2 | Open |
-
-**How to verify:**
-- `bun run test` — all new tests pass
-- Coverage report shows the previously-uncovered branches are now hit
-
----
-
-## Chunk 10: CLI — Restore Removed Flags
-
-**Why:** Breaking change for existing users. Needs user-facing communication.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | Restore `--crf` and `--video-bitrate` CLI flags alongside `--hdr` (or add deprecation) | `packages/cli/src/commands/render.ts` | PR #268 I3, PR hdr-image-support I3 |
-
-**How to verify:**
-- `hyperframes render --crf 18 ...` works (or prints deprecation warning)
-- `hyperframes render --hdr ...` still works
-- `hyperframes render --help` shows all flags
-
----
-
-## Chunk 11: OSS & CI Hygiene
-
-**Why:** Fixture provenance, CI stability, repo bloat prevention. Independent of code correctness.
-
-| # | Item | File(s) | Source | Status |
-|---|------|---------|--------|--------|
-| A | ~~Replace third-party `hdr-pq` fixture with synthesized HDR source (FFmpeg test patterns)~~ | ~~Test fixtures~~ | ~~Deferred #4~~ | **Absorbed by Chunk 0** (synthesized assets) |
-| B | ~~Relax HDR fixture `maxFrameFailures` from 0 to 2~~ | ~~Test config~~ | ~~Deferred #7~~ | **Absorbed by Chunk 0** (accommodates known-failing windows) |
-| C | Add `tests/*/src/*.png` to LFS tracking in `.gitattributes` | `.gitattributes` | Deferred #11 | Open |
-
-**How to verify:**
-- (C) `git lfs ls-files` includes HDR PNG fixtures after commit
-
----
-
-## Chunk 12: Investigation — `__name` Polyfill
-
-**Why:** Investigation item — outcome determines whether there's a code change or just a polyfill removal.
-
-| # | Item | File(s) | Source |
-|---|------|---------|--------|
-| A | Investigate the bundler/runtime boundary causing the `__name` issue; remove polyfill if fixable | Runtime | Deferred #6 |
-
-**How to verify:**
-- If root cause found: polyfill removed, `bun run test` passes, `bun run build` clean
-- If root cause is upstream: document why polyfill is necessary, add a test that detects if the upstream fix lands
-
-**Status: Done — keeping polyfill, documented + regression-tested.**
-
-Empirical findings (probe in `/tmp/hf-name-probe`):
-
-| Runtime / build | Injects `__name(fn, "name")` wrappers in `Function.prototype.toString()`? |
-|-----------------|---------------------------------------------------------------------------|
-| `bun` (TS loader) | No — verified for top-level and nested named functions / arrow expressions. |
-| `tsx` (esbuild loader, `keepNames=true`) | Yes for nested named functions / arrows; observed crash mode in dev/test. |
-| `tsc` (`noEmit` and emit) | No — does not inject the helper. |
-| `tsup` for `@hyperframes/cli` (`noExternal: ["@hyperframes/engine"]`) | Polyfill *definition* is bundled, but `__name(...)` *call sites* are absent in `packages/cli/dist/cli.js` (grepped). |
-
-Root cause: `@hyperframes/engine`'s `package.json` exports raw TypeScript (`main`/`exports` → `./src/index.ts`), so every consumer's transpiler decides whether to inject `__name`. Anything that runs through `tsx` (producer parity-harness, ad-hoc dev scripts, `bun run --filter @hyperframes/engine test` via Vitest's loader) will serialize wrapped function bodies into `page.evaluate(...)` and crash with `ReferenceError: __name is not defined`.
-
-Decision: keep the no-op `window.__name` shim in `frameCapture.ts`. Cost is one `evaluateOnNewDocument` call; alternative (rewriting every `page.evaluate(fn)` site to `page.addScriptTag({ content: "..." })` like `packages/cli/src/commands/contrast-audit.browser.js`) is far more invasive and easy to regress.
-
-What landed:
-- Expanded the inline comment in `packages/engine/src/services/frameCapture.ts` to explain the per-runtime matrix above and point to the script-tag alternative.
-- Added `packages/engine/src/services/frameCapture-namePolyfill.test.ts` — a pure unit-test (matches the rest of the engine package's convention, no browser launch) that:
-  1. Asserts the polyfill is wired up via `evaluateOnNewDocument` and runs before the first awaited `browser.version()` call.
-  2. Probes the active Vitest transpiler for `__name(...)` injection so the next maintainer can see at a glance whether the upstream behavior has shifted.
-
-Verification:
-- `bun run --filter @hyperframes/engine test` → 408/408 pass (3 new tests in this file).
-- `bunx tsc --noEmit -p packages/engine` clean.
-- `bunx oxlint` and `bunx oxfmt --check` clean on edited files.
-
----
-
-## Suggested Merge Order
-
-```
-Chunk 0  (regression test)     — FIRST. Establishes the safety net. Known-failing windows accepted initially.
-Chunk 6  (type safety)         — mechanical, zero risk, unblocks nothing but cleans the diff
-Chunk 2  (transition defaults) — small, high-value correctness fix
-Chunk 1  (opacity pipeline)    — highest-impact bug; regenerate golden for window C after merge
-Chunk 3  (chunkEncoder HDR)    — live bug, independent code path
-Chunk 5  (resource management) — independent fixes, each small
-Chunk 10 (CLI flags)           — user-facing, small
-Chunk 7  (refactoring)         — after correctness fixes land
-Chunk 4  (transform pipeline)  — largest chunk, depends on Chunk 1; regenerate golden for window F after merge
-Chunk 11 (OSS/CI hygiene)      — anytime (11A already addressed by Chunk 0's synthesized assets)
-Chunk 9  (test coverage)       — anytime, pairs well with any chunk (9A partially addressed by Chunk 0)
-Chunk 8  (performance)         — after refactoring lands (cleaner code to benchmark)
-Chunk 12 (investigation)       — anytime, independent
-```
-
-Chunk 0 lands first to establish the regression safety net. Windows C and F will fail until Chunks 1 and 4 land — set `maxFrameFailures` accordingly and tighten as fixes merge.
-
-Chunks 6, 9, 11, and 12 can run in parallel with anything. Chunks 1 and 4 share `videoFrameInjector.ts` so should be sequenced. Chunk 7 (refactoring) should land after Chunks 1-3 so you're refactoring correct code.