@1aboveio/skills 0.10.0

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-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 reviewer attestation (verified: true, after manual check) 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
+// (blocking Unverified until attested/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). Blocking until reviewer attests or escalates ` +
+      `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}`)
+  }
+}

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

@@ -0,0 +1,154 @@
+// Presentation-axis Reachability & Affordance instrument for e2e-test (issue #197).
+//
+// "Can a user GET to a control and tell it's actionable" — plus the negative form,
+// "things that must be blocked are blocked" (modal focus-trap, no click-through,
+// wrong-role route not reachable). Tag specs `@level presentation:reachability`.
+//
+// Distinct from ensure-coverage's existing Route Reachability Protocol, which is
+// GUARD-CHAIN reachability ("can the URL load past middleware/auth"). This is
+// NAVIGATIONAL reachability ("can a user click their way here from an entry point").
+// A route can be guard-reachable yet navigation-orphaned (nothing links to it).
+//
+// Affordance↔impeccable boundary: the DETERMINISTIC affordance checks live here
+// (focus-indicator presence, ≥44px target size, nav-orphan). Holistic a11y
+// resilience and the *aesthetics* of focus styling stay in the `impeccable` skill
+// (its `harden` reference). This instrument proves the cue EXISTS; impeccable judges
+// whether it's good. See impeccable/reference/harden.md.
+
+// ---------- pure cores (no browser) ----------
+
+// Navigational orphans = routes the app DEFINES (manifest) minus routes REACHABLE
+// by crawling nav from an entry point. `ignore` suppresses intentionally
+// unlinked-but-valid routes (deep-link targets, auth callbacks) by exact id or
+// prefix ending in '*'.
+export function findNavOrphans(manifestRoutes, reachableRoutes, { ignore = [] } = {}) {
+  const reachable = new Set(reachableRoutes)
+  const matchesIgnore = (r) => ignore.some((ig) => (ig.endsWith('*') ? r.startsWith(ig.slice(0, -1)) : r === ig))
+  return manifestRoutes.filter((r) => !reachable.has(r) && !matchesIgnore(r))
+}
+
+// Minimum interactive target size (WCAG 2.5.5 / 2.5.8). Returns pass + which
+// dimension is short. Default 44px (24px is the relaxed AA floor — pass min).
+export function meetsTargetSize({ width = 0, height = 0 } = {}, min = 44) {
+  const short = []
+  if (width < min) short.push('width')
+  if (height < min) short.push('height')
+  return { pass: short.length === 0, min, width, height, short }
+}
+
+// A focusable control must show a VISIBLE focus indicator: focusing it must change
+// the outline or box-shadow vs its blurred state. Pure comparison of the two
+// computed-style snapshots; absence of any change == no visible focus ring.
+export function hasVisibleFocusIndicator(blurred = {}, focused = {}) {
+  const noOutline = (s) =>
+    !s.outlineStyle || s.outlineStyle === 'none' || parseFloat(s.outlineWidth || '0') === 0
+  // An outline change only counts if the FOCUSED outline is actually visible — a
+  // 0px-width color-only change (e.g. `0px solid red` → `0px solid blue`) paints
+  // nothing and must not pass.
+  const focusedHasOutline = !noOutline(focused)
+  const outlineVisibleAndChanged = focusedHasOutline && (
+    noOutline(blurred) ||
+    (blurred.outlineColor || '') !== (focused.outlineColor || '') ||
+    (blurred.outlineWidth || '') !== (focused.outlineWidth || '') ||
+    (blurred.outlineStyle || '') !== (focused.outlineStyle || '')
+  )
+  const shadowChanged = (blurred.boxShadow || 'none') !== (focused.boxShadow || 'none')
+  return Boolean(outlineVisibleAndChanged || shadowChanged)
+}
+
+// ---------- Playwright wrappers (need a real browser) ----------
+
+// BFS-crawl the navigational graph from `start`, clicking same-origin links the
+// rendered nav exposes, and return the set of reachable pathnames. Drives a real
+// browser so JS-rendered / hover/scroll-revealed nav is exercised. Seed an
+// authenticated context for guarded nav.
+export async function crawlReachableRoutes(page, { start = '/', maxPages = 200 } = {}) {
+  const origin = new URL(start, page.url() || 'http://localhost').origin
+  const seen = new Set()
+  const queue = [new URL(start, origin).pathname]
+  while (queue.length && seen.size < maxPages) {
+    const path = queue.shift()
+    if (seen.has(path)) continue
+    seen.add(path)
+    await page.goto(new URL(path, origin).href).catch(() => {})
+    const hrefs = await page.$$eval('a[href]', (as) => as.map((a) => a.getAttribute('href') || ''))
+    for (const h of hrefs) {
+      let u
+      try { u = new URL(h, origin) } catch { continue }
+      if (u.origin !== origin) continue
+      if (!seen.has(u.pathname)) queue.push(u.pathname)
+    }
+  }
+  return [...seen]
+}
+
+// Assert no navigational orphans: every manifest route is reachable by crawling.
+export async function assertNoNavOrphans(page, manifestRoutes, { start = '/', ignore = [] } = {}) {
+  const reachable = await crawlReachableRoutes(page, { start })
+  const orphans = findNavOrphans(manifestRoutes, reachable, { ignore })
+  if (orphans.length) {
+    throw new Error(`presentation:reachability — ${orphans.length} route(s) reachable by URL but linked from no nav:\n${orphans.map((o) => '  ' + o).join('\n')}`)
+  }
+}
+
+// Assert every matched interactive control meets the minimum target size.
+export async function assertTargetSizes(page, selector = 'a, button, [role="button"], input, select', { min = 44 } = {}) {
+  const boxes = await page.$$eval(selector, (els) => els
+    .filter((el) => el.offsetParent !== null)
+    .map((el) => { const r = el.getBoundingClientRect(); return { tag: el.tagName.toLowerCase(), id: el.id, width: r.width, height: r.height } }))
+  const small = boxes.map((b) => ({ ...b, ...meetsTargetSize(b, min) })).filter((b) => !b.pass)
+  if (small.length) {
+    throw new Error(`presentation:reachability — ${small.length} control(s) below ${min}px target:\n${small.map((s) => `  ${s.tag}${s.id ? '#' + s.id : ''} ${Math.round(s.width)}x${Math.round(s.height)}`).join('\n')}`)
+  }
+}
+
+// Assert a control shows a visible focus indicator when focused.
+export async function assertFocusVisible(page, locator) {
+  const read = () => locator.evaluate((el) => {
+    const s = getComputedStyle(el)
+    return { outlineStyle: s.outlineStyle, outlineWidth: s.outlineWidth, outlineColor: s.outlineColor, boxShadow: s.boxShadow }
+  })
+  const blurred = await read()
+  await locator.focus()
+  const focused = await read()
+  if (!hasVisibleFocusIndicator(blurred, focused)) {
+    throw new Error(`presentation:reachability (affordance) — control shows no visible focus indicator on focus: ${locator}`)
+  }
+}
+
+// Negative form: a modal must trap focus — tabbing never moves focus to an element
+// outside the modal (no escape to the background). Containment is checked on the
+// modal element the locator resolves to (no fragile re-derived global selector).
+export async function assertModalTrapsFocus(page, modalLocator, { tabs = 12 } = {}) {
+  for (let i = 0; i < tabs; i++) {
+    await page.keyboard.press('Tab')
+    const inside = await modalLocator.evaluate((modal) => modal.contains(document.activeElement))
+    if (!inside) {
+      throw new Error('presentation:reachability (negative) — focus escaped the modal; focus is not trapped')
+    }
+  }
+}
+
+// Negative form: with a modal open, a background element must not be interactable
+// (no click-through). Asserts the background is `inert`, `aria-hidden`, or covered
+// (pointer-events:none) — the standard ways an open dialog neutralizes the page.
+export async function assertNoBackgroundClickThrough(page, backgroundLocator) {
+  const interactable = await backgroundLocator.evaluate((el) => {
+    if (el.inert) return false
+    if (el.getAttribute('aria-hidden') === 'true') return false
+    if (getComputedStyle(el).pointerEvents === 'none') return false
+    return true // still interactable behind the modal — a click-through leak
+  })
+  if (interactable) {
+    throw new Error('presentation:reachability (negative) — background is still interactable behind the modal (click-through); expected inert / aria-hidden / pointer-events:none')
+  }
+}
+
+// Negative form: a privilege-gated route must NOT be navigationally reachable for a
+// user lacking the role (it must not appear in the crawl set).
+export async function assertRouteNotReachable(page, route, { start = '/' } = {}) {
+  const reachable = await crawlReachableRoutes(page, { start })
+  if (reachable.includes(route)) {
+    throw new Error(`presentation:reachability (negative) — privilege-gated route is reachable via nav for the wrong role: ${route}`)
+  }
+}

package/skills/engineering/e2e-test/scripts/presentation-render-health.mjs

@@ -0,0 +1,141 @@
+// Presentation-axis SPINE instrument for e2e-test: render-health.
+//
+// The cheapest, most foundational presentation check — does the page render
+// without a `pageerror` (uncaught exception), a `console.error`, a rendered error
+// boundary, or an HTTP >= 500? An uncaught TypeError on mount fails here before
+// any layout question is asked. This is the check that catches the class of bug a
+// green functional journey sails past when its only test of the route intercepts
+// the route's own API (the journey never exercises the real render path).
+//
+// Import into a Playwright spec and tag it `@covers <route>` /
+// `@level presentation:render-health` so the Coverage Ledger resolves it. Drives a
+// REAL browser — a DOM-only / JSDOM equivalent cannot observe a pageerror on mount
+// and is graded `Over-mocked` by the ledger. Mirrors the contract in ensure-coverage
+// references/presentation/runner-contract.md.
+
+// ---- pure, unit-testable core (no browser) ----
+
+// Default substrings that mark a console message or error as a framework/error-
+// boundary render failure regardless of source. Repos extend via `extraFatal`.
+export const DEFAULT_FATAL_MARKERS = [
+  'Application error: a client-side exception',
+  'Application error: a server-side exception',
+  'Unhandled Runtime Error',
+  'Cannot read properties of undefined',
+  'Cannot read properties of null',
+  'is not a function',
+  'Hydration failed',
+  'There was an error while hydrating',
+  'Minified React error',
+]
+
+// Decide whether a single captured console message is fatal. `type` is the console
+// level ('error' | 'warning' | …). console.error is fatal by default; warnings are
+// not. `ignore` suppresses known-benign messages by substring (curate sparingly).
+export function isFatalConsole(type, text, { ignore = [] } = {}) {
+  if (type !== 'error') return false
+  if (ignore.some((ig) => text.includes(ig))) return false
+  return true
+}
+
+// A response is fatal if the document or any first-party request returns >= 500.
+// Cross-origin (external) responses are ignored — externals are faked, not graded.
+export function isFatalResponse(status, url, { origin } = {}) {
+  if (status < 500) return false
+  if (origin && !url.startsWith(origin) && !url.startsWith('/')) return false
+  return true
+}
+
+// Does any captured text match an error-boundary / framework-error marker?
+export function hasFatalMarker(text, { extraFatal = [] } = {}) {
+  const markers = [...DEFAULT_FATAL_MARKERS, ...extraFatal]
+  return markers.some((m) => text.includes(m))
+}
+
+// Reduce a batch of captured signals into a verdict. Pure — the Playwright wrapper
+// collects `signals` and delegates here so the decision logic is testable headless.
+//   signals: { pageerrors:[{message}], consoles:[{type,text}], responses:[{status,url}], bodyText? }
+export function evaluateRenderHealth(signals = {}, opts = {}) {
+  const { ignore = [], extraFatal = [], origin } = opts
+  const offenders = []
+  for (const e of signals.pageerrors || []) {
+    offenders.push({ kind: 'pageerror', detail: e.message || String(e) })
+  }
+  for (const c of signals.consoles || []) {
+    if (isFatalConsole(c.type, c.text || '', { ignore })) {
+      offenders.push({ kind: 'console.error', detail: c.text })
+    }
+  }
+  for (const r of signals.responses || []) {
+    if (isFatalResponse(r.status, r.url || '', { origin })) {
+      offenders.push({ kind: 'http>=500', detail: `${r.status} ${r.url}` })
+    }
+  }
+  if (signals.bodyText && hasFatalMarker(signals.bodyText, { extraFatal })) {
+    offenders.push({ kind: 'error-boundary', detail: 'error overlay / boundary text present in DOM' })
+  }
+  return { healthy: offenders.length === 0, offenders }
+}
+
+// ---- browser wrapper (Playwright) ----
+
+// Attach listeners BEFORE navigation, then drive: returns a handle whose
+// `.assert()` throws with the concrete offender(s) if the page did not render
+// healthy. Usage:
+//   const health = watchRenderHealth(page, { origin: baseURL })
+//   await page.goto('/tasks')
+//   await page.waitForLoadState('networkidle').catch(() => {})
+//   await health.assert()
+export function watchRenderHealth(page, opts = {}) {
+  const signals = { pageerrors: [], consoles: [], responses: [] }
+  page.on('pageerror', (err) => signals.pageerrors.push({ message: err?.message || String(err) }))
+  page.on('console', (msg) => signals.consoles.push({ type: msg.type(), text: msg.text() }))
+  page.on('response', (res) => signals.responses.push({ status: res.status(), url: res.url() }))
+  return {
+    signals,
+    async evaluate() {
+      // Pull rendered body text so an error boundary that swallowed the throw is caught too.
+      try { signals.bodyText = await page.evaluate(() => document.body?.innerText || '') } catch { /* page gone */ }
+      return evaluateRenderHealth(signals, opts)
+    },
+    async assert() {
+      const { healthy, offenders } = await this.evaluate()
+      if (!healthy) {
+        const lines = offenders.map((o) => `  - [${o.kind}] ${o.detail}`).join('\n')
+        throw new Error(`presentation:render-health — page did not render cleanly:\n${lines}`)
+      }
+    },
+  }
+}
+
+// Continuous-invariant form: render-health must hold not only at LOAD but THROUGH an
+// interaction — a `presentation:temporal` trigger, a `presentation:perceivability`
+// post-delete mutation, or a mutation-form journey's submit. Attach the watcher,
+// run the interaction, then assert nothing threw during it. COMPOSE with the other
+// presentation instruments rather than re-driving the form:
+//
+//   await assertHealthyThrough(page, async () => {
+//     await assertRemovedAfterMutation(page, page.getByRole('row', { name: 'X' }))
+//   }, { origin: baseURL })
+//
+// This is "mutate-health": render-health × the trigger/mutation pattern temporal and
+// perceivability already use. The durable-state assertion (depth) and the visible
+// post-state assertion (perceivability) stay as-is; this adds "…and nothing threw
+// while it happened." Reuse one handle across several interactions for full lifecycle
+// coverage, or call this per interaction.
+export async function assertHealthyThrough(page, action, opts = {}) {
+  const health = watchRenderHealth(page, opts)
+  await action()
+  await health.assert()
+}
+
+// One-shot convenience: navigate and assert render-health in a single call.
+export async function assertRenderHealthy(page, url, opts = {}) {
+  const health = watchRenderHealth(page, opts)
+  const res = await page.goto(url, { waitUntil: 'domcontentloaded' })
+  await page.waitForLoadState('networkidle').catch(() => {})
+  if (res && isFatalResponse(res.status(), res.url(), { origin: opts.origin })) {
+    throw new Error(`presentation:render-health — document returned ${res.status()} for ${url}`)
+  }
+  await health.assert()
+}