@awarebydefault/display-case 1.0.0

package/docs/hierarchy.md

@@ -0,0 +1,59 @@
+# Hierarchy
+
+> Nav: [Quick start](quick-start.md) · [Writing cases](writing-cases.md) · **Hierarchy** · [Tweaks](tweaks.md) · [Theming](theming.md) · [Documentation panel](documentation-panel.md) · [Writing placard docs](writing-placard-docs.md) · [Testing](testing.md) · [CLI](cli.md) · [AI agents](ai-agents.md) · [Configuration](configuration.md)
+
+Each component declares where it sits in an Atomic Design hierarchy. The level drives how the sidebar groups and orders components, so the showcase reads from smallest building block to largest assembled flow. The first five levels mirror Brad Frost's [five stages of atomic design](https://atomicdesign.bradfrost.com/chapter-2/); `flow` is a Display Case addition for walkable multi-step journeys.
+
+```tsx
+export default defineCases('TweakControl', { /* … */ }, { level: 'atom' })
+export default defineCases('FlowNav', { /* … */ }, { level: 'molecule' })
+export default defineCases('TweaksPanel', { /* … */ }, { level: 'organism' })
+```
+
+## The levels
+
+Levels are ordered by increasing composition. The descriptions below follow the [five stages of atomic design](https://atomicdesign.bradfrost.com/chapter-2/):
+
+| Level | Meaning | Example |
+| --- | --- | --- |
+| `atom` | A foundational building block — the smallest primitive that can't be broken down without losing meaning | TweakControl (a single tweak input) |
+| `molecule` | A relatively simple group of atoms functioning together as a unit | FlowNav (a flow stepper) |
+| `organism` | A relatively complex section composed of groups of molecules and/or atoms | TweaksPanel, Sidebar |
+| `template` | A page-level layout that places components into a structure, with no real data | The Shell browse chrome, empty |
+| `page` | A specific instance of a template shown with representative content | The Shell with a component selected |
+| `flow` | A multi-step behavioural journey (Display Case's own level, beyond atomic design) | A sign-in sequence |
+
+The internal order is fixed as `atom, molecule, organism, template, page, flow`. Components are sorted by level (atoms first), then alphabetically by name. A component with **no** declared level is treated as "unclassified" and sorts after everything else.
+
+## Flows
+
+A flow is a multi-step behavioural journey rather than a set of independent variants. Author it with `defineFlow` — it is always placed at the `flow` level, and you do not pass a `level` yourself.
+
+```tsx
+import { defineFlow } from '@awarebydefault/display-case'
+
+export default defineFlow('Sign-in flow', {
+  steps: {
+    'Request link': {
+      transitions: ['Check email'],
+      render: ({ goto }) => <RequestLink onSubmit={() => goto('Check email')} />,
+    },
+    'Check email': { render: () => <CheckEmail /> },
+    'Signed in': { render: () => <SignedIn /> },
+  },
+})
+```
+
+How a flow differs from a regular component:
+
+- **Ordered steps, not variants.** The `steps` keep their declared order and represent states of one journey.
+- **Per-step addresses.** Each step is individually addressable and snapshottable — `/c/sign-in-flow/request-link`, `/c/sign-in-flow/check-email`, and so on. The manifest marks the component with `isFlow: true` and lists the steps as its `cases`, each with its outgoing `transitions`.
+- **In-step transitions.** A step's `render` receives a `goto` that advances the flow in place; wire it into a view's callbacks. `goto(step, overrides?)` re-enters the target step with optional preset tweak values.
+- **Preset state.** A step may declare `tweaks`; their defaults are the step's preset state, so one view serves several steps. A flow with no transitions is a static, walkable sequence.
+
+This lets you walk a flow step by step in the browser, click through it via in-step buttons, deep-link to any single step, or screenshot just one state of the journey.
+
+## See also
+
+- [Writing cases](writing-cases.md) for the authoring API.
+- [AI agents](ai-agents.md) for how `level` and `isFlow` appear in the manifest.

package/docs/quick-start.md

@@ -0,0 +1,78 @@
+# Quick start
+
+> Nav: **Quick start** · [Writing cases](writing-cases.md) · [Hierarchy](hierarchy.md) · [Tweaks](tweaks.md) · [Theming](theming.md) · [Documentation panel](documentation-panel.md) · [Writing placard docs](writing-placard-docs.md) · [Testing](testing.md) · [CLI](cli.md) · [AI agents](ai-agents.md) · [Configuration](configuration.md)
+
+Get a component browsing in a few minutes. Everything here runs on Bun — no bundler config, no separate dev server.
+
+## 1. Write a config
+
+Display Case looks for a `display-case.config.ts` at the root of the package it is pointed at. It must default-export `defineConfig(...)`.
+
+```ts
+// display-case.config.ts
+import { defineConfig } from '@awarebydefault/display-case'
+
+export default defineConfig({
+  title: 'Display Case',
+  roots: ['src/components/**/*.case.tsx'],
+  globalStyles: ['./src/tokens.css', './src/components.css'],
+})
+```
+
+- `title` shows in the browsing chrome and the manifest.
+- `roots` are globs (relative to the package) that locate your case files.
+- `globalStyles` are CSS entrypoints injected into every preview, so components render with their real tokens and styles.
+
+Full reference: [Configuration](configuration.md).
+
+## 2. Write a case file
+
+A case file is `*.case.tsx`, colocated with the component it showcases. It default-exports `defineCases(...)`.
+
+```tsx
+// src/components/tweak-control.case.tsx
+import { defineCases } from '@awarebydefault/display-case'
+import { TweakControl } from './tweak-control'
+
+export default defineCases('TweakControl', {
+  Variants: () => (
+    <div style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap' }}>
+      <TweakControl kind="text" label="Label" value="Save" />
+      <TweakControl kind="choice" label="Variant" options={['default', 'outline']} value="default" />
+      <TweakControl kind="boolean" label="Disabled" value={false} />
+    </div>
+  ),
+}, { level: 'atom' })
+```
+
+The render functions are lazy thunks — they only run when a case is viewed or screenshotted. Keep the module side-effect-free at the top level; the server imports it to build the manifest without ever calling them.
+
+## 3. Start the server
+
+Point the CLI at the package directory:
+
+```bash
+bunx @awarebydefault/display-case .
+```
+
+Or wire up an npm script and use that:
+
+```jsonc
+// package.json
+{ "scripts": { "display-case": "display-case ." } }
+```
+
+```bash
+bun run display-case
+```
+
+The server prints its URL (default `http://localhost:3100`). Open it and you'll see your components grouped by hierarchy level in the sidebar, with each case rendered in an isolated frame.
+
+Change a `*.case.tsx` or `*.placard.md` file and the server rebuilds automatically. There is no in-page hot reload — refresh to pick up the change.
+
+## 4. Next steps
+
+- Add interactive controls: [Tweaks](tweaks.md).
+- Group and order components: [Hierarchy](hierarchy.md).
+- Document a component inline: [Documentation panel](documentation-panel.md).
+- Catch regressions: [Testing](testing.md).

package/docs/style-engines.md

@@ -0,0 +1,180 @@
+# Style engines (CSS-in-JS: MUI / emotion)
+
+> Nav: [Quick start](quick-start.md) · [Writing cases](writing-cases.md) · [Hierarchy](hierarchy.md) · [Tweaks](tweaks.md) · [Theming](theming.md) · **Style engines** · [Documentation panel](documentation-panel.md) · [Writing placard docs](writing-placard-docs.md) · [Testing](testing.md) · [CLI](cli.md) · [AI agents](ai-agents.md) · [Configuration](configuration.md)
+
+Display Case delivers every surface **rendered and styled before scripts run**.
+For static CSS that means [`globalStyles`](configuration.md#globalstyles); for a
+theme provider or context it means the [`decorator`](configuration.md#decorator).
+But libraries like **Material UI** style components with **emotion**, a runtime
+CSS-in-JS engine that emits CSS *while the component renders*. Server rendering
+keeps the markup but, without help, throws that styling away — so a MUI snapshot
+comes back unstyled and a live preview flashes unstyled before the client runtime
+catches up.
+
+A **style engine** closes that gap. It does the two things a runtime CSS-in-JS
+library needs on the server: give each render an isolated style store, then read
+that render's critical CSS back into the document head **before scripting**.
+
+## The shape of an engine
+
+```ts
+import type { StyleEngine } from '@awarebydefault/display-case'
+
+// A StyleEngine is a factory called once per server render. It returns a
+// collector with two methods:
+//   wrap(node)    — wrap the tree in the library's provider over a FRESH store
+//   collect(html) — after render, return the <head> markup (style tags) it used
+```
+
+A fresh store per render is what keeps one case's styling out of another's
+snapshot, so the engine must be a **factory** (`() => …`), not a single object.
+Engines are configured on [`styleEngines`](configuration.md#styleengines), and
+apply to the isolated `/render` document and the Primer — the two surfaces that
+render your components in-document.
+
+## Material UI / emotion (the flagship)
+
+Two pieces, working together:
+
+1. **`styleEngines`** — the server-only emotion extractor (this seam).
+2. **`decorator`** — the `ThemeProvider` your components need, on both server and
+   client. On the client, emotion's default cache adopts the server styles
+   automatically, so there is no flash and no duplication.
+
+### 1. The emotion engine
+
+```tsx
+// display-case.style-engine.tsx
+import createCache from '@emotion/cache'
+import { CacheProvider } from '@emotion/react'
+import createEmotionServer from '@emotion/server/create-instance'
+import type { StyleEngine } from '@awarebydefault/display-case'
+
+export const emotionEngine: StyleEngine = () => {
+  // A fresh cache per render → per-render isolation. Key `css` is emotion's
+  // default, which the client runtime adopts automatically (no client wiring).
+  const cache = createCache({ key: 'css' })
+  cache.compat = true // required for extractCritical-style extraction
+  const { extractCriticalToChunks, constructStyleTagsFromChunks } =
+    createEmotionServer(cache)
+  return {
+    wrap: (node) => <CacheProvider value={cache}>{node}</CacheProvider>,
+    collect: (html) =>
+      constructStyleTagsFromChunks(extractCriticalToChunks(html)),
+  }
+}
+```
+
+### 2. Wire it into the config
+
+```tsx
+// display-case.config.tsx
+import { defineConfig } from '@awarebydefault/display-case'
+import { ThemeProvider, createTheme } from '@mui/material/styles'
+import CssBaseline from '@mui/material/CssBaseline'
+import { emotionEngine } from './display-case.style-engine'
+
+const theme = createTheme({ /* your palette, typography, … */ })
+
+export default defineConfig({
+  title: 'My MUI library',
+  roots: ['src/**/*.case.tsx'],
+  // Server: extract emotion's critical CSS into the document head.
+  styleEngines: [emotionEngine],
+  // Server + client: the provider your MUI components need. CssBaseline is
+  // optional but makes the preview match your app.
+  decorator: ({ children }) => (
+    <ThemeProvider theme={theme}>
+      <CssBaseline />
+      {children}
+    </ThemeProvider>
+  ),
+})
+```
+
+That is the whole integration. Now:
+
+- `/render/<component>/<case>?theme=dark` fetched **without scripts** comes back
+  **fully styled** — a real snapshot, not a skeleton.
+- The live preview paints styled on first frame: **no flash of unstyled content**.
+- When scripts run, emotion finds its `data-emotion` style tags already in the
+  document and **adopts** them — nothing is re-injected or duplicated.
+
+### Why the pairing
+
+| Concern | Where it lives | Runs on |
+| --- | --- | --- |
+| Fresh emotion cache + critical-CSS extraction | `styleEngines` | server only |
+| `ThemeProvider` / `CssBaseline` (and the client cache emotion adopts into) | `decorator` | server + client |
+
+Keep their cache keys aligned. With emotion's default key (`css`) the client cache
+is implicit and adoption is automatic — which is why MUI needs no client-side
+engine code.
+
+## Other emotion-like libraries
+
+Any runtime CSS-in-JS library that exposes "provide a store, then read critical
+CSS" fits the same `wrap` + `collect` contract.
+
+**styled-components:**
+
+```tsx
+import { ServerStyleSheet, StyleSheetManager } from 'styled-components'
+import type { StyleEngine } from '@awarebydefault/display-case'
+
+export const styledComponentsEngine: StyleEngine = () => {
+  const sheet = new ServerStyleSheet()
+  return {
+    wrap: (node) => (
+      <StyleSheetManager sheet={sheet.instance}>{node}</StyleSheetManager>
+    ),
+    collect: () => sheet.getStyleTags(), // reads the sheet, not the html
+  }
+}
+```
+
+styled-components does **not** auto-adopt the way emotion's default key does, so
+add a matching client provider in your `decorator` if you see a re-style on
+hydration.
+
+## Multiple engines
+
+[`styleEngines`](configuration.md#styleengines) is an ordered array; engines nest
+in array order (the first is outermost) and their head output is concatenated. Use
+this only if a single showcase genuinely mixes two runtimes:
+
+```ts
+styleEngines: [emotionEngine, styledComponentsEngine]
+```
+
+## When you do *not* need a style engine
+
+- **Static CSS** (Tailwind's compiled output, hand-written stylesheets, design
+  tokens) → list it in [`globalStyles`](configuration.md#globalstyles). Tailwind:
+  build your CSS, then point `globalStyles` at the output file.
+- **Zero-runtime CSS-in-JS** (Vanilla Extract, Linaria, **MUI Pigment CSS**) →
+  these emit static CSS at build time; treat the emitted file as `globalStyles`.
+- **A component that must run in a browser anyway** → mark it
+  [`browserOnly`](writing-cases.md); it is exempt from server styling and mounts
+  (and styles) in the client. You lose the pre-scripting snapshot for that case.
+
+## Contract for a custom engine
+
+If you write your own engine, it must:
+
+- Be a **factory** — return a new collector (and a new store) on every call. A
+  shared store leaks one render's styling into another's document.
+- Have an **idempotent `collect`** — the case tree renders inside `StrictMode`
+  (it may render twice); `collect` must return the same styling regardless.
+- Return **complete head markup** from `collect` (e.g. `<style …>…</style>`),
+  including whatever attributes your client runtime keys on to adopt the styles —
+  Display Case places the string verbatim, after the document's static styles, and
+  does not parse it.
+- Pair with a **client provider in `decorator`** if your library does not adopt
+  server styles automatically.
+
+## See also
+
+- [Theming](theming.md) — `globalStyles`, `decorator`, and `data-theme`.
+- [Configuration › `styleEngines`](configuration.md#styleengines) — the field reference.
+- [Configuration › `decorator`](configuration.md#decorator) — the provider you pair with an engine.

package/docs/testing.md

@@ -0,0 +1,245 @@
+# Testing
+
+> Nav: [Quick start](quick-start.md) · [Writing cases](writing-cases.md) · [Hierarchy](hierarchy.md) · [Tweaks](tweaks.md) · [Theming](theming.md) · [Documentation panel](documentation-panel.md) · [Writing placard docs](writing-placard-docs.md) · **Testing** · [CLI](cli.md) · [AI agents](ai-agents.md) · [Configuration](configuration.md)
+
+`display-case check` runs three kinds of audit over your cases:
+
+- **Token conformance** — a static parse that flags `var(--token)` references which resolve to no custom property the package defines. No browser.
+- **Accessibility** — an axe-core audit of every rendered case.
+- **Visual regression** — a pixel diff of every rendered case against a stored baseline.
+
+The a11y and visual phases drive the same `/render/<component>/<case>` endpoint the browse iframe uses, so what is tested is exactly what a viewer sees. Each case is exercised in **both** light and dark themes.
+
+```bash
+display-case check .            # run all phases
+display-case check . --tokens   # token conformance only (static, no browser)
+display-case check . --a11y     # a11y only
+display-case check . --visual   # visual only
+display-case check . --update   # (re)record visual baselines
+```
+
+With no phase flag, every phase runs; naming any phase flag runs only the named phase(s).
+
+Wrapped as an npm script (see [CLI](cli.md)):
+
+```bash
+bun run display-case:check
+```
+
+> The default runner uses Playwright's Chromium. Those packages are **optional** (see below); when present, pages are rendered at a fixed 1024×768 viewport with reduced motion, and the runner waits for the network to settle and fonts to load before auditing.
+
+## The default backend is lazy and optional
+
+The capture/audit driver and the image diff are pluggable (config [`providers`](configuration.md#providers)). When you leave them unset, Display Case uses a built-in default: a Playwright + axe driver and a pixelmatch/pngjs diff. That default backs `playwright`, `@axe-core/playwright`, `pixelmatch`, and `pngjs` as **`optionalDependencies`** — and it is imported **lazily**, only when a default-backed `check --a11y`/`--visual` actually runs.
+
+So the four packages are needed *only* for a default-backed check. Browsing, snapshotting (`/render`, `--print-manifest`), the token phase (`check --tokens`), and `init` never touch a browser and never trigger the import.
+
+If a default-backed check runs without those packages installed, it fails with an actionable error — install the toolchain, run `init --with-visual`, or inject your own providers:
+
+```
+Visual/a11y checks need the default toolchain. Install it with
+`bun add -d playwright @axe-core/playwright pixelmatch pngjs && bunx playwright install chromium`
+(or run `display-case init --with-visual`), or set `providers.driver`/`providers.diff` in display-case.config.ts.
+```
+
+The on-demand setup step is the easiest path:
+
+```bash
+display-case init <pkgDir> --with-visual   # bun add the deps + install Chromium
+```
+
+See [AI agents → Scaffolding integration](ai-agents.md#scaffolding-integration-init--uninstall).
+
+### Injecting a custom provider
+
+Setting a [provider](configuration.md#providers) replaces the corresponding default and removes the need for the four packages. Point `diff` at a hosted service or a looser comparator, or point `driver` at a different headless browser:
+
+```ts
+// display-case.config.ts
+export default defineConfig({
+  title: 'Display Case',
+  roots: ['src/components/**/*.case.tsx'],
+  providers: {
+    driver: () => myDriver(),  // unset half still falls back to the built-in
+    diff: myDiff,
+  },
+})
+```
+
+Each provider receives the `CaseContext` (`componentId`, `caseId`, `theme`, `width`), so identity-aware providers can vary per case while pure ones ignore it. The built-ins double as reference implementations: [`src/checks/providers/playwright-driver.ts`](../src/checks/providers/playwright-driver.ts) and [`src/checks/providers/pixelmatch-diff.ts`](../src/checks/providers/pixelmatch-diff.ts). See [Configuration → `providers`](configuration.md#providers) for the full interfaces and a worked per-case-tolerance diff.
+
+## Structure checks
+
+The structure phase (`check --structure`) is a set of static best-practice rules — no browser, no server. Each finding carries a **severity**: `error` findings fail the run, `warn` findings are reported but non-fatal (unless `--strict` escalates them). Rules are grouped by what they read:
+
+**File / config rules** (default on, error):
+
+- `case-placard-coverage` — every showcasable component has a sibling `*.case.tsx` **and** `*.placard.md`.
+- `no-orphaned-placard-doc` — every `*.placard.md` has a sibling `*.case.tsx` (a component module is not required).
+- `primer-present-and-used` — a primer is configured, exists, embeds ≥1 `<Display>` specimen, and has prose (parsed, not regex-scanned).
+- `setup-present` — custom `providers` are configured, or the default snapshot toolchain resolves from either the showcase or the Display Case package itself (so a toolchain provided transitively via Display Case is not a false miss).
+- `config-paths-exist` — `globalStyles` entries (and `baselineDir`) resolve.
+
+**Catalog-integrity rules** (default on, error):
+
+- `levels-classified` — every component declares a hierarchy level (none left unclassified).
+- `cases-load` — every case file loads.
+- `flow-transitions-resolve` — every flow step transition targets an existing step.
+- `flow-multi-step` — a flow has more than one step.
+- `unique-slugs` — no two components, or two cases within a component, collide on their address slug.
+- `tweak-defaults-valid` — a `choice` tweak's default is one of its options.
+
+**Case-content rules** (default on, error):
+
+- `interactive-cases-keyed` — a locally-defined stateful specimen (a wrapper that calls `useState`/`useReducer`) reused across **≥2** cases carries a `key` on every usage. The browse chrome swaps cases in place without unmounting, so an unkeyed wrapper keeps the previous case's state on switch (see [Writing cases → Authoring rules](writing-cases.md#authoring-rules)). Single-use specimens are exempt (they always remount). Heuristic, regex-based: it checks for *presence* of a `key`, not that the keys are distinct.
+
+**Composition (import-graph) rules** (opt-in, default **off**):
+
+- `atom-purity` (error) — an `atom` imports no other showcased component.
+- `no-downward-dependency` (error) — no component imports a strictly-higher-level component (same-level is allowed; an organism may compose other organisms).
+- `composes-lower-level` (warn) — a non-atom imports at least one lower-level showcased component. An organism built only of atoms passes.
+- `level-fit` (warn) — a component composing more lower-level parts than its level's threshold is flagged for promotion.
+
+Composition rules scan imports and resolve them to levels, following workspace re-exports so a component that imports its atoms from another showcase in the same workspace is understood. An import that can't be resolved to a showcased component is never an error; a workspace-showcase import the resolver can't follow is reported as a warning.
+
+```
+structure ✗ src/components/button.tsx: missing colocated usage doc (expected a sibling *.placard.md) (case-placard-coverage)
+structure ⚠ src/sections/header.tsx: organism "Header" composes no lower-level showcased component (composes-lower-level)
+```
+
+Escapes:
+
+- **Per file** — a `display-case: <token>` comment. `no-case` marks a module non-showcasable (exempt from coverage entirely); `no-placard` waives only the prompt; `allow-orphan` (in a `*.placard.md`) waives the orphan rule; `unclassified` (in a `*.case.tsx`) waives the level rule; any other rule accepts `allow-<rule-id>` in the relevant source file. Include a reason after the token.
+- **Per path** — `check.structure.rules.<id>.ignore` globs (see [Configuration](configuration.md)); the only escape for findings not tied to one editable file (e.g. `unique-slugs`).
+- **Per rule** — set the rule to `false` to disable it, or `'warn'`/`'error'` to retune its severity.
+
+## Token conformance
+
+A package's design tokens are a closed vocabulary: the custom properties its `globalStyles` define, plus any set at runtime via an inline `style={{ '--x': … }}` object. This phase scans the package source (component CSS/TSX **and** case files) and flags every `var(--token)` whose name is in neither set — the class of bug where a component borrows a foreign design system's token (`var(--muted-foreground, #6b7280)`) that never resolves and silently falls back to a hardcoded value.
+
+```
+tokens ✗ src/components/tweak-control.case.tsx:18:30 unknown token --muted-foreground (fallback does not excuse it)
+```
+
+It is deliberately strict: a `var(--x, fallback)` is still flagged even though the fallback makes it valid CSS — the rule is conformance to *this* package's vocabulary, not CSS validity. Comments and string contents are handled so a `var()` inside a comment is ignored while one inside a JS string (real usage) is checked.
+
+Escapes:
+
+- **Per reference** — an `allow: unknown-token` comment on the offending line or the line directly above it.
+- **Per token** — list names the package legitimately references but does not define (e.g. tokens a host app supplies) under `tokens.allow` in the config:
+
+  ```ts
+  export default defineConfig({
+    title: 'Display Case',
+    roots: ['src/components/**/*.case.tsx'],
+    globalStyles: ['./src/tokens.css', './src/components.css'],
+    tokens: { allow: ['--app-provided-token'] },
+  })
+  ```
+
+## Accessibility
+
+For every case in every theme, the runner analyzes the page with axe-core and reports each violation, followed by the affected nodes — for colour-contrast, the failing element and the exact measured-vs-required pair, so a finding is fixable without re-running a browser:
+
+```
+a11y ✗ tweak-control/variants [dark] color-contrast: Elements must meet contrast ratio (2 node(s))
+      ↳ .dcui-tweak-label  #8a8073 on #ffffff = 3.87:1 (need 4.5:1)  [12.0pt (16px) normal]
+      ↳ .dcui-tweak-url  #8a8073 on #ffffff = 3.87:1 (need 4.5:1)  [12.0pt (16px) normal]
+```
+
+The inline list is capped per violation (with a `+N more` note); the **complete** results of every run — each failing case with its per-node detail — are written to `.display-case/a11y/last-check.json` (under the gitignored cache, overwritten each run, empty on a clean run). Read that file to inspect the exact failing colours/elements later without re-running the checks. The per-node detail is present whenever the audit mechanism provides it (the built-in axe driver always does); a custom [`providers.driver`](configuration.md#providers) MAY populate or omit it.
+
+The detail rides on the same machine-readable violation shape the in-app surface uses, but the running Accessibility panel deliberately shows only the per-variant verdict (rule, severity, node count) — the per-node detail stays in the gate output and the persisted report.
+
+The isolated render document is a complete page (a `<title>`, `lang`, and a single `<main>` landmark) so the audit reports real component issues rather than harness chrome.
+
+## Visual regression
+
+For every case in every theme, the runner takes a screenshot and compares it to a baseline PNG:
+
+- **No baseline yet** → the screenshot is recorded as the new baseline (counted as "recorded", not a failure).
+- **Baseline matches** → pass.
+- **Baseline differs** → failure. A `<case>.<theme>.diff.png` is written next to the baseline so you can inspect the change.
+- **Dimensions changed** → failure. The new render is saved as `<case>.<theme>.actual.png` for inspection.
+
+```
+visual ✗ tweak-control/variants [light] differs from baseline
+```
+
+The diff threshold is strict: any differing pixel counts as a change.
+
+### Recording and updating baselines
+
+Pass `--update` to (re)record every baseline from the current renders. Do this after an intentional visual change, then review the new PNGs before committing.
+
+```bash
+display-case check . --visual --update
+```
+
+When baselines are committed and diffed in CI (Linux), record them in that same environment so they match — this repo provides two paths:
+
+- **Locally** — `bun run baselines:record` records inside the pinned Playwright Docker image (`scripts/record-baselines.ts`). Requires Docker. Review the diff and commit the PNGs.
+- **From CI** — run the **Update visual baselines** workflow (`.github/workflows/update-baselines.yml`) via *Actions → Run workflow*. Pick the branch, optionally an `only` filter, and it records in the CI container and commits the refreshed baselines back to that branch (`[skip ci]`). Use this when you don't have Docker locally.
+
+### Where baselines live
+
+By default baselines are written to the gitignored cache at `.display-case/baselines/`, organized as `<component>/<case>.<theme>.png`. These are local-only and will be recorded fresh on a clean checkout.
+
+To **commit** baselines and gate CI on them, point `baselineDir` at a tracked directory in your config:
+
+```ts
+// display-case.config.ts
+export default defineConfig({
+  title: 'Display Case',
+  roots: ['src/components/**/*.case.tsx'],
+  baselineDir: 'baselines', // committed; resolved relative to the package
+})
+```
+
+`baselineDir` accepts a path relative to the package or an absolute path. See [Configuration](configuration.md#baselinedir).
+
+> **Committed baselines must match the environment that diffs them.** Pixel
+> renders differ across operating systems (fonts, antialiasing). If CI diffs in
+> Linux, record the committed baselines in that same Linux environment, not on a
+> developer's machine — otherwise every CI run reports false changes. This repo
+> records them in the pinned Playwright Docker image via `bun run
+> baselines:record`; see [contributing/testing-best-practices.md](../contributing/testing-best-practices.md).
+>
+> Because of this, a repo with committed (Linux) baselines should opt `visual`
+> out of the **default** run so a bare `display-case check .` on a contributor's
+> machine doesn't report off-platform false diffs. Set
+> [`check.defaultPhases`](configuration.md)`: { visual: false }`; the phase still
+> runs when asked explicitly (`--visual`) and in CI. This repo does exactly that.
+
+## Change-scoped checks
+
+The a11y and visual phases re-render every case, which is wasteful in CI when a
+change touched only a few components. Two flags restrict them to a subset (the
+static phases are unaffected):
+
+- `--only=<ids/globs>` — check only the named components (comma-separated).
+- `--changed[=ref]` — check only the components a change touched since `ref`
+  (default the base branch; override with `=ref` or `DISPLAY_CASE_BASE_REF`).
+
+With `--changed`, a component is in scope when a changed file is in its **import
+closure** — the case, the component, and everything they reference transitively
+(including stylesheets reached by `@import`). Two deliberate fallbacks keep it
+sound:
+
+- A render-relevant change that **no** component's closure claims — a
+  globally-applied stylesheet, the shared render path, other shared source —
+  scopes to **every** component, so a regression is never silently skipped.
+- A change touching **no** render input (docs, specs, tests, tooling) scopes to
+  **nothing**: the render phases report success without launching a browser.
+
+When both flags are given, the scope is their intersection. This is what the CI
+a11y/visual jobs use to gate a PR on only the components it could have affected.
+
+```bash
+display-case check . --a11y --only=button
+display-case check . --a11y --visual --changed=origin/main
+```
+
+## Exit codes
+
+`display-case check` exits **0** when there are zero token violations, zero a11y violations, zero visual changes, and zero **error**-severity structure findings, and **1** otherwise. Structure **warnings** are reported but do not, by themselves, cause a non-zero exit unless `--strict` (or `check.structure.strict`) escalates them. Recording new baselines does not, by itself, cause a non-zero exit. This makes the command safe to use as a CI gate.

package/docs/theming.md

@@ -0,0 +1,97 @@
+# Theming
+
+> Nav: [Quick start](quick-start.md) · [Writing cases](writing-cases.md) · [Hierarchy](hierarchy.md) · [Tweaks](tweaks.md) · **Theming** · [Style engines](style-engines.md) · [Documentation panel](documentation-panel.md) · [Writing placard docs](writing-placard-docs.md) · [Testing](testing.md) · [CLI](cli.md) · [AI agents](ai-agents.md) · [Configuration](configuration.md)
+
+Components render in an isolated document so what you see (and what the check runner screenshots) is exactly the component, with no showcase chrome leaking in. Theming is controlled in three places: global styles, an optional decorator, and per-render URL parameters. (For components styled by a runtime CSS-in-JS library like emotion/MUI, see [Render-time styling](#render-time-styling-css-in-js--mui) below.)
+
+## Global styles
+
+List your CSS entrypoints in the config. Their contents are concatenated and injected into both the browse shell and the isolated render document, so components render with their real tokens and styles.
+
+```ts
+// display-case.config.ts
+import { defineConfig } from '@awarebydefault/display-case'
+
+export default defineConfig({
+  title: 'Display Case',
+  roots: ['src/components/**/*.case.tsx'],
+  globalStyles: ['./src/tokens.css', './src/components.css'],
+})
+```
+
+Paths are resolved relative to the package. A listed file that does not exist is silently skipped.
+
+## Light and dark via `data-theme`
+
+The isolated render reads a `theme` query parameter and sets it on the document root before rendering:
+
+```
+/render/tweak-control/variants?theme=light
+/render/tweak-control/variants?theme=dark
+```
+
+It applies as `<html data-theme="light">` (or `"dark"`). The render document also sets `data-theme-pref` to the same value, so an app `ThemeProvider` rendered via the [decorator](configuration.md#decorator) (e.g. behind a nav `ThemeToggle`) initializes to the harness theme instead of re-resolving from the OS and fighting the `?theme=` selection. Any value other than `dark` is treated as light. Author your tokens against this attribute:
+
+```css
+:root[data-theme='dark'] {
+  --bg: #111;
+  --fg: #eee;
+}
+```
+
+The check runner exercises **both** themes for every case, so a baseline is captured per theme. See [Testing](testing.md).
+
+## Decorator
+
+A decorator is a single React wrapper rendered around every case — the place for a theme provider, context, or a fixed frame.
+
+```tsx
+// display-case.config.ts
+import { defineConfig } from '@awarebydefault/display-case'
+import { ThemeProvider } from './src/components/theme-provider'
+
+export default defineConfig({
+  title: 'Display Case',
+  roots: ['src/components/**/*.case.tsx'],
+  decorator: ThemeProvider,
+})
+```
+
+The decorator accepts `{ children }` plus the active case's `level`, `sourcePath`, and `area` — so beyond cross-cutting context it can wrap page/flow cases in app chrome (nav/header/footer). It wraps the rendered case (and the viewport-width wrapper, if any) inside React `StrictMode`. Use it for cross-cutting context that every component needs; prefer per-case composition for anything component-specific. See [Configuration › decorator](configuration.md#decorator) for the full signature and the per-area chrome pattern.
+
+## Render-time styling (CSS-in-JS / MUI)
+
+Global styles and the decorator cover static CSS and providers. But **Material UI**
+(and any emotion / styled-components library) emits its CSS *while a component
+renders* — so server rendering keeps the markup but loses the styling, giving an
+unstyled snapshot and a flash on first paint.
+
+A **style engine** fixes that: it collects the render-time CSS during the server
+render and delivers it before scripting. Configure it alongside the decorator —
+the engine handles the server-side extraction, the decorator provides the
+`ThemeProvider` your components need:
+
+```ts
+styleEngines: [emotionEngine],
+decorator: ({ children }) => <ThemeProvider theme={theme}>{children}</ThemeProvider>,
+```
+
+See [Style engines](style-engines.md) for the full emotion/MUI recipe and the
+contract for other libraries.
+
+## Viewport width
+
+In the **browse chrome**, the header carries a Chrome-DevTools-style device toolbar: a **Responsive** mode (full or a preset width — Desktop/Tablet/Mobile — with manual zoom) and **fixed device sizes** (1080p, 4K, laptop, iPad, iPhone, Pixel, Galaxy, or a custom `W × H` with a rotate button) that render the iframe at exact pixels and auto-scale to fit the panel. No URL parameter is involved — the toolbar sizes the iframe element directly.
+
+For the **standalone `/render` endpoint** (snapshots, direct navigation), constrain the width with the `width` query parameter (in pixels) instead:
+
+```
+/render/page/dashboard?width=480
+```
+
+The case is wrapped in a centered container with `max-width: <width>px`. This is handy for previewing responsive behavior or capturing a narrow snapshot. Omit it for the default full-width render.
+
+## See also
+
+- [Configuration](configuration.md) for the full `globalStyles` / `decorator` reference and defaults.
+- [AI agents](ai-agents.md) for combining `theme`, `width`, and tweak parameters into a single deterministic render URL.