Code-first video & image, rendered natively on WebGPU.
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { loadImage } from "skia-canvas";
import { describe, expect, it } from "vitest";
import {
Composition,
computeGridLayout,
Layer,
LayerAnimation,
renderFrameGrid,
resolveSamplePoints,
} from "./index.js";
describe("FrameGrid Rendering Conformance & Validations", () => {
it("resolves sample points by frame range with step", () => {
const { samples, fps } = resolveSamplePoints(
{
startFrame: 10,
endFrame: 30,
stepFrames: 5,
fps: 30,
},
30,
);
expect(fps).toBe(30);
expect(samples.length).toBe(5); // 10, 15, 20, 25, 30
expect(samples[0]).toEqual({ frame: 10, timeMs: 1000 / 3 });
expect(samples[4]).toEqual({ frame: 30, timeMs: 1000 });
});
it("resolves sample points by millisecond range", () => {
const { samples } = resolveSamplePoints(
{
startMs: 0,
endMs: 500,
stepMs: 100,
fps: 20,
},
20,
);
expect(samples.length).toBe(6); // 0, 100, 200, 300, 400, 500
expect(samples[0]).toEqual({ frame: 0, timeMs: 0 });
expect(samples[3]).toEqual({ frame: 6, timeMs: 300 });
});
it("resolves sample points from explicit frame array", () => {
const { samples } = resolveSamplePoints(
{
frames: [0, 12, 24, 48],
fps: 24,
},
24,
);
expect(samples.length).toBe(4);
expect(samples.map((s) => s.frame)).toEqual([0, 12, 24, 48]);
});
it("throws on invalid ranges and bounds", () => {
expect(() => resolveSamplePoints({ startFrame: 50, endFrame: 10 })).toThrow(
/startFrame must be <= endFrame/,
);
expect(() => resolveSamplePoints({ startMs: 1000, endMs: 200 })).toThrow(
/startMs must be <= endMs/,
);
expect(() => resolveSamplePoints({ stepFrames: 0 })).toThrow(
/stepFrames.*Must be > 0/,
);
expect(() => resolveSamplePoints({ stepMs: -10 })).toThrow(
/stepMs.*Must be > 0/,
);
});
it("throws safety error when requested frames exceed maxFrames limit", () => {
expect(() =>
resolveSamplePoints({
startFrame: 0,
endFrame: 1000,
stepFrames: 1, // 1001 frames!
maxFrames: 40,
}),
).toThrow(/exceeds the safety threshold/);
});
it("computes balanced grid dimensions and clamps to max canvas size", () => {
const layout = computeGridLayout(16, 16 / 9, {
cellWidth: 320,
gap: 10,
padding: 20,
});
expect(layout.columns).toBe(4);
expect(layout.rows).toBe(4);
expect(layout.cellWidth).toBe(320);
expect(layout.cellHeight).toBe(180);
expect(layout.totalWidth).toBe(4 * 320 + 3 * 10 + 20 * 2); // 1350
expect(layout.totalHeight).toBe(
4 * 180 + 3 * 10 + 20 * 2 + layout.headerHeight,
);
});
it("downscales cell sizes automatically if total grid exceeds maxGridWidth/Height", () => {
const layout = computeGridLayout(25, 16 / 9, {
columns: 5,
cellWidth: 800, // 5 * 800 = 4000px without gap/padding
maxGridWidth: 1600, // force aggressive downscale
gap: 10,
padding: 10,
});
expect(layout.totalWidth).toBeLessThanOrEqual(1600);
expect(layout.cellWidth).toBeLessThan(800);
});
it("renders a multi-frame animation into a consolidated PNG grid", async () => {
const comp = new Composition({
width: 320,
height: 240,
fps: 24,
durationMs: 1000,
backgroundColor: "#05070a",
});
const anim = LayerAnimation.create().fromTo("x", 10, 200, {
from: 0,
to: 24,
});
comp.add(
Layer.shape("rect", {
width: 60,
height: 60,
y: 90,
fillColor: "#6366f1",
}).animate(anim),
);
// Render a 5-frame contact sheet
const gridPng = await comp.renderFrameGrid({
startFrame: 0,
endFrame: 20,
stepFrames: 5,
cellWidth: 160,
showHeader: true,
showLabels: true,
});
expect(gridPng).toBeInstanceOf(Buffer);
expect(gridPng.length).toBeGreaterThan(1000);
// Verify valid PNG header (0x89 50 4E 47 0D 0A 1A 0A)
expect(gridPng[0]).toBe(0x89);
expect(gridPng[1]).toBe(0x50);
expect(gridPng[2]).toBe(0x4e);
expect(gridPng[3]).toBe(0x47);
// Verify image decodability using skia-canvas
const img = await loadImage(gridPng);
expect(img.width).toBeGreaterThan(300);
expect(img.height).toBeGreaterThan(200);
// Also verify standalone renderFrameGrid export directly
const standalonePng = await renderFrameGrid(comp, {
startFrame: 0,
endFrame: 10,
stepFrames: 5,
cellWidth: 160,
});
expect(standalonePng).toBeInstanceOf(Buffer);
expect(standalonePng.length).toBeGreaterThan(1000);
});
});
describe("bounded canonical grid sampling", () => {
it("bounds work before allocating an enormous range", async () => {
const source = new URL("./renderer/framegrid.ts", import.meta.url).href;
const script = `import { resolveSamplePoints } from ${JSON.stringify(source)};
for (const endFrame of [1_000_000_000, Infinity, NaN]) {
let rejected = false;
try { resolveSamplePoints({ endFrame, stepFrames: 1 }); } catch { rejected = true; }
if (!rejected) process.exit(1);
}
process.exit(0);`;
await promisify(execFile)(
process.execPath,
[
"--import",
"tsx",
"--conditions=development",
"--input-type=module",
"-e",
script,
],
{ timeout: 10000 },
);
});
it("validates steps, frame indices and limits", () => {
for (const stepFrames of [NaN, Infinity, 0.1])
expect(() => resolveSamplePoints({ stepFrames })).toThrow();
for (const maxFrames of [0, -1, 1.5, NaN, Infinity])
expect(() => resolveSamplePoints({ maxFrames })).toThrow(/maxFrames/);
expect(() => resolveSamplePoints({ frames: [0.5] })).toThrow(/frame/);
expect(() =>
resolveSamplePoints({ startMs: 1e20, endMs: 1e20, stepMs: 0.1 }),
).toThrow(/advance/);
});
it("preserves explicit ordering and duplicates while enforcing the cap", () => {
expect(
resolveSamplePoints({ frames: [5, 0, 5] }).samples.map((s) => s.frame),
).toEqual([5, 0, 5]);
expect(
resolveSamplePoints({
startFrame: 0,
endFrame: 119,
stepFrames: 1,
maxFrames: 200,
}).samples,
).toHaveLength(120);
expect(() =>
resolveSamplePoints({ endFrame: 120, stepFrames: 1, maxFrames: 200 }),
).toThrow(/120/);
});
it("keeps automatic samples inside rounded export duration", () => {
expect(
resolveSamplePoints({}, 30, 1000).samples.map((s) => s.frame),
).toEqual([0, 5, 10, 15, 20, 25]);
expect(resolveSamplePoints({}, 30, 1).samples.map((s) => s.frame)).toEqual([
0,
]);
expect(
resolveSamplePoints({ stepFrames: 1 }, 30, 50).samples.map(
(s) => s.frame,
),
).toEqual([0, 1]);
expect(
resolveSamplePoints({ stepMs: 100 }, 30, 1000).samples.at(-1)?.frame,
).toBeLessThan(30);
expect(
resolveSamplePoints({ frames: [30] }, 30, 1000).samples[0].frame,
).toBe(30);
});
it("does not round-trip timestamp labels into another frame", () => {
expect(resolveSamplePoints({ timesMs: [16.6], fps: 30 }).samples).toEqual([
{ frame: 0, timeMs: 0 },
]);
});
});