demo-capture

Capturing the screen

Rehearse, then perform

The rehearsal session (demo_* MCP tools, or node scripts/stage.mjs <name> from the shell when the tools are not in your tool list) is for figuring things out. The performance runner replays what you found, smoothly, while recording.

Consequences worth internalising:

• Anything you do during rehearsal is invisible in the final video. Explore freely.
• Only successful actions are recorded, so a failed click cannot poison a script.
• The performance replays exactly the recorded steps. If the app needs to be in a particular state to start, put that in the action script or reset the app before performing.

Writing a flow that films well

• One idea per scene. If narration needs "and then", it is two scenes.
• Start where the user starts. Not on a page you navigated to off-camera.
• Type realistic content. "Acme Demo" reads as a demo. "asdf" reads as a bug.
• Pause after the payoff. Add dwellMs on the step that produces the result; the viewer needs a beat to see what changed.
• Highlight the moment that matters. One demo_highlight per scene, on the thing the narration is naming. More than one and none of them land.
• Never demo a login. Use storageState or log in before markStart.

Pacing to the narration

--target-duration stretches dwell, never motion. The clip lands on the voiceover instead of being cut to fit afterwards.

pinToWord goes further: a step fires exactly when a word is spoken.

{ "type": "click", "selectors": ["[data-testid=save]"],
  "label": "Save", "pinToWord": "save" }

Use word#2 for the second occurrence. Requires the scene's .words.json, passed as --timestamps.

If the runner warns about overrun, the steps genuinely cannot fit — cut steps or lengthen the line. It will not silently speed up the cursor.

Web specifics

• The cursor in the video is drawn, because Playwright's real pointer is invisible to the recorder. It is animated with the Web Animations API rather than requestAnimationFrame, which does not fire reliably under headless capture.
• Prefer demo_inspect selectors. The ladder (data-testid → id → role+name → text → structural path) is tried in order, so replay survives small DOM changes.
• Headless is fine and slightly more reliable; use headed when you want to watch.
• Authenticated sessions: --storage-state <file>.