design-spine 0.1.0 → 0.2.1

package/README.md

@@ -14,7 +14,7 @@ Most UI gets built and checked in one state: the happy path, at desktop width, i
 
 ## Quick start
 
-Requires [Bun](https://bun.sh) 1.3+ and a running copy of your app.
+Requires a running copy of your app. The CLI runs on [Bun](https://bun.sh), which the npm install bundles, so you do not install it yourself. A Bun 1.3+ already on your PATH is used first.
 
 ```bash
 npm install -D design-spine
@@ -72,12 +72,30 @@ In CI, add the action after the step that starts your app, and commit `design-sp
 
 ```yaml
 - run: npm run build && (npm start &) && npx wait-on http://localhost:3000
-- uses: forbiddenlink/design-spine@main
+- uses: forbiddenlink/design-spine@v0.2.1
   with:
     base-url: http://localhost:3000
 ```
 
-The job fails when any screen changes from its approved baseline, and uploads the run as an artifact. To accept a change, download the artifact into `.design-spine/runs/`, run `spine review --run <id>`, approve, then `spine approve --run <id>` and commit the new baselines. Fonts render differently on macOS and Linux, so approve baselines from a CI (Linux) run.
+The job fails when any screen changes from its approved baseline. The action writes a pass/fail summary with a table of changed tiles to the job summary, and uploads two artifacts: `design-spine-run` (the captures) and `design-spine-report` (a single offline HTML file with the screenshots). Reviewers open the report instead of unzipping the run.
+
+To also post that summary on the pull request, set `comment: "true"` and grant the job write access to pull requests. The action keeps one comment, marked `<!-- design-spine -->`, and edits it on each push:
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+steps:
+  - uses: forbiddenlink/design-spine@v0.2.1
+    with:
+      comment: "true"
+```
+
+Comments are skipped outside `pull_request` events. On pull requests from forks the token is read-only, so the comment step fails without failing the job. The job summary still appears.
+
+To accept a change, download the artifact into `.design-spine/runs/`, run `spine review --run <id>`, approve, then `spine approve --run <id>` and commit the new baselines. Fonts render differently on macOS and Linux. Capture with `spine capture --docker` and approve those baselines; the action also captures in that image by default, so the two match pixel for pixel. The first run builds a local image, and amd64 emulation on Apple silicon is slower. See [Matching CI baselines](docs/USAGE.md#matching-ci-baselines).
+
+Upgrading from v0.1.0: that version captured with the runner's own Chromium and fonts. Baselines approved from those runs differ from docker captures, so either approve new baselines from a `--docker` capture, or keep the old behavior with `docker: "false"`.
 
 ## Commands
 
@@ -93,6 +111,7 @@ The job fails when any screen changes from its approved baseline, and uploads th
 | `report` | Self-contained HTML record of a review |
 | `lint` | Ratchet on arbitrary Tailwind values such as `w-[37px]` |
 | `status` | Writes `.design-spine/status.json` for dashboards |
+| `mcp` | Read-only MCP server over stdio for agents; see [docs/USAGE.md](docs/USAGE.md#use-from-an-mcp-client) |
 
 Full reference: [docs/USAGE.md](docs/USAGE.md).
 
@@ -100,18 +119,19 @@ Full reference: [docs/USAGE.md](docs/USAGE.md).
 
 | | Design Spine | Chromatic, Percy, Argos | Playwright `toHaveScreenshot` |
 |---|---|---|---|
-| Runs locally, no upload | Yes | No | Yes |
-| Plans the route x state matrix from your app | Yes | No | No |
-| Human approval ledger per screenshot | Yes | Yes, in the cloud | No |
-| Coverage gaps shown as unfinished | Yes | No | No |
-| Needs Storybook | No | Chromatic: mostly | No |
-| Pricing | Free | Per snapshot | Free |
+| Screenshots stay on your machine | Yes | No, uploaded to a hosted service | Yes |
+| Plans the route x state matrix from your app | Yes | No, captures the stories or tests you write | No |
+| Human approval per screenshot | Yes, local review UI | Yes, in the vendor's web app | No, `--update-snapshots` accepts all at once |
+| Needs an account | No | Yes | No |
+| Pricing | Free, MIT | Free tier, then billed per screenshot | Free |
+
+Checked 2026-10-18 against each vendor's docs and pricing pages. Argos is open source; Chromatic works with Storybook, Vitest, Playwright and Cypress.
 
 ## Limits
 
 - Next.js App Router only for `plan`. Other apps can write the manifest by hand.
 - Chromium only. Tested on macOS, and the test suite runs on Linux in CI. Windows is not verified.
-- Requires Bun to run the CLI.
+- The CLI runs on Bun. The npm package bundles Bun 1.3.13 for macOS, Linux and Windows on x64 and arm64; other platforms need Bun 1.3+ installed. `--docker` also needs Docker and downloads a 2.6 GB image once.
 
 ## License
 

package/bin/resolve-bun.d.ts

@@ -0,0 +1,23 @@
+export const MIN_MAJOR: number
+export const MIN_MINOR: number
+export function satisfiesMinimum(versionText: string): boolean
+export function platformPackage(target: {
+  platform: string
+  arch: string
+  musl?: boolean
+}): string | undefined
+export function bundledBunPath(options?: {
+  platform?: string
+  arch?: string
+  musl?: boolean
+  resolve?: (id: string) => string
+  exists?: (path: string) => boolean
+}): string | undefined
+export function resolveBun(options?: {
+  run?: (
+    command: string,
+    args: string[],
+    options: { encoding: 'utf8'; timeout: number },
+  ) => { error?: Error; status: number | null; stdout?: string | null }
+  bundled?: () => string | undefined
+}): string | undefined

package/bin/resolve-bun.js

@@ -0,0 +1,66 @@
+// Finds a Bun >= 1.3: one on PATH first, else the binary from the bundled @oven/bun-<platform> package.
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+export const MIN_MAJOR = 1
+export const MIN_MINOR = 3
+
+export function satisfiesMinimum(versionText) {
+  const [major = 0, minor = 0] = String(versionText).trim().split('.').map(Number)
+  return major > MIN_MAJOR || (major === MIN_MAJOR && minor >= MIN_MINOR)
+}
+
+// Maps node's platform/arch to the @oven/bun-* package that holds the real binary.
+export function platformPackage({ platform, arch, musl = false }) {
+  const cpu = { x64: 'x64', arm64: 'aarch64' }[arch]
+  const os = { darwin: 'darwin', linux: 'linux', win32: 'windows' }[platform]
+  if (!cpu || !os) return undefined
+  return `@oven/bun-${os}-${cpu}${os === 'linux' && musl ? '-musl' : ''}`
+}
+
+function isMusl() {
+  if (process.platform !== 'linux') return false
+  try {
+    return !process.report.getReport().header.glibcVersionRuntime
+  } catch {
+    return false
+  }
+}
+
+// Oven's `bun` package ships a stub bin until its postinstall runs, which pnpm 12 and
+// --ignore-scripts skip, and pnpm 12 fails the whole install over that script. So we depend on
+// the script-free platform packages directly; they carry the real binary.
+export function bundledBunPath({
+  platform = process.platform,
+  arch = process.arch,
+  musl = isMusl(),
+  resolve = createRequire(import.meta.url).resolve,
+  exists = existsSync,
+} = {}) {
+  const name = platformPackage({ platform, arch, musl })
+  if (!name) return undefined
+  try {
+    const pkgDir = dirname(resolve(`${name}/package.json`))
+    const file = join(pkgDir, 'bin', platform === 'win32' ? 'bun.exe' : 'bun')
+    return exists(file) ? file : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function bunVersion(command, run) {
+  const result = run(command, ['--version'], { encoding: 'utf8', timeout: 10000 })
+  if (result.error || result.status !== 0) return undefined
+  return result.stdout ?? ''
+}
+
+// Returns the command to run Bun with, or undefined when no usable Bun exists.
+export function resolveBun({ run = spawnSync, bundled = bundledBunPath } = {}) {
+  const onPath = bunVersion('bun', run)
+  if (onPath !== undefined && satisfiesMinimum(onPath)) return 'bun'
+  const file = bundled()
+  if (file && satisfiesMinimum(bunVersion(file, run) ?? '')) return file
+  return undefined
+}

package/bin/spine.js

@@ -1,15 +1,27 @@
 #!/usr/bin/env node
 // Thin launcher: Design Spine needs Bun (HTML imports, Bun.serve), so hand off to it.
-import { spawnSync } from 'node:child_process'
+import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { resolveBun } from './resolve-bun.js'
 
 const MESSAGE = 'Design Spine runs on Bun 1.3+. Install: curl -fsSL https://bun.sh/install | bash'
 const cli = fileURLToPath(new URL('../src/cli.ts', import.meta.url))
-const version = spawnSync('bun', ['--version'], { encoding: 'utf8' })
-const [major = 0, minor = 0] = (version.stdout ?? '').trim().split('.').map(Number)
-if (version.error || version.status !== 0 || major < 1 || (major === 1 && minor < 3)) {
+const bun = resolveBun()
+if (!bun) {
   console.error(MESSAGE)
   process.exit(1)
 }
-const result = spawnSync('bun', [cli, ...process.argv.slice(2)], { stdio: 'inherit' })
-process.exit(result.status ?? 1)
+const child = spawn(bun, [cli, ...process.argv.slice(2)], { stdio: 'inherit' })
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => child.kill(signal))
+child.on('error', () => {
+  console.error(MESSAGE)
+  process.exit(1)
+})
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.removeAllListeners(signal)
+    process.kill(process.pid, signal)
+  } else {
+    process.exit(code ?? 1)
+  }
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-spine",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Screenshot every route and state of your Next.js app, then approve each screen by eye. Local, no account.",
   "license": "MIT",
   "author": "Elizabeth Stein",
@@ -39,21 +39,34 @@
     "build": "bun build --compile src/cli.ts src/lib/comparison-worker.ts --external 'chromium-bidi/*' --external electron --define 'import.meta.spineWorker=\"./lib/comparison-worker.js\"' --outfile dist/spine",
     "spine": "bun src/cli.ts",
     "test": "vitest run",
+    "test:visual": "bun scripts/visual-tests.ts",
+    "test:visual:update": "bun scripts/visual-tests.ts --update",
     "lint": "biome check .",
     "format": "biome format --write ."
   },
   "dependencies": {
     "@axe-core/playwright": "^4.13.0",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "commander": "^15.0.0",
     "pixelmatch": "^7.2.0",
     "playwright": "^1.63.0",
     "pngjs": "^7.0.0"
   },
+  "optionalDependencies": {
+    "@oven/bun-darwin-aarch64": "1.3.13",
+    "@oven/bun-darwin-x64": "1.3.13",
+    "@oven/bun-linux-aarch64": "1.3.13",
+    "@oven/bun-linux-aarch64-musl": "1.3.13",
+    "@oven/bun-linux-x64": "1.3.13",
+    "@oven/bun-linux-x64-musl": "1.3.13",
+    "@oven/bun-windows-aarch64": "1.3.13",
+    "@oven/bun-windows-x64": "1.3.13"
+  },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.15",
-    "@types/bun": "^1.4.2",
-    "@types/pngjs": "^6.0.5",
-    "typescript": "^7.0.2",
-    "vitest": "^5.0.3"
+    "@biomejs/biome": "2.6.4",
+    "@types/bun": "1.4.4",
+    "@types/pngjs": "6.0.5",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
   }
 }

package/src/assets.d.ts

@@ -1,3 +1,13 @@
 interface ImportMeta {
   readonly spineWorker?: string
 }
+
+declare module '*.css' {
+  const path: string
+  export default path
+}
+
+declare module '*ui/review.js' {
+  const path: string
+  export default path
+}

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { createHash } from 'node:crypto'
 import {
+  appendFileSync,
   existsSync,
   mkdirSync,
   readdirSync,
@@ -15,6 +16,7 @@ import { loadManifest, planJobs, runCapture } from './lib/capture.ts'
 import { collectDesignRules } from './lib/critique.ts'
 import { runCritique } from './lib/critique-run.ts'
 import { compareImages } from './lib/diff.ts'
+import { captureInDocker, manifestInRoot } from './lib/docker.ts'
 import { unfinishedLines } from './lib/doctor.ts'
 import { evaluateGate } from './lib/gate.ts'
 import {
@@ -50,12 +52,14 @@ import {
   writeJson,
 } from './lib/runs.ts'
 import { startReviewServer } from './lib/server.ts'
+import { buildSummary } from './lib/summary.ts'
 import type { Provenance } from './lib/types.ts'
+import { runMcp } from './mcp.ts'
 
 const root = resolve(process.env.SPINE_CWD ?? process.cwd())
 const program = new Command('spine')
   .description('Design gate for Next.js repos')
-  .version('0.1.0')
+  .version('0.2.1')
   // Usage errors exit 2 so they never look like doctor's exit 1 (unfinished coverage).
   .exitOverride((err) => process.exit(err.exitCode === 0 ? 0 : 2))
 
@@ -199,35 +203,66 @@ program
   .option('--manifest <file>', 'manifest path', 'design-spine.json')
   .option('--routes <list>', 'comma-separated route paths to limit to')
   .option('--concurrency <n>', 'parallel tiles', '3')
+  .option(
+    '--docker',
+    'capture inside a pinned Linux x64 Playwright image so baselines match ubuntu-latest CI',
+  )
   .action(
-    guard(async (o: { base?: string; manifest: string; routes?: string; concurrency: string }) => {
-      const concurrency = numberOption(o.concurrency, 'concurrency', 1, 32)
-      const mpath = resolve(root, o.manifest)
-      if (!existsSync(mpath))
-        throw new Error(`Manifest ${o.manifest} not found. Run \`spine plan\`.`)
-      const raw = JSON.parse(readFileSync(mpath, 'utf8')) as { baseUrl?: unknown }
-      const baseUrl = o.base ?? (typeof raw.baseUrl === 'string' ? raw.baseUrl : '')
-      if (!baseUrl)
-        throw new Error(`No base URL. Pass --base <url> or set baseUrl in ${o.manifest}.`)
-      const { run, dir, skipped } = await runCapture({
-        root,
-        manifest: validateManifest({ ...raw, baseUrl }, root),
-        baseUrl,
-        routes: o.routes?.split(',').map((s) => s.trim()),
-        concurrency,
-        log: console.log,
-      })
-      for (const s of skipped) console.warn(`skipped ${s}`)
-      const flagged = run.tiles.filter(isFlagged).length
-      console.log(`Run ${run.id}: ${run.tiles.length} tiles, ${flagged} flagged -> ${dir}`)
-      const errored = run.tiles.filter((t) => t.error)
-      if (errored.length) {
-        console.error(`${errored.length} of ${run.tiles.length} tiles failed to capture:`)
-        for (const t of errored.slice(0, 5)) console.error(`  ${t.id}: ${t.error}`)
-        if (errored.length > 5) console.error(`  ${errored.length - 5} more, see run.json`)
-        process.exit(1)
-      }
-    }),
+    guard(
+      async (o: {
+        base?: string
+        manifest: string
+        routes?: string
+        concurrency: string
+        docker?: boolean
+      }) => {
+        const concurrency = numberOption(o.concurrency, 'concurrency', 1, 32)
+        const mpath = resolve(root, o.manifest)
+        if (!existsSync(mpath))
+          throw new Error(`Manifest ${o.manifest} not found. Run \`spine plan\`.`)
+        const raw = JSON.parse(readFileSync(mpath, 'utf8')) as { baseUrl?: unknown }
+        const baseUrl = o.base ?? (typeof raw.baseUrl === 'string' ? raw.baseUrl : '')
+        if (!baseUrl)
+          throw new Error(`No base URL. Pass --base <url> or set baseUrl in ${o.manifest}.`)
+        if (o.docker) {
+          validateManifest({ ...raw, baseUrl }, root)
+          const code = await captureInDocker({
+            root,
+            manifest: manifestInRoot(root, o.manifest),
+            base: baseUrl,
+            hostBase: baseUrl,
+            routes: o.routes,
+            concurrency: String(concurrency),
+            log: console.log,
+          })
+          process.exit(code)
+        }
+        const { run, dir, skipped } = await runCapture({
+          root,
+          manifest: validateManifest({ ...raw, baseUrl }, root),
+          baseUrl,
+          // Set by --docker, where the container reaches the host through another name.
+          recordedBaseUrl: process.env.SPINE_RECORDED_BASE_URL || undefined,
+          routes: o.routes?.split(',').map((s) => s.trim()),
+          concurrency,
+          log: console.log,
+        })
+        for (const s of skipped) console.warn(`skipped ${s}`)
+        const flagged = run.tiles.filter(isFlagged).length
+        // Inside --docker the run lives under /work; print where the host will find it.
+        const shown = process.env.SPINE_HOST_ROOT
+          ? dir.replace(/^\/work(?=\/|$)/, process.env.SPINE_HOST_ROOT)
+          : dir
+        console.log(`Run ${run.id}: ${run.tiles.length} tiles, ${flagged} flagged -> ${shown}`)
+        const errored = run.tiles.filter((t) => t.error)
+        if (errored.length) {
+          console.error(`${errored.length} of ${run.tiles.length} tiles failed to capture:`)
+          for (const t of errored.slice(0, 5)) console.error(`  ${t.id}: ${t.error}`)
+          if (errored.length > 5) console.error(`  ${errored.length - 5} more, see run.json`)
+          process.exit(1)
+        }
+      },
+    ),
   )
 
 program
@@ -352,17 +387,30 @@ program
     }),
   )
 
+interface DiffOptions {
+  run: string
+  threshold: string
+  strict?: boolean
+  requireBaselines?: boolean
+  summary?: string
+}
+
 program
   .command('diff')
   .description('Compare a run to baselines; exit 1 when any tile exceeds the threshold')
   .option('--run <id>', 'run id or path', 'latest')
   .option('--threshold <ratio>', 'changed-pixel ratio', '0.002')
+  .option(
+    '--require-baselines',
+    'fail when a captured tile has no baseline, without requiring a new review',
+  )
   .option(
     '--strict',
     'also require complete coverage, human approval and compatible baseline provenance',
   )
+  .option('--summary <file>', 'append a GitHub-flavoured Markdown summary to this file')
   .action(
-    guard(async (o: { run: string; threshold: string; strict?: boolean }) => {
+    guard(async (o: DiffOptions) => {
       const threshold = numberOption(o.threshold, 'threshold', 0, 1, false)
       const dir = resolveRunDir(root, o.run)
       const run = loadRun(dir)
@@ -401,6 +449,7 @@ program
         }
         if (!existsSync(bp)) {
           rows.push({ id: t.id, result: 'new', ratio: '-' })
+          if (o.requireBaselines) failed++
           continue
         }
         const pinned = baselineManifest?.tiles[t.id]?.imageHash
@@ -444,11 +493,11 @@ program
       const w = Math.max(4, ...rows.map((r) => r.id.length))
       console.log(`${'tile'.padEnd(w)}  ${'result'.padEnd(12)}  ratio`)
       for (const r of rows) console.log(`${r.id.padEnd(w)}  ${r.result.padEnd(12)}  ${r.ratio}`)
-      console.log(`\n${rows.length} tiles, ${failed} over threshold ${threshold}`)
+      console.log(`\n${rows.length} tiles, ${failed} failed comparisons; threshold ${threshold}`)
       const fresh = rows.filter((r) => r.result === 'new').length
       if (fresh && !o.strict)
         console.warn(
-          `${fresh} tiles have no baseline. Run \`spine approve\` after review, or use --strict.`,
+          `${fresh} tiles have no baseline. Run \`spine approve\` after review. Use --require-baselines to fail on missing baselines, or --strict for complete sign-off.`,
         )
       const reasons = o.strict
         ? evaluateGate(
@@ -465,9 +514,20 @@ program
       writeJson(join(dir, 'diff.json'), {
         threshold,
         rows,
-        policy: o.strict ? 'strict' : 'pixels',
+        policy: o.strict ? 'strict' : o.requireBaselines ? 'require-baselines' : 'pixels',
         gateReasons: reasons,
       })
+      if (o.summary)
+        appendFileSync(
+          resolve(root, o.summary),
+          buildSummary({
+            rows,
+            threshold,
+            policy: o.strict ? 'strict' : o.requireBaselines ? 'require-baselines' : 'pixels',
+            gateReasons: reasons,
+            failed,
+          }),
+        )
       process.exit(failed ? 1 : 0)
     }),
   )
@@ -576,4 +636,9 @@ program
     }),
   )
 
+program
+  .command('mcp')
+  .description('Serve a read-only MCP server over stdio (spine_status, spine_list_tiles)')
+  .action(guard(() => runMcp(root)))
+
 await program.parseAsync(process.argv)

package/src/lib/capture.ts

@@ -3,11 +3,12 @@ import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import AxeBuilder from '@axe-core/playwright'
-import { type Browser, type BrowserContext, chromium } from 'playwright'
+import { type Browser, type BrowserContext, chromium, type Request } from 'playwright'
 import { PNG } from 'pngjs'
 import { findBlankBoxes } from './blank.ts'
 import { fingerprint, validateManifest } from './manifest.ts'
 import { routeSlug, tileFilename, tileId } from './names.ts'
+import { redactUrls, safeUrl } from './redact.ts'
 import { fillParams } from './routes.ts'
 import { setLatest, spineDir, writeJson } from './runs.ts'
 import type {
@@ -265,6 +266,10 @@ function fixedOverlays(): string[] {
     )
 }
 
+export function requestFailureCode(errorText?: string): string {
+  return errorText?.match(/^net::ERR_[A-Z0-9_]+\b/)?.[0] ?? 'Network request failed'
+}
+
 /** Wait before retrying a 429: Retry-After seconds (max 10), else 2s. */
 export function retryDelayMs(retryAfter?: string): number {
   const seconds = retryAfter?.trim() ? Number(retryAfter) : Number.NaN
@@ -340,6 +345,7 @@ async function captureTile(
     textClipped: [],
   }
   let ctx: BrowserContext | undefined
+  let collectingRequests = true
   let stage = 'context initialization'
   try {
     ctx = await browser.newContext({
@@ -354,22 +360,52 @@ async function captureTile(
     const page = await ctx.newPage()
     page.setDefaultTimeout(manifest.capture?.timeoutMs ?? 5000)
     if (manifest.capture?.clock) await page.clock.setFixedTime(new Date(manifest.capture.clock))
+    // Requests answered by a state mock carry the status the author chose, so they are not
+    // request failures even when that status is 500.
+    const mocked = new WeakSet<Request>()
     for (const response of job.state.responses ?? []) {
-      await page.route(response.url, (route) =>
-        route.fulfill({
+      await page.route(response.url, (route) => {
+        mocked.add(route.request())
+        return route.fulfill({
           status: response.status,
           body: response.body ?? '',
           contentType: response.contentType ?? 'text/plain',
-        }),
-      )
+        })
+      })
     }
     page.on('console', (m) => {
       if (m.type() === 'error' && tile.consoleErrors.length < 20)
-        tile.consoleErrors.push(m.text().slice(0, 200))
+        tile.consoleErrors.push(redactUrls(m.text()).slice(0, 200))
     })
     page.on('pageerror', (e) => {
-      if (tile.pageErrors.length < 20) tile.pageErrors.push(e.message.slice(0, 200))
+      if (tile.pageErrors.length < 20) tile.pageErrors.push(redactUrls(e.message).slice(0, 200))
     })
+    const navigationStarted = performance.now()
+    const recordedRequests = new WeakSet<Request>()
+    const requestErrors: NonNullable<Tile['requestErrors']> = []
+    tile.requestErrors = requestErrors
+    const recordRequestError = (request: Request, status?: number): void => {
+      if (
+        !collectingRequests ||
+        mocked.has(request) ||
+        recordedRequests.has(request) ||
+        requestErrors.length >= 20
+      )
+        return
+      recordedRequests.add(request)
+      requestErrors.push({
+        url: safeUrl(request.url()).slice(0, 500),
+        resourceType: request.resourceType(),
+        ...(status !== undefined
+          ? { status }
+          : { failure: requestFailureCode(request.failure()?.errorText) }),
+        elapsedMs: Math.round(performance.now() - navigationStarted),
+      })
+    }
+    page.on('response', (response) => {
+      if (response.status() >= 400) recordRequestError(response.request(), response.status())
+    })
+    page.on('requestfailed', (request) => recordRequestError(request))
     // `load` first, then a bounded wait for network idle. Pages that poll (live
     // embeds) never go idle; waiting on networkidle alone timed out and lost the tile.
     const url = manifest.baseUrl.replace(/\/$/, '') + job.path
@@ -377,8 +413,22 @@ async function captureTile(
       page.goto(url, { waitUntil: 'load', timeout: 30000 })
     let resp = await go()
     if (resp?.status() === 429) {
+      const limited = resp.request()
       await page.waitForTimeout(retryDelayMs(resp.headers()['retry-after']))
+      const before = requestErrors.length
       resp = await go()
+      // A recovered retry means the first 429 says nothing about this screen; drop its entry.
+      if (resp && resp.status() < 400) {
+        const first = requestErrors
+          .slice(0, before)
+          .findIndex(
+            (e) =>
+              e.status === 429 &&
+              e.resourceType === 'document' &&
+              e.url === safeUrl(limited.url()).slice(0, 500),
+          )
+        if (first !== -1) requestErrors.splice(first, 1)
+      }
     }
     tile.status = resp?.status() ?? 0
     await page.waitForLoadState('networkidle', { timeout: 8000 }).catch(() => {
@@ -490,7 +540,7 @@ async function captureTile(
       }
     }
     tile.overflowX = m.overflowX
-    tile.brokenImages = m.brokenImages
+    tile.brokenImages = m.brokenImages.map(redactUrls)
     tile.textClipped = m.textClipped
     const boxes = findBlankBoxes(PNG.sync.read(buf), m.candidates).map((b) => ({
       x: Math.round(b.x),
@@ -502,12 +552,13 @@ async function captureTile(
     tile.consoleErrors = [...new Set(tile.consoleErrors)].slice(0, 5)
     tile.pageErrors = [...new Set(tile.pageErrors)].slice(0, 5)
   } catch (e) {
-    tile.error = (e as Error).message.split('\n')[0]?.slice(0, 200)
+    tile.error = redactUrls((e as Error).message.split('\n')[0] ?? '').slice(0, 200)
     tile.diagnostic = {
       stage,
       message: `Capture failed during ${stage}. Inspect the configured condition and retry.`,
     }
   } finally {
+    collectingRequests = false
     await ctx?.close().catch(() => {})
   }
   return tile
@@ -517,6 +568,8 @@ export interface CaptureOptions {
   root: string
   manifest: Manifest
   baseUrl: string
+  /** Written to run.json instead of baseUrl when the capture reaches the app by another name. */
+  recordedBaseUrl?: string
   routes?: string[]
   concurrency: number
   log?: (s: string) => void
@@ -557,7 +610,7 @@ export async function runCapture(
     id,
     startedAt: startedAt.toISOString(),
     finishedAt: new Date().toISOString(),
-    baseUrl: manifest.baseUrl,
+    baseUrl: redactUrls(opts.recordedBaseUrl ?? manifest.baseUrl),
     tiles,
     coverage: coverage.map((entry) => {
       if (entry.outcome !== 'planned') return entry