Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { describe, it, expect } from "vitest";
import { ensureHfIds, mintHfId, stampHfIdsInPlace, walkCompositionDescendants } from "./hfIds.js";
import { parseHTML } from "linkedom";
import { assignHfIds } from "./hfIdAssignment.js";
function ids(html: string): string[] {
const { document } = parseHTML(html);
return Array.from(document.querySelectorAll("[data-hf-id]")).map(
(e) => e.getAttribute("data-hf-id") as string,
);
}
// data-hf-id of the first element matching `selector`.
function idOf(html: string, selector: string): string | null {
const { document } = parseHTML(html);
return document.querySelector(selector)?.getAttribute("data-hf-id") ?? null;
}
const doc = (body: string) => `<!doctype html><html><body>${body}</body></html>`;
describe("ensureHfIds fragment detection", () => {
it.each([
`<!-- Example: <html lang="en"> --><div id="stage"><p id="title">Hello</p></div>`,
`<!-- Example: <!doctype html> --><div id="stage"><p id="title">Hello</p></div>`,
`<div id="stage" title="<html>"><p id="title">Hello</p></div>`,
`<script>const example = "<!doctype html>";</script><div id="stage"><p id="title">Hello</p></div>`,
])("stamps fragments containing document markers in inert text: %s", (html) => {
const out = ensureHfIds(html);
expect(ids(out)).toHaveLength(2);
expect(idOf(out, "#title")).toBe(
idOf(ensureHfIds(`<div id="stage"><p id="title">Hello</p></div>`), "#title"),
);
expect(out).not.toContain("<head>");
expect(out).not.toContain("<body>");
expect(ensureHfIds(out)).toBe(out);
});
it("preserves a full document following leading comments", () => {
const out = ensureHfIds(`<!-- note --><html><body><p id="title">Hello</p></body></html>`);
expect(out).toContain("<html>");
expect(idOf(out, "#title")).toMatch(/^hf-[a-z0-9]{4}$/);
expect(ensureHfIds(out)).toBe(out);
});
});
describe("stampHfIdsInPlace keeps the source's own formatting", () => {
it.each(["script", "style"])("keeps source offsets after expanding Unicode near %s", (tag) => {
const html = `<div DATA-X='KeepCase'>${"İ".repeat(20)}<${tag}>/* İ <span> */</${tag.toUpperCase()} \n><p class='KeepMe'>after</p></div>`;
const out = stampHfIdsInPlace(html);
expect(out.replace(/ data-hf-id="hf-[a-z0-9]{4}"/g, "")).toBe(html);
expect(ids(out)).toEqual(ids(ensureHfIds(html)));
expect(stampHfIdsInPlace(out)).toBe(out);
});
it("only inserts ids into a composition written without whitespace", () => {
const html =
'<template id="s-template"><div data-composition-id="s" data-start="0" data-duration="4"><style>#t{color:red}</style><img src="a.png"/><input disabled><p class=\'t\' id=t>Hi<br></p></div></template>';
const out = stampHfIdsInPlace(html);
expect(out.replace(/ data-hf-id="hf-[a-z0-9]{4}"/g, "")).toBe(html);
expect(ids(out.replace(/<\/?template[^>]*>/g, ""))).toHaveLength(5);
expect(stampHfIdsInPlace(out)).toBe(out);
});
it("only inserts ids into a full document with comments, scripts and SVG", () => {
const html = `<!DOCTYPE html>\n<html>\n<head><meta charset="UTF-8"><script>if(a<b){x="<div>"}</script></head>\n<body>\n <!-- <span> -->\n <div id="root" data-composition-id="main"><svg viewBox="0 0 10 10"><path d="M0 0"/></svg></div>\n</body>\n</html>\n`;
const out = stampHfIdsInPlace(html);
expect(out.replace(/ data-hf-id="hf-[a-z0-9]{4}"/g, "")).toBe(html);
expect(ids(out)).toEqual(ids(ensureHfIds(html)));
expect(idOf(out, "path")).toMatch(/^hf-/);
});
it("keeps an astral character from shifting the minted id", () => {
const html = `<div title='😀' data-hf-id=""><span>Hello</span></div>`;
const out = stampHfIdsInPlace(html);
expect(out).toContain(`title='😀' data-hf-id="`);
expect(out).not.toMatch(/data-hf-id=hf-/);
expect(ids(out)).toEqual(ids(ensureHfIds(html)));
});
it("does not mint an id inside another attribute's quotes", () => {
const html = `<div title=' data-hf-id=""' data-hf-id=""><p data-hf-id="">Hi</p></div>`;
const out = stampHfIdsInPlace(html);
expect(out).toContain(`title=' data-hf-id=""'`);
expect(out.replace(/data-hf-id="hf-[a-z0-9]{4}"/g, 'data-hf-id=""')).toBe(html);
expect(ids(out)).toEqual(ids(ensureHfIds(html)));
});
it("fills an empty data-hf-id instead of leaving it blank", () => {
const html = `<div data-hf-id=""><p data-hf-id="">Hello</p></div>`;
const out = stampHfIdsInPlace(html);
expect(out.replace(/data-hf-id="hf-[a-z0-9]{4}"/g, 'data-hf-id=""')).toBe(html);
expect(out).not.toMatch(/data-hf-id=""\s+data-hf-id=/);
expect(ids(out)).toEqual(ids(ensureHfIds(html)));
expect(ids(out).every((id) => /^hf-[a-z0-9]{4}$/.test(id))).toBe(true);
});
it("does not treat a longer tag name as the end of a script or style", () => {
const script = `<div><script>s="</scripts>"</script><span>x</span></div>`;
const styled = `<div><style>/* </styles */</style><span>x</span></div>`;
for (const html of [script, styled]) {
const out = stampHfIdsInPlace(html);
expect(out.replace(/ data-hf-id="hf-[a-z0-9]{4}"/g, "")).toBe(html);
expect(ids(out)).toEqual(ids(ensureHfIds(html)));
}
const stray = `<div><script>s="</scripts><p>"</script></p><span>x</span></div>`;
const stamped = stampHfIdsInPlace(stray);
expect(stamped).toContain(`s="</scripts><p>"</script>`);
expect(stamped).not.toMatch(/scripts><p>" data-hf-id/);
expect(ids(stamped)).toEqual(ids(ensureHfIds(stray)));
});
});
describe("ensureHfIds", () => {
it("ignores HTML attribute case and editor state while retaining pinned IDs", () => {
const lower = doc(`<div id="x" data-start="2" data-hf-state="a">hello</div>`);
const upper = doc(`<DIV ID="x" DATA-START="2" DATA-HF-STATE="b">hello</DIV>`);
expect(ids(ensureHfIds(upper))).toEqual(ids(ensureHfIds(lower)));
const pinned = ensureHfIds(doc(`<DIV DATA-HF-ID="pinned" DATA-START="2">hello</DIV>`));
expect(
new DOMParser()
.parseFromString(pinned, "text/html")
.querySelector("[data-start]")
?.getAttribute("data-hf-id"),
).toBe("pinned");
});
it.each([
`<TEMPLATE DATA-COMPOSITION-ID="sub"><DIV ID="x" DATA-START="2">hello</DIV></TEMPLATE>`,
`<TEMPLATE><DIV DATA-COMPOSITION-ID="sub"><DIV ID="x" DATA-START="2">hello</DIV></DIV></TEMPLATE>`,
])("assigns matching IDs inside mixed-case composition templates: %s", (body) => {
const html = doc(body);
const native = new DOMParser().parseFromString(html, "text/html");
assignHfIds(native.body);
const persisted = new DOMParser().parseFromString(ensureHfIds(html), "text/html");
const collect = (document: Document): string[] => {
const result: string[] = [];
walkCompositionDescendants(document.body, (el) => {
if (el.tagName.toLowerCase() !== "template")
result.push(el.getAttribute("data-hf-id") ?? "missing");
});
return result;
};
expect(collect(native).length).toBeGreaterThan(0);
expect(collect(native)).not.toContain("missing");
expect(collect(native)).toEqual(collect(persisted));
});
it.each([
'<svg><linearGradient VIEWBOX="0 0 1 1"></linearGradient></svg>',
'<svg><linearGradient GRADIENTUNITS="userSpaceOnUse"></linearGradient></svg>',
'<svg><linearGradient ID="g" CLASS="paint" ARIA-LABEL="Gradient" DATA-HF-STATE="ignored"></linearGradient></svg>',
'<svg><linearGradient DATA-HF-ID="pinned" VIEWBOX="0 0 1 1"></linearGradient></svg>',
])("matches persisted IDs for mixed-case SVG attributes: %s", (body) => {
const html = doc(body);
const native = new DOMParser().parseFromString(html, "text/html");
assignHfIds(native.body);
const persisted = new DOMParser().parseFromString(ensureHfIds(html), "text/html");
const collect = (document: Document) =>
Array.from(document.querySelectorAll("svg, linearGradient")).map((el) =>
el.getAttribute("data-hf-id"),
);
expect(collect(native)).toHaveLength(2);
expect(collect(native)).not.toContain(null);
expect(collect(native)).toEqual(collect(persisted));
expect(ensureHfIds(ensureHfIds(html))).toBe(ensureHfIds(html));
const gradient = persisted.querySelector("linearGradient");
if (body.includes("VIEWBOX")) expect(gradient?.getAttribute("viewBox")).toBe("0 0 1 1");
if (body.includes("DATA-HF-ID")) expect(gradient?.getAttribute("data-hf-id")).toBe("pinned");
});
it("mints a hf- id on every editable element node in body", () => {
const html = `<!doctype html><html><body>
<div class="card"><h1>Hi</h1><img src="a.png"><span>x</span></div>
</body></html>`;
const out = ensureHfIds(html);
for (const id of ids(out)) expect(id).toMatch(/^hf-[a-z0-9]{4}$/);
// div, h1, img, span = 4 ids
expect(ids(out)).toHaveLength(4);
});
it("skips script/style/template/meta and head", () => {
const html = `<!doctype html><html><head><meta charset="utf-8"></head>
<body><script>1</script><style>.a{}</style><p>keep</p></body></html>`;
const out = ensureHfIds(html);
// only the <p> gets an id
expect(ids(out)).toHaveLength(1);
expect(out).not.toContain("<script data-hf-id");
expect(out).not.toContain("<style data-hf-id");
expect(out).not.toContain("<meta data-hf-id");
});
it("is idempotent: a second call mints nothing and is byte-stable", () => {
const html = `<!doctype html><html><body><div><p>a</p></div></body></html>`;
const once = ensureHfIds(html);
const twice = ensureHfIds(once);
expect(twice).toBe(once);
});
it("pins existing data-hf-id and mints around it", () => {
const html = `<!doctype html><html><body>
<div data-hf-id="hf-keep"><p>a</p></div></body></html>`;
const out = ensureHfIds(html);
expect(out).toContain('data-hf-id="hf-keep"');
expect(ids(out)).toContain("hf-keep");
expect(ids(out)).toHaveLength(2); // div pinned + p minted
});
it("two identical sibling nodes get distinct ids", () => {
const html = `<!doctype html><html><body>
<p class="x">same</p><p class="x">same</p></body></html>`;
const got = ids(ensureHfIds(html));
expect(new Set(got).size).toBe(got.length);
});
it("is deterministic: same input → same ids", () => {
const html = `<!doctype html><html><body><div><p>a</p><span>b</span></div></body></html>`;
expect(ids(ensureHfIds(html))).toEqual(ids(ensureHfIds(html)));
});
it("mintHfId rehashes on collision against the assigned set", () => {
const { document } = parseHTML(`<p class="x">same</p>`);
const el = document.querySelector("p") as Element;
const assigned = new Set<string>();
const a = mintHfId(el, assigned);
const b = mintHfId(el, assigned); // identical element, same assigned set
expect(a).not.toBe(b);
expect(a).toMatch(/^hf-[a-z0-9]{4}$/);
expect(b).toMatch(/^hf-[a-z0-9]{4}$/);
});
// Post-persist stability: once data-hf-id is written back to source, edits
// don't drift the id because the attribute is already present and pinned.
it("pinned id survives text edit after first persist", () => {
const raw = `<!doctype html><html><body><div>original text</div></body></html>`;
const persisted = ensureHfIds(raw); // simulates write-back on first serve
const [originalId] = ids(persisted);
const edited = persisted.replace("original text", "edited text");
expect(ids(ensureHfIds(edited))).toContain(originalId);
});
// Hash-based stability (no prior pin): the same element content yields the
// same id regardless of what sibling elements appear in the document.
it("content-keyed minting is stable: same element content → same id in different documents", () => {
const alone = `<!doctype html><html><body><div class="card">hello</div></body></html>`;
const [idAlone] = ids(ensureHfIds(alone));
// The <div class="card">hello</div> appears alongside a new sibling here.
const withSibling = `<!doctype html><html><body><span>prefix</span><div class="card">hello</div></body></html>`;
expect(ids(ensureHfIds(withSibling))).toContain(idAlone);
});
});
// Lock the edit-lifecycle behavior. These pin BOTH the guarantee that holds
// once ids are persisted to source (pinning) AND the behavior for truly unpinned
// HTML (no data-hf-id in the input — unreachable in production after write-back
// landed in R7 Task 1-2, but still the correct contract for that path).
describe("ensureHfIds — template-inner minting", () => {
// linkedom's querySelectorAll does not descend into <template>, so extract
// ids by regex over the serialized output instead of the DOM-walk helper.
const rawIds = (html: string) => [...html.matchAll(/data-hf-id="([^"]+)"/g)].map((m) => m[1]);
it("mints ids on elements inside a <template> (template itself stays unstamped)", () => {
const html = doc(
`<template data-composition-id="t"><div class="clip" data-start="0" data-end="3">Hi</div><p>x</p></template>`,
);
const out = ensureHfIds(html);
expect(rawIds(out)).toHaveLength(2); // div + p, not the template
expect(out).not.toMatch(/<template[^>]*data-hf-id/);
});
it("template-inner ids equal the ids minted for the same content unwrapped (preview parity)", () => {
const inner = `<div class="clip" data-start="0" data-end="3">Hi</div><p>x</p>`;
const wrapped = ensureHfIds(doc(`<template data-composition-id="t">${inner}</template>`));
const unwrapped = ensureHfIds(doc(inner));
expect(rawIds(wrapped)).toEqual(rawIds(unwrapped));
});
it("pins existing template-inner ids and seeds them against fresh mints", () => {
const html = doc(
`<template data-composition-id="t"><div data-hf-id="hf-keep">a</div><p>b</p></template>`,
);
const out = ensureHfIds(html);
expect(out).toContain('data-hf-id="hf-keep"');
expect(new Set(rawIds(out)).size).toBe(2);
});
it("descends nested composition templates", () => {
const html = doc(
`<template data-composition-id="a"><div>a</div><template data-composition-id="b"><span>b</span></template></template>`,
);
const out = ensureHfIds(html);
expect(rawIds(out)).toHaveLength(2); // div + span
});
it("does NOT stamp inside a plain <template> (runtime clone-source)", () => {
// A plain template's content is cloned N times into the live DOM at
// runtime; a persisted inner id would be duplicated across every clone.
const html = doc(`<div class="stage">x</div><template><li class="row">item</li></template>`);
const out = ensureHfIds(html);
expect(rawIds(out)).toHaveLength(1); // only the stage div
expect(out).not.toMatch(/<li[^>]*data-hf-id/);
});
it("does NOT stamp inside a plain template nested in a composition template", () => {
const html = doc(
`<template data-composition-id="t"><div>a</div><template><li>clone-src</li></template></template>`,
);
const out = ensureHfIds(html);
expect(rawIds(out)).toHaveLength(1); // only the div
expect(out).not.toMatch(/<li[^>]*data-hf-id/);
});
it("is idempotent for template-inner ids", () => {
const once = ensureHfIds(doc(`<template data-composition-id="t"><div>a</div></template>`));
expect(ensureHfIds(once)).toBe(once);
});
});
describe("ensureHfIds — edit lifecycle (R1 stability)", () => {
it("pinned id survives a content edit (the §3 write-back guarantee)", () => {
// Element already carries data-hf-id in source (as it would after write-back).
const edited = doc(`<p class="body" data-hf-id="hf-abcd">Hello world</p>`);
expect(idOf(ensureHfIds(edited), "p.body")).toBe("hf-abcd");
});
it("unpinned id drifts when element text is edited (pure-hash, unreachable after write-back)", () => {
// No data-hf-id in source → every parse re-mints from content. This path is
// unreachable in production after R7 write-back: the first serve pins the id.
const before = idOf(ensureHfIds(doc(`<p class="body">Hello</p>`)), "p.body");
const after = idOf(ensureHfIds(doc(`<p class="body">Hello world</p>`)), "p.body");
expect(before).not.toBe(after);
});
it("unpinned id drifts when attribute is edited (pure-hash, unreachable after write-back)", () => {
const before = idOf(ensureHfIds(doc(`<p class="body">x</p>`)), "p");
const after = idOf(ensureHfIds(doc(`<p class="lead">x</p>`)), "p");
expect(before).not.toBe(after);
});
it("identical-content siblings: second occurrence gets a position-derived dedup id", () => {
// Insertion stability holds for DISTINCT content (covered elsewhere), but a
// second identical sibling collides and gets a position-derived dedup id.
// First element keeps the base (content-derived) id; documented in project_hfid_dedup_tiebreak.
const single = idOf(ensureHfIds(doc(`<p class="x">same</p>`)), "p.x");
const pair = ids(ensureHfIds(doc(`<p class="x">same</p><p class="x">same</p>`)));
expect(pair[0]).toBe(single); // first identical element: stable, content-derived
expect(pair[1]).not.toBe(single); // second: dedup id, exists only by position
});
});