Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import puppeteer, { type Browser, type Page } from "puppeteer";
import { displacementMapSampleRef } from "../../../core/src/vfx/refs/displacementMap";
import { fractalNoiseRef } from "../../../core/src/vfx/refs/fractalNoise";
import { waveWarpSampleRef } from "../../../core/src/vfx/refs/waveWarp";
/**
* Browser-side contract for `data-vfx-chain`, on the real runtime bundle.
*
* Rebuild the bundle before running this file, or it tests a stale runtime:
*
* cd packages/core && bun run build:hyperframes-runtime
*
* `drawElementImage` lives behind `--enable-features=CanvasDrawElement`, which
* the engine's own browser launcher already passes
* (`packages/engine/src/services/browserManager.ts`,
* `CANVAS_DRAW_ELEMENT_FEATURE_FLAG`).
*/
const RUNTIME_PATH = resolve(import.meta.dirname, "../../../core/dist/hyperframe.runtime.iife.js");
const HOST_W = 160;
const HOST_H = 120;
/** The red block fills the left half of `.hf-vfx-in`. */
const SQUARE_W = 80;
/** Clearance between the two hosts of `twoHostFixture`. */
const GAP = 20;
/** Opaque red — what a correctly painted identity chain puts at the probe point. */
const red = [255, 0, 0, 255];
interface CompositeWindow extends Window {
__hf_page_composite_pending?: boolean;
__hf_page_composite_resolve?: () => boolean;
__player?: { renderSeek: (t: number) => void };
__playerReady?: boolean;
__renderReady?: boolean;
}
function chainOf(type: string, params: Record<string, number | boolean>): string {
return JSON.stringify({ version: 1, nodes: [{ type, id: "n1", params }] });
}
function waveWarpChain(params: Record<string, number>): string {
return chainOf("wave-warp", {
waveType: 1,
direction: 0,
speed: 0,
pinning: 1,
phase: 0,
...params,
});
}
/**
* A `self` host exactly as the exporter emits it: the layer content lives in a
* `<canvas layoutsubtree>`, the kernel's output in a sibling canvas. The page
* is blue so a transparent output pixel is distinguishable from a black one.
*
* `.hf-vfx-in` carries an explicit pixel box. Inside a `layoutsubtree` canvas
* there is no containing block to resolve `inset: 0` against, so the wrapper
* collapses to 0×0 and `drawElementImage` silently draws nothing — the same
* collapse the page-side compositor avoids by staging scene copies in a sized frame.
*/
function fixture(chain: string, innerStyle = "", hostStart = 0): string {
return `<!doctype html>
<style>
html, body { margin: 0; background: #0000ff; }
#host { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
/* An explicit box, not inset:0 — see the fixture note below. */
.hf-vfx-in { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#square {
position: absolute; left: 0; top: 0;
width: ${SQUARE_W}px; height: ${HOST_H}px; background: #ff0000;
}
</style>
<div data-composition-id="root" data-start="0" data-duration="4"
data-width="${HOST_W}" data-height="${HOST_H}">
<div id="host" class="clip" data-start="${hostStart}" data-duration="4"
data-vfx-chain='${chain}'>
<canvas layoutsubtree class="hf-vfx-src"><div class="hf-vfx-in" style="${innerStyle}"><div id="square"></div></div></canvas>
<canvas class="hf-vfx-out"></canvas>
</div>
</div>`;
}
/**
* The same `self` host, except `.hf-vfx-in` is a SUB-COMPOSITION MOUNT: it
* carries `data-composition-src`, so the runtime empties it and mounts
* `inner.html` into it after init. The real exporter emits exactly this shape
* for any AE layer that is a pre-comp — the mount attributes live on
* `.hf-vfx-in` rather than the host so `resetCompositionHost` cannot take the
* `.hf-vfx-src`/`.hf-vfx-out` canvases with it.
*/
function mountFixture(chain: string): string {
return `<!doctype html>
<style>
html, body { margin: 0; background: #0000ff; }
#host { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
</style>
<div data-composition-id="root" data-start="0" data-duration="4"
data-width="${HOST_W}" data-height="${HOST_H}">
<div id="host" class="clip" data-start="0" data-duration="4" data-vfx-chain='${chain}'>
<canvas layoutsubtree class="hf-vfx-src" width="${HOST_W}" height="${HOST_H}"><div class="hf-vfx-in" data-composition-id="inner" data-composition-src="inner.html" data-width="${HOST_W}" data-height="${HOST_H}" style="position:absolute;left:0;top:0;width:${HOST_W}px;height:${HOST_H}px;"><div id="pre-mount" style="position:absolute;left:0;top:0;width:${HOST_W}px;height:${HOST_H}px;background:rgb(0,255,0)"></div></div></canvas>
<canvas class="hf-vfx-out"></canvas>
</div>
</div>`;
}
/** The mounted sub-composition, in the exporter's `<template>` document shape. */
const MOUNT_INNER = `<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Inner</title></head>
<body>
<template>
<style>html,body{margin:0;padding:0;background:transparent}#root *{box-sizing:border-box}</style>
<div id="root" data-composition-id="inner" data-width="${HOST_W}" data-height="${HOST_H}" data-duration="4" data-fps="30" style="position:relative;overflow:hidden;width:${HOST_W}px;height:${HOST_H}px;background:transparent">
<div id="inner-square" class="clip" data-start="0" data-duration="4" style="position:absolute;left:0;top:0;width:${SQUARE_W}px;height:${HOST_H}px;background:rgb(255,0,0)"></div>
</div>
<script>
(function () {
var tl = window.gsap ? gsap.timeline({ paused: true }) : { seek: function () {} };
window.__timelines["inner"] = tl;
})();
</script>
</template>
</body>
</html>`;
/** A page whose only content is a sub-composition mount. */
const NESTED_HOST_MAIN = `<!doctype html>
<style>html, body { margin: 0; background: #0000ff; }</style>
<div data-composition-id="root" data-start="0" data-duration="4"
data-width="${HOST_W}" data-height="${HOST_H}">
<div id="outer" class="clip" data-start="0" data-duration="4" data-composition-id="inner"
data-composition-src="inner.html" data-width="${HOST_W}" data-height="${HOST_H}"
style="position:absolute;left:0;top:0;width:${HOST_W}px;height:${HOST_H}px"></div>
</div>`;
/** The whole vfx host lives in the sub-composition, so it enters the DOM on mount. */
const NESTED_HOST_INNER = (chain: string): string => `<!doctype html>
<html lang="en"><head><meta charset="utf-8"></head><body>
<template>
<style>
#host { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
</style>
<div id="root" data-composition-id="inner" data-width="${HOST_W}" data-height="${HOST_H}" data-duration="4" data-fps="30" style="position:relative;overflow:hidden;width:${HOST_W}px;height:${HOST_H}px">
<div id="host" class="clip" data-start="0" data-duration="4" data-vfx-chain='${chain}'>
<canvas layoutsubtree class="hf-vfx-src" width="${HOST_W}" height="${HOST_H}"><div class="hf-vfx-in" style="position:absolute;left:0;top:0;width:${HOST_W}px;height:${HOST_H}px"><div style="position:absolute;left:0;top:0;width:${SQUARE_W}px;height:${HOST_H}px;background:rgb(255,0,0)"></div></div></canvas>
<canvas class="hf-vfx-out"></canvas>
</div>
</div>
</template>
</body></html>`;
/** Where the two side-by-side panels sit in the chain-order fixture. */
const PANEL = { ax: 20, bx: 220, y: 30, w: HOST_W, h: HOST_H };
/** Retro-wave's Fractal Noise parameter point, opacity raised to 100 so the readback isn't flattened by alpha. */
const NOISE_PARAMS = {
fractalType: 1,
noiseType: 3,
invert: false,
contrast: 562,
brightness: 0,
scale: 411,
complexity: 6,
subInfluence: 70,
subScaling: 56,
evolution: 0,
randomSeed: 0,
opacity: 100,
};
/**
* `fractal-noise` has `capture: "none"` — no `.hf-vfx-src`/`.hf-vfx-in`
* wrapper, so the host is plain content with just the output canvas the
* runtime paints into inline on `renderSeek` (no page-composite round trip).
*/
function noiseFixture(chain: string): string {
return `<!doctype html>
<style>
html, body { margin: 0; background: #000; }
#host { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
</style>
<div data-composition-id="root" data-start="0" data-duration="4"
data-width="${HOST_W}" data-height="${HOST_H}">
<div id="host" class="clip" data-start="0" data-duration="4" data-vfx-chain='${chain}'>
<canvas class="hf-vfx-out"></canvas>
</div>
</div>`;
}
async function readNoiseBuffer(
page: Page,
): Promise<{ width: number; height: number; data: number[] }> {
return page.evaluate(() => {
const out = document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement;
const gl = out.getContext("webgl2")!;
const buf = new Uint8Array(out.width * out.height * 4);
gl.readPixels(0, 0, out.width, out.height, gl.RGBA, gl.UNSIGNED_BYTE, buf);
return { width: out.width, height: out.height, data: Array.from(buf) };
});
}
async function renderSeekOnly(page: Page, t: number): Promise<void> {
await page.evaluate((time: number) => {
(window as CompositeWindow).__player!.renderSeek(time);
}, t);
}
/**
* TWO `self` hosts, so a per-host sequential wait costs twice as many frames
* as a single-host one. One host can be painted by luck; two cannot.
*/
function twoHostFixture(chain: string): string {
const host = (side: string): string => `
<div id="host-${side}" class="vfx-host clip" data-start="0" data-duration="4"
data-vfx-chain='${chain}'>
<canvas layoutsubtree class="hf-vfx-src"><div class="hf-vfx-in"><div class="square"></div></div></canvas>
<canvas class="hf-vfx-out"></canvas>
</div>`;
return `<!doctype html>
<style>
html, body { margin: 0; background: #0000ff; }
.vfx-host { position: absolute; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host-a { left: 0; }
#host-b { left: ${HOST_W + GAP}px; }
.vfx-host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
.hf-vfx-in { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
.square {
position: absolute; left: 0; top: 0;
width: ${SQUARE_W}px; height: ${HOST_H}px; background: #ff0000;
}
</style>
<div data-composition-id="root" data-start="0" data-duration="4"
data-width="${HOST_W * 2 + GAP}" data-height="${HOST_H}">${host("a")}${host("b")}
</div>`;
}
/**
* What `seekCompositionTimeline` does, by hand: dispatch the seek, drain the
* seek-completion barrier, then ONE settle race — `setTimeout(100)` against a
* double rAF, copied from the CLI's default `animationFrameSettle: "race"`
* (`packages/cli/src/capture/captureCompositionFrame.ts`). Whatever has not
* painted by the time this returns is what `hyperframes snapshot` screenshots
* as blank.
*/
async function seekAndDrainBarrier(page: Page, t: number): Promise<void> {
await page.evaluate((time: number) => {
(window as CompositeWindow).__player!.renderSeek(time);
}, t);
// Asserted, not optional-chained: a bundle that never exposed the barrier
// would make the whole case a no-op that passes.
const drained = await page.evaluate(async () => {
const wait = Reflect.get(window, "__hfWaitForSeekCompletion");
if (typeof wait !== "function") return false;
await Reflect.apply(wait, window, []);
return true;
});
expect(drained).toBe(true);
}
/**
* The CLI's default `animationFrameSettle: "race"`, copied verbatim from
* `packages/cli/src/capture/captureCompositionFrame.ts`: a 100 ms timeout
* against a double rAF, whichever lands first. This is all the slack a real
* snapshot leaves between the barrier and the screenshot.
*/
async function settleRace(page: Page): Promise<void> {
await page.evaluate(`new Promise(function(r) {
var settled = false;
function finish() { if (settled) return; settled = true; r(); }
window.setTimeout(finish, 100);
requestAnimationFrame(function() { requestAnimationFrame(finish); });
})`);
}
/** RGBA at one interior point of every `.hf-vfx-out` on the page. */
async function sampleEveryOut(page: Page): Promise<number[][]> {
return page.evaluate(() =>
[...document.querySelectorAll("canvas.hf-vfx-out")].map((node) => {
const gl = (node as HTMLCanvasElement).getContext("webgl2");
if (!gl) return [];
const px = new Uint8Array(4);
gl.readPixels(40, 60, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, px);
return [...px];
}),
);
}
/**
* Chain order is nesting order. The exporter puts effects that run BEFORE the
* chain node on `.hf-vfx-in` (inside the capture) and effects that run AFTER it
* on the host (outside, applied by the page compositor to `.hf-vfx-out`).
*
* Panel A is that arrangement with an identity kernel between the two filters;
* panel B is the same nesting as plain DOM. If the runtime honours the order,
* the two panels are the same picture. Both sit on the same blue field with the
* same clearance, so their filters spill into identical neighbourhoods.
*/
function chainOrderFixture(chain: string): string {
return `<!doctype html>
<style>
html, body { margin: 0; background: #0000ff; }
.panel { position: absolute; top: ${PANEL.y}px; width: ${HOST_W}px; height: ${HOST_H}px; }
#host { left: ${PANEL.ax}px; }
#control { left: ${PANEL.bx}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
.inner { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
.square {
position: absolute; left: 0; top: 0;
width: ${SQUARE_W}px; height: ${HOST_H}px; background: #ff0000;
}
</style>
<svg width="0" height="0" style="position:absolute">
<filter id="tint" color-interpolation-filters="sRGB">
<feColorMatrix type="matrix" values="0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 1 0"/>
</filter>
</svg>
<div data-composition-id="root" data-start="0" data-duration="4"
data-width="400" data-height="180">
<div id="host" class="panel clip" data-start="0" data-duration="4"
data-vfx-chain='${chain}' style="filter: blur(2px)">
<canvas layoutsubtree class="hf-vfx-src"><div class="hf-vfx-in inner" style="filter: url(#tint)"><div class="square"></div></div></canvas>
<canvas class="hf-vfx-out"></canvas>
</div>
<div id="control" class="panel" style="filter: blur(2px)">
<div class="inner" style="filter: url(#tint)"><div class="square"></div></div>
</div>
</div>`;
}
/**
* `backdrop` capture: two stacked (not side-by-side) colored blocks live in a
* `<canvas layoutsubtree class="hf-vfx-src" data-vfx-for="host">` SIBLING of
* the host, per interface v1.1 and `resolveCaptureSource`/`findBackdropWrapper`
* in `packages/core/src/runtime/vfx.ts`. `#control` renders the same two
* blocks as plain DOM at `PANEL.bx` so `panelPsnr` can compare the two.
*/
function backdropStackedFixture(chain: string): string {
const blocks = `
<div style="position:absolute;left:0;top:0;width:${PANEL.w}px;height:${PANEL.h / 2}px;background:#ff0000"></div>
<div style="position:absolute;left:0;top:${PANEL.h / 2}px;width:${PANEL.w}px;height:${PANEL.h / 2}px;background:#00ff00"></div>`;
return `<!doctype html>
<style>
html, body { margin: 0; background: #0000ff; }
.panel { position: absolute; top: ${PANEL.y}px; width: ${PANEL.w}px; height: ${PANEL.h}px; }
#host { left: ${PANEL.ax}px; }
#host > canvas { position: absolute; inset: 0; width: ${PANEL.w}px; height: ${PANEL.h}px; }
#wrap { position: absolute; left: ${PANEL.ax}px; top: ${PANEL.y}px; width: ${PANEL.w}px; height: ${PANEL.h}px; }
.hf-vfx-in { position: absolute; left: 0; top: 0; width: ${PANEL.w}px; height: ${PANEL.h}px; }
#control { left: ${PANEL.bx}px; }
</style>
<div data-composition-id="root" data-start="0" data-duration="4"
data-width="${PANEL.bx + PANEL.w + PANEL.ax}" data-height="${PANEL.y + PANEL.h + PANEL.y}">
<canvas id="wrap" layoutsubtree class="hf-vfx-src" data-vfx-for="host"><div class="hf-vfx-in">${blocks}</div></canvas>
<div id="host" class="panel clip" data-start="0" data-duration="4" data-vfx-chain='${chain}'>
<canvas class="hf-vfx-out"></canvas>
</div>
<div id="control" class="panel">${blocks}</div>
</div>`;
}
/**
* The same two stacked blocks, but the host reading them through `backdrop`
* is OUTSIDE its own `data-start`/`data-duration` window at the seek time
* under test — the real way a host goes invisible (the clip runtime owns
* `visibility` for `.clip` elements and forces it back to `visible` inside
* the window, which is what made a plain CSS `visibility:hidden` override on
* an in-window host a no-op when this fixture was first written).
* `capturePassThrough` keeps the captured bitmap ON the wrapper canvas itself
* rather than clearing it, because the wrapper's children never paint on
* their own — it is the only thing left that can still show the layers below
* a switched-off adjustment layer.
*/
function hiddenBackdropFixture(chain: string): string {
return `<!doctype html>
<style>
html, body { margin: 0; background: #0000ff; }
#wrap { position: absolute; left: 20px; top: 30px; width: ${HOST_W}px; height: ${HOST_H}px; }
.hf-vfx-in { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host { position: absolute; left: 20px; top: 30px; width: ${HOST_W}px; height: ${HOST_H}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
</style>
<div data-composition-id="root" data-start="0" data-duration="20" data-width="240" data-height="180">
<canvas id="wrap" layoutsubtree class="hf-vfx-src" data-vfx-for="host">
<div class="hf-vfx-in">
<div style="position:absolute;left:0;top:0;width:${HOST_W}px;height:${HOST_H / 2}px;background:#ff0000"></div>
<div style="position:absolute;left:0;top:${HOST_H / 2}px;width:${HOST_W}px;height:${HOST_H / 2}px;background:#00ff00"></div>
</div>
</canvas>
<div id="host" class="clip" data-start="10" data-duration="4" data-vfx-chain='${chain}'>
<canvas class="hf-vfx-out"></canvas>
</div>
</div>`;
}
/**
* `luma-matte`: the host's own content is an opaque white square (so the
* kernel's output is coverage alone), and a `matte` `ref` param names a
* second element — `#matte` — wrapped in its own `.hf-vfx-src` capture, per
* `resolveRefSource`. Four vertical strips give four coverage samples.
*/
function lumaMatteFixture(chain: string, matteStrips: string): string {
return `<!doctype html>
<style>
html, body { margin: 0; background: #000; }
#host { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#matte { position: absolute; left: 0; top: 200px; width: ${HOST_W}px; height: ${HOST_H}px; }
.hf-vfx-in { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
</style>
<div data-composition-id="root" data-start="0" data-duration="4" data-width="${HOST_W}" data-height="320">
<div id="host" class="clip" data-start="0" data-duration="4" data-vfx-chain='${chain}'>
<canvas layoutsubtree class="hf-vfx-src"><div class="hf-vfx-in"><div style="position:absolute;left:0;top:0;width:${HOST_W}px;height:${HOST_H}px;background:#ffffff"></div></div></canvas>
<canvas class="hf-vfx-out"></canvas>
</div>
<div id="matte">
<canvas layoutsubtree class="hf-vfx-src"><div class="hf-vfx-in">${matteStrips}</div></canvas>
</div>
</div>`;
}
/**
* `displacement-map` with an EXTERNAL map: the host holds the same red block
* as `fixture`, and `#map` — a second element with its own `.hf-vfx-src`
* capture — supplies `u_src2`. The map is a solid opaque BLACK panel, not a
* gradient: a CSS gradient's interpolation is implementation-defined, while a
* flat panel gives an exact texel and therefore an exact displacement.
*/
function displacementRefFixture(chain: string, mapVisible = false, mapW = HOST_W): string {
const visible = mapVisible ? " data-vfx-ref-visible" : "";
return `<!doctype html>
<style>
html, body { margin: 0; background: #0000ff; }
#host { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host .hf-vfx-in { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#map { position: absolute; left: 0; top: 200px; width: ${mapW}px; height: ${HOST_H}px; }
#map > canvas { width: ${mapW}px; height: ${HOST_H}px; }
#map .hf-vfx-in { position: absolute; left: 0; top: 0; width: ${mapW}px; height: ${HOST_H}px; }
</style>
<div data-composition-id="root" data-start="0" data-duration="4" data-width="${HOST_W}" data-height="320">
<div id="host" class="clip" data-start="0" data-duration="4" data-vfx-chain='${chain}'>
<canvas layoutsubtree class="hf-vfx-src"><div class="hf-vfx-in"><div style="position:absolute;left:0;top:0;width:${SQUARE_W}px;height:${HOST_H}px;background:#ff0000"></div></div></canvas>
<canvas class="hf-vfx-out"></canvas>
</div>
<div id="map">
<canvas layoutsubtree class="hf-vfx-src"${visible}><div class="hf-vfx-in"><div style="position:absolute;left:0;top:0;width:${mapW}px;height:${HOST_H}px;background:#000000"></div></div></canvas>
</div>
</div>`;
}
/**
* `luma-matte` with a VISIBLE matte whose box is twice the host's. Two claims
* at once: the wrapper's bitmap survives the capture (the layer still paints),
* and the kernel still reads it scaled into the host's box.
*/
function visibleMatteFixture(chain: string, matteW: number): string {
const strips = [0, 85 / 255, 170 / 255, 1]
.map(
(a, i) =>
`<div style="position:absolute;left:${(i * matteW) / 4}px;top:0;width:${matteW / 4}px;height:${HOST_H}px;background:rgba(0,0,0,${a})"></div>`,
)
.join("");
return `<!doctype html>
<style>
html, body { margin: 0; background: #000; }
#host { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host > canvas { position: absolute; inset: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#host .hf-vfx-in { position: absolute; left: 0; top: 0; width: ${HOST_W}px; height: ${HOST_H}px; }
#matte { position: absolute; left: 0; top: 200px; width: ${matteW}px; height: ${HOST_H}px; }
#matte > canvas { width: ${matteW}px; height: ${HOST_H}px; }
#matte .hf-vfx-in { position: absolute; left: 0; top: 0; width: ${matteW}px; height: ${HOST_H}px; }
</style>
<div data-composition-id="root" data-start="0" data-duration="4" data-width="${matteW}" data-height="320">
<div id="host" class="clip" data-start="0" data-duration="4" data-vfx-chain='${chain}'>
<canvas layoutsubtree class="hf-vfx-src"><div class="hf-vfx-in"><div style="position:absolute;left:0;top:0;width:${HOST_W}px;height:${HOST_H}px;background:#ffffff"></div></div></canvas>
<canvas class="hf-vfx-out"></canvas>
</div>
<div id="matte">
<canvas layoutsubtree class="hf-vfx-src" data-vfx-ref-visible><div class="hf-vfx-in">${strips}</div></canvas>
</div>
</div>`;
}
/** Four strips of constant luma (black) with alpha 0, 1/3, 2/3, 1 — isolates the Alpha/Alpha Inverted modes from Luma. */
function alphaMatteStrips(): string {
return [0, 85 / 255, 170 / 255, 1]
.map(
(a, i) =>
`<div style="position:absolute;left:${i * 40}px;top:0;width:40px;height:${HOST_H}px;background:rgba(0,0,0,${a})"></div>`,
)
.join("");
}
/** Four strips of constant alpha (opaque) with luma 0, 1/3, 2/3, 1 — isolates the Luma/Luma Inverted modes from Alpha. */
function lumaMatteStrips(): string {
return [0, 85, 170, 255]
.map(
(g, i) =>
`<div style="position:absolute;left:${i * 40}px;top:0;width:40px;height:${HOST_H}px;background:rgb(${g},${g},${g})"></div>`,
)
.join("");
}
interface OutSample {
width: number;
height: number;
/** RGBA at a few probe points. */
left: number[];
right: number[];
/** Every `[start, end)` run of red pixels in each requested row. */
rows: [number, number][][];
/** Alpha left behind in the capture canvas after the upload. */
srcAlpha: number[];
}
describe("data-vfx-chain in the browser", () => {
let browser: Browser;
let runtime: string;
beforeAll(async () => {
runtime = readFileSync(RUNTIME_PATH, "utf8");
browser = await puppeteer.launch({
headless: true,
args: ["--no-sandbox", "--disable-setuid-sandbox", "--enable-features=CanvasDrawElement"],
});
const probe = await browser.newPage();
const caps = await probe.evaluate(() => ({
drawElementImage: typeof (
document.createElement("canvas").getContext("2d") as CanvasRenderingContext2D & {
drawElementImage?: unknown;
}
)?.drawElementImage,
webgl2: !!document.createElement("canvas").getContext("webgl2"),
}));
await probe.close();
// A missing capability makes every assertion below meaningless, so fail
// here — naming the build that was actually launched — rather than on a
// pixel compare thirty lines down.
expect({ ...caps, version: await browser.version() }).toMatchObject({
drawElementImage: "function",
webgl2: true,
});
}, 60_000);
afterAll(async () => {
await browser?.close();
});
/**
* Loud-error collector per page. A chain the runtime refused — the shape a
* stale `dist/hyperframe.runtime.iife.js` takes, since a kernel it has never
* heard of is an unknown effect type — otherwise surfaces as an unreadable
* `expected false to be true` two helpers away.
*/
const pageErrors = new Map<Page, string[]>();
function watchPage(page: Page): string[] {
const errors: string[] = [];
pageErrors.set(page, errors);
page.on("console", (message) => {
const text = message.text();
if (text.includes("[HyperFrames] composition script error:")) errors.push(text);
});
page.on("pageerror", (error) => errors.push(error.message));
return errors;
}
async function bootRuntime(
page: Page,
errors: string[],
registeredStyle?: string,
): Promise<void> {
// The wrapper registers with `registeredStyle` and gets its own back before any paint.
if (registeredStyle === undefined) await page.addScriptTag({ content: runtime });
else
await page.evaluate(
(src: string, style: string) => {
const inner = document.querySelector(".hf-vfx-in") as HTMLElement;
const own = inner.style.cssText;
inner.style.cssText = style;
const script = document.createElement("script");
script.textContent = src;
document.head.append(script);
inner.style.cssText = own;
},
runtime,
registeredStyle,
);
await page.waitForFunction(
() =>
(window as CompositeWindow).__playerReady === true &&
(window as CompositeWindow).__renderReady === true,
);
expect(errors).toEqual([]);
}
async function open(
html: string,
viewport = { width: 320, height: 240 },
registeredStyle?: string,
): Promise<Page> {
const page = await browser.newPage();
const errors = watchPage(page);
await page.setViewport({ ...viewport, deviceScaleFactor: 1 });
await page.setContent(html);
await bootRuntime(page, errors, registeredStyle);
return page;
}
/**
* `setContent` leaves the document on `about:blank`, where the loader's
* `fetch("<data-composition-src>")` cannot resolve — a mounted fixture needs
* a real origin, so both files are served from the interceptor.
*/
async function openMounted(files: Record<string, string>): Promise<Page> {
const page = await browser.newPage();
const errors = watchPage(page);
await page.setRequestInterception(true);
page.on("request", (request) => {
const name = new URL(request.url()).pathname.slice(1);
const body = files[name];
if (body === undefined) {
void request.continue();
return;
}
void request.respond({ status: 200, contentType: "text/html", body });
});
await page.setViewport({ width: 320, height: 240, deviceScaleFactor: 1 });
await page.goto("http://vfx.test/main.html", { waitUntil: "domcontentloaded" });
await bootRuntime(page, errors);
return page;
}
/**
* The engine's three-phase protocol, by hand: seek (which arms the pending
* flag), force a compositor paint with a 1×1 screenshot, then resolve.
*/
async function seekAndResolve(page: Page, t: number): Promise<boolean> {
const armed = await page.evaluate((time: number) => {
(window as CompositeWindow).__player!.renderSeek(time);
return (window as CompositeWindow).__hf_page_composite_pending === true;
}, t);
expect({ armed, errors: pageErrors.get(page) }).toEqual({ armed: true, errors: [] });
await page.screenshot({ clip: { x: 0, y: 0, width: 1, height: 1 } });
return page.evaluate(() => (window as CompositeWindow).__hf_page_composite_resolve!());
}
async function sample(page: Page, rows: number[]): Promise<OutSample> {
return page.evaluate((rowList: number[]) => {
const out = document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement;
const gl = out.getContext("webgl2")!;
const buf = new Uint8Array(out.width * out.height * 4);
gl.readPixels(0, 0, out.width, out.height, gl.RGBA, gl.UNSIGNED_BYTE, buf);
const at = (x: number, y: number): number[] => {
const i = (y * out.width + x) * 4;
return [buf[i]!, buf[i + 1]!, buf[i + 2]!, buf[i + 3]!];
};
// Runs, not a width: a displacement can split the block in two, and a
// shift that runs one edge off the frame leaves the width unchanged.
const redRuns = (y: number): [number, number][] => {
const runs: [number, number][] = [];
let start = -1;
for (let x = 0; x <= out.width; x++) {
const red = x < out.width && buf[(y * out.width + x) * 4]! > 127;
if (red && start < 0) start = x;
if (!red && start >= 0) {
runs.push([start, x]);
start = -1;
}
}
return runs;
};
const src = document.querySelector("canvas.hf-vfx-src") as HTMLCanvasElement;
const sctx = src.getContext("2d")!;
return {
width: out.width,
height: out.height,
left: at(40, 60),
right: at(120, 60),
rows: rowList.map(redRuns),
srcAlpha: [
sctx.getImageData(40, 60, 1, 1).data[3]!,
sctx.getImageData(120, 60, 1, 1).data[3]!,
],
};
}, rows);
}
it("reproduces the captured layer exactly when the kernel is an identity", async () => {
const page = await open(fixture(waveWarpChain({ height: 0, width: 93.4 })));
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const s = await sample(page, [10, 60, 90]);
expect([s.width, s.height]).toEqual([HOST_W, HOST_H]);
expect(s.left).toEqual([255, 0, 0, 255]);
expect(s.right).toEqual([0, 0, 0, 0]);
expect(s.rows).toEqual([[[0, SQUARE_W]], [[0, SQUARE_W]], [[0, SQUARE_W]]]);
} finally {
await page.close();
}
}, 60_000);
const CLEAR = [0, 0, 0, 0];
// `pixel` null: the host has not started yet. The options override the wrapper's style at
// load and at registration, and the host's start.
it.each<
[
string,
[style: string, pixel: number[] | null][],
number,
{ load?: string; registered?: string; hostStart?: number }?,
]
>([
[
"grows from 0×0: it paints on the next frame, not empty for the rest",
[
["width:0px", CLEAR],
["", red],
],
1,
],
[
"is sized at registration but first painted at 0×0 (a GSAP fromTo): it paints once it grows",
[
["width:0px", CLEAR],
["", red],
],
1,
{ registered: "" },
],
[
"shrinks to 0×0: it paints empty, not the previous frame again",
[
["", red],
["width:0px", CLEAR],
],
1,
],
[
"is hidden at 0×0, then shown and sized: it paints on that frame",
[
["width:0px;visibility:hidden", CLEAR],
["", red],
],
0,
],
[
"is 0×0 under a host that starts later, then sized: it paints once the host shows",
[
["width:0px", null],
["", red],
],
0,
{ registered: "", hostStart: 0.02 },
],
[
"is 0×0 at load and sized before the first seek: it paints on that seek",
[["", red]],
0,
{ load: "width:0px" },
],
])(
"a layer that %s",
async (_case, frames, reports, { load = frames[0]![0], registered, hostStart } = {}) => {
const chain = waveWarpChain({ height: 0, width: 93.4 });
const page = await open(fixture(chain, load, hostStart), undefined, registered);
const reported: string[] = [];
try {
for (const [i, [innerStyle, pixel]] of frames.entries()) {
await page.evaluate((style: string) => {
(document.querySelector(".hf-vfx-in") as HTMLElement).style.cssText = style;
}, innerStyle);
if (pixel === null) {
const armed = await page.evaluate((t: number) => {
(window as CompositeWindow).__player!.renderSeek(t);
return (window as CompositeWindow).__hf_page_composite_pending === true;
}, i / 30);
expect(armed).toBe(false);
continue;
}
expect(await seekAndResolve(page, i / 30)).toBe(true);
expect((await sample(page, [60])).left).toEqual(pixel);
reported.push(...pageErrors.get(page)!.splice(0));
}
expect(reported).toEqual(Array(reports).fill(expect.stringContaining("vfx-frame:")));
} finally {
await page.close();
}
},
60_000,
);
/**
* `hyperframes snapshot` (and `check`/`compare`/`validate`/`layout`, and
* Studio's thumbnail capture) seek through the same `renderSeek` the engine
* does, but never read
* `__hf_page_composite_pending` and never call `__hf_page_composite_resolve`
* — so arming the protocol alone left every `self` chain unpainted and
* silent there. No `page.screenshot` in this case ON PURPOSE: a screenshot
* is the engine's phase-2 paint force, and taking one would test the engine
* protocol again by the back door instead of the runtime's own fallback.
*/
it("paints a self-capture host when nobody ever resolves the composite", async () => {
const page = await open(fixture(waveWarpChain({ height: 0, width: 93.4 })));
try {
const armed = await page.evaluate(() => {
(window as CompositeWindow).__player!.renderSeek(0);
return (window as CompositeWindow).__hf_page_composite_pending === true;
});
expect({ armed, errors: pageErrors.get(page) }).toEqual({ armed: true, errors: [] });
await page.waitForFunction(
() => {
const out = document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement;
const gl = out.getContext("webgl2");
if (!gl) return false;
const px = new Uint8Array(4);
gl.readPixels(40, 60, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, px);
return px[3] === 255;
},
{ timeout: 5_000 },
);
const s = await sample(page, [10, 60, 90]);
expect([s.width, s.height]).toEqual([HOST_W, HOST_H]);
expect(s.left).toEqual([255, 0, 0, 255]);
expect(s.right).toEqual([0, 0, 0, 0]);
expect(s.rows).toEqual([[[0, SQUARE_W]], [[0, SQUARE_W]], [[0, SQUARE_W]]]);
// The engine contract is untouched: the flag stays armed, so a host that
// DOES run the three-phase protocol still gets its authoritative capture.
expect(
await page.evaluate(() => (window as CompositeWindow).__hf_page_composite_pending),
).toBe(true);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
/**
* The same snapshot-family path, but joined rather than raced. Every
* `hyperframes` seek caller (`snapshot`/`check`/`compare`/`validate`/
* `layout`) drains `__hfWaitForSeekCompletion` and then allows exactly one
* settle race before screenshotting. The preview-side capture used to be
* fire-and-forget AND sequential per host, so N hosts cost up to 2N frames
* while the settle bought about two — the screenshot landed on hosts that
* had not painted yet, and which ones varied run to run.
*
* Two hosts, so one host finishing in time cannot hide the defect. No
* `page.screenshot` before the read: that is the engine's phase-2 paint
* force, and taking one would test the engine protocol by the back door.
*/
it("has every self-capture host painted the moment the CLI's seek barrier returns", async () => {
const page = await open(twoHostFixture(waveWarpChain({ height: 0, width: 93.4 })), {
width: HOST_W * 2 + GAP,
height: HOST_H + GAP,
});
try {
expect(await page.evaluate(() => document.querySelectorAll("[data-vfx-chain]").length)).toBe(
2,
);
await seekAndDrainBarrier(page, 0);
// Read immediately — no waitForFunction, no extra rAF. Measured on the
// pre-fix bundle this is `[[0,0,0,0],[0,0,0,0]]`: the barrier returned
// with neither host painted, and only the settle race that follows
// happened to cover them. That slack is not a guarantee — it is two
// frames against a cost that grows with host count — so the contract is
// pinned here, where the barrier's promise is the only thing holding.
const atBarrier = await sampleEveryOut(page);
await settleRace(page);
const atScreenshot = await sampleEveryOut(page);
expect({ atBarrier, atScreenshot, errors: pageErrors.get(page) }).toEqual({
atBarrier: [red, red],
atScreenshot: [red, red],
errors: [],
});
} finally {
await page.close();
}
}, 60_000);
it("captures a .hf-vfx-in that is a sub-composition mount", async () => {
const page = await openMounted({
"main.html": mountFixture(waveWarpChain({ height: 0, width: 93.4 })),
"inner.html": MOUNT_INNER,
});
try {
// The mount replaces .hf-vfx-in's children, so the exporter's
// preceding-effect content goes with them — and a silent 404 would leave
// the wrapper empty, which looks exactly like the defect under test.
expect(
await page.evaluate(() => {
const inner = document.querySelector(".hf-vfx-in")!;
return {
mounted: inner.querySelectorAll("#inner-square").length,
preMountContentKept: !!document.getElementById("pre-mount"),
};
}),
).toEqual({ mounted: 1, preMountContentKept: false });
expect(await seekAndResolve(page, 0)).toBe(true);
const s = await sample(page, [10, 60, 90]);
expect([s.width, s.height]).toEqual([HOST_W, HOST_H]);
expect(s.left).toEqual([255, 0, 0, 255]);
expect(s.rows).toEqual([[[0, SQUARE_W]], [[0, SQUARE_W]], [[0, SQUARE_W]]]);
} finally {
await page.close();
}
}, 60_000);
it("registers a vfx host that arrives inside a mounted sub-composition", async () => {
const page = await openMounted({
"main.html": NESTED_HOST_MAIN,
"inner.html": NESTED_HOST_INNER(waveWarpChain({ height: 0, width: 93.4 })),
});
try {
expect(await page.evaluate(() => document.querySelectorAll("[data-vfx-chain]").length)).toBe(
1,
);
expect(await seekAndResolve(page, 0)).toBe(true);
const s = await sample(page, [10, 60, 90]);
expect([s.width, s.height]).toEqual([HOST_W, HOST_H]);
expect(s.left).toEqual([255, 0, 0, 255]);
} finally {
await page.close();
}
}, 60_000);
it("clears the capture canvas so the unprocessed layer cannot show through", async () => {
const page = await open(fixture(waveWarpChain({ height: 0, width: 93.4 })));
try {
await seekAndResolve(page, 0);
const s = await sample(page, []);
// The layoutsubtree canvas's CHILDREN are not painted by the page
// compositor, but its bitmap is — and that bitmap is where the capture
// landed. Every transparent pixel of .hf-vfx-out would otherwise reveal
// the unwarped original underneath it.
expect(s.srcAlpha).toEqual([0, 0]);
} finally {
await page.close();
}
}, 60_000);
it("shifts each row by the analytic wave displacement", async () => {
const params = {
waveType: 1,
direction: 0,
speed: 0,
pinning: 1,
phase: 0,
height: 20,
width: 93.4,
};
const page = await open(fixture(waveWarpChain(params)));
try {
await seekAndResolve(page, 0);
const rows = [30, 90];
const s = await sample(page, rows);
for (const [i, y] of rows.entries()) {
// out(x, y) samples the source at x + disp, so the block's edges move
// by −disp, and anything displaced off the source is transparent.
const disp = waveWarpSampleRef({ x: 0, y }, 0, params).x;
expect(Math.abs(disp)).toBeGreaterThan(1);
expect(s.rows[i]).toHaveLength(1);
const [first, end] = s.rows[i]![0]!;
expect(first).toBeCloseTo(Math.max(0, -disp), -0.5);
expect(end).toBeCloseTo(Math.min(HOST_W, SQUARE_W - disp), -0.5);
}
} finally {
await page.close();
}
}, 60_000);
it("displaces by its own pixels when the map layer is the layer itself", async () => {
// Use For Horizontal = Red, maxH = 20, maxV = 0. The block is opaque red
// (red = 1 ⇒ +20 px) and everything right of it is transparent
// (red = 0 ⇒ −20 px), so the output reads the source from two different
// directions and the block comes back split:
// x < 80 reads x + 20 ⇒ red while x < 60
// x ≥ 80 reads x − 20 ⇒ red while x < 100
const params = { useH: 1, useV: 2, maxH: 20, maxV: 0, behavior: 1, edge: 0, expand: true };
const page = await open(fixture(chainOf("displacement-map", params)));
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const s = await sample(page, [30, 90]);
const opaqueRed = { r: 1, g: 0, b: 0, a: 1 };
const transparent = { r: 0, g: 0, b: 0, a: 0 };
const shiftInside = displacementMapSampleRef({ x: 0, y: 0 }, 0, params, () => opaqueRed).x;
const shiftOutside = displacementMapSampleRef({ x: 0, y: 0 }, 0, params, () => transparent).x;
expect([shiftInside, shiftOutside]).toEqual([20, -20]);
for (const runs of s.rows) {
expect(runs).toEqual([
[0, SQUARE_W - shiftInside],
[SQUARE_W, SQUARE_W - shiftOutside],
]);
}
} finally {
await page.close();
}
}, 60_000);
/**
* Decode the page's own screenshot back inside the page and compare the two
* panels. Keeping the compare in the browser avoids a PNG decoder in Node
* and guarantees both panels went through one compositor pass.
*/
async function panelPsnr(page: Page): Promise<{ mse: number; psnr: number; aCentre: number[] }> {
const shot = await page.screenshot({ encoding: "base64" });
const raw = await page.evaluate(
async (base64: string, panel: typeof PANEL) => {
const img = new Image();
img.src = `data:image/png;base64,${base64}`;
await img.decode();
const scratch = document.createElement("canvas");
scratch.width = img.width;
scratch.height = img.height;
const ctx = scratch.getContext("2d")!;
ctx.drawImage(img, 0, 0);
const a = ctx.getImageData(panel.ax, panel.y, panel.w, panel.h).data;
const b = ctx.getImageData(panel.bx, panel.y, panel.w, panel.h).data;
let se = 0;
let n = 0;
for (let i = 0; i < a.length; i += 4) {
for (let c = 0; c < 3; c++) {
const d = a[i + c]! - b[i + c]!;
se += d * d;
n += 1;
}
}
const centre = ((panel.h >> 1) * panel.w + 20) * 4;
// `Infinity` does not survive the CDP round trip, so the MSE crosses
// and the decibels are computed on this side.
return { mse: se / n, aCentre: [a[centre]!, a[centre + 1]!, a[centre + 2]!] };
},
shot,
PANEL,
);
return {
...raw,
psnr: raw.mse === 0 ? Number.POSITIVE_INFINITY : 10 * Math.log10((255 * 255) / raw.mse),
};
}
it("captures the filters that precede the node and leaves the ones that follow outside", async () => {
const page = await open(chainOrderFixture(waveWarpChain({ height: 0, width: 93.4 })), {
width: PANEL.bx + PANEL.w + PANEL.ax,
height: PANEL.y + PANEL.h + PANEL.y,
});
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const { psnr, aCentre } = await panelPsnr(page);
// The tint runs INSIDE the capture, so the block reaches the kernel green
// rather than red — proof that drawElementImage paints the subtree's own
// filter rather than its unfiltered source.
expect(aCentre[0]).toBeLessThan(64);
expect(aCentre[1]).toBeGreaterThan(160);
// ...and the host's blur runs OUTSIDE, on the canvas the kernel wrote.
expect(psnr).toBeGreaterThanOrEqual(40);
} finally {
await page.close();
}
}, 60_000);
it("paints byte-identical fractal-noise output for the same seek time (determinism)", async () => {
const page = await open(noiseFixture(chainOf("fractal-noise", NOISE_PARAMS)));
try {
await renderSeekOnly(page, 1.25);
const first = await page.evaluate(() =>
(document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement).toDataURL(),
);
// Seek away, then back to the same time — the paint must not carry any
// state between calls (the determinism contract's "no state carried
// between paints" clause).
await renderSeekOnly(page, 0.5);
await renderSeekOnly(page, 1.25);
const second = await page.evaluate(() =>
(document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement).toDataURL(),
);
expect(second).toBe(first);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
it("matches the CPU reference within the cross-backend PSNR bar for fractal-noise", async () => {
const page = await open(noiseFixture(chainOf("fractal-noise", NOISE_PARAMS)));
try {
const frames = [0, 0.5, 1.25, 2.0];
// 8 points spread across the 160x120 canvas.
const samplePoints: [number, number][] = [
[10, 10],
[40, 30],
[80, 60],
[120, 90],
[20, 100],
[150, 5],
[60, 60],
[100, 20],
];
let se = 0;
let n = 0;
for (const t of frames) {
await renderSeekOnly(page, t);
const buf = await readNoiseBuffer(page);
for (const [x, y] of samplePoints) {
// Device pixels, y measured from the bottom — readPixels' row order
// and the shader's v_uv y-up agree, and refs/fractalNoise.ts is
// documented against exactly that convention.
const i = (y * buf.width + x) * 4;
const measured = buf.data[i]!;
const expected = Math.round(
fractalNoiseRef({ x: x + 0.5, y: y + 0.5 }, t, NOISE_PARAMS) * 255,
);
const d = measured - expected;
se += d * d;
n += 1;
}
}
const mse = se / n;
const psnr = mse === 0 ? Number.POSITIVE_INFINITY : 10 * Math.log10((255 * 255) / mse);
expect(psnr).toBeGreaterThanOrEqual(32);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
/**
* RGBA at arbitrary points of `canvas.hf-vfx-out`, via `readPixels`. Safe
* for content that varies only along x (a vertical readback flip cannot
* change what column a pixel is in) — `screenshotPixels` below is used
* instead wherever a fixture varies along y.
*/
async function sampleOutPoints(page: Page, points: [number, number][]): Promise<number[][]> {
return page.evaluate((pts: [number, number][]) => {
const out = document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement;
const gl = out.getContext("webgl2")!;
const buf = new Uint8Array(out.width * out.height * 4);
gl.readPixels(0, 0, out.width, out.height, gl.RGBA, gl.UNSIGNED_BYTE, buf);
return pts.map(([x, y]) => {
const i = (y * out.width + x) * 4;
return [buf[i]!, buf[i + 1]!, buf[i + 2]!, buf[i + 3]!];
});
}, points);
}
/**
* RGBA at arbitrary points of the page's own screenshot, decoded back
* inside the page (same technique as `panelPsnr`). Used wherever a fixture
* varies along y, so the WebGL readback's vertical flip cannot bite —
* the browser's own compositor produced this pixel, top-down, the way the
* page actually looks.
*/
async function screenshotPixels(page: Page, points: [number, number][]): Promise<number[][]> {
const shot = await page.screenshot({ encoding: "base64" });
return page.evaluate(
async (base64: string, pts: [number, number][]) => {
const img = new Image();
img.src = `data:image/png;base64,${base64}`;
await img.decode();
const scratch = document.createElement("canvas");
scratch.width = img.width;
scratch.height = img.height;
const ctx = scratch.getContext("2d")!;
ctx.drawImage(img, 0, 0);
return pts.map(([x, y]) => Array.from(ctx.getImageData(x, y, 1, 1).data));
},
shot,
points,
);
}
describe("backdrop capture (Task 2.6)", () => {
it("composites an identity backdrop kernel back over the two stacked blocks below it", async () => {
const chain = chainOf("noise", { amount: 0 });
const page = await open(backdropStackedFixture(chain), {
width: PANEL.bx + PANEL.w + PANEL.ax,
height: PANEL.y + PANEL.h + PANEL.y,
});
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const [top, bottom] = await screenshotPixels(page, [
[PANEL.ax + 80, PANEL.y + 30],
[PANEL.ax + 80, PANEL.y + 90],
]);
expect(top!.slice(0, 3)).toEqual([255, 0, 0]);
expect(bottom!.slice(0, 3)).toEqual([0, 255, 0]);
const { psnr } = await panelPsnr(page);
expect(psnr).toBeGreaterThanOrEqual(40);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
it("keeps a hidden backdrop host's captured layers on the wrapper canvas's own bitmap", async () => {
const page = await open(hiddenBackdropFixture(chainOf("noise", { amount: 0 })), {
width: 240,
height: 180,
});
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const pixels = await page.evaluate(() => {
const wrap = document.querySelector("canvas.hf-vfx-src") as HTMLCanvasElement;
const ctx = wrap.getContext("2d")!;
return {
top: Array.from(ctx.getImageData(40, 10, 1, 1).data),
bottom: Array.from(ctx.getImageData(40, 90, 1, 1).data),
};
});
expect(pixels.top).toEqual([255, 0, 0, 255]);
expect(pixels.bottom).toEqual([0, 255, 0, 255]);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
});
describe("luma-matte (Task 2.7)", () => {
const points: [number, number][] = [
[20, 60],
[60, 60],
[100, 60],
[140, 60],
];
const ALPHA_TOLERANCE = 4;
it.each([
[1, [0, 85, 170, 255]],
[2, [255, 170, 85, 0]],
] as const)(
"mode %i (Alpha/Alpha Inverted) follows the matte's alpha",
async (mode, expected) => {
const chain = chainOf("luma-matte", { matte: "matte", mode });
const page = await open(lumaMatteFixture(chain, alphaMatteStrips()), {
width: HOST_W,
height: 320,
});
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const samples = await sampleOutPoints(page, points);
samples.forEach((px, i) => {
expect(Math.abs(px[3]! - expected[i]!)).toBeLessThanOrEqual(ALPHA_TOLERANCE);
});
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
},
60_000,
);
it.each([
[3, [0, 85, 170, 255]],
[4, [255, 170, 85, 0]],
] as const)(
"mode %i (Luma/Luma Inverted) follows the matte's luma",
async (mode, expected) => {
const chain = chainOf("luma-matte", { matte: "matte", mode });
const page = await open(lumaMatteFixture(chain, lumaMatteStrips()), {
width: HOST_W,
height: 320,
});
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const samples = await sampleOutPoints(page, points);
samples.forEach((px, i) => {
expect(Math.abs(px[3]! - expected[i]!)).toBeLessThanOrEqual(ALPHA_TOLERANCE);
});
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
},
60_000,
);
});
describe("noise (Task 2.7)", () => {
it("leaves the source untouched when amount is 0", async () => {
const page = await open(fixture(chainOf("noise", { amount: 0 })));
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const s = await sample(page, [10, 60, 90]);
expect([s.width, s.height]).toEqual([HOST_W, HOST_H]);
expect(s.left).toEqual([255, 0, 0, 255]);
expect(s.right).toEqual([0, 0, 0, 0]);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
it("paints byte-identical output for the same seek time (determinism)", async () => {
const page = await open(fixture(chainOf("noise", { amount: 50 })));
try {
expect(await seekAndResolve(page, 1.25)).toBe(true);
const first = await page.evaluate(() =>
(document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement).toDataURL(),
);
// Seek away, then back to the same time — no state may carry between paints.
expect(await seekAndResolve(page, 0.5)).toBe(true);
expect(await seekAndResolve(page, 1.25)).toBe(true);
const second = await page.evaluate(() =>
(document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement).toDataURL(),
);
expect(second).toBe(first);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
it("changes the pattern when the seek time — its only seed — changes", async () => {
const page = await open(fixture(chainOf("noise", { amount: 50 })));
try {
expect(await seekAndResolve(page, 1.25)).toBe(true);
const a = await page.evaluate(() =>
(document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement).toDataURL(),
);
expect(await seekAndResolve(page, 2.0)).toBe(true);
const b = await page.evaluate(() =>
(document.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement).toDataURL(),
);
expect(b).not.toBe(a);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
it("matches refs/noise.ts's hash byte-for-byte at several pixels", async () => {
// The three checks above (identity at amount 0, same-time determinism,
// different-time difference) hold for almost any hash function — none
// of them can tell a correct Jenkins-mix port from a subtly wrong one
// (see PR #4330's review). This pins actual measured bytes against
// refs/noise.ts, the same CPU reference fractal-noise's pixel test
// above compares against.
//
// Known, checked limitation: the seed is `floor(t * fps + 0.5)`, and
// this fixture's reachable t is bounded by data-duration="4" at this
// composition's ~30 fps, so the seed here is 0 — small enough that a
// mutation to `hfJenkinsMix`'s FIRST line (`a ^= (c >> 13u)`, which
// touches only the raw incoming seed, before anything has mixed it into
// a wrapped, effectively-random register) would not move any pixel
// this test reads: `seed >> 13` and `seed >> 14` are both 0 for any
// seed under 2^13, which every reachable (x, y, seed) in this fixture
// is. Confirmed by brute force over the full reachable input space
// (x<80, y<120, seed<=120): the review's own 13->14 mutation changes
// ZERO of the 1,161,600 possible outputs there. Every OTHER line of the
// mix — all 8 of them — differs on the very first input tried under
// the same one-bit-shift mutation, so this test is a real hash-pinning
// guard for 8 of the mix's 9 steps, not a restatement of the three
// invariant checks above.
const AMOUNT = 100;
const page = await open(fixture(chainOf("noise", { amount: AMOUNT })));
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const buf = await readNoiseBuffer(page);
// [x, readback row (bottom-origin, as gl.readPixels indexes), R byte].
// Computed offline from noiseOffsetRef with the SAME flip the shader
// applies (its own y is top-origin, After Effects' convention; a
// readback row is bottom-origin/y-up, so topY = HOST_H - 1 - row) —
// see the flip line in noise.frag.ts and the doc comment on
// refs/noise.ts's noiseOffsetRef. Verified against a live measurement
// (not just derived): swapping the flip direction reproduces a
// DIFFERENT, also-internally-consistent set of values, so getting it
// backwards silently passes against the wrong ground truth — this
// set was checked against the actual runtime output, not only
// against its own formula. All points sit inside the opaque red
// square (x < 80) and well clear of the 0/255 clip bounds, so 8-bit
// rounding cannot mask a wrong hash.
const points: [x: number, row: number, expectedR: number][] = [
[4, 10, 160],
[5, 10, 192],
[6, 10, 135],
[0, 60, 162],
[2, 60, 145],
[4, 60, 200],
[0, 90, 142],
[1, 90, 201],
[3, 90, 182],
];
for (const [x, row, expectedR] of points) {
const i = (row * buf.width + x) * 4;
// ±1 for GPU-vs-JS float rounding at the 8-bit conversion, not for
// hash tolerance: a mutated shift on any of the 8 reachable steps
// moves these by tens of levels, verified by brute force above.
expect(Math.abs(buf.data[i]! - expectedR)).toBeLessThanOrEqual(1);
}
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
});
/**
* The `map` ref (plan Backlog, "one-line def change after Task 2.6"). The
* discriminator is that a SELF map gives a visibly different picture: a
* black external map displaces every pixel by the same −maxH, translating
* the block right as one run, while the layer's own pixels displace the red
* half one way and the transparent half the other, splitting it in two.
*/
describe("displacement-map with an external map (Task 2.6 backlog)", () => {
const MAX_H = 20;
const mapParams = { useH: 1, maxH: MAX_H, useV: 11, maxV: 0, behavior: 1, edge: 0 };
const BLACK = { r: 0, g: 0, b: 0, a: 1 };
it("reads a named map element as u_src2", async () => {
const chain = chainOf("displacement-map", { ...mapParams, map: "map" });
const page = await open(displacementRefFixture(chain), { width: HOST_W, height: 320 });
try {
expect(await seekAndResolve(page, 0)).toBe(true);
// Through the CPU reference, with the constant sampler the fixture
// paints: an opaque black map reads 0 on Red, so d = (0 − 0.5)·2·maxH.
const probe = { x: 40, y: 60 };
const shift = probe.x - displacementMapSampleRef(probe, 0, mapParams, () => BLACK).x;
expect(shift).toBe(MAX_H);
const s = await sample(page, [60]);
expect(s.rows).toEqual([[[shift, SQUARE_W + shift]]]);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
it("displaces by the layer's own pixels when no map is named", async () => {
const chain = chainOf("displacement-map", mapParams);
const page = await open(displacementRefFixture(chain), { width: HOST_W, height: 320 });
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const s = await sample(page, [60]);
// Two runs, not one: the self-referential form is a different picture,
// which is what makes the case above a real check of the binding.
expect(s.rows[0]!.length).toBe(2);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
});
/**
* A ref source that also paints (retro-wave `Logo Anim` layer 5 is layer 4's
* displacement map AND an enabled, opaque layer). Both halves of the rule in
* one page: the wrapper keeps its bitmap, and the kernel still reads it
* scaled into the host's box even though the two boxes differ.
*/
describe("a visible ref source (data-vfx-ref-visible)", () => {
const MATTE_W = HOST_W * 2;
it("keeps the matte on screen and still mattes the host with it", async () => {
const chain = chainOf("luma-matte", { matte: "matte", mode: 1 });
const page = await open(visibleMatteFixture(chain, MATTE_W), {
width: MATTE_W,
height: 320,
});
try {
expect(await seekAndResolve(page, 0)).toBe(true);
// 1. The wrapper's own bitmap still holds the strips — an invisible
// ref would have been cleared to nothing after its upload.
const bitmap = await page.evaluate((w: number) => {
const canvas = document.querySelector("#matte canvas.hf-vfx-src") as HTMLCanvasElement;
const ctx = canvas.getContext("2d")!;
const at = (x: number): number => ctx.getImageData(x, 60, 1, 1).data[3]!;
return { width: canvas.width, alphas: [at(w / 8), at((w * 7) / 8)] };
}, MATTE_W);
expect(bitmap.width).toBe(MATTE_W);
expect(bitmap.alphas[0]).toBe(0);
expect(bitmap.alphas[1]).toBe(255);
// 2. And the kernel read it across the host's box, not 1:1 — the four
// strips of a 320px matte land as four 40px bands in a 160px host.
const samples = await sampleOutPoints(page, [
[20, 60],
[60, 60],
[100, 60],
[140, 60],
]);
[0, 85, 170, 255].forEach((expected, i) => {
expect(Math.abs(samples[i]![3]! - expected)).toBeLessThanOrEqual(4);
});
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
it("clears an ordinary ref's bitmap, so an invisible matte stays invisible", async () => {
const chain = chainOf("luma-matte", { matte: "matte", mode: 1 });
const page = await open(lumaMatteFixture(chain, alphaMatteStrips()), {
width: HOST_W,
height: 320,
});
try {
expect(await seekAndResolve(page, 0)).toBe(true);
const alphas = await page.evaluate(() => {
const canvas = document.querySelector("#matte canvas.hf-vfx-src") as HTMLCanvasElement;
const ctx = canvas.getContext("2d")!;
return [40, 140].map((x) => ctx.getImageData(x, 60, 1, 1).data[3]!);
});
expect(alphas).toEqual([0, 0]);
expect(pageErrors.get(page)).toEqual([]);
} finally {
await page.close();
}
}, 60_000);
});
});