Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { initSandboxRuntimeModular } from "./init";
import { WebAudioTransport } from "./webAudioTransport";
import { STUDIO_MANUAL_EDIT_GESTURE_ATTR } from "../editing/draftMarkers";
import type { RuntimeTimelineLike } from "./types";
// The readiness gate's 8s timeout is a one-shot timer these transport tests must not count.
vi.mock("../compositionReadiness", async (importOriginal) => {
const actual = await importOriginal<typeof import("../compositionReadiness")>();
return {
...actual,
settleCompositionReadiness: vi.fn(),
settleFirstFrameCompositionReadiness: vi.fn(),
};
});
/**
* The transport parks itself when the editor is paused and settled. Everything
* it used to discover by looking again on the next frame has to arrive by some
* other route, and each of those routes gets a test here — one per row of the
* enumeration in the PR body. A loop that stops noticing one of them is a
* correctness regression no performance test would catch.
*/
const PARK_HEARTBEAT_MS = 80; // state.bridgeMaxPostIntervalMs
function createManualRaf() {
let now = 0;
let nextId = 0;
const callbacks = new Map<number, FrameRequestCallback>();
return {
requestAnimationFrame: (callback: FrameRequestCallback) => {
nextId += 1;
callbacks.set(nextId, callback);
return nextId;
},
cancelAnimationFrame: (id: number) => {
callbacks.delete(id);
},
pending: () => callbacks.size,
step: (milliseconds = 16) => {
now += milliseconds;
const batch = Array.from(callbacks.entries());
callbacks.clear();
for (const [, callback] of batch) callback(now);
},
now: () => now,
};
}
function createMockTimeline(duration: number): RuntimeTimelineLike {
const state = { time: 0, paused: true, duration };
return {
play: () => {
state.paused = false;
},
pause: () => {
state.paused = true;
},
seek: (time?: number) => {
if (time !== undefined) state.time = time;
return state.time;
},
totalTime: (time?: number) => {
if (time !== undefined) state.time = time;
return state.time;
},
time: () => state.time,
duration: () => state.duration,
add: () => {},
paused: (value?: boolean) => {
if (typeof value === "boolean") state.paused = value;
return state.paused;
},
timeScale: () => {},
set: () => {},
getChildren: () => [],
};
}
/** jsdom implements neither play() nor pause(), and `paused` is the only state the
* runtime reads. Returns a handle driving it the way a browser does, so a test can
* start the element and watch whether the transport stops it. */
function stubMediaPlayback(
el: HTMLMediaElement,
durationSeconds: number,
): { start: () => void; isPaused: () => boolean } {
let paused = true;
Object.defineProperty(el, "duration", { value: durationSeconds, configurable: true });
Object.defineProperty(el, "paused", { configurable: true, get: () => paused });
el.pause = () => {
paused = true;
};
el.play = () => {
paused = false;
// A real browser fires this, and firing it is what makes the defect deterministic.
el.dispatchEvent(new Event("play"));
return Promise.resolve();
};
return { start: () => void el.play(), isPaused: () => paused };
}
/** MutationObserver records land in a microtask; nothing observes them sooner. */
const flushObservers = () => new Promise<void>((resolve) => queueMicrotask(() => resolve()));
describe("parked transport loop", () => {
const originalRaf = window.requestAnimationFrame;
const originalCancelRaf = window.cancelAnimationFrame;
let raf: ReturnType<typeof createManualRaf>;
let posted: Array<Record<string, unknown>>;
const mount = (bodyHtml = "") => {
document.body.innerHTML = `<div id="root" data-composition-id="main" data-root="true" data-start="0" data-duration="5">${bodyHtml}</div>`;
window.__timelines = { main: createMockTimeline(5) };
};
/** Run frames until nothing asks for another one. */
const settle = (maxFrames = 200): number => {
let frames = 0;
while (raf.pending() > 0 && frames < maxFrames) {
raf.step();
frames += 1;
}
return frames;
};
/** One frame at 120 Hz: the clock and the animation frame advance together. */
const frame120Hz = () => {
vi.advanceTimersByTime(8);
raf.step(8);
};
/**
* Park the transport AND drain init's own one-shot timers, several of which
* post state and would otherwise be mistaken for a heartbeat. Leaves exactly
* one timer pending: the parked heartbeat.
*/
const quiesce = (): void => {
settle();
// Up to ~400 ms of 1 ms steps: the transport holds a deferred manifest
// post for one cadence interval before it may park.
for (let i = 0; i < 400; i += 1) {
if (raf.pending() === 0 && vi.getTimerCount() <= 1) return;
vi.advanceTimersByTime(1);
settle();
}
throw new Error(
`transport never quiesced (raf ${raf.pending()}, timers ${vi.getTimerCount()})`,
);
};
beforeEach(() => {
vi.useFakeTimers({
toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"],
});
document.body.innerHTML = "";
(globalThis as typeof globalThis & { CSS?: { escape?: (v: string) => string } }).CSS ??= {};
globalThis.CSS.escape ??= (value: string) => value;
raf = createManualRaf();
window.requestAnimationFrame = raf.requestAnimationFrame as typeof window.requestAnimationFrame;
window.cancelAnimationFrame = raf.cancelAnimationFrame as typeof window.cancelAnimationFrame;
posted = [];
vi.spyOn(window.parent, "postMessage").mockImplementation((message: unknown) => {
posted.push(message as Record<string, unknown>);
});
window.__timelines = {};
});
afterEach(() => {
window.__hfRuntimeTeardown?.();
delete (document as { visibilityState?: DocumentVisibilityState }).visibilityState;
document.body.innerHTML = "";
window.__timelines = {} as Record<string, RuntimeTimelineLike>;
delete window.__player;
delete window.__playerReady;
delete window.__HF_EXPORT_RENDER_SEEK_CONFIG;
delete (window as { __hfLottie?: unknown }).__hfLottie;
vi.restoreAllMocks();
vi.useRealTimers();
window.requestAnimationFrame = originalRaf;
window.cancelAnimationFrame = originalCancelRaf;
});
it("stops asking for animation frames once paused and settled", () => {
mount();
initSandboxRuntimeModular();
quiesce();
expect(raf.pending()).toBe(0);
// Exactly one thing still scheduled: the parked heartbeat.
expect(vi.getTimerCount()).toBe(1);
});
it("reports the end in the state it posts when the film finishes", () => {
let nowMs = 1000;
vi.spyOn(performance, "now").mockImplementation(() => nowMs);
document.body.innerHTML = `<div id="root" data-composition-id="main" data-root="true" data-start="0" data-duration="4.97"><div id="clip" data-start="0.48" data-duration="4.49"></div></div>`;
window.__timelines = { main: createMockTimeline(4.97) };
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
for (let step = 0; step < 120 && window.__player!.isPlaying(); step += 1) {
nowMs += 50;
raf.step(50);
}
const states = posted.filter((m) => m["type"] === "state");
expect(states.at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 149 });
});
const setPlayRange = (startSeconds: number | null, endSeconds: number | null) =>
window.dispatchEvent(
new MessageEvent("message", {
source: window.parent,
data: {
source: "hf-parent",
type: "control",
action: "set-play-range",
startSeconds,
endSeconds,
},
}),
);
const stateMessages = () => posted.filter((m) => m["type"] === "state");
/** Mounts a 5 s film with clips a [0, 3) and b [3, 5), driven by a mocked clock. */
const mountRangeFilm = () => {
let nowMs = 1000;
vi.spyOn(performance, "now").mockImplementation(() => nowMs);
mount(
`<div id="a" data-start="0" data-duration="3"></div><div id="b" data-start="3" data-duration="2"></div>`,
);
const timeline = window.__timelines!.main!;
initSandboxRuntimeModular();
quiesce();
const frames: Array<{ time: number; b: string }> = [];
const step = () => {
nowMs += 7;
raf.step(7);
frames.push({ time: timeline.time(), b: document.getElementById("b")!.style.visibility });
};
const playOut = () => {
window.__player!.play();
for (let n = 0; n < 1000 && window.__player!.isPlaying(); n += 1) step();
};
return { timeline, frames, step, playOut };
};
it("stops on a play range's last frame, says it ended, and restarts at the range start only while it is set", () => {
const { timeline, frames, playOut } = mountRangeFilm();
setPlayRange(2, 3);
window.__player!.seek(2);
for (let wrap = 0; wrap < 3; wrap += 1) playOut();
expect(stateMessages().at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 89 });
expect(stateMessages().at(-1)?.["currentTime"]).toBeCloseTo(89 / 30, 9);
expect(timeline.time()).toBeCloseTo(89 / 30, 9);
expect(Math.max(...frames.map((f) => f.time))).toBeLessThan(3);
expect(frames.every((f) => f.b === "hidden")).toBe(true);
expect(document.getElementById("a")!.style.visibility).not.toBe("hidden");
expect(window.__player!.getDuration()).toBe(5);
const before = stateMessages().length;
window.__player!.play();
expect(stateMessages()[before]).toMatchObject({ isPlaying: true, frame: 60 });
window.__player!.pause();
setPlayRange(null, null);
playOut();
expect(stateMessages().at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 150 });
const atFilmEnd = stateMessages().length;
window.__player!.play();
expect(stateMessages()[atFilmEnd]).toMatchObject({ isPlaying: true, frame: 0 });
});
it("jumps to the range start and keeps playing when a new range leaves the playhead outside", () => {
const { step } = mountRangeFilm();
setPlayRange(2, 3);
window.__player!.seek(2.5);
window.__player!.play();
step();
const before = stateMessages().length;
setPlayRange(2, 2.4);
const after = stateMessages().slice(before);
expect(after.some((m) => m["ended"] === true)).toBe(false);
expect(after.at(-1)).toMatchObject({ isPlaying: true, currentTime: 2 });
expect(after.at(-1)?.["capabilities"]).toContain("play-range");
expect(window.__player!.isPlaying()).toBe(true);
});
// The render stops at the root's declared length too; a longer animation is cut off.
it.each([
["3 s, shorter than its animation", "3", 90],
["under a second", "0.2", 6],
["one 60 fps frame", String(1 / 60), 1],
])("stops a film declared %s at that length, and says so", (_label, declared, frame) => {
const seconds = Number(declared);
let nowMs = 1000;
vi.spyOn(performance, "now").mockImplementation(() => nowMs);
document.body.innerHTML = `<div id="root" data-composition-id="main" data-root="true" data-start="0" data-duration="${declared}"></div>`;
window.__timelines = { main: createMockTimeline(5) };
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
for (let step = 0; step < 400 && window.__player!.isPlaying(); step += 1) {
nowMs += 10;
raf.step(10);
}
const states = posted.filter((m) => m["type"] === "state");
expect(states.at(-1)).toMatchObject({ isPlaying: false, ended: true, frame });
expect(window.__player!.getDuration()).toBeCloseTo(seconds, 9);
const timeline = posted.filter((m) => m["type"] === "timeline").at(-1);
expect(timeline?.["durationSeconds"]).toBeCloseTo(seconds, 9);
});
it("keeps asking for animation frames while playing", () => {
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
// Every frame during playback re-arms: the loop must never park mid-play.
for (let i = 0; i < 10; i += 1) {
expect(raf.pending()).toBeGreaterThan(0);
raf.step();
}
expect(raf.pending()).toBeGreaterThan(0);
});
/** The host's per-frame tick, as the player posts it on the runtime-bridge path. */
const hostTick = () =>
window.dispatchEvent(
new MessageEvent("message", {
source: window.parent,
data: { source: "hf-parent", type: "control", action: "tick" },
}),
);
const countSeeks = () => {
const timeline = window.__timelines!["main"] as RuntimeTimelineLike;
const seeks: number[] = [];
const originalTotalTime = timeline.totalTime!.bind(timeline);
timeline.totalTime = (time?: number, suppress?: boolean) => {
if (time !== undefined) seeks.push(time);
return originalTotalTime(time, suppress);
};
return seeks;
};
it("does not seek a timeline time already rendered by its frame loop", () => {
vi.spyOn(performance, "now").mockReturnValue(1000);
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
frame120Hz();
const seeks = countSeeks();
frame120Hz();
const perFrame = seeks.length;
hostTick();
expect(perFrame).toBeGreaterThan(0);
expect(seeks.length).toBe(perFrame);
});
it("renders a newer host time after its own frame rendered an earlier time", () => {
let nowMs = 1000;
vi.spyOn(performance, "now").mockImplementation(() => nowMs);
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
nowMs = 1008;
frame120Hz();
const seeks = countSeeks();
nowMs = 1024;
hostTick();
expect(seeks).toContain(0.024);
});
it("reapplies an explicit seek even when that timeline time was already rendered", () => {
vi.spyOn(performance, "now").mockReturnValue(1000);
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
frame120Hz();
const timeline = window.__timelines!["main"]!;
timeline.totalTime!(1);
const seeks = countSeeks();
window.__player!.seek(0);
expect(seeks).toContain(0);
expect(timeline.totalTime!()).toBe(0);
});
it("refreshes the WebAudio snapshot on host ticks without iframe frames", () => {
let audioTime = 0;
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
vi.spyOn(WebAudioTransport.prototype, "ownsClock").mockReturnValue(true);
vi.spyOn(WebAudioTransport.prototype, "context", "get").mockReturnValue({} as AudioContext);
vi.spyOn(WebAudioTransport.prototype, "getTime").mockImplementation(() => audioTime);
frame120Hz();
const seeks = countSeeks();
audioTime = 0.024;
hostTick();
const firstSeekCount = seeks.length;
hostTick();
expect(seeks.length).toBe(firstSeekCount);
audioTime = 0.048;
hostTick();
expect(seeks).toContain(0.024);
expect(seeks.at(-1)).toBe(0.048);
expect(window.__player!.getTime()).toBe(0.048);
});
it.each([false, true])(
"renders the first host tick after play with prior playback %s",
(resume) => {
let nowMs = 1000;
vi.spyOn(performance, "now").mockImplementation(() => nowMs);
mount();
initSandboxRuntimeModular();
quiesce();
if (resume) {
window.__player!.play();
frame120Hz();
window.__player!.pause();
quiesce();
}
window.__player!.play();
const seeks = countSeeks();
nowMs += 8;
vi.advanceTimersByTime(8);
hostTick();
expect(seeks.length).toBeGreaterThan(0);
},
);
it("advances on the host's ticks while its own animation frames are throttled", () => {
let nowMs = 1000;
vi.spyOn(performance, "now").mockImplementation(() => nowMs);
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
frame120Hz();
hostTick();
const seeks = countSeeks();
for (let i = 0; i < 3; i += 1) {
nowMs += 8;
vi.advanceTimersByTime(8);
hostTick();
}
expect(seeks).toContain(0.008);
expect(seeks).toContain(0.016);
expect(seeks.at(-1)).toBe(0.024);
});
it("posts the paused bridge heartbeat on its documented interval while parked", () => {
mount();
initSandboxRuntimeModular();
quiesce();
const before = posted.filter((m) => m["type"] === "state").length;
for (let beat = 0; beat < 3; beat += 1) vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
const after = posted.filter((m) => m["type"] === "state").length;
expect(after - before).toBe(3);
// Still parked: the heartbeat is a timer, not a frame.
expect(raf.pending()).toBe(0);
});
const setIdleHeartbeat = (slow: boolean) =>
window.dispatchEvent(
new MessageEvent("message", {
source: window.parent,
data: { source: "hf-parent", type: "control", action: "set-idle-heartbeat", slow },
}),
);
const states = () => posted.filter((m) => m["type"] === "state").length;
it("slows the parked heartbeat to once a second when the host asks, and back when it stops", () => {
mount();
initSandboxRuntimeModular();
quiesce();
setIdleHeartbeat(true);
quiesce();
const slow = states();
vi.advanceTimersByTime(3000);
expect(states() - slow).toBe(3);
expect(raf.pending()).toBe(0);
// Turned off mid-interval, the 80 ms beat resumes without waiting out the second.
vi.advanceTimersByTime(500);
setIdleHeartbeat(false);
settle();
const resumed = states();
for (let beat = 0; beat < 3; beat += 1) vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
expect(states() - resumed).toBe(3);
});
it("keeps the fast heartbeat under a slow request until a timeline is bound", () => {
mount();
window.__timelines = {};
initSandboxRuntimeModular();
document.getElementById("root")!.removeAttribute("data-duration");
setIdleHeartbeat(true);
quiesce();
// A composition that registers its timeline late (after fonts load) must still be seen at once.
window.__timelines!["main"] = createMockTimeline(12);
vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
settle();
expect(window.__player!.getDuration()).toBeCloseTo(12, 3);
});
it("keeps the fast heartbeat under a slow request while a sub-composition is unbound", () => {
mount('<div data-composition-id="child"></div>');
initSandboxRuntimeModular();
setIdleHeartbeat(true);
quiesce();
const before = states();
for (let beat = 0; beat < 3; beat += 1) vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
expect(states() - before).toBe(3);
});
it("delivers a live data-duration edit while parked", async () => {
mount();
initSandboxRuntimeModular();
quiesce();
window.__timelines!["main"] = createMockTimeline(9);
document.getElementById("root")!.setAttribute("data-duration", "9");
await flushObservers();
settle();
expect(window.__player!.getDuration()).toBeCloseTo(9, 3);
});
it("delivers a timeline registered into window.__timelines, which no observer can see", () => {
mount();
window.__timelines = {};
initSandboxRuntimeModular();
document.getElementById("root")!.removeAttribute("data-duration");
quiesce();
expect(window.__player!.getDuration()).not.toBeCloseTo(12, 3);
// No DOM mutation and no event: the registry is a plain object. Only the
// parked heartbeat's signature re-read can find this.
window.__timelines!["main"] = createMockTimeline(12);
vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
settle();
expect(window.__player!.getDuration()).toBeCloseTo(12, 3);
});
it("delivers a timed element mounted after the loop parked", async () => {
mount();
initSandboxRuntimeModular();
quiesce();
const manifestBefore = window.__clipManifest?.clips.length ?? 0;
const late = document.createElement("div");
late.id = "late-clip";
late.setAttribute("data-start", "1");
late.setAttribute("data-duration", "2");
document.getElementById("root")!.appendChild(late);
await flushObservers();
settle();
expect(window.__clipManifest!.clips.length).toBeGreaterThan(manifestBefore);
expect(window.__clipManifest!.clips.some((clip) => clip.id === "late-clip")).toBe(true);
});
it("delivers media metadata that arrives after the loop parked", async () => {
mount(`<video id="v" data-start="0" src="a.mp4"></video>`);
// A declared length would hold the film at 5 s; only an inferred one can grow.
document.getElementById("root")!.removeAttribute("data-duration");
initSandboxRuntimeModular();
quiesce();
const video = document.getElementById("v") as HTMLVideoElement;
Object.defineProperty(video, "duration", { value: 30, configurable: true });
// `durationchange` is an event, not a DOM mutation: this is the only route.
video.dispatchEvent(new Event("durationchange"));
await flushObservers();
settle();
expect(window.__player!.getDuration()).toBeGreaterThanOrEqual(30);
});
it("delivers the start of a Studio manual-edit gesture while parked", async () => {
mount(`<div id="c" data-start="0" data-duration="2"></div>`);
initSandboxRuntimeModular();
quiesce();
expect(raf.pending()).toBe(0);
document.getElementById("c")!.setAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR, "token-1");
await flushObservers();
expect(raf.pending()).toBeGreaterThan(0);
});
it("runs the reconciling seek the frame a manual-edit gesture ends", async () => {
mount(`<div id="c" data-start="0" data-duration="2"></div>`);
initSandboxRuntimeModular();
quiesce();
const target = document.getElementById("c")!;
target.setAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR, "token-1");
await flushObservers();
raf.step();
// A gesture owns the paused frame: the loop defers the seek and parks until the marker clears.
expect(raf.pending()).toBe(0);
const timeline = window.__timelines!["main"] as RuntimeTimelineLike;
const seeks: number[] = [];
const originalTotalTime = timeline.totalTime!.bind(timeline);
timeline.totalTime = (time?: number, suppress?: boolean) => {
if (time !== undefined) seeks.push(time);
return originalTotalTime(time, suppress);
};
target.removeAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR);
await flushObservers();
raf.step();
expect(seeks.length).toBeGreaterThan(0);
});
it("wakes on an explicit seek from the control surface", () => {
mount();
initSandboxRuntimeModular();
quiesce();
expect(raf.pending()).toBe(0);
window.__player!.seek(1);
expect(raf.pending()).toBeGreaterThan(0);
settle();
expect(window.__player!.getTime()).toBeCloseTo(1, 3);
});
it("never parks while an export render is driving frames", () => {
window.__HF_EXPORT_RENDER_SEEK_CONFIG = { mode: "seek" };
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.renderSeek(1);
// The render path must keep the exact scheduling it had before: a frame is
// always in flight, whatever the playhead is doing.
for (let i = 0; i < 10; i += 1) {
expect(raf.pending()).toBeGreaterThan(0);
raf.step();
}
});
it("still parks after Studio's own renderSeek fallback, which is not a render", () => {
// `playbackAdapter` drives an overhanging-timeline preview through
// renderSeek. Latching on that alone would leave the loop unparked for the
// whole session — the export config is what separates the two.
expect(window.__HF_EXPORT_RENDER_SEEK_CONFIG).toBeUndefined();
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.renderSeek(1);
quiesce();
expect(raf.pending()).toBe(0);
expect(window.__player!.getTime()).toBeCloseTo(1, 3);
});
it("stops both the frame loop and the parked timer on teardown", () => {
mount();
initSandboxRuntimeModular();
quiesce();
window.__hfRuntimeTeardown?.();
posted.length = 0;
// The count, not just the silence: a heartbeat that is still armed but
// returns early on `tornDown` posts nothing either, so counting posts
// alone passes with the clearTimeout deleted.
expect(vi.getTimerCount()).toBe(0);
vi.advanceTimersByTime(PARK_HEARTBEAT_MS * 5);
expect(raf.pending()).toBe(0);
expect(posted.filter((m) => m["type"] === "state")).toHaveLength(0);
});
it("rate-limits the manifest while playing, whatever the DOM does", () => {
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
// Two seconds in, so the rebind policy's play hold is not what is doing
// the work — this has to hold for the rest of playback too.
for (let i = 0; i < 130; i += 1) raf.step();
const root = document.getElementById("root")!;
const before = posted.filter((m) => m["type"] === "timeline").length;
for (let frame = 0; frame < 30; frame += 1) {
// A composition that appends a node every frame. The manifest is a full
// document walk; posting it per frame is the regression this guards.
const node = document.createElement("div");
node.setAttribute("data-start", String(frame));
node.setAttribute("data-duration", "1");
root.appendChild(node);
raf.step();
}
const posts = posted.filter((m) => m["type"] === "timeline").length - before;
// Main's cadence over 30 frames is one post per 20 frames, so at most two.
expect(posts).toBeLessThanOrEqual(2);
});
it("does not re-post the manifest while playing a film that is not changing", () => {
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
// Past the rebind policy's play hold, at 120 Hz.
for (let i = 0; i < 300; i += 1) frame120Hz();
const before = posted.filter((m) => m["type"] === "timeline").length;
for (let i = 0; i < 250; i += 1) frame120Hz();
expect(posted.filter((m) => m["type"] === "timeline").length - before).toBe(0);
});
it("posts a playing clip's new track, label and z-index once playback stops", async () => {
mount(
'<div id="clip" data-start="0" data-duration="5" data-track-index="0" data-timeline-label="Before" style="z-index: 1"></div>',
);
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
for (let i = 0; i < 300; i += 1) frame120Hz();
const clip = document.getElementById("clip")!;
clip.setAttribute("data-track-index", "7");
clip.setAttribute("data-timeline-label", "After");
clip.style.zIndex = "9";
await flushObservers();
posted.length = 0;
for (let i = 0; i < 130; i += 1) frame120Hz();
expect(posted.filter((m) => m["type"] === "timeline")).toHaveLength(0);
window.__player!.pause();
for (let i = 0; i < 10; i += 1) frame120Hz();
const clips = (posted.filter((m) => m["type"] === "timeline").at(-1)?.["clips"] ?? []) as Array<
Record<string, unknown>
>;
const clip_ = clips.find((c) => c["id"] === "clip");
expect([clip_?.["track"], clip_?.["timelineLabel"], clip_?.["zIndex"]]).toEqual([
7,
"After",
9,
]);
});
it("posts a label edited while playing and paused before the next poll", async () => {
mount('<div id="clip" data-start="0" data-duration="5" data-timeline-label="Before"></div>');
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
for (let i = 0; i < 300; i += 1) frame120Hz();
document.getElementById("clip")!.setAttribute("data-timeline-label", "After");
await flushObservers();
for (let i = 0; i < 12; i += 1) frame120Hz();
window.__player!.pause();
for (let i = 0; i < 300; i += 1) frame120Hz();
const clips = (posted.filter((m) => m["type"] === "timeline").at(-1)?.["clips"] ?? []) as Array<
Record<string, unknown>
>;
expect(clips.find((c) => c["id"] === "clip")?.["timelineLabel"]).toBe("After");
});
it("applies a data-width change while playing", async () => {
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
for (let i = 0; i < 300; i += 1) frame120Hz();
const root = document.getElementById("root")!;
root.setAttribute("data-width", "640");
await flushObservers();
for (let i = 0; i < 60; i += 1) frame120Hz();
expect(root.style.width).toBe("640px");
});
it("applies a data-height change while parked", async () => {
mount();
initSandboxRuntimeModular();
quiesce();
const root = document.getElementById("root")!;
root.setAttribute("data-height", "360");
await flushObservers();
vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
settle();
expect(root.style.height).toBe("360px");
});
it("does not park when the manifest post throws with a change still pending", async () => {
mount();
initSandboxRuntimeModular();
quiesce();
// postTimeline walks author DOM, which can throw. Fail it exactly once.
const NODE_SELECTOR =
"[data-start], [data-track-index], [data-composition-id], video, audio, img";
const realQueryAll = Document.prototype.querySelectorAll;
let failuresLeft = 1;
vi.spyOn(Document.prototype, "querySelectorAll").mockImplementation(function (
this: Document,
selector: string,
) {
if (selector === NODE_SELECTOR && failuresLeft > 0) {
failuresLeft -= 1;
throw new Error("author DOM blew up");
}
return realQueryAll.call(this, selector);
} as typeof Document.prototype.querySelectorAll);
const late = document.createElement("div");
late.id = "late-after-throw";
late.setAttribute("data-start", "1");
late.setAttribute("data-duration", "2");
document.getElementById("root")!.appendChild(late);
await flushObservers();
// Run frames until the manifest post is attempted and throws. The post is
// rate-limited, so it lands on the frame counter's boundary, not the first
// woken frame.
let thrown: unknown = null;
for (let frame = 0; frame < 60 && thrown == null; frame += 1) {
if (raf.pending() === 0) break;
try {
raf.step();
} catch (error) {
thrown = error;
}
}
expect(String(thrown)).toContain("author DOM blew up");
// The change is still owed, so the loop must not have parked on it.
expect(raf.pending()).toBeGreaterThan(0);
settle();
expect(window.__clipManifest!.clips.some((clip) => clip.id === "late-after-throw")).toBe(true);
});
it("delivers an adapter duration that grows while parked, with no DOM mutation and no event", () => {
mount();
document.getElementById("root")!.removeAttribute("data-duration");
initSandboxRuntimeModular();
quiesce();
const before = window.__player!.getDuration();
// A Lottie instance lengthening is a live animation object changing. No
// observer and no event can see it; only the parked poll can.
window.__hfLottie = [{ goToAndStop: () => {}, totalFrames: 600, frameRate: 30 }] as never;
vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
settle();
expect(before).toBeLessThan(20);
expect(window.__player!.getDuration()).toBeCloseTo(20, 3);
});
it("stops a media element that starts playing while parked and the clock is paused", () => {
// Nothing may run while the clock is paused. `play` does not bubble, so the
// wake comes from a capture-phase listener; without it the enforcement is
// unreachable exactly when it is needed, because a parked loop runs no ticks.
mount(`<video id="rogue" data-start="0" data-duration="5"></video>`);
const media = stubMediaPlayback(document.getElementById("rogue") as HTMLVideoElement, 5);
initSandboxRuntimeModular();
quiesce();
expect(window.__player!.isPlaying()).toBe(false);
expect(raf.pending()).toBe(0);
// Autoplay, a composition script, a restored bfcache state.
media.start();
settle();
expect(media.isPaused()).toBe(true);
});
it("stops hosted media with no data-start of its own, which the transport also drives", () => {
// A clip inside a composition inherits its timing from the host. It is the
// transport's to play, so it is the transport's to stop; a probe keyed on
// data-start alone could not see it.
mount(`
<div data-composition-id="host" data-start="0" data-duration="10">
<video id="hosted" data-duration="5"></video>
</div>`);
const media = stubMediaPlayback(document.getElementById("hosted") as HTMLVideoElement, 5);
initSandboxRuntimeModular();
quiesce();
media.start();
settle();
expect(media.isPaused()).toBe(true);
});
it("leaves a LEASED element alone while paused, and stops it once released", () => {
// The colour-grading preview and the Studio's scrub audition both play media
// on purpose with the clock stopped. They borrow the element first; the
// enforcement is for anything that plays without borrowing.
mount(`<video id="grade" data-start="0" data-duration="5"></video>`);
const video = document.getElementById("grade") as HTMLVideoElement;
const media = stubMediaPlayback(video, 5);
initSandboxRuntimeModular();
quiesce();
window.__hf!.leasePausedMedia!(video);
media.start();
settle();
// Several more ticks: a lease must survive more than the frame it was taken on.
for (let i = 0; i < 5; i += 1) {
window.__player!.seek(window.__player!.getTime());
settle();
}
expect(media.isPaused()).toBe(false);
window.__hf!.releasePausedMedia!(video);
settle();
expect(media.isPaused()).toBe(true);
});
it("does not stop the colour-grading preview, which plays on purpose while paused", () => {
// The end-to-end wiring, not the lease in isolation: init constructs the
// grading runtime with the lease, so startPreviewPlayback borrows before the
// play() whose own event wakes the transport that would otherwise stop it.
mount(`<video id="graded" data-start="0" data-duration="5"></video>`);
const video = document.getElementById("graded") as HTMLVideoElement;
const media = stubMediaPlayback(video, 5);
let currentTime = 0;
Object.defineProperty(video, "currentTime", {
configurable: true,
get: () => currentTime,
set: (next: number) => {
currentTime = next;
},
});
initSandboxRuntimeModular();
quiesce();
const stop = window.__hf!.colorGrading!.startPreviewPlayback("graded");
expect(typeof stop).toBe("function");
settle();
for (let beat = 0; beat < 5; beat += 1) {
vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
settle();
}
expect(media.isPaused()).toBe(false);
stop!();
expect(media.isPaused()).toBe(true);
// The stop closure must RELEASE, not just pause: a restart after it is an
// unleased play while paused, and the transport has to stop it.
media.start();
settle();
expect(media.isPaused()).toBe(true);
});
it("reclaims a leased element the moment the transport plays", () => {
// A lease is an exemption from the PAUSED-side enforcement only. Once the
// clock runs the transport owns every element again, so a leased clip that is
// outside the playhead's window is stopped like any other.
mount(`<video id="late" data-start="10" data-duration="5"></video>`);
const video = document.getElementById("late") as HTMLVideoElement;
const media = stubMediaPlayback(video, 5);
initSandboxRuntimeModular();
quiesce();
window.__hf!.leasePausedMedia!(video);
media.start();
settle();
expect(media.isPaused()).toBe(false);
window.__player!.play();
settle();
expect(window.__player!.isPlaying()).toBe(true);
expect(media.isPaused()).toBe(true);
});
const setVisibility = (state: DocumentVisibilityState) => {
Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
document.dispatchEvent(new Event("visibilitychange"));
};
it("keeps the transport ticking on a timer while the document is hidden", () => {
// A hidden document runs no animation frames but its media keeps playing, so a
// transport driven by frames alone never ends a clip at the end of its window.
let nowMs = 1000;
vi.spyOn(performance, "now").mockImplementation(() => nowMs);
mount(`<audio id="a1" data-start="0" data-duration="1"></audio>`);
const media = stubMediaPlayback(document.getElementById("a1") as HTMLAudioElement, 10);
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
settle();
expect(media.isPaused()).toBe(false);
setVisibility("hidden");
for (let i = 0; i < 100; i += 1) {
nowMs += 16;
vi.advanceTimersByTime(16);
}
expect(window.__player!.getTime()).toBeGreaterThan(1);
expect(media.isPaused()).toBe(true);
});
it("moves a pending tick between animation frames and a timer as visibility changes", () => {
mount();
initSandboxRuntimeModular();
quiesce();
window.__player!.play();
expect(raf.pending()).toBe(1);
setVisibility("hidden");
expect(raf.pending()).toBe(0);
vi.advanceTimersByTime(16);
expect(raf.pending()).toBe(0);
expect(window.__player!.isPlaying()).toBe(true);
setVisibility("visible");
expect(raf.pending()).toBe(1);
});
});