overlay-factory-worker 0.1.0

package/scripts/series.ts

@@ -0,0 +1,816 @@
+/**
+ * User-generated series: build one from references, and render one onto a clip.
+ *
+ * A series lives at series/<slug>/ and is entirely declarative:
+ *
+ *   series.json   what the form asks for, and where each template sits
+ *   *.html        self-contained HTML+CSS with {{field}} placeholders
+ *
+ * Nothing here is executed — templates are markup that the Overlay composition
+ * paints over the footage. That's the whole reason this is HTML and not
+ * generated components: a bad generation costs one job, not the render engine.
+ *
+ * Motion is NOT the template's job. Remotion renders by seeking to each frame
+ * and screenshotting, so CSS animations and transitions never advance — they'd
+ * freeze on whatever the first frame painted. Each layer instead declares an
+ * `enter`, which the composition drives with Remotion's own spring.
+ */
+import { execFile, execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const ROOT = join(__dirname, "..");
+const SERIES_DIR = join(ROOT, "series");
+
+export type SeriesField = {
+  key: string;
+  label: string;
+  type: "text" | "textarea" | "code" | "select" | "image";
+  required?: boolean;
+  placeholder?: string;
+  help?: string;
+  options?: string[];
+};
+
+type SeriesLayerSpec = {
+  template: string;
+  anchor?: "top" | "center" | "bottom";
+  x?: number;
+  y?: number;
+  widthPct?: number;
+  enter?: "none" | "fade" | "slide-up" | "slide-down" | "pop";
+  fromSec?: number;
+  toSec?: number;
+};
+
+type SeriesSpec = {
+  name: string;
+  fields: SeriesField[];
+  layers: SeriesLayerSpec[];
+  /** How the series sources what it says — see scripts/stock.ts. */
+  content?: {
+    what: string;
+    research?: string[];
+    rules?: string[];
+  };
+};
+
+/** The subset of the user's brand a template can reach. */
+export type Brand = {
+  colors: Record<string, string>;
+  fonts: { heading: string; body: string; mono?: string };
+  handle?: string;
+};
+
+/**
+ * Brand as CSS custom properties, prepended to every template.
+ *
+ * Custom properties rather than substitution because a template should be able
+ * to fall back — `var(--brand-primary, #001AFF)` still renders when the series
+ * is set to ignore the brand, so one contract covers both.
+ *
+ * The font stacks stay SHORT on purpose. A longer, more "correct" stack ending
+ * in -apple-system silently breaks the whole declaration in this renderer:
+ * substituting a chain containing -apple-system makes font-family invalid at
+ * computed-value time, so the element inherits the page font and the brand
+ * appears not to apply at all. Verified by rendering both — the colours came
+ * through and only the type was wrong, which is a maddening thing to chase.
+ *
+ * The families themselves are loaded by src/overlay/brandFonts.ts; naming a
+ * family here does not load it.
+ */
+export const brandVars = (brand: Brand | null): string => {
+  if (!brand) return "";
+  const vars = Object.entries(brand.colors)
+    .map(([k, v]) => `--brand-${k.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase())}: ${v};`)
+    .join("\n  ");
+  return `<style>:root {
+  ${vars}
+  --brand-font-heading: "${brand.fonts.heading}", sans-serif;
+  --brand-font-body: "${brand.fonts.body}", sans-serif;
+}</style>\n`;
+};
+
+// ── Generation ────────────────────────────────────────────────────────────
+
+const FILE_RE = /^===\s*FILE:\s*(.+?)\s*===$/;
+
+/** Parse the `=== FILE: name ===` blocks the prompt asks for. */
+const extractFiles = (out: string): Record<string, string> => {
+  const files: Record<string, string> = {};
+  let current: string | null = null;
+  let buf: string[] = [];
+  for (const line of out.split("\n")) {
+    const m = line.match(FILE_RE);
+    if (m) {
+      if (current) files[current] = buf.join("\n").trim();
+      current = m[1];
+      buf = [];
+    } else if (current) {
+      buf.push(line);
+    }
+  }
+  if (current) files[current] = buf.join("\n").trim();
+  // Fenced code blocks are habit-forming; strip them if they wrapped a file.
+  for (const k of Object.keys(files)) {
+    files[k] = files[k]
+      .replace(/^```[a-z]*\n/i, "")
+      .replace(/\n```$/i, "")
+      .trim();
+  }
+  return files;
+};
+
+const validate = (files: Record<string, string>): SeriesSpec => {
+  if (!files["series.json"]) throw new Error("no series.json returned");
+
+  let spec: SeriesSpec;
+  try {
+    spec = JSON.parse(files["series.json"]);
+  } catch (e) {
+    throw new Error(`series.json is not valid JSON: ${(e as Error).message}`);
+  }
+
+  if (!Array.isArray(spec.fields)) throw new Error("series.json needs a fields array");
+  if (spec.content && typeof spec.content.what !== "string") {
+    throw new Error("series.json content needs a 'what' sentence");
+  }
+  if (!Array.isArray(spec.layers) || spec.layers.length === 0) {
+    throw new Error("series.json needs at least one layer");
+  }
+  for (const f of spec.fields) {
+    if (!f.key || !f.label) throw new Error("every field needs a key and a label");
+    if (!["text", "textarea", "code", "select", "image"].includes(f.type)) {
+      throw new Error(`field ${f.key}: unknown type ${f.type}`);
+    }
+  }
+  for (const l of spec.layers) {
+    if (!l.template) throw new Error("every layer needs a template");
+    if (!files[l.template]) throw new Error(`layer references missing file ${l.template}`);
+  }
+
+  for (const [name, body] of Object.entries(files)) {
+    if (name === "series.json") continue;
+    if (/<script/i.test(body)) throw new Error(`${name}: no <script> allowed`);
+    // An external URL in a render is a hang waiting to happen, and fonts are
+    // supplied by the engine.
+    if (/(src|href)\s*=\s*["']?https?:/i.test(body)) {
+      throw new Error(`${name}: no external URLs allowed`);
+    }
+    if (/@import|url\(\s*["']?https?:/i.test(body)) {
+      throw new Error(`${name}: no remote CSS or fonts`);
+    }
+  }
+  return spec;
+};
+
+const prompt = (opts: {
+  slug: string;
+  name: string;
+  instructions: string;
+  refPaths: string[];
+  brand: Brand | null;
+}) => `You are designing a reusable overlay series for a vertical video engine.
+
+An "episode" is a clip of b-roll with your overlay burned on top. The user
+supplies a few short pieces of text each time; your templates turn those into
+the look.
+
+## What the user asked for
+${opts.instructions}
+
+${
+  opts.refPaths.length
+    ? `## Reference images — THE SOURCE OF TRUTH
+Read each of these image files closely (in order — the first matters most):
+${opts.refPaths.map((p) => `- ${p}`).join("\n")}
+
+Sample the ACTUAL colors from them. Match their typography treatment (weight,
+case, letter-spacing, serif vs sans), their shapes (radius, borders, bars),
+their spacing and their composition. A finished frame should look like it
+belongs in the same account as these references.`
+    : `## No reference images
+Design from the description alone. Favour high contrast and heavy weight —
+this sits over moving footage and has to read on a phone at arm's length.`
+}
+
+## Engine contract (hard rules)
+- The frame is 1080x1920. Your templates are drawn OVER video, so they must
+  stay legible against ANY footage: use solid fills, heavy scrims or strong
+  text shadows. Never rely on the footage being dark or light.
+- Instagram covers the frame with its own UI. Keep content out of: the top
+  250px (status bar + Reels header), the right 260px below y=1080 (like /
+  comment / share rail), and the bottom 420px (caption + audio). Anchors
+  already account for this — prefer them over absolute x/y.
+- Each template file is self-contained HTML with its own <style> block, scoped
+  by unique class names so two layers can't collide. NO <script>. NO external
+  URLs of any kind — no font links, no imports, no remote images. A picture
+  comes from an "image" field, never from a URL you write.
+- Fonts available: system sans (-apple-system, "Segoe UI", Roboto, sans-serif)
+  and monospace, plus the two brand font variables below. Nothing else loads,
+  so always end a font stack with a system fallback.
+${
+  opts.brand
+    ? `- The user's BRAND is available as CSS custom properties, already defined
+  for you. Use them for colour rather than hardcoding hex, so the series
+  follows their brand when it changes:
+${Object.keys(opts.brand.colors)
+  .map((k) => `    var(--brand-${k.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase())})`)
+  .join("\n")}
+    var(--brand-font-heading)   var(--brand-font-body)
+  Their palette right now is ${Object.entries(opts.brand.colors)
+    .slice(0, 4)
+    .map(([k, v]) => `${k} ${v}`)
+    .join(", ")}, heading font ${opts.brand.fonts.heading}.
+  Give every var() a fallback — var(--brand-primary, #001AFF) — because a
+  series can be set to render without the brand.
+  Where the REFERENCES and the BRAND disagree on colour, follow the brand: the
+  references are there for layout, weight and composition.`
+    : "- No brand is set; choose colours from the references."
+}
+- DO NOT write CSS animations, transitions, or @keyframes. They do not run in
+  this engine — every frame is rendered by seeking, so an animation freezes on
+  its first frame. Motion comes from each layer's "enter" value instead.
+- Placeholders: write {{fieldKey}} anywhere in a template and the user's input
+  for that field is substituted in (HTML-escaped). Use only keys you declared
+  in fields.
+- A template's root element should size to its content — the engine gives it a
+  width and positions it.
+
+## The content brief — this is what stops the series running dry
+Alongside the look, decide where this series' CONTENT comes from, and put it in
+"content". A series is a format that has to keep producing episodes, so think
+about what the hundredth one looks like, not just the first.
+
+- "what": one sentence describing exactly what a single episode is.
+- "research": if real-world material would make it better, say where to look and
+  what a good find looks like. Be specific about SOURCES — name the forums,
+  boards, subreddits, or sites where this material actually appears. A series
+  about interview questions should be researching what people report being
+  asked, not inventing questions that sound plausible. Omit "research" entirely
+  when the content genuinely comes from imagination or from the user each time.
+- "rules": what would make an episode WRONG rather than weak. Include the
+  honesty rules — never attribute something to a company without a source,
+  never invent a statistic, never claim something is real when it isn't.
+
+## series.json
+{
+  "name": ${JSON.stringify(opts.name)},
+  "fields": [
+    {"key":"claim","label":"The claim","type":"textarea","required":true,
+     "placeholder":"...","help":"optional hint shown under the input"}
+  ],
+  "layers": [
+    {"template":"claim.html","anchor":"top","widthPct":0.86,"enter":"slide-down"},
+    {"template":"verdict.html","anchor":"bottom","widthPct":0.6,
+     "enter":"pop","fromSec":2}
+  ],
+  "content": {
+    "what": "One question a software engineer was actually asked in a real interview, with the company when it is known.",
+    "research": [
+      "Search r/cscareerquestions, Blind, Glassdoor interview reports and levels.fyi for questions people report being asked recently",
+      "Prefer the specific and surprising over the canonical — 'reverse a linked list' is not worth watching",
+      "Keep the company attribution only when the source states it"
+    ],
+    "rules": [
+      "Never attribute a question to a company without a source that says so",
+      "The question must fit in about 12 words",
+      "No duplicates or near-duplicates of episodes already in the library"
+    ]
+  }
+}
+
+- content: the brief above. Include it whenever the series could generate its
+  own episodes; omit it only when every episode's text genuinely comes from the
+  user. Without it, the series can never restock itself.
+- fields: what the form asks for. type is text | textarea | code | select
+  | image. An "image" field gives the user an upload; its {{placeholder}} is a
+  path, so use it ONLY inside a src attribute: <img src="{{photo}}" alt="">.
+  Style it with CSS (object-fit, border-radius, a fixed height) — the picture
+  could be any shape and an unconstrained <img> will blow the layout apart.
+  (select also needs "options": [...]). Keep it to the FEWEST fields that make
+  the series work — every field is something the user retypes for every post.
+- layers: drawn in order, first at the back. anchor is top | center | bottom
+  ("center" means the band Instagram never covers). widthPct is 0-1 of frame
+  width. enter is none | fade | slide-up | slide-down | pop. fromSec / toSec
+  limit a layer to part of the clip; omit for the whole clip.
+
+## Output format — EXACTLY this, no commentary before or after
+=== FILE: series.json ===
+{ ... }
+=== FILE: claim.html ===
+<div class="${opts.slug}-claim">{{claim}}</div>
+<style>.${opts.slug}-claim { ... }</style>
+`;
+
+const VIDEO_EXT_RE = /\.(mp4|mov|m4v)$/i;
+
+/**
+ * A video reference is only useful as pictures.
+ *
+ * Claude reads images, not clips, so a reel gets sampled into a handful of
+ * evenly spaced frames — enough to see the look AND to read wording that
+ * appears part way through, which is the usual reason someone attaches one.
+ * Scaled down because a 4K frame costs a lot to read and says nothing extra.
+ */
+const framesFrom = (video: string, dir: string, prefix: string, count = 5) => {
+  let duration = 0;
+  try {
+    duration = Number(
+      execFileSync(
+        "ffprobe",
+        [
+          "-v", "error",
+          "-show_entries", "format=duration",
+          "-of", "default=nw=1:nk=1",
+          video,
+        ],
+        { encoding: "utf8" },
+      ).trim(),
+    );
+  } catch {
+    // No probe, no sampling plan — one frame from the start is still a look.
+  }
+  const paths: string[] = [];
+  for (let i = 0; i < count; i++) {
+    // Inside the clip at both ends: the first and last frames of a reel are
+    // often a fade, and a black frame is a wasted read.
+    const at = duration ? (duration * (i + 0.5)) / count : 0;
+    const out = join(dir, `${prefix}-frame-${i}.png`);
+    try {
+      execFileSync(
+        "ffmpeg",
+        [
+          "-y", "-v", "error",
+          "-ss", at.toFixed(2),
+          "-i", video,
+          "-frames:v", "1",
+          "-vf", "scale=720:-2",
+          out,
+        ],
+        { stdio: ["ignore", "pipe", "pipe"] },
+      );
+      if (existsSync(out)) paths.push(out);
+    } catch {
+      // A frame that won't decode isn't worth failing the generation over.
+    }
+    if (!duration) break; // Without a duration there's only one frame to take.
+  }
+  return paths;
+};
+
+/**
+ * Download the references so Claude can actually read them.
+ *
+ * Videos are allowed: they come back as sampled frames, in order, so the
+ * caller sees one flat list of image paths either way.
+ */
+const fetchRefs = async (urls: string[], dir: string) => {
+  const paths: string[] = [];
+  for (const [i, url] of urls.entries()) {
+    try {
+      const res = await fetch(url);
+      if (!res.ok) continue;
+      const pathname = new URL(url).pathname;
+      const contentType = res.headers.get("content-type") ?? "";
+      const isVideo =
+        VIDEO_EXT_RE.test(pathname) || contentType.startsWith("video/");
+      const ext = isVideo
+        ? (pathname.match(VIDEO_EXT_RE)?.[0] ?? ".mp4")
+        : (pathname.match(/\.(png|jpe?g|webp)$/i)?.[0] ?? ".png");
+      const p = join(dir, `ref-${i}${ext}`);
+      writeFileSync(p, Buffer.from(await res.arrayBuffer()));
+      if (isVideo) {
+        paths.push(...framesFrom(p, dir, `ref-${i}`));
+        rmSync(p, { force: true }); // Hundreds of megabytes; the frames are the reference.
+      } else {
+        paths.push(p);
+      }
+    } catch {
+      // A reference that won't download shouldn't sink the generation.
+    }
+  }
+  return paths;
+};
+
+/**
+ * Ask for the files, check them, and write series/<slug>/.
+ *
+ * Shared by a series and a one-off because the output is the same thing in
+ * both cases: templates plus a spec saying where they sit. What differs is the
+ * prompt and whether anyone keeps the result.
+ */
+const generateInto = async (
+  slug: string,
+  initialPrompt: string,
+  what: string,
+): Promise<SeriesSpec> => {
+  let p = initialPrompt;
+  let files: Record<string, string> | undefined;
+  let spec: SeriesSpec | undefined;
+
+  // Two attempts: the second is told exactly what was wrong with the first.
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const { stdout } = await execFileAsync(
+      "claude",
+      ["-p", p, "--output-format", "text", "--allowedTools", "Read"],
+      { maxBuffer: 20 * 1024 * 1024, timeout: 15 * 60 * 1000 },
+    );
+    try {
+      files = extractFiles(stdout);
+      spec = validate(files);
+      break;
+    } catch (e) {
+      const why = (e as Error).message;
+      console.error(`  attempt ${attempt} rejected: ${why}`);
+      if (attempt === 2) throw new Error(`${what} failed: ${why}`);
+      p += `\n\nYour previous attempt was rejected: ${why}\nReturn the corrected files in full, in the same format.`;
+    }
+  }
+
+  const out = join(SERIES_DIR, slug);
+  rmSync(out, { recursive: true, force: true });
+  mkdirSync(out, { recursive: true });
+  for (const [f, content] of Object.entries(files!)) {
+    writeFileSync(join(out, f), content);
+  }
+  console.log(`  wrote series/${slug}/ (${Object.keys(files!).length} files)`);
+  return spec!;
+};
+
+export const generateSeries = async (input: {
+  slug: string;
+  name: string;
+  instructions: string;
+  refUrls: string[];
+  brand?: Brand | null;
+}): Promise<SeriesField[]> => {
+  const dir = mkdtempSync(join(tmpdir(), `series-${input.slug}-`));
+  try {
+    const refPaths = await fetchRefs(input.refUrls ?? [], dir);
+    console.log(`  ${refPaths.length} reference image(s)`);
+    const spec = await generateInto(
+      input.slug,
+      prompt({ ...input, refPaths, brand: input.brand ?? null }),
+      "Series generation",
+    );
+    return spec.fields;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+// ── One-offs ──────────────────────────────────────────────────────────────
+
+const singlePrompt = (opts: {
+  slug: string;
+  say: string;
+  refPaths: string[];
+  brand: Brand | null;
+}) => `You are designing the overlay for ONE vertical video. Not a format, not
+a template someone fills in later — this post, once.
+
+## What the user asked for
+${opts.say.trim() || "(nothing typed — the reference is the whole brief)"}
+
+${
+  opts.refPaths.length
+    ? `## Reference — READ THESE FILES
+${opts.refPaths.map((p) => `- ${p}`).join("\n")}
+
+${
+  opts.refPaths.some((p) => p.includes("-frame-"))
+    ? `Some of these are frames sampled from a video the user attached, in order.
+TRANSCRIBE the on-screen text you can read in them. Unless the instructions say
+otherwise, that wording IS the copy for this overlay — reproduce it faithfully,
+including line breaks and capitalisation, and lay it out the same way.`
+    : `Read the wording and the look off these. Unless the instructions say
+otherwise, the text in them IS the copy for this overlay.`
+}
+
+Sample the ACTUAL colors. Match the typography treatment (weight, case,
+letter-spacing, serif vs sans), the shapes, the spacing, the composition.`
+    : `## No reference
+Design from the description alone. Favour high contrast and heavy weight — this
+sits over moving footage and has to read on a phone at arm's length.`
+}
+
+## Engine contract (hard rules)
+- The frame is 1080x1920. Your templates are drawn OVER video, so they must
+  stay legible against ANY footage: solid fills, heavy scrims or strong text
+  shadows. Never rely on the footage being dark or light.
+- Instagram covers the frame with its own UI. Keep content out of: the top
+  250px, the right 260px below y=1080, and the bottom 420px. Anchors already
+  account for this — prefer them over absolute x/y.
+- Each template file is self-contained HTML with its own <style> block, scoped
+  by unique class names. NO <script>. NO external URLs of any kind — no font
+  links, no imports, no remote images.
+- Fonts available: system sans (-apple-system, "Segoe UI", Roboto, sans-serif)
+  and monospace, plus the brand variables below. Nothing else loads, so always
+  end a font stack with a system fallback.
+${
+  opts.brand
+    ? `- The user asked for THEIR BRAND. It is available as CSS custom properties,
+  already defined for you — use them rather than hardcoded hex:
+${Object.keys(opts.brand.colors)
+  .map((k) => `    var(--brand-${k.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase())})`)
+  .join("\n")}
+    var(--brand-font-heading)   var(--brand-font-body)
+  Their palette right now is ${Object.entries(opts.brand.colors)
+    .slice(0, 4)
+    .map(([k, v]) => `${k} ${v}`)
+    .join(", ")}, heading font ${opts.brand.fonts.heading}.
+  Give every var() a fallback — var(--brand-primary, #001AFF).
+  Where the REFERENCE and the BRAND disagree on colour or type, follow the
+  BRAND: the reference is there for wording, layout and composition.`
+    : `- The user did NOT ask for their brand, so choose colours and type yourself
+  — from the reference if there is one, or to suit the words if there isn't.`
+}
+- DO NOT write CSS animations, transitions, or @keyframes. They do not run in
+  this engine — every frame is rendered by seeking, so an animation freezes on
+  its first frame. Motion comes from each layer's "enter" value instead.
+- Write the words DIRECTLY into the templates. This is a one-off: there is
+  nobody to fill in a placeholder later, so "fields" MUST be an empty array and
+  no {{...}} placeholder may appear anywhere.
+
+## series.json
+{
+  "name": "One-off",
+  "fields": [],
+  "layers": [
+    {"template":"line.html","anchor":"top","widthPct":0.86,"enter":"slide-down"},
+    {"template":"kicker.html","anchor":"bottom","widthPct":0.6,"enter":"pop",
+     "fromSec":2}
+  ]
+}
+
+- layers: drawn in order, first at the back. anchor is top | center | bottom
+  ("center" is the band Instagram never covers). widthPct is 0-1 of frame
+  width. enter is none | fade | slide-up | slide-down | pop. fromSec / toSec
+  limit a layer to part of the clip; omit for the whole clip. Use fromSec when
+  a line should land later — but keep the main line up from the start, or a
+  scroller never sees it.
+- Keep it to the fewest layers that say what was asked. One strong line usually
+  beats three.
+
+## Output format — EXACTLY this, no commentary before or after
+=== FILE: series.json ===
+{ ... }
+=== FILE: line.html ===
+<div class="${opts.slug}-line">The actual words go here</div>
+<style>.${opts.slug}-line { ... }</style>
+`;
+
+/**
+ * Write the overlay for a single post, and return its layers.
+ *
+ * It goes through the same generation, the same validation and the same
+ * templates a series does — the text is baked in instead of being a field, and
+ * the directory is thrown away afterwards. `cleanup` is the caller's job so
+ * the layers can be rendered before the templates disappear.
+ */
+/** Whether this one-off has already been written and is still on disk. */
+export const singleExists = (slug: string) =>
+  existsSync(join(SERIES_DIR, slug, "series.json"));
+
+/**
+ * Throw away one-offs nobody came back for.
+ *
+ * A one-off's templates are kept between its preview and its burn — that's
+ * what makes the preview mean anything, since regenerating would produce
+ * something else. Anything older than a day was previewed and abandoned.
+ */
+export const sweepSingles = (maxAgeMs = 24 * 60 * 60 * 1000) => {
+  if (!existsSync(SERIES_DIR)) return 0;
+  let removed = 0;
+  for (const d of readdirSync(SERIES_DIR, { withFileTypes: true })) {
+    if (!d.isDirectory() || !d.name.startsWith("single-")) continue;
+    const p = join(SERIES_DIR, d.name);
+    try {
+      if (Date.now() - statSync(p).mtimeMs > maxAgeMs) {
+        rmSync(p, { recursive: true, force: true });
+        removed++;
+      }
+    } catch {
+      // A directory that can't be read isn't one worth failing over.
+    }
+  }
+  return removed;
+};
+
+export const generateSingle = async (input: {
+  slug: string;
+  say: string;
+  refUrls: string[];
+  durationSec: number;
+  brand?: Brand | null;
+  /** Keep the templates for a later burn instead of deleting them. */
+  keep?: boolean;
+}): Promise<{ layers: ReturnType<typeof seriesLayers>; cleanup: () => void }> => {
+  const dir = mkdtempSync(join(tmpdir(), `single-${input.slug}-`));
+  const cleanup = () => {
+    if (input.keep) return;
+    rmSync(join(SERIES_DIR, input.slug), { recursive: true, force: true });
+  };
+  try {
+    // Already written — by the preview this burn is confirming. Reusing it is
+    // the whole point: generating again would produce a different overlay
+    // from the one that was approved.
+    if (singleExists(input.slug)) {
+      console.log(`  reusing the overlay from its preview`);
+      return {
+        layers: seriesLayers(input.slug, {}, input.durationSec, input.brand ?? null),
+        cleanup,
+      };
+    }
+    const refPaths = await fetchRefs(input.refUrls ?? [], dir);
+    console.log(`  ${refPaths.length} reference image(s)`);
+    await generateInto(
+      input.slug,
+      singlePrompt({
+        slug: input.slug,
+        say: input.say,
+        refPaths,
+        brand: input.brand ?? null,
+      }),
+      "Overlay generation",
+    );
+    return {
+      layers: seriesLayers(input.slug, {}, input.durationSec, input.brand ?? null),
+      cleanup,
+    };
+  } catch (e) {
+    cleanup();
+    throw e;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+// ── Rendering ─────────────────────────────────────────────────────────────
+
+/** Field values are user text going into markup — escape before substitution. */
+const escapeHtml = (s: string) =>
+  s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+
+/**
+ * Newlines are meaningful in what the user typed but invisible in HTML, and a
+ * template can't know whether a field will be one line or five.
+ *
+ * Image fields are the exception: their value is a path sitting inside a src
+ * attribute, where a <br> would corrupt it. They're escaped for attribute
+ * safety and otherwise left alone.
+ */
+const substitute = (
+  template: string,
+  values: Record<string, string>,
+  imageKeys: string[] = [],
+) => {
+  const images = new Set(imageKeys);
+  return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_, key: string) => {
+    const raw = values[key] ?? "";
+    if (images.has(key)) {
+      // Served from public/, so a leading slash resolves to the render's root.
+      return raw ? "/" + escapeHtml(raw).replace(/^\//, "") : "";
+    }
+    return escapeHtml(raw).replace(/\n/g, "<br>");
+  });
+};
+
+export const seriesLayers = (
+  slug: string,
+  values: Record<string, string>,
+  durationSec: number,
+  brand: Brand | null = null,
+) => {
+  const dir = join(SERIES_DIR, slug);
+  if (!existsSync(dir)) {
+    throw new Error(
+      `Series "${slug}" isn't built on this computer. Rebuild it from the tool.`,
+    );
+  }
+  const spec = JSON.parse(
+    readFileSync(join(dir, "series.json"), "utf8"),
+  ) as SeriesSpec;
+
+  const imageKeys = spec.fields
+    .filter((f) => f.type === "image")
+    .map((f) => f.key);
+
+  return spec.layers.map((l) => {
+    const template = readFileSync(join(dir, l.template), "utf8");
+    return {
+      type: "html" as const,
+      html: brandVars(brand) + substitute(template, values, imageKeys),
+      anchor: l.anchor,
+      x: l.x,
+      y: l.y,
+      widthPct: l.widthPct,
+      enter: l.enter,
+      // A layer told to start after the clip ends would never be seen.
+      fromSec: l.fromSec === undefined ? undefined : Math.min(l.fromSec, durationSec),
+      toSec: l.toSec,
+    };
+  });
+};
+
+/**
+ * A sample frame for the series tile.
+ *
+ * Rendered over a neutral grey rather than real footage: the tile is showing
+ * what the OVERLAY looks like, and a busy clip behind it makes two series hard
+ * to tell apart. Sample text comes from each field's own placeholder, so the
+ * preview shows the series doing its actual job rather than lorem.
+ */
+export const renderSeriesPreview = (
+  slug: string,
+  fields: SeriesField[],
+  brand: Brand | null,
+  outPng: string,
+) => {
+  const sample: Record<string, string> = {};
+  for (const f of fields) {
+    sample[f.key] =
+      f.options?.[0] ?? f.placeholder ?? f.label;
+  }
+  const layers = seriesLayers(slug, sample, 3, brand).map((l) => ({
+    ...l,
+    // The tile is one frame, so entrance animation would only ever show the
+    // first moment of itself — mid-fade, mid-slide, wrong.
+    enter: "none" as const,
+    fromSec: undefined,
+    toSec: undefined,
+  }));
+
+  const propsFile = join(tmpdir(), `${slug}-preview-props.json`);
+  const alphaPng = join(tmpdir(), `${slug}-preview-alpha.png`);
+  writeFileSync(propsFile, JSON.stringify({ durationSec: 3, layers }));
+
+  try {
+    execFileSync(
+      "npx",
+      [
+        "remotion", "still", "Overlay", alphaPng,
+        "--props", propsFile,
+        "--image-format", "png",
+        "--frame", "0",
+      ],
+      { cwd: ROOT, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" },
+    );
+    // Flatten onto a neutral vertical gradient so light and dark overlays both
+    // read on the tile.
+    execFileSync(
+      "ffmpeg",
+      [
+        "-y", "-v", "error",
+        "-f", "lavfi",
+        "-i", "gradients=s=1080x1920:c0=0x3a3a3a:c1=0x6e6e6e:x0=0:y0=0:x1=1080:y1=1920:n=2",
+        "-i", alphaPng,
+        "-filter_complex", "[0:v][1:v]overlay=0:0,format=yuv420p[o]",
+        "-map", "[o]", "-frames:v", "1",
+        outPng,
+      ],
+      { cwd: ROOT, stdio: ["ignore", "pipe", "pipe"] },
+    );
+    return outPng;
+  } finally {
+    rmSync(propsFile, { force: true });
+    rmSync(alphaPng, { force: true });
+  }
+};
+
+/** A series' spec as built on this machine — fields, layers and content brief. */
+export const readSeriesSpec = (slug: string): SeriesSpec | null => {
+  const f = join(SERIES_DIR, slug, "series.json");
+  if (!existsSync(f)) return null;
+  try {
+    return JSON.parse(readFileSync(f, "utf8")) as SeriesSpec;
+  } catch {
+    return null;
+  }
+};
+
+/** Which series this machine has actually built — used by the CLI helper. */
+export const installedSeries = () =>
+  existsSync(SERIES_DIR)
+    ? readdirSync(SERIES_DIR, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+    : [];