Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* VFX chain runtime — paints every `data-vfx-chain` host's WebGL2 canvas from
* `(t, params)` after each seek.
*
* One registry entry per host element. Shaders are compiled once at init; a
* paint binds uniforms and draws one full-screen triangle per enabled node,
* ping-ponging through two framebuffers when a chain has more than one node so
* the last pass always lands on the visible `.hf-vfx-out` canvas.
*
* A paint may read only `(u_size, u_t, u_fps, params, u_src)` — no clock, no
* randomness, no state carried between paints. That is the determinism
* contract the exporter's gate depends on.
*
* Every failure is loud: the engine records the `[HyperFrames] composition script error:`
* prefix as a composition script error, which fails a render whose timeline wait times out.
*/
import {
HF_VFX_ATTR,
VfxChainError,
chainCapture,
enabledVfxNodes,
getVfxDef,
normalizeVfxParams,
parseVfxChain,
type HfVfxCapture,
type HfVfxChain,
type HfVfxDef,
type HfVfxNode,
type HfVfxParam,
type HfVfxParamValues,
type HfVfxRefParam,
} from "../vfx";
import { htmlInCanvasForm, markCaptureCanvas, markCaptured } from "../htmlInCanvas";
import { registerSeekCompletion } from "./adapters/seek-dispatch";
import { isCanvasElement, isHtmlElement } from "./domRealm";
/**
* Marks a `ref` wrapper whose element ALSO paints on its own — v1.1 assumed a
* matte source is invisible in After Effects and that is not always true
* (retro-wave `Logo Anim` layer 5 is layer 4's displacement map AND an enabled,
* fully opaque layer). Without it the runtime would clear the wrapper's bitmap
* after reading it and the layer would vanish from the page.
*/
const VFX_REF_VISIBLE_ATTR = "data-vfx-ref-visible";
/** The prefix `frameCapture.ts` records as a composition script error. */
const VFX_ERROR_LABEL = "[HyperFrames] composition script error:";
/**
* `preserveDrawingBuffer` is what the engine's accelerated-canvas composite
* needs to `drawImage` this canvas later (Phase 5); it costs nothing now.
*/
const GL_ATTRS: WebGLContextAttributes = {
preserveDrawingBuffer: true,
antialias: false,
premultipliedAlpha: true,
alpha: true,
};
/**
* A full-screen triangle from `gl_VertexID` alone — no buffers, no attributes,
* so nothing about the geometry can differ between backends. `v_uv` is 0..1
* across the viewport with y UP, matching texture space rather than canvas
* space.
*/
const VERTEX_SHADER = `#version 300 es
out vec2 v_uv;
void main() {
vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
v_uv = p;
gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
}
`;
/** The html-in-canvas 2-D context, behind the Chrome flag. */
interface DrawElementCtx extends CanvasRenderingContext2D {
drawElementImage: (el: Element, x: number, y: number, w: number, h: number) => void;
}
/** Chrome's paint-record invalidation hook on a `layoutsubtree` canvas. */
interface RequestPaintCanvas extends HTMLCanvasElement {
requestPaint?: () => void;
}
interface CompositeWindow extends Window {
__hf_page_composite_pending?: boolean;
__hf_page_composite_resolve?: () => boolean;
}
/**
* One captured texture: the `<canvas layoutsubtree class="hf-vfx-src">` wrapper
* the exporter emitted, its single `.hf-vfx-in` child, and the GL texture the
* capture is uploaded into.
*
* The same shape serves all three sources a chain can read — the host's own
* pixels (`self`), everything below the host (`backdrop`), and a second element
* named by a `ref` param (`u_src2`) — because at capture time they differ only
* in WHICH element supplies the pixels.
*/
interface VfxCaptureSource {
canvas: HTMLCanvasElement;
inner: HTMLElement;
ctx: DrawElementCtx;
texture: WebGLTexture;
/**
* The wrapper was found through `data-vfx-for`, i.e. it wraps the layers
* BELOW the host rather than the host's own content. Such a wrapper lives
* outside the host, which is what makes a hidden host a pass-through rather
* than a hole (see `capturePassThrough`).
*/
backdrop: boolean;
/**
* The wrapper carries `data-vfx-ref-visible`: its bitmap is a layer the page
* shows, not only a texture, so the capture keeps it and draws it at the
* REF's own box rather than the host's.
*/
visible: boolean;
/** `.hf-vfx-in` measured 0×0 and that has already been reported once. */
emptyBoxReported: boolean;
/** `.hf-vfx-in` measured 0×0 at registration or the last seek, captured or not. */
laidOutEmpty: boolean;
}
/**
* Every uniform location one pass can bind, resolved once. `getUniformLocation`
* is a synchronous driver query, and the paint loop used to make one per
* uniform per param per pass per frame; the program is linked once at init, so
* the answers never change.
*
* `null` is the correct cached value for a uniform the linker optimised out —
* `gl.uniform*(null, …)` is a defined no-op, which is what the old per-frame
* query did with it too.
*/
interface PassLocations {
size: WebGLUniformLocation | null;
t: WebGLUniformLocation | null;
fps: WebGLUniformLocation | null;
src: WebGLUniformLocation | null;
/** Bound only for a def with a `ref` param (v1.1's second source). */
src2: WebGLUniformLocation | null;
/** 1 when this pass's optional ref actually resolved, 0 when it did not. */
hasSrc2: WebGLUniformLocation | null;
/** Keyed by the def's param key, without the `u_` prefix. */
params: Record<string, WebGLUniformLocation | null>;
}
interface VfxPass {
node: HfVfxNode;
def: HfVfxDef;
program: WebGLProgram;
/** Chain params after clamp/defaults; CSS vars override per paint. */
params: HfVfxParamValues;
locations: PassLocations;
/** `u_src2`: the element this node's `ref` param named. Per NODE, not per
* entry — two nodes in one chain may matte against different elements. */
ref?: VfxCaptureSource;
/**
* The `ref` param names this pass's OWN host — the self-referential stencil
* shape (`target === host` in `resolveRefSource`). There is no second
* texture to capture, so `bindPass` points `u_src2` at unit 0 explicitly
* instead of leaving it unbound.
*/
selfRef?: boolean;
}
/** Two colour targets a multi-node chain alternates between. */
interface PingPong {
textures: [WebGLTexture, WebGLTexture];
framebuffers: [WebGLFramebuffer, WebGLFramebuffer];
width: number;
height: number;
}
export interface VfxEntry {
host: HTMLElement;
chain: HfVfxChain;
/**
* What this host RESOLVED to, not what its defs declare: `backdrop` when the
* wrapper was found through `data-vfx-for`, else the chain's own requirement.
* The two are the same kernel reading the same `u_src` — `self` and
* `backdrop` differ only in which element the exporter put inside the
* wrapper — so the DOM is the only place the distinction exists.
*/
capture: HfVfxCapture;
out: HTMLCanvasElement;
gl: WebGL2RenderingContext;
passes: VfxPass[];
/** Present exactly when `capture !== "none"`. */
src?: VfxCaptureSource;
ping?: PingPong;
/** Set once `out` fires `webglcontextlost`; the entry never paints again. */
contextLost: boolean;
}
export type VfxRegistry = VfxEntry[];
let registry: VfxRegistry = [];
let registryFps = 30;
/** The time the last `paintVfx` was given; a capturing chain paints later. */
let lastPaintTime = 0;
/**
* Monotonic seek token. Every `paintVfx` claims one; an async capture that
* comes back to find a newer token has been superseded and must not repaint.
*/
let paintSeq = 0;
/** The token the page-composite resolver last completed, so a race can yield. */
let resolvedSeq = -1;
/** The resolver we installed, and whoever owned the slot when we wrapped it. */
let vfxResolver: (() => boolean) | null = null;
let priorResolver: (() => boolean) | null = null;
function reportVfxError(message: string): void {
// eslint-disable-next-line no-console
console.error(VFX_ERROR_LABEL, `vfx: ${message}`);
}
/** One frame's capture failed; later frames may still paint, so the engine does not stop the render on it. */
function reportVfxFrameError(message: string): void {
// eslint-disable-next-line no-console
console.error(VFX_ERROR_LABEL, `vfx-frame: ${message}`);
}
function compileShader(
gl: WebGL2RenderingContext,
type: number,
source: string,
): WebGLShader | null {
const shader = gl.createShader(type);
if (!shader) return null;
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (gl.getShaderParameter(shader, gl.COMPILE_STATUS)) return shader;
reportVfxError(`shader failed to compile: ${gl.getShaderInfoLog(shader) ?? "(no log)"}`);
gl.deleteShader(shader);
return null;
}
// The attach/link/delete sequence is the same six WebGL calls colorGrading.ts
// makes; the two differ in their failure reporting (loud here, `swallow` there)
// and in who owns the vertex shader, so sharing one helper would couple the
// vfx runtime's error contract to the colour pipeline's.
// fallow-ignore-next-line code-duplication
function linkVfxProgram(gl: WebGL2RenderingContext, frag: string): WebGLProgram | null {
const vertex = compileShader(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
const fragment = vertex ? compileShader(gl, gl.FRAGMENT_SHADER, frag) : null;
if (!vertex || !fragment) return null;
// fallow-ignore-next-line code-duplication
const program = gl.createProgram();
if (!program) return null;
gl.attachShader(program, vertex);
gl.attachShader(program, fragment);
gl.linkProgram(program);
gl.deleteShader(vertex);
gl.deleteShader(fragment);
if (gl.getProgramParameter(program, gl.LINK_STATUS)) return program;
reportVfxError(`program failed to link: ${gl.getProgramInfoLog(program) ?? "(no log)"}`);
gl.deleteProgram(program);
return null;
}
/**
* The box the interface spec fixes for `.hf-vfx-out` ("it is `position:absolute;
* inset:0` and sized to the host's box"). It belongs to the ELEMENT, not to
* whoever created it, so an exporter-emitted canvas gets it too.
*/
const OUT_BOX = "position:absolute;inset:0;width:100%;height:100%;pointer-events:none;";
/** The output canvas the exporter may already have emitted, else a new one. */
function findOrCreateOut(host: HTMLElement): HTMLCanvasElement {
const existing = host.querySelector("canvas.hf-vfx-out");
if (isCanvasElement(existing)) {
// The exporter emits the canvas bare — `<canvas class="hf-vfx-out"></canvas>`
// — "for layout stability". Adopted untouched it keeps the default
// `position:static; display:inline`, so it is an inline box that wraps to
// the line AFTER the (layer-wide) `.hf-vfx-src` canvas and paints one full
// layer height below the host. Measured on retro-wave `#main-l6-text`:
// `.hf-vfx-src` rect top 315.1 h 93.0, `.hf-vfx-out` rect top 409.2 — a
// clean, unwarped second copy of the layer below where it belongs, with no
// error anywhere (ae-mcp findings §Task 3.5b). Prepending rather than
// assigning leaves any style the exporter DID write in the winning position.
existing.style.cssText = OUT_BOX + existing.style.cssText;
return existing;
}
const out = document.createElement("canvas");
out.className = "hf-vfx-out";
out.style.cssText = OUT_BOX;
host.appendChild(out);
return out;
}
function resolveUniformLocations(
gl: WebGL2RenderingContext,
program: WebGLProgram,
def: HfVfxDef,
): PassLocations {
const params: Record<string, WebGLUniformLocation | null> = {};
for (const param of def.params) {
// `ref` params carry element ids, not numbers, and have no uniform.
if (param.kind === "ref") continue;
params[param.key] = gl.getUniformLocation(program, `u_${param.key}`);
}
return {
size: gl.getUniformLocation(program, "u_size"),
t: gl.getUniformLocation(program, "u_t"),
fps: gl.getUniformLocation(program, "u_fps"),
src: gl.getUniformLocation(program, "u_src"),
src2: gl.getUniformLocation(program, "u_src2"),
hasSrc2: gl.getUniformLocation(program, "u_hasSrc2"),
params,
};
}
/**
* What a pass's `ref` param resolved to. A plain union return (rather than
* overloading `undefined`/`null`) is what lets `buildPasses` tell "no ref
* param on this def" apart from "ref param present, but self-referential" —
* `VfxPass.selfRef` needs that distinction to bind `u_src2` explicitly instead
* of relying on an unbound sampler's implicit unit-0 default.
*/
type RefResolution =
| { kind: "none" }
| { kind: "self" }
| { kind: "error" }
| { kind: "source"; source: VfxCaptureSource };
/**
* The element a `ref` param names, wrapped in its own capture canvas.
*
* The exporter wraps a matte/map source the same way it wraps a `self` layer
* (the interface spec's v1.1: "the exporter wraps the referenced element in its
* own `.hf-vfx-src` canvas") — which is also why nothing is injected here. A
* runtime-created `<canvas layoutsubtree>` would be invisible to
* `detectRenderModeHints`, and the `htmlInCanvas` single-worker pin it derives
* from the SOURCE markup is what keeps concurrent `drawElementImage` off.
*/
/**
* A `ref` param with no id supplied. An optional ref left empty is the def's
* own fallback (displacement-map reads `u_src` as its map), not a broken
* chain; a mandatory one with nothing named is an authoring error.
*/
function resolveEmptyRefParam(
host: HTMLElement,
node: HfVfxNode,
def: HfVfxDef,
param: HfVfxRefParam,
): RefResolution {
if (param.optional) return { kind: "none" };
reportVfxError(
`${describeHost(host)}: node "${node.id}" (${def.id}) needs a "${param.key}" ` +
`param naming the id of the element to read as its second source.`,
);
return { kind: "error" };
}
function resolveRefSource(
host: HTMLElement,
node: HfVfxNode,
def: HfVfxDef,
params: HfVfxParamValues,
gl: WebGL2RenderingContext,
cache: Map<HTMLElement, VfxCaptureSource>,
): RefResolution {
const param = def.params.find((p): p is HfVfxRefParam => p.kind === "ref");
if (!param) return { kind: "none" };
const id = params[param.key];
if (typeof id !== "string" || id === "") return resolveEmptyRefParam(host, node, def, param);
const target = host.ownerDocument.getElementById(id);
if (!isHtmlElement(target)) {
reportVfxError(
`${describeHost(host)}: node "${node.id}" (${def.id}) names "${param.key}" element ` +
`#${id}, which is not in the composition.`,
);
return { kind: "error" };
}
// A ref naming its own host is the self-referential form — `u_src` already
// holds those pixels. Capturing it again would cost a second
// `drawElementImage` per frame for the same image, and on a `backdrop` host
// it would resolve the `data-vfx-for` sibling and read the layers BELOW as
// the map.
//
// An OPTIONAL ref (displacement-map's `map`) already has a shader-side
// branch keyed off `u_hasSrc2` for "nothing named" — self-reference means
// exactly the same thing to it as leaving the param empty, so it is folded
// into `"none"` rather than given its own kind: `u_hasSrc2` stays 0 and the
// shader's own fallback reads `u_src`, unchanged from before this type.
// A MANDATORY ref (luma-matte's `matte`) has no such branch — its shader
// always samples `u_src2` — so a real `"self"` kind is the only way `u_src2`
// gets bound at all; `bindPass` points it at `u_src`'s own texture unit.
if (target === host) return param.optional ? { kind: "none" } : { kind: "self" };
const cached = cache.get(target);
if (cached) return { kind: "source", source: cached };
const source = resolveCaptureSource(target, gl, `${describeHost(host)}: "${param.key}" source`);
if (!source) return { kind: "error" };
source.visible = source.canvas.hasAttribute(VFX_REF_VISIBLE_ATTR);
cache.set(target, source);
return { kind: "source", source };
}
function buildPasses(
gl: WebGL2RenderingContext,
chain: HfVfxChain,
host: HTMLElement,
): VfxPass[] | null {
const passes: VfxPass[] = [];
// One source per referenced ELEMENT: two nodes matting against the same
// matte capture it once and share the texture.
const refs = new Map<HTMLElement, VfxCaptureSource>();
for (const node of enabledVfxNodes(chain)) {
const def = getVfxDef(node.type);
if (!def) {
reportVfxError(`node "${node.id}" has unknown effect type "${node.type}"`);
return null;
}
const program = linkVfxProgram(gl, def.frag);
if (!program) {
reportVfxError(`node "${node.id}" (${def.id}) has no usable program`);
return null;
}
const params = normalizeVfxParams(def.id, node.params);
const resolved = resolveRefSource(host, node, def, params, gl, refs);
if (resolved.kind === "error") return null;
passes.push({
node,
def,
program,
params,
locations: resolveUniformLocations(gl, program, def),
...(resolved.kind === "source" ? { ref: resolved.source } : {}),
selfRef: resolved.kind === "self",
});
}
return passes;
}
function createCaptureTexture(gl: WebGL2RenderingContext): WebGLTexture {
const texture = gl.createTexture()!;
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
return texture;
}
/**
* The `backdrop` wrapper for `owner`: a `<canvas layoutsubtree class="hf-vfx-src"
* data-vfx-for="<owner id>">` among the owner's SIBLINGS, holding every layer
* below it (interface v1.1).
*
* Scoped to the parent rather than the document because that is where the
* exporter puts it — z-order is DOM order, so the wrapper is the host's own
* preceding sibling at whatever depth the host sits, stacked adjustment layers
* included. Read attribute-by-attribute instead of through a selector: an id
* goes into this comparison unescaped, and a `querySelector` built by
* concatenation would throw on an id a selector cannot spell.
*/
function findBackdropWrapper(owner: HTMLElement): HTMLCanvasElement | null {
const parent = owner.parentElement;
if (!parent || owner.id === "") return null;
const siblings = parent.children;
for (let i = 0; i < siblings.length; i++) {
const sibling = siblings.item(i);
if (!isCanvasElement(sibling)) continue;
if (!sibling.classList.contains("hf-vfx-src")) continue;
if (sibling.getAttribute("data-vfx-for") === owner.id) return sibling;
}
return null;
}
/** The exporter writes `layoutsubtree`; a browser that dropped it needs `content="drawable"` and `drawable` instead. */
function adoptCaptureForm(canvas: HTMLCanvasElement, inner: HTMLElement): void {
if (htmlInCanvasForm() !== "drawable") return;
markCaptureCanvas(canvas, "drawable");
markCaptured(inner, "drawable");
}
/**
* The `<canvas layoutsubtree class="hf-vfx-src">` that supplies `owner`'s
* pixels, plus its 2-D context. Never injected at runtime: the compiler derives
* the `htmlInCanvas` render-mode hint from this canvas being in the source, and
* that pin exists for a measured reason.
*
* Resolution order, per plan Task 2.6: a `data-vfx-for` sibling (the
* `backdrop` shape — the layers below) before the owner's own child (the
* `self` shape — its own content). A def's `capture` says only THAT the kernel
* needs a texture; which element fills it is the exporter's placement, and this
* is where the runtime reads that placement off the DOM.
*
* `.hf-vfx-in` must be the canvas's IMMEDIATE child: Chrome refuses anything
* else with "Only immediate children of the <canvas> element can be passed to
* DrawElementImage", so a deeper wrapper is a registration-time error here
* rather than a throw on every frame.
*/
function resolveCaptureSource(
owner: HTMLElement,
gl: WebGL2RenderingContext,
label: string,
): VfxCaptureSource | undefined {
const backdrop = findBackdropWrapper(owner);
const canvas = backdrop ?? owner.querySelector("canvas.hf-vfx-src");
const inner = isCanvasElement(canvas) ? canvas.querySelector(":scope > .hf-vfx-in") : null;
if (!isCanvasElement(canvas) || !isHtmlElement(inner)) {
reportVfxError(
`${label}: a capturing chain needs ` +
`<canvas layoutsubtree class="hf-vfx-src"><div class="hf-vfx-in">…</div></canvas> in ` +
`source: inside the element for its own pixels, or beside it with ` +
`data-vfx-for="${owner.id}" for the layers below it.`,
);
return undefined;
}
const ctx = canvas.getContext("2d") as DrawElementCtx | null;
if (!ctx || typeof ctx.drawElementImage !== "function") {
reportVfxError(
`${label}: drawElementImage is unavailable, so the layer cannot be ` +
`captured. In Studio, enable chrome://flags/#canvas-draw-element.`,
);
return undefined;
}
adoptCaptureForm(canvas, inner);
return {
canvas,
inner,
ctx,
texture: createCaptureTexture(gl),
backdrop: backdrop !== null,
// Only a `ref` source may be visible; `resolveRefSource` sets it.
visible: false,
emptyBoxReported: false,
laidOutEmpty: deviceSize(inner) === null,
};
}
/**
* Chrome caps live WebGL contexts (commonly 16, and `colorGrading.ts` holds
* one per graded element too), and a driver reset can take one at any moment.
* Calls on a lost context are spec'd to do nothing, so without this the chain
* would go on "painting" an empty canvas in silence — the one thing this
* module promises not to do.
*
* Only the OUTPUT canvas is watched: `.hf-vfx-src` is a 2-D context and is
* unaffected by GL context loss.
*
* Restore is deliberately unhandled — the entry stays lost for as long as this
* registry does. `initVfx` already re-scans and re-registers every host when
* the composition mounts and again when a sub-composition arrives, rebuilding
* every program, texture and framebuffer from scratch; a second, narrower
* rebuild path for `webglcontextrestored` alone would duplicate that one and
* be free to drift from it. `preventDefault()` still runs, so the context is
* restorable if a follow-up wants to take it.
*/
function watchContextLoss(entry: VfxEntry): void {
entry.out.addEventListener("webglcontextlost", (event) => {
event.preventDefault();
// A later `initVfx` may have replaced the registry, and `findOrCreateOut`
// hands the same canvas to the new entry — a released entry's loss is
// nobody's frame, and reporting it would be a phantom error.
if (!registry.includes(entry) || entry.contextLost) return;
entry.contextLost = true;
reportVfxError(`${describeHost(entry.host)}: WebGL context lost.`);
});
}
/** The host's chain, or `null` once the reason it is unusable has been said. */
function readVfxChain(host: HTMLElement): HfVfxChain | null {
try {
return parseVfxChain(host.getAttribute(HF_VFX_ATTR) ?? "");
} catch (err) {
const detail = err instanceof VfxChainError ? err.message : String(err);
reportVfxError(`${describeHost(host)}: ${detail}`);
return null;
}
}
function registerVfxHost(host: HTMLElement): VfxEntry | null {
const chain = readVfxChain(host);
if (!chain) return null;
const out = findOrCreateOut(host);
const gl = out.getContext("webgl2", GL_ATTRS);
if (!gl) {
reportVfxError(`${describeHost(host)}: WebGL2 is unavailable, so the chain cannot paint.`);
out.remove();
return null;
}
const passes = buildPasses(gl, chain, host);
if (!passes) {
out.remove();
return null;
}
const declared = chainCapture(chain);
const src = declared === "none" ? undefined : resolveCaptureSource(host, gl, describeHost(host));
if (declared !== "none" && !src) {
out.remove();
return null;
}
const capture = src?.backdrop ? "backdrop" : declared;
const entry: VfxEntry = { host, chain, capture, out, gl, passes, src, contextLost: false };
watchContextLoss(entry);
return entry;
}
/**
* Whether an element is on screen, and so whether it has a paint record at
* all: `drawElementImage` throws on a hidden subtree, and the clip runtime
* hides everything outside its `data-start`/`data-duration` window, which
* would otherwise fail the render on each of those frames.
*
* Asked of hosts (does this chain paint?) and of capture sources (is there
* anything to read?) alike.
*/
function isPaintableHost(host: HTMLElement): boolean {
const style = getComputedStyle(host);
return style.display !== "none" && style.visibility !== "hidden";
}
/**
* Whether a source's `.hf-vfx-in` has a paint record to capture. `visibility`
* inherits, so one read at `inner` covers a matte hidden that way; `display`
* does NOT, so a ref whose OWNING element is `display:none` (the clip
* runtime's `data-hidden` and in-flow timed-leaf paths) still computes
* `display:block` at `inner` — and would wait out the paint ceiling, then fail
* as a misleading 0×0. Hence the ancestor walk. `checkVisibility()` and
* `offsetParent` would say the same in Chrome but are absent or always-null
* in the unit harness's DOM.
*/
function isPaintableSource(src: VfxCaptureSource): boolean {
if (getComputedStyle(src.inner).visibility === "hidden") return false;
for (let el: HTMLElement | null = src.inner; el; el = el.parentElement) {
if (getComputedStyle(el).display === "none") return false;
}
return true;
}
function describeHost(host: HTMLElement): string {
return host.id ? `#${host.id}` : `<${host.tagName.toLowerCase()}>`;
}
/**
* Every texture this entry captures per frame, in binding order: `u_src`
* first, then each node's `u_src2`. A ref shared by two nodes appears once —
* `buildPasses` hands both passes the same source object.
*/
function entrySources(entry: VfxEntry): VfxCaptureSource[] {
const sources: VfxCaptureSource[] = entry.src ? [entry.src] : [];
for (const pass of entry.passes) {
if (pass.ref && !sources.includes(pass.ref)) sources.push(pass.ref);
}
return sources;
}
/**
* A chain whose source is the layers BELOW the host. Its wrapper is outside the
* host, so the host's own visibility does not decide whether those layers are
* on screen — `capturePassThrough` does.
*/
function isBackdropEntry(entry: VfxEntry): boolean {
return entry.src?.backdrop === true;
}
/**
* Every distinct VISIBLE ref this entry's passes read — element(s) that paint
* on the page independently of whether this entry's own kernel currently
* runs, exactly like `entrySources` but restricted to the sources whose
* bitmap is itself the frame (`VFX_REF_VISIBLE_ATTR`). A ref shared by two
* passes appears once, same rule as `entrySources`.
*/
function visibleRefSources(entry: VfxEntry): VfxCaptureSource[] {
const sources: VfxCaptureSource[] = [];
for (const pass of entry.passes) {
if (pass.ref?.visible && !sources.includes(pass.ref)) sources.push(pass.ref);
}
return sources;
}
/** Drop the GL objects the outgoing registry owns before replacing it. */
function releaseRegistry(): void {
for (const entry of registry) {
const { gl } = entry;
for (const pass of entry.passes) gl.deleteProgram(pass.program);
for (const source of entrySources(entry)) gl.deleteTexture(source.texture);
if (!entry.ping) continue;
for (const texture of entry.ping.textures) gl.deleteTexture(texture);
for (const framebuffer of entry.ping.framebuffers) gl.deleteFramebuffer(framebuffer);
}
}
/**
* Discover every chain host under `root`, compile its programs, and replace
* the module registry. Called where the runtime finishes mounting the
* composition and AGAIN once sub-compositions have loaded — a host inside a
* `data-composition-src` mount is not in the DOM for the first pass, and an
* unregistered host paints nothing and reports nothing. Re-initialising
* forgets (and releases) the previous pass's hosts.
*/
export function initVfx(root: HTMLElement, fps: number): VfxRegistry {
releaseRegistry();
registry = [];
registryFps = Number.isFinite(fps) && fps > 0 ? fps : 30;
const hosts = root.querySelectorAll(`[${HF_VFX_ATTR}]`);
for (const host of hosts) {
if (!isHtmlElement(host)) continue;
const entry = registerVfxHost(host);
if (entry) registry.push(entry);
}
return registry;
}
/**
* Device-pixel size of the host's box; `null` when it has no area to paint.
*
* `offsetWidth`/`offsetHeight`, not `getBoundingClientRect()`: the latter is
* the element's transformed axis-aligned bounding box, so a host carrying a
* GSAP scale or rotation would get an inflated output canvas and a stretched
* capture. An After Effects effect operates on the layer's own untransformed
* box, which is what the layout size gives.
*/
function deviceSize(host: HTMLElement): { width: number; height: number } | null {
const dpr = typeof window === "undefined" ? 1 : window.devicePixelRatio || 1;
const width = Math.round(host.offsetWidth * dpr);
const height = Math.round(host.offsetHeight * dpr);
return width > 0 && height > 0 ? { width, height } : null;
}
function makePingTarget(
gl: WebGL2RenderingContext,
width: number,
height: number,
): [WebGLTexture, WebGLFramebuffer] {
const texture = gl.createTexture()!;
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
const framebuffer = gl.createFramebuffer()!;
gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
return [texture, framebuffer];
}
function ensurePingPong(entry: VfxEntry, width: number, height: number): PingPong {
const existing = entry.ping;
if (existing && existing.width === width && existing.height === height) return existing;
const { gl } = entry;
if (existing) {
for (const t of existing.textures) gl.deleteTexture(t);
for (const f of existing.framebuffers) gl.deleteFramebuffer(f);
}
const a = makePingTarget(gl, width, height);
const b = makePingTarget(gl, width, height);
const ping: PingPong = {
textures: [a[0], b[0]],
framebuffers: [a[1], b[1]],
width,
height,
};
entry.ping = ping;
return ping;
}
/**
* A number for `u_<key>`: the `--vfx-<nodeId>-<key>` CSS var when the def says
* the param is animatable and the var resolves, else the chain's clamped value.
* Booleans become 0/1; `ref` params carry element ids and have no uniform.
*/
function paramUniformValue(
param: HfVfxParam,
pass: VfxPass,
style: CSSStyleDeclaration,
): number | null {
if (param.kind === "ref") return null;
if (param.kind === "number" && param.animatable) {
const raw = style.getPropertyValue(`--vfx-${pass.node.id}-${param.key}`).trim();
const n = raw === "" ? Number.NaN : Number.parseFloat(raw);
if (Number.isFinite(n)) return Math.min(param.max, Math.max(param.min, n));
}
const value = pass.params[param.key];
if (typeof value === "boolean") return value ? 1 : 0;
return typeof value === "number" ? value : 0;
}
function setPassUniforms(
entry: VfxEntry,
pass: VfxPass,
style: CSSStyleDeclaration,
t: number,
width: number,
height: number,
): void {
const { gl } = entry;
const { locations } = pass;
gl.uniform2f(locations.size, width, height);
gl.uniform1f(locations.t, t);
gl.uniform1f(locations.fps, registryFps);
// A def whose ref is optional needs to know which sampler holds its second
// input; on a shader without the uniform the location is null and this is a
// defined no-op. A self-referential ref counts as resolved too — `u_src2`
// reads real data, just from unit 0 rather than a second capture.
gl.uniform1f(locations.hasSrc2, pass.ref || pass.selfRef ? 1 : 0);
for (const param of pass.def.params) {
const value = paramUniformValue(param, pass, style);
if (value === null) continue;
gl.uniform1f(locations.params[param.key] ?? null, value);
}
}
/** Where this pass draws: the visible canvas for the last one, else the
* ping-pong target the next pass will read. */
function passTarget(index: number, last: number, ping: PingPong | null): WebGLFramebuffer | null {
if (index === last || !ping) return null;
return ping.framebuffers[index % 2] ?? null;
}
/** What this pass reads as `u_src`: the capture for the first pass, the
* previous pass's target after that. */
function passInput(entry: VfxEntry, index: number, ping: PingPong | null): WebGLTexture | null {
if (index === 0) return entry.src?.texture ?? null;
return ping?.textures[(index - 1) % 2] ?? null;
}
/** Bind this pass's render target and its input textures. */
function bindPass(entry: VfxEntry, index: number, last: number, ping: PingPong | null): void {
const { gl } = entry;
const pass = entry.passes[index]!;
gl.bindFramebuffer(gl.FRAMEBUFFER, passTarget(index, last, ping));
const source = passInput(entry, index, ping);
if (source) bindSampler(gl, pass.locations.src, source, 0);
// Unit 1 for `u_src2`, then back to unit 0 so every other bind in this
// module — the next pass's, and `uploadCaptureTexture`'s — starts from the
// same active unit no matter which passes carry a ref.
if (pass.ref) {
bindSampler(gl, pass.locations.src2, pass.ref.texture, 1);
gl.activeTexture(gl.TEXTURE0);
} else if (pass.selfRef && source) {
// A `ref` param naming its own host: `u_src2` reads exactly what `u_src`
// just bound. Previously left unbound, which happened to read unit 0 by
// GLSL's default sampler binding — correct today, but implicit rather than
// stated.
gl.uniform1i(pass.locations.src2, 0);
}
}
function bindSampler(
gl: WebGL2RenderingContext,
location: WebGLUniformLocation | null,
texture: WebGLTexture,
unit: 0 | 1,
): void {
gl.activeTexture(unit === 0 ? gl.TEXTURE0 : gl.TEXTURE1);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.uniform1i(location, unit);
}
function paintEntry(entry: VfxEntry, t: number): void {
const size = deviceSize(entry.host);
if (!size) return;
const { gl, out, passes } = entry;
if (out.width !== size.width) out.width = size.width;
if (out.height !== size.height) out.height = size.height;
const ping = passes.length > 1 ? ensurePingPong(entry, size.width, size.height) : null;
const style = getComputedStyle(entry.host);
const last = passes.length - 1;
for (let i = 0; i <= last; i++) {
const pass = passes[i]!;
// useProgram FIRST: bindPass sets the `u_src` sampler, and uniforms land on
// whichever program is current at the time of the call.
gl.useProgram(pass.program);
bindPass(entry, i, last, ping);
gl.viewport(0, 0, size.width, size.height);
setPassUniforms(entry, pass, style, t, size.width, size.height);
gl.drawArrays(gl.TRIANGLES, 0, 3);
}
}
function uploadCaptureTexture(gl: WebGL2RenderingContext, src: VfxCaptureSource): void {
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, src.texture);
// The full-screen triangle's `v_uv` is y-up and a canvas is y-down; the
// kernels write premultiplied colour, so the source must arrive that way too.
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 1);
gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, 1);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, src.canvas);
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0);
gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, 0);
}
/**
* What a capture does with what it drew. Three combinations exist, and each
* one is a different kind of source:
*
* - texture only — an invisible source read as `u_src`/`u_src2`. The bitmap is
* cleared after the upload because a `layoutsubtree` canvas's BITMAP is
* painted by the page compositor even though its children are not, and
* leaving the raw capture there would show through `.hf-vfx-out`.
* - bitmap only — a `backdrop` wrapper whose host is not painting this frame
* (the bitmap IS the frame: it carries the layers below an adjustment layer
* that is currently off), or a VISIBLE ref whose owning host is not
* painting (the ref's own layer still has to show; no kernel will read the
* texture this frame, so there is nothing to upload).
* - both — a `ref` source the exporter marked visible, captured while its
* owning host IS painting. Its layer paints on its own AND feeds a kernel,
* so the capture is uploaded and left on screen.
*/
interface CaptureMode {
upload: boolean;
keepBitmap: boolean;
}
const CAPTURE_TO_TEXTURE: CaptureMode = { upload: true, keepBitmap: false };
const CAPTURE_PASS_THROUGH: CaptureMode = { upload: false, keepBitmap: true };
const CAPTURE_VISIBLE_SOURCE: CaptureMode = { upload: true, keepBitmap: true };
/**
* A visible ref captured while its owning entry's host is NOT painting: the
* ref's own layer still has to stay current on screen, but no kernel will run
* to read the texture this frame (`paintEntry` never fires), so the upload is
* skipped.
*/
const CAPTURE_VISIBLE_ONLY: CaptureMode = { upload: false, keepBitmap: true };
/** Assigning `width`/`height` clears the bitmap, so only a real change does. */
function resizeCaptureCanvas(src: VfxCaptureSource, size: { width: number; height: number }): void {
if (src.canvas.width !== size.width) src.canvas.width = size.width;
if (src.canvas.height !== size.height) src.canvas.height = size.height;
}
function captureEmpty(
entry: VfxEntry,
src: VfxCaptureSource,
size: { width: number; height: number },
mode: CaptureMode,
): true {
resizeCaptureCanvas(src, size);
src.ctx.clearRect(0, 0, size.width, size.height);
if (mode.upload) uploadCaptureTexture(entry.gl, src);
return true;
}
/**
* Read one source's pixels into its texture. Both `clearRect`s matter: the
* first because `drawElementImage` composites onto whatever is there, the
* second because a `layoutsubtree` canvas's BITMAP is painted by the page
* compositor even though its children are not — leaving the captured frame in
* it would show the unprocessed layer through every transparent pixel of
* `.hf-vfx-out`.
*
* `keepBitmap` inverts exactly that second clear: for a `backdrop` wrapper
* whose host is not painting this frame, where the bitmap IS the frame (see
* `capturePassThrough`), and for a VISIBLE ref whose owning host is not
* painting (see `captureVisibleRefsOnly`) — the ref's layer is on screen
* either way.
*
* Every source is drawn at the HOST's device size (`captureBox`'s default),
* so `u_src` and `u_src2` share one coordinate space with `.hf-vfx-out` and a
* kernel can read both at the same `v_uv`. A matte whose own box differs from
* the host's is therefore scaled into the host's box rather than placed in
* composition space — v1's semantic, recorded because After Effects places it
* in comp space. A VISIBLE ref is the one exception: `captureBox` draws it at
* its OWN box, since it is a layer on the page and must paint at its own
* size, not the host's.
*/
function captureSource(
entry: VfxEntry,
src: VfxCaptureSource,
size: { width: number; height: number },
quiet: boolean,
mode: CaptureMode,
): boolean {
// A hidden source is an EMPTY capture, not a failure. The clip runtime hides
// a matte layer outside its own window (`visibility: hidden`, inherited by
// the `.hf-vfx-in` inside it), and a hidden subtree has no paint record:
// `drawElementImage` would throw "No cached paint record" on every one of
// those frames, and the `paint` wait before it would burn its whole ceiling
// first. An empty `u_src2` is also the right answer — under Alpha the layer
// it mattes disappears, under Alpha Inverted it passes, which is what After
// Effects does with a matte that is not there yet.
if (!isPaintableSource(src)) return captureEmpty(entry, src, size, mode);
// The one capture failure Chrome does NOT report: inside a `layoutsubtree`
// canvas a child sized by `inset`/percentages measures 0×0, and
// `drawElementImage` then succeeds and draws nothing at all — no throw, no
// warning, a blank layer. Measured (vault `layoutsubtree-capture-rules`),
// so it is said out loud once per source, and the frame paints from an empty
// capture rather than repeating the last one.
if (deviceSize(src.inner) === null) {
if (!src.emptyBoxReported) {
src.emptyBoxReported = true;
reportVfxFrameError(
`${describeHost(entry.host)}: the .hf-vfx-in wrapper measures 0×0, so its capture ` +
`would be empty. Inside a layoutsubtree canvas an inset or percentage box has no ` +
`size, so the wrapper must state an explicit width and height in px.`,
);
}
return captureEmpty(entry, src, size, mode);
}
resizeCaptureCanvas(src, size);
src.ctx.clearRect(0, 0, size.width, size.height);
try {
src.ctx.drawElementImage(src.inner, 0, 0, size.width, size.height);
} catch (err) {
// A speculative capture is quiet on purpose: it is the engine path's SECOND
// attempt at the same frame, racing the host's own `resolve`, and "no cached
// paint record yet" there is expected, recoverable, and must not fail a
// render. The authoritative attempt (preview paint, or `resolveVfxCapture`)
// still owns the loud error contract.
if (!quiet) {
reportVfxError(
`${describeHost(entry.host)}: drawElementImage failed: ${(err as Error).message} ` +
`In Studio, enable chrome://flags/#canvas-draw-element.`,
);
}
return false;
}
if (mode.upload) uploadCaptureTexture(entry.gl, src);
if (!mode.keepBitmap) src.ctx.clearRect(0, 0, size.width, size.height);
return true;
}
/**
* The box one source is drawn at. The host's, so `u_src`, `u_src2` and
* `.hf-vfx-out` share a pixel grid — except for a VISIBLE ref, which is a
* layer on the page and must paint at its own size and resolution. Sampling is
* unaffected either way: `drawElementImage(el, 0, 0, w, h)` scales the element
* into the whole canvas, so normalized `v_uv` addresses the same point in the
* element's box whatever the bitmap's pixel size — which is the v1 rule, a
* ref scaled into the host's box rather than placed in composition space.
*/
function captureBox(
src: VfxCaptureSource,
hostSize: { width: number; height: number },
): { width: number; height: number } {
if (!src.visible) return hostSize;
return deviceSize(src.inner) ?? hostSize;
}
/**
* Capture everything this entry's kernels read for one frame: `u_src`, then
* each node's `u_src2`. A source that fails does not stop the others — the
* failure is reported where it happened — but the frame is only "captured"
* when all of them are, so a half-captured paint never counts as authoritative.
*/
function captureEntry(entry: VfxEntry, quiet = false): boolean {
const size = deviceSize(entry.host);
const sources = entrySources(entry);
if (!size || sources.length === 0) return false;
let captured = true;
for (const source of sources) {
const mode = source.visible ? CAPTURE_VISIBLE_SOURCE : CAPTURE_TO_TEXTURE;
if (!captureSource(entry, source, captureBox(source, size), quiet, mode)) {
captured = false;
}
}
return captured;
}
/**
* A `backdrop` host that is not painting this frame — the clip runtime hides
* every host outside its `data-start`/`data-duration` window — still has to
* draw its source, because that source is every layer BELOW it and those
* layers are children of a `layoutsubtree` canvas: the page compositor paints
* the canvas bitmap and nothing else. Skipping the capture the way a `self`
* host is skipped would delete them from the frame instead of passing them
* through unprocessed.
*
* So: capture, keep the bitmap, paint no kernel. The adjustment layer is off,
* its input is on. Sized from the wrapper's own box when the host has none, so
* a host hidden with `display:none` (the timed-clip leaf path) still passes its
* layers through.
*/
function capturePassThrough(entry: VfxEntry, quiet = false): boolean {
const src = entry.src;
if (!src) return false;
const size = deviceSize(entry.host) ?? deviceSize(src.inner);
if (!size) return false;
return captureSource(entry, src, size, quiet, CAPTURE_PASS_THROUGH);
}
/**
* A host that is not painting this frame but owns a VISIBLE ref: that ref's
* AE layer can outlive the kernel host's own `data-start`/`data-duration`
* window (retro-wave `Logo Anim` layer 5 again — it is layer 4's displacement
* map AND a layer with its own, different, on-screen span), so its bitmap has
* to stay current even though no kernel reads it this frame. Capture only,
* never upload: nothing will bind the texture, since `paintEntry` does not
* run for a host that is not painting.
*
* A `hostSize` fallback of `{0, 0}` is safe here: `captureBox` only falls back
* to it when a VISIBLE source's own box (`deviceSize(src.inner)`) is null, and
* that is already reported by `captureSource`'s own 0×0 check.
*/
function captureVisibleRefsOnly(entry: VfxEntry, quiet = false): boolean {
let ok = true;
for (const ref of visibleRefSources(entry)) {
const size = captureBox(ref, { width: 0, height: 0 });
if (!captureSource(entry, ref, size, quiet, CAPTURE_VISIBLE_ONLY)) ok = false;
}
return ok;
}
/**
* A hidden host still needs capturing when it's a backdrop's layers-below
* source, or when one of its passes' ref sources paints visibly elsewhere —
* and a host can be BOTH (a backdrop whose displacement map is itself a
* visible layer), so this always runs whichever apply, not one or the other.
*/
function captureHiddenEntry(entry: VfxEntry): boolean {
let ok = false;
if (isBackdropEntry(entry) && capturePassThrough(entry)) ok = true;
if (visibleRefSources(entry).length > 0 && captureVisibleRefsOnly(entry)) ok = true;
return ok;
}
/** Phase 2 of the page-composite protocol: the paint records are valid now. */
function resolveVfxCapture(): boolean {
let painted = false;
for (const entry of registry) {
if (entry.contextLost) continue;
if (entrySources(entry).length === 0) continue;
if (!isPaintableHost(entry.host)) {
if (captureHiddenEntry(entry)) painted = true;
continue;
}
if (!captureEntry(entry)) continue;
paintEntry(entry, lastPaintTime);
painted = true;
}
// Deliberately NOT idempotent: the engine resolves only after its own
// before-capture hooks have mutated the DOM (video frames injected as <img>,
// scenes cloned), so its capture is the authoritative one even when a
// fallback already painted this frame from the pre-hook DOM. Recording the
// token is what lets that earlier fallback stand down, not the reverse.
resolvedSeq = paintSeq;
(window as CompositeWindow).__hf_page_composite_pending = false;
return painted;
}
/**
* Claim the engine's two-phase readiness protocol, COMPOSING with whoever else
* owns it rather than replacing them: shader-transitions runs first (its
* composite is whole-scene, ours is per-layer). Re-checked on every paint
* because `installPageSideCompositor` polls for `__hf.seek` on a 50 ms interval
* and plainly assigns the slot, so an install after ours would replace us.
*/
function armPageComposite(): void {
const w = window as CompositeWindow;
const current = w.__hf_page_composite_resolve;
if (current !== vfxResolver) {
priorResolver = typeof current === "function" ? current : null;
vfxResolver = () => {
const prior = priorResolver ? priorResolver() : false;
return resolveVfxCapture() || prior;
};
w.__hf_page_composite_resolve = vfxResolver;
}
w.__hf_page_composite_pending = true;
}
/**
* Ceiling on ONE host's `paint` wait before its capture is abandoned.
*
* A real paint is two animation frames — under 100 ms at any plausible frame
* rate — so 2 s is roughly a 20x margin, and it is short next to what a hung
* barrier would otherwise burn (Puppeteer's ~180 s CDP `protocolTimeout`). It
* is also the deadline this repo already uses for a BeginFrame-shaped wait
* (`BEGINFRAME_PROBE_TIMEOUT_MS`, `engine/src/services/browserManager.ts`).
*
* Deliberately longer than the comparable 250 ms `paint`-event fallback in
* `engine/src/services/drawElementService.ts`: that one falls back to DRAWING a
* frame-stale snapshot, so a false positive costs a frame of staleness, while
* this one skips the host's capture and reports loudly — so its false positives
* are expensive and it gets the wider margin.
*/
const CAPTURE_PAINT_TIMEOUT_MS = 2000;
/**
* Preview/Studio readiness: `drawElementImage` throws "No cached paint record
* for element" unless the subtree has been painted since it last changed, and
* a synchronous `requestPaint()` does not create one within the same task.
*
* BOUNDED, because this wait is part of the shared seek-completion barrier
* (see `paintVfx`) and neither thing that settles it is guaranteed to happen.
* Under BeginFrame control (Linux headless-shell, `drawelement` capture) the
* compositor advances only on an explicit `HeadlessExperimental.beginFrame`,
* and `frameCapture.ts` issues that inside its per-frame capture stage — AFTER
* `prepareFrameForCapture` has already drained this barrier. With no tick yet
* for the frame, no `paint` event fires, and the rAF fallback does not fire
* either: the engine's own notes say rAF is gated the same way
* (`frameCapture.ts` ~line 2445, "waitForFunction uses rAF polling internally,
* which won't fire in beginFrame mode"; ~line 4755, "headless only fires rAF
* when a frame is produced, and nothing produces one until a screenshot
* asks"). `setTimeout` is the one clock that is NOT compositor-gated there —
* `drawElementService.ts` (~line 341) describes its 250 ms paint-wait fallback
* as burning "on every frame" under BeginFrame control, which can only happen
* if the timer fires — so this ceiling is what keeps the barrier live.
*/
function awaitCanvasPaint(canvas: HTMLCanvasElement): Promise<"painted" | "timeout"> {
return new Promise<"painted" | "timeout">((resolve) => {
let settled = false;
const finish = (outcome: "painted" | "timeout"): void => {
if (settled) return;
settled = true;
clearTimeout(timer);
canvas.removeEventListener("paint", onPaint);
resolve(outcome);
};
const onPaint = (): void => finish("painted");
// Cleared by `finish`, so the common case adds no latency and leaves no
// timer behind; on a canvas that never paints it is the only way out.
const timer = setTimeout(() => finish("timeout"), CAPTURE_PAINT_TIMEOUT_MS);
canvas.addEventListener("paint", onPaint, { once: true });
try {
(canvas as RequestPaintCanvas).requestPaint?.();
} catch {
// Feature drift on this build — the rAF fallback below still fires.
}
if (typeof requestAnimationFrame !== "function") {
finish("painted");
return;
}
requestAnimationFrame(() => requestAnimationFrame(() => finish("painted")));
});
}
/** Every source's canvas, awaited together; `false` once a timeout has been
* reported. In parallel because one canvas's wait does not inform another's. */
async function awaitSourcePaints(entry: VfxEntry, sources: VfxCaptureSource[]): Promise<boolean> {
const outcomes = await Promise.all(sources.map((source) => awaitCanvasPaint(source.canvas)));
if (!outcomes.includes("timeout")) return true;
reportVfxFrameError(
`${describeHost(entry.host)}: no paint arrived within ${CAPTURE_PAINT_TIMEOUT_MS}ms, so ` +
`this frame's capture was skipped (a BeginFrame-controlled compositor without a tick ` +
`for this frame is a known cause).`,
);
return false;
}
/**
* Which of an entry's three capture shapes this frame needs, decided once so
* every step of `capturePaintedHost` reads the same answer: the host's own
* kernel paint, the backdrop pass-through (which ALSO captures any visible
* ref the host owns — a backdrop's displacement map can itself be a layer
* with its own on-screen span), or — a host that is hidden and NOT a
* backdrop, but owns a visible ref whose own layer must keep showing — a
* ref-only capture that skips the kernel entirely.
*/
type FrameCaptureMode = "paint" | "passThrough" | "refOnly";
function frameCaptureMode(entry: VfxEntry): FrameCaptureMode {
if (isPaintableHost(entry.host)) return "paint";
return isBackdropEntry(entry) ? "passThrough" : "refOnly";
}
/** The sources this frame needs: all of them to paint; the backdrop wrapper
* plus any visible ref(s) to pass through (a backdrop host can itself own a
* visible ref — its displacement map may be a layer with its own on-screen
* span); or just the visible ref(s) alone to keep them current. */
function sourcesForFrame(entry: VfxEntry, mode: FrameCaptureMode): VfxCaptureSource[] {
const sources =
mode === "passThrough"
? [...(entry.src ? [entry.src] : []), ...visibleRefSources(entry)]
: mode === "refOnly"
? visibleRefSources(entry)
: entrySources(entry);
// A hidden source never fires `paint`, and under a BeginFrame-controlled
// compositor the rAF fallback does not either — waiting on one would spend
// the whole ceiling, every frame, to arrive at the empty capture
// `captureSource` gives it for free.
return sources.filter(isPaintableSource);
}
/**
* Nothing has taken this frame over during the paint wait: no newer seek, no
* engine resolve that already owns the pixels, and no `initVfx` re-scan — that
* releases the outgoing registry's programs and textures, and painting a
* released entry is a silent GL error rather than a frame.
*/
function stillOwnsFrame(entry: VfxEntry, seq: number): boolean {
if (seq !== paintSeq || resolvedSeq === seq) return false;
return registry.includes(entry) && !entry.contextLost;
}
/**
* Wait for one host's canvas to paint, then capture and paint that host.
*
* Per host, not per batch: a host whose compositor genuinely cannot paint this
* frame must not make every other host on the page wait out the ceiling too.
* A host that times out is skipped for this paint — no capture, no guess at
* pixels — and says so loudly. The report is NOT suppressed in engine mode
* even though a capture failure there is quiet (`speculative`): that quiet is
* for the engine's second attempt at the same frame, and in `drawelement` /
* `beginframe` capture mode there is no second attempt — `frameCapture.ts`
* (~line 2708) skips `__hf_page_composite_resolve` in exactly those modes, so
* this wait is the only capture path the frame has.
*/
async function capturePaintedHost(
entry: VfxEntry,
t: number,
seq: number,
speculative: boolean,
): Promise<void> {
// A pass-through frame needs the backdrop wrapper's paint record plus any
// visible ref's; a ref-only frame needs only the visible ref's; a painting
// frame needs one per source the kernels read. Records are per canvas, so
// the waits are too.
const mode = frameCaptureMode(entry);
if (!(await awaitSourcePaints(entry, sourcesForFrame(entry, mode)))) return;
if (!stillOwnsFrame(entry, seq)) return;
if (mode === "passThrough") {
capturePassThrough(entry, speculative);
captureVisibleRefsOnly(entry, speculative);
return;
}
if (mode === "refOnly") {
captureVisibleRefsOnly(entry, speculative);
return;
}
if (captureEntry(entry, speculative)) paintEntry(entry, t);
}
async function capturePreviewThenPaint(
entries: VfxEntry[],
t: number,
seq: number,
speculative: boolean,
): Promise<void> {
// In parallel, not in sequence: each wait costs up to two animation frames,
// so N hosts awaited one after another cost 2N — more slack than the CLI's
// post-barrier settle leaves, and the cost grows with the composition.
await Promise.all(entries.map((entry) => capturePaintedHost(entry, t, seq, speculative)));
}
/** A `.hf-vfx-in` first painted at 0×0 and then sized can stay blank in its capture until re-inserted (measured). */
function reinsertRegrownSources(): void {
for (const src of registry.flatMap(entrySources)) {
const empty = deviceSize(src.inner) === null;
if (src.laidOutEmpty && !empty) src.canvas.insertBefore(src.inner, src.inner.nextSibling);
src.laidOutEmpty = empty;
}
}
/**
* Repaint every registered chain for composition-local time `t`. Called from
* the runtime transport's `seek` (preview) and `renderSeek` (engine) — the two
* places a frame's DOM state is finished changing.
*
* A chain with no capture paints inline. A capturing chain cannot: its texture
* comes from `drawElementImage`, which needs a paint record that does not exist
* yet at this point in the task.
*
* That deferred capture is REGISTERED INTO THE SHARED SEEK-COMPLETION BARRIER
* (`adapters/seek-dispatch.ts`) rather than left fire-and-forget, so the paths
* that already drain the barrier wait for it instead of racing it:
* `seekCompositionTimeline` awaits `window.__hfWaitForSeekCompletion` before
* its settle race and screenshot, which covers `snapshot`, `check`, `compare`,
* `validate` and `layout`. Racing it is the silent-blank-under-snapshot defect
* this module has already shipped once (dcfbda9fd) — there the capture never
* ran at all, here it ran too late, and both read as an unpainted layer.
*
* Joining that barrier makes this module's wait able to STALL every caller of
* `__hfWaitForSeekCompletion`, the engine's render path included:
* `frameCapture.ts` drains the barrier inside `prepareFrameForCapture` (~line
* 2692), which on a BeginFrame-controlled host (Linux headless-shell,
* `drawelement` capture) runs BEFORE the per-frame
* `HeadlessExperimental.beginFrame` that the compositor needs to paint at all
* (~line 3797). Fire-and-forget, that could not hurt anyone; registered, it
* can. `awaitCanvasPaint` is therefore bounded at
* `CAPTURE_PAINT_TIMEOUT_MS`, which converts an indefinite hang into a loud,
* bounded, per-host failure — the other hosts on the page still paint on their
* own schedule, and the barrier always resolves.
*/
export function paintVfx(t: number, options?: { engineMode?: boolean }): void {
lastPaintTime = t;
const seq = ++paintSeq;
reinsertRegrownSources();
const capturing: VfxEntry[] = [];
for (const entry of registry) {
// Reported once, at the moment of loss; repeating it per frame is spam.
if (entry.contextLost) continue;
if (!isPaintableHost(entry.host)) {
// A hidden `backdrop` host is an adjustment layer that is off, not a
// reason to drop the layers below it — those live in the wrapper
// OUTSIDE the host and are invisible until something draws them. A
// hidden non-backdrop host with a VISIBLE ref is the same shape one
// level removed: the ref's own AE layer can outlive this host's
// data-start/data-duration window, and skipping the whole entry would
// leave that layer missing (before its host's window) or stale (after
// it, since `CAPTURE_VISIBLE_SOURCE`/`CAPTURE_VISIBLE_ONLY` both keep
// the bitmap).
if (isBackdropEntry(entry) || visibleRefSources(entry).length > 0) capturing.push(entry);
continue;
}
if (entrySources(entry).length > 0) capturing.push(entry);
else paintEntry(entry, t);
}
if (capturing.length === 0) return;
// Engine mode arms the page-composite protocol AND the preview-side capture,
// then paints on whichever completes first. Arming alone was a bet that every
// capture host runs under `frameCapture.ts`, and it does not: `hyperframes
// snapshot` (and `check`/`compare`/`validate`/`layout`, and Studio's
// thumbnail capture) seek through the same `seekCompositionTimeline` →
// `renderSeek`, never read `__hf_page_composite_pending`, and never call
// `__hf_page_composite_resolve` — so a `self` chain painted nothing there, in
// silence. The runtime has to be able to finish its own frame.
if (options?.engineMode) armPageComposite();
registerSeekCompletion(capturePreviewThenPaint(capturing, t, seq, options?.engineMode === true));
}