Install in seconds

Install this skill

Copy the command and run it in your terminal. You can review the source before installing.

terminal

git clone https://github.com/rengwu/wayfinder-maps

Works with Git. The repository opens in your current directory.

✅

QualityGo

Verify Wayfinder Maps

by rengwu

Build, launch, and drive the wayfinder-maps server with a headless browser to verify changes end-to-end. Suitable for validating map visualization, interactions, and cross-browser behavior.

59 stars1 forksAdded 2026/07/16

View source on GitHub Download ZIP

agent-skillsgo

Documentation

README

From the original repository

Verifying wayfinder-maps

Build & fixture

go build -o /tmp/wayfinder-maps ./cmd/wayfinder-maps

There is no sample map in the repo. Create an effort dir with map.md + tickets/NN-slug.md. Ticket format: YAML frontmatter (type:, blocked_by: [01], claimed_by:, undermined_by: [NN]) then # Title, ## Question; a ## Answer section with prose = resolved, ## Ruled out = out_of_scope. Map format: # Name, ## Destination, and fog under ## Not yet specified as - **Title.** clears-with: NN. Sanity-check the fixture with wayfinder-maps status <effort-dir>.

Launch

PORT=78xx /tmp/wayfinder-maps serve <effort-dir>   # pick a fresh port EVERY time

Gotcha: the user often has an instance (binary wm) already listening; a bind failure only shows in the log while curl happily talks to the OLD server — check the serve log says "serving", don't trust the port being answerable.

Dev mode: WAYFINDER_DEV=cmd/wayfinder-maps/web (path to web/ from cwd) serves the frontend from disk with Cache-Control: no-store instead of the go:embed copy.

Drive (GUI surface)

Playwright's cached headless shell works without a full playwright install:

cd <scratch> && npm i playwright-core
# executablePath: ~/Library/Caches/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-mac-arm64/chrome-headless-shell

Wait ~4s after goto: the constellation fades in over 2.2s (a plain --screenshot --virtual-time-budget capture shows HUD but NO stars — artifact, not a bug).
App state is inside ES modules (not on window). To click a specific star, find it by pixel colour on the canvas (frontier glow is gold) — layout is deterministic (fixed PRNG seed), so positions repeat across runs.
Live-reload probe: append ## Answer\ntext to a ticket while the map is open; the 1.5s poller updates the HUD counts in ~2-3s.
Recents on the splash come from the user's real config — don't dismiss entries.

Flows worth driving: map render (all statuses + fog + edges), click star → panel markdown, data-goto cross-ticket link, Escape closes, wheel zoom (labels thin out), back button → splash/maplist.

WebKit

npx playwright-core install webkit (~77MB, cached in ms-playwright) then require("playwright-core").webkit.launch() — no executablePath needed. Covered headlessly: full map render, the label-alpha fade workaround (capture a frame ~600ms into loadMap: labels must be dim WITH the stars, not opaque over them), touch tap via a hasTouch context, wheel zoom, panel markdown.

NOT reachable headlessly — manual Safari checklist:

Trackpad pinch zooms the map, not the page (gesture* events; Playwright's WebKit cannot construct GestureEvent, and Chromium never fires them).
Touch pan/pinch on a real iOS device or simulator.