state-scenarios-cli 0.5.0 → 0.7.0

package/skills/scenario-coverage-loop/references/workflow.yml

@@ -0,0 +1,232 @@
+# Scenario coverage loop: sense -> select -> capture -> check -> one PR.
+# Replace every <placeholder>. Shown with Claude Code and npm; swap in the repo's agent and package manager.
+#
+# Three jobs, so the checks are a boundary and not the agent's word for it:
+#   agent    read-only token. Runs the agent; hands over a patch, never a push.
+#   verify   read-only token, fresh runner. Refuses a patch outside the scenarios folder and the map,
+#            then checks it with the default branch's own install and code: nothing the agent wrote runs.
+#   open-pr  the only job with write access. Applies the checked patch and opens the PR.
+
+name: "Agent: scenario coverage"
+
+on:
+  schedule:
+    - cron: "0 7 * * 1" # Mondays 07:00 UTC
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: scenario-coverage
+  cancel-in-progress: false
+
+env:
+  SCENARIOS: <src/scenarios>
+  MAP: <.agents/skills/scenarios-app>
+  BASE_URL: <http://localhost:5173>
+  BATCH: 3
+  LABEL: scenario-coverage
+
+jobs:
+  agent:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      work: ${{ steps.patch.outputs.work }}
+    steps:
+      # Flow control: scheduled runs wait until the last loop PR is merged or closed.
+      - name: One open loop PR at a time
+        id: gate
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          OPEN=$(gh pr list --repo "$GITHUB_REPOSITORY" --state open --label "$LABEL" --json number --jq length)
+          if [ "${{ github.event_name }}" = schedule ] && [ "$OPEN" -gt 0 ]; then
+            echo "run=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/checkout@v5
+        if: steps.gate.outputs.run == 'true'
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v5
+        if: steps.gate.outputs.run == 'true'
+        with:
+          node-version: 24
+
+      - name: Install
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          <npm ci>
+          npx playwright install --with-deps chromium
+
+      - name: Sensor
+        if: steps.gate.outputs.run == 'true'
+        run: npx state-scenarios coverage "$SCENARIOS" --json > /tmp/coverage.json
+
+      - name: Controller
+        id: select
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          node scripts/scenario-coverage-next.mjs /tmp/coverage.json "$BATCH" > /tmp/selected.md
+          if [ -s /tmp/selected.md ]; then echo "work=true" >> "$GITHUB_OUTPUT"; else echo "Nothing missing."; fi
+
+      - name: Start the app
+        if: steps.select.outputs.work == 'true'
+        run: |
+          <npm run dev> > /tmp/dev.log 2>&1 &
+          for i in $(seq 60); do curl -sf "$BASE_URL" > /dev/null && exit 0; sleep 2; done
+          cat /tmp/dev.log; exit 1
+
+      - name: Actuator
+        if: steps.select.outputs.work == 'true'
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          set -o pipefail
+          PROMPT="$(cat .github/agent-prompts/scenario-coverage.md)"
+          PROMPT="${PROMPT/\$SELECTED/$(cat /tmp/selected.md)}"
+          PROMPT="${PROMPT/\$MEMORY/$(cat .github/agent-memory/scenario-coverage.md)}"
+
+          # An explicit tool list rather than a permission bypass. It isn't a sandbox: --rules and
+          # --steps load JavaScript, and the agent can write files, so it can run code here. That's
+          # why this job holds no write token and the verify job decides what's kept.
+          npx -y @anthropic-ai/claude-code -p "$PROMPT" \
+            --mcp-config .mcp.json \
+            --permission-mode acceptEdits \
+            --allowedTools "Read,Edit,Write,Glob,Grep,mcp__state-scenarios,Bash(npx state-scenarios validate:*),Bash(npx state-scenarios coverage:*),Bash(npx state-scenarios list:*),Bash(npx state-scenarios shoot:*),Bash(git status:*),Bash(git diff:*)" \
+            --max-turns 80 \
+            --output-format stream-json --verbose \
+            2>&1 | tee /tmp/agent.jsonl
+
+          grep '^{' /tmp/agent.jsonl \
+            | jq -rs '[.[] | select(.type == "assistant")] | last | .message.content[] | select(.type == "text") | .text' \
+            > /tmp/pr-body.md
+
+      - name: Hand over a patch
+        id: patch
+        if: steps.select.outputs.work == 'true'
+        run: |
+          mkdir -p /tmp/handover
+          git add -A
+          git diff --cached --binary HEAD > /tmp/handover/change.patch
+          cp /tmp/pr-body.md /tmp/handover/pr-body.md
+          if [ -s /tmp/handover/change.patch ]; then echo "work=true" >> "$GITHUB_OUTPUT"; else echo "The agent changed nothing."; fi
+
+      - uses: actions/upload-artifact@v4
+        if: steps.patch.outputs.work == 'true'
+        with:
+          name: handover
+          path: /tmp/handover
+
+      - name: Keep the agent's log
+        if: always() && steps.select.outputs.work == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: agent-log
+          path: |
+            /tmp/agent.jsonl
+            /tmp/dev.log
+
+  verify:
+    needs: agent
+    if: needs.agent.outputs.work == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: handover
+          path: /tmp/handover
+
+      # Only data may change: scenario JSON and the map's Markdown. No symlinks, no "..",
+      # nothing else, so the install and dev server below are the default branch's own.
+      - name: The patch stays in scope
+        run: |
+          set -euo pipefail
+          PATCH=/tmp/handover/change.patch
+          git apply --check "$PATCH"
+          if git apply --summary "$PATCH" | grep -Eq 'mode 120000|rename|copy'; then
+            echo "::error::The patch adds a symlink, rename or copy."; exit 1
+          fi
+          BAD=0
+          while IFS= read -r path; do
+            case "$path" in
+              *..*) BAD=1 ;;
+              "$SCENARIOS"/*.json | "$MAP"/*.md) ;;
+              *) BAD=1 ;;
+            esac
+            [ "$BAD" = 1 ] && { echo "::error::Out of scope: $path"; exit 1; }
+          done < <(git apply --numstat "$PATCH" | cut -f3-)
+          git apply "$PATCH"
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+
+      - name: Install
+        run: |
+          <npm ci>
+          npx playwright install --with-deps chromium
+
+      - name: Scenarios parse and the map names only real ones
+        run: |
+          npx state-scenarios validate "$SCENARIOS"
+          npx state-scenarios coverage "$SCENARIOS"
+
+      - name: Start the app
+        run: |
+          <npm run dev> > /tmp/dev.log 2>&1 &
+          for i in $(seq 60); do curl -sf "$BASE_URL" > /dev/null && exit 0; sleep 2; done
+          cat /tmp/dev.log; exit 1
+
+      - name: Every state renders, the new ones included
+        run: npx state-scenarios shoot "$SCENARIOS" --base-url "$BASE_URL" --out /tmp/shots
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: shots
+          path: /tmp/shots
+
+  open-pr:
+    needs: verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: handover
+          path: /tmp/handover
+
+      # Nothing runs here but git and gh, on a patch verify already accepted.
+      - name: Open the PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          BRANCH="agent/scenario-coverage-$GITHUB_RUN_ID"
+          git switch -c "$BRANCH"
+          git apply --index /tmp/handover/change.patch
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "scenarios: fill coverage gaps"
+          git push --set-upstream origin "$BRANCH"
+          gh label create "$LABEL" --color 0E8A16 --description "Scenario coverage loop" 2>/dev/null || true
+          gh pr create --head "$BRANCH" --title "Scenarios: fill coverage gaps ($(date +%F))" \
+            --body-file /tmp/handover/pr-body.md --label "$LABEL"

package/skills/scenario-pr/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: scenario-pr
+description: >
+  Write or update a pull request description that shows the UI change: before and after
+  screenshots of every state the branch touches, taken with state-scenarios, published to the PR,
+  plus a short outline of the code's shape. Use for /scenario-pr, or when asked to describe a UI
+  PR "with screenshots", "show the before and after", or "make the PR visual".
+disable-model-invocation: true
+---
+
+# Describe a UI pull request with its real states
+
+A reviewer of a UI change needs to see it. This skill finds the states the branch touches, shoots
+them before and after, publishes the images, and writes a short PR body around them. Write as one
+person to another: plain words, no jargon, nothing a screenshot already says.
+
+For the images alone on every PR, without an agent, the repository's GitHub Action
+`jagreehal/state-scenarios/actions/pr-screenshots` posts them as a comment (see the README). This
+skill adds the written description around them.
+
+The `state-scenarios` skill is the reference for the library; its topic `verify` covers every
+command used here. Read it first (`npx state-scenarios guide verify`).
+
+## 1. Find the PR and the base
+
+```bash
+gh pr view --json number,url,baseRefName,headRefName,title 2>/dev/null
+```
+
+No PR yet: check `git status --short --branch` and the branch's commits. Commit work that belongs
+to the task, push the branch, and `gh pr create --draft --fill`. Ask the user only when the branch
+holds no relevant work.
+
+Done when: you have the PR number and its base branch.
+
+## 2. Understand the change
+
+Read the full diff (`gh pr diff`) and enough of the code around it to explain what changed and why.
+Read the ticket or task notes if they are linked.
+
+Done when: you can say in one sentence why the change exists.
+
+## 3. Pick the states
+
+```bash
+npx state-scenarios affected <dir> --base origin/<base> --src <app folders>
+```
+
+Treat the list as a starting point. Keep states the diff really changes; drop route or endpoint
+matches the diff can't reach. When a shared file changed (layout, theme, global CSS), add the
+main states of each feature, or all of them if there are few. Add loading, empty and error for
+any feature the change touches. A change no scenario covers is worth saying in the PR; capturing
+the state (topic `capture`) is better still.
+
+Done when: you have the list of scenario names, each with a reason you could defend.
+
+## 4. Shoot before and after
+
+The dev server must be running (the project's scenario map skill, `scenarios-<app>`, says how).
+
+1. Before: put the base's code in front of the dev server, e.g. `git switch --detach origin/<base>`
+   with a clean tree (or a worktree of the base on another port). Shoot the listed states that
+   exist on the base, with the same options you'll use after:
+   `npx state-scenarios shoot <dir> --base-url <url> --only <names> --out .shots/before`
+2. After: switch back to the branch, let the dev server reload, then
+   `npx state-scenarios shoot <dir> --base-url <url> --only <names> --out .shots/after --compare .shots/before`
+
+Look at every `.diff.png` and every `new` state. Tell the user about any diff the change didn't
+intend before writing the PR. A scenario that fails (`✗`) needs fixing first; read its
+`.md` page.
+
+When the change is about an interaction (a flow, an animation, focus), record it too:
+`npx state-scenarios record <dir> --base-url <url> --steps <file> --only <name> --format gif --width 900`
+(topic `media`). GitHub plays GIFs inline; it doesn't play linked MP4s.
+
+Done when: `.shots/after` holds a diff for each changed state, a PNG for each new one, and you
+have looked at all of them.
+
+## 5. Publish the images
+
+If the repository is public, the images will be public: check them for real names, emails, tokens
+or internal URLs first, and ask the user before the first publish.
+
+```bash
+npx state-scenarios publish .shots/after/*.diff.png <new states' PNGs> <GIFs> --folder pr-<number>
+```
+
+It pushes to the `scenario-shots` branch without touching the checkout and prints one Markdown
+image line per file. Publishing the same folder again replaces it.
+
+Done when: you have an image line for each picture the PR body will show.
+
+## 6. Write and save the description
+
+Read [references/pr-template.md](references/pr-template.md) and follow it. Save the body to
+`.shots/pr-body.md`, then:
+
+```bash
+gh pr edit <number> --body-file .shots/pr-body.md
+```
+
+Done when: `gh pr view <number>` shows the new body with its images.
+
+## 7. Report
+
+Tell the user, in a few lines: the PR URL, the states shown (changed, new, unchanged), anything
+that looked wrong in the screenshots, and states the change touches that have no scenario.
+
+## Rules
+
+- Show only states the change touches. Unchanged states go in one line, not in pictures.
+- Never publish a screenshot you haven't looked at.
+- Keep `.shots/` out of commits (add it to `.gitignore` if it isn't).
+- Don't restate the diff in prose. The outline shows shape; the screenshots show the result.

package/skills/scenario-pr/references/pr-template.md

@@ -0,0 +1,61 @@
+# PR description template
+
+Fill this in. Leave out any section or view that doesn't apply; never add sections beyond these.
+
+```markdown
+## Why
+
+{One sentence: the problem this PR solves and what's possible once it ships.}
+
+## What changes on screen
+
+{One line per changed or new state, with its picture. Order by importance, not by name.}
+
+**{State, e.g. "Orders: empty"}** · `{scenario-name}` · {changed | new}
+{One short line on what changed, if the picture doesn't make it obvious.}
+![{scenario-name}]({published URL})
+
+{Unchanged states that were checked, in one line: "No change: orders-error, orders-loading."}
+
+## Things to note
+
+- {1-3 bullets: anything the reviewer could miss. A state the change touches with no scenario,
+  an intended diff elsewhere, a migration, a deliberate omission. "None." when there is nothing.}
+
+## Change outline
+
+{The smallest code-shape views that explain the implementation, each under one line of text.
+Pick from: a component tree, a call tree, a file tree with responsibilities, a key type, or
+pseudocode for the logic. Use a `diff` block when the shape already existed, a plain block when
+it's new.}
+
+## Try it
+
+{The scenario links for the states above, so a reviewer can open them in their own dev server.}
+
+- `/orders?scenario=orders-empty`
+```
+
+## Change outline examples
+
+A component change:
+
+```diff
+ <OrdersPage> (src/features/orders/OrdersPage.tsx)
+   useOrders()
+-  <OrdersTable />
++  {orders.length ? <OrdersTable /> : <EmptyOrders />}
++    <EmptyOrders> (src/features/orders/EmptyOrders.tsx)
+```
+
+A control-flow change:
+
+```diff
+ loadOrders
+   fetch /api/orders
+-  on error: throw
++  on error: show <OrdersError> with Retry
++  retry: loadOrders
+```
+
+Keep each view to what the reviewer needs. Leave out files and calls the change didn't touch.

package/skills/state-scenarios/SKILL.md

@@ -44,6 +44,13 @@ http://localhost:5173/orders?scenario=orders-empty&scenario-strict
 real backend. Once `<html data-scenario="orders-empty">` is set and the `ready` selector is
 visible, the state is on screen.
 
+## Show the real state, not a mock-up
+
+When you explain a UI change or a design choice to a person, show the app: `shoot --only` the states
+in question and put the PNGs (or `--compare` diffs) in front of them, instead of drawing the UI in
+HTML or ASCII. Real screenshots show real data, real styles and real bugs. Describe in words only
+what a screenshot can't show, such as the order things happen in.
+
 ## Topics
 
 Read the topic for the job before you start. The files sit next to this one, and
@@ -56,8 +63,8 @@ Read the topic for the job before you start. The files sit next to this one, and
 | `capture`           | [references/capture.md](references/capture.md)                     | Making a scenario from the running app: the panel, `?scenario-record`, MCP `save_scenario`           |
 | `auth`              | [references/auth.md](references/auth.md)                           | Signed-in and signed-out states, cookies, apps that validate a token on startup                      |
 | `network`           | [references/network.md](references/network.md)                     | Strict mode, `allow`, `ignore` for analytics, an existing MSW setup, named handlers                  |
-| `verify`            | [references/verify.md](references/verify.md)                       | Checking a UI change across every state with `shoot`, reading failure pages, PR evidence             |
-| `media`             | [references/media.md](references/media.md)                         | Screenshots and videos for docs and websites: viewports, dark mode, locales, `record`                |
+| `verify`            | [references/verify.md](references/verify.md)                       | Checking a UI change: `affected`, `shoot`, before/after `--compare`, failure pages, `publish`        |
+| `media`             | [references/media.md](references/media.md)                         | Screenshots and videos for docs and websites: viewports, dark mode, locales, `record`, Remotion      |
 | `mcp`               | [references/mcp.md](references/mcp.md)                             | Driving the live app from a coding agent: open, observe, act, check ready, save                      |
 | `debugging`         | [references/debugging.md](references/debugging.md)                 | Something fails: `doctor`, error codes and exit codes, common causes                                 |
 
@@ -69,9 +76,10 @@ Read the topic for the job before you start. The files sit next to this one, and
    the wiring one step at a time and prints the fix for each problem.
 3. New state: capture it from the running app (topic `capture`) instead of writing fixtures by
    hand. Set a `ready` selector and check it matches.
-4. Changed UI: `npx state-scenarios shoot <dir> --base-url <url>` and look at the screenshots of the
-   states your change touches (topic `verify`). Each failed scenario gets `<out>/<name>.md` with the
-   fix; read that page, not the JSON.
+4. Changed UI: `npx state-scenarios affected <dir>` names the states your branch touches; shoot
+   them with `--only`, and with `--compare` against a run from before the change (topic `verify`).
+   Look at the screenshots. Each failed scenario gets `<out>/<name>.md` with the fix; read that
+   page, not the JSON.
 5. `npx state-scenarios validate <dir>` before committing.
 
 ## Rules

package/skills/state-scenarios/references/media.md

@@ -40,8 +40,10 @@ export default {
 npx state-scenarios record src/scenarios --base-url http://localhost:5173 --steps steps.ts --format mp4
 ```
 
-- The panel is hidden and a cursor is drawn (Playwright videos don't show the mouse). Actions are
-  slowed slightly so the cursor reaches each target before the click.
+- The panel is hidden and a bright arrow cursor is drawn (Playwright videos don't show the mouse).
+  It pulses, glides to each target before `locator.click()` lands, and sends out a ripple on the
+  click. `--cursor-color <css>` (default `#ff2d55`) recolours it; `--cursor <file.svg>` draws your
+  own, with its top-left corner at the mouse.
 - The video starts once the scenario is ready and holds the last frame for `--hold` ms (default
   800), so there's no need for a `waitForTimeout` at the end of steps. Uncropped
   `--format webm` is the exception: it keeps the page load, and needs no ffmpeg.
@@ -54,7 +56,39 @@ npx state-scenarios record src/scenarios --base-url http://localhost:5173 --step
 - Video records at viewport size, so use a larger `--viewport` for sharper video; `--scale`
   affects screenshots only.
 - MP4, GIF, `--element`, `--fps` and `--width` need ffmpeg on `PATH`, or `FFMPEG_PATH`. WebM without them doesn't.
-- In your own Playwright scripts, `showCursor(page)` from `state-scenarios/playwright` draws the
-  cursor; call it before `openScenario(page, name, { panel: false })`.
+- Each video gets a `<name>.video.json` manifest: size, length, description and clicks. See
+  [Videos in Remotion](#videos-in-remotion).
+- In your own Playwright scripts, `showCursor(page, { color, svg })` from `state-scenarios/playwright`
+  draws the cursor; call it before `openScenario(page, name, { panel: false })`. Hover before a
+  click there, so the cursor arrives first.
+
+## Videos in Remotion
+
+`record` writes `<name>.video.json` next to each video, for editors such as
+[Remotion](https://www.remotion.dev):
+
+```json
+{
+  "name": "default",
+  "description": "All 248 countries from the API",
+  "video": "default.mp4",
+  "width": 1280,
+  "height": 720,
+  "durationMs": 4185,
+  "clicks": [{ "t": 731, "x": 93, "y": 56 }]
+}
+```
+
+`durationMs` and click times count from the first frame of the saved video. Click `x` and `y` are
+pixels in it, after `--element` and `--width`. Record into the Remotion project's `public/` folder,
+then:
+
+- Read the manifests in the composition's `calculateMetadata` to set `durationInFrames`.
+- Play each video with `<Video src={staticFile(...)} />` from `@remotion/media`.
+- Zoom to each click by scaling the video around its `x` and `y` shortly before `t`.
+- Use `description` as a caption, or replace it per scenario.
+
+Pace steps with a short `page.waitForTimeout` before each click, so the zoom has time to arrive.
+`examples/remotion-promo` in the state-scenarios repo does all of this.
 
 Use demo data in scenarios meant for public images: fictional names, no real customer records.

package/skills/state-scenarios/references/verify.md

@@ -10,6 +10,47 @@ For each scenario `shoot` opens the link in strict mode, waits for `ready`, save
 checks for unmocked requests, uncaught exceptions and `console.error` calls. `--only a,b` limits
 the run; `--json` prints the report for scripts.
 
+## Which states a change touches
+
+```bash
+npx state-scenarios affected src/scenarios --base main --src src
+```
+
+It lists each scenario the branch can affect (committed, uncommitted and new files) and why:
+
+| Reason     | Means                                                              |
+| ---------- | ------------------------------------------------------------------ |
+| `scenario` | The scenario's file changed                                        |
+| `extends`  | It extends a scenario that changed                                 |
+| `map`      | A scenario map row's Source column covers a changed file           |
+| `endpoint` | A changed file mentions an endpoint the scenario mocks             |
+| `route`    | A changed file sits under a folder named like the scenario's route |
+
+The last line is `--only a,b,c`, ready for `shoot`. Changed files nothing pointed at are listed
+too: a shared file (layout, theme, global CSS) can change every state, so shoot them all then.
+`--src` limits it to the app's folders in a monorepo; `--json` is for scripts. A scenario map with
+Source columns (`/create-scenario-map`) makes the result much sharper than the endpoint and route
+guesses.
+
+## Before and after
+
+Shoot the base branch first, then the change, and compare:
+
+```bash
+git stash                      # or check out the base branch in a worktree on another port
+npx state-scenarios shoot src/scenarios --base-url http://localhost:5173 --only <affected> --out .shots/before
+git stash pop
+npx state-scenarios shoot src/scenarios --base-url http://localhost:5173 --only <affected> --out .shots/after --compare .shots/before
+```
+
+Each state that changed gets `.shots/after/<name>.diff.png`: before, after and the changed pixels
+in red, side by side. States are reported `changed`, `same` or `new` (no earlier shot), and ones
+that are gone as `removed`. A diff doesn't fail the run: in a UI change, diffs are the point. Look
+at every `changed` state and ask whether the change meant to touch it.
+
+Shoot both runs with the same viewport and options, and with the dev server warm, or fonts and
+images still loading show as changes.
+
 ## When a scenario fails
 
 The terminal names a page for it: `❯ details .scenario-shots/<name>.md`. Read that page. It has:
@@ -26,9 +67,20 @@ wrong, or that the UI change broke the state. Fix the app when the screenshot sh
 
 ## Evidence
 
-Look at the PNGs for the states the change touches, plus loading, empty and error. Attach the
-relevant ones to the PR. Pages for passing scenarios are deleted on each run, so the `.md` files
-in the output folder are always the current failures.
+Look at the PNGs for the states the change touches, plus loading, empty and error. Pages for
+passing scenarios are deleted on each run, so the `.md` files in the output folder are always the
+current failures.
+
+To show them in a PR, publish them; `gh` can't upload images:
+
+```bash
+npx state-scenarios publish .shots/after/*.diff.png --folder pr-42
+```
+
+It commits the files to a `scenario-shots` branch with git plumbing (the checkout, index and
+current branch stay as they are), pushes it, and prints a Markdown image line per file, linked to
+that commit so the links don't change. Paste those lines into the PR body. `--branch` and
+`--remote` change where they go. The `scenario-pr` skill writes the whole PR description this way.
 
 ## In Playwright tests
 

package/dist/record-HXIYGMWA.js

@@ -1,65 +0,0 @@
-import {
-  CliError
-} from "./chunk-GCYOLAFU.js";
-
-// src/record.ts
-import { spawnSync } from "child_process";
-import { copyFileSync } from "fs";
-function visibleCrop(box, viewport) {
-  const x = Math.max(0, box.x);
-  const y = Math.max(0, box.y);
-  const width = Math.min(viewport.width, box.x + box.width) - x;
-  const height = Math.min(viewport.height, box.y + box.height) - y;
-  if (width < 2 || height < 2) return void 0;
-  return { crop: { x, y, width, height }, clipped: width < box.width || height < box.height };
-}
-var even = (n) => Math.max(2, Math.floor(n / 2) * 2);
-function ffmpegArgs({ input, output, format, start, crop, fps, width }) {
-  const rate = fps ?? (format === "gif" ? 12 : void 0);
-  const filters = [
-    crop && `crop=${even(crop.width)}:${even(crop.height)}:${Math.round(crop.x)}:${Math.round(crop.y)}`,
-    rate && `fps=${rate}`,
-    // Quoted so the comma in min() isn't read as a filter separator.
-    width && `scale='trunc(min(${width},iw)/2)*2':-2:flags=lanczos`
-  ].filter(Boolean);
-  const codec = {
-    mp4: ["-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "23", "-movflags", "+faststart"],
-    webm: ["-c:v", "libvpx-vp9", "-b:v", "0", "-crf", "32"],
-    gif: []
-  }[format];
-  const vf = format === "gif" ? `${filters.join(",")},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer` : filters.join(",");
-  return [
-    "-y",
-    "-loglevel",
-    "error",
-    "-i",
-    input,
-    "-ss",
-    start.toFixed(2),
-    ...vf ? ["-vf", vf] : [],
-    "-an",
-    ...codec,
-    output
-  ];
-}
-function encodeVideo(options) {
-  if (options.format === "webm" && !options.crop && !options.fps && !options.width) {
-    copyFileSync(options.input, options.output);
-    return;
-  }
-  const ffmpeg = process.env.FFMPEG_PATH || "ffmpeg";
-  const result = spawnSync(ffmpeg, ffmpegArgs(options), { encoding: "utf8" });
-  if (result.error) {
-    throw new CliError(
-      "FFMPEG_MISSING",
-      `record needs ffmpeg for ${options.format}${options.format === "webm" ? " with --element, --fps or --width" : ""}: install it (https://ffmpeg.org/download.html) or set FFMPEG_PATH`
-    );
-  }
-  if (result.status !== 0) throw new Error(`ffmpeg failed: ${result.stderr.trim()}`);
-}
-export {
-  encodeVideo,
-  ffmpegArgs,
-  visibleCrop
-};
-//# sourceMappingURL=record-HXIYGMWA.js.map

package/dist/record-HXIYGMWA.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/record.ts"],"sourcesContent":["import { spawnSync } from 'node:child_process';\nimport { copyFileSync } from 'node:fs';\nimport { CliError } from './errors.js';\n\nexport type VideoFormat = 'mp4' | 'gif' | 'webm';\n\nexport interface Crop {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\n/**\n * The part of an element's box the video shows. Video holds only the viewport, so a crop must\n * stay inside it; `clipped` says the element was larger than the visible area.\n */\nexport function visibleCrop(box: Crop, viewport: { width: number; height: number; }) {\n  const x = Math.max(0, box.x);\n  const y = Math.max(0, box.y);\n  const width = Math.min(viewport.width, box.x + box.width) - x;\n  const height = Math.min(viewport.height, box.y + box.height) - y;\n\n  if (width < 2 || height < 2) return undefined;\n\n  return { crop: { x, y, width, height }, clipped: width < box.width || height < box.height };\n}\n\nconst even = (n: number) => Math.max(2, Math.floor(n / 2) * 2);\n\n/**\n * ffmpeg arguments that trim the page load off the start, crop to an element, and encode.\n * MP4 is H.264 in yuv420p so it plays everywhere, including Safari and phones; GIF uses a\n * generated palette, which keeps it sharp at a fraction of the naive size.\n */\nexport function ffmpegArgs(\n  { input, output, format, start, crop, fps, width }: {\n    input: string;\n    output: string;\n    format: VideoFormat;\n    /** Seconds to skip, e.g. the page loading before the steps begin. */\n    start: number;\n    crop?: Crop;\n    /** Frames per second; GIFs default to 12. */\n    fps?: number;\n    /** Maximum output width in pixels, never upscaled; height follows the aspect ratio. */\n    width?: number;\n  },\n): string[] {\n  const rate = fps ?? (format === 'gif' ? 12 : undefined);\n\n  // yuv420p needs even sizes.\n  const filters = [\n    crop && `crop=${even(crop.width)}:${even(crop.height)}:${Math.round(crop.x)}:${Math.round(crop.y)}`,\n    rate && `fps=${rate}`,\n    // Quoted so the comma in min() isn't read as a filter separator.\n    width && `scale='trunc(min(${width},iw)/2)*2':-2:flags=lanczos`,\n  ].filter(Boolean);\n\n  const codec = {\n    mp4: ['-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '23', '-movflags', '+faststart'],\n    webm: ['-c:v', 'libvpx-vp9', '-b:v', '0', '-crf', '32'],\n    gif: [],\n  }[format];\n\n  const vf = format === 'gif'\n    ? `${filters.join(',')},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer`\n    : filters.join(',');\n\n  return [\n    '-y',\n    '-loglevel',\n    'error',\n    '-i',\n    input,\n    '-ss',\n    start.toFixed(2),\n    ...(vf ? ['-vf', vf] : []),\n    '-an',\n    ...codec,\n    output,\n  ];\n}\n\n/**\n * Convert Playwright's WebM into the requested format. WebM without a crop, --fps or --width is\n * copied as recorded (page load included), so it works without ffmpeg.\n */\nexport function encodeVideo(options: Parameters<typeof ffmpegArgs>[0]) {\n  if (options.format === 'webm' && !options.crop && !options.fps && !options.width) {\n    copyFileSync(options.input, options.output);\n\n    return;\n  }\n\n  // FFMPEG_PATH is the usual override when ffmpeg isn't on PATH (common on Windows).\n  const ffmpeg = process.env.FFMPEG_PATH || 'ffmpeg';\n  const result = spawnSync(ffmpeg, ffmpegArgs(options), { encoding: 'utf8' });\n\n  if (result.error) {\n    throw new CliError(\n      'FFMPEG_MISSING',\n      `record needs ffmpeg for ${options.format}${\n        options.format === 'webm' ? ' with --element, --fps or --width' : ''\n      }: install it (https://ffmpeg.org/download.html) or set FFMPEG_PATH`,\n    );\n  }\n\n  if (result.status !== 0) throw new Error(`ffmpeg failed: ${result.stderr.trim()}`);\n}\n"],"mappings":";;;;;AAAA,SAAS,iBAAiB;AAC1B,SAAS,oBAAoB;AAgBtB,SAAS,YAAY,KAAW,UAA8C;AACnF,QAAM,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;AAC3B,QAAM,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;AAC3B,QAAM,QAAQ,KAAK,IAAI,SAAS,OAAO,IAAI,IAAI,IAAI,KAAK,IAAI;AAC5D,QAAM,SAAS,KAAK,IAAI,SAAS,QAAQ,IAAI,IAAI,IAAI,MAAM,IAAI;AAE/D,MAAI,QAAQ,KAAK,SAAS,EAAG,QAAO;AAEpC,SAAO,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,OAAO,GAAG,SAAS,QAAQ,IAAI,SAAS,SAAS,IAAI,OAAO;AAC5F;AAEA,IAAM,OAAO,CAAC,MAAc,KAAK,IAAI,GAAG,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC;AAOtD,SAAS,WACd,EAAE,OAAO,QAAQ,QAAQ,OAAO,MAAM,KAAK,MAAM,GAYvC;AACV,QAAM,OAAO,QAAQ,WAAW,QAAQ,KAAK;AAG7C,QAAM,UAAU;AAAA,IACd,QAAQ,QAAQ,KAAK,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,MAAM,CAAC,IAAI,KAAK,MAAM,KAAK,CAAC,CAAC,IAAI,KAAK,MAAM,KAAK,CAAC,CAAC;AAAA,IACjG,QAAQ,OAAO,IAAI;AAAA;AAAA,IAEnB,SAAS,oBAAoB,KAAK;AAAA,EACpC,EAAE,OAAO,OAAO;AAEhB,QAAM,QAAQ;AAAA,IACZ,KAAK,CAAC,QAAQ,WAAW,YAAY,WAAW,QAAQ,MAAM,aAAa,YAAY;AAAA,IACvF,MAAM,CAAC,QAAQ,cAAc,QAAQ,KAAK,QAAQ,IAAI;AAAA,IACtD,KAAK,CAAC;AAAA,EACR,EAAE,MAAM;AAER,QAAM,KAAK,WAAW,QAClB,GAAG,QAAQ,KAAK,GAAG,CAAC,gFACpB,QAAQ,KAAK,GAAG;AAEpB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,MAAM,QAAQ,CAAC;AAAA,IACf,GAAI,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC;AAAA,IACxB;AAAA,IACA,GAAG;AAAA,IACH;AAAA,EACF;AACF;AAMO,SAAS,YAAY,SAA2C;AACrE,MAAI,QAAQ,WAAW,UAAU,CAAC,QAAQ,QAAQ,CAAC,QAAQ,OAAO,CAAC,QAAQ,OAAO;AAChF,iBAAa,QAAQ,OAAO,QAAQ,MAAM;AAE1C;AAAA,EACF;AAGA,QAAM,SAAS,QAAQ,IAAI,eAAe;AAC1C,QAAM,SAAS,UAAU,QAAQ,WAAW,OAAO,GAAG,EAAE,UAAU,OAAO,CAAC;AAE1E,MAAI,OAAO,OAAO;AAChB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,2BAA2B,QAAQ,MAAM,GACvC,QAAQ,WAAW,SAAS,sCAAsC,EACpE;AAAA,IACF;AAAA,EACF;AAEA,MAAI,OAAO,WAAW,EAAG,OAAM,IAAI,MAAM,kBAAkB,OAAO,OAAO,KAAK,CAAC,EAAE;AACnF;","names":[]}