overlay-factory-worker 0.1.0

package/scripts/ingest.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Ingest assets from ~/Desktop/Automate Editing into public/assets/.
+# Uses Finder via osascript because macOS TCC blocks direct shell reads of ~/Desktop.
+set -euo pipefail
+
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+ASSETS="$REPO/public/assets"
+mkdir -p "$ASSETS/b-roll" "$ASSETS/cards-raw" "$ASSETS/captions" "$ASSETS/inspiration"
+
+copy_folder() { # $1 = AppleScript folder ref, $2 = dest dir
+  osascript <<EOF
+tell application "Finder"
+  set dest to POSIX file "$2" as alias
+  duplicate every file of $1 to dest with replacing
+end tell
+EOF
+}
+
+BASE='folder "Automate Editing" of desktop'
+
+copy_folder "folder \"b-roll\" of $BASE" "$ASSETS/b-roll" >/dev/null
+copy_folder "folder \"what prints?\" of $BASE" "$ASSETS/cards-raw" >/dev/null
+copy_folder "folder \"captions\" of folder \"what prints?\" of $BASE" "$ASSETS/captions" >/dev/null
+osascript >/dev/null <<EOF
+tell application "Finder"
+  set dest to POSIX file "$ASSETS/inspiration" as alias
+  duplicate file "title inspiration.jpg" of $BASE to dest with replacing
+end tell
+EOF
+
+echo "Ingested:"
+echo "  b-roll:   $(ls "$ASSETS/b-roll" | wc -l | tr -d ' ') files"
+echo "  cards:    $(ls "$ASSETS/cards-raw" | grep -ci 'jpe\?g$' || true) images"
+echo "  captions: $(ls "$ASSETS/captions" | wc -l | tr -d ' ') screenshots"

package/scripts/library.ts

@@ -0,0 +1,143 @@
+/**
+ * The What Prints? puzzle library — the cards already written, verified and
+ * rendered on this machine.
+ *
+ * The Overlay Factory's job is to pair a clip with a puzzle, not to make
+ * someone retype a puzzle they already have. episodes/index.json is that
+ * library (31 entries and counting, most from the original caption
+ * screenshots), public/assets/cards holds their rendered PNGs, and
+ * episodes/used.json records which have been posted.
+ *
+ * Selection mirrors scripts/new-episode.ts deliberately: first unused card in
+ * filename order, never one the quality gates retired. Two paths that disagree
+ * about "next" would double-post a card.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(__dirname, "..");
+const EPISODES = join(ROOT, "episodes");
+const CARDS = join(ROOT, "public/assets/cards");
+
+type IndexEntry = {
+  name?: string;
+  language?: string;
+  code?: string;
+  answer?: string;
+  why?: string;
+  caption?: string;
+  card?: string; // e.g. "IMG_4030.jpg" — the SOURCE name, .png once rendered
+  difficulty?: "easy" | "medium" | "hard";
+  retired?: string;
+};
+
+type Used = { cards: Record<string, string>; broll: Record<string, string> };
+
+const readJson = <T>(p: string, fallback: T): T =>
+  existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")) as T) : fallback;
+
+/** index.json stores the source screenshot name; the render is always .png. */
+const asPng = (card: string) => card.replace(/\.(jpe?g|png)$/i, ".png");
+
+export type Puzzle = {
+  /** Card PNG filename — the stable id for a puzzle across both scripts. */
+  key: string;
+  name: string;
+  /** Source, kept so the card can be re-rendered with the series' look. */
+  code: string | null;
+  language: string | null;
+  difficulty: "easy" | "medium" | "hard";
+  answer: string | null;
+  why: string | null;
+  caption: string | null;
+  used: boolean;
+  /** Path under public/, ready for an image layer. */
+  cardRelPath: string;
+};
+
+export const listPuzzles = (): Puzzle[] => {
+  const index = readJson<IndexEntry[]>(join(EPISODES, "index.json"), []);
+  const used = readJson<Used>(join(EPISODES, "used.json"), {
+    cards: {},
+    broll: {},
+  });
+
+  const retired = new Set(
+    index.filter((e) => e.retired && e.card).map((e) => asPng(e.card!)),
+  );
+  const byCard = new Map(
+    index.filter((e) => e.card).map((e) => [asPng(e.card!), e]),
+  );
+
+  // A machine that has never rendered a card has no cards directory at all.
+  // readdirSync throws there, which took down the whole listing — and since
+  // What Prints? is seeded for every account, a new user saw the series and
+  // watched every job fail.
+  if (!existsSync(CARDS)) return [];
+
+  return readdirSync(CARDS)
+    // "--look.png" files are per-look renders of a card that is already in the
+    // library; counting them would double every puzzle and inflate the stock.
+    .filter(
+      (f) => f.endsWith(".png") && !f.endsWith("--look.png") && !retired.has(f),
+    )
+    .sort()
+    .map((key) => {
+      const e = byCard.get(key);
+      return {
+        key,
+        name: e?.name ?? key.replace(/\.png$/, ""),
+        code: e?.code ?? null,
+        language: e?.language ?? null,
+        difficulty: e?.difficulty ?? "medium",
+        answer: e?.answer ?? null,
+        why: e?.why ?? null,
+        caption: e?.caption ?? null,
+        used: Boolean(used.cards[key]),
+        cardRelPath: `assets/cards/${key}`,
+      };
+    });
+};
+
+/**
+ * The next puzzle to post, or a specific one by key.
+ *
+ * Throws rather than silently reusing a card: quietly re-posting a puzzle that
+ * already went out is worse than a failed job with a clear reason.
+ */
+export const pickPuzzle = (
+  key?: string | null,
+  /**
+   * Cards this ACCOUNT has already consumed, from the cloud.
+   *
+   * used.json only knows about this computer, so a second machine on the same
+   * account would pick the same card again and post it twice. The cloud is the
+   * authority; the local file stays as a fast path and an offline fallback.
+   */
+  usedElsewhere: string[] = [],
+): Puzzle => {
+  const all = listPuzzles();
+  if (key) {
+    const found = all.find((p) => p.key === key);
+    if (!found) throw new Error(`No puzzle named ${key} on this computer`);
+    return found;
+  }
+  const alsoUsed = new Set(usedElsewhere);
+  const next = all.find((p) => !p.used && !alsoUsed.has(p.key));
+  if (!next) {
+    throw new Error(
+      all.length === 0
+        ? "No puzzle library on this computer yet. Run: npx tsx scripts/make-card.ts puzzles/*.json"
+        : "Every puzzle in your library has been used — it will write more on its own shortly.",
+    );
+  }
+  return next;
+};
+
+/** Record a puzzle as posted, so the next pick moves on. */
+export const markUsed = (key: string, label: string) => {
+  const file = join(EPISODES, "used.json");
+  const used = readJson<Used>(file, { cards: {}, broll: {} });
+  used.cards[key] = label;
+  writeFileSync(file, JSON.stringify(used, null, 2) + "\n");
+};

package/scripts/look-card.ts

@@ -0,0 +1,107 @@
+/**
+ * Render a puzzle's card with the series' look applied.
+ *
+ * The library cards are baked PNGs, so look values that belong to the CARD —
+ * the code size, the language label, the fill, the corner radius — can't reach
+ * them. Feedback that said "make the code smaller" changed a number that never
+ * touched a pixel, which is worse than not offering the knob at all.
+ *
+ * So when the look differs from the shipped design, the card is re-rendered
+ * for this job from the puzzle's stored code. When it doesn't, the library PNG
+ * is used unchanged and nothing is spent.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { codeToTokens } from "shiki";
+import {
+  CARD_THEME,
+  MAX_COLUMNS,
+  fitScale,
+} from "../src/series/what-prints/codeCardTypes";
+import type { ResolvedLook } from "../src/overlay/look";
+import { DEFAULT_LOOK } from "../src/overlay/look";
+
+const ROOT = join(__dirname, "..");
+const CARDS = join(ROOT, "public/assets/cards");
+
+/** Emoji occupy about 1.8 mono cells — same rule make-card.ts uses. */
+const lineWidth = (line: string) => {
+  const emoji = (line.match(/\p{Extended_Pictographic}/gu) ?? []).length;
+  return line.length - emoji + emoji * 1.8;
+};
+
+const cardDiffersFromDefault = (look: ResolvedLook) =>
+  look.card.codeScale !== DEFAULT_LOOK.card.codeScale ||
+  look.card.showLanguage !== DEFAULT_LOOK.card.showLanguage ||
+  look.card.background !== DEFAULT_LOOK.card.background ||
+  look.card.radiusPct !== DEFAULT_LOOK.card.radiusPct;
+
+/**
+ * Returns a path under public/ for the card to draw — either the library PNG
+ * or a freshly rendered one carrying this look.
+ */
+export const cardForLook = async (opts: {
+  /** Card filename in the library, e.g. "IMG_4032.png". */
+  key: string;
+  /** The puzzle's source, needed only when re-rendering. */
+  code?: string | null;
+  language?: string | null;
+  look: ResolvedLook;
+}): Promise<string> => {
+  const libraryPath = `assets/cards/${opts.key}`;
+  if (!cardDiffersFromDefault(opts.look)) return libraryPath;
+  if (!opts.code) {
+    // A screenshot-only card can't be re-rendered; its own look wins over the
+    // series look rather than failing the job.
+    return libraryPath;
+  }
+
+  const slug = opts.key.replace(/\.png$/, "");
+  const outName = `${slug}--look.png`;
+  const out = join(CARDS, outName);
+
+  const language = opts.language ?? "Python";
+  const widest = Math.max(...opts.code.split("\n").map(lineWidth));
+  // The look's scale rides on top of the fit, so a long snippet still shrinks
+  // to stay inside MAX_COLUMNS and the look only ever scales from there.
+  const codeScale = fitScale(widest) * opts.look.card.codeScale;
+
+  const { tokens } = await codeToTokens(opts.code, {
+    lang: language.toLowerCase() as Parameters<typeof codeToTokens>[1]["lang"],
+    theme: CARD_THEME,
+  });
+  const lines = tokens.map((line) =>
+    line.map((t) => ({ content: t.content, color: t.color ?? "#c5c8d4" })),
+  );
+
+  const props = {
+    language,
+    lines,
+    codeScale,
+    showLanguage: opts.look.card.showLanguage,
+    background: opts.look.card.background,
+    radiusPct: opts.look.card.radiusPct,
+  };
+  const propsFile = join(ROOT, `.look-card-${slug}.json`);
+  writeFileSync(propsFile, JSON.stringify(props));
+  try {
+    execFileSync(
+      "npx",
+      [
+        "remotion", "still", "CodeCard", out,
+        `--props=${propsFile}`,
+        "--image-format=png",
+        "--log=error",
+      ],
+      { cwd: ROOT, stdio: ["ignore", "pipe", "pipe"] },
+    );
+  } finally {
+    execFileSync("rm", ["-f", propsFile]);
+  }
+
+  return existsSync(out) ? `assets/cards/${outName}` : libraryPath;
+};
+
+/** MAX_COLUMNS is re-exported so callers can warn about over-long snippets. */
+export { MAX_COLUMNS, readFileSync };

package/scripts/look-store.ts

@@ -0,0 +1,176 @@
+/**
+ * The stored look for a series, and how feedback changes it.
+ *
+ * Feedback edits PARAMETERS, not code. The model is handed the current look,
+ * the schema's bounds, and the note, and returns a new look — which is then
+ * validated before it can affect a render. A note that asks for something the
+ * parameters can't express comes back unchanged with a reason, which is a much
+ * better failure than silently rendering something unrelated.
+ *
+ * Generated series don't come through here: they're HTML templates, so their
+ * feedback path regenerates the template (see scripts/series.ts).
+ */
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import {
+  DEFAULT_LOOK,
+  TITLE_FAMILIES,
+  lookSchema,
+  resolveLook,
+  type Look,
+} from "../src/overlay/look";
+
+const execFileAsync = promisify(execFile);
+const ROOT = join(__dirname, "..");
+const SERIES_DIR = join(ROOT, "series");
+
+const lookPath = (slug: string) => join(SERIES_DIR, slug, "look.json");
+
+export const readLook = (slug: string): Look => {
+  const p = lookPath(slug);
+  if (!existsSync(p)) return {};
+  try {
+    return lookSchema.parse(JSON.parse(readFileSync(p, "utf8")));
+  } catch {
+    // A look that no longer validates must not break every render — the
+    // shipped design is always a safe answer.
+    return {};
+  }
+};
+
+export const writeLook = (slug: string, look: Look) => {
+  mkdirSync(join(SERIES_DIR, slug), { recursive: true });
+  writeFileSync(lookPath(slug), JSON.stringify(look, null, 2) + "\n");
+};
+
+/**
+ * Apply a note to a series' look.
+ *
+ * Returns the new look plus what the model said it did, so the UI can show
+ * that a note was understood rather than leaving the user guessing why the
+ * picture looks the same.
+ */
+export const applyFeedback = async (opts: {
+  slug: string;
+  feedback: string;
+  /** Families the user uploaded, on top of the built-in list. */
+  customFamilies?: string[];
+}): Promise<{ look: Look; note: string }> => {
+  const current = resolveLook(readLook(opts.slug));
+
+  const prompt = `You are adjusting the look of a short-form video overlay.
+
+The overlay is a title over a code card over a difficulty badge, burned onto
+vertical footage. You cannot rearrange it or add anything — you can only change
+the values below. If the request needs something these values can't express,
+change nothing and say so.
+
+## Current values
+${JSON.stringify(current, null, 2)}
+
+## What each one does, and its limits
+card.widthPct     0.5-0.95  fraction of frame width the card occupies
+card.radiusPct    0-0.12    corner radius as a fraction of card width
+card.background   hex       the card's fill
+card.opacity      0.3-1     1 is solid; lower lets footage through
+card.showLanguage bool      the "Python" label above the snippet
+card.codeScale    0.6-1.4   multiplier on the code type size
+title.family      one of: ${[...TITLE_FAMILIES, ...(opts.customFamilies ?? [])].join(", ")}
+                  — sets BOTH title lines, including the letterforms the dots
+                  are made from
+title.sansSize    60-160    the bold first line
+title.rows        8-24      dot-matrix cap height in cells; MORE = FINER dots
+title.cell        5-20      grid pitch in px; SMALLER = finer dots
+title.gap         0-6       space inside the pitch, so the dot is cell - gap
+title.weight      100-900   stroke thickness of the dot-matrix line
+title.scrim       bool      dark wash behind the title
+meter.show        bool      the difficulty badge
+
+Notes on intent, so the obvious requests land correctly:
+- "smaller code" → lower card.codeScale, not card.widthPct
+- "smaller card" → lower card.widthPct
+- "finer / more dots" → raise title.rows AND lower title.cell together
+- "chunkier dots" → lower title.rows and raise title.cell
+- "thicker letters" → raise title.weight
+- "see through" / "less heavy" → lower card.opacity
+- "serif title" → title.family to Instrument Serif, Fraunces or DM Serif Display
+- a family not on the list can't be used; say so rather than picking a lookalike
+
+## The request
+${opts.feedback}
+
+## Output — JSON and nothing else
+{"look": { ...the FULL new value set... }, "note": "one short sentence on what you changed, or why you couldn't"}`;
+
+  const { stdout } = await execFileAsync(
+    "claude",
+    ["-p", prompt, "--output-format", "text", "--allowedTools", ""],
+    { maxBuffer: 4 * 1024 * 1024, timeout: 5 * 60 * 1000 },
+  );
+
+  const text = stdout.trim();
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start === -1 || end === -1) throw new Error("No JSON in the look response");
+
+  let raw: { look?: unknown; note?: string };
+  try {
+    raw = JSON.parse(text.slice(start, end + 1));
+  } catch (e) {
+    throw new Error(`Look response wasn't valid JSON: ${(e as Error).message}`);
+  }
+
+  // Validated before it can reach a render: an out-of-range value here is the
+  // difference between "the card got smaller" and an unreadable post.
+  const parsed = lookSchema.safeParse(raw.look ?? {});
+  if (!parsed.success) {
+    throw new Error(
+      `That change would go outside what the look allows: ${parsed.error.issues[0]?.message ?? "invalid"}`,
+    );
+  }
+
+  // A family the renderer doesn't have would silently render as a system
+  // fallback, which looks like the change not working.
+  const allowed = new Set<string>([
+    ...TITLE_FAMILIES,
+    ...(opts.customFamilies ?? []),
+  ]);
+  const chosen = parsed.data.title?.family;
+  if (chosen && !allowed.has(chosen)) {
+    throw new Error(
+      `"${chosen}" isn't available. Upload it on the brand page, or pick one of: ${[...allowed].join(", ")}`,
+    );
+  }
+
+  writeLook(opts.slug, parsed.data);
+  return { look: parsed.data, note: raw.note?.slice(0, 300) ?? "Updated." };
+};
+
+/**
+ * Apply an exact change to the look, with no model in the loop.
+ *
+ * Dragging something to a position is not a request to be interpreted — it IS
+ * the value. Sending "move the card to y=1104" through a language model would
+ * be slower, cost a call, and could come back with 1100.
+ */
+export const patchLook = (slug: string, patch: Look): Look => {
+  const current = readLook(slug);
+  const merged: Look = {
+    ...current,
+    card: { ...(current.card ?? {}), ...(patch.card ?? {}) },
+    title: { ...(current.title ?? {}), ...(patch.title ?? {}) },
+    meter: { ...(current.meter ?? {}), ...(patch.meter ?? {}) },
+  };
+  const parsed = lookSchema.safeParse(merged);
+  if (!parsed.success) {
+    throw new Error(
+      `That position is outside what the frame allows: ${parsed.error.issues[0]?.message ?? "invalid"}`,
+    );
+  }
+  writeLook(slug, parsed.data);
+  return parsed.data;
+};
+
+export { DEFAULT_LOOK, resolveLook };

package/scripts/make-card.ts

@@ -0,0 +1,237 @@
+/**
+ * Generate a "What Prints?" code card from a puzzle JSON — no phone screenshot
+ * needed. Highlights the snippet with Shiki, renders the CodeCard composition
+ * to a transparent rounded PNG, and registers it in episodes/{cards,index}.json.
+ *
+ * Usage:
+ *   npx tsx scripts/make-card.ts puzzles/nan-trap.json [more.json ...]
+ *   cat puzzle.json | npx tsx scripts/make-card.ts -
+ *
+ * The snippet is executed and its output checked against "answer" before it
+ * renders, then put through scripts/quality.ts (deterministic? same on every
+ * Python? answerable? not a duplicate?). Either failing stops the render;
+ * --no-verify and --no-gates override.
+ *
+ * A puzzle file is one object or an array of them:
+ *   {
+ *     "slug": "nan-trap",              // -> assets/cards/nan-trap.png
+ *     "name": "Bowser's NaN Trap",
+ *     "language": "Python",            // card label; also picks the grammar
+ *     "lang": "python",                // optional Shiki id override
+ *     "code": "a = float(\"nan\")\n...",
+ *     "answer": "False",
+ *     "why": "...",                    // the explanation for the caption/slide
+ *     "difficulty": "easy|medium|hard",
+ *     "caption": "..."                 // optional IG caption
+ *   }
+ */
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { codeToTokens } from "shiki";
+import { verify } from "./verify";
+import { runGates } from "./quality";
+import {
+  CARD_THEME,
+  MAX_COLUMNS,
+  fitScale,
+} from "../src/series/what-prints/codeCardTypes";
+
+const ROOT = join(import.meta.dirname, "..");
+const CARDS_DIR = join(ROOT, "public/assets/cards");
+const CARDS_JSON = join(ROOT, "episodes/cards.json");
+const INDEX_JSON = join(ROOT, "episodes/index.json");
+const TMP = join(ROOT, ".make-card-props.json");
+
+type CardEntry = { card: string; language: string; code: string };
+
+type IndexEntry = {
+  card: string;
+  episode: number | null;
+  name: string;
+  code: string;
+  answer: string | null;
+  why: string | null;
+  caption: string | null;
+  sourceScreenshots: string[];
+  difficulty: string;
+  concept?: string;
+  generated?: boolean;
+};
+
+type Puzzle = {
+  slug: string;
+  name?: string;
+  language: string;
+  lang?: string;
+  code: string;
+  answer?: string;
+  why?: string;
+  difficulty?: "easy" | "medium" | "hard";
+  caption?: string;
+  concept?: string; // e.g. "mutation-during-iteration" — grouped by report.ts
+  format?: string; // "debate" opts out of output verification
+};
+
+const readJson = (file: string) =>
+  JSON.parse(readFileSync(file, "utf8")) as unknown;
+
+const writeJson = (file: string, value: unknown) =>
+  writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+
+/** Shiki tokens -> the flat {content,color} lines the composition renders. */
+const highlight = async (code: string, lang: string) => {
+  const { tokens } = await codeToTokens(code, {
+    lang: lang as never,
+    theme: CARD_THEME as never,
+  });
+  return tokens.map((line) =>
+    line.map((t) => ({ content: t.content, color: t.color ?? "#c5c8d4" })),
+  );
+};
+
+/** Insert or replace an entry keyed by `card` so re-runs stay idempotent. */
+const upsert = <T extends { card: string }>(list: T[], entry: T) => {
+  const i = list.findIndex((e) => e.card === entry.card);
+  if (i === -1) list.push(entry);
+  else list[i] = { ...list[i], ...entry };
+  return list;
+};
+
+/**
+ * Width of a line in monospace cells. Emoji render wider than one cell in
+ * Roboto Mono's fallback, so they count for ~1.8.
+ */
+const EMOJI =
+  /\p{Extended_Pictographic}(?:️|[\u{1F3FB}-\u{1F3FF}]|‍\p{Extended_Pictographic})*/gu;
+
+const lineWidth = (line: string) => {
+  const emoji = line.match(EMOJI)?.length ?? 0;
+  const rest = [...line.replace(EMOJI, "")].length;
+  return rest + emoji * 1.8;
+};
+
+const makeCard = async (p: Puzzle, skipVerify: boolean, skipGates: boolean) => {
+  if (!p.slug || !p.code || !p.language)
+    throw new Error("puzzle needs slug, language and code");
+
+  // Run it for real. A card that states the wrong output is wrong in public,
+  // so a mismatch stops the render rather than warning about it.
+  if (!skipVerify && p.format !== "debate") {
+    const v = verify(p.code, p.lang ?? p.language.toLowerCase(), p.answer);
+    if (v.status === "mismatch" || v.status === "error")
+      throw new Error(
+        `${p.slug}: the snippet does not print the stated answer.\n` +
+          `  stated: ${JSON.stringify(p.answer)}\n` +
+          `  actual: ${JSON.stringify(v.output)}`,
+      );
+    if (v.status === "skipped")
+      console.warn(`  ! ${p.slug}: not verified — ${v.reason}`);
+    if (v.status === "loose")
+      console.warn(`  ~ ${p.slug}: answer matches only after normalizing`);
+  }
+
+  // Correct isn't the same as fair. These catch cards nobody could answer:
+  // non-deterministic output, interpreter disagreements, duplicates.
+  if (!skipGates) {
+    const failed = runGates({ ...p, card: `${p.slug}.png` }).filter(
+      (g) => !g.pass,
+    );
+    if (failed.length)
+      throw new Error(
+        `${p.slug}: failed ${failed.length} quality gate(s).\n` +
+          failed.map((g) => `  ✗ ${g.gate}: ${g.detail}`).join("\n"),
+      );
+  }
+
+  const widest = Math.max(...p.code.split("\n").map(lineWidth));
+  const codeScale = fitScale(widest);
+  if (codeScale < 1)
+    console.warn(
+      `  ! ${p.slug}: longest line is ${Math.ceil(widest)} cells (max ${MAX_COLUMNS}) — ` +
+        `shrinking type to ${Math.round(codeScale * 100)}%. Shorten it if it reads small.`,
+    );
+
+  const lines = await highlight(p.code, p.lang ?? p.language.toLowerCase());
+  writeJson(TMP, { language: p.language, lines, codeScale });
+
+  const cardFile = `${p.slug}.png`;
+  const out = join(CARDS_DIR, cardFile);
+  mkdirSync(CARDS_DIR, { recursive: true });
+
+  execFileSync(
+    "npx",
+    [
+      "remotion",
+      "still",
+      "CodeCard",
+      out,
+      `--props=${TMP}`,
+      "--image-format=png",
+      "--log=error",
+    ],
+    { cwd: ROOT, stdio: "inherit" },
+  );
+
+  // cards.json: the raw snippet inventory.
+  const cards = readJson(CARDS_JSON) as CardEntry[];
+  writeJson(
+    CARDS_JSON,
+    upsert(cards, { card: cardFile, language: p.language, code: p.code }),
+  );
+
+  // index.json: the episode metadata the caption/answer slides read from.
+  const index = readJson(INDEX_JSON) as IndexEntry[];
+  writeJson(
+    INDEX_JSON,
+    upsert(index, {
+      episode: null,
+      name: p.name ?? p.slug,
+      code: p.code,
+      answer: p.answer ?? null,
+      why: p.why ?? null,
+      caption: p.caption ?? null,
+      sourceScreenshots: [],
+      ...(p.concept ? { concept: p.concept } : {}),
+      ...(p.format ? { format: p.format } : {}),
+      card: cardFile,
+      difficulty: p.difficulty ?? "medium",
+      generated: true,
+    }),
+  );
+
+  console.log(`${cardFile}  (${lines.length} lines, ${p.language})`);
+};
+
+const main = async () => {
+  const argv = process.argv.slice(2);
+  const skipVerify = argv.includes("--no-verify");
+  const skipGates = argv.includes("--no-gates");
+  const args = argv.filter((a) => !a.startsWith("--"));
+  if (!args.length) {
+    console.error("usage: npx tsx scripts/make-card.ts <puzzle.json ...> | -");
+    process.exit(1);
+  }
+
+  const puzzles: Puzzle[] = args.flatMap((a) => {
+    const raw =
+      a === "-"
+        ? (JSON.parse(readFileSync(0, "utf8")) as unknown)
+        : readJson(a);
+    return (Array.isArray(raw) ? raw : [raw]) as Puzzle[];
+  });
+
+  try {
+    for (const p of puzzles) await makeCard(p, skipVerify, skipGates);
+  } finally {
+    if (existsSync(TMP)) rmSync(TMP);
+  }
+};
+
+main();