@awarebydefault/display-case 1.0.2 → 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.2",
+  "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/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). */