feat(docs): add template preview generation script (#159)

## What

Add a script that uses `@hyperframes/producer` to render PNG thumbnails of each built-in template. Output goes to `docs/images/templates/`.

## Why

User feedback: "I would have loved more visual examples of what's actually possible. I had to scaffold every template just to see what they look like." This is the foundation for a visual template gallery in the docs.

## How

- New `scripts/generate-template-previews.ts` uses the producer's `createFileServer` + `createCaptureSession` + `captureFrame` APIs — hyperframes renders its own templates
- Patches out `__VIDEO_SRC__` placeholders (same logic as `init.ts`) so templates render without a video file
- Captures a frame at t=2s for each template (skips `blank` — it's just empty scaffolding)
- Handles varying dimensions (vignelli is 1080x1920 portrait)
- Adds `pnpm generate:previews` npm script

## Test plan

- [x] `pnpm generate:previews` generates 8 PNGs in `docs/images/templates/`
- [x] Each PNG is visually correct (verified by viewing)
- [x] `--only <template>` flag works for single template generation

package.json

@@ -24,6 +24,7 @@
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "knip": "knip",
+    "generate:previews": "tsx scripts/generate-template-previews.ts",
     "prepare": "test -d .git && lefthook install || true"
   },
   "devDependencies": {

scripts/generate-template-previews.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env tsx
+/**
+ * Generate Template Preview Images
+ *
+ * Uses @hyperframes/producer to render PNG thumbnails of each built-in template.
+ * Output: docs/images/templates/<id>.png
+ *
+ * Usage:
+ *   pnpm generate:previews              # all templates
+ *   pnpm generate:previews -- --only warm-grain
+ */
+
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  cpSync,
+  rmSync,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import {
+  createFileServer,
+  createCaptureSession,
+  initializeSession,
+  captureFrame,
+  getCompositionDuration,
+  closeCaptureSession,
+} from "@hyperframes/producer";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
+const bundledTemplatesDir = resolve(repoRoot, "packages/cli/src/templates");
+const examplesDir = resolve(repoRoot, "examples");
+const outputDir = resolve(repoRoot, "docs/images/templates");
+
+// Point the producer at the monorepo's built core manifest
+if (!process.env.PRODUCER_HYPERFRAME_MANIFEST_PATH) {
+  process.env.PRODUCER_HYPERFRAME_MANIFEST_PATH = resolve(
+    repoRoot,
+    "packages/core/dist/hyperframe.manifest.json",
+  );
+}
+
+// Templates to skip — blank is just empty scaffolding (black screen without a video)
+const SKIP_TEMPLATES = new Set(["blank"]);
+
+// Template metadata: dimensions and best capture time for visual interest
+const TEMPLATE_CONFIG: Record<string, { width: number; height: number; captureTime: number }> = {
+  "warm-grain": { width: 1920, height: 1080, captureTime: 2.0 },
+  "play-mode": { width: 1920, height: 1080, captureTime: 2.0 },
+  "swiss-grid": { width: 1920, height: 1080, captureTime: 2.0 },
+  vignelli: { width: 1080, height: 1920, captureTime: 2.0 },
+  "decision-tree": { width: 1920, height: 1080, captureTime: 2.0 },
+  "kinetic-type": { width: 1920, height: 1080, captureTime: 2.0 },
+  "product-promo": { width: 1920, height: 1080, captureTime: 2.0 },
+  "nyt-graph": { width: 1920, height: 1080, captureTime: 2.0 },
+};
+
+/**
+ * Patch template HTML: remove __VIDEO_SRC__ placeholders and set duration.
+ * Same logic as init.ts patchVideoSrc() with no video file.
+ */
+function patchTemplateHtml(dir: string, durationSeconds: number): void {
+  const htmlFiles = readdirSync(dir, { withFileTypes: true, recursive: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".html"))
+    .map((e) => join(e.parentPath ?? e.path, e.name));
+
+  for (const file of htmlFiles) {
+    let content = readFileSync(file, "utf-8");
+    // Remove video/audio elements with placeholder src
+    content = content.replace(/<video[^>]*src="__VIDEO_SRC__"[^>]*>[\s\S]*?<\/video>/g, "");
+    content = content.replace(/<video[^>]*src="__VIDEO_SRC__"[^>]*>/g, "");
+    content = content.replace(/<audio[^>]*src="__VIDEO_SRC__"[^>]*>[\s\S]*?<\/audio>/g, "");
+    content = content.replace(/<audio[^>]*src="__VIDEO_SRC__"[^>]*>/g, "");
+    const dur = String(Math.round(durationSeconds * 100) / 100);
+    content = content.replaceAll("__VIDEO_DURATION__", dur);
+    writeFileSync(file, content, "utf-8");
+  }
+}
+
+function parseArgs(): { only: string | null } {
+  let only: string | null = null;
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === "--only" && process.argv[i + 1]) {
+      i++;
+      only = process.argv[i] ?? null;
+    }
+  }
+  return { only };
+}
+
+/** Resolve the on-disk directory for a template (bundled or examples). */
+function resolveTemplateDir(templateId: string): string | null {
+  const bundled = join(bundledTemplatesDir, templateId);
+  if (existsSync(join(bundled, "index.html"))) return bundled;
+  const example = join(examplesDir, templateId);
+  if (existsSync(join(example, "index.html"))) return example;
+  return null;
+}
+
+function discoverTemplates(only: string | null): string[] {
+  const seen = new Set<string>();
+  const all: string[] = [];
+
+  // Scan bundled templates
+  for (const dir of [bundledTemplatesDir, examplesDir]) {
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (
+        e.isDirectory() &&
+        e.name !== "_shared" &&
+        !SKIP_TEMPLATES.has(e.name) &&
+        !seen.has(e.name) &&
+        existsSync(join(dir, e.name, "index.html"))
+      ) {
+        seen.add(e.name);
+        all.push(e.name);
+      }
+    }
+  }
+
+  if (only) {
+    const match = all.find((t) => t === only);
+    if (!match) {
+      console.error(`Template "${only}" not found. Available: ${all.join(", ")}`);
+      process.exit(1);
+    }
+    return [match];
+  }
+  return all;
+}
+
+async function generatePreview(templateId: string): Promise<void> {
+  const config = TEMPLATE_CONFIG[templateId] ?? {
+    width: 1920,
+    height: 1080,
+    captureTime: 2.0,
+  };
+
+  // Copy template to temp dir
+  const tmpDir = join(tmpdir(), `hf-preview-${templateId}-${Date.now()}`);
+  mkdirSync(tmpDir, { recursive: true });
+
+  const templateSrc = resolveTemplateDir(templateId);
+  if (!templateSrc) throw new Error(`Template directory not found for "${templateId}"`);
+  cpSync(templateSrc, tmpDir, { recursive: true });
+
+  // Patch out video/audio placeholders, set 10s duration
+  patchTemplateHtml(tmpDir, 10);
+
+  const fileServer = await createFileServer({ projectDir: tmpDir, port: 0 });
+
+  try {
+    const framesDir = join(tmpDir, "_frames");
+    mkdirSync(framesDir, { recursive: true });
+
+    const session = await createCaptureSession(fileServer.url, framesDir, {
+      width: config.width,
+      height: config.height,
+      fps: 30,
+      format: "png",
+    });
+
+    await initializeSession(session);
+
+    // Query actual duration in case template declares something different
+    let duration: number;
+    try {
+      duration = await getCompositionDuration(session);
+    } catch {
+      duration = 10;
+    }
+
+    // Capture at the configured time, clamped to composition duration
+    const captureTime = Math.min(config.captureTime, duration * 0.8);
+    const result = await captureFrame(session, 0, captureTime);
+
+    // Copy to output
+    const outPath = join(outputDir, `${templateId}.png`);
+    cpSync(result.path, outPath);
+
+    console.log(
+      `  ✓ ${templateId} → ${outPath} (${config.width}x${config.height} @ ${captureTime.toFixed(1)}s, ${result.captureTimeMs}ms)`,
+    );
+
+    await closeCaptureSession(session);
+  } finally {
+    fileServer.close();
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+async function main(): Promise<void> {
+  const { only } = parseArgs();
+  const templates = discoverTemplates(only);
+
+  console.log(`Generating previews for ${templates.length} templates...\n`);
+
+  mkdirSync(outputDir, { recursive: true });
+
+  for (const templateId of templates) {
+    try {
+      await generatePreview(templateId);
+    } catch (err) {
+      console.error(`  ✗ ${templateId}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
+  console.log(`\nDone. Output: ${outputDir}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});