Skip to content

Write HTML. Render video. Built for agents.

21.0 KB
Raw Blame
// @vitest-environment node
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it, onTestFinished } from "vitest";
import { gsapCdnDist } from "@hyperframes/core/gsap-cdn";
import { parseHTML } from "linkedom";
import { AFTER_FONTS_SCRIPT_TYPE } from "@hyperframes/core/compiler";
import { buildSubCompositionHtml, hasBaseElement } from "./subComposition";

function makeTempProject(files: Record<string, string>): string {
  const dir = mkdtempSync(join(tmpdir(), "hf-subcomp-preview-"));
  onTestFinished(() => rmSync(dir, { recursive: true, force: true }));
  for (const [rel, content] of Object.entries(files)) {
    const full = join(dir, rel);
    mkdirSync(join(full, ".."), { recursive: true });
    writeFileSync(full, content, "utf-8");
  }
  return dir;
}

describe("buildSubCompositionHtml", () => {
  it("loads the default gsap version when the project head has no gsap", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head><title>Host</title></head><body></body></html>`,
      "compositions/scene.html": `<div data-composition-id="scene" data-width="320" data-height="180"></div>`,
    });
    const html = buildSubCompositionHtml(dir, "compositions/scene.html", "/api/runtime.js");
    expect(html).toContain(`<script src="${gsapCdnDist()}gsap.min.js"></script>`);
  });

  it("adds the preview runtime even when the project head's script mentions a runtime file", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head><script>console.log("hyperframe.runtime.iife.js");</script></head><body></body></html>`,
      "compositions/scene.html": `<div data-composition-id="scene" data-width="320" data-height="180"></div>`,
    });
    const html = buildSubCompositionHtml(dir, "compositions/scene.html", "/api/runtime.js");
    expect(html).toContain(
      '<script data-hyperframes-preview-runtime="1" src="/api/runtime.js"></script>',
    );
    expect(html).toContain('console.log("hyperframe.runtime.iife.js")');
  });

  it("adds the preview base even when the project head's script mentions a <base>", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head><script>if (0) document.write('<base href="../">');</script></head><body></body></html>`,
      "compositions/scene.html": `<div data-composition-id="scene" data-width="320" data-height="180"></div>`,
    });
    const html = buildSubCompositionHtml(
      dir,
      "compositions/scene.html",
      "/api/runtime.js",
      "/api/projects/demo/preview/",
    );
    expect(html).toContain('<base href="/api/projects/demo/preview/">');
  });

  it("handles full HTML document compositions without nesting <html> in <body>", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html>
<html><head><title>Host</title></head><body></body></html>`,
      "compositions/map-block.html": `<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=1920, height=1080" />
    <link rel="stylesheet" href="../styles/theme.css" />
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <style>
      .map { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
      #root { position: relative; width: 1920px; height: 1080px; overflow: hidden; }
    </style>
  </head>
  <body>
    <div id="root" data-composition-id="map-block" data-width="1920" data-height="1080">
      <img class="map" src="assets/map.png" alt="" />
    </div>
    <script>
      window.__timelines = window.__timelines || {};
      window.__timelines["map-block"] = gsap.timeline({ paused: true });
    </script>
  </body>
</html>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/map-block.html",
      "/api/runtime.js",
      "/api/projects/demo/preview/",
    );

    expect(html).not.toBeNull();
    // Must not nest a full HTML document inside <body>
    const bodyStart = html!.indexOf("<body>");
    const afterBody = html!.slice(bodyStart);
    expect(afterBody).not.toContain("<html");
    expect(afterBody).not.toContain("<head>");
    // Composition styles must be in <head>, not lost
    expect(html).toContain(".map {");
    expect(html).toContain("#root {");
    // Image src preserved (no ../ rewrite needed for bare relative paths)
    expect(html).toContain('src="assets/map.png"');
    // Base tag for asset resolution
    expect(html).toContain('<base href="/api/projects/demo/preview/">');
    // GSAP from the composition's own <head> must be preserved
    expect(html).toContain("[email protected]");
    // Body script content preserved
    expect(html).toContain('__timelines["map-block"]');
    // <link> and <meta> from composition head must not be dropped
    expect(html).toContain('rel="stylesheet"');
    expect(html).toContain('href="styles/theme.css"');
    expect(html).toContain('name="viewport"');
    // <html lang="en"> attribute forwarded to the output
    expect(html).toContain('lang="en"');
  });

  it("keeps an installed block's <html> variables though a marker comment precedes the doctype", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html>
<html><head></head><body></body></html>`,
      "compositions/blk.html": `<!-- hyperframes-registry-item: blk -->
<!doctype html>
<html lang="en" data-composition-variables='[{"id":"image1","type":"image","default":"assets/blk/one.jpg"}]'>
  <body>
    <div id="root" data-composition-id="blk" data-width="1920" data-height="1080"></div>
  </body>
</html>`,
    });

    const html = buildSubCompositionHtml(dir, "compositions/blk.html", "/api/runtime.js", "/p/");

    const body = html!.indexOf("<body");
    expect(html!.slice(0, body)).toContain("data-composition-variables=");
    expect(html!.slice(body)).not.toContain("<html");
  });

  it.each([
    ["a template", (body: string) => `<template>${body}</template>`],
    ["a full document", (body: string) => `<!doctype html><html><body>${body}</body></html>`],
    ["a fragment", (body: string) => body],
  ])("defers the scripts of %s composition until fonts, but not the preview's own", (_, wrap) => {
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "compositions/card.html": wrap(
        `<div data-composition-id="card" data-width="400" data-height="300"><p>Hi</p>` +
          `<script>window.CARD = 1;</script><script type="module">window.CARD_MODULE = 1;</script></div>`,
      ),
    });

    const html = buildSubCompositionHtml(dir, "compositions/card.html", "/api/runtime.js")!;
    const types = [...parseHTML(html).document.querySelectorAll("script")].map((el) => [
      el.textContent?.trim() || el.getAttribute("src"),
      el.getAttribute("type"),
    ]);
    expect(types).toEqual([
      ["/api/runtime.js", null],
      [`${gsapCdnDist()}gsap.min.js`, null],
      ["window.__timelines=window.__timelines||{};", null],
      ["window.CARD = 1;", AFTER_FONTS_SCRIPT_TYPE],
      ["window.CARD_MODULE = 1;", `${AFTER_FONTS_SCRIPT_TYPE}+module`],
    ]);
  });

  it("handles raw fragment compositions (no template, no full document)", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html>
<html><head><title>Host</title></head><body></body></html>`,
      "compositions/card.html": `<div data-composition-id="card" data-width="400" data-height="300">
  <img src="../icon.svg" alt="" />
  <p>Hello</p>
</div>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/card.html",
      "/api/runtime.js",
      "/api/projects/demo/preview/",
    );

    expect(html).not.toBeNull();
    expect(html).toContain('<base href="/api/projects/demo/preview/">');
    // ../icon.svg from compositions/ rewrites to icon.svg at project root
    expect(html).toContain('src="icon.svg"');
    expect(html).not.toContain('src="../icon.svg"');
    expect(html).toContain("<p>Hello</p>");
  });

  it("rewrites sub-composition asset paths against the project root preview base", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html>
<html><head><title>Test</title></head><body></body></html>`,
      "compositions/hero.html": `<template id="hero-template">
  <div data-composition-id="hero" data-width="1920" data-height="1080">
    <img src="../logo.png" alt="Logo" />
    <div style="background-image: url('../poster.png')"></div>
    <style>
      @font-face {
        font-family: "Brand Sans";
        src: url("../fonts/brand.woff2") format("woff2");
      }
    </style>
  </div>
</template>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/hero.html",
      "/api/runtime.js",
      "/api/projects/demo/preview/",
    );

    expect(html).toContain('<base href="/api/projects/demo/preview/">');
    expect(html).toContain('src="logo.png"');
    expect(html).toContain("background-image: url('poster.png')");
    expect(html).toContain('url("fonts/brand.woff2")');
    expect(html).not.toContain('src="../logo.png"');
    expect(html).not.toContain("url('../poster.png')");
    expect(html).not.toContain('url("../fonts/brand.woff2")');
  });

  it("promotes the <template>'s data-composition-id onto the root element when the content lacks one", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "compositions/frames/02-music.html": `<template data-composition-id="02-music">
  <style>#music-scene { background: #121212; }</style>
  <div id="music-scene" class="clip" data-start="0" data-duration="3.213" data-track-index="0">
    <div id="music-headline">ready when you are.</div>
  </div>
  <script>
    window.__timelines = window.__timelines || {};
    window.__timelines["02-music"] = gsap.timeline({ paused: true });
  </script>
</template>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/frames/02-music.html",
      "/api/runtime.js",
    );

    // Root rendered element gains the id so the runtime can bind the timeline
    // (attribute order is serializer-dependent, so match the tag as a whole).
    expect(html).toMatch(
      /<div\b(?=[^>]*\sid="music-scene")(?=[^>]*\sdata-composition-id="02-music")[^>]*>/,
    );
    // The <style>/<script> siblings must NOT receive it.
    expect(html).not.toMatch(/<style[^>]*data-composition-id/i);
    expect(html).not.toMatch(/<script[^>]*data-composition-id/i);
  });

  it("extracts the real <template> even when a head comment mentions the literal text <template>", () => {
    // Regression: a greedy /<template>([\s\S]*)<\/template>/ regex latches onto
    // the "<template>" inside the head comment, mis-slicing the capture so the
    // real content stays wrapped in an inert <template> in the output — leaving
    // the preview with no [data-composition-id] element and rendering blank.
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "compositions/frames/03-force-pair.html": `<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <!-- head is metadata only; the HF runtime clones ONLY <template> contents -->
  </head>
  <body>
    <template>
      <style>#fp-root { width: 1920px; height: 1080px; }</style>
      <div id="fp-root" data-composition-id="03-force-pair" data-width="1920" data-height="1080">
        <div class="headline">forces come in pairs</div>
      </div>
      <script>
        window.__timelines = window.__timelines || {};
        window.__timelines["03-force-pair"] = gsap.timeline({ paused: true });
      </script>
    </template>
  </body>
</html>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/frames/03-force-pair.html",
      "/api/runtime.js",
      "/api/projects/demo/preview/",
    );

    expect(html).not.toBeNull();
    // The real composition content is rendered into <body> directly...
    expect(html).toContain('data-composition-id="03-force-pair"');
    expect(html).toContain("forces come in pairs");
    expect(html).toContain('__timelines["03-force-pair"]');
    // ...and is NOT re-wrapped in an inert <template> (which the browser would
    // never render). The comment fragment must not leak through either.
    const bodyStart = html!.indexOf("<body>");
    const body = html!.slice(bodyStart);
    expect(body).not.toContain("<template");
    expect(body).not.toContain("clones ONLY");
  });

  it("escapes #id selectors whose id starts with a digit so the rule is not dropped", () => {
    // A CSS ident can't start with a digit, so `#01-wall { ... }` is an invalid
    // selector and the browser drops the whole rule — the root loses its size and
    // background and a standalone preview renders blank. Escape it to a valid form.
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "compositions/frames/01-wall.html": `<template>
  <div id="01-wall" data-composition-id="01-wall" data-start="0" data-duration="5.5" data-track-index="0">
    <style>
      #01-wall { position: absolute; inset: 0; width: 1920px; height: 1080px; background-color: #F0EBDE; }
      .arrow { background: #1F2BE0; color: #1A2B3C; }
    </style>
    <div class="arrow">action</div>
  </div>
</template>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/frames/01-wall.html",
      "/api/runtime.js",
    );

    expect(html).not.toBeNull();
    // The invalid `#01-wall` selector is rewritten to its escaped, valid form.
    expect(html).toContain("#\\30 1-wall {");
    expect(html).not.toMatch(/#01-wall\s*\{/);
    // Digit-leading hex color VALUES (not element ids) must be left untouched.
    expect(html).toContain("background: #1F2BE0;");
    expect(html).toContain("color: #1A2B3C;");
    // The element's id attribute itself is unchanged (only the selector is escaped).
    expect(html).toContain('id="01-wall"');
  });

  it("does not add a duplicate data-composition-id when the root element already has one", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "compositions/frames/04-allinone.html": `<template data-composition-id="04-allinone">
  <div id="c04" data-composition-id="04-allinone" data-start="0" data-duration="5.695" data-track-index="0">
    <div class="headline">all in one app.</div>
  </div>
</template>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/frames/04-allinone.html",
      "/api/runtime.js",
    );
    const occurrences = html?.match(/data-composition-id="04-allinone"/g) ?? [];
    expect(occurrences).toHaveLength(1);
  });

  it("escapes every digit-leading #id selector when several appear in one composition", () => {
    // The fix iterates over all digit-leading ids present on elements; pin that
    // a second id in the same document is escaped too, not just the first.
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "compositions/frames/01-wall.html": `<template>
  <div id="01-wall" data-composition-id="01-wall" data-start="0" data-duration="4" data-track-index="0">
    <style>
      #01-wall { width: 1920px; height: 1080px; }
      #02-music { color: #1F2BE0; }
    </style>
    <div id="02-music">two</div>
  </div>
</template>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/frames/01-wall.html",
      "/api/runtime.js",
    );

    expect(html).not.toBeNull();
    expect(html).toContain("#\\30 1-wall {");
    expect(html).toContain("#\\30 2-music {");
    expect(html).not.toMatch(/#01-wall\s*\{/);
    expect(html).not.toMatch(/#02-music\s*\{/);
    // The hex color value is still left untouched.
    expect(html).toContain("color: #1F2BE0;");
  });

  it("escapes a digit-leading #id inside compound and combinator selectors", () => {
    // Only the leading-digit id token is escaped; the descendant/combinator and
    // pseudo-class tail must be preserved verbatim.
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "compositions/frames/01-wall.html": `<template>
  <div id="01-wall" data-composition-id="01-wall" data-start="0" data-duration="4" data-track-index="0">
    <style>
      #01-wall .child > span { color: red; }
      #01-wall:hover { opacity: 1; }
    </style>
    <div class="child"><span>x</span></div>
  </div>
</template>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/frames/01-wall.html",
      "/api/runtime.js",
    );

    expect(html).not.toBeNull();
    expect(html).toContain("#\\30 1-wall .child > span {");
    expect(html).toContain("#\\30 1-wall:hover {");
    // No unescaped form survives.
    expect(html).not.toContain("#01-wall .child");
    expect(html).not.toContain("#01-wall:hover");
  });

  it("leaves the DOM untouched when the <template> has no data-composition-id to promote", () => {
    // No data-composition-id on the <template> tag → promoteTemplateCompositionId
    // returns early. The content's own id must be the only one, with nothing
    // injected onto the root or its siblings.
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "compositions/frames/05-plain.html": `<template>
  <style>#c05 { width: 1920px; height: 1080px; }</style>
  <div id="c05" data-composition-id="05-plain" data-start="0" data-duration="3" data-track-index="0">
    <div class="headline">plain</div>
  </div>
</template>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "compositions/frames/05-plain.html",
      "/api/runtime.js",
    );

    expect(html).not.toBeNull();
    // The authored id is preserved and is the ONLY data-composition-id — promote
    // didn't fabricate one (no <template> id to copy) or duplicate it.
    const occ = html?.match(/data-composition-id="05-plain"/g) ?? [];
    expect(occ).toHaveLength(1);
    expect(html).toMatch(
      /<div\b(?=[^>]*\sid="c05")(?=[^>]*\sdata-composition-id="05-plain")[^>]*>/,
    );
    // The <style> sibling was not tagged.
    expect(html).not.toMatch(/<style[^>]*data-composition-id/i);
  });

  // Regression guard for the dark/illegible styleframe thumbnail: a composition
  // in a subdirectory that references a SIBLING file (`_shared.css`, not
  // `../_shared.css`) used to be served unrewritten under the project-root
  // <base>, so the browser requested /preview/_shared.css → 404. The frame then
  // rendered unstyled, and the thumbnailer's transparent-body fallback painted
  // it dark navy with unreadable text.
  it("resolves same-directory asset refs against the composition's own directory", () => {
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "design/styleframes/_shared.css": `.stage { background: #fff; }`,
      "design/styleframes/frame-01.png": `png`,
      "design/styleframes/frame-01.html": `<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="stylesheet" href="_shared.css" />
    <style>.stage { background-image: url("frame-01.png"); }</style>
  </head>
  <body><div class="stage"><img src="frame-01.png" alt="" /></div></body>
</html>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "design/styleframes/frame-01.html",
      "/api/runtime.js",
      "/api/projects/demo/preview/",
    );

    expect(html).not.toBeNull();
    expect(html).toContain('href="design/styleframes/_shared.css"');
    expect(html).toContain('src="design/styleframes/frame-01.png"');
    expect(html).toContain('url("design/styleframes/frame-01.png")');
    expect(html).not.toContain('href="_shared.css"');
  });

  it("leaves project-root-relative asset refs alone when no sibling file exists", () => {
    // Registry blocks are installed into a subdirectory but reference assets at
    // the project root (`assets/logo.png`). Those already resolve correctly
    // under the project-root <base> and must not be re-pointed at the block dir.
    const dir = makeTempProject({
      "index.html": `<!doctype html><html><head></head><body></body></html>`,
      "assets/logo.png": `png`,
      "blocks/hero.html": `<div data-composition-id="hero"><img src="assets/logo.png" alt="" /></div>`,
    });

    const html = buildSubCompositionHtml(
      dir,
      "blocks/hero.html",
      "/api/runtime.js",
      "/api/projects/demo/preview/",
    );

    expect(html).toContain('src="assets/logo.png"');
  });
});

describe("hasBaseElement", () => {
  it("counts a real <base> element and nothing that only mentions one", () => {
    expect(hasBaseElement(`<head><base href="/cdn/"></head>`)).toBe(true);
    expect(hasBaseElement(`<head><BASE HREF="/cdn/"></head>`)).toBe(true);
    for (const html of [
      `<head><script>document.write('<base href="../">')</script></head>`,
      `<head><script >x = "<base>";</script ></head>`,
      `<head><!-- <base href="x"> --></head>`,
      `<head><template><base href="t"></template></head>`,
      `<head><basefont></head>`,
    ]) {
      expect(hasBaseElement(html)).toBe(false);
    }
  });
});