versioncam 0.1.1

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "versioncam",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Record demo clips of a real web app: scripted, deterministic, regenerated on deploy.",
+  "license": "FSL-1.1-ALv2",
+  "author": "Peter Bulovec",
+  "homepage": "https://version.cam",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petbul/versioncam.git",
+    "directory": "packages/recorder"
+  },
+  "bugs": "https://github.com/petbul/versioncam-home/issues",
+  "keywords": [
+    "demo",
+    "video",
+    "screen-recording",
+    "playwright",
+    "docs",
+    "ci",
+    "deterministic",
+    "agent-skill"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "versioncam": "bin/versioncam.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./scene": {
+      "types": "./dist/scene.d.ts",
+      "import": "./dist/scene.js"
+    },
+    "./fixtures": {
+      "types": "./dist/fixtures.d.ts",
+      "import": "./dist/fixtures.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "bin",
+    "dsl.md",
+    "plugin",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -b --force tsconfig.json && vite build -c vite.render.config.ts",
+    "test:integration": "env -u NODE_OPTIONS playwright test -c test/playwright.config.ts",
+    "typecheck": "tsc -p tsconfig.render.json"
+  },
+  "dependencies": {
+    "esbuild": "^0.25.0",
+    "playwright": "1.59.1"
+  },
+  "optionalDependencies": {
+    "ffmpeg-static": "^5.2.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.59.1",
+    "@types/node": "^22.10.0",
+    "@types/pngjs": "^6.0.5",
+    "jsdom": "^26.0.0",
+    "pngjs": "^7.0.0",
+    "vite": "^8.0.16"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "versioncam",
+  "description": "Record a short, true demo clip of a web app from one sentence: a skill that sets the repository up on its first run, writes the clip, and has a reviewer pass it from a contact sheet.",
+  "author": {
+    "name": "Peter Bulovec"
+  },
+  "homepage": "https://version.cam",
+  "keywords": ["demo", "recording", "playwright", "screencast"]
+}

package/plugin/README.md

@@ -0,0 +1,105 @@
+# The versioncam skill
+
+`/versioncam "<what the clip should show>"` records a clip of your web app: it
+writes the script, records it, has a reviewer look at the result, and fixes
+what the reviewer finds — until the reviewer passes it or the rounds run out.
+The first time it runs in a repository, it sets the repository up first.
+
+Nothing here calls an API. The model is whichever agent session runs the
+skill, and the vision step is that session's file reader opening a contact
+sheet. Everything is markdown, and you can edit all of it.
+
+## Install
+
+The skill ships inside the `versioncam` npm package:
+
+```bash
+npx versioncam init        # .claude/skills/versioncam/ and .claude/agents/versioncam-reviewer.md
+```
+
+`init` installs the skill and nothing else — no config: the first run writes
+that. It refuses to overwrite a file that is already there, and refuses the
+whole install if any one is; `--force` overwrites. For an agent host that reads
+skills from somewhere other than `.claude/`, `--into <dir>` puts the skill
+directory at `<dir>/versioncam/`, with the reviewer inside it.
+
+Or, without copying anything, load the plugin directory as it is:
+
+```bash
+claude --plugin-dir node_modules/versioncam/plugin
+```
+
+## Run it
+
+```
+/versioncam "Create a shipment for a new recipient and show it appearing in the list"
+/versioncam "Find a shipment by filtering the list" --id 02-find --max-rounds 4
+```
+
+## What it does
+
+**The first run** — no `versioncam.config.ts` in the directory — sets the
+repository up (`skills/versioncam/onboarding.md`): it works out how the app
+starts and where it is served, from `package.json`, the framework's config and
+the README, and asks when there is more than one plausible answer; asks whether
+the app signs in and how you want that handled; writes the config, with a
+`webServer` so every command starts the app itself; runs `doctor` and
+`inspect` to prove the app starts and settles; and records a three-second clip
+twice with `stability`, to prove the app records the same way twice before a
+clip is written for it. Nothing is committed.
+
+**Every run** then (`skills/versioncam/SKILL.md`):
+
+1. `versioncam doctor` — which starts the app — and `inspect /`.
+2. The session writes the clip itself, following
+   `skills/versioncam/authoring.md`: it reads `versioncam dsl` and the existing
+   clips, writes a beat sheet, writes the clip, records it in draft, and runs
+   the deterministic checks in `versioncam review`. Three recordings at most,
+   then on. On a page too big to hold in context, it hands this to a subagent
+   and keeps that subagent for later rounds.
+3. A contact sheet sampled at the beats, and a **fresh reviewer** on it — one
+   picture, a five-item checklist, a JSON verdict. Fresh every round,
+   deliberately: it sees the clip, never the argument for it.
+4. On a pass, a full-quality record and render. Otherwise the fixes the verdict
+   names, and another round.
+
+The reviewer is `agents/versioncam-reviewer.md`, one file used three ways:
+registered as an agent, which is what Claude Code does with it; as the prompt
+of a plain subagent, on a host that cannot register agents; or as a checklist
+the session applies to its own sheet, on a host with no subagents at all. The
+verdict records which, as `"reviewer": "restricted"`, `"unrestricted"` or
+`"self"` — a clip passed by its own author is a weaker claim, and says so.
+
+The skill never runs `git`. The clip it writes lands in your clips directory as
+an ordinary file, for you to read and commit yourself.
+
+## What it leaves behind
+
+```
+.versioncam/author/<id>/
+  beats.json              the beat sheet: { label, expect } per beat
+  summary.json            { id, rounds, passed, wallMs, reviewer }
+  <id>-sheet.png          the final contact sheet
+  round-1/
+    author.md             what the round produced, including what was awkward
+    beats.json
+    verdict.json          the reviewer's JSON, verbatim
+  round-2/ …
+```
+
+`.versioncam/` is a build product and is gitignored. Keep the clip; the
+transcripts are for reading when something goes wrong, and for finding the
+next thing to fix in the recorder — the paragraph on awkward tooling is there
+because the first agent to write one produced a list that became a work
+package.
+
+## What it costs
+
+On the example app, headless, with an earlier two-agent version of this loop:
+one clip took between six and twelve minutes, in one or two rounds, and all six
+intents across two apps passed. Most of the time is model latency rather than
+the recorder: a round is a handful of recordings of a few seconds each, and a
+reviewer's single look at a single picture still takes a minute or two end to
+end. It runs on a subscription rather than a metered key, so the setup cost is
+close to zero; for anything higher-volume the prompts in these files are what
+would move to a direct SDK loop, unchanged.

package/plugin/agents/versioncam-reviewer.md

@@ -0,0 +1,63 @@
+---
+name: versioncam-reviewer
+description: Judges one recorded demo clip from its contact sheet against a fixed five-item checklist and returns a JSON verdict. Spawned fresh for each round by the versioncam skill, with only the sheet path, the beat sheet and the clip id — it never sees how the clip was written.
+tools: Read, Bash(npx versioncam frame *)
+model: sonnet
+effort: low
+maxTurns: 8
+omitClaudeMd: true
+---
+
+You are given one contact sheet: a single PNG of tiles from one clip, in time
+order, left to right then top to bottom. You are also given the clip's beat
+sheet and its id. Read the sheet and say whether the clip is watchable.
+
+## The checklist
+
+1. The cursor starts clear of the controls in the first tile — not hovering a
+   button, a row or a field.
+2. Each beat's expected effect is visible in some tile.
+3. Nothing a beat depends on is cropped by the camera framing.
+4. A caption is present and legible.
+5. The final tile has nothing left open — no dialog, menu or tooltip.
+
+## Rules
+
+- **Judge only what you can see.** The beat sheet says what was intended; it is
+  not evidence that it happened. If a tile does not show it, it did not
+  happen as far as this review is concerned.
+- If a tile is too small to be sure, run `npx versioncam frame <id> <n>` for that
+  frame at full size and read the PNG it prints. That is the only shell
+  command you run.
+- **Tile *n* is not frame *n*.** You are given the frame number behind each
+  tile; pull those. A reviewer that guessed pulled frames 1 to 16 of a clip
+  whose beat fired at frame 29, watched nothing happen, and failed a clip that
+  was fine. If you were not given the numbers, say so in `legibility` and judge
+  from the tiles alone rather than inventing frames to pull.
+- Say which tile each observation comes from.
+- If you genuinely cannot tell after looking at the full-size frame, fail the
+  item and say what you could not make out. Guessing in either direction is
+  worse than saying so.
+
+## Return
+
+Only JSON. No preamble, no commentary around it.
+
+```json
+{
+  "items": [
+    { "item": "cursor starts clear of controls", "pass": true, "note": "tile 1: cursor sits over empty page margin" },
+    { "item": "beat: shipment created", "pass": false, "note": "no tile shows a new row; tiles 4-6 show the spinner" }
+  ],
+  "pass": false,
+  "legibility": "1440x900 downscaled to 8 tiles; body text unreadable, headings and buttons clear",
+  "reviewer": "restricted"
+}
+```
+
+One entry in `items` for each of the five checklist points, plus one for each
+beat in the beat sheet, labelled `beat: <label>`. `pass` at the top level is
+true only when every item passed. `legibility` is one sentence on how much of
+the sheet you could actually read, so the next round knows how much to trust
+this verdict. `reviewer` is always `"restricted"`: it records that the verdict
+came from this file, run as an agent that saw only the sheet.

package/plugin/skills/versioncam/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: versioncam
+description: Record a short demo clip — a screencast, a short video, a GIF of a feature — of this repository's web app from one sentence of what it should show, and iterate until a reviewer passes it from a contact sheet. Use when someone asks to record, film or make a demo of a feature, or to set versioncam up in a repository. Works in any repository with a web app — the first run writes versioncam.config.ts, works out how to start the app, and proves the app records the same way twice before anything is authored.
+user-invocable: true
+argument-hint: "\"<what the clip should show>\" [--id <slug>] [--max-rounds 6]"
+allowed-tools:
+  - Agent
+  - SendMessage
+  - AskUserQuestion
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash(npx versioncam *)
+  - Bash(mkdir *)
+  - Bash(cp *)
+  - Bash(ls *)
+---
+
+# Record a demo clip
+
+`$ARGUMENTS`
+
+You turn one sentence into a clip: a script in this repository that drives the
+running app through its own controls, and a video recorded from it. You write
+the clip; a reviewer who has never seen how it was written looks at a picture
+of it and says whether it shows what it claims; and you go round again until it
+does, or the rounds run out.
+
+Follow these steps in order. Two more files sit beside this one, in this
+skill's directory: `onboarding.md` and `authoring.md`. They are briefs, read
+when a step says to.
+
+## 0. Which phase
+
+First, check versioncam is installed where Node will find it:
+`ls -d node_modules/versioncam`, then the same in each parent directory up to
+the repository root (`../node_modules/versioncam`, …) — a workspace hoists it.
+If none has it, **stop** and say it must be installed first
+(`npm i -D versioncam`, then `npx versioncam install`). Every step below runs
+`npx versioncam`, and `npx` with nothing installed downloads the latest
+published version — not necessarily the one this repository will pin, and
+with no Chromium to record with.
+
+Then: is there a `versioncam.config.ts` (or `.js`, `.mjs`) in the working
+directory?
+
+- **No** → this is the repository's first run. Read `onboarding.md` and do all
+  of it, then continue with step 1.
+- **Yes** → continue with step 1.
+
+## 1. Set up
+
+Parse `$ARGUMENTS`. The first quoted string is the **intent**. `--id <slug>`
+names the clip; without it, derive a slug from the intent — lowercase, hyphens,
+at most 40 characters, cut at a word boundary. `--max-rounds <n>` defaults to 6.
+
+```bash
+mkdir -p .versioncam/author/<id>
+npx versioncam doctor
+```
+
+`doctor` checks the machine and the config, and **starts the app** through the
+config's `webServer` when nothing is serving it, then stops it again. Every
+later command does the same, so you never start a dev server yourself. If the
+app check fails, **stop** and say so: nothing below works without the app, and
+every round would spend a recording discovering that. If another check fails,
+print it and stop too.
+
+Then capture the start page once:
+
+```bash
+npx versioncam inspect /
+```
+
+## 2. Author — this session
+
+Read `authoring.md` now: it is how to write and repair a clip, and it applies
+to you. Then, as it says: `npx versioncam dsl`, the existing clips, `inspect`
+of every page the intent touches; write `.versioncam/author/<id>/beats.json`;
+write the clip; `record --draft`; `review --beats …`; repair — **at most three
+recordings**, then on to the sheet, passed or not.
+
+Write what the round produced to `.versioncam/author/<id>/round-N/author.md` —
+the four things `authoring.md` asks for, including the paragraph on what was
+awkward about the tools. That paragraph is the point of keeping these
+directories; do not summarise it away. Copy `beats.json` beside it.
+
+**Delegation.** If the first `inspect /` printed more than 400 lines, or your
+host makes subagents cheap, hand the authoring to a subagent instead of doing
+it here. Spawn a plain one (general-purpose) whose prompt is the full text of
+`authoring.md`, followed by the intent, the clip id, the clips directory (the
+config's `clips`), the `inspect /` output inline, and the beats path. **Keep the
+agent id it returns**: that id is how you continue the same author in later
+rounds, with `SendMessage`, everything it learned about the page still in its
+context — spawning a new one would start from nothing and repeat the same
+recordings. Save its reply as `round-N/author.md`. You then orchestrate; the
+rest of this file is the same either way.
+
+## 3. The sheet, then a fresh reviewer
+
+```bash
+npx versioncam sheet <id> --at-marks
+```
+
+`--at-marks` samples frame 0, each beat's settle mark, and the last frame,
+instead of eight evenly spaced points — so the tiles the reviewer sees are the
+beats, not whatever happened to fall on an eighth of the duration. It prints
+the sheet's path, then the frame number behind each tile.
+
+The reviewer is given only:
+
+- the sheet path,
+- **the frame numbers `sheet --at-marks` just printed**, in order, one per tile,
+- the contents of `.versioncam/author/<id>/beats.json`,
+- the clip id (so it can call `npx versioncam frame <id> <n>` — from this
+  directory, which you name if a subagent on your host starts somewhere else).
+
+The frame numbers are not optional. A reviewer given only the id assumed tile
+*n* was frame *n*, pulled frames 1 to 16 — every one of them before the beat
+fired at frame 29 — and reported that the clip never filtered anything. It was
+looking at the right clip and the wrong seconds. `sheet` prints the list for
+exactly this reason; pass it on verbatim.
+
+The reviewer's brief is `versioncam-reviewer.md`: in `agents/` two levels up
+from this skill's directory when the skill came from the plugin, in
+`.claude/agents/` when `versioncam init` installed it, and beside this file
+when it was installed with `--into`. Take the first rung of this ladder your
+host allows:
+
+1. **Registered.** If an agent named `versioncam-reviewer` is available — it is
+   `versioncam:versioncam-reviewer` when it came with the plugin — spawn it
+   with those inputs. It is blind by construction: a fresh context holding the
+   sheet and the beats and nothing of how the clip was made. Its JSON says
+   `"reviewer": "restricted"`.
+2. **A plain subagent.** Otherwise, spawn a general-purpose subagent whose
+   prompt is the full text of `versioncam-reviewer.md` followed by those
+   inputs. It is blind by instruction rather than by construction. Its JSON
+   will still say `"restricted"`, because the file it was given says so; save
+   it with `"reviewer": "unrestricted"`, which is what it was.
+3. **No subagents.** Otherwise, read `versioncam-reviewer.md` and judge the
+   sheet yourself, in a step of its own — *before* you look at your beats or
+   your clip again, with only the four inputs in front of you — and save the
+   verdict with `"reviewer": "self"`. The summary says so: a clip passed by its
+   own author is a weaker claim, and whoever reads it should know.
+
+A fresh reviewer every round is the point, not an accident. It must not see
+the author's reasoning, an earlier verdict, or how hard the clip was to get
+working — only this round's picture. Never continue a reviewer, and never pass
+it the author's report.
+
+Save its JSON verbatim, with `reviewer` as above, as
+`.versioncam/author/<id>/round-N/verdict.json`.
+
+### If you think the verdict is wrong
+
+You will sometimes believe a reviewer has erred, and sometimes you will be
+right. **Do not override it.** Overriding is the one move that undoes the
+design: a fresh reviewer is trusted precisely because it has not watched the
+clip being built, and a session that has watched three rounds is the least
+independent judge available.
+
+Get **one** second opinion, from a fresh reviewer on the same rung — same
+sheet, same beats, same frame numbers, and nothing about the first verdict or
+what you think it got wrong. Save it as `round-N/verdict-2.json`. That verdict
+stands, whichever way it goes. If it agrees with the first, the clip has failed
+and the round continues; if it disagrees, take it and move on, and keep both
+files so the disagreement is on the record.
+
+One second opinion, once per round. Two reviewers who disagree is information.
+A third is shopping for the answer you wanted.
+
+## 4. If the verdict passes
+
+Take the real recording and render it:
+
+```bash
+npx versioncam record <id>
+npx versioncam render <id>
+npx versioncam sheet <id> --at-marks
+```
+
+Copy that final sheet into `.versioncam/author/<id>/`. Write
+`.versioncam/author/<id>/summary.json`:
+
+```json
+{ "id": "<id>", "rounds": 2, "passed": true, "wallMs": 812000, "reviewer": "restricted" }
+```
+
+`reviewer` is the rung the passing verdict came from. `wallMs` only if you can
+measure it — leave it out rather than guess; a harness running you measures it
+from outside. After a first run that found the app unstable, add
+`"stable": false`.
+
+Name the clip file and the rendered video, and stop.
+
+## 5. If this was the last round
+
+If the verdict failed and `N == max-rounds`, write `summary.json` with
+`"passed": false` and the last verdict inline. Say which items failed, and
+stop; in a headless run, say plainly in your final message that it failed.
+
+Do not quietly raise `max-rounds`. A clip that has not converged in six rounds
+is a finding about the intent or the tools, and it is worth more written down
+than ground out.
+
+## 6. Otherwise — fix it, and go round again
+
+Fix what the verdict names — the items that failed, read as written — and
+nothing it did not name. When the authoring is delegated, send the author the
+verdict JSON **verbatim** with `SendMessage`, by the id you kept — not
+summarised, not reordered, not softened — and the instruction: fix the failing
+items, re-record in draft, run `npx versioncam review`, and return. Add no
+opinion of your own: the reviewer has looked at the clip in a way you have
+not, and the author trusts the verdict because it is a reviewer's and not a
+relayed impression.
+
+Re-record in draft, run `review`, make `.versioncam/author/<id>/round-N/` for
+the new round with its `author.md` and `beats.json`, and go back to step 3.
+
+## What this leaves behind
+
+```
+.versioncam/author/<id>/
+  beats.json
+  summary.json              { id, rounds, passed, wallMs?, reviewer }
+  <id>-sheet.png            the final sheet
+  round-1/  author.md  beats.json  verdict.json  (verdict-2.json)
+  round-2/  …
+```
+
+`.versioncam/` is gitignored — a build product, none of it to be committed. The
+clip is not: it lives in the clips directory and is the thing worth reading and
+keeping. You commit nothing; that is the person's call.