Create a visual demo document showcasing UI changes. Use when creating a pull request that modifies UI files (App.tsx, CommandPane.tsx, SearchableDropdown.tsx, renderer.ts, CSS, or main.tsx). Uses rodney (headless Chrome) and showboat (demo document builder) to capture screenshots and build an executable markdown walkthrough in demos/.
Create a visual demo document showcasing UI changes using rodney (headless Chrome automation) and showboat (executable demo document builder).
Choose a short kebab-case name describing the UI change (e.g. drag-reorder, export-button, theme-update). The demo will live at demos/<name>/.
mkdir -p demos/<name>
npm run build
npm run dev -- --port 5199 &
DEV_PID=$!
# wait for the server to be ready
sleep 3
Try rodney start --local first. If it fails because it can't find a browser binary, launch the Playwright-bundled Chrome manually and connect rodney to it:
# Option A: rodney finds its own Chrome
uvx rodney start --local
# Option B: rodney can't find a browser — use Playwright's Chrome instead
/root/.cache/ms-playwright/chromium-1194/chrome-linux/chrome \
--headless --no-sandbox --disable-gpu --remote-debugging-port=9222 &
sleep 2
uvx rodney connect localhost:9222
Then navigate to the app:
uvx rodney open http://localhost:5199
uvx rodney waitload
uvx rodney waitstable
uvx showboat init demos/<name>/demo.md "<Title Describing the Change>"
Use showboat note to describe what the PR changes and why it matters.
uvx showboat note demos/<name>/demo.md "Brief description of what changed and why."
Walk through the change step by step. For each step:
Add a note explaining what the user is about to see:
uvx showboat note demos/<name>/demo.md "## Step N: Description"
Interact with the app using rodney to demonstrate the change. Load example dances, click buttons, edit fields, etc. Use rodney wait, rodney waitstable, and rodney sleep as needed between interactions.
Screenshot the result and add it to the demo:
uvx rodney screenshot demos/<name>/screenshot-N.png
uvx showboat image demos/<name>/demo.md "demos/<name>/screenshot-N.png"
Repeat for each meaningful state you want to showcase. Aim for 3-6 screenshots that tell the story of the change.
If relevant, capture test or build output to prove nothing is broken:
uvx showboat exec demos/<name>/demo.md bash "npx vitest run 2>&1 | tail -8"
uvx showboat exec demos/<name>/demo.md bash "npx tsc --noEmit 2>&1 | tail -3"
uvx rodney stop
kill $DEV_PID 2>/dev/null
Stage and commit the entire demos/<name>/ directory along with the rest of the PR changes.
uvx rodney screenshot-el <selector> <file> to capture a specific element instead of the full page.uvx rodney js <expression> to manipulate app state (e.g. load a specific dance, set a beat position).uvx rodney click <selector> and uvx rodney input <selector> <text> to interact with forms.uvx showboat pop demos/<name>/demo.md to remove a bad entry and redo it.uvx showboat verify demos/<name>/demo.md at the end to confirm all exec blocks still reproduce.