@awarebydefault/display-case 1.0.1 → 1.1.0

package/docs/configuration.md

@@ -34,7 +34,7 @@ The CLI looks for `display-case.config.ts` then `display-case.config.tsx` in the
 | `baselineDir` | `string` | no | `.display-case/baselines` | Where visual-regression baselines are stored. |
 | `tokens` | `{ allow?: string[] }` | no | none | Design-token conformance options for `--tokens`. `allow` lists custom-property names the package may reference but does not itself define (e.g. host-app-provided tokens). See [Testing](testing.md#token-conformance). |
 | `providers` | `{ driver?, diff? }` | no | built-in | Override the visual-regression backend. When unset, the built-in Playwright/axe driver and pixelmatch/pngjs diff are loaded lazily. See [`providers`](#providers). |
-| `check` | `{ defaultPhases?, structure? }` | no | none | Tune the `check` command: which phases run by default, and the structure phase's rules and severities. See [`check`](#check). |
+| `check` | `{ defaultPhases?, concurrency?, structure? }` | no | none | Tune the `check` command: which phases run by default, how many variants the a11y/visual phases scan concurrently, and the structure phase's rules and severities. See [`check`](#check). |
 | `a11y` | `{ enabled?, themes?, exclude?, startup? }` | no | off | Live accessibility surfacing in the running browse chrome. See [`a11y`](#a11y). |
 
 ### `title`
@@ -349,6 +349,9 @@ check: {
   // opt out. An opted-out phase still runs when named explicitly (e.g. --visual).
   defaultPhases: { visual: false },
 
+  // How many variants the a11y/visual phases scan concurrently. Default 4.
+  concurrency: 4,
+
   structure: {
     // Treat every structure warning as an error for the run (same as --strict).
     strict: false,
@@ -365,6 +368,7 @@ check: {
 ```
 
 - **`defaultPhases`** — a `Partial<Record<'tokens' | 'a11y' | 'visual' | 'structure', boolean>>`. Drop a phase from the bare `check` run (e.g. `visual` when no baselines are committed) while keeping it available via its flag.
+- **`concurrency`** — how many variants the render phases (a11y/visual) scan at once, each on its own page from a shared browser. Default `4`; override per run with `--concurrency=N`. A custom `providers.driver` must tolerate concurrent `open()` calls (set `1` if it can't). See [Testing → Reporting and concurrency](testing.md#reporting-and-concurrency).
 - **`structure.rules[id]`** — `false` disables the rule; `'warn'`/`'error'` enables it at that severity; an options object (`{ severity?, ignore?, thresholds? }`) enables it with overrides. Unset ⇒ the rule's default. The rule ids, defaults, and escape-hatch markers are listed in [Testing → Structure checks](testing.md#structure-checks).
 - **`structure.strict`** — escalate all structure warnings to errors (the config equivalent of `check --strict`).
 

package/docs/testing.md

@@ -139,10 +139,12 @@ Escapes:
 
 ## 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:
+For every case in every theme, the runner analyzes the page with axe-core. Each variant is reported as a test — `(pass)` or `(fail)`, with its own timing — in the shape of `bun test`, so a CI log can be grepped and summarized the same way a test run is. A failing variant is followed by each violation and its 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))
+a11y   (pass) eyebrow/tones [light] [270.84ms]
+a11y   (fail) tweak-control/variants [dark] [412.30ms]
+         serious 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]
 ```
@@ -155,15 +157,17 @@ The isolated render document is a complete page (a `<title>`, `lang`, and a sing
 
 ## Visual regression
 
-For every case in every theme, the runner takes a screenshot and compares it to a baseline PNG:
+For every case in every theme, the runner takes a screenshot and compares it to a baseline PNG. Each variant is reported as a `bun test`-style test with its own timing:
 
-- **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.
+- **No baseline yet** → the screenshot is recorded as the new baseline, reported `(record)` (counted as "recorded", not a failure).
+- **Baseline matches** → `(pass)`.
+- **Baseline differs** → `(fail)`. A `<case>.<theme>.diff.png` is written next to the baseline (its path is printed under the failing line) so you can inspect the change.
+- **Dimensions changed** → `(fail)`. The new render is saved as `<case>.<theme>.actual.png` for inspection.
 
 ```
-visual ✗ tweak-control/variants [light] differs from baseline
+visual (pass) eyebrow/tones [light] [87.75ms]
+visual (fail) tweak-control/variants [light] [203.86ms]
+         differs from baseline → test/visual-baselines/tweak-control/variants.light.diff.png
 ```
 
 The diff threshold is strict: any differing pixel counts as a change.
@@ -211,6 +215,39 @@ export default defineConfig({
 > [`check.defaultPhases`](configuration.md)`: { visual: false }`; the phase still
 > runs when asked explicitly (`--visual`) and in CI. This repo does exactly that.
 
+## Reporting and concurrency
+
+The a11y and visual phases report in the shape of `bun test`: one `(pass)` /
+`(fail)` / `(record)` line per variant, each tagged with its own elapsed time
+(high-resolution, via `Bun.nanoseconds()`), then a rolled-up summary — per-phase
+counts, the overall `N pass` / `N fail`, and a `Ran N checks [time]` line whose
+time is the **wall-clock** for the whole render run:
+
+```
+a11y   42 pass  0 fail
+visual 40 pass  2 fail  3 recorded
+
+82 pass
+2 fail
+3 recorded
+Ran 87 checks [12.41s] (concurrency 4)
+```
+
+Because the variants are scanned concurrently, the wall-clock is well below the
+sum of the per-variant times. The fixed `(pass)`/`(fail)` tags are plain text (no
+colour or glyphs to parse), so a CI step can grep and tally them like any test
+run.
+
+The render phases scan multiple variants at once — each on its own page from a
+shared browser — to cut wall-clock. The default concurrency is **4**; override it
+per run with `--concurrency=N` or globally with `check.concurrency` in the config.
+A custom [`providers.driver`](configuration.md#providers) must tolerate
+concurrent `open()` calls (set concurrency to `1` if it can't).
+
+```bash
+display-case check . --a11y --visual --concurrency=8
+```
+
 ## Change-scoped checks
 
 The a11y and visual phases re-render every case, which is wasteful in CI when a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awarebydefault/display-case",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "A Bun-native, AI-friendly component showcase — a lightweight alternative to Storybook.",
   "license": "MIT",
   "author": "Jake Uskoski <jake@awarebydefault.com>",

package/src/checks/check-reporter.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  emptyTally,
+  formatDuration,
+  summaryLines,
+  testLine,
+} from './check-reporter'
+
+const MS = 1e6
+const SEC = 1e9
+
+describe('check-reporter: formatDuration', () => {
+  test('sub-second spans render as milliseconds with two decimals', () => {
+    expect(formatDuration(12.345 * MS)).toBe('12.35ms')
+    expect(formatDuration(0)).toBe('0.00ms')
+  })
+
+  test('spans of a second or more render as seconds', () => {
+    expect(formatDuration(SEC)).toBe('1.00s')
+    expect(formatDuration(3.456 * SEC)).toBe('3.46s')
+  })
+})
+
+describe('check-reporter: testLine', () => {
+  test('a pass carries the (pass) tag, name, and timing', () => {
+    expect(testLine('a11y', 'Button/default [light]', 'pass', 12.34 * MS)).toBe(
+      '  a11y   (pass) Button/default [light] [12.34ms]',
+    )
+  })
+
+  test('phases pad to a common width so tags align', () => {
+    const a = testLine('a11y', 'X/y [light]', 'fail', MS)
+    const v = testLine('visual', 'X/y [light]', 'fail', MS)
+    expect(a.indexOf('(fail)')).toBe(v.indexOf('(fail)'))
+  })
+
+  test('a recorded baseline carries the (record) tag', () => {
+    expect(testLine('visual', 'X/y [dark]', 'record', MS)).toContain('(record)')
+  })
+})
+
+describe('check-reporter: summaryLines', () => {
+  test('rolls up per-phase tallies, totals, and wall-clock', () => {
+    const a11y = { ...emptyTally(), pass: 43, fail: 1 }
+    const visual = { ...emptyTally(), pass: 42, fail: 2, record: 3 }
+    const lines = summaryLines(
+      [
+        { phase: 'a11y', tally: a11y },
+        { phase: 'visual', tally: visual },
+      ],
+      2.5 * SEC,
+      4,
+    )
+    const text = lines.join('\n')
+    expect(text).toContain('a11y   43 pass  1 fail')
+    expect(text).toContain('visual 42 pass  2 fail  3 recorded')
+    // 43+1 + 42+2+3 = 91 checks; 85 pass / 3 fail overall.
+    expect(text).toContain('  85 pass')
+    expect(text).toContain('  3 fail')
+    expect(text).toContain('Ran 91 checks [2.50s] (concurrency 4)')
+  })
+
+  test('a single check is not pluralized', () => {
+    const lines = summaryLines(
+      [{ phase: 'a11y', tally: { ...emptyTally(), pass: 1 } }],
+      MS,
+      1,
+    )
+    expect(lines.join('\n')).toContain('Ran 1 check [')
+  })
+})

package/src/checks/check-reporter.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure formatting for the render-phase (a11y + visual) progress output. Models
+ * each scanned variant as a "test" that passes or fails, in the shape of `bun
+ * test`'s reporter — a `(pass)`/`(fail)` tag, a stable name, and a per-test
+ * timing — so a CI log can be grepped and summarized the same way a test run is.
+ *
+ * Kept side-effect-free (no console, no I/O) so the formatting is unit-tested;
+ * `check.ts` owns the timing (via `Bun.nanoseconds()`), the browser, and the
+ * actual `console` writes.
+ */
+
+/** A single scanned variant under one phase — the unit that passes or fails. */
+export type TestStatus = 'pass' | 'fail' | 'record'
+
+const STATUS_TAG: Record<TestStatus, string> = {
+  pass: '(pass)',
+  fail: '(fail)',
+  record: '(record)',
+}
+
+// Phase labels are padded to a common width so the `(pass)`/`(fail)` tags line
+// up into a scannable column regardless of which phase emitted the line.
+const PHASE_WIDTH = 6
+
+/**
+ * Human duration from a nanosecond span (`Bun.nanoseconds()` deltas), matching
+ * `bun test`'s `[12.34ms]` / `[1.50s]` convention: milliseconds below a second,
+ * seconds above.
+ */
+export function formatDuration(ns: number): string {
+  const ms = ns / 1e6
+  return ms < 1000 ? `${ms.toFixed(2)}ms` : `${(ms / 1000).toFixed(2)}s`
+}
+
+/**
+ * One per-test line: `  a11y   (pass) Button/default [light] [12.34ms]`. The
+ * `(pass)`/`(fail)`/`(record)` tag is fixed-text so a downstream summarizer can
+ * count outcomes without parsing colour or glyphs.
+ */
+export function testLine(
+  phase: string,
+  name: string,
+  status: TestStatus,
+  durationNs: number,
+): string {
+  return `  ${phase.padEnd(PHASE_WIDTH)} ${STATUS_TAG[status]} ${name} [${formatDuration(durationNs)}]`
+}
+
+/** Per-phase pass/fail/recorded counts feeding the summary block. */
+export interface PhaseTally {
+  pass: number
+  fail: number
+  record: number
+}
+
+export function emptyTally(): PhaseTally {
+  return { pass: 0, fail: 0, record: 0 }
+}
+
+/** Total tests a tally represents (recorded baselines count as run, not failed). */
+function tallyTotal(t: PhaseTally): number {
+  return t.pass + t.fail + t.record
+}
+
+/**
+ * The closing summary, in `bun test`'s shape: a per-phase line, then the rolled-up
+ * `N pass` / `N fail`, then a `Ran …` line carrying the total wall-clock (which is
+ * less than the sum of per-test times when the phases run concurrently) and the
+ * concurrency the run used.
+ *
+ * Returns the lines without the trailing canonical `✓ checks passed` verdict —
+ * `check.ts` still prints that, so the overall pass/fail signal (and its exit
+ * code) is unchanged.
+ */
+export function summaryLines(
+  phases: { phase: string; tally: PhaseTally }[],
+  totalNs: number,
+  concurrency: number,
+): string[] {
+  const out: string[] = ['']
+  let pass = 0
+  let fail = 0
+  let record = 0
+  let total = 0
+  for (const { phase, tally } of phases) {
+    pass += tally.pass
+    fail += tally.fail
+    record += tally.record
+    total += tallyTotal(tally)
+    const parts = [`${tally.pass} pass`, `${tally.fail} fail`]
+    if (tally.record) parts.push(`${tally.record} recorded`)
+    out.push(`  ${phase.padEnd(PHASE_WIDTH)} ${parts.join('  ')}`)
+  }
+  out.push('')
+  out.push(`  ${pass} pass`)
+  out.push(`  ${fail} fail`)
+  if (record) out.push(`  ${record} recorded`)
+  out.push(
+    `  Ran ${total} check${total === 1 ? '' : 's'} ` +
+      `[${formatDuration(totalNs)}] (concurrency ${concurrency})`,
+  )
+  return out
+}

package/src/checks/check.ts

@@ -12,6 +12,12 @@ import type {
   RenderDriver,
 } from '../index'
 import { startDisplayCase } from '../server/server'
+import {
+  emptyTally,
+  type PhaseTally,
+  summaryLines,
+  testLine,
+} from './check-reporter'
 import { checkSsr } from './ssr-check'
 import { checkStructure } from './structure-check'
 import { checkTokens } from './tokens-check'
@@ -46,9 +52,41 @@ export interface CheckOptions {
   /** Restrict the render phases to components whose import closure touches a
    *  file changed since this git ref (CLI `--changed[=ref]`). */
   changedRef?: string
+  /** How many variants the render phases (a11y/visual) scan concurrently.
+   *  CLI `--concurrency=N`; defaults to {@link DEFAULT_CONCURRENCY}. */
+  concurrency?: number
   port?: number
 }
 
+/** Default render-phase concurrency — modest, so a stock laptop isn't swamped by
+ *  parallel headless pages while still cutting wall-clock well below serial. */
+const DEFAULT_CONCURRENCY = 4
+
+/**
+ * Run `worker` over `items` with at most `limit` in flight at once. Drives the
+ * a11y/visual phases: the browser work is I/O-bound, so concurrent pages overlap
+ * almost entirely. JS stays single-threaded, so the shared counters/arrays the
+ * workers mutate need no locking — only one worker runs between any two awaits.
+ */
+async function mapPool<T>(
+  items: T[],
+  limit: number,
+  worker: (item: T) => Promise<void>,
+): Promise<void> {
+  let next = 0
+  const lanes = Array.from(
+    { length: Math.max(1, Math.min(limit, items.length)) },
+    async () => {
+      while (true) {
+        const i = next++
+        if (i >= items.length) return
+        await worker(items[i])
+      }
+    },
+  )
+  await Promise.all(lanes)
+}
+
 interface Target {
   componentId: string
   caseId: string
@@ -359,43 +397,65 @@ export async function runChecks(
 
   const driver = await resolveDriver(config)
   const diff = opts.visual ? await resolveDiff(config) : null
+  const requested =
+    opts.concurrency ?? config.check?.concurrency ?? DEFAULT_CONCURRENCY
+  const concurrency =
+    Number.isFinite(requested) && requested > 0
+      ? Math.floor(requested)
+      : DEFAULT_CONCURRENCY
 
   let a11yViolations = 0
   let visualChanges = 0
-  let recorded = 0
   const a11yReport: A11yReportEntry[] = []
-
-  try {
-    for (const t of targets) {
-      const ctx: CaseContext = {
-        componentId: t.componentId,
-        caseId: t.caseId,
-        theme: t.theme,
-        width: VIEWPORT_WIDTH,
-      }
-      const page = await driver.open(t.renderUrl, ctx)
-
+  const a11yTally = emptyTally()
+  const visualTally = emptyTally()
+  const rel = (p: string) =>
+    p.startsWith(`${pkgDir}/`) ? p.slice(pkgDir.length + 1) : p
+
+  // Each variant is reported as a test — `(pass)`/`(fail)`/`(record)` with its own
+  // timing, in `bun test`'s shape — so a CI log can be grepped and summarized. The
+  // a11y and visual phases run together on one shared page per variant; the whole
+  // set is scanned with bounded concurrency (`mapPool`) since the work is
+  // browser-I/O-bound. A variant's lines are buffered and flushed as one block so
+  // concurrent variants never interleave mid-test.
+  async function scan(t: Target): Promise<void> {
+    const ctx: CaseContext = {
+      componentId: t.componentId,
+      caseId: t.caseId,
+      theme: t.theme,
+      width: VIEWPORT_WIDTH,
+    }
+    const name = `${t.componentId}/${t.caseId} [${t.theme}]`
+    const out: string[] = []
+    const page = await driver.open(t.renderUrl, ctx)
+    try {
       if (opts.a11y && a11yThemes.includes(t.theme)) {
+        const t0 = Bun.nanoseconds()
         const violations = await page.audit({ exclude: a11yExclude })
+        const dur = Bun.nanoseconds() - t0
         if (violations.length) {
+          a11yTally.fail++
           a11yReport.push({
             component: t.componentId,
             case: t.caseId,
             theme: t.theme,
             violations,
           })
-        }
-        for (const v of violations) {
-          a11yViolations++
-          const sev = v.impact ? `${v.impact} ` : ''
-          console.error(
-            `  a11y ✗ ${t.componentId}/${t.caseId} [${t.theme}] ${sev}${v.id}: ${v.help} (${v.nodes} node(s))`,
-          )
-          for (const line of a11yDetailLines(v)) console.error(line)
+          out.push(testLine('a11y', name, 'fail', dur))
+          for (const v of violations) {
+            a11yViolations++
+            const sev = v.impact ? `${v.impact} ` : ''
+            out.push(`         ${sev}${v.id}: ${v.help} (${v.nodes} node(s))`)
+            for (const line of a11yDetailLines(v)) out.push(line)
+          }
+        } else {
+          a11yTally.pass++
+          out.push(testLine('a11y', name, 'pass', dur))
         }
       }
 
       if (opts.visual && diff) {
+        const t0 = Bun.nanoseconds()
         const shot = await page.screenshot()
         const file = join(
           baselines,
@@ -405,36 +465,52 @@ export async function runChecks(
         if (opts.update || !(await Bun.file(file).exists())) {
           await mkdir(dirname(file), { recursive: true })
           await Bun.write(file, shot)
-          recorded++
+          visualTally.record++
+          out.push(testLine('visual', name, 'record', Bun.nanoseconds() - t0))
         } else {
           const baseline = new Uint8Array(await Bun.file(file).arrayBuffer())
           const res = await diff(
             { baseline, actual: shot },
             { ...ctx, baselinePath: file },
           )
+          const dur = Bun.nanoseconds() - t0
           if (res.changed) {
             visualChanges++
+            visualTally.fail++
+            let where = ''
             if (res.diffImage) {
-              await Bun.write(
-                file.replace(/\.png$/, '.diff.png'),
-                res.diffImage,
-              )
+              const diffPath = file.replace(/\.png$/, '.diff.png')
+              await Bun.write(diffPath, res.diffImage)
+              where = ` → ${rel(diffPath)}`
             }
-            console.error(
-              `  visual ✗ ${t.componentId}/${t.caseId} [${t.theme}] differs from baseline`,
-            )
+            out.push(testLine('visual', name, 'fail', dur))
+            out.push(`         differs from baseline${where}`)
+          } else {
+            visualTally.pass++
+            out.push(testLine('visual', name, 'pass', dur))
           }
         }
       }
-
+    } finally {
       await page.dispose()
     }
+    if (out.length) console.log(out.join('\n'))
+  }
+
+  const startedAt = Bun.nanoseconds()
+  try {
+    await mapPool(targets, concurrency, scan)
   } finally {
     await driver.close()
     server.stop(true)
   }
+  const totalNs = Bun.nanoseconds() - startedAt
 
-  if (opts.visual && recorded) console.log(`  recorded ${recorded} baseline(s)`)
+  const phases: { phase: string; tally: PhaseTally }[] = []
+  if (opts.a11y) phases.push({ phase: 'a11y', tally: a11yTally })
+  if (opts.visual) phases.push({ phase: 'visual', tally: visualTally })
+  for (const line of summaryLines(phases, totalNs, concurrency))
+    console.log(line)
 
   // Persist the full run (every failing variant, with per-node detail) so an
   // agent or human can read the exact failing colours/elements later without
@@ -446,15 +522,19 @@ export async function runChecks(
     await Bun.write(
       reportPath,
       `${JSON.stringify(
-        { scannedAt: Date.now(), total: a11yViolations, results: a11yReport },
+        {
+          scannedAt: Date.now(),
+          durationMs: Math.round(totalNs / 1e6),
+          total: a11yViolations,
+          results: a11yReport,
+        },
         null,
         2,
       )}\n`,
     )
-    const rel = reportPath.startsWith(`${pkgDir}/`)
-      ? reportPath.slice(pkgDir.length + 1)
-      : reportPath
-    console.log(`  a11y detail → ${rel}${a11yViolations ? '' : ' (clean run)'}`)
+    console.log(
+      `  a11y detail → ${rel(reportPath)}${a11yViolations ? '' : ' (clean run)'}`,
+    )
   }
 
   const ok =

package/src/cli.ts

@@ -21,7 +21,7 @@ if (typeof globalThis.Bun === 'undefined') {
  *
  *   display-case <pkgDir> [--port=N]        start the dev server
  *   display-case <pkgDir> --print-manifest  print the manifest JSON and exit
- *   display-case check <pkgDir> [--a11y] [--visual] [--tokens] [--structure] [--ssr] [--update] [--strict] [--only=ids] [--changed[=ref]] [--port=N]
+ *   display-case check <pkgDir> [--a11y] [--visual] [--tokens] [--structure] [--ssr] [--update] [--strict] [--only=ids] [--changed[=ref]] [--concurrency=N] [--port=N]
  *   display-case init <pkgDir> [--agent=claude] [--with-visual] [--dry-run] [--json]
  *   display-case uninstall <pkgDir> [--agent=claude] [--dry-run] [--json]
  *
@@ -182,6 +182,10 @@ if (argv[0] === 'init' || argv[0] === 'uninstall') {
         process.env.DISPLAY_CASE_BASE_REF ??
         'origin/main')
       : undefined,
+    concurrency: (() => {
+      const n = Number.parseInt(option('concurrency') ?? '', 10)
+      return Number.isInteger(n) && n > 0 ? n : undefined
+    })(),
     port,
   })
   process.exit(ok ? 0 : 1)

package/src/commands/publish.ts

@@ -10,6 +10,7 @@ import {
   resolveConfig,
 } from '../core/discovery'
 import { mdxPlugin } from '../core/mdx-plugin'
+import { pinReact } from '../core/pin-react'
 import type { DisplayCaseConfig } from '../index'
 import { getManifest } from '../server/server'
 
@@ -166,7 +167,9 @@ export async function publish(
 
   const defines = await buildDefines(pkgDir)
 
-  // Browser bundle: minified, content-hashed, production React.
+  // Browser bundle: minified, content-hashed, production React. pinReact keeps
+  // Display Case's render runtime and the consumer's components on one React copy
+  // (see pinReact for the dual-React bug it prevents).
   const browserEntries = [BROWSER_ENTRY, renderEntry]
   if (primerEntry) browserEntries.push(primerEntry)
   const browser = await Bun.build({
@@ -175,7 +178,7 @@ export async function publish(
     target: 'browser',
     minify: true,
     sourcemap: 'none',
-    plugins: [mdxPlugin()],
+    plugins: [mdxPlugin(), pinReact(pkgDir)],
     define: defines,
     naming: {
       entry: '[name]-[hash].[ext]',
@@ -196,7 +199,15 @@ export async function publish(
   }
 
   // SSR renderers for the production server: built once (no watching), imported
-  // by `prod-server`. React stays external (resolved at runtime).
+  // by `prod-server`. React stays external here (unlike the browser bundle and
+  // the dev server's in-process SSR, which pin React to the consumer copy): a
+  // published build deploys with its own `bun install`, so the prod process has a
+  // single React already. Leaving it external keeps `prod-server`'s own chrome
+  // renderer (`ssr-shell`, which needs `react-dom/server` at runtime regardless)
+  // and these bundled case renderers on that one copy — bundling React here would
+  // instead put a second copy in the prod process for no benefit. The dual-React
+  // hazard pinReact addresses comes from a temp/global *tool* install resolving a
+  // different React than the consumer's components; a clean deploy has neither.
   const ssrEntries = [ssrEntry]
   if (ssrPrimerEntry) ssrEntries.push(ssrPrimerEntry)
   const ssr = await Bun.build({

package/src/core/pin-react.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { makeTempDir } from '../testing/test-helpers'
+import { pinReact } from './pin-react'
+
+type OnResolveArgs = { path: string }
+type OnResolveResult = { path: string }
+type OnResolveCb = (args: OnResolveArgs) => OnResolveResult
+
+/**
+ * Drive the plugin without a real Bun build: capture the `onResolve` handler it
+ * registers (and its filter), then invoke it directly.
+ */
+function captureOnResolve(pkgDir: string): {
+  filter: RegExp
+  run: OnResolveCb
+} {
+  const calls: Array<{ filter: RegExp; cb: OnResolveCb }> = []
+  const build = {
+    onResolve: (opts: { filter: RegExp }, cb: OnResolveCb) =>
+      calls.push({ filter: opts.filter, cb }),
+  }
+  const plugin = pinReact(pkgDir)
+  plugin.setup(build as unknown as Parameters<typeof plugin.setup>[0])
+  if (!calls[0]) throw new Error('plugin registered no onResolve handler')
+  return { filter: calls[0].filter, run: calls[0].cb }
+}
+
+describe('pinReact', () => {
+  test('matches react / react-dom and their sub-paths, but not lookalikes', () => {
+    const { filter } = captureOnResolve(process.cwd())
+    for (const id of [
+      'react',
+      'react-dom',
+      'react-dom/client',
+      'react-dom/server',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+    ]) {
+      expect(filter.test(id)).toBe(true)
+    }
+    // Unrelated packages that merely start with "react" must not be captured.
+    for (const id of ['react-foo', 'react-router', '@scope/react', 'preact']) {
+      expect(filter.test(id)).toBe(false)
+    }
+  })
+
+  test('resolves every react specifier from the given pkgDir', () => {
+    const dir = process.cwd()
+    const { run } = captureOnResolve(dir)
+    for (const id of [
+      'react',
+      'react-dom',
+      'react-dom/client',
+      'react/jsx-runtime',
+    ]) {
+      expect(run({ path: id }).path).toBe(Bun.resolveSync(id, dir))
+    }
+  })
+
+  test('throws a helpful error when react is not resolvable from pkgDir', async () => {
+    const dir = await makeTempDir()
+    try {
+      const { run } = captureOnResolve(dir)
+      expect(() => run({ path: 'react' })).toThrow(
+        /Install react and react-dom/,
+      )
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('bundles the render runtime and a hook component into one browser bundle', async () => {
+    const dir = await makeTempDir()
+    try {
+      // The pairing that splits across two React copies without pinning: the
+      // renderer (`react-dom/client`) plus a hook-using component. Bundling one
+      // copy per resolved path, and pinning every specifier to a single pkgDir,
+      // is what guarantees they share a React (proven by the resolution test
+      // above); here we assert the plugin keeps a real build working end to end.
+      const entry = join(dir, 'entry.tsx')
+      await Bun.write(
+        entry,
+        [
+          "import { createRoot } from 'react-dom/client'",
+          "import { useState } from 'react'",
+          'export function App() {',
+          '  const [n] = useState(0)',
+          '  return n',
+          '}',
+          'export { createRoot }',
+        ].join('\n'),
+      )
+      const result = await Bun.build({
+        entrypoints: [entry],
+        target: 'browser',
+        plugins: [pinReact(process.cwd())],
+      })
+      expect(result.success).toBe(true)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/core/pin-react.ts

@@ -0,0 +1,48 @@
+import type { BunPlugin } from 'bun'
+
+/**
+ * Bun bundler plugin that pins every `react` / `react-dom` specifier to the
+ * single copy installed in the **consumer** project (`pkgDir`).
+ *
+ * Why this is necessary: Display Case's own client runtime (`browser-entry`,
+ * `render-mount`) statically imports `react-dom/client` and `react`, whose bare
+ * specifiers resolve relative to **where Display Case itself is installed** —
+ * while the consumer's `*.case.tsx` files and their deps resolve relative to the
+ * **consumer project**. When those two installs differ (the common case for
+ * `bunx @awarebydefault/display-case`, which installs the tool — and its peer
+ * react/react-dom — into a temp prefix), the browser bundle ends up with *two*
+ * React instances. `react-dom` drives one React's dispatcher; the consumer's
+ * components read the other's (null) dispatcher → "Invalid hook call … more than
+ * one copy of React", and every hook-using component blanks. Hook-free
+ * components never touch the dispatcher, so they render and mask the bug.
+ *
+ * Forcing all react/react-dom resolution to `pkgDir` collapses the two copies to
+ * one regardless of how the tool was invoked (bunx temp prefix, global install,
+ * npx, pnpm's strict layout, hoisting differences). The renderer
+ * (`createRoot`/`hydrateRoot`/`renderToString`) then binds to the same React the
+ * consumer's components use.
+ *
+ * Resolve from `pkgDir`, NOT the package dir — the renderer must bind to the
+ * React the consumer's components import, not Display Case's own.
+ */
+export function pinReact(pkgDir: string): BunPlugin {
+  return {
+    name: 'display-case-pin-react',
+    setup(build) {
+      // Matches `react`, `react-dom`, and their sub-paths (`react-dom/client`,
+      // `react-dom/server`, `react/jsx-runtime`, `react/jsx-dev-runtime`) — but
+      // not unrelated packages like `react-foo` or `@scope/react`.
+      build.onResolve({ filter: /^(react|react-dom)(\/.*)?$/ }, (args) => {
+        try {
+          return { path: Bun.resolveSync(args.path, pkgDir) }
+        } catch (cause) {
+          throw new Error(
+            `Display Case could not resolve "${args.path}" from ${pkgDir}. ` +
+              'Install react and react-dom in the package you point Display Case at.',
+            { cause },
+          )
+        }
+      })
+    },
+  }
+}

package/src/index.ts

@@ -411,6 +411,14 @@ export interface CheckConfig {
    * still be invoked explicitly by naming its flag.
    */
   defaultPhases?: Partial<Record<CheckPhase, boolean>>
+  /**
+   * How many variants the render phases (a11y/visual) scan concurrently. The
+   * built-in Playwright driver opens one page per variant from a shared browser
+   * context, so concurrent pages overlap the browser-bound work. Default 4; CLI
+   * `--concurrency=N` overrides. A custom `providers.driver` MUST tolerate
+   * concurrent `open()` calls for values above 1 (set this to `1` if it can't).
+   */
+  concurrency?: number
   /** Structure-phase rule configuration; each rule is on (at its default severity) unless overridden. */
   structure?: {
     /** Treat every structure warning as an error for the run (CI strict mode). */

package/src/server/server.ts

@@ -20,6 +20,7 @@ import {
 } from '../core/discovery'
 import type { Manifest } from '../core/manifest'
 import { mdxPlugin } from '../core/mdx-plugin'
+import { pinReact } from '../core/pin-react'
 import type { DisplayCaseConfig } from '../index'
 import type { PrimerHtmlResult } from '../render/ssr-primer'
 import type { CaseRenderer } from '../render/ssr-render'
@@ -225,8 +226,10 @@ async function rebuild(
     outdir,
     target: 'browser',
     // The MDX plugin compiles the primer's `.mdx` (and any `.mdx` it imports)
-    // to JS on load; it's a no-op for builds without a primer entry.
-    plugins: [mdxPlugin()],
+    // to JS on load; it's a no-op for builds without a primer entry. pinReact
+    // collapses Display Case's render runtime and the consumer's components onto
+    // a single React copy — see pinReact for the dual-React bug it prevents.
+    plugins: [mdxPlugin(), pinReact(pkgDir)],
     // Inline the consumer's public env (BUN_PUBLIC_*) so a `process.env.*` read
     // in bundled code (e.g. the API base URL) doesn't survive as a literal that
     // throws `process is not defined` in the browser. See publicEnvDefines.
@@ -248,8 +251,10 @@ async function rebuild(
   // each rebuild because Bun caches imports by resolved path — a stable name
   // would return the stale renderer after an edit (the same staleness that forces
   // the manifest into a subprocess). The bundle inlines case source from disk, so
-  // importing the fresh file yields current modules. React stays external so the
-  // server resolves it from node_modules at import time.
+  // importing the fresh file yields current modules. pinReact bundles the
+  // consumer's React (instead of leaving it external) so `renderToString` and
+  // the consumer's components share one React — the same dual-React hazard the
+  // browser bundle faces, here for the in-process server render.
   const ssrEntry = await codegenSsrEntry(pkgDir, files, configPath)
   const ssrOutDir = join(cacheDir(pkgDir), 'ssr')
   const ssrName = `ssr-entry-${++ssrBuildSeq}`
@@ -257,15 +262,8 @@ async function rebuild(
     entrypoints: [ssrEntry],
     outdir: ssrOutDir,
     target: 'bun',
-    plugins: [mdxPlugin()],
+    plugins: [mdxPlugin(), pinReact(pkgDir)],
     define: await publicEnvDefines(pkgDir),
-    external: [
-      'react',
-      'react-dom',
-      'react-dom/server',
-      'react/jsx-runtime',
-      'react/jsx-dev-runtime',
-    ],
     naming: {
       entry: `${ssrName}.[ext]`,
       chunk: '[name]-[hash].[ext]',
@@ -297,15 +295,8 @@ async function rebuild(
       entrypoints: [ssrPrimerEntry],
       outdir: ssrOutDir,
       target: 'bun',
-      plugins: [mdxPlugin()],
+      plugins: [mdxPlugin(), pinReact(pkgDir)],
       define: await publicEnvDefines(pkgDir),
-      external: [
-        'react',
-        'react-dom',
-        'react-dom/server',
-        'react/jsx-runtime',
-        'react/jsx-dev-runtime',
-      ],
       naming: {
         entry: `${ssrPrimerName}.[ext]`,
         chunk: '[name]-[hash].[ext]',