Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { swallow } from "../diagnostics";
/**
* Shared, deduplicated `"hf-seek"` CustomEvent dispatcher for GPU adapters.
*
* Both the Three.js and TypeGPU adapters dispatch the same `"hf-seek"` event
* so that compositions need not know which GPU library they're paired with.
* Without deduplication, a seek to time T would fire two events (one from each
* adapter), doubling per-scrub work in any composition that has both present.
*
* This module deduplicates by tracking the last dispatched time. If the same
* time value is dispatched twice in the same synchronous call stack (e.g. two
* adapters both calling `dispatchSeekEvent(5.0)` without yielding), only the
* first call fires the event.
*
* The deduplication is intentionally coarse (exact float equality). Adapter
* seek paths clamp and normalise time before calling this function, so the
* values that arrive here are already stable.
*/
let _lastDispatchedTime = -1;
type SeekCompletionResult = { status: "fulfilled" } | { status: "rejected"; reason: unknown };
let _pendingCompletions = new Set<Promise<SeekCompletionResult>>();
let _videoFrameCompletions = new WeakSet<Promise<SeekCompletionResult>>();
let _pendingFailure: { reason: unknown } | undefined;
let _activeCompletionBarriers = 0;
export interface HfSeekEventDetail {
time: number;
waitUntil: (promise: PromiseLike<unknown>) => void;
}
function dispatch(time: number): void {
const pending: PromiseLike<unknown>[] = [];
let accepting = true;
const detail: HfSeekEventDetail = {
time,
waitUntil: (promise) => {
if (!accepting) {
throw new Error("hf-seek waitUntil() must be called synchronously from the event listener");
}
pending.push(promise);
},
};
try {
window.dispatchEvent(new CustomEvent<HfSeekEventDetail>("hf-seek", { detail }));
} catch (err) {
swallow("runtime.adapters.seek-dispatch.site1", err);
} finally {
accepting = false;
}
if (pending.length === 0) return;
registerSeekCompletion(Promise.all(pending));
}
/**
* Join `promise` to the seek-completion barrier: `waitForSeekCompletion` will
* not resolve until it settles, and its rejection (the first one) becomes the
* barrier's.
*
* Exported because the `"hf-seek"` event's synchronous `waitUntil()` is not
* the only asynchronous seek work a frame can owe. `runtime/vfx.ts` registers
* its preview-side capture here, so the CLI seek paths that already await this
* barrier wait for a `self` chain's paint instead of racing it.
*/
export function registerSeekCompletion(promise: Promise<unknown>, kind?: "video-frame"): void {
const completion = promise
.then<SeekCompletionResult>(() => ({ status: "fulfilled" }))
.catch<SeekCompletionResult>((reason: unknown) => ({ status: "rejected", reason }));
_pendingCompletions.add(completion);
if (kind === "video-frame") _videoFrameCompletions.add(completion);
void completion.then((result) => {
if (!_pendingCompletions.delete(completion)) return;
if (result.status === "rejected" && _pendingFailure === undefined) {
_pendingFailure = { reason: result.reason };
}
});
}
export function dispatchSeekEvent(time: number): void {
if (time === _lastDispatchedTime) return;
_lastDispatchedTime = time;
dispatch(time);
}
/**
* Force-dispatch a `"hf-seek"` event even if `time` equals the last dispatched
* time, bypassing the dedup guard.
*
* Needed for the post-video-injection GPU re-render: the engine seeks to time
* T (GPU adapters render once, before video frames are injected), then injects
* the decoded `__render_frame__` images, then must re-render GPU compositions
* at the *same* T so they re-upload textures from the now-present frames. The
* normal dedup would swallow that second dispatch.
*/
export function forceDispatchSeekEvent(time: number): void {
_lastDispatchedTime = time;
dispatch(time);
}
export function isSeekCompletionBarrierActive(): boolean {
return _activeCompletionBarriers > 0;
}
/** Settles with every pending completion, without consuming a failure the barrier reports. */
export async function seekCompletionsSettled(): Promise<void> {
for (
let pending = [..._pendingCompletions];
pending.length > 0;
pending = [..._pendingCompletions]
) {
await Promise.all(pending);
}
}
export function hasPendingSeekCompletion(): boolean {
return _pendingCompletions.size > 0;
}
/** `videoFrames: false` skips only the video-frame holds: a geometry read needs every other completion. */
export async function waitForSeekCompletion(options?: { videoFrames?: boolean }): Promise<void> {
const awaited = () =>
[..._pendingCompletions].filter(
(completion) => options?.videoFrames !== false || !_videoFrameCompletions.has(completion),
);
_activeCompletionBarriers += 1;
let failed = _pendingFailure;
try {
// Let concurrently started barriers snapshot the same retained failure
// before either one consumes it.
await Promise.resolve();
for (let pending = awaited(); pending.length > 0; pending = awaited()) {
const results = await Promise.all(pending);
const rejected = results.find((result) => result.status === "rejected");
if (failed === undefined && rejected?.status === "rejected") {
failed = { reason: rejected.reason };
}
}
const retainedFailure = _pendingFailure;
if (failed === undefined) {
failed = retainedFailure;
}
if (_pendingFailure === retainedFailure) {
_pendingFailure = undefined;
}
if (failed) throw failed.reason;
} finally {
_activeCompletionBarriers -= 1;
}
}
/** Reset internal state — used in tests to prevent cross-test contamination. */
export function resetSeekDispatchState(): void {
_lastDispatchedTime = -1;
_pendingCompletions = new Set();
_videoFrameCompletions = new WeakSet();
_pendingFailure = undefined;
_activeCompletionBarriers = 0;
}