retake-demos 0.2.2 → 0.4.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,277 @@
+# 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.
+
+## What a change costs
+
+Reaching for a new recording when a re-render would do is the one mistake
+that wastes real time. Almost nothing needs the camera twice.
+
+| You want to change | Do this | Cost |
+|---|---|---|
+| size, shape, format | `retake render <dir> --preset <other>` | seconds |
+| caption words, speed, zoom, cards, music | edit the manifest, `retake render` | seconds |
+| **where** a caption or still sits | `nudge: <ms>` on the scene, then render | seconds |
+| the ENDING of a demo | `retake run … --from <scene>` | the tail only |
+| one beat, while iterating | `retake run … --until <scene>` | the head only |
+| what the demo actually DOES | full `retake run` | the whole thing |
+
+`--from` runs the earlier steps at full speed and off camera so the app
+reaches the right state, then starts recording there. A seven-minute demo
+whose last third changed costs ninety seconds.
+
+Housekeeping, since outputs grow: `retake takes <dir>` lists the kept
+versions of a demo and `retake restore <dir> <id>` puts one back;
+`retake tidy` reports reclaimable disk and removes nothing without
+`--apply`. Neither ever touches a raw recording or a take.json — those are
+the only things a re-render cannot rebuild.
+
+
+## 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 the RESULT, and know the three ways a bare selector lies.** It
+  resolves the moment the element exists, which is wrong when (a) the element
+  is the PREVIOUS action's banner still on screen — use
+  `{ action: waitFor, selector: ".landed", gone: true }` and wait for it to
+  leave; (b) the element is a shell that streams its text in — use
+  `minChars: 40`; (c) the element is there but still changing — use
+  `stableMs: 500`, which resolves when its subtree has been quiet that long.
+  Each of these cost a real take before it existed.
+- **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.
+- **`run --name <x>`** records into outputs/<x> without touching the
+  original; **`render <dir> --out <newdir>`** re-renders a copy and leaves
+  the published cut alone. Revising is never overwriting.
+- **A failed step writes `failed-step.png`** (full page, the exact moment)
+  and the failing URL into the log and take.json. Read the picture first.
+- **`manifest.used.yaml`** sits in every output — the exact manifest this
+  video came from, not whatever the file on disk says today.
+- **Size is a render-time choice.** One preset = one output size, always
+  (the caption band sits inside the canvas). Any take renders at any preset:
+  `retake render outputs/<name> --preset post-vertical`. Never re-record to
+  change a shape, and never set `viewport` — `validate` warns because it
+  makes one demo a different shape from the rest.
+- **`retake contact outputs/<name>`** — one timestamped grid of the whole
+  video. This is how you review a cut without pulling frames by hand, and
+  how you check a caption is still true in the middle of its own scene.
+  Launch cuts write `contact.png` automatically.
+- **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.
+
+## Every release gets a note a non-developer can read
+
+`site/releases.json` is the one list of what shipped. The landing page and the
+Retake window both read it — there is no second copy to update.
+
+When a release changes anything a person can see, add an entry: a version, a
+date, a headline, and a few lines. Write them for the person using Retake, not
+for whoever wrote the code. Name no files. Name no flag they will not type. Do
+not write "refactor", "regression", "schema" or "pipeline". If a line only
+makes sense to someone who has read the source, it is not a release note —
+it belongs in the commit message, which is where that audience already is.
+
+Good: "You choose the cover image. Click any frame to make it the one people
+see first." Bad: "Poster selection is now persisted via a marker file."

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,15 @@ 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
+  contact.png     launch cuts: one timestamped grid of the whole video (`retake contact`)
   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 +98,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
@@ -103,9 +119,13 @@ outputs:
 
 The full template is [`demos/example.yaml`](demos/example.yaml); `retake init` copies it into a new workspace.
 
-**Steps** — `click`, `type`, `fill`, `hover`, `drag`, `scroll`, `keyboard`, `navigate`, `wait`, `waitFor`, `evaluate`, `upload`, `download`, `screenshot`, `scene`. Every step takes `pauseAfter`, `waitFor`, `timeout`, `secret`. Targets are a selector, or a point — `{x, y}` or `{selector, dx, dy}` — for canvases and SVG editors. `${VAR}` expands from `.env` and fails loudly when unset.
+**Steps** — `click`, `type`, `fill`, `select`, `hover`, `drag`, `scroll`, `keyboard`, `navigate`, `wait`, `waitFor`, `evaluate`, `upload`, `download`, `screenshot`, `scene`. Every step takes `pauseAfter`, `waitFor`, `timeout`, `secret`. Targets are a selector, or a point — `{x, y}` or `{selector, dx, dy}` — for canvases and SVG editors. `${VAR}` expands from `.env` and fails loudly when unset.
+
+**Waits** take three modifiers, because a bare selector resolves the moment the element exists: `gone: true` waits for it to leave (the previous action's banner), `minChars: 40` waits for it to hold real text (a streamed reply), `stableMs: 500` waits for its subtree to stop changing.
+
+**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. **Labels must be unique** — `thumbnail`, `until`, the stills and the proof log all address scenes by label, so two scenes called the same thing make every one of those ambiguous. `validate` rejects it.
 
-**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.
 
@@ -115,33 +135,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×540 | 960×464 | iterating — the finals' layout at a quarter of the pixels, fastest |
+| `preview-fast` | 1920×1080 | 1920×930 | checking timing and framing, hardware-encoded |
+| `post-landscape` *(default)* | 1920×1080 | 1920×930 | the general-purpose demo, plus a CRF-14 master |
+| `post-square` | 1080×1080 | 1080×960 | feeds |
+| `post-vertical` | 1080×1920 | 1080×1800 | shorts and reels |
+| `docs-gif` | 1440×900 | 1440×800 | README and docs GIFs |
+| `master` | 1920×1080 | 1920×930 | archive, CRF 12 |
 
-**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.
+**One preset, one size — and size is not recorded.** The caption band sits inside the canvas, so `post-landscape` is always exactly 1920×1080 and two demos of the same app are never different shapes. Better still, the shape is decided at render: the take is fitted into whichever canvas you ask for, so `retake render outputs/x --preset post-vertical` gives you a 9:16 cut of a demo you recorded landscape — seconds, no browser, no re-record. Setting `viewport` in a manifest overrides the page and `validate` warns, because that is how one demo ends up a different shape from the rest.
 
-**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.
+**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.
 
-## Signing in
+## 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.
+
+**Without the window:** the agent relays one line — run this in your workspace and type the values (hidden):
+
+```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.
+
+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/dist/captions.js

@@ -0,0 +1,55 @@
+/** 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, captionTexts) {
+    if (q.layout !== "band" && q.layout !== "card")
+        return 0;
+    if (!q.captions)
+        return 0;
+    // A band with nothing to draw in it is an empty strip on the video: when
+    // the texts are known and none exist, the page gets the whole frame.
+    if (captionTexts && !captionTexts.some((t) => t && t.trim()))
+        return 0;
+    // Fixed per preset. The default page is the canvas minus this, so the
+    // finished video is exactly the preset's size — every take the same shape,
+    // and no player letterboxing it.
+    return q.bandHeight;
+}