Local docs and screenshot workflow
How to preview the handbook while you're editing it, and how the screenshots get made.
Building the handbook
From the PlayNext worktree:
pnpm docs:sync # pull in the PlayGo-owned pages and OpenAPI
pnpm docs:start # local preview with live reload
pnpm docs:check # sync, validate links and images, then build
docs:sync finds the PlayGo docs branch, copies its curated publish set, generates the Go package reference from package comments, and copies the canonical OpenAPI file.
If your PlayGo worktree isn't in the expected sibling location, set PLAYGO_DIR and the script will use that instead. The error message lists every path it tried, so you don't have to go reading the script to work out what it wanted.
Capturing screenshots
pnpm docs:capture
This starts Vite with VITE_USE_MSW=true, logs in as the fake superadmin@example.com, walks the documented admin screens, and writes the images plus a manifest into docs-site/static/img/operator/admin/.
Nothing here touches a real system. That's the point, and it's worth knowing why each safeguard exists:
- No PlayGo backend or database is contacted — everything is served by MSW fixtures.
- All credentials and identities in the fixtures are invented. No real player ever appears in a screenshot.
- A fixed desktop viewport and reduced motion keep captures deterministic, so a rerun doesn't produce a diff caused by an animation frame.
- The script fails if login, navigation, or an expected control is missing. A capture run that half-worked would silently publish a screenshot of a broken screen, which is worse than no screenshot.
- The docs check fails if a page references an image that doesn't exist.
Spot-checking in a browser
After capturing, point Surf or Chrome DevTools at the same local Vite server to check the accessibility tree, the console, and how the page is framed.
When writing automation selectors, prefer roles and labels over CSS classes. Classes change every time someone restyles something; a role or a label changes only when the meaning changes — which is exactly when you want your test to notice.
Updating a screenshot
- Change the UI and its tests.
- Update the operator page if the meaning or the sequence of steps changed. A new screenshot with stale instructions beside it is still wrong.
- Update the capture case only if the route or a control changed.
- Run
pnpm docs:capture. - Look at the image and at
manifest.jsonbefore committing. Actually look — a capture can succeed and still frame the wrong thing. - Run
pnpm docs:checkandpnpm check.