screencast

Scripts do the work; this file lists only what differs from a plain Playwright recordVideo + ffmpeg job.

node "${CLAUDE_SKILL_DIR}/scripts/finish.mjs" spec-1-1.webm spec-1-2.webm --out .agent/feat-x/.aw-tester/recordings/spec-1.mp4

Outputs (the contract other skills read)

<id>.mp4, <id>.timings.json (steps: [{ label, start, end, result }] in output seconds), and <id>.sheet.png (one frame per step), side by side. Standalone runs write to .agent/{branch}/recordings/; a caller such as aw-tester keeps its own directory.

Deviations from the default

1. Read <id>.sheet.png before any upload or claim. You cannot watch a video; the sheet is how you check it shows what you say it shows.
2. Record at 1x. Playwright video ignores deviceScaleFactor: a 2x page lands in a corner of the frame. Upscale in ffmpeg if needed.
3. Hide the overlay in screenshots: page.screenshot({ style: '#__screencast{display:none!important}' }), so evidence images show only the app.
4. A runner writes timings as it goes: { label, start, end, result } per step, seconds from newPage(); several launches → pass every segment to finish.mjs in order, and it joins them and offsets their timings.
5. A failed recording is a notes line, never a failed check.
6. Chrome driver (claude-in-chrome): no recordVideo, so record with capture.mjs, never gif_creator: a GIF gets one frame per tool call and is ~20× larger than the mp4. It needs Chrome's remote debugging on once (chrome://inspect/#remote-debugging), and the user clicks Allow once per Chrome session: the first start prints connecting to Chrome and waits, and later ones reuse the relay's connection. --wait 600 when you start it before asking. Chrome paints only while the page changes and its window is visible, so the video starts at the first frame after start, and stop exits 6 if none came. start injects overlay.js into the tab and every later navigation, and capture.mjs step "<label>" draws that label as the bottom caption: never inject the overlay or call __rec.step yourself. When step prints caption not drawn, the page blocked the script (a strict CSP); the video has no caption for that step, so say so in notes. Write each label as what the viewer should notice, in the product's words ("The list keeps only slow requests"), not "Click Filter". Exit 6 (no debugging, no matching tab, no frames) → fall back to gif_creator, convert the GIF (ffmpeg -i x.gif -movflags +faststart -vf "scale=1280:-2,format=yuv420p" -c:v libx264 -crf 28 -an x.mp4), and add a notes line.
7. Narration is opt-in (--narrate): each step's say line, spoken with macOS say or SCREENCAST_TTS="<cmd with {text} and {out}>". Never by default — reviewers watch muted.

Exit codes: 2 bad arguments, 3 ffmpeg missing, encoding failed, or the mp4 failed its sanity check, 4 playwright does not resolve, 5 --narrate with no voice, 6 capture.mjs found no DevTools endpoint, tab, or frames.