retake-demos 0.3.0 → 0.4.0

package/site/releases.json

@@ -0,0 +1,45 @@
+{
+  "_readme": "What's new, written for the person using Retake — not for whoever wrote it. Both the landing page and the Retake window read THIS file; there is no second copy. Rules for adding one: say what changed for them, name no files, no flags they will not type, no words like refactor or regression. If a line only makes sense to someone who has read the source, it does not belong here. Newest first. Add an entry on every release that changes what people see.",
+  "releases": [
+    {
+      "version": "0.4.0",
+      "date": "2026-08-25",
+      "headline": "Videos come out the size you asked for — and changing your mind is nearly free",
+      "notes": [
+        "Every video is exactly the size of the format you picked. Landscape is 1920×1080, square is square, vertical fits a phone. No more sizes drifting between takes.",
+        "Changing your mind costs seconds, not another recording. Size, shape, format, captions, speed, zoom, music, title cards and the cover image all re-make themselves from the recording you already have.",
+        "Moved a caption to the wrong moment? Nudge it. The caption, the still and the cover all follow, and you never record again.",
+        "Only the ending changed? Record only the ending. The earlier steps still run so your app gets to the right place, but they happen at full speed and off camera. On a seven-minute demo that is about three minutes instead of sixteen.",
+        "Your old recordings are kept. A re-record no longer throws away the take you had — you can look at the previous ones and go back to any of them. Only the recording itself is stored, so it stays small.",
+        "A failed recording can no longer cost you the one that worked.",
+        "New: clear out old files safely. It shows you what it would free before removing anything, and never touches a recording.",
+        "In the window: pick several demos at once — or a whole folder — and archive them together. The archive empties in one click.",
+        "Launch videos can open with a title card and close with your own sign-off, put music underneath, and add a spoken voiceover.",
+        "Dead air gets trimmed: while your app is thinking, the video moves through the wait instead of sitting in it.",
+        "You can sign in to a demo account without any AI ever seeing your password.",
+        "Renders are about twice as fast.",
+        "Your agent now checks far more before recording — that a click will land on something clickable, that a stub is really being used, that it is looking at the same screen the recording will — so fewer takes are wasted finding out mid-recording.",
+        "On a long demo your agent shows you a quick draft and asks before spending the full recording.",
+        "The window has been rebuilt: one place for everything, and it stops shouting at you."
+      ]
+    },
+    {
+      "version": "0.3.0",
+      "date": "2026-08-23",
+      "headline": "Demos behind a login",
+      "notes": [
+        "Demos of apps that need signing in. You sign in once in a real browser window; nothing types your password and nothing records it.",
+        "The video player shows your video in its own shape, with no black bars around it."
+      ]
+    },
+    {
+      "version": "0.2.0",
+      "date": "2026-08-23",
+      "headline": "The first public release",
+      "notes": [
+        "Describe a demo in one readable file, and get a video, still frames, and a written record of what happened.",
+        "When your app changes, fix the file and run it again — instead of recording the whole thing over."
+      ]
+    }
+  ]
+}

package/skill/SKILL.md

@@ -62,10 +62,53 @@ say so in one line and stop.
    names actually on screen? Anything in shot that shouldn't be (dev
    badges, leftover data, cut-off text)? Wrong story or failed step →
    `edit`, run again. More than four rounds → ask the person.
-8. When it is right: `run` with `preview=false` once (full quality), then
+8. **Before the expensive take, if it is expensive, show them the draft.**
+   `run` prints an estimate before capture. If it said this is a long take
+   (over ~2.5 minutes), do not go straight to full quality: `ask` them,
+   naming the demo and pointing at the draft in the Retake window, and say
+   what the full take will cost. Something like *"Draft is ready — 40s, 6
+   scenes, in the window. Full quality is about 7 minutes of recording.
+   Worth spending, or change something first?"*
+   - **Their taste is the thing you cannot check.** Every mechanical
+     problem is already caught by `dry` and the take's own checks. What a
+     person sees that no checker will is whether the story lands, whether
+     the payoff reads, whether it looks right for their product. Getting
+     that verdict on a cheap draft is the whole point.
+   - **Short take?** Skip the gate. Asking someone to approve a 30-second
+     recording costs them more than just recording it.
+   - **Nobody there to ask?** Never block and never guess. Leave the draft,
+     `done` with what you have and what it would cost, and let them start
+     the expensive one when they are back.
+9. When they say go: `run` with `preview=false` once (full quality), then
    `done` with one sentence. Outputs: `demo.mp4`, `stills/` (one PNG per
    scene), `proof-log.md`.
 
+## What a change costs — read this before re-recording anything
+
+The one mistake that wastes real time is reaching for a new recording when a
+re-render would do. Almost nothing needs the camera twice.
+
+| You want to change | Do this | Cost |
+|---|---|---|
+| size, shape, format (landscape → square → vertical) | `render` with another preset | seconds |
+| a caption's words, the speed, a zoom, cards, music | edit the manifest, `render` | seconds |
+| **where** a caption or still sits in time | `nudge: <ms>` on the scene, then `render` | seconds |
+| which frame is the poster | click a frame in the window, or `--scene` | seconds |
+| the ENDING of a demo | `run --from <scene>` | the tail only |
+| one beat, iterating | `run --until <scene>` | the head only |
+| the steps themselves — what the demo DOES | full `run` | the whole thing |
+
+Only the last row needs the camera for the whole demo. If you are about to
+re-record and your reason is not in that last row, you are paying for
+something you already have.
+
+`nudge` and `--from` are the two most recently added and the two most often
+missed. `nudge: -1500` moves a scene's marker 1.5s earlier in the finished
+video — caption, still and thumbnail follow it. `--from <scene>` runs the
+earlier steps at full speed off camera so the app reaches the right state,
+then starts recording there; a seven-minute demo whose last third changed
+costs ninety seconds instead of seven minutes.
+
 ## Style — how the person wants their videos to look
 
 Do not ask about knobs before the first take — nobody has opinions about
@@ -151,7 +194,13 @@ Anything they would tell a videographer maps to a knob, in plain English:
 - "hide the cursor" → `cursor: false`
 - "no captions" / "shorter captions" → captions off, or rewrite them
 - "slower" / "hold the ending" → `pauseAfter`, scene `holdMs`, end waits
-- "square" / "vertical" / "for X" → preset `post-square` / `post-vertical`
+- "square" / "vertical" / "for X" → preset `post-square` / `post-vertical`,
+  and this is a RE-RENDER of the take you already have, never a re-record:
+  `retake render outputs/<name> --preset post-square`. Size is not recorded.
+- **Never set `viewport`.** The preset owns the size — one preset, one
+  output shape, every time. A manifest that sets its own viewport comes out
+  a different shape from every other demo of the same app, and players
+  letterbox it. `validate` warns.
 
 The default is calm and real: still camera (`camera: static` is the
 manifest default — write `auto` only when asked), cursor shown, plain
@@ -212,6 +261,103 @@ Never ask for a credential in chat. Never write a literal one into a
 manifest. Never invent one. Tell the person to use a demo account — the
 output is a video they may publish.
 
+## Hard-won rules from real sessions
+
+- **Scout again after ANY server restart** — not just the first time. A dev
+  server that restarts can come back serving a different build or mode on
+  the same port, and the take fails 20 seconds in with a selector timeout
+  that looks like your manifest's fault. Five takes were lost to this once.
+  If the run aborts saying "the app at <url> is not what this manifest
+  expects", believe it: look at not-the-app.png, fix the server, re-run.
+- **A failed step leaves failed-step.png next to the take** — a full-page
+  picture of the exact moment. Read it BEFORE re-running or editing
+  anything; it turns a five-round guess loop into one round.
+- **`waitFor` can match a STALE element.** After an action, the previous
+  capture's Undo button (or any leftover) may still satisfy your selector,
+  and the click lands on the wrong thing. Wait for something unique to the
+  NEW state (a count, a heading, a row with the new text), never for a
+  control that also existed before the action.
+- **What `compressIdle` compresses:** the app's own delays (`waitFor`,
+  `navigate`) and long typing. It NEVER touches your `wait` steps — those
+  are your pacing. Do not re-render hoping a `wait` gets shorter; shorten
+  the wait.
+- **Streaming content:** `waitFor` on a container resolves when the shell
+  exists, not when the text has streamed in. Wait on the signal the app
+  itself uses — a button flipping from busy to ready
+  (`button:has-text("Send")`), a count, a class change.
+
+## Waits that do not lie
+
+A bare `waitFor` resolves the instant the element exists. Three times that
+is the wrong moment, and each has cost a take:
+
+- the element is the **previous** action's success banner, still on screen →
+  `{ action: waitFor, selector: ".landed", gone: true }`
+- the element is an empty shell that **streams** its text in →
+  `minChars: 40`
+- the element is there but still **changing** → `stableMs: 500`
+
+Prefer these to a flat `wait`. A timer that happens to work today is the
+thing that breaks when the app gets slower.
+
+## Rules the manifest enforces, so you do not have to remember them
+
+`validate` and `dry` refuse these outright rather than letting a take discover
+them:
+
+- **Scene labels are unique.** `thumbnail`, `--until`, the stills and the proof
+  log all address a scene by its label.
+- **The action has to fit the element.** `type` on a `<select>`, `select` on a
+  `<div>`, `upload` on something that is not a file input, `click` on a button
+  that is disabled at that moment — `dry` names the fix.
+- **A navigate that changes only the `#fragment` is flagged.** It does not
+  reload the document, so an SPA keeps its state and a stub armed just before
+  it never fires. Add a throwaway query param, or click the app's own link.
+- **A stub that never answers a request fails `check`.** Armed but unmatched
+  means that screen showed the app's real data.
+- **Seeds may not leave anything running** — no `&`, `nohup`, `pm2`. Starting
+  the app is `start_app`'s job, which the person authorises.
+
+## Cheap iteration — a demo should not cost five takes
+
+A take is real time (capture is ~2.3× the finished video) and the field
+average is three to five takes per demo. Most of that is avoidable:
+
+1. **Draft everything.** `--preset draft` has the same layout and timing at
+   a quarter of the pixels. Judge the story there; switch to a post preset
+   once, at the end.
+2. **`--until <scene>` for the head, `--from <scene>` for the tail.** These
+   are the two halves of the same idea and `--from` is the one people miss:
+   when the ending changed, everything before it still runs (the app has to
+   reach that state) but at full speed and off camera. Re-recording a 60s
+   demo to change its last 8 seconds is paying for 50 seconds you already
+   have.
+3. **Get a person's eyes on a cheap draft before buying an expensive take.**
+   A draft costs a quarter of the pixels and answers the only question a
+   checker cannot: is this the right video? Spending seven minutes of
+   capture to find out the story was wrong is the most expensive mistake
+   available in this tool.
+4. **A caption in the wrong place is a nudge, not a take.** `nudge: -1500` on
+   a scene moves its marker 1.5s earlier in the finished video; the caption,
+   the still and the thumbnail all follow. Re-render and look — it is seconds.
+5. **Never re-record for a size or a format.** `render outputs/<name>
+   --preset post-vertical` re-frames the take you have. Captions, camera,
+   speed, cards and posters are all render-time too.
+6. **`dry` before every `run`** — including after the app restarts. It is
+   ~10s and it catches the wrong-build-on-the-port failure that otherwise
+   costs a take and a confusing video.
+7. **Fix everything `dry` and the proof log report in ONE pass.** Reading
+   the whole failure list before editing turns three rounds into one.
+
+## Judging the cut
+
+`check: pass` proves the file is sound, not that the demo is good. Before
+`done`, look: `retake contact outputs/<name>` writes one timestamped grid
+of the whole video (launch cuts get it automatically). Read it for the
+things checks cannot see — a caption that is true when its scene starts and
+false by the end, a payoff nobody can find, four seconds where nothing
+changes. `look` at the payoff scene is the other half.
+
 ## When a take fails
 
 The camera stops at the first failed step, so a failed take is short and

package/demos/example.yaml

@@ -1,65 +0,0 @@
-# A template. Copy it, point it at your app, replace the selectors.
-#
-#   retake validate demos/example.yaml     schema + warnings, instant
-#   retake dry demos/example.yaml          every selector and wait, no camera
-#   retake run demos/example.yaml          record + render → outputs/example/
-#
-# Or don't write it at all: once `retake install` has run, ask your coding
-# agent for "a demo of my app at localhost:3000 showing …" and it drafts,
-# dry-runs, records and checks this file for you. `retake ui` is the window
-# to watch it in.
-
-name: example
-title: "Example — the shape of a demo"
-url: http://localhost:3000
-
-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: 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 }
-#   - { kind: evaluate, script: "localStorage.clear()" }
-#   - { kind: command, run: "curl -X POST http://localhost:3000/api/test/reset" }
-seed: []
-
-# Runs before recording starts and is trimmed off the front of the video.
-# Sign-ins belong here — see the "Signing in" section of the README.
-setup: []
-
-steps:
-  - action: scene
-    label: start
-    caption: "The problem, before anything happens."
-    camera: static
-  - action: wait
-    ms: 1800
-
-  - action: click
-    selector: "button:has-text('Get started')"
-    pauseAfter: 900
-
-  - action: type
-    selector: "input[name=title]"
-    text: "A realistic thing a person would type"
-    delay: 40
-    pauseAfter: 600
-
-  - action: click
-    selector: "button[type=submit]"
-  - action: waitFor              # wait for the RESULT, never a fixed sleep
-    selector: ".result"
-    timeout: 30000
-
-  - action: scene
-    label: result
-    caption: "And the result, which is the whole point."
-  - action: wait
-    ms: 2600
-
-outputs:
-  mp4: true
-  gif: false                   # opt-in; gifski is used when installed
-  thumbnail: { scene: result }