@adia-ai/adia-ui-factory 0.8.55 → 0.8.56

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.55",
+  "version": "0.8.56",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework \u2014 orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.55",
+  "version": "0.8.56",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "adia-gen-ui": {
       "command": "npx",
-      "args": ["-y", "@adia-ai/mcp@0.8.55", "gen-ui"]
+      "args": ["-y", "@adia-ai/mcp@0.8.56", "gen-ui"]
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog — adia-ui-kit-factory
 
+## [0.8.56] — 2026-08-31
+
+### Added
+- **`theme-audit` skill, `/theme-audit` command, and `scripts/adia-theme-audit.mjs` runner (lld-0012 B1–B3, gh#2257).** Audits a consumer app's `theme.css` for the four redundancy classes (restated defaults, token re-derivations, dead selectors, hand-built components) across every sitemap route, with a Playwright class-1 toggle and route discovery (#2308, #2312, #2413). Fixtures under `scripts/theme-audit-fixtures/`; report shape in `skills/theme-audit/references/report-shape.md`; Codex/Pi/Hermes manifests derived (`skills/theme-audit/agents/openai.yaml`, `prompts/theme-audit.md`).
+- **`HARNESS-NOTES.md`** pointer for non-Claude harnesses (gh#2449) — points at `AGENTS.md`/README rather than duplicating install prose.
+
+### Changed
+- **`scripts/adia-probe.mjs`** gains the route-discovery + class-1 toggle hooks the theme-audit runner drives (#2413); `agents/surface-qa-agent.md` cites the extended probe.
+- **`skills/token-selection/references/a-alias-layer.md`** documents the 15 new `--a-*` aliases from tokens batch C0 and the advisory reroute gate (gh#2240, #2243).
+- **`skills/pattern-catalog/references/{pattern-index.md,annotations.yaml}`** pick up the sidebar-modal pattern (#2226) and the registration/NPI-search and errors surfaces (#2242, #2270); `skills/table-composition/references/base-table.md` follows `table-toolbar-ui`'s count-cluster redesign (#2190); `skills/find-unused/SKILL.md` wording tightened.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`.codex-plugin/` touched in this release window** (1 file(s), e.g. `.codex-plugin/plugin.json`) — carried by the entries above.
+- **`commands/` touched in this release window** (1 file(s), e.g. `commands/theme-audit.md`) — carried by the entries above.
+
 ## [0.8.55] — 2026-08-28
 
 ### Changed

package/README.md

@@ -51,7 +51,7 @@ posture (ADR-0040) is about this plugin working standalone in any consumer
 repo once installed some other way (no monorepo path assumptions in its own
 scripts) — it does not add an npm-sourced marketplace entry.
 
-## Skills (19 — `skills/` on disk is the roster; `check:plugin-count-claims` guards this header count)
+## Skills (20 — `skills/` on disk is the roster; `check:plugin-count-claims` guards this header count)
 
 | Skill | Species | Job |
 |---|---|---|
@@ -74,6 +74,7 @@ scripts) — it does not add an npm-sourced marketplace entry.
 | `app-migration` | procedural | version upgrades + port-to-adia sweeps (breaking changes) |
 | `find-unused` | procedural | what a *non*-breaking upgrade left unused — inert opt-in layers, stale workarounds |
 | `surface-qa` | procedural | browser + a11y + composition exit gate |
+| `theme-audit` | procedural | classify a consumer theme.css against the framework's own defaults/tokens/primitives — restated defaults, re-derived tokens, dead selectors, hand-built component work; audit + report only, no rewrites (gh#2257) |
 
 ## Agents (4)
 
@@ -97,11 +98,20 @@ surface-qa-agent) · `component-model.md` · the `references/contracts/` twins.
 
 ## Commands
 
-`/project-scaffolding` · `/app-planning` · `/surface-qa` · `/app-migration` · `/find-unused` · `/gen-ui-wiring` · `/app-audit`
+`/project-scaffolding` · `/app-planning` · `/surface-qa` · `/app-migration` · `/find-unused` · `/gen-ui-wiring` · `/app-audit` · `/theme-audit`
+
+## Scripts
+
+Consumer-runnable checks shipped as plain Node scripts under `scripts/`, no
+MCP server required: `adia-probe.mjs` (the browser-QA gate; see
+`surface-qa`), `adia-preflight.mjs` (every CI-step prerequisite, each
+failure named with its remedy), `adia-contract-check.mjs` (authored markup
+attributes vs. the shipped component contracts), and `adia-theme-audit.mjs`
+(the theme.css redundancy classifier; see `theme-audit`).
 
 ## MCP
 
-`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.55` (tool SoT:
+`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.56` (tool SoT:
 `packages/gen-ui/mcp/TOOLS.md` — the `gen-ui` section; stability rule in
 `references/contracts/`; pin lives in `.mcp.json` — `check:plugin-count-claims`
 guards this README copy against it). The server is `adia-mcp gen-ui`,
@@ -120,6 +130,12 @@ plug-and-play install** — read this section before promising Pi/Hermes
 support for this plugin specifically, since its whole value proposition is
 wiring the `adia-gen-ui` MCP server.
 
+`theme-audit`'s `adia-theme-audit` bin runs identically on every harness — a
+plain Node script with no Claude-specific runtime dependency; the
+`/theme-audit` command degrades to invoking the skill directly on Codex and
+Hermes, and becomes a genuine `prompts/theme-audit.md` Pi command via
+`build:harness-manifests`.
+
 - **Codex** (gh#1888): `.codex-plugin/plugin.json` + per-skill
   `agents/openai.yaml`, derived; `mcpServers` points at the same
   `.mcp.json` Claude Code uses. No manifest key for hooks/commands/agents —

package/__init__.py

@@ -263,7 +263,7 @@ def register(ctx):
     ctx.register_skill(
         name="find-unused",
         path=Path(os.path.join(_HERE, "skills", "find-unused", "SKILL.md")),
-        description="Finds what a non-breaking @adia-ai upgrade shipped that this app never picked up — the opt-in layers nothing imports, the local workarounds a fixed bug made redundant, retired enum values still sitting in stored state, and the fixes that never reached MIGRATION.md. Use after \"we bumped and nothing broke\", \"what are we missing from 0.8.x\", \"are we actually using what we ship\", \"why is [scale]/[theme] doing nothing\", or when a PATCH span needs adoption rather than repair. NOT for breaking-change repair (app-migration); NOT for a first-time install (adia-scaffold); NOT for diagnosing a broken surface (app-audit).",
+        description="Finds what a non-breaking @adia-ai upgrade shipped that this app never picked up — the opt-in layers nothing imports, the local workarounds a fixed bug made redundant, retired enum values still sitting in stored state, and the fixes that never reached MIGRATION.md. Use after \"we bumped and nothing broke\", \"what are we missing from 0.8.x\", \"are we actually using what we ship\", \"why is [scale]/[theme] doing nothing\", or when a PATCH span needs adoption rather than repair. NOT for breaking-change repair (app-migration); NOT for a first-time install (adia-scaffold); NOT for diagnosing a broken surface (app-audit); NOT for CSS-only redundancy in a theme file (theme-audit — the CSS-side sibling).",
     )
     ctx.register_skill(
         name="gen-ui-wiring",
@@ -310,6 +310,11 @@ def register(ctx):
         path=Path(os.path.join(_HERE, "skills", "table-composition", "SKILL.md")),
         description="Answers how to display/organize tabular data with table-ui: contained vs uncontained chrome, [raw] (consumer-owned body, a separate axis), opt-in striped rows, and resize/sort defaults that flip between JS .columns and declarative col-def forms, plus inline-edit-grid and tree/hierarchical-row patterns. Use for \"how do I show a table\", \"add sorting/filtering\", \"make this table striped\", \"columns aren't resizable\", \"card vs bare table\", \"editable/spreadsheet grid\", \"tree table / nested rows\", \"huge list of rows\". NOT for composing the surrounding screen (screen-composition), data wiring (data-wiring), OTHER non-table patterns (pattern-catalog), or 1000+-row virtualized lists (list-window-ui).",
     )
+    ctx.register_skill(
+        name="theme-audit",
+        path=Path(os.path.join(_HERE, "skills", "theme-audit", "SKILL.md")),
+        description="Classifies a consumer app's theme.css against what the adia-ui framework already ships — restated defaults, re-derived tokens, dead selectors, and hand-built component work. Runs `adia-theme-audit` against a theme file + app root; audits and reports, never rewrites. Use when a theme.css is suspected of restating the kit, after bumping `@adia-ai/web-components`, or before a `find-unused` sweep. NOT for rendering/grading a surface (surface-qa); NOT for picking a token going forward (token-selection); NOT for JS/markup an upgrade left unused (find-unused — the CSS-side sibling); NOT for the framework's OWN token layer in packages/web-components (forge's component-token-audit).",
+    )
     ctx.register_skill(
         name="token-selection",
         path=Path(os.path.join(_HERE, "skills", "token-selection", "SKILL.md")),

package/agents/surface-qa-agent.md

@@ -9,6 +9,7 @@ description: |
 tools: Read, Grep, Glob, Bash
 skills:
   - surface-qa
+  - theme-audit
 # Explicit pin (gh#618, tier corrected gh#1045): a review/critic seat's
 # verdict must not depend on the caller's model tier — never `inherit`.
 # Operator's explicit standing instruction for this seat family: sonnet + xhigh.

package/commands/theme-audit.md

@@ -0,0 +1,28 @@
+---
+wraps: theme-audit
+description: Classify a consumer app's theme.css against what the adia-ui framework already ships — restated defaults, re-derived tokens, dead selectors, hand-built component work. Audit and report only; no rewrites.
+argument-hint: "[--theme <file>] [--app <root>]"
+disable-model-invocation: false
+user-invocable: true
+---
+
+Audit a theme stylesheet. **$ARGUMENTS**
+
+Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/adia-theme-audit.mjs" --theme <file>
+--app <root>` (add `--json`/`--json-out <path>` for a structured report,
+`--strict` to exit non-zero on any `high`-confidence finding, `--class
+1,2,3,4` to narrow scope). No `@adia-ai/web-components` resolvable from
+`<app>` → the tool reports `E_NO_FRAMEWORK` with the install remedy; pass
+`--framework-root <checkout>` to audit against an unreleased framework
+checkout instead. No `--base-url`/Playwright unreachable → class 3's
+rendered census degrades to `UNMEASURED` and the run still exits `0`
+(unless `--strict`); static `last-wins` detection still runs.
+
+Return the human-readable summary and per-class tables (theme-audit
+§Reading the report). Findings route back to the owning skill — a
+restated default or re-derived token deletes from the theme file directly;
+a hand-built-component finding routes to `screen-composition` to swap in
+the primitive; a dead selector still needs a human's confirmation before
+removal (the census may not have covered every interaction state). Never
+apply a fix inline from this command — theme-audit and its runner never
+rewrite the file, and neither does this wrapper.

package/hermes-mcp.yaml

@@ -6,5 +6,5 @@ mcp_servers:
     command: "npx"
     args:
       - "-y"
-      - "@adia-ai/mcp@0.8.55"
+      - "@adia-ai/mcp@0.8.56"
       - "gen-ui"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-factory",
-  "version": "0.8.55",
+  "version": "0.8.56",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "keywords": [
     "adia-ui",
@@ -19,6 +19,9 @@
   "bugs": {
     "email": "kim.granlund@adia.ai"
   },
+  "bin": {
+    "adia-theme-audit": "./scripts/adia-theme-audit.mjs"
+  },
   "pi": {
     "skills": ["./skills"],
     "prompts": ["./prompts"],

package/plugin.yaml

@@ -1,4 +1,4 @@
 name: "adia-ui-kit-factory"
-version: "0.8.55"
+version: "0.8.56"
 description: "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation."
 manifest_version: 1

package/prompts/theme-audit.md

@@ -0,0 +1,25 @@
+---
+description: "Classify a consumer app's theme.css against what the adia-ui framework already ships — restated defaults, re-derived tokens, dead selectors, hand-built component work. Audit and report only; no rewrites."
+argument-hint: "[--theme <file>] [--app <root>]"
+---
+
+Audit a theme stylesheet. **$ARGUMENTS**
+
+Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/adia-theme-audit.mjs" --theme <file>
+--app <root>` (add `--json`/`--json-out <path>` for a structured report,
+`--strict` to exit non-zero on any `high`-confidence finding, `--class
+1,2,3,4` to narrow scope). No `@adia-ai/web-components` resolvable from
+`<app>` → the tool reports `E_NO_FRAMEWORK` with the install remedy; pass
+`--framework-root <checkout>` to audit against an unreleased framework
+checkout instead. No `--base-url`/Playwright unreachable → class 3's
+rendered census degrades to `UNMEASURED` and the run still exits `0`
+(unless `--strict`); static `last-wins` detection still runs.
+
+Return the human-readable summary and per-class tables (theme-audit
+§Reading the report). Findings route back to the owning skill — a
+restated default or re-derived token deletes from the theme file directly;
+a hand-built-component finding routes to `screen-composition` to swap in
+the primitive; a dead selector still needs a human's confirmation before
+removal (the census may not have covered every interaction state). Never
+apply a fix inline from this command — theme-audit and its runner never
+rewrite the file, and neither does this wrapper.

package/scripts/adia-probe.mjs

@@ -72,7 +72,7 @@ export function isLargeText(fontSizePx, fontWeight) {
 }
 
 // samples: [{ text, element, fg:[r,g,b], bg:[r,g,b], fontSizePx, fontWeight }]
-export function scoreContrastSamples(samples, { skipped = 0 } = {}) {
+export function scoreContrastSamples(samples, { skipped = 0, unparsed = 0 } = {}) {
   const pairs = samples.map((s) => {
     const large = isLargeText(s.fontSizePx, s.fontWeight);
     const required = large ? 3.0 : 4.5;
@@ -85,12 +85,16 @@ export function scoreContrastSamples(samples, { skipped = 0 } = {}) {
     standard: 'WCAG AA — 4.5:1 normal / 3.0:1 large text (≥18pt, or ≥14pt bold)',
     checked: pairs.length,
     skippedImageBacked: skipped,
+    // Sampler health travels with the row even when some pairs parsed: a
+    // page with 1 literal rgb() pair and 200 unreadable token colors is a
+    // 1/1 pass only in the narrowest sense. Distinct unreadable strings.
+    ...(unparsed > 0 ? { unparsedColors: unparsed } : {}),
     failing,
     pairs,
   };
 }
 
-export function buildProof({ url, errors, boxes, screenshotPath, navTiming, perfBudgetMs = DEFAULT_PERF_BUDGET_MS, contrastSamples = null, contrastSkipped = 0 }) {
+export function buildProof({ url, errors, boxes, screenshotPath, navTiming, perfBudgetMs = DEFAULT_PERF_BUDGET_MS, contrastSamples = null, contrastSkipped = 0, contrastUnparsed = 0 }) {
   const consolePass = errors.length === 0;
   const boxFailures = Object.entries(boxes)
     .filter(([, b]) => !b || b.width <= 0 || b.height <= 0)
@@ -112,9 +116,13 @@ export function buildProof({ url, errors, boxes, screenshotPath, navTiming, perf
   // captured no samples (selftest fixtures, an all-image page, a sampler
   // crash). This mirrors the perf row's degradation shape but NOT its
   // advisory nature: a measured failing pair fails the verdict.
-  const contrast = contrastSamples
-    ? scoreContrastSamples(contrastSamples, { skipped: contrastSkipped })
-    : { pass: null, reason: 'UNMEASURED — no text foreground/background pairs sampled' };
+  // A page whose colors were SEEN but none PARSED is a broken sampler, not
+  // an unmeasurable page — fail loud instead of reporting UNMEASURED.
+  const contrast = contrastSamples?.length
+    ? scoreContrastSamples(contrastSamples, { skipped: contrastSkipped, unparsed: contrastUnparsed })
+    : contrastUnparsed > 0
+      ? { pass: false, checked: 0, failing: [], unparsedColors: contrastUnparsed, reason: `sampler parsed 0 pairs but saw ${contrastUnparsed} unreadable color value(s) — color syntax unsupported by the sampler` }
+      : { pass: null, reason: 'UNMEASURED — no text foreground/background pairs sampled' };
   return {
     record: 'VerifyProof',
     url,
@@ -176,6 +184,26 @@ function selftest() {
     { text: 'gray at body size', element: 'p', fg: [148, 148, 148], bg: [255, 255, 255], fontSizePx: 16, fontWeight: 400 },
     { text: 'gray as a heading', element: 'h1', fg: [148, 148, 148], bg: [255, 255, 255], fontSizePx: 24, fontWeight: 400 },
   ]);
+  // Sampler saw colors but parsed none — a broken sampler must fail loud,
+  // never degrade to UNMEASURED.
+  const allUnparsed = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 640, height: 480 } }, screenshotPath: 'p.png',
+    contrastUnparsed: 7,
+  });
+
+  const emptySamples = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 640, height: 480 } }, screenshotPath: 'p.png',
+    contrastSamples: [],
+  });
+  // One pair parsed, many colors unreadable — the pass stands (a measured
+  // pair is a measured pair) but the sampler-health count must ride on the
+  // row, never vanish behind a 1/1.
+  const partialUnparsed = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 640, height: 480 } }, screenshotPath: 'p.png',
+    contrastSamples: [{ text: 'ok', element: 'p', fg: [0, 0, 0], bg: [255, 255, 255], fontSizePx: 16, fontWeight: 400 }],
+    contrastUnparsed: 200,
+  });
+
   const fails = [];
   const bw = contrastRatio([0, 0, 0], [255, 255, 255]);
   if (bw < 20.9 || bw > 21.1) fails.push(`black/white ratio ${bw} not ≈21`);
@@ -198,6 +226,19 @@ function selftest() {
   if (good.gates.contrast.pass !== null || !good.gates.contrast.reason.includes('UNMEASURED')) {
     fails.push('missing contrast samples did not degrade to UNMEASURED contrast row');
   }
+  if (emptySamples.gates.contrast.pass !== null || emptySamples.verdict !== 'pass-pending-read') {
+    fails.push('empty contrast sample array did not degrade to UNMEASURED');
+  }
+  if (allUnparsed.verdict !== 'fail' || allUnparsed.gates.contrast.pass !== false
+      || !allUnparsed.gates.contrast.reason.includes('unreadable color')) {
+    fails.push('all-unparsed sampler did not fail loud');
+  }
+  if (partialUnparsed.gates.contrast.pass !== true || partialUnparsed.gates.contrast.unparsedColors !== 200) {
+    fails.push('partially-parsed sampler dropped the unparsedColors count');
+  }
+  if (good.gates.contrast.unparsedColors !== undefined) {
+    fails.push('unparsedColors leaked onto a row with nothing unparsed');
+  }
   if (good.verdict !== 'pass-pending-read') fails.push('good fixture not pass-pending-read');
   if (badBox.verdict !== 'fail' || badBox.gates.boundingBoxes.failing[0] !== 'my-surface') fails.push('0x0 box not failed');
   if (badErr.verdict !== 'fail' || badErr.gates.consoleErrors.pass) fails.push('console error not failed');
@@ -213,7 +254,7 @@ function selftest() {
     console.error('selftest FAIL: ' + fails.join(' | '));
     process.exit(1);
   }
-  console.log('selftest OK — 8 fixtures, verdicts + imageRead + advisory perf row + AA contrast gate (positive/negative/large-text) correct');
+  console.log('selftest OK — 11 fixtures, verdicts + imageRead + advisory perf row + AA contrast gate (positive/negative/large-text) correct');
   process.exit(0);
 }
 
@@ -310,11 +351,38 @@ async function main() {
   // guessed. Deduped by (fg, bg, size, weight) and capped, so the report
   // stays bounded on long pages.
   const sampled = await page.evaluate(() => {
+    // gh#1259 follow-up: computed styles come back as oklch()/color() in
+    // current Chromium for token-driven colors — the rgb() regex alone read
+    // checked:0 on every AdiaUI page. Any non-rgb syntax rasterizes through
+    // a 1x1 canvas (ground-truth sRGB bytes, not a hand-rolled conversion).
+    const rasterCtx = document.createElement('canvas').getContext('2d', { willReadFrequently: true });
+    rasterCtx.canvas.width = rasterCtx.canvas.height = 1;
+    // Memoized by the computed string: bgFor re-parses every ancestor
+    // background per text node, so without a memo the same token color
+    // rasterizes O(textNodes x depth) times and one unreadable body
+    // background counts once per visit instead of once. `unparsed` is
+    // the number of DISTINCT unreadable strings.
+    const memo = new Map();
+    let unparsed = 0;
     const parse = (s) => {
-      const m = /rgba?\(([^)]+)\)/.exec(s || '');
-      if (!m) return null;
-      const [r, g, b, a = 1] = m[1].split(',').map(Number);
-      return { rgb: [r, g, b], a };
+      if (!s) return null;
+      if (memo.has(s)) return memo.get(s);
+      let out = null;
+      const m = /rgba?\(([^)]+)\)/.exec(s);
+      if (m) {
+        const [r, g, b, a = 1] = m[1].split(',').map(Number);
+        out = { rgb: [r, g, b], a };
+      } else if (!CSS.supports('color', s)) {
+        unparsed += 1;
+      } else {
+        rasterCtx.fillStyle = s;
+        rasterCtx.clearRect(0, 0, 1, 1);
+        rasterCtx.fillRect(0, 0, 1, 1);
+        const d = rasterCtx.getImageData(0, 0, 1, 1).data;
+        out = { rgb: [d[0], d[1], d[2]], a: d[3] / 255 };
+      }
+      memo.set(s, out);
+      return out;
     };
     const over = (fg, a, bg) => fg.map((c, i) => Math.round(c * a + bg[i] * (1 - a)));
     const bgFor = (el) => {
@@ -322,7 +390,12 @@ async function main() {
       for (let n = el; n && n.nodeType === 1; n = n.parentElement || (n.getRootNode && n.getRootNode().host) || null) {
         const cs = getComputedStyle(n);
         if (cs.backgroundImage && cs.backgroundImage !== 'none') return null; // indeterminate — pixels, not computed styles
-        const c = parse(cs.backgroundColor);
+        const raw = cs.backgroundColor;
+        const c = parse(raw);
+        // An unreadable layer is indeterminate too, not transparent: falling
+        // through to the white default would score white-on-dark as ~1:1
+        // (measured, and wrong). Skip and count, same as the image branch.
+        if (raw && c === null) return null;
         if (c && c.a > 0) {
           layers.push(c);
           if (c.a >= 1) break;
@@ -382,7 +455,7 @@ async function main() {
       }
     };
     visitRoot(document.body);
-    return { samples, skipped };
+    return { samples, skipped, unparsed };
   }).catch(() => null);
   await page.screenshot({ path: screenshotPath, scale: 'device', fullPage: true });
   await browser.close();
@@ -391,6 +464,7 @@ async function main() {
     url, errors, boxes, screenshotPath, navTiming, perfBudgetMs,
     contrastSamples: sampled && sampled.samples.length ? sampled.samples : null,
     contrastSkipped: sampled ? sampled.skipped : 0,
+    contrastUnparsed: sampled ? sampled.unparsed : 0,
   });
   if (process.argv.includes('--json')) {
     console.log(JSON.stringify(proof, null, 1));
@@ -401,7 +475,9 @@ async function main() {
     const c = proof.gates.contrast;
     const contrastNote = c.pass === null
       ? 'contrast:UNMEASURED'
-      : `contrast:${c.pass ? 'pass' : 'FAIL'} ${c.checked - c.failing.length}/${c.checked} pairs${c.skippedImageBacked ? ` (+${c.skippedImageBacked} image-backed skipped)` : ''}`;
+      : c.reason
+        ? `contrast:FAIL ${c.reason}`
+      : `contrast:${c.pass ? 'pass' : 'FAIL'} ${c.checked - c.failing.length}/${c.checked} pairs${c.skippedImageBacked ? ` (+${c.skippedImageBacked} image-backed skipped)` : ''}${c.unparsedColors ? ` (+${c.unparsedColors} unreadable color value(s) — sampler coverage partial)` : ''}`;
     console.log(`[adia-probe] ${proof.verdict} — errors:${errors.length} boxes:${selectors.length - proof.gates.boundingBoxes.failing.length}/${selectors.length} shot:${screenshotPath} ${perfNote} ${contrastNote}`);
     if (proof.verdict === 'fail') {
       for (const e of errors) console.log(`  console: ${e}`);