overlay-factory-worker 0.1.0

package/scripts/overlay-worker.ts

@@ -0,0 +1,1119 @@
+/**
+ * Overlay Factory worker.
+ *
+ * Polls Goose Tools for overlay jobs, renders them here, uploads the result.
+ * The render needs Remotion and ffmpeg, which is exactly why it can't run in a
+ * serverless function — this machine is the renderer.
+ *
+ *   npm run overlay:worker
+ *
+ * The token is the same one the Carousel Maker worker uses — one connected
+ * computer serves every Goose Tools worker — so this reads ~/.goosetools/env,
+ * where that worker's installer already saved it. Set OVERLAY_WORKER_TOKEN to
+ * override, or get a fresh token from /dashboard/overlay.
+ */
+import { upload } from "@vercel/blob/client";
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import sharp from "sharp";
+import { overlaySchema } from "../src/overlay/types";
+import { cardBox } from "../src/overlay/cardLayout";
+import { renderOverlay } from "./render-overlay";
+import {
+  generateSeries,
+  generateSingle,
+  sweepSingles,
+  readSeriesSpec,
+  renderSeriesPreview,
+  seriesLayers,
+  type Brand,
+} from "./series";
+import {
+  markEpisodeUsed,
+  nextEpisode,
+  restock,
+  stockCount,
+} from "./stock";
+// Only the functions — library exports its own Puzzle type, and the one in
+// this file means something different (a typed-in one-off, not a library card).
+import { listPuzzles, markUsed, pickPuzzle } from "./library";
+import { applyFeedback, patchLook, readLook, resolveLook } from "./look-store";
+import { LOOK_BOUNDS } from "../src/overlay/look";
+import { cardForLook } from "./look-card";
+import { resolveCustomFonts, type ResolvedFont } from "./custom-fonts";
+import { resolveFieldImages } from "./field-images";
+import { autoRestock, whatPrintsRestock } from "./wp-restock";
+import { ensureStateLinks } from "./state-dir";
+
+// Installed from npm, the writable directories under ROOT are symlinks into
+// ~/.goosetools/overlay. Re-made on every start: `update` reinstalls the
+// package directory and the previous run's links go with it. No-op in a
+// checkout, where state has always lived in the repo. First thing, before
+// anything reads or writes through one of those paths.
+ensureStateLinks();
+
+/**
+ * Where the Goose Tools installer keeps this machine's worker credentials.
+ * Reading it means the usual case needs no environment variables at all.
+ */
+const readSharedEnv = (): Record<string, string> => {
+  const file = join(homedir(), ".goosetools", "env");
+  if (!existsSync(file)) return {};
+  const out: Record<string, string> = {};
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    const m = line.match(/^\s*([A-Z_]+)\s*=\s*(.*)$/);
+    if (m) out[m[1]] = m[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+};
+
+const shared = readSharedEnv();
+const BASE_URL =
+  process.env.GOOSE_TOOLS_URL ?? shared.GOOSETOOLS_URL ?? "https://goosetools.com";
+const TOKEN = process.env.OVERLAY_WORKER_TOKEN ?? shared.WORKER_TOKEN;
+/**
+ * How long to wait when there was nothing to do — adaptive.
+ *
+ * The idle interval is the floor on how long ANY tap waits before this machine
+ * even hears about it, so while someone is actually working it has to be
+ * short: at 30s a preview redraw spent most of its life queued, which is what
+ * made dragging feel broken rather than slow.
+ *
+ * But most of the day nobody is posting, and asking every 4s around the clock
+ * is ~20,000 requests a day to catch a few minutes of activity. So it stays
+ * quick for a couple of minutes after the last job and then backs off.
+ */
+const POLL_FAST_MS = 3_000;
+// 60s, not 10s: the 10s idle poll (with three sibling workers doing the
+// same) kept the prod database awake around the clock and burned its whole
+// compute quota. A first tap after a quiet spell now waits up to a minute;
+// everything after it rides the fast lane.
+const POLL_IDLE_MS = 60_000;
+const STAY_FAST_MS = 2 * 60 * 1000;
+
+/** When the last job finished — the thing "are we still working?" means. */
+let lastJobAt = 0;
+const pollDelay = () =>
+  Date.now() - lastJobAt < STAY_FAST_MS ? POLL_FAST_MS : POLL_IDLE_MS;
+
+if (!TOKEN) {
+  console.error(
+    "No worker token. Either connect this computer from /dashboard/setup,\n" +
+      "or set OVERLAY_WORKER_TOKEN=gt_...",
+  );
+  process.exit(1);
+}
+
+type Puzzle = {
+  name: string;
+  language: string;
+  code: string;
+  answer: string;
+  difficulty: "easy" | "medium" | "hard";
+  why?: string;
+};
+
+type NewSeries = {
+  slug: string;
+  name: string;
+  instructions: string;
+  refUrls: string[];
+};
+
+type Job = {
+  id: string;
+  kind: "overlay" | "series" | "restock" | "preview" | "single" | "look";
+  /** kind='single' and one-off previews: what it should say, and what to copy. */
+  single?: { say: string; refUrls: string[] } | null;
+  /** The preview this job confirms, so it reuses that overlay rather than writing a new one. */
+  singleFor?: string | null;
+  /** kind='preview': a note asking for a change, if this is a revision. */
+  feedback?: string | null;
+  /** kind='preview': an exact change — a drag, or a reset. No model involved. */
+  lookPatch?: unknown;
+  /** kind='restock': how many episodes to research and write. */
+  restockCount?: number;
+  /** Null when the series is set to render in its own colours. */
+  brand: (Brand & { customFonts?: { family: string; url: string }[] }) | null;
+  newSeries: NewSeries | null;
+  series: string;
+  puzzle: Puzzle | Record<string, string> | null;
+  sourceUrl: string;
+  sourceName: string | null;
+  durationSec: number | null;
+  layers: unknown[];
+  /** Cards this account has consumed on any machine. */
+  usedKeys?: string[];
+};
+
+const ROOT = join(__dirname, "..");
+const PUBLIC = join(ROOT, "public");
+
+/** A one-off's directory name — the same for its preview and its burn. */
+const singleSlug = (id: string) => `single-${id.slice(0, 8)}`;
+
+/** Filesystem-safe, collision-free, and still readable in assets/cards/. */
+const slugFor = (job: Job, puzzle: Puzzle) =>
+  `${(puzzle.name || "puzzle")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 40) || "puzzle"}-${job.id.slice(0, 8)}`;
+
+/**
+ * Run a script, and on failure raise the part a human wrote.
+ *
+ * execFileSync's message is the whole command line plus a Node stack trace,
+ * which is what ends up in job.error and then on her phone. The scripts fail
+ * with real explanations ("failed 1 quality gate(s): why is missing or too
+ * thin") — that's the sentence worth surfacing, so pull it out and drop the
+ * interpreter noise.
+ */
+const run = (cmd: string, args: string[]) => {
+  try {
+    return execFileSync(cmd, args, {
+      cwd: ROOT,
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (e) {
+    const err = e as { stdout?: string; stderr?: string; message?: string };
+    const text = `${err.stdout ?? ""}\n${err.stderr ?? ""}`;
+    const lines = text.split("\n");
+    const start = lines.findIndex((l) => /^\s*(Error|TypeError):/.test(l));
+    const meaningful =
+      start === -1
+        ? []
+        : lines
+            .slice(start)
+            .filter((l) => !/^\s*at\s/.test(l)) // stack frames
+            .filter((l) => l.trim())
+            .slice(0, 6);
+    throw new Error(
+      meaningful.length
+        ? meaningful.join("\n").replace(/^\s*Error:\s*/, "")
+        : (err.message ?? "script failed"),
+    );
+  }
+};
+
+/**
+ * Build the What Prints? layers.
+ *
+ * The puzzle comes from the library on this machine — 30-odd cards already
+ * written, verified against a real run, and rendered. Asking someone to retype
+ * a puzzle they already have was the wrong shape entirely: the tool's job is to
+ * pair a clip with a puzzle, not to collect one.
+ *
+ * `puzzle.key` picks a specific card; without it, the next unused one, exactly
+ * as scripts/new-episode.ts would choose. A one-off typed puzzle still works —
+ * it goes through make-card.ts so it gets the same verify and quality gates the
+ * library cards passed.
+ */
+const whatPrintsLayers = (
+  job: Job,
+  input: Record<string, string> | Puzzle | null,
+  brollRelPath: string,
+  durationSec: number,
+  lookCardPath?: string,
+) => {
+  const typed = input && "code" in input && input.code ? (input as Puzzle) : null;
+  const revealAtSec = Math.min(2, Math.max(0, durationSec - 1));
+
+  let cardRelPath: string;
+  let difficulty: "easy" | "medium" | "hard";
+
+  if (typed) {
+    const slug = slugFor(job, typed);
+    const puzzleFile = join(tmpdir(), `${slug}.json`);
+    writeFileSync(
+      puzzleFile,
+      JSON.stringify({ ...typed, slug, name: typed.name || slug }),
+    );
+    try {
+      console.log("  rendering card + verifying the answer");
+      run("npx", ["tsx", "scripts/make-card.ts", puzzleFile]);
+    } finally {
+      rmSync(puzzleFile, { force: true });
+    }
+    cardRelPath = `assets/cards/${slug}.png`;
+    difficulty = typed.difficulty;
+  } else {
+    const chosen = pickPuzzle(
+      (input as Record<string, string> | null)?.key,
+      job.usedKeys ?? [],
+    );
+    console.log(`  puzzle: ${chosen.name} (${chosen.difficulty}) — ${chosen.key}`);
+    // The same card the preview showed, so what she approved is what renders.
+    cardRelPath = lookCardPath ?? chosen.cardRelPath;
+    difficulty = chosen.difficulty;
+    // Claimed as soon as it's chosen. A crash mid-render costs one card from
+    // the queue; double-posting the same puzzle costs a post.
+    markUsed(chosen.key, `overlay-${job.id.slice(0, 8)}`);
+    consumedKey = chosen.key;
+  }
+
+  // place-overlay reads and rewrites an episode file, so it gets a throwaway
+  // one pointing at this job's clip and card.
+  const episodeFile = join(tmpdir(), `overlay-${job.id.slice(0, 8)}-episode.json`);
+  let meterX: number | undefined;
+  let meterY: number | undefined;
+  // Set only when the card had to move off something — usually her face.
+  let cardY: number | undefined;
+  let cardWidthPct: number | undefined;
+  try {
+    writeFileSync(
+      episodeFile,
+      JSON.stringify({
+        broll: brollRelPath,
+        card: cardRelPath,
+        durationSec,
+        revealAtSec,
+        trimBeforeSec: 0,
+      }),
+    );
+    console.log("  placing the meter against the footage");
+    run("npx", ["tsx", "scripts/place-overlay.ts", episodeFile]);
+    const placed = JSON.parse(readFileSync(episodeFile, "utf8"));
+    meterX = placed.meterX;
+    meterY = placed.meterY;
+    cardY = placed.cardY;
+    cardWidthPct = placed.cardWidthPct;
+  } catch (e) {
+    // Placement is an optimisation, not a requirement — the meter has a
+    // sensible home position. Losing it shouldn't cost her the whole render.
+    console.warn(
+      `  ! placement skipped (${e instanceof Error ? e.message.split("\n")[0] : e})`,
+    );
+  } finally {
+    rmSync(episodeFile, { force: true });
+  }
+
+  return whatPrintsComposite(job, {
+    cardRelPath,
+    difficulty,
+    revealAtSec,
+    cardY,
+    cardWidthPct,
+    meterX,
+    meterY,
+  });
+};
+
+/**
+ * Assemble the layers, with the series' stored look applied over whatever the
+ * browser sent. The look is what feedback edits, so it has to win.
+ */
+const whatPrintsComposite = (
+  job: Job,
+  p: {
+    cardRelPath: string;
+    difficulty: "easy" | "medium" | "hard";
+    revealAtSec: number;
+    cardY?: number;
+    cardWidthPct?: number;
+    meterX?: number;
+    meterY?: number;
+  },
+) => {
+  const look = resolveLook(readLook(job.series));
+  const layers: unknown[] = [];
+
+  for (const raw of job.layers) {
+    const l = raw as Record<string, unknown>;
+    if (l.type === "title") {
+      layers.push({
+        ...l,
+        sansSize: look.title.sansSize,
+        rows: look.title.rows,
+        cell: look.title.cell,
+        gap: look.title.gap,
+        weight: look.title.weight,
+        family: look.title.family,
+        // The checkbox can only turn the scrim OFF; the look can't force it on
+        // over an explicit choice in the form.
+        scrim: l.scrim === false ? false : look.title.scrim,
+      });
+    } else {
+      layers.push(l);
+    }
+  }
+
+  // A hand-placed position beats the placement script. The script is a good
+  // guess about footage it has just looked at; a drag is a decision.
+  layers.push({
+    type: "image",
+    src: p.cardRelPath,
+    // Null means automatic: centred horizontally, placed vertically by the
+    // script that just looked at the footage.
+    ...(look.card.x == null ? {} : { x: look.card.x }),
+    y: look.card.y ?? p.cardY,
+    widthPct: look.card.y != null ? look.card.widthPct : (p.cardWidthPct ?? look.card.widthPct),
+    opacity: look.card.opacity,
+  });
+
+  if (look.meter.show) {
+    layers.push({
+      type: "meter",
+      difficulty: p.difficulty,
+      fromSec: p.revealAtSec,
+      x: look.meter.x ?? p.meterX,
+      y: look.meter.y ?? p.meterY,
+    });
+  }
+  return layers;
+};
+
+const api = async (path: string, body?: unknown) => {
+  const res = await fetch(`${BASE_URL}/api/overlay/worker/${path}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${TOKEN}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body ?? {}),
+  });
+  if (res.status === 204) return null;
+  if (!res.ok) throw new Error(`${path}: ${res.status} ${await res.text()}`);
+  return res.json();
+};
+
+/** ffprobe the downloaded clip — the browser's duration guess isn't authoritative. */
+const probeDuration = (file: string): number => {
+  const out = execFileSync(
+    "ffprobe",
+    [
+      "-v", "error",
+      "-show_entries", "format=duration",
+      "-of", "default=nw=1:nk=1",
+      file,
+    ],
+    { encoding: "utf8" },
+  );
+  return Number(out.trim());
+};
+
+/**
+ * Generate a new series from references and instructions. No footage involved:
+ * the output is series/<slug>/ on this machine, plus the field list the form
+ * will ask for from now on.
+ */
+const runSeriesJob = async (job: Job) => {
+  const spec = job.newSeries;
+  console.log(`→ series ${spec?.slug ?? "?"} — building`);
+  try {
+    if (!spec?.slug) throw new Error("Series job carried no definition");
+    const fields = await generateSeries({ ...spec, brand: job.brand });
+
+    // The tile art. Best-effort: a series that renders but whose preview fails
+    // is still a usable series, and the tile falls back to a reference image.
+    let previewUrl: string | undefined;
+    const previewPath = join(tmpdir(), `${spec.slug}-preview.png`);
+    try {
+      console.log("  rendering preview frame");
+      renderSeriesPreview(spec.slug, fields, job.brand, previewPath);
+      const blob = await upload(
+        `overlay/series-previews/${spec.slug}.png`,
+        readFileSync(previewPath),
+        {
+          access: "public",
+          handleUploadUrl: `${BASE_URL}/api/overlay/upload`,
+          clientPayload: JSON.stringify({ workerToken: TOKEN }),
+          contentType: "image/png",
+        },
+      );
+      previewUrl = blob.url;
+    } catch (e) {
+      console.warn(
+        `  ! preview skipped (${e instanceof Error ? e.message.split("\n")[0] : e})`,
+      );
+    } finally {
+      rmSync(previewPath, { force: true });
+    }
+
+    // Whether it wrote itself a content brief decides if it can ever restock.
+    const canRestock = Boolean(readSeriesSpec(spec.slug)?.content?.what);
+    await api("complete", {
+      jobId: job.id,
+      ok: true,
+      fields,
+      previewUrl,
+      canRestock,
+    });
+    console.log(`✓ series ${spec.slug} ready (${fields.length} field(s))`);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`✗ series ${spec?.slug}: ${message}`);
+    await api("complete", { jobId: job.id, ok: false, error: message });
+  }
+};
+
+/**
+ * What this episode of a generated series should say.
+ *
+ * Typed values win. Otherwise it takes the next unused episode from the
+ * series' own queue — the generic version of What Prints? taking the next
+ * unused card, so any series that has a content brief keeps producing without
+ * anyone typing.
+ */
+const resolveValues = (job: Job): Record<string, string> => {
+  const typed = (job.puzzle ?? {}) as Record<string, string>;
+  if (Object.keys(typed).length > 0) return typed;
+
+  const episode = nextEpisode(job.series);
+  if (!episode) {
+    throw new Error(
+      `"${job.series}" has no episodes left. Restock it from the tool, or fill the fields in yourself.`,
+    );
+  }
+  console.log(`  episode: ${Object.values(episode.values).join(" · ").slice(0, 80)}`);
+  // Claimed at selection, like a What Prints? card: a crash costs one episode
+  // from the queue, a double-claim costs a duplicate post.
+  markEpisodeUsed(job.series, episode.id, `overlay-${job.id.slice(0, 8)}`);
+  return episode.values;
+};
+
+/**
+ * Research and write new episodes for a series that's running low.
+ */
+const runRestockJob = async (job: Job) => {
+  console.log(`→ restock ${job.series} — researching`);
+  try {
+    // What Prints? writes real puzzles rather than field values: the snippet
+    // has to be executed and gated before it can become a post, which no
+    // generated series can do.
+    if (job.series === "what-prints") {
+      const { accepted, rejected } = await whatPrintsRestock(job.restockCount ?? 6);
+      await api("complete", {
+        jobId: job.id,
+        ok: true,
+        stock: listPuzzles().filter((p) => !p.used).length,
+        wrote: accepted.length,
+        note:
+          `Wrote ${accepted.length}` +
+          (rejected.length ? ` · ${rejected.length} failed checking` : ""),
+      });
+      console.log(`✓ restock what-prints: +${accepted.length}`);
+      return;
+    }
+
+    const spec = readSeriesSpec(job.series);
+    if (!spec) throw new Error(`Series "${job.series}" isn't built on this computer`);
+    if (!spec.content?.what) {
+      throw new Error(
+        `"${spec.name}" has no content brief, so it can't write its own episodes. Rebuild it and say where its content should come from.`,
+      );
+    }
+    const written = await restock({
+      slug: job.series,
+      seriesName: spec.name,
+      fields: spec.fields,
+      content: spec.content,
+      count: job.restockCount ?? 10,
+    });
+    await api("complete", {
+      jobId: job.id,
+      ok: true,
+      stock: stockCount(job.series),
+      wrote: written.length,
+    });
+    console.log(`✓ restock ${job.series}: +${written.length} (${stockCount(job.series)} in stock)`);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`✗ restock ${job.series}: ${message}`);
+    await api("complete", { jobId: job.id, ok: false, error: message });
+  }
+};
+
+/**
+ * Remember where something was put. No render, no image, no wait.
+ *
+ * Dragging is answered by the browser, which holds the pieces and can move
+ * them as many times as it likes. This is only the part that has to outlive
+ * the tab: the position, written into the series' stored look so the final
+ * burn puts it in the same place.
+ */
+const runLookJob = async (job: Job) => {
+  try {
+    if (!job.lookPatch) throw new Error("Look job carried no change");
+    patchLook(job.series, job.lookPatch as never);
+    console.log(`✓ look ${job.series} — saved`);
+    await api("complete", { jobId: job.id, ok: true });
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`✗ look ${job.series}: ${message}`);
+    await api("complete", { jobId: job.id, ok: false, error: message });
+  }
+};
+
+/**
+ * Render the look as a still, and apply any note that came with it.
+ *
+ * No clip involved: the point is to see and correct the overlay BEFORE
+ * committing a 4K render to it. The still is drawn over a neutral grey for the
+ * same reason the series tiles are — this is showing the overlay, and real
+ * footage behind it makes two attempts hard to compare.
+ */
+const runPreviewJob = async (job: Job) => {
+  console.log(`→ preview ${job.series}${job.feedback ? " (revision)" : ""}`);
+  const dir = mkdtempSync(join(tmpdir(), `overlay-preview-${job.id}-`));
+  const alpha = join(dir, "alpha.png");
+
+  // A one-off previews the overlay it is about to burn. The templates are
+  // KEPT: the burn reuses them, because generating again would write a
+  // different overlay from the one that was approved.
+  if (job.single) {
+    try {
+      const { layers } = await generateSingle({
+        slug: singleSlug(job.singleFor ?? job.id),
+        say: job.single.say,
+        refUrls: job.single.refUrls,
+        durationSec: 6,
+        brand: job.brand,
+        keep: true,
+      });
+      const fonts = await resolveCustomFonts(job.brand?.customFonts ?? []);
+      const propsFile = join(dir, "props.json");
+      writeFileSync(propsFile, JSON.stringify({ durationSec: 6, layers, fonts }));
+      run("npx", [
+        "remotion", "still", "Overlay", alpha,
+        "--props", propsFile,
+        "--image-format", "png",
+        "--frame", "45",
+      ]);
+      const blob = await upload(
+        `overlay/previews/${job.id}-base.png`,
+        readFileSync(alpha),
+        {
+          access: "public",
+          handleUploadUrl: `${BASE_URL}/api/overlay/upload`,
+          clientPayload: JSON.stringify({ workerToken: TOKEN }),
+          contentType: "image/png",
+        },
+      );
+      await api("complete", { jobId: job.id, ok: true, previewUrl: blob.url });
+      console.log(`✓ preview ${job.id} (one-off)`);
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      console.error(`✗ preview ${job.id}: ${message}`);
+      await api("complete", { jobId: job.id, ok: false, error: message });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    return;
+  }
+
+  try {
+    let note: string | undefined;
+    if (job.lookPatch) {
+      patchLook(job.series, job.lookPatch as never);
+      note = "Moved.";
+    } else if (job.feedback?.trim()) {
+      console.log(`  applying: ${job.feedback.trim().slice(0, 80)}`);
+      const applied = await applyFeedback({
+        slug: job.series,
+        feedback: job.feedback.trim(),
+        customFamilies: (job.brand?.customFonts ?? []).map((f) => f.family),
+      });
+      note = applied.note;
+      console.log(`  ${note}`);
+    }
+
+    // The puzzle is only READ here — a preview must not consume a card from
+    // the library, or iterating on the look would burn the queue.
+    const puzzle = pickPuzzle(
+      (job.puzzle as Record<string, string> | null)?.key ?? null,
+    );
+    const cardRelPath = await cardForLook({
+      key: puzzle.key,
+      code: puzzle.code,
+      language: puzzle.language,
+      look: resolveLook(readLook(job.series)),
+    });
+    const layers = whatPrintsComposite(job, {
+      cardRelPath,
+      difficulty: puzzle.difficulty,
+      revealAtSec: 0,
+    });
+
+    const fonts: ResolvedFont[] = await resolveCustomFonts(
+      job.brand?.customFonts ?? [],
+    );
+    // Rendered in PIECES rather than as one baked frame.
+    //
+    // A single flattened still means every nudge of the card is a round trip
+    // to this machine — you move a thing, then wait to see it move. Sending
+    // the card and the badge as their own images lets the browser place them
+    // itself, so dragging is immediate and can be done as many times as you
+    // like; this machine only hears the final position.
+    //
+    // What's left in the base still is everything that isn't draggable — the
+    // title, the scrim — so it stays a render rather than a reimplementation
+    // of the overlay in CSS.
+    const draggable = new Set(["image", "meter"]);
+    const baseLayers = layers.filter(
+      (l) => !draggable.has((l as { type?: string }).type ?? ""),
+    );
+
+    const stillOf = (name: string, only: unknown[]) => {
+      const out = join(dir, `${name}.png`);
+      const props = join(dir, `${name}.props.json`);
+      writeFileSync(props, JSON.stringify({ durationSec: 3, layers: only, fonts }));
+      run("npx", [
+        "remotion", "still", "Overlay", out,
+        "--props", props,
+        "--image-format", "png",
+        "--frame", "45", // past the meter's entrance spring, so it's fully in
+      ]);
+      return out;
+    };
+
+    stillOf("alpha", baseLayers);
+    // The still keeps its ALPHA — it is uploaded as-is rather than flattened
+    // onto a neutral gradient here. The overlay is meant to be judged against
+    // the footage it will actually sit on, and the browser already holds the
+    // clip: stacking a transparent PNG over it there costs nothing, where
+    // doing it on this machine would mean shipping the clip up and back. With
+    // no clip picked yet the UI paints the same grey behind it.
+
+    // Where things actually landed, in 1080x1920 space, so the UI can put a
+    // drag handle exactly on top of them instead of guessing from the image.
+    const cardLayer = layers.find(
+      (l) => (l as { type?: string }).type === "image",
+    ) as { x?: number; y?: number; widthPct?: number } | undefined;
+    const meterLayer = layers.find(
+      (l) => (l as { type?: string }).type === "meter",
+    ) as { x?: number; y?: number } | undefined;
+
+    let boxes: Record<string, unknown> | undefined;
+    try {
+      const meta = await sharp(join(PUBLIC, cardRelPath)).metadata();
+      const box = cardBox(
+        meta.height! / meta.width!,
+        cardLayer?.widthPct ?? undefined,
+        cardLayer?.y ?? undefined,
+      );
+      const cardX =
+        cardLayer?.x === undefined ? box.x : cardLayer.x - box.width / 2;
+      // Where each piece sits when nothing has been placed by hand. For a
+      // preview that is not a decision this machine makes — there's no
+      // footage to look at, so it's the composition's own defaults. Sending
+      // them lets "reset to automatic" happen in the browser, immediately,
+      // instead of costing a render to find out something already known.
+      const autoBox = cardBox(meta.height! / meta.width!);
+      const auto = {
+        card: {
+          x: autoBox.x + autoBox.width / 2,
+          y: autoBox.y + autoBox.height / 2,
+        },
+        meter: { x: 90, y: 1400 },
+      };
+
+      boxes = {
+        auto,
+        // What the schema will actually accept, so a drag can't produce a
+        // position that fails to save.
+        bounds: LOOK_BOUNDS,
+        card: { x: cardX, y: box.y, w: box.width, h: box.height },
+        meter: meterLayer
+          ? {
+              x: meterLayer.x ?? 90,
+              y: meterLayer.y ?? 1400,
+              w: 400,
+              h: 150,
+            }
+          : null,
+        frame: { w: 1080, h: 1920 },
+      };
+    } catch {
+      // Handles are a convenience; a preview without them still works.
+    }
+
+    const put = async (name: string, file: string) => {
+      const b = await upload(
+        `overlay/previews/${job.id}-${name}.png`,
+        readFileSync(file),
+        {
+          access: "public",
+          handleUploadUrl: `${BASE_URL}/api/overlay/upload`,
+          clientPayload: JSON.stringify({ workerToken: TOKEN }),
+          contentType: "image/png",
+        },
+      );
+      return b.url;
+    };
+
+    const blob = { url: await put("base", alpha) };
+
+    // The pieces the browser will position. The card is already a PNG on disk
+    // — it's the post — so it goes up as-is. The badge is drawn on its own and
+    // cropped to its box, so the browser gets a badge rather than a
+    // mostly-empty 1080x1920 sheet with a badge in one corner.
+    let pieces: Record<string, string> | undefined;
+    try {
+      const cardUrl = await put("card", join(PUBLIC, cardRelPath));
+      let meterUrl: string | undefined;
+      const meterBox = (boxes?.meter ?? null) as
+        | { x: number; y: number; w: number; h: number }
+        | null;
+      if (meterLayer && meterBox) {
+        const sheet = stillOf("meter", [meterLayer]);
+        const cropped = join(dir, "meter-crop.png");
+        await sharp(sheet)
+          .extract({
+            left: Math.max(0, Math.round(meterBox.x)),
+            top: Math.max(0, Math.round(meterBox.y)),
+            width: Math.round(meterBox.w),
+            height: Math.round(meterBox.h),
+          })
+          .toFile(cropped);
+        meterUrl = await put("meter", cropped);
+      }
+      pieces = { card: cardUrl, ...(meterUrl ? { meter: meterUrl } : {}) };
+    } catch (e) {
+      // Without pieces the UI falls back to the old baked behaviour, which
+      // still works — it just costs a redraw per move.
+      console.warn(
+        `  ! draggable pieces skipped (${e instanceof Error ? e.message.split("\n")[0] : e})`,
+      );
+    }
+
+    await api("complete", {
+      jobId: job.id,
+      ok: true,
+      previewUrl: blob.url,
+      note,
+      boxes: boxes ? { ...boxes, pieces } : boxes,
+      // Which card this attempt drew, so a later nudge redraws the SAME one.
+      // Without it every redraw takes the next card off the library and the
+      // snippet changes under a change that was only ever about position.
+      puzzleKey: puzzle.key,
+    });
+    console.log(`✓ preview ${job.id}`);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`✗ preview ${job.id}: ${message}`);
+    await api("complete", { jobId: job.id, ok: false, error: message });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+/**
+ * The card this job should draw, with the series' look baked in — or undefined
+ * to use the library PNG unchanged.
+ */
+const lookCardFor = async (job: Job): Promise<string | undefined> => {
+  if (job.series !== "what-prints") return undefined;
+  try {
+    const puzzle = pickPuzzle(
+      (job.puzzle as Record<string, string> | null)?.key ?? null,
+    );
+    return await cardForLook({
+      key: puzzle.key,
+      code: puzzle.code,
+      language: puzzle.language,
+      look: resolveLook(readLook(job.series)),
+    });
+  } catch {
+    // Never fail a render over the look — the library card is always valid.
+    return undefined;
+  }
+};
+
+/**
+ * Write more puzzles if the library is running low. Never fails a job.
+ */
+const topUpLibrary = async () => {
+  try {
+    const unused = listPuzzles().filter((p) => !p.used).length;
+    const done = await autoRestock(unused, Date.now());
+    if (done) {
+      console.log(
+        `  library topped up: +${done.accepted.length}` +
+          (done.rejected.length ? ` (${done.rejected.length} failed checking)` : ""),
+      );
+    }
+  } catch (e) {
+    console.warn(
+      `  ! auto top-up skipped (${e instanceof Error ? e.message.split("\n")[0] : e})`,
+    );
+  }
+};
+
+/**
+ * Not an error — the reason a render has no tile to donate.
+ *
+ * Thrown rather than branched around so the upload and the "never fail a
+ * render over tile art" catch stay in one piece.
+ */
+class NoTile extends Error {}
+
+/** Set by whatPrintsLayers so completion can report what was consumed. */
+let consumedKey: string | undefined;
+
+/** Swap any uploaded photo URLs for local files before rendering. */
+const withLocalImages = async (
+  slug: string,
+  values: Record<string, string>,
+): Promise<Record<string, string>> => {
+  const spec = readSeriesSpec(slug);
+  const imageKeys = (spec?.fields ?? [])
+    .filter((f) => f.type === "image")
+    .map((f) => f.key);
+  return resolveFieldImages(values, imageKeys);
+};
+
+const runJob = async (job: Job) => {
+  consumedKey = undefined;
+  console.log(`→ job ${job.id} [${job.series}] (${job.sourceName ?? "clip"})`);
+  const dir = mkdtempSync(join(tmpdir(), `overlay-job-${job.id}-`));
+  const output = join(dir, "output.mp4");
+
+  // The clip is staged under public/ rather than in the temp dir because
+  // place-overlay.ts resolves b-roll relative to public/. Removed in `finally`
+  // — it's hundreds of megabytes and the result is what she wanted.
+  // .mov covers the iPhone camera roll's usual container; ffmpeg sniffs the
+  // real format from the bytes, so the extension is only a hint.
+  const brollRelPath = `assets/b-roll/job-${job.id}.mov`;
+  const source = join(PUBLIC, brollRelPath);
+
+  let layers: unknown[];
+  // A one-off's templates live under series/ just long enough to render.
+  let cleanupSingle: (() => void) | undefined;
+
+  try {
+    // A job with no clip is not a render — it's a kind this worker has never
+    // heard of, claimed before the machine picked up the code that handles it.
+    // Without this it dies inside fetch() on "Failed to parse URL from
+    // undefined", which says nothing about the actual problem and lands on her
+    // phone as the reason her post failed.
+    if (!job.sourceUrl) {
+      throw new Error(
+        `This computer doesn't know how to run a "${job.kind}" job — its code is behind. ` +
+          `It restarts itself when the code changes; try again in a minute.`,
+      );
+    }
+
+    mkdirSync(join(PUBLIC, "assets/b-roll"), { recursive: true });
+    const res = await fetch(job.sourceUrl);
+    if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+    const bytes = Buffer.from(await res.arrayBuffer());
+    writeFileSync(source, bytes);
+    console.log(`  downloaded ${(bytes.length / 1024 / 1024).toFixed(0)} MB`);
+
+    // The overlay has to last as long as the clip, and the browser's estimate
+    // can be off (or absent for a codec it couldn't parse). ffprobe decides.
+    const durationSec = probeDuration(source) || job.durationSec || 6;
+
+    // A one-off: the overlay for THIS post is written now, from what she typed
+    // and whatever she attached, then thrown away. Same generation and same
+    // templates as a series — nothing is kept because nothing repeats.
+    if (job.kind === "single") {
+      console.log("  writing a one-off overlay");
+      const single = await generateSingle({
+        // The preview's slug when this burn is confirming one, so the overlay
+        // that was approved is the overlay that gets burned.
+        slug: singleSlug(job.singleFor ?? job.id),
+        say: job.single?.say ?? "",
+        refUrls: job.single?.refUrls ?? [],
+        durationSec,
+        brand: job.brand,
+      });
+      cleanupSingle = single.cleanup;
+      layers = single.layers;
+    } else {
+      layers =
+        job.series === "what-prints"
+          ? whatPrintsLayers(
+              job,
+              job.puzzle,
+              brollRelPath,
+              durationSec,
+              await lookCardFor(job),
+            )
+          : job.series && job.series !== "custom"
+            ? // A generated series: its templates, filled either with what she
+              // typed or with the next episode off its own queue. Photos are
+              // fetched to disk first — templates get a local path, never a URL.
+              seriesLayers(
+                job.series,
+                await withLocalImages(job.series, resolveValues(job)),
+                durationSec,
+                job.brand,
+              )
+            : job.layers;
+    }
+
+    const fonts = await resolveCustomFonts(job.brand?.customFonts ?? []);
+    const props = overlaySchema.parse({ durationSec, layers, fonts });
+
+    renderOverlay(source, props, output);
+
+    // The series tile has no art until something has been made with it, so
+    // the first finished render donates a frame. The server only accepts it
+    // when the series has no cover yet, and she can change it in the editor.
+    // A one-off belongs to no series, so it has no tile to donate to.
+    // A one-off belongs to no series, so it has no tile to donate to.
+    let seriesPreviewUrl: string | undefined;
+    const framePath = join(dir, "tile.png");
+    try {
+      if (job.kind === "single") throw new NoTile();
+      execFileSync(
+        "ffmpeg",
+        [
+          "-y", "-v", "error",
+          // A second in, so a clip that fades up doesn't donate a black frame.
+          "-ss", String(Math.min(1, Math.max(0, durationSec / 3))),
+          "-i", output,
+          "-frames:v", "1",
+          "-vf", "scale=540:-1",
+          framePath,
+        ],
+        { stdio: ["ignore", "pipe", "pipe"] },
+      );
+      const blob = await upload(
+        `overlay/series-previews/${job.series}.png`,
+        readFileSync(framePath),
+        {
+          access: "public",
+          handleUploadUrl: `${BASE_URL}/api/overlay/upload`,
+          clientPayload: JSON.stringify({ workerToken: TOKEN }),
+          contentType: "image/png",
+        },
+      );
+      seriesPreviewUrl = blob.url;
+    } catch (e) {
+      // Tile art is a nicety; never fail a finished render over it.
+      if (!(e instanceof NoTile)) {
+        console.warn(
+          `  ! tile frame skipped (${e instanceof Error ? e.message.split("\n")[0] : e})`,
+        );
+      }
+    }
+
+    const result = readFileSync(output);
+    const blob = await upload(`overlay/results/${job.id}/overlay.mp4`, result, {
+      access: "public",
+      handleUploadUrl: `${BASE_URL}/api/overlay/upload`,
+      clientPayload: JSON.stringify({ workerToken: TOKEN }),
+      contentType: "video/mp4",
+    });
+
+    await api("complete", {
+      jobId: job.id,
+      ok: true,
+      resultUrl: blob.url,
+      resultBytes: statSync(output).size,
+      seriesPreviewUrl,
+      puzzleKey: consumedKey,
+    });
+    console.log(`✓ job ${job.id} uploaded`);
+
+    // A render just consumed a puzzle, so this is the moment the library
+    // actually got shorter. Topping up here rather than on a schedule means
+    // it tracks real use — and it happens while she's already waiting, not in
+    // the middle of the next post.
+    await topUpLibrary();
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`✗ job ${job.id}: ${message}`);
+    await api("complete", { jobId: job.id, ok: false, error: message });
+  } finally {
+    // Hundreds of megabytes per job. Cleaned up even on failure — the error is
+    // already reported upstream, and a full disk breaks every later job. The
+    // rendered card is deliberately NOT removed: it stays in assets/cards/ as
+    // a reusable asset, the same as one made by hand.
+    rmSync(dir, { recursive: true, force: true });
+    rmSync(source, { force: true });
+    // A one-off's templates were written for this render and nothing else.
+    cleanupSingle?.();
+  }
+};
+
+// Wrapped rather than top-level: this package is CommonJS, where top-level
+// await doesn't compile.
+/**
+ * Exit when this worker's own code changes.
+ *
+ * It runs under launchd with KeepAlive, so exiting IS restarting — with the
+ * new code. Without this the agent keeps running whatever it loaded at boot,
+ * and a job kind added later is claimed by a worker that has never heard of
+ * it: it falls through to the video path and dies fetching a clip that isn't
+ * there. That failure reads like a broken deploy and isn't one.
+ */
+const watchOwnSource = () => {
+  const files = [
+    "scripts/overlay-worker.ts",
+    "scripts/series.ts",
+    "scripts/library.ts",
+    "scripts/stock.ts",
+    "scripts/look-store.ts",
+    "scripts/look-card.ts",
+    "scripts/render-overlay.ts",
+  ].map((f) => join(ROOT, f));
+  const stamp = () =>
+    files
+      .map((f) => (existsSync(f) ? statSync(f).mtimeMs : 0))
+      .join(",");
+  const at_start = stamp();
+  setInterval(() => {
+    if (stamp() !== at_start) {
+      console.log("Worker code changed — restarting to pick it up.");
+      process.exit(0);
+    }
+  }, 15_000).unref();
+};
+
+const main = async () => {
+  watchOwnSource();
+  console.log(
+    `Overlay Factory worker connected to ${BASE_URL} — waiting for jobs (Ctrl+C to stop)`,
+  );
+  // A library that's already thin shouldn't wait for the next post to notice.
+  await topUpLibrary();
+  const swept = sweepSingles();
+  if (swept) console.log(`Cleared ${swept} abandoned one-off overlay(s).`);
+
+  for (;;) {
+    try {
+      // Report the stock with every poll: the library lives here, so the cloud
+      // can only warn her it's running low if this tells it.
+      let puzzlesLeft: number | undefined;
+      try {
+        puzzlesLeft = listPuzzles().filter((p) => !p.used).length;
+      } catch {
+        // A machine without the library still renders generated series.
+      }
+      const job = (await api("claim", { puzzlesLeft })) as Job | null;
+      if (job) {
+        if (job.kind === "series") await runSeriesJob(job);
+        else if (job.kind === "restock") await runRestockJob(job);
+        else if (job.kind === "preview") await runPreviewJob(job);
+        // A saved position: nothing to draw, so it finishes in milliseconds.
+        else if (job.kind === "look") await runLookJob(job);
+        // A single goes down the video path like any other render — it writes
+        // its overlay on the way through.
+        else await runJob(job);
+        lastJobAt = Date.now();
+        continue; // Straight back for the next one rather than sleeping.
+      }
+    } catch (e) {
+      console.error(`poll failed: ${e instanceof Error ? e.message : e}`);
+    }
+    await new Promise((r) => setTimeout(r, pollDelay()));
+  }
+};
+
+main();