retake-demos 0.13.1 → 0.14.0

package/.env.example

@@ -1,9 +1,7 @@
-# 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.
+# Logins are not kept here any more: the Retake window (or `retake login <url>`)
+# saves one per site in your Keychain, and demos sign in with ${LOGIN_USER} and
+# ${LOGIN_PASSWORD}. A value set below still wins over a saved login, and the
+# ${APP_USER}-style names older demos use keep working. Blank lines count as unset.
 APP_USER=
 APP_PASSWORD=
 APP_TOTP_SECRET=

package/AGENTS.md

@@ -23,6 +23,7 @@ that wastes real time. Almost nothing needs the camera twice.
 |---|---|---|
 | size, shape, format | `retake render <dir> --preset <other>` | seconds |
 | caption words, speed, zoom, cards, music | edit the manifest, `retake render` | seconds |
+| join separate recorded outputs | `retake stitch outputs/a outputs/b --out outputs/joined/demo.mp4 --transition fade` | render only |
 | **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 |
@@ -38,6 +39,13 @@ versions of a demo and `retake restore <dir> <id>` puts one back;
 `--apply`. Neither ever touches a raw recording or a take.json — those are
 the only things a re-render cannot rebuild.
 
+`retake stitch` accepts output folders or video files in playback order. It
+uses the existing transition styles and the first clip's canvas and frame
+rate. Other clips fit without cropping. Source audio stays aligned and
+crossfades with non-cut joins. Use `--no-audio` for silence. The output must
+be a new MP4 path. This command creates no recording or library entry and
+does not synthesize or approve narration. See `docs/stitch.md`.
+
 
 ## Starting from nothing (the person pasted the repo link)
 
@@ -57,7 +65,9 @@ it exists.
 ## The loop an agent should run
 
 ```
-write demos/<name>.yaml
+retake routine                             the locked standard — read it BEFORE drafting
+  → write demos/<name>.yaml
+  → retake routine apply demos/<name>.yaml  stamp format, captions, voice, rate
   → 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"
@@ -81,6 +91,41 @@ 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.
 
+## First call in any session: `retake routine`
+
+It prints the locked standard and, when the product has one, names its **brief** (`demos/capture.md` for Capture). Over MCP, the `routine` tool returns the whole brief. Read it before writing a step: where the app runs, what is on the board, which selectors hold, and the pitfalls that already cost takes.
+
+## The settings are not yours to choose — `retake routine`
+
+A workspace has a standard: output format, captions on or off, which voice
+narration uses and how fast it speaks, music or none. It lives in
+`demos/routine.json`, a person set it, and it is applied by the machine.
+
+Read it with `retake routine` before you draft, and **do not set these
+yourself**: `preset`, `layout`, `captions`, `viewport`, `scale`,
+`voiceover.voice`, `voiceover.ratePercent`, `music`. Choosing them per demo is
+exactly how one video comes back narrated too fast, the next too slow, and a
+third in a voice nobody asked for.
+
+```
+retake env up                       bring the app up isolated, reset, and proven — before any take
+retake routine                      what every recording here will look and sound like
+retake routine learn                read the standard off demos already recorded here
+retake routine apply <manifest>     stamp the standard onto a manifest you drafted
+retake routine run                  work demos/plan.json: stamp, dry, record, finish
+retake routine check                would a viewer see ONE set? measures the finished files
+retake routine reference <video>    the north star every cut is scored against
+```
+
+`retake routine apply` never turns narration ON — that still needs a script and
+a person who has heard it. It only fixes the voice and rate of narration that
+already exists, and strips any `viewport`/`scale` pin, which silently beats the
+preset and is the one way two takes of the same app come out different shapes.
+
+Writing the steps, the captions and the story is still entirely your job.
+`demos/style.md` is the taste that needs judgement; the routine is the part
+that only needs to be the same every time.
+
 ## How to tell Claude Code / Codex to use it
 
 From the Retake folder:
@@ -186,24 +231,29 @@ Full reference: `README.md` → "Demo-as-code". The short version:
 
 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.
+- **Ask for the site, not for the value.** Over MCP, call `login` with the
+  app's URL and a one-line why. A login is saved once per site (in the
+  person's Keychain) and reused by every demo of that site, so it often
+  answers "Ready" at once, with the exact manifest lines. Otherwise a form
+  opens in the Retake window — relay the sentence the tool returns, link
+  included, wait for "done", call `login` again. Without a window the
+  person runs `retake login <url>` (typed into their terminal, hidden). From
+  the CLI only, say the same sentence yourself.
+- **Put the sign-in under `auth.setup`** with `${LOGIN_USER}` /
+  `${LOGIN_PASSWORD}` and `secret: true`, plus the per-site
+  `auth.storageState` that `login` gives you. It runs before the camera, is
+  trimmed off, and the session is reused by later takes; when it runs out,
+  Retake signs in again by itself. A failed sign-in never saves a session.
+- **Authenticator codes:** `${TOTP:LOGIN_TOTP}` is the current six-digit
+  code, computed when the field is filled — present when the person saved
+  an authenticator key.
+- **SMS, SSO, captcha:** a script cannot; a person can, once. The same form
+  has "Sign in by hand" (or `retake login <url> --by-hand`): a real window
+  opens, they sign in, press Done, and the session is kept. Leave
+  `auth.setup` empty; a take with no fresh session and no setup refuses to
+  run rather than record logged out.
+- **Other values** (API tokens, keys) still go through `secrets` into the
+  workspace `.env` by name, referenced as `${NAME}` with `secret: true`.
 - **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.
@@ -235,9 +285,14 @@ Most real demos start behind a sign-in. The agent never sees a password:
   control where nothing is wrong, then reports recall and false positives.
   Expensive: nine takes, about ten minutes, needs the app running. The report
   it leaves is cheap to read, and **you should read it before telling anybody
-  how much a sweep finding is worth.** Its stated limits travel with it: the
-  seeds were written by somebody who has read the checklist, so recall is an
-  upper bound.
+  how much a sweep finding is worth.** Its stated limits travel with it, and
+  all four belong in anything you say about the numbers: the seeds were written
+  by somebody who has read the checklist, so recall is an upper bound; injected
+  faults are cleaner than real ones; the run names the checklist items nothing
+  seeds, and says nothing whatever about those; and a run whose control did not
+  record cleanly measured nothing at all and exits 3 rather than printing a
+  reassuring zero. From MCP you can only READ the last measurement — making one
+  is a terminal command, because it records for ten minutes.
 - `retake intent` — what the product IS, in the builder's words: what it does,
   who uses it, and what about it is deliberate. Every visual check reads it.
   Without it they judge the app as a generic web page — measured on a real

package/README.md

@@ -42,16 +42,27 @@ mkdir my-demos && cd my-demos
 retake install
 ```
 
-`retake install` makes the folder a workspace (`demos/`, `outputs/`, `.env`, the `.gitignore` lines), downloads Chromium, registers the tools with Claude Code and installs its *recording-product-demos* skill, and prints the config for Codex. Restart your agent afterwards — agents load tools at the start of a session.
+`retake install` makes the folder a workspace (`demos/`, `outputs/`, `.env`, and the `.gitignore` lines), downloads Chromium, registers the tools with Claude Code, installs its *recording-product-demos* skill, and prints the config for Codex. Restart your agent afterwards because agents load tools at the start of a session.
 
-Prefer not to install globally? `npx retake-demos install` works the same. Don't use Claude Code? `retake agent` prints the MCP config for Codex, Cursor, or anything else.
+Start `retake ui` and open http://localhost:4310. On an empty workspace, Retake asks only for:
 
-Then, in your agent:
+1. the public or localhost URL;
+2. the result the viewer should see;
+3. the final sound: silent, Edge, local Aiden, or local Kokoro;
+4. confirmation of the request.
+
+The first draft is always silent. Choosing a local voice plays a packaged sample and asks for consent, but it does not download a model or generate speech. Narration starts only after you approve the recording and its continuous script.
+
+Prefer not to install globally? `npx retake-demos install` works the same. Don't use Claude Code? `retake agent` prints the MCP config for Codex, Cursor, or another MCP client.
+
+If you already have demos, ask your agent directly:
 
 > Record a demo of my app at localhost:3000 showing a new user creating their first project.
 
 and in another terminal, `retake ui` → http://localhost:4310 to watch it happen. The agent reports its plan and progress there; the video, stills and receipts land there when it's done.
 
+Not sure what to request? Use [How to prompt an agent to use Retake](docs/prompting-retake.md) to choose the recording type, format, voice, music, camera, branding, privacy rules, and delivery checks.
+
 `retake doctor` tells you if anything is missing.
 
 ## What you get
@@ -82,6 +93,10 @@ retake validate demos/x.yaml   # schema + warnings, instant
 retake dry demos/x.yaml        # every selector and wait, no camera (~30s)
 retake run demos/x.yaml --preset draft   # first take, quarter-size, fast
 retake check outputs/x         # resolution, fps, duration, files: pass/fail
+retake golden approve finished.mp4 --id short-landscape --title "Short landscape" --approved-by "Your name" --rubric story=pass,framing=pass,timing=pass,text=pass,motion=pass  # interactive human approval
+retake golden add finished.mp4 --approval-receipt goldens/.approvals/short-landscape-<hash>.json  # store evidence; never copies the MP4
+retake golden verify           # integrity plus the required 5–8 visual families
+retake golden score candidate.mp4 --against short-landscape  # cheap deterministic media scorecard
 retake verify outputs/x        # did it LOOK right: each scene's `expect`, judged (exit 3 on failure)
 retake run demos/x.yaml --brisk  # the steps without the pacing — for iterating, not for keeping
 retake intent                 # what your product IS — context every visual check needs
@@ -100,6 +115,178 @@ The expensive step comes last on purpose. `dry` catches most failures in seconds
 
 Exit codes: `0` good · `2` a step failed or the video is a raw fallback · `3` `dry`/`check` failed.
 
+To join separate recordings, use [`retake stitch`](docs/stitch.md). Supply existing output folders or video files, a new MP4 path, and one transition style.
+
+## The recording environment — what has to be true before the camera
+
+Six takes in one session were lost to the environment and not one to the
+recorder: an app pointed at the owner's real cloud store, a browser tab still
+attached that pushed the owner's board back into the "isolated" instance, a dev
+server caching its board so the seed only applied at boot, and two runs racing
+one output folder. Every one is cheap to assert and expensive to read off a
+frame.
+
+```bash
+retake env up        # restart it clean, clear its state, then PROVE it
+retake env check     # prove the running one without restarting
+retake env down
+```
+
+`demos/environment.yaml` declares it:
+
+```yaml
+name: capture-local
+start:
+  command: npm run dev -- --port 3179
+  cwd: ~/capture-local
+  port: 3179
+  env:
+    # Blanked, not unset: .env files are read AFTER the process environment,
+    # so "" is what stops a real token reaching a real account.
+    UPSTASH_REDIS_REST_URL: ""
+    APP_PASSWORD: ""
+reset:
+  restart: true            # the app caches state; without this, take two
+  clear: [".retake/sync"]  # inherits whatever take one left behind
+expect:
+  path: /app
+  present: ["button.tab:has-text('Intentions')"]
+  absent:  ["text=a real note of mine"]   # name what must NOT be there
+```
+
+`absent` is the one that earns its place. A present-only check cannot see real
+data leaking in, and you cannot assert the absence of something you did not
+think of — so name it. `retake routine run` picks the file up automatically and
+**refuses to record** if the environment is not what it claims.
+
+## Routines — the settings nobody should decide twice
+
+`demos/style.md` is taste an agent reads while drafting, so every draft is a
+fresh interpretation of it. That is how one video comes back narrated too fast,
+the next too slow, and a third in a voice nobody asked for.
+
+A routine is the other half: format, captions, voice, speaking rate and music
+held as data and **stamped onto the manifest after it is drafted**. The model
+writes the story; the routine writes the settings; they never argue.
+
+**A new product in one step.** Point at the app and at one video you love:
+
+```bash
+retake routine setup http://localhost:3000/app --like "~/Videos/the-one-we-liked.mp4"
+```
+
+Everything that can be read off those two arrives decided: the shape, the
+cards and their colours from the video; the brand's mark from the page; an
+environment that starts your app on its own port with every token in `.env`
+blanked (names only — a value never leaves its file); and a brief with the
+selectors on the first screen, so the next agent starts informed. What cannot
+be read — the closing card's words, the one real thing that must never appear —
+is asked once, at the end. A live site works too; there is just nothing to start.
+
+**Start by reading, not by guessing.** The first routine used to be Retake's
+defaults — an opinion wearing the clothes of a standard, which `apply` then
+stamps over everything with confidence. Read it off demos you already shipped:
+
+```bash
+retake routine learn                 # what your existing manifests actually agree on
+retake routine learn --write         # make that the standard
+```
+
+It reports what did *not* agree rather than quietly picking, so a split shows up
+as a question instead of a silent decision.
+
+```bash
+retake routine init                  # or start from Retake's defaults instead
+retake routine voices                # hear the named voices once, then stop discussing speed
+retake routine set voice neutral
+retake routine set rate -8           # too fast, once, for every video that follows
+retake routine                       # what every recording here will look and sound like
+```
+
+Three styles, because a style is a shape and not a theme:
+
+| Style | Output | Captions |
+|---|---|---|
+| `showcase` | 1920×1080 | the app inset on your own colour, with a shadow |
+| `fullscreen` | 1920×1080 | the app fills the frame, nothing around it |
+| `mobile` | 1080×1920 | inset the same way, for shorts and reels |
+
+**Proving they match.** A standard nobody measures is a hope.
+
+```bash
+retake routine check          # measures the finished files, not the manifests
+```
+
+It reads back size, frame rate, whether there is a voice and how loud it is, and
+judges each video against the standard *and* against the others — because two
+videos can agree with each other and both be wrong (a batch whose final render
+failed leaves matching previews at the wrong frame rate).
+
+Three things it cannot see, which the earlier steps catch instead: a key Retake
+does not know (strict manifests reject it), a script copied from another demo
+(`validate` compares the narration against that demo's own captions), and data
+the app repopulated mid-take (stub the sync so nothing outside the demo can
+change what is on screen).
+
+**Start from a north star.** One approved video that every cut is held to:
+
+```bash
+retake routine reference "~/Videos/the-one-we-liked.mp4"
+```
+
+Before anything records, it says what this routine cannot reproduce — "the
+reference is narrated, the routine is silent", "the routine uses Retake's own
+card, not a branded one" — so a take is never the thing that discovers it.
+After, `retake routine check` scores each cut against it: the opening card, the
+closing card and the frame around the app, as structural similarity, plus
+size, frame rate and how loud the voice is.
+
+Two pieces exist so a north star *can* be reproduced: a branded `card` (the
+product's mark, typeface, ground, ink and corner circles, drawn by Retake
+instead of added afterwards), and narration with `align: scenes` — the script
+read once so it sounds like a person, then each paragraph placed on its
+narrated scene. A line that would run into the next scene is reported, never
+sped up.
+
+**Recording a batch.** `demos/plan.json` is the queue — names and one-sentence
+stories, written by whoever has the ideas. A routine never invents one.
+
+```bash
+retake routine run              # everything not done yet
+retake routine run -n 3         # three videos, then stop
+retake routine run --only hero  # re-record one
+```
+
+**Letting it run itself.** Once a routine has a plan and a north star, nobody
+needs to be at the keyboard:
+
+```bash
+retake routine schedule weekdays 09:00   # the next drafted video, every weekday morning
+retake routine schedule                  # what is scheduled, and whether the machine holds it
+retake routine schedule off
+```
+
+Each run brings the app up isolated, records one video, judges it against the
+north star and delivers it only if it matches — then a notification says how
+it went. launchd wakes it on a Mac, cron on Linux; nothing of Retake's stays
+running. A story with no manifest yet waits instead of failing, so an
+undrafted idea never costs a morning.
+
+Each item is stamped, dry-run, recorded as a preview and finished at full
+quality, with progress written to `plan.json` as it goes — so an interrupted
+batch resumes where it stopped, and one broken selector does not cost the other
+four videos. Two failures in a row stops the batch and asks whether the app is
+actually running.
+
+**Two standards, two products.** `retake routine new techtutor-vn`, then
+`retake routine set voice vi-VN-HoaiMyNeural --as techtutor-vn`. The language
+rides on the voice, so there is no second setting that could disagree with the
+first. `retake routine use <name>` switches; `--as <name>` is a one-off.
+
+**What a routine will not do:** turn narration on. That needs a script and a
+person who has heard it — the routine only says which voice reads it, and how
+fast, once somebody has written one.
+
 ## Demo-as-code
 
 ```yaml
@@ -129,7 +316,7 @@ outputs:
   thumbnail: { scene: result }
 ```
 
-The full template is [`demos/example.yaml`](demos/example.yaml); `retake init` copies it into a new workspace.
+On a new workspace, `retake ui` opens the first-demo flow and writes the manifest from your answers.
 
 **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.
 
@@ -163,37 +350,34 @@ Think in the publishing format, not the browser window.
 
 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.
+**Save a login once per site.** When the agent sees the app needs a login, a small form appears in the window: *Sign in to app.example.com*. Type a demo account's username and password; Retake keeps them in your Mac's Keychain (the system keyring on Linux), never in a file the agent can read, and never sends them anywhere. Every demo of that site — in any workspace — signs in with it from then on, and signs in again by itself whenever its session runs out.
 
-**Without the window:** the agent relays one line — run this in your workspace and type the values (hidden):
+**Without the window**, the agent relays one line — run it and type the login (hidden):
 
 ```bash
-retake secret APP_USER APP_PASSWORD
+retake login https://app.example.com
 ```
 
-**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:
+`retake logins` lists the sites with a saved login (names only); `retake login <url> --forget` removes one.
 
-```bash
-retake signin demos/<name>.yaml
-```
+**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.
 
-opens a real browser; you log in by hand, press Enter, and Retake keeps the session (not the password) for every later take.
+**Two-factor.** If the site asks for an authenticator code, choose *It asks for a code* and paste the setup key; Retake computes the current code when it fills the field. SMS codes, SSO, captchas — anything only a person can do — choose *Sign in by hand*: a real browser opens, you sign in, press Done, and Retake keeps the session (not the password). From a terminal: `retake login <url> --by-hand`.
 
 What the agent writes:
 
 ```yaml
 auth:
-  storageState: .auth/myapp.json   # session saved here, reused until stale
-  maxAgeHours: 8
+  storageState: ../.auth/app.example.com.json   # the site's session, reused until stale
   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: fill, selector: "#user", text: "${LOGIN_USER}", secret: true }
+    - { action: fill, selector: "#password", text: "${LOGIN_PASSWORD}", secret: true }
+    - { action: fill, selector: "#code", text: "${TOTP:LOGIN_TOTP}", secret: true }   # only if asked
     - { action: click, selector: "button[type=submit]" }
 ```
 
+A value of the same name in the workspace `.env` still wins, so demos written with `${APP_USER}`-style names and `retake secret` keep working.
+
 `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/action-proof.js

@@ -0,0 +1,66 @@
+export function proofMatches(spec, snapshot) {
+    switch (spec.state) {
+        case "visible": return snapshot.found && snapshot.visible;
+        case "hidden": return !snapshot.found || !snapshot.visible;
+        case "active":
+            return snapshot.found && snapshot.visible && (snapshot.classTokens.some((token) => /(^|[-_])(active|selected|current|checked)([-_]|$)/i.test(token)) ||
+                snapshot.attributes["aria-selected"] === "true" ||
+                snapshot.attributes["aria-pressed"] === "true" ||
+                snapshot.attributes["data-state"] === "active" ||
+                snapshot.checked);
+        case "checked": return snapshot.found && snapshot.checked;
+        case "text": return snapshot.found && snapshot.text.includes(spec.value ?? "");
+        case "attribute": return snapshot.found && snapshot.attributes[spec.attribute ?? ""] === spec.value;
+    }
+}
+export function assessActionProof(spec, before, after) {
+    if (spec.change && proofMatches(spec, before)) {
+        return { ok: false, reason: `proof already satisfied before the action: ${describeProof(spec)}; choose an action that visibly changes state` };
+    }
+    if (!proofMatches(spec, after)) {
+        return { ok: false, reason: `proof not satisfied after the action: ${describeProof(spec)}` };
+    }
+    return { ok: true, reason: "" };
+}
+export async function snapshotActionProof(page, spec) {
+    const locator = page.locator(spec.selector).first();
+    const found = await locator.count().then((count) => count > 0).catch(() => false);
+    if (!found)
+        return emptySnapshot();
+    const visible = await locator.isVisible().catch(() => false);
+    return locator.evaluate((element) => {
+        const input = element;
+        const attributes = {};
+        for (const name of ["aria-selected", "aria-pressed", "data-state"])
+            attributes[name] = element.getAttribute(name);
+        for (const attribute of Array.from(element.attributes))
+            attributes[attribute.name] = attribute.value;
+        return {
+            found: true,
+            visible: true,
+            classTokens: Array.from(element.classList),
+            attributes,
+            text: (element.textContent ?? "").replace(/\s+/g, " ").trim(),
+            checked: "checked" in input ? Boolean(input.checked) : false,
+        };
+    }).then((snapshot) => ({ ...snapshot, visible })).catch(() => ({ ...emptySnapshot(), found, visible }));
+}
+export async function waitForActionProof(page, spec) {
+    const deadline = Date.now() + spec.timeout;
+    let latest = await snapshotActionProof(page, spec);
+    while (!proofMatches(spec, latest) && Date.now() < deadline) {
+        await page.waitForTimeout(100);
+        latest = await snapshotActionProof(page, spec);
+    }
+    return latest;
+}
+export function describeProof(spec) {
+    if (spec.state === "text")
+        return `${spec.selector} contains text ${JSON.stringify(spec.value ?? "")}`;
+    if (spec.state === "attribute")
+        return `${spec.selector} has ${spec.attribute}=${JSON.stringify(spec.value ?? "")}`;
+    return `${spec.selector} is ${spec.state}`;
+}
+function emptySnapshot() {
+    return { found: false, visible: false, classTokens: [], attributes: {}, text: "", checked: false };
+}

package/dist/browser-home.js

@@ -0,0 +1,64 @@
+/** Retake's browser lives in Retake's own folder.
+
+    Playwright keeps one browser cache for every project on the machine, and
+    any project's `playwright install` sweeps out the browsers it decides
+    nobody uses — Retake's included. Recording then stopped with "run npx
+    playwright install", for a reason the person never caused and could not
+    see. So Retake keeps its browser where no other project looks, and fetches
+    it again by itself if it is ever missing.
+
+    Import this module before anything that loads playwright: Playwright reads
+    where its browsers are once, when it loads. An explicit
+    PLAYWRIGHT_BROWSERS_PATH (CI sets one) is left alone. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+function cacheHome() {
+    if (process.platform === "darwin")
+        return path.join(os.homedir(), "Library", "Caches");
+    if (process.platform === "win32")
+        return process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    return process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+}
+export const BROWSERS = process.env.PLAYWRIGHT_BROWSERS_PATH || path.join(cacheHome(), "retake", "browsers");
+process.env.PLAYWRIGHT_BROWSERS_PATH = BROWSERS;
+const require = createRequire(import.meta.url);
+/** The browser Retake's Playwright wants, if it is on disk. */
+export function chromiumPath() {
+    try {
+        const { chromium } = require("playwright");
+        const p = chromium.executablePath();
+        return fs.existsSync(p) ? p : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `npx playwright install chromium`, from wherever playwright actually is. */
+export function installChromium(say = (l) => process.stderr.write(l + "\n")) {
+    let cli;
+    try {
+        cli = path.join(path.dirname(require.resolve("playwright/package.json")), "cli.js");
+    }
+    catch {
+        return false;
+    }
+    say("… downloading Retake's browser (one time, ~150 MB)");
+    const r = spawnSync(process.execPath, [cli, "install", "chromium"], { stdio: ["ignore", "ignore", "inherit"], env: process.env });
+    return r.status === 0;
+}
+const missing = (e) => /Executable doesn't exist|playwright install/i.test(String(e?.message ?? e));
+/** chromium.launch, but a missing browser is fetched once instead of stopping the take. */
+export async function launchChromium(options) {
+    const { chromium } = await import("playwright");
+    try {
+        return await chromium.launch(options);
+    }
+    catch (e) {
+        if (!missing(e) || !installChromium())
+            throw e;
+        return chromium.launch(options);
+    }
+}