Demo Recorder

Turn a running frontend app into a set of narrated demo videos. The workflow: discover features → agree scope with the user → plan scenarios → generate Playwright recording scripts → record per-scenario clips → emit a timed narration script the user feeds to TTS for voiceover.

Design stance: demo-first with light verification. Every scenario script asserts its flow's key business outcome. A recording that completes is a flow that works; a broken flow fails loudly instead of producing a silently wrong video. This is not a substitute for a real e2e suite — don't build one here.

Two tools, two jobs — don't mix them up:

• Playwright MCP tools (mcp__plugin_playwright_playwright__*): live exploration during discovery, and selector verification while writing scripts. They cannot record video.
• Generated Node scripts using Playwright's recordVideo: the actual recordings. They live in the user's project, so demos are re-runnable after UI changes without redoing this whole process.

Phase 0 — Prerequisites

Check before promising anything:

1. Playwright MCP tools available (load via ToolSearch in one call: select:mcp__plugin_playwright_playwright__browser_navigate,mcp__plugin_playwright_playwright__browser_snapshot,mcp__plugin_playwright_playwright__browser_click,mcp__plugin_playwright_playwright__browser_type,mcp__plugin_playwright_playwright__browser_take_screenshot). If absent, tell the user to install the Playwright plugin and stop.
2. npx playwright --version works. Chromium installed (npx playwright install chromium if recording later fails to launch).
3. which ffmpeg — optional; without it, deliver .webm and say so.
4. The app runs. Find the dev-server command (README, CLAUDE.md, package.json scripts), start it yourself in the background if it isn't up, and verify with an HTTP request before recording anything.

Phase 1 — Discovery

Goal: a feature inventory grounded in what the product is for, not just what routes exist. Consult sources in this order — cheap and authoritative first:

1. Domain context files: .tasks/domain.md, docs/, anything a domain-context skill maintains. These state business rules code only implies.
2. CLAUDE.md / README: product intent, which frontend is which, key flows.
3. Memory: prior sessions may record what the product's selling points are.
4. Route definitions: router files (App.tsx, route configs) enumerate the surface area. Map each route to a feature guess.
5. Live exploration: only after the above — navigate the running app with MCP tools, snapshot key pages, follow the primary flows once. This confirms what actually renders and captures real selectors, auth steps, seed-data needs.

Write the inventory as a short list: feature, user role, why it matters to the business, rough flow. Note anything that needs credentials or seeded data.

Phase 2 — Scope interview

Never guess scope. Ask with AskUserQuestion (it adds a free-text "Other" automatically — offer 3 concrete choices per question). Ask about:

1. Coverage: main business scenarios only / all happy paths / happy + key unhappy paths (validation errors, rejections — these can showcase robustness in a demo).
2. Audience: sales demo (polished, slower pacing, no edge cases) / internal walkthrough (denser, can show admin views) / feature announcement (one feature, tight clip). Include narration language in this question — default to the UI's language (a Polish app usually gets a Polish voiceover), offer English as the alternative; a second-language variant file is cheap to add.
3. Which features from the inventory to include — list them as options.
4. Anything discovery left uncertain: base URL, credentials, seed data, which of several frontends. Ask only what you genuinely couldn't determine.

Batch these into one AskUserQuestion call (max 4 questions). If more uncertainty remains after that, ask again rather than assuming — a wrong guess here wastes an entire recording cycle.

Phase 3 — Demo plan (user approval gate)

Write demos/demo-plan.md in the project:

# Demo plan — <app name>

## Scenario: <slug>
- Role / login: …
- Business value: one sentence — why this is worth showing.
- Steps: numbered, each step = one narration beat.
- Key assertion: the business outcome that must hold.
- Narration draft: one line per beat, conversational, present tense.
- Est. length: ~Ns

Target 30–90 seconds per clip. Longer than 90s means the scenario should split. Show the plan to the user and get explicit approval before recording — the plan is cheap to change, recordings are not.

Phase 4 — Workspace setup (first run only)

Create a self-contained demos/ directory in the project — its own package.json so the project's dependencies stay untouched:

mkdir -p demos/scenarios demos/helpers demos/videos
cd demos && npm init -y && npm i -D playwright @playwright/test
npx playwright install chromium

Copy from this skill's assets/ into the project:

• assets/record.js → demos/helpers/record.js (recording session + cue API)
• assets/build_narration.js → demos/helpers/build_narration.js

Add demos/videos/ and demos/node_modules/ to .gitignore. The scripts themselves belong in git — they're the re-runnable demo suite.

Phase 5 — Scenario scripts

Write one script per scenario into demos/scenarios/<slug>.js, following assets/scenario-template.js. The API (from helpers/record.js):

• startRecording({ name, baseURL }) → rec with page, cue, pause, click, type, finish. It auto-injects a cursor overlay (teal dot + click ripples) — headless recordings show no OS cursor, so without it the viewer can't follow the action.
• rec.cue(label, narration) — call at the start of each visible action group. This is the heart of the skill: cues log elapsed time, so narration timestamps come out exactly aligned with the video, for free.
• rec.pause(ms) — after every meaningful screen change. A demo without pauses is unwatchable; the viewer needs ~1.5–2.5s to absorb a new screen.
• rec.click(locator) / rec.type(locator, text) — eased mouse glide and visible keystrokes; raw locator.click() teleports and fill() pastes, both read as fake on video.
• One assertion minimum on the key business outcome (expect(...) from @playwright/test). Wrap the flow in try/catch: on failure, exit non-zero and say the flow is broken — never deliver a video of a broken flow.
• Re-assert the final success state after the closing pause. Background pipelines (security gatekeepers, async analysis, rate limiters) can flip a confirmation screen to an error seconds after the first assertion passes — this guard caught exactly that in live testing. A demo must never end on an error frame nobody watched for.

Narration lines: conversational, present tense, ~2.5 words/second of segment time ("The reviewer checks the analysis and releases the summary to the customer."). Write them from the demo plan, refine after seeing real timings.

Before finalizing selectors, verify them against the live app with MCP browser_snapshot — accessibility-role selectors (getByRole, getByLabel) survive UI changes far better than CSS classes. UI text may be non-English; match what's actually rendered.

Phase 6 — Record + narration

Per scenario:

cd demos
DEMO_BASE_URL=http://localhost:3000 node scenarios/<slug>.js
node helpers/build_narration.js videos/<slug>.cues.json --mp4

build_narration.js writes videos/<slug>.narration.md — timestamped segments with narration text — plus a matching .srt subtitle file (drops into video editors and subtitle-driven TTS tools), and warns (exit 2) when a line exceeds the segment's word budget. Fix warnings by shortening the line or adding rec.pause() after that beat, then re-record; TTS audio that outruns the video ruins the demo.

Watch at least the first video yourself: take a few ffmpeg-extracted frames (ffmpeg -i clip.webm -vf fps=1/3 frame_%02d.png) and check pacing, cut-off states, stray dev overlays. First recordings usually pace too fast.

Phase 7 — Deliver + iterate

Report a table: scenario · video file · length · narration file · assertion result. Remind the user: narration .md → their TTS tool → audio track over the .mp4 (or use the .srt directly). Still frames extracted with ffmpeg -i clip.mp4 -vf fps=1/3 stills_%02d.png make free pitch-deck material — offer them when the audience is sales. Offer per-scenario re-recording — that's why clips are per-scenario. The demos/ directory is the durable artifact: next time features change, rerun scripts, don't restart from discovery.

Troubleshooting

• Login walls: script the login inside the scenario (it's often worth showing) or use Playwright storageState to skip it when the demo starts deeper in the app.
• Data-dependent flows (dashboards, inboxes): seed via the app's API or fixtures before recording. Never record an empty inbox demo.
• Demo identities and security pipelines: recording runs often submit real data. Use a fresh, clearly-fake identity with benign copy — apps with injection classifiers or rate limiters can silently block or even ban a demo identity (one live test earned a 24h email ban for text that looked like a prompt injection), which then poisons every later take. Also check what state each run creates; prefer scenarios that stop before submitting when the submission has side effects you can't clean up.
• Flaky timing: prefer expect(...).toBeVisible() waits over raw waitForTimeout for correctness; keep pause() purely for viewer pacing.
• Animations/spinners: give async operations a cue of their own with narration covering the wait ("The AI analysis runs — this takes a few seconds."), rather than cutting them out.