Skip to content

Write HTML. Render video. Built for agents.

20.8 KB
Raw Blame
// @vitest-environment happy-dom
import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
import {
  bundleToSingleHtml,
  extractCompiledHtmlParityContract,
  injectScriptsIntoHtml,
} from "@hyperframes/core/compiler";
// Deep import: the mount path is not part of core's published export map (it is
// bundled into the runtime IIFE, not imported by consumers). Same shape as
// engine/src/services/videoFrameExtractor.test.ts reaching into core's runtime.
import { loadCompositions } from "../../../core/src/runtime/compositionLoader.js";
import { compileForRender } from "./htmlCompiler.js";
import { getVerifiedHyperframeRuntimeSource } from "./hyperframeRuntimeLoader.js";

vi.mock("../utils/urlDownloader.js", async (importOriginal) => ({
  ...(await importOriginal<typeof import("../utils/urlDownloader.js")>()),
  fetchPublicHttpsText: async () => {
    throw new Error("offline test");
  },
}));
Object.assign(
  (
    window as unknown as {
      happyDOM: {
        settings: { disableCSSFileLoading: boolean; handleDisabledFileLoadingAsSuccess: boolean };
      };
    }
  ).happyDOM.settings,
  { disableCSSFileLoading: true, handleDisabledFileLoadingAsSuccess: true },
);

const tempDirs: string[] = [];

const nativeQuerySelector = Element.prototype.querySelector;
const nativeQuerySelectorAll = Element.prototype.querySelectorAll;
afterEach(() => {
  Element.prototype.querySelector = nativeQuerySelector;
  Element.prototype.querySelectorAll = nativeQuerySelectorAll;
  delete window.__hfSvgSelectorAliases;
});

beforeAll(() => {
  // The mount path scopes CSS with CSS.escape, which the DOM stub omits.
  if (typeof globalThis.CSS === "undefined") {
    Object.defineProperty(globalThis, "CSS", { value: {}, configurable: true, writable: true });
  }
  if (typeof CSS.escape !== "function") {
    CSS.escape = (value: string) => value.replace(/([^\w-])/g, "\\$1");
  }
});

afterEach(() => {
  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
  document.head.innerHTML = "";
  document.body.innerHTML = "";
  delete (window as Window & { __hfVariablesByComp?: unknown }).__hfVariablesByComp;
  delete (window as Window & { __timelines?: unknown }).__timelines;
  vi.restoreAllMocks();
});

function project(files: Record<string, string>): string {
  const dir = mkdtempSync(join(tmpdir(), "hf-compiler-parity-"));
  tempDirs.push(dir);
  for (const [relative, content] of Object.entries(files)) {
    const path = join(dir, relative);
    mkdirSync(dirname(path), { recursive: true });
    writeFileSync(path, content);
  }
  return dir;
}

type ParityContract = ReturnType<typeof extractCompiledHtmlParityContract>;

/**
 * Mount the project the way the player does — parse `index.html` into the live
 * document, serve its sub-compositions over a stubbed `fetch`, and let the
 * runtime assemble them — then read the same contract off the resulting DOM.
 *
 * This is the third assembly path. Both compiler arms below run the same code
 * up to `bundleToSingleHtml`, which is why a runtime-only regression (a mounted
 * composition losing every `<style>` authored beside its root) stayed invisible
 * to a green suite.
 */
async function mountContract(dir: string, indexHtml: string): Promise<ParityContract> {
  const parsed = new DOMParser().parseFromString(indexHtml, "text/html");
  document.head.innerHTML = parsed.head.innerHTML;
  document.body.innerHTML = parsed.body.innerHTML;
  vi.spyOn(globalThis, "fetch").mockImplementation(async (input) =>
    Promise.resolve(new Response(readFileSync(join(dir, String(input)), "utf8"), { status: 200 })),
  );
  await loadCompositions({
    injectedStyles: [],
    injectedScripts: [],
    injectedLinks: [],
    parseDimensionPx: (value: string | null) => (value ? `${value}px` : null),
    // A mount that fails is not a parity result. Surface it instead of
    // comparing the contract of an empty host against a compiled one.
    onDiagnostic: ({ code, details }) => {
      throw new Error(`mount diagnostic ${code}: ${JSON.stringify(details)}`);
    },
  });
  return extractCompiledHtmlParityContract(`<!doctype html>${document.documentElement.outerHTML}`);
}

async function contracts(files: Record<string, string>) {
  const dir = project(files);
  const preview = await bundleToSingleHtml(dir);
  const render = await compileForRender(dir, join(dir, "index.html"), join(dir, ".downloads"), {
    allowSystemFontCapture: false,
  });
  const servedRender = injectScriptsIntoHtml(
    render.html,
    [getVerifiedHyperframeRuntimeSource()],
    [],
    true,
  );
  return {
    preview: extractCompiledHtmlParityContract(preview),
    render: extractCompiledHtmlParityContract(servedRender),
    mount: await mountContract(dir, files["index.html"]!),
  };
}

const shell = (body: string, head = "") => `<!doctype html>
<html><head>${head}</head><body>${body}
<script>window.__timelines = window.__timelines || {};</script></body></html>`;

describe("preview/render semantic compilation parity", () => {
  it("preserves canonical timing, track, authored style, font, and resource contracts", async () => {
    const result = await contracts({
      "index.html": shell(
        `<main data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="4">
          <div id="title" data-start="1" data-duration="2" data-track-index="3" class="clip parity-card">Title</div>
          <img id="logo" src="assets/logo.svg" alt="" />
        </main>`,
        `<style>@font-face { font-family: "ParityDisplay"; src: url(data:font/woff2;base64,d09GMgAB) format("woff2"); }
        .parity-card { --parity-contract: 1; color: red; font-family: "ParityDisplay", sans-serif; }</style>`,
      ),
      "assets/logo.svg": `<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"></svg>`,
    });
    expect(result.render).toEqual(result.preview);
  });

  it("keeps conditional head styles apart the same way in preview and render", async () => {
    const dir = project({
      "index.html": shell(
        `<main data-composition-id="main" data-start="0" data-width="320" data-height="180" data-duration="1"></main>`,
        `<style>p{color:red}</style><style media="print">p{color:blue}</style>` +
          `<style type="text/x-tpl">{{ a }}</style><style title="alt">p{color:green}</style>` +
          `<style>h1{color:black}</style><style>h2{color:black}</style>`,
      ),
    });
    const headStyles = (html: string) =>
      [...new DOMParser().parseFromString(html, "text/html").head.querySelectorAll("style")]
        .filter((el) => !el.hasAttribute("data-hyperframes-text-rendering"))
        .map((el) => [
          el.getAttribute("media"),
          el.getAttribute("type"),
          el.getAttribute("title"),
          el.textContent,
        ]);
    const preview = headStyles(await bundleToSingleHtml(dir));
    const render = headStyles(
      (
        await compileForRender(dir, join(dir, "index.html"), join(dir, ".downloads"), {
          allowSystemFontCapture: false,
        })
      ).html,
    );
    expect(preview).toEqual([
      [null, null, null, "p{color:red}"],
      ["print", null, null, "p{color:blue}"],
      [null, "text/x-tpl", null, "{{ a }}"],
      [null, null, "alt", "p{color:green}"],
      [null, null, null, "h1{color:black}\n\nh2{color:black}"],
    ]);
    expect(render).toEqual(preview);
  });

  it("keeps a composition's print style print-only in preview and render", async () => {
    const dir = project({
      "index.html": shell(
        `<main data-composition-id="main" data-start="0" data-width="320" data-height="180" data-duration="1">
          <section data-composition-id="card" data-composition-src="card.html" data-start="0" data-duration="1"></section>
        </main>`,
      ),
      "card.html": `<template id="card-template"><article data-composition-id="card" data-width="320" data-height="180">
        <style media="print">.card-p{color:blue}</style><p class="card-p">x</p></article></template>`,
    });
    const printCss = (html: string) =>
      [
        ...new DOMParser()
          .parseFromString(html, "text/html")
          .querySelectorAll('style[media="print"]'),
      ]
        .map((el) => el.textContent)
        .join("\n");
    expect(printCss(await bundleToSingleHtml(dir))).toMatch(/\.card-p\{color:blue\}/);
    const render = await compileForRender(dir, join(dir, "index.html"), join(dir, ".downloads"), {
      allowSystemFontCapture: false,
    });
    expect(printCss(render.html)).toMatch(/\.card-p\{color:blue\}/);
  });

  it("emits conditional composition styles and links as their own elements in preview and render", async () => {
    const host = (id: string) =>
      `<section data-composition-id="${id}" data-composition-src="${id}.html" data-start="0" data-duration="1"></section>`;
    const comp = (id: string, inner: string) =>
      `<template id="${id}-template"><article data-composition-id="${id}" data-width="320" data-height="180">${inner}<p class="p${id}">x</p></article></template>`;
    const dir = project({
      "index.html": shell(
        `<main data-composition-id="main" data-start="0" data-width="320" data-height="180" data-duration="1">
          ${["a", "b", "c", "d"].map(host).join("")}</main>`,
      ),
      "a.html": comp("a", `<style media="(max-width: 10px">.pa{color:blue}</style>`),
      "b.html": comp("b", `<style>.pb{color:green}</style>`),
      "c.html": comp("c", `<style media="screen">@import "local.css"; .pc{color:red}</style>`),
      "d.html": comp(
        "d",
        `<style title="alt">.pd{color:black}</style><link rel="stylesheet" href="d.css" media="print" title="alt">`,
      ),
      "local.css": ".q{color:green}",
      "d.css": ".pd{color:white}",
    });
    const head = (html: string) => {
      const doc = new DOMParser().parseFromString(html, "text/html");
      const styles = [...doc.head.querySelectorAll("style")]
        .filter((el) => /\.p[a-d]\b/.test(el.textContent ?? ""))
        .map((el) => ({
          media: el.getAttribute("media"),
          title: el.getAttribute("title"),
          css: (el.textContent ?? "").trim(),
        }));
      const links = [...doc.head.querySelectorAll('link[rel="stylesheet"]')].map((el) => ({
        media: el.getAttribute("media"),
        title: el.getAttribute("title"),
      }));
      return { styles, links };
    };
    const preview = head(await bundleToSingleHtml(dir));
    const render = head(
      (
        await compileForRender(dir, join(dir, "index.html"), join(dir, ".downloads"), {
          allowSystemFontCapture: false,
        })
      ).html,
    );
    const find = (id: string) => preview.styles.find((style) => style.css.includes(`.p${id}{`));
    expect(find("a")?.media).toBe("(max-width: 10px");
    expect(find("a")?.css).not.toContain(".pb{");
    expect(find("b")).toMatchObject({ media: null, title: null });
    expect(find("c")?.media).toBe("screen");
    expect(find("c")?.css.startsWith('@import "local.css"')).toBe(true);
    expect(find("d")).toMatchObject({ media: null, title: "alt" });
    expect(preview.links).toEqual([{ media: "print", title: "alt" }]);
    expect(render).toEqual(preview);
  });

  it("keeps each composition's link to a shared file under its own condition in preview, render and mount", async () => {
    const url = "https://cdn.example/shared.css";
    const host = (id: string) =>
      `<section data-composition-id="${id}" data-composition-src="${id}.html" data-start="0" data-duration="1"></section>`;
    const comp = (id: string, attrs: string) =>
      `<template id="${id}-template"><article data-composition-id="${id}" data-width="320" data-height="180"><link rel="stylesheet" href="${url}"${attrs}><p>x</p></article></template>`;
    const files = {
      "index.html": shell(
        `<main data-composition-id="main" data-start="0" data-width="320" data-height="180" data-duration="1">
          ${["a", "b", "c"].map(host).join("")}</main>`,
        `<link rel="stylesheet" href="${url}" title="alt">`,
      ),
      "a.html": comp("a", ' media="print"'),
      "b.html": comp("b", ""),
      "c.html": comp("c", ' media="print"'),
    };
    const dir = project(files);
    const links = (head: ParentNode) =>
      [...head.querySelectorAll(`link[href="${url}"]`)].map((el) => ({
        media: el.getAttribute("media"),
        title: el.getAttribute("title"),
      }));
    const parsedHead = (html: string) => new DOMParser().parseFromString(html, "text/html").head;
    const expected = [
      { media: null, title: "alt" },
      { media: "print", title: null },
      { media: null, title: null },
    ];
    expect(links(parsedHead(await bundleToSingleHtml(dir)))).toEqual(expected);
    const render = await compileForRender(dir, join(dir, "index.html"), join(dir, ".downloads"), {
      allowSystemFontCapture: false,
    });
    expect(links(parsedHead(render.html))).toEqual(expected);
    await mountContract(dir, files["index.html"]);
    expect(links(document.head)).toEqual(expected);
  });

  it("keeps legacy end/layer timing semantically identical", async () => {
    const result = await contracts({
      "index.html":
        shell(`<main data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="5">
        <div id="legacy" class="clip" data-start="1.5" data-end="4" data-layer="2">Legacy timing</div>
      </main>`),
    });
    expect(result.render).toEqual(result.preview);
  });

  it("keeps flattened sub-composition identity and variable bootstrap identical", async () => {
    const result = await contracts({
      "index.html":
        shell(`<main data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="6">
        <section id="card-host" data-composition-id="card" data-composition-src="compositions/card.html"
          data-start="1" data-duration="3" data-variable-values='{"title":"Pro"}'></section>
      </main>`),
      "compositions/card.html": `<template id="card-template">
        <article data-composition-id="card" data-width="800" data-height="600">
          <h2 id="card-title" class="parity-card">Card</h2>
          <style>@font-face { font-family: ParityBody; src: url(data:font/woff2;base64,d09GMgAB) format("woff2"); }
          .parity-card { --parity-contract: 2; font-family: ParityBody, sans-serif; }</style>
        </article>
      </template>
      <script>window.__timelines = window.__timelines || {};</script>`,
    });
    expect(result.render).toEqual(result.preview);
  });
});

const FONT_FACE = `@font-face { font-family: ParityBody; src: url(data:font/woff2;base64,d09GMgAB) format("woff2"); }`;

const anonymousCardHost = (body: string) => ({
  "index.html":
    shell(`<main data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="6">
      <section id="card-host" data-composition-src="compositions/card.html"
        data-start="1" data-duration="3"></section>
    </main>`),
  "compositions/card.html": body,
});

const cardHost = (body: string) => ({
  "index.html":
    shell(`<main data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="6">
      <section id="card-host" data-composition-id="card" data-composition-src="compositions/card.html"
        data-start="1" data-duration="3"></section>
    </main>`),
  "compositions/card.html": body,
});

/**
 * Every fixture here mounts a sub-composition, because the mount path only runs
 * for one. The set has to keep covering the shape that broke — see the
 * assertion below, which fails if a refactor quietly drops it.
 */
const MOUNT_PARITY_FIXTURES: { name: string; files: Record<string, string> }[] = [
  {
    name: "assets authored as siblings of the composition root",
    files: cardHost(`<template id="card-template">
      <style>${FONT_FACE}
      .parity-card { --parity-contract: 3; font-family: ParityBody, sans-serif; }</style>
      <article id="card-root" data-composition-id="card" data-width="800" data-height="600">
        <h2 class="parity-card">Card</h2>
      </article>
    </template>`),
  },
  {
    name: "assets authored inside the composition root",
    files: cardHost(`<template id="card-template">
      <article id="card-root" data-composition-id="card" data-width="800" data-height="600">
        <style>${FONT_FACE}
        .parity-card { --parity-contract: 4; font-family: ParityBody, sans-serif; }</style>
        <h2 class="parity-card">Card</h2>
      </article>
    </template>`),
  },
  {
    name: "a TEMPLATED composition hoisting a head stylesheet link",
    // The compiler used to hoist a <link> only for a non-templated
    // composition, so a templated one's webfont survived preview (the mount
    // path always hoisted) and vanished from the render.
    files: cardHost(`<!doctype html><html><head>
      <link rel="preconnect" href="https://fonts.example.com" />
      </head><body>
      <template id="card-template">
        <style>${FONT_FACE}
        .parity-card { --parity-contract: 6; font-family: ParityBody, sans-serif; }</style>
        <article id="card-root" data-composition-id="card" data-width="800" data-height="600">
          <h2 class="parity-card">Card</h2>
        </article>
      </template>
      </body></html>`),
  },
  {
    name: "an anonymous host scoping to the id its content declares",
    // A host naming no composition id. The mount path used to drop the
    // content in whole and unscoped, so this composition's CSS landed on the
    // host document at large; the compiler has always fallen back to the
    // first declared root and scoped to it.
    files: anonymousCardHost(`<template id="card-template">
      <style>${FONT_FACE}
      .parity-card { --parity-contract: 7; font-family: ParityBody, sans-serif; }</style>
      <article id="card-root" data-composition-id="card" data-width="800" data-height="600">
        <h2 class="parity-card">Card</h2>
      </article>
    </template>`),
  },
  {
    name: "a full-document composition hoisting a head stylesheet link",
    files: cardHost(`<!doctype html><html><head>
      <link rel="preconnect" href="https://fonts.example.com" />
      <style>${FONT_FACE}
      .parity-card { --parity-contract: 5; font-family: ParityBody, sans-serif; }</style>
      </head><body>
      <article id="card-root" data-composition-id="card" data-width="800" data-height="600">
        <h2 class="parity-card">Card</h2>
      </article>
      </body></html>`),
  },
];

/** True when a sub-composition authors a `<style>`/`<script>` outside its root. */
function hasRootSiblingAssets(subCompositionHtml: string): boolean {
  const doc = new DOMParser().parseFromString(subCompositionHtml, "text/html");
  const template = doc.querySelector("template");
  const scope: ParentNode = template ? template.content : doc.body;
  const root = scope.querySelector("[data-composition-id]");
  const assets = Array.from(scope.querySelectorAll("style, script"));
  return assets.length > 0 && assets.some((asset) => !root?.contains(asset));
}

const subCompositions = (files: Record<string, string>) =>
  Object.entries(files)
    .filter(([path]) => path !== "index.html")
    .map(([, content]) => content);

/**
 * The runtime's assembly is not a compiler, so two contract fields are outside
 * what this arm gates, and are asserted rather than compared:
 *
 * - `runtimeBootstrap` / `variableBootstrap` — the runtime IIFE and the variable
 *   bootstrap script are injected by the player and the producer AROUND a mount,
 *   never by `loadCompositions`. Comparing them would compare harnesses.
 *
 * Nothing else is excluded. The templated-head-`<link>` and anonymous-host
 * divergences are gated by fixtures above. Two divergences remain ungated HERE rather than
 * unfixed — an inline `<head>` script and the split between the CSS scope id
 * and the script scope id both live in script bodies, and this contract
 * carries no script-body field. Their gates are the unit suites in
 * `packages/core/src/{compiler,runtime}`.
 */
function assembledContract(contract: ParityContract) {
  const { runtimeBootstrap: _runtime, variableBootstrap: _variables, ...assembled } = contract;
  return assembled;
}

describe("mount/compile assembly parity", () => {
  it("keeps a fixture set that still covers the shape the mount path used to drop", () => {
    expect(MOUNT_PARITY_FIXTURES.length).toBeGreaterThan(0);
    const siblingShaped = MOUNT_PARITY_FIXTURES.filter((fixture) =>
      subCompositions(fixture.files).some(hasRootSiblingAssets),
    );
    expect(siblingShaped.map((fixture) => fixture.name)).not.toHaveLength(0);
  });

  it.each(MOUNT_PARITY_FIXTURES)(
    "assembles $name identically on all three paths",
    async ({ files }) => {
      const result = await contracts(files);
      expect(result.render).toEqual(result.preview);
      expect(assembledContract(result.mount)).toEqual(assembledContract(result.preview));
      expect(result.mount.runtimeBootstrap).toBe(false);
      expect(result.mount.variableBootstrap).toBe(false);
    },
  );
});