versioncam 0.1.1

package/plugin/skills/versioncam/authoring.md

@@ -0,0 +1,226 @@
+# Writing and repairing a clip
+
+You write one clip of a running web app and get it recording cleanly. The
+clip is a TypeScript file in the app's repository that drives the shipped UI
+through its own controls. Someone else decides whether it is a good demo; your
+job is that it runs, it satisfies the intent, and a person watching it can see
+each thing it claims to show.
+
+You have: the intent, the clip id, the clips directory, and the output of
+`npx versioncam inspect /` for the start page — whether you are the session
+running the skill or a subagent it handed this brief to. Work from the
+directory that holds `versioncam.config.ts`.
+
+## Look before you write
+
+Three things, in this order, before the first line of the clip:
+
+1. **`npx versioncam dsl`.** The whole authoring surface, held to the code by
+   a test — the only list of methods worth trusting. Prose about this DSL has
+   been wrong before, and a clip written against a method that did not exist
+   quietly did something else for months. If a method is not in that output,
+   it does not exist, however plausible it sounds.
+2. **The existing clips in the clips directory.** Read them. They are the
+   house style, and they show which patterns survive contact with this app —
+   how long a spinner is held, when the camera moves, what a caption says.
+3. **`npx versioncam inspect <path>`** for every page the intent touches
+   beyond the start page. If the intent names a screen you have not
+   inspected, navigate to it and inspect it before scripting anything there.
+
+Do not read the app's source to find a control. Clips written from source
+reach for things that are conditional, renamed, or not rendered at all;
+`inspect` reports what is actually on the page and what it is called. The
+bracket after each name says where the name came from, which is which
+locator finds it: `[aria-label]` and `[label]` are what `byLabel` finds,
+`[placeholder]` is what `byPlaceholder` finds, `[text]` is a control's own
+words — `byRole("button", { name })` — and `[name]` or `[none]` means use the
+test id. Use `npx versioncam measure <path> <css>` when you need to know where
+matches are.
+
+`measure` prints what each match says, too. **Read a status line before
+promising it in a beat**: `npx versioncam measure / '[data-testid="status"]'`
+answers `text="12 shipments"` and where it sits — including when that is
+below the fold, where no frame will show it.
+
+## Rules
+
+- **Target by test id or role, never by coordinates.** `s.byTestId(…)`,
+  `s.byRole(…)`, `s.byLabel(…)`. A clip built from locators survives a layout
+  change; one built from pixels is broken by the next padding tweak and does
+  not say so. Geometry belongs only inside a stroke authored as fractions of a
+  target's own box.
+- **Nine to eleven seconds**, unless `review` in the config says otherwise —
+  `versioncam review` enforces whatever it says. Shorter reads as a fragment,
+  longer loses the viewer. Adjust holds to hit it; never drop a beat to save
+  time.
+- **A caption.** A clip with no caption fails review. One caption, unless the
+  beats genuinely change subject — and if you write a second, look at the
+  contact sheet, because two captions on screen at once is the failure that
+  hides best.
+- **Every beat ends in `await s.settle({ label })`, then a `hold`.** The
+  settle advances the page's clock without capturing, so the app's own waiting
+  never reaches the video. The hold after it is what makes the result
+  *visible*: settle by itself moves straight on to the next action and the
+  thing you waited for flashes past in one frame.
+- **A camera, highlight or caption write costs no time.** It writes to a track
+  at the current instant, and only the frames captured after it show the
+  result. So anything you write needs frames after it or it never renders. The
+  usual victim is a `s.camera.reset()` on the last line: the reset is in the
+  timeline, no frame follows it, and the video ends zoomed in. Give it a hold.
+- **A canvas, a WebGL map or a video needs `forceCaptureEvery: 1`.** The
+  recorder skips the screenshot when nothing observable changed, and what it
+  watches is the DOM, the element under the cursor and the running animations
+  — none of which a surface that redraws itself ever touches. The symptom is
+  what you will see on the contact sheet: the map, the chart or the video is
+  *identical* in every tile while the cursor and the caption move normally,
+  and nothing in the `record` or `review` output mentions it, because as far
+  as either is concerned nothing changed. If the subject of the clip is such a
+  surface, say so in the clip's options and pay full price:
+  `clip("<id>", { title: "…", capture: { forceCaptureEvery: 1 } }, …)`.
+- **End with nothing open.** No dialog, no menu, no tooltip, no focused
+  dropdown, and the cursor clear of whatever the last frame is about.
+- **Start the cursor clear of the controls.** Where it rests in frame 0 is
+  `cursorStart` in the config, fixed before a clip's first line runs; the
+  default was tuned for one app and lands on a row or a field in others. Look
+  at frame 0 (`npx versioncam frame <id> 0`) before the sheet does; if the
+  cursor sits on a control, the fix is `cursorStart` — the one change to the
+  config allowed below.
+- **If `open()` lands on a sign-in screen, stop.** Say so and go no further.
+  Signing the recorder in is the repository owner's job, through `auth` in
+  `versioncam.config.ts`, and `versioncam login` is interactive so you cannot
+  run it. Do not type credentials, do not go looking for any in the repository
+  or the environment, and do not script a way around the screen. A clip that
+  signs itself in is a clip nobody can run.
+- **Do not run `git`.** You do not need it. Someone else reads your work and
+  commits it.
+- **Do not edit the app, and leave `versioncam.config.ts` alone — with one
+  exception.** The app is not yours to change, and the config is every
+  clip's: a setting changed to make this clip pass changes all the others. The
+  exception is `cursorStart`, when a reviewer fails the cursor in the first
+  frame — frame 0 is taken before a clip's first line runs, so nothing in the
+  clip can move it, and the config is the only fix. Change it between
+  recordings, never during one (a save the dev server sees reloads the page
+  being recorded), and say so in what you write down.
+
+## The shape of a clip
+
+Whenever the clips directory has clips in it, they are better models than this
+— they are the ones that already work against this app. This is the minimum,
+for a repository whose first clip you are writing:
+
+```ts
+import { clip } from "versioncam";
+
+export default clip(
+  "<id>",
+  { title: "<a short title>", seed: 11 },
+  async (s) => {
+    await s.open("/");
+    s.caption("<what this clip shows>");
+    await s.hold(400);
+
+    await s.click(s.byTestId("<control>"));
+    await s.settle({ label: "<beat label>" });
+    await s.hold(700);
+  },
+);
+```
+
+`seed` fixes the motion, so two runs of the clip produce the same frames. Pick
+one and leave it alone.
+
+## Write the beat sheet before you record
+
+`.versioncam/author/<id>/beats.json`, an array of `{ label, expect }`:
+
+```json
+[
+  { "label": "shipment created", "expect": "a new row for Mira Halloran at the top of the shipment list" },
+  { "label": "cancelled", "expect": "the list status line reads one fewer shipment" }
+]
+```
+
+`label` is exactly the string you pass to `settle({ label })` — `versioncam
+review` matches them and fails on any beat with no mark. `expect` is one
+sentence about what a person should *see* once the beat has landed, not what
+the code did — and if it quotes the screen, it quotes what `measure` read.
+
+Write it before the first recording. Written afterwards it describes what you
+got instead of what you meant, which is precisely the check it exists to be.
+
+## The round
+
+```
+inspect → write the clip → npx versioncam record --draft <id>
+        → npx versioncam review <id> --beats .versioncam/author/<id>/beats.json
+        → fix → record again
+```
+
+The clip goes in the clips directory as `<id>.clip.ts`, and the id inside
+`clip("<id>", …)` must match the id you were given — that is what `record`
+looks up.
+
+Record in `--draft` while you are working. It is the same page at the same
+viewport, captured cheaply, and it is what the loop is for; the full recording
+is taken once the reviewer passes the clip.
+
+When `record --draft` fails it names the step, the locator and the frame, and
+writes `failure.png` and `failure.json` into the recording directory. **Read
+`failure.png`.** One look at the moment it gave up is almost always faster
+than reasoning about the DOM from the message. To look at a beat that did
+record, `npx versioncam frame <id> --at "<label>"` renders the frame the
+contact sheet will show for it.
+
+**At most three `record` calls, then the sheet, whether or not review has
+passed.** If the third has not passed review, stop there and write down which
+check still fails, what you tried, and what you think is in the way. A fourth
+attempt on a stuck clip has not helped in this loop. The round after this one
+arrives with a picture of the clip and a reviewer's verdict, which is
+information you do not have.
+
+In a later round you have that verdict. Fix what it names — the items that
+failed, read as written — and nothing else; then record again, in draft, and
+run `review`.
+
+## Failure → repair
+
+Every row of this happened while the recorder was being built, and two of them
+happened again the first time an agent used it.
+
+| Failure | Repair |
+|---|---|
+| locator not found at step N | `inspect` at that moment; pick a control that exists; if none does, the beat is wrong |
+| beat produced no new state | missing `settle`, wrong target, or effect off-screen; check cuts and states |
+| settle timed out on `X` | add a `ready` hook, raise the timeout, or the source is live — record a HAR |
+| document reloaded mid-clip | something navigated; find the trigger and avoid it |
+| drag or lasso selected nothing | `measure`, re-author geometry as fractions of the real box |
+| duration drift | adjust holds, never the beats |
+| tooltip / menu open in a frame it should not be | move the cursor start; add a hold before the next action |
+
+Two more, from the tools rather than the app:
+
+| Failure | Repair |
+|---|---|
+| a locator "matched N elements" | the text appears in more than one place — use `byRole` with a name, or a test id |
+| review warns that a track never rendered | you wrote a camera, highlight or caption with no frames after it; add a hold |
+
+## What you write down
+
+Four things, at the end of every round — in `round-N/author.md`, or as your
+reply if you are a subagent — and the fourth matters as much as the rest:
+
+1. The path of the clip file you wrote.
+2. The path of `beats.json`.
+3. The last `versioncam record` summary line, verbatim, and the
+   `versioncam review` verdict.
+4. **One paragraph on what was awkward about the tools.** Where a message
+   misled you, where you had to guess, what you looked for and could not find,
+   what took three attempts that should have taken one. Be blunt and specific;
+   naming the command and what you expected is worth more than a judgement
+   about it. This paragraph is kept and read — it is how the next fix to the
+   recorder gets found, and the last agent to write one produced the list that
+   became a work package.
+
+If you stopped without passing review, say so plainly in the first line. A
+failure that names the obstacle is useful. A claim that it passed when it did
+not wastes a whole round.

package/plugin/skills/versioncam/onboarding.md

@@ -0,0 +1,199 @@
+# The first run: setting a repository up
+
+There is no `versioncam.config.ts` here, so before any clip can be written the
+repository has to be taught three things: how its app starts, whether it signs
+in, and what "the page is done" means. Then one question has to be answered
+before anything is authored: **does this app record the same way twice?** A
+clip is only as deterministic as the app it films, and one written against an
+app that is not fails CI for reasons nobody wrote.
+
+You do not run the app yourself — not with `npm run dev`, not in the
+background, not ever in this phase. You write what you learn into the config,
+and `versioncam` starts the app from it, every time, and stops it again. If
+you find yourself wanting to start a server by hand, the config is wrong;
+fix the config.
+
+Work in the directory the skill was run from; the config goes here. If there
+is no config here but `Glob` finds a `versioncam.config.*` further down, stop
+and say to run the skill from that directory instead: every `versioncam`
+command reads the config from the directory it runs in, and a second config
+would split the repository in two.
+
+## 1. How the app runs
+
+Look, in this order, and stop when the answer is clear:
+
+- `package.json` `scripts` — `dev`, then `start`, then `serve`. A script's own
+  `--port` flag is the port. In a monorepo, the package whose scripts start
+  the web app, which may be a directory below this one.
+- The framework's config for the port — `vite.config.*` (`server.port`),
+  `next.config.*`, `angular.json`, `astro.config.*` — and, if it says nothing,
+  the framework's default: Vite and SvelteKit 5173, Next and Remix 3000,
+  Astro 4321, Angular 4200.
+- `Makefile`, `Procfile`, `docker-compose.yml`, and the README's
+  getting-started section, for anything that needs more than one process.
+
+From that, the config's `baseUrl` and `webServer`:
+
+```ts
+baseUrl: "http://localhost:<port>",
+webServer: { command: "<the command a person would type>", url: "http://localhost:<port>" },
+```
+
+`command` runs through a shell from the config's directory; add `cwd` when it
+has to run from somewhere else (`cwd: "../.."` for a repository root two levels
+up). A stack of several services started by one command — a `make start`, a
+`docker compose up` — needs `url` pointed at the service that is ready *last*,
+usually a backend's health endpoint, not at the page: a dev server answers
+seconds before the API behind it, and a clip that opens then meets a sign-in
+form with nothing to sign in to. Give such a stack `timeoutMs: 180_000`.
+
+**If the port comes from an environment variable, or there are several
+plausible commands, ask** — with `AskUserQuestion`, listing the candidates
+you found and what each would start. If nothing plausible turned up, ask what
+starts the app. If you cannot ask (no one is there: the question tool is not
+available or errors), take the most specific candidate, and say in your final
+report which one you took and why.
+
+**Never read a value out of any `.env` file.** A port, a URL, a key: if it is
+only in a `.env`, it is a question for the person, not a file for you to open.
+
+## 2. Whether it signs in
+
+Look for sign-in routes, a login component, a redirect on `/` in the router.
+Step 5 below will show it for certain — `inspect /` of an app behind a
+sign-in lists a login form — so this is a first look, not the verdict.
+
+If it does sign in, the choice is the person's, asked once:
+
+- **`versioncam login`** — a browser opens, they sign in the way they always
+  do, and the session is saved to a file that stays out of git. The right
+  default when a person is there. Config: `auth: { storageState:
+  ".versioncam/auth.json" }`, and they run `npx versioncam login` themselves;
+  you cannot, because it waits for them.
+- **A `login` hook** reading named variables from `.env.recording` — the right
+  one for CI. You write the hook with the variable *names*
+  (`process.env.RECORDING_USER`, say); they put the values in
+  `.env.recording`, which is gitignored.
+
+Never write a secret anywhere — not into the config, not into a clip, not into
+your report — and never go looking for one. With no one to ask, stop here and
+say what the person needs to do: nothing below works on a sign-in screen.
+
+## 3. Write the config
+
+`versioncam.config.ts` in this directory, with only what the app needs:
+
+```ts
+import { defineRecorder } from "versioncam";
+
+export default defineRecorder({
+  baseUrl: "http://localhost:5173",
+  webServer: { command: "npm run dev", url: "http://localhost:5173" },
+  viewport: { width: 1440, height: 900 },
+  clips: "demos/clips/**/*.clip.ts",
+});
+```
+
+Plus `auth` if step 2 said so, and `cursorStart` if step 7 says so. Not
+`settle`, not `review`, not `theme`: every default is there because it is right
+for most apps, and a field nobody needed is a question the next person has to
+answer. Say in a comment above each field you did write why it has the value
+it has — the port came from the dev script, the command from the README.
+
+Then: create `demos/clips/`, and make sure `.versioncam/` is ignored —
+recordings, renders and a saved sign-in go there. If a `.gitignore` here, or
+in a directory above this one up to the repository root, already says so,
+leave it; otherwise add the line to the nearest one, creating one here if
+there is none, and leave the rest of the file alone.
+
+## 4. `npx versioncam doctor`
+
+It checks the machine, loads the config, and starts the app through
+`webServer` exactly as every later command will, then stops it. **It must
+pass.** If the app check fails, the reason is in its last lines and in
+`.versioncam/webserver.log`: the wrong command, the wrong port, a port already
+taken. Fix the config and run it again. Do not go on until it passes.
+
+## 5. `npx versioncam inspect /`
+
+What is on the start page, as a clip will see it. Three things to look for:
+
+- **A sign-in form.** Step 2 was wrong; go back to it.
+- **A loading screen, or a warning that a settle timed out.** The app needs
+  `settle.ready`: a function that says when the page is really done. Find what
+  "loaded" means here — a map's `loaded()`, a canvas that has drawn, a
+  spinner's test id gone — add it to the config, and inspect again.
+- **An empty page.** The app may need a path other than `/`, or data it does
+  not have; say so.
+
+## 6. Stability
+
+Write `demos/clips/00-open.clip.ts` — open the start page, one caption, hold
+three seconds:
+
+```ts
+import { clip } from "versioncam";
+
+export default clip("00-open", { title: "The app opens", seed: 1 }, async (s) => {
+  await s.open("/");
+  s.caption("<the app's name>");
+  await s.hold(3000);
+});
+```
+
+Then:
+
+```bash
+npx versioncam stability 00-open
+```
+
+It records the clip twice and compares every frame. `stable` is the answer
+that lets you go on. `unstable` prints the first frame that differs and saves
+the two pictures behind it; **read both** and say what differs.
+
+What you may fix, in the config:
+
+- Something still animating in when the clip starts — a fade, a skeleton
+  screen: a `settle.ready` that waits for it to finish.
+- Time rendered from the server rather than the page: the page's own clock is
+  already fixed (`clock.time`), so a timestamp that still moves came from an
+  API, and that is the next item.
+
+What you may not: **live data** — a feed, a count that changes, a model's
+answer. That needs recorded network replay, which versioncam does not have
+yet. Say so, and ask whether to go on regardless.
+
+**Never author on an unstable app without saying so** — in the report now,
+and in `summary.json` at the end, as `"stable": false`. A clip written against
+an app that does not reproduce will fail CI, and whoever reads the failure
+deserves to know it was known.
+
+## 7. The first frame
+
+```bash
+npx versioncam record --draft 00-open
+npx versioncam frame 00-open 0
+```
+
+Look at where the cursor is. Every clip starts it there, and it is taken
+before a clip's first line runs, so no clip can move it. The default,
+`(0.72, 0.28)` of the viewport, was picked for one app's open map and lands on
+a list row or a field in others — and a reviewer fails a clip whose first
+frame has the cursor on a control, a row or a field. If it is on one, set
+`cursorStart` in the config to open space — a margin, the gap below a panel —
+as fractions of the viewport, with a comment saying what is there, and look
+at frame 0 again.
+
+## 8. Report
+
+Before going on to the clip, say — in a few lines:
+
+- what you found (the command, the port, and where each came from);
+- what you asked, and what the answer was — or what you assumed and why;
+- that `stability` passed on `00-open`, or what differed;
+- the files you created or changed — the config, `demos/clips/00-open.clip.ts`,
+  `.gitignore` — and that **nothing was committed**: reviewing and committing
+  them is the person's job.
+
+Then go back to the skill and continue with the clip.