Skip to content

Write HTML. Render video. Built for agents.

65.5 KB
Raw Blame
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="mod&#117;le"', `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(&quot;#x&quot;, { 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="&#99;1" 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");
    });
  });
});