design-spine 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elizabeth Stein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# Design Spine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Look at every screen before you ship it.
+
+Design Spine screenshots every route of your Next.js app in every state, width and theme, flags what broke, and gives you one contact sheet to approve or reject each screen. Approved screens become baselines, and `spine diff` fails CI when a screen drifts from what a person approved.
+
+Everything runs on your machine. No account, no upload, no per-snapshot bill.
+
+![Design Spine contact sheet](docs/images/contact-sheet.png)
+
+## Why
+
+Most UI gets built and checked in one state: the happy path, at desktop width, in light mode. AI coding agents make this worse, because they build screen by screen and never open the 390px dark-mode empty state. Design Spine makes the full matrix visible and makes "someone looked at it" a recorded fact instead of a hope.
+
+## Quick start
+
+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
+npx playwright install chromium
+
+npx spine plan        # reads app/ and drafts design-spine.json
+npx spine capture     # screenshots route x state x 390/1280 x light/dark
+npx spine review      # opens the contact sheet at http://localhost:4747
+```
+
+In the contact sheet, press `j`/`k` to move, `a` to approve, `r` to reject and `Enter` to inspect a screenshot at full size against its baseline.
+
+## What it checks on every screenshot
+
+- HTTP errors, redirects and failed captures
+- Console errors and uncaught page errors
+- Horizontal overflow (the classic mobile bug)
+- Near-blank regions, such as cards that rendered empty
+- Broken images and clipped text
+- Fixed overlays covering content, such as cookie banners and chat widgets
+- Optional: axe accessibility scan, repeat-capture stability, and a Claude vision critique
+
+Automatic checks never count as approval. Only a person approves.
+
+## Reach the states nobody opens
+
+Empty, loading and error states need data. Describe them in `design-spine.json` with mocked responses and interaction steps instead of seeding a database:
+
+```json
+{
+  "path": "/dashboard",
+  "states": [
+    { "name": "ideal", "storageState": "auth/populated.json" },
+    {
+      "name": "error",
+      "responses": [{ "url": "**/api/dashboard", "status": 503, "body": "Unavailable" }],
+      "ready": { "selector": "[role=alert]" }
+    }
+  ]
+}
+```
+
+`spine doctor` lists every state you have not made capturable yet, so missing coverage stays visible instead of silently passing.
+
+## Gate CI on approved screens
+
+```bash
+spine approve           # approved tiles become baselines
+spine diff              # exit 1 when a screen differs from its approved baseline
+spine diff --strict     # also require full coverage and a person's approval on this run
+spine report --out review.html   # portable offline record of what was approved and why
+```
+
+In CI, add the action after the step that starts your app, and commit `design-spine.json` and `.design-spine/baselines/`:
+
+```yaml
+- run: npm run build && (npm start &) && npx wait-on http://localhost:3000
+- uses: forbiddenlink/design-spine@v0.2.0
+  with:
+    base-url: http://localhost:3000
+```
+
+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
+
+| Command | What it does |
+|---|---|
+| `plan` | Drafts `design-spine.json` from `app/` or `src/app/` |
+| `doctor` | Validates the manifest and lists unfinished coverage, without a browser |
+| `capture` | Screenshots every route x state x viewport x theme and runs the checks |
+| `review` | Local contact sheet for approve, reject and notes |
+| `critique` | Optional Claude vision pass through the `claude` CLI |
+| `approve` | Promotes approved tiles to baselines |
+| `diff` | Compares a run with baselines; `--strict` requires complete approved evidence |
+| `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 |
+
+Full reference: [docs/USAGE.md](docs/USAGE.md).
+
+## How it compares
+
+| | Design Spine | Chromatic, Percy, Argos | Playwright `toHaveScreenshot` |
+|---|---|---|---|
+| 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.
+- 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
+
+MIT

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Thin launcher: Design Spine needs Bun (HTML imports, Bun.serve), so hand off to it.
+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 bun = resolveBun()
+if (!bun) {
+  console.error(MESSAGE)
+  process.exit(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,70 @@
 {
   "name": "design-spine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+  "homepage": "https://github.com/forbiddenlink/design-spine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forbiddenlink/design-spine.git"
+  },
+  "bugs": "https://github.com/forbiddenlink/design-spine/issues",
+  "keywords": [
+    "visual-regression",
+    "screenshot",
+    "nextjs",
+    "playwright",
+    "design-review",
+    "ui-testing",
+    "cli",
+    "claude-code"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12",
+    "bun": ">=1.3.13"
+  },
+  "type": "module",
+  "bin": {
+    "spine": "bin/spine.js"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "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"
+  },
+  "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

@@ -0,0 +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
+}