Skip to content

Write HTML. Render video. Built for agents.

48.6 KB
Raw Blame
import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
import { ChildProcess, execFile } from "node:child_process";
import { mkdirSync, mkdtempSync, writeFileSync, rmSync, symlinkSync } from "node:fs";
import { join } from "node:path";
import { tmpdir } from "node:os";
import type { HyperframeLintFinding } from "./types.js";
import { lintProject } from "./project.js";

// Keep project lint tests independent of the host's ffprobe installation.
vi.mock("node:child_process", () => {
  const mocked = { ChildProcess: class {}, execFile: vi.fn(), execSync: vi.fn() };
  return { ...mocked, default: mocked };
});

function tmpProject(name: string): string {
  return mkdtempSync(join(tmpdir(), `hf-lint-test-${name}-`));
}

function validHtml(compId = "main"): string {
  return `<html><body>
  <div data-composition-id="${compId}" data-width="1920" data-height="1080" data-start="0" data-duration="10"></div>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>window.__timelines = window.__timelines || {}; window.__timelines["${compId}"] = gsap.timeline({ paused: true });</script>
</body></html>`;
}

let dirs: string[] = [];

function makeProject(indexHtml: string, subComps?: Record<string, string>): string {
  const dir = tmpProject("lint");
  dirs.push(dir);
  writeFileSync(join(dir, "index.html"), indexHtml);
  if (subComps) {
    const compsDir = join(dir, "compositions");
    mkdirSync(compsDir, { recursive: true });
    for (const [name, html] of Object.entries(subComps)) {
      writeFileSync(join(compsDir, name), html);
    }
  }
  return dir;
}

afterEach(() => {
  for (const d of dirs) {
    rmSync(d, { recursive: true, force: true });
  }
  dirs = [];
});

describe("missing_data_no_timeline", () => {
  it("surfaces bare nested composition hosts through project lint", async () => {
    const project = makeProject(`<!doctype html><html><body>
  <div data-composition-id="root" data-width="1920" data-height="1080" data-start="0" data-duration="5">
    <section id="alpha" data-composition-id="alpha"></section>
    <section id="beta" data-composition-id="beta"></section>
  </div>
  <script>window.__timelines["root"] = gsap.timeline({ paused: true });</script>
</body></html>`);

    const { results, totalWarnings } = await lintProject(project);
    const findings = results[0]?.result.findings.filter(
      (finding) => finding.code === "missing_data_no_timeline",
    );

    expect(totalWarnings).toBe(2);
    expect(findings?.map((finding) => finding.elementId)).toEqual(["alpha", "beta"]);
  });
});

describe("external symlink assets", () => {
  it("does not report a shared asset addressed through an in-project symlink", async () => {
    const project = makeProject(
      validHtml().replace("</div>", '<img src="assets/shared/sample.svg" /></div>'),
    );
    const externalDir = tmpProject("shared-assets");
    dirs.push(externalDir);
    mkdirSync(join(project, "assets"));
    writeFileSync(join(externalDir, "sample.svg"), "<svg>shared</svg>");
    try {
      symlinkSync(externalDir, join(project, "assets", "shared"), "dir");
    } catch {
      return;
    }

    const { results } = await lintProject(project);
    const findings = results.flatMap((result) => result.result.findings);

    expect(findings.some((finding) => finding.code === "missing_local_asset")).toBe(false);
  });
});

describe("blank_root_with_standalone_composition", () => {
  it("errors when the default entry is blank but an authored standalone composition lives under compositions", async () => {
    const project = makeProject(validHtml(), {
      "index.html": `<!doctype html><html><body>
  <div data-composition-id="bona-brand-card" data-width="1920" data-height="1080" data-start="0" data-duration="5">
    <div id="main-clip" class="clip" data-start="0" data-duration="5" data-track-index="0">BONA</div>
  </div>
  <script>window.__timelines = { "bona-brand-card": gsap.timeline({ paused: true }) };</script>
</body></html>`,
    });

    const { results, totalErrors } = await lintProject(project);
    const finding = results
      .flatMap((result) => result.result.findings)
      .find((item) => item.code === "blank_root_with_standalone_composition");

    expect(totalErrors).toBeGreaterThan(0);
    expect(finding?.severity).toBe("error");
    expect(finding?.message).toContain("compositions/index.html");
    expect(finding?.message).toContain("index.html");
    expect(finding?.message).toContain("publish");
    expect(finding?.fixHint).toContain("data-composition-src");
    expect(finding?.suggestedComposition).toBe("compositions/index.html");
  });

  it("treats non-rendering script, style, link, meta, and template children as blank", async () => {
    const shellOnlyRoot = validHtml().replace(
      "</div>",
      `<script type="application/json">{}</script>
       <style>.unused { color: white; }</style>
       <link rel="stylesheet" href="data:text/css,.unused%7Bcolor:white%7D">
       <meta name="description" content="shell">
       <template id="row-template"><div>row</div></template>
       </div>`,
    );
    const project = makeProject(shellOnlyRoot, {
      "authored.html": `<!doctype html><html><body>
  <div data-composition-id="authored" data-width="1920" data-height="1080" data-start="0" data-duration="5">
    <div class="clip" data-start="0" data-duration="5">Visible</div>
  </div>
</body></html>`,
    });

    const { results } = await lintProject(project);
    const finding = results
      .flatMap((result) => result.result.findings)
      .find((item) => item.code === "blank_root_with_standalone_composition");

    expect(finding).toBeDefined();
  });

  it("does not fire when index.html already contains authored clip content", async () => {
    const authoredRoot = validHtml().replace(
      "</div>",
      '<div class="clip" data-start="0" data-duration="10">Master content</div></div>',
    );
    const project = makeProject(authoredRoot, {
      "alternate.html": `<!doctype html><html><body>
  <div data-composition-id="alternate" data-width="1920" data-height="1080" data-start="0" data-duration="5">
    <div class="clip" data-start="0" data-duration="5">Alternate</div>
  </div>
</body></html>`,
    });

    const { results } = await lintProject(project);
    const finding = results
      .flatMap((result) => result.result.findings)
      .find((item) => item.code === "blank_root_with_standalone_composition");

    expect(finding).toBeUndefined();
  });

  it("does not treat a template-wrapped sub-composition as a misplaced standalone entry", async () => {
    const project = makeProject(validHtml(), {
      "scene.html": `<template>
  <div data-composition-id="scene" data-width="1920" data-height="1080">
    <div class="clip" data-start="0" data-duration="5">Scene</div>
  </div>
</template>`,
    });

    const { results } = await lintProject(project);
    const finding = results
      .flatMap((result) => result.result.findings)
      .find((item) => item.code === "blank_root_with_standalone_composition");

    expect(finding).toBeUndefined();
  });

  it("still catches a standalone composition that contains an unrelated nested template", async () => {
    const project = makeProject(validHtml(), {
      "card.html": `<!doctype html><html><body>
  <div data-composition-id="card" data-width="1920" data-height="1080" data-start="0" data-duration="5">
    <div class="clip" data-start="0" data-duration="5">Card</div>
    <template id="repeated-row"><div class="row">Row</div></template>
  </div>
</body></html>`,
    });

    const { results } = await lintProject(project);
    const finding = results
      .flatMap((result) => result.result.findings)
      .find((item) => item.code === "blank_root_with_standalone_composition");

    expect(finding).toBeDefined();
  });

  it("does not treat a composition that only mounts another composition as standalone", async () => {
    const project = makeProject(validHtml(), {
      "wrapper.html": `<!doctype html><html><body>
  <div data-composition-id="wrapper" data-width="1920" data-height="1080" data-start="0" data-duration="5">
    <div data-composition-src="compositions/scene.html" data-start="0" data-duration="5"></div>
  </div>
</body></html>`,
      "scene.html": `<template><div data-composition-id="scene"><p>Scene</p></div></template>`,
    });

    const { results } = await lintProject(project);
    const finding = results
      .flatMap((result) => result.result.findings)
      .find((item) => item.code === "blank_root_with_standalone_composition");

    expect(finding).toBeUndefined();
  });
});

describe("missing_or_empty_sub_composition", () => {
  function htmlWithSubComp(srcPath: string): string {
    return `<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
    <div data-composition-src="${srcPath}" data-composition-id="scene-title" data-start="0" data-duration="5"></div>
  </div>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
</body></html>`;
  }

  function validSubCompHtml(): string {
    return `<!doctype html><html><body>
  <div data-composition-id="scene-title" data-width="1920" data-height="1080">
    <div class="title">Hello</div>
  </div>
</body></html>`;
  }

  // Shared assertion: lint a project referencing "compositions/scene-title.html"
  // (or a custom srcPath) and return the missing_or_empty_sub_composition
  // finding, if any, plus the raw lint result for callers that need totalErrors.
  async function lintSubComp(
    srcPath: string,
    subCompFiles?: Record<string, string>,
  ): Promise<{ finding: HyperframeLintFinding | undefined; totalErrors: number }> {
    const project = makeProject(htmlWithSubComp(srcPath), subCompFiles);
    const { totalErrors, results } = await lintProject(project);
    const finding = results
      .flatMap((r) => r.result.findings)
      .find((f) => f.code === "missing_or_empty_sub_composition");
    return { finding, totalErrors };
  }

  it.each([
    {
      label: "empty",
      content: "",
      expectMessageContains: "empty",
    },
    {
      label: "whitespace-only",
      content: "   \n\t  ",
      expectMessageContains: "empty",
    },
    {
      label: "malformed / non-HTML",
      content: "just some plain text, no tags at all",
      expectMessageContains: "could not be parsed",
    },
  ])(
    "errors when the referenced sub-composition file is $label",
    async ({ content, expectMessageContains }) => {
      const { finding, totalErrors } = await lintSubComp("compositions/scene-title.html", {
        "scene-title.html": content,
      });

      expect(totalErrors).toBeGreaterThan(0);
      expect(finding).toBeDefined();
      expect(finding?.severity).toBe("error");
      expect(finding?.message).toContain(expectMessageContains);
    },
  );

  it("errors when the referenced sub-composition file does not exist", async () => {
    // No subComps passed — compositions/ directory doesn't even exist.
    const { finding, totalErrors } = await lintSubComp("compositions/does-not-exist.html");

    expect(totalErrors).toBeGreaterThan(0);
    expect(finding).toBeDefined();
    expect(finding?.message).toContain("compositions/does-not-exist.html");
    expect(finding?.message).toContain("does not exist");
  });

  it("errors, instead of crashing, when the referenced sub-composition is a folder", async () => {
    const project = makeProject(htmlWithSubComp("compositions/scene-title"), {});
    mkdirSync(join(project, "compositions", "scene-title"));
    writeFileSync(join(project, "compositions", "scene-title", "index.html"), validSubCompHtml());
    const { results } = await lintProject(project);
    const finding = results
      .flatMap((r) => r.result.findings)
      .find((f) => f.code === "missing_or_empty_sub_composition");

    expect(finding?.message).toContain("compositions/scene-title");
    expect(finding?.message).toContain("a folder, not an HTML file");
    expect(finding?.fixHint).toContain('"compositions/scene-title/index.html"');
  });

  it("errors when the referenced sub-composition file has content but no data-composition-id root", async () => {
    const { finding, totalErrors } = await lintSubComp("compositions/scene-title.html", {
      "scene-title.html": "<!doctype html><html><body><p>TODO: scene content</p></body></html>",
    });

    expect(totalErrors).toBeGreaterThan(0);
    expect(finding).toBeDefined();
    expect(finding?.message).toContain("data-composition-id");
  });

  it("does not error when the referenced sub-composition file is valid (happy path)", async () => {
    const { finding } = await lintSubComp("compositions/scene-title.html", {
      "scene-title.html": validSubCompHtml(),
    });
    expect(finding).toBeUndefined();
  });

  it("does not error on a project with no data-composition-src references", async () => {
    const project = makeProject(validHtml());
    const { results } = await lintProject(project);
    const finding = results
      .flatMap((r) => r.result.findings)
      .find((f) => f.code === "missing_or_empty_sub_composition");
    expect(finding).toBeUndefined();
  });

  it("dedupes a single bad reference into one finding even if repeated", async () => {
    const html = `<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
    <div data-composition-src="compositions/scene-title.html" data-composition-id="a" data-start="0" data-duration="5"></div>
    <div data-composition-src="compositions/scene-title.html" data-composition-id="b" data-start="5" data-duration="5"></div>
  </div>
  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
</body></html>`;
    const project = makeProject(html, { "scene-title.html": "" });

    const { results } = await lintProject(project);

    const findings = results
      .flatMap((r) => r.result.findings)
      .filter((f) => f.code === "missing_or_empty_sub_composition");
    expect(findings).toHaveLength(1);
  });

  // Regression: lint used to raw-filesystem-walk every .html under
  // compositions/, regardless of whether the root composition actually
  // references it. render's pre-flight (assertSubCompositionsUsable) only
  // follows real data-composition-src references starting from the root, so
  // an orphaned file with its own dangling reference made `lint`/`validate`
  // fail even though `render` succeeds fine on the same project.
  it("does not error on an orphaned, unreferenced file under compositions/ with a dangling reference inside it", async () => {
    const project = makeProject(validHtml(), {});
    const archivedDir = join(project, "compositions", "archived");
    mkdirSync(archivedDir, { recursive: true });
    // Never referenced from index.html — this file is unreachable.
    writeFileSync(
      join(archivedDir, "old-draft.html"),
      `<!doctype html><html><body>
  <div data-composition-id="old-draft" data-width="1920" data-height="1080">
    <div data-composition-src="compositions/does-not-exist.html" data-composition-id="ghost"></div>
  </div>
</body></html>`,
    );

    const { results, totalErrors } = await lintProject(project);
    const finding = results
      .flatMap((r) => r.result.findings)
      .find((f) => f.code === "missing_or_empty_sub_composition");

    expect(finding).toBeUndefined();
    expect(totalErrors).toBe(0);
  });

  it("still errors when a broken reference IS reachable from the root (nested, not just top-level)", async () => {
    const project = makeProject(htmlWithSubComp("compositions/parent.html"));
    mkdirSync(join(project, "compositions"), { recursive: true });
    writeFileSync(
      join(project, "compositions", "parent.html"),
      `<!doctype html><html><body>
  <div data-composition-id="scene-title" data-width="1920" data-height="1080">
    <div data-composition-src="compositions/does-not-exist.html" data-composition-id="child"></div>
  </div>
</body></html>`,
    );

    const { results, totalErrors } = await lintProject(project);
    const finding = results
      .flatMap((r) => r.result.findings)
      .find((f) => f.code === "missing_or_empty_sub_composition");

    expect(totalErrors).toBeGreaterThan(0);
    expect(finding).toBeDefined();
    expect(finding?.message).toContain("compositions/does-not-exist.html");
  });
});

describe("template shell style sources", () => {
  it("collects links, style blocks, and inline styles from template content", async () => {
    const project = makeProject(`<html><body>
      <div id="scene" data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10"></div>
      <template data-composition-id="shell">
        <link rel="stylesheet" href="shell.css">
        <style>[data-composition-id="from-style-block"] .title { opacity: 0; }</style>
        <div style="mask-image: url(missing-inline-mask.png)"></div>
        <template><style>[data-composition-id="from-nested-template"] .nested { opacity: 0; }</style></template>
      </template>
      <script>window.__timelines = {};</script>
    </body></html>`);
    writeFileSync(
      join(project, "shell.css"),
      '[data-composition-id="from-link"] .from-link { opacity: 0; }',
    );

    const { results } = await lintProject(project);
    const findings = results.flatMap((entry) => entry.result.findings);
    // Each style source scopes CSS to a composition id that has no wrapper, so
    // one scoped_css_missing_wrapper per source proves all three were collected.
    expect(
      findings
        .filter((finding) => finding.code === "scoped_css_missing_wrapper")
        .map((finding) => finding.selector)
        .sort(),
    ).toEqual([
      '[data-composition-id="from-link"]',
      '[data-composition-id="from-nested-template"]',
      '[data-composition-id="from-style-block"]',
    ]);
    expect(findings.some((finding) => finding.code === "texture_mask_asset_not_found")).toBe(true);
  });
});

describe("sub-composition stylesheet links", () => {
  function projectWithSharedFonts(compDir: string, href: string): string {
    const project = makeProject(validHtml());
    mkdirSync(join(project, "assets", "fonts"), { recursive: true });
    writeFileSync(join(project, "assets", "fonts", "repro.woff2"), "font");
    writeFileSync(
      join(project, "assets", "fonts.css"),
      "@font-face{font-family:'Repro';src:url('fonts/repro.woff2') format('woff2')}",
    );
    mkdirSync(join(project, compDir), { recursive: true });
    writeFileSync(
      join(project, compDir, "scene.html"),
      `<template>
  <link rel="stylesheet" href="${href}">
  <style>#scene-title{font-family:'Repro'}</style>
  <div id="root" data-composition-id="scene" data-width="1920" data-height="1080" data-duration="1">
    <h1 id="scene-title">Hello</h1>
  </div>
  <script>window.__timelines["scene"] = gsap.timeline({ paused: true });</script>
</template>`,
    );
    return project;
  }

  async function fontFaceFindings(project: string): Promise<HyperframeLintFinding[]> {
    const { results } = await lintProject(project);
    return results
      .flatMap((entry) => entry.result.findings)
      .filter((finding) => finding.code === "font_family_without_font_face");
  }

  it("reads a stylesheet from the project root when none sits next to the sub-composition", async () => {
    expect(
      await fontFaceFindings(projectWithSharedFonts("compositions/frames", "assets/fonts.css")),
    ).toEqual([]);
    expect(
      await fontFaceFindings(projectWithSharedFonts("compositions", "assets/fonts.css")),
    ).toEqual([]);
  });

  it("reads the stylesheet next to the sub-composition when both exist", async () => {
    const project = projectWithSharedFonts("compositions/frames", "fonts.css");
    writeFileSync(join(project, "fonts.css"), "@font-face{font-family:'Other';src:local('Other')}");
    writeFileSync(
      join(project, "compositions", "frames", "fonts.css"),
      "@font-face{font-family:'Repro';src:local('Repro')}",
    );
    expect(await fontFaceFindings(project)).toEqual([]);
  });

  it("does not read a root-anchored or parent href from the project root", async () => {
    for (const href of ["/assets/fonts.css", "../assets/fonts.css", "./../assets/fonts.css"]) {
      expect(
        await fontFaceFindings(projectWithSharedFonts("compositions/frames", href)),
      ).toHaveLength(1);
    }
  });

  it("skips a folder that has the stylesheet's name", async () => {
    const project = projectWithSharedFonts("compositions/frames", "shared.css");
    mkdirSync(join(project, "shared.css"));
    expect(await fontFaceFindings(project)).toHaveLength(1);
  });
});

describe("hevc_preview_codec", () => {
  interface ProbeStream {
    codec_name: string;
    codec_tag_string: string;
  }

  const mockExecFile = vi.mocked(execFile);

  // Any real file works as a stand-in "ffprobe" path — execFile itself is
  // mocked below, so it's never actually spawned.
  const FAKE_FFPROBE_PATH = process.execPath;

  function mockFfprobeStreams(streamsByFile: Record<string, ProbeStream[]>): void {
    mockExecFile.mockImplementation((_file, args, _options, callback) => {
      const filePath = args[args.length - 1] ?? "";
      callback(
        null,
        Buffer.from(JSON.stringify({ streams: streamsByFile[filePath] ?? [] })),
        Buffer.alloc(0),
      );
      return new ChildProcess();
    });
  }

  function videoHtml(...videoSrcs: string[]): string {
    const videoTags = videoSrcs
      .map(
        (src, i) =>
          `<video id="v${i}" class="clip" src="${src}" muted data-start="${i * 5}" data-duration="5"></video>`,
      )
      .join("\n    ");
    return `<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
    ${videoTags}
  </div>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
</body></html>`;
  }

  function makeVideoProject(
    videoSrc: string,
    writeVideoFile = true,
  ): { project: string; videoAbsPath: string } {
    const project = makeProject(videoHtml(videoSrc));
    const videoAbsPath = join(project, videoSrc);
    if (writeVideoFile) writeFileSync(videoAbsPath, "fake video bytes");
    return { project, videoAbsPath };
  }

  async function hevcFindings(project: string): Promise<HyperframeLintFinding[]> {
    const { results } = await lintProject(project);
    return results.flatMap((r) => r.result.findings).filter((f) => f.code === "hevc_preview_codec");
  }

  beforeEach(() => {
    process.env.HYPERFRAMES_FFPROBE_PATH = FAKE_FFPROBE_PATH;
    mockExecFile.mockReset();
  });

  afterEach(() => {
    delete process.env.HYPERFRAMES_FFPROBE_PATH;
    mockExecFile.mockReset();
  });

  it("flags an HEVC video with exactly one info finding naming the file", async () => {
    const { project, videoAbsPath } = makeVideoProject("clip.mp4");
    mockFfprobeStreams({
      [videoAbsPath]: [{ codec_name: "hevc", codec_tag_string: "hvc1" }],
    });

    const result = await lintProject(project);
    const findings = result.results
      .flatMap((entry) => entry.result.findings)
      .filter((finding) => finding.code === "hevc_preview_codec");

    expect(findings).toHaveLength(1);
    expect(findings[0]?.severity).toBe("info");
    expect(findings[0]?.code).toBe("hevc_preview_codec");
    expect(findings[0]?.message).toContain("clip.mp4");
    expect(findings[0]?.message).toContain("automatically uses a cached H.264 proxy");
    expect(result.totalErrors).toBe(0);
    expect(result.results[0]?.result.ok).toBe(true);
  });

  it('flags an hev1-tagged HEVC video the same way (ffprobe reports codec_name "hevc" regardless of the container fourcc)', async () => {
    const { project, videoAbsPath } = makeVideoProject("clip-hev1.mp4");
    mockFfprobeStreams({
      [videoAbsPath]: [{ codec_name: "hevc", codec_tag_string: "hev1" }],
    });

    const findings = await hevcFindings(project);

    expect(findings).toHaveLength(1);
    expect(findings[0]?.message).toContain("clip-hev1.mp4");
  });

  it("does not flag an H.264 video", async () => {
    const { project, videoAbsPath } = makeVideoProject("clip.mp4");
    mockFfprobeStreams({
      [videoAbsPath]: [{ codec_name: "h264", codec_tag_string: "avc1" }],
    });

    const findings = await hevcFindings(project);

    expect(findings).toHaveLength(0);
  });

  it("does not flag anything, and lint completes normally, when ffprobe cannot be resolved", async () => {
    const { project } = makeVideoProject("clip.mp4");
    process.env.HYPERFRAMES_FFPROBE_PATH = join(project, "missing-ffprobe");

    const { results, totalErrors } = await lintProject(project);

    const findings = results.flatMap((r) => r.result.findings);
    expect(findings.some((f) => f.code === "hevc_preview_codec")).toBe(false);
    expect(mockExecFile).not.toHaveBeenCalled();
    expect(totalErrors).toBe(0);
  });

  it("silently skips the finding when ffprobe errors or times out", async () => {
    const { project } = makeVideoProject("clip.mp4");
    mockExecFile.mockImplementation((_file, _args, _options, callback) => {
      callback(new Error("ffprobe timed out"), Buffer.alloc(0), Buffer.alloc(0));
      return new ChildProcess();
    });

    const { results, totalErrors } = await lintProject(project);

    const findings = results.flatMap((entry) => entry.result.findings);
    expect(findings.some((finding) => finding.code === "hevc_preview_codec")).toBe(false);
    expect(totalErrors).toBe(0);
  });

  it("does not probe or flag a missing video file — missing_local_asset covers it instead", async () => {
    const { project } = makeVideoProject("missing.mp4", false);

    const { results } = await lintProject(project);

    const findings = results.flatMap((r) => r.result.findings);
    expect(findings.some((f) => f.code === "hevc_preview_codec")).toBe(false);
    expect(findings.some((f) => f.code === "missing_local_asset")).toBe(true);
    expect(mockExecFile).not.toHaveBeenCalled();
  });

  it("probes the same HEVC file once when referenced twice (per-run cache)", async () => {
    const project = makeProject(videoHtml("clip.mp4", "clip.mp4"));
    const videoAbsPath = join(project, "clip.mp4");
    writeFileSync(videoAbsPath, "fake video bytes");
    mockFfprobeStreams({
      [videoAbsPath]: [{ codec_name: "hevc", codec_tag_string: "hvc1" }],
    });

    const findings = await hevcFindings(project);

    expect(findings).toHaveLength(1);
    expect(mockExecFile).toHaveBeenCalledTimes(1);
  });
});

describe("video_media_start_at_or_past_eof", () => {
  const mockExecFile = vi.mocked(execFile);
  const FAKE_FFPROBE_PATH = process.execPath;

  function videoProject(videoTags: string): { project: string; videoAbsPath: string } {
    const project = makeProject(`<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
    ${videoTags}
  </div>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
</body></html>`);
    const videoAbsPath = join(project, "clip.mp4");
    writeFileSync(videoAbsPath, "fake video bytes");
    return { project, videoAbsPath };
  }

  function mockDurationProbe(streamDuration: number, containerDuration = streamDuration): void {
    mockExecFile.mockImplementation((_file, _args, _options, callback) => {
      callback(
        null,
        Buffer.from(
          JSON.stringify({
            streams: [{ codec_name: "h264", duration: String(streamDuration) }],
            format: { duration: String(containerDuration) },
          }),
        ),
        Buffer.alloc(0),
      );
      return new ChildProcess();
    });
  }

  async function mediaStartFindings(project: string): Promise<HyperframeLintFinding[]> {
    const { results } = await lintProject(project);
    return results
      .flatMap((entry) => entry.result.findings)
      .filter((finding) => finding.code === "video_media_start_at_or_past_eof");
  }

  beforeEach(() => {
    process.env.HYPERFRAMES_FFPROBE_PATH = FAKE_FFPROBE_PATH;
    mockExecFile.mockReset();
  });

  afterEach(() => {
    delete process.env.HYPERFRAMES_FFPROBE_PATH;
    mockExecFile.mockReset();
  });

  it.each([2, 5])(
    "warns that a finite non-looping local video starting at/past stream EOF (%ss) holds its final frame",
    async (mediaStart) => {
      const { project } = videoProject(
        `<video id="clip" src="clip.mp4" data-start="0" data-duration="6" data-media-start="${mediaStart}" muted></video>`,
      );
      mockDurationProbe(2, 60);

      const result = await lintProject(project);
      const findings = result.results
        .flatMap((entry) => entry.result.findings)
        .filter((finding) => finding.code === "video_media_start_at_or_past_eof");

      expect(findings).toHaveLength(1);
      expect(findings[0]).toMatchObject({
        severity: "warning",
        file: "index.html",
        elementId: "clip",
      });
      expect(findings[0]?.message).toContain("will hold its final frame");
      expect(findings[0]?.fixHint).toContain("Trim data-media-start");
      expect(result.totalWarnings).toBeGreaterThanOrEqual(1);
      expect(result.totalErrors).toBe(0);
      expect(result.results[0]?.result.ok).toBe(true);
    },
  );

  it("does not warn when the media start is just inside EOF", async () => {
    const { project } = videoProject(
      '<video id="clip" src="clip.mp4" data-start="0" data-duration="6" data-media-start="1.999" muted></video>',
    );
    mockDurationProbe(2);

    expect(await mediaStartFindings(project)).toEqual([]);
  });

  it("silently skips open, looping, remote, variable, missing, and unprobeable slots", async () => {
    const { project } = videoProject(`
      <video src="clip.mp4" data-start="0" data-duration="6" data-media-start="1.9" muted></video>
      <video src="clip.mp4" data-start="0" data-media-start="5" muted></video>
      <video src="clip.mp4" data-start="0" data-duration="6" data-media-start="5" loop muted></video>
      <video src="clip.mp4" data-var-src="selectedVideo" data-start="0" data-duration="6" data-media-start="5" muted></video>
      <video src="https://cdn.example.com/clip.mp4" data-start="0" data-duration="6" data-media-start="5" muted></video>
      <video src="missing.mp4" data-start="0" data-duration="6" data-media-start="5" muted></video>
    `);
    // Every locally addressable source receives a successful duration probe;
    // each listed attribute/path boundary, not a probe failure, must exclude it.
    mockDurationProbe(2);

    expect(await mediaStartFindings(project)).toEqual([]);
  });
});

describe("missing asset findings name the file that references them", () => {
  it("points a draft section's missing image, audio and mask at the draft, not the film", async () => {
    const project = makeProject(
      `<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
    <img src="assets/missing-in-film.png" />
    <div data-composition-src="compositions/draft.html" data-composition-id="draft" data-start="0" data-duration="5"></div>
  </div>
</body></html>`,
      {
        "draft.html": `<!doctype html><html><body>
  <div data-composition-id="draft" data-width="1920" data-height="1080">
    <style>.masked { mask-image: url(../assets/missing-mask.png); }</style>
    <img src="../assets/missing-in-draft.png" />
    <audio src="../assets/missing-in-draft.mp3" data-start="0" data-duration="5"></audio>
  </div>
</body></html>`,
      },
    );

    const { results } = await lintProject(project);
    const fileOf = (code: string, name: string) =>
      results
        .flatMap((entry) => entry.result.findings)
        .find((finding) => finding.code === code && finding.message.includes(name))?.file;

    const draft = join(project, "compositions", "draft.html");
    expect(fileOf("missing_local_asset", "missing-in-draft.png")).toBe(draft);
    expect(fileOf("audio_src_not_found", "missing-in-draft.mp3")).toBe(draft);
    expect(fileOf("texture_mask_asset_not_found", "missing-mask.png")).toBe(draft);
    expect(fileOf("missing_local_asset", "missing-in-film.png")).toBe(join(project, "index.html"));
    const entryOf = (name: string) =>
      results.find((entry) => entry.result.findings.some((f) => f.message.includes(name)))?.file;
    expect(entryOf("missing-in-draft.png")).toBe("compositions/draft.html");
    expect(entryOf("missing-in-draft.mp3")).toBe("compositions/draft.html");
    expect(entryOf("missing-mask.png")).toBe("compositions/draft.html");
    expect(entryOf("missing-in-film.png")).toBe("index.html");
  });
});

describe("audio_src_not_found with templating tokens", () => {
  // A src carrying an unresolved templating placeholder is late-bound before render,
  // so the static linter cannot resolve it to a file and must not report it missing.
  function audioProject(src: string): string {
    return makeProject(`<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10"></div>
  <audio id="a1" class="clip" data-start="0" data-duration="3" data-track-index="10" src="${src}"></audio>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
</body></html>`);
  }

  async function hasAudioSrcNotFound(project: string): Promise<boolean> {
    const { results } = await lintProject(project);
    const findings: HyperframeLintFinding[] = results.flatMap((entry) => entry.result.findings);
    return findings.some((finding) => finding.code === "audio_src_not_found");
  }

  it("does not flag unresolved <<token>>, {{ token }}, or ${token} audio srcs", async () => {
    for (const token of ["<<tts_abc>>", "{{ audioUrl }}", "${audioUrl}"]) {
      expect(await hasAudioSrcNotFound(audioProject(token))).toBe(false);
    }
  });

  it("still flags a genuinely missing local audio file", async () => {
    expect(await hasAudioSrcNotFound(audioProject("audio/missing.mp3"))).toBe(true);
  });

  it("accepts an existing audio file addressed the way the renderer resolves it", async () => {
    for (const src of [
      "audio/bed.mp3",
      "/audio/bed.mp3",
      "../audio/bed.mp3",
      "audio/bed.mp3?v=2",
      "audio/bed.mp3#t=5",
    ]) {
      const project = audioProject(src);
      mkdirSync(join(project, "audio"), { recursive: true });
      writeFileSync(join(project, "audio", "bed.mp3"), "");
      expect(await hasAudioSrcNotFound(project)).toBe(false);
    }
  });
});

describe("a double-quoted src that contains an apostrophe", () => {
  const name = "Narrator's voice take 1.mp3";

  it("finds the existing audio file instead of cutting the src at the apostrophe", async () => {
    const project = makeProject(`<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10"></div>
  <audio id="a1" class="clip" data-start="0" data-duration="3" data-track-index="10" src="assets/${name}"></audio>
</body></html>`);
    mkdirSync(join(project, "assets"), { recursive: true });
    writeFileSync(join(project, "assets", name), "");
    const { results } = await lintProject(project);
    const codes = results.flatMap((entry) => entry.result.findings).map((f) => f.code);
    expect(codes).not.toContain("audio_src_not_found");
  });

  async function lintCodes(body: string, files: string[]): Promise<string[]> {
    const project = makeProject(`<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10"></div>
  ${body}
</body></html>`);
    mkdirSync(join(project, "assets"), { recursive: true });
    for (const file of files) writeFileSync(join(project, "assets", file), "");
    const { results } = await lintProject(project);
    return results.flatMap((entry) => entry.result.findings).map((f) => f.code);
  }

  it("finds an existing audio file whose apostrophe is written as a character reference", async () => {
    const codes = await lintCodes(
      `<audio id="a1" class="clip" data-start="0" data-duration="3" data-track-index="10" src="assets/Narrator&#39;s take.mp3"></audio>`,
      ["Narrator's take.mp3"],
    );
    expect(codes).not.toContain("audio_src_not_found");
  });

  it("tells two layered files apart when their names share text up to an apostrophe", async () => {
    const audio = (id: string, file: string) =>
      `<audio id="${id}" class="clip" data-start="0" data-duration="5" data-track-index="10" src="assets/${file}"></audio>`;
    const codes = await lintCodes(
      audio("a1", "Narrator's take 1.mp3") + audio("a2", "Narrator's take 2.mp3"),
      ["Narrator's take 1.mp3", "Narrator's take 2.mp3"],
    );
    expect(codes).toContain("duplicate_audio_track");
  });

  it("still reports a missing file whose name starts with a quote character", async () => {
    const codes = await lintCodes(
      `<audio id="a1" class="clip" data-start="0" data-duration="3" data-track-index="10" src="'90s theme.mp3"></audio>`,
      [],
    );
    expect(codes).toContain("audio_src_not_found");
  });

  it("does not read an audio tag that an inline script builds as a string", async () => {
    const codes = await lintCodes(
      `<script>var s = '<audio src="' + u + '">'; var t = "<audio src='" + u + "'>";</script>`,
      [],
    );
    expect(codes).not.toContain("audio_src_not_found");
  });

  it("does not read a src out of another attribute's text", async () => {
    const codes = await lintCodes(`<img id="i1" alt="x src='ghost.png'" />`, []);
    expect(codes).not.toContain("missing_local_asset");
  });

  it("finds the existing image through the shared src pattern too", async () => {
    const image = "Ann's photo.png";
    const project = makeProject(`<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
    <img id="i1" class="clip" data-start="0" data-duration="3" data-track-index="0" src="assets/${image}">
  </div>
</body></html>`);
    mkdirSync(join(project, "assets"), { recursive: true });
    writeFileSync(join(project, "assets", image), "");
    const { results } = await lintProject(project);
    const codes = results.flatMap((entry) => entry.result.findings).map((f) => f.code);
    expect(codes).not.toContain("missing_local_asset");
  });
});

describe("templating tokens are checked on the raw src, before cleanAssetUrl", () => {
  // cleanAssetUrl splits on ?/#, which also chops inside a ${...} expression
  // (e.g. `${asset?.url}` -> `${asset`). The token skip must run on the RAW value or
  // these still false-positive at the video/img/source and CSS-url() sites.
  function projectWith(bodyInner: string): string {
    return makeProject(`<html><body>
  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10"></div>
  ${bodyInner}
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
</body></html>`);
  }
  async function codes(project: string): Promise<Set<string>> {
    const { results } = await lintProject(project);
    return new Set(results.flatMap((entry) => entry.result.findings).map((f) => f.code));
  }

  // The blocker: ?/# lives inside the templating expression, so cleanAssetUrl truncates it.
  const TRICKY = ["${asset?.url}", "${a ?? b}", "${u}?v=1", "<<video_x>>", "{{ videoUrl }}"];

  it("does not flag missing_local_asset for <video> token srcs (incl. ?/# inside ${...})", async () => {
    for (const src of TRICKY) {
      const c = await codes(
        projectWith(
          `<video id="v1" class="clip" src="${src}" muted data-start="0" data-duration="3"></video>`,
        ),
      );
      expect(c.has("missing_local_asset")).toBe(false);
    }
  });

  it("does not flag missing_local_asset for <img> token srcs (incl. ?/# inside ${...})", async () => {
    for (const src of TRICKY) {
      const c = await codes(projectWith(`<img src="${src}" />`));
      expect(c.has("missing_local_asset")).toBe(false);
    }
  });

  it("does not flag texture_mask_asset_not_found for CSS url() token values (incl. ?/# inside ${...})", async () => {
    for (const url of ["${asset?.url}", "${a ?? b}"]) {
      const c = await codes(projectWith(`<div style="mask-image: url(${url})"></div>`));
      expect(c.has("texture_mask_asset_not_found")).toBe(false);
    }
  });

  // `\bsrc\s*=` also matched the tail of `data-var-src="bg"`, and `[^>]*` is greedy,
  // so a real src earlier in the same tag lost to the variable id: bindings were
  // reported as a missing file named after the variable.
  it("reports the real src, not the data-var-src variable id", async () => {
    const { results } = await lintProject(
      projectWith(`<img src="assets/logo.png" data-var-src="bg" />`),
    );
    const finding = results
      .flatMap((entry) => entry.result.findings)
      .find((f) => f.code === "missing_local_asset");
    expect(finding?.message).toContain("assets/logo.png");
    expect(finding?.message).not.toContain("bg");
  });

  it("does not invent a missing asset for a binding on an element whose src resolves", async () => {
    const c = await codes(projectWith(`<img src="${"${imgUrl}"}" data-var-src="bg" />`));
    expect(c.has("missing_local_asset")).toBe(false);
  });

  it("still flags a genuinely missing local video file", async () => {
    const c = await codes(
      projectWith(
        `<video id="v1" class="clip" src="assets/missing.mp4" muted data-start="0" data-duration="3"></video>`,
      ),
    );
    expect(c.has("missing_local_asset")).toBe(true);
  });
});

describe("audio-aware project rules", () => {
  const composition = (body: string) => validHtml().replace("></div>", `>${body}</div>`);
  const codesFor = async (html: string, files: string[] = []) => {
    const project = makeProject(html);
    for (const file of files) writeFileSync(join(project, file), "x");
    const { results } = await lintProject(project);
    return results.flatMap((result) => result.result.findings.map((f) => f.code));
  };
  const video = (attrs: string, start = 0) =>
    `<video id="v${start}${attrs.length}" src="a.mp4" data-start="${start}" data-duration="5" data-track-index="0" ${attrs}></video>`;

  describe("duplicate_audio_track", () => {
    it("warns when audible videos overlap on one track", async () => {
      const codes = await codesFor(
        composition(video('data-has-audio="true"', 0) + video('data-has-audio="true"', 2)),
      );
      expect(codes).toContain("duplicate_audio_track");
    });

    it("stays quiet when one of the overlapping videos is muted", async () => {
      const codes = await codesFor(
        composition(video('data-has-audio="true"', 0) + video("muted", 2)),
      );
      expect(codes).not.toContain("duplicate_audio_track");
    });

    it("stays quiet when an overlapping video is explicitly non-audible", async () => {
      const codes = await codesFor(
        composition(video('data-has-audio="true"', 0) + video('data-has-audio="false"', 2)),
      );
      expect(codes).not.toContain("duplicate_audio_track");
    });

    it("stays quiet for back-to-back clips whose start plus duration only rounds past the next start", async () => {
      // 21.03 + 0.1 is 21.130000000000003 in floating point.
      const clip = (id: string, start: string, duration: string) =>
        `<audio id="${id}" src="a.mp3" data-start="${start}" data-duration="${duration}" data-track-index="0"></audio>`;
      const codes = await codesFor(
        composition(
          clip("m1", "0", "21.03") + clip("m2", "21.03", "0.1") + clip("m3", "21.13", "5"),
        ),
      );
      expect(codes).not.toContain("duplicate_audio_track");
    });

    const scene = (id: string, videoDuration = 5) => `<template id="${id}-template">
  <div data-composition-id="${id}" data-width="1920" data-height="1080">
    ${video('data-has-audio="true"')
      .replace('src="a.mp4"', `src="${id}.mp4"`)
      .replace('data-duration="5"', `data-duration="${videoDuration}"`)}
  </div>
</template>`;
    const host = (id: string, start: number | string, length: number | null) =>
      `<div data-composition-id="${id}" data-composition-src="compositions/${id}.html" data-start="${start}"${length === null ? "" : ` data-duration="${length}"`} data-track-index="1"></div>`;
    const scenesCodes = (
      starts: Array<number | string>,
      { videoDuration = 5, hostDuration = 5 as number | null } = {},
    ) => {
      const ids = starts.map((_, i) => `s${i}`);
      const project = makeProject(
        composition(ids.map((id, i) => host(id, starts[i]!, hostDuration)).join("")),
        Object.fromEntries(ids.map((id) => [`${id}.html`, scene(id, videoDuration)])),
      );
      return lintProject(project).then(({ results }) =>
        results.flatMap((result) => result.result.findings.map((f) => f.code)),
      );
    };

    it("places each scene's audio at its host's start, so scenes played one after another pass", async () => {
      expect(await scenesCodes([0, 5])).not.toContain("duplicate_audio_track");
      expect(await scenesCodes([0, 5], { hostDuration: null })).not.toContain(
        "duplicate_audio_track",
      );
    });

    it("still warns when two scenes' hosts overlap", async () => {
      expect(await scenesCodes([0, 2])).toContain("duplicate_audio_track");
    });

    it("places a scene chained to the one before it with a reference start", async () => {
      expect(await scenesCodes([0, "s0"])).not.toContain("duplicate_audio_track");
      expect(await scenesCodes([0, "s0 - 2"])).toContain("duplicate_audio_track");
    });

    it("cuts a scene's audio at its host's end, as playback does", async () => {
      expect(await scenesCodes([0, 5], { videoDuration: 10 })).not.toContain(
        "duplicate_audio_track",
      );
    });
  });

  describe("audio_file_without_element", () => {
    const audibleRoll = video('data-has-audio="true"');
    it("does not claim silence when an audible video carries the sound", async () => {
      const codes = await codesFor(composition(audibleRoll), ["audio.mp3"]);
      expect(codes).not.toContain("audio_file_without_element");
    });

    it("still warns when the only video is muted", async () => {
      const codes = await codesFor(composition(video("muted")), ["audio.mp3"]);
      expect(codes).toContain("audio_file_without_element");
    });
  });
});

describe("sub-composition files", () => {
  const sceneFindings = async (project: string) =>
    (await lintProject(project)).results.find((result) => result.file === "compositions/scene.html")
      ?.result.findings ?? [];

  it("resolves a scene's ../assets/ path from its own folder, as preview and render do", async () => {
    const project = makeProject(validHtml(), {
      "scene.html": `<template id="scene-template">
  <div data-composition-id="scene" data-width="1920" data-height="1080">
    <img src="../assets/logo.png" alt=""><img src="../../outside.png" alt="">
  </div>
</template>`,
    });
    mkdirSync(join(project, "assets"));
    writeFileSync(join(project, "assets", "logo.png"), "");
    const finding = (await sceneFindings(project)).find(
      (f) => f.code === "invalid_parent_traversal_in_asset_path",
    );
    expect(finding?.message).toContain("1 asset path(s)");
    expect(finding?.message).toContain("../../");
  });

  it("resolves a linked stylesheet's url()s from the stylesheet's own folder", async () => {
    const project = makeProject(
      validHtml().replace(
        "<body>",
        '<head><link rel="stylesheet" href="styles/main.css"></head><body>',
      ),
      {
        "scene.html": `<template id="scene-template">
  <link rel="stylesheet" href="../styles/escape.css">
  <div data-composition-id="scene" data-width="1920" data-height="1080"></div>
</template>`,
      },
    );
    mkdirSync(join(project, "styles"));
    writeFileSync(
      join(project, "styles", "main.css"),
      "@font-face { src: url('../fonts/B.woff2'); }",
    );
    writeFileSync(
      join(project, "styles", "escape.css"),
      ".a { background: url('../../outside.png'); }",
    );
    const { results } = await lintProject(project);
    const traversal = (file: string) =>
      results
        .find((result) => result.file === file)
        ?.result.findings.find((f) => f.code === "invalid_parent_traversal_in_asset_path");
    expect(traversal("index.html")).toBeUndefined();
    expect(traversal("compositions/scene.html")?.message).toContain("../../");
  });

  it("does not stop the check over a scene without its own size", async () => {
    const project = makeProject(validHtml(), {
      "scene.html": `<template id="scene-template">
  <div data-composition-id="scene"><p>Hi</p></div>
</template>`,
    });
    expect((await sceneFindings(project)).map((f) => f.code)).not.toContain(
      "root_missing_dimensions",
    );
  });
});