@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/e2e-test/scripts/detect-routes-nextjs.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/*
+  detect-routes-nextjs.mjs
+
+  Detect all Next.js App Router routes and compare against route manifest.
+  Fails CI if any route exists in the app but not in the manifest.
+
+  Scans for page routes (page.tsx) and API routes (route.ts).
+
+  Handles Next.js conventions:
+    Route groups (auth)/ -- stripped from path
+    Dynamic segments [id]/ -- preserved
+    Catch-all [...slug]/ -- preserved
+    Parallel routes @panel/ -- skipped
+    Intercepting routes (.)/ -- skipped
+    Private folders _components/ -- skipped
+
+  Usage:
+    node detect-routes-nextjs.mjs [options]
+
+  Options:
+    --app-dir <path>       Path to app/ directory (default: src/app or app)
+    --manifest <path>      Path to route-manifest.json (default: e2e/route-manifest.json)
+    --strict               Exit 1 if any route is missing (default: true)
+    --no-strict            Only warn, don't fail
+
+  Exit codes:
+    0 -- all routes accounted for
+    1 -- routes missing from manifest (strict mode)
+*/
+
+import { readdirSync, existsSync, readFileSync, statSync } from 'fs';
+import { join, resolve, relative, sep } from 'path';
+
+// ─── CLI args ───────────────────────────────────────────────
+const args = process.argv.slice(2);
+function getArg(name, defaultVal) {
+  const idx = args.indexOf(`--${name}`);
+  return idx >= 0 && args[idx + 1] ? args[idx + 1] : defaultVal;
+}
+const hasFlag = (name) => args.includes(`--${name}`);
+const strict = !hasFlag('no-strict');
+
+// Auto-detect app directory
+function findAppDir() {
+  const explicit = getArg('app-dir', '');
+  if (explicit) return resolve(explicit);
+  if (existsSync('src/app')) return resolve('src/app');
+  if (existsSync('app')) return resolve('app');
+  return null;
+}
+
+const appDir = findAppDir();
+const manifestPath = resolve(getArg('manifest', 'e2e/route-manifest.json'));
+
+if (!appDir || !existsSync(appDir)) {
+  console.error(`❌ App directory not found. Use --app-dir <path>`);
+  process.exit(1);
+}
+
+// ─── Route scanning ─────────────────────────────────────────
+
+/**
+ * Recursively scan the app directory for page.tsx/ts and route.ts/tsx files.
+ * Returns an array of { path: string, type: 'page' | 'api', file: string }
+ */
+function scanRoutes(dir, segments = []) {
+  const routes = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return routes;
+  }
+
+  // Check for route files in current directory
+  const pageFile = entries.find(
+    (e) => e.isFile() && /^page\.(tsx?|jsx?)$/.test(e.name)
+  );
+  const routeFile = entries.find(
+    (e) => e.isFile() && /^route\.(tsx?|jsx?)$/.test(e.name)
+  );
+
+  if (pageFile) {
+    const routePath = '/' + segments.join('/') || '/';
+    routes.push({
+      path: routePath === '/' ? '/' : routePath,
+      type: 'page',
+      file: relative(process.cwd(), join(dir, pageFile.name)),
+    });
+  }
+
+  if (routeFile) {
+    const routePath = '/' + segments.join('/') || '/';
+    routes.push({
+      path: routePath,
+      type: 'api',
+      file: relative(process.cwd(), join(dir, routeFile.name)),
+    });
+  }
+
+  // Recurse into subdirectories
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const name = entry.name;
+
+    // Skip private folders (Next.js convention: _name)
+    if (name.startsWith('_')) continue;
+
+    // Skip parallel routes (@panel, @modal — not independent routes)
+    if (name.startsWith('@')) continue;
+
+    // Skip intercepting routes ((.), (..), (..)(..))
+    if (/^\(\.+\)/.test(name)) continue;
+
+    // Route groups: (groupName) => strip from path
+    if (/^\([^)]+\)$/.test(name) && !name.startsWith('(.)')) {
+      routes.push(...scanRoutes(join(dir, name), segments));
+      continue;
+    }
+
+    // Normal segment (including [dynamic], [...catchAll], [[...optional]])
+    routes.push(...scanRoutes(join(dir, name), [...segments, name]));
+  }
+
+  return routes;
+}
+
+// ─── Manifest comparison ────────────────────────────────────
+
+// Load manifest
+let manifest = { routes: [] };
+if (existsSync(manifestPath)) {
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    console.error(`❌ Invalid JSON in manifest: ${e.message}`);
+    process.exit(1);
+  }
+} else {
+  console.error(`❌ Manifest not found: ${manifestPath}`);
+  console.error(`   Create it with at minimum: { "version": 1, "routes": [] }`);
+  process.exit(1);
+}
+
+const manifestRoutes = new Set(
+  (manifest.routes || []).map((r) => r.path)
+);
+// Also check endpoints (for API routes in combined manifests)
+const manifestEndpoints = new Set(
+  (manifest.endpoints || []).map((r) => r.path)
+);
+const allManifestPaths = new Set([...manifestRoutes, ...manifestEndpoints]);
+
+// Scan
+console.log(`🔍 Scanning: ${relative(process.cwd(), appDir)}/`);
+console.log(`📋 Manifest: ${relative(process.cwd(), manifestPath)}\n`);
+
+const appRoutes = scanRoutes(appDir);
+const missing = [];
+const accounted = [];
+
+for (const route of appRoutes) {
+  if (allManifestPaths.has(route.path)) {
+    accounted.push(route);
+  } else {
+    missing.push(route);
+  }
+}
+
+// ─── Report ─────────────────────────────────────────────────
+
+console.log(`Found ${appRoutes.length} routes in app (${appRoutes.filter(r => r.type === 'page').length} pages, ${appRoutes.filter(r => r.type === 'api').length} API routes)`);
+console.log(`Manifest has ${allManifestPaths.size} entries`);
+console.log(`Accounted: ${accounted.length} | Missing: ${missing.length}\n`);
+
+if (missing.length > 0) {
+  console.log(`${'─'.repeat(60)}`);
+  console.log(`❌ Routes in app but NOT in manifest:\n`);
+  for (const route of missing) {
+    const tag = route.type === 'api' ? ' [API]' : '';
+    console.log(`  ${route.path}${tag}`);
+    console.log(`    └─ ${route.file}`);
+  }
+  console.log(`\n${'─'.repeat(60)}`);
+  console.log(`\nAdd these to ${relative(process.cwd(), manifestPath)}:`);
+  console.log(`  { "path": "<route>", "tier": 1, "specs": [] }\n`);
+  console.log(`Routes with specs: [] will pass CI but show as uncovered`);
+  console.log(`in the E2E PR comment.\n`);
+
+  if (strict) {
+    console.log('🚫 Failing CI (strict mode). Use --no-strict to warn only.');
+    process.exit(1);
+  } else {
+    console.log('⚠️  Warning only (non-strict mode).');
+  }
+} else {
+  console.log('✅ All app routes are accounted for in the manifest.');
+}

package/skills/engineering/e2e-test/scripts/presentation-checks.mjs

@@ -0,0 +1,171 @@
+// Presentation-axis instruments for e2e-test (issue #195).
+//
+// Real-rendered-page checks — import into a Playwright spec and tag it
+// `@covers <route>` / `@level presentation:spatial` so the Coverage Ledger
+// resolves it. The spine ships the Spatial/overflow invariant; later slices add
+// perceivability (contrast), reachability, and temporal (layout shift).
+//
+// These drive a REAL browser. A DOM-only / JSDOM equivalent cannot see layout and
+// is graded `Over-mocked` by the ledger — that is intentional.
+
+// The condition-matrix floor: every browser route is checked at these viewports.
+// Mirrors PRESENTATION_VIEWPORT_FLOOR in ensure-coverage's coverage-ledger.mjs.
+export const PRESENTATION_VIEWPORT_FLOOR = [
+  { name: 'mobile', width: 375, height: 812 },
+  { name: 'desktop', width: 1280, height: 800 },
+]
+
+// Pure predicate (no browser) — given element geometry and the viewport width,
+// return the elements that overflow horizontally. Extracted so the detection
+// logic is unit-testable without a browser; the Playwright wrapper collects the
+// geometry and delegates here.
+//
+//   elements: [{ selector, left, right, width, height }]
+export function findHorizontalOverflow(elements, viewportWidth, { tolerancePx = 1, ignore = [] } = {}) {
+  const offenders = []
+  for (const el of elements) {
+    if (!el.width || !el.height) continue // not rendered
+    const overflowsRight = el.right - tolerancePx > viewportWidth
+    const overflowsLeft = el.left < -tolerancePx
+    if (!overflowsRight && !overflowsLeft) continue
+    if (ignore.some((ig) => (el.selector || '').includes(ig))) continue
+    offenders.push({
+      selector: el.selector,
+      overflowPx: Math.round(overflowsRight ? el.right - viewportWidth : -el.left),
+    })
+  }
+  return offenders
+}
+
+// In-browser collector, serialized into page.evaluate. Returns the viewport width
+// and one record per body descendant.
+function collectGeometry() {
+  const vw = document.documentElement.clientWidth
+  const sel = (el) => {
+    if (el.id) return '#' + el.id
+    let s = el.tagName.toLowerCase()
+    if (typeof el.className === 'string' && el.className.trim()) {
+      s += '.' + el.className.trim().split(/\s+/).join('.')
+    }
+    return s
+  }
+  const elements = [...document.querySelectorAll('body *')].map((el) => {
+    const r = el.getBoundingClientRect()
+    return { selector: sel(el), left: r.left, right: r.right, width: r.width, height: r.height }
+  })
+  return { vw, elements }
+}
+
+// Assert no unintended horizontal overflow at each floor viewport. Throws with the
+// offending selectors + overflow amounts. `ignore` suppresses intentional cases by
+// substring match on the selector (curate sparingly).
+export async function assertNoHorizontalOverflow(page, { viewports = PRESENTATION_VIEWPORT_FLOOR, tolerancePx = 1, ignore = [] } = {}) {
+  const offenders = []
+  for (const vp of viewports) {
+    await page.setViewportSize({ width: vp.width, height: vp.height })
+    // Let layout settle (fonts/images) — real condition, not a fixed sleep.
+    await page.waitForLoadState('networkidle').catch(() => {})
+    const { vw, elements } = await page.evaluate(collectGeometry)
+    for (const o of findHorizontalOverflow(elements, vw, { tolerancePx, ignore })) {
+      offenders.push({ viewport: vp.name, width: vp.width, ...o })
+    }
+  }
+  if (offenders.length) {
+    const lines = offenders.map((o) => `  [${o.viewport} ${o.width}px] ${o.selector} overflows by ${o.overflowPx}px`)
+    throw new Error(`presentation:spatial — horizontal overflow detected:\n${lines.join('\n')}`)
+  }
+}
+
+// ---------- overlap detection (part of presentation:spatial) ----------
+
+// Pure AABB intersection test with a tolerance (sub-pixel touching is not overlap).
+export function rectsIntersect(a, b, tolerancePx = 1) {
+  return (
+    a.left < b.right - tolerancePx &&
+    a.right > b.left + tolerancePx &&
+    a.top < b.bottom - tolerancePx &&
+    a.bottom > b.top + tolerancePx
+  )
+}
+
+// Pure: find intersecting element pairs. `elements` is a flat list of rendered
+// elements with geometry + an `interactive` flag; only sibling-ish *content*
+// overlaps matter, so a pair where one element CONTAINS the other (nesting) is
+// skipped — nesting is normal, collision is not.
+function contains(outer, inner, tol = 1) {
+  return outer.left - tol <= inner.left && outer.right + tol >= inner.right &&
+    outer.top - tol <= inner.top && outer.bottom + tol >= inner.bottom
+}
+export function findOverlaps(elements, { tolerancePx = 1 } = {}) {
+  const els = elements.filter((e) => (e.rect?.width || 0) > 0 && (e.rect?.height || 0) > 0)
+  const pairs = []
+  for (let i = 0; i < els.length; i++) {
+    for (let j = i + 1; j < els.length; j++) {
+      const a = els[i], b = els[j]
+      if (!rectsIntersect(a.rect, b.rect, tolerancePx)) continue
+      if (contains(a.rect, b.rect, tolerancePx) || contains(b.rect, a.rect, tolerancePx)) continue // nesting
+      pairs.push({ a: a.selector, b: b.selector, aInteractive: !!a.interactive, bInteractive: !!b.interactive })
+    }
+  }
+  return pairs
+}
+
+// Pure: apply the GATED allowlist to overlap pairs. An allowlist entry needs a
+// `match` (substring tested against either selector), a `category`, and a `reason`.
+// GATE (mirrors the Surface Baseline Contract's exclusion gate): an entry may NOT
+// suppress a pair where an **interactive** element is occluded — you cannot
+// allowlist a reachable control into invisibility. Returns reported (still failing),
+// suppressed (census), and rejected (bad allowlist usage — also failing).
+export function applyOverlapAllowlist(pairs, allowlist = []) {
+  const reported = [], suppressed = [], rejected = []
+  for (const p of pairs) {
+    const entry = allowlist.find((e) => e.match && (p.a.includes(e.match) || p.b.includes(e.match)))
+    if (!entry) { reported.push(p); continue }
+    if (!entry.category || !entry.reason) { rejected.push({ ...p, why: 'allowlist entry needs category + reason' }); continue }
+    if (p.aInteractive || p.bInteractive) { rejected.push({ ...p, why: `cannot allowlist an overlap that occludes an interactive element (${entry.category})` }); continue }
+    suppressed.push({ ...p, category: entry.category, reason: entry.reason })
+  }
+  return { reported, suppressed, rejected }
+}
+
+// In-browser collector for overlap: geometry + interactivity per element.
+function collectOverlapGeometry() {
+  const sel = (el) => {
+    if (el.id) return '#' + el.id
+    let s = el.tagName.toLowerCase()
+    if (typeof el.className === 'string' && el.className.trim()) s += '.' + el.className.trim().split(/\s+/).join('.')
+    return s
+  }
+  const INTERACTIVE = 'a,button,input,select,textarea,[role="button"],[role="link"],[tabindex]'
+  return [...document.querySelectorAll('body *')].map((el) => {
+    const r = el.getBoundingClientRect()
+    return {
+      selector: sel(el),
+      rect: { left: r.left, top: r.top, right: r.right, bottom: r.bottom, width: r.width, height: r.height },
+      interactive: el.matches(INTERACTIVE),
+    }
+  })
+}
+
+// Assert no unintended element overlap. Intentional z-stacks (carousels, badges,
+// sticky headers) are suppressed only via the gated `allowlist`
+// (`[{ match, category, reason }]`); the suppressions are returned as a visible
+// census. Throws on real overlaps and on rejected (ungated/interactive) allowlist use.
+export async function assertNoOverlap(page, { selector, tolerancePx = 1, allowlist = [], viewports = PRESENTATION_VIEWPORT_FLOOR } = {}) {
+  const failures = [], census = []
+  for (const vp of viewports) {
+    await page.setViewportSize({ width: vp.width, height: vp.height })
+    await page.waitForLoadState('networkidle').catch(() => {})
+    let elements = await page.evaluate(collectOverlapGeometry)
+    if (selector) elements = elements.filter((e) => e.selector.includes(selector))
+    const pairs = findOverlaps(elements, { tolerancePx })
+    const { reported, suppressed, rejected } = applyOverlapAllowlist(pairs, allowlist)
+    for (const r of [...reported, ...rejected]) failures.push({ viewport: vp.name, ...r })
+    for (const s of suppressed) census.push({ viewport: vp.name, ...s })
+  }
+  if (failures.length) {
+    const lines = failures.map((f) => `  [${f.viewport}] ${f.a} ⨯ ${f.b}${f.why ? ` — ${f.why}` : ''}`)
+    throw new Error(`presentation:spatial — element overlap detected:\n${lines.join('\n')}`)
+  }
+  return { census } // visible record of intentional, gated suppressions
+}

package/skills/engineering/e2e-test/scripts/presentation-checks.test.mjs

@@ -0,0 +1,106 @@
+// Unit tests for the pure overflow predicate (issue #195). Run: `node --test`.
+// The Playwright wrapper (assertNoHorizontalOverflow) needs a real browser and is
+// exercised downstream; this proves the detection logic without one.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  findHorizontalOverflow, PRESENTATION_VIEWPORT_FLOOR,
+  rectsIntersect, findOverlaps, applyOverlapAllowlist,
+} from './presentation-checks.mjs'
+
+// helper: build an element with a rect + interactive flag
+const el = (selector, [left, top, right, bottom], interactive = false) =>
+  ({ selector, rect: { left, top, right, bottom, width: right - left, height: bottom - top }, interactive })
+
+const VW = 375
+
+test('no overflow when everything fits', () => {
+  const els = [
+    { selector: 'header', left: 0, right: 375, width: 375, height: 60 },
+    { selector: '.card', left: 16, right: 359, width: 343, height: 120 },
+  ]
+  assert.deepEqual(findHorizontalOverflow(els, VW), [])
+})
+
+test('flags an element wider than the viewport (right overflow)', () => {
+  const els = [{ selector: '.wide-table', left: 0, right: 520, width: 520, height: 200 }]
+  const out = findHorizontalOverflow(els, VW)
+  assert.equal(out.length, 1)
+  assert.equal(out[0].selector, '.wide-table')
+  assert.equal(out[0].overflowPx, 145) // 520 - 375
+})
+
+test('flags a negatively-positioned element (left overflow)', () => {
+  const els = [{ selector: '#drawer', left: -120, right: 200, width: 320, height: 400 }]
+  const out = findHorizontalOverflow(els, VW)
+  assert.equal(out.length, 1)
+  assert.equal(out[0].overflowPx, 120)
+})
+
+test('respects the tolerance band (sub-pixel rounding does not flag)', () => {
+  const els = [{ selector: '.x', left: 0, right: 375.5, width: 375.5, height: 10 }]
+  assert.deepEqual(findHorizontalOverflow(els, VW, { tolerancePx: 1 }), [])
+})
+
+test('ignore list suppresses intentional overflow by selector substring', () => {
+  const els = [{ selector: '.carousel-track', left: 0, right: 900, width: 900, height: 150 }]
+  assert.deepEqual(findHorizontalOverflow(els, VW, { ignore: ['carousel'] }), [])
+})
+
+test('zero-size (unrendered) elements are skipped', () => {
+  const els = [{ selector: '.hidden', left: 0, right: 999, width: 0, height: 0 }]
+  assert.deepEqual(findHorizontalOverflow(els, VW), [])
+})
+
+test('viewport floor is the documented 375 + 1280 pair', () => {
+  assert.deepEqual(PRESENTATION_VIEWPORT_FLOOR.map((v) => v.width), [375, 1280])
+})
+
+// ---------- overlap detection (presentation:spatial) ----------
+
+test('rectsIntersect: overlapping yes, separated no, touching (within tol) no', () => {
+  const a = { left: 0, top: 0, right: 100, bottom: 50 }
+  assert.equal(rectsIntersect(a, { left: 50, top: 25, right: 150, bottom: 75 }), true)
+  assert.equal(rectsIntersect(a, { left: 200, top: 0, right: 300, bottom: 50 }), false)
+  assert.equal(rectsIntersect(a, { left: 100, top: 0, right: 200, bottom: 50 }), false) // edge-touch
+})
+
+test('findOverlaps: flags a collision but skips pure nesting', () => {
+  const parent = el('.card', [0, 0, 200, 200])
+  const child = el('.card .title', [10, 10, 190, 40]) // nested inside parent
+  const stray = el('.badge', [180, 180, 260, 260]) // overlaps parent corner
+  const pairs = findOverlaps([parent, child, stray])
+  // parent⨯child is nesting (skipped); parent⨯stray is a real overlap
+  assert.equal(pairs.length, 1)
+  assert.equal(pairs[0].b, '.badge')
+})
+
+test('applyOverlapAllowlist: gated suppression yields a census entry', () => {
+  const pairs = [{ a: '.carousel-track', b: '.carousel-slide', aInteractive: false, bInteractive: false }]
+  const r = applyOverlapAllowlist(pairs, [{ match: 'carousel', category: 'decorative', reason: 'z-stacked slides' }])
+  assert.equal(r.reported.length, 0)
+  assert.equal(r.suppressed.length, 1)
+  assert.equal(r.suppressed[0].reason, 'z-stacked slides')
+})
+
+test('applyOverlapAllowlist: entry without category/reason is rejected (still fails)', () => {
+  const pairs = [{ a: '.x', b: '.y', aInteractive: false, bInteractive: false }]
+  const r = applyOverlapAllowlist(pairs, [{ match: '.x' }])
+  assert.equal(r.suppressed.length, 0)
+  assert.equal(r.rejected.length, 1)
+})
+
+test('applyOverlapAllowlist: cannot allowlist an overlap that occludes an interactive element', () => {
+  const pairs = [{ a: '.overlay', b: 'button#save', aInteractive: false, bInteractive: true }]
+  const r = applyOverlapAllowlist(pairs, [{ match: '.overlay', category: 'decorative', reason: 'hero flourish' }])
+  assert.equal(r.suppressed.length, 0)
+  assert.equal(r.rejected.length, 1)
+  assert.match(r.rejected[0].why, /interactive/)
+})
+
+test('applyOverlapAllowlist: unmatched overlap is reported', () => {
+  const pairs = [{ a: '.a', b: '.b', aInteractive: false, bInteractive: false }]
+  const r = applyOverlapAllowlist(pairs, [{ match: '.zzz', category: 'decorative', reason: 'n/a' }])
+  assert.equal(r.reported.length, 1)
+})

package/skills/engineering/e2e-test/scripts/presentation-perceivability.mjs

@@ -0,0 +1,179 @@
+// Presentation-axis Perceivability instrument for e2e-test (issue #196).
+//
+// "Can a human actually see/distinguish this control" — and its negative form,
+// "is something that must be hidden actually gone" (privilege leak, stale item).
+//
+// Positive form uses axe-core's `color-contrast` rule against the REAL rendered
+// page. Tag the spec `@covers <route>` / `@level presentation:perceivability`.
+// A DOM-only / JSDOM equivalent is graded Over-mocked by the ledger.
+//
+// Abstain doctrine: axe abstains ("incomplete") on text over a background-image /
+// gradient / partially-obscured element — exactly the case that hides an invisible
+// control. An abstain is NOT a silent pass: it surfaces as a blocking AbstainError.
+// Resolve it by a manual check (verified: true) OR by
+// escalating to a stronger instrument (screenshot / AI-vision triage). AI-vision is
+// triage-only — it may flag for human attestation but can never by itself promote
+// an obligation to Covered (run-to-run non-determinism).
+
+// Distinguishable error so callers/CI can tell an abstain from a hard violation.
+export class AbstainError extends Error {
+  constructor(message, details) {
+    super(message)
+    this.name = 'AbstainError'
+    this.abstain = true
+    this.details = details
+  }
+}
+
+// ---------- pure WCAG contrast math (testable, no browser) ----------
+
+// sRGB channel [0..255] → linearized component for relative luminance.
+function linearize(c) {
+  const s = c / 255
+  return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+}
+
+// WCAG relative luminance of an [r,g,b] triple.
+export function relativeLuminance([r, g, b]) {
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b)
+}
+
+// WCAG contrast ratio between two [r,g,b] colors → 1..21.
+export function contrastRatio(rgb1, rgb2) {
+  const l1 = relativeLuminance(rgb1)
+  const l2 = relativeLuminance(rgb2)
+  const [hi, lo] = l1 >= l2 ? [l1, l2] : [l2, l1]
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+// Does fg-on-bg meet the WCAG threshold? large text & non-text UI components use
+// 3:1; normal text uses 4.5:1 (AA). Returns the ratio, threshold, and pass.
+export function meetsContrast(fg, bg, { large = false, nonText = false } = {}) {
+  const ratio = contrastRatio(fg, bg)
+  const threshold = nonText || large ? 3 : 4.5
+  return { ratio: Math.round(ratio * 100) / 100, threshold, pass: ratio >= threshold }
+}
+
+// ---------- pure axe-result classifier (testable, no browser) ----------
+
+// Map an axe-core run to one of three Presentation outcomes for color-contrast.
+// `pass` → satisfied; `fail` → hard violation; `abstain` → axe could not decide
+// (`Unverified` until read and marked verified, or escalated).
+export function classifyAxeContrast(axeResults = {}) {
+  const pick = (arr) => (arr || []).filter((r) => r.id === 'color-contrast')
+  const violations = pick(axeResults.violations)
+  const incomplete = pick(axeResults.incomplete)
+  if (violations.length) {
+    const nodes = violations.flatMap((v) => v.nodes || [])
+    return { status: 'fail', count: nodes.length, nodes }
+  }
+  if (incomplete.length) {
+    const nodes = incomplete.flatMap((v) => v.nodes || [])
+    return { status: 'abstain', count: nodes.length, nodes }
+  }
+  return { status: 'pass', count: 0, nodes: [] }
+}
+
+// ---------- pure visibility predicate (testable, no browser) ----------
+
+// Is an element effectively hidden from a sighted user? Used by the negative form
+// (a privilege-leaked control must be truly gone, not just visually small) and to
+// AVOID false-flagging intentionally non-rendered state. `style` is the element's
+// computed style snapshot; `rect` its bounding box.
+export function isEffectivelyHidden({ style = {}, rect = {}, ariaHidden = false } = {}) {
+  if (style.display === 'none') return true
+  if (style.visibility === 'hidden' || style.visibility === 'collapse') return true
+  if (Number(style.opacity) === 0) return true
+  if (ariaHidden) return true
+  if ((rect.width || 0) === 0 || (rect.height || 0) === 0) return true
+  return false
+}
+
+// State-aware: a disabled control is *intended* to be low-contrast (WCAG exempts
+// it), so a contrast check must skip it rather than false-flag.
+//
+// NOTE on where this runs: `assertContrast` delegates to axe-core, which already
+// skips disabled controls natively — so the primary path does NOT call this. This
+// predicate (and `assessElementContrast` below) is the **manual / escalation path**:
+// when axe abstains and a reviewer escalates to per-element checking, they compute
+// contrast for the specific element here, and this is where the disabled-exemption
+// is enforced.
+export function isExemptFromContrast({ disabled = false, ariaDisabled = false } = {}) {
+  return disabled || ariaDisabled
+}
+
+// Manual / escalation per-element contrast assessment. Composes the disabled
+// exemption with the WCAG threshold check → 'exempt' | 'pass' | 'fail'. Pure and
+// testable; used when axe abstains and a reviewer resolves a specific element by
+// reading its computed fg/bg colors.
+export function assessElementContrast(fg, bg, { large = false, nonText = false, disabled = false, ariaDisabled = false } = {}) {
+  if (isExemptFromContrast({ disabled, ariaDisabled })) return { status: 'exempt' }
+  const m = meetsContrast(fg, bg, { large, nonText })
+  return { status: m.pass ? 'pass' : 'fail', ratio: m.ratio, threshold: m.threshold }
+}
+
+// ---------- Playwright wrappers (need a real browser) ----------
+
+// Assert the rendered page has no color-contrast violations. Requires
+// @axe-core/playwright (peer dep). On a hard violation → throws Error; on an axe
+// abstain ("incomplete") → throws AbstainError (blocking, resolve by attest/escalate).
+export async function assertContrast(page, { axeBuilder, include, exclude } = {}) {
+  if (!axeBuilder) {
+    // Lazy import so the pure exports above are usable without the peer dep.
+    const mod = await import('@axe-core/playwright')
+    const AxeBuilder = mod.default || mod.AxeBuilder
+    axeBuilder = new AxeBuilder({ page })
+  }
+  let builder = axeBuilder.withRules(['color-contrast'])
+  if (include) builder = builder.include(include)
+  if (exclude) builder = builder.exclude(exclude)
+  const results = await builder.analyze()
+  const c = classifyAxeContrast(results)
+  if (c.status === 'fail') {
+    const where = c.nodes.map((n) => '  ' + (n.target || []).join(' ')).join('\n')
+    throw new Error(`presentation:perceivability — ${c.count} contrast violation(s):\n${where}`)
+  }
+  if (c.status === 'abstain') {
+    const where = c.nodes.map((n) => '  ' + (n.target || []).join(' ')).join('\n')
+    throw new AbstainError(
+      `presentation:perceivability — axe could not decide contrast for ${c.count} element(s) ` +
+      `(text over image/gradient/obscured). Unverified until checked by hand and marked verified, or escalated ` +
+      `to a screenshot/AI-vision triage:\n${where}`,
+      c,
+    )
+  }
+  return c // { status: 'pass' }
+}
+
+// Negative form: a control gated to a role must NOT be present/visible for a user
+// lacking that role (a visual privilege leak). `locator` should resolve to the
+// gated control; asserts it is absent or effectively hidden. Uses the pure
+// `isEffectivelyHidden` predicate against the element's computed style + box, which
+// catches cases Playwright's `isVisible()` misses (e.g. opacity:0 with non-zero
+// size — visually invisible but still a leak if it were the positive case).
+export async function assertHiddenFromWrongRole(page, locator) {
+  const count = await locator.count()
+  if (count === 0) return // not rendered — good
+  const snap = await locator.first().evaluate((el) => {
+    const cs = getComputedStyle(el)
+    const r = el.getBoundingClientRect()
+    return {
+      style: { display: cs.display, visibility: cs.visibility, opacity: cs.opacity },
+      rect: { width: r.width, height: r.height },
+      ariaHidden: el.getAttribute('aria-hidden') === 'true',
+    }
+  })
+  if (!isEffectivelyHidden(snap)) {
+    throw new Error(`presentation:perceivability (negative) — privilege-gated control is visible to a user without the role: ${locator}`)
+  }
+}
+
+// Negative form: after a delete/optimistic mutation, the item must be gone from the
+// rendered page (no ghost/stale row).
+export async function assertRemovedAfterMutation(page, locator, { timeout = 5000 } = {}) {
+  await locator.waitFor({ state: 'detached', timeout }).catch(() => {})
+  const count = await locator.count()
+  if (count !== 0) {
+    throw new Error(`presentation:perceivability (negative) — item still rendered after its mutation (stale/ghost): ${locator}`)
+  }
+}