Record Browser Gif

Record Browser GIF

Produce a short, truthful UI demonstration as a local GIF, and — only when the task includes attaching it to a pull request — publish it through the attach workflow at the end of this skill. The available browser-control workflow remains preferred. Use Playwright Videos when that workflow supports continuous capture at higher frame rates; use the bundled encoder for trimming, playback speed, final hold, dimensions, and size.

The evidence-chain decision owns why one storyboard comes from one isolated run and why publication revalidates both the artifact and the demonstrated pull-request head.

Every GUI pull request includes a GIF

A pull request that changes product-user-visible GUI behavior MUST include a demonstration GIF recorded with this skill and embedded in the pull request body via the attach workflow.

The recording itself is part of the evidence: use a real server booted from that pull request's branch tree, a real API key, and real model rounds. Never substitute fixture queries, mock transports, synthetic event injection, or test-only hooks unless the user explicitly asked for a fixture recording. Next to the embed, state the exact demonstrated commit SHA, the tree and origin that served it, any mode flags or browser-state exceptions, and whether a real model round ran, so reviewers know exactly what the recording proves.

Keep recording separate from publication

• Recording produces local video or screenshots and one .gif artifact only; it never mutates remote state.
• Publication — attaching the GIF to a pull request body with gh --attach, or pushing it to an assets branch and embedding its URL where attach cannot apply — is the separate final step, performed only when the task includes attaching the GIF to a pull request. It never touches the pull request's own branch.
• Preserve the requested recording conditions. A real-server or real-API demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture.
• Never read or expose credential values. Use the application's normal configuration path and a benign demonstration prompt.

Stage the application

A GIF for a specific pull request demonstrates that pull request's tree, so stage per pull request:

1. Require a clean worktree, record its exact commit with git rev-parse HEAD, then build that recorded tree — here, pnpm run build && pnpm run build:web. A GIF recorded against another commit's build misattributes the evidence.
2. Boot one server per port from that tree with fresh scratch ALEGO_HOME, ALEGO_AGENTS_HOME, workspace, and session state. Give the browser a fresh isolated context or profile as well; if the browser workflow cannot create one, clear that origin's cookies and site storage before navigation so persisted client state cannot affect the evidence. Source the root .env for the API key through the application's normal path; never echo the key.
3. Treat one storyboard as one evidence run: every published frame comes from that server and those state roots, workspace, session, and model-backed scenario run. If capture automation fails, discard its frames and rerun from fresh roots; never splice frames from separate runs.
4. When switching between pull requests, stop the old server by PID or an exact match on its command line. A broad pkill -f pattern can match and kill the shell that launched it — including your own.

Record the flow

Follow the available browser-control workflow's setup, interaction, and cleanup instructions. When it exposes recordVideo, enable video on the same controlled context to capture more intermediate frames. Otherwise use screenshot capture within that workflow; video availability does not determine which browser-control workflow to use. Existing user browser state remains an explicit isolation exception.

Only when browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser and state that fallback in the capture notes. In this repository it resolves from apps/web/package.json; do not install another driver or open the user's browser.

Before recording, identify the origin, built or development server, transport, and any mode overrides. When a production default opens a native surface that automation cannot drive, select an official browser-operable production backend through normal application configuration and disclose the override.

Store the script, raw video, timing notes, QA frames, and GIF under the repository's gitignored .playwright-mcp/ directory. Create the run directory first.

Capture video

Match viewport and recordVideo.size explicitly: Playwright otherwise scales the video down to fit 800×800, which can make UI text unreadable.

Configure video through the chosen browser-control workflow. The standalone Playwright fallback uses:

const { chromium } = createRequire(join(repo, 'apps/web/package.json'))('playwright')
const browser = await chromium.launch()
const size = { width: 1440, height: 900 }
const context = await browser.newContext({
  viewport: size,
  recordVideo: { dir: join(runDir, 'videos'), size },
})
try {
  const page = await context.newPage()
  const video = page.video()
  // Navigate and exercise the real application here.
  await context.close()
  await video.saveAs(join(runDir, 'demo.webm'))
} finally {
  await context.close()
  await browser.close()
}

Import createRequire from node:module and join from node:path; set repo and a fresh runDir to absolute paths in the recording script. Retain the page's video handle before closing it. Await context.close() before video.saveAs() or encoding; closing only the browser does not guarantee the video's flush. Each page has its own video: choose the demonstrated page explicitly and do not concatenate unrelated pages or runs. Failed runs are diagnostic only.

Choose a short story with three to six meaningful states. Wait for unique semantic locators before acting; use exact: true for accessible-name equality and exact-text completion predicates that cannot match a prompt echo. Fixed waits may provide a reading hold after the state is verified, but never establish readiness. When capturing video, preserve animations and scrolling.

When demonstrating a tool call, rejection, or recovery, open its detail or trajectory so the video shows the tool identity, status or stable error code, and downstream result. If a transient running state matters, prompt for a slow foreground operation and observe its concrete DOM marker; continuous video captures its intermediate frames. Give the model a short final sentinel to anchor completion. Stop an unnecessarily long real-API run after the demonstrated state is visible.

Capture no secrets, personal data, unrelated tabs, or notifications. Browser video contains page content, not browser chrome; avoid rendering credential-bearing URLs in the application. Review the whole selected interval, including intermediate states. Keep one viewport throughout.

Encode the GIF

Require python3, ffmpeg, and ffprobe. If a media binary is missing, report the dependency instead of installing software without authorization. Export GIF_SKILL_DIR on its own line before using it; an inline assignment cannot affect argument expansion in the same command.

export GIF_SKILL_DIR=/absolute/path/to/this/skill
python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
  /absolute/path/to/demo.webm \
  /absolute/path/to/demo.gif \
  --start 2 --end 32 --speed 2 --final-hold 3 \
  --fps 10 --max-width 1200 --colors 128

--start and --end select one continuous source interval in seconds. Defaults retain the full video at 1× speed and add a two-second final hold. --speed changes playback speed; disclose it and the selected interval beside the GIF so the demo cannot imply measured response latency. Use observed video times, not guessed wall-clock offsets, and preserve the complete cause and outcome of the demonstrated behavior. The final hold repeats the last selected frame. --fps sets the encoded GIF frame rate; increasing it cannot recover motion that the source recording did not capture. Keep the original WebM for QA; do not splice separate runs or synthesize missing states.

The encoder probes WebM container duration, applies trim and speed before palette conversion, and checks encoded duration, animation, width, and byte size. It refuses an empty or out-of-range interval, a selection shorter than two output frames, mode-inappropriate flags, and accidental overwrite. Reduce --max-width, then --colors or --fps for a large artifact; preserve readable text. Use --force only after resolving the exact output path.

Screenshot capture

When continuous video is unavailable or the user requests a storyboard, follow the available browser-control workflow. Capture three to six verified states from one isolated run with the browser's screenshot API. Save returned image bytes directly under one run directory as 00-initial.png, 01-typed.png, and so on; use identical dimensions and crop. For a transient state, poll its DOM marker and capture within the same browser-script call.

python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
  /absolute/path/to/frames /absolute/path/to/demo.gif \
  --durations 1.5,1.5,1.5,3.5 --fps 10 --max-width 1200 --colors 128

One duration applies to every screenshot; otherwise supply one positive duration per frame and hold the settled state longest. Directory input rejects fewer than two frames and mismatched dimensions or duration counts. Video timing flags apply only to video files; --durations and --pattern apply only to screenshot directories.