Skip to content

Commit e7f9918

Browse files
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.
1 parent 7cf6416 commit e7f9918

11 files changed

Lines changed: 49 additions & 89 deletions

File tree

‎packages/cli/src/registry/registryComponents.test.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,7 @@ async function invalidInstallableMedia(entryName: string): Promise<string[]> {
2626
isSubComposition: true,
2727
});
2828
for (const finding of result.findings) {
29-
if (finding.code !== "media_in_subcomposition" && finding.code !== "media_missing_src") {
30-
continue;
31-
}
29+
if (finding.code !== "media_missing_src") continue;
3230
invalidMedia.push(`${entryName}/${file.path}: ${finding.code}`);
3331
}
3432
}

‎packages/lint/src/rules/media.test.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -348,7 +348,13 @@ describe("media rules", () => {
348348
expect(finding).toBeUndefined();
349349
});
350350

351-
it("flags <video> inside a sub-composition (media must be a host-root child)", async () => {
351+
it("does not flag <video> inside a sub-composition (runtime drives nested media)", async () => {
352+
// The runtime's global media sweep (querySelectorAll("video, audio")) drives
353+
// media at any nesting depth, and startResolver re-bases each nested clip's
354+
// local data-start by its host composition's absolute start. Sub-composition
355+
// media is therefore seeked + decoded correctly in preview and render — see
356+
// packages/core/src/runtime/{media,startResolver,init}.ts. A prior
357+
// `media_in_subcomposition` rule wrongly hard-errored this and was removed.
352358
const html = `<template id="scene-template">
353359
<div id="root" data-composition-id="scene" data-width="1920" data-height="1080">
354360
<video id="v1" src="clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
@@ -357,10 +363,7 @@ describe("media rules", () => {
357363
</template>`;
358364
const result = await lintHyperframeHtml(html, { isSubComposition: true });
359365
const finding = result.findings.find((f) => f.code === "media_in_subcomposition");
360-
expect(finding).toBeDefined();
361-
expect(finding?.severity).toBe("error");
362-
expect(finding?.elementId).toBe("v1");
363-
expect(finding?.message).toContain("sub-composition");
366+
expect(finding).toBeUndefined();
364367
});
365368

366369
it("does not flag media in a host-root (non-sub) composition", async () => {

‎packages/lint/src/rules/media.ts‎

Lines changed: 0 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -396,29 +396,6 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
396396
return findings;
397397
},
398398

399-
// media_in_subcomposition — <video>/<audio> only render as a DIRECT child of the host
400-
// root (index.html). Inside a sub-composition <template> the runtime never seeks/decodes
401-
// them, so they render BLANK/black in preview and renders — and the other lint/validate
402-
// passes otherwise miss it (only a per-frame snapshot reveals the blank panel).
403-
({ tags, options }) => {
404-
const findings: HyperframeLintFinding[] = [];
405-
if (!options.isSubComposition) return findings;
406-
for (const tag of tags) {
407-
if (tag.name !== "video" && tag.name !== "audio") continue;
408-
const elementId = readAttr(tag.raw, "id") || undefined;
409-
findings.push({
410-
code: "media_in_subcomposition",
411-
severity: "error",
412-
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.`,
413-
elementId,
414-
fixHint:
415-
"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.",
416-
snippet: truncateSnippet(tag.raw),
417-
});
418-
}
419-
return findings;
420-
},
421-
422399
// self_closing_media_tag
423400
({ source }) => {
424401
const findings: HyperframeLintFinding[] = [];

‎skills-manifest.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"files": 140
77
},
88
"faceless-explainer": {
9-
"hash": "d53bcc3cbcfaa7bb",
9+
"hash": "15fc5a20e2a44bbe",
1010
"files": 22
1111
},
1212
"figma": {
@@ -26,11 +26,11 @@
2626
"files": 121
2727
},
2828
"hyperframes-cli": {
29-
"hash": "dc57ec7198b9eaac",
29+
"hash": "de00375f053c05e8",
3030
"files": 11
3131
},
3232
"hyperframes-core": {
33-
"hash": "85004c9571ed19ce",
33+
"hash": "773fc6d15d9e87b3",
3434
"files": 19
3535
},
3636
"hyperframes-creative": {
@@ -58,7 +58,7 @@
5858
"files": 132
5959
},
6060
"pr-to-video": {
61-
"hash": "17ed27aa2cc32501",
61+
"hash": "0eb5abe09844cee4",
6262
"files": 29
6363
},
6464
"product-launch-video": {

‎skills/faceless-explainer/scripts/assemble-index.mjs‎

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -38,14 +38,14 @@
3838
// `lint` failures surface HERE instead of after assembly + a wasted render):
3939
// ① AUTO-REPAIR — a sub-comp root missing data-width/data-height: inject the canvas
4040
// dims (the renderer needs them on the cloned root; else lint root_missing_dimensions).
41-
// ② HARD FAIL — <video>/<audio> inside a sub-comp: the runtime only drives media that
42-
// is a DIRECT child of the host root, so sub-comp media renders blank/black.
43-
// ③ HARD FAIL — a timed element (data-start+duration+track-index) that is not the root
41+
// ② HARD FAIL — a timed element (data-start+duration+track-index) that is not the root
4442
// and lacks class="clip" (shows the whole frame), or two same-track clips that overlap.
43+
// (Media inside a sub-comp is NOT a violation: the runtime seeks + decodes nested
44+
// <video>/<audio> at any depth — see packages/core/src/runtime/{media,startResolver}.ts.)
4545
//
4646
// Exit 0 = index.html written + summary. Exit 1 = fatal contract break (no
4747
// frames, a built/animated frame missing its src/file, a frame with no
48-
// duration, an inner data-composition-id mismatch, or a guard ②/③ violation).
48+
// duration, an inner data-composition-id mismatch, or a guard ② violation).
4949
// No backstop: fix upstream.
5050

5151
import { existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -121,15 +121,15 @@ const outPath = resolve(flag("out", join(hyperframesDir, "index.html")));
121121

122122
const r3 = (x) => Math.round(x * 1000) / 1000;
123123
const anomalies = [];
124-
const frameErrors = []; // fatal per-frame composition violations (guards ②/③) — reported together
124+
const frameErrors = []; // fatal per-frame composition violations (guard ②) — reported together
125125
const repairs = []; // auto-repairs applied to frame files in place (guard ①)
126126

127127
// ---------- parse storyboard ----------
128128
if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
129129
const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
130130
const { width: WIDTH, height: HEIGHT } = parseFormat(manifest.globals.format);
131131

132-
// ---------- per-frame composition guards (see header ①②③) ----------
132+
// ---------- per-frame composition guards (see header ①②) ----------
133133
// String-level checks on each frame's HTML — no DOM parse, deterministic, run in
134134
// the same pass that already reads the file. OPEN_TAG matches one opening tag while
135135
// tolerating quoted attribute values that contain ">" (e.g. inline styles).
@@ -166,21 +166,17 @@ function guardFrame(html, label) {
166166
const errors = [];
167167
// Scan a copy with comments + <script>/<style> bodies blanked, so a tag-like string
168168
// in a comment (e.g. "<!-- match the host <video> coords -->") or in GSAP code can't
169-
// trip ②/③. ① still splices into the ORIGINAL html, so its offsets stay correct.
169+
// trip ②. ① still splices into the ORIGINAL html, so its offsets stay correct.
170170
const scan = html
171171
.replace(/<!--[\s\S]*?-->/g, " ")
172172
.replace(/<script\b[\s\S]*?<\/script[^>]*>/gi, " ")
173173
.replace(/<style\b[\s\S]*?<\/style[^>]*>/gi, " ");
174174

175-
// ② media inside a sub-comp — never driven by the runtime (renders blank/black).
176-
const media = scan.match(/<(video|audio)(?=[\s/>])/i);
177-
if (media) {
178-
errors.push(
179-
`${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).`,
180-
);
181-
}
182-
183-
// ③ timed-element checks: missing class="clip", and same-track window overlap.
175+
// ② timed-element checks: missing class="clip", and same-track window overlap.
176+
// (Media inside a sub-comp is fine: the runtime's global media sweep seeks + decodes
177+
// <video>/<audio> at any nesting depth, re-basing each clip's local data-start by its
178+
// host composition's absolute start — no root-child requirement. See
179+
// packages/core/src/runtime/{media,startResolver}.ts.)
184180
const re = new RegExp(OPEN_TAG, "g");
185181
const clips = [];
186182
let m;
@@ -285,7 +281,7 @@ for (const f of manifest.frames) {
285281
`${label}: ${f.src} is empty or has no HTML — the worker wrote a blank/partial file. Re-dispatch that worker before assembling.`,
286282
);
287283
}
288-
// pre-assembly guards: ① repair missing root dims in place, ②/③ collect fatal violations.
284+
// pre-assembly guards: ① repair missing root dims in place, ② collects fatal violations.
289285
const guard = guardFrame(html, label);
290286
if (guard.repairedHtml) {
291287
writeFileSync(compAbs, guard.repairedHtml);

‎skills/hyperframes-cli/references/lint-validate-inspect.md‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,7 @@ npx hyperframes lint --json # machine-readable
2323

2424
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.
2525

26-
**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:
27-
28-
```bash
29-
grep -nE '<(video|audio)\b' compositions/*.html # expect NO matches; media belongs in index.html
30-
```
31-
32-
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).
26+
`<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).
3327

3428
## check
3529

‎skills/hyperframes-core/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ Surfaced here; full rationale in the linked reference. Do not violate:
6060
- No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count). → `determinism-rules.md`
6161
- 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`
6262
- No `<br>` in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → `determinism-rules.md`
63-
- `<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`
63+
- `<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`
6464
- 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`
6565
- 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`
6666

‎skills/hyperframes-core/references/composition-patterns.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -130,11 +130,11 @@ Key properties of this layout:
130130

131131
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.
132132

133-
### B. Host media + main-timeline driver (REQUIRED for any `<video>`/`<audio>`)
133+
### B. Host media + main-timeline driver (one pattern for `<video>`/`<audio>`)
134134

135-
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.
135+
`<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.
136136

137-
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`.
137+
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`.
138138

139139
```html
140140
<!-- index.html (host) -->
@@ -193,7 +193,7 @@ A sub-comp timeline **cannot** drive host elements (a global selector or `docume
193193

194194
Caveats:
195195

196-
- The host media must be a direct root child and exist in the DOM (static in `index.html`) — it always is.
196+
- 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.)
197197
- 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.
198198
- Two media elements sharing the same `src` + `data-start` trigger `duplicate_media_discovery_risk` (benign — both still render).
199199

‎skills/hyperframes-core/references/data-attributes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ The root should be `position: relative`, have explicit pixel dimensions, and hid
2222

2323
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).
2424

25-
**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`.)
25+
**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`.)
2626

2727
| Attribute | Required | Meaning |
2828
| ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |

0 commit comments

Comments
 (0)