Demo Video Skill — visual validation for web apps

Record a captioned walkthrough video of a running web app, verify it frame-by-frame, convert to mp4, and deliver it. Battle-tested on real client-feedback proof videos.

This is the harness's default visual validation for web projects: a demo video walks a real user flow end-to-end and doubles as a passing E2E test, so "it works" is proven visually, not claimed. It complements [[visual-validation]] (autonomous screenshot-regression checks) and [[playwright-testing]] (the E2E suite): screenshots catch pixel regressions, the suite proves behavior, and a demo video proves the whole user-facing flow the way a person would see it.

The method

1. Write a temporary Playwright spec (e2e/zz-<name>-video.spec.ts or scratchpad) that walks the real flows as one continuous test. One test = one video.
2. Record via Playwright's built-in video, never external screen capture:

   test.use({ video: { mode: 'on', size: { width: 1280, height: 800 } }, viewport: { width: 1280, height: 800 } })
   test.setTimeout(240000)

3. Narrate with an injected caption bar — the video must explain itself without audio. Call before each chapter; the pause gives viewers time to read:

   async function caption(page: Page, text: string) {
     await page.evaluate((t) => {
       let bar = document.getElementById('demo-caption')
       if (!bar) {
         bar = document.createElement('div')
         bar.id = 'demo-caption'
         bar.style.cssText =
           'position:fixed;left:0;right:0;bottom:0;z-index:99999;background:#142b1e;color:#f7f5f0;' +
           'font:600 15px/1.4 Inter,system-ui,sans-serif;padding:12px 20px;letter-spacing:0.01em'
         document.body.appendChild(bar)
       }
       bar.textContent = t
     }, text)
     await page.waitForTimeout(2200)
   }

   The caption bar is re-injected automatically because caption() re-creates it after each page.goto (the element does not survive navigation — call caption AFTER navigating).
4. Structure as chapters: caption → act → assert → caption the outcome. Keep real assertions in the spec so the video doubles as a passing test — a video of a broken flow must fail loudly, never ship silently.
5. Reuse the project's e2e helpers (logins, seeded data, fixtures) instead of hand-rolling flows. Prefer fake/deterministic AI modes so runs are repeatable.

Recording gotchas (learned the hard way)

• Scroll-reveal animations: elements animated in by IntersectionObserver stay invisible in captures unless you actually scroll. Walk the page (scrollIntoViewIfNeeded or step-scroll) before asserting/capturing.
• OTP/async steps: after submitting a form that triggers an email/side effect, wait for the next UI state (await expect(page.locator('#code')).toBeVisible()) before reading outboxes/fixtures — racing the write is the #1 flake.
• Selector traps: "first link" often matches a New/Create button; exclude it (a[href^="/x/"]:not([href$="/new"])).
• Demonstrating error states: drive the app's real error surface (e.g. navigate to the URL the failing action redirects to) rather than mocking pages that don't exist.

Produce and verify

rm -rf test-results/zz-<name>*          # stale videos have the same filename
npx playwright test e2e/zz-<name>-video.spec.ts
find test-results -name "video.webm"    # the recording

# Convert to mp4 (universal playback, ~2-3x smaller)
ffmpeg -y -i "<video.webm>" -c:v libx264 -pix_fmt yuv420p -movflags +faststart out.mp4

# ALWAYS spot-check frames before delivering — extract a few and LOOK at them
ffmpeg -y -i out.mp4 -vf "select='eq(n\,60)+eq(n\,300)+eq(n\,600)'" -vsync vfr frame_%d.png

Read the extracted frames with the Read tool and confirm captions render and each chapter shows what it claims. Never deliver an unviewed video.

Deliver and clean up

• Copy the mp4 to your stakeholder-updates archive (e.g. ~/Documents/updates/<project>/, the house archive for stakeholder updates), and send it to the user (SendUserFile or equivalent).
• Naming is mandatory and identifying: YYYY-MM-DD-NN-<project>-<what-it-proves>.mp4 — the date it was recorded, then a two-digit index so several videos on the same day stay ordered and every video is uniquely identifiable at a glance. Allocate the next free index with a no-clobber loop — never a count (wc -l), which reuses an index if an earlier file was deleted and silently overwrites an existing mp4:

  DIR=~/Documents/updates/<project>; DATE=$(date +%F); mkdir -p "$DIR"
  NN=1
  while printf -v F '%s/%s-%02d-<project>-<what-it-proves>.mp4' "$DIR" "$DATE" "$NN" && [ -e "$F" ]; do
    NN=$((NN+1))
  done
  cp out.mp4 "$F"

  Never video.mp4, never a name without its date and index.
• Delete the temporary spec — it is a capture script, not a test; it must not join the suite or CI.

Prerequisites

• Playwright installed in the project (@playwright/test) with a working dev/preview server.
• ffmpeg on PATH for the webm→mp4 conversion and frame extraction.