Portal screenshots: capture script + docs site embeds

[cjimti]

Summary

Brings api-test up to parity with mcp-test on portal screenshots: a Playwright-driven capture script, the 18 PNGs it produces, the home-page carousel, and inline embeds across docs/operations/portal.md.

The home page previously had a placeholder note saying "the portal-screenshots carousel that mcp-test ships in this template is omitted here" — that's gone; the carousel is live.

What's in here

scripts/screenshots/ — the capture pipeline

A standalone Node project (Playwright + pg) that:

1. Seeds Postgres deterministically. Truncates audit_events / audit_payloads / api_keys, then inserts 100 fixed-PRNG audit events spread over the last 75 minutes (skewed toward recent), 20 of them with full payload rows, plus 3 demo API keys. Same input → same PNGs, so git diffs only show real visual changes.
2. Drives Chromium through every portal page. Sets the theme (localStorage["api-test-theme"]) and API key (sessionStorage["api-test-api-key"]) before navigation, captures at 1440×900 @ 2× DPR, and writes to docs/images/portal/<slug>-{light,dark}.png.
3. Handles non-deep-linkable state. Audit detail panel selection is React component state, not URL-driven, so the audit-detail capture clicks the first row matching a seeded payload event before snapping.

Adapted from mcp-test's screenshots.mjs to api-test's reality:

• HTTP API columns (method / path / status / route_name / endpoint_group) instead of MCP's tool_name / tool_group.
• audit_payloads uses BYTEA bodies + JSONB headers / query (not the MCP shape with response_result / notifications).
• Storage keys: api-test-api-key, api-test-theme, APITEST_DEV_KEY, APITEST_BASE_URL, APITEST_DATABASE_URL.
• Drops the four mcp-only captures (audit-compare, audit-livetail, audit-jsonb, tools-tryit, wellknown) — those features don't exist in api-test's M3 portal.
• Adds api-test-specific captures: endpoints (catalog), endpoints-detail (deep-linked to /portal/endpoints/flaky so the right-pane card renders), and about.

make screenshots

Mirrors the mcp-test target: sources .env.dev for APITEST_DEV_KEY, runs npm install on first invocation, executes screenshots.mjs against SHOTS_BASE_URL (default http://localhost:8080).

Captures — 18 PNGs

9 screens × 2 themes:

slug	shows
login	Sign-in screen (OIDC button + API key form). Captured but kept out of the carousel rotation.
dashboard	1-hour totals (87 calls / 72 successes / 15 errors / 17.2% rate) + recent activity table.
endpoints	Catalog of all 14 registered routes grouped by behavior.
endpoints-detail	Right-pane detail card for flaky (method/path/group/auth/description/curl hint).
audit	Filter row + paginated event table, showing 100 of 100.
audit-detail	First row clicked: timestamp / duration / request id / identity / remote / bytes plus request_headers / response_headers JSON trees with [redacted] Authorization and Cookie.
keys	API key listing with the 3 seeded keys (ci-runner, alice-personal, demo-only).
config	Read-only YAML view with secrets masked.
about	Build info + well-known metadata (api endpoint, OIDC issuer, audience).

docs/overrides/home.html

Adds the carousel + lightbox markup between the hero and the capabilities grid. Reuses the existing shots.js and extra.css (already wired into mkdocs.yml), so no new assets needed. Captions are api-test-specific (HTTP requests, not MCP tool calls).

docs/operations/portal.md

Drops the stale "Lands in M3" admonition (M3 shipped in #2). Adds inline #only-light / #only-dark mkdocs-material image embeds at every page section so readers see the actual UI alongside the prose.

Verification

• make screenshots runs end-to-end in ~10 s against make dev's stack and produces all 18 PNGs.
• make docs (mkdocs build --strict) passes — no broken image references, no Jinja errors in the carousel template.
• Spot-checked dashboard-light.png, audit-detail-dark.png, endpoints-detail-light.png: seeded data renders cleanly in both themes; redacted headers show as expected.

Test plan

• make dev in one terminal, make screenshots in another → all 18 PNGs land in docs/images/portal/.
• make docs-serve → home page carousel cycles through all 8 slides; click any frame to open the lightbox; arrow keys / side rails navigate; Esc closes.
• Toggle the docs site between light and dark — every embed under operations/portal.md swaps the matching PNG.
• Re-run make screenshots on an unchanged binary and confirm git status reports no diff (deterministic seed).