Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { afterEach, describe, expect, it, vi } from "vitest";
import { Hono } from "hono";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
truncateSync,
utimesSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { pruneThumbnailCache, registerThumbnailRoutes } from "./thumbnail";
import { PREVIEW_CAPTURE_PARAM } from "./preview";
import type { StudioApiAdapter } from "../types";
import { createProjectSignature } from "../helpers/projectSignature.js";
import { proxyActivityMark } from "../helpers/proxyTranscoder.js";
vi.mock("../helpers/proxyTranscoder.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../helpers/proxyTranscoder.js")>()),
proxyActivityMark: vi.fn(() => "0"),
}));
const tempProjectDirs: string[] = [];
afterEach(() => {
for (const dir of tempProjectDirs.splice(0)) {
rmSync(dir, { recursive: true, force: true });
}
});
function createAdapter(): StudioApiAdapter {
const projectDir = mkdtempSync(join(tmpdir(), "hf-thumbnail-test-"));
tempProjectDirs.push(projectDir);
return {
listProjects: () => [],
resolveProject: async (id: string) => ({ id, dir: projectDir }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => "/tmp/renders",
startRender: () => ({
id: "job-1",
status: "rendering",
progress: 0,
outputPath: "/tmp/out.mp4",
}),
generateThumbnail: vi.fn(async () => Buffer.from("thumb")),
};
}
async function writeComposition(
adapter: StudioApiAdapter,
width: number,
height: number,
): Promise<void> {
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
writeFileSync(
join(project.dir, "index.html"),
`<div data-width="${width}" data-height="${height}"></div>`,
);
}
describe("registerThumbnailRoutes", () => {
it("screenshots the capture variant of the preview document", async () => {
const adapter = createAdapter();
await writeComposition(adapter, 1920, 1080);
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const loaded: string[] = [];
vi.mocked(adapter.generateThumbnail!).mockImplementation(async ({ previewUrl }) => {
loaded.push(new URL(previewUrl).search);
return Buffer.from("thumb");
});
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=6");
await app.request("http://localhost/projects/demo/thumbnail/scenes%2Fb.html?t=6");
expect(loaded).toEqual([`?${PREVIEW_CAPTURE_PARAM}=1`, `?${PREVIEW_CAPTURE_PARAM}=1`]);
});
it("forwards selector queries to thumbnail generation", async () => {
const adapter = createAdapter();
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const response = await app.request(
"http://localhost/projects/demo/thumbnail/index.html?t=1.2&selector=%23title-card",
);
expect(response.status).toBe(200);
expect(adapter.generateThumbnail).toHaveBeenCalledWith(
expect.objectContaining({
compPath: "index.html",
seekTime: 1.2,
selector: "#title-card",
format: "jpeg",
outputWidth: 240,
outputHeight: 135,
signal: expect.any(AbortSignal),
}),
);
});
it("keeps selectors that differ only in punctuation apart in the cache", async () => {
const adapter = createAdapter();
const app = new Hono();
registerThumbnailRoutes(app, adapter);
for (const selector of ["%23a%5C.b", "%23a_b", "%23a%5C.b"]) {
await app.request(
`http://localhost/projects/demo/thumbnail/index.html?t=1.2&selector=${selector}`,
);
}
expect(vi.mocked(adapter.generateThumbnail!).mock.calls.map(([opts]) => opts.selector)).toEqual(
["#a\\.b", "#a_b"],
);
});
it("maps square authored dimensions across jpeg output modes", async () => {
const adapter = createAdapter();
const app = new Hono();
registerThumbnailRoutes(app, adapter);
await writeComposition(adapter, 1080, 1080);
const sourceResponse = await app.request(
"http://localhost/projects/demo/thumbnail/index.html?t=1.2&output=source",
);
const previewResponse = await app.request(
"http://localhost/projects/demo/thumbnail/index.html?t=1.2&output=preview",
);
expect(sourceResponse.status).toBe(200);
expect(previewResponse.status).toBe(200);
expect(adapter.generateThumbnail).toHaveBeenNthCalledWith(
1,
expect.objectContaining({
format: "jpeg",
outputWidth: 1080,
outputHeight: 1080,
}),
);
expect(adapter.generateThumbnail).toHaveBeenNthCalledWith(
2,
expect.objectContaining({ outputWidth: 135, outputHeight: 135 }),
);
});
it("answers a cache-only request from the cache, with no content and no render on a miss", async () => {
const adapter = createAdapter();
await writeComposition(adapter, 1920, 1080);
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const url = "http://localhost/projects/demo/thumbnail/index.html?t=0&output=source";
const miss = await app.request(`${url}&cached=1`);
expect(miss.status).toBe(204);
expect(miss.headers.get("Cache-Control")).toBe("no-cache");
expect(await miss.text()).toBe("");
expect(adapter.generateThumbnail).not.toHaveBeenCalled();
expect((await app.request(url)).status).toBe(200);
const hit = await app.request(`${url}&cached=1`);
expect(hit.status).toBe(200);
expect(await hit.text()).toBe("thumb");
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
});
it("deduplicates concurrent generation and writes one complete cache entry", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
let resolve!: (buffer: Buffer) => void;
const generated = new Promise<Buffer>((done) => (resolve = done));
adapter.generateThumbnail = vi.fn(async () => generated);
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
const first = app.request(url);
const second = app.request(url);
await vi.waitFor(() => expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1));
resolve(Buffer.from("shared"));
expect(await (await first).text()).toBe("shared");
expect(await (await second).text()).toBe("shared");
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
const cached = readdirSync(join(project.dir, ".thumbnails"));
expect(cached).toHaveLength(1);
expect(cached[0]).not.toContain(".tmp");
});
it("forwards png capture requests and returns a png content type", async () => {
const adapter = createAdapter();
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const response = await app.request(
"http://localhost/projects/demo/thumbnail/compositions%2Fintro.html?t=2&format=png",
);
expect(response.status).toBe(200);
expect(response.headers.get("Content-Type")).toBe("image/png");
expect(adapter.generateThumbnail).toHaveBeenCalledWith(
expect.objectContaining({
compPath: "compositions/intro.html",
seekTime: 2,
format: "png",
outputWidth: 1920,
outputHeight: 1080,
}),
);
});
it("allows png callers to opt into bounded preview output", async () => {
const adapter = createAdapter();
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const response = await app.request(
"http://localhost/projects/demo/thumbnail/index.html?format=png&output=preview",
);
expect(response.status).toBe(200);
expect(adapter.generateThumbnail).toHaveBeenCalledWith(
expect.objectContaining({ outputWidth: 240, outputHeight: 135 }),
);
});
it("preserves an explicit zero seek time", async () => {
const adapter = createAdapter();
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const response = await app.request(
"http://localhost/projects/demo/thumbnail/index.html?t=0&format=png",
);
expect(response.status).toBe(200);
expect(adapter.generateThumbnail).toHaveBeenCalledWith(
expect.objectContaining({
compPath: "index.html",
seekTime: 0,
format: "png",
}),
);
});
it("forwards selector occurrence indexes to thumbnail generation", async () => {
const adapter = createAdapter();
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const response = await app.request(
"http://localhost/projects/demo/thumbnail/index.html?t=1.2&selector=.card&selectorIndex=2",
);
expect(response.status).toBe(200);
expect(adapter.generateThumbnail).toHaveBeenCalledWith(
expect.objectContaining({
selector: ".card",
selectorIndex: 2,
}),
);
});
it("keeps url thumbnail versions separated in the disk cache", async () => {
const adapter = createAdapter();
const app = new Hono();
registerThumbnailRoutes(app, adapter);
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=old");
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=old");
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=new");
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
it("keeps changed composition dimensions separated in the disk cache", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const indexPath = join(project.dir, "index.html");
writeFileSync(indexPath, `<div data-composition-id="main" data-width="640" data-height="360">`);
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
writeFileSync(
indexPath,
`<div data-composition-id="main" data-width="1280" data-height="720">`,
);
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
expect(adapter.generateThumbnail).toHaveBeenLastCalledWith(
expect.objectContaining({
width: 1280,
height: 720,
}),
);
});
it("keeps changed studio manual edits separated in the disk cache", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const indexPath = join(project.dir, "index.html");
writeFileSync(indexPath, `<div data-composition-id="main" data-width="640" data-height="360">`);
const manualEditsDir = join(project.dir, ".hyperframes");
mkdirSync(manualEditsDir, { recursive: true });
const manualEditsPath = join(manualEditsDir, "studio-manual-edits.json");
writeFileSync(manualEditsPath, `{"version":1,"edits":[]}`);
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
writeFileSync(
manualEditsPath,
`{"version":1,"edits":[{"kind":"rotation","target":{"sourceFile":"index.html","id":"card"},"angle":30}]}`,
);
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
it("regenerates when the composition HTML changes even with explicit w/h", async () => {
// Repro: the Studio requests thumbnails WITH explicit dimensions. The old
// code only read (and keyed on) the composition file when no w/h was given,
// so editing the HTML left the disk-cache key unchanged and served a stale
// thumbnail — even after a hard reload. The content hash must always be keyed.
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const indexPath = join(project.dir, "index.html");
const url = "http://localhost/projects/demo/thumbnail/index.html?t=2&w=640&h=360&v=test";
writeFileSync(indexPath, `<div id="box">before</div>`);
await app.request(url);
writeFileSync(indexPath, `<div id="box">after</div>`);
await app.request(url);
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
it("regenerates a parent thumbnail when nested composition HTML changes", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
writeFileSync(
join(project.dir, "index.html"),
`<div data-width="640" data-height="360" data-composition-src="compositions/nested.html"></div>`,
);
const compositionsDir = join(project.dir, "compositions");
mkdirSync(compositionsDir, { recursive: true });
const nestedPath = join(compositionsDir, "nested.html");
writeFileSync(nestedPath, `<div>before</div>`);
const url = "http://localhost/projects/demo/thumbnail/index.html?t=2&v=test";
await app.request(url);
writeFileSync(nestedPath, `<div>after with a different size</div>`);
await app.request(url);
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
function writeTwoScenes(dir: string): { sceneA: string; sceneB: string } {
writeFileSync(
join(dir, "index.html"),
`<head><style>body { margin: 0 }</style></head><div data-width="640" data-height="360">` +
`<div data-composition-src="compositions/a.html"></div>` +
`<div data-composition-src="compositions/b.html"></div></div>`,
);
mkdirSync(join(dir, "compositions"), { recursive: true });
const sceneA = join(dir, "compositions", "a.html");
const sceneB = join(dir, "compositions", "b.html");
writeFileSync(sceneA, `<template><div data-composition-id="a">A</div></template>`);
writeFileSync(sceneB, `<template><div data-composition-id="b">B</div></template>`);
return { sceneA, sceneB };
}
it("keeps a scene's cached thumbnail when a sibling scene changes", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const { sceneA } = writeTwoScenes(project.dir);
const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=2&v=test";
await app.request(url);
writeFileSync(sceneA, `<template><div data-composition-id="a">A, edited</div></template>`);
await app.request(url);
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
});
it("regenerates a scene thumbnail when the root it is built on changes", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
writeTwoScenes(project.dir);
const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=2&v=test";
await app.request(url);
const root = join(project.dir, "index.html");
writeFileSync(root, readFileSync(root, "utf-8").replace("margin: 0", "margin: 4px"));
await app.request(url);
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
it("regenerates a thumbnail when imported CSS changes", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
writeFileSync(
join(project.dir, "index.html"),
`<link rel="stylesheet" href="./styles.css"><div data-width="640" data-height="360"></div>`,
);
const stylesPath = join(project.dir, "styles.css");
writeFileSync(stylesPath, `.card { color: red; }`);
const url = "http://localhost/projects/demo/thumbnail/index.html?t=2&v=test";
await app.request(url);
writeFileSync(stylesPath, `.card { color: rebeccapurple; }`);
await app.request(url);
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
it("uses the adapter-cached project signature for disk reuse and in-flight dedupe", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const getProjectSignature = vi.fn(() => createProjectSignature(project.dir));
adapter.getProjectSignature = getProjectSignature;
let resolve!: (buffer: Buffer) => void;
const generated = new Promise<Buffer>((done) => (resolve = done));
adapter.generateThumbnail = vi.fn(async () => generated);
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
const first = app.request(url);
const duplicate = app.request(url);
await vi.waitFor(() => expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1));
resolve(Buffer.from("shared"));
expect(await (await first).text()).toBe("shared");
expect(await (await duplicate).text()).toBe("shared");
expect(await (await app.request(url)).text()).toBe("shared");
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
expect(getProjectSignature).toHaveBeenCalledTimes(4);
expect(getProjectSignature).toHaveBeenNthCalledWith(1, project.dir);
});
it("does not cache generated pixels when the composition's inputs changed in flight", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const { sceneB } = writeTwoScenes(project.dir);
adapter.generateThumbnail = vi
.fn()
.mockImplementationOnce(async () => {
writeFileSync(sceneB, `<template><div data-composition-id="b">B, edited</div></template>`);
return Buffer.from("rendered-after-change");
})
.mockResolvedValueOnce(Buffer.from("rendered-current"));
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=3";
expect(await (await app.request(url)).text()).toBe("rendered-after-change");
expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
expect(await (await app.request(url)).text()).toBe("rendered-current");
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
it("does not cache a thumbnail rendered while a clip's preview copy is still being made", async () => {
const adapter = createAdapter();
await writeComposition(adapter, 1920, 1080);
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
vi.mocked(proxyActivityMark).mockReturnValueOnce(null).mockReturnValueOnce(null);
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
expect((await app.request(url)).status).toBe(200);
expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
expect((await app.request(url)).status).toBe(200);
expect(existsSync(join(project.dir, ".thumbnails"))).toBe(true);
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
it("does not cache a thumbnail when a preview copy starts or lands during the render", async () => {
const adapter = createAdapter();
await writeComposition(adapter, 1920, 1080);
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
vi.mocked(proxyActivityMark).mockReturnValueOnce("0").mockReturnValueOnce("1");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
expect(
(await app.request("http://localhost/projects/demo/thumbnail/index.html?t=3")).status,
).toBe(200);
expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
});
it("does not cache pixels changed in flight behind a stale adapter signature", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const { sceneB } = writeTwoScenes(project.dir);
const stale = createProjectSignature(project.dir);
adapter.getProjectSignature = () => stale;
adapter.generateThumbnail = vi
.fn()
.mockImplementationOnce(async () => {
writeFileSync(sceneB, `<template><div data-composition-id="b">B, edited</div></template>`);
return Buffer.from("rendered-after-change");
})
.mockResolvedValueOnce(Buffer.from("rendered-again"));
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=3";
expect(await (await app.request(url)).text()).toBe("rendered-after-change");
expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
expect(await (await app.request(url)).text()).toBe("rendered-again");
});
it("keeps changed studio motion separated in the disk cache", async () => {
const adapter = createAdapter();
const project = await adapter.resolveProject("demo");
if (!project) throw new Error("missing project");
const app = new Hono();
registerThumbnailRoutes(app, adapter);
const indexPath = join(project.dir, "index.html");
writeFileSync(indexPath, `<div data-composition-id="main" data-width="640" data-height="360">`);
const motionDir = join(project.dir, ".hyperframes");
mkdirSync(motionDir, { recursive: true });
const motionPath = join(motionDir, "studio-motion.json");
writeFileSync(motionPath, `{"version":1,"motions":[]}`);
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
writeFileSync(
motionPath,
`{"version":1,"motions":[{"kind":"gsap-motion","target":{"sourceFile":"index.html","id":"card"},"start":0,"duration":1,"ease":"power2.out","from":{"y":32},"to":{"y":0}}]}`,
);
await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
});
it("prunes expired and over-budget files without touching protected work", () => {
const cacheDir = mkdtempSync(join(tmpdir(), "hf-thumbnail-cache-test-"));
tempProjectDirs.push(cacheDir);
const expiredPath = join(cacheDir, "expired.jpg");
const protectedPath = join(cacheDir, "protected.jpg");
const overflowPath = join(cacheDir, "overflow.jpg");
writeFileSync(expiredPath, "expired");
writeFileSync(protectedPath, "protected");
writeFileSync(overflowPath, "overflow");
const now = Date.now();
const expiredSeconds = (now - 15 * 24 * 60 * 60 * 1000) / 1000;
utimesSync(expiredPath, expiredSeconds, expiredSeconds);
truncateSync(protectedPath, 400 * 1024 * 1024);
truncateSync(overflowPath, 200 * 1024 * 1024);
pruneThumbnailCache(cacheDir, new Set([protectedPath]), now);
expect(existsSync(expiredPath)).toBe(false);
expect(existsSync(protectedPath)).toBe(true);
expect(existsSync(overflowPath)).toBe(false);
});
});