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";
function compositionWithBodyPrefix(prefixContent: string, rootContent = ""): string {
return `
<html>
<head>
<style>
body { margin: 0; }
</style>
</head>
<body>
${prefixContent}
<div data-composition-id="c1" data-width="1920" data-height="1080">
${rootContent}
</div>
<script>window.__timelines = {};</script>
</body>
</html>`;
}
/** A portrait root inside a document whose scaffold copies of the resolution
* are supplied by the caller, so they can be aligned or left stale. */
function portraitCompositionWithScaffold(bodyCss: string, viewportContent: string): string {
return `
<html>
<head>
<meta name="viewport" content="${viewportContent}" />
<style>
html, body { ${bodyCss} overflow: hidden; }
</style>
</head>
<body>
<div id="root" data-composition-id="c1" data-width="1080" data-height="1920"></div>
<script>window.__timelines = {};</script>
</body>
</html>`;
}
describe("inline script syntax attribute semantics", () => {
it.each([
["type=module", `import value from "pkg"; await value;`],
['TYPE="module"', `import value from "pkg"; await value;`],
['type=" MODULE "', `import value from "pkg"; await value;`],
['type="module"', `import value from "pkg"; await value;`],
["type=application/json", `{"value":1}`],
["type=importmap", `{"imports":{"pkg":"./pkg.js"}}`],
["type=application/hyperframes-slideshow+json", `{"slides":[]}`],
['type="module" type="text/javascript"', `import value from "pkg"; await value;`],
])("recognizes the exempt script type in %s", async (attrs, content) => {
const result = await lintHyperframeHtml(`<script ${attrs}>${content}</script>`);
expect(result.findings.filter((f) => f.code === "invalid_inline_script_syntax")).toEqual([]);
});
it.each([
'data-type="module"',
'data-src="external.js"',
`data-note='type="module"'`,
`data-note='src="external.js"'`,
`data-note=">" data-src="external.js"`,
'type="text/javascript" type="module"',
'type=""',
])("checks classic inline syntax despite metadata in %s", async (attrs) => {
const result = await lintHyperframeHtml(`<script ${attrs}>const = broken;</script>`);
expect(result.findings.filter((f) => f.code === "invalid_inline_script_syntax")).toHaveLength(
1,
);
});
it.each(['src="external.js"', 'SRC="external.js"', "src"])(
"skips inline text when a real external src attribute is present: %s",
async (attrs) => {
const result = await lintHyperframeHtml(`<script ${attrs}>const = broken;</script>`);
expect(result.findings.filter((f) => f.code === "invalid_inline_script_syntax")).toEqual([]);
},
);
});
describe("core rules", () => {
it("does not invent a composition host from an attribute mentioned in a title", async () => {
const html = `<html><body>
<div id="root" data-composition-id="main" data-no-timeline data-width="640" data-height="360">
<span id="example" title='data-composition-src="ghost.html"'>Example</span>
</div>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.map((finding) => finding.code)).not.toContain(
"host_missing_composition_id",
);
});
it("does not invent timing from attributes mentioned in a title", async () => {
const html = `<html><body>
<div id="root" data-composition-id="main" data-no-timeline data-width="640" data-height="360">
<span id="example" title='data-start="0" data-duration="1"'>Example</span>
</div>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.map((finding) => finding.code)).not.toContain(
"timed_element_missing_clip_class",
);
});
it("does not lint scripts embedded inside an iframe srcdoc attribute", async () => {
const html = `
<html><body>
<div data-composition-id="root" data-width="1280" data-height="720"></div>
<iframe srcdoc="<script>const child = gsap.timeline({ paused: true }); child.to("#x", { opacity: 1 });</script>"></iframe>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const rootTl = gsap.timeline({ paused: true });
window.__timelines["root"] = rootTl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((finding) => finding.code === "invalid_inline_script_syntax"),
).toBeUndefined();
expect(
result.findings.find((finding) => finding.code === "gsap_timeline_not_registered"),
).toBeUndefined();
});
it("does not lint elements embedded inside an iframe srcdoc attribute", async () => {
const html = `
<html><body>
<div data-composition-id="root" data-width="1280" data-height="720"></div>
<iframe srcdoc='<video src="child.mp4" data-start="0"></video>'></iframe>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find(
(finding) => finding.elementId === undefined && finding.message.includes("<video"),
),
).toBeUndefined();
});
it.each([
["no selector uses it", "", "", "warning"],
["a CSS rule targets it", "#123-frame { opacity: 0; }", "", "error"],
["a GSAP string targets it", "", 'gsap.to("#123-frame", { x: 1 });', "error"],
["querySelector targets it", "", 'document.querySelector(".a #123-frame");', "error"],
["gsap.utils.toArray targets it", "", 'gsap.utils.toArray("#123-frame");', "error"],
[
"a scrollTrigger trigger targets it",
"",
'gsap.to(".box", { x: 10, scrollTrigger: { trigger: "#123-frame" } });',
"error",
],
[
"ScrollTrigger.create triggers on it",
"",
'ScrollTrigger.create({ trigger: "#123-frame", pin: true });',
"error",
],
[
"a ScrollTrigger pin targets it",
"",
'ScrollTrigger.create({ trigger: ".a", pin: "#123-frame" });',
"error",
],
[
"a ScrollTrigger endTrigger targets it",
"",
'ScrollTrigger.create({ trigger: ".a", endTrigger: "#123-frame" });',
"error",
],
[
"the scrollTrigger shorthand targets it",
"",
'gsap.to(".box", { scrollTrigger: "#123-frame" });',
"error",
],
[
"a ScrollTrigger scroller targets it",
"",
'ScrollTrigger.create({ trigger: ".a", scroller: "#123-frame" });',
"error",
],
[
"a ScrollTrigger pinnedContainer targets it",
"",
'ScrollTrigger.create({ trigger: ".a", pinnedContainer: "#123-frame" });',
"error",
],
[
"a ScrollTrigger pinSpacer targets it",
"",
'ScrollTrigger.create({ trigger: ".a", pinSpacer: "#123-frame" });',
"error",
],
[
"a quoted ScrollTrigger key targets it",
"",
'ScrollTrigger.create({ "trigger": "#123-frame" });',
"error",
],
[
"a $-prefixed key ending in pin holds it",
"",
'const meta = { $pin: "#123-frame" };',
"warning",
],
["a key ending in pin holds it", "", 'const meta = { spin: "#123-frame" };', "warning"],
["a non-selector key holds it", "", 'const meta = { label: "#123-frame" };', "warning"],
[
"a hyphenated key ending in pin holds it",
"",
'const meta = { "data-pin": "#123-frame" };',
"warning",
],
["only url(#id) references it", ".a { mask: url(#123-frame); }", "", "warning"],
["only a longer id is selected", "#123-frame-2 { opacity: 0; }", "", "warning"],
["getElementById looks it up", "", 'document.getElementById("123-frame");', "warning"],
["the CSS selector is escaped", "#\\31 23-frame { opacity: 0; }", "", "warning"],
[
"the script selector is escaped",
"",
'document.querySelector("#\\\\31 23-frame");',
"warning",
],
[
"CSS.escape builds the selector",
"",
'document.querySelector(`#${CSS.escape("123-frame")}`);',
"warning",
],
])("rates a digit-leading id by selector use: %s", async (_case, css, js, severity) => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080">
<style>${css}</style>
<div id="123-frame"></div>
</div>
<script>window.__timelines = {}; ${js}</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((item) => item.code === "id_requires_css_escape");
expect(finding?.severity).toBe(severity);
expect(finding?.elementId).toBe("123-frame");
expect(finding?.fixHint).toContain("CSS.escape");
});
it("accepts ids that start with a letter", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080">
<div id="frame-123"></div>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((item) => item.code === "id_requires_css_escape")).toBeUndefined();
});
it("reports error when root is missing data-composition-id", async () => {
const html = `
<html><body>
<div id="root" data-width="1920" data-height="1080"></div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "root_missing_composition_id");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
});
it("reports error when root is missing data-width or data-height", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1"></div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "root_missing_dimensions");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
});
it("reports root_dimensions_mismatch when html/body CSS and the viewport meta are still the scaffolded landscape size", async () => {
// GH#4001: the root is edited to portrait without `hyperframes init
// --resolution`, the only thing that otherwise keeps the scaffold's copies
// of the resolution in sync. The stale landscape body (overflow: hidden)
// then clips the correctly-sized root at its old height.
const html = portraitCompositionWithScaffold(
"width: 1920px; height: 1080px;",
"width=1920, height=1080",
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "root_dimensions_mismatch");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("warning");
expect(finding?.message).toContain("html/body CSS is 1920x1080");
expect(finding?.message).toContain("the viewport meta is 1920x1080");
});
it("reads a stale html/body size authored height-before-width", async () => {
const html = portraitCompositionWithScaffold(
"height: 1080px; width: 1920px;",
"width=1080, height=1920",
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "root_dimensions_mismatch");
expect(finding?.message).toContain("html/body CSS is 1920x1080");
expect(finding?.message).not.toContain("viewport");
});
it("does not report root_dimensions_mismatch when the scaffold agrees with the root", async () => {
const html = portraitCompositionWithScaffold(
"width: 1080px; height: 1920px;",
"width=1080, height=1920",
);
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "root_dimensions_mismatch")).toBeUndefined();
});
it("does not report root_dimensions_mismatch for a sub-composition fragment with no html/body/viewport to compare", async () => {
const html = `<div data-composition-id="c1" data-width="1080" data-height="1920"></div>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "root_dimensions_mismatch")).toBeUndefined();
});
it("does not report root_dimensions_mismatch for a full sub-composition document whose own viewport meta disagrees with its root", async () => {
// Matches the hf2550 flowchart-vertical fixture's shape: a full standalone
// document mounted as a sub-composition. See the rule's comment in core.ts
// for why its own <meta viewport> never reaches the rendering document.
const html = `
<!doctype html>
<html>
<head>
<meta name="viewport" content="width=1440, height=2560" />
</head>
<body>
<div id="root" data-composition-id="c1" data-width="1080" data-height="1920"></div>
<script>window.__timelines = {};</script>
</body>
</html>`;
const result = await lintHyperframeHtml(html, { isSubComposition: true });
expect(result.findings.find((f) => f.code === "root_dimensions_mismatch")).toBeUndefined();
});
it("still reports root_dimensions_mismatch for the same shape linted as a top-level composition, with no-clipping-risk wording since there is no html/body CSS block at all", async () => {
const html = `
<!doctype html>
<html>
<head>
<meta name="viewport" content="width=1440, height=2560" />
</head>
<body>
<div id="root" data-composition-id="c1" data-width="1080" data-height="1920"></div>
<script>window.__timelines = {};</script>
</body>
</html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "root_dimensions_mismatch");
expect(finding).toBeDefined();
// No html/body CSS block is present here at all (the real hf2550 fixture
// shape) -- distinct from the "present and matching" case covered below --
// so the "absent" and "matches" cases of describeSizeMismatch must both
// route to the same no-clipping-risk wording, not just the "matches" one.
expect(finding?.message).not.toContain("clips");
expect(finding?.message.toLowerCase()).toContain("no effect on capture");
});
it("uses no-clipping-risk wording when only the viewport meta disagrees and html/body CSS matches the root", async () => {
const html = portraitCompositionWithScaffold(
"width: 1080px; height: 1920px;",
"width=1440, height=2560",
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "root_dimensions_mismatch");
expect(finding).toBeDefined();
expect(finding?.message).toContain("the viewport meta is 1440x2560");
expect(finding?.message).not.toContain("clips");
expect(finding?.message.toLowerCase()).toContain("no effect on capture");
});
it("keeps the body-clipping wording when html/body CSS itself disagrees with the root", async () => {
const html = portraitCompositionWithScaffold(
"width: 1920px; height: 1080px;",
"width=1080, height=1920",
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "root_dimensions_mismatch");
expect(finding?.message).toContain("clips");
});
it("accepts body as the composition root", async () => {
const html = `
<html><body data-composition-id="c1" data-width="1920" data-height="1080">
<div id="overlay-flash"></div>
<script>window.__timelines = window.__timelines || {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
});
it("skips a leading <svg> defs block when detecting the composition root", async () => {
// Regression: two independent reports of a leading <svg><defs><filter>...
// block (icon/gradient/filter plumbing referenced via url(#id) elsewhere)
// getting mistaken for the composition root, since findRootTag returned
// the first non-script/style/meta/link/title body child unconditionally.
// The <svg> here carries no composition markers, so it must be skipped in
// favor of the real root that follows it.
const html = `
<html><body>
<svg width="0" height="0" style="position:absolute">
<defs><filter id="glow"><feGaussianBlur stdDeviation="4" /></filter></defs>
</svg>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>window.__timelines = window.__timelines || {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
});
it("does not ask a sub-composition for its own size: a mounted one fills its host", async () => {
const html = `<template id="scene-template">
<div id="scene" data-composition-id="scene"><p>Hi</p></div>
</template>`;
const result = await lintHyperframeHtml(html, { isSubComposition: true });
expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
});
it("finds a sub-composition's root inside <template> when <html> carries its variables", async () => {
const html = `<html lang="en" data-composition-variables='[{"id":"title","type":"string","label":"Title","default":"Hi"}]'>
<template id="scene-template">
<div id="scene" data-composition-id="scene" data-width="1280" data-height="720"></div>
</template>
</html>`;
const result = await lintHyperframeHtml(html, { isSubComposition: true });
expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
});
it("still treats an <svg> as the root when it carries composition markers itself", async () => {
const html = `
<html><body>
<svg id="root" data-composition-id="c1" data-width="1920" data-height="1080"></svg>
<script>window.__timelines = window.__timelines || {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
});
it("does not mistake a <tag>-shaped CSS comment inside <style> for the composition root", async () => {
// Regression: a CSS comment referencing an SVG tag name (e.g. `/* <g> wrapper */`)
// inside a <style> block reads as a real open tag to the flat TAG_PATTERN scan,
// manufacturing a phantom root before the real composition root and firing
// root_missing_composition_id/root_missing_dimensions on an
// otherwise valid sub-composition.
const html = `
<html><body>
<style>
/* <g> wrapper for icon groups */
.icon { fill: currentColor; }
</style>
<svg id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<g class="icon"></g>
</svg>
<script>window.__timelines = window.__timelines || {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
});
it("reports error when timeline registry is missing", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
const tl = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "missing_timeline_registry");
expect(finding).toBeDefined();
});
it("allows a timeline-free root that explicitly declares data-no-timeline", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-no-timeline data-width="1920" data-height="1080" data-duration="5"></div>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "missing_timeline_registry")).toBeUndefined();
});
it("does not flag missing_timeline_registry on a sub-composition (inherits from host)", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
const tl = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = await lintHyperframeHtml(html, { isSubComposition: true });
const finding = result.findings.find((f) => f.code === "missing_timeline_registry");
expect(finding).toBeUndefined();
});
it("reports error for composition host missing data-composition-id", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="host1" data-composition-src="child.html"></div>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "host_missing_composition_id");
expect(finding).toBeDefined();
});
// The runtime creates `window.__timelines` at script-evaluation time
// (runtime/entry.ts), before any inline composition script runs, so a bare
// assignment needs no `window.__timelines = window.__timelines || {}` guard.
// Verified by rendering a composition whose only registration is the bare
// assignment: it renders and animates correctly. The old
// `timeline_registry_missing_init` error therefore failed a working file, and
// because a lint ERROR also suppresses the layout and contrast audits in
// `check`, it cost far more than the line it asked for.
it("accepts a bracket registry assignment with no init guard", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="stage"></div>
</div>
<script>
const tl = gsap.timeline({ paused: true });
tl.to("#stage", { opacity: 1, duration: 1 }, 0);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "timeline_registry_missing_init"),
).toBeUndefined();
expect(result.findings.find((f) => f.code === "missing_timeline_registry")).toBeUndefined();
});
it("accepts a dot registry assignment with no init guard", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="stage"></div>
</div>
<script>
const tl = gsap.timeline({ paused: true });
tl.to("#stage", { opacity: 1, duration: 1 }, 0);
window.__timelines.c1 = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "timeline_registry_missing_init"),
).toBeUndefined();
expect(result.findings.find((f) => f.code === "missing_timeline_registry")).toBeUndefined();
});
it("does not flag timeline assignment when init guard is present", async () => {
const validComposition = `
<html>
<body>
<div id="root" data-composition-id="comp-1" data-width="1920" data-height="1080">
<div id="stage"></div>
</div>
<script src="https://cdn.gsap.com/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to("#stage", { opacity: 1, duration: 1 }, 0);
window.__timelines["comp-1"] = tl;
</script>
</body>
</html>`;
const result = await lintHyperframeHtml(validComposition);
const finding = result.findings.find((f) => f.code === "timeline_registry_missing_init");
expect(finding).toBeUndefined();
});
it("reports error when an extra style closer dumps CSS as text", async () => {
const html = compositionWithBodyPrefix(
"",
`
<style>
.editorial-block { color: #fff; }
</style>
</style>
.leftover { color: red; }
<div class="editorial-block">Hello</div>
`,
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "unbalanced_style_tags");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("extra </style>");
});
it("does not count style text inside a script closed with a spaced end tag", async () => {
const html = compositionWithBodyPrefix(
"",
`
<style>
.editorial-block { color: #fff; }
</style>
<script>
const marker = "</style>";
</script >
<div class="editorial-block">Hello</div>
`,
);
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "unbalanced_style_tags")).toBeUndefined();
});
it("reports an extra closer written as </style >", async () => {
const html = compositionWithBodyPrefix(
"",
`
<style>
.editorial-block { color: #fff; }
</style >
</style >
.leftover { color: red; }
<div class="editorial-block">Hello</div>
`,
);
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "unbalanced_style_tags")?.severity).toBe("error");
});
it("does not count a closer that only appears inside an html comment", async () => {
const html = compositionWithBodyPrefix(
"",
`
<style>
.editorial-block { color: #fff; }
</style>
<!-- dropped the second sheet: </style> -->
<div class="editorial-block">Hello</div>
`,
);
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "unbalanced_style_tags")).toBeUndefined();
});
it("does not report paired style blocks", async () => {
const html = compositionWithBodyPrefix("", `<div class="editorial-block">Hello</div>`);
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "unbalanced_style_tags")).toBeUndefined();
});
it("reports error when CSS block comment syntax leaks into visible markup", async () => {
const html = compositionWithBodyPrefix(
"",
`
/* Main Content Block */
<div class="editorial-block">Hello</div>
`,
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "visible_markup_comment");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("visible HTML markup");
expect(finding?.snippet).toContain("Main Content Block");
});
it("reports error when a misbalanced style block leaves block comment syntax visible", async () => {
const html = compositionWithBodyPrefix(
"",
`
<style>
.editorial-block { color: #fff; }
</style>
</style>
/* Main Content Block */
<div class="editorial-block">Hello</div>
`,
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "visible_markup_comment");
expect(finding).toBeDefined();
expect(finding?.snippet).toContain("Main Content Block");
});
it("does not report block comments inside style or script blocks", async () => {
const html = `
<html>
<head>
<title>/* tab name */ Particle Field</title>
<style>
/* Layout reset */
body { margin: 0; }
</style>
<noscript>/* fallback note */</noscript>
</head>
<body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
/* Timeline registry */
window.__timelines = {};
</script>
</body>
</html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "visible_markup_comment");
expect(finding).toBeUndefined();
});
it("does not report block comments in attributes, html comments, or protected text contexts", async () => {
const html = compositionWithBodyPrefix(
"",
`
<!-- /* hidden implementation note */ -->
<div data-note="/* attribute note */"></div>
<div data-note="a > b /* quoted attribute note */"></div>
<pre>/* visible code sample */</pre>
<code>/* visible inline code sample */</code>
<textarea>/* editable code sample */</textarea>
<template>/* template-only note */</template>
<svg viewBox="0 0 100 20"><text x="0" y="15">/* svg label */</text></svg>
`,
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "visible_markup_comment");
expect(finding).toBeUndefined();
});
describe("timeline_id_mismatch", () => {
it("accepts dot timeline registration", async () => {
const html = `
<html><body>
<div data-composition-id="launch" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
window.__timelines.launch = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
expect(finding).toBeUndefined();
});
it("reports mismatched dot timeline registration", async () => {
const html = `
<html><body>
<div data-composition-id="launch" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
window.__timelines.intro = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
expect(finding).toBeDefined();
expect(finding?.message).toContain('Timeline registered as "intro"');
});
it("accepts bracket timeline registration for hyphenated ids", async () => {
const html = `
<html><body>
<div data-composition-id="product-launch" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
window.__timelines["product-launch"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
expect(finding).toBeUndefined();
});
it("matches timeline keys against browser-decoded composition ids", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "timeline_id_mismatch")).toBeUndefined();
});
it("accepts object-literal timeline registration and extracts its keys", async () => {
const html = `
<html><body>
<div data-composition-id="comp-1" data-width="1920" data-height="1080"></div>
<script>
const tl = gsap.timeline({ paused: true });
window.__timelines = { "comp-1": tl };
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "missing_timeline_registry")).toBeUndefined();
expect(
result.findings.find((f) => f.code === "timeline_registry_missing_init"),
).toBeUndefined();
expect(result.findings.find((f) => f.code === "timeline_id_mismatch")).toBeUndefined();
});
it("reports mismatched object-literal timeline registration keys", async () => {
const html = `
<html><body>
<div data-composition-id="comp-1" data-width="1920" data-height="1080"></div>
<script>
const tl = gsap.timeline({ paused: true });
window.__timelines = { main: tl };
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
expect(finding).toBeDefined();
expect(finding?.message).toContain('Timeline registered as "main"');
});
});
describe("repeated_id_descendant_selector", () => {
it("reports a selector that nests the same id inside itself", async () => {
const html = `<div id="scene_01" data-composition-id="root" data-width="1920" data-height="1080">
<style>#scene_01 #scene_01 .headline { color: red; }</style>
</div>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "repeated_id_descendant_selector");
expect(finding?.severity).toBe("error");
expect(finding?.selector).toBe("#scene_01 #scene_01 .headline");
});
it("does not report distinct descendant ids", async () => {
const html = `<div id="scene_01" data-composition-id="root" data-width="1920" data-height="1080">
<style>#scene_01 #headline { color: red; }</style>
</div>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "repeated_id_descendant_selector"),
).toBeUndefined();
});
it.each(["#scene_01 > #scene_01", "#scene_01 .wrapper #scene_01"])(
"reports repeated ids across descendant combinators: %s",
async (selector) => {
const html = `<div data-composition-id="root" data-width="1920" data-height="1080">
<style>${selector} { color: red; }</style>
</div>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "repeated_id_descendant_selector"),
).toBeDefined();
},
);
it.each([
":is(#scene_01) #scene_01",
":where(#scene_01) #scene_01",
"#scene_01 :is(#scene_01)",
])("reports repeated ids required by selector pseudos: %s", async (selector) => {
const html = `<div data-composition-id="root" data-width="1920" data-height="1080">
<style>${selector} { color: red; }</style>
</div>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "repeated_id_descendant_selector"),
).toBeDefined();
});
it.each([
":is(#scene_01, .scene) #scene_01",
":not(#scene_01) #scene_01",
":has(#scene_01) #scene_01",
])("does not report ids that are not required by a selector pseudo: %s", async (selector) => {
const html = `<div data-composition-id="root" data-width="1920" data-height="1080">
<style>${selector} { color: red; }</style>
</div>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "repeated_id_descendant_selector"),
).toBeUndefined();
});
it.each(["& #scene_01 .headline", "#scene_01 .headline"])(
"reports repeated ids created by nested CSS: %s",
async (nestedSelector) => {
const html = `<div data-composition-id="root" data-width="1920" data-height="1080">
<style>#scene_01 { ${nestedSelector} { color: red; } }</style>
</div>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find(
(candidate) => candidate.code === "repeated_id_descendant_selector",
);
expect(finding).toBeDefined();
expect(finding?.selector).toContain("#scene_01 #scene_01");
},
);
it("preserves dollar sequences while resolving nested selectors", async () => {
const html = `<div data-composition-id="root" data-width="1920" data-height="1080">
<style>#scene_01[data-query="$1"] { & #scene_01 { color: red; } }</style>
</div>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find(
(candidate) => candidate.code === "repeated_id_descendant_selector",
);
expect(finding?.selector).toBe('#scene_01[data-query="$1"] #scene_01');
});
it.each(['[data-query="#scene_01 #scene_01"]', String.raw`#scene_01 #scene_01\:child`])(
"does not report non-repeated parsed ids: %s",
async (selector) => {
const html = `<div data-composition-id="root" data-width="1920" data-height="1080">
<style>${selector} { color: red; }</style>
</div>`;
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "repeated_id_descendant_selector"),
).toBeUndefined();
},
);
});
it("warns when a timeline-visible element has no stable id for Studio editing", async () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<section class="clip hero-card" data-start="0" data-duration="3"></section>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "studio_missing_editable_id");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("warning");
expect(finding?.message).toContain('<section class="hero-card" data-start="0">');
expect(finding?.fixHint).toContain("stable, human-readable id");
});
it("does not warn about the composition root or timeline elements with ids", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0">
<section id="hero-card" class="clip hero-card" data-start="0" data-duration="3"></section>
</div>
<script>window.__timelines = {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "studio_missing_editable_id");
expect(finding).toBeUndefined();
});
describe("css_transition_used", () => {
it.each([
["transition", "opacity 0.5s ease"],
["transition-duration", "0.5s"],
["transition-delay", "100ms"],
["transition-property", "opacity"],
["-webkit-transition", "opacity 0.5s ease"],
["-webkit-transition-duration", "0.5s"],
["transition", "opacity 0s linear 1s"],
["transition-duration", "0s, .2s"],
["transition-duration", "var(--speed)"],
])("warns for %s declarations in style blocks", async (property, value) => {
const result = await lintHyperframeHtml(
compositionWithBodyPrefix(`<style>.card { ${property}: ${value}; }</style>`),
);
const finding = result.findings.find((item) => item.code === "css_transition_used");
expect(finding).toMatchObject({ severity: "warning", selector: ".card" });
expect(finding?.message).toContain(property);
expect(finding?.fixHint).toContain("paused GSAP timeline");
});
it("warns for an inline transition and identifies its element", async () => {
const result = await lintHyperframeHtml(
compositionWithBodyPrefix(
"",
'<div id="card" style="transition: opacity 0.5s ease"></div>',
),
);
const finding = result.findings.find((item) => item.code === "css_transition_used");
expect(finding).toMatchObject({ severity: "warning", elementId: "card" });
expect(finding?.snippet).toContain('id="card"');
});
it.each([
["transition", "none"],
["transition-property", "none"],
["-webkit-transition", "none"],
["-webkit-transition-property", "NONE"],
["transition-duration", "0s"],
["transition-delay", "0ms, 0s"],
["-webkit-transition-duration", "0s"],
["transition", "opacity 0s ease 0s"],
])("allows %s: %s", async (property, value) => {
const result = await lintHyperframeHtml(
compositionWithBodyPrefix(`<style>.card { ${property}: ${value} !important; }</style>`),
);
expect(result.findings.find((item) => item.code === "css_transition_used")).toBeUndefined();
});
it("ignores custom properties that contain transition in their name", async () => {
const result = await lintHyperframeHtml(
compositionWithBodyPrefix(
'<div id="card" style="--transition-speed: 0.5s"></div>',
"<style>.card { --transition-easing: ease; opacity: 1; }</style>",
),
);
expect(result.findings.find((item) => item.code === "css_transition_used")).toBeUndefined();
});
});
describe("non_deterministic_code", () => {
it("gives randomness guidance for crypto and clock guidance for wall time", async () => {
const result = await lintHyperframeHtml(`<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
crypto.getRandomValues(new Uint32Array(1));
Date.now();
window.__timelines = { c1: gsap.timeline({ paused: true }) };
</script>
</body></html>`);
const crypto = result.findings.find((finding) =>
finding.message.includes("crypto.getRandomValues"),
);
const clock = result.findings.find((finding) => finding.message.includes("Date.now"));
expect(crypto).toMatchObject({ code: "non_deterministic_code", severity: "error" });
expect(crypto?.fixHint).toContain("seeded PRNG");
expect(crypto?.fixHint).not.toContain("time-dependent");
expect(clock?.fixHint).toContain("wall-clock time");
});
it("detects Math.random() in script content", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const x = Math.random();
window.__timelines["c1"] = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("Math.random");
});
it("detects Date.now() in script content", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const ts = Date.now();
window.__timelines["c1"] = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("Date.now");
});
it("does not flag non-deterministic calls inside single-line comments", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
// const x = Math.random();
// Date.now() is not used here
window.__timelines["c1"] = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
expect(finding).toBeUndefined();
});
it("detects gsap.utils.random() in script content", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to(".chip", { x: gsap.utils.random(-100, 100), duration: 1 }, 0);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("gsap.utils.random");
});
it("detects GSAP 'random(...)' string tween values", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to(".chip", { x: "random(-100, 100)", duration: 1 }, 0);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
expect(finding).toBeDefined();
expect(finding?.message).toContain('"random(...)"');
});
it("detects prefixed '+=random(...)' string tween values", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to(".chip", { x: "+=random(-10, 10)", duration: 1 }, 0);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
expect(finding).toBeDefined();
});
it("does NOT flag prose strings that merely mention random(", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const note = "avoid random(seed) helpers in render code";
window.__timelines["c1"] = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
expect(finding).toBeUndefined();
});
});
describe("non_deterministic_code — determinism is about execution, not text", () => {
const comp = (script: string) => `
<html><body>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="5"></div>
<script src="gsap.min.js"></script>
<script>const tl = gsap.timeline({ paused: true }); ${script} window.__timelines = { main: tl };</script>
</body></html>`;
it("does not flag new Date() with a fixed timestamp", async () => {
// Deterministic, and the fixHint ("remove time-dependent code") cannot be
// applied without deleting the label the composition renders.
const result = await lintHyperframeHtml(
comp(`const label = new Date("2026-01-01T00:00:00Z").toISOString();`),
);
expect(result.findings.find((f) => f.code === "non_deterministic_code")).toBeUndefined();
});
it("does not flag non-deterministic APIs quoted inside a string literal", async () => {
// Code-display compositions render source they never execute.
const result = await lintHyperframeHtml(comp(`const SNIPPET = "const x = Math.random();";`));
expect(result.findings.find((f) => f.code === "non_deterministic_code")).toBeUndefined();
});
it("still flags a bare new Date()", async () => {
const result = await lintHyperframeHtml(comp(`const now = new Date();`));
expect(result.findings.find((f) => f.code === "non_deterministic_code")).toBeDefined();
});
it("still flags Math.random() in executed code", async () => {
const result = await lintHyperframeHtml(comp(`const r = Math.random();`));
expect(result.findings.find((f) => f.code === "non_deterministic_code")).toBeDefined();
});
});
describe("non_deterministic_code — inlined GSAP library", () => {
// UMD wrapper, banner and internals excerpted from [email protected] dist/gsap.min.js.
const banner = "/*! GSAP 3.14.2 | @license Copyright 2025, GreenSock. All rights reserved. */";
const gsapUmd =
'!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports):' +
'"function"==typeof define&&define.amd?define(["exports"],e):e((t=t||self).window=t.window||{})}' +
'(this,function(e){"use strict";function gb(t){return t.sort(function(){return.5-Math.random()})}' +
"function Ic(){var t=Date.now(),o=[];return o}});";
const pastedGsap = `${banner}\n${gsapUmd}`;
const producerInlinedGsap = `/* inlined: https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js */\n${gsapUmd}`;
// Unminified builds carry the banner inside the factory.
const unminifiedGsap = gsapUmd.replace('"use strict";', `"use strict";${banner}`);
const inlinedUnminifiedGsap = `/* inlined: https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.js */\n(${unminifiedGsap.slice(1, -1)});`;
const separatedGsap = `${banner};${gsapUmd}`;
const umdBundle = (body: string) =>
`(function (root, factory) {\nif (typeof define === "function" && define.amd) define([], factory); else factory();\n})(this, function () {\n${body}\n});`;
// Rollup 4 `--format umd` output for `import { gsap } from "gsap"` plus author code, excerpted.
const rollupBundle = `(function (global, factory) {
typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
typeof define === 'function' && define.amd ? define(['exports'], factory) :
(global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.Composition = {}));
})(this, (function (exports) { 'use strict';
${banner}
var _config = {
autoSleep: 120,
force3D: "auto",
nullTargetWarn: 1,
units: {
lineHeight: ""
}
};
window.authorSeed = Math.random();
window.authorTime = Date.now();
exports.gsap = gsapWithCSS;
}));`;
// The same import through Rollup UMD plus Terser, excerpted: the banner stays inside the factory.
const minifiedRollupBundle = `!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports):"function"==typeof define&&define.amd?define(["exports"],e):e((t="undefined"!=typeof globalThis?globalThis:t||self).Composition={})}(this,function(t){"use strict";function r(t,e){t.prototype=Object.create(e.prototype),t.prototype.constructor=t,t.__proto__=e}\n${banner}\nvar Ji=Ar.registerPlugin($i)||Ar;Ji.core.Tween,window.authorSeed=Math.random(),window.authorTime=Date.now(),t.gsap=Ji});`;
const comp = (library: string, author = "") => `
<html><body>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="5"></div>
<script>${library}</script>
<script>const tl = gsap.timeline({ paused: true }); ${author} window.__timelines = { main: tl };</script>
</body></html>`;
const labels = async (html: string) =>
(await lintHyperframeHtml(html)).findings
.filter((f) => f.code === "non_deterministic_code")
.map((f) => f.message.match(/`(.+?)`/)?.[1]);
it.each([
["pasted with its banner", pastedGsap],
["inlined by the producer", producerInlinedGsap],
["unminified and inlined by the producer", inlinedUnminifiedGsap],
[
"inlined by the producer from an unversioned dist URL with a query and hash",
inlinedUnminifiedGsap.replace(
"https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.js",
"https://unpkg.com/gsap/dist/gsap.js?module#top",
),
],
["after a statement separator", separatedGsap],
])("does not flag GSAP's own internals when %s", async (_shape, library) => {
expect(await labels(comp(library))).toEqual([]);
});
it("still flags the author's Math.random() in a script next to inlined GSAP", async () => {
expect(await labels(comp(pastedGsap, "const r = Math.random();"))).toEqual(["Math.random()"]);
});
it("still flags author calls before and after GSAP in the same script", async () => {
const library = `const a = Math.random();\n${pastedGsap}\nconst b = performance.now();`;
expect(await labels(comp(library))).toEqual(["Math.random()", "performance.now()"]);
});
it("checks an outer wrapper that only borrows define.amd from a nested library", async () => {
const library = `(function (root, factory) {\n${banner}\nwindow.seed = Math.random();\n${gsapUmd}\n})(this, function () {});`;
expect(await labels(comp(library))).toEqual(["Math.random()", "Date.now()"]);
});
it("checks a UMD wrapper whose GSAP banner is separated from it by other code", async () => {
expect(await labels(comp(`${banner}\nwindow.x = 1;\n${gsapUmd}`))).toEqual([
"Math.random()",
"Date.now()",
]);
});
it.each([
[
"joined to it with a comma",
`${banner}\n${gsapUmd.slice(0, -1)}, window.seed = Math.random();`,
],
[
"beside it inside an outer wrapper",
`(function () {\n${pastedGsap}\nwindow.seed = Math.random();\n})();`,
],
[
"beside it inside an outer two-argument wrapper",
`(function (root, factory) {\n${pastedGsap}\nwindow.seed = Math.random();\n})(this, function () {});`,
],
[
"beside it inside an outer UMD bundle",
umdBundle(`${pastedGsap}\nwindow.seed = Math.random();`),
],
[
"beside producer-inlined unminified GSAP inside an outer UMD bundle",
umdBundle(`${inlinedUnminifiedGsap}\nwindow.seed = Math.random();`),
],
[
"beside separated GSAP inside an outer UMD bundle",
umdBundle(`${separatedGsap}\nwindow.seed = Math.random();`),
],
[
"beside a stray banner inside an outer UMD bundle",
umdBundle(`${banner}\nwindow.seed = Math.random();\n${pastedGsap}`),
],
])("still flags author code %s", async (_shape, library) => {
expect(await labels(comp(library))).toEqual(["Math.random()"]);
});
it("flags author code that Rollup bundles into one factory with GSAP's banner", async () => {
expect(await labels(comp(rollupBundle))).toEqual(["Math.random()", "Date.now()"]);
});
it.each([
"gsap-composition.js",
"composition.js",
"scene.js?vendor=gsap",
"https://example.com/gsap-demo/scene.js",
])("flags author code in a minified bundle inlined from %s", async (src) => {
const library = `/* inlined: ${src} */\n${minifiedRollupBundle}`;
expect(await labels(comp(library))).toEqual(["Math.random()", "Date.now()"]);
});
// Known limit: a banner inside a factory cannot be told apart from a bundled one, so it exempts nothing.
it.each([
["pasted unminified GSAP", unminifiedGsap],
[
"unminified GSAP beside author code in an outer UMD bundle",
umdBundle(`${unminifiedGsap}\nwindow.seed = Math.random();`),
],
])("checks %s, whose banner sits inside its factory", async (_shape, library) => {
expect(await labels(comp(library))).toEqual(["Math.random()", "Date.now()"]);
});
it.each([
["a string", `const label = "GreenSock"; const x = Math.random();`],
["a comment", `// eased like GreenSock\nconst x = Math.random();`],
["a spoofed banner", `${banner}\nwindow.seed = Math.random();`],
["a spoofed inlining comment", `/* inlined: gsap.min.js */\nwindow.seed = Math.random();`],
[
"a banner plus define.amd in a string",
`${banner}\nwindow.seed = ("define.amd", Math.random());`,
],
[
"a banner plus define.amd in a comment",
`${banner}\nwindow.seed = /* define.amd */ Math.random();`,
],
])("still flags author code whose script mentions GSAP in %s", async (_where, author) => {
expect(await labels(comp("", author))).toEqual(["Math.random()"]);
});
});
describe("timeline_id_mismatch — only top-level registry keys are composition ids", () => {
const comp = (script: string) => `
<html><body>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="5"></div>
<script src="gsap.min.js"></script>
<script>${script}</script>
</body></html>`;
it("does not flag the one-liner registration form", async () => {
// The inlined options object is not a registration. Reading `paused` as a
// composition id produced an error whose fixHint named a registration that
// did not exist, so it could never be applied.
const result = await lintHyperframeHtml(
comp(`window.__timelines = { main: gsap.timeline({ paused: true }) };`),
);
expect(result.findings.find((f) => f.code === "timeline_id_mismatch")).toBeUndefined();
});
it("still flags a genuinely mismatched id", async () => {
const result = await lintHyperframeHtml(
comp(`window.__timelines = { wrongid: gsap.timeline({ paused: true }) };`),
);
expect(result.findings.find((f) => f.code === "timeline_id_mismatch")).toBeDefined();
});
});
describe("runtime_hidden_style_opacity", () => {
const comp = (css: string, extraMarkup = "") => `
<html><head><style>${css}</style></head><body>
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<video id="footage" src="clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
${extraMarkup}
</div>
<script>window.__timelines = { main: gsap.timeline({ paused: true }) };</script>
</body></html>`;
it("errors when a broad hidden-style selector forces replacement-frame opacity to zero", async () => {
const result = await lintHyperframeHtml(
comp(`[style*="visibility: hidden"] { opacity: 0 !important; }`),
);
const finding = result.findings.find((item) => item.code === "runtime_hidden_style_opacity");
expect(finding?.severity).toBe("error");
expect(finding?.selector).toBe(`[style*="visibility: hidden"]`);
expect(finding?.message).toContain("replacement frame");
expect(finding?.fixHint).toContain("data-composition-src");
});
it("errors when composition scoping still leaves the hidden-style selector on video", async () => {
const result = await lintHyperframeHtml(
comp(`#root > video[style*="visibility: hidden"] { opacity: 0; }`),
);
expect(
result.findings.find((item) => item.code === "runtime_hidden_style_opacity")?.selector,
).toBe(`#root > video[style*="visibility: hidden"]`);
});
it("errors when the root stylesheet can affect video mounted from a sub-composition", async () => {
const result = await lintHyperframeHtml(`
<html><head><style>[style*="visibility: hidden"] { opacity: 0; }</style></head><body>
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<div data-composition-id="scene" data-composition-src="scene.html"></div>
</div>
<script>window.__timelines = { main: gsap.timeline({ paused: true }) };</script>
</body></html>`);
expect(
result.findings.find((item) => item.code === "runtime_hidden_style_opacity")?.severity,
).toBe("error");
});
it("allows hidden-style opacity guards scoped to sub-composition hosts", async () => {
const result = await lintHyperframeHtml(
comp(
`[data-composition-src][style*="visibility: hidden"],
[data-composition-file][style*="visibility: hidden"] { opacity: 0 !important; }`,
`<div data-composition-id="scene-a" data-composition-src="scene-a.html"></div>
<div data-composition-id="scene-b" data-composition-file="scene-b.html"></div>`,
),
);
expect(
result.findings.find((item) => item.code === "runtime_hidden_style_opacity"),
).toBeUndefined();
});
it("allows broad hidden-style selectors that do not change opacity", async () => {
const result = await lintHyperframeHtml(
comp(`[style*="visibility: hidden"] { pointer-events: none; }`),
);
expect(
result.findings.find((item) => item.code === "runtime_hidden_style_opacity"),
).toBeUndefined();
});
});
describe("id_override_reduced_specificity", () => {
const comp = (css: string) => `
<html><head><style>${css}</style></head><body>
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<div class="parent"><div id="line1" class="row">text</div></div>
</div>
<script>window.__timelines = { main: gsap.timeline({ paused: true }) };</script>
</body></html>`;
it("warns when an attribute selector on id sets a position property", async () => {
const result = await lintHyperframeHtml(
comp(`.parent .row { position: absolute; left: 0; } [id="line1"] { left: 40px; }`),
);
const finding = result.findings.find((f) => f.code === "id_override_reduced_specificity");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("warning");
expect(finding?.selector).toBe(`[id="line1"]`);
expect(finding?.fixHint).toContain("`#line1`");
});
it("warns when a :where()-wrapped id selector sets a position property", async () => {
const result = await lintHyperframeHtml(
comp(`.parent .row { position: absolute; top: 0; } :where(#line1) { top: 20px; }`),
);
const finding = result.findings.find((f) => f.code === "id_override_reduced_specificity");
expect(finding).toBeDefined();
expect(finding?.selector).toBe(`:where(#line1)`);
});
it("does not flag a bare #id selector, which always wins regardless of specificity", async () => {
const result = await lintHyperframeHtml(
comp(`.parent .row { position: absolute; left: 0; } #line1 { left: 40px; }`),
);
expect(
result.findings.find((f) => f.code === "id_override_reduced_specificity"),
).toBeUndefined();
});
it("hints an escaped #id for a digit-leading id, where a bare #01-intro is invalid CSS", async () => {
const result = await lintHyperframeHtml(
comp(`.parent .row { position: absolute; left: 0; } [id="01-intro"] { left: 40px; }`),
);
const finding = result.findings.find((f) => f.code === "id_override_reduced_specificity");
expect(finding?.fixHint).toContain("`#\\30 1-intro`");
});
it("does not flag prefix-matching id selectors or !important position overrides", async () => {
const result = await lintHyperframeHtml(
comp(
`[id^="line"] { top: 0; } [id*="ine"] { left: 0; } [id="line1"] { left: 40px !important; }`,
),
);
expect(
result.findings.find((f) => f.code === "id_override_reduced_specificity"),
).toBeUndefined();
});
it("does not flag a compound that also carries a bare #id, or a nested rule's position", async () => {
const result = await lintHyperframeHtml(
comp(`#line1[id="line1"] { left: 40px; } [id="root"] { color: red; .row { left: 0; } }`),
);
expect(
result.findings.find((f) => f.code === "id_override_reduced_specificity"),
).toBeUndefined();
});
it("does not flag an attribute selector on id for a non-position property", async () => {
const result = await lintHyperframeHtml(comp(`[id="line1"] { color: red; }`));
expect(
result.findings.find((f) => f.code === "id_override_reduced_specificity"),
).toBeUndefined();
});
});
describe("unclosed_tag_swallowed_element", () => {
it("flags an <img> tag whose unclosed start tag swallows a nested <div> as bogus attribute text", async () => {
const html = compositionWithBodyPrefix(
`<img class="browser-img" src="a.png" <div class="hl"></div></figure>`,
);
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "unclosed_tag_swallowed_element");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.snippet).toContain("<img");
});
it("does not flag a normal <img> tag", async () => {
const html = compositionWithBodyPrefix(`<img class="browser-img" src="a.png" />`);
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "unclosed_tag_swallowed_element"),
).toBeUndefined();
});
it.each([
["adjacent", `<span>A</span><span>B</span>`],
["spaces", `<span>A</span ><span>B</span>`],
["newline", `<span>A</span\n ><span>B</span>`],
])(
"does not flag valid sibling spans when the closing tag uses %s whitespace",
async (_label, body) => {
const result = await lintHyperframeHtml(compositionWithBodyPrefix(body));
expect(
result.findings.find((f) => f.code === "unclosed_tag_swallowed_element"),
).toBeUndefined();
},
);
it.each([`<span class="first" <span>B</span>`, `<span data-label=first <strong>B</strong>`])(
"still flags a malformed span start tag that swallows its next element",
async (body) => {
const result = await lintHyperframeHtml(compositionWithBodyPrefix(body));
const finding = result.findings.find((f) => f.code === "unclosed_tag_swallowed_element");
expect(finding?.severity).toBe("error");
expect(finding?.snippet).toContain("<span");
},
);
it("does not flag a legitimate attribute value containing a raw <", async () => {
const html = compositionWithBodyPrefix(`<div data-expr="x < y">hi</div>`);
const result = await lintHyperframeHtml(html);
expect(
result.findings.find((f) => f.code === "unclosed_tag_swallowed_element"),
).toBeUndefined();
});
});
describe("css_parse_error — malformed CSS is reported instead of silently swallowed", () => {
it("reports a css_parse_error finding for unparseable CSS", async () => {
const html = `<html><body>
<style>.stage { transform: xPercent: -10; }</style>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="5"></div>
<script src="gsap.min.js"></script>
<script>window.__timelines = { main: gsap.timeline({ paused: true }) };</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "css_parse_error");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
expect(finding?.message).toContain("Missed semicolon");
});
});
});