heliosian/docs/screenshots.md

Screenshots

tools/screenshot captures pages from the local dev server as PNGs, so humans and agents can verify visual changes. It drives a locally installed Chrome (or Chromium) headless via chromedp; no other browser tooling is required.

Usage

With the server running:

go run ./tools/screenshot -url http://localhost:8080/people -out screenshots/directory.png -wait .sidebar

Flags:

• -url — page to capture (default http://localhost:8080/people)
• -out — output PNG path (default screenshots/capture.png); screenshots/ is gitignored
• -wait — CSS selector that must be visible before capture (default body); pass a selector the page's JavaScript renders (for example .card) to capture after data loads

The capture is a full-page screenshot at a 1280×800 viewport.

Capturing authenticated external sites

Some source material (like the production apps being ported) sits behind a login. The capture browser handles this:

go run ./tools/capturebrowser

launches a headed Chrome with a dedicated profile in ~/.heliosian/capture-profile and DevTools on localhost:9222. Log in to the target site in that window; the session persists in the profile across restarts. The browser stays out of the repo entirely — no cookies or credentials ever land here.

With the capture browser running, add -remote to attach to it instead of launching headless Chrome:

go run ./tools/screenshot -remote -url https://example.com/some/page -out screenshots/existing/page.png -wait body

Each capture opens a fresh tab in the authenticated session, navigates, waits for the -wait selector, screenshots, and closes the tab. Exploring a site is a series of -remote captures over its URLs.

Interactive exploration

tools/browse drives the capture browser one step at a time: each invocation attaches to the current tab, performs at most one action, then captures and reports the resulting URL and title. The tab survives between invocations, so state (login, SPA position) carries across steps.

go run ./tools/browse -nav https://example.com/ -out screenshots/step1.png
go run ./tools/browse -clicksel "a.next" -wait "h1" -out screenshots/step2.png
go run ./tools/browse -click 640,300 -out screenshots/step3.png
go run ./tools/browse -dump

Actions (at most one step's worth per invocation):

• -nav <url> — navigate the tab
• -back — history back
• -clicksel <selector> — click the first match; times out if the selector never appears
• -click <x,y> — click at viewport coordinates, which map 1:1 onto the screenshot (1280×800 viewport)
• -type <text> — insert text into the focused element
• -key <name> — press enter, tab, escape, backspace, or a literal character
• -scroll <px> — scroll vertically, negative for up
• -wait <selector> — block until this selector is visible before capturing
• -dump — print the page HTML (for finding selectors) instead of writing a PNG
• -mobile — emulate a phone viewport (390×844, touch) instead of the desktop 1280×800; click coordinates still map 1:1 onto the screenshot

The capture is the visible viewport, not the full page, so click coordinates read off a screenshot are directly usable. After an action that triggers cross-page navigation, always pass -wait with a selector expected on the destination page — the built-in settle delay is short, and without -wait the capture can race the navigation and show the previous page. The reported URL/title always reflect the final state; when a capture looks stale, re-run with no action to capture the current state.

Invocations must not linger: every run exits by itself within its 15-second internal timeout, leaving the browser and tab untouched.

Leave the browser running between capture sessions — never kill it. In practice logins do not reliably survive a browser restart, and killing it forces a human to sign in again.

Agent recipe

One self-contained command that starts the server, captures, and shuts down:

go run . &
go run ./tools/screenshot -out screenshots/directory.png -wait .sidebar
kill $(lsof -ti :8080)

Then read screenshots/directory.png to inspect the result.