Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* Generate labeled contact sheet grids from images.
*
* Stitches images into a numbered grid with cell labels.
* Saves 50-65% tokens vs. AI agents reading images individually.
*/
import type { OverlayOptions } from "sharp";
import { readdirSync, readFileSync, unlinkSync, existsSync } from "node:fs";
import { loadSharp } from "../utils/optionalPackages.js";
import { writeCaptureFileSync } from "./captureFile.js";
import { join, extname, basename, dirname } from "node:path";
interface ContactSheetOptions {
cols?: number;
maxImages?: number;
padding?: number;
labelMode?: "index" | "filename" | "custom";
labels?: string[];
quality?: number;
/** Target width per cell in pixels (default: 600) */
cellWidth?: number;
/** Cooperative boundary checked before starting each native Sharp page. */
remainingMs?: () => number;
}
/**
* Create a contact sheet from a list of image paths.
* Returns the output file path, or null if no images.
*/
export async function createContactSheet(
imagePaths: string[],
outputPath: string,
opts: ContactSheetOptions = {},
): Promise<string | null> {
const {
cols = 3,
maxImages = 16,
padding = 4,
labelMode = "index",
labels,
quality = 88,
cellWidth = 600,
} = opts;
if ((opts.remainingMs?.() ?? 1) <= 0) return null;
const files = imagePaths.slice(0, maxImages);
if (files.length === 0) return null;
const sharp = await loadSharp("contact sheets");
// Read first image to determine aspect ratio
const firstMeta = await sharp(files[0]!).metadata();
const srcW = firstMeta.width || 1920;
const srcH = firstMeta.height || 1080;
// Scale to target cell width, maintain aspect ratio
const scale = cellWidth / srcW;
const cellW = cellWidth;
const cellH = Math.round(srcH * scale);
const rows = Math.ceil(files.length / cols);
const labelH = 26;
const totalW = cols * cellW + (cols + 1) * padding;
const totalH = rows * (cellH + labelH) + (rows + 1) * padding;
const overlays: OverlayOptions[] = [];
for (let i = 0; i < files.length; i++) {
const col = i % cols;
const row = Math.floor(i / cols);
const x = padding + col * (cellW + padding);
const y = padding + row * (cellH + labelH + padding);
// Resize image to cell size — contain keeps full image visible (no cropping)
const resized = await sharp(files[i]!)
.resize(cellW, cellH, { fit: "contain", background: { r: 26, g: 26, b: 26 } })
.toBuffer();
overlays.push({ input: resized, left: x, top: y + labelH });
// Label text
let labelText = `${i + 1}`;
if (labelMode === "filename") {
labelText = `${i + 1}. ${basename(files[i]!).replace(extname(files[i]!), "")}`;
} else if (labelMode === "custom" && labels?.[i]) {
labelText = `${i + 1}. ${labels[i]}`;
}
// Truncate label to fit cell
if (labelText.length > 60) labelText = labelText.slice(0, 57) + "...";
const labelSvg = Buffer.from(
`<svg width="${cellW}" height="${labelH}">` +
`<rect width="${cellW}" height="${labelH}" fill="#1a1a1a"/>` +
`<text x="8" y="18" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#ffffff">${escapeXml(labelText)}</text>` +
`</svg>`,
);
overlays.push({ input: labelSvg, left: x, top: y });
}
const sheet = sharp({
create: {
width: totalW,
height: totalH,
channels: 3,
background: { r: 26, g: 26, b: 26 },
},
}).composite(overlays);
// Encode to a buffer and write through the capture writer rather than
// `toFile`, which opens the path itself and would follow a planted link.
const encoded =
extname(outputPath).toLowerCase() === ".png"
? await sheet.png().toBuffer()
: await sheet.jpeg({ quality }).toBuffer();
writeCaptureFileSync(outputPath, encoded);
return outputPath;
}
function escapeXml(s: string): string {
return s
.replace(/&/g, "&")
.replace(/</g, "<")
.replace(/>/g, ">")
.replace(/"/g, """)
.replace(/'/g, "'");
}
/**
* Split imagePaths into pages of `pageSize`, write one contact sheet per page.
* Output files: basePath → base-1.jpg, base-2.jpg, ...
* Returns the list of written file paths (empty if no images).
*/
// fallow-ignore-next-line complexity
async function createContactSheetPages(
imagePaths: string[],
outputBasePath: string,
opts: ContactSheetOptions & { pageSize?: number } = {},
labelOffset = 0,
customLabels?: string[],
): Promise<string[]> {
if (imagePaths.length === 0) return [];
const { pageSize = imagePaths.length, remainingMs, ...sheetOpts } = opts;
const ext = outputBasePath.match(/\.[^.]+$/)?.[0] ?? ".jpg";
const base = outputBasePath.slice(0, -ext.length);
const pages = Math.ceil(imagePaths.length / pageSize);
const results: string[] = [];
for (let p = 0; p < pages; p++) {
if ((remainingMs?.() ?? 1) <= 0) break;
const chunk = imagePaths.slice(p * pageSize, (p + 1) * pageSize);
const chunkLabels = customLabels?.slice(p * pageSize, (p + 1) * pageSize);
const outPath = pages === 1 ? outputBasePath : `${base}-${p + 1}${ext}`;
const labelsForChunk = chunkLabels
? { labelMode: "custom" as const, labels: chunkLabels }
: sheetOpts.labelMode === "filename"
? { labelMode: "filename" as const }
: { labelMode: "index" as const };
const written = await createContactSheet(chunk, outPath, {
...sheetOpts,
...labelsForChunk,
maxImages: chunk.length,
});
if (written) results.push(written);
void labelOffset; // used by callers that pre-compute labels
}
return results;
}
/**
* Contact sheet for scroll screenshots. Paginated — all screenshots covered.
* Labels: "1. 0% scroll", "2. 23% scroll", etc.
* Returns array of written file paths.
*/
export async function createScrollContactSheet(
screenshotsDir: string,
outputPath: string,
budget: Pick<ContactSheetOptions, "remainingMs"> = {},
): Promise<string[]> {
if (!existsSync(screenshotsDir)) return [];
const scrollFiles = readdirSync(screenshotsDir)
.filter((f) => f.startsWith("scroll-") && f.endsWith(".png"))
.sort();
if (scrollFiles.length === 0) return [];
const paths = scrollFiles.map((f) => join(screenshotsDir, f));
const labels = scrollFiles.map((f) => {
const m = f.match(/scroll-(\d+)\.png/);
return m ? `${m[1]}% scroll` : f;
});
// 3 cols max for readability; 9 per page (3×3) so cells stay large enough to read
return createContactSheetPages(
paths,
outputPath,
{ cols: 3, cellWidth: 600, pageSize: 9, ...budget },
0,
labels,
);
}
/**
* Contact sheet for snapshot frames. All frames covered across pages.
* Labels: "1. 1.0s", "2. 3.0s", etc.
* Returns array of written file paths.
*/
export async function createSnapshotContactSheet(
snapshotsDir: string,
outputPath: string,
budget: Pick<ContactSheetOptions, "remainingMs"> = {},
): Promise<string[]> {
if (!existsSync(snapshotsDir)) return [];
const snapshotFiles = readdirSync(snapshotsDir)
.filter((f) => f.startsWith("frame-") && f.endsWith(".png"))
.sort();
if (snapshotFiles.length === 0) return [];
const paths = snapshotFiles.map((f) => join(snapshotsDir, f));
const labels = snapshotFiles.map((f) => {
const m = f.match(/at-([\d.]+)s/);
return m ? `${m[1]}s` : f;
});
// 3 cols, 9 per page (3×3)
return createContactSheetPages(
paths,
outputPath,
{ cols: 3, cellWidth: 600, pageSize: 9, ...budget },
0,
labels,
);
}
/**
* Contact sheet for captured assets. Paginated — all assets covered.
* Labels: "1. filename"
* Returns array of written file paths.
*/
export async function createAssetContactSheet(
assetsDir: string,
outputPath: string,
budget: Pick<ContactSheetOptions, "remainingMs"> = {},
): Promise<string[]> {
if (!existsSync(assetsDir)) return [];
const imageExts = new Set([".png", ".jpg", ".jpeg", ".webp"]);
const assetFiles = readdirSync(assetsDir)
.filter((f) => imageExts.has(extname(f).toLowerCase()) && !f.includes("contact-sheet"))
.sort();
if (assetFiles.length === 0) return [];
const paths = assetFiles.map((f) => join(assetsDir, f));
// 4 cols, 12 per page (4×3) — covers all assets across as many pages as needed
return createContactSheetPages(paths, outputPath, {
cols: 4,
cellWidth: 480,
labelMode: "filename",
pageSize: 12,
...budget,
});
}
/**
* Contact sheet for SVGs — renders each SVG to a thumbnail PNG, then grids them.
* Sharp supports SVG input natively, so no browser needed.
* Labels: "1. filename"
*
* Accepts one or two directories: the primary svgs/ subdir and optionally the
* parent assets/ root (for external SVGs downloaded as <img src="*.svg">).
* Files are deduplicated by basename so duplicates across dirs are collapsed.
*/
// fallow-ignore-next-line complexity
export async function createSvgContactSheet(
svgsDir: string,
outputPath: string,
assetsRootDir?: string,
budget: Pick<ContactSheetOptions, "remainingMs"> = {},
): Promise<string[]> {
const dirsToScan = [svgsDir, assetsRootDir].filter(
(d): d is string => d !== undefined && existsSync(d),
);
if (dirsToScan.length === 0) return [];
const seen = new Set<string>();
const svgPaths: string[] = [];
for (const dir of dirsToScan) {
for (const f of readdirSync(dir)
.filter((f) => f.endsWith(".svg"))
.sort()) {
if (!seen.has(f)) {
seen.add(f);
svgPaths.push(join(dir, f));
}
}
}
if (svgPaths.length === 0) return [];
const sharp = await loadSharp("contact sheets");
const svgFileNames = svgPaths.map((p) => p.split("/").pop()!);
// Render ALL SVGs to PNG thumbnails first, then paginate the sheets
const thumbSize = 200;
const tmpDir = dirname(outputPath);
const tmpPaths: string[] = [];
const labels: string[] = [];
for (let i = 0; i < svgPaths.length; i++) {
if ((budget.remainingMs?.() ?? 1) <= 0) break;
const svgPath = svgPaths[i]!;
const tmpPath = join(tmpDir, `.thumb-${i}.png`);
try {
const svgBuf = readFileSync(svgPath);
const thumb = await sharp(svgBuf)
.resize(thumbSize, thumbSize, {
fit: "contain",
background: { r: 245, g: 245, b: 245, alpha: 1 },
})
.flatten({ background: { r: 245, g: 245, b: 245 } })
.png()
.toBuffer();
writeCaptureFileSync(tmpPath, thumb);
tmpPaths.push(tmpPath);
labels.push(svgFileNames[i]!.replace(".svg", ""));
} catch {
// SVG might be malformed — skip
}
}
if (tmpPaths.length === 0) return [];
// 5 cols, 15 per page (5×3) — all SVGs covered across pages
let results: string[] = [];
try {
results = await createContactSheetPages(
tmpPaths,
outputPath,
{
cols: 5,
cellWidth: thumbSize,
pageSize: 15,
...budget,
},
0,
labels,
);
} finally {
for (const tmp of tmpPaths) {
try {
unlinkSync(tmp);
} catch {
/* best effort */
}
}
}
return results;
}