Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { describe, expect, it } from "vitest";
import { parseHTML } from "linkedom";
import { ensureExternalLinkTag, inlineSubCompositions } from "./inlineSubCompositions";
import { readDeclaredDefaults, parseHostVariableValues } from "../runtime/getVariables";
import { JSDOM } from "jsdom";
// Fixtures reference GSAP CDN but are never loaded in a real browser — resolveHtml is mocked.
/**
* Minimal sub-composition HTML that uses `#intro` as its CSS and GSAP scope.
* This is the pattern that breaks when the producer path strips the inner root.
*/
const SUB_COMP_HTML = `<template id="intro-template">
<div id="intro" data-composition-id="intro" data-width="1920" data-height="1080">
<div class="title" style="opacity:0;">HELLO WORLD</div>
<style>
#intro { position:relative; width:1920px; height:1080px; background:#111; }
#intro .title { font-size:120px; color:#fff; }
</style>
<script>
(function() {
window.__timelines = window.__timelines || {};
var tl = gsap.timeline({ paused: true });
tl.fromTo('#intro .title', { opacity:0 }, { opacity:1, duration:0.5 }, 0.2);
window.__timelines['intro'] = tl;
})();
</script>
</div>
</template>`;
function makeHostDocument(compId: string) {
const { document } = parseHTML(`<!DOCTYPE html>
<html><body>
<div data-composition-id="main">
<div data-composition-id="${compId}" data-composition-src="intro.html"
data-start="0" data-duration="4" data-track-index="0"></div>
</div>
</body></html>`);
return document;
}
describe("inlineSubCompositions – #ID selector scoping divergence", () => {
it.each([
{ label: "empty", html: "" },
{ label: "whitespace-only", html: " \n \t " },
{
label: "valid-parse-empty-body",
html: "<!doctype html><html><head></head><body></body></html>",
},
// linkedom's parseHTML("just some text") returns documentElement === null.
// Any code that then touches .head/.body (as linkedom's own internals do)
// throws "Cannot destructure property 'firstElementChild' of
// 'documentElement' as it is null" — the #1 raw crash in production
// telemetry. Must be skipped gracefully, not crash.
{ label: "malformed non-HTML text", html: "just some plain text, no tags at all" },
])("skips $label sub-composition files gracefully", ({ html }) => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const missing: string[] = [];
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => html,
parseHtml: (h) => parseHTML(h).document,
onMissingComposition: (src) => missing.push(src),
});
expect(missing).toEqual(["intro.html"]);
expect(result.styles).toHaveLength(0);
expect(result.scripts).toHaveLength(0);
});
it("hoists stylesheet and preconnect links from a bare fragment", () => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => `<link rel="stylesheet" href="theme.css">
<link rel="preconnect" href="https://fonts.example" crossorigin>
<link rel="icon" href="favicon.ico">
<div data-composition-id="intro"><link rel="stylesheet" href="nested.css"><link rel="icon" href="keep.ico"><div class="title">Hello</div></div>`,
parseHtml: (html) => parseHTML(html).document,
});
expect(result.externalLinks).toEqual([
{ href: "theme.css", rel: "stylesheet", crossorigin: undefined },
{ href: "https://fonts.example", rel: "preconnect", crossorigin: "" },
{ href: "nested.css", rel: "stylesheet", crossorigin: undefined },
]);
expect(host.querySelectorAll('link[rel="stylesheet"]')).toHaveLength(0);
expect(host.querySelectorAll('link[rel="icon"]')).toHaveLength(1);
});
it("passes the failure reason through to onMissingComposition", () => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const reasons: Array<string | undefined> = [];
inlineSubCompositions(document, [host], {
resolveHtml: () => "",
parseHtml: (h) => parseHTML(h).document,
onMissingComposition: (_src, reason) => reasons.push(reason),
});
expect(reasons).toHaveLength(1);
expect(reasons[0]).toContain("empty");
});
it("producer path (no flattenInnerRoot): strips inner root, losing #id attribute", () => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP_HTML,
parseHtml: (html) => parseHTML(html).document,
});
// The producer path takes innerHTML when compId matches, stripping the
// wrapper <div id="intro" ...>. The host element should NOT contain a
// child with id="intro" — the id attribute is lost.
const innerRootById = host.querySelector("#intro");
expect(innerRootById).toBeNull();
// The host itself still has data-composition-id="intro" (from the
// original markup), but no element inside has id="intro".
expect(host.getAttribute("data-composition-id")).toBe("intro");
// CSS was scoped: #intro selectors should be rewritten to use
// data-hf-authored-id attribute selector so they still resolve.
const scopedCss = result.styles.map((style) => style.css).join("\n");
expect(scopedCss).toContain('[data-hf-authored-id="intro"]');
expect(scopedCss).not.toContain("#intro");
});
it("producer path: scoped CSS rewrites #id selectors to [data-hf-authored-id] attribute", () => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP_HTML,
parseHtml: (html) => parseHTML(html).document,
});
// The CSS scoper rewrites `#intro` to `[data-hf-authored-id="intro"]`
// so that the selector resolves against the flattened structure.
const scopedCss = result.styles.map((style) => style.css).join("\n");
expect(scopedCss).toContain('[data-hf-authored-id="intro"]');
expect(scopedCss).toContain('[data-hf-authored-id="intro"] .title');
});
it("producer path: scoped scripts rewrite #intro selectors for GSAP targets", () => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP_HTML,
parseHtml: (html) => parseHTML(html).document,
});
// The wrapped script should contain the authored root id normalization
// logic so that runtime querySelector('#intro .title') maps to the
// data-hf-authored-id attribute selector.
const wrappedScript = result.scripts.join("\n");
expect(wrappedScript).toContain("__hfAuthoredRootId");
expect(wrappedScript).toContain('"intro"');
});
it("maps a template-local timeline id onto a differently named mount", () => {
const document = makeHostDocument("captions-comp");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const captionsHtml = `<template id="captions-template">
<div data-composition-id="captions" data-width="1920" data-height="1080">
<style>[data-composition-id="captions"] { opacity: 1; }</style>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["captions"] = { duration: 4 };
</script>
</div>
</template>`;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => captionsHtml,
parseHtml: (html) => parseHTML(html).document,
});
expect(host.getAttribute("data-composition-id")).toBe("captions-comp");
expect(host.querySelector('[data-composition-id="captions"]')).not.toBeNull();
expect(result.styles.map((style) => style.css).join("\n")).toContain(
'[data-composition-id="captions-comp"]',
);
const wrappedScript = result.scripts.join("\n");
expect(wrappedScript).toContain('var __hfCompId = "captions"');
expect(wrappedScript).toContain('var __hfTimelineCompId = "captions-comp"');
});
it("bundler path (with flattenInnerRoot): preserves inner root as a child element", () => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
// Simulate the bundler's flattenInnerRoot: clone the element, add
// data-hf-authored-id, strip timing attrs (simplified here).
function flattenInnerRoot(innerRoot: Element): Element {
const clone = innerRoot.cloneNode(true) as Element;
const authoredId = clone.getAttribute("id");
if (authoredId) {
clone.setAttribute("data-hf-authored-id", authoredId);
clone.removeAttribute("id");
}
clone.removeAttribute("data-start");
clone.removeAttribute("data-duration");
return clone;
}
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP_HTML,
parseHtml: (html) => parseHTML(html).document,
flattenInnerRoot,
});
// With flattenInnerRoot, the inner root is preserved as a child of the
// host via outerHTML. The data-hf-authored-id attribute is present.
const authoredRoot = host.querySelector('[data-hf-authored-id="intro"]');
expect(authoredRoot).not.toBeNull();
// CSS is still rewritten to use the attribute selector.
const scopedCss = result.styles.map((style) => style.css).join("\n");
expect(scopedCss).toContain('[data-hf-authored-id="intro"]');
});
it("with flattenInnerRoot: restores data-composition-id on the wrapper for an anonymous host", () => {
// Regression test: a host mounted via data-composition-src with no
// data-composition-id of its own (an "anonymous" host). The composition
// styles its own root box via the bare composition-id selector and a
// script self-references it too — both need something in the render DOM
// to actually carry that id once flattenInnerRoot strips it from the
// wrapper by default.
const { document } = parseHTML(`<!DOCTYPE html>
<html><body>
<div data-composition-id="main">
<div data-composition-src="scoped-text.html" data-start="0" data-duration="3"></div>
</div>
</body></html>`);
const host = document.querySelector('[data-composition-src="scoped-text.html"]')!;
const scopedTextHtml = `<template id="scoped-text-template">
<div data-composition-id="scoped-text" data-width="1080" data-height="1920" data-duration="3">
<div class="label">Scoped Text Should Stay Styled</div>
<style>
[data-composition-id="scoped-text"] { display: flex; background: rgb(12, 12, 12); }
</style>
</div>
</template>`;
function flattenInnerRoot(innerRoot: Element): Element {
const clone = innerRoot.cloneNode(true) as Element;
clone.removeAttribute("data-composition-id");
clone.removeAttribute("data-start");
clone.removeAttribute("data-duration");
clone.setAttribute("data-hf-inner-root", "true");
return clone;
}
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => scopedTextHtml,
parseHtml: (html) => parseHTML(html).document,
flattenInnerRoot,
});
const wrapper = host.querySelector("[data-hf-inner-root]");
expect(wrapper?.getAttribute("data-composition-id")).toBe("scoped-text");
const scopedCss = result.styles.map((style) => style.css).join("\n");
expect(scopedCss).toContain("display: flex");
});
it("extracts <link> elements from sub-composition <head> with original rel and crossorigin", () => {
const subCompWithLinks = `<!doctype html>
<html><head>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Montserrat:wght@800&display=swap">
</head><body>
<div data-composition-id="captions" data-width="1920" data-height="1080">
<span>Hello</span>
</div>
</body></html>`;
const document = makeHostDocument("captions");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => subCompWithLinks,
parseHtml: (html) => parseHTML(html).document,
});
expect(result.externalLinks).toHaveLength(3);
expect(result.externalLinks[0]).toEqual({
href: "https://fonts.googleapis.com",
rel: "preconnect",
crossorigin: undefined,
});
expect(result.externalLinks[1]).toEqual({
href: "https://fonts.gstatic.com",
rel: "preconnect",
crossorigin: "",
});
expect(result.externalLinks[2]).toEqual({
href: "https://fonts.googleapis.com/css2?family=Montserrat:wght@800&display=swap",
rel: "stylesheet",
crossorigin: undefined,
});
});
it("collects an inline <head> script instead of discarding it", () => {
// The <head> loop had a `src` branch and no else, so an inline <head>
// script was silently dropped on render while the mount path executed it.
const subCompWithHeadScript = `<!doctype html>
<html><head>
<script>window.__headScriptRan = true;</script>
</head><body>
<div data-composition-id="intro" data-width="1920" data-height="1080"><span>Hi</span></div>
</body></html>`;
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => subCompWithHeadScript,
parseHtml: (html) => parseHTML(html).document,
});
expect(result.scripts.join("\n")).toContain("window.__headScriptRan = true;");
expect(result.scriptItems).toContainEqual({
kind: "inline",
content: expect.stringContaining("window.__headScriptRan = true;"),
});
});
it("hoists a <link> from a TEMPLATED sub-composition's head", () => {
// Hoisting used to be gated on the composition being non-templated, so a
// templated composition's webfont link was kept in preview (the mount path
// hoists unconditionally) and dropped from the render.
const templatedSubCompWithLink = `<!doctype html>
<html><head>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Montserrat">
</head><body>
<template id="intro-template">
<div data-composition-id="intro" data-width="1920" data-height="1080"><span>Hi</span></div>
</template>
</body></html>`;
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => templatedSubCompWithLink,
parseHtml: (html) => parseHTML(html).document,
});
expect(result.externalLinks).toEqual([
{
href: "https://fonts.googleapis.com/css2?family=Montserrat",
rel: "stylesheet",
crossorigin: undefined,
},
]);
});
it("emits one link for the same link in two sub-compositions", () => {
const subComp = `<!doctype html>
<html><head>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Montserrat:wght@800">
</head><body>
<div data-composition-id="cap1" data-width="1920" data-height="1080"><span>A</span></div>
</body></html>`;
const { document } = parseHTML(`<!DOCTYPE html>
<html><body>
<div data-composition-id="main">
<div data-composition-id="cap1" data-composition-src="cap1.html" data-start="0" data-duration="4" data-track-index="0"></div>
<div data-composition-id="cap2" data-composition-src="cap2.html" data-start="4" data-duration="4" data-track-index="1"></div>
</div>
</body></html>`);
const hosts = Array.from(document.querySelectorAll("[data-composition-src]"));
const result = inlineSubCompositions(document, hosts, {
resolveHtml: () => subComp,
parseHtml: (html) => parseHTML(html).document,
});
for (const link of result.externalLinks) ensureExternalLinkTag(document, link);
expect(
[...document.head.querySelectorAll("link")].map((el) => el.getAttribute("href")),
).toEqual(["https://fonts.googleapis.com/css2?family=Montserrat:wght@800"]);
});
it("propagates data-timeline-locked from inner root to host element", () => {
const lockedSubComp = `<!doctype html>
<html><head></head><body>
<div id="captions" data-composition-id="captions" data-timeline-locked data-width="1920" data-height="1080">
<span>Hello</span>
</div>
</body></html>`;
const document = makeHostDocument("captions");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
inlineSubCompositions(document, [host], {
resolveHtml: () => lockedSubComp,
parseHtml: (html) => parseHTML(html).document,
});
expect(host.hasAttribute("data-timeline-locked")).toBe(true);
});
it("producer path propagates data-hf-authored-id to host when inner root has id", () => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP_HTML,
parseHtml: (html) => parseHTML(html).document,
});
// The inner root's id="intro" is stripped (innerHTML), but the producer
// now propagates it as data-hf-authored-id on the host element so that
// rewritten #ID selectors ([data-hf-authored-id="intro"]) resolve.
expect(host.getAttribute("data-hf-authored-id")).toBe("intro");
// The original #intro element is still gone — innerHTML stripped it.
const introById = host.querySelector("#intro");
expect(introById).toBeNull();
expect(host.getAttribute("data-composition-id")).toBe("intro");
});
it("producer path: scoped CSS matches host element when both attributes coexist", () => {
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP_HTML,
parseHtml: (html) => parseHTML(html).document,
compoundAuthoredRoot: true,
});
// After inlining, the host has both data-composition-id and data-hf-authored-id.
// CSS selectors targeting the root must be compound (no space) so they match
// when both attributes are on the same element.
expect(host.getAttribute("data-composition-id")).toBe("intro");
expect(host.getAttribute("data-hf-authored-id")).toBe("intro");
const scopedCss = result.styles.map((style) => style.css).join("\n");
// Root-only selector: must be compound
expect(scopedCss).toMatch(/\[data-composition-id="intro"\]\[data-hf-authored-id="intro"\]/);
// Must NOT have a descendant combinator between the two attribute selectors
expect(scopedCss).not.toMatch(
/\[data-composition-id="intro"\]\s+\[data-hf-authored-id="intro"\]\s*\{/,
);
// Descendant selector: compound root + space + child
expect(scopedCss).toMatch(
/\[data-composition-id="intro"\]\[data-hf-authored-id="intro"\]\s+\.title/,
);
});
});
describe("inlineSubCompositions – variable defaults on a template sub-comp root div", () => {
const SUB_COMP_WITH_VAR = `<template id="card-template">
<div id="card" data-composition-id="card" data-width="1920" data-height="1080"
data-composition-variables='[{"id":"headline","type":"string","label":"Headline","default":"Hi there"}]'>
<h1 class="title" data-var-text="headline">Hi there</h1>
</div>
</template>`;
function hostDoc() {
const { document } = parseHTML(`<!DOCTYPE html><html><body>
<div data-composition-id="main">
<div data-composition-id="card" data-composition-src="card.html"
data-start="0" data-duration="4" data-track-index="0"></div>
</div></body></html>`);
return document;
}
it("aggregates defaults declared on the inner root div (template comps have no <html> to hold them)", () => {
const document = hostDoc();
const host = document.querySelector('[data-composition-src="card.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP_WITH_VAR,
parseHtml: (h) => parseHTML(h).document,
readVariableDefaults: readDeclaredDefaults,
parseHostVariables: parseHostVariableValues,
});
expect(result.variablesByComp["card"]).toMatchObject({ headline: "Hi there" });
});
it("lets a per-instance host value override the declared default", () => {
const document = hostDoc();
const host = document.querySelector('[data-composition-src="card.html"]')!;
host.setAttribute("data-variable-values", JSON.stringify({ headline: "Overridden" }));
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP_WITH_VAR,
parseHtml: (h) => parseHTML(h).document,
readVariableDefaults: readDeclaredDefaults,
parseHostVariables: parseHostVariableValues,
});
expect(result.variablesByComp["card"]).toMatchObject({ headline: "Overridden" });
});
});
describe("inlineSubCompositions – recursive host discovery", () => {
const MAX_NESTING_DEPTH = 20;
function compositionHtml(label: string, nestedSrcs: string[] = []) {
const nestedHosts = nestedSrcs
.map(
(src, index) =>
`<div data-composition-id="${label}-child-${index}" data-composition-src="${src}"></div>`,
)
.join("");
return `<template><div data-composition-id="${label}"><span data-level="${label}">${label}</span>${nestedHosts}</div></template>`;
}
function inlineFixture(rootHosts: string[], compositions: Record<string, string>) {
const { document } = parseHTML(`<!DOCTYPE html><html><body>
<main data-level="root">root</main>
${rootHosts
.map(
(src, index) =>
`<div data-composition-id="root-host-${index}" data-composition-src="${src}"></div>`,
)
.join("")}
</body></html>`);
const missing: Array<{ src: string; reason?: string }> = [];
inlineSubCompositions(
document,
Array.from(document.querySelectorAll("[data-composition-src]")),
{
resolveHtml: (src) => compositions[src] ?? null,
parseHtml: (html) => parseHTML(html).document,
onMissingComposition: (src, reason) => missing.push({ src, reason }),
},
);
return { document, missing };
}
it("inlines a three-level root -> A -> B chain", () => {
const { document, missing } = inlineFixture(["a.html"], {
"a.html": compositionHtml("A", ["b.html"]),
"b.html": compositionHtml("B"),
});
expect(document.querySelector('[data-level="root"]')?.textContent).toBe("root");
expect(document.querySelector('[data-level="A"]')?.textContent).toBe("A");
expect(document.querySelector('[data-level="B"]')?.textContent).toBe("B");
expect(missing).toEqual([]);
});
it("inlines a four-level root -> A -> B -> C chain", () => {
const { document, missing } = inlineFixture(["a.html"], {
"a.html": compositionHtml("A", ["b.html"]),
"b.html": compositionHtml("B", ["c.html"]),
"c.html": compositionHtml("C"),
});
expect(
Array.from(document.querySelectorAll("[data-level]")).map((element) => element.textContent),
).toEqual(["root", "A", "B", "C"]);
expect(missing).toEqual([]);
});
it("reports and leaves a direct circular reference uninlined", () => {
const { document, missing } = inlineFixture(["a.html"], {
"a.html": compositionHtml("A", ["a.html"]),
});
expect(document.querySelectorAll('[data-level="A"]')).toHaveLength(1);
expect(document.querySelector('[data-composition-src="a.html"]')).not.toBeNull();
expect(missing).toEqual([{ src: "a.html", reason: "circular composition reference" }]);
});
it("reports and leaves an indirect circular reference uninlined", () => {
const { document, missing } = inlineFixture(["a.html"], {
"a.html": compositionHtml("A", ["b.html"]),
"b.html": compositionHtml("B", ["a.html"]),
});
expect(document.querySelectorAll('[data-level="A"]')).toHaveLength(1);
expect(document.querySelectorAll('[data-level="B"]')).toHaveLength(1);
expect(document.querySelector('[data-composition-src="a.html"]')).not.toBeNull();
expect(missing).toEqual([{ src: "a.html", reason: "circular composition reference" }]);
});
it("inlines the same sub-composition in sibling branches", () => {
const { document, missing } = inlineFixture(["a.html"], {
"a.html": compositionHtml("A", ["shared.html", "shared.html"]),
"shared.html": compositionHtml("shared"),
});
expect(document.querySelectorAll('[data-level="shared"]')).toHaveLength(2);
expect(missing).toEqual([]);
});
it("allows the depth ceiling and stops only the branch one level beyond it", () => {
const compositions: Record<string, string> = {
"sibling.html": compositionHtml("sibling"),
};
for (const prefix of ["exact", "overflow"]) {
const length = prefix === "exact" ? MAX_NESTING_DEPTH : MAX_NESTING_DEPTH + 1;
for (let level = 1; level <= length; level += 1) {
const nextSrc = level < length ? [`${prefix}-${level + 1}.html`] : [];
compositions[`${prefix}-${level}.html`] = compositionHtml(`${prefix}-${level}`, nextSrc);
}
}
const { document, missing } = inlineFixture(
["exact-1.html", "overflow-1.html", "sibling.html"],
compositions,
);
expect(document.querySelector(`[data-level="exact-${MAX_NESTING_DEPTH}"]`)).not.toBeNull();
expect(document.querySelector(`[data-level="overflow-${MAX_NESTING_DEPTH}"]`)).not.toBeNull();
expect(document.querySelector(`[data-level="overflow-${MAX_NESTING_DEPTH + 1}"]`)).toBeNull();
expect(document.querySelector('[data-level="sibling"]')).not.toBeNull();
expect(missing).toEqual([
{
src: `overflow-${MAX_NESTING_DEPTH + 1}.html`,
reason: "nesting depth exceeded",
},
]);
});
});
describe("inlineSubCompositions – sub-composition asset paths", () => {
// Every asset ref a sub-composition in a subdirectory carries has to be
// re-pointed when its content moves into the project-root document. Hoisted
// <head> <link>/<script src> used to bypass the rewrite entirely (so even the
// documented `../` form escaped the project), and sibling refs (`_shared.css`)
// silently 404'd. Both render the frame unstyled.
const SUB_COMP = `<!doctype html>
<html><head>
<link rel="stylesheet" href="_shared.css">
<link rel="stylesheet" href="../shared/theme.css">
<script src="helper.js"></script>
<style>.badge { background-image: url("frame.png"); }</style>
</head><body>
<div data-composition-id="frame" data-width="1920" data-height="1080">
<img src="frame.png" alt="">
<div style="background-image: url('frame.png')"></div>
</div>
</body></html>`;
const PROJECT_FILES = [
"design/styleframes/_shared.css",
"design/styleframes/frame.png",
"design/styleframes/helper.js",
"design/shared/theme.css",
];
function inlineFrame() {
const { document } = parseHTML(`<!DOCTYPE html>
<html><body>
<div data-composition-id="main">
<div data-composition-id="frame" data-composition-src="design/styleframes/frame-01.html"
data-start="0" data-duration="4" data-track-index="0"></div>
</div>
</body></html>`);
const host = document.querySelector("[data-composition-src]")!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => SUB_COMP,
parseHtml: (html) => parseHTML(html).document,
rewriteInlineStyles: true,
assetExists: (path: string) => PROJECT_FILES.includes(path),
});
return { document, result };
}
it("rewrites hoisted <link> hrefs against the sub-composition dir", () => {
const { result } = inlineFrame();
const hrefs = result.externalLinks.map((l) => l.href);
expect(hrefs).toContain("design/styleframes/_shared.css");
expect(hrefs).toContain("design/shared/theme.css");
expect(hrefs).not.toContain("_shared.css");
expect(hrefs).not.toContain("../shared/theme.css");
});
it("rewrites hoisted external script srcs", () => {
const { result } = inlineFrame();
expect(result.externalScriptSrcs).toContain("design/styleframes/helper.js");
});
it("rewrites sibling refs in markup, hoisted CSS, and inline styles", () => {
const { document, result } = inlineFrame();
expect(document.querySelector("img")?.getAttribute("src")).toBe("design/styleframes/frame.png");
expect(result.styles.map((style) => style.css).join("\n")).toContain(
"design/styleframes/frame.png",
);
expect(document.querySelector("[style]")?.getAttribute("style")).toContain(
"design/styleframes/frame.png",
);
});
});
/**
* Mirror of the bundler's runtime-id assignment (`assignBundledRuntimeCompositionIds`
* in htmlBundler.ts): a host whose authored composition id appears more than
* once gets a document-unique `<id>__hf<n>` runtime id. Reproduced here rather
* than imported because htmlBundler.ts statically imports esbuild, which
* refuses to load inside a jsdom test realm on Windows.
*/
function assignTestRuntimeCompositionIds(
hosts: Element[],
): Map<Element, { authoredCompositionId: string | null; runtimeCompositionId: string | null }> {
const counts = new Map<string, number>();
for (const host of hosts) {
const id = host.getAttribute("data-composition-id");
if (id) counts.set(id, (counts.get(id) ?? 0) + 1);
}
const seen = new Map<string, number>();
const identities = new Map<
Element,
{ authoredCompositionId: string | null; runtimeCompositionId: string | null }
>();
for (const host of hosts) {
const authored = host.getAttribute("data-composition-id");
if (!authored) {
identities.set(host, { authoredCompositionId: null, runtimeCompositionId: null });
continue;
}
let runtime = authored;
if ((counts.get(authored) ?? 0) > 1) {
const index = (seen.get(authored) ?? 0) + 1;
seen.set(authored, index);
runtime = `${authored}__hf${index}`;
host.setAttribute("data-hf-original-composition-id", authored);
host.setAttribute("data-composition-id", runtime);
}
identities.set(host, { authoredCompositionId: authored, runtimeCompositionId: runtime });
}
return identities;
}
/** Inline `hostEntries` (each pointing at a source in `sources`) into one
* bundler-shaped document with runtime composition ids assigned. */
function inlineScenes(
sources: Record<string, string>,
hostEntries: Array<{ compId: string; src: string }>,
) {
const hostsMarkup = hostEntries
.map(
({ compId, src }, i) =>
`<div data-composition-id="${compId}" data-composition-src="${src}"
data-start="0" data-duration="4" data-track-index="${i}"></div>`,
)
.join("\n");
const { document } = parseHTML(`<!DOCTYPE html>
<html><body>
<div data-composition-id="main">${hostsMarkup}</div>
</body></html>`);
const hosts = Array.from(document.querySelectorAll("[data-composition-src]"));
const hostIdentityMap = assignTestRuntimeCompositionIds(hosts);
const result = inlineSubCompositions(document, hosts, {
resolveHtml: (src) => sources[src] ?? null,
parseHtml: (html) => parseHTML(html).document,
hostIdentityMap,
});
return { document, result };
}
describe("inlineSubCompositions – #3490 nested SVG id collisions", () => {
// Same shape as the issue repro: a composition-scoped clipPath, a <use>
// target, and a CSS filter, all hardcoded ids a catalog block or a scene
// author has no reason to think are unsafe to repeat.
function svgScene(compId: string, color: string): string {
return `<!DOCTYPE html><html><body><div id="${compId}" data-composition-id="${compId}" data-width="100" data-height="100">
<svg width="0" height="0">
<clipPath id="clip"><rect width="10" height="10"/></clipPath>
<symbol id="shape"><circle r="5" fill="${color}"/></symbol>
<filter id="fx"><feFlood flood-color="${color}"/></filter>
</svg>
<g class="clipped" clip-path="url(#clip)"><use class="shape" href="#shape"></use></g>
<div class="fx-target" style="filter:url(#fx)"></div>
<style>#${compId} .fx-target { filter: url(#fx); }</style>
</div></body></html>`;
}
it("gives two sibling scenes reusing #clip/#shape/#fx distinct, non-colliding ids", () => {
const { document, result } = inlineScenes(
{ "scene-a.html": svgScene("scene-a", "red"), "scene-b.html": svgScene("scene-b", "blue") },
[
{ compId: "scene-a", src: "scene-a.html" },
{ compId: "scene-b", src: "scene-b.html" },
],
);
// Exactly one "clip" survives verbatim (the first instance keeps its
// authored id) and no id repeats across the two scenes — the exact
// document-order collision the browser resolves incorrectly before this
// fix.
const allIds = Array.from(document.querySelectorAll("[id]")).map((el) => el.getAttribute("id"));
expect(allIds.filter((id) => id === "clip")).toHaveLength(1);
expect(new Set(allIds).size).toBe(allIds.length);
const [gA, gB] = Array.from(document.querySelectorAll("g.clipped"));
const [useA, useB] = Array.from(document.querySelectorAll("use.shape"));
const [fxA, fxB] = Array.from(document.querySelectorAll(".fx-target"));
const clipA = gA!.getAttribute("clip-path");
const clipB = gB!.getAttribute("clip-path");
expect(clipA).toMatch(/^url\(#.*clip\)$/);
expect(clipA).not.toBe(clipB);
const hrefA = useA!.getAttribute("href");
const hrefB = useB!.getAttribute("href");
expect(hrefA).toMatch(/^#.*shape$/);
expect(hrefA).not.toBe(hrefB);
// <use>/clip-path must resolve to the id actually declared in THIS
// scene's <svg>, not merely to a unique-looking string.
const clipAId = clipA!.slice("url(#".length, -1);
const shapeAId = hrefA!.slice(1);
expect(document.getElementById(clipAId)?.closest("svg")).toBeTruthy();
expect(document.getElementById(shapeAId)?.closest("svg")).toBeTruthy();
const styleFxA = fxA!.getAttribute("style");
const styleFxB = fxB!.getAttribute("style");
expect(styleFxA).not.toBe(styleFxB);
// The CSS text (`<style>#scene-a .fx-target { filter: url(#fx) }`)
// extracted alongside the DOM (never re-injected by this shared function
// — that is the caller's job) must resolve to the SAME renamed id the
// element attribute above did, or the two diverge and the rule stops
// matching once inlined.
const styles = result.styles.map((style) => style.css).join("\n");
const fxAId = styleFxA!.match(/url\(#([^)]+)\)/)?.[1];
expect(fxAId).toBeTruthy();
expect(styles).toContain(`filter: url(#${fxAId})`);
});
it("disambiguates the same catalog block used twice in one scene", () => {
const block = svgScene("block", "green");
const { document } = inlineScenes({ "block.html": block }, [
{ compId: "block", src: "block.html" },
{ compId: "block", src: "block.html" },
]);
const uses = Array.from(document.querySelectorAll("use.shape"));
expect(uses).toHaveLength(2);
const hrefs = uses.map((u) => u.getAttribute("href"));
expect(hrefs[0]).not.toBe(hrefs[1]);
expect(new Set(hrefs).size).toBe(2);
// Each <use> must still resolve within the merged document.
for (const href of hrefs) {
const id = href!.slice(1);
expect(document.getElementById(id)).toBeTruthy();
}
});
it("records the authored id on the renamed (second) instance only", () => {
// Mirrors #646: an author's own script calling
// document.getElementById('shape') from inside its composition must
// still find its element after this module renames the real id — the
// scoped shim falls back to data-hf-authored-id.
const { document } = inlineScenes(
{ "scene-a.html": svgScene("scene-a", "red"), "scene-b.html": svgScene("scene-b", "blue") },
[
{ compId: "scene-a", src: "scene-a.html" },
{ compId: "scene-b", src: "scene-b.html" },
],
);
const sceneARoot = document.querySelector('[data-composition-id="scene-a"]')!;
const sceneBRoot = document.querySelector('[data-composition-id="scene-b"]')!;
expect(sceneARoot.querySelector('[data-hf-authored-id="shape"]')).toBeNull();
expect(sceneARoot.querySelector("symbol")!.getAttribute("id")).toBe("shape");
const authoredMatch = sceneBRoot.querySelector('[data-hf-authored-id="shape"]');
expect(authoredMatch).toBeTruthy();
expect(authoredMatch).toBe(sceneBRoot.querySelector("symbol"));
});
});
describe("inlineSubCompositions – renamed SVG ids stay reachable from author scripts", () => {
// These tests execute the compiled, scoped scripts inside a real jsdom
// window built from the assembled document — the same thing the browser
// does — so they exercise the selector runtime in compositionScoping.ts,
// not just the DOM rewrite.
function scriptedScene(compId: string, script: string, extra = ""): string {
return `<!DOCTYPE html><html><body><div id="${compId}" data-composition-id="${compId}" data-width="100" data-height="100">
<svg class="art" width="0" height="0">
<path id="shape" d="M0,0 L10,10"/>
<use class="ref" href="#shape"></use>
</svg>
${extra}
<script>${script}</script>
</div></body></html>`;
}
function inlineAndBoot(
sources: Record<string, string>,
hostEntries: Array<{ compId: string; src: string }>,
fakeGsap?: (window: Window & typeof globalThis) => unknown,
) {
const { document, result } = inlineScenes(sources, hostEntries);
const dom = new JSDOM(document.toString(), { runScripts: "outside-only" });
const window = dom.window as unknown as Window & typeof globalThis & Record<string, unknown>;
window.__captured = {};
if (fakeGsap) (window as Record<string, unknown>).gsap = fakeGsap(window);
const nativeQuery = window.Element.prototype.querySelector;
for (const script of result.scripts) window.eval(script);
return { window, result, nativeQuery, captured: window.__captured as Record<string, unknown> };
}
it("single composition: native and script references to the same element both keep resolving", () => {
const { window, captured, nativeQuery } = inlineAndBoot(
{
"scene.html": scriptedScene(
"scene",
`var svg = document.querySelector("svg.art");
window.__captured.viaDocument = document.querySelector("#shape");
window.__captured.viaElement = svg.querySelector("#shape");
window.__captured.byId = document.getElementById("shape");
window.__captured.all = document.querySelectorAll("#shape").length;`,
),
},
[{ compId: "scene", src: "scene.html" }],
);
const path = window.document.querySelector("path")!;
// Ids are byte-for-byte untouched: no collision, no rename, no shim.
expect(path.getAttribute("id")).toBe("shape");
expect(path.hasAttribute("data-hf-authored-id")).toBe(false);
expect(window.document.querySelector("use")!.getAttribute("href")).toBe("#shape");
expect(window.Element.prototype.querySelector).toBe(nativeQuery);
expect(captured.viaDocument).toBe(path);
expect(captured.viaElement).toBe(path);
expect(captured.byId).toBe(path);
expect(captured.all).toBe(1);
});
it("two colliding compositions: native refs point at their own element and each script still finds its own", () => {
const probe = `var svg = document.querySelector("svg.art");
window.__captured[__hfProbeName] = {
viaDocument: document.querySelector("#shape"),
viaElement: svg.querySelector("#shape"),
viaElementAll: svg.querySelectorAll("#shape").length,
byId: document.getElementById("shape"),
gsapTargets: gsap.to(["#shape", ".ref"], {}),
toArray: gsap.utils.toArray("#shape"),
};`;
const { window, captured, nativeQuery } = inlineAndBoot(
{
"scene-a.html": scriptedScene("scene-a", `var __hfProbeName = "a"; ${probe}`),
"scene-b.html": scriptedScene("scene-b", `var __hfProbeName = "b"; ${probe}`),
},
[
{ compId: "scene-a", src: "scene-a.html" },
{ compId: "scene-b", src: "scene-b.html" },
],
() => ({
to: (targets: unknown) => targets,
utils: { toArray: (targets: unknown) => targets },
}),
);
const [rootA, rootB] = Array.from(
window.document.querySelectorAll(
'[data-composition-id="scene-a"], [data-composition-id="scene-b"]',
),
);
const pathA = rootA!.querySelector("path")!;
const pathB = rootB!.querySelector("path")!;
// DOM: A keeps the authored id, B is renamed and its <use> follows.
expect(pathA.getAttribute("id")).toBe("shape");
expect(pathB.getAttribute("id")).not.toBe("shape");
expect(pathB.getAttribute("data-hf-authored-id")).toBe("shape");
expect(rootA!.querySelector("use")!.getAttribute("href")).toBe("#shape");
expect(rootB!.querySelector("use")!.getAttribute("href")).toBe(`#${pathB.getAttribute("id")}`);
// Scripts: every lookup form resolves to the element of ITS OWN scene.
const a = captured.a as Record<string, unknown>;
const b = captured.b as Record<string, unknown>;
expect(a.viaDocument).toBe(pathA);
expect(a.viaElement).toBe(pathA);
expect(a.byId).toBe(pathA);
expect(b.viaDocument).toBe(pathB);
expect(b.viaElement).toBe(pathB);
expect(b.viaElementAll).toBe(1);
expect(b.byId).toBe(pathB);
// GSAP selector arrays resolve string entries through the scoped lookup.
expect(a.gsapTargets).toEqual([pathA, rootA!.querySelector("use.ref")]);
expect(b.gsapTargets).toEqual([pathB, rootB!.querySelector("use.ref")]);
expect(a.toArray).toEqual([pathA]);
expect(b.toArray).toEqual([pathB]);
expect(window.Element.prototype.querySelector).not.toBe(nativeQuery);
});
it("escaped CSS id: a styled element that is also natively referenced keeps its rule after rename", () => {
function fxScene(compId: string): string {
return `<!DOCTYPE html><html><body><div id="${compId}" data-composition-id="${compId}" data-width="100" data-height="100">
<svg width="0" height="0"><filter id="fx.1"><feFlood flood-color="red"/></filter></svg>
<rect class="target" filter="url(#fx.1)"></rect>
<style>#fx\\.1 { color: red; } .target { filter: url(#fx.1); }</style>
<script>window.__captured[${JSON.stringify(compId)}] = document.querySelector("#fx\\\\.1");</script>
</div></body></html>`;
}
const { window, result, captured } = inlineAndBoot(
{ "scene-a.html": fxScene("scene-a"), "scene-b.html": fxScene("scene-b") },
[
{ compId: "scene-a", src: "scene-a.html" },
{ compId: "scene-b", src: "scene-b.html" },
],
);
const [rootA, rootB] = Array.from(
window.document.querySelectorAll(
'[data-composition-id="scene-a"], [data-composition-id="scene-b"]',
),
);
const filterA = rootA!.querySelector("filter")!;
const filterB = rootB!.querySelector("filter")!;
expect(filterA.getAttribute("id")).toBe("fx.1");
expect(filterB.getAttribute("id")).toBe("scene-b--fx.1");
expect(rootB!.querySelector("rect")!.getAttribute("filter")).toBe("url(#scene-b--fx.1)");
// Scene B's stylesheet was rewritten with a VALID escaped selector and a
// matching url(); scene A's is untouched.
const [cssA, cssB] = result.styles.map((style) => style.css);
expect(cssA).toContain(String.raw`#fx\.1`);
expect(cssA).toContain("url(#fx.1)");
expect(cssB).toContain(String.raw`#scene-b--fx\.1`);
expect(cssB).toContain("url(#scene-b--fx.1)");
expect(cssB).toContain(String.raw`:is(#fx\.1, #scene-b--fx\.1)`);
// The rewritten selector actually matches the renamed element in a real
// selector engine.
const ruleSelector = cssB!.slice(0, cssB!.indexOf("{")).trim();
expect(ruleSelector).toBeTruthy();
expect(window.document.querySelector(ruleSelector!)).toBe(filterB);
// And the author's own escaped selector still resolves through the
// scoped document proxy in both scenes.
expect(captured["scene-a"]).toBe(filterA);
expect(captured["scene-b"]).toBe(filterB);
});
});
describe("SVG namespacing compatibility on current compiler", () => {
it.each([false, true])(
"preserves inherited native references and child styles (shadow=%s)",
(shadow) => {
const parent = `<div data-composition-id="parent"><svg><linearGradient id="paint"><stop stop-color="red"/></linearGradient><rect fill="url(#paint)"/></svg>
<div data-composition-id="child" data-composition-src="child.html"></div></div>`;
const child = `<div data-composition-id="child"><svg>${shadow ? '<linearGradient id="paint"><stop stop-color="green"/></linearGradient>' : ""}<rect class="child-paint" fill="url(#paint)"/></svg>
<style media="screen" title="child">.child-paint { fill: url(#paint) }</style></div>`;
const { document } = parseHTML(
'<html><body><div data-composition-id="parent" data-composition-src="parent.html"></div><svg><linearGradient id="paint"><stop stop-color="blue"/></linearGradient></svg></body></html>',
);
const result = inlineSubCompositions(
document,
[...document.querySelectorAll("[data-composition-src]")],
{
resolveHtml: (src) => (src === "parent.html" ? parent : child),
parseHtml: (html) => parseHTML(html).document,
},
);
const rect = document.querySelector(".child-paint")!;
const id = rect.getAttribute("fill")!.slice(5, -1);
expect(document.getElementById(id)!.querySelector("stop")!.getAttribute("stop-color")).toBe(
shadow ? "green" : "red",
);
expect(result.styles[0]).toEqual({
css: expect.stringContaining(`url(#${id})`),
media: "screen",
title: "child",
});
},
);
it("initializes selector compatibility for module-only compositions", () => {
const scene = (
id: string,
) => `<div data-composition-id="${id}"><svg><path id="shape"/><use href="#shape"/></svg>
<script type="module">window.moduleHit = document.querySelector('[data-composition-id="b"]').querySelector('#shape').id;</script></div>`;
const { document, result } = inlineScenes({ "a.html": scene("a"), "b.html": scene("b") }, [
{ compId: "a", src: "a.html" },
{ compId: "b", src: "b.html" },
]);
expect(result.scripts).toHaveLength(0);
const dom = new JSDOM(document.toString(), { runScripts: "outside-only" });
for (const script of result.moduleScripts) dom.window.eval(script);
expect(dom.window.moduleHit).toBe("b--shape");
dom.window.close();
});
});