Skip to content

Write HTML. Render video. Built for agents.

fix(lint): tell an agent where to move a video nested in a timed wrapper (#6113)

Miguel Ángeld1aeb31bf47d
diff --git a/packages/lint/src/rules/media.test.ts b/packages/lint/src/rules/media.test.ts
index 07a00fea68..a8f4b29144 100644
--- a/packages/lint/src/rules/media.test.ts
+++ b/packages/lint/src/rules/media.test.ts
@@ -319,6 +319,90 @@ describe("media rules", () => {
expect(finding?.elementId).toBe("demo-video");
});
+ it("names the timed wrapper in the hint, and following it lints clean", async () => {
+ const page = (body: string) => `
+<html><body>
+ <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+ ${body}
+ </div>
+ <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+ const codes = async (body: string) =>
+ (await lintHyperframeHtml(page(body))).findings.map((f) => f.code);
+
+ const nested = await lintHyperframeHtml(
+ page(
+ `<div id="wrap" class="clip" data-start="2" data-duration="6"><video id="nv" src="assets/clip.mp4" muted></video></div>`,
+ ),
+ );
+ const hint = nested.findings.find((f) => f.code === "media_missing_data_start")?.fixHint;
+ expect(hint).toContain('id="wrap"');
+ expect(hint).toContain('data-start="2"');
+ expect(hint).not.toContain('data-start="0"');
+
+ // The hint's one step: the video leaves the wrapper and takes its timing.
+ const followed = await codes(
+ `<div id="wrap" class="clip" data-start="2" data-duration="6"></div><video id="nv" src="assets/clip.mp4" data-start="2" data-duration="6" muted></video>`,
+ );
+ expect(followed).not.toContain("media_missing_data_start");
+ expect(followed).not.toContain("video_nested_in_timed_element");
+
+ // Direct case keeps the plain hint, and following it is clean too.
+ const direct = await lintHyperframeHtml(
+ page(`<video id="dv" src="assets/clip.mp4" muted></video>`),
+ );
+ expect(direct.findings.find((f) => f.code === "media_missing_data_start")?.fixHint).toContain(
+ 'data-start="0"',
+ );
+ expect(
+ await codes(
+ `<video id="dv" src="assets/clip.mp4" data-start="0" data-duration="5" muted></video>`,
+ ),
+ ).not.toContain("media_missing_data_start");
+ });
+
+ it("hints the innermost timed wrapper, skips closed siblings, and leaves audio alone", async () => {
+ const hintFor = async (body: string) =>
+ (
+ await lintHyperframeHtml(`
+<html><body>
+ <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">${body}</div>
+ <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`)
+ ).findings.find((f) => f.code === "media_missing_data_start")?.fixHint;
+
+ const scene = await hintFor(
+ `<div id="scene" data-start="0" data-duration="10"><div id="clip" data-start="3" data-duration="4"><video id="v" src="a.mp4" muted></video></div></div>`,
+ );
+ expect(scene).toContain('id="clip"');
+ expect(scene).toContain('data-start="3" and data-duration="4"');
+
+ const sibling = await hintFor(
+ `<div id="scene" data-start="0" data-duration="10"><div id="gone" data-start="1"></div><video id="v" src="a.mp4" muted></video></div>`,
+ );
+ expect(sibling).toContain('id="scene"');
+
+ const afterClosed = await lintHyperframeHtml(`
+<html><body>
+ <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+ <div id="title" data-start="0" data-duration="3"></div>
+ <div id="frame"><video id="v" src="a.mp4" data-start="4" data-duration="5" muted></video></div>
+ </div>
+ <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`);
+ expect(afterClosed.findings.map((f) => f.code)).not.toContain("video_nested_in_timed_element");
+
+ const noDuration = await hintFor(
+ `<div id="w" data-start="2"><video id="v" src="a.mp4" muted></video></div>`,
+ );
+ expect(noDuration).toContain('data-start="2".');
+
+ const audio = await hintFor(
+ `<div id="w" data-start="2" data-duration="6"><audio id="a" src="a.mp3"></audio></div>`,
+ );
+ expect(audio).toContain('data-start="0"');
+ });
+
it("allows audible video clips to omit muted when data-has-audio is true", async () => {
const html = `
<html><body>
diff --git a/packages/lint/src/rules/media.ts b/packages/lint/src/rules/media.ts
index 02e1706605..d185e54f6d 100644
--- a/packages/lint/src/rules/media.ts
+++ b/packages/lint/src/rules/media.ts
@@ -423,6 +423,66 @@ function findRuntimeMediaSrcMutationFindings(ctx: LintContext): HyperframeLintFi
return findings;
}
+// HTML5 void elements cannot contain children, so they can never be a parent
+// of a nested <video>. Skipping them avoids false positives where the linter
+// looks for `</img>` and never finds it.
+const VOID_ELEMENTS = new Set([
+ "area",
+ "base",
+ "br",
+ "col",
+ "embed",
+ "hr",
+ "img",
+ "input",
+ "link",
+ "meta",
+ "source",
+ "track",
+ "wbr",
+]);
+
+const closeTag = (name: string) => new RegExp(`</${name}>`, "gi");
+
+function innermostTimedWrapper(
+ source: string,
+ tags: OpenTag[],
+ media: OpenTag,
+): { name: string; id?: string; start: string; duration: string | null } | null {
+ let found: ReturnType<typeof innermostTimedWrapper> = null;
+ for (const parent of tags) {
+ if (parent.index >= media.index) break;
+ if (parent.name === "video" || parent.name === "audio" || VOID_ELEMENTS.has(parent.name))
+ continue;
+ // The composition root uses data-start as a playback anchor, not as a clip timer
+ if (readDecodedAttr(parent.raw, "data-composition-id")) continue;
+ const start = readAttr(parent.raw, "data-start");
+ if (!start) continue;
+ const events: Array<[at: number, delta: 1 | -1]> = [
+ ...tags
+ .filter((t) => t.name === parent.name && t.index > parent.index && t.index < media.index)
+ .map((t): [number, 1] => [t.index, 1]),
+ ...[...source.substring(parent.index, media.index).matchAll(closeTag(parent.name))].map(
+ (m): [number, -1] => [parent.index + m.index, -1],
+ ),
+ ];
+ let depth = 1;
+ for (const [, delta] of events.sort((x, y) => x[0] - y[0])) {
+ depth += delta;
+ if (depth === 0) break;
+ }
+ if (depth > 0) {
+ found = {
+ name: parent.name,
+ id: readAttr(parent.raw, "id") || undefined,
+ start,
+ duration: readAttr(parent.raw, "data-duration"),
+ };
+ }
+ }
+ return found;
+}
+
export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
findNestedMediaStartBasisFindings,
findSpeedRampOnNonMediaFindings,
@@ -570,59 +630,20 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
// video_nested_in_timed_element
({ source, tags }) => {
const findings: HyperframeLintFinding[] = [];
- // HTML5 void elements cannot contain children, so they can never be a
- // parent of a nested <video>. Skipping them avoids false positives where
- // the linter looks for `</img>` and never finds it.
- const voidElements = new Set([
- "area",
- "base",
- "br",
- "col",
- "embed",
- "hr",
- "img",
- "input",
- "link",
- "meta",
- "source",
- "track",
- "wbr",
- ]);
- const timedTagPositions: Array<{ name: string; start: number; id?: string }> = [];
- for (const tag of tags) {
- if (tag.name === "video" || tag.name === "audio") continue;
- if (voidElements.has(tag.name)) continue;
- // Skip the composition root — it uses data-start as a playback anchor, not as a clip timer
- if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
- if (readAttr(tag.raw, "data-start")) {
- timedTagPositions.push({
- name: tag.name,
- start: tag.index,
- id: readAttr(tag.raw, "id") || undefined,
- });
- }
- }
for (const tag of tags) {
if (tag.name !== "video") continue;
if (!readAttr(tag.raw, "data-start")) continue;
- for (const parent of timedTagPositions) {
- if (parent.start < tag.index) {
- const parentClosePattern = new RegExp(`</${parent.name}>`, "gi");
- const between = source.substring(parent.start, tag.index);
- if (!parentClosePattern.test(between)) {
- findings.push({
- code: "video_nested_in_timed_element",
- severity: "error",
- message: `<video> with data-start is nested inside <${parent.name}${parent.id ? ` id="${parent.id}"` : ""}> which also has data-start. The frame extractor resolves the video's start from its own data-start without the wrapper's offset, while visibility uses the wrapper's window, so the two disagree: the clip shows the wrong source frames and then disappears partway through its slot.`,
- elementId: readAttr(tag.raw, "id") || undefined,
- fixHint:
- "Time the wrapper OR the video, never both: remove data-start from the wrapper (use it as a non-timed visual container), or move the <video> up to be a direct child of the stage.",
- snippet: truncateSnippet(tag.raw),
- });
- break;
- }
- }
- }
+ const parent = innermostTimedWrapper(source, tags, tag);
+ if (!parent) continue;
+ findings.push({
+ code: "video_nested_in_timed_element",
+ severity: "error",
+ message: `<video> with data-start is nested inside <${parent.name}${parent.id ? ` id="${parent.id}"` : ""}> which also has data-start. The frame extractor resolves the video's start from its own data-start without the wrapper's offset, while visibility uses the wrapper's window, so the two disagree: the clip shows the wrong source frames and then disappears partway through its slot.`,
+ elementId: readAttr(tag.raw, "id") || undefined,
+ fixHint:
+ "Time the wrapper OR the video, never both: remove data-start from the wrapper (use it as a non-timed visual container), or move the <video> up to be a direct child of the stage.",
+ snippet: truncateSnippet(tag.raw),
+ });
}
return findings;
},
@@ -698,7 +719,7 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
},
// media_missing_data_start + media_missing_id + media_missing_src + media_preload_none
- ({ tags }) => {
+ ({ source, tags }) => {
const findings: HyperframeLintFinding[] = [];
for (const tag of tags) {
if (tag.name !== "video" && tag.name !== "audio") continue;
@@ -706,12 +727,15 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
const hasId = readAttr(tag.raw, "id");
const hasSrc = mediaHasResolvableSrc(tag, tags);
if (hasSrc && !hasDataStart) {
+ const wrapper = tag.name === "video" ? innermostTimedWrapper(source, tags, tag) : null;
findings.push({
code: "media_missing_data_start",
severity: "error",
message: `<${tag.name}${hasId ? ` id="${hasId}"` : ""}> has src but no data-start. HyperFrames cannot own playback for untimed media, so preview and render behavior can diverge.`,
elementId: hasId || undefined,
- fixHint: `Add data-start="0" (or the intended start time) and data-duration if the clip should stop before the source ends.`,
+ fixHint: wrapper
+ ? `This <${tag.name}> sits inside the timed <${wrapper.name}${wrapper.id ? ` id="${wrapper.id}"` : ""}> (data-start="${wrapper.start}"), and the wrapper's data-start would then clash. Move the <${tag.name}> out as a direct child of the stage and give it that wrapper's data-start="${wrapper.start}"${wrapper.duration ? ` and data-duration="${wrapper.duration}"` : ""}.`
+ : `Add data-start="0" (or the intended start time) and data-duration if the clip should stop before the source ends.`,
snippet: truncateSnippet(tag.raw),
});
}