Pull Request Demo

Demos for frontend PRs

Capture only the changed dashboard behavior and post it as a PR comment. Use one or two PNGs for a static visual change; use a 10-20 second WebM recording for an interaction.

REQUIRED SUB-SKILL: Use gram-playwright-cli for browser commands.

Uploads cannot be undone. gh attachments have no delete endpoint, and deleting the comment does not unpublish the asset: it stays live at an unauthenticated URL. The inspect step in section 3 is the last reversible moment in this workflow.

Prerequisites

• Discover the dashboard URL with mise run zero:summary — read the address from the Gram dashboard row (don't assume a port). The same table shows whether each service is RUNNING. A paused worktree shows Database and ClickHouse as STOPPED: run mise run wake (containers, then daemons) and expect two to four minutes. Do not use mise start here, which launches the foreground process-manager TUI and starts only the daemons, leaving the server wedged against a stopped Postgres with no diagnostic. Dev-idp auto-login is enabled, and the local TLS cert is browser-trusted (mkcert CA in the NSS store, set up by mise run zero:tls — rerun that if you see cert errors).

• Use the default project for all flows — mise run seed (the demo seed retargeted at your dev org) provisions exactly one project. Before recording, verify the database is seeded by probing it directly (the connection string is in the Database row of zero:summary; drop its &search_path=public parameter, which psql rejects with invalid URI query parameter):

  psql "postgres://gram:gram@127.0.0.1:<port>/gram?sslmode=disable" -c "SELECT p.slug, om.gram_account_type FROM projects p JOIN organization_metadata om ON om.id = p.organization_id WHERE p.slug = 'default' AND NOT p.deleted;"

  Expect at least one row, every row reading gram_account_type = 'enterprise'. Two rows is normal, because your dev org and the demo org each own a default project. Run mise run seed only on zero rows or a non-enterprise tier.

• Invoke Playwright only through mise run playwright. The task uses the repo configuration and installs Chromium on demand.

• Use ./tools/ffmpeg for the trim, frame-extraction, and GIF steps. The PNG path needs no conversion.

The login flow is credential-less: open the dashboard, click Login if redirected, and wait for /speakeasy. If the first load is blank after a fresh browser install, navigate to the URL again.

0. Namespace everything by PR number

Concurrent agent sessions share a worktree and share the Playwright browser. Key the artifact directory and the Playwright session name on the PR number, so two sessions cannot overwrite each other's files or drive each other's browser:

PR=<pr-number>
DIR=.playwright-cli/pr-demos/$PR
mkdir -p "$DIR"

Use -s=pr-demo-$PR as the session flag in every Playwright command below. If your tooling runs each command in a fresh shell, these variables do not survive between calls: re-export them in every command, or write the literal paths. .playwright-cli/ is gitignored at any depth. Relative paths resolve against your current directory, so stay at the repo root for the whole workflow: a path that resolves differently at capture time and at upload time silently breaks the body rewrite in section 4.

1. Rehearse

mise run playwright -s=pr-demo-$PR open "<dashboard-url>"
mise run playwright -s=pr-demo-$PR snapshot

Navigate to the feature and rehearse the exact interaction using snapshot refs. Keep the browser open. Video recording starts only when requested, so rehearsal does not create footage.

Return to the intended starting state before capture. Hide the fixed development dock with eval before every capture, whether or not it obscures the change: it is dev-only chrome and reads as a product bug to a reviewer. Page navigation removes DOM-only adjustments, so re-apply it after navigating.

2. Capture

Static change

Prepare the exact frame, then capture a viewport or element screenshot:

mise run playwright -s=pr-demo-$PR screenshot --hires --filename="$DIR/demo.png"
mise run playwright -s=pr-demo-$PR screenshot <element-ref> --hires --filename="$DIR/demo-detail.png"

The shared config keeps the CSS viewport at 1440x900 and uses a 2x device scale factor, so --hires produces a crisp 2880x1800 viewport image. Use --full-page only when the changed layout cannot fit in the viewport.

Interaction change

Start recording only after the page is ready:

mise run playwright -s=pr-demo-$PR video-start "$DIR/demo.webm" --size=1440x900
mise run playwright -s=pr-demo-$PR video-show-actions --duration=700 --position=top-right --cursor=pointer

Perform the rehearsed clicks, fills, and navigation with normal CLI commands. The action overlay supplies the pointer, target highlight, and action label; do not inject a fake cursor. Let each important state remain visible long enough to read. When a longer hold is needed:

mise run playwright -s=pr-demo-$PR run-code "async page => await page.waitForTimeout(1000)"

For a meaningful transition, optionally add a short chapter card:

mise run playwright -s=pr-demo-$PR video-chapter "<title>" --description="<what changes>" --duration=1200

Stop recording to flush the WebM, then close the session:

mise run playwright -s=pr-demo-$PR video-stop
mise run playwright -s=pr-demo-$PR close

Every mise run playwright subcommand costs one to two seconds of process startup, and all of it lands in the recording as dead air. Budget for it: a take with six commands and six seconds of deliberate holds runs near thirty seconds. Trim the lead-in and tail before uploading:

./tools/ffmpeg -y -ss <start> -to <end> -i "$DIR/demo.webm" \
  -c:v libvpx -b:v 1M -crf 30 -an "$DIR/demo-trimmed.webm"

The trimmed file is the one you publish, so it is the one section 3 applies to. GitHub serves .webm back as video/webm and renders it as a player, so no further conversion is needed. If a take goes wrong, stop it, restore the starting state in a new session, and record again. Do not include setup, login, exploration, or unrelated page tours.

GIF fallback

Convert only when the reviewer needs the demo inline where a player will not render, notably GitHub notification emails. Convert the trimmed file, not the raw take, so the GIF does not carry the dead air you just removed. Two-pass palette:

./tools/ffmpeg -i "$DIR/demo-trimmed.webm" \
  -vf "fps=10,scale=1200:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
  "$DIR/demo.gif"

A GIF is hard-refused over 10 MB. Increase the scale toward 1440 for small text, or crop to the relevant region before fps= instead of shrinking the whole frame.