Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { describe, expect, it } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import path, { join } from "node:path";
import { tmpdir } from "node:os";
import {
closeFileServerSafely,
createFileServer,
RENDER_CAPTURE_MODE_SHIM,
HF_BRIDGE_SCRIPT,
HF_EARLY_STUB,
injectScriptsAtHeadStart,
isPathInside,
parseRangeHeader,
VIRTUAL_TIME_SHIM,
} from "./fileServer.js";
function captureLogger() {
const warnings: { message: string; meta?: Record<string, unknown> }[] = [];
return {
warnings,
log: {
error() {},
warn(message: string, meta?: Record<string, unknown>) {
warnings.push({ message, meta });
},
info() {},
debug() {},
},
};
}
describe("closeFileServerSafely", () => {
it("swallows and logs a throwing close instead of propagating", () => {
const { log, warnings } = captureLogger();
const fileServer = {
close: () => {
// http.Server.close() throws ERR_SERVER_NOT_RUNNING on a second close.
throw new Error("Server is not running.");
},
};
expect(() => closeFileServerSafely(fileServer, "plan", log)).not.toThrow();
expect(warnings).toHaveLength(1);
expect(warnings[0].message).toContain("[plan]");
expect(warnings[0].meta?.error).toBe("Server is not running.");
});
it("closes once and stays quiet on the happy path", () => {
const { log, warnings } = captureLogger();
let closed = 0;
closeFileServerSafely({ close: () => closed++ }, "renderChunk", log);
expect(closed).toBe(1);
expect(warnings).toHaveLength(0);
});
});
async function withFileServer(
projectDir: string,
run: (server: Awaited<ReturnType<typeof createFileServer>>) => Promise<void>,
): Promise<void> {
const server = await createFileServer({
projectDir,
preHeadScripts: [],
headScripts: [],
bodyScripts: [],
});
try {
await run(server);
} finally {
server.close();
}
}
function writeEmptyIndex(projectDir: string): void {
writeFileSync(join(projectDir, "index.html"), "<!doctype html><html></html>");
}
async function expectTextResponse(
url: string,
options: { contentType?: string; bodyIncludes: string },
): Promise<void> {
const response = await fetch(url);
expect(response.status).toBe(200);
if (options.contentType) {
expect(response.headers.get("content-type")).toContain(options.contentType);
}
expect(await response.text()).toContain(options.bodyIncludes);
}
describe("injectScriptsIntoHtml", () => {
it("injects the virtual time shim into head content before authored scripts", () => {
const html = `<!DOCTYPE html>
<html>
<head><script>window.__order = ["authored-head"];</script></head>
<body><script>window.__order.push("authored-body");</script></body>
</html>`;
const injected = injectScriptsAtHeadStart(html, [VIRTUAL_TIME_SHIM]);
const injectedShimTag = `<script>${VIRTUAL_TIME_SHIM}\n//# sourceURL=hyperframes://injected/0</script>`;
const authoredHeadTag = `<script>window.__order = ["authored-head"];</script>`;
expect(injected.indexOf(injectedShimTag)).toBeGreaterThanOrEqual(0);
expect(injected.indexOf(injectedShimTag)).toBeLessThan(injected.indexOf(authoredHeadTag));
});
it("supports iframe html by injecting pre-head scripts without body scripts", () => {
const html =
"<!DOCTYPE html><html><head></head><body><script>window.targetLoaded = true;</script></body></html>";
const preInjected = injectScriptsAtHeadStart(html, [VIRTUAL_TIME_SHIM]);
const final = preInjected;
expect(final).toContain(VIRTUAL_TIME_SHIM);
expect(final).not.toContain("bodyOnly = true");
});
it("propagates virtual time seeks into same-origin iframe documents", () => {
expect(HF_BRIDGE_SCRIPT).toContain("function seekSameOriginChildFrames");
expect(HF_BRIDGE_SCRIPT).toContain("childWindow.__HF_VIRTUAL_TIME__.seekToTime(nextTimeMs)");
expect(HF_BRIDGE_SCRIPT).toContain("seekSameOriginChildFrames(window, nextTimeMs)");
});
});
describe("isPathInside", () => {
it("returns true when the child equals the parent", () => {
expect(isPathInside("/tmp/project", "/tmp/project")).toBe(true);
});
it("returns true for direct children", () => {
expect(isPathInside("/tmp/project/index.html", "/tmp/project")).toBe(true);
});
it("returns true for deeply nested descendants", () => {
expect(isPathInside("/tmp/project/a/b/c/file.html", "/tmp/project")).toBe(true);
});
it("rejects siblings with a shared name prefix", () => {
// The classic prefix-bug: "/foo" should NOT contain "/foobar/x". A naive
// startsWith check without a trailing separator would incorrectly accept
// this as nested.
expect(isPathInside("/tmp/projectile/a", "/tmp/project")).toBe(false);
expect(isPathInside("/tmp/project-other/a", "/tmp/project")).toBe(false);
});
it("rejects paths outside the parent entirely", () => {
expect(isPathInside("/etc/passwd", "/tmp/project")).toBe(false);
expect(isPathInside("/tmp/other/file.html", "/tmp/project")).toBe(false);
});
it("rejects path-traversal attempts that escape the parent", () => {
// path.join("/tmp/project", "../etc/passwd") normalizes to "/tmp/etc/passwd"
// — outside the project root. The whole point of isPathInside is to catch
// exactly this after the join.
expect(isPathInside("/tmp/etc/passwd", "/tmp/project")).toBe(false);
expect(isPathInside("/tmp/project/../etc/passwd", "/tmp/project")).toBe(false);
});
it("accepts traversal that resolves back inside the parent", () => {
expect(isPathInside("/tmp/project/sub/../index.html", "/tmp/project")).toBe(true);
});
it("treats parents with and without trailing slashes the same", () => {
expect(isPathInside("/tmp/project/index.html", "/tmp/project/")).toBe(true);
expect(isPathInside("/tmp/project/index.html", "/tmp/project")).toBe(true);
});
it("resolves relative paths against the current working directory", () => {
// Both sides resolve against cwd, so a relative file under a relative dir
// should be considered nested. We don't assert the absolute path; we just
// check the containment relationship holds after resolution.
expect(isPathInside("a/b/c.html", "a/b")).toBe(true);
expect(isPathInside("a/b/../../c.html", "a/b")).toBe(false);
});
it("rejects symlink escapes when realpath enforcement is enabled", () => {
const rootDir = mkdtempSync(join(tmpdir(), "hf-file-server-root-"));
const outsideDir = mkdtempSync(join(tmpdir(), "hf-file-server-outside-"));
const outsideFile = join(outsideDir, "secret.txt");
const symlinkPath = join(rootDir, "escaped.txt");
try {
writeFileSync(outsideFile, "secret");
symlinkSync(outsideFile, symlinkPath);
expect(isPathInside(symlinkPath, rootDir)).toBe(true);
expect(isPathInside(symlinkPath, rootDir, { resolveSymlinks: true })).toBe(false);
} finally {
rmSync(rootDir, { recursive: true, force: true });
rmSync(outsideDir, { recursive: true, force: true });
}
});
describe("with path.win32 (cross-platform pinning tests)", () => {
// Pin Windows-path semantics on Linux/macOS CI by injecting the win32
// path module. Without this, accidental Unix-only assumptions (e.g. only
// splitting on "/") would silently regress for Windows users.
const win32 = { pathModule: path.win32 };
it("returns true when the child equals the parent", () => {
expect(isPathInside("C:\\foo", "C:\\foo", win32)).toBe(true);
});
it("returns true for direct children", () => {
expect(isPathInside("C:\\foo\\bar", "C:\\foo", win32)).toBe(true);
});
it("returns true for deeply nested descendants", () => {
expect(isPathInside("C:\\foo\\a\\b\\c.html", "C:\\foo", win32)).toBe(true);
});
it("rejects siblings with a shared name prefix", () => {
expect(isPathInside("C:\\foobar\\x", "C:\\foo", win32)).toBe(false);
expect(isPathInside("C:\\foo-other\\x", "C:\\foo", win32)).toBe(false);
});
it("rejects path-traversal attempts that escape the parent", () => {
expect(isPathInside("C:\\foo\\..\\etc\\passwd", "C:\\foo", win32)).toBe(false);
});
it("treats parents with and without trailing backslashes the same", () => {
expect(isPathInside("C:\\foo\\bar", "C:\\foo\\", win32)).toBe(true);
expect(isPathInside("C:\\foo\\bar", "C:\\foo", win32)).toBe(true);
});
it("rejects paths on a different drive letter", () => {
expect(isPathInside("D:\\foo\\bar", "C:\\foo", win32)).toBe(false);
});
});
});
describe("parseRangeHeader", () => {
const SIZE = 1000;
it("returns absent when there is no Range header", () => {
expect(parseRangeHeader(undefined, SIZE)).toEqual({ kind: "absent" });
expect(parseRangeHeader(null, SIZE)).toEqual({ kind: "absent" });
expect(parseRangeHeader("", SIZE)).toEqual({ kind: "absent" });
});
it("parses a closed range bytes=START-END", () => {
expect(parseRangeHeader("bytes=0-99", SIZE)).toEqual({
kind: "satisfiable",
start: 0,
end: 99,
});
expect(parseRangeHeader("bytes=100-199", SIZE)).toEqual({
kind: "satisfiable",
start: 100,
end: 199,
});
});
it("parses an open-ended range bytes=START- as start..EOF", () => {
expect(parseRangeHeader("bytes=100-", SIZE)).toEqual({
kind: "satisfiable",
start: 100,
end: SIZE - 1,
});
expect(parseRangeHeader("bytes=0-", SIZE)).toEqual({
kind: "satisfiable",
start: 0,
end: SIZE - 1,
});
});
it("parses a suffix range bytes=-N as the last N bytes", () => {
expect(parseRangeHeader("bytes=-50", SIZE)).toEqual({
kind: "satisfiable",
start: SIZE - 50,
end: SIZE - 1,
});
// Suffix larger than the file: clamp to the whole file.
expect(parseRangeHeader("bytes=-5000", SIZE)).toEqual({
kind: "satisfiable",
start: 0,
end: SIZE - 1,
});
});
it("clamps the end of a closed range to the last valid byte", () => {
// bytes=900-9999 on a 1000-byte file -> serve 900..999.
expect(parseRangeHeader("bytes=900-9999", SIZE)).toEqual({
kind: "satisfiable",
start: 900,
end: SIZE - 1,
});
});
it("returns unsatisfiable when start >= size", () => {
expect(parseRangeHeader("bytes=1000-2000", SIZE)).toEqual({ kind: "unsatisfiable" });
expect(parseRangeHeader("bytes=2000-", SIZE)).toEqual({ kind: "unsatisfiable" });
});
it("returns unsatisfiable when end < start in a closed range", () => {
expect(parseRangeHeader("bytes=200-100", SIZE)).toEqual({ kind: "unsatisfiable" });
});
it("returns unsatisfiable for a suffix request on a zero-byte file", () => {
expect(parseRangeHeader("bytes=-10", 0)).toEqual({ kind: "unsatisfiable" });
});
it("returns absent for non-bytes units, multi-range, and malformed inputs", () => {
expect(parseRangeHeader("items=0-1", SIZE)).toEqual({ kind: "absent" });
expect(parseRangeHeader("bytes=0-99,200-299", SIZE)).toEqual({ kind: "absent" });
expect(parseRangeHeader("bytes=abc-def", SIZE)).toEqual({ kind: "absent" });
expect(parseRangeHeader("bytes=", SIZE)).toEqual({ kind: "absent" });
expect(parseRangeHeader("bytes=-", SIZE)).toEqual({ kind: "absent" });
});
it("tolerates surrounding whitespace and case", () => {
expect(parseRangeHeader(" Bytes = 0-99 ", SIZE)).toEqual({
kind: "satisfiable",
start: 0,
end: 99,
});
});
});
describe("createFileServer", () => {
it.each([
["avif", "image/avif"],
["flac", "audio/flac"],
["M4A", "audio/mp4"],
["mov", "video/quicktime"],
["ico", "image/vnd.microsoft.icon"],
])("serves .%s media with its content type for full and range requests", async (ext, type) => {
const projectDir = mkdtempSync(join(tmpdir(), "hf-media-content-type-"));
const bytes = new Uint8Array([0, 255, 128, 64, 32]);
try {
writeFileSync(join(projectDir, `asset.${ext}`), bytes);
await withFileServer(projectDir, async (server) => {
const response = await fetch(`${server.url}/asset.${ext}`);
expect(response.status).toBe(200);
expect(response.headers.get("content-type")).toBe(type);
expect(new Uint8Array(await response.arrayBuffer())).toEqual(bytes);
const partial = await fetch(`${server.url}/asset.${ext}`, {
headers: { Range: "bytes=1-3" },
});
expect(partial.status).toBe(206);
expect(partial.headers.get("content-type")).toBe(type);
expect(partial.headers.get("content-range")).toBe("bytes 1-3/5");
expect(new Uint8Array(await partial.arrayBuffer())).toEqual(bytes.slice(1, 4));
});
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
it("marks producer pages as render capture before the runtime loads", async () => {
const projectDir = mkdtempSync(join(tmpdir(), "hf-file-server-render-mode-"));
try {
writeFileSync(
join(projectDir, "index.html"),
"<!doctype html><html><head></head><body></body></html>",
);
const runtimeScript = "globalThis.__hfRuntimeLoaded = true;";
const server = await createFileServer({
projectDir,
preHeadScripts: [],
headScripts: [runtimeScript],
});
try {
const response = await fetch(`${server.url}/index.html`);
expect(response.status).toBe(200);
const html = await response.text();
expect(html).toContain(RENDER_CAPTURE_MODE_SHIM);
expect(html.indexOf(RENDER_CAPTURE_MODE_SHIM)).toBeLessThan(html.indexOf(runtimeScript));
} finally {
server.close();
}
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
it("serves ES modules with a JavaScript MIME type", async () => {
const projectDir = mkdtempSync(join(tmpdir(), "hf-file-server-mjs-"));
try {
writeEmptyIndex(projectDir);
writeFileSync(join(projectDir, "scene.mjs"), "export const scene = true;");
const server = await createFileServer({ projectDir, preHeadScripts: [], headScripts: [] });
try {
const response = await fetch(`${server.url}/scene.mjs`);
expect(response.status).toBe(200);
expect(response.headers.get("content-type")).toBe("application/javascript; charset=utf-8");
} finally {
server.close();
}
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
async function expectInjectedRenderFps(
fps: Parameters<typeof createFileServer>[0]["fps"],
expected: {
value: string;
source: "render-options" | "default";
fallbackReason?: "missing" | "invalid";
},
): Promise<void> {
const projectDir = mkdtempSync(join(tmpdir(), "hf-file-server-render-fps-"));
try {
writeEmptyIndex(projectDir);
const server = await createFileServer({
projectDir,
preHeadScripts: [],
headScripts: [],
...(fps ? { fps } : {}),
});
try {
const response = await fetch(`${server.url}/index.html`);
expect(response.status).toBe(200);
const html = await response.text();
expect(html).toContain("window.__HF_EXPORT_RENDER_SEEK_CONFIG");
expect(html).toContain(`var __renderFps = ${expected.value}`);
expect(html).toContain(`var __renderFpsSource = "${expected.source}"`);
if (expected.fallbackReason) {
expect(html).toContain(`var __renderFpsFallbackReason = "${expected.fallbackReason}"`);
} else {
expect(html).toContain("var __renderFpsFallbackReason = null");
}
expect(html).toContain("fps: __renderFps");
expect(html).toContain("fpsSource: __renderFpsSource");
expect(html).not.toContain("[hyperframes] render fps defaulted");
} finally {
server.close();
}
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
}
it("injects the requested render fps into the page render config", async () => {
await expectInjectedRenderFps({ num: 60, den: 1 }, { value: "60", source: "render-options" });
});
it("injects fractional render fps without rounding", async () => {
await expectInjectedRenderFps(
{ num: 24000, den: 1001 },
{ value: "23.976023976023978", source: "render-options" },
);
});
it("marks missing render fps as an explicit 30fps default", async () => {
await expectInjectedRenderFps(undefined, {
value: "30",
source: "default",
fallbackReason: "missing",
});
});
it("marks invalid render fps as an explicit 30fps default", async () => {
await expectInjectedRenderFps(
{ num: 60, den: 0 },
{
value: "30",
source: "default",
fallbackReason: "invalid",
},
);
});
it("serves asset files through project-root symlinked directories", async () => {
const workspaceDir = mkdtempSync(join(tmpdir(), "hf-file-server-symlink-assets-"));
const adsDir = join(workspaceDir, "Ads");
const projectDir = join(adsDir, "annual-upsell-2");
const sharedDir = join(adsDir, "shared");
try {
mkdirSync(projectDir, { recursive: true });
mkdirSync(sharedDir, { recursive: true });
writeEmptyIndex(projectDir);
writeFileSync(
join(sharedDir, "brand.css"),
".aisplus-glass { backdrop-filter: blur(28px); }",
);
symlinkSync("../shared", join(projectDir, "shared"));
await withFileServer(projectDir, async (server) => {
await expectTextResponse(`${server.url}/shared/brand.css`, {
contentType: "text/css",
bodyIncludes: ".aisplus-glass",
});
});
} finally {
rmSync(workspaceDir, { recursive: true, force: true });
}
});
it("streams binary file content without buffering through readFileSync", async () => {
// Regression test for the video-heavy event-loop block documented at
// renderOrchestrator.ts:1277-1306. Pre-fix the file route called
// readFileSync on every binary asset, which on 32MB+ videos stalled
// the Node event loop long enough to wedge concurrent /health probes.
// This test pins three properties of the streaming path:
//
// 1. Correctness: the served byte sequence matches the file exactly,
// across a chunk boundary (we use a 5 MB synthetic asset, well past
// Node's default 64KB createReadStream highWaterMark).
// 2. Content-Length is reported via statSync so range-aware HTTP
// consumers (Chrome's media stack) see the size up front.
// 3. Concurrent requests don't serialize behind each other — N
// parallel fetches all return identical content. With readFileSync
// they'd block the event loop in serial; with the stream they
// pipe interleaved chunks.
const projectDir = mkdtempSync(join(tmpdir(), "hf-file-server-stream-"));
try {
writeEmptyIndex(projectDir);
// 5 MB of deterministic bytes — large enough to span many 64KB read
// chunks, small enough to keep the test fast.
const size = 5 * 1024 * 1024;
const buf = Buffer.alloc(size);
for (let i = 0; i < size; i++) buf[i] = i & 0xff;
writeFileSync(join(projectDir, "big.bin"), buf);
await withFileServer(projectDir, async (server) => {
// Single-request correctness + content-length.
const r = await fetch(`${server.url}/big.bin`);
expect(r.status).toBe(200);
expect(r.headers.get("content-length")).toBe(String(size));
const out = Buffer.from(await r.arrayBuffer());
expect(out.length).toBe(size);
// Spot-check a few sentinel positions (full equality check is O(5MB)
// and unnecessary — if any chunk were misaligned we'd see it here).
expect(out[0]).toBe(0);
expect(out[255]).toBe(255);
expect(out[256]).toBe(0);
expect(out[size - 1]).toBe((size - 1) & 0xff);
// Concurrent requests don't corrupt each other.
const concurrent = await Promise.all(
Array.from({ length: 4 }, () => fetch(`${server.url}/big.bin`)),
);
for (const resp of concurrent) {
expect(resp.status).toBe(200);
const body = Buffer.from(await resp.arrayBuffer());
expect(body.length).toBe(size);
expect(body[0]).toBe(0);
expect(body[size - 1]).toBe((size - 1) & 0xff);
}
});
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
it("serves Range requests with 206 Partial Content + Accept-Ranges", async () => {
// Pins the RFC 7233 implementation for the binary path: Chrome's <video>
// element issues `Range: bytes=...` when seeking, and the response must
// be 206 with `Content-Range` + a sliced body so the player can resume
// partial-load without re-pulling the whole file. Also pins that the
// server advertises `Accept-Ranges: bytes` on full-body GETs so clients
// know future Range requests are supported.
const projectDir = mkdtempSync(join(tmpdir(), "hf-file-server-range-"));
try {
writeEmptyIndex(projectDir);
// Use a 4 KB deterministic asset: small enough to keep the test
// fast, large enough that suffix / partial responses exercise the
// slicing math meaningfully.
const size = 4096;
const buf = Buffer.alloc(size);
for (let i = 0; i < size; i++) buf[i] = i & 0xff;
writeFileSync(join(projectDir, "asset.bin"), buf);
await withFileServer(projectDir, async (server) => {
// 1. Full GET advertises Accept-Ranges: bytes.
const full = await fetch(`${server.url}/asset.bin`);
expect(full.status).toBe(200);
expect(full.headers.get("accept-ranges")).toBe("bytes");
expect(full.headers.get("content-length")).toBe(String(size));
await full.body?.cancel();
// 2. Closed range: bytes=0-99 returns the first 100 bytes.
const head = await fetch(`${server.url}/asset.bin`, {
headers: { Range: "bytes=0-99" },
});
expect(head.status).toBe(206);
expect(head.headers.get("content-range")).toBe(`bytes 0-99/${size}`);
expect(head.headers.get("content-length")).toBe("100");
expect(head.headers.get("accept-ranges")).toBe("bytes");
const headBody = Buffer.from(await head.arrayBuffer());
expect(headBody.length).toBe(100);
expect(headBody[0]).toBe(0);
expect(headBody[99]).toBe(99);
// 3. Open-ended: bytes=4000- returns the tail.
const tail = await fetch(`${server.url}/asset.bin`, {
headers: { Range: "bytes=4000-" },
});
expect(tail.status).toBe(206);
expect(tail.headers.get("content-range")).toBe(`bytes 4000-${size - 1}/${size}`);
expect(tail.headers.get("content-length")).toBe(String(size - 4000));
const tailBody = Buffer.from(await tail.arrayBuffer());
expect(tailBody.length).toBe(size - 4000);
expect(tailBody[0]).toBe(4000 & 0xff);
expect(tailBody[tailBody.length - 1]).toBe((size - 1) & 0xff);
// 4. Suffix: bytes=-50 returns the last 50 bytes.
const suffix = await fetch(`${server.url}/asset.bin`, {
headers: { Range: "bytes=-50" },
});
expect(suffix.status).toBe(206);
expect(suffix.headers.get("content-range")).toBe(`bytes ${size - 50}-${size - 1}/${size}`);
expect(suffix.headers.get("content-length")).toBe("50");
const suffixBody = Buffer.from(await suffix.arrayBuffer());
expect(suffixBody.length).toBe(50);
expect(suffixBody[0]).toBe((size - 50) & 0xff);
expect(suffixBody[49]).toBe((size - 1) & 0xff);
// 5. Unsatisfiable: bytes=99999-99999 returns 416 with
// Content-Range: bytes */<size> per RFC 7233 §4.4.
const bad = await fetch(`${server.url}/asset.bin`, {
headers: { Range: "bytes=99999-99999" },
});
expect(bad.status).toBe(416);
expect(bad.headers.get("content-range")).toBe(`bytes */${size}`);
expect(bad.headers.get("accept-ranges")).toBe("bytes");
await bad.body?.cancel();
// 6. Multi-range falls back to 200 (we don't reassemble
// multipart/byteranges for the single-asset use case).
const multi = await fetch(`${server.url}/asset.bin`, {
headers: { Range: "bytes=0-9,20-29" },
});
expect(multi.status).toBe(200);
expect(multi.headers.get("accept-ranges")).toBe("bytes");
await multi.body?.cancel();
});
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
it("decodes percent-encoded reserved characters in URL path segments", async () => {
const projectDir = mkdtempSync(join(tmpdir(), "hf-file-server-reserved-chars-"));
try {
const subDir = join(projectDir, "video#1");
mkdirSync(subDir, { recursive: true });
writeEmptyIndex(projectDir);
writeFileSync(join(subDir, "frame.jpg"), "fake-jpg");
await withFileServer(projectDir, async (server) => {
await expectTextResponse(`${server.url}/video%231/frame.jpg`, {
bodyIncludes: "fake-jpg",
});
});
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
});
describe("HF_EARLY_STUB + HF_BRIDGE_SCRIPT integration", () => {
/**
* Simulates the real injection order in a Puppeteer page:
* 1. HF_EARLY_STUB (start of <head>, before everything)
* 2. authored page scripts that write to window.__hf.transitions
* (e.g. @hyperframes/shader-transitions in <body>)
* 3. HF_BRIDGE_SCRIPT (end of <body>, upgrades __hf with seek/duration)
*
* Regression test for the race condition where the bridge used to overwrite
* window.__hf with a fresh object, dropping any fields user libraries
* (notably `transitions`) had populated during page-script execution.
* Without the early stub + patch-not-replace bridge, the engine never
* detects shader transitions and HDR compositing falls back to plain DOM.
*/
it("preserves __hf.transitions written by page scripts through bridge upgrade", () => {
const sandbox: {
window: Record<string, unknown> & {
__hf?: { transitions?: unknown[]; seek?: (t: number) => void; duration?: number };
__player?: { renderSeek: (t: number) => void; getDuration: () => number };
setInterval: typeof setInterval;
clearInterval: typeof clearInterval;
};
document: { querySelector: () => null };
} = {
window: {
setInterval: globalThis.setInterval,
clearInterval: globalThis.clearInterval,
},
document: { querySelector: () => null },
};
sandbox.window.window = sandbox.window;
sandbox.window.document = sandbox.document;
const run = (src: string): void => {
new Function("window", "document", `with (window) {\n${src}\n}`)(
sandbox.window,
sandbox.document,
);
};
run(HF_EARLY_STUB);
expect(sandbox.window.__hf).toBeDefined();
expect(sandbox.window.__hf?.transitions).toBeUndefined();
sandbox.window.__hf!.transitions = [
{ time: 5, duration: 0.5, shader: "domain-warp", fromScene: "a", toScene: "b" },
];
sandbox.window.__player = {
renderSeek: () => {},
getDuration: () => 30,
};
run(HF_BRIDGE_SCRIPT);
expect(sandbox.window.__hf).toBeDefined();
expect(sandbox.window.__hf?.transitions).toEqual([
{ time: 5, duration: 0.5, shader: "domain-warp", fromScene: "a", toScene: "b" },
]);
expect(typeof sandbox.window.__hf?.seek).toBe("function");
expect(sandbox.window.__hf?.duration).toBe(0);
sandbox.window.__renderReady = true;
expect(sandbox.window.__hf?.duration).toBe(30);
});
it("forwards suppressEvents from __hf.seek to renderSeek", () => {
const renderSeekCalls: Array<[number, { suppressEvents?: boolean } | undefined]> = [];
const sandbox: {
window: Record<string, unknown> & {
__hf?: {
seek?: (t: number, options?: { suppressEvents?: boolean }) => void;
duration?: number;
};
__player?: {
renderSeek: (t: number, options?: { suppressEvents?: boolean }) => void;
getDuration: () => number;
};
setInterval: typeof setInterval;
clearInterval: typeof clearInterval;
};
document: { querySelector: () => null };
} = {
window: {
setInterval: globalThis.setInterval,
clearInterval: globalThis.clearInterval,
},
document: { querySelector: () => null },
};
sandbox.window.window = sandbox.window;
sandbox.window.document = sandbox.document;
sandbox.window.__renderReady = true;
sandbox.window.__player = {
renderSeek: (time, options) => {
renderSeekCalls.push([time, options]);
},
getDuration: () => 10,
};
new Function("window", "document", `with (window) {\n${HF_BRIDGE_SCRIPT}\n}`)(
sandbox.window,
sandbox.document,
);
sandbox.window.__hf?.seek?.(5, { suppressEvents: true });
expect(renderSeekCalls).toEqual([[5, { suppressEvents: true }]]);
});
it("keeps render-time timeline seeks synchronous during large renders", () => {
const sandbox: {
window: Record<string, unknown> & {
__hf?: Record<string, unknown>;
__hfTimelinesBuilding?: boolean;
gsap?: { timeline: () => { totalTime: (time?: number) => number | unknown } };
requestAnimationFrame: typeof requestAnimationFrame;
setTimeout: typeof setTimeout;
};
document: Record<string, never>;
CustomEvent: typeof CustomEvent;
} = {
window: {
requestAnimationFrame: (() => 1) as typeof requestAnimationFrame,
setTimeout: (() => 1) as typeof setTimeout,
},
document: {},
CustomEvent,
};
sandbox.window.window = sandbox.window;
sandbox.window.document = sandbox.document;
sandbox.window.CustomEvent = sandbox.CustomEvent;
new Function("window", "document", "CustomEvent", `with (window) {\n${HF_EARLY_STUB}\n}`)(
sandbox.window,
sandbox.document,
sandbox.CustomEvent,
);
const totalTimeCalls: number[] = [];
sandbox.window.gsap = {
timeline: () => ({
to: () => {},
from: () => {},
fromTo: () => {},
set: () => {},
pause: () => {},
play: () => {},
seek: () => {},
totalTime: (time?: number) => {
if (typeof time === "number") totalTimeCalls.push(time);
return totalTimeCalls.at(-1) ?? 0;
},
time: () => 0,
duration: () => 10,
add: () => {},
getChildren: () => [],
paused: () => true,
timeScale: () => 1,
kill: () => {},
}),
};
const timeline = sandbox.window.gsap.timeline();
for (let i = 0; i < 5100; i += 1) {
timeline.totalTime(i / 30);
}
expect(totalTimeCalls).toHaveLength(5100);
expect(sandbox.window.__hfTimelinesBuilding).toBe(false);
});
it("flushes queued construction calls before forwarding timeline children", () => {
const sandbox: {
window: Record<string, unknown> & {
__hf?: Record<string, unknown>;
__hfTimelinesBuilding?: boolean;
gsap?: {
timeline: () => { to: (...args: unknown[]) => unknown; getChildren: () => unknown[] };
};
requestAnimationFrame: typeof requestAnimationFrame;
setTimeout: typeof setTimeout;
};
document: Record<string, never>;
CustomEvent: typeof CustomEvent;
} = {
window: {
requestAnimationFrame: (() => 1) as typeof requestAnimationFrame,
setTimeout: ((callback: () => void) => {
callback();
return 1;
}) as typeof setTimeout,
},
document: {},
CustomEvent,
};
sandbox.window.window = sandbox.window;
sandbox.window.document = sandbox.document;
sandbox.window.CustomEvent = sandbox.CustomEvent;
new Function("window", "document", "CustomEvent", `with (window) {\n${HF_EARLY_STUB}\n}`)(
sandbox.window,
sandbox.document,
sandbox.CustomEvent,
);
const constructionCalls: unknown[][] = [];
const child = { id: "child" };
sandbox.window.gsap = {
timeline: () => ({
to: (...args: unknown[]) => {
constructionCalls.push(args);
},
from: () => {},
fromTo: () => {},
set: () => {},
pause: () => {},
play: () => {},
seek: () => {},
totalTime: () => 0,
time: () => 0,
duration: () => 10,
add: () => {},
getChildren: () => [child],
paused: () => true,
timeScale: () => 1,
kill: () => {},
}),
};
const timeline = sandbox.window.gsap.timeline();
timeline.to("#box", { x: 100 });
expect(constructionCalls).toHaveLength(0);
expect(timeline.getChildren()).toEqual([child]);
expect(constructionCalls).toHaveLength(1);
expect(sandbox.window.__hfTimelinesBuilding).toBe(false);
});
it("proxy is non-thenable — Promise.resolve(proxy) resolves immediately", async () => {
const sandbox: {
window: Record<string, unknown> & {
__hf?: Record<string, unknown>;
__hfTimelinesBuilding?: boolean;
gsap?: { timeline: () => Record<string, unknown> };
requestAnimationFrame: typeof requestAnimationFrame;
setTimeout: typeof setTimeout;
};
document: Record<string, never>;
CustomEvent: typeof CustomEvent;
} = {
window: {
requestAnimationFrame: (() => 1) as typeof requestAnimationFrame,
setTimeout: (() => 1) as typeof setTimeout,
},
document: {},
CustomEvent,
};
sandbox.window.window = sandbox.window;
sandbox.window.document = sandbox.document;
sandbox.window.CustomEvent = sandbox.CustomEvent;
new Function("window", "document", "CustomEvent", `with (window) {\n${HF_EARLY_STUB}\n}`)(
sandbox.window,
sandbox.document,
sandbox.CustomEvent,
);
sandbox.window.gsap = {
timeline: () => ({
to: () => {},
from: () => {},
fromTo: () => {},
set: () => {},
pause: () => {},
play: () => {},
seek: () => {},
totalTime: () => 0,
time: () => 0,
duration: () => 10,
add: () => {},
getChildren: () => [],
paused: () => true,
timeScale: () => 1,
kill: () => {},
then: (_resolve: () => void) => {
throw new Error("Real then() was called — proxy is thenable");
},
}),
};
const timeline = sandbox.window.gsap.timeline();
const resolved = await Promise.resolve(timeline);
expect(resolved).toBe(timeline);
});
it("keeps bridge duration at zero until the runtime publishes render readiness", () => {
const sandbox: {
window: Record<string, unknown> & {
__hf?: { seek?: (t: number) => void; duration?: number };
__player?: { renderSeek: (t: number) => void; getDuration: () => number };
__renderReady?: boolean;
__hfTimelinesBuilding?: boolean;
setInterval: typeof setInterval;
clearInterval: typeof clearInterval;
};
document: { querySelector: () => { getAttribute: (name: string) => string | null } };
} = {
window: {
setInterval: globalThis.setInterval,
clearInterval: globalThis.clearInterval,
},
document: {
querySelector: () => ({
getAttribute: (name: string) => (name === "data-duration" ? "15" : null),
}),
},
};
sandbox.window.window = sandbox.window;
sandbox.window.document = sandbox.document;
sandbox.window.__player = {
renderSeek: () => {},
getDuration: () => 0,
};
new Function("window", "document", `with (window) {\n${HF_BRIDGE_SCRIPT}\n}`)(
sandbox.window,
sandbox.document,
);
expect(sandbox.window.__hf?.duration).toBe(0);
sandbox.window.__renderReady = true;
expect(sandbox.window.__hf?.duration).toBe(15);
sandbox.window.__hfTimelinesBuilding = true;
expect(sandbox.window.__hf?.duration).toBe(0);
});
it("derives duration from sub-composition data-start + data-duration when root has none", () => {
const sandbox: any = {
window: {
setInterval: globalThis.setInterval,
clearInterval: globalThis.clearInterval,
},
document: {
querySelector: () => ({
getAttribute: () => null,
}),
querySelectorAll: () => [
{
getAttribute: (n: string) =>
n === "data-start" ? "0" : n === "data-duration" ? "5" : null,
},
{
getAttribute: (n: string) =>
n === "data-start" ? "5" : n === "data-duration" ? "8" : null,
},
],
},
};
sandbox.window.window = sandbox.window;
sandbox.window.document = sandbox.document;
sandbox.window.__player = {
renderSeek: () => {},
getDuration: () => 0,
};
sandbox.window.__renderReady = true;
new Function("window", "document", `with (window) {\n${HF_BRIDGE_SCRIPT}\n}`)(
sandbox.window,
sandbox.document,
);
expect(sandbox.window.__hf?.duration).toBe(13);
});
it("stands in for the GSAP timeline itself when the GSAP bundle sets window.gsap twice", () => {
class FakeTimeline {
parent: FakeTimeline | null = null;
add(child: FakeTimeline) {
child.parent = this;
return this;
}
}
const gsap = { timeline: () => new FakeTimeline() };
const win: Record<string, unknown> = {
__HF_VIRTUAL_TIME__: { originalRequestAnimationFrame: () => 0, originalSetTimeout: () => {} },
};
new Function("window", HF_EARLY_STUB)(win);
win.gsap = gsap;
win.gsap = gsap;
const parent = gsap.timeline() as unknown as { __hfReal: unknown; add: (c: unknown) => void };
const child = gsap.timeline() as unknown as { __hfReal: FakeTimeline };
parent.add(child);
(win.__hfFlushSync as () => void)();
expect(child.__hfReal).toBeInstanceOf(FakeTimeline);
expect(child.__hfReal.parent).toBe(parent.__hfReal);
});
});