Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
// @vitest-environment node
import { describe, expect, it, afterEach } from "vitest";
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
gatherAssetRefs,
runAssetImport,
runAssetImportMany,
type AssetImportDeps,
} from "./asset.js";
import { FigmaClientError, readManifest, type FigmaClient } from "@hyperframes/core/figma";
const dirs: string[] = [];
function scratch(): string {
const d = mkdtempSync(join(tmpdir(), "hf-figma-asset-"));
dirs.push(d);
return d;
}
afterEach(() => {
for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
});
function fakeClient(overrides: Partial<FigmaClient> = {}): FigmaClient {
const client: FigmaClient = {
renderNode: () => Promise.resolve({ url: "https://cdn.example/a", ext: "png" }),
renderNodes: () => Promise.resolve([]),
imageFills: () => Promise.resolve(new Map()),
variables: () => Promise.resolve({ variables: {}, variableCollections: {} }),
styles: () => Promise.resolve([]),
nodeTree: () => Promise.resolve({ id: "1:2", name: "n", type: "FRAME" }),
fileVersion: () => Promise.resolve({ version: "7", lastModified: "2026-07-01" }),
...overrides,
};
// Default renderNodes delegates to renderNode (honoring any override) so
// existing single-node tests keep controlling behavior via renderNode.
if (!overrides.renderNodes) {
client.renderNodes = (fileKey, nodeIds, opts) =>
Promise.all(
nodeIds.map((nodeId) =>
client
.renderNode({ fileKey, nodeId }, opts)
.then((r) => ({ nodeId, url: r.url, ext: r.ext })),
),
);
}
return client;
}
const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
function deps(projectDir: string, overrides: Partial<AssetImportDeps> = {}): AssetImportDeps {
return {
projectDir,
client: fakeClient(),
download: () => Promise.resolve(PNG_BYTES),
...overrides,
};
}
describe("runAssetImport", () => {
it("freezes the render, appends a manifest record with provenance, returns a snippet", async () => {
const dir = scratch();
const out = await runAssetImport(
"https://www.figma.com/design/FILEKEY/T?node-id=1-2",
{ format: "png" },
deps(dir),
);
expect(out.record.provenance).toMatchObject({
source: "figma",
fileKey: "FILEKEY",
nodeId: "1:2",
version: "7",
format: "png",
});
expect(out.snippet.html).toContain("<img");
const frozen = readFileSync(join(dir, out.record.path));
expect(Array.from(frozen)).toEqual(Array.from(PNG_BYTES));
const manifest = readFileSync(join(dir, ".media", "manifest.jsonl"), "utf8");
expect(manifest).toContain('"fileKey":"FILEKEY"');
});
it("sanitizes svg output before freezing", async () => {
const dir = scratch();
const dirty = `<svg><script>evil()</script><rect width="1"/></svg>`;
const out = await runAssetImport(
"FILEKEY:1-2",
{ format: "svg" },
deps(dir, {
client: fakeClient({
renderNode: () => Promise.resolve({ url: "https://cdn.example/a", ext: "svg" }),
}),
download: () => Promise.resolve(new TextEncoder().encode(dirty)),
}),
);
const frozen = readFileSync(join(dir, out.record.path), "utf8");
expect(frozen).not.toContain("script");
expect(frozen).toContain("<rect");
});
it("reuses on identical version, re-imports when the file version moved on", async () => {
const dir = scratch();
const importPng = (over?: Partial<AssetImportDeps>) =>
runAssetImport("FILEKEY:1-2", { format: "png" }, deps(dir, over));
const first = await importPng();
const sameVersion = await importPng();
expect(sameVersion.record.id).toBe(first.record.id);
expect(sameVersion.reused).toBe(true);
const bumped = await importPng({
client: fakeClient({
fileVersion: () => Promise.resolve({ version: "8", lastModified: "2026-07-02" }),
}),
});
expect(bumped.reused).toBe(false);
expect(bumped.record.id).not.toBe(first.record.id);
});
it("rejects a ref without a node id", async () => {
await expect(runAssetImport("FILEKEYONLY", { format: "png" }, deps(scratch()))).rejects.toThrow(
/node/i,
);
});
it("records description + entity and regenerates .media/index.md", async () => {
const dir = scratch();
const out = await runAssetImport(
"KEY:1-2",
{ format: "png", description: "hero illustration", entity: "Acme hero" },
deps(dir),
);
expect(out.record.description).toBe("hero illustration");
expect(out.record.entity).toBe("Acme hero");
expect(out.snippet.html).toContain('alt="hero illustration"');
const index = readFileSync(join(dir, ".media", "index.md"), "utf8");
expect(index).toContain("hero illustration");
expect(index).toContain(out.record.id);
});
it("applies --description/--entity on a reuse hit instead of dropping them", async () => {
const dir = scratch();
const first = await runAssetImport("KEY:1-2", { format: "png" }, deps(dir));
expect(first.record.description).toBeUndefined();
const again = await runAssetImport(
"KEY:1-2",
{ format: "png", description: "Acme logo", entity: "Acme logo" },
deps(dir),
);
expect(again.reused).toBe(true);
expect(again.record.description).toBe("Acme logo");
expect(again.snippet.html).toContain('alt="Acme logo"');
const index = readFileSync(join(dir, ".media", "index.md"), "utf8");
expect(index).toContain("Acme logo");
expect(index).not.toContain("image_002");
});
it("batches many nodes into ONE renderNodes call and freezes each", async () => {
const dir = scratch();
let renderNodesCalls = 0;
let batchSize = 0;
const batchClient = fakeClient({
renderNodes: (fileKey, nodeIds, opts) => {
renderNodesCalls += 1;
batchSize = nodeIds.length;
return Promise.resolve(
nodeIds.map((nodeId) => ({ nodeId, url: `https://cdn/${nodeId}`, ext: opts.format })),
);
},
});
const results = await runAssetImportMany(
["KEY:1-2", "KEY:3-4", "KEY:5-6"],
{ format: "png" },
deps(dir, { client: batchClient }),
);
expect(results).toHaveLength(3);
expect(results.every((r) => !r.reused)).toBe(true);
expect(renderNodesCalls).toBe(1); // one REST call for all three
expect(batchSize).toBe(3);
// distinct frozen files, all recorded
expect(new Set(results.map((r) => r.record.id)).size).toBe(3);
});
it.each([
["KEY:1-2", "KEY:1-2", "KEY:3-4", "KEY:1-2"],
["KEY:1-2", "https://www.figma.com/design/KEY/F?node-id=1-2", "KEY:3-4", "KEY:1:2"],
])("imports each normalized node once for %j", async (...refs) => {
const dir = scratch();
const requests: string[][] = [];
let downloads = 0;
const importDeps = deps(dir, {
client: fakeClient({
renderNodes: (_fileKey, nodeIds, opts) => {
requests.push([...nodeIds]);
return Promise.resolve(
nodeIds.map((nodeId) => ({ nodeId, url: `https://cdn/${nodeId}`, ext: opts.format })),
);
},
}),
download: async () => {
downloads += 1;
return PNG_BYTES;
},
});
const results = await runAssetImportMany(refs, { format: "png" }, importDeps);
expect(requests).toEqual([["1:2", "3:4"]]);
expect(downloads).toBe(2);
expect(results.map((r) => r.record.id)).toEqual([
"image_001",
"image_001",
"image_002",
"image_001",
]);
expect(results.map((r) => r.reused)).toEqual([false, true, false, true]);
expect(readManifest(dir)).toHaveLength(2);
const repeated = await runAssetImportMany(refs, { format: "png" }, importDeps);
expect(repeated.every((r) => r.reused)).toBe(true);
expect(requests).toHaveLength(1);
expect(downloads).toBe(2);
});
it("imports one missing node among duplicated cached and missing references", async () => {
const dir = scratch();
const cached = await runAssetImport("KEY:1-2", { format: "png" }, deps(dir));
const requests: string[][] = [];
const results = await runAssetImportMany(
["KEY:1-2", "KEY:3-4", "KEY:1:2", "KEY:3:4"],
{ format: "png", description: "Updated" },
deps(dir, {
client: fakeClient({
renderNodes: (_fileKey, nodeIds) => {
requests.push([...nodeIds]);
return Promise.resolve(
nodeIds.map((nodeId) => ({ nodeId, url: `https://cdn/${nodeId}`, ext: "png" })),
);
},
}),
}),
);
expect(requests).toEqual([["3:4"]]);
expect(results.map((r) => r.record.id)).toEqual([
cached.record.id,
"image_002",
cached.record.id,
"image_002",
]);
expect(results.map((r) => r.reused)).toEqual([true, false, true, true]);
expect(results.every((r) => r.record.description === "Updated")).toBe(true);
expect(readManifest(dir)).toHaveLength(2);
});
it("records one completed duplicate node when a later batch node fails", async () => {
const dir = scratch();
let downloads = 0;
await expect(
runAssetImportMany(
["KEY:1-2", "KEY:1:2", "KEY:3-4"],
{ format: "png" },
deps(dir, {
client: fakeClient({
renderNodes: (_fileKey, nodeIds) =>
Promise.resolve(
nodeIds.map((nodeId) => ({
nodeId,
url: nodeId === "1:2" ? "https://cdn/1" : null,
ext: "png",
})),
),
}),
download: async () => {
downloads += 1;
return PNG_BYTES;
},
}),
),
).rejects.toMatchObject({ code: "RENDER_FAILED", endpoint: "images" });
expect(downloads).toBe(1);
expect(readManifest(dir)).toHaveLength(1);
expect(readFileSync(join(dir, ".media", "index.md"), "utf8")).toContain("1 asset");
});
it("labels a batch-miss RENDER_FAILED with the images endpoint (telemetry parity with client.ts)", async () => {
const dir = scratch();
const missClient = fakeClient({
renderNodes: (fileKey, nodeIds) =>
Promise.resolve(nodeIds.map((nodeId) => ({ nodeId, url: null, ext: "png" }))),
});
const err = await runAssetImportMany(
["KEY:1-2"],
{ format: "png" },
deps(dir, { client: missClient }),
).catch((e: unknown) => e);
expect(err).toBeInstanceOf(FigmaClientError);
if (err instanceof FigmaClientError) {
expect(err.code).toBe("RENDER_FAILED");
expect(err.endpoint).toBe("images");
}
});
it("gatherAssetRefs splits bare comma-joined ids but keeps URLs whole", () => {
// bare tokens comma-split
expect(gatherAssetRefs(["KEY:1-2,KEY:3-4"])).toEqual(["KEY:1-2", "KEY:3-4"]);
// space-separated positionals preserved
expect(gatherAssetRefs(["KEY:1-2", "KEY:3-4"])).toEqual(["KEY:1-2", "KEY:3-4"]);
// a URL with a comma in its query is NOT torn apart
const url = "https://www.figma.com/design/KEY/F?node-id=1:2,3:4";
expect(gatherAssetRefs([url])).toEqual([url]);
// mixed: URL stays whole, bare token splits
expect(gatherAssetRefs([url, "KEY:5-6,KEY:7-8"])).toEqual([url, "KEY:5-6", "KEY:7-8"]);
});
it("splits comma-joined refs and rejects a cross-file batch", async () => {
const dir = scratch();
await expect(
runAssetImportMany(["KEY:1-2", "OTHER:3-4"], { format: "png" }, deps(dir)),
).rejects.toThrow(/share a fileKey/);
});
it("reuses against ANY matching tuple, not just the oldest row", async () => {
const dir = scratch();
await runAssetImport("KEY:1-2", { format: "svg" }, deps(dir)); // image_001 (svg)
const png = await runAssetImport("KEY:1-2", { format: "png" }, deps(dir)); // image_002
expect(png.reused).toBe(false);
const pngAgain = await runAssetImport("KEY:1-2", { format: "png" }, deps(dir));
expect(pngAgain.reused).toBe(true);
expect(pngAgain.record.id).toBe(png.record.id);
});
it("flattens whitespace in descriptions so index.md rows stay single-line", async () => {
const dir = scratch();
const out = await runAssetImport(
"KEY:1-2",
{ format: "png", description: "line one\nline two" },
deps(dir),
);
expect(out.record.description).toBe("line one line two");
});
});