@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/embedded-captions/modes/standard/_motion.md

@@ -0,0 +1,192 @@
+---
+name: caption-template-motion
+description: The named flow + climax entrance/exit recipes (GSAP, seek-safe) that the per-template files reference, plus the motion numerics (ease palette, exit=75% entry, climax dwell, restraint, mood→motion). Every template picks a FLOW_IN/OUT and a CLIMAX_IN/OUT from here — look up only the 2-3 recipes a template names (grep the `### name`), this is a catalog, not a read-through.
+metadata:
+  tags: gsap, easing, entrance, exit, timing, restraint, mood-matching, captions
+---
+
+# Caption Template — Motion Language
+
+`_anatomy.md` wires four hooks onto one paused timeline: `FLOW_IN`, `FLOW_OUT`, `CLIMAX_IN`, `CLIMAX_OUT`. This file is the catalog each template picks from. Each recipe is a GSAP tween on the climax `span` (or a flow `.w`); placed at an absolute time it is fully **seek-safe**. Multi-stage looks use GSAP `keyframes:{}` (still seek-safe) — never CSS keyframes.
+
+## Numerics (shared)
+
+**Ease palette** (sanctioned — reads clean on video, stays distinct):
+
+| Curve           | GSAP                                    | Use                                                 |
+| --------------- | --------------------------------------- | --------------------------------------------------- |
+| overshoot entry | `back.out(1.4–1.7)`                     | confident arrivals (premium/epic/creator)           |
+| heavy/refined   | `power3.out`                            | hero/secondary entrances, slides                    |
+| general         | `power2.out`                            | fades, scales                                       |
+| exit accel      | `power2.in`                             | the _exit_ side of any move (departure accelerates) |
+| snappy          | `expo.out`                              | warp/fly/sonic confident snaps                      |
+| breathing       | `sine.inOut`                            | gentle wellness drift                               |
+| impact thud     | `back.out(1.5–2)` or a quick `expo.out` | slam/stomp/stamp landings                           |
+| linear driver   | `none`                                  | the asr active-word envelope driver only            |
+| digital stutter | `steps(n)`                              | glitch/vhs/blink/possess/cut                        |
+
+**Forbidden:** `bounce.out`, `elastic.out` everywhere **except** the Playful cluster (explicit playfulness — KIDS drop-bounce, CANDY jelly). Elsewhere real objects decelerate; they don't bounce. Use low `back.out` for sanctioned overshoot.
+
+**Durations** — flow word enter 0.30–0.50 s · climax entrance 0.6–1.6 s · **exit ≈ 75 % of entry** (arrival deliberate, departure swift) · stagger 50–150 ms / word.
+
+**Restraint (the rule that makes it premium):** the FLOW stays clean — a tasteful reveal + the active-word accent, no effects. The big mood move + any scene effect (flash, shockwave, shake) happens **only at the CLIMAX**, then clears. Never sprinkle effects across the flow.
+
+**Climax dwell ≥ 1 s** after the entrance finishes — the climax is the headline beat.
+
+**Mood → motion** (pick an entrance whose physics match the theme):
+
+| Mood                            | Entrances                                            |
+| ------------------------------- | ---------------------------------------------------- |
+| premium                         | deblur · rise · expose · breathe · flip              |
+| epic                            | slam · monument · fly · grandrise                    |
+| cyber                           | glitch · type · scan · boot                          |
+| horror                          | loom · possess · glimpse · seep (never bouncy/clean) |
+| luxury                          | tracking-expand · hairrise                           |
+| retro                           | vhs · stamp · blink · type                           |
+| neon                            | ignite · buzz                                        |
+| hype                            | stomp · punch · slap                                 |
+| playful                         | jelly · dropb · scrawl · popr                        |
+| creator                         | boxpop · slideup · flip · shimmer                    |
+| ultra (flash in the type)       | volt · hyper · liquid · prism · shatter · extrude    |
+| atelier (design)                | editwipe · rise · block · vert · ink · weight        |
+| impact (scene effect at climax) | nuke · meteor · sonic · seismic · judge              |
+
+---
+
+## FLOW entrances / exits (per word `.w`)
+
+The flow caption reveals word-by-word from the transcript. The active word gets `.act` (→ `--cacc`). Exit hard-hides the group.
+
+- **fade-up** (premium/atelier default) — `fromTo(w,{opacity:0,y:14},{opacity:1,y:0,duration:.42,ease:'power3.out'})`
+- **pop** (epic/hype) — `fromTo(w,{opacity:0,scale:.5},{opacity:1,scale:1,duration:.34,ease:'back.out(1.6)'})`
+- **whip** (kinetic) — `fromTo(w,{opacity:0,x:-30,filter:'blur(10px)'},{opacity:1,x:0,filter:'blur(0)',duration:.32,ease:'expo.out'})`
+- **glitch** (cyber) — `fromTo(w,{opacity:0,clipPath:'inset(45% 0 45% 0)'},{opacity:1,clipPath:'inset(0)',duration:.4,ease:'steps(6)'})`
+- **type** (terminal/retro) — `fromTo(w,{opacity:0},{opacity:1,duration:.2,ease:'steps(3)'})` staggered as the cadence
+- **blur-in** (horror) — `fromTo(w,{opacity:0,filter:'blur(10px)',y:'.1em'},{opacity:1,filter:'blur(0)',y:0,duration:.6,ease:'power2.out'})`
+- **karaoke** (creator) — words start visible-dim; on `w.start` `set(w,{className:'w act'})` (active → `--cacc`), prior word back to spoken. The signature verbatim mechanic.
+- **flow exits** — fade-up-out `to{opacity:0,y:-10}` · horror smear `to{opacity:0,x:6,skewX:10,filter:'blur(5px)'}` · all ≈0.4–0.55 s.
+
+---
+
+## CLIMAX entrances
+
+Each is a `gsap.fromTo(span, {from}, {to, duration, ease})`. Where a `keyframes:{}` is shown, pass it as the 2nd arg's `keyframes`.
+
+### premium
+
+- **deblur** — `{opacity:0,scale:.96,filter:'blur(8px)'}→{opacity:1,scale:1,filter:'blur(0)',duration:.8,ease:'power3.out'}`
+- **rise** — `{opacity:0,yPercent:48}→{opacity:1,yPercent:0,duration:.9,ease:'power3.out'}`
+- **expose** — `{opacity:0,filter:'brightness(3.2) blur(5px)',scale:1.05}→{opacity:1,filter:'brightness(1) blur(0)',scale:1,duration:1,ease:'power2.out'}`
+- **breathe** — `{opacity:0,scale:1.09,filter:'blur(8px)'}→{opacity:1,scale:1,filter:'blur(0)',duration:1.2,ease:'sine.out'}`
+- **flip** — `{opacity:0,rotationX:93,transformPerspective:720}→{opacity:1,rotationX:0,duration:.9,ease:'power3.out'}`
+
+### epic
+
+- **slam** — `{opacity:0,scale:1.6,filter:'blur(12px)'}→{opacity:1,scale:1,filter:'blur(0)',duration:.7,ease:'back.out(1.6)'}` (lands with a thud; overshoot ~1.03 mid)
+- **monument** — `{opacity:0,scale:1.42,letterSpacing:'.12em'}→{opacity:1,scale:1,letterSpacing:'0',duration:1.3,ease:'power3.out'}`
+- **fly** — `{opacity:0,scale:.3,filter:'blur(14px)'}→{opacity:1,scale:1,filter:'blur(0)',duration:.8,ease:'expo.out'}`
+- **grandrise** — `{opacity:0,yPercent:66,scale:1.05}→{opacity:1,yPercent:0,scale:1,duration:1.15,ease:'power3.out'}`
+
+### cyber
+
+- **glitch** — `{opacity:0}→{opacity:1,duration:.6,ease:'steps(8)',keyframes:{clipPath:['inset(40% 0 40% 0)','inset(0)','inset(60% 0 10% 0)','inset(0)'],x:[-8,5,-2,0],textShadow:['4px 0 #ff003c,-4px 0 #00ffd1','none']}}`
+- **type** — `{opacity:1,clipPath:'inset(0 100% 0 0)'}→{clipPath:'inset(0 0 0 0)',duration:.85,ease:'steps(13)'}` (typewriter L→R)
+- **scan** — `{opacity:0,scaleY:.02,filter:'brightness(2.4)'}→{opacity:1,scaleY:1,filter:'brightness(1)',duration:.75,ease:'power3.out'}`
+- **boot** — `{opacity:0,scaleY:.1}→{opacity:1,scaleY:1,duration:1,ease:'steps(1)',keyframes:{opacity:[0,.6,.1,.85,.2,1]}}` (hologram power-up flicker)
+
+### horror (never bouncy, never clean)
+
+- **loom** — `{opacity:0,scale:.6,filter:'blur(17px)'}→{opacity:1,scale:1,filter:'blur(0)',duration:1.6,ease:'power2.in',keyframes:{scale:[.6,.93,1.07,1]}}` (slowly approaches out of the dark, then a lurch closer)
+- **possess** — `{opacity:0}→{opacity:1,duration:1.15,ease:'steps(1)',keyframes:{x:[0,-5,6,-4,5,-2,0],skewX:[0,9,-10,7,-5,3,0],textShadow:['none','4px 0 #c00,-4px 0 #0aa','-6px 0 #c00,6px 0 #0aa','none']}}` (materialise then violent demonic shudder)
+- **glimpse** — `{opacity:0}→{opacity:1,duration:1.35,ease:'steps(1)',keyframes:{opacity:[0,1,0,0,1,0,0,1,.05,1,.15,1],x:[0,0,0,3,0,-2,0]}}` (subliminal failing-light flicker)
+- **seep** — `{opacity:0,clipPath:'inset(-15% -8% 100% -8%)',filter:'blur(4px)'}→{opacity:1,clipPath:'inset(-15% -8% -15% -8%)',filter:'blur(0)',duration:1.35,ease:'power1.inOut'}` (blood seeps down into the word; negative insets so script tops aren't clipped)
+
+### luxury
+
+- **tracking** — `{opacity:0,letterSpacing:'-.05em'}→{opacity:1,letterSpacing:'.28em',duration:1.4,ease:'power3.out'}` (the most "expensive" move)
+- **hairrise** — `{opacity:0,yPercent:32,letterSpacing:'.07em'}→{opacity:1,yPercent:0,letterSpacing:'0',duration:1.1,ease:'power3.out'}`
+
+### retro
+
+- **vhs** — `{opacity:0}→{opacity:1,duration:.8,ease:'steps(1)',keyframes:{x:[0,-7,6,-3,2,0],textShadow:['none','3px 0 #ff3b5c,-3px 0 #3aa0ff','none']}}` (tracking-lock jitter + chroma)
+- **stamp** — `{opacity:0,scale:1.7,rotation:-5}→{opacity:1,scale:1,rotation:0,duration:.7,ease:'back.out(2)'}` (printing-stamp thud)
+- **blink** — `{opacity:0}→{opacity:1,duration:.75,ease:'steps(1)',keyframes:{opacity:[0,0,1,0,1,0,1,1]}}` (8-bit blink-in)
+
+### neon
+
+- **ignite** — `{opacity:0}→{opacity:1,duration:1.3,ease:'steps(1)',keyframes:{opacity:[.2,1,.2,1,.3,1,1]}}` (tube strikes + buzzes alight; glow is a style `text-shadow`)
+- **buzz** — `{opacity:0}→{opacity:1,duration:1.2,ease:'steps(1)',keyframes:{opacity:[0,.7,.1,.85,.2,1,.5,1]}}` (slower warm-up rhythm)
+
+### hype
+
+- **stomp** — `{opacity:0,scale:1.5,filter:'blur(8px)'}→{opacity:1,scale:1,filter:'blur(0)',duration:.9,ease:'back.out(1.6)'}`
+- **punch** — `{opacity:0,xPercent:-55,scale:1.1,filter:'blur(9px)'}→{opacity:1,xPercent:0,scale:1,filter:'blur(0)',duration:.6,ease:'expo.out'}` (whip from the side)
+- **slap** — `{opacity:0,rotation:12,scale:1.5,filter:'blur(7px)'}→{opacity:1,rotation:0,scale:1,filter:'blur(0)',duration:.7,ease:'back.out(2)'}` (sticker/tag slap)
+
+### playful (bounce allowed here)
+
+- **jelly** — `{opacity:0,scale:.5}→{opacity:1,scale:1,duration:.8,ease:'back.out(2.2)',keyframes:{scale:[.5,1.12,.92,1.04,1],skewX:[0,0,6,-4,0]}}`
+- **dropb** — `{opacity:0,yPercent:-85}→{opacity:1,yPercent:0,duration:.95,ease:'power2.out',keyframes:{yPercent:[-85,0,-22,0,-8,0]}}` (drop + multi-bounce). **❗opacity must reach 1 and stay** — declare it at the end of the keyframes.
+- **scrawl** — `{opacity:0,clipPath:'inset(-12% 100% -12% 0)',rotation:-3}→{opacity:1,clipPath:'inset(-12% 0 -12% 0)',rotation:0,duration:.8,ease:'power2.out'}` (handwritten write-on, for script faces)
+- **popr** — `{opacity:0,scale:.4,rotation:8}→{opacity:1,scale:1,rotation:0,duration:.6,ease:'back.out(2)'}`
+
+### creator
+
+- **boxpop** — `{opacity:0,scale:.5}→{opacity:1,scale:1,duration:.5,ease:'back.out(1.8)'}` (the active flow word's highlight box is a style)
+- **slideup** — `{opacity:0,yPercent:44}→{opacity:1,yPercent:0,duration:.55,ease:'power3.out'}`
+- **flip** — see premium
+- **shimmer** — `{opacity:0,scale:.7,filter:'brightness(2.2)'}→{opacity:1,scale:1,filter:'brightness(1)',duration:.75,ease:'power2.out'}`
+
+### ultra (the flash lives in the type)
+
+- **volt** — `{opacity:0}→{opacity:1,duration:1.1,ease:'steps(1)',keyframes:{opacity:[0,1,.12,1,.35,1],x:[0,0,0,2,-2,0]}}` then settle to glow `text-shadow:0 0 8px #fff,0 0 22px #43f4ff,0 0 48px #1e90ff` (electric strike)
+- **hyper** — `{opacity:0,scale:.05,filter:'blur(3px) brightness(3)'}→{opacity:1,scale:1,filter:'blur(0) brightness(1)',duration:.9,ease:'expo.out'}` (warp from depth)
+- **liquid** — `{opacity:0,scale:.9,yPercent:6,filter:'blur(10px)'}→{opacity:1,scale:1,yPercent:0,filter:'blur(0)',duration:1,ease:'power2.out'}` + the `.climax` _container_ carries SVG `filter:url(#liquid)`; in HF drive `feDisplacementMap@scale` from the timeline (don't use SMIL — not seek-safe)
+- **prism** — `{opacity:0,textShadow:'-38px 0 #ff003c,38px 0 #00ffd1',filter:'blur(5px)',scale:1.08}→{opacity:1,textShadow:'-3px 0 #ff003c,3px 0 #00ffd1',filter:'blur(0)',scale:1,duration:1,ease:'power3.out'}` (chromatic dispersion converge)
+- **shatter** — `{opacity:0,scale:1.9,rotation:-3,filter:'blur(14px)'}→{opacity:1,scale:1,rotation:0,filter:'blur(0)',duration:1,ease:'back.out(1.4)',keyframes:{scale:[1.9,.9,1.06,.98,1]}}` (+ a 1-frame white `text-shadow` flash on landing)
+- **extrude** — `{opacity:0,rotationY:42,scale:.9,transformPerspective:700}→{opacity:1,rotationY:-9,scale:1,duration:.9,ease:'power3.out'}` (3D turn; depth via stacked `text-shadow` in the style)
+
+### atelier (design-forward)
+
+- **editwipe** — `{opacity:1,clipPath:'inset(-15% 100% -15% 0)'}→{clipPath:'inset(-15% -4% -15% 0)',duration:.7,ease:'power4.inOut'}` (Swiss precise wipe; negative top/bottom so glyph tops aren't clipped)
+- **rise** — see premium (slower, `duration:.9`)
+- **block** — `{opacity:0,scaleY:0,transformOrigin:'bottom center'}→{opacity:1,scaleY:1,duration:.7,ease:'power3.out'}` (constructed/Bauhaus)
+- **vert** — `{opacity:0,clipPath:'inset(0 0 100% 0)'}→{opacity:1,clipPath:'inset(0 0 0 0)',duration:.9,ease:'power2.out'}` (vertical ink-drop; `writing-mode:vertical-rl` is a style, climax sits at `left:81%`)
+- **ink** — `{opacity:0,clipPath:'inset(-28% 100% -28% -4%)',filter:'blur(3px)'}→{opacity:1,clipPath:'inset(-28% -8% -28% -4%)',filter:'blur(0)',duration:.9,ease:'power2.out'}` (brush write-on; generous negative insets for the script face)
+- **weight** — `{opacity:0,fontVariationSettings:"'wght' 100",letterSpacing:'.18em'}→{opacity:1,fontVariationSettings:"'wght' 900",letterSpacing:'0',duration:1,ease:'power2.out'}` (variable-font morph; needs a variable face, e.g. Inter `wght@100..900`)
+
+### impact (the ONE sanctioned scene effect, at the climax only)
+
+Each pairs the type move with a scene element (`<div class="flash">` / `<div class="ring">`) and/or a stage shake. Keep it to the climax beat.
+
+- **nuke** — type: `{opacity:0,scale:.3,filter:'brightness(8) blur(10px)'}→{opacity:1,scale:1,filter:'brightness(1) blur(0)',duration:1,ease:'expo.out'}` + white `.flash` `to{opacity:0}` over 0.3 s + brief stage `x` shake
+- **meteor** — `{opacity:0,yPercent:-45,scale:1.12,filter:'blur(12px) brightness(2.2)'}→{opacity:1,yPercent:0,scale:1,filter:'blur(0)',duration:1,ease:'power4.in'}` (accelerate DOWN) + on-land stage shake
+- **sonic** — `{opacity:0,scale:1.4,filter:'blur(8px)'}→{opacity:1,scale:1,filter:'blur(0)',duration:.9,ease:'expo.out'}` + a `.ring` scaling `0→3` opacity `1→0`
+- **seismic** — `{opacity:0,scale:1.1}→{opacity:1,scale:1,duration:.9,ease:'power3.out'}` + stage `x`/`y` quake `keyframes:[3,-3,2,-2,0]` decaying
+- **judge** — `{opacity:0,yPercent:-45,scale:1.12,filter:'blur(12px) brightness(2.2)'}→{opacity:1,yPercent:0,scale:1,filter:'blur(0)',duration:1,ease:'power3.out'}` (descends from above) + light-shaft `.flash`
+
+---
+
+## CLIMAX exits
+
+Default is **fade** unless a template names another. **Every exit ends at `opacity:0`** (or fully-clipped) so nothing lingers — declare opacity:0 at the end even on transform/clip exits.
+
+- **fade** — `to{opacity:0,scale:1.03,duration:.6,ease:'power2.in'}` (premium/epic/most defaults)
+- **rise-off** — `to{opacity:0,yPercent:-42,duration:.6}` · **sink** — `to{opacity:0,yPercent:16,scale:.97}` · **lift** — `to{opacity:0,yPercent:-26,letterSpacing:'.1em'}`
+- **expose-off** — `to{opacity:0,filter:'brightness(3.6) blur(4px)'}` · **breathe-off** — `to{opacity:0,scale:1.08,filter:'blur(7px)'}`
+- **flip-off** — `to{opacity:0,rotationX:-90}` · **fly-off** — `to{opacity:0,scale:2.5,filter:'blur(13px)'}`
+- **untype** — `to{clipPath:'inset(-15% 100% -15% 0)',opacity:0,ease:'steps(11)'}` (backspace) · **scan-collapse** — `to{opacity:0,scaleY:.02}` · **power-off** — `keyframes:{opacity:[1,.3,1,.1,.5,0]}` + scaleY collapse
+- **drag** (horror) — `to{opacity:0,xPercent:-40,skewX:-20,filter:'blur(11px)',duration:.55,ease:'power2.in'}` (dragged away)
+- **snap** (horror) — `keyframes:{x:[0,7,-6,0],skewX:[0,-13,0],scale:[1,1.1,1.16,1.32],opacity:[1,1,1,0],textShadow:['none','8px 0 #c00,-8px 0 #0aa','none','none']}` (violent jerk then gone)
+- **cut** (horror) — `keyframes:{opacity:[1,0,1,0,.8,0]},ease:'steps(1)'` (frame-drop) · **bleed** — `to{opacity:0,yPercent:50,scale:.97,filter:'blur(6px)'}` (drips down)
+- **knock** — `to{opacity:0,xPercent:55,filter:'blur(9px)'}` · **peel** — `to{opacity:0,rotation:14,xPercent:42,scale:.9}` · **spin-out** — `to{opacity:0,rotation:180,scale:.3}`
+- **hop** — `keyframes:{yPercent:[0,-26,120],opacity:[1,1,0]},scaleY:.7` · **popout** — `to{opacity:0,scale:.3,rotation:-10}` · **slidedown** — `to{opacity:0,yPercent:42}` · **scrawl-off** — `to{opacity:0,yPercent:-14,rotation:2}`
+- **vhs-out** — `keyframes:{x:[0,-9,8,0],opacity:[1,1,0]},scaleY:.2` (tracking-lost roll) · **blink-out** — `keyframes:{opacity:[1,0,1,0,1,0,0]},ease:'steps(1)'` · **power-down** — `keyframes:{opacity:[1,.2,.7,.1,0]},ease:'steps(2)'` · **lift2** — `to{opacity:0,scale:1.12,filter:'blur(3px)'}` (stamp lift) · **shim-out** — `to{opacity:0,scale:.8,filter:'brightness(1.9)'}`
+- **iris-close** — `to{opacity:0,clipPath:'circle(0% at 50% 46%)'}` (Bond) · **un-shine** — `to{opacity:0,clipPath:'inset(0 0 0 100%)',filter:'brightness(1.7)'}` · **sweep-off** — `to{opacity:1,clipPath:'inset(0 100% 0 0)'}`
+- ultra family exits: **glitch-out**, **neon-out**, **hyper-out** `to{opacity:0,scale:2.6,filter:'blur(13px)'}`, **liquid-out** `to{opacity:0,yPercent:40,scale:.96,filter:'blur(9px)'}`, **prism-out** (channels split apart), **shatter-out** `to{opacity:0,scale:1.45,filter:'blur(9px)',textShadow:'7px 0 #ff003c,-7px 0 #00ffd1'}`
+
+## Pairs with HF skills
+
+- `hyperframes-gsap` — single paused timeline, transform aliases, ease list, the animated-property allowlist.
+- `_anatomy.md` — where these four hooks attach.
+- `hyperframes-animation/rules/asr-keyword-glow.md` — the verbatim active-word envelope for the flow.

package/.agents/skills/embedded-captions/modes/standard/fonts/build-fonts-css.cjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/*
+ * build-fonts-css.cjs — bundle the template fonts into ONE self-contained
+ * fonts.css with base64 data-URI @font-face (no sub-resources, no CDN, no
+ * system-font dependency). This is what makes Standard/Cinematic renders
+ * deterministic on ANY machine: hyperframes' renderer only auto-supplies its
+ * ~18 CANONICAL_FONTS; every other family falls back to a generic font unless
+ * the HTML ships a local @font-face. (hyperframes' own font linter says exactly
+ * this: "Use local @font-face declarations with captured .woff2 files.")
+ *
+ * Source woff2 live in ./files/<slug>-latin-<weight>-normal.woff2 (latin subset
+ * from @fontsource via jsdelivr). Re-run after adding/removing a font:
+ *   node build-fonts-css.cjs
+ */
+const fs = require("fs");
+const path = require("path");
+
+const FILES = path.join(__dirname, "files");
+const OUT = path.join(__dirname, "fonts.css");
+
+// slug → exact CSS family name (must match what templates declare in font-family).
+const FAMILY = {
+  anton: "Anton",
+  audiowide: "Audiowide",
+  inter: "Inter",
+  "baloo-2": "Baloo 2",
+  bangers: "Bangers",
+  "bodoni-moda": "Bodoni Moda",
+  caveat: "Caveat",
+  cinzel: "Cinzel",
+  "cormorant-garamond": "Cormorant Garamond",
+  creepster: "Creepster",
+  fredoka: "Fredoka",
+  monoton: "Monoton",
+  orbitron: "Orbitron",
+  "permanent-marker": "Permanent Marker",
+  "press-start-2p": "Press Start 2P",
+  "saira-stencil-one": "Saira Stencil One",
+  "shippori-mincho": "Shippori Mincho",
+  rajdhani: "Rajdhani",
+  "chakra-petch": "Chakra Petch",
+  sora: "Sora",
+  "space-grotesk": "Space Grotesk",
+  "special-elite": "Special Elite",
+  teko: "Teko",
+  vt323: "VT323",
+};
+
+const files = fs
+  .readdirSync(FILES)
+  .filter((f) => f.endsWith(".woff2"))
+  .sort();
+const faces = [];
+let raw = 0;
+const seenFamilies = new Set();
+for (const f of files) {
+  const m = f.match(/^(.*)-latin-(\d+)-(normal|italic)\.woff2$/);
+  if (!m) {
+    console.error(`[fonts] skip unrecognized filename: ${f}`);
+    continue;
+  }
+  const slug = m[1],
+    weight = m[2],
+    style = m[3];
+  const family = FAMILY[slug];
+  if (!family) {
+    console.error(`[fonts] no family mapping for slug "${slug}" (${f}) — add it to FAMILY`);
+    process.exit(1);
+  }
+  const buf = fs.readFileSync(path.join(FILES, f));
+  raw += buf.length;
+  seenFamilies.add(family);
+  faces.push(
+    `@font-face {\n` +
+      `  font-family: '${family}';\n` +
+      `  font-style: ${style};\n` +
+      `  font-weight: ${weight};\n` +
+      `  font-display: block;\n` + // block (not swap): render text only once the real face is ready — measure-layout + capture see the true glyphs, never a fallback flash
+      `  src: url(data:font/woff2;base64,${buf.toString("base64")}) format('woff2');\n` +
+      `}`,
+  );
+}
+
+const header =
+  `/* AUTO-GENERATED by build-fonts-css.cjs — do not edit by hand.\n` +
+  `   ${faces.length} faces / ${seenFamilies.size} families, ${Math.round(raw / 1024)}KB raw woff2 (latin subset, base64-inlined).\n` +
+  `   Families: ${[...seenFamilies].sort().join(", ")}.\n` +
+  `   These are the template fonts NOT in hyperframes' auto-resolved set; inlining\n` +
+  `   them makes every render deterministic regardless of installed system fonts. */\n`;
+
+fs.writeFileSync(OUT, header + "\n" + faces.join("\n\n") + "\n");
+const outKb = Math.round(fs.statSync(OUT).size / 1024);
+console.log(`[fonts] wrote ${OUT}`);
+console.log(
+  `[fonts] ${faces.length} faces, ${seenFamilies.size} families, ${outKb}KB css (${Math.round(raw / 1024)}KB raw)`,
+);
+console.log(`[fonts] families: ${[...seenFamilies].sort().join(", ")}`);

package/.agents/skills/embedded-captions/references/aesthetic-principles.md

@@ -0,0 +1,168 @@
+# Aesthetic Principles for Cinematic Captions
+
+The 18 rules that separate "designed" caption work from "preset-generated" caption work. This is the single most important reference in the skill — every plan.json and every Standard-mode HTML should be checked against these before committing.
+
+The whole competitive thesis: every AI caption tool in 2026 (Veed, Submagic, Opus Clip, Captions.ai, CapCut) is a **preset picker**. They hand the user a box of crayons. This skill is a **director** — it exercises judgment. Beat them on taste, not feature count.
+
+---
+
+## The 18 rules
+
+### 1. The subject always wins
+
+Captions exist to serve the face, not compete with it. If the caption draws the eye before the speaker, the caption has failed. **Before shipping any plan.json, ask: "does the caption or the subject read first?"** If caption wins, shrink, dim, or move it.
+
+### 2. Occlude, don't hover
+
+World-class caption design puts text _into_ the scene. Letters that pass behind a shoulder, mic, or head feel diegetic. Letters that float uniformly above the lower-third feel like PowerPoint. Use the matte pipeline — that's the moat over every competitor.
+
+### 3. Contrast is a hierarchy problem, not a brightness problem
+
+A white box behind text is a failure of taste. Priority order:
+
+1. `mix-blend-mode: overlay` or `screen` picking up scene luminance
+2. 2–3px dark stroke + soft drop shadow
+3. Narrow semi-opaque gradient bar (NOT a solid box)
+4. Dim the background plate by 10–15% locally
+5. (LAST RESORT) A hard white pill box — banned on cinematic directions
+
+### 4. Kill the constant lower-third
+
+Fixed-bottom captions are monotone. Caption zone shifts with shot:
+
+- Tight close-up → upper sidebar or crown
+- Mid-shot → embedded on back wall / foam / whiteboard
+- Wide → classic lower-third offset to non-subject side
+
+### 5. One family, two weights maximum
+
+Hierarchy lives in **weight** (e.g., 500 → 800), not in **font**. Mixing Montserrat + script + serif in one clip is the #1 amateur tell. Ship Inter, SF Pro, Söhne, GT America, Aktiv Grotesk, or Neue Haas Grotesk with ≥5 weights and compose with weight + size.
+
+### 6. Tracking tightens as size grows
+
+Display-size (>40pt) wants negative tracking (-10 to -30 units, or `-0.015em` to `-0.035em`). Body-size (14–20pt equivalent) wants positive tracking (+5 to +15, or `+0.005em` to `+0.015em`). Apple SF Pro's optical-size model is the reference. Submagic defaults do the opposite — they look cheap because of it.
+
+### 7. Cap height ≈ 3.5–5% of frame height for body captions
+
+- 1080p vertical (1920 tall): body 65–95px, emph/hook 130–170px
+- 1080p landscape (1080 tall): body 40–55px, emph 70–100px
+- Hormozi-size (~7–9% of frame) is **hook** size, not body size. Reserve for punchlines.
+
+### 8. Never italicize for emphasis in video text
+
+Italics are a **print** convention for flow inside a paragraph. On 24fps motion they read as "tilted" not "stressed". Emphasize with weight (extrabold), color (single accent), or size (1.3–1.6×). Italics allowed only for:
+
+- Literal quotation of written material
+- Foreign word
+- Thought vs spoken dichotomy
+
+### 9. Color discipline: one hue + neutrals
+
+Pick **one** saturated accent per video for keyword highlights. Hormozi's yellow+green+red works for him because his content is already loud. Cinematic = single accent + white/bone/charcoal. Default palette:
+
+- Warm white `#F5EFE6` on dark
+- Graphite `#1A1A1A` on light
+- Accent chosen from scene sampling
+
+### 10. Animate transform only, never the letter itself
+
+`letter-spacing`, `filter:blur`, `font-weight` animations cause inline-block reflow → line-jumps. Animate `translateY`, `scale`, `opacity`, `clip-path`. This is locked from the embedded-captions debugging.
+
+### 11. Minimum 0.4s per word visible
+
+BBC reading speed is 160–180 wpm (0.33–0.38s/word). Cinematic feel wants more breathing room — 200–220ms stagger per word, hold full phrase 0.4–0.6s before exit. Entries under 150ms read as frantic.
+
+### 12. Stagger is the primary expressive axis
+
+Same phrase, different stagger, totally different feel:
+
+| Stagger | Feel                             |
+| ------- | -------------------------------- |
+| 40ms    | machine-gun, urgent, TikTok-hook |
+| 80ms    | conversational, default          |
+| 150ms   | deliberate, documentary          |
+| 250ms+  | poetic, ceremonial               |
+
+Pick from content tone, not default to one value.
+
+### 13. Emphasis escalates _within_ a phrase, not _between_ phrases
+
+Every word bolded = no emphasis. Structure:
+
+- 70% plain body
+- 20% slight lift (color OR weight, not both)
+- 8% full emphasis (bigger, brighter, held longer)
+- 2% climax (biggest, held 1.5s, breath before + after)
+
+### 14. Break rhythm once per 30s
+
+Every-word-same-way = eye adapts, stops registering motion. Plant a rhythm-break every ~30s:
+
+- Phrase enters from opposite direction
+- A single word at 2× size
+- A beat of pure silence with no caption
+- A color shift
+
+This is what separates Submagic-preset work from something designed.
+
+### 15. Caption what adds, cut what restates
+
+Transcribe everything. **Display** 70–85%. Remove:
+
+- Filler ("um", "like", "you know", "I mean")
+- Self-corrections ("I think... I mean actually...")
+- Obvious visual echoes ("as you can see here" while pointing)
+
+Editorial judgment — no existing AI caption tool does this. It's pure upside.
+
+### 16. Segment on breath, not on duration
+
+Chunk at natural pauses ≥ 250ms. A caption spanning a breath-break feels wrong. Whisper word-level timestamps make this trivial.
+
+### 17. Safe zones per platform, always
+
+- 9:16 TikTok/IG/Shorts: caption zone `y ∈ [12%, 78%]` (bottom 22% is UI)
+- 16:9 broadcast: title-safe = center 80%
+- TV export: 5% margin on all sides
+
+Bake into the layout solver. Never eyeball.
+
+### 18. Letterbox/pillarbox is caption real estate
+
+Black bars on 9:16 from 16:9 source? Those bars are the caption home. 2.35:1 cinematic frame on 16:9 export? Serif quotation in the letterbox reads as documentary.
+
+---
+
+## Rhetorical judgment rules (editorial)
+
+These are the "what to caption" decisions. No existing tool exercises them.
+
+- **Filler suppression** — off/light/strong. Default: light for documentary, strong for vlog.
+- **Self-correction folding** — display only the final version.
+- **Breath-group segmentation** — split on silences >250ms, never mid-phrase.
+- **Semantic emphasis** — LLM-pass per phrase: "which 1–2 words carry the meaning?" Highlight those. Don't default to stressed syllables or loudest words.
+- **Silence honor** — if speaker pauses 1.5s+ for rhetorical effect, don't back-fill with lingering prior caption. Let silence breathe.
+- **Quote-sensing** — "he said, quote…" or air quotes → italic (one of the allowed italic exceptions).
+- **No `[laughs]` / `[sighs]`** — those are accessibility captions. For aesthetic captions, they pollute the frame.
+
+---
+
+## Self-critique checklist (run before rendering)
+
+The agent's own pre-render pass. Flag violations:
+
+- [ ] Does the caption or subject read first? (Rule #1)
+- [ ] Any hard white pill boxes? (Rule #3 — banned on cinematic)
+- [ ] Still lower-third for a close-up? (Rule #4)
+- [ ] More than 2 weights or more than 1 font family? (Rule #5)
+- [ ] Italic used for emphasis? (Rule #8 — banned)
+- [ ] More than 1 saturated accent color? (Rule #9)
+- [ ] Letter-spacing or filter:blur animating? (Rule #10 — banned)
+- [ ] Stagger same for documentary and vlog? (Rule #12)
+- [ ] Every group emphasized? (Rule #13)
+- [ ] 30s+ with no rhythm-break? (Rule #14)
+- [ ] Displaying every filler word? (Rule #15)
+- [ ] Caption crossing breath-break? (Rule #16)
+- [ ] Caption in platform UI zone? (Rule #17)
+
+Any "yes" to a violation question → regenerate the affected segment.

package/.agents/skills/embedded-captions/references/anti-patterns.md

@@ -0,0 +1,188 @@
+# Anti-Patterns
+
+You default to these. Stop.
+
+Each entry: the bad habit, what it produces, what to do instead. Written in the voice of someone who has watched an agent do this 10 times — because we have.
+
+---
+
+## Layout
+
+### You default to center-aligned crown.
+
+`.crown-plane { left: 0; right: 0; text-align: center }` is the template default, and you'll leave it on every video because it worked once. On a subject that sits right-of-center (Jobs in a 16:9 frame), the body eats the middle 60% of the word and "THE BEATLES" becomes "THE \_\_\_ S".
+
+**Before using the default crown**, run the three conditions in [layout-heuristics.md § Crown placement](layout-heuristics.md):
+
+1. Subject centered within 10% of frame center
+2. Clean zones ≥ 15% on each side
+3. Crown width > subject width + 400px
+
+If any one fails, **move the crown to the larger clean zone** with a narrower container and smaller font. Don't keep centering a word that's about to be 60% occluded.
+
+### You compute text leftmost as `plane_left + padding`.
+
+That's correct for left-aligned. Wrong for the templates you're using, which are **right-aligned** on the main column and **center-aligned** on crowns. The real leftmost depends on the word width.
+
+| Alignment | leftmost_x                                         |
+| --------- | -------------------------------------------------- |
+| Left      | `plane_left + padding_left`                        |
+| Right     | `plane_right − padding_right − longest_line_width` |
+| Center    | `plane_center − longest_line_width / 2`            |
+
+Compute it against the **longest wrapped line**, not the whole phrase. "four very talented guys" wraps to 3 lines — the widest is "talented" (~8 chars), not 23.
+
+### You treat `plane_left` as the text's leftmost edge.
+
+It isn't. With `left: 180px` and a right-aligned 468px word, the text starts 104px **before** `plane_left` relative to the plane, but actually lands somewhere inside the plane box. The plane box just sets the coordinate space — the text positions inside it based on alignment. Check the compiled output, not the plane attribute.
+
+### You center text on the frame when the subject is off-center.
+
+Look at the subject's body center, not the frame center. Jobs sits at x=1100 in a 1920 frame. The **scene's** center of gravity is 1100, not 960. Center-aligning text to 960 is center-aligning to the empty left third, not to anything meaningful.
+
+### You copy-paste position values from memory-wall to a new video.
+
+`top: 40, right: 30, width: 720, rotateY: -13` worked for a 1280×720 frame with an acoustic foam wall on the right. It will not work on a 1920×1080 frame with a bookshelf backdrop. Run the 6-item checklist in [scene-types.md](scene-types.md) for the new video before reusing any numbers.
+
+---
+
+## Typography
+
+### You use template default font sizes regardless of column width.
+
+Template defaults (66/78/92/140) are tuned for a ~560px column. When you bump the plane to 700px+ and don't touch the fonts, the captions feel underweight — small text swimming in negative space.
+
+Use the [Font-size × column-width matrix](typography-presets.md). For a 700px column, that's 78/108/128/220 — a 30-40% bump across the board. Re-check pillarbox safety after bumping (bigger right-aligned text extends further left).
+
+### You pick `intro` style for every first caption.
+
+Intro = italic, smaller, contemplative. Fine for filler discourse markers ("You know,", "So,", "Well,"). **Not** for the first line when it's actually the thesis ("I've had this kind of upbringing"). Read the words semantically, not positionally.
+
+### You skip emphasis entirely because "every caption looks clean."
+
+A story without an emph or crown is typographically flat — viewers can't feel the crescendo. Reserve at least ONE emph per video for the line that lands. Skip it only for truly monotone content (policy statements, warnings).
+
+### You give every group its own style.
+
+Style is supposed to signal _hierarchy_. Using `intro`/`phrase`/`emph`/`dream`/`crown` all in one 15-second video means none of them signal anything. Pick 2-3 styles max for a short clip.
+
+### You only use the 5 preset class names.
+
+`intro / phrase / emph / dream / crown` are scaffolding, not a closed set. The canonical `memory-wall.html` uses `cap-1 / cap-2 / cap-3 / cap-4` — **position-indexed** with bespoke typography per position. That's how it achieves the 3-line right-aligned cascade on the climax. You can't express "this cap has a hanging indent at position 2" with `"style": "dream"`.
+
+The `"style"` field in plan.json accepts **any string** — it becomes `class="cap-<string>"`. Define the class in `custom_css`:
+
+```json
+"custom_css": ".cap-1 { font-size: 78px; ... } .cap-2 { padding-right: 44px; }",
+"groups": [{"id": "cg-0", "style": "1", ...}]
+```
+
+When the scene needs per-position bespoke typography, do this. Don't force-fit into `intro / phrase / emph`.
+
+### You regenerate from plan.json when a canonical example already has the answer.
+
+When scene framing matches `references/example-renders/memory-wall.html` or `champion.html`, clone that HTML into `<project>/index.html` and only swap the GROUPS array. Don't re-derive the design from presets — you'll lose the specific per-position typography that took many iterations to validate. See [bespoke-vs-presets.md § The clone-and-tweak workflow](bespoke-vs-presets.md).
+
+---
+
+## Blending
+
+### You default to `mix-blend-mode: overlay`.
+
+Overlay works on **mid-tone** backgrounds. On dark bookshelves (<60 luminance), overlay makes white text render as black. On sunny backgrounds (>180 luminance), overlay blows out. Check the actual luminance of the caption region in a sampled frame. Pick:
+
+- mid-tone surface (60-180) → `overlay`
+- dark surface (<60) → `screen`
+- bright surface (>180) → `normal` with opaque text
+
+### You animate `letter-spacing` on the word entry.
+
+You saw a "typewriter breath" effect somewhere and added `letterSpacing: "0.04em"` to the `fromTo` "from" state. Result: inline-block reflow every frame → the whole `.cap` line box recomputes → captions visibly jump between rows. See the "Some → line 2" bug from memory-wall.
+
+**Animate only opacity + transform.** If you want a breath effect, use `scale` or `y`, not letter-spacing.
+
+---
+
+## Animation
+
+### You fade both the group container AND each word.
+
+Default feels safer: fade the container in, then fade each word in. But container.opacity × word.opacity produces a non-linear curve — at progress 40% the combined opacity is 16%, not 40%. Visible result: captions seem to "pop" into view around halfway.
+
+Set container opacity to 1 at entrance via `tl.set`, then fade only the words. Single-layer opacity = linear perceived fade.
+
+### You stack captions in a flex column.
+
+Flex-direction: column with multiple `.cap` children looks tidy in source. At runtime, hidden captions (`visibility: hidden`) still reserve flex space. The newly-entering caption shows up at the _bottom_ of the column instead of the designed position — landing in the gesture zone, getting clipped.
+
+Use `position: absolute` for each `.cap` inside the plane so hidden ones don't occupy layout. Both shipped templates do this.
+
+### You start the timeline at t=0.
+
+Caption at exactly t=0 feels like it was there before the video started. Offset 0.1-0.3s (hyperframes motion-principles.md agrees). Same for the very last caption — let it exit before the video fades.
+
+---
+
+## Scene admission
+
+### You trust that "looks like one speaker" = "is one speaker throughout."
+
+TV archive clips cut to B-roll mid-sentence. Interview clips insert cutaways to the interviewer. You didn't check frames beyond the first one, so you rendered captions across a shot transition. Result: captions designed for Subject A are placed relative to Subject B's position (or empty frame) for half the render.
+
+Sample frames at 20%, 50%, 80% BEFORE planning. If the scene changes, trim to the largest single-subject segment.
+
+### You ignore baked-in captions / pillarbox / watermarks.
+
+You saw black bars on the sides and didn't computing the safe-zone. Your captions cross the pillarbox. Or: the source already has burned-in subtitles and you added more — two caption systems fighting for attention.
+
+Run the **letterbox probe** first. If the source has existing captions, refuse with: "source already captioned, adding more would conflict."
+
+### You ship Whisper's transcript without checking timings against the beat.
+
+Transcription is Whisper (via `transcribe.cjs`, no API key) — good word timings, but not infallible: a word can land with a near-zero duration or a timestamp a beat off. This skill is verbatim + on-beat, so `check-timing.cjs --strict` (80ms tolerance) is the gate, not a suggestion — fix drift in `plan.json` before rendering, and never pack two transcript words into one timed entry (the second inherits the first's timestamp and fires early).
+
+---
+
+## Matting
+
+### You enable CoreML for the matting ONNX.
+
+It's the Apple way, obviously faster. No. CoreML partitions the ONNX graph across providers. The mixed-precision boundary produced (observed with the previous RVM engine) alpha=30 inside the subject's face while background correctly reads 0. Captions shine through face. Pin the CPU execution provider only (`onnxruntime-node`). Our `matte.cjs` already does this; don't "optimize" it by re-adding CoreML.
+
+### You pick a matte model by "general vs human."
+
+DECISION FLIPPED 2026-06-12 after a 5-model × 6-scene A/B with caption renders: the matte's job here is CAPTION LAYERING, not prop fidelity. `u2net_human_seg` (via hyperframes `remove-background`) usually excludes thin offset furniture (mic boom arms) from the matte — words stop being sliced by booms, which beat PP-MattingV2's prop-preserving behavior on real caption videos. It is NOT surgical: large salient objects near the subject (telescope rigs) can still leak in — always sample frames_fg/. Known cost: HELD products can drop out intermittently (captions pass in front) — route product-demo climaxes away from held objects. `isnet-general-use` lost outright (backlit-hair collapse). birefnet-portrait (MIT) beat everything semantically (keeps held items AND drops furniture) but is 928 MB / ~7 s-per-frame CPU — a future quality tier, not the default.
+
+---
+
+## Grouping
+
+### You caption every word.
+
+Transcripts are verbose — "you know, um, I, I mean, you know" is 5 words from a single beat. Captioning all of them clutters the screen and breaks reading rhythm.
+
+Editorially drop filler. Use the rules in [caption-grouping.md](caption-grouping.md): merge short fragments, cut repeated discourse markers, keep the meaning, trim the noise. You are writing typography to support speech, not a court transcript.
+
+### You group by fixed word-count.
+
+"3 words per caption, always" makes every caption look the same and fights the natural cadence of speech. Break on sentence boundaries, 250ms+ pauses, and semantic units instead. Caption sizes will naturally vary from 2 words to 5 — that's correct.
+
+---
+
+## The meta anti-pattern
+
+### You read one reference doc and skip the rest.
+
+You'll read this file alone and feel covered. These anti-patterns reference concepts defined in `layout-heuristics.md`, `typography-presets.md`, `scene-types.md`. If you haven't read those, the fix advice here won't make sense.
+
+**Order of reading for a new video**:
+
+1. SKILL.md (decision gate + pipeline + pre-flight probes)
+2. bespoke-vs-presets.md (**first check if a canonical example fits — clone if so**)
+3. scene-types.md (template selection — all 4 wall conditions)
+4. layout-heuristics.md (positions, sides, crown, font scale, pillarbox formula)
+5. typography-presets.md (font-size × column-width table, starting points)
+6. caption-grouping.md (word → group)
+7. **This file last** (to catch yourself before committing to plan.json)
+
+If you're pressed for time, still read this one — it flags the failures you're about to make.