design-spine 0.1.0 → 0.2.0

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.0
   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.0
+    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
 
@@ -100,18 +118,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' },
+  ) => { 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' })
+  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.0",
   "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",
@@ -26,7 +26,6 @@
     "README.md",
     "LICENSE"
   ],
-  "packageManager": "pnpm@12.6.0",
   "engines": {
     "node": ">=22.12",
     "bun": ">=1.3.13"
@@ -35,13 +34,6 @@
   "bin": {
     "spine": "bin/spine.js"
   },
-  "scripts": {
-    "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",
-    "lint": "biome check .",
-    "format": "biome format --write ."
-  },
   "dependencies": {
     "@axe-core/playwright": "^4.13.0",
     "commander": "^15.0.0",
@@ -49,11 +41,30 @@
     "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"
+  },
+  "scripts": {
+    "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 ."
   }
-}
+}

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,13 @@ 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'
 
 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.0')
   // 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 +202,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 +386,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 +448,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 +492,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 +513,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)
     }),
   )

package/src/lib/capture.ts

@@ -517,6 +517,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 +559,7 @@ export async function runCapture(
     id,
     startedAt: startedAt.toISOString(),
     finishedAt: new Date().toISOString(),
-    baseUrl: manifest.baseUrl,
+    baseUrl: opts.recordedBaseUrl ?? manifest.baseUrl,
     tiles,
     coverage: coverage.map((entry) => {
       if (entry.outcome !== 'planned') return entry