From e7f9918d21f9fa57f1799c7b3ba38963cfcb52f1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Fri, 24 Jul 2026 23:12:48 +0200
Subject: [PATCH] fix(lint): drop false media_in_subcomposition rule (#2765)

The media_in_subcomposition rule blanket-errored every <video>/<audio>
inside a sub-composition, claiming nested media is "never seeked/decoded
and renders blank/black". This is false: the runtime discovers media with
a flat document.querySelectorAll("video, audio"), resolves each element's
host composition via closest("[data-composition-id]"), and rebases its
local data-start by the accumulated absolute start of every ancestor
composition (packages/core/src/runtime/{media,startResolver}.ts). Media
seeks and decodes at any nesting depth, verified end to end through the
producer render path.

- Remove the rule and flip its test to assert nested media is NOT flagged.
- Drop the now-dead media_in_subcomposition clause from the registry
  components test.
- Drop the equivalent pre-render guard from the faceless-explainer and
  pr-to-video assemble scripts.
- Correct the reference docs (hyperframes-core SKILL, data-attributes,
  variables-and-media, composition-patterns; hyperframes-cli
  lint-validate-inspect): media works at any depth. Preserve the one real
  constraint, that a sub-comp timeline cannot reach host-root elements, so
  host-root media motion is authored on the main timeline.
---
 .../src/registry/registryComponents.test.ts   |  4 +--
 packages/lint/src/rules/media.test.ts         | 13 ++++----
 packages/lint/src/rules/media.ts              | 23 --------------
 skills-manifest.json                          |  8 ++---
 .../scripts/assemble-index.mjs                | 30 ++++++++-----------
 .../references/lint-validate-inspect.md       |  8 +----
 skills/hyperframes-core/SKILL.md              |  2 +-
 .../references/composition-patterns.md        |  8 ++---
 .../references/data-attributes.md             |  2 +-
 .../references/variables-and-media.md         | 10 ++-----
 skills/pr-to-video/scripts/assemble-index.mjs | 30 ++++++++-----------
 11 files changed, 49 insertions(+), 89 deletions(-)

diff --git a/packages/cli/src/registry/registryComponents.test.ts b/packages/cli/src/registry/registryComponents.test.ts
index 2716e7401..37537c759 100644
--- a/packages/cli/src/registry/registryComponents.test.ts
+++ b/packages/cli/src/registry/registryComponents.test.ts
@@ -26,9 +26,7 @@ async function invalidInstallableMedia(entryName: string): Promise<string[]> {
       isSubComposition: true,
     });
     for (const finding of result.findings) {
-      if (finding.code !== "media_in_subcomposition" && finding.code !== "media_missing_src") {
-        continue;
-      }
+      if (finding.code !== "media_missing_src") continue;
       invalidMedia.push(`${entryName}/${file.path}: ${finding.code}`);
     }
   }
diff --git a/packages/lint/src/rules/media.test.ts b/packages/lint/src/rules/media.test.ts
index 49ad5768d..b9ae81d3a 100644
--- a/packages/lint/src/rules/media.test.ts
+++ b/packages/lint/src/rules/media.test.ts
@@ -348,7 +348,13 @@ describe("media rules", () => {
     expect(finding).toBeUndefined();
   });
 
-  it("flags <video> inside a sub-composition (media must be a host-root child)", async () => {
+  it("does not flag <video> inside a sub-composition (runtime drives nested media)", async () => {
+    // The runtime's global media sweep (querySelectorAll("video, audio")) drives
+    // media at any nesting depth, and startResolver re-bases each nested clip's
+    // local data-start by its host composition's absolute start. Sub-composition
+    // media is therefore seeked + decoded correctly in preview and render — see
+    // packages/core/src/runtime/{media,startResolver,init}.ts. A prior
+    // `media_in_subcomposition` rule wrongly hard-errored this and was removed.
     const html = `<template id="scene-template">
   <div id="root" data-composition-id="scene" data-width="1920" data-height="1080">
     <video id="v1" src="clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
@@ -357,10 +363,7 @@ describe("media rules", () => {
 </template>`;
     const result = await lintHyperframeHtml(html, { isSubComposition: true });
     const finding = result.findings.find((f) => f.code === "media_in_subcomposition");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.elementId).toBe("v1");
-    expect(finding?.message).toContain("sub-composition");
+    expect(finding).toBeUndefined();
   });
 
   it("does not flag media in a host-root (non-sub) composition", async () => {
diff --git a/packages/lint/src/rules/media.ts b/packages/lint/src/rules/media.ts
index 3084d4ce7..08abde636 100644
--- a/packages/lint/src/rules/media.ts
+++ b/packages/lint/src/rules/media.ts
@@ -396,29 +396,6 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
     return findings;
   },
 
-  // media_in_subcomposition — <video>/<audio> only render as a DIRECT child of the host
-  // root (index.html). Inside a sub-composition <template> the runtime never seeks/decodes
-  // them, so they render BLANK/black in preview and renders — and the other lint/validate
-  // passes otherwise miss it (only a per-frame snapshot reveals the blank panel).
-  ({ tags, options }) => {
-    const findings: HyperframeLintFinding[] = [];
-    if (!options.isSubComposition) return findings;
-    for (const tag of tags) {
-      if (tag.name !== "video" && tag.name !== "audio") continue;
-      const elementId = readAttr(tag.raw, "id") || undefined;
-      findings.push({
-        code: "media_in_subcomposition",
-        severity: "error",
-        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> is inside a sub-composition. The runtime only drives media that is a DIRECT child of the host root (index.html); media inside a sub-comp <template> is never seeked/decoded and renders BLANK/black in preview and renders.`,
-        elementId,
-        fixHint:
-          "Move the media OUT of the sub-composition: place the <video>/<audio> as a direct child of #root in index.html, positioned over the scene, and drive any per-scene motion on the MAIN timeline at global time (a sub-comp timeline cannot reach host elements). See composition-patterns.md archetype B.",
-        snippet: truncateSnippet(tag.raw),
-      });
-    }
-    return findings;
-  },
-
   // self_closing_media_tag
   ({ source }) => {
     const findings: HyperframeLintFinding[] = [];
diff --git a/skills-manifest.json b/skills-manifest.json
index d65353ba6..3201569e6 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -6,7 +6,7 @@
       "files": 140
     },
     "faceless-explainer": {
-      "hash": "d53bcc3cbcfaa7bb",
+      "hash": "15fc5a20e2a44bbe",
       "files": 22
     },
     "figma": {
@@ -26,11 +26,11 @@
       "files": 121
     },
     "hyperframes-cli": {
-      "hash": "dc57ec7198b9eaac",
+      "hash": "de00375f053c05e8",
       "files": 11
     },
     "hyperframes-core": {
-      "hash": "85004c9571ed19ce",
+      "hash": "773fc6d15d9e87b3",
       "files": 19
     },
     "hyperframes-creative": {
@@ -58,7 +58,7 @@
       "files": 132
     },
     "pr-to-video": {
-      "hash": "17ed27aa2cc32501",
+      "hash": "0eb5abe09844cee4",
       "files": 29
     },
     "product-launch-video": {
diff --git a/skills/faceless-explainer/scripts/assemble-index.mjs b/skills/faceless-explainer/scripts/assemble-index.mjs
index b51ee0421..8a7554500 100644
--- a/skills/faceless-explainer/scripts/assemble-index.mjs
+++ b/skills/faceless-explainer/scripts/assemble-index.mjs
@@ -38,14 +38,14 @@
 // `lint` failures surface HERE instead of after assembly + a wasted render):
 //   ① AUTO-REPAIR — a sub-comp root missing data-width/data-height: inject the canvas
 //      dims (the renderer needs them on the cloned root; else lint root_missing_dimensions).
-//   ② HARD FAIL  — <video>/<audio> inside a sub-comp: the runtime only drives media that
-//      is a DIRECT child of the host root, so sub-comp media renders blank/black.
-//   ③ HARD FAIL  — a timed element (data-start+duration+track-index) that is not the root
+//   ② HARD FAIL  — a timed element (data-start+duration+track-index) that is not the root
 //      and lacks class="clip" (shows the whole frame), or two same-track clips that overlap.
+//   (Media inside a sub-comp is NOT a violation: the runtime seeks + decodes nested
+//    <video>/<audio> at any depth — see packages/core/src/runtime/{media,startResolver}.ts.)
 //
 // Exit 0 = index.html written + summary. Exit 1 = fatal contract break (no
 // frames, a built/animated frame missing its src/file, a frame with no
-// duration, an inner data-composition-id mismatch, or a guard ②/③ violation).
+// duration, an inner data-composition-id mismatch, or a guard ② violation).
 // No backstop: fix upstream.
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -121,7 +121,7 @@ const outPath = resolve(flag("out", join(hyperframesDir, "index.html")));
 
 const r3 = (x) => Math.round(x * 1000) / 1000;
 const anomalies = [];
-const frameErrors = []; // fatal per-frame composition violations (guards ②/③) — reported together
+const frameErrors = []; // fatal per-frame composition violations (guard ②) — reported together
 const repairs = []; // auto-repairs applied to frame files in place (guard ①)
 
 // ---------- parse storyboard ----------
@@ -129,7 +129,7 @@ if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPat
 const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
 const { width: WIDTH, height: HEIGHT } = parseFormat(manifest.globals.format);
 
-// ---------- per-frame composition guards (see header ①②③) ----------
+// ---------- per-frame composition guards (see header ①②) ----------
 // String-level checks on each frame's HTML — no DOM parse, deterministic, run in
 // the same pass that already reads the file. OPEN_TAG matches one opening tag while
 // tolerating quoted attribute values that contain ">" (e.g. inline styles).
@@ -166,21 +166,17 @@ function guardFrame(html, label) {
   const errors = [];
   // Scan a copy with comments + <script>/<style> bodies blanked, so a tag-like string
   // in a comment (e.g. "<!-- match the host <video> coords -->") or in GSAP code can't
-  // trip ②/③. ① still splices into the ORIGINAL html, so its offsets stay correct.
+  // trip ②. ① still splices into the ORIGINAL html, so its offsets stay correct.
   const scan = html
     .replace(/<!--[\s\S]*?-->/g, " ")
     .replace(/<script\b[\s\S]*?<\/script[^>]*>/gi, " ")
     .replace(/<style\b[\s\S]*?<\/style[^>]*>/gi, " ");
 
-  // ② media inside a sub-comp — never driven by the runtime (renders blank/black).
-  const media = scan.match(/<(video|audio)(?=[\s/>])/i);
-  if (media) {
-    errors.push(
-      `${label}: has a <${media[1].toLowerCase()}> inside the sub-composition. The runtime only drives media that is a DIRECT child of the host root (index.html) — sub-comp media renders blank/black. Move the clip to index.html as a root-level <video>/<audio> and drive any per-scene motion on the main timeline (composition-patterns.md archetype B).`,
-    );
-  }
-
-  // ③ timed-element checks: missing class="clip", and same-track window overlap.
+  // ② timed-element checks: missing class="clip", and same-track window overlap.
+  // (Media inside a sub-comp is fine: the runtime's global media sweep seeks + decodes
+  // <video>/<audio> at any nesting depth, re-basing each clip's local data-start by its
+  // host composition's absolute start — no root-child requirement. See
+  // packages/core/src/runtime/{media,startResolver}.ts.)
   const re = new RegExp(OPEN_TAG, "g");
   const clips = [];
   let m;
@@ -285,7 +281,7 @@ for (const f of manifest.frames) {
       `${label}: ${f.src} is empty or has no HTML — the worker wrote a blank/partial file. Re-dispatch that worker before assembling.`,
     );
   }
-  // pre-assembly guards: ① repair missing root dims in place, ②/③ collect fatal violations.
+  // pre-assembly guards: ① repair missing root dims in place, ② collects fatal violations.
   const guard = guardFrame(html, label);
   if (guard.repairedHtml) {
     writeFileSync(compAbs, guard.repairedHtml);
diff --git a/skills/hyperframes-cli/references/lint-validate-inspect.md b/skills/hyperframes-cli/references/lint-validate-inspect.md
index 78a6eee89..3d6b13f1e 100644
--- a/skills/hyperframes-cli/references/lint-validate-inspect.md
+++ b/skills/hyperframes-cli/references/lint-validate-inspect.md
@@ -23,13 +23,7 @@ npx hyperframes lint --json           # machine-readable
 
 Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`). Catches missing `data-composition-id`, overlapping tracks on the same `data-track-index`, unregistered timelines, and GSAP/CSS transform conflicts.
 
-**Blind spot — media inside a sub-composition (not yet a lint rule).** A `<video>`/`<audio>` inside a `compositions/*.html` `<template>` (or nested in a wrapper `<div>` anywhere) is never seeked/decoded and renders blank/black; the automated checks all pass. Media must be a direct child of the host root (`index.html`) — see `hyperframes-core` → `variables-and-media.md`. Until a rule exists, check manually before render:
-
-```bash
-grep -nE '<(video|audio)\b' compositions/*.html   # expect NO matches; media belongs in index.html
-```
-
-A non-empty result is a defect. Then `snapshot` each scene that has a video and confirm the panel actually shows footage (a blank/black panel where a clip should play is a bug, not a placeholder — treat it as render-blocking).
+`<video>`/`<audio>` work at any nesting depth, including inside a `compositions/*.html` sub-composition or a wrapper `<div>`: the runtime discovers media with a flat DOM query and seeks/decodes it wherever it lives (`packages/core/src/runtime/{media,startResolver}.ts`). After a render, `snapshot` each scene that has a video and confirm the panel actually shows footage (a blank/black panel where a clip should play is a real bug, not a placeholder).
 
 ## check
 
diff --git a/skills/hyperframes-core/SKILL.md b/skills/hyperframes-core/SKILL.md
index 74d21fb81..f3dc06d76 100644
--- a/skills/hyperframes-core/SKILL.md
+++ b/skills/hyperframes-core/SKILL.md
@@ -60,7 +60,7 @@ Surfaced here; full rationale in the linked reference. Do not violate:
 - No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count). → `determinism-rules.md`
 - Animate only the visual-property allowlist; never tween `display` or raw `visibility`. GSAP `autoAlpha` and zero-duration timeline boundary sets are the only visibility exceptions, and only on non-clip elements or wrappers inside a clip. The framework alone controls `.clip` visibility. Do not `gsap.set` later-scene clips at page load. → `determinism-rules.md`
 - No `<br>` in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → `determinism-rules.md`
-- `<video>`/`<audio>` must be a **direct child of the host root** (never inside a sub-comp `<template>`/wrapper); the framework owns playback. → `variables-and-media.md`
+- `<video>`/`<audio>` work at **any nesting depth** (including inside a sub-comp `<template>` or wrapper); the framework owns playback and seeks/decodes media wherever it lives. The one caveat is timelines, not placement: a sub-comp timeline can't animate host-root elements. → `variables-and-media.md`
 - Every `id` must be unique across the **assembled** page; inside a sub-comp, prefix ids with the composition id (`#<id>-hero`). Duplicate `<video>`/`<img>` ids render **blank** — the producer injects frames by `getElementById`, and cross-file dupes slip past `lint`. → `composition-patterns.md`
 - A full-screen scene fill goes on a full-bleed **child** (`position:absolute; inset:0`), never on the composition root itself — the producer's frame compositing can drop the root element's own `background` (the frame renders **black**) even though preview/`snapshot` show it correctly. → `composition-patterns.md`
 
diff --git a/skills/hyperframes-core/references/composition-patterns.md b/skills/hyperframes-core/references/composition-patterns.md
index 54f66bc4f..271407d1e 100644
--- a/skills/hyperframes-core/references/composition-patterns.md
+++ b/skills/hyperframes-core/references/composition-patterns.md
@@ -130,11 +130,11 @@ Key properties of this layout:
 
 The sub-comp contains the scene's full DOM, scoped CSS, and timeline. This is the standard pattern in `sub-compositions.md` — most scenes are this.
 
-### B. Host media + main-timeline driver (REQUIRED for any `<video>`/`<audio>`)
+### B. Host media + main-timeline driver (one pattern for `<video>`/`<audio>`)
 
-Media playback only works when the `<video>`/`<audio>` is a **direct child of the host root** — never inside a sub-comp `<template>` (it would render blank/black). This is not optional or "for media that spans scenes"; it applies to every clip, including a scene-specific one. The scene's sub-comp keeps the frame/shell; the media is a host sibling positioned over it.
+`<video>`/`<audio>` seek and decode at any nesting depth, so a scene-specific clip can live inside its scene's sub-comp with scene-local `data-start` and be driven by that sub-comp's own timeline. Use this host-media pattern instead when you want the media's motion authored on the **main** timeline: put the `<video>`/`<audio>` as a host-root sibling positioned over the scene's frame.
 
-A sub-comp timeline **cannot** drive host elements (a global selector or `document.querySelector` does not resolve across the boundary). So author the media's per-scene motion (scale/opacity/morph/tilt/breathing) on the **main timeline** in `index.html`, at **global time** = scene-local time + the scene slot's `data-start`.
+The reason to reach for it: a sub-comp timeline **cannot** drive host elements (a global selector or `document.querySelector` does not resolve across the boundary). So if the media lives at the host root, author its per-scene motion (scale/opacity/morph/tilt/breathing) on the **main timeline** in `index.html`, at **global time** = scene-local time + the scene slot's `data-start`.
 
 ```html
 <!-- index.html (host) -->
@@ -193,7 +193,7 @@ A sub-comp timeline **cannot** drive host elements (a global selector or `docume
 
 Caveats:
 
-- The host media must be a direct root child and exist in the DOM (static in `index.html`) — it always is.
+- In this pattern the media is a host-root child, static in `index.html`, so the main timeline's selector resolves it. (Media nested in a sub-comp is also driven fine; it just can't be reached by the main timeline's selectors — drive it from the sub-comp's own timeline.)
 - Clip lifecycle owns the media element's visibility across its `[data-start, data-start+data-duration]` window. The main-timeline opacity/scale tweens compose with it fine; for an opacity reveal/crossfade prefer a host **wrapper** so you are not fighting the lifecycle on the media element itself.
 - Two media elements sharing the same `src` + `data-start` trigger `duplicate_media_discovery_risk` (benign — both still render).
 
diff --git a/skills/hyperframes-core/references/data-attributes.md b/skills/hyperframes-core/references/data-attributes.md
index dfde93be3..fcaae3362 100644
--- a/skills/hyperframes-core/references/data-attributes.md
+++ b/skills/hyperframes-core/references/data-attributes.md
@@ -22,7 +22,7 @@ The root should be `position: relative`, have explicit pixel dimensions, and hid
 
 Timed child elements are clips. **`class="clip"` is required on visible timed elements** (`<div>`, `<img>`, etc.) — without it the runtime keeps the element visible for the whole composition, ignoring `data-start` / `data-duration`. Omit on `<video>` (framework manages visibility directly) and `<audio>` (no visual).
 
-**Clips must be DIRECT children of the composition root.** A clip nested inside a wrapper `<div>` is not registered — most visibly, a `<video>` in a wrapper is never seeked/decoded and renders black. To wrap/transform a clip, put the wrapper _inside_ the clip, or animate the clip element itself; do not wrap the clip. (`<video>`/`<audio>` additionally must be at the **host** root, never in a sub-comp `<template>` — see `variables-and-media.md`.)
+**Visual clips (`class="clip"`) must be DIRECT children of the composition root.** A clip nested inside a wrapper `<div>` is not registered as a clip, so its `data-start`/`data-duration` are ignored and it stays visible the whole composition. To wrap/transform a clip, put the wrapper _inside_ the clip, or animate the clip element itself; do not wrap the clip. (This is a clip-_visibility_ rule. `<video>`/`<audio>` are exempt: the framework drives their playback via a flat DOM query, so they seek/decode at any depth, including inside a sub-comp `<template>` — see `variables-and-media.md`.)
 
 | Attribute          | Required                                        | Meaning                                                                                                                           |
 | ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
diff --git a/skills/hyperframes-core/references/variables-and-media.md b/skills/hyperframes-core/references/variables-and-media.md
index 4a4319110..0d50268f6 100644
--- a/skills/hyperframes-core/references/variables-and-media.md
+++ b/skills/hyperframes-core/references/variables-and-media.md
@@ -62,12 +62,9 @@ document.getElementById("title").textContent = title;
 
 ## Media
 
-**NON-NEGOTIABLE: `<video>`/`<audio>` must be a DIRECT child of the host composition root (`index.html`).** The runtime only registers + drives media that is a direct root child. Media placed inside a sub-composition `<template>`, or wrapped in any intermediate `<div>`, is never seeked/decoded → renders blank (paper/white) or black. Do not rely on `lint` or `check` alone; a per-frame `snapshot` reveals the blank panel.
+**`<video>`/`<audio>` work at any nesting depth, including inside a sub-composition `<template>` or a wrapper `<div>`.** The runtime discovers media with a flat `document.querySelectorAll("video, audio")`, resolves each element's host composition via `element.closest("[data-composition-id]")`, and rebases its local `data-start` by the accumulated absolute start of every ancestor composition (`packages/core/src/runtime/{media,startResolver}.ts`). So a scene-specific clip can live in its scene's sub-comp with scene-local `data-start`, and it seeks/decodes correctly. If a panel renders blank after a render, that is a real bug: capture a per-frame `snapshot` and treat it as render-blocking.
 
-Consequences:
-
-- A scene-specific clip still lives at the host root, not in the scene's sub-comp. The sub-comp keeps only the frame/shell; the media is a sibling host element positioned over it.
-- A sub-composition **cannot reach or animate host elements** — neither `document.querySelector("#host-id")` nor a gsap selector string (`tl.to("#host-id", …)`) resolves across the boundary; a sub-comp timeline only drives its own subtree. So **all per-scene motion on host media (scale/opacity/morph/tilt/breathing) must be authored on the MAIN timeline in `index.html`, at GLOBAL time** (scene-local time + the scene slot's `data-start`). For 3D tilt without a perspective parent, use gsap `transformPerspective` on the element. See `composition-patterns.md` archetype B.
+The one real constraint is about **timelines, not media placement**: a sub-composition timeline **cannot reach or animate host elements** — neither `document.querySelector("#host-id")` nor a gsap selector string (`tl.to("#host-id", …)`) resolves across the boundary; a sub-comp timeline only drives its own subtree. So if a media element lives at the host root, **its per-scene motion (scale/opacity/morph/tilt/breathing) must be authored on the MAIN timeline in `index.html`, at GLOBAL time** (scene-local time + the scene slot's `data-start`). Keeping the media inside the scene sub-comp instead lets that sub-comp's own timeline animate it with scene-local time. For 3D tilt without a perspective parent, use gsap `transformPerspective` on the element. See `composition-patterns.md` archetype B.
 
 Video elements must be muted and inline. Audio must be a separate `<audio>` element, even when it uses the same source file.
 
@@ -96,8 +93,7 @@ Video elements must be muted and inline. Audio must be a separate `<audio>` elem
 ### Media Rules
 
 - **Do not** call `video.play()`, `audio.play()`, pause, or seek in composition code. HyperFrames owns playback.
-- **Do not** place media inside a sub-comp `<template>` or any wrapper `<div>` — direct host-root child only (see above), else it never decodes.
-- **Do not** drive host media from a sub-comp timeline — it has no effect. Drive it from the main timeline at global time.
+- **Do not** drive host-root media from a sub-comp timeline: a sub-comp timeline cannot reach elements outside its subtree, so it has no effect. Drive host-root media from the main timeline at global time (or keep the media inside the sub-comp whose timeline animates it).
 - **Do not** animate timed media element dimensions; animate a non-timed wrapper instead.
 - **Do not** nest video inside a timed wrapper. Put timing on the media element or keep the wrapper untimed.
 - Add `crossorigin="anonymous"` for external media that needs canvas capture or pixel inspection.
diff --git a/skills/pr-to-video/scripts/assemble-index.mjs b/skills/pr-to-video/scripts/assemble-index.mjs
index fe4f1e786..adb1318f2 100644
--- a/skills/pr-to-video/scripts/assemble-index.mjs
+++ b/skills/pr-to-video/scripts/assemble-index.mjs
@@ -38,14 +38,14 @@
 // `lint` failures surface HERE instead of after assembly + a wasted render):
 //   ① AUTO-REPAIR — a sub-comp root missing data-width/data-height: inject the canvas
 //      dims (the renderer needs them on the cloned root; else lint root_missing_dimensions).
-//   ② HARD FAIL  — <video>/<audio> inside a sub-comp: the runtime only drives media that
-//      is a DIRECT child of the host root, so sub-comp media renders blank/black.
-//   ③ HARD FAIL  — a timed element (data-start+duration+track-index) that is not the root
+//   ② HARD FAIL  — a timed element (data-start+duration+track-index) that is not the root
 //      and lacks class="clip" (shows the whole frame), or two same-track clips that overlap.
+//   (Media inside a sub-comp is NOT a violation: the runtime seeks + decodes nested
+//    <video>/<audio> at any depth — see packages/core/src/runtime/{media,startResolver}.ts.)
 //
 // Exit 0 = index.html written + summary. Exit 1 = fatal contract break (no
 // frames, a built/animated frame missing its src/file, a frame with no
-// duration, an inner data-composition-id mismatch, or a guard ②/③ violation).
+// duration, an inner data-composition-id mismatch, or a guard ② violation).
 // No backstop: fix upstream.
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -122,7 +122,7 @@ const outPath = resolve(flag("out", join(hyperframesDir, "index.html")));
 
 const r3 = (x) => Math.round(x * 1000) / 1000;
 const anomalies = [];
-const frameErrors = []; // fatal per-frame composition violations (guards ②/③) — reported together
+const frameErrors = []; // fatal per-frame composition violations (guard ②) — reported together
 const repairs = []; // auto-repairs applied to frame files in place (guard ①)
 
 // ---------- parse storyboard ----------
@@ -130,7 +130,7 @@ if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPat
 const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
 const { width: WIDTH, height: HEIGHT } = parseFormat(manifest.globals.format);
 
-// ---------- per-frame composition guards (see header ①②③) ----------
+// ---------- per-frame composition guards (see header ①②) ----------
 // String-level checks on each frame's HTML — no DOM parse, deterministic, run in
 // the same pass that already reads the file. OPEN_TAG matches one opening tag while
 // tolerating quoted attribute values that contain ">" (e.g. inline styles).
@@ -167,21 +167,17 @@ function guardFrame(html, label) {
   const errors = [];
   // Scan a copy with comments + <script>/<style> bodies blanked, so a tag-like string
   // in a comment (e.g. "<!-- match the host <video> coords -->") or in GSAP code can't
-  // trip ②/③. ① still splices into the ORIGINAL html, so its offsets stay correct.
+  // trip ②. ① still splices into the ORIGINAL html, so its offsets stay correct.
   const scan = html
     .replace(/<!--[\s\S]*?-->/g, " ")
     .replace(/<script\b[\s\S]*?<\/script[^>]*>/gi, " ")
     .replace(/<style\b[\s\S]*?<\/style[^>]*>/gi, " ");
 
-  // ② media inside a sub-comp — never driven by the runtime (renders blank/black).
-  const media = scan.match(/<(video|audio)(?=[\s/>])/i);
-  if (media) {
-    errors.push(
-      `${label}: has a <${media[1].toLowerCase()}> inside the sub-composition. The runtime only drives media that is a DIRECT child of the host root (index.html) — sub-comp media renders blank/black. Move the clip to index.html as a root-level <video>/<audio> and drive any per-scene motion on the main timeline (composition-patterns.md archetype B).`,
-    );
-  }
-
-  // ③ timed-element checks: missing class="clip", and same-track window overlap.
+  // ② timed-element checks: missing class="clip", and same-track window overlap.
+  // (Media inside a sub-comp is fine: the runtime's global media sweep seeks + decodes
+  // <video>/<audio> at any nesting depth, re-basing each clip's local data-start by its
+  // host composition's absolute start — no root-child requirement. See
+  // packages/core/src/runtime/{media,startResolver}.ts.)
   const re = new RegExp(OPEN_TAG, "g");
   const clips = [];
   let m;
@@ -291,7 +287,7 @@ for (const f of manifest.frames) {
   } catch (error) {
     die(`${label}: ${error.message}`);
   }
-  // pre-assembly guards: ① repair missing root dims in place, ②/③ collect fatal violations.
+  // pre-assembly guards: ① repair missing root dims in place, ② collects fatal violations.
   const guard = guardFrame(html, label);
   if (guard.repairedHtml) {
     writeFileSync(compAbs, guard.repairedHtml);