pr-demo-gif

name	pr-demo-gif
description	Always use after creating a pull request that proposes user-visible changes.

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 GIF for an interaction.

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

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; if the dashboard or server is STOPPED, start the stack with mise start first. 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 one row with gram_account_type = 'enterprise'. Otherwise run mise run seed before continuing.

3. Invoke Playwright only through mise run playwright. The task uses the repo configuration and installs Chromium on demand.
4. Use ./tools/ffmpeg for GIF 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.

1. Rehearse

Use a named session so every command reaches the same browser:

mise run playwright -s=pr-demo open "<dashboard-url>"
mise run playwright -s=pr-demo 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 an irrelevant fixed development dock with eval only if it obscures the changed behavior; page navigation removes DOM-only adjustments.

2. Capture

Create ignored artifact directories:

mkdir -p .playwright-cli/pr-demos /tmp/pr-demo

Static change

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

mise run playwright -s=pr-demo screenshot --hires --filename=.playwright-cli/pr-demos/demo.png
mise run playwright -s=pr-demo screenshot <element-ref> --hires --filename=.playwright-cli/pr-demos/demo-detail.png

The shared config keeps the CSS viewport at 1440×900 and uses a 2× device scale factor, so --hires produces a crisp 2880×1800 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 video-start .playwright-cli/pr-demos/demo.webm --size=1440x900
mise run playwright -s=pr-demo 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 run-code "async page => await page.waitForTimeout(1000)"

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

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

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

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

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.

3. Convert and inspect

Convert interaction footage in the scratchpad with a two-pass palette:

./tools/ffmpeg -ss <trim-seconds> -i .playwright-cli/pr-demos/demo.webm \
  -vf "fps=10,scale=1200:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
  /tmp/pr-demo/demo.gif

Inspect the final PNG or GIF before publishing. Confirm it shows the changed behavior, contains no sensitive data, and the GIF is under roughly 10 MB. Increase the scale toward 1440 for small text, or crop to the relevant region before fps= instead of shrinking the whole frame.

4. Host in a secret gist

GitHub does not expose PR attachment upload through its API. Create a secret gist from a text placeholder, then push the binary through the gist repository:

cd /tmp/pr-demo
echo "demo" > placeholder.md
gh gist create placeholder.md --desc "PR demo"
git clone https://gist.github.com/<gist-id>.git gist
cp demo.gif gist/
cd gist
git add demo.gif
git commit -m "add demo gif"
git -c credential.helper='!gh auth git-credential' push

For screenshots, copy the PNG from .playwright-cli/pr-demos/ instead. Secret is the default; gh gist create has no --secret flag. Never pass a binary directly to gh gist create, because it silently fails. The raw URL is:

https://gist.githubusercontent.com/<user>/<gist-id>/raw/<file>

5. Post the PR comment

gh pr comment <pr> --body "$(cat <<'EOF'
### Demo

![demo](https://gist.githubusercontent.com/<user>/<gist-id>/raw/demo.gif)

What it shows:
1. <starting state>
2. <interaction>
3. <changed behavior>
EOF
)"

Keep the numbered list short and aligned with the visible steps.