@starci/hfs 4.7.32 → 4.7.33

package/runtime/scripts/work/draw/draw-taste.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// draw-taste.mjs — the taste metrics a machine can measure on a drawing (owner r5 ruling 2026-09-27: "correct is not
+// beautiful" - too many hairline bands per card, red everywhere, badges on every fact). Thresholds are
+// modules/models/runtimes.yaml allocation.drawLoop (accentBudget, bandsPerCardMax, badgesPerEntityMax):
+//
+//   DRAW_ACCENT_BUDGET   the accent colour fills more than `accentBudget` of the render's area. Measured on the PNG:
+//                        a pixel within deltaE ACCENT_TOLERANCE (OKLab x100) of the accent token counts only where
+//                        it belongs to a solid ACCENT_BLOCK x ACCENT_BLOCK block of accent (a fill - a button, a meter,
+//                        a band - never a text stroke or a hairline), and the brand art band is excluded: the rects
+//                        draw-render.mjs records under layout.accentExempt ([data-brand-art], data-grammar-part
+//                        artwork-band, a data-grammar-proposal naming Artwork). The accent is the render's own
+//                        `--accent` custom property (resolved through var()), else the brand primary;
+//   DRAW_TOO_MANY_BANDS  a card (SurfaceCard, SurfaceListCard, SurfaceAccordionCard) splits into more than
+//                        `bandsPerCardMax` bands: hairline-separated sections (Divider, <hr>, separator/divider/
+//                        hairline classes - bands = separators + 1) or children marked band;
+//   DRAW_TOO_MANY_BADGES an entity (a card, a static state row, a list/table row) carries more than
+//                        `badgesPerEntityMax` badges (Badge, StateMark, badge/chip/pill classes) of its own.
+//
+//   starci work draw-taste --html <render.html> [--png <part.png>]... [--json]
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMain } from '../../lib/is-main.mjs';
+import { ancestorsOf } from '../../lib/dom-tree.mjs';
+import { allocationSettings } from '../../../engine/config.mjs';
+import { decodePng } from '../png.mjs';
+import { parseColor, parseCssCustomProperties } from '../brand/brand.mjs';
+import { COMPONENT_ATTR, PART_ATTR, classesOf, elementsOf, parseHtml, visibleElement, walkElements } from './draw-dna.mjs';
+
+export const DRAW_ACCENT_BUDGET = 'DRAW_ACCENT_BUDGET';
+export const DRAW_TOO_MANY_BANDS = 'DRAW_TOO_MANY_BANDS';
+export const DRAW_TOO_MANY_BADGES = 'DRAW_TOO_MANY_BADGES';
+/** How close (OKLab deltaE x100) a pixel is to the accent to count as accent. */
+const ACCENT_TOLERANCE = 8;
+/** The side of the solid block (device pixels) an accent pixel must belong to: fills count, strokes do not. */
+const ACCENT_BLOCK = 5;
+/** The selector draw-render.mjs measures as the brand art band (exempt from the accent budget). */
+export const ACCENT_EXEMPT_SELECTOR = '[data-brand-art], [data-accent-exempt], [data-grammar-part="artwork-band"], [data-grammar-proposal*="Artwork"], [data-grammar-proposal*="artwork"]';
+
+/** modules/models/runtimes.yaml allocation.drawLoop - the draw loop's and the taste metrics' numbers. Throws when absent. */
+export function drawLoopSettings() {
+  const s = allocationSettings().drawLoop;
+  if (!s || typeof s !== 'object') throw new Error('modules/models/runtimes.yaml allocation.drawLoop must declare the draw loop settings');
+  for (const k of ['maxRounds', 'stallRounds', 'beautyMin', 'accentBudget', 'bandsPerCardMax', 'badgesPerEntityMax']) {
+    if (!Number.isFinite(Number(s[k]))) throw new Error(`modules/models/runtimes.yaml allocation.drawLoop.${k} must be a number`);
+  }
+  return s;
+}
+
+const CARDS = new Set(['SurfaceCard', 'SurfaceListCard', 'SurfaceAccordionCard']);
+const ENTITY_PARTS = /(^|-)(surface-fact|list-box-item|list-box-row|data-table-row|accordion-row|timeline-item|static-row)$/;
+const SEPARATOR_CLASS = /(^|[-_])(separator|divider|hairline|rule)($|[-_])/i;
+const BAND_CLASS = /(^|[-_])band($|[-_]|s$)/i;
+const BADGE_CLASS = /(^|[-_])(badge|chip|pill|status-pill)($|[-_]{2}|$)/i;
+const CSS_VAR_WITH_FALLBACK = /^var\(\s*(--[\w-]+)\s*,\s*((?:[^\s)][^)]*)?)\)$/;
+const CSS_VAR_WITHOUT_FALLBACK = /^var\(\s*(--[\w-]+)\s*\)$/;
+const nameOf = (el) => String(el?.attrs?.[COMPONENT_ATTR] ?? '').trim();
+const partOf = (el) => String(el?.attrs?.[PART_ATTR] ?? '').trim();
+/** A component root (not one of its own parts that repeats the component attribute). */
+const rootOf = (el, names) => names.has(nameOf(el)) && !(partOf(el) && ancestorsOf(el).some((a) => nameOf(a)) && nameOf(ancestorsOf(el).find((a) => nameOf(a))) === nameOf(el));
+const isSeparator = (el) => nameOf(el) === 'Divider' || el.tag === 'hr' || /divider/.test(partOf(el)) || classesOf(el).some((c) => SEPARATOR_CLASS.test(c));
+const isBandMarked = (el) => /(^|-)band$/.test(partOf(el)) || classesOf(el).some((c) => BAND_CLASS.test(c) && !/(badge|brand)/i.test(c));
+const isBadge = (el) => ['Badge', 'StateMark'].includes(nameOf(el)) && !(partOf(el) && nameOf(el.parent ?? {}) === nameOf(el))
+  || (!nameOf(el) && classesOf(el).some((c) => BADGE_CLASS.test(c) && !/(dot|icon|label|text)$/i.test(c)));
+
+/** The bands of one card: separators + 1 when it has hairlines, else its children marked band, else 1. */
+function bandsOfCard(card) {
+  let level = elementsOf(card).filter(visibleElement);
+  // Unwrap single content wrappers (surface-content, a lone div) to reach the band level.
+  while (level.length === 1 && !isBandMarked(level[0]) && !isSeparator(level[0]) && elementsOf(level[0]).length) level = elementsOf(level[0]).filter(visibleElement);
+  const separators = level.filter(isSeparator).length;
+  const marked = level.filter(isBandMarked).length;
+  return Math.max(separators ? separators + 1 : 0, marked, 1);
+}
+
+const isEntity = (el) => rootOf(el, CARDS) || nameOf(el) === 'StaticStateRow' || ENTITY_PARTS.test(partOf(el))
+  || ((el.tag === 'li' || el.tag === 'tr') && ancestorsOf(el).some((a) => CARDS.has(nameOf(a)) || nameOf(a) === 'DataTable'));
+
+/** The badges an entity carries itself (a nested entity's badges are its own). */
+function badgesOfEntity(entity) {
+  let n = 0;
+  const visit = (el) => {
+    for (const c of elementsOf(el)) {
+      if (!visibleElement(c)) continue;
+      if (isEntity(c)) continue;
+      if (isBadge(c)) { n += 1; continue; }
+      visit(c);
+    }
+  };
+  visit(entity);
+  return n;
+}
+
+const describe = (el) => {
+  const classes = classesOf(el);
+  const className = classes.length ? `.${classes.slice(0, 2).join('.')}` : '';
+  const name = nameOf(el);
+  const namePart = name ? ` ${name}` : '';
+  return `<${el.tag}${className}>${namePart}`;
+};
+
+/** The html taste findings (bands, badges) of one render source: [{code, detail, count, examples}]. */
+export function htmlTasteFindings(html, { settings = drawLoopSettings(), label = 'the render' } = {}) {
+  const tree = parseHtml(html);
+  const all = walkElements(tree).filter(visibleElement);
+  const out = [];
+  const bandMax = Number(settings.bandsPerCardMax), badgeMax = Number(settings.badgesPerEntityMax);
+  const heavy = all.filter((el) => rootOf(el, CARDS)).map((el) => ({ el, bands: bandsOfCard(el) })).filter((c) => c.bands > bandMax);
+  if (heavy.length) {
+    const ex = heavy.map((c) => `${describe(c.el)} ${c.bands} bands`);
+    out.push({ code: DRAW_TOO_MANY_BANDS, count: heavy.length, examples: ex.slice(0, 8), detail: `${label}: ${heavy.length} card(s) split into more than ${bandMax} bands - ${ex.slice(0, 4).join('; ')}: merge bands (identity+status, capabilities, numbers+actions)` });
+  }
+  const loud = all.filter(isEntity).map((el) => ({ el, badges: badgesOfEntity(el) })).filter((e) => e.badges > badgeMax);
+  if (loud.length) {
+    const ex = loud.map((e) => `${describe(e.el)} ${e.badges} badges`);
+    out.push({ code: DRAW_TOO_MANY_BADGES, count: loud.length, examples: ex.slice(0, 8), detail: `${label}: ${loud.length} entit${loud.length > 1 ? 'ies carry' : 'y carries'} more than ${badgeMax} badges - ${ex.slice(0, 4).join('; ')}: a status is one toned word, facts stay plain text` });
+  }
+  return out;
+}
+
+/** The accent colour a render declares: its `--accent` (var() chains resolved within the same scope), else null. */
+function accentOf(html, { name = '--accent' } = {}) {
+  const css = [...String(html).matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1]).join('\n');
+  const { base } = parseCssCustomProperties(css);
+  let value = base.get(name)?.value ?? null;
+  for (let hop = 0; value && hop < 8; hop += 1) {
+    const trimmed = value.trim();
+    const ref = CSS_VAR_WITH_FALLBACK.exec(trimmed) ?? CSS_VAR_WITHOUT_FALLBACK.exec(trimmed);
+    if (!ref) break;
+    value = base.get(ref[1])?.value ?? ref[2] ?? null;
+  }
+  return value ? parseColor(value) : null;
+}
+
+const accentColorMatches = (color, accent, tolerance) => color ? 100 * Math.hypot(color.oklab.L - accent.L, color.oklab.a - accent.a, color.oklab.b - accent.b) <= tolerance : false;
+function accentMaskOf(data, width, height, accent, tolerance) {
+  const mask = new Uint8Array(width * height);
+  const cache = new Map();
+  for (let y = 0, i = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1, i += 1) {
+      const offset = i * 4;
+      if (data[offset + 3] < 128) continue;
+      const key = (data[offset] << 16) | (data[offset + 1] << 8) | data[offset + 2];
+      let hit = cache.get(key);
+      if (hit === undefined) {
+        const color = parseColor(`rgb(${data[offset]} ${data[offset + 1]} ${data[offset + 2]})`);
+        hit = accentColorMatches(color, accent, tolerance);
+        cache.set(key, hit);
+      }
+      if (hit) mask[i] = 1;
+    }
+  }
+  return mask;
+}
+
+function excludeAccentRects(mask, width, height, exempt) {
+  const excluded = new Uint8Array(width * height);
+  let excludedCount = 0;
+  for (const rect of exempt) {
+    const x0 = Math.max(0, Math.floor(rect.x)), y0 = Math.max(0, Math.floor(rect.y)), x1 = Math.min(width, Math.ceil(rect.x + rect.width)), y1 = Math.min(height, Math.ceil(rect.y + rect.height));
+    for (let y = y0; y < y1; y += 1) {
+      for (let x = x0; x < x1; x += 1) {
+        const i = y * width + x;
+        if (!excluded[i]) { excluded[i] = 1; excludedCount += 1; }
+        mask[i] = 0;
+      }
+    }
+  }
+  return excludedCount;
+}
+
+function summedAreaTable(mask, width, height) {
+  const table = new Uint32Array((width + 1) * (height + 1));
+  for (let y = 1; y <= height; y += 1) {
+    let row = 0;
+    for (let x = 1; x <= width; x += 1) {
+      row += mask[(y - 1) * width + (x - 1)];
+      table[y * (width + 1) + x] = table[(y - 1) * (width + 1) + x] + row;
+    }
+  }
+  return table;
+}
+
+const tableRectSum = (table, stride, x0, y0, x1, y1) => table[y1 * stride + x1] - table[y0 * stride + x1] - table[y1 * stride + x0] + table[y0 * stride + x0];
+function erodedAccentMask(mask, width, height, block, sum, full) {
+  const eroded = new Uint8Array(width * height);
+  for (let y = 0; y + block <= height; y += 1) {
+    for (let x = 0; x + block <= width; x += 1) {
+      if (sum(x, y, x + block, y + block) === full) eroded[y * width + x] = 1;
+    }
+  }
+  return eroded;
+}
+
+function countSolidAccentPixels(mask, width, height, block, sum) {
+  let count = 0;
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      if (!mask[y * width + x]) continue;
+      if (sum(Math.max(0, x - block + 1), Math.max(0, y - block + 1), x + 1, y + 1) > 0) count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * The accent share of a decoded RGBA image: {share, accentPixels, measuredPixels}. `exempt` rects are in image pixels.
+ * A pixel counts only inside a solid `block` x `block` square of accent pixels (a morphological opening).
+ */
+function accentShareOf(img, accent, { exempt = [], tolerance = ACCENT_TOLERANCE, block = ACCENT_BLOCK } = {}) {
+  const { width: W, height: H, data } = img;
+  const L = accent.oklab;
+  const mask = accentMaskOf(data, W, H, L, tolerance);
+  const excludedCount = excludeAccentRects(mask, W, H, exempt);
+  // Summed-area table of the mask: a block is solid when its sum is block*block.
+  const S = summedAreaTable(mask, W, H);
+  const sum = (x0, y0, x1, y1) => tableRectSum(S, W + 1, x0, y0, x1, y1);
+  const full = block * block;
+  // eroded[i] = the block whose top-left is i is solid; a pixel counts when any solid block covers it.
+  const eroded = erodedAccentMask(mask, W, H, block, sum, full);
+  const E = summedAreaTable(eroded, W, H);
+  const esum = (x0, y0, x1, y1) => tableRectSum(E, W + 1, x0, y0, x1, y1);
+  const count = countSolidAccentPixels(mask, W, H, block, esum);
+  const measured = W * H - excludedCount;
+  return { share: measured > 0 ? count / measured : 0, accentPixels: count, measuredPixels: measured };
+}
+
+/** The accent-exempt rects of a part in image pixels, from its draw-render record (layout.accentExempt, CSS px). */
+function exemptRectsOf(record) {
+  const dpr = Number(record?.viewport?.deviceScaleFactor ?? 1) || 1;
+  return (Array.isArray(record?.layout?.accentExempt) ? record.layout.accentExempt : [])
+    .map((r) => ({ x: r.x * dpr, y: r.y * dpr, width: r.width * dpr, height: r.height * dpr }))
+    .filter((r) => [r.x, r.y, r.width, r.height].every(Number.isFinite) && r.width > 0 && r.height > 0);
+}
+
+/** The draw-render record beside a part PNG (same stem .json, schema starci/draw-render@1), or null. */
+function renderRecordOf(png) {
+  try {
+    const doc = JSON.parse(fs.readFileSync(png.replace(/\.png$/i, '.json'), 'utf8'));
+    return doc?.schema === 'starci/draw-render@1' ? doc : null;
+  } catch { return null; }
+}
+
+/** The accent-budget finding of one part PNG, or null. {finding|null, share, accent} */
+export function accentBudgetOf(png, { html = null, accent = null, settings = drawLoopSettings(), label = null } = {}) {
+  const colour = accent ?? (html ? accentOf(html) : null);
+  if (!colour) return { finding: null, share: null, accent: null, why: 'no --accent in the render source and no brand primary' };
+  let img = null;
+  try { img = decodePng(fs.readFileSync(png)); } catch { img = null; }
+  if (!img?.data) return { finding: null, share: null, accent: colour.hex, why: 'image unreadable' };
+  const r = accentShareOf(img, colour, { exempt: exemptRectsOf(renderRecordOf(png)) });
+  const budget = Number(settings.accentBudget);
+  const finding = r.share > budget ? { code: DRAW_ACCENT_BUDGET, count: 1, examples: [], detail: `${label ?? path.basename(png)}: the accent ${colour.hex} fills ${(r.share * 100).toFixed(1)}% of the render (budget ${(budget * 100).toFixed(0)}%, the brand art band excluded): spend the accent on the one primary action and the meters, keep surfaces neutral` } : null;
+  return { finding, share: r.share, accent: colour.hex };
+}
+
+async function main(argv) {
+  const at = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : null; };
+  const html = at('--html');
+  if (!html) { process.stderr.write('use: starci work draw-taste --html <render.html> [--png <part.png>]... [--json]\n'); return 2; }
+  const text = fs.readFileSync(html, 'utf8');
+  const findings = htmlTasteFindings(text, { label: path.basename(html) });
+  const accents = [];
+  argv.forEach((a, i) => { if (a === '--png' && argv[i + 1]) { const r = accentBudgetOf(argv[i + 1], { html: text }); accents.push({ png: argv[i + 1], share: r.share, accent: r.accent }); if (r.finding) findings.push(r.finding); } });
+  if (argv.includes('--json')) process.stdout.write(`${JSON.stringify({ ok: !findings.length, findings, accents }, null, 2)}\n`);
+  else {
+    const findingText = findings.map((f) => `  [${f.code}] ${f.detail}`).join('\n');
+    const accentText = accents.map((a) => {
+      const share = a.share == null ? 'unmeasured' : `${(a.share * 100).toFixed(1)}%`;
+      return `  accent ${a.accent ?? '-'} ${share} ${a.png}`;
+    }).join('\n');
+    process.stdout.write(`${findings.length ? 'REFUSED' : 'ok'}: ${findings.length} finding(s)\n${findingText}\n${accentText}\n`);
+  }
+  return findings.length ? 1 : 0;
+}
+
+if (isMain(import.meta.url)) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/runtime/scripts/work/draw/draw-typecheck.mjs

@@ -0,0 +1,72 @@
+// draw-typecheck.mjs — the typecheck half of the interface.draw source gate (draw-source.mjs): type-check one draw file
+// against a grammar candidate with the product's typescript. Split out so draw-grammar.mjs, which draw-source.mjs loads,
+// never imports the draw-source entry module back.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findPackage, requirePackage } from '../../lib/package-at.mjs';
+import { isFile } from '../../lib/fs-kind.mjs';
+
+export const GRAMMAR_PACKAGE = '@starci/grammar';
+const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+/** Ambient declarations every draw file type-checks with (a raster import is its URL, as draw-render's esbuild emits it). */
+const DRAW_AMBIENT = ['png', 'jpg', 'jpeg', 'webp', 'gif', 'avif'].map((ext) => `declare module "*.${ext}" { const src: string; export default src }\n`).join('');
+
+/** The typescript module: the product's own install, else the runtime's. */
+export function loadTypescript(dirs = []) {
+  const found = findPackage([...dirs, SKILL_ROOT], ['typescript']);
+  if (!found) return null;
+  return { ts: requirePackage(found), version: found.version, root: found.root };
+}
+
+const nodeModulesUp = (dir) => {
+  const out = [];
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    const nm = path.join(d, 'node_modules');
+    if (fs.existsSync(nm)) out.push(nm);
+    if (path.dirname(d) === d) break;
+  }
+  return out;
+};
+
+/**
+ * Type-check one draw file against the grammar at `grammarRoot` (a package root holding dist/<family>/index.d.ts),
+ * with the product's typescript and compiler options. Every bare import resolves from the product's node_modules, so
+ * the draw file may live anywhere (a temp or ui-record dir). Returns {ok, errors:[{file, line, code, message}], typescript}.
+ */
+export function typecheckDraw({ file, productDir, grammarRoot, ts: tsIn = null }) {
+  const loaded = tsIn ? { ts: tsIn, version: tsIn.version } : loadTypescript([productDir]);
+  if (!loaded) return { ok: false, errors: [{ file, line: null, code: 'no-typescript', message: `no typescript resolvable from ${productDir}` }], typescript: null };
+  const { ts } = loaded;
+  let options = { strict: true, jsx: ts.JsxEmit.ReactJSX, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler, target: ts.ScriptTarget.ES2020,
+    lib: ['lib.dom.d.ts', 'lib.dom.iterable.d.ts', 'lib.esnext.d.ts'], skipLibCheck: true, esModuleInterop: true, isolatedModules: true, resolveJsonModule: true };
+  const tsconfig = path.join(productDir, 'tsconfig.json');
+  if (isFile(tsconfig)) {
+    const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
+    if (!read.error) options = ts.parseJsonConfigFileContent(read.config, ts.sys, productDir, undefined, tsconfig).options;
+  }
+  const modules = nodeModulesUp(productDir);
+  const paths = { ...options.paths };
+  const base = options.pathsBasePath ?? options.baseUrl ?? productDir;
+  for (const [k, v] of Object.entries(paths)) paths[k] = v.map((p) => path.resolve(base, p));
+  const gRoot = path.resolve(grammarRoot);
+  paths[GRAMMAR_PACKAGE] = [path.join(gRoot, 'dist', 'core', 'index.d.ts')];
+  paths[`${GRAMMAR_PACKAGE}/*`] = [path.join(gRoot, 'dist', '*', 'index.d.ts')];
+  paths['*'] = [...modules.map((m) => path.join(m, '@types', '*')), ...modules.map((m) => path.join(m, '*'))];
+  const opts = { ...options, paths, baseUrl: undefined, pathsBasePath: productDir, noEmit: true, incremental: false, composite: false, tsBuildInfoFile: undefined, plugins: undefined,
+    skipLibCheck: true, types: [], typeRoots: modules.map((m) => path.join(m, '@types')) };
+  const ambient = path.join(path.dirname(path.resolve(file)), '__starci-draw-ambient.d.ts');
+  const host = ts.createCompilerHost(opts);
+  const same = (a, b) => path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
+  const { getSourceFile, fileExists, readFile } = host;
+  host.fileExists = (f) => same(f, ambient) || fileExists.call(host, f);
+  host.readFile = (f) => (same(f, ambient) ? DRAW_AMBIENT : readFile.call(host, f));
+  host.getSourceFile = (f, lang, ...rest) => (same(f, ambient) ? ts.createSourceFile(f, DRAW_AMBIENT, lang) : getSourceFile.call(host, f, lang, ...rest));
+  const program = ts.createProgram({ rootNames: [path.resolve(file), ambient], options: opts, host });
+  const diagnostics = ts.getPreEmitDiagnostics(program).filter((d) => d.category === ts.DiagnosticCategory.Error);
+  const errors = diagnostics.map((d) => {
+    const pos = d.file && d.start != null ? d.file.getLineAndCharacterOfPosition(d.start) : null;
+    return { file: d.file ? d.file.fileName : null, line: pos ? pos.line + 1 : null, code: `TS${d.code}`, message: ts.flattenDiagnosticMessageText(d.messageText, ' ').slice(0, 600) };
+  });
+  return { ok: errors.length === 0, errors, typescript: loaded.version ?? ts.version };
+}

package/runtime/scripts/work/draw/rationale-findings.mjs

@@ -0,0 +1,205 @@
+import { COMPONENT_ATTR, PART_ATTR, componentRootOf, parseHtml, visibleElement, walkElements, classesOf } from './draw-dna.mjs';
+import { list } from '../../lib/list.mjs';
+import { ancestorsOf } from '../../lib/dom-tree.mjs';
+
+const PHRASING = new Set(['strong', 'em', 'b', 'i', 'u', 's', 'small', 'sub', 'sup', 'abbr', 'mark', 'time', 'code', 'bdi', 'bdo', 'q', 'cite', 'dfn', 'var', 'data', 'kbd', 'br', 'wbr', 'span']);
+const KINDS_OF_CLASS = Object.freeze({ spacing: ['spacing', 'layout'], radius: ['radius'], fontSize: ['type'], fontWeight: ['type'], lineHeight: ['type'] });
+const CLASS_LABEL = Object.freeze({ spacing: 'gap/padding/inset', radius: 'radius', fontSize: 'font-size', fontWeight: 'font-weight', lineHeight: 'line-height' });
+
+const describe = (el) => {
+  const cls = classesOf(el).slice(0, 2).join('.');
+  return '<' + el.tag + (el.attrs.id ? '#' + el.attrs.id : '') + (cls ? '.' + cls : '') + '>';
+};
+const whysOf = (el, whyAttr, str) => str(el?.attrs?.[whyAttr]).split(/\s+/).filter(Boolean);
+const inRedline = (el, redlineAttr) => [el, ...ancestorsOf(el)].some((a) => a.attrs?.[redlineAttr] != null || a.attrs?.id === 'redlines');
+const refsOf = (record) => list(record?.refs).map((r) => (typeof r === 'string' ? r : r?.id ?? r?.ref ?? null)).filter(Boolean).map(String);
+const hexRgb = (hex) => { const h = String(hex).replace('#', ''); return [0, 2, 4].map((i) => Number.parseInt(h.slice(i, i + 2), 16)); };
+const colourClose = (a, b) => { const x = hexRgb(a), y = hexRgb(b); return x.every((v, i) => Math.abs(v - y[i]) <= 2); };
+
+export function findRationaleIssues({ html, entries, errors, measures, resolve, record, dna, label, redlines }, { str, statesValue, round, statedValues, becauseCites, kebab, regionContainerOf, code, measureSchema, whyAttr, redlineAttr }) {
+  const groups = new Map();
+  const add = (kind, item) => {
+    if (!groups.has(kind)) groups.set(kind, []);
+    groups.get(kind).push(item);
+  };
+  for (const e of errors) add('rationale file', e);
+  const byId = new Map(entries.filter((e) => e?.id != null).map((e) => [String(e.id), e]));
+
+  const inspectDecisions = () => {
+    const refs = refsOf(record);
+    for (const e of entries) {
+      for (const r of list(e.rules)) {
+        const got = resolve(r);
+        if (!got.ok) add('unresolvable rule id', `${e.id}: "${str(r).slice(0, 60)}" (${got.why})`);
+      }
+      if (!str(e.because).trim()) add('empty because', `${e.id}`);
+      else if (!becauseCites(e.because, refs)) add('because cites no FR, content or user job', `${e.id}: "${str(e.because).slice(0, 60)}"`);
+    }
+  };
+  inspectDecisions();
+
+  const tree = parseHtml(html);
+  const visible = walkElements(tree).filter((el) => visibleElement(el) && !inRedline(el, redlineAttr));
+  const inspectVisibleElements = () => {
+    for (const el of visible) {
+      if (ancestorsOf(el).some((a) => a.tag === 'svg')) continue;
+      const ids = whysOf(el, whyAttr, str);
+      if (!ids.length) {
+        if (PHRASING.has(el.tag) && (el.tag === 'br' || el.tag === 'wbr' || (!el.attrs.class && !el.attrs.style && !el.attrs.id)) && el.parent?.tag !== '#root') continue;
+        add('element without data-why', describe(el));
+        continue;
+      }
+      for (const id of ids) if (!byId.has(id)) add('data-why naming no decision', `${describe(el)} data-why="${id}"`);
+    }
+  };
+  inspectVisibleElements();
+
+  const container = regionContainerOf(tree);
+  const regions = (container.children ?? []).filter((c) => c.tag && visibleElement(c) && !inRedline(c, redlineAttr) && !['script', 'style', 'template'].includes(c.tag));
+  const inspectRegions = () => {
+    for (const r of regions) {
+      const kinds = whysOf(r, whyAttr, str).map((id) => byId.get(id)?.kind).filter(Boolean);
+      if (kinds.length && !kinds.includes('layout')) add('region without a layout decision', `${describe(r)} (${whysOf(r, whyAttr, str).join(' ')} is ${kinds.join('/')})`);
+    }
+    const orderEntries = entries.filter((e) => e.kind === 'layout' && /order/i.test(`${e.id} ${e.selector} ${e.decision}`));
+    const counts = new Set([regions.length, ...measures.map((m) => m?.regions?.count).filter(Number.isFinite)]);
+    if (regions.length > 1 && !orderEntries.length) add('no region order decision', `${regions.length} regions and no layout decision states their order (id, selector or decision naming "order")`);
+    else if (regions.length > 1 && !orderEntries.some((e) => [...counts].some((n) => statedValues(`${e.value} ${e.decision}`).nums.has(n)))) {
+      add('region order without its count', `${orderEntries.map((e) => e.id).join(', ')} names no region count (${[...counts].join(' or ')})`);
+    }
+  };
+  inspectRegions();
+
+  const mentions = (needle) => {
+    const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+    return entries.some((e) => new RegExp(`(^|[^A-Za-z0-9])${escaped}([^A-Za-z0-9]|$)`).test(`${str(e.decision)} ${str(e.value)} ${list(e.rules).map((r) => str(r)).join(' ')}`));
+  };
+  const variantsOfElement = (el, spec) => {
+    const variants = [];
+    for (const [k, v] of Object.entries(el.attrs)) {
+      if (!k.startsWith('data-') || [COMPONENT_ATTR, PART_ATTR, whyAttr, 'data-grammar-proposal'].includes(k) || !v) continue;
+      const prop = k.replace(/^data-(grammar-)?/, '');
+      const closed = spec ? [...spec.closed.keys()].find((p) => kebab(p) === prop) : null;
+      if (closed || ['variant', 'size', 'tone', 'color'].includes(prop)) variants.push(`${prop}=${v}`);
+    }
+    return variants;
+  };
+  const collectUsedVariants = () => {
+    const used = new Map();
+    for (const el of visible) {
+      const name = componentRootOf(el);
+      if (!name) continue;
+      if (!used.has(name)) used.set(name, new Set());
+      const spec = dna?.components?.get(name);
+      for (const variant of variantsOfElement(el, spec)) used.get(name).add(variant);
+    }
+    return used;
+  };
+  const inspectUsedVariants = (used) => {
+    for (const [name, variants] of used) {
+      if (!mentions(name)) { add('DNA component without a decision', name); continue; }
+      for (const pv of variants) {
+        const value = pv.split('=')[1];
+        if (!entries.some((e) => {
+          const text = `${str(e.decision)} ${str(e.value)} ${list(e.rules).map((r) => str(r)).join(' ')}`;
+          return new RegExp(`(^|[^A-Za-z0-9])${name}([^A-Za-z0-9]|$)`).test(text) && text.toLowerCase().includes(value.toLowerCase());
+        })) add('DNA variant without a decision', `${name} ${pv}`);
+      }
+    }
+  };
+  inspectUsedVariants(collectUsedVariants());
+
+  const inspectArtSlots = () => {
+    const artOf = (el) => whysOf(el, whyAttr, str).some((id) => byId.get(id)?.kind === 'art');
+    for (const el of visible) {
+      const slot = el.tag === 'img' || el.tag === 'picture' || el.attrs['data-asset-slot'] != null || el.attrs['data-artwork-slot'] != null;
+      if (slot && whysOf(el, whyAttr, str).length && !artOf(el)) add('art slot without an art decision', describe(el));
+    }
+  };
+  inspectArtSlots();
+
+  let need;
+  const inspectMeasuredValues = (m) => {
+    for (const cls of Object.keys(need)) {
+      for (const v of list(m.values?.[cls])) {
+        const key = typeof v.value === 'number' ? round(v.value) : String(v.value);
+        if (!need[cls].has(key)) need[cls].set(key, { value: key, at: new Set() });
+        need[cls].get(key).at.add(`${m.viewport?.width ?? '?'}px ${list(v.at)[0] ?? ''}`.trim());
+      }
+    }
+  };
+  const inspectMeasuredGrids = (m) => {
+    const gridsSeen = new Set();
+    for (const g of list(m.grids)) {
+      const gk = `${g.selector}|${g.columns}|${list(g.why).join(' ')}`;
+      if (gridsSeen.has(gk)) continue;
+      gridsSeen.add(gk);
+      const own = list(g.why).map((id) => byId.get(id)).filter(Boolean);
+      if (!own.some((e) => e.kind === 'layout' && statedValues(`${e.value} ${e.decision}`).nums.has(g.columns))) {
+        add('grid without its column count', `${g.selector} at ${m.viewport?.width ?? '?'}px renders ${g.columns} column(s); its layout decision (${list(g.why).join(' ') || 'none'}) does not state ${g.columns}`);
+      }
+    }
+  };
+  const inspectMeasuredColours = (m) => {
+    const tokens = m.tokenColours ?? {};
+    const colourEntries = entries.filter((e) => e.kind === 'colour');
+    const named = (hex) => colourEntries.some((e) => {
+      const text = `${str(e.decision)} ${str(e.value)}`.toLowerCase();
+      if (text.includes(hex.toLowerCase())) return true;
+      for (const t of text.match(/--[a-z0-9-]+/g) ?? []) if (tokens[t] && colourClose(tokens[t], hex)) return true;
+      return false;
+    });
+    for (const c of list(m.colours)) if (!named(c.hex)) add('colour without a decision', `${c.hex} (${c.use} at ${m.viewport?.width ?? '?'}px, ${list(c.at)[0] ?? ''})`);
+  };
+  const inspectMeasuredArt = (m) => {
+    for (const a of list(m.art)) {
+      const own = list(a.why).map((id) => byId.get(id)).filter(Boolean);
+      if (!own.some((e) => e.kind === 'art')) add('art slot without an art decision', `${a.selector} at ${m.viewport?.width ?? '?'}px (a background image)`);
+    }
+  };
+  const inspectMissingMeasuredValues = () => {
+    for (const [cls, values] of Object.entries(need)) {
+      const kinds = KINDS_OF_CLASS[cls];
+      for (const { value, at } of values.values()) {
+        if (!entries.some((e) => kinds.includes(e.kind) && statesValue(e, value))) {
+          let displayValue = value;
+          if (typeof value === 'number') {
+            displayValue = String(value);
+            if (cls !== 'fontWeight') displayValue += 'px';
+          }
+          add(`uncovered ${CLASS_LABEL[cls]} value`, `${displayValue} (${[...at].slice(0, 2).join('; ')}) - no ${kinds.join('/')} decision states it in its value`);
+        }
+      }
+    }
+  };
+  const inspectMeasures = () => {
+    if (!measures.length || measures.some((m) => m?.schema !== measureSchema)) {
+      add('render not measured', `${label} has no measured render (draw-render records carry rationale measures): re-render it with starci work draw-render`);
+    }
+    need = { spacing: new Map(), radius: new Map(), fontSize: new Map(), fontWeight: new Map(), lineHeight: new Map() };
+    for (const m of measures.filter((x) => x?.schema === measureSchema)) {
+      inspectMeasuredValues(m);
+      inspectMeasuredGrids(m);
+      inspectMeasuredColours(m);
+      inspectMeasuredArt(m);
+    }
+    inspectMissingMeasuredValues();
+  };
+  const inspectRedlines = () => {
+    if (Array.isArray(redlines)) {
+      for (const r of redlines) if (!r.ok) add('no redline render', `${r.part ?? label}: no annotated redline (<part>.redline.png) - draw-render captures it with the rationale beside the source`);
+    }
+  };
+  const summarize = () => {
+    const out = [];
+    for (const [kind, items] of groups) {
+      out.push({ code, kind, count: items.length, examples: items.slice(0, 8),
+        detail: `${label}: ${kind} (${items.length}) - ${items.slice(0, 4).join('; ')}${items.length > 4 ? ' (+' + (items.length - 4) + ')' : ''}` });
+    }
+    return out;
+  };
+
+  inspectMeasures();
+  inspectRedlines();
+  return summarize();
+}