@nurix/etna 0.18.19 → 0.18.20

package/data/harnesses/code/skills/design/scripts/render-rung.mjs

@@ -0,0 +1,690 @@
+// skills/design/scripts/render-rung.mjs — verification-ladder rung 2: deterministic render checks + pixel instruments (D32)
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { inflateSync } from 'node:zlib';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+// The four viewports the ladder sweeps; width is the breakpoint, height is a fixed tall canvas.
+const VIEWPORTS = [375, 768, 1024, 1440];
+const VIEWPORT_HEIGHT = 900;
+
+// Axe rule ids the render rung gates on: the accessible-name family and the ARIA-validity family (int-17 / int-18).
+const AXE_ACCESSIBLE_NAME = ['button-name', 'select-name', 'image-alt', 'link-name'];
+const AXE_ARIA_VALIDITY = ['aria-allowed-attr', 'aria-required-attr', 'aria-required-children', 'aria-valid-attr-value'];
+
+// Common local dev-server ports probed when no --url is given.
+const DEV_PORTS = [5173, 4173, 3000, 8080];
+
+// Severity rank for the delivered (severity-ranked) list; auto-critical is never minted by machine render rules.
+const SEVERITY_RANK = { 'auto-critical': 0, critical: 1, major: 2, minor: 3 };
+
+const NO_BROWSER_LINE = 'render rung: no headless browser available in this project; rung skipped (rungs 0-1 still hold)';
+
+// ----------------------------------------------------------------------------
+// Pure helpers (exported for unit testing — no browser required)
+// ----------------------------------------------------------------------------
+
+// Decode an 8-bit non-interlaced RGB/RGBA PNG into { width, height, channels, data } using only node:zlib.
+export function decodePng(buffer) {
+  const sig = [137, 80, 78, 71, 13, 10, 26, 10];
+  for (let i = 0; i < 8; i++) if (buffer[i] !== sig[i]) throw new Error('not a PNG (bad signature)');
+  let pos = 8;
+  let width = 0, height = 0, bitDepth = 0, colorType = 0, interlace = 0;
+  const idat = [];
+  while (pos < buffer.length) {
+    const len = buffer.readUInt32BE(pos); pos += 4;
+    const type = buffer.toString('ascii', pos, pos + 4); pos += 4;
+    const chunk = buffer.subarray(pos, pos + len); pos += len;
+    pos += 4; // skip CRC
+    if (type === 'IHDR') {
+      width = chunk.readUInt32BE(0);
+      height = chunk.readUInt32BE(4);
+      bitDepth = chunk[8];
+      colorType = chunk[9];
+      interlace = chunk[12];
+    } else if (type === 'IDAT') {
+      idat.push(chunk);
+    } else if (type === 'IEND') {
+      break;
+    }
+  }
+  if (bitDepth !== 8) throw new Error(`unsupported bit depth ${bitDepth} (need 8)`);
+  if (interlace !== 0) throw new Error('interlaced PNG unsupported');
+  const channels = colorType === 2 ? 3 : colorType === 6 ? 4 : 0;
+  if (!channels) throw new Error(`unsupported color type ${colorType} (need 2 or 6)`);
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const out = new Uint8Array(height * stride);
+  let rp = 0;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[rp++];
+    const rowStart = y * stride;
+    for (let i = 0; i < stride; i++) {
+      const x = raw[rp++];
+      const a = i >= channels ? out[rowStart + i - channels] : 0;
+      const b = y > 0 ? out[rowStart - stride + i] : 0;
+      const c = y > 0 && i >= channels ? out[rowStart - stride + i - channels] : 0;
+      let recon;
+      switch (filter) {
+        case 0: recon = x; break;
+        case 1: recon = x + a; break;
+        case 2: recon = x + b; break;
+        case 3: recon = x + ((a + b) >> 1); break;
+        case 4: recon = x + paethPredictor(a, b, c); break;
+        default: throw new Error(`unknown PNG filter ${filter}`);
+      }
+      out[rowStart + i] = recon & 0xff;
+    }
+  }
+  return { width, height, channels, data: out };
+}
+
+// The PNG Paeth predictor: pick the neighbour (left/up/upper-left) closest to the initial estimate.
+function paethPredictor(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+
+// inst-01: Sobel gradient-magnitude edge density — edge pixels over interior pixels (evidence, not a verdict).
+export function edgeDensity(img, threshold = 110) {
+  const { width, height, channels, data } = img;
+  if (width < 3 || height < 3) return 0;
+  const gray = new Float64Array(width * height);
+  for (let i = 0, p = 0; i < gray.length; i++, p += channels) {
+    gray[i] = 0.299 * data[p] + 0.587 * data[p + 1] + 0.114 * data[p + 2];
+  }
+  let edges = 0;
+  let interior = 0;
+  for (let y = 1; y < height - 1; y++) {
+    for (let x = 1; x < width - 1; x++) {
+      const i = y * width + x;
+      const tl = gray[i - width - 1], t = gray[i - width], tr = gray[i - width + 1];
+      const l = gray[i - 1], r = gray[i + 1];
+      const bl = gray[i + width - 1], bb = gray[i + width], br = gray[i + width + 1];
+      const gx = (tr + 2 * r + br) - (tl + 2 * l + bl);
+      const gy = (bl + 2 * bb + br) - (tl + 2 * t + tr);
+      const mag = Math.sqrt(gx * gx + gy * gy);
+      if (mag >= threshold) edges++;
+      interior++;
+    }
+  }
+  return interior === 0 ? 0 : edges / interior;
+}
+
+// inst-05: white-space ratio — fraction of pixels within a small Euclidean distance of the page background colour.
+export function whiteSpaceRatio(img, bg = [255, 255, 255], distance = 20) {
+  const { width, height, channels, data } = img;
+  const total = width * height;
+  if (total === 0) return 0;
+  const d2 = distance * distance;
+  let near = 0;
+  for (let p = 0; p < total * channels; p += channels) {
+    const dr = data[p] - bg[0], dg = data[p + 1] - bg[1], db = data[p + 2] - bg[2];
+    if (dr * dr + dg * dg + db * db <= d2) near++;
+  }
+  return near / total;
+}
+
+// inst-10: distinct-RGB count after quantizing each channel to its top 5 bits.
+export function distinctRgbCount(img) {
+  const { width, height, channels, data } = img;
+  const total = width * height;
+  const seen = new Set();
+  for (let p = 0; p < total * channels; p += channels) {
+    const key = ((data[p] >> 3) << 10) | ((data[p + 1] >> 3) << 5) | (data[p + 2] >> 3);
+    seen.add(key);
+  }
+  return seen.size;
+}
+
+// inst-09: Hasler-Susstrunk colourfulness of the surface.
+export function colorfulness(img) {
+  const { width, height, channels, data } = img;
+  const total = width * height;
+  if (total === 0) return 0;
+  let sumRg = 0, sumYb = 0, sumRg2 = 0, sumYb2 = 0;
+  for (let p = 0; p < total * channels; p += channels) {
+    const rg = data[p] - data[p + 1];
+    const yb = 0.5 * (data[p] + data[p + 1]) - data[p + 2];
+    sumRg += rg; sumYb += yb; sumRg2 += rg * rg; sumYb2 += yb * yb;
+  }
+  const meanRg = sumRg / total, meanYb = sumYb / total;
+  const stdRg = Math.sqrt(Math.max(0, sumRg2 / total - meanRg * meanRg));
+  const stdYb = Math.sqrt(Math.max(0, sumYb2 / total - meanYb * meanYb));
+  return Math.sqrt(stdRg * stdRg + stdYb * stdYb) + 0.3 * Math.sqrt(meanRg * meanRg + meanYb * meanYb);
+}
+
+// Parse an "rgb(...)" / "rgba(...)" string into [r, g, b, a]; returns null if not parseable.
+export function parseRgb(str) {
+  if (!str) return null;
+  const m = String(str).match(/rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:[,/\s]+([\d.]+))?/i);
+  if (!m) return null;
+  return [Math.round(+m[1]), Math.round(+m[2]), Math.round(+m[3]), m[4] === undefined ? 1 : +m[4]];
+}
+
+// sRGB relative luminance per WCAG 2.x.
+export function relativeLuminance([r, g, b]) {
+  const lin = (v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+// WCAG contrast ratio between two [r,g,b] colours.
+export function wcagContrast(rgb1, rgb2) {
+  const l1 = relativeLuminance(rgb1), l2 = relativeLuminance(rgb2);
+  const hi = Math.max(l1, l2), lo = Math.min(l1, l2);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// Extract colour-valued custom-property values from a personality.css text (skips var()-referencing values).
+export function extractCssColorValues(cssText) {
+  const values = [];
+  const re = /--[\w-]+\s*:\s*([^;{}]+);/g;
+  let m;
+  const colorish = /(#[0-9a-f]{3,8}\b)|\b(rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)\s*\(/i;
+  while ((m = re.exec(cssText)) !== null) {
+    const value = m[1].trim();
+    if (value.includes('var(')) continue;
+    if (colorish.test(value)) values.push(value);
+  }
+  return [...new Set(values)];
+}
+
+// Normalize an [r,g,b] triple to the "r,g,b" set key.
+function rgbKey(rgb) {
+  return `${rgb[0]},${rgb[1]},${rgb[2]}`;
+}
+
+// ----------------------------------------------------------------------------
+// CLI plumbing
+// ----------------------------------------------------------------------------
+
+// Parse argv into { project, url }.
+function parseArgs(argv) {
+  const out = { project: process.cwd(), url: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project') out.project = resolve(argv[++i] ?? '.');
+    else if (a.startsWith('--project=')) out.project = resolve(a.slice('--project='.length));
+    else if (a === '--url') out.url = argv[++i] ?? null;
+    else if (a.startsWith('--url=')) out.url = a.slice('--url='.length);
+  }
+  return out;
+}
+
+// Try to import playwright, playwright-core, then puppeteer from the target project; return a driver adapter or null.
+async function loadBrowserDriver(projectDir) {
+  const require = createRequire(join(resolve(projectDir), 'package.json'));
+  for (const name of ['playwright', 'playwright-core', 'puppeteer']) {
+    let resolved;
+    try { resolved = require.resolve(name); } catch { continue; }
+    let mod;
+    try { mod = await import(pathToFileURL(resolved).href); } catch { continue; }
+    const ns = mod && mod.default && (mod.default.chromium || typeof mod.default.launch === 'function') ? mod.default : mod;
+    if (ns.chromium) return { kind: 'playwright', name, launcher: ns.chromium };
+    if (typeof ns.launch === 'function') return { kind: 'puppeteer', name, launcher: ns };
+  }
+  return null;
+}
+
+// Install a self-contained init script (runs before page scripts on every navigation) across the playwright / puppeteer split.
+async function addInitScript(driver, page, fn) {
+  if (driver.kind === "playwright") await page.addInitScript(fn);
+  else await page.evaluateOnNewDocument(fn);
+}
+
+// Set the page viewport across the playwright / puppeteer API split.
+async function setViewport(driver, page, width) {
+  if (driver.kind === 'playwright') await page.setViewportSize({ width, height: VIEWPORT_HEIGHT });
+  else await page.setViewport({ width, height: VIEWPORT_HEIGHT });
+}
+
+// Probe common localhost dev ports; return the first reachable URL or null.
+async function detectDevServer() {
+  for (const port of DEV_PORTS) {
+    const url = `http://localhost:${port}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 400);
+    try {
+      await fetch(url, { signal: controller.signal, redirect: 'manual' });
+      clearTimeout(timer);
+      return url;
+    } catch {
+      clearTimeout(timer);
+    }
+  }
+  return null;
+}
+
+// ----------------------------------------------------------------------------
+// In-page collectors (serialized into the browser; must be self-contained)
+// ----------------------------------------------------------------------------
+
+// Return true if the page scrolls horizontally at the current viewport.
+function inPageOverflow() {
+  const el = document.scrollingElement || document.documentElement;
+  return { scrollWidth: el.scrollWidth, innerWidth: window.innerWidth, overflow: el.scrollWidth > window.innerWidth };
+}
+
+// Walk visible text nodes, compute effective contrast against the nearest opaque ancestor background, return offenders.
+function inPageTextContrast(cap) {
+  const parseRgb = (s) => {
+    const m = String(s).match(/rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:[,/\s]+([\d.]+))?/i);
+    return m ? [Math.round(+m[1]), Math.round(+m[2]), Math.round(+m[3]), m[4] === undefined ? 1 : +m[4]] : null;
+  };
+  const lum = ([r, g, b]) => {
+    const f = (v) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4); };
+    return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+  };
+  const ratio = (a, b) => { const l1 = lum(a), l2 = lum(b); const hi = Math.max(l1, l2), lo = Math.min(l1, l2); return (hi + 0.05) / (lo + 0.05); };
+  const path = (el) => {
+    let s = el.tagName.toLowerCase();
+    if (el.id) s += '#' + el.id;
+    else if (el.classList.length) s += '.' + el.classList[0];
+    return s;
+  };
+  const effectiveBg = (el) => {
+    let node = el;
+    while (node && node.nodeType === 1) {
+      const bg = parseRgb(getComputedStyle(node).backgroundColor);
+      if (bg && bg[3] > 0) return [bg[0], bg[1], bg[2]];
+      node = node.parentElement;
+    }
+    return [255, 255, 255];
+  };
+  const offenders = [];
+  const seen = new Set();
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  let n;
+  while ((n = walker.nextNode())) {
+    if (!n.nodeValue || !n.nodeValue.trim()) continue;
+    const el = n.parentElement;
+    if (!el) continue;
+    const cs = getComputedStyle(el);
+    if (cs.visibility === 'hidden' || cs.display === 'none' || +cs.opacity === 0) continue;
+    const rect = el.getBoundingClientRect();
+    if (rect.width < 1 || rect.height < 1) continue;
+    const fg = parseRgb(cs.color);
+    if (!fg || fg[3] === 0) continue;
+    const bg = effectiveBg(el);
+    const size = parseFloat(cs.fontSize) || 16;
+    const weight = parseInt(cs.fontWeight, 10) || 400;
+    const large = size >= 24 || (size >= 18.66 && weight >= 700);
+    const threshold = large ? 3 : 4.5;
+    const r = ratio([fg[0], fg[1], fg[2]], bg);
+    if (r < threshold) {
+      const key = path(el) + '|' + cs.color;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      offenders.push({ selector: path(el), color: cs.color, bg: `rgb(${bg.join(', ')})`, ratio: +r.toFixed(2), threshold, large });
+      if (offenders.length >= cap) break;
+    }
+  }
+  return offenders;
+}
+
+// Return the geometry of every visible interactive element for target-size analysis.
+function inPageTargets() {
+  const sel = 'a[href], button, input:not([type=hidden]), select, textarea, [role=button], [role=link], [role=menuitem], [role=tab], [role=checkbox], [role=switch], [tabindex]:not([tabindex="-1"])';
+  const path = (el) => {
+    let s = el.tagName.toLowerCase();
+    if (el.id) s += '#' + el.id;
+    else if (el.classList.length) s += '.' + el.classList[0];
+    return s;
+  };
+  const out = [];
+  for (const el of document.querySelectorAll(sel)) {
+    const cs = getComputedStyle(el);
+    if (cs.visibility === 'hidden' || cs.display === 'none' || +cs.opacity === 0) continue;
+    if (el.disabled) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) continue;
+    out.push({ selector: path(el), x: r.x, y: r.y, w: r.width, h: r.height });
+  }
+  return out;
+}
+
+// Resolve a list of CSS colour strings to canonical "rgb(...)" via a probe element.
+function inPageResolveColors(colorStrings) {
+  const probe = document.createElement('span');
+  probe.style.display = 'none';
+  document.body.appendChild(probe);
+  const out = [];
+  for (const s of colorStrings) {
+    probe.style.color = '';
+    probe.style.color = s;
+    out.push(getComputedStyle(probe).color);
+  }
+  probe.remove();
+  return out;
+}
+
+// Sample computed foreground / background / border colours across visible elements for drift analysis.
+function inPageComputedColors(cap) {
+  const path = (el) => {
+    let s = el.tagName.toLowerCase();
+    if (el.id) s += '#' + el.id;
+    else if (el.classList.length) s += '.' + el.classList[0];
+    return s;
+  };
+  const out = [];
+  const all = document.querySelectorAll('body *');
+  const step = Math.max(1, Math.floor(all.length / cap));
+  for (let i = 0; i < all.length; i += step) {
+    const el = all[i];
+    const cs = getComputedStyle(el);
+    if (cs.visibility === 'hidden' || cs.display === 'none') continue;
+    const rect = el.getBoundingClientRect();
+    if (rect.width < 1 || rect.height < 1) continue;
+    const entry = { selector: path(el), colors: [] };
+    if (el.textContent && el.textContent.trim()) entry.colors.push(['color', cs.color]);
+    if (cs.backgroundColor && cs.backgroundColor !== 'rgba(0, 0, 0, 0)' && cs.backgroundColor !== 'transparent') entry.colors.push(['background', cs.backgroundColor]);
+    for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
+      if (parseFloat(cs['border' + side + 'Width']) > 0) entry.colors.push(['border', cs['border' + side + 'Color']]);
+    }
+    if (entry.colors.length) out.push(entry);
+  }
+  return out;
+}
+
+// Install PerformanceObservers (cod-12) before any page script runs, accumulating CLS and the latest LCP on window.
+function inPagePerfInit() {
+  window.__perf = { cls: 0, lcp: 0 };
+  try {
+    new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) if (!e.hadRecentInput) window.__perf.cls += e.value;
+    }).observe({ type: "layout-shift", buffered: true });
+  } catch (e) { /* layout-shift not supported in this build */ }
+  try {
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      const last = entries[entries.length - 1];
+      if (last) window.__perf.lcp = last.renderTime || last.loadTime || last.startTime || 0;
+    }).observe({ type: "largest-contentful-paint", buffered: true });
+  } catch (e) { /* largest-contentful-paint not supported in this build */ }
+}
+
+// Read the accumulated perf metrics installed by inPagePerfInit.
+function inPagePerfRead() {
+  return window.__perf || { cls: 0, lcp: 0 };
+}
+
+// Read the page's effective background colour for the white-space instrument.
+function inPageBackground() {
+  const parse = (s) => {
+    const m = String(s).match(/rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:[,/\s]+([\d.]+))?/i);
+    return m ? [+m[1], +m[2], +m[3], m[4] === undefined ? 1 : +m[4]] : null;
+  };
+  for (const el of [document.body, document.documentElement]) {
+    const bg = parse(getComputedStyle(el).backgroundColor);
+    if (bg && bg[3] > 0) return [Math.round(bg[0]), Math.round(bg[1]), Math.round(bg[2])];
+  }
+  return [255, 255, 255];
+}
+
+// ----------------------------------------------------------------------------
+// Finding accumulation + output
+// ----------------------------------------------------------------------------
+
+// Register a machine-rule finding, deduped by anchor+evidence, tracking which viewports saw it.
+function addFinding(findings, viewport, finding) {
+  const key = `${finding.anchor}|${finding.evidenceKey}`;
+  const existing = findings.get(key);
+  if (existing) existing.viewports.add(viewport);
+  else findings.set(key, { ...finding, viewports: new Set([viewport]) });
+}
+
+// Print one finding in the detector's fix-or-classify format.
+function printFinding(f) {
+  const vp = [...f.viewports].sort((a, b) => a - b).join(', ');
+  console.log(`[${f.severity}] ${f.anchor}  ${f.dimension} — ${f.statement}`);
+  console.log(`  viewport ${vp}  ·  ${f.where}`);
+  console.log(`  before -> after  ·  ${f.before}  ->  ${f.after}`);
+  console.log(`  consequence  ·  ${f.consequence}`);
+  console.log('  fix it now, or classify why the rule does not apply and record that classification in docs/memory/design-decay.md — never ignore silently.');
+  console.log('');
+}
+
+// ----------------------------------------------------------------------------
+// Main
+// ----------------------------------------------------------------------------
+
+// Run the render rung: load a browser, sweep viewports for machine findings, compute pixel instruments.
+async function main() {
+  const { project, url: urlArg } = parseArgs(process.argv.slice(2));
+
+  const driver = await loadBrowserDriver(project);
+  if (!driver) {
+    console.log(NO_BROWSER_LINE);
+    return 0;
+  }
+
+  let url = urlArg;
+  if (!url) {
+    url = await detectDevServer();
+    if (url) console.log(`render rung: no --url given; using detected dev server ${url}`);
+  }
+  if (!url) {
+    console.log('render rung: no --url given and no dev server detected on common ports; pass --url <dev-server-url>. rung skipped.');
+    return 0;
+  }
+
+  // Resolve axe-core from the project if present; gate only the accessible-name + ARIA-validity families.
+  let axeSource = null;
+  try {
+    const require = createRequire(join(resolve(project), 'package.json'));
+    axeSource = readFileSync(require.resolve('axe-core'), 'utf8');
+  } catch {
+    console.log('render rung: axe-core not installed in this project; the accessible-name and ARIA-validity checks (int-17/int-18) are skipped.');
+  }
+
+  // Parse the project's personality.css token colours for the drift check (cod-02).
+  let tokenColorStrings = null;
+  const cssPath = join(resolve(project), 'src', 'styles', 'personality.css');
+  if (existsSync(cssPath)) {
+    tokenColorStrings = extractCssColorValues(readFileSync(cssPath, 'utf8'));
+  } else {
+    console.log('render rung: no src/styles/personality.css found; the rendered token-drift check (cod-02) is skipped.');
+  }
+
+  const findings = new Map();
+  const instruments = {};
+  const axeRules = [...(axeSource ? AXE_ACCESSIBLE_NAME.concat(AXE_ARIA_VALIDITY) : [])];
+  let axeSeen = new Set();
+
+  const browser = await driver.launcher.launch({ headless: true, args: ['--no-sandbox', '--disable-setuid-sandbox'] });
+  try {
+    const page = await browser.newPage();
+    // cod-12: register the perf observers before any navigation so LCP/CLS are captured from first paint.
+    try { await addInitScript(driver, page, inPagePerfInit); } catch (err) { /* init-script API unavailable; cod-12 perf skipped */ }
+    for (const width of VIEWPORTS) {
+      await setViewport(driver, page, width);
+      try {
+        await page.goto(url, { waitUntil: 'load', timeout: 30000 });
+      } catch (err) {
+        console.log(`render rung: could not load ${url} at ${width}px (${err.message}); is the dev server running? rung skipped.`);
+        await browser.close();
+        return 0;
+      }
+      await new Promise((r) => setTimeout(r, 150));
+
+      // (1) spc-10 — horizontal overflow.
+      const ov = await page.evaluate(inPageOverflow);
+      if (ov.overflow) {
+        addFinding(findings, width, {
+          anchor: 'spc-10', dimension: 'P3 Spatial', statement: 'horizontal scroll at this viewport means the design is broken',
+          evidenceKey: 'overflow', where: `document scrollWidth ${ov.scrollWidth}px > innerWidth ${ov.innerWidth}px`,
+          before: `${ov.scrollWidth}px content`, after: `<= ${ov.innerWidth}px (no horizontal scroll)`,
+          consequence: 'the operator scrolls sideways to reach controls; layout reads as broken', severity: 'critical',
+        });
+      }
+
+      // (2) typ-01 — effective text contrast.
+      const contrast = await page.evaluate(inPageTextContrast, 60);
+      for (const o of contrast) {
+        addFinding(findings, width, {
+          anchor: 'typ-01', dimension: 'P1 Typography', statement: 'text contrast below the readable floor',
+          evidenceKey: `${o.selector}|${o.color}`, where: `${o.selector} · ${o.color} on ${o.bg}`,
+          before: `${o.ratio}:1`, after: `>= ${o.threshold}:1 (${o.large ? 'large' : 'body'})`,
+          consequence: 'the operator cannot read the text; the surface reads as broken', severity: 'critical',
+        });
+      }
+
+      // (3) spc-03 — target geometry with the int-11 >=8px spacing exception.
+      const targets = await page.evaluate(inPageTargets);
+      for (const t of targets) {
+        if (t.w >= 24 && t.h >= 24) continue;
+        if (isSpacingExcepted(t, targets)) continue;
+        addFinding(findings, width, {
+          anchor: 'spc-03', dimension: 'P3 Spatial', statement: 'interactive target below the 24x24 CSS-px minimum (WCAG 2.5.8) and not covered by the >=8px spacing exception',
+          evidenceKey: t.selector, where: `${t.selector} · ${Math.round(t.w)}x${Math.round(t.h)}px`,
+          before: `${Math.round(t.w)}x${Math.round(t.h)}px`, after: '>= 24x24px, or >= 8px clearance from every neighbour',
+          consequence: 'the target is hard to hit; mis-clicks cost the operator time and trust', severity: 'major',
+        });
+      }
+
+      // (4) cod-02 — rendered token drift.
+      if (tokenColorStrings && tokenColorStrings.length) {
+        const resolved = await page.evaluate(inPageResolveColors, tokenColorStrings);
+        const allowed = new Set();
+        for (const s of resolved) { const rgb = parseRgb(s); if (rgb) allowed.add(rgbKey(rgb)); }
+        const sampled = await page.evaluate(inPageComputedColors, 400);
+        for (const el of sampled) {
+          for (const [prop, colStr] of el.colors) {
+            const rgb = parseRgb(colStr);
+            if (!rgb || rgb[3] === 0) continue;
+            if (allowed.has(rgbKey(rgb))) continue;
+            addFinding(findings, width, {
+              anchor: 'cod-02', dimension: 'S3 Design Tokens', statement: 'rendered colour resolves outside the personality.css token vocabulary (drift)',
+              evidenceKey: `${prop}|${rgbKey(rgb)}`, where: `${el.selector} · ${prop} ${colStr} not among the emitted tokens`,
+              before: colStr, after: 'a value from the emitted token surface',
+              consequence: 'an off-manifest colour erodes token discipline; the look drifts from the resolved personality', severity: 'minor',
+            });
+          }
+        }
+      }
+
+      // (5) int-17 / int-18 — axe accessible-name + ARIA-validity families.
+      if (axeSource) {
+        try {
+          await page.addScriptTag({ content: axeSource });
+          const violations = await page.evaluate(async (rules) => {
+            const res = await window.axe.run(document, { runOnly: { type: 'rule', values: rules }, resultTypes: ['violations'] });
+            return res.violations.map((v) => ({ id: v.id, impact: v.impact, count: v.nodes.length, target: v.nodes[0] ? String(v.nodes[0].target[0]) : '' }));
+          }, axeRules);
+          for (const v of violations) {
+            if (axeSeen.has(v.id)) continue;
+            axeSeen.add(v.id);
+            const isName = AXE_ACCESSIBLE_NAME.includes(v.id);
+            addFinding(findings, width, {
+              anchor: isName ? 'int-17' : 'int-18', dimension: 'S1 Semantic Markup',
+              statement: isName ? `axe ${v.id}: element lacks a discernible accessible name` : `axe ${v.id}: invalid ARIA usage`,
+              evidenceKey: v.id, where: `${v.count} node(s), e.g. ${v.target || '(unnamed)'}`,
+              before: `axe ${v.id} violation (${v.impact || 'serious'})`, after: 'zero violations in this rule',
+              consequence: isName ? 'assistive tech announces nothing actionable; keyboard and screen-reader operators are blocked' : 'invalid ARIA misleads assistive tech about state and role', severity: 'critical',
+            });
+          }
+        } catch (err) {
+          console.log(`render rung: axe run failed at ${width}px (${err.message}); continuing without the accessible-name/ARIA checks.`);
+          axeSource = null;
+        }
+      }
+
+      // (6) cod-12 — runtime perf budgets measurable in a passive headless load: LCP and CLS.
+      // INP and frame time require real interaction and belong to the interactive rung (3), not this one.
+      try {
+        const perf = await page.evaluate(inPagePerfRead);
+        if (perf && typeof perf.lcp === 'number' && perf.lcp > 2500) {
+          addFinding(findings, width, {
+            anchor: 'cod-12', dimension: 'S4 Performance', statement: 'largest-contentful-paint over the 2.5s budget',
+            evidenceKey: 'lcp', where: `LCP ${Math.round(perf.lcp)}ms at load`,
+            before: `${Math.round(perf.lcp)}ms`, after: '<= 2500ms',
+            consequence: 'the operator waits on first meaningful paint; the surface feels slow to arrive', severity: 'major',
+          });
+        }
+        if (perf && typeof perf.cls === 'number' && perf.cls > 0.1) {
+          addFinding(findings, width, {
+            anchor: 'cod-12', dimension: 'S4 Performance', statement: 'cumulative layout shift over the 0.1 budget',
+            evidenceKey: 'cls', where: `CLS ${perf.cls.toFixed(3)} across load`,
+            before: perf.cls.toFixed(3), after: '<= 0.1',
+            consequence: 'content jumps as it loads; the operator mis-clicks and loses their place', severity: 'major',
+          });
+        }
+      } catch (err) { /* PerformanceObserver entries unsupported; cod-12 skipped, rungs 0-1 still hold */ }
+
+      // Instruments — pixel evidence, never a verdict.
+      try {
+        const shot = Buffer.from(await page.screenshot({ type: 'png' }));
+        const bg = await page.evaluate(inPageBackground);
+        const img = decodePng(shot);
+        instruments[width] = {
+          edgeDensity: edgeDensity(img),
+          whiteSpace: whiteSpaceRatio(img, bg),
+          colorfulness: colorfulness(img),
+          distinctRgb: distinctRgbCount(img),
+        };
+      } catch (err) {
+        instruments[width] = { error: err.message };
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+
+  return report(findings, instruments);
+}
+
+// Return true when an undersized target is covered by the int-11 spacing exception (>=8px clearance from every neighbour).
+export function isSpacingExcepted(t, all) {
+  const GAP = 8;
+  for (const o of all) {
+    if (o === t) continue;
+    const overlapX = t.x < o.x + o.w && o.x < t.x + t.w;
+    const overlapY = t.y < o.y + o.h && o.y < t.y + t.h;
+    if (overlapX && overlapY) return false; // overlapping targets — not excepted
+    const gapX = Math.max(o.x - (t.x + t.w), t.x - (o.x + o.w));
+    const gapY = Math.max(o.y - (t.y + t.h), t.y - (o.y + o.h));
+    if (overlapY && gapX < GAP) return false; // same row band, too close horizontally
+    if (overlapX && gapY < GAP) return false; // same column band, too close vertically
+  }
+  return true;
+}
+
+// Print the severity-ranked findings and the instruments block; return the process exit code.
+function report(findings, instruments) {
+  const list = [...findings.values()].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]);
+  if (list.length === 0) {
+    console.log('render rung: no machine-rule findings across 375/768/1024/1440.');
+  } else {
+    console.log(`render rung: ${list.length} machine-rule finding(s) — fix or classify each before ship.`);
+    console.log('');
+    for (const f of list) printFinding(f);
+  }
+
+  console.log('instruments (evidence, not verdicts — dense is not bad)');
+  console.log('  these numbers are evidence for a judged finding, never a verdict; a high reading is a prompt to look, not proof of a problem.');
+  for (const width of VIEWPORTS) {
+    const m = instruments[width];
+    if (!m) { console.log(`  ${width}px: not computed`); continue; }
+    if (m.error) { console.log(`  ${width}px: not computed (${m.error})`); continue; }
+    console.log(`  ${width}px:  inst-01 edge-density ${m.edgeDensity.toFixed(3)}  ·  inst-05 white-space ${m.whiteSpace.toFixed(3)}  ·  inst-09 colorfulness ${m.colorfulness.toFixed(1)}  ·  inst-10 distinct-rgb ${m.distinctRgb}`);
+  }
+  console.log('  not computed: inst-02 feature-congestion, inst-03 subband-entropy, inst-04 grid-quality, inst-06 symmetry, inst-07 figure-ground, inst-08 contour-congestion, inst-11 klm-operator-cost');
+  console.log('  cod-12: LCP and CLS measured on the passive load; INP and 16ms frame time need real interaction — the interactive rung (3) covers those.');
+
+  return list.length > 0 ? 1 : 0;
+}
+
+const isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+if (isMain) {
+  main().then((code) => process.exit(code)).catch((err) => {
+    console.error(`render rung: unexpected error — ${err.stack || err.message}`);
+    process.exit(1);
+  });
+}