@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,117 @@
+// Unit tests for the pure Perceivability cores (issue #196). Run: `node --test`.
+// The Playwright wrappers (assertContrast / assertHiddenFromWrongRole /
+// assertRemovedAfterMutation) need a real browser + @axe-core/playwright and are
+// exercised downstream; the contrast math, axe classifier, and predicates are
+// proven here without one.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  relativeLuminance, contrastRatio, meetsContrast, classifyAxeContrast,
+  isEffectivelyHidden, isExemptFromContrast, assessElementContrast, AbstainError,
+} from './presentation-perceivability.mjs'
+
+const WHITE = [255, 255, 255]
+const BLACK = [0, 0, 0]
+
+// ---------- WCAG math ----------
+
+test('relative luminance: white ~1, black 0', () => {
+  assert.ok(Math.abs(relativeLuminance(WHITE) - 1) < 1e-9)
+  assert.equal(relativeLuminance(BLACK), 0)
+})
+
+test('contrast ratio: black on white is 21:1, white on white is 1:1', () => {
+  assert.ok(Math.abs(contrastRatio(BLACK, WHITE) - 21) < 1e-6)
+  assert.ok(Math.abs(contrastRatio(WHITE, WHITE) - 1) < 1e-9)
+  assert.equal(contrastRatio(BLACK, WHITE), contrastRatio(WHITE, BLACK)) // symmetric
+})
+
+test('meetsContrast: black text on white passes AA', () => {
+  const r = meetsContrast(BLACK, WHITE)
+  assert.equal(r.threshold, 4.5)
+  assert.equal(r.pass, true)
+})
+
+test('meetsContrast: a faint gray fails both text and non-text', () => {
+  const faint = [170, 170, 170] // ~2.3:1 on white
+  assert.equal(meetsContrast(faint, WHITE).pass, false)
+  assert.equal(meetsContrast(faint, WHITE, { nonText: true }).pass, false)
+})
+
+test('meetsContrast: threshold flips between text (4.5) and non-text (3.0)', () => {
+  const mid = [130, 130, 130] // ~3.8:1 on white — between 3 and 4.5
+  const asText = meetsContrast(mid, WHITE)
+  const asUi = meetsContrast(mid, WHITE, { nonText: true })
+  assert.equal(asText.threshold, 4.5)
+  assert.equal(asText.pass, false, 'fails as normal text')
+  assert.equal(asUi.threshold, 3)
+  assert.equal(asUi.pass, true, 'passes as a UI component / large text')
+})
+
+// ---------- axe classifier ----------
+
+test('classifyAxeContrast: no findings → pass', () => {
+  assert.equal(classifyAxeContrast({ violations: [], incomplete: [] }).status, 'pass')
+  assert.equal(classifyAxeContrast({}).status, 'pass')
+})
+
+test('classifyAxeContrast: a color-contrast violation → fail', () => {
+  const res = { violations: [{ id: 'color-contrast', nodes: [{ target: ['.btn'] }] }], incomplete: [] }
+  const c = classifyAxeContrast(res)
+  assert.equal(c.status, 'fail')
+  assert.equal(c.count, 1)
+})
+
+test('classifyAxeContrast: incomplete (gradient/image) → abstain, not pass', () => {
+  const res = { violations: [], incomplete: [{ id: 'color-contrast', nodes: [{ target: ['.hero'] }] }] }
+  assert.equal(classifyAxeContrast(res).status, 'abstain')
+})
+
+test('classifyAxeContrast: violation outranks incomplete; other rule ids ignored', () => {
+  const res = {
+    violations: [{ id: 'color-contrast', nodes: [{}] }, { id: 'label', nodes: [{}] }],
+    incomplete: [{ id: 'color-contrast', nodes: [{}] }],
+  }
+  const c = classifyAxeContrast(res)
+  assert.equal(c.status, 'fail')
+  assert.equal(c.count, 1, 'only color-contrast nodes counted')
+})
+
+// ---------- visibility / exemption predicates ----------
+
+test('isEffectivelyHidden: catches display/visibility/opacity/aria/zero-size', () => {
+  assert.equal(isEffectivelyHidden({ style: { display: 'none' } }), true)
+  assert.equal(isEffectivelyHidden({ style: { visibility: 'hidden' } }), true)
+  assert.equal(isEffectivelyHidden({ style: { opacity: '0' } }), true)
+  assert.equal(isEffectivelyHidden({ ariaHidden: true }), true)
+  assert.equal(isEffectivelyHidden({ rect: { width: 0, height: 10 } }), true)
+})
+
+test('isEffectivelyHidden: a normal visible element is not hidden', () => {
+  assert.equal(isEffectivelyHidden({ style: { display: 'block', visibility: 'visible', opacity: '1' }, rect: { width: 100, height: 40 } }), false)
+})
+
+test('isExemptFromContrast: disabled controls are exempt (WCAG), normal are not', () => {
+  assert.equal(isExemptFromContrast({ disabled: true }), true)
+  assert.equal(isExemptFromContrast({ ariaDisabled: true }), true)
+  assert.equal(isExemptFromContrast({}), false)
+})
+
+test('assessElementContrast (manual/escalation path) composes exemption + threshold', () => {
+  // disabled → exempt, regardless of (bad) colors
+  assert.equal(assessElementContrast(WHITE, WHITE, { disabled: true }).status, 'exempt')
+  // enabled, good contrast → pass
+  assert.equal(assessElementContrast(BLACK, WHITE).status, 'pass')
+  // enabled, faint gray → fail, with ratio reported
+  const fail = assessElementContrast([170, 170, 170], WHITE)
+  assert.equal(fail.status, 'fail')
+  assert.ok(fail.ratio < fail.threshold)
+})
+
+test('AbstainError is distinguishable from a hard failure', () => {
+  const e = new AbstainError('x', { count: 2 })
+  assert.equal(e.abstain, true)
+  assert.equal(e.name, 'AbstainError')
+  assert.ok(e instanceof Error)
+})

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-reachability.test.mjs

@@ -0,0 +1,69 @@
+// Unit tests for the pure Reachability & Affordance cores (issue #197).
+// Run: `node --test`. The Playwright wrappers (crawlReachableRoutes,
+// assertNoNavOrphans, assertTargetSizes, assertFocusVisible, assertModalTrapsFocus,
+// assertRouteNotReachable) need a real browser and are exercised downstream.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { findNavOrphans, meetsTargetSize, hasVisibleFocusIndicator } from './presentation-reachability.mjs'
+
+// ---------- nav-orphan set diff ----------
+
+test('findNavOrphans: routes in manifest but not reachable are orphans', () => {
+  const manifest = ['/', '/dashboard', '/settings', '/secret-report']
+  const reachable = ['/', '/dashboard', '/settings']
+  assert.deepEqual(findNavOrphans(manifest, reachable), ['/secret-report'])
+})
+
+test('findNavOrphans: none when everything is reachable', () => {
+  assert.deepEqual(findNavOrphans(['/', '/a'], ['/', '/a', '/extra']), [])
+})
+
+test('findNavOrphans: ignore by exact id and by prefix glob', () => {
+  const manifest = ['/', '/auth/callback', '/admin/secret', '/deep/x', '/deep/y']
+  const reachable = ['/']
+  // exact ignore for the callback, prefix ignore for everything under /deep
+  const orphans = findNavOrphans(manifest, reachable, { ignore: ['/auth/callback', '/deep/*'] })
+  assert.deepEqual(orphans, ['/admin/secret'])
+})
+
+// ---------- target size ----------
+
+test('meetsTargetSize: 44x44 passes, smaller fails with the short dimension', () => {
+  assert.equal(meetsTargetSize({ width: 44, height: 44 }).pass, true)
+  const r = meetsTargetSize({ width: 30, height: 44 })
+  assert.equal(r.pass, false)
+  assert.deepEqual(r.short, ['width'])
+  assert.deepEqual(meetsTargetSize({ width: 10, height: 10 }).short, ['width', 'height'])
+})
+
+test('meetsTargetSize: custom minimum', () => {
+  assert.equal(meetsTargetSize({ width: 24, height: 24 }, 24).pass, true)
+  assert.equal(meetsTargetSize({ width: 24, height: 24 }, 44).pass, false)
+})
+
+// ---------- focus indicator ----------
+
+const NO_OUTLINE = { outlineStyle: 'none', outlineWidth: '0px', outlineColor: 'rgb(0,0,0)', boxShadow: 'none' }
+
+test('hasVisibleFocusIndicator: outline appearing on focus → visible', () => {
+  const focused = { outlineStyle: 'solid', outlineWidth: '2px', outlineColor: 'rgb(0,90,255)', boxShadow: 'none' }
+  assert.equal(hasVisibleFocusIndicator(NO_OUTLINE, focused), true)
+})
+
+test('hasVisibleFocusIndicator: box-shadow ring appearing on focus → visible', () => {
+  const focused = { ...NO_OUTLINE, boxShadow: '0 0 0 3px rgba(0,90,255,.5)' }
+  assert.equal(hasVisibleFocusIndicator(NO_OUTLINE, focused), true)
+})
+
+test('hasVisibleFocusIndicator: no change between states → NOT visible (the bug)', () => {
+  // outline:none in both states and identical shadow — the missing-focus-ring case
+  assert.equal(hasVisibleFocusIndicator(NO_OUTLINE, { ...NO_OUTLINE }), false)
+})
+
+test('hasVisibleFocusIndicator: zero-width color-only outline change → NOT visible', () => {
+  // `0px solid red` → `0px solid blue` paints nothing; must not false-pass
+  const blurred = { outlineStyle: 'solid', outlineWidth: '0px', outlineColor: 'rgb(255,0,0)', boxShadow: 'none' }
+  const focused = { outlineStyle: 'solid', outlineWidth: '0px', outlineColor: 'rgb(0,0,255)', boxShadow: 'none' }
+  assert.equal(hasVisibleFocusIndicator(blurred, focused), false)
+})

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-sweep.md (result shape).
+
+// ---- 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()
+}

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

@@ -0,0 +1,98 @@
+// Unit tests for the render-health spine — the pure core, no browser.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  isFatalConsole,
+  isFatalResponse,
+  hasFatalMarker,
+  evaluateRenderHealth,
+  assertHealthyThrough,
+} from './presentation-render-health.mjs'
+
+// Minimal fake Playwright page: records listeners, lets a test emit events, and
+// returns body text from evaluate(). Enough to exercise the watcher/compose path
+// without a browser.
+function fakePage(bodyText = '') {
+  const handlers = {}
+  return {
+    on(ev, fn) { (handlers[ev] ||= []).push(fn) },
+    emit(ev, arg) { (handlers[ev] || []).forEach((f) => f(arg)) },
+    async evaluate() { return bodyText },
+  }
+}
+
+test('console.error is fatal; warning is not', () => {
+  assert.equal(isFatalConsole('error', 'boom'), true)
+  assert.equal(isFatalConsole('warning', 'meh'), false)
+  assert.equal(isFatalConsole('log', 'hi'), false)
+})
+
+test('ignored console substrings are not fatal', () => {
+  assert.equal(isFatalConsole('error', 'Download the React DevTools', { ignore: ['React DevTools'] }), false)
+})
+
+test('http >= 500 is fatal; < 500 is not', () => {
+  assert.equal(isFatalResponse(500, '/api/x'), true)
+  assert.equal(isFatalResponse(503, '/api/x'), true)
+  assert.equal(isFatalResponse(404, '/api/x'), false)
+  assert.equal(isFatalResponse(200, '/api/x'), false)
+})
+
+test('cross-origin 5xx is ignored (externals are faked, not graded)', () => {
+  assert.equal(isFatalResponse(500, 'https://stripe.com/v1/x', { origin: 'http://localhost:3000' }), false)
+  assert.equal(isFatalResponse(500, 'http://localhost:3000/api/x', { origin: 'http://localhost:3000' }), true)
+  assert.equal(isFatalResponse(500, '/api/x', { origin: 'http://localhost:3000' }), true) // relative = first-party
+})
+
+test('error-boundary markers are detected in body text', () => {
+  assert.equal(hasFatalMarker('Application error: a client-side exception has occurred'), true)
+  assert.equal(hasFatalMarker("Cannot read properties of undefined (reading 'id')"), true)
+  assert.equal(hasFatalMarker('All good here'), false)
+})
+
+test('the /tasks bug shape fails render-health (pageerror on mount)', () => {
+  const v = evaluateRenderHealth({
+    pageerrors: [{ message: "Cannot read properties of undefined (reading 'id')" }],
+  })
+  assert.equal(v.healthy, false)
+  assert.equal(v.offenders[0].kind, 'pageerror')
+  assert.match(v.offenders[0].detail, /reading 'id'/)
+})
+
+test('a clean render is healthy', () => {
+  const v = evaluateRenderHealth({
+    consoles: [{ type: 'log', text: 'mounted' }, { type: 'warning', text: 'deprecated' }],
+    responses: [{ status: 200, url: '/api/tasks/list' }],
+    bodyText: 'Tasks\nNo tasks match these filters.',
+  })
+  assert.equal(v.healthy, true)
+  assert.deepEqual(v.offenders, [])
+})
+
+test('assertHealthyThrough fails when an error fires DURING the interaction (mutate-health)', async () => {
+  const page = fakePage()
+  await assert.rejects(
+    assertHealthyThrough(page, async () => {
+      // simulate an uncaught error thrown while a delete/submit runs
+      page.emit('pageerror', { message: "Cannot read properties of undefined (reading 'id')" })
+    }),
+    /render-health.*reading 'id'/s,
+  )
+})
+
+test('assertHealthyThrough passes a clean interaction', async () => {
+  const page = fakePage('Tasks\nDeleted.')
+  await assertHealthyThrough(page, async () => { /* clean mutation */ })
+})
+
+test('aggregates multiple offenders (pageerror + console + 5xx + boundary)', () => {
+  const v = evaluateRenderHealth({
+    pageerrors: [{ message: 'x is not a function' }],
+    consoles: [{ type: 'error', text: 'render failed' }],
+    responses: [{ status: 500, url: '/api/tasks/list' }],
+    bodyText: 'Unhandled Runtime Error',
+  }, { origin: 'http://localhost:3000' })
+  assert.equal(v.healthy, false)
+  assert.deepEqual(v.offenders.map((o) => o.kind).sort(), ['console.error', 'error-boundary', 'http>=500', 'pageerror'])
+})