Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { describe, it, expect } from "vitest";
import { lintHyperframeHtml } from "../hyperframeLinter.js";
describe("media rules", () => {
it("reports a missing real media id even when the title mentions one", async () => {
const html = `<html><body>
<div id="root" data-composition-id="main" data-width="640" data-height="360">
<video title='id="ghost"' src="clip.mp4" data-start="0" data-duration="1" muted></video>
</div>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.map((finding) => finding.code)).toContain("media_missing_id");
});
it.each([
'title="an unmuted muted crossorigin clip"',
"title='an unmuted muted crossorigin clip'",
])("does not treat words in %s as media attributes", async (tooltip) => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" ${tooltip} src="a.mp4" data-start="0" data-duration="3"></video>
<audio id="a1" src="a.mp4" data-start="0" data-duration="3"></audio>
</div>
</body></html>`;
const result = await lintHyperframeHtml(html);
const codes = result.findings.map((finding) => finding.code);
expect(codes).toContain("video_missing_muted");
expect(codes).toContain("video_audio_double_source");
expect(codes).not.toContain("media_crossorigin_breaks_preview");
});
it.each(["muted", 'muted=""', 'muted="false"', "MUTED"])(
"keeps %s as a present Boolean attribute",
async (mutedAttr) => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" ${mutedAttr} src="a.mp4" data-start="0" data-duration="3"></video>
</div>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.some((finding) => finding.code === "video_missing_muted")).toBe(false);
},
);
it("reports error for duplicate media ids", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" src="a.mp4" data-start="0" data-duration="5"></video>
<video id="v1" src="b.mp4" data-start="0" data-duration="3"></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "duplicate_media_id");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("v1");
});
it("reports error for audio with data-start but no id", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<audio data-start="0" data-duration="10" src="narration.wav"></audio>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_missing_id");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("SILENT");
});
it("reports error for video with data-start but no id", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video data-start="0" data-duration="10" src="clip.mp4" muted playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_missing_id");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("FROZEN");
});
it("flags media that has data-hf-id but no real id", async () => {
// Regression: readAttr(tag, "id") used a \b boundary that matched the
// trailing `id="…"` inside `data-hf-id="…"`, so media carrying only a
// Studio-stamped data-hf-id passed the check and then rendered as a blank
// wash (video) / silent (audio). data-hf-id is NOT a render id.
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video data-hf-id="hf-v1a2b3" data-start="0" data-duration="10" src="clip.mp4" muted playsinline></video>
<audio data-hf-id="hf-a4c5d6" data-start="0" data-duration="10" src="narration.wav"></audio>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const findings = result.findings.filter((f) => f.code === "media_missing_id");
expect(findings).toHaveLength(2);
expect(findings.every((f) => f.severity === "error")).toBe(true);
});
it("does not flag media elements that have id", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<audio id="a1" data-start="0" data-duration="10" src="narration.wav"></audio>
<video id="v1" data-start="0" data-duration="10" src="clip.mp4" muted playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_missing_id");
expect(finding).toBeUndefined();
});
it("reports grading controls placed outside their schema sections", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" data-start="0" data-duration="5" src="clip.mp4" muted data-color-grading='{"preset":"skin-soft","intensity":0.58,"highlights":-0.06,"temperature":0.02}'></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "color_grading_invalid_structure");
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("highlights");
expect(finding?.fixHint).toContain('"adjust"');
});
it("accepts grading controls inside their schema sections", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" data-start="0" data-duration="5" src="clip.mp4" muted data-color-grading='{"preset":"skin-soft","intensity":0.58,"adjust":{"highlights":-0.06,"temperature":0.02},"details":{"vignette":0.03},"effects":{"blur":0.1,"chromaBleed":0.2,"tapeDamage":0.3,"tapeTracking":0.4,"tapeNoise":0.5,"tapeSpeed":0.6,"filmArtifacts":0.4,"halftone":0.5,"halftoneSize":0.6,"twoInkPrint":0.7,"twoInkPrintSize":0.8,"ascii":0.9,"asciiSize":0.4,"asciiInvert":1,"dither":0.8,"ditherSize":0.3,"bloom":0.5,"bloomRadius":8,"asciiStyle":4,"asciiColor":1,"asciiRotation":1,"monoScreen":0.5,"monoScreenSize":0.4,"monoScreenAngle":0.3,"monoScreenSpread":0.2,"monoScreenShape":3,"monoScreenInvert":1,"scanlines":0.3,"scanlineCount":0.4,"scanlineSoftness":0.5,"chromaticAberration":0.2,"chromaticAngle":0.6,"crtCurvature":0.25,"digitalGlitch":0.4,"digitalGlitchColorSplit":0.45,"digitalGlitchLineTear":0.5,"digitalGlitchPixelate":0.55,"digitalGlitchBlockAmount":0.6,"digitalGlitchBlockDisplacement":0.7,"digitalGlitchBlockOpacity":0.2,"digitalGlitchSpeed":0.7,"engraving":1,"engravingSpacing":0.4117647,"engravingMinThickness":0.2,"engravingMaxThickness":0.4571429,"engravingAngle":0.25,"engravingContrast":0.4666667,"engravingSharpness":0.59,"engravingWave":0.2,"engravingWaveFrequency":0.2222222},"palette":["#ff6b66","#080717","#d9339f","#3c185f"],"lut":null}'></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code.startsWith("color_grading_"))).toBeUndefined();
});
it("accepts crosshatch controls in the effects section", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video data-start="0" data-duration="5" src="clip.mp4" muted data-color-grading='{"effects":{"crosshatch":1,"crosshatchSpacing":0.28,"crosshatchThickness":0.25,"crosshatchAngle":0.25,"crosshatchContrast":0.3333333,"crosshatchEdges":0.5,"crosshatchLineWeight":0,"crosshatchWave":0.33,"crosshatchWaveFrequency":0.2222222}}'></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code.startsWith("color_grading_"))).toBeUndefined();
});
it("accepts Kuwahara controls in the effects section", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video data-start="0" data-duration="5" src="clip.mp4" muted data-color-grading='{"effects":{"kuwahara":1,"kuwaharaRadius":0.142857,"kuwaharaSharpness":0.3125,"kuwaharaSaturation":0.5}}'></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code.startsWith("color_grading_"))).toBeUndefined();
});
it("reports malformed or out-of-range color grading palettes", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" data-start="0" data-duration="5" src="clip.mp4" muted data-color-grading='{"effects":{"dither":1},"palette":["#000000","red"]}'></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "color_grading_invalid_structure");
expect(finding?.severity).toBe("error");
expect(finding?.fixHint).toContain("2 to 6");
expect(finding?.fixHint).toContain("#RRGGBB");
});
it("reports malformed grading JSON", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" data-start="0" data-duration="5" src="clip.mp4" muted data-color-grading='{"preset":"skin-soft"'></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "color_grading_invalid_json")?.severity).toBe(
"error",
);
});
it("reports invalid string values for structured grading sections", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" data-start="0" data-duration="5" src="clip.mp4" muted data-color-grading='{"adjust":"cinematic"}'></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "color_grading_invalid_structure")?.severity,
).toBe("error");
});
it("reports color grading on non-media elements", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="background" data-color-grading='{"preset":"skin-soft"}'></div>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "color_grading_non_media")?.severity).toBe(
"error",
);
});
it("accepts color grading on a canvas", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<canvas id="drawn" width="1920" height="1080" data-color-grading='{"preset":"skin-soft"}'></canvas>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.filter((f) => f.code.startsWith("color_grading_"))).toEqual([]);
});
it("reports warning for media with preload=none", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" data-start="0" data-duration="10" src="clip.mp4" muted playsinline preload="none"></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_preload_none");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("warning");
});
it("reports error for media with id but no src", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<audio id="a1" data-start="0" data-duration="10"></audio>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_missing_src");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
});
it("accepts <source src> children in place of parent src", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="rec" data-start="0" data-duration="4" muted playsinline>
<source src="clip.mp4" type="video/mp4">
<source src="clip.webm" type="video/webm">
</video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.some((f) => f.code === "media_missing_src")).toBe(false);
});
it("reports error for <source>-only media with no data-start", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="rec" muted playsinline>
<source src="clip.mp4" type="video/mp4">
</video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_missing_data_start");
expect(finding).toBeDefined();
expect(finding?.elementId).toBe("rec");
});
it("reports error for media with src but no data-start", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="demo-video" src="clip.mp4" muted playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_missing_data_start");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
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>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="demo-video" data-start="0" data-duration="5" data-has-audio="true" src="clip.mp4" playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "video_missing_muted")).toBeUndefined();
expect(
result.findings.find((f) => f.code === "video_muted_with_declared_audio"),
).toBeUndefined();
});
it("reports error for videos that declare audio while muted", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="demo-video" data-start="0" data-duration="5" data-has-audio="true" src="clip.mp4" muted playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "video_muted_with_declared_audio");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("demo-video");
});
it("video_missing_muted recommends data-has-audio first", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v" data-start="0" data-duration="5" src="clip.mp4" playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "video_missing_muted");
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("declares neither muted nor data-has-audio");
expect(finding?.message).not.toContain("separate <audio>");
expect(finding?.fixHint?.indexOf("data-has-audio")).toBeLessThan(
finding?.fixHint?.indexOf("muted") ?? -1,
);
});
it("video_audio_double_source suggests removing the <audio> first", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v" data-start="0" data-duration="5" data-has-audio="true" src="clip.mp4" playsinline></video>
<audio id="a" data-start="0" data-duration="5" src="clip.mp4"></audio>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "video_audio_double_source");
expect(finding?.fixHint?.startsWith("Remove the <audio>")).toBe(true);
});
const wrap = (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 (html: string) =>
(await lintHyperframeHtml(html)).findings.map((f) => f.code);
it.each(['data-has-audio="false"', 'data-has-audio=""', "data-has-audio"])(
"video_missing_muted stays quiet when the video declares its audio state (%s)",
async (attr) => {
const found = await codes(
wrap(`<video id="v" data-start="0" data-duration="5" ${attr} src="clip.mp4"></video>`),
);
expect(found).not.toContain("video_missing_muted");
},
);
it.each(['data-has-audio="false"', 'data-has-audio=""', "muted"])(
"video_audio_double_source ignores an explicitly silent video (%s)",
async (attr) => {
const found = await codes(
wrap(`<video id="v" data-start="0" data-duration="5" ${attr} src="clip.mp4"></video>
<audio id="a" data-start="0" data-duration="5" src="clip.mp4"></audio>`),
);
expect(found).not.toContain("video_audio_double_source");
},
);
it("video_audio_double_source ignores same-src clips that do not overlap in time", async () => {
const found = await codes(
wrap(`<video id="v" data-start="0" data-duration="4" data-has-audio="true" src="clip.mp4"></video>
<audio id="a" data-start="4" data-duration="4" src="clip.mp4"></audio>`),
);
expect(found).not.toContain("video_audio_double_source");
});
it("video_audio_double_source flags same-src clips that overlap in time", async () => {
const found = await codes(
wrap(`<video id="v" data-start="0" data-duration="4" data-has-audio="true" src="clip.mp4"></video>
<audio id="a" data-start="3" data-duration="4" src="clip.mp4"></audio>`),
);
expect(found).toContain("video_audio_double_source");
});
it("video_audio_double_source keeps flagging when a duration is not numeric", async () => {
const found = await codes(
wrap(`<video id="v" data-start="0" data-has-audio="true" src="clip.mp4"></video>
<audio id="a" data-start="9" data-duration="4" src="clip.mp4"></audio>`),
);
expect(found).toContain("video_audio_double_source");
});
it("does NOT flag <video> as nested in a void element with data-start (regression)", async () => {
// Regression: void elements like <img> have no closing tag, so the previous
// implementation kept them on the parent stack indefinitely and flagged any
// later <video> with data-start as "nested" inside them.
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<img id="hdr-img" src="hdr.png" data-start="0" data-duration="5" data-track-index="0" />
<video id="hdr-vid" src="clip.mp4" data-start="5" data-duration="5" data-track-index="1" muted playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "video_nested_in_timed_element");
expect(finding).toBeUndefined();
});
it("reports imperative play() control on managed media ids", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="demo-video" data-start="0" data-duration="5" src="clip.mp4" muted playsinline></video>
</div>
<script>
const video = document.getElementById("demo-video");
video.play();
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "imperative_media_control");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("demo-video");
});
function optionalMediaScene(script: string): string {
return `<html><body>
<div id="root" data-composition-id="main" data-width="640" data-height="360">
<video id="demo-video" class="demo-video" src="clip.mp4" muted data-start="0" data-duration="1"></video>
<div id="panel"></div>
</div>
<script>${script}</script>
</body></html>`;
}
it.each([
'const video = document.getElementById("demo-video"); video?.play();',
'const video = document.getElementById("demo-video"); video.play?.();',
'const video = document.getElementById("demo-video"); video?.play?.();',
'const video = document.querySelector("#demo-video"); video?.pause();',
'const video = document.querySelector(".demo-video"); video.pause?.();',
'document.getElementById("demo-video")?.play();',
'document.getElementById("demo-video").pause?.();',
'document.querySelector("#demo-video")?.play?.();',
'window.document.querySelector("video")?.pause();',
'const video = document.getElementById("demo-video"); const label = `playing ${video?.play()}`;',
])("reports an executed optional media call: %s", async (script) => {
const result = await lintHyperframeHtml(optionalMediaScene(script));
expect(
result.findings.find((finding) => finding.code === "imperative_media_control"),
).toMatchObject({
severity: "error",
});
});
it.each([
'const video = document.getElementById("demo-video"); const example = "video.play()";',
'const video = document.getElementById("demo-video"); // video.play()\n',
'const video = document.getElementById("demo-video"); const example = `video.play()`;',
'const video = document.getElementById("demo-video"); const example = /video.play()/;',
'const video = document.getElementById("demo-video"); const example = "video?.play?.()";',
'const video = document.getElementById("demo-video"); /* video?.play() */',
'const video = document.getElementById("demo-video"); const example = `video.pause?.()`;',
`const example = 'document.getElementById("demo-video").play()';`,
`const example = 'document.querySelector("video")?.play()';`,
'const panel = document.getElementById("panel"); panel?.play?.();',
'document.querySelector("#panel")?.pause();',
])("does not report a quoted example or non-media optional call: %s", async (script) => {
const result = await lintHyperframeHtml(optionalMediaScene(script));
expect(result.findings.map((finding) => finding.code)).not.toContain(
"imperative_media_control",
);
});
it("reports imperative currentTime writes on query-selected managed media", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="demo-video" data-start="0" data-duration="5" src="clip.mp4" muted playsinline></video>
</div>
<script>
const demo = document.querySelector("#demo-video");
demo.currentTime = 1.5;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "imperative_media_control");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
});
it("reports imperative muted/play control on class-selected media without ids", async () => {
const html = `
<template id="scene-template">
<div data-composition-id="scene" data-width="1920" data-height="1080">
<video class="demo-video" src="clip.mp4" muted playsinline></video>
<script>
const vid = document.querySelector('[data-composition-id="scene"] .demo-video');
if (vid) { vid.muted = true; vid.play(); }
</script>
</div>
</template>`;
const result = await lintHyperframeHtml(html, { filePath: "compositions/scene.html" });
const imperativeFindings = result.findings.filter((f) => f.code === "imperative_media_control");
expect(imperativeFindings.length).toBe(2);
expect(imperativeFindings.some((f) => f.snippet === "vid.muted =")).toBe(true);
expect(imperativeFindings.some((f) => f.snippet === "vid.play(")).toBe(true);
});
it("does not flag play() on non-media elements", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="panel"></div>
</div>
<script>
const panel = document.getElementById("panel");
panel.play?.();
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "imperative_media_control");
expect(finding).toBeUndefined();
});
it("warns on raw src mutations targeting existing video and audio", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080">
<video id="clip" src="video-a.mp4"></video>
<audio id="voice" src="audio-a.wav"></audio>
</div>
<script>
const clip = document.getElementById("clip");
clip.src = "video-b.mp4";
document.querySelector("#voice").setAttribute("src", "audio-b.wav");
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const findings = result.findings.filter(
(finding) => finding.code === "media_runtime_src_mutation",
);
expect(findings).toHaveLength(2);
expect(findings.map((finding) => finding.elementId).sort()).toEqual(["clip", "voice"]);
expect(findings.every((finding) => finding.fixHint?.includes("data-var-src"))).toBe(true);
});
it("does not flag img or script src mutations", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080">
<img id="poster" src="a.png"><script id="loader"></script>
</div>
<script>
document.getElementById("poster").src = "b.png";
document.getElementById("loader").setAttribute("src", "loader-b.js");
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((finding) => finding.code === "media_runtime_src_mutation"),
).toBeUndefined();
});
it("warns when a source child of existing media is mutated", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080">
<video id="clip"><source id="clip-source" src="video-a.mp4"></video>
</div>
<script>document.getElementById("clip-source").src = "video-b.mp4";</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((finding) => finding.code === "media_runtime_src_mutation"),
).toMatchObject({ severity: "warning", elementId: "clip" });
});
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>
<script>window.__timelines = window.__timelines || {}; window.__timelines["scene"] = gsap.timeline({ paused: true });</script>
</div>
</template>`;
const result = await lintHyperframeHtml(html, { isSubComposition: true });
const finding = result.findings.find((f) => f.code === "media_in_subcomposition");
expect(finding).toBeUndefined();
});
it("does not flag media in a host-root (non-sub) composition", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" src="clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_in_subcomposition");
expect(finding).toBeUndefined();
});
it("warns that an unmarked nonzero nested media start is local", async () => {
const html = `<template>
<div data-composition-id="scene" data-width="1920" data-height="1080">
<video id="clip" src="clip.mp4" data-start="2" data-duration="2" muted></video>
</div>
</template>`;
const result = await lintHyperframeHtml(html, { isSubComposition: true });
const finding = result.findings.find(
(item) => item.code === "nested_media_start_basis_ambiguous",
);
expect(finding?.severity).toBe("warning");
expect(finding?.message).toContain("local to its composition");
expect(finding?.fixHint).toContain('data-hf-media-start-basis="global"');
});
it.each([
['data-start="0"', "zero local start"],
['data-start="2" data-hf-media-start-basis="local"', "explicit local start"],
['data-start="2" data-hf-media-start-basis="global"', "explicit legacy-global start"],
])("does not warn for %s (%s)", async (attrs) => {
const html = `<template>
<div data-composition-id="scene" data-width="1920" data-height="1080">
<audio id="clip" src="clip.wav" ${attrs} data-duration="2"></audio>
</div>
</template>`;
const result = await lintHyperframeHtml(html, { isSubComposition: true });
expect(result.findings.some((item) => item.code === "nested_media_start_basis_ambiguous")).toBe(
false,
);
});
it("reports error for media with crossorigin (breaks preview when host omits CORS)", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" crossorigin="anonymous" src="https://cdn.example.com/clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_crossorigin_breaks_preview");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("v1");
});
it("does not flag media without crossorigin", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" src="https://cdn.example.com/clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
</div>
<script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_crossorigin_breaks_preview");
expect(finding).toBeUndefined();
});
});
describe("media_variable_src_no_fallback", () => {
it("downgrades missing src to a warning when data-var-src is present", async () => {
const html = `<html><body>
<video id="clip" data-start="0" data-duration="2" data-var-src="media"></video>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.some((f) => f.code === "media_missing_src")).toBe(false);
const finding = result.findings.find((f) => f.code === "media_variable_src_no_fallback");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("warning");
});
it("keeps the hard error when neither src nor data-var-src exists", async () => {
const html = `<html><body>
<video id="clip" data-start="0" data-duration="2"></video>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.some((f) => f.code === "media_missing_src")).toBe(true);
});
});
describe("audio_volume_tween_overrides_gain", () => {
const withScript = (audioAttrs: string, script: string) => `<!DOCTYPE html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
<audio id="bgm" src="a.wav" data-start="0" data-duration="10" ${audioAttrs}></audio>
</div>
<script>${script}</script>
</body></html>`;
it("warns that the tween's values win over an authored gain", async () => {
const res = await lintHyperframeHtml(
withScript(`data-volume="1.949845"`, `tl.fromTo("#bgm", { volume: 0 }, { volume: 1 });`),
);
const finding = res.findings.find((f) => f.code === "audio_volume_tween_overrides_gain");
expect(finding?.severity).toBe("warning");
expect(finding?.elementId).toBe("bgm");
expect(finding?.message).toMatch(/5\.8 dB/);
});
it("warns about an attenuation the tween overrides, not just a boost", async () => {
const res = await lintHyperframeHtml(
withScript(`data-volume="0.3"`, `tl.to("#bgm", { volume: 1 });`),
);
expect(res.findings.some((f) => f.code === "audio_volume_tween_overrides_gain")).toBe(true);
});
it("stays quiet on the fade the docs recommend, which carries no data-volume", async () => {
// `Number(null)` is 0 — finite and not 1 — so a clip with NO `data-volume`
// was reported as authored at silence. Both halves were false, and this is
// the shape the docs recommend for a tweened clip: the baseline attribute is
// for elements no tween touches. The rule fired on exactly the common fade.
const res = await lintHyperframeHtml(
withScript("", `tl.fromTo("#bgm", { volume: 0 }, { volume: 1 });`),
);
expect(res.findings.some((f) => f.code === "audio_volume_tween_overrides_gain")).toBe(false);
});
it("stays quiet at unity, without a tween, or when a lane makes the tween inert", async () => {
const unity = await lintHyperframeHtml(
withScript(`data-volume="1"`, `tl.to("#bgm", { volume: 0 });`),
);
const noTween = await lintHyperframeHtml(
withScript(`data-volume="2"`, `tl.to("#bgm", { x: 1 });`),
);
const lane = await lintHyperframeHtml(
withScript(
`data-volume="2" data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":1}]}]}'`,
`tl.to("#bgm", { volume: 0 });`,
),
);
for (const res of [unity, noTween, lane]) {
expect(res.findings.some((f) => f.code === "audio_volume_tween_overrides_gain")).toBe(false);
}
});
});
describe("audio_volume_double_automation", () => {
const withScript = (audioAttrs: string, script: string) => `<!DOCTYPE html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
<audio id="bgm" src="a.wav" data-start="0" data-duration="10" ${audioAttrs}></audio>
</div>
<script>${script}</script>
</body></html>`;
const LANE = `data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":1}]}]}'`;
it("warns when a lane and a GSAP volume tween both shape the same track", async () => {
const res = await lintHyperframeHtml(
withScript(LANE, `tl.to("#bgm", { volume: 0, duration: 1 });`),
);
const finding = res.findings.find((f) => f.code === "audio_volume_double_automation");
expect(finding?.severity).toBe("warning");
expect(finding?.elementId).toBe("bgm");
});
it("stays quiet for a lane alone, a tween alone, or a tween on another track", async () => {
const laneOnly = await lintHyperframeHtml(withScript(LANE, `tl.to("#bgm", { x: 10 });`));
const tweenOnly = await lintHyperframeHtml(withScript("", `tl.to("#bgm", { volume: 0 });`));
const otherTrack = await lintHyperframeHtml(withScript(LANE, `tl.to("#vo", { volume: 0 });`));
for (const res of [laneOnly, tweenOnly, otherTrack]) {
expect(res.findings.some((f) => f.code === "audio_volume_double_automation")).toBe(false);
}
});
it("still warns when another value in the same call is a function result", async () => {
// Bounding the scan at the first `)` to fix the chained-timeline case
// silenced the rule for the ordinary shape of a tween whose object holds a
// call — the paren closing `fadeTime(2)` ended the match before `volume`.
// The lane and the tween still both drive volume, and the author still gets
// no warning about it.
const res = await lintHyperframeHtml(
withScript(LANE, `tl.to("#bgm", { duration: fadeTime(2), volume: 0.2 });`),
);
expect(res.findings.some((f) => f.code === "audio_volume_double_automation")).toBe(true);
});
it("does not blame the wrong element in a chained timeline", async () => {
// A chain has no semicolon until its very end, so a run that could cross `)`
// reached the `volume` in a LATER call and reported the element from an
// earlier one. Acting on the fixHint would have deleted #bgm's only real
// automation to fix a tween that is on #vo.
const res = await lintHyperframeHtml(
withScript(
LANE,
`gsap.timeline().to("#bgm", { duration: 0.6, x: 10 }).to("#vo", { volume: 1 });`,
),
);
expect(res.findings.some((f) => f.code === "audio_volume_double_automation")).toBe(false);
});
it("still catches a real tween further down the same call", async () => {
const res = await lintHyperframeHtml(
withScript(LANE, `gsap.timeline().to("#bgm", { duration: 0.6, ease: "none", volume: 0 });`),
);
expect(res.findings.some((f) => f.code === "audio_volume_double_automation")).toBe(true);
});
it("ignores a lane that automates something other than volume", async () => {
const res = await lintHyperframeHtml(
withScript(
`data-automation='{"version":1,"lanes":[{"target":"fx.n1.frequency","points":[{"t":0,"v":200}]}]}'`,
`tl.to("#bgm", { volume: 0 });`,
),
);
expect(res.findings.some((f) => f.code === "audio_volume_double_automation")).toBe(false);
});
});
describe("audio_group_no_members", () => {
const doc = (body: string) => `<!DOCTYPE html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
${body}
</div>
</body></html>`;
const BUS = `<hf-audio-group id="voiceover" data-label="Voiceover" data-volume="0.4"
data-fx-chain='{"version":1,"nodes":[{"type":"peaking","id":"n1","params":{"frequency":250,"gain":-3,"q":1.2}}]}'></hf-audio-group>`;
it("errors on a bus no clip in the file belongs to", async () => {
const res = await lintHyperframeHtml(
doc(
`${BUS}<audio id="s-1" src="s.wav" data-start="0" data-duration="2" data-audio-group="sfx"></audio>`,
),
);
const finding = res.findings.find((f) => f.code === "audio_group_no_members");
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("voiceover");
});
// The whole point: one typo drops the authored bus (fader AND chain) and
// invents a phantom group at unity, with nothing said about either.
it("catches the misspelled member — the case that motivated the rule", async () => {
const res = await lintHyperframeHtml(
doc(
`${BUS}<audio id="vo-1" src="vo.wav" data-start="0" data-duration="5" data-audio-group="voiceovr"></audio>`,
),
);
const finding = res.findings.find((f) => f.code === "audio_group_no_members");
expect(finding?.elementId).toBe("voiceover");
expect(finding?.message).toContain("voiceovr");
});
it("suggests only unmatched member ids, not a healthy sibling group", async () => {
const res = await lintHyperframeHtml(
doc(`${BUS}<hf-audio-group id="music"></hf-audio-group>
<audio id="bgm" src="music.wav" data-start="0" data-duration="5" data-audio-group="music"></audio>
<audio id="vo-1" src="vo.wav" data-start="0" data-duration="5" data-audio-group="voiceovr"></audio>`),
);
const finding = res.findings.find((item) => item.code === "audio_group_no_members");
expect(finding?.message).toContain('"voiceovr"');
expect(finding?.message).not.toContain('"music"');
});
it("counts an audible video as group membership", async () => {
const res = await lintHyperframeHtml(
doc(`${BUS}<video id="v" src="v.mp4" data-start="0" data-duration="5" data-has-audio="true" data-audio-group="voiceover"></video>
<audio id="s-1" src="s.wav" data-start="0" data-duration="2" data-audio-group="sfx"></audio>`),
);
expect(
res.findings.some(
(finding) => finding.code === "audio_group_no_members" && finding.elementId === "voiceover",
),
).toBe(false);
});
it("does not count a muted video as group membership", async () => {
const res = await lintHyperframeHtml(
doc(`${BUS}<video id="v" src="v.mp4" data-start="0" data-duration="5" muted data-audio-group="voiceover"></video>
<audio id="s-1" src="s.wav" data-start="0" data-duration="2" data-audio-group="sfx"></audio>`),
);
expect(
res.findings.some(
(finding) => finding.code === "audio_group_no_members" && finding.elementId === "voiceover",
),
).toBe(true);
});
it("stays quiet when a clip belongs to it", async () => {
const res = await lintHyperframeHtml(
doc(
`${BUS}<audio id="vo-1" src="vo.wav" data-start="0" data-duration="5" data-audio-group="voiceover"></audio>`,
),
);
expect(res.findings.some((f) => f.code === "audio_group_no_members")).toBe(false);
});
// A bus with no id cannot be joined at all, and `resolveAudioGroups` skips it
// when building its element map — a different mistake, not this rule's.
// The rule can only speak about a file it can see all of. `lintHyperframeHtml`
// takes ONE file, and the studio's own group creation writes the bus into the
// active composition while patching `data-audio-group` into each member's own
// file (timelineAudioGroupCreate) — so a file holding a bus and no members at
// all is the normal cross-file shape, not a mistake.
it("stays quiet in a file that declares no members at all", async () => {
const res = await lintHyperframeHtml(doc(BUS));
expect(res.findings.some((f) => f.code === "audio_group_no_members")).toBe(false);
});
it("stays quiet for an unmatched bus when another group has local members", async () => {
const res = await lintHyperframeHtml(
doc(`<hf-audio-group id="local"></hf-audio-group>
<audio id="local-1" src="local.wav" data-start="0" data-duration="5" data-audio-group="local"></audio>
${BUS}
<div id="host" data-composition-src="compositions/voices.html" data-start="0" data-duration="10"></div>`),
);
expect(res.findings.some((f) => f.code === "audio_group_no_members")).toBe(false);
});
it("stays quiet for a bus with no id", async () => {
const res = await lintHyperframeHtml(
doc(`<hf-audio-group data-label="Nameless"></hf-audio-group>
<audio id="s-1" src="s.wav" data-start="0" data-duration="2" data-audio-group="sfx"></audio>`),
);
expect(res.findings.some((f) => f.code === "audio_group_no_members")).toBe(false);
});
});
describe("audio_group_timing_attrs", () => {
const doc = (busAttrs: string) => `<!DOCTYPE html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
<hf-audio-group id="voiceover" data-label="Voiceover" ${busAttrs}></hf-audio-group>
<audio id="vo-1" src="vo.wav" data-start="0" data-duration="5" data-audio-group="voiceover"></audio>
</div>
</body></html>`;
it("warns on data-start", async () => {
const res = await lintHyperframeHtml(doc(`data-start="0" data-duration="40"`));
const finding = res.findings.find((f) => f.code === "audio_group_timing_attrs");
expect(finding?.severity).toBe("warning");
expect(finding?.elementId).toBe("voiceover");
expect(finding?.message).toContain("data-start");
expect(finding?.message).toContain("data-duration");
});
it("warns on data-track-index", async () => {
const res = await lintHyperframeHtml(doc(`data-track-index="7"`));
expect(res.findings.some((f) => f.code === "audio_group_timing_attrs")).toBe(true);
});
it("stays quiet on a bus carrying only its own attributes", async () => {
const res = await lintHyperframeHtml(doc(`data-volume="0.4" data-hidden`));
expect(res.findings.some((f) => f.code === "audio_group_timing_attrs")).toBe(false);
});
});
describe("audio_group_carve_attr", () => {
const doc = (busAttrs: string) => `<!DOCTYPE html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
<hf-audio-group id="music" data-label="Music bed" ${busAttrs}></hf-audio-group>
<audio id="bgm" src="bgm.mp3" data-start="0" data-duration="10" data-audio-group="music"></audio>
</div>
</body></html>`;
// The observed bug: the bus and its one member each carried a carve against
// the same voiceover, so the bed ran through both sets of filters.
it("warns on a carve written onto a bus", async () => {
const res = await lintHyperframeHtml(
doc(`data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.25}'`),
);
const finding = res.findings.find((f) => f.code === "audio_group_carve_attr");
expect(finding?.severity).toBe("warning");
expect(finding?.elementId).toBe("music");
expect(finding?.message).toContain("data-fx-carve");
});
it("stays quiet on a bus carrying only its own attributes", async () => {
const res = await lintHyperframeHtml(doc(`data-volume="0.4"`));
expect(res.findings.some((f) => f.code === "audio_group_carve_attr")).toBe(false);
});
it("leaves a carve on the clip alone", async () => {
const res = await lintHyperframeHtml(`<!DOCTYPE html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
<hf-audio-group id="music" data-label="Music bed"></hf-audio-group>
<audio id="bgm" src="bgm.mp3" data-start="0" data-duration="10" data-audio-group="music"
data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.25}'></audio>
</div>
</body></html>`);
expect(res.findings.some((f) => f.code === "audio_group_carve_attr")).toBe(false);
});
});
describe("audio_carve_ungrouped_sources", () => {
const withCarve = (carveJson: string, extra = "") => `<!DOCTYPE html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
<audio id="bed" src="bed.wav" data-start="0" data-duration="10" data-fx-carve='${carveJson}'></audio>
${extra}
</div>
</body></html>`;
it("warns when sources names two or more plain clip ids", async () => {
const res = await lintHyperframeHtml(
withCarve(`{"enabled":true,"sources":["vo-1","vo-2"],"strength":0.35}`),
);
const finding = res.findings.find((f) => f.code === "audio_carve_ungrouped_sources");
expect(finding?.severity).toBe("warning");
expect(finding?.elementId).toBe("bed");
});
it("stays quiet when sources names a group", async () => {
const res = await lintHyperframeHtml(
withCarve(
`{"enabled":true,"sources":["voiceover"],"strength":0.35}`,
`<hf-audio-group id="voiceover" data-label="Voiceover"></hf-audio-group>`,
),
);
expect(res.findings.some((f) => f.code === "audio_carve_ungrouped_sources")).toBe(false);
});
it("stays quiet for a single-clip sources list", async () => {
const res = await lintHyperframeHtml(
withCarve(`{"enabled":true,"sources":["narration"],"strength":0.35}`),
);
expect(res.findings.some((f) => f.code === "audio_carve_ungrouped_sources")).toBe(false);
});
it("still warns when one entry is a group and the rest are plain clip ids", async () => {
// Mixing a group with two more bare clip ids is still an ungrouped-source
// rot risk for those two clips — only fully-grouped sources are silent.
const res = await lintHyperframeHtml(
withCarve(
`{"enabled":true,"sources":["voiceover","vo-3","vo-4"],"strength":0.35}`,
`<hf-audio-group id="voiceover" data-label="Voiceover"></hf-audio-group>`,
),
);
const finding = res.findings.find((f) => f.code === "audio_carve_ungrouped_sources");
expect(finding?.severity).toBe("warning");
});
});
describe("media_src_kind_mismatch", () => {
it("errors when <video> src is an image", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="bg" src="still.jpg" data-start="0" data-duration="5" muted></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_src_kind_mismatch");
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("bg");
expect(finding?.message).toContain("image");
});
it("errors when <img> src is a video", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<img id="still" src="clip.mov">
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_src_kind_mismatch");
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("still");
expect(finding?.message).toContain("video");
});
it("errors when <video> src is a data:image URI", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video src="data:image/png;base64,aaaa" data-start="0" muted></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.some((f) => f.code === "media_src_kind_mismatch")).toBe(true);
});
it("does not flag matching video/img src kinds", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" src="clip.mp4" data-start="0" data-duration="5" muted></video>
<img id="i1" src="still.png">
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "media_src_kind_mismatch")).toBeUndefined();
});
it("errors when <img> src is an audio file", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<img id="logo" src="https://cdn.example.com/brand-assets/music/theme.mp3?sig=abc">
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_src_kind_mismatch");
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("logo");
expect(finding?.message).toContain("an audio file");
});
it("errors when <video> src is an audio file", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="bg" src="theme.wav" data-start="0" data-duration="5" muted></video>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "media_src_kind_mismatch");
expect(finding?.severity).toBe("error");
expect(finding?.elementId).toBe("bg");
});
it("does not flag <audio> pointing at a video container", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<audio id="sfx" src="whoosh.mp4" data-start="0"></audio>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "media_src_kind_mismatch")).toBeUndefined();
});
it("does not flag .ogg or .m4a, whose containers can carry video too", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" src="clip.ogg" data-start="0" data-duration="5" muted></video>
<video id="v2" src="clip.m4a" data-start="0" data-duration="5" muted></video>
<img id="i1" src="clip.ogg" data-start="0" data-duration="5" />
<img id="i2" src="clip.m4a" data-start="0" data-duration="5" />
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "media_src_kind_mismatch")).toBeUndefined();
});
it("does not flag extensionless or audio src", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<video id="v1" src="https://images.unsplash.com/photo-1566041510394" data-start="0" muted></video>
<audio id="a1" src="still.jpg" data-start="0"></audio>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "media_src_kind_mismatch")).toBeUndefined();
});
});
describe("speed_ramp_on_non_media", () => {
const RATE = `data-automation='{"version":1,"lanes":[{"target":"rate","points":[{"t":0,"v":1},{"t":2,"v":3}]}]}'`;
const page = (tag: string) => `<!DOCTYPE html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">${tag}</div>
</body></html>`;
it("warns on a rate lane outside video and audio, and stays quiet on a clip", async () => {
const bad = await lintHyperframeHtml(
page(`<img id="pic" src="a.png" data-start="0" data-duration="4" ${RATE}>`),
);
const good = await lintHyperframeHtml(
page(`<video id="v" src="a.mp4" data-start="0" data-duration="4" ${RATE}></video>`),
);
expect(bad.findings.find((f) => f.code === "speed_ramp_on_non_media")?.elementId).toBe("pic");
expect(good.findings.some((f) => f.code === "speed_ramp_on_non_media")).toBe(false);
});
});