overlay-factory-worker 0.1.0

package/scripts/wp-restock.ts

@@ -0,0 +1,281 @@
+/**
+ * Write new What Prints? puzzles.
+ *
+ * Three inputs, in order of authority:
+ *
+ *  1. The existing library — house style. The names are Nintendo-flavoured,
+ *     the snippets are short, the answers are surprising, and the `why` does
+ *     the teaching. New puzzles have to belong to that set.
+ *  2. What actually performed, by comments per 1,000 reach. Reach swings by
+ *     orders of magnitude and likes track reach, so raw likes measure
+ *     distribution rather than whether the puzzle landed.
+ *  3. What makes people argue. The best-performing episode so far is the one
+ *     where a list mutates while you iterate it — people turn up in the
+ *     comments to insist the language is broken. A puzzle that provokes
+ *     disagreement outperforms one that merely surprises.
+ *
+ * Nothing written here is trusted. Every puzzle goes through make-card.ts,
+ * which EXECUTES the snippet, checks it prints exactly the stated answer, and
+ * runs the quality gates (deterministic, same on every installed Python, no
+ * duplicates, has a real explanation). A puzzle that fails is dropped, not
+ * shipped — a wrong answer is the one mistake this series can't survive.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(__dirname, "..");
+const EPISODES = join(ROOT, "episodes");
+const PUZZLES = join(ROOT, "puzzles");
+
+/** Top up when the library gets this thin. */
+export const LOW_STOCK = 8;
+
+/** How many to write when topping up unprompted. */
+export const AUTO_BATCH = 6;
+
+/**
+ * Don't retry a failing generation in a tight loop.
+ *
+ * Writing puzzles costs a Claude call and a Python run per candidate, and a
+ * generation that fails tends to keep failing for the same reason — an API
+ * problem, or a concept space that's genuinely exhausted. Backing off makes
+ * that a slow annoyance rather than a machine pinned at 100%.
+ */
+const COOLDOWN_MS = 6 * 60 * 60 * 1000;
+const stampFile = join(EPISODES, ".restock-attempted");
+
+const lastAttempt = (): number => {
+  try {
+    return Number(readFileSync(stampFile, "utf8").trim()) || 0;
+  } catch {
+    return 0;
+  }
+};
+
+type Entry = {
+  name?: string;
+  code?: string;
+  answer?: string;
+  why?: string;
+  concept?: string;
+  difficulty?: string;
+  card?: string;
+  retired?: string;
+  metrics?: {
+    likes?: number;
+    comments?: number;
+    reach?: number;
+    saved?: number;
+    shares?: number;
+  };
+};
+
+const readJson = <T>(p: string, fallback: T): T =>
+  existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")) as T) : fallback;
+
+const slugify = (s: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 48);
+
+/**
+ * Comments per 1,000 reach — the metric the README argues for, and the only
+ * one that says whether the puzzle itself landed.
+ */
+const engagement = (e: Entry): number | null => {
+  const c = e.metrics?.comments;
+  const r = e.metrics?.reach;
+  if (typeof c !== "number" || typeof r !== "number" || r < 200) return null;
+  return (c / r) * 1000;
+};
+
+/**
+ * Top the library up if it's running low, unprompted.
+ *
+ * Called after a render — the moment a puzzle is actually consumed — and once
+ * at worker start, so a library that's already thin doesn't wait for the next
+ * post to notice. Returns null when nothing was needed.
+ */
+export const autoRestock = async (
+  unusedCount: number,
+  now: number,
+): Promise<{ accepted: string[]; rejected: string[] } | null> => {
+  if (unusedCount >= LOW_STOCK) return null;
+  if (now - lastAttempt() < COOLDOWN_MS) return null;
+
+  // Stamped BEFORE the attempt, not after: a crash mid-generation must still
+  // count as an attempt, or a reproducible failure retries on every job.
+  writeFileSync(stampFile, String(now));
+  console.log(
+    `  library down to ${unusedCount} — writing more (auto)`,
+  );
+  return whatPrintsRestock(AUTO_BATCH);
+};
+
+export const whatPrintsRestock = async (count: number) => {
+  const index = readJson<Entry[]>(join(EPISODES, "index.json"), []);
+  const live = index.filter((e) => !e.retired && e.code);
+
+  const scored = live
+    .map((e) => ({ e, score: engagement(e) }))
+    .filter((x): x is { e: Entry; score: number } => x.score !== null)
+    .sort((a, b) => b.score - a.score);
+
+  const existingConcepts = [
+    ...new Set(live.map((e) => e.concept).filter(Boolean)),
+  ];
+
+  // Style is taught by example rather than described — three real puzzles say
+  // more about the house voice than a paragraph about it would.
+  const examples = live
+    .slice(0, 3)
+    .map((e) =>
+      JSON.stringify(
+        {
+          name: e.name,
+          code: e.code,
+          answer: e.answer,
+          why: e.why,
+          difficulty: e.difficulty,
+          concept: e.concept,
+        },
+        null,
+        2,
+      ),
+    )
+    .join("\n\n");
+
+  const perfSection = scored.length
+    ? `## What actually performed
+Measured as comments per 1,000 reach — likes mostly track how far a post was
+pushed, so they say little about whether the puzzle landed.
+
+${scored
+  .slice(0, 6)
+  .map(
+    (x) =>
+      `- ${x.score.toFixed(1)} per 1k · ${x.e.name} · ${x.e.concept ?? "?"} — ${(x.e.why ?? "").slice(0, 110)}`,
+  )
+  .join("\n")}
+
+Look at what the top ones have in common and write more of THAT.`
+    : `## No performance data yet
+Nothing has enough reach to judge, so go on the house style and the rule below.`;
+
+  const prompt = `You are writing new puzzles for "What Prints?", a short-form video series where
+a code snippet is shown and viewers guess the output.
+
+## House style — match this
+${examples}
+
+Names are playful and Nintendo-flavoured. Snippets are SHORT: under 8 lines and
+under ~45 characters wide, or the card shrinks the type and stops being
+readable on a phone. The answer must be surprising. The "why" does the actual
+teaching and is the payoff.
+
+${perfSection}
+
+## What makes one work
+The best-performing episode so far is a list being mutated while it's iterated:
+people arrive in the comments to argue the language is broken. That's the
+shape to aim for — a snippet where the correct answer feels WRONG, and where
+someone confident will insist it's a bug.
+
+Prefer behaviour people have opinions about: mutable default arguments, late
+binding in closures, integer caching, float arithmetic, truthiness, copy vs
+deepcopy, iterator exhaustion, operator precedence surprises, string interning.
+Avoid anything that needs trivia rather than reasoning — the viewer should be
+able to work it out and still get it wrong.
+
+## Already covered — do NOT repeat these concepts
+${existingConcepts.join(", ") || "(none yet)"}
+
+## Hard rules
+- Python 3, standard library only, no imports beyond the stdlib.
+- It must print EXACTLY what you say it prints. The snippet gets executed and
+  checked; a mismatch throws the puzzle away.
+- Deterministic: same output every run, and on every Python 3.11-3.14. No dict
+  ordering luck, no memory addresses, no timing, no randomness.
+- Answerable from the snippet alone.
+- "why" must be a real explanation, 2-4 sentences, and include the fix where
+  there is one.
+
+## Output — a JSON array and nothing else
+[
+  {
+    "slug": "kebab-case-name",
+    "name": "Bowser's NaN Trap",
+    "language": "Python",
+    "code": "a = float(\\"nan\\")\\nprint(a == a)",
+    "answer": "False",
+    "why": "...",
+    "difficulty": "easy" | "medium" | "hard",
+    "concept": "short-slug-for-the-idea"
+  }
+]
+
+Write at most ${count}. Fewer good ones beats more weak ones.`;
+
+  const out = execFileSync(
+    "claude",
+    ["-p", prompt, "--output-format", "text", "--allowedTools", ""],
+    { encoding: "utf8", maxBuffer: 20 * 1024 * 1024, timeout: 20 * 60 * 1000 },
+  );
+
+  const start = out.indexOf("[");
+  const end = out.lastIndexOf("]");
+  if (start === -1 || end === -1) throw new Error("No JSON array came back");
+
+  let raw: Entry[];
+  try {
+    raw = JSON.parse(out.slice(start, end + 1));
+  } catch (e) {
+    throw new Error(`Puzzles weren't valid JSON: ${(e as Error).message}`);
+  }
+
+  const accepted: string[] = [];
+  const rejected: string[] = [];
+
+  for (const p of raw) {
+    const slug = slugify((p as { slug?: string }).slug ?? p.name ?? "puzzle");
+    if (!slug || !p.code || !p.answer) {
+      rejected.push(`${p.name ?? "unnamed"}: missing code or answer`);
+      continue;
+    }
+    const file = join(PUZZLES, `${slug}.json`);
+    writeFileSync(file, JSON.stringify({ ...p, slug }, null, 2) + "\n");
+
+    // make-card runs the snippet, checks the answer, applies the quality
+    // gates, renders the card and registers it. Anything it rejects never
+    // becomes a post.
+    try {
+      execFileSync("npx", ["tsx", "scripts/make-card.ts", file], {
+        cwd: ROOT,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf8",
+      });
+      accepted.push(slug);
+      console.log(`  ✓ ${slug}`);
+    } catch (err) {
+      const e = err as { stdout?: string; stderr?: string };
+      const why =
+        `${e.stdout ?? ""}${e.stderr ?? ""}`
+          .split("\n")
+          .find((l) => /Error:/.test(l))
+          ?.replace(/^.*Error:\s*/, "") ?? "failed verification";
+      rejected.push(`${slug}: ${why}`);
+      console.log(`  ✗ ${slug}: ${why}`);
+      execFileSync("rm", ["-f", file]);
+    }
+  }
+
+  if (accepted.length === 0) {
+    throw new Error(
+      `Nothing survived checking. ${rejected.slice(0, 3).join("; ")}`,
+    );
+  }
+  return { accepted, rejected };
+};

package/src/Root.tsx

@@ -0,0 +1,112 @@
+import React from "react";
+import { Composition, CalculateMetadataFunction } from "remotion";
+import { WhatPrints } from "./series/what-prints/Composition";
+import { whatPrintsSchema, WhatPrintsProps } from "./series/what-prints/types";
+import { FontLab } from "./lab/FontLab";
+import { FontSheet } from "./lab/FontSheet";
+import { PillLab } from "./lab/PillLab";
+import { CodeCard } from "./series/what-prints/CodeCard";
+import {
+  codeCardSchema,
+  CodeCardProps,
+  CARD_WIDTH,
+  cardHeight,
+} from "./series/what-prints/codeCardTypes";
+import { Overlay } from "./overlay/Composition";
+import { overlaySchema, OverlayProps } from "./overlay/types";
+import defaultEpisode from "../episodes/what-prints-001.json";
+
+const calculateMetadata: CalculateMetadataFunction<WhatPrintsProps> = ({
+  props,
+}) => {
+  return {
+    durationInFrames: Math.round(props.durationSec * 30),
+  };
+};
+
+const overlayMetadata: CalculateMetadataFunction<OverlayProps> = ({ props }) => ({
+  durationInFrames: Math.max(1, Math.round(props.durationSec * 30)),
+});
+
+export const RemotionRoot: React.FC = () => {
+  return (
+    <>
+      <Composition
+        id="WhatPrints"
+        component={WhatPrints}
+        fps={30}
+        width={1080}
+        height={1920}
+        schema={whatPrintsSchema}
+        defaultProps={defaultEpisode as WhatPrintsProps}
+        calculateMetadata={calculateMetadata}
+      />
+      {/* Overlay layers with nothing behind them — rendered alpha-only and
+          composited over untouched footage by scripts/render-overlay.ts. The
+          frame stays 1080x1920 at any output resolution; --scale handles 4K. */}
+      <Composition
+        id="Overlay"
+        component={Overlay}
+        fps={30}
+        width={1080}
+        height={1920}
+        schema={overlaySchema}
+        defaultProps={{
+          durationSec: 6,
+          layers: [
+            { type: "title", line1: "What", line2: "PRINTS?" },
+            { type: "meter", difficulty: "medium", fromSec: 2 },
+          ],
+        } as OverlayProps}
+        calculateMetadata={overlayMetadata}
+      />
+      {/* Still image only — rendered by scripts/make-card.ts, which sizes the
+          canvas to the snippet's line count. */}
+      <Composition
+        id="CodeCard"
+        component={CodeCard}
+        fps={30}
+        durationInFrames={1}
+        width={CARD_WIDTH}
+        height={cardHeight(5)}
+        schema={codeCardSchema}
+        defaultProps={{
+          language: "Python",
+          lines: [
+            [{ content: "npx tsx scripts/make-card.ts", color: "#c5c8d4" }],
+          ],
+          codeScale: 1,
+        }}
+        calculateMetadata={({ props }: { props: CodeCardProps }) => ({
+          width: CARD_WIDTH,
+          height: cardHeight(props.lines.length, props.codeScale ?? 1),
+        })}
+      />
+      <Composition
+        id="PillLab"
+        component={PillLab}
+        fps={30}
+        durationInFrames={1}
+        width={1080}
+        height={1920}
+      />
+      {/* Candidate faces for the title's second line, at real size. */}
+      <Composition
+        id="FontSheet"
+        component={FontSheet}
+        fps={30}
+        durationInFrames={1}
+        width={1500}
+        height={1500}
+      />
+      <Composition
+        id="FontLab"
+        component={FontLab}
+        fps={30}
+        durationInFrames={1}
+        width={1400}
+        height={1500}
+      />
+    </>
+  );
+};

package/src/index.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/src/index.ts

@@ -0,0 +1,4 @@
+import { registerRoot } from "remotion";
+import { RemotionRoot } from "./Root";
+
+registerRoot(RemotionRoot);

package/src/lab/FontLab.tsx

@@ -0,0 +1,50 @@
+import React from "react";
+import { AbsoluteFill, Img, staticFile } from "remotion";
+import { PixelText } from "../overlay/PixelText";
+import { sansFamily } from "../overlay/fonts";
+
+// Direct comparison against the inspiration: same words, so stroke thickness
+// and pixel size can be matched by eye rather than guessed.
+const SAMPLES = [
+  { rows: 10, cell: 15, gap: 3, weight: 500 },
+  { rows: 10, cell: 15, gap: 3, weight: 400 },
+  { rows: 10, cell: 15, gap: 3, weight: 300 },
+  { rows: 9, cell: 16, gap: 3, weight: 400 },
+];
+
+export const FontLab: React.FC = () => (
+  <AbsoluteFill style={{ background: "#3a3128", justifyContent: "center", gap: 26 }}>
+    <div style={{ padding: "0 40px", fontFamily: "monospace", fontSize: 26, color: "#ffd08a" }}>
+      INSPIRATION (target)
+    </div>
+    <Img
+      src={staticFile("assets/inspiration/title inspiration.jpg")}
+      style={{
+        width: 1180,
+        objectFit: "none",
+        objectPosition: "-40px -410px",
+        height: 160,
+        alignSelf: "flex-start",
+        marginLeft: 40,
+      }}
+    />
+    <div style={{ padding: "0 40px", marginTop: 10, fontFamily: "monospace", fontSize: 26, color: "#8affc1" }}>
+      RASTERIZED — rows = cap height in cells
+    </div>
+    {SAMPLES.map((s) => (
+      <div key={`${s.rows}-${s.weight}`} style={{ display: "flex", alignItems: "center", gap: 24, padding: "0 40px" }}>
+        <div style={{ width: 130, fontFamily: "monospace", fontSize: 24, color: "#bbb" }}>
+          rows {s.rows} / w{s.weight}
+        </div>
+        <PixelText
+          text="Prints?"
+          fontFamily={sansFamily}
+          fontWeight={s.weight}
+          rows={s.rows}
+          cell={s.cell}
+          gap={s.gap}
+        />
+      </div>
+    ))}
+  </AbsoluteFill>
+);

package/src/lab/FontSheet.tsx

@@ -0,0 +1,188 @@
+import React, { useEffect, useState } from "react";
+import { AbsoluteFill, continueRender, delayRender, staticFile } from "remotion";
+import { loadFont as poppins } from "@remotion/google-fonts/Poppins";
+import { loadFont as handjet } from "@remotion/google-fonts/Handjet";
+import { loadFont as silkscreen } from "@remotion/google-fonts/Silkscreen";
+import { loadFont as pixelifySans } from "@remotion/google-fonts/PixelifySans";
+import { loadFont as jersey15 } from "@remotion/google-fonts/Jersey15";
+import { loadFont as micro5 } from "@remotion/google-fonts/Micro5";
+import { loadFont as dotGothic16 } from "@remotion/google-fonts/DotGothic16";
+import { PixelText } from "../overlay/PixelText";
+
+/**
+ * Candidates for the title's second line, at the real size, so the choice is
+ * made by looking rather than by reasoning about it.
+ *
+ * The line this replaces is PixelText — a canvas rasterizer that draws Poppins
+ * onto a dot grid. It was written because "pixel fonts cap stroke weight at one
+ * grid cell", a conclusion reached with Handjet at weight 370. Handjet goes to
+ * 900, so the premise is worth retesting before keeping a bespoke rasterizer.
+ *
+ * Note @remotion/google-fonts serves one static instance per weight, so
+ * Handjet's ELGR/ELSH axes can't be varied — these are its default shapes.
+ */
+
+const { fontFamily: sans } = poppins("normal", {
+  weights: ["700"],
+  subsets: ["latin"],
+});
+
+/**
+ * Handjet as a TRUE variable font.
+ *
+ * @remotion/google-fonts serves one static instance per weight, which pins
+ * ELGR/ELSH at their defaults — and those two axes are the whole reason to
+ * want Handjet. ELSH shapes the element (0 square … 16 round) and ELGR sets
+ * how coarse the grid is, which together are what make separated dots rather
+ * than the continuous strokes every other pixel face gives.
+ *
+ * Self-hosted from public/fonts so the render doesn't depend on the network.
+ */
+const HANDJET_VAR = "HandjetVar";
+
+const variableFace = `
+@font-face {
+  font-family: "${HANDJET_VAR}";
+  src: url("${staticFile("fonts/Handjet-variable.woff2")}") format("woff2");
+  font-weight: 400 900;
+  font-display: block;
+}`;
+
+const VARIABLE: { label: string; weight: number; elgr: number; elsh: number }[] = [
+  { label: "Handjet var 700 · ELSH 4", weight: 700, elgr: 1, elsh: 4 },
+  { label: "Handjet var 900 · ELSH 8", weight: 900, elgr: 1, elsh: 8 },
+];
+
+/**
+ * The rasterizer, retuned. `rows` is cap height in cells, so more rows = finer
+ * dots; `cell` is the pitch and `gap` the space inside it, so cell-gap is the
+ * dot. The current title is rows 10 / cell 15 / gap 3 at Poppins 300 — big
+ * sparse dots. The reference is finer and heavier than that.
+ */
+const RASTER: { label: string; rows: number; cell: number; gap: number; weight: number }[] = [
+  { label: "raster NOW (10/15/3 w300)", rows: 10, cell: 15, gap: 3, weight: 300 },
+  { label: "raster finer (14/11/2 w500)", rows: 14, cell: 11, gap: 2, weight: 500 },
+  { label: "raster fine+bold (16/9/2 w700)", rows: 16, cell: 9, gap: 2, weight: 700 },
+  { label: "raster tight (18/8/1 w700)", rows: 18, cell: 8, gap: 1, weight: 700 },
+];
+
+const CANDIDATES: { label: string; family: string; weight: number }[] = [
+  { label: "Handjet 800", family: handjet("normal", { weights: ["800"], subsets: ["latin"] }).fontFamily, weight: 800 },
+  { label: "Silkscreen 700", family: silkscreen("normal", { weights: ["700"], subsets: ["latin"] }).fontFamily, weight: 700 },
+  { label: "Pixelify Sans 700", family: pixelifySans("normal", { weights: ["700"], subsets: ["latin"] }).fontFamily, weight: 700 },
+  { label: "Jersey 15", family: jersey15("normal", { weights: ["400"], subsets: ["latin"] }).fontFamily, weight: 400 },
+  { label: "Micro 5", family: micro5("normal", { weights: ["400"], subsets: ["latin"] }).fontFamily, weight: 400 },
+  { label: "DotGothic16", family: dotGothic16("normal", { weights: ["400"], subsets: ["latin"] }).fontFamily, weight: 400 },
+];
+
+// The reference sets a bold sans line over a dot-matrix line, so each sample
+// shows the pair — a face that looks fine alone can still fight the Poppins.
+const SAMPLE_1 = "What";
+const SAMPLE_2 = "PRINTS?";
+
+export const FontSheet: React.FC = () => {
+  // A hand-written @font-face is not covered by Remotion's font loading, so
+  // the frame gets captured while the face is still fetching and the row
+  // renders as ghost outlines. Hold the frame until it's actually usable.
+  const [handle] = useState(() => delayRender("Loading variable Handjet"));
+  useEffect(() => {
+    const done = () => continueRender(handle);
+    document.fonts.load(`700 104px "${HANDJET_VAR}"`).then(done, done);
+  }, [handle]);
+
+  return (
+  <AbsoluteFill
+    style={{
+      background: "#151515",
+      padding: 48,
+      display: "flex",
+      flexDirection: "column",
+      gap: 26,
+    }}
+  >
+    <style dangerouslySetInnerHTML={{ __html: variableFace }} />
+    {VARIABLE.map((v) => (
+      <div key={v.label} style={{ display: "flex", alignItems: "center", gap: 36 }}>
+        <div style={{ fontFamily: sans, fontSize: 20, fontWeight: 700, color: "#8ee3a1", width: 260, flexShrink: 0 }}>
+          {v.label}
+        </div>
+        <div style={{ display: "flex", alignItems: "baseline", gap: 20 }}>
+          <span style={{ fontFamily: sans, fontWeight: 700, fontSize: 78, color: "white" }}>
+            {SAMPLE_1}
+          </span>
+          <span
+            style={{
+              fontFamily: HANDJET_VAR,
+              fontWeight: v.weight,
+              fontVariationSettings: `"ELGR" ${v.elgr}, "ELSH" ${v.elsh}`,
+              fontSize: 104,
+              color: "white",
+            }}
+          >
+            {SAMPLE_2}
+          </span>
+        </div>
+      </div>
+    ))}
+    {RASTER.map((r) => (
+      <div key={r.label} style={{ display: "flex", alignItems: "center", gap: 36 }}>
+        <div style={{ fontFamily: sans, fontSize: 20, fontWeight: 700, color: "#ffd166", width: 260, flexShrink: 0 }}>
+          {r.label}
+        </div>
+        <div style={{ display: "flex", alignItems: "center", gap: 20 }}>
+          <span style={{ fontFamily: sans, fontWeight: 700, fontSize: 78, color: "white" }}>
+            {SAMPLE_1}
+          </span>
+          <PixelText text={SAMPLE_2} fontFamily={sans} fontWeight={r.weight} rows={r.rows} cell={r.cell} gap={r.gap} />
+        </div>
+      </div>
+    ))}
+    {CANDIDATES.map((c) => (
+      <div
+        key={c.label}
+        style={{ display: "flex", alignItems: "center", gap: 36 }}
+      >
+        <div
+          style={{
+            fontFamily: sans,
+            fontSize: 20,
+            fontWeight: 700,
+            color: "#6f7686",
+            width: 260,
+            flexShrink: 0,
+          }}
+        >
+          {c.label}
+        </div>
+        <div style={{ display: "flex", alignItems: "baseline", gap: 20 }}>
+          <span
+            style={{
+              fontFamily: sans,
+              fontWeight: 700,
+              fontSize: 78,
+              color: "white",
+              textShadow: "0 0 4px rgba(0,0,0,0.9), 0 4px 20px rgba(0,0,0,0.6)",
+            }}
+          >
+            {SAMPLE_1}
+          </span>
+          <span
+            style={{
+              fontFamily: c.family,
+              fontWeight: c.weight,
+              fontSize: 104,
+              color: "white",
+              // Same doubled shadow PixelText uses: a single wide blur tints
+              // the area and the dots stop reading against bright footage.
+              textShadow:
+                "0 0 3px rgba(0,0,0,0.95), 0 4px 16px rgba(0,0,0,0.6)",
+            }}
+          >
+            {SAMPLE_2}
+          </span>
+        </div>
+      </div>
+    ))}
+  </AbsoluteFill>
+  );
+};