Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
// fallow-ignore-file code-duplication
import { parseHTML } from "linkedom";
import { describe, expect, it } from "vitest";
import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
import {
splitElementInHtml,
relinkSplitHalvesInHtml,
unwrapElementsFromHtml,
wrapElementsInHtml,
} from "./sourceMutation.js";
describe("splitElementInHtml — hfId clone isolation", () => {
it("does not copy data-hf-id to the cloned second half", () => {
const source = `<html><body><div data-composition-id="root"><div id="clip1" class="clip" data-start="0" data-duration="10" data-hf-id="hf-abc123"></div></div></body></html>`;
const { html, matched } = splitElementInHtml(source, { id: "clip1" }, 5, "clip2");
expect(matched).toBe(true);
const { document } = parseHTML(html);
const occurrences = (html.match(/data-hf-id="hf-abc123"/g) ?? []).length;
expect(occurrences).toBe(1);
expect(document.getElementById("clip2")?.getAttribute("data-hf-id")).toMatch(/^hf-/);
expect(document.getElementById("clip2")?.getAttribute("data-hf-id")).not.toBe("hf-abc123");
});
});
describe("splitElementInHtml", () => {
const source = `<!DOCTYPE html><html><head><style>#box { position: absolute; top: 100px; background: red; }</style></head><body><div data-composition-id="root"><div id="box" class="clip" data-start="1" data-duration="6">Hello</div></div></body></html>`;
it("splits element at the given time", () => {
const result = splitElementInHtml(source, { id: "box" }, 3, "box-split");
expect(result.matched).toBe(true);
expect(result.html).toContain('data-duration="2"');
expect(result.html).toContain('id="box-split"');
expect(result.html).toContain('data-start="3"');
expect(result.html).toContain('data-duration="4"');
});
it("pins both halves to the caller-supplied track so an unauthored clip's split half can't drift to a new row", () => {
// #box has no data-track-index/data-layer — this is the common, unauthored
// case that relies on the runtime's positional-index fallback. Without an
// explicit stamp, splitting only the clone changes DOM sibling order and
// the runtime resolves the clone to a different fallback track.
const result = splitElementInHtml(source, { id: "box" }, 3, "box-split", {
start: 1,
duration: 6,
track: 2,
});
expect(result.matched).toBe(true);
expect(result.html.match(/data-track-index="2"/g)).toHaveLength(2);
});
it("canonicalizes legacy timing attributes on both split halves", () => {
const legacy = source.replace(
'data-start="1" data-duration="6"',
'data-start="1" data-end="7" data-layer="3"',
);
const result = splitElementInHtml(legacy, { id: "box" }, 3, "box-split");
expect(result.matched).toBe(true);
expect(result.html).not.toContain("data-end=");
expect(result.html).not.toContain("data-layer=");
expect(result.html.match(/data-track-index="3"/g)).toHaveLength(2);
expect(result.html).toContain('data-duration="2"');
expect(result.html).toContain('data-duration="4"');
});
it("duplicates CSS rules for the new element ID", () => {
const result = splitElementInHtml(source, { id: "box" }, 3, "box-split");
expect(result.html).toContain("#box-split");
expect(result.html).toContain("background: red");
const cssMatches = result.html.match(/#box-split\s*\{/g);
expect(cssMatches?.length).toBeGreaterThanOrEqual(1);
});
it("deduplicates IDs when the requested newId already exists", () => {
const withExisting = source.replace(
"</div></div>",
'</div><div id="box-split" data-start="5" data-duration="1">Existing</div></div>',
);
const result = splitElementInHtml(withExisting, { id: "box" }, 3, "box-split");
expect(result.matched).toBe(true);
expect(result.html).toContain('id="box-split-2"');
});
it("keeps clip class on the cloned element", () => {
const result = splitElementInHtml(source, { id: "box" }, 3, "box-split");
expect(result.html).toMatch(/id="box-split"[^>]*class="clip"/);
});
it("keeps every half of a split composition mount on the root it mounts", () => {
const composition = source.replace(
'id="box" class="clip"',
'id="box" class="clip" data-composition-id="headline" data-composition-src="headline.html"',
);
const first = splitElementInHtml(composition, { id: "box" }, 3, "box-split");
const second = splitElementInHtml(first.html, { id: "box-split" }, 4, "box-split-2");
const { document } = parseHTML(second.html);
const mounts = Array.from(document.querySelectorAll("[data-composition-src]"));
expect(mounts.map((element) => element.getAttribute("data-composition-id"))).toEqual([
"headline",
"headline",
"headline",
]);
expect(new Set(mounts.map((element) => element.id)).size).toBe(3);
});
it("keeps a split inline-template mount on its template", () => {
const composition = source
.replace('id="box" class="clip"', 'id="box" class="clip" data-composition-id="headline"')
.replace(
"</body>",
'<template id="headline-template"><div data-composition-id="headline"></div></template></body>',
);
const result = splitElementInHtml(composition, { id: "box" }, 3, "box-split");
expect(result.html).toMatch(
/id="box-split"[^>]*data-composition-id="headline"|data-composition-id="headline"[^>]*id="box-split"/,
);
});
it("returns matched false for out-of-range split time", () => {
expect(splitElementInHtml(source, { id: "box" }, 0.5, "box-split").matched).toBe(false);
expect(splitElementInHtml(source, { id: "box" }, 7.5, "box-split").matched).toBe(false);
});
it("splits a GSAP element with no authored timing using fallback timing", () => {
const gsapSource = `<html><body><div data-composition-id="root"><h1 id="title" class="title">Hi</h1></div></body></html>`;
const result = splitElementInHtml(gsapSource, { id: "title" }, 2, "title-split", {
start: 0,
duration: 6,
});
expect(result.matched).toBe(true);
const original = result.html.match(/<h1[^>]*\bid="title"[^>]*>/);
const clone = result.html.match(/<h1[^>]*\bid="title-split"[^>]*>/);
expect(original?.[0]).toContain('data-start="0"');
expect(original?.[0]).toContain('data-duration="2"');
expect(clone?.[0]).toContain('data-start="2"');
expect(clone?.[0]).toContain('data-duration="4"');
});
it("still rejects a no-timing element when no fallback timing is given", () => {
const gsapSource = `<html><body><div data-composition-id="root"><h1 id="title">Hi</h1></div></body></html>`;
expect(splitElementInHtml(gsapSource, { id: "title" }, 2, "title-split").matched).toBe(false);
});
it("adjusts media playback-start for the second half", () => {
const mediaSource = source.replace(
'id="box" class="clip" data-start="1" data-duration="6"',
'id="box" class="clip" data-start="1" data-duration="6" data-playback-start="0"',
);
const result = splitElementInHtml(mediaSource, { id: "box" }, 3, "box-split");
expect(result.html).toMatch(/id="box-split"[^>]*data-playback-start="2"/);
});
it.each(["audio", "video"])(
"seeds the second %s half with a media in-point when the source starts at zero",
(tag) => {
const mediaSource = `<!DOCTYPE html><html><body><div data-composition-id="root"><${tag} id="media" class="clip" src="asset.mp4" data-start="1" data-duration="6"></${tag}></div></body></html>`;
const result = splitElementInHtml(mediaSource, { id: "media" }, 3, "media-split");
const { document } = parseHTML(result.html);
expect(result.matched).toBe(true);
expect(document.getElementById("media")?.getAttribute("data-media-start")).toBe("0");
expect(document.getElementById("media-split")?.getAttribute("data-media-start")).toBe("2");
},
);
it("advances a zero-based media in-point by playback rate", () => {
const mediaSource = `<!DOCTYPE html><html><body><div data-composition-id="root"><video id="media" class="clip" src="asset.mp4" data-start="1" data-duration="6" data-playback-rate="2"></video></div></body></html>`;
const result = splitElementInHtml(mediaSource, { id: "media" }, 3, "media-split");
const { document } = parseHTML(result.html);
expect(document.getElementById("media-split")?.getAttribute("data-media-start")).toBe("4");
});
it("leaves the first half's authored in-point exactly as written", () => {
const mediaSource = `<!DOCTYPE html><html><body><div data-composition-id="root"><video id="media" class="clip" src="asset.mp4" data-start="1" data-duration="6" data-media-start="3.296375" data-playback-rate="0.25"></video></div></body></html>`;
const result = splitElementInHtml(mediaSource, { id: "media" }, 3, "media-split");
const { document } = parseHTML(result.html);
expect(document.getElementById("media")?.getAttribute("data-media-start")).toBe("3.296375");
});
it.each([
['data-playback-start="-1" data-media-start="2"', "data-playback-start", 2, 4],
['data-playback-start="abc" data-media-start="2"', "data-playback-start", 2, 4],
['data-media-start="-1"', "data-media-start", 0, 2],
['data-media-start="junk"', "data-media-start", 0, 2],
['data-media-start="1.5s"', "data-media-start", 0, 2],
])("splits %s where playback reads it", (inPoint, attr, left, right) => {
const mediaSource = `<!DOCTYPE html><html><body><div data-composition-id="root"><video id="media" class="clip" src="asset.mp4" data-start="0" data-duration="6" ${inPoint}></video></div></body></html>`;
const { document } = parseHTML(splitElementInHtml(mediaSource, { id: "media" }, 2, "b").html);
const playbackReads = (id: string) =>
readMediaOffsetSeconds((name) => document.getElementById(id)?.getAttribute(name));
expect([playbackReads("media"), playbackReads("b")]).toEqual([left, right]);
expect(document.getElementById("b")?.getAttribute(attr)).toBe(String(right));
});
it("does not add a media in-point to non-media elements", () => {
const result = splitElementInHtml(source, { id: "box" }, 3, "box-split");
expect(result.html).not.toContain("data-media-start");
expect(result.html).not.toContain("data-playback-start");
});
it.each(['data-composition-src="scene.html"', 'data-composition-id="scene"'])(
"stamps an in-point on both halves of a sub-composition host (%s)",
(host) => {
const hostSource = source.replace('id="box"', `id="box" ${host}`);
const { document } = parseHTML(
splitElementInHtml(hostSource, { id: "box" }, 3, "box-split").html,
);
expect(document.getElementById("box")?.getAttribute("data-playback-start")).toBe("0");
expect(document.getElementById("box-split")?.getAttribute("data-playback-start")).toBe("2");
},
);
it("stamps a legacy composition offset and advances the second half by playback rate", () => {
const hostSource = source.replace('id="box"', 'id="box" data-composition-src="scene.html"');
const result = splitElementInHtml(hostSource, { id: "box" }, 3, "box-split", {
start: 1,
duration: 6,
playbackStart: 1.5,
playbackRate: 2,
});
const { document } = parseHTML(result.html);
expect(document.getElementById("box")?.getAttribute("data-playback-start")).toBe("1.5");
expect(document.getElementById("box-split")?.getAttribute("data-playback-start")).toBe("5.5");
});
it("splits the timed video inside an untimed wrapper and leaves both wrappers untimed", () => {
const wrapped = `<!DOCTYPE html><html><head><style>#v { object-fit: cover; }</style></head><body><div data-composition-id="root"><div id="wrap" class="frame"><video id="v" class="clip" src="a.mp4" data-start="1" data-duration="6"></video></div></div></body></html>`;
// The requested wrapper id is the media's natural split id: both must still come out unique.
const result = splitElementInHtml(wrapped, { id: "wrap" }, 3, "v-split", {
start: 1,
duration: 6,
});
const { document } = parseHTML(result.html);
const wrappers = [...document.querySelectorAll("div.frame")];
const [first, second] = [...document.querySelectorAll("video")];
expect(result.matched).toBe(true);
expect(wrappers).toHaveLength(2);
for (const wrapper of wrappers) {
expect(wrapper.hasAttribute("data-start")).toBe(false);
expect(wrapper.hasAttribute("data-duration")).toBe(false);
}
expect(first?.id).toBe("v");
expect(second?.id).toBeTruthy();
const ids = [...document.querySelectorAll("[id]")].map((node) => node.id);
expect(new Set(ids).size).toBe(ids.length);
expect(result.html).toContain(`#${second?.id} {`);
expect(first?.getAttribute("data-duration")).toBe("2");
expect(second?.getAttribute("data-start")).toBe("3");
expect(second?.getAttribute("data-duration")).toBe("4");
expect(second?.getAttribute("data-media-start")).toBe("2");
});
it.each(['data-start="1"', 'data-duration="6"', 'data-composition-id="scene"'])(
"cuts a wrapper with %s itself, not the video inside it",
(wrapperAttrs) => {
const wrapped = `<!DOCTYPE html><html><body><div data-composition-id="root"><div id="wrap" ${wrapperAttrs}><video id="v" src="a.mp4" data-start="1" data-duration="6"></video></div></div></body></html>`;
const result = splitElementInHtml(wrapped, { id: "wrap" }, 3, "wrap-split", {
start: 1,
duration: 6,
});
const { document } = parseHTML(result.html);
expect(document.getElementById("wrap-split")?.hasAttribute("data-start")).toBe(true);
expect(document.getElementById("v")?.getAttribute("data-duration")).toBe("6");
},
);
it("keeps cutting a GSAP scene on its own window when it holds a shorter timed video", () => {
const scene = `<!DOCTYPE html><html><body><div data-composition-id="root"><div id="card"><video id="v" src="a.mp4" data-start="2" data-duration="3"></video></div></div></body></html>`;
const result = splitElementInHtml(scene, { id: "card" }, 7, "card-split", {
start: 0,
duration: 10,
});
const { document } = parseHTML(result.html);
expect(result.matched).toBe(true);
expect(document.getElementById("card")?.getAttribute("data-duration")).toBe("7");
expect(document.getElementById("card-split")?.getAttribute("data-start")).toBe("7");
});
});
describe("wrapElementsInHtml / unwrapElementsFromHtml", () => {
const FIXTURE = `<!doctype html><html><body><div data-composition-id="main">
<div id="title" class="clip" style="position: absolute; left: 260px; top: 100px">Title</div>
<div id="logo" class="clip" style="position: absolute; left: 300px; top: 200px; transform: translate(10px, 5px)">Logo</div>
<div id="badge" class="clip" style="position: absolute; left: 400px; top: 50px; --hf-studio-offset: 12px">Badge</div>
<div id="outside" class="clip" style="position: absolute; left: 10px; top: 10px">Outside</div>
</div></body></html>`;
const BBOX = { left: 260, top: 50, width: 300, height: 300 };
const REBASES = [
{ target: { id: "title" }, left: 0, top: 50 },
{ target: { id: "logo" }, left: 40, top: 150 },
{ target: { id: "badge" }, left: 140, top: 0 },
];
const TARGETS = [{ id: "title" }, { id: "logo" }, { id: "badge" }];
function leftTop(el: Element): { left: number; top: number } {
const style = el.getAttribute("style") ?? "";
const left = parseFloat(/(?:^|;)\s*left\s*:\s*([\d.]+)px/.exec(style)?.[1] ?? "NaN");
const top = parseFloat(/(?:^|;)\s*top\s*:\s*([\d.]+)px/.exec(style)?.[1] ?? "NaN");
return { left, top };
}
function requireElement(document: Document, selector: string): Element {
const element = document.querySelector(selector);
if (!element) throw new Error(`Expected ${selector} to match`);
return element;
}
it.each([
["Group 1", "group-1"],
[" --HELLO___World!! ", "hello-world"],
["a---b---c", "a-b-c"],
["--123--", "123"],
["", "group"],
[" --- ", "group"],
["你好", "group"],
["-".repeat(100_000) + "Title" + "-".repeat(100_000), "title"],
])("preserves normalized group IDs and collision suffixes (case %#)", (name, id) => {
const source = FIXTURE.replace(
"</body>",
`<div id="${id}"></div><div id="${id}-2"></div></body>`,
);
const result = wrapElementsInHtml(source, TARGETS, name, BBOX, REBASES);
expect(result.matched).toBe(true);
const { document } = parseHTML(result.html);
const group = document.getElementById(`${id}-3`);
expect(group?.getAttribute("data-hf-group")).toBe(name);
expect(Array.from(group?.children ?? []).map((child) => child.id)).toEqual([
"title",
"logo",
"badge",
]);
});
it("wraps members in a data-hf-group div, preserving order and rebasing left/top", () => {
const { html, matched, groupId } = wrapElementsInHtml(
FIXTURE,
TARGETS,
"Group 1",
BBOX,
REBASES,
);
expect(matched).toBe(true);
expect(groupId).toBe("Group 1");
const { document } = parseHTML(html);
const group = requireElement(document, '[data-hf-group="Group 1"]');
expect(leftTop(group)).toEqual({ left: 260, top: 50 });
expect(Array.from(group.children).map((c) => c.id)).toEqual(["title", "logo", "badge"]);
expect(requireElement(document, "#outside").parentElement).toBe(
requireElement(document, '[data-composition-id="main"]'),
);
expect(leftTop(requireElement(document, "#title"))).toEqual({ left: 0, top: 50 });
expect(leftTop(requireElement(document, "#logo"))).toEqual({ left: 40, top: 150 });
expect(requireElement(document, "#logo").getAttribute("style")).toContain(
"transform: translate(10px, 5px)",
);
expect(leftTop(requireElement(document, "#badge"))).toEqual({ left: 140, top: 0 });
expect(requireElement(document, "#badge").getAttribute("style")).toContain(
"--hf-studio-offset: 12px",
);
});
it("stamps each member's resolved track so grouping an unauthored clip can't drift it to a new row", () => {
const rebasesWithTrack = [
{ target: { id: "title" }, left: 0, top: 50, track: 1 },
{ target: { id: "logo" }, left: 40, top: 150, track: 3 },
{ target: { id: "badge" }, left: 140, top: 0 },
];
const { html } = wrapElementsInHtml(FIXTURE, TARGETS, "Group 1", BBOX, rebasesWithTrack);
const { document } = parseHTML(html);
expect(requireElement(document, "#title").getAttribute("data-track-index")).toBe("1");
expect(requireElement(document, "#logo").getAttribute("data-track-index")).toBe("3");
expect(requireElement(document, "#badge").hasAttribute("data-track-index")).toBe(false);
});
it("round-trips: unwrap restores original structure and coordinates", () => {
const wrapped = wrapElementsInHtml(FIXTURE, TARGETS, "Group 1", BBOX, REBASES).html;
const { html, unwrapped } = unwrapElementsFromHtml(wrapped, {
selector: '[data-hf-group="Group 1"]',
});
expect(unwrapped).toBe(true);
const { document } = parseHTML(html);
expect(document.querySelector("[data-hf-group]")).toBeNull();
const main = requireElement(document, '[data-composition-id="main"]');
expect(Array.from(main.children).map((c) => c.id)).toEqual([
"title",
"logo",
"badge",
"outside",
]);
expect(leftTop(requireElement(document, "#title"))).toEqual({ left: 260, top: 100 });
expect(leftTop(requireElement(document, "#logo"))).toEqual({ left: 300, top: 200 });
expect(requireElement(document, "#logo").getAttribute("style")).toContain(
"transform: translate(10px, 5px)",
);
expect(leftTop(requireElement(document, "#badge"))).toEqual({ left: 400, top: 50 });
expect(requireElement(document, "#badge").getAttribute("style")).toContain(
"--hf-studio-offset: 12px",
);
});
it("stamps each child's resolved track on ungroup so it can't drift to a new row when it moves back out of the wrapper", () => {
const wrapped = wrapElementsInHtml(FIXTURE, TARGETS, "Group 1", BBOX, REBASES).html;
const childTracks = [
{ target: { id: "title" }, track: 1 },
{ target: { id: "logo" }, track: 3 },
];
const { html } = unwrapElementsFromHtml(
wrapped,
{ selector: '[data-hf-group="Group 1"]' },
childTracks,
);
const { document } = parseHTML(html);
expect(requireElement(document, "#title").getAttribute("data-track-index")).toBe("1");
expect(requireElement(document, "#logo").getAttribute("data-track-index")).toBe("3");
expect(requireElement(document, "#badge").hasAttribute("data-track-index")).toBe(false);
});
it("rejects members that do not share a single parent", () => {
const split = `<!doctype html><html><body><div data-composition-id="main"><div id="a" style="position:absolute;left:0;top:0"></div><section><div id="b" style="position:absolute;left:0;top:0"></div></section></div></body></html>`;
const result = wrapElementsInHtml(split, [{ id: "a" }, { id: "b" }], "Group 1", BBOX, [
{ target: { id: "a" }, left: 0, top: 0 },
{ target: { id: "b" }, left: 0, top: 0 },
]);
expect(result.matched).toBe(false);
expect(result.error).toMatch(/single parent/);
expect(result.html).toBe(split);
});
it("lifts the group to the topmost member's slot so an interleaved non-member falls below it", () => {
const fixture = `<!doctype html><html><body><div data-composition-id="main"><div id="low" style="position:absolute;left:0;top:0;z-index:2"></div><div id="middle" style="position:absolute;left:0;top:0;z-index:3"></div><div id="high" style="position:absolute;left:0;top:0;z-index:4"></div></div></body></html>`;
const { html, matched } = wrapElementsInHtml(
fixture,
[{ id: "low" }, { id: "high" }],
"Group 1",
{ left: 0, top: 0, width: 10, height: 10 },
[
{ target: { id: "low" }, left: 0, top: 0 },
{ target: { id: "high" }, left: 0, top: 0 },
],
);
expect(matched).toBe(true);
const { document } = parseHTML(html);
const parent = requireElement(document, '[data-composition-id="main"]');
const group = requireElement(document, '[data-hf-group="Group 1"]');
expect(Array.from(group.children).map((c) => c.id)).toEqual(["low", "high"]);
const topChildren = Array.from(parent.children).map(
(c) => c.getAttribute("data-hf-group") ?? c.id,
);
expect(topChildren).toEqual(["middle", "Group 1"]);
expect(group.getAttribute("style")).toMatch(/z-index:\s*4/);
});
it("refuses to unwrap an element without data-hf-group (no silent corruption)", () => {
const html = `<!doctype html><html><body><div data-composition-id="main"><div id="plain" style="position:absolute;left:0;top:0"><span id="kid"></span></div></div></body></html>`;
const result = unwrapElementsFromHtml(html, { id: "plain" });
expect(result.unwrapped).toBe(false);
expect(result.html).toBe(html);
});
});
describe("relinkSplitHalvesInHtml", () => {
it("makes each half of a split linked pair its own pair", () => {
const source =
'<div data-composition-id="c"><video id="v" src="t.mp4" muted data-link="lk-1" data-start="0" data-duration="4"></video><audio id="a" src="t.mp4" data-link="lk-1" data-start="0" data-duration="4"></audio></div>';
const first = splitElementInHtml(source, { id: "v" }, 2, "v-split");
const second = splitElementInHtml(first.html, { id: "a" }, 2, "a-split");
const html = relinkSplitHalvesInHtml(second.html, ["v-split", "a-split"]);
const link = (id: string) => new RegExp(`id="${id}"[^>]*data-link="([^"]+)"`).exec(html)?.[1];
expect(link("v")).toBe("lk-1");
expect(link("a")).toBe("lk-1");
expect(link("v-split")).toBe("lk-2");
expect(link("a-split")).toBe("lk-2");
});
it("gives an unlinked pair's right halves their own sync origin", () => {
const source =
'<div data-composition-id="c"><video id="v" src="t.mp4" muted data-sync-origin="lk-1" data-start="0" data-duration="4"></video><audio id="a" src="t.mp4" data-sync-origin="lk-1" data-start="0" data-duration="4"></audio></div>';
const first = splitElementInHtml(source, { id: "v" }, 2, "v-split");
const second = splitElementInHtml(first.html, { id: "a" }, 2, "a-split");
const html = relinkSplitHalvesInHtml(second.html, ["v-split", "a-split"]);
const origin = (id: string) =>
new RegExp(`id="${id}"[^>]*data-sync-origin="([^"]+)"`).exec(html)?.[1];
expect(origin("v")).toBe("lk-1");
expect(origin("v-split")).not.toBe("lk-1");
expect(origin("v-split")).toBe(origin("a-split"));
});
it("leaves unlinked splits byte-identical", () => {
const source = '<div><img id="i" data-start="0" data-duration="4"></div>';
expect(relinkSplitHalvesInHtml(source, ["i"])).toBe(source);
});
});