Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* Regression guard for HF#1731 / HF#1730 — pins the 0-based `framePaths`
* key convention on `rebuildExtractedFramesFromPlanDir`.
*
* Why a separate file from `renderChunk.test.ts`: that file's top-level
* `beforeAll` boots a Chrome smoke probe so the byte-identical-retry
* assertions can soft-skip on hosts where chrome-headless-shell can't
* initialize. The probe is a 5-15s tax on the whole module even when no
* Chrome-dependent test runs. This file is pure-filesystem and stays
* Chrome-free so the regression check runs in ~10ms on every PR.
*
* The bug: the consumer of `framePaths` is
* `videoFrameExtractor.ts:getFrameAtTime`, which computes
* `Math.floor(localTime * fps + 1e-9)` (0-based) and reads
* `framePaths.get(frameIndex)`. The pre-fix code in
* `rebuildExtractedFramesFromPlanDir` wrote `framePaths.set(i + 1, …)`
* instead of `framePaths.set(i, …)`, so `framePaths.get(0)` returned
* `undefined` at every `<video>`'s first-paint frame: the vid silently
* dropped out of activePayloads, the injector didn't fire, and
* BeginFrame screenshotted an empty composition (Y≈22 black flash for
* one frame at each first-paint boundary). Symptom only reproduced in
* distributed mode — local single-process renders take a different
* code path (`videoFrameExtractor.ts:317`) that was already 0-based.
*
* This test must FAIL against the previous `i + 1` indexing and PASS
* against the fix. Don't soften it into a "key set has expected size"
* shape — the bug was specifically that `get(0)` returned undefined,
* so assert that directly.
*/
import { describe, expect, it } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { rebuildExtractedFramesFromPlanDir } from "./renderChunk.js";
import type { PlanVideosJson } from "./shared.js";
function makeFramesDir(planDir: string, videoId: string, frameNames: string[]): void {
const outputDir = join(planDir, "video-frames", videoId);
mkdirSync(outputDir, { recursive: true });
for (const name of frameNames) {
// Contents don't matter — the function only lists + sorts the dir
// and maps names to absolute paths. A single byte keeps the test
// fast and stays well clear of any filesystem reservation quirks.
writeFileSync(join(outputDir, name), "x", "utf-8");
}
}
// The function never reads inside `metadata`, it just forwards it onto
// the returned `ExtractedFrames`. A bare cast spares us the full
// `VideoMetadata` shape per test.
const VIDEO_METADATA_STUB = {} as PlanVideosJson["extracted"][number]["metadata"];
describe("rebuildExtractedFramesFromPlanDir", () => {
it("indexes framePaths 0-based (regression guard for HF#1731)", () => {
const planDir = mkdtempSync(join(tmpdir(), "hf-rebuild-frames-0based-"));
try {
const videoId = "vid-0";
// Zero-padded monotonic names — same shape `extractVideoFramesRange`
// produces (`frame_%05d.jpg`).
const frameNames = [
"frame_00001.jpg",
"frame_00002.jpg",
"frame_00003.jpg",
"frame_00004.jpg",
"frame_00005.jpg",
];
makeFramesDir(planDir, videoId, frameNames);
const result = rebuildExtractedFramesFromPlanDir(planDir, [
{
videoId,
srcPath: "/does/not/matter.mp4",
framePattern: "frame_%05d.jpg",
fps: 30,
totalFrames: frameNames.length,
metadata: VIDEO_METADATA_STUB,
},
]);
expect(result).toHaveLength(1);
const extracted = result[0]!;
expect(extracted.framePaths.size).toBe(frameNames.length);
// The load-bearing assertion. `getFrameAtTime` calls
// `framePaths.get(0)` for every video's first-paint frame
// (localTime === 0 → frameIndex === 0). The pre-fix code's `i + 1`
// indexing meant this returned `undefined` and the vid silently
// dropped from activePayloads — that's HF#1731.
const first = extracted.framePaths.get(0);
expect(first).toBeDefined();
expect(first).toBe(join(planDir, "video-frames", videoId, "frame_00001.jpg"));
// Last frame at index N-1 (0-based) must resolve; index N must not.
// Together with `get(0)` defined this fully pins the 0-based
// contract — the pre-fix shape would have `get(N)` defined and
// `get(0)` undefined.
const last = extracted.framePaths.get(frameNames.length - 1);
expect(last).toBe(join(planDir, "video-frames", videoId, "frame_00005.jpg"));
expect(extracted.framePaths.get(frameNames.length)).toBeUndefined();
} finally {
rmSync(planDir, { recursive: true, force: true });
}
});
it("preserves 0-based indexing across multiple videos in the same planDir", () => {
// Multi-video shape — the HF#1731 repro was a back-to-back composition
// (v1: 0-4s, v2: 4-8s, v3: 8-12s) and EVERY vid's first-paint frame
// was PRISTINE black. The function must produce the 0-based contract
// for every video in the manifest, not just the first.
const planDir = mkdtempSync(join(tmpdir(), "hf-rebuild-frames-multi-"));
try {
makeFramesDir(planDir, "vid-a", ["frame_00001.jpg", "frame_00002.jpg"]);
makeFramesDir(planDir, "vid-b", ["frame_00001.jpg", "frame_00002.jpg", "frame_00003.jpg"]);
const result = rebuildExtractedFramesFromPlanDir(planDir, [
{
videoId: "vid-a",
srcPath: "/a.mp4",
framePattern: "frame_%05d.jpg",
fps: 30,
totalFrames: 2,
metadata: VIDEO_METADATA_STUB,
},
{
videoId: "vid-b",
srcPath: "/b.mp4",
framePattern: "frame_%05d.jpg",
fps: 30,
totalFrames: 3,
metadata: VIDEO_METADATA_STUB,
},
]);
expect(result).toHaveLength(2);
// Every video's `framePaths.get(0)` must resolve — pre-fix, all of
// them returned undefined and every vid's first-paint dropped.
expect(result[0]!.framePaths.get(0)).toBe(
join(planDir, "video-frames", "vid-a", "frame_00001.jpg"),
);
expect(result[1]!.framePaths.get(0)).toBe(
join(planDir, "video-frames", "vid-b", "frame_00001.jpg"),
);
// Cleanup ownership flag — chunk workers don't own the planDir's
// video-frames tree (the controller does); a flip would cause the
// injector cleanup to rm bytes another worker may still be reading.
expect(result[0]!.ownedByLookup).toBe(false);
expect(result[1]!.ownedByLookup).toBe(false);
} finally {
rmSync(planDir, { recursive: true, force: true });
}
});
it("keeps the historical sorted-position mapping for v1 numeric filenames", () => {
const planDir = mkdtempSync(join(tmpdir(), "hf-rebuild-frames-v1-numeric-"));
try {
makeFramesDir(planDir, "vid-v1-numeric", ["frame_00000.jpg", "frame_00001.jpg"]);
const [extracted] = rebuildExtractedFramesFromPlanDir(planDir, [
{
videoId: "vid-v1-numeric",
srcPath: "/v1-numeric.mp4",
framePattern: "frame_%05d.jpg",
fps: 30,
totalFrames: 2,
metadata: VIDEO_METADATA_STUB,
},
]);
expect(extracted!.framePaths.get(0)).toBe(
join(planDir, "video-frames", "vid-v1-numeric", "frame_00000.jpg"),
);
expect(extracted!.framePaths.get(1)).toBe(
join(planDir, "video-frames", "vid-v1-numeric", "frame_00001.jpg"),
);
expect(extracted!.framePaths.get(-1)).toBeUndefined();
} finally {
rmSync(planDir, { recursive: true, force: true });
}
});
it("orders mixed-width dense-v1 filenames by numeric ordinal", () => {
const planDir = mkdtempSync(join(tmpdir(), "hf-rebuild-frames-v1-mixed-width-"));
try {
const frameNames = Array.from({ length: 10 }, (_, index) => `frame_${index + 1}.jpg`);
makeFramesDir(planDir, "vid-v1-mixed-width", frameNames.toReversed());
const [extracted] = rebuildExtractedFramesFromPlanDir(planDir, [
{
videoId: "vid-v1-mixed-width",
srcPath: "/v1-mixed-width.mp4",
framePattern: "frame_%05d.jpg",
fps: 30,
totalFrames: frameNames.length,
metadata: VIDEO_METADATA_STUB,
},
]);
expect(extracted!.framePaths.get(8)).toBe(
join(planDir, "video-frames", "vid-v1-mixed-width", "frame_9.jpg"),
);
expect(extracted!.framePaths.get(9)).toBe(
join(planDir, "video-frames", "vid-v1-mixed-width", "frame_10.jpg"),
);
} finally {
rmSync(planDir, { recursive: true, force: true });
}
});
it("preserves original indexes for a sparse v2 chunk materialization", () => {
const planDir = mkdtempSync(join(tmpdir(), "hf-rebuild-frames-sparse-"));
try {
makeFramesDir(planDir, "vid-sparse", [
"frame_00021.jpg",
"frame_00022.jpg",
"frame_00101.jpg",
]);
const [extracted] = rebuildExtractedFramesFromPlanDir(
planDir,
[
{
videoId: "vid-sparse",
srcPath: "/sparse.mp4",
framePattern: "frame_%05d.jpg",
fps: 30,
totalFrames: 200,
metadata: VIDEO_METADATA_STUB,
},
],
"sparse-v2",
);
if (!extracted) throw new Error("expected sparse v2 extracted-frame result");
expect(extracted.framePaths.get(20)).toBe(
join(planDir, "video-frames", "vid-sparse", "frame_00021.jpg"),
);
expect(extracted.framePaths.get(21)).toBe(
join(planDir, "video-frames", "vid-sparse", "frame_00022.jpg"),
);
expect(extracted.framePaths.get(100)).toBe(
join(planDir, "video-frames", "vid-sparse", "frame_00101.jpg"),
);
expect(extracted.framePaths.get(0)).toBeUndefined();
} finally {
rmSync(planDir, { recursive: true, force: true });
}
});
});