overlay-factory-worker 0.1.0

package/README.md

@@ -0,0 +1,215 @@
+# reel-factory
+
+Automated overlay editing for Erin's reel series. Feed it b-roll + a code card +
+an episode JSON, get a finished vertical MP4 with the "What **Prints?**" title,
+the code card, and a timed difficulty reveal.
+
+## Flow
+
+```bash
+npx tsx scripts/make-card.ts puzzles/x.json   # write a NEW code card from a puzzle JSON
+./scripts/ingest.sh                      # pull assets from ~/Desktop/Automate Editing (via Finder)
+npx tsx scripts/prep-card.ts             # code-card JPGs -> transparent rounded PNGs
+npx tsx scripts/new-episode.ts        # picks next card + b-roll, places the meter
+npx remotion render WhatPrints out/what-prints-XXX.mp4 --props=episodes/what-prints-XXX.json
+./scripts/export.sh out/what-prints-XXX.mp4   # copy to Desktop/Automate Editing/exports
+```
+
+Preview while tweaking: `npm run dev` (Remotion Studio).
+
+## Episode JSON
+
+```json
+{
+  "broll": "assets/b-roll/IMG_4858.MOV",
+  "card": "assets/cards/IMG_4030.png",
+  "titleLine1": "What",
+  "titleLine2": "Prints?",
+  "difficulty": "hard",        // easy | medium | hard
+  "durationSec": 10,
+  "revealAtSec": 4,            // when the difficulty meter pops in
+  "trimBeforeSec": 0,          // skip into the b-roll clip
+  "meterX": 70,                // set by scripts/place-overlay.ts
+  "meterY": 670
+}
+```
+
+`episodes/index.json` maps every code card to its episode metadata (answer, why,
+caption) extracted from the caption screenshots. `episodes/used.json` tracks
+which cards/b-roll are consumed.
+
+## Generating code cards
+
+The original cards were phone screenshots of a chat app's code block, cropped by
+`prep-card.ts`. New ones are rendered directly: write a puzzle JSON in `puzzles/`
+and run `scripts/make-card.ts`. It highlights the snippet with Shiki (any
+language), renders the `CodeCard` composition to a transparent rounded PNG at
+`public/assets/cards/<slug>.png`, and upserts the entry into `cards.json` and
+`index.json` — so re-running the same slug edits in place.
+
+```json
+{
+  "slug": "nan-trap",
+  "name": "Bowser's NaN Trap",
+  "language": "Python",
+  "code": "score = float(\"nan\")\nbest = score\n\nprint(score == best)",
+  "answer": "False",
+  "why": "NaN is never equal to itself...",
+  "difficulty": "easy"
+}
+```
+
+Every card is executed before it renders and put through `scripts/quality.ts`:
+the snippet must print exactly what `answer` claims, print the *same thing*
+three runs in a row and on every installed Python 3.11-3.14, be answerable in a
+comment (no memory addresses, nothing over 120 chars), not duplicate an existing
+card, and carry a real `why`. Any failure stops the render; `--no-verify` and
+`--no-gates` override. Audit the whole library with `npx tsx scripts/quality.ts`
+or `npx tsx scripts/verify.ts`.
+
+Cards that fail get a `retired` note in `index.json` rather than being deleted —
+`new-episode.ts` skips them, and the audits ignore them.
+
+Keep lines under ~45 characters and snippets under ~8 lines — beyond that the
+script shrinks the type to fit and warns. Colors and geometry live in
+`src/series/what-prints/codeCardTypes.ts`; preview with `npm run dev`.
+
+The `/what-prints-card` skill writes the puzzles and drives this end to end.
+
+## Engagement data
+
+`npx tsx scripts/ig-sync.ts` pulls the Instagram history for `@erin.codes` into
+`episodes/performance.json` — captions, likes, comments, and per-post insights
+(reach, saves, shares, views). Read-only; the token comes from
+`~/code/crossposter/.env` (the `ig-auto-dm` one has expired).
+
+Insights calls are rate-limited, so by default it only fetches them for posts
+whose caption looks like a series episode. Use `--since=2026-06-01` for a date
+range or `--all` for every reel; results already fetched are reused.
+
+`npx tsx scripts/report.ts` then ranks the published episodes against the
+account's own baseline and links each post back to the card it came from
+(captions are the join key; set `permalink` on an `index.json` entry to force it).
+
+Judge cards by **comments per 1,000 reach** — reach swings by orders of magnitude
+and likes track reach, so raw likes say more about distribution than about
+whether the puzzle landed.
+
+## Overlay Factory
+
+The overlay components (`src/overlay/`) are shared: What Prints composites them
+over its own b-roll, and the Overlay Factory tool on Goose Tools burns them onto
+any clip uploaded from a phone.
+
+Burn overlays onto a clip locally:
+
+```bash
+npm run overlay -- clip.mov overlay.json out.mp4
+```
+
+Run the worker so `/dashboard/overlay` can send jobs to this machine. The token
+comes from `~/.goosetools/env`, where the Carousel Maker's installer already
+put it — one token serves every Goose Tools worker on a machine:
+
+```bash
+npm run overlay:worker      # foreground, stops when the terminal closes
+npm run overlay:install     # keep it running across reboots (launchd)
+npm run overlay:uninstall   # stop it and remove the agent
+```
+
+`overlay:install` writes `~/Library/LaunchAgents/com.goosetools.overlay.plist`,
+matching the Carousel/Caption/Brand agents. Logs land in
+`~/.goosetools/overlay-worker.log`. The plist sets PATH explicitly — launchd
+starts with an almost-empty environment, and the render shells out to ffmpeg,
+npx and claude, so an inherited-PATH assumption is what leaves one of these
+agents running but failing every job.
+
+Two passes, and the split is the point. Remotion renders **only the overlay**,
+alpha-only to ProRes 4444, at `--scale` so the 1080x1920 composition rasterizes
+natively at the output resolution. ffmpeg then composites that over the
+untouched source. The footage never enters Chrome, so a 4K clip stays 4K and
+renders in seconds rather than minutes — and every coordinate in the overlay
+components stays in 1080x1920 space no matter the output size.
+
+Output is HEVC in `yuv420p`. That pixel format isn't cosmetic: the overlay
+filter hands back BGRA, and an HEVC file in BGRA imports into iOS Photos as a
+file that won't play.
+
+## Series
+
+What Prints? is special-cased in the worker — it runs your snippet, checks the
+answer against a real run, applies the quality gates, and places the meter
+against the footage. Nothing generated can do that, which is why it stays code.
+
+Every other series is generated. Tapping "+ New series" on Goose Tools queues a
+job; this machine reads your reference images with Claude and writes
+`series/<slug>/`:
+
+```
+series/hot-take/
+  series.json     the fields the form asks for, and where each layer sits
+  claim.html      self-contained HTML+CSS, {{field}} placeholders
+  verdict.html
+```
+
+`series/` is gitignored — each worker builds its own from its own user's
+references, so no two machines have the same set.
+
+The hard rule for templates is **no CSS animation**. Remotion renders by seeking
+to each frame and screenshotting, so a CSS animation or transition freezes on
+whatever the first frame painted. Motion comes from the layer's `enter` value
+(`fade`, `slide-up`, `slide-down`, `pop`), which the composition drives with
+Remotion's own spring. Templates also can't carry `<script>` or any external
+URL; `scripts/series.ts` rejects a generation that does, and the composition
+strips scripts again at render time rather than trusting it.
+
+## Instagram's safe area
+
+`src/overlay/safeArea.ts` holds where Instagram draws over a reel, as
+three rectangles rather than one inset margin — the action rail only runs down
+the lower half, so a flat "keep the right 260px clear" would flag the title and
+card as unsafe when nothing is near them.
+
+| Zone | Area |
+|---|---|
+| top bar | full width, y 0-250 |
+| action rail | x 820-1080, y 1080-1700 |
+| caption | x 0-820, y 1500-1920 |
+
+`npx tsx scripts/check-safe-area.ts episodes/what-prints-00X.json` measures the
+real overlay bounding boxes out of a render (same two-render diff as the
+legibility check) and reports anything intersecting a zone. It also flags
+elements outside the 3:4 centre crop that the profile grid uses for thumbnails.
+
+Numbers are conservative — IG moves its chrome between app versions and notched
+phones differ from flat ones. If something looks wrong on a real phone, adjust
+the zones there and every check follows.
+
+## Does it read on a phone?
+
+`npx tsx scripts/check-legibility.ts episodes/what-prints-00X.json` renders three
+frames twice — once whole, once with `hideOverlays` so only the background
+draws — diffs them to find the overlay pixels, and measures real contrast.
+
+Text (the title) is scored on *local* contrast: strokes against what's
+immediately around them in the finished frame, so the dark halo counts. Panels
+(the code card, the difficulty pill) are scored on how well the opaque block
+separates from the footage, because their internal contrast is fixed by design.
+Thresholds are calibrated against the known-bad title, which measured 4.3:1 and
+would have passed a textbook WCAG bar; the fixed one measures 12.3:1.
+
+`new-episode.ts` runs this automatically after placing the meter.
+
+## Notes
+
+- macOS blocks direct shell reads of `~/Desktop` (TCC). All Desktop I/O goes
+  through Finder AppleScript — that's why ingest/export use `osascript`.
+- Exports are silent; add trending audio in Instagram.
+- The title and code card are in fixed positions every episode (title centred
+  200px from the top, card centred at 86% width). The difficulty meter has a
+  house position too — lower-left at (70, 1400) — and `scripts/place-overlay.ts`
+  only moves it when the footage there is more than 25% busier than the calmest
+  spot available. The comparison is relative because footage with Erin in frame
+  scores high everywhere. Override by editing meterX/meterY.
+- New series (Interviewer, Games): add `src/series/<name>/` with its own
+  composition, register it in `src/Root.tsx`, same episode-JSON pattern.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "overlay-factory-worker",
+  "version": "0.1.0",
+  "description": "The Goose Tools Overlay Factory worker — your computer renders reel overlays for goosetools.com with Remotion and ffmpeg.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ernkerr/reel-factory.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@remotion/cli": "4.0.507",
+    "@remotion/google-fonts": "^4.0.507",
+    "@remotion/media": "^4.0.507",
+    "@remotion/tailwind-v4": "4.0.507",
+    "@vercel/blob": "^2.8.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "remotion": "4.0.507",
+    "sharp": "^0.35.3",
+    "shiki": "^4.4.3",
+    "tailwindcss": "4.0.0",
+    "tsx": "^4.23.12",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@remotion/eslint-config-flat": "4.0.507",
+    "@types/react": "19.2.7",
+    "@types/web": "0.0.166",
+    "eslint": "9.19.0",
+    "prettier": "3.8.1",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "dev": "remotion studio",
+    "build": "remotion bundle",
+    "upgrade": "remotion upgrade",
+    "lint": "eslint src && tsc",
+    "overlay": "tsx scripts/render-overlay.ts",
+    "overlay:worker": "tsx scripts/overlay-worker.ts",
+    "overlay:install": "node worker/cli.mjs install",
+    "overlay:uninstall": "node worker/cli.mjs uninstall",
+    "overlay:status": "node worker/cli.mjs status",
+    "overlay:doctor": "node worker/cli.mjs doctor"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "author": "Erin Kerr",
+  "bin": {
+    "overlay-factory-worker": "worker/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "worker",
+    "scripts",
+    "src",
+    "public/fonts/Handjet-variable.woff2",
+    "remotion.config.ts",
+    "tsconfig.json",
+    "README.md"
+  ]
+}

package/remotion.config.ts

@@ -0,0 +1,14 @@
+/**
+ * Note: When using the Node.JS APIs, the config file
+ * doesn't apply. Instead, pass options directly to the APIs.
+ *
+ * All configuration options: https://remotion.dev/docs/config
+ */
+
+import { Config } from "@remotion/cli/config";
+import { enableTailwind } from '@remotion/tailwind-v4';
+
+Config.setRspack(true);
+Config.setVideoImageFormat("jpeg");
+Config.setOverwriteOutput(true);
+Config.overrideBundlerConfig(enableTailwind);

package/scripts/check-legibility.ts

@@ -0,0 +1,284 @@
+/**
+ * Will the overlays actually read against this b-roll?
+ *
+ * The code gates in quality.ts check the puzzle. This checks the *picture* —
+ * the failure that shipped a title nobody could read over a bright keyboard.
+ *
+ * Renders each sampled frame twice: once whole, once with the overlays hidden
+ * (`hideOverlays`). Pixels that differ are overlay; the second render says what
+ * each one is sitting on. From that we get a real WCAG contrast ratio per
+ * region instead of guessing.
+ *
+ *   npx tsx scripts/check-legibility.ts episodes/what-prints-002.json
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import sharp from "sharp";
+
+const ROOT = join(import.meta.dirname, "..");
+const W = 1080;
+const H = 1920;
+
+/**
+ * Calibrated against two real frames rather than taken off the shelf.
+ *
+ * WCAG's 3:1 for large text assumes static, solid type. A dot-matrix title over
+ * moving footage is neither — it's mostly gaps, and it moves. The title that
+ * shipped unreadable over a bright keyboard measures 4.3:1 here and would have
+ * *passed* a WCAG-derived threshold; the fixed one measures 12.3:1. So the bar
+ * sits above the known-bad case, not at the standard.
+ *
+ * If a future episode fails at a number that looks fine on screen, re-check
+ * these against it rather than assuming the render is wrong.
+ */
+const LIMITS = {
+  // Strokes sitting straight on the footage — the demanding case.
+  text: { fail: 5.0, warn: 8.0 },
+  // An opaque panel only has to separate from what's behind it; its own text
+  // contrast is fixed by the card design and can't be spoiled by the b-roll.
+  panel: { fail: 3.0, warn: 4.5 },
+};
+
+/**
+ * Regions to judge separately, in full-frame pixels.
+ *
+ * The mode matters. "text" elements sit straight on the footage, so every
+ * stroke has to win against whatever is behind it. "panel" elements are opaque
+ * — the code card, the difficulty pill — so their internal text contrast is
+ * fixed by design and the only question is whether the panel separates from the
+ * background. Scoring a panel per-pixel compares its white text against the
+ * footage *behind the panel*, which the viewer never sees, and reports a
+ * failure that isn't real.
+ */
+const REGIONS = [
+  { name: "title", x: 0, y: 150, w: W, h: 420, mode: "text" as const },
+  { name: "card", x: 0, y: 600, w: W, h: 800, mode: "panel" as const },
+  { name: "meter", x: 0, y: 1300, w: W, h: 320, mode: "panel" as const },
+];
+
+type Episode = { durationSec: number; revealAtSec: number };
+
+const srgbToLinear = (c: number) => {
+  const s = c / 255;
+  return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+};
+
+const luminance = (r: number, g: number, b: number) =>
+  0.2126 * srgbToLinear(r) + 0.7152 * srgbToLinear(g) + 0.0722 * srgbToLinear(b);
+
+const contrast = (l1: number, l2: number) => {
+  const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+};
+
+const renderStill = (
+  episodePath: string,
+  frame: number,
+  out: string,
+  hideOverlays: boolean,
+) => {
+  const episode = JSON.parse(readFileSync(episodePath, "utf8")) as object;
+  const props = join(ROOT, ".legibility-props.json");
+  writeFileSync(props, JSON.stringify({ ...episode, hideOverlays }));
+  try {
+    execFileSync(
+      "npx",
+      [
+        "remotion",
+        "still",
+        "WhatPrints",
+        out,
+        `--props=${props}`,
+        `--frame=${frame}`,
+        "--log=error",
+      ],
+      { cwd: ROOT, stdio: "inherit" },
+    );
+  } finally {
+    rmSync(props, { force: true });
+  }
+};
+
+const raw = async (file: string) => {
+  const { data, info } = await sharp(file)
+    .resize(W, H, { fit: "fill" })
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  return { data, channels: info.channels };
+};
+
+/** How far out from a stroke to look for "the background right next to it". */
+const RING = 7;
+
+/**
+ * Text: local contrast between the strokes and what immediately surrounds them
+ * in the finished frame.
+ *
+ * Not stroke-vs-footage-underneath. The title carries a dark halo, so a white
+ * dot on a bright desk still reads fine — the eye compares the dot to the halo
+ * around it, not to the desk it hides. Measuring against the raw footage scores
+ * a perfectly readable title as a failure.
+ *
+ * Strokes are the pixels the two renders strongly disagree about; the ring is
+ * everything just outside them, sampled from the composited frame so the halo
+ * and scrim count.
+ */
+const scoreRegion = (
+  full: Uint8Array,
+  bg: Uint8Array,
+  ch: number,
+  r: (typeof REGIONS)[number],
+) => {
+  const x0 = r.x;
+  const y0 = r.y;
+  const w = Math.min(W, r.x + r.w) - x0;
+  const h = Math.min(H, r.y + r.h) - y0;
+
+  const stroke = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = ((y + y0) * W + (x + x0)) * ch;
+      const d =
+        Math.abs(full[i] - bg[i]) +
+        Math.abs(full[i + 1] - bg[i + 1]) +
+        Math.abs(full[i + 2] - bg[i + 2]);
+      // Solid strokes only. Anti-aliased edges sit between the two colours by
+      // definition, and there are a lot of them around thousands of small
+      // squares — counting them would drag any percentile down to ~1:1.
+      if (d >= 200) stroke[y * w + x] = 1;
+    }
+  }
+
+  // Separable max filter = dilation; ring is what the dilation added.
+  const dil = new Uint8Array(w * h);
+  const tmp = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++)
+    for (let x = 0; x < w; x++) {
+      let on = 0;
+      for (let k = -RING; k <= RING && !on; k++) {
+        const xx = x + k;
+        if (xx >= 0 && xx < w && stroke[y * w + xx]) on = 1;
+      }
+      tmp[y * w + x] = on;
+    }
+  for (let y = 0; y < h; y++)
+    for (let x = 0; x < w; x++) {
+      let on = 0;
+      for (let k = -RING; k <= RING && !on; k++) {
+        const yy = y + k;
+        if (yy >= 0 && yy < h && tmp[yy * w + x]) on = 1;
+      }
+      dil[y * w + x] = on;
+    }
+
+  const strokeLum: number[] = [];
+  const ringLum: number[] = [];
+  for (let y = 0; y < h; y++)
+    for (let x = 0; x < w; x++) {
+      const p = y * w + x;
+      if (!dil[p]) continue;
+      const i = ((y + y0) * W + (x + x0)) * ch;
+      const l = luminance(full[i], full[i + 1], full[i + 2]);
+      if (stroke[p]) strokeLum.push(l);
+      else ringLum.push(l);
+    }
+
+  if (strokeLum.length < 200 || !ringLum.length) return null;
+  const mid = (n: number[]) => n.sort((a, b) => a - b)[n.length >> 1];
+  // The ring's brightest quarter is the hardest thing the strokes compete with.
+  const sorted = ringLum.sort((a, b) => a - b);
+  const ringHigh = sorted[Math.floor(sorted.length * 0.75)];
+  const ratio = contrast(mid(strokeLum), ringHigh);
+  return { pixels: strokeLum.length, p10: ratio, median: ratio };
+};
+
+/**
+ * Panels: how well the opaque block separates from the footage around it.
+ * Compares the panel body's typical luminance to the typical luminance of what
+ * it covers, so a dark card on a dark desk is what fails here — not its text.
+ */
+const scorePanel = (
+  full: Uint8Array,
+  bg: Uint8Array,
+  ch: number,
+  r: (typeof REGIONS)[number],
+) => {
+  const fl: number[] = [];
+  const bl: number[] = [];
+  for (let y = r.y; y < Math.min(H, r.y + r.h); y++) {
+    for (let x = r.x; x < Math.min(W, r.x + r.w); x++) {
+      const i = (y * W + x) * ch;
+      const d =
+        Math.abs(full[i] - bg[i]) +
+        Math.abs(full[i + 1] - bg[i + 1]) +
+        Math.abs(full[i + 2] - bg[i + 2]);
+      if (d < 90) continue;
+      fl.push(luminance(full[i], full[i + 1], full[i + 2]));
+      bl.push(luminance(bg[i], bg[i + 1], bg[i + 2]));
+    }
+  }
+  if (!fl.length) return null;
+  const mid = (n: number[]) => n.sort((a, b) => a - b)[n.length >> 1];
+  const ratio = contrast(mid(fl), mid(bl));
+  return { pixels: fl.length, p10: ratio, median: ratio };
+};
+
+const main = async () => {
+  const episodePath = process.argv[2];
+  if (!episodePath) {
+    console.error("usage: check-legibility.ts <episode.json>");
+    process.exit(1);
+  }
+  const ep = JSON.parse(readFileSync(episodePath, "utf8")) as Episode;
+  const dir = mkdtempSync(join(tmpdir(), "reel-legibility-"));
+
+  // Sample after the meter appears so every overlay is on screen.
+  const fps = 30;
+  const frames = [
+    Math.round((ep.revealAtSec + 0.5) * fps),
+    Math.round(((ep.revealAtSec + ep.durationSec) / 2) * fps),
+    Math.round((ep.durationSec - 0.4) * fps),
+  ];
+
+  const worst = new Map<string, number>();
+  const modeOf = new Map(REGIONS.map((r) => [r.name, r.mode]));
+  for (const f of frames) {
+    const a = join(dir, `full-${f}.png`);
+    const b = join(dir, `bg-${f}.png`);
+    renderStill(episodePath, f, a, false);
+    renderStill(episodePath, f, b, true);
+    const [full, bg] = [await raw(a), await raw(b)];
+
+    for (const r of REGIONS) {
+      const s =
+        r.mode === "panel"
+          ? scorePanel(full.data, bg.data, full.channels, r)
+          : scoreRegion(full.data, bg.data, full.channels, r);
+      if (!s) continue;
+      const prev = worst.get(r.name);
+      if (prev === undefined || s.p10 < prev) worst.set(r.name, s.p10);
+    }
+  }
+  rmSync(dir, { recursive: true, force: true });
+
+  console.log(`\n${episodePath} — worst contrast across ${frames.length} frames`);
+  let failed = false;
+  for (const [name, p10] of worst) {
+    const lim = LIMITS[modeOf.get(name) ?? "text"];
+    const verdict = p10 < lim.fail ? "FAIL" : p10 < lim.warn ? "warn" : "ok";
+    if (p10 < lim.fail) failed = true;
+    console.log(`  ${name.padEnd(6)} ${p10.toFixed(1)}:1  ${verdict}`);
+  }
+  console.log(
+    failed
+      ? `\nThat overlay stops reading on a phone. Darken the\n` +
+          `scrim in Composition.tsx, or pick calmer b-roll for this episode.`
+      : "",
+  );
+  process.exit(failed ? 1 : 0);
+};
+
+main();