overlay-factory-worker 0.1.0

package/src/overlay/Title.tsx

@@ -0,0 +1,75 @@
+import React from "react";
+import { sansFamily } from "./fonts";
+import { PixelText } from "./PixelText";
+
+// Mixed-typography title in the style of the inspiration reel:
+// line 1 in Instagram-style geometric bold, line 2 rasterized to a dot matrix.
+export const Title: React.FC<{
+  line1: string;
+  line2: string;
+  /** From the series look — see src/overlay/look.ts. */
+  sansSize?: number;
+  rows?: number;
+  cell?: number;
+  gap?: number;
+  weight?: number;
+  /** Family name; must be one the renderer loads (see brandFonts.ts). */
+  family?: string;
+}> = ({
+  line1,
+  line2,
+  sansSize = 112,
+  rows = 16,
+  cell = 9,
+  gap = 2,
+  weight = 700,
+  family,
+}) => {
+  // Falls back to Poppins rather than to a system font: a title in the wrong
+  // face is a silent design regression, and this is the last place to catch it.
+  const face = family ? `"${family}", ${sansFamily}` : sansFamily;
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: 18,
+        textAlign: "center",
+      }}
+    >
+      <div
+        style={{
+          fontFamily: face,
+          fontWeight: 700,
+          fontSize: sansSize,
+          lineHeight: 1.02,
+          color: "white",
+          textShadow:
+            "0 0 4px rgba(0,0,0,0.9), 0 4px 20px rgba(0,0,0,0.6)",
+        }}
+      >
+        {line1}
+      </div>
+      {/*
+        Fine dots, thick strokes. The old 10/15/3 at weight 300 drew big sparse
+        squares that read as a pattern rather than as a dot-matrix display; the
+        reference is denser and heavier than that.
+
+        Chosen by rendering the alternatives side by side at this exact size —
+        see src/lab/FontSheet.tsx, which also shows why this stays a rasterizer.
+        Every real pixel font available (Handjet at any weight or shape axis,
+        Silkscreen, Pixelify Sans, Micro 5, DotGothic16, Jersey) draws SOLID
+        blocks. None of them make separated dots, which is the whole look.
+      */}
+      <PixelText
+        text={line2}
+        fontFamily={face}
+        fontWeight={weight}
+        rows={rows}
+        cell={cell}
+        gap={gap}
+      />
+    </div>
+  );
+};

package/src/overlay/brandFonts.ts

@@ -0,0 +1,58 @@
+// The brand fonts, made available to generated series templates.
+//
+// A template writes font-family: var(--brand-font-heading), and that variable
+// names a family — naming it isn't loading it. Without this the family silently
+// falls through to the system fallback, which looks like the brand simply not
+// applying and gives no error to chase.
+//
+// These are the curated families the Goose Tools brand form offers (see
+// HEADING_FONTS / BODY_FONTS in goosetools' src/lib/brand-kit.ts). Keep the two
+// lists in step: a family offered there but missing here renders as fallback.
+//
+// Loading all of them costs almost nothing at render time — loadFont only
+// injects @font-face rules, and the browser fetches a face only when something
+// actually uses it. That beats loading conditionally, which would mean calling
+// loaders from inside a render.
+
+import { loadFont as instrumentSerif } from "@remotion/google-fonts/InstrumentSerif";
+import { loadFont as spaceGrotesk } from "@remotion/google-fonts/SpaceGrotesk";
+import { loadFont as fraunces } from "@remotion/google-fonts/Fraunces";
+import { loadFont as archivo } from "@remotion/google-fonts/Archivo";
+import { loadFont as bricolage } from "@remotion/google-fonts/BricolageGrotesque";
+import { loadFont as dmSerifDisplay } from "@remotion/google-fonts/DMSerifDisplay";
+import { loadFont as inter } from "@remotion/google-fonts/Inter";
+import { loadFont as dmSans } from "@remotion/google-fonts/DMSans";
+import { loadFont as workSans } from "@remotion/google-fonts/WorkSans";
+import { loadFont as ibmPlexSans } from "@remotion/google-fonts/IBMPlexSans";
+import { loadFont as spaceMono } from "@remotion/google-fonts/SpaceMono";
+
+// Called individually rather than mapped over an array: each family's loadFont
+// is generically typed over its own variant table, so a shared array collapses
+// them to a union TypeScript won't call.
+const LOADED = [
+  instrumentSerif(),
+  spaceGrotesk(),
+  fraunces(),
+  archivo(),
+  bricolage(),
+  dmSerifDisplay(),
+  inter(),
+  dmSans(),
+  workSans(),
+  ibmPlexSans(),
+  spaceMono(),
+];
+
+export const BRAND_FONT_FAMILIES = LOADED.map((f) => f.fontFamily);
+
+/**
+ * Resolves once every face is actually usable.
+ *
+ * Injecting @font-face is not the same as having the font: the renderer will
+ * happily capture a frame while the face is still loading, and the text comes
+ * out in the fallback with no warning. The composition holds the frame on this
+ * via delayRender — the same thing PixelText does before it rasterizes.
+ */
+export const brandFontsReady: Promise<unknown> = Promise.all(
+  LOADED.map((f) => f.waitUntilDone()),
+);

package/src/overlay/cardLayout.ts

@@ -0,0 +1,94 @@
+/**
+ * Where the code card sits, and how big it is.
+ *
+ * This lived in three places that disagreed: src/overlay/Composition.tsx,
+ * src/series/what-prints/Composition.tsx, and scripts/place-overlay.ts. The
+ * placement script assumed the card was centred on H/2 and 86% wide; both
+ * compositions centre it on SAFE_CENTER_Y and cap its HEIGHT, which for a
+ * normal five-line card binds first and makes it ~83% wide, 85px higher than
+ * the script believed. The meter was therefore placed against a card that
+ * wasn't where it was thought to be.
+ */
+import { CARD_MAX_HEIGHT, FRAME, SAFE_AREA, SAFE_CENTER_Y } from "./safeArea";
+
+/** Fraction of frame width the card may occupy when nothing is in its way. */
+export const CARD_WIDTH_PCT = 0.86;
+
+/**
+ * How small the card may get to avoid something — a face, mainly.
+ *
+ * Below about two thirds the code stops being readable on a phone, at which
+ * point a smaller card is worse than an obscured one.
+ */
+export const CARD_MIN_WIDTH_PCT = 0.62;
+
+/**
+ * Where the title stops, measured rather than guessed.
+ *
+ * Title.tsx draws line 1 at fontSize 112 (lineHeight 1.02), an 18px gap, then
+ * the dot-matrix line at rows 16 x cell 9. It starts at SAFE_AREA.top + 12.
+ * The card has to begin below all of that: dodging a face by sliding UP is
+ * useless if it lands on the title instead.
+ */
+export const TITLE_BOTTOM = SAFE_AREA.top + 12 + Math.round(112 * 1.02) + 18 + 16 * 9;
+
+export type CardBox = {
+  /** Drawn size in frame pixels. */
+  width: number;
+  height: number;
+  /** Top-left, for hit-testing against the UI zones and the energy map. */
+  x: number;
+  y: number;
+  bottom: number;
+};
+
+/**
+ * The box a card of this aspect ratio actually draws, given a width fraction
+ * and an optional vertical centre.
+ *
+ * Both bounds are maxima with the aspect preserved, exactly as the `Img` in
+ * Composition.tsx behaves — so whichever binds first wins, and callers can't
+ * drift from what gets rendered.
+ */
+export const cardBox = (
+  aspect: number, // natural height / natural width
+  widthPct: number = CARD_WIDTH_PCT,
+  centerY: number = SAFE_CENTER_Y,
+  maxHeight: number = CARD_MAX_HEIGHT,
+): CardBox => {
+  let width = FRAME.width * widthPct;
+  let height = width * aspect;
+  if (height > maxHeight) {
+    height = maxHeight;
+    width = height / aspect;
+  }
+  return {
+    width,
+    height,
+    x: (FRAME.width - width) / 2,
+    y: centerY - height / 2,
+    bottom: centerY + height / 2,
+  };
+};
+
+/**
+ * Vertical range the card's centre may be moved within.
+ *
+ * Bounded by Instagram's own chrome rather than by taste: above the top bar it
+ * gets covered by the Reels header, below the caption band it gets covered by
+ * the caption. Moving DOWN is the useful direction — a face is usually
+ * centre-frame and slightly high, and the calm space is under it.
+ *
+ * `reserveBelow` keeps room for whatever has to sit under the card. Without
+ * it the search happily shoves the card to the bottom of the legal area to
+ * dodge a face, leaving the difficulty meter — which reads as the answer to
+ * the snippet and so must sit below it — with nowhere legal to go at all.
+ */
+export const cardCenterRange = (
+  height: number,
+  reserveBelow = 0,
+): [number, number] => {
+  const top = TITLE_BOTTOM + 24 + height / 2;
+  const bottom = 1500 - reserveBelow - height / 2 - 20; // 1500 = caption band
+  return [Math.min(top, bottom), Math.max(top, bottom)];
+};

package/src/overlay/fonts.ts

@@ -0,0 +1,19 @@
+import { loadFont as loadPoppins } from "@remotion/google-fonts/Poppins";
+import { loadFont as loadHandjet } from "@remotion/google-fonts/Handjet";
+
+// Poppins is the closest free stand-in for Instagram's "Modern" title font —
+// geometric, circular bowls, single-story g. Used for "What" and the pill.
+export const { fontFamily: sansFamily } = loadPoppins("normal", {
+  weights: ["300", "400", "500", "700"],
+  subsets: ["latin"],
+});
+
+// Handjet is a variable dot-matrix face. Its separated square pixels (the look
+// in the title inspiration) come from a light weight on the coarse element grid:
+// heavier weights fill the gaps in, lighter ones fade out.
+export const { fontFamily: pixelFamily } = loadHandjet("normal", {
+  weights: ["300", "400", "500"],
+  subsets: ["latin"],
+});
+
+export const PIXEL_VARIATION = '"ELGR" 1, "ELSH" 0';

package/src/overlay/look.ts

@@ -0,0 +1,155 @@
+/**
+ * The What Prints? look, as data.
+ *
+ * Generated series are HTML templates, so feedback can regenerate them
+ * wholesale. What Prints? isn't — its card is rendered by CodeCard.tsx with
+ * real syntax highlighting, and its answer-checking and quality gates depend
+ * on that path. So its look is exposed as parameters instead, and feedback
+ * edits those.
+ *
+ * That trade is deliberate and worth stating plainly: this can move, resize,
+ * restyle and re-weight what's already there. It cannot invent a new
+ * arrangement. "Make the code smaller", "less rounded", "move it down",
+ * "bigger title", "lose the language label" all work. "Put the answer in a
+ * speech bubble" does not — that needs a template, which is what the
+ * generated-series path is for.
+ *
+ * Everything here has a default that reproduces the current design, so an
+ * absent or partial look.json is always safe.
+ */
+import { z } from "zod";
+
+/**
+ * Typefaces available to the title.
+ *
+ * Every one of these is loaded by src/overlay/brandFonts.ts, which blocks the
+ * frame until the faces are usable. A family outside this list would render as
+ * a system fallback with no error — which looks like the change silently not
+ * working, and is exactly the failure this list exists to prevent.
+ */
+export const TITLE_FAMILIES = [
+  "Poppins",
+  "Instrument Serif",
+  "Space Grotesk",
+  "Fraunces",
+  "Archivo",
+  "Bricolage Grotesque",
+  "DM Serif Display",
+  "Inter",
+  "DM Sans",
+  "Work Sans",
+  "IBM Plex Sans",
+] as const;
+
+export const lookSchema = z.object({
+  card: z
+    .object({
+      /** Fraction of frame width, 0.5–0.95. */
+      widthPct: z.number().min(0.5).max(0.95).optional(),
+      /** Corner radius as a fraction of card width. */
+      radiusPct: z.number().min(0).max(0.12).optional(),
+      /** Card fill. */
+      background: z.string().optional(),
+      /** 0–1. Below ~0.75 the code starts fighting the footage. */
+      opacity: z.number().min(0.3).max(1).optional(),
+      /** The "Python" label above the snippet. */
+      showLanguage: z.boolean().optional(),
+      /** Multiplier on the code type size. */
+      codeScale: z.number().min(0.6).max(1.4).optional(),
+      /**
+       * CENTRE of the card, in 1080x1920 space. Set only when it has been
+       * placed by hand; null means "let the placement script decide", which
+       * is the default and what handles footage it hasn't seen.
+       *
+       * x exists so the card can be moved like anything else on the frame.
+       * It stays centred when null, which is where a code card almost always
+       * wants to be — but "almost always" is not "always", and a face on one
+       * side of the shot is the obvious case.
+       */
+      x: z.number().min(0).max(1080).nullable().optional(),
+      y: z.number().min(200).max(1700).nullable().optional(),
+    })
+    .optional(),
+  title: z
+    .object({
+      /**
+       * The typeface for BOTH title lines — line 1 directly, and line 2 as the
+       * face being rasterized into dots, so it changes the letterforms too.
+       * Restricted to families the renderer actually loads: naming one it
+       * doesn't have would silently fall back to a system font.
+       */
+      // Not an enum: an uploaded font is a valid family too, and the worker
+      // is the only thing that knows which ones exist on this machine. The
+      // allowed set is checked at feedback time instead — see look-store.ts.
+      family: z.string().max(60).optional(),
+      /** Line 1, the geometric bold line. */
+      sansSize: z.number().min(60).max(160).optional(),
+      /** Dot-matrix cap height in grid cells — more rows = finer dots. */
+      rows: z.number().min(8).max(24).optional(),
+      /** Grid pitch in px. */
+      cell: z.number().min(5).max(20).optional(),
+      /** Space inside the pitch, so the dot is cell - gap. */
+      gap: z.number().min(0).max(6).optional(),
+      /** Weight of the face being rasterized — this is the stroke thickness. */
+      weight: z.number().min(100).max(900).optional(),
+      /** The dark wash behind the title. */
+      scrim: z.boolean().optional(),
+    })
+    .optional(),
+  meter: z
+    .object({
+      show: z.boolean().optional(),
+      /** Top-left of the badge. Null on either axis means automatic. */
+      x: z.number().min(0).max(1080).nullable().optional(),
+      y: z.number().min(0).max(1920).nullable().optional(),
+    })
+    .optional(),
+});
+
+/**
+ * How far each piece may be moved, in 1080x1920 space.
+ *
+ * Exported because the browser needs to clamp a drag to exactly this. When it
+ * clamped to the frame instead, a card dragged near the top or bottom was
+ * accepted by the UI and rejected by the schema — the position was lost, the
+ * preview showed one thing and the burn did another, and nothing said so.
+ */
+export const LOOK_BOUNDS = {
+  card: { x: [0, 1080], y: [200, 1700] },
+  meter: { x: [0, 1080], y: [0, 1920] },
+} as const;
+
+export type Look = z.infer<typeof lookSchema>;
+
+/** The shipped design. Every field the schema allows has a value here. */
+export const DEFAULT_LOOK = {
+  card: {
+    widthPct: 0.86,
+    radiusPct: 0.045,
+    background: "#212121",
+    opacity: 1,
+    showLanguage: true,
+    codeScale: 1,
+    x: null,
+    y: null,
+  },
+  title: {
+    family: "Poppins" as (typeof TITLE_FAMILIES)[number],
+    sansSize: 112,
+    rows: 16,
+    cell: 9,
+    gap: 2,
+    weight: 700,
+    scrim: true,
+  },
+  meter: { show: true, x: null, y: null },
+} as const;
+
+/** A look with every gap filled from the shipped design. */
+export const resolveLook = (look: Look | null | undefined) => ({
+  card: { ...DEFAULT_LOOK.card, ...(look?.card ?? {}) },
+  title: { ...DEFAULT_LOOK.title, ...(look?.title ?? {}) },
+  meter: { ...DEFAULT_LOOK.meter, ...(look?.meter ?? {}) },
+});
+
+export type ResolvedLook = ReturnType<typeof resolveLook>;

package/src/overlay/safeArea.ts

@@ -0,0 +1,89 @@
+/**
+ * Where Instagram covers a reel with its own interface.
+ *
+ * A 1080x1920 reel is never shown clean: the app draws the status bar and
+ * "Reels" header over the top, the caption / username / audio row over the
+ * bottom, and the like-comment-share-audio rail down the right. Anything the
+ * composition puts in those bands is either hidden or fighting IG's own UI.
+ *
+ * These are deliberately conservative. Instagram moves its chrome between app
+ * versions and the bars sit differently on a notched phone versus a flat one,
+ * so the numbers below leave slack rather than hugging any one build. Treat
+ * them as "don't put anything you need read here", not as measurements.
+ */
+export const FRAME = { width: 1080, height: 1920 } as const;
+
+/**
+ * The chrome as actual rectangles, not margins.
+ *
+ * Modelling it as a single inset rectangle gets the right-hand side wrong: the
+ * action rail only runs down the *lower* half, so a flat "keep 260px clear on
+ * the right" reports the title and the code card as unsafe when nothing is
+ * drawn near them. A check that cries wolf gets ignored, so the zones match
+ * where the controls actually are.
+ */
+export const UI_ZONES = [
+  {
+    name: "top bar",
+    x: 0,
+    y: 0,
+    width: FRAME.width,
+    height: 250, // status bar + the Reels header row
+  },
+  {
+    name: "action rail",
+    x: FRAME.width - 260,
+    y: 1080,
+    width: 260,
+    height: 620, // like / comment / share / save / audio disc
+  },
+  {
+    name: "caption",
+    x: 0,
+    y: 1500,
+    width: FRAME.width - 260,
+    height: FRAME.height - 1500, // username, caption, audio title
+  },
+] as const;
+
+/** Convenience for layout code that just wants the clear middle band. */
+export const SAFE_AREA = {
+  top: 250,
+  bottom: 420,
+  left: 60,
+  right: 260,
+} as const;
+
+/** Vertical centre of the band that is never covered — where the card belongs. */
+export const SAFE_CENTER_Y = Math.round((SAFE_AREA.top + 1500) / 2);
+
+/**
+ * Tallest the code card may render. Centring alone isn't enough: a 6-line card
+ * centred on SAFE_CENTER_Y still reaches past y=1080 and puts its bottom-right
+ * corner behind the like button. Capping the height means a long snippet gets
+ * a little smaller instead of sliding under the rail.
+ *
+ * The 60px allowance is the drop shadow: it paints ~20px past the image on each
+ * axis, so a cap set to the bare image height still lands shadow under the rail
+ * (and check-safe-area.ts measures drawn pixels, shadow included).
+ */
+export const CARD_MAX_HEIGHT = (1080 - SAFE_CENTER_Y) * 2 - 60;
+
+export const overlaps = (
+  box: { top: number; bottom: number; left: number; right: number },
+  z: (typeof UI_ZONES)[number],
+) =>
+  box.right >= z.x &&
+  box.left <= z.x + z.width &&
+  box.bottom >= z.y &&
+  box.top <= z.y + z.height;
+
+/**
+ * The profile grid crops a reel to 3:4 about its centre, so the cover
+ * thumbnail loses ~240px off the top and bottom of the frame. Anything that has
+ * to survive in the grid — the title, mainly — needs to sit inside this too.
+ */
+export const GRID_CROP = {
+  top: Math.round((FRAME.height - (FRAME.width * 4) / 3) / 2),
+  bottom: Math.round((FRAME.height - (FRAME.width * 4) / 3) / 2),
+} as const;

package/src/overlay/types.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+
+/**
+ * Props for the generic `Overlay` composition — the overlay layers on their
+ * own, with nothing behind them.
+ *
+ * The composition renders at 1080x1920 and is scaled up at render time
+ * (`--scale=2` for 4K), so every coordinate in here is in 1080x1920 space no
+ * matter what resolution the footage is. That's deliberate: the safe-area
+ * numbers, the meter placement chosen by scripts/place-overlay.ts, and the
+ * type sizes baked into Title/DifficultyMeter are all tuned against that
+ * frame, and they stay correct for 4K output without being touched.
+ */
+
+/** Every layer can be limited to a slice of the clip. Omitted = whole clip. */
+const timing = {
+  fromSec: z.number().optional(),
+  toSec: z.number().optional(),
+};
+
+const titleLayer = z.object({
+  type: z.literal("title"),
+  line1: z.string(),
+  line2: z.string(),
+  // Look knobs, supplied by the series' look.json. Absent = the shipped design.
+  sansSize: z.number().optional(),
+  rows: z.number().optional(),
+  cell: z.number().optional(),
+  gap: z.number().optional(),
+  weight: z.number().optional(),
+  family: z.string().optional(),
+  /**
+   * The gradient wash behind the title. The dot-matrix line is mostly gaps, so
+   * over bright footage the squares stop reading as letters — this buys back
+   * contrast without touching the typography. On for anything shot outdoors or
+   * against a white desk.
+   */
+  scrim: z.boolean().optional(),
+  /** Top offset. Defaults to just under Instagram's Reels header. */
+  y: z.number().optional(),
+  ...timing,
+});
+
+const pixelTextLayer = z.object({
+  type: z.literal("pixelText"),
+  text: z.string(),
+  /** Cap height in grid cells — the stroke-thickness control. */
+  rows: z.number().optional(),
+  /** On-screen size of one grid cell, in px. */
+  cell: z.number().optional(),
+  gap: z.number().optional(),
+  color: z.string().optional(),
+  x: z.number().optional(),
+  y: z.number().optional(),
+  ...timing,
+});
+
+const imageLayer = z.object({
+  type: z.literal("image"),
+  /** An http(s) URL, or a path under public/ for a local render. */
+  src: z.string(),
+  /**
+   * Omit both to centre on the band Instagram never covers — which is where a
+   * code card belongs. Dead-centring the frame instead puts the lower edge
+   * under the like/comment rail.
+   */
+  x: z.number().optional(),
+  y: z.number().optional(),
+  /** Fraction of frame width, 0-1. Defaults to 0.86, matching the code cards. */
+  widthPct: z.number().optional(),
+  maxHeight: z.number().optional(),
+  /** Let the footage through the card. 1 = solid, the shipped design. */
+  opacity: z.number().optional(),
+  ...timing,
+});
+
+/**
+ * A block of self-contained HTML/CSS drawn over the footage — how a generated
+ * series gets a look of its own without anyone writing a component for it.
+ *
+ * Remotion renders by seeking to each frame and screenshotting, so CSS
+ * animations and transitions never advance: they'd freeze at whatever the
+ * first frame painted. Motion therefore comes from `enter`, which is driven by
+ * Remotion's own spring and applied as an inline transform. Templates supply
+ * the look; the engine supplies the movement.
+ */
+const htmlLayer = z.object({
+  type: z.literal("html"),
+  html: z.string(),
+  /** Fraction of frame width, 0-1. Default 0.86 — matches the code cards. */
+  widthPct: z.number().optional(),
+  x: z.number().optional(),
+  y: z.number().optional(),
+  /** Used when x/y are absent. `center` means the safe band, not the frame. */
+  anchor: z.enum(["top", "center", "bottom"]).optional(),
+  enter: z.enum(["none", "fade", "slide-up", "slide-down", "pop"]).optional(),
+  ...timing,
+});
+
+const meterLayer = z.object({
+  type: z.literal("meter"),
+  difficulty: z.enum(["easy", "medium", "hard"]),
+  x: z.number().optional(),
+  y: z.number().optional(),
+  ...timing,
+});
+
+export const overlayLayerSchema = z.discriminatedUnion("type", [
+  titleLayer,
+  pixelTextLayer,
+  imageLayer,
+  htmlLayer,
+  meterLayer,
+]);
+
+/**
+ * A font the user uploaded, already fetched and verified by the worker.
+ * `file` is a path under public/ — never a remote URL, so a render can't hang
+ * waiting on the network.
+ */
+const fontFace = z.object({
+  family: z.string(),
+  file: z.string(),
+  format: z.string(),
+});
+
+export const overlaySchema = z.object({
+  durationSec: z.number(),
+  layers: z.array(overlayLayerSchema),
+  fonts: z.array(fontFace).optional(),
+});
+
+export type OverlayLayer = z.infer<typeof overlayLayerSchema>;
+export type OverlayProps = z.infer<typeof overlaySchema>;