Browser Video

Browser Video

You cannot see what you recorded. Every rule here exists because a script succeeded and the video was still wrong: the run returned "done", exited 0, and shipped a take with the click 200px off target and no pointer in frame. A green run is evidence the script ran, not evidence the video is right.

Assumes playwright-cli is on PATH. Begins where its references/video-recording.md ends - that reference has the screencast and overlay API; this skill has what it takes to get a correct take.

One take per browser session

Overlays leak. An overlay with duration: 3400 outlived its duration, survived page.goto, survived screencast.stop(), and reappeared in two later recordings as a stale pill nobody put there. Start every take in a fresh named session and close it after:

playwright-cli -s=take1 open https://example.com/
playwright-cli -s=take1 video-show-actions
playwright-cli -s=take1 run-code --filename hero.js
playwright-cli -s=take1 close

page.screencast.hideOverlays() clears leaked overlays and is worth calling before stop(), but only a fresh session is deterministic.

Make actions visible

The screencast records no cursor. Not the OS pointer, not a synthetic one - page.mouse.move() moves an invisible thing. Run video-show-actions on the session before the scripted run and the recording gains both an animated pointer and a callout naming each action:

playwright-cli -s=take1 video-show-actions --duration=600 --position=top-right

--cursor pointer is the default; --cursor none disables the pointer and keeps the callouts. It annotates run-code actions, not just CLI-driven ones, so it replaces any hand-rolled cursor overlay entirely.

Work in two phases

1. Explore with CLI commands. Drive the real flow with playwright-cli goto/snapshot/click/fill, recording nothing. This is where you learn the locators, what the app actually anchors to, and where the flow surprises you. Skipping it means discovering the surprise inside a take.
2. Script the take with run-code. One file, run once, so pauses and pacing are deliberate. Copy assets/hero-template.js and adapt it - it carries the coordinate mapping, the glide helper, and the chapter brackets.

Coordinates inside a scaled iframe

boundingBox() does not correct for a CSS transform scaling an iframe. It reported (766, 538) for an element rendering at (442, 350) inside an iframe at Fit 55%; the click landed 200px low and pinned a comment to the wrong thing. Map through the iframe box instead:

const ib = await page.locator(FRAME).boundingBox();          // iframe in the page
const r = await locator.evaluate(el => {                     // element in the frame
  const b = el.getBoundingClientRect();
  return { x: b.x, y: b.y, w: b.width, h: b.height, vw: innerWidth };
});
const s = ib.width / r.vw;                                   // the real scale
const point = { x: ib.x + r.x * s, y: ib.y + r.y * s };

Outside a scaled frame boundingBox() is correct and needs none of this. The tell that you need it: the app renders a page inside a page, or shows a zoom control such as "Fit 55%".

Verify before delivering

Extract frames and look at them. This is the only step that has ever caught any of the above.

scripts/video.sh probe take.webm                  # duration, size, codec
scripts/video.sh sheet take.webm                  # 6 frames tiled into one PNG
scripts/video.sh sheet take.webm -n 6 --around 5 --window 2   # hunt a short overlay

Read the sheet, not the frames one at a time. Check four things:

• the pointer is visible and near what is being clicked
• the intended target was hit, and the app responded to it
• no overlay from an earlier take is on screen
• text is legible at the delivered size

A short annotation can hide entirely between evenly spaced frames; --around with a narrow --window is how you confirm a 900ms callout rendered.

Deliver .mp4 unless asked otherwise - .webm will not play in several places a reviewer might open it:

scripts/video.sh mp4 take.webm     # H.264, yuv420p, faststart

Record against a disposable fixture

A flow that mutates state burns its target on every take, and you will need more than one take. Recording a comment flow consumed three real canvases before a clean run. Create the fixture you can recreate before recording - a fresh account, board, document or seeded row - rather than after the first take has dirtied the real one. Where the flow is read-only, none of this applies.

Craft

For a video a human watches, as opposed to a verification artefact:

• Type with pressSequentially(text, { delay: 55 }). Instant fills read as a glitch; 50-60ms reads as a person.
• Move with page.mouse.move(x, y, { steps: 28 }), then wait ~500ms before clicking. The settle pause is what makes the action legible.
• Bracket sections with page.screencast.showChapter(title, { description, duration: 2400 }). Open on one, close on one.
• Highlight the outcome with showOverlay for ~3s at the end, so the viewer knows which part was the point.
• Aim for 20-40s. Under 20s a viewer misses the setup; over 40s they scrub.

Boundaries

• playwright-cli - the screencast, overlay and chapter API itself.
• video-thumbnails - a still image composed from a video that already exists.
• terminal-control, terminal-fabricate - recordings of a terminal, not a browser.
• prove-it - whether evidence supports a claim; this skill is how the evidence gets captured.

tests/video.bats covers scripts/video.sh's CLI contract; run it after changing the script. evals/ holds this skill's own test prompts and rubric; neither is part of the procedure.