Files
hyperframes/packages/core/src/runtime/startResolver.test.ts
T
Miguel Ángel 0979e32a8d fix(core): a composition behind a wrapper takes its host's start (#6435)
* fix(core): a composition behind a wrapper takes its host's start

Fixes #4334.

* fix(core): a composition inside a timed wrapper starts with the wrapper

The nearest host or timed wrapper above a mounted root sets its start, so its clock starts when the wrapper shows it, matching how CSS animations already pick their clip.

* test(producer): re-pin the test classification digest
2026-10-26 16:48:57 +00:00

587 lines
23 KiB
TypeScript

import { describe, it, expect, afterEach, beforeAll } from "vitest";
import { DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS } from "@hyperframes/parsers/media-duration";
import { createRuntimeStartTimeResolver } from "./startResolver";
// jsdom doesn't provide CSS.escape — polyfill it
beforeAll(() => {
if (typeof globalThis.CSS === "undefined") {
(globalThis as any).CSS = {};
}
if (typeof CSS.escape !== "function") {
CSS.escape = (value: string) => value.replace(/([^\w-])/g, "\\$1");
}
});
describe("createRuntimeStartTimeResolver", () => {
afterEach(() => {
document.body.innerHTML = "";
});
describe("resolveStartForElement", () => {
it("resolves absolute numeric data-start", () => {
const el = document.createElement("div");
el.setAttribute("data-start", "5");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(el)).toBe(5);
});
it("resolves zero start", () => {
const el = document.createElement("div");
el.setAttribute("data-start", "0");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(el)).toBe(0);
});
it("returns fallback when no data-start", () => {
const el = document.createElement("div");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(el, 3)).toBe(3);
});
it("resolves reference to another element (after end)", () => {
const a = document.createElement("div");
a.id = "scene-1";
a.setAttribute("data-start", "2");
a.setAttribute("data-duration", "3");
document.body.appendChild(a);
const b = document.createElement("div");
b.setAttribute("data-start", "scene-1");
document.body.appendChild(b);
const resolver = createRuntimeStartTimeResolver({});
// scene-1 starts at 2, duration 3, so b starts at 2+3 = 5
expect(resolver.resolveStartForElement(b)).toBe(5);
});
it("resolves reference with positive offset", () => {
const a = document.createElement("div");
a.id = "intro";
a.setAttribute("data-start", "0");
a.setAttribute("data-duration", "5");
document.body.appendChild(a);
const b = document.createElement("div");
b.setAttribute("data-start", "intro + 2");
document.body.appendChild(b);
const resolver = createRuntimeStartTimeResolver({});
// intro ends at 5, offset +2 → 7
expect(resolver.resolveStartForElement(b)).toBe(7);
});
it("resolves reference with negative offset", () => {
const a = document.createElement("div");
a.id = "scene-a";
a.setAttribute("data-start", "0");
a.setAttribute("data-duration", "10");
document.body.appendChild(a);
const b = document.createElement("div");
b.setAttribute("data-start", "scene-a - 3");
document.body.appendChild(b);
const resolver = createRuntimeStartTimeResolver({});
// scene-a ends at 10, offset -3 → 7
expect(resolver.resolveStartForElement(b)).toBe(7);
});
it("clamps resolved start to 0", () => {
const a = document.createElement("div");
a.id = "clip";
a.setAttribute("data-start", "1");
a.setAttribute("data-duration", "2");
document.body.appendChild(a);
const b = document.createElement("div");
b.setAttribute("data-start", "clip - 100");
document.body.appendChild(b);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(b)).toBe(0);
});
it("handles circular references gracefully", () => {
const a = document.createElement("div");
a.id = "a";
a.setAttribute("data-start", "b");
document.body.appendChild(a);
const b = document.createElement("div");
b.id = "b";
b.setAttribute("data-start", "a");
document.body.appendChild(b);
const resolver = createRuntimeStartTimeResolver({});
// Should not infinite loop — returns fallback
expect(resolver.resolveStartForElement(a)).toBeGreaterThanOrEqual(0);
expect(resolver.resolveStartForElement(b)).toBeGreaterThanOrEqual(0);
});
it("uses data-composition-id selector for lookup", () => {
const comp = document.createElement("div");
comp.setAttribute("data-composition-id", "hero");
comp.setAttribute("data-start", "0");
comp.setAttribute("data-duration", "5");
document.body.appendChild(comp);
const after = document.createElement("div");
after.setAttribute("data-start", "hero");
document.body.appendChild(after);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(after)).toBe(5);
});
it("uses preserved authored duration when live composition duration was sanitized", () => {
const slide1 = document.createElement("div");
slide1.id = "slide-1";
slide1.setAttribute("data-composition-id", "slide-1");
slide1.setAttribute("data-start", "0");
slide1.setAttribute("data-hf-authored-duration", "14");
document.body.appendChild(slide1);
const slide2 = document.createElement("div");
slide2.id = "slide-2";
slide2.setAttribute("data-start", "slide-1");
slide2.setAttribute("data-hf-authored-duration", "12");
document.body.appendChild(slide2);
const slide3 = document.createElement("div");
slide3.setAttribute("data-start", "slide-2");
document.body.appendChild(slide3);
const resolver = createRuntimeStartTimeResolver({ includeAuthoredTimingAttrs: true });
expect(resolver.resolveStartForElement(slide2)).toBe(14);
expect(resolver.resolveStartForElement(slide3)).toBe(26);
});
it("adds composition host offset for nested absolute starts", () => {
const host = document.createElement("div");
host.id = "slide-5";
host.setAttribute("data-composition-id", "slide-video-agent");
host.setAttribute("data-start", "54");
host.setAttribute("data-duration", "45");
document.body.appendChild(host);
const innerRoot = document.createElement("div");
innerRoot.setAttribute("data-composition-id", "slide-video-agent");
host.appendChild(innerRoot);
const video = document.createElement("video");
video.setAttribute("data-start", "0");
innerRoot.appendChild(video);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(video)).toBe(54);
});
it("walks up to the host's data-start when the inner root has none (host has its own data-composition-id)", () => {
const host = document.createElement("div");
host.setAttribute("data-composition-id", "montage");
host.setAttribute("data-start", "10");
document.body.appendChild(host);
const innerRoot = document.createElement("div");
innerRoot.setAttribute("data-composition-id", "scene-10");
host.appendChild(innerRoot);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(innerRoot)).toBe(10);
});
it("walks up to the host's data-start via data-composition-file (anonymous host, post-inlining)", () => {
// A host mounted via data-composition-src with no data-composition-id of
// its own. After inlining, data-composition-src is stripped and replaced
// with data-composition-file, and the composition's own id is restored
// onto the wrapper (which has no data-start of its own).
const host = document.createElement("div");
host.setAttribute("data-composition-file", "compositions/reveal1.html");
host.setAttribute("data-start", "4.619");
document.body.appendChild(host);
const wrapper = document.createElement("div");
wrapper.setAttribute("data-composition-id", "reveal1");
wrapper.setAttribute("data-hf-inner-root", "true");
host.appendChild(wrapper);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(wrapper)).toBe(4.619);
});
describe.each([
['data-composition-src="child.html"'],
['data-composition-id="host"'],
['data-composition-file="compositions/child.html"'],
])("an inner root under a %s host", (marker) => {
it.each([0, 1, 2])("takes the host's start through %i neutral wrappers", (wrappers) => {
const open = "<section>".repeat(wrappers);
const close = "</section>".repeat(wrappers);
document.body.innerHTML = `
<div data-composition-id="root" data-start="0">
<div ${marker} data-start="5">
${open}<div id="inner" data-composition-id="child"></div>${close}
</div>
</div>`;
const inner = document.getElementById("inner")!;
expect(createRuntimeStartTimeResolver({}).resolveStartForElement(inner)).toBe(5);
});
});
it("takes the nearest host, not an outer one, across a wrapper", () => {
document.body.innerHTML = `
<div data-composition-src="outer.html" data-start="2">
<div data-composition-id="outer">
<div data-composition-src="inner.html" data-start="3">
<canvas><div id="inner" data-composition-id="inner"></div></canvas>
</div>
</div>
</div>`;
const inner = document.getElementById("inner")!;
// The inner host's 3 s is local to the outer composition, which starts at 2 s.
expect(createRuntimeStartTimeResolver({}).resolveStartForElement(inner)).toBe(5);
});
it("takes a timed wrapper's start over its host's", () => {
document.body.innerHTML = `
<div data-composition-id="root" data-start="0">
<div data-composition-id="scene" data-start="5">
<section data-start="2"><div id="inner" data-composition-id="child"></div></section>
</div>
</div>`;
const inner = document.getElementById("inner")!;
// The wrapper shows the inner composition from 2 s into the scene; its clock starts then.
expect(createRuntimeStartTimeResolver({}).resolveStartForElement(inner)).toBe(7);
});
it("keeps nested references in the host composition timeline", () => {
const host = document.createElement("div");
host.id = "slide-5";
host.setAttribute("data-composition-id", "slide-video-agent");
host.setAttribute("data-start", "54");
host.setAttribute("data-duration", "45");
document.body.appendChild(host);
const innerRoot = document.createElement("div");
innerRoot.setAttribute("data-composition-id", "slide-video-agent");
host.appendChild(innerRoot);
const firstClip = document.createElement("div");
firstClip.id = "bullet-reveal";
firstClip.setAttribute("data-start", "1");
firstClip.setAttribute("data-duration", "2");
innerRoot.appendChild(firstClip);
const secondClip = document.createElement("div");
secondClip.setAttribute("data-start", "bullet-reveal + 1");
innerRoot.appendChild(secondClip);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(firstClip)).toBe(55);
expect(resolver.resolveStartForElement(secondClip)).toBe(58);
});
it("adds the nearest composition root start for nested absolute media in inlined compositions", () => {
const root = document.createElement("div");
root.setAttribute("data-composition-id", "main");
document.body.appendChild(root);
const slide1 = document.createElement("div");
slide1.id = "slide-1";
slide1.setAttribute("data-composition-id", "slide-core-conviction");
slide1.setAttribute("data-start", "0");
slide1.setAttribute("data-hf-authored-duration", "14");
root.appendChild(slide1);
const slide2 = document.createElement("div");
slide2.id = "slide-2";
slide2.setAttribute("data-composition-id", "slide-avatar-v");
slide2.setAttribute("data-start", "slide-1");
slide2.setAttribute("data-hf-authored-duration", "12");
root.appendChild(slide2);
const slide3 = document.createElement("div");
slide3.id = "slide-3";
slide3.setAttribute("data-composition-id", "slide-translation");
slide3.setAttribute("data-start", "slide-2");
slide3.setAttribute("data-hf-authored-duration", "16");
root.appendChild(slide3);
const video = document.createElement("video");
video.setAttribute("data-start", "0");
slide3.appendChild(video);
const resolver = createRuntimeStartTimeResolver({ includeAuthoredTimingAttrs: true });
expect(resolver.resolveStartForElement(slide2)).toBe(14);
expect(resolver.resolveStartForElement(slide3)).toBe(26);
expect(resolver.resolveStartForElement(video)).toBe(26);
});
it("resolves a reference inside the referencing clip's own composition", () => {
const mount = (hostId: string, start: string) => {
const host = document.createElement("div");
host.id = hostId;
host.setAttribute("data-composition-id", "card");
host.setAttribute("data-start", start);
host.setAttribute("data-duration", "2");
document.body.appendChild(host);
const first = document.createElement("div");
first.id = "first";
first.setAttribute("data-start", "0");
first.setAttribute("data-duration", "1");
host.appendChild(first);
const second = document.createElement("div");
second.setAttribute("data-start", "first");
second.setAttribute("data-duration", "1");
host.appendChild(second);
return second;
};
const secondInA = mount("card-a", "0");
const secondInB = mount("card-b", "2");
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(secondInA)).toBe(1);
expect(resolver.resolveStartForElement(secondInB)).toBe(3);
});
it("returns fallback when reference target not found", () => {
const el = document.createElement("div");
el.setAttribute("data-start", "nonexistent");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(el, 0)).toBe(0);
});
it("caches resolved values (second call is same result)", () => {
const el = document.createElement("div");
el.setAttribute("data-start", "3.5");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
const first = resolver.resolveStartForElement(el);
const second = resolver.resolveStartForElement(el);
expect(first).toBe(second);
expect(first).toBe(3.5);
});
});
describe("resolveDurationForElement", () => {
it("resolves explicit data-duration", () => {
const el = document.createElement("div");
el.setAttribute("data-duration", "7");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveDurationForElement(el)).toBe(7);
});
it("resolves from data-end minus start", () => {
const el = document.createElement("div");
el.setAttribute("data-start", "2");
el.setAttribute("data-end", "8");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveDurationForElement(el)).toBe(6);
});
it.each([["data-start"], ["data-track-index"]])(
"gives an img with only %s the dropped-image default",
(attr) => {
const el = document.createElement("img");
el.setAttribute(attr, "1");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveDurationForElement(el)).toBe(
DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS,
);
},
);
it("leaves a bare img with no length", () => {
const el = document.createElement("img");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveDurationForElement(el)).toBeNull();
});
it("returns null when no duration info available", () => {
const el = document.createElement("div");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveDurationForElement(el)).toBeNull();
});
it("resolves from timeline registry for compositions", () => {
const el = document.createElement("div");
el.setAttribute("data-composition-id", "comp-1");
document.body.appendChild(el);
const mockTimeline = {
duration: () => 12,
time: () => 0,
play: () => {},
pause: () => {},
seek: () => {},
add: () => {},
paused: () => {},
set: () => {},
};
const resolver = createRuntimeStartTimeResolver({
timelineRegistry: { "comp-1": mockTimeline as any },
});
expect(resolver.resolveDurationForElement(el)).toBe(12);
});
it("prefers data-duration over timeline registry", () => {
const el = document.createElement("div");
el.setAttribute("data-composition-id", "comp-1");
el.setAttribute("data-duration", "5");
document.body.appendChild(el);
const mockTimeline = {
duration: () => 12,
time: () => 0,
play: () => {},
pause: () => {},
seek: () => {},
add: () => {},
paused: () => {},
set: () => {},
};
const resolver = createRuntimeStartTimeResolver({
timelineRegistry: { "comp-1": mockTimeline as any },
});
expect(resolver.resolveDurationForElement(el)).toBe(5);
});
it("resolves preserved authored duration when runtime stripped the public attr", () => {
const el = document.createElement("div");
el.setAttribute("data-composition-id", "comp-1");
el.setAttribute("data-hf-authored-duration", "9");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({ includeAuthoredTimingAttrs: true });
expect(resolver.resolveDurationForElement(el)).toBe(9);
});
it("ignores preserved authored duration by default", () => {
const el = document.createElement("div");
el.setAttribute("data-composition-id", "comp-1");
el.setAttribute("data-hf-authored-duration", "9");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveDurationForElement(el)).toBeNull();
});
it("caches duration results", () => {
const el = document.createElement("div");
el.setAttribute("data-duration", "4");
document.body.appendChild(el);
const resolver = createRuntimeStartTimeResolver({});
const first = resolver.resolveDurationForElement(el);
const second = resolver.resolveDurationForElement(el);
expect(first).toBe(second);
});
});
});
describe("documentRef", () => {
it("resolves references against a supplied document instead of the global one", () => {
const doc = document.implementation.createHTMLDocument("t");
const intro = doc.createElement("div");
intro.id = "intro";
intro.setAttribute("data-start", "0");
intro.setAttribute("data-duration", "4");
doc.body.appendChild(intro);
const outro = doc.createElement("div");
outro.setAttribute("data-start", "intro + 2");
doc.body.appendChild(outro);
const resolver = createRuntimeStartTimeResolver({ documentRef: doc });
// intro ends at 0 + 4; outro starts 2s after → 6.
expect(resolver.resolveStartForElement(outro)).toBe(6);
});
it("resolves a composition reference without the browser CSS namespace", () => {
const doc = document.implementation.createHTMLDocument("t");
doc.body.innerHTML =
'<div data-composition-id="intro" data-start="1" data-duration="4"></div>' +
'<div id="outro" data-start="intro + 2"></div>';
const css = globalThis.CSS;
Reflect.deleteProperty(globalThis, "CSS");
try {
const resolver = createRuntimeStartTimeResolver({ documentRef: doc });
expect(resolver.resolveStartForElement(doc.getElementById("outro")!)).toBe(7);
} finally {
globalThis.CSS = css;
}
});
it("defaults to the global document when documentRef is omitted", () => {
const el = document.createElement("div");
el.id = "ref-a";
el.setAttribute("data-start", "0");
el.setAttribute("data-duration", "2");
document.body.appendChild(el);
const dependent = document.createElement("div");
dependent.setAttribute("data-start", "ref-a");
document.body.appendChild(dependent);
const resolver = createRuntimeStartTimeResolver({});
expect(resolver.resolveStartForElement(dependent)).toBe(2);
});
});
describe("a host's in-point", () => {
afterEach(() => {
document.body.innerHTML = "";
});
it("shifts what a host holds by the host's in-point, through nested hosts", () => {
document.body.innerHTML =
`<div data-composition-id="main">` +
`<div id="half" data-composition-id="scene" data-start="5" data-duration="4" data-playback-start="5">` +
`<video id="v2" data-start="4"></video><video id="v3" data-start="8"></video></div>` +
`<div data-composition-id="early" data-start="2" data-duration="4" data-playback-start="5">` +
`<video id="legacy" data-start="3" data-hf-media-start-basis="global"></video></div>` +
`<div data-composition-id="outer" data-start="5" data-duration="10" data-playback-start="1">` +
`<div id="inner" data-composition-id="inner" data-start="2" data-duration="5">` +
`<video id="deep" data-start="0"></video></div></div></div>`;
const resolver = createRuntimeStartTimeResolver({});
const media = (id: string) =>
resolver.resolveMediaStartForElement(document.getElementById(id)!);
// The half starts at 5 with in-point 5: local t plays at 5 + t - 5.
expect([media("v2"), media("v3")]).toEqual([4, 8]);
expect(resolver.resolveHostStartForElement(document.getElementById("v2")!)).toBe(0);
// Root-time media keeps its authored time, even where the in-point puts local 0 before 0.
expect(media("legacy")).toBe(3);
// Outer at 5 with in-point 1 puts the inner host at 5 - 1 + 2 = 6.
expect(resolver.resolveStartForElement(document.getElementById("inner")!)).toBe(6);
expect(media("deep")).toBe(6);
});
it("places a relative start where the same local time written as a number lands", () => {
// A host at 0 with in-point 5 puts local 0 at -5.
document.body.innerHTML =
`<div data-composition-id="main"><div data-composition-id="half" data-start="0" data-duration="7" data-playback-start="5">` +
`<div id="x" data-start="0" data-duration="1"></div>` +
`<video id="relative" data-start="x + 3"></video><video id="numeric" data-start="4"></video></div></div>`;
const resolver = createRuntimeStartTimeResolver({});
const media = (id: string) =>
resolver.resolveMediaStartForElement(document.getElementById(id)!);
expect([media("relative"), media("numeric")]).toEqual([-1, -1]);
});
});