retake-demos 0.2.2 → 0.3.0

package/.env.example

@@ -1,3 +1,13 @@
+# Your app's demo account, for demos that start behind a login. You rarely edit
+# this by hand: the agent asks by name and the Retake window (or `retake secret
+# APP_USER APP_PASSWORD`) writes it here. Stays on this machine; never sent to the
+# agent. A manifest references ${APP_USER} with `secret: true` — never the values.
+# APP_TOTP_SECRET is the authenticator enrolment secret; ${TOTP:APP_TOTP_SECRET}
+# becomes the current code. Blank lines below count as unset.
+APP_USER=
+APP_PASSWORD=
+APP_TOTP_SECRET=
+
 # Retake — optional. Only `retake describe` and `retake ideas` use a model; validate/dry/run/render/check never do.
 # With a coding agent driving Retake over MCP you can leave all of this empty.
 # Pick explicitly with RETAKE_MODEL=claude-code|codex|groq|mistral|local; otherwise the first available is used.

package/AGENTS.md

@@ -0,0 +1,213 @@
+# Using Retake from Claude Code, Codex, or any coding agent
+
+Retake records product demos of web apps from a small YAML manifest. Its CLI
+is deliberately agent-shaped: every command prints plain text, exits non-zero
+on failure, and the cheap checks come before the expensive recording. An agent
+can drive the whole loop — write, check, record, inspect, fix — without ever
+opening the UI.
+
+This file is also what Claude Code and Codex read when you point them at this
+folder, so it doubles as the tool's own instructions to them.
+
+`retake` here is the installed command (`npm install -g retake-demos`). From a
+clone of this repo the same commands run from source as `npm run retake -- …`.
+The MCP route is better than the CLI when it exists: `retake install` registers
+the tools and the skill with Claude Code, so the loop below becomes tool calls.
+
+## Starting from nothing (the person pasted the repo link)
+
+```
+npm install -g retake-demos
+mkdir -p ~/retake-demos && cd ~/retake-demos && retake install   # workspace + tools + skill
+retake ui                                                         # their window: http://localhost:4310
+```
+
+`retake install` registers the MCP tools with Claude Code (user scope) and
+prints the Codex / Cursor config. Tools load at the start of a session, so
+in the session that ran the install, use the CLI loop below and tell the
+person to restart you afterwards. `retake doctor` says what, if anything,
+is missing. Always tell the person the window's address — they may not know
+it exists.
+
+## The loop an agent should run
+
+```
+write demos/<name>.yaml
+  → retake validate demos/<name>.yaml      schema + warnings (instant)
+  → retake dry demos/<name>.yaml           every selector & wait, no camera (~30–60s)
+  → fix what dry reports, repeat until "all N steps resolved"
+  → retake run demos/<name>.yaml --preset preview-fast   first take (~2 min)
+  → read outputs/<name>/proof-log.md                  what actually happened, per step
+  → retake check outputs/<name>             pass/fail on the result
+  → adjust, then: retake run demos/<name>.yaml          final quality
+```
+
+Rule of thumb: **never go straight to `run`.** `dry` catches most failures in
+seconds; a failed `run` costs two minutes and a confusing video. When `dry`
+fails it prints the step, the error, and the text that was on screen — read
+that before changing anything.
+
+## How to tell Claude Code / Codex to use it
+
+From the Retake folder:
+
+```
+claude "Record a demo of http://localhost:3000 that shows a user creating
+        their first project. Use Retake: draft demos/first-project.yaml,
+        dry-run it until it passes, record a preview, then check it.
+        Show me the proof log."
+```
+
+or with Codex:
+
+```
+codex "Using Retake (see AGENTS.md), make a 30-second demo of the sign-up
+       flow at http://localhost:3000. Dry-run before recording."
+```
+
+Both CLIs read this file automatically when run in this directory, so the
+loop above is already in their context. If the agent works from *another*
+folder (your app's repo), add the workspace: `claude --add-dir <your retake workspace>`
+— or skip all this with `retake install`, which gives the agent the tools directly.
+
+## Letting the agent draft with Retake's own scouting
+
+The agent does not have to write the manifest from nothing:
+
+```bash
+retake describe <name> <url> "<one sentence of what to show>" -P <path-to-app-source>
+retake ideas <url> -P <path-to-app-source>        # 5–7 demo ideas, saved to ideas/
+```
+
+`describe` scouts the live page for real, unique selectors, reads the app's
+source for routes / sign-in fields / things that animate, and drafts the YAML.
+`-P` is optional but makes drafts much better. The model is whichever is set in
+`.env` (`RETAKE_MODEL=claude-code|codex|groq|mistral|local`) — so an agent can
+use Retake's drafting, or draft itself; both are fine.
+
+## What the agent must know about manifests
+
+Full reference: `README.md` → "Demo-as-code". The short version:
+
+- **Wait for results, not timers.** After any click that loads or computes
+  something, `{ action: waitFor, selector: <thing that appears> }`. A fixed
+  `wait` is for pacing only.
+- **Selectors must be unique.** Playwright runs strict: a selector matching two
+  elements fails. Prefer ids, `data-testid`, `aria-label`, then
+  `button:has-text("…")`; append `>> nth=0` only when duplicates are intended.
+- **The poster** is `thumbnail.png`. `outputs.thumbnail: { scene: <label> }` picks the scene; the person can override it in the window from any frame, a generated cover, or their own image (`POST /api/cover/<name>`). Launch mode also writes `cover.png` (the title card) and `cover-titled.png` (a real frame with the title on it) as candidates. Do not re-render to change a poster.
+- **`mode:`** — `demo` (default) proves the interaction: nothing in the frame
+  but the product. A CLIENT WALKTHROUGH IS A DEMO. `launch` presents the
+  product in public (a launch, a post, an ad) and may carry a title card,
+  music, emphasis and a branded ending — ending with THEIR product, never
+  with Retake. Decide from the audience, not the subject; never upgrade a
+  demo yourself (`validate` warns).
+- **voiceover** needs a continuous `script:` and `approved: true` from a
+  person who heard it. Off otherwise.
+- **The launch cut**: `compressIdle: true` (waits shown short — render-time),
+  `voiceover: true` (captions read aloud), `typing: brisk` (re-record). Offer
+  as one package when the destination is a launch or post; default is plain.
+- **`music: <file>`** mixes a bed under the video at render (looped, faded
+  out). The person supplies the file — never invent a path, never bundle.
+- **Cards and callouts:** `intro: { title, subtitle }` / `outro:` splice a
+  title card (render-time; the intro frame becomes cover.png). A
+  `{ action: callout, selector, label }` step rings an element on camera.
+  At most one callout per scene; never callout what the caption already says.
+- **Scenes carry the story.** `{ action: scene, label, caption }` at each beat;
+  captions burn into the video. The camera is still by default; `camera: auto`
+  eases toward the last thing touched, or per scene `camera: { focus:
+  <selector>, zoom: 1.3 }`. Add zoom only when the person asks.
+- **Logins go in `auth.setup`**, never in `steps` — see "Logins" below.
+- **Backend not available?** `stub:` answers API calls with canned JSON for the
+  take, and a `stub` step swaps the answer mid-demo. Every stub is named in the
+  proof log.
+- **Long forms:** `{ action: scroll, to: <selector>, align: center }` before
+  filling them, so the viewer sees the whole thing.
+
+## Logins
+
+Most real demos start behind a sign-in. The agent never sees a password:
+
+- **Ask by name, not for the value.** Over MCP, call `secrets` with the
+  variable names (`APP_USER`, `APP_PASSWORD`, `APP_TOTP_SECRET` for an
+  authenticator) and a one-line why. With the Retake window open, a form
+  appears there and the values go straight into the workspace `.env` — the
+  tool returns "set". Without a window, the tool returns the sentence to
+  relay: the person runs `retake secret APP_USER APP_PASSWORD` (typed into
+  their terminal, hidden, kept on their machine) and the agent calls
+  `secrets` again. From the CLI only, say the same sentence yourself.
+- **Put the sign-in under `auth.setup`** with `${APP_USER}` / `${APP_PASSWORD}`
+  and `secret: true`, plus `auth.storageState: .auth/<name>.json`. It runs
+  before the camera, is trimmed off, and the session is reused by later takes.
+  A failed sign-in never saves a session.
+- **Authenticator codes:** `${TOTP:APP_TOTP_SECRET}` is the current six-digit
+  code, computed when the field is filled.
+- **SMS, SSO, captcha:** a script cannot; a person can, once.
+  `retake signin demos/<name>.yaml` opens a real window, they log in, press
+  Enter, and the session is saved. Leave `auth.setup` empty; a take with no
+  fresh session and no setup refuses to run rather than record logged out.
+- **Firebase-style sessions** (IndexedDB) cannot be restored from a saved
+  session: put the login under plain `setup` so it runs every take.
+- **Demo accounts only.** The output is a video.
+
+## Reading the results
+
+- `outputs/<name>/proof-log.md` — per-step ✓/✗ with timings, the shot list,
+  quality facts, and which endpoints were stubbed. This is the file to read
+  when something looks wrong.
+- `outputs/<name>/take.json` — the same, machine-readable.
+- `outputs/<name>/demo.mp4` — the video. `master.mp4` is the CRF-14 keeper
+  on post presets.
+- `retake check outputs/<name>` — resolution, fps, duration, files,
+  pass/fail. Exit 3 on failure.
+
+Exit codes: `run` → 0 all steps passed, 2 something failed (video still
+produced, proof log says why). `dry` → 3 if any step would fail.
+
+## Fixing a take without re-recording
+
+Captions, camera zoom, hold length, trim, format and layout are **render-time**.
+Change them in the YAML and `retake render outputs/<name>` — seconds,
+no browser. Only changes to what the browser *does* (steps, selectors, waits,
+viewport) need `run` again; `run --reuse` skips the browser when nothing
+recording-relevant changed, and the UI's one button works this out for you.
+
+## Things that trip agents up
+
+- The app must be running and reachable at the manifest's `url` before `dry`
+  or `run`. Retake says "Nothing is running at …" if not.
+- `describe` and `ideas` need a model configured (`.env` or the UI's Settings).
+  `validate`, `dry`, `run`, `render`, `check` never use a model.
+- Two runs on the same demo at once are refused (a lock); wait for the first.
+- Deleted demos go to `.trash/`; `POST /api/demos/<name>/restore` or copy the
+  file back.
+- **Wait for durable state, not its announcement.** Toasts and banners clear
+  themselves (and often share a class with other notices); a wait on one can
+  time out while the thing it announced sits on the board. Wait for the row,
+  the count, the heading — `.act >> nth=1` beats `.landed`.
+- `dry` runs file/command seeds first so it sees the state `run` will
+  (`--no-seed` to skip). `evaluate` seeds only run with a camera.
+- A one-line `script:` with braces is a YAML mapping, not a string — write
+  `script: |` and put the JS on the next line.
+- Iterating on one beat of a long demo: `run demos/x.yaml --until <scene>`
+  records up to the end of that scene and stops (MCP: `run` with `until`).
+  Better still, keep demos short — above ~40 steps, split the story.
+- If Retake itself fails (render/ffmpeg error, crash), stop and report it —
+  do not patch around the tool.
+- **Cursor cap: ~180 moves per take.** (Was ~45; Retake now flattens testreel's
+  cursor expressions at install.) `validate` warns past it, the recorder
+  detects a failed overlay and `check` FAILs. Split long stories anyway —
+  above ~40 steps nobody is watching.
+- Stills: `NN-label.png` is mid-scene, `NN-label-end.png` the last moment.
+- Scroll pacing defaults to constant pixels-per-second; `speed:` overrides.
+- **New tabs are folded back into the recorded page** (`keepInTab`, default
+  true): `window.open` navigates in place and `target="_blank"` is stripped.
+  Retake records one page, so a popup login or a "preview" button used to lose
+  the demo's subject entirely. Set `keepInTab: false` if a flow genuinely needs
+  a separate window — and know it will not be on camera.
+- **Iterate at `--preset draft`.** Same 960px layout as the post presets (so
+  selectors, wrapping and timing match) at a quarter of the pixels. Measured on
+  a 22s demo: capture 22.4s vs 30.1s, render 1.2s vs 3.6s — the 1080p encoder
+  adds ~8s to every take and competes with the app being recorded. Ladder:
+  `draft` while fixing, `preview-fast` to check final framing, a post preset to
+  ship. Never ship a draft.

package/README.md

@@ -19,6 +19,19 @@ It is built for the way people work now: **you ask your coding agent for a demo
 
 <p align="center"><img src="assets/window.png" width="900" alt="The Retake window: your demos on the left, the video and its scenes in the middle"></p>
 
+## If you are a coding agent reading this
+
+Someone pasted this link and wants demos recorded. Do this, in order, and say what you are doing as you go — assume they have never seen Retake:
+
+1. `npm install -g retake-demos` (Node 20+; ffmpeg is bundled, Chromium downloads once).
+2. Make a workspace and set up from inside it: `mkdir -p ~/retake-demos && cd ~/retake-demos && retake install`. This creates `demos/` and `outputs/`, registers Retake's tools with Claude Code and installs its skill, and prints the config for Codex/Cursor — apply it if that is what you are.
+3. **Your tools arrive at your next session.** For this one, drive Retake from the CLI exactly as [`AGENTS.md`](AGENTS.md) describes (`validate → dry → run → check`). Tell the person: "Restart me after this and I'll have Retake's tools directly."
+4. Start the window for them — `retake ui` in the workspace — and give them the link: http://localhost:4310. That is where the video, stills and proof log appear.
+5. If they did not say what to record, ask one question: which app (URL) and what to show. If the app needs a login, read the "Behind a login" section below — you never handle the password yourself.
+6. Read [`skill/SKILL.md`](skill/SKILL.md) once: it is the method (order of operations, failures as text, when to stop) and it is what Claude Code loads automatically after step 2.
+
+Everything below is for the person; it is accurate for you too.
+
 ## Install
 
 Needs Node 20+. ffmpeg ships with the package; Chromium is downloaded once.
@@ -48,12 +61,14 @@ outputs/<name>/
   demo.mp4        the shareable — captions burned in
   master.mp4      the CRF-14 keeper (post presets only)
   stills/         one PNG per scene, mid-scene and at its last moment
-  thumbnail.png   the frame at a chosen scene
+  thumbnail.png   the poster — pick any frame, a cover, or your own image in the window
+  cover.png       launch mode: the title card, settled
+  cover-titled.png launch mode: a real frame with the title over it
   proof-log.md    result, shot list, every step's timing, pass/fail, what was on screen when it failed
   take.json       the raw timeline the renderer reads
 ```
 
-In the window: play it, switch speed (0.75× to 1.3×, re-rendered in seconds), download, or open its folder — stills, proof log, manifest. Demos group by the app they point at; archive what you're done with.
+In the window: play it, switch speed (0.75× to 1.3×, re-rendered in seconds), download, or open its folder — stills, proof log, manifest. **The poster is chosen, not guessed**: scrub to a frame and press *Use this frame*, click any scene still, take one of the generated covers, or upload your own. It rewrites `thumbnail.png`, so it costs no re-render — and on a feed the poster decides whether anyone presses play. Demos group by the app they point at; archive what you're done with.
 
 ## The loop
 
@@ -82,7 +97,7 @@ preset: post-landscape            # `retake presets` — 1920×1080 page + capti
 viewport: { width: 1440, height: 1080 }
 scale: 1.8                        # page drawn at 1.8× so text stays crisp
 reducedMotion: true
-camera: auto                      # each scene eases toward the last thing touched
+camera: static                    # still (the default); `auto` eases toward the last thing touched
 
 seed: []                          # put the app in a known state first
 setup: []                         # runs before the camera; trimmed off the video
@@ -107,6 +122,8 @@ The full template is [`demos/example.yaml`](demos/example.yaml); `retake init` c
 
 **Scenes** are the spine: `{ action: scene, label, caption }` at each beat. They take their timestamps from the actual run, so captions land on the frames they describe even when the app took 3 seconds this time and 11 the last.
 
+**Two kinds of take.** `mode: demo` (the default) proves how something works — a client walkthrough, a PR clip, a lesson — and keeps everything but the product out of the frame. `mode: launch` presents the product in public and may carry a title card, music, emphasis and a branded ending. `validate` warns if a demo is carrying launch furniture. **The launch cut.** `compressIdle: true` shows the app's long waits as ~1.5 s each (your own pacing `wait`s are never touched); `voiceover: true` reads the captions aloud (edge-tts, `pipx install edge-tts` once); `typing: brisk` makes typed text land fast with the pauses carrying the meaning. All render-time except typing. **Music.** `music: track.mp3` (or `{ file, gainDb, fadeOutMs }`) mixes a bed under the video at render time, looped or trimmed to fit and faded out at the end. Bring your own track — it ships inside your video, so it must be one you may use (CC0 or licensed). **Cards and callouts.** `intro:`/`outro:` add a title card in Retake's own look — rendered at render time, so changing a word is a re-render, and the intro's settled frame is written as `cover.png`, the poster. `{ action: callout, selector, label, ms }` draws an animated ring and label around an element while the take holds — recorded coordinates, drawn at render, moving with the camera. Sparingly: the captions carry the story.
+
 **Seeds** put the app in a known state before the camera: write a JSON file, run JS in the page, or run a shell command. **Setup** is the stuff that runs before recording and is trimmed off the front — logins live there. **`tempo`** speeds the finished video up or down at render time; **`lock`** names a shared resource so two demos that touch the same backend don't record over each other.
 
 ## Quality
@@ -115,33 +132,54 @@ Think in the publishing format, not the browser window.
 
 | Preset | Video | Page area | For |
 |---|---:|---:|---|
-| `draft` | 960×616 | 960×540 | iterating — the finals' layout at a quarter of the pixels, fastest |
-| `preview-fast` | 1920×1230 | 1920×1080 | checking timing and framing, hardware-encoded |
-| `post-landscape` *(default)* | 1920×1230 | 1920×1080 | the general-purpose demo, plus a CRF-14 master |
-| `post-square` | 1080×1080 | 1080×950 | feeds — a true square |
-| `post-vertical` | 1080×1920 | 1080×1750 | shorts and reels — a true 9:16 |
-| `docs-gif` | 1440×1000 | 1440×900 | README and docs GIFs |
-| `master` | 1920×1230 | 1920×1080 | archive, CRF 12 |
+| `draft` | 960×592 | 960×540 | iterating — the finals' layout at a quarter of the pixels, fastest |
+| `preview-fast` | 1920×1180 | 1920×1080 | checking timing and framing, hardware-encoded |
+| `post-landscape` *(default)* | 1920×1180 | 1920×1080 | the general-purpose demo, plus a CRF-14 master |
+| `post-square` | 1080×1080 | 1080×960 | feeds — a true square |
+| `post-vertical` | 1080×1920 | 1080×1800 | shorts and reels — a true 9:16 |
+| `docs-gif` | 1440×970 | 1440×900 | README and docs GIFs |
+| `master` | 1920×1180 | 1920×1080 | archive, CRF 12 |
+
+**The video is the page area plus the caption band, and the band fits the captions.** On landscape presets the page keeps its full 1920×1080 and the band under it is sized to the longest caption — about 100 px for one line, 160 for two, one height for the whole take (video sizes above are for one-line captions). The captions never cover the app. Square and vertical keep a fixed 120 px band inside the canvas, because a feed that wants 1:1 or 9:16 will letterbox anything else. `captions: false` → no band at all. A manifest's `viewport` replaces the page area and the video follows it, so a 1240×1080 viewport gives a 1240×1230 video. `retake presets` prints this table, and `retake validate` tells you the exact size of the video a manifest will produce before you record it.
+
+**Page scale** is what makes it crisp: the page lays out as if the viewport were smaller and every glyph is drawn at 2×, so 1080p text reads on a phone. **Camera** is still by default — a calm demo reads as real. `camera: auto` eases toward whatever the demo just touched, at render time, clamped so it can never crop the thing it points at; per scene: `camera: { focus: ".result", zoom: 1.3 }`. Zoom is something you ask for after seeing a take, not something that happens to you. Captions, camera, speed, trim, format and layout are all render-time: change them and `retake render` takes seconds, never touches the browser.
+
+## Behind a login
+
+Most real demos start on the far side of a sign-in. You never put a password anywhere an agent can read it.
+
+**With the window open** (`retake ui`): when the agent sees the app needs a login, a small form appears in the window asking for a demo account by name — `APP_USER`, `APP_PASSWORD`. You type them; they are written to one local file, the workspace `.env` (readable by you only), and never sent to the agent, to any server, or to anyone. The agent learns only that the names are set.
 
-**The video is the page area plus the caption band.** Landscape keeps a full 1920×1080 page and the band goes under it (1920×1230) — the captions never cover the app. Square and vertical fit the band inside the canvas, because a feed that wants 1:1 or 9:16 will letterbox anything else. A manifest's `viewport` replaces the page area and the video follows it, so a 1240×1080 viewport gives a 1240×1230 video. `retake presets` prints this table, and `retake validate` tells you the exact size of the video a manifest will produce before you record it.
+**Without the window:** the agent relays one line — run this in your workspace and type the values (hidden):
 
-**Page scale** is what makes it crisp: the page lays out as if the viewport were smaller and every glyph is drawn at 2×, so 1080p text reads on a phone. **Camera** eases toward whatever the demo just touched, at render time, clamped so it can never crop the thing it points at — per scene: `camera: static` or `camera: { focus: ".result", zoom: 1.3 }`. Captions, camera, speed, trim, format and layout are all render-time: change them and `retake render` takes seconds, never touches the browser.
+```bash
+retake secret APP_USER APP_PASSWORD
+```
+
+**Then:** the login runs *before the camera* and is trimmed off the front; the video starts signed in. The session is saved to `.auth/`, so later takes skip the login. A wrong password stops the take instead of recording a logged-out one.
+
+**Two-factor.** Authenticator apps: add the enrolment secret as `APP_TOTP_SECRET` and the manifest uses `${TOTP:APP_TOTP_SECRET}` — Retake computes the current code when it fills the field. SMS codes, SSO, captchas — anything only a person can do:
+
+```bash
+retake signin demos/<name>.yaml
+```
+
+opens a real browser; you log in by hand, press Enter, and Retake keeps the session (not the password) for every later take.
 
-## Signing in
+What the agent writes:
 
 ```yaml
 auth:
   storageState: .auth/myapp.json   # session saved here, reused until stale
   maxAgeHours: 8
-setup:
-  - { action: fill, selector: "#user", text: "${APP_USER}" }
-  - { action: fill, selector: "#password", text: "${APP_PASSWORD}", secret: true }
-  - { action: click, selector: "button[type=submit]" }
+  setup:
+    - { action: fill, selector: "#user", text: "${APP_USER}" }
+    - { action: fill, selector: "#password", text: "${APP_PASSWORD}", secret: true }
+    - { action: fill, selector: "#code", text: "${TOTP:APP_TOTP_SECRET}", secret: true }   # only if asked
+    - { action: click, selector: "button[type=submit]" }
 ```
 
-Secrets live in `.env`, never in a manifest. `secret: true` keeps a value out of the terminal, the window and the proof log — but not out of the video, which is why `validate` warns when a secret step is in `steps` rather than `setup`. A session is only saved when the sign-in actually succeeded. Use a demo account: the output is a video you may publish.
-
-Apps that keep their session in IndexedDB (Firebase) can't be restored from `storageState`; put the login in plain `setup` instead.
+`secret: true` keeps a value out of the terminal, the window and the proof log — but not out of the video, which is why `validate` warns when a secret step is in `steps` rather than `auth.setup`. Use a demo account: the output is a video you may publish. Apps that keep their session in IndexedDB (Firebase) can't be restored from a saved session; put the login under plain `setup` instead.
 
 ## Limits worth knowing
 

package/demos/example.yaml

@@ -17,7 +17,7 @@ preset: post-landscape        # 1080p @ 30fps · see `retake presets`
 viewport: { width: 1440, height: 1080 }   # match your app's natural shape
 scale: 1.8                    # page drawn at 1.8× so text stays crisp at 1080p
 reducedMotion: true           # calms infinite spinners and entrance animations
-camera: auto                  # each scene eases toward the last thing touched
+camera: static                # still by default; `auto` eases toward the last thing touched
 
 # Put the app in a known state before the camera rolls. Pick what fits:
 #   - { kind: file, path: /tmp/app/state.json, from: seeds/empty.json }

package/dist/captions.js

@@ -0,0 +1,56 @@
+/** Word-wrap long captions; two-line captions break near the middle so no
+    word is left orphaned on the second line. */
+export function wrap(text, max) {
+    if (text.length <= max)
+        return text;
+    const words = text.split(/\s+/);
+    if (text.length <= max * 2) {
+        let best = 1, bestDiff = Infinity;
+        for (let i = 1; i < words.length; i++) {
+            const a = words.slice(0, i).join(" ").length;
+            const b = words.slice(i).join(" ").length;
+            if (a <= max && b <= max && Math.abs(a - b) < bestDiff) {
+                best = i;
+                bestDiff = Math.abs(a - b);
+            }
+        }
+        return words.slice(0, best).join(" ") + "\n" + words.slice(best).join(" ");
+    }
+    const out = [];
+    let line = "";
+    for (const w of words) {
+        if (line && (line + " " + w).length > max) {
+            out.push(line);
+            line = w;
+        }
+        else
+            line = line ? line + " " + w : w;
+    }
+    if (line)
+        out.push(line);
+    return out.join("\n");
+}
+/** Characters per caption line at this width and font size. */
+export const maxCharsFor = (width, fontSize) => Math.max(28, Math.round((width / fontSize) * 1.55));
+/** How many lines the longest caption needs. */
+export function captionLines(texts, width, fontSize) {
+    const max = maxCharsFor(width, fontSize);
+    return Math.max(1, ...texts.map((t) => wrap(t, max).split("\n").length));
+}
+/** The band's height for this take: fitted to the text, or the preset's
+    fixed band when the canvas is the constraint. 0 when captions are off. */
+export function bandHeightFor(q, width, texts, pageHeight = q.height) {
+    if (q.layout !== "band" && q.layout !== "card")
+        return 0;
+    if (!q.captions)
+        return 0;
+    // Fixed canvas: whatever the page turned out to be (an older take may have
+    // a different page height), the band fills the rest so the canvas is exact.
+    if (q.bandFit === "fill")
+        return Math.max(0, q.height + q.bandHeight - pageHeight);
+    const size = q.captions.fontSize;
+    const lines = captionLines(texts, width, size);
+    // glyph height ≈ 1.05 × size; line spacing 0.25 × size; breathing room above and below.
+    const h = size * 1.05 * lines + size * 0.25 * (lines - 1) + size * 1.1;
+    return Math.ceil(h / 2) * 2;
+}

package/dist/cards.js

@@ -0,0 +1,134 @@
+/**
+ * Motion pieces rendered from HTML — title cards and callout overlays.
+ *
+ * Chromium is the motion renderer: a template page defines `__seek(tMs)`
+ * which lays the frame out for that exact moment, and Node steps through
+ * the timeline one screenshot per video frame. Deterministic to the pixel —
+ * the same take renders the same twice — and styled with the same theme as
+ * the caption band, so cards look like Retake, not like a slide deck.
+ *
+ * All of it is render-time: change a title, `retake render`, seconds.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { chromium } from "playwright";
+import { execFileSync } from "node:child_process";
+const AMBER = "#e8b04b";
+const ease = "t<0?0:t>1?1:t*t*(3-2*t)"; // smoothstep, in the page
+function cardHtml(w, h, theme, title, subtitle, ms) {
+    const titleSize = Math.round(Math.min(w * 0.055, h * 0.14));
+    const subSize = Math.round(titleSize * 0.4);
+    return `<!doctype html><meta charset="utf-8"><style>
+  html,body{margin:0;width:${w}px;height:${h}px;overflow:hidden;background:${theme.background}}
+  .wrap{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;font-family:-apple-system,BlinkMacSystemFont,"SF Pro Display","Helvetica Neue",Arial,sans-serif}
+  .title{font-size:${titleSize}px;font-weight:700;letter-spacing:-.02em;color:${theme.ink};opacity:0}
+  .rule{height:${Math.max(3, Math.round(titleSize * 0.07))}px;background:${AMBER};border-radius:99px;margin:${Math.round(titleSize * 0.35)}px 0;width:0}
+  .sub{font-size:${subSize}px;color:${theme.ink};opacity:0;font-weight:400}
+  </style>
+  <div class="wrap"><div class="title"></div><div class="rule"></div><div class="sub"></div></div>
+  <script>
+  const T = document.querySelector(".title"), R = document.querySelector(".rule"), S = document.querySelector(".sub");
+  T.textContent = ${JSON.stringify(title)}; S.textContent = ${JSON.stringify(subtitle ?? "")};
+  const DUR = ${ms}, FADE = Math.min(420, DUR * 0.22), OUT = Math.min(320, DUR * 0.18);
+  const ez = (t) => (${ease});
+  window.__seek = (ms) => {
+    const a = ez(ms / FADE);                          // entrance
+    const o = ez((DUR - ms) / OUT);                   // exit
+    const v = Math.min(a, o);
+    T.style.opacity = v; T.style.transform = "translateY(" + (1 - a) * 14 + "px)";
+    R.style.width = (ez((ms - FADE * 0.4) / (FADE * 1.6)) * ${Math.round(titleSize * 3.2)}) * Math.min(1, o + 0.0) + "px";
+    R.style.opacity = Math.min(1, o + 0.2);
+    S.style.opacity = v; S.style.transform = "translateY(" + (1 - a) * 10 + "px)";
+    return true;
+  };
+  </script>`;
+}
+function calloutHtml(w, h, box, label, ms, fontSize, ink) {
+    const pad = 10;
+    const r = { x: box.x - pad, y: box.y - pad, w: box.width + 2 * pad, h: box.height + 2 * pad };
+    const below = r.y + r.h + 18 + fontSize * 2 < h; // label under the ring when there is room
+    return `<!doctype html><meta charset="utf-8"><style>
+  html,body{margin:0;width:${w}px;height:${h}px;overflow:hidden;background:transparent}
+  .ring{position:absolute;left:${r.x}px;top:${r.y}px;width:${r.w}px;height:${r.h}px;border:3px solid ${AMBER};border-radius:14px;box-shadow:0 0 0 3px rgba(0,0,0,.06);opacity:0}
+  .tag{position:absolute;left:${Math.max(8, Math.min(w - 8, r.x))}px;top:${below ? r.y + r.h + 12 : Math.max(8, r.y - fontSize * 1.9 - 12)}px;background:${ink};color:#f4f4ef;font-family:-apple-system,BlinkMacSystemFont,"SF Pro Text",Arial,sans-serif;font-size:${fontSize}px;font-weight:600;line-height:1;padding:${Math.round(fontSize * 0.55)}px ${Math.round(fontSize * 0.8)}px;border-radius:10px;opacity:0;max-width:${Math.round(w * 0.6)}px;white-space:nowrap}
+  </style>
+  <div class="ring"></div>${label ? '<div class="tag"></div>' : ""}
+  <script>
+  const ring = document.querySelector(".ring"), tag = document.querySelector(".tag");
+  if (tag) tag.textContent = ${JSON.stringify(label ?? "")};
+  const DUR = ${ms}, IN = Math.min(360, DUR * 0.25), OUT = Math.min(280, DUR * 0.2);
+  const ez = (t) => (${ease});
+  window.__seek = (ms) => {
+    const a = ez(ms / IN), o = ez((DUR - ms) / OUT), v = Math.min(a, o);
+    ring.style.opacity = v;
+    ring.style.transform = "scale(" + (1.12 - 0.12 * a) + ")";
+    if (tag) { tag.style.opacity = Math.min(ez((ms - IN * 0.6) / IN), o); tag.style.transform = "translateY(" + (1 - a) * 6 + "px)"; }
+    return true;
+  };
+  </script>`;
+}
+/** Screenshot a __seek()-driven page at every frame; returns the frame dir. */
+async function renderFrames(html, w, h, ms, fps, transparent) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "retake-frames-"));
+    const browser = await chromium.launch();
+    const page = await browser.newPage({ viewport: { width: w, height: h } });
+    await page.setContent(html, { waitUntil: "load" });
+    const frames = Math.max(2, Math.round((ms / 1000) * fps));
+    for (let i = 0; i < frames; i++) {
+        await page.evaluate((t) => window.__seek(t), (i / fps) * 1000);
+        await page.screenshot({ path: path.join(dir, `f${String(i).padStart(5, "0")}.png`), omitBackground: transparent });
+    }
+    await browser.close();
+    return dir;
+}
+/** A title card as an H.264 segment at the final canvas size, plus (for the
+    intro) the settled middle frame as cover.png — the poster. */
+export async function renderCard(ffmpeg, outDir, kind, spec, w, h, fps, theme) {
+    const dir = await renderFrames(cardHtml(w, h, theme, spec.title, spec.subtitle, spec.ms), w, h, spec.ms, fps, false);
+    const mp4 = path.join(outDir, `.card-${kind}.mp4`);
+    execFileSync(ffmpeg, ["-y", "-loglevel", "error", "-framerate", String(fps), "-i", path.join(dir, "f%05d.png"), "-c:v", "libx264", "-crf", "17", "-preset", "veryfast", "-pix_fmt", "yuv420p", mp4], { stdio: "inherit" });
+    let cover;
+    if (kind === "intro") {
+        const frames = fs.readdirSync(dir).sort();
+        const settled = frames[Math.min(frames.length - 1, Math.round(frames.length * 0.55))];
+        cover = path.join(outDir, "cover.png");
+        fs.copyFileSync(path.join(dir, settled), cover);
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+    return { mp4, cover };
+}
+/** A callout as a VP9 segment with alpha, overlaid onto the take at render. */
+export async function renderCalloutOverlay(ffmpeg, outDir, index, c, w, h, fps, fontSize, ink) {
+    const dir = await renderFrames(calloutHtml(w, h, c.box, c.label, c.ms, fontSize, ink), w, h, c.ms, fps, true);
+    const webm = path.join(outDir, `.callout-${index}.webm`);
+    execFileSync(ffmpeg, ["-y", "-loglevel", "error", "-framerate", String(fps), "-i", path.join(dir, "f%05d.png"), "-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p", "-b:v", "0", "-crf", "28", webm], { stdio: "inherit" });
+    fs.rmSync(dir, { recursive: true, force: true });
+    return webm;
+}
+/** A cover built from a real frame of the video with the title laid over it —
+    a screenshot plus a few words, which is what actually stops a scroll. Not
+    a skin of the centred card: the product is the picture. */
+export async function renderTitledCover(ffmpeg, frame, out, spec, w, h, theme) {
+    const b64 = fs.readFileSync(frame).toString("base64");
+    const titleSize = Math.round(Math.min(w * 0.045, h * 0.1));
+    const subSize = Math.round(titleSize * 0.42);
+    const html = `<!doctype html><meta charset="utf-8"><style>
+  html,body{margin:0;width:${w}px;height:${h}px;overflow:hidden;background:${theme.background};font-family:-apple-system,BlinkMacSystemFont,"SF Pro Display","Helvetica Neue",Arial,sans-serif}
+  .shot{position:absolute;inset:0;background:url(data:image/png;base64,${b64}) center/cover no-repeat}
+  .veil{position:absolute;inset:0;background:linear-gradient(to bottom, rgba(0,0,0,0) 38%, rgba(0,0,0,.14) 58%, ${theme.background} 78%)}
+  .txt{position:absolute;left:0;right:0;bottom:${Math.round(h * 0.055)}px;text-align:center;padding:0 ${Math.round(w * 0.08)}px}
+  .t{font-size:${titleSize}px;font-weight:700;letter-spacing:-.02em;color:${theme.ink};margin:0}
+  .r{height:${Math.max(3, Math.round(titleSize * 0.08))}px;width:${Math.round(titleSize * 2.6)}px;background:${AMBER};border-radius:99px;margin:${Math.round(titleSize * 0.3)}px auto}
+  .s{font-size:${subSize}px;color:${theme.ink};margin:0;opacity:.75}
+  </style>
+  <div class="shot"></div><div class="veil"></div>
+  <div class="txt"><p class="t">${escapeHtml(spec.title)}</p><div class="r"></div>${spec.subtitle ? `<p class="s">${escapeHtml(spec.subtitle)}</p>` : ""}</div>`;
+    const browser = await chromium.launch();
+    const page = await browser.newPage({ viewport: { width: w, height: h } });
+    await page.setContent(html, { waitUntil: "load" });
+    await page.screenshot({ path: out });
+    await browser.close();
+    return out;
+}
+const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");