@starci/hfs 4.8.0 → 4.9.1

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

@@ -1,306 +0,0 @@
-// draw-layer.mjs — the layer and measure gates of a drawing (owner, 2026-09-28, StarCi Next SignInBase#signed-out:
-// "this is KNOWLEDGE, not golden rules" - the runtime catches these from knowledge and gates, never from owner feedback).
-//
-//   DRAW_NESTED_VARIANT    knowledge/ui/proof/anatomy-source.yaml ANATOMY-2. The layer chain is page Background ->
-//                          Surface -> nested control: every form control ON a painted surface (a SurfaceCard, a
-//                          card, a dialog / drawer panel) carries HeroUI's nested `secondary` variant - the choice
-//                          controls (Checkbox, RadioGroup, ...) as much as the text fields (case-1); a form region
-//                          (fields plus a primary submit) stands in a Surface, never directly on the Background
-//                          (case-3). Judged on the RENDERED DOM (draw-render's snapshot, or the html itself): the
-//                          variant is the control root's data-grammar-variant, else its vendor `<part>--<variant>`
-//                          class. A control whose vendor anatomy has no layer variant (Switch, Slider) is exempt.
-//   DRAW_MEASURE_UNCAPPED  knowledge/ui/presentation/measure.yaml MEASURE-4 case-3/case-4. A form region (fields plus
-//                          a primary submit) caps its measure; rendered wider than FORM_MEASURE_CAP_PX (W-3xl, 48rem)
-//                          at any viewport it stretched across its column. Measured in the browser (measureLayer,
-//                          run by draw-render; the record's `layer`). A chat composer (inside a ChatWorkspace, a
-//                          composer part or a role=log conversation) is not a form and is skipped.
-import fs from 'node:fs';
-import path from 'node:path';
-import { isMain } from '../../lib/is-main.mjs';
-import { classesOf, parseHtml, walkElements } from './draw-dna.mjs';
-import { safeRemove } from '../../api/fs/safe-remove.mjs';
-import { artifactHoldReason } from '../../machine/artifact-hold.mjs';
-import {isFile} from '../../lib/fs-kind.mjs';
-import {ancestorsOf} from '../../lib/dom-tree.mjs';
-import { readEnv } from '../../lib/env.mjs';
-import { invocationDir } from '../../lib/roots.mjs';
-import { mapInOrder } from '../../lib/in-order.mjs';
-import { makeTempDir } from '../../api/fs/make-temp-dir.mjs';
-
-export const DRAW_NESTED_VARIANT = 'DRAW_NESTED_VARIANT';
-export const DRAW_MEASURE_UNCAPPED = 'DRAW_MEASURE_UNCAPPED';
-
-/** W-3xl of the Width scale (measure.yaml guidance width-scale): no form region renders wider. */
-const FORM_MEASURE_CAP_PX = 768;
-
-/** Grammar form controls that publish the layer variant (primary | secondary). */
-const VARIANT_CONTROLS = Object.freeze(['Input', 'Textarea', 'Select', 'ComboBox', 'SearchField', 'NumberField', 'DateField', 'TimeField',
-  'DatePicker', 'DateRangePicker', 'Checkbox', 'CheckboxGroup', 'RadioGroup', 'OtpInput', 'PressableField']);
-/** Every grammar field control (the variant ones plus those without a vendor variant): what makes a region a form. */
-const FIELD_CONTROLS = Object.freeze([...VARIANT_CONTROLS, 'Switch', 'Slider', 'FileDropzone']);
-/** Components that paint a surface of their own. */
-const SURFACE_COMPONENTS = Object.freeze(['SurfaceCard', 'SurfaceListCard', 'Sidebar', 'Dialog', 'Drawer', 'AlertDialog', 'Popover']);
-/** Boolean surface-owner hooks emitted by Grammar compositions. */
-const SURFACE_STAMPS = Object.freeze(['data-grammar-surface', 'data-grammar-surface-card', 'data-grammar-surface-list', 'data-grammar-surface-accordion-card']);
-/** The vendor class prefixes that carry the layer variant (`<prefix>--primary|secondary`). */
-const VARIANT_CLASS_PREFIXES = Object.freeze(['input', 'input-group', 'textfield', 'textarea', 'select', 'combo-box', 'search-field', 'number-field',
-  'date-input-group', 'date-field', 'time-field', 'date-picker', 'checkbox', 'checkbox-group', 'radio-group', 'input-otp']);
-
-const VARIANT_CLASS = new RegExp(`^(?:${VARIANT_CLASS_PREFIXES.join('|')})--(primary|secondary)$`);
-const componentOf = (attrs) => attrs?.['data-component'] ?? attrs?.['data-grammar-component'] ?? null;
-
-/** Whether one parsed/DOM element paints a surface; unpainted layout containers inherit their parent. */
-function isSurface({ component, attrs, classes }) {
-  if (attrs['data-grammar-frame'] === 'frameless') return false;
-  if (SURFACE_COMPONENTS.includes(component)) return true;
-  if (attrs['data-grammar-nesting'] === 'surface') return true;
-  if (SURFACE_STAMPS.some((stamp) => attrs[stamp] === 'true')) return true;
-  if (attrs['data-grammar-surface-depth'] != null) return true;
-  if (attrs['data-grammar-overlay-surface'] != null) return true;
-  if (attrs.role === 'dialog' || attrs.role === 'alertdialog') return true;
-  return classes.some((name) => /(?:^|:)bg-surface(?:$|[-/])/.test(name))
-    || classes.includes('card') || classes.includes('surface') || classes.includes('starci-core-surface');
-}
-
-/** The layer variant a control root renders: data-grammar-variant, else the first vendor variant class in it. */
-function variantOfControl(root) {
-  const own = root.attrs?.['data-grammar-variant'];
-  if (own === 'primary' || own === 'secondary') return own;
-  for (const el of [root, ...walkElements(root)]) {
-    for (const c of classesOf(el)) { const m = VARIANT_CLASS.exec(c); if (m) return m[1]; }
-  }
-  return null;
-}
-
-const describe = (el) => {
-  const component = componentOf(el.attrs);
-  const name = el.attrs?.name ?? el.attrs?.id ?? walkElements(el).find((d) => d.attrs?.name)?.attrs?.name ?? null;
-  const label = name ? ` "${name}"` : '';
-  return `${component ?? el.tag}${label}`;
-};
-const surfaceAncestor = (el) => ancestorsOf(el).find((a) => isSurface({ component: componentOf(a.attrs), attrs: a.attrs ?? {}, classes: classesOf(a) })) ?? null;
-const isPrimaryButton = (el) => (componentOf(el.attrs) === 'Button' && (classesOf(el).includes('button--primary') || el.attrs?.['data-variant'] === 'primary' || el.attrs?.['data-grammar-variant'] === 'primary'))
-  || (el.tag === 'button' && el.attrs?.type === 'submit');
-
-/**
- * DRAW_NESTED_VARIANT findings of one rendered DOM (html text): [{code, kind, detail}]. `label` names the capture.
- */
-export function nestedVariantFindings(html, { label = 'the render' } = {}) {
-  const all = walkElements(parseHtml(html));
-  const out = [];
-  const controls = all.filter((el) => VARIANT_CONTROLS.includes(componentOf(el.attrs))
-    && !ancestorsOf(el).some((a) => FIELD_CONTROLS.includes(componentOf(a.attrs))));
-  const bad = [];
-  for (const el of controls) {
-    if (!surfaceAncestor(el)) continue;
-    const variant = variantOfControl(el);
-    if (variant !== 'secondary') bad.push(`${describe(el)} (${variant ?? 'no layer variant'})`);
-  }
-  if (bad.length) out.push({ code: DRAW_NESTED_VARIANT, kind: 'control on a surface not nested', count: bad.length,
-    detail: `${label}: ${bad.length} form control(s) on a surface without the nested variant="secondary" - ${bad.slice(0, 6).join('; ')} (ANATOMY-2 case-1: every form control on a surface, choice controls included)` });
-  // ANATOMY-2 case-3: a form region (fields plus a primary submit) stands in a Surface, never on the page Background.
-  const loose = [];
-  for (const button of all.filter(isPrimaryButton)) {
-    const region = ancestorsOf(button).find((a) => walkElements(a).some((d) => FIELD_CONTROLS.includes(componentOf(d.attrs))));
-    if (!region || surfaceAncestor(button) || isSurface({ component: componentOf(region.attrs), attrs: region.attrs ?? {}, classes: classesOf(region) })) continue;
-    const fields = walkElements(region).filter((d) => FIELD_CONTROLS.includes(componentOf(d.attrs)));
-    // A form is one unit: fields on a surface with the submit on the Background is a split form; a field on a surface
-    // is otherwise judged as a nested control only, never also as a loose form.
-    const split = fields.some((d) => surfaceAncestor(d));
-    if (!loose.some((l) => l.region === region)) loose.push({ region, fields, split });
-  }
-  for (const { fields, split } of loose) out.push(split
-    ? { code: DRAW_NESTED_VARIANT, kind: 'form-split-across-layers', count: 1,
-      detail: `${label}: form-split-across-layers - ${fields.slice(0, 4).map(describe).join(', ')} stand(s) on a Surface while the form's primary submit sits on the page Background; a form is one unit, its fields and its submit/actions belong in the same Surface (ANATOMY-2 case-3)` }
-    : { code: DRAW_NESTED_VARIANT, kind: 'form on the page background', count: 1,
-      detail: `${label}: a form region (${fields.slice(0, 4).map(describe).join(', ')} and its primary submit) stands directly on the page Background - it belongs in a Surface (SurfaceCard), its controls nested in variant="secondary" (ANATOMY-2 case-3)` });
-  return out;
-}
-
-/**
- * DRAW_MEASURE_UNCAPPED findings of one capture's measured layer (draw-render record `layer`, measureLayer):
- * {viewport:{width,height}, forms:[{desc, width, fields}]}.
- */
-export function measureFindings(layer, { label = 'the capture', cap = FORM_MEASURE_CAP_PX } = {}) {
-  const wide = (Array.isArray(layer?.forms) ? layer.forms : []).filter((f) => Number(f.width) > cap + 0.5);
-  return wide.map((f) => ({ code: DRAW_MEASURE_UNCAPPED, kind: 'form region past its measure', count: 1,
-    detail: `${label}: the form region ${f.desc ?? ''} (${(f.fields ?? []).slice(0, 4).join(', ') || 'fields'} and a primary submit) renders ${Math.round(Number(f.width))}px wide at ${layer.viewport?.width ?? '?'}px, past the ${cap}px (W-3xl) form cap - a drawn XBase owns its measure: SurfaceCard measure="form"/"formCompact", else w-full max-w-md mx-auto (MEASURE-4 case-3/case-4; MEASURE-1 is the page width, not the form's)`.replace(/\s+/g, ' ') }));
-}
-
-
-/**
- * Runs IN THE PAGE (draw-render passes it to page.evaluate): every form region's rendered width. A form region is the
- * nearest ancestor of a primary submit that also holds a field control; a region holding a table or grid is data, not
- * a form, and is skipped. Self-contained: it closes over nothing.
- */
-export function measureLayer({ fields, primary, chat }) {
-  const fieldSel = fields.map((n) => `[data-component="${n}"],[data-grammar-component="${n}"]`).join(',');
-  const forms = [];
-  const seen = new Set();
-  const isVisible = (button) => {
-    const cs = getComputedStyle(button);
-    return cs.display !== 'none' && cs.visibility !== 'hidden';
-  };
-  const regionOf = (button) => {
-    let region = button.parentElement;
-    while (region && region !== document.body && !region.querySelector(fieldSel)) region = region.parentElement;
-    return region;
-  };
-  // A chat / messaging composer (a text input and a send button in a chat workspace) follows its conversation column.
-  const isExcludedRegion = (region) => region.querySelector('table,[role="grid"],[role="table"]')
-    || region.closest(chat) || region.querySelector(chat) || [...region.classList].some((c) => c.startsWith('starci-core-chat-'));
-  for (const button of document.querySelectorAll(primary)) {
-    if (!isVisible(button)) continue;
-    const region = regionOf(button);
-    if (!region || region === document.body || seen.has(region)) continue;
-    seen.add(region);
-    if (isExcludedRegion(region)) continue;
-    const names = [...region.querySelectorAll(fieldSel)].map((el) => el.dataset.component ?? el.dataset.grammarComponent ?? null);
-    const cls = typeof region.className === 'string' ? region.className.trim().split(/\s+/).slice(0, 3).join('.') : '';
-    const classLabel = cls ? `.${cls}` : '';
-    forms.push({ desc: `<${region.tagName.toLowerCase()}${classLabel}>`, width: region.getBoundingClientRect().width, fields: names });
-  }
-  return { viewport: { width: window.innerWidth, height: window.innerHeight }, forms };
-}
-
-/** The argument draw-render passes measureLayer. */
-export const LAYER_PROBE = Object.freeze({
-  fields: FIELD_CONTROLS,
-  chat: '[data-component="ChatWorkspace"],[data-grammar-component="ChatWorkspace"],[data-component*="Composer"],[data-grammar-component*="Composer"],[data-grammar-part*="composer"],[role="log"]',
-  primary: '[data-component="Button"].button--primary,[data-grammar-component="Button"].button--primary,[data-component="Button"][data-variant="primary"],[data-grammar-component="Button"][data-variant="primary"],button[type="submit"]',
-});
-
-// ---------------------------------------------------------------------------------------------------------
-// Existing renders: the CLI and the draw-gates gate
-//
-//   starci work draw-layer <render dir | part png>... [--playwright <product dir>] [--json]
-//
-// Every drawn part under the paths (a <part>.png whose <part>.json is a starci/draw-render@1 record) is judged:
-// DRAW_NESTED_VARIANT on its rendered DOM (<part>.dom.html, else the html beside it), DRAW_MEASURE_UNCAPPED on the
-// record's measured `layer`. A record drawn before the measure existed carries no `layer`: the part is re-rendered at
-// its viewport from the round's harness/index.html (a draw-loop round dir) or its html source, with the product's
-// Playwright (--playwright, else the cwd), and measured; a part that cannot be re-measured says so (unmeasured).
-// Exit 0 all clear, 1 a finding, 2 usage.
-// ---------------------------------------------------------------------------------------------------------
-
-const readJsonFile = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
-
-/** Every drawn part (png with a draw-render record) under the paths, skipping node_modules and capture outputs. */
-function partsUnder(paths) {
-  const out = [];
-  const visit = (p) => {
-    let st = null;
-    try { st = fs.statSync(p); } catch { return; }
-    if (st.isDirectory()) {
-      if (/^(node_modules|\.git|harness|layer-remeasure)$/.test(path.basename(p))) return;
-      for (const e of fs.readdirSync(p)) visit(path.join(p, e));
-      return;
-    }
-    if (!/\.png$/i.test(p) || /\.redline\.png$/i.test(p)) return;
-    const record = readJsonFile(p.replace(/\.png$/i, '.json'));
-    if (record?.schema === 'starci/draw-render@1') out.push({ png: p, record });
-  };
-  for (const p of paths) visit(path.resolve(p));
-  return out;
-}
-
-/** The html a part can be re-rendered from: its round's harness, its record's html source, the html beside it. */
-function renderSourceOf({ png, record }) {
-  const harness = path.join(path.dirname(png), 'harness', 'index.html');
-  if (isFile(harness)) return harness;
-  // The html beside the part is the copy that was judged; the record's source path may point at a live repo since edited.
-  const beside = png.replace(/\.png$/i, '.html');
-  if (isFile(beside)) return beside;
-  const src = record?.source?.html?.path;
-  return src && isFile(src) ? src : null;
-}
-
-/** The dom snapshot of a part: the record's, the one beside it, or the html beside it; null when none exists. */
-function domOfPart(part) {
-  const dom = part.record?.dom?.path && isFile(part.record.dom.path) ? part.record.dom.path : part.png.replace(/\.png$/i, '.dom.html');
-  if (isFile(dom)) return dom;
-  return isFile(part.png.replace(/\.png$/i, '.html')) ? part.png.replace(/\.png$/i, '.html') : null;
-}
-
-/** Re-renders `source` for a part with no record layer: {layer, measured, dom} (dom is the snapshot it found, else `dom`). */
-async function remeasuredLayer(source, viewport, { playwright, scratch, index }, dom) {
-  const found = { layer: null, measured: null, dom };
-  try {
-    const { captureHtml } = await import('../draw-render.mjs');
-    const [r] = await captureHtml({ html: source, out: path.join(scratch, `${index}`), viewports: [viewport], theme: 'light', fullPage: true, name: 'layer-remeasure', source: { mode: 'html' }, playwright, rationale: null });
-    if (r?.layer && !r.layer.error) { found.layer = r.layer; found.measured = `re-rendered ${path.relative(process.cwd(), source)}`; }
-    if (!dom && r?.dom?.path && isFile(r.dom.path)) found.dom = r.dom.path;
-  } catch (error) { found.measured = `re-render failed: ${String(error?.message ?? error).split(/\r?\n/)[0]}`; }
-  return found;
-}
-
-/** The layer result of one part: {part, viewport, dom, measured, forms, findings}. */
-async function layerResultOf(part, ctx, index) {
-  const label = path.basename(part.png).replace(/\.png$/i, '');
-  const viewport = part.record?.viewport ? { width: part.record.viewport.width, height: part.record.viewport.height } : null;
-  let dom = domOfPart(part);
-  let layer = part.record?.layer && !part.record.layer.error ? part.record.layer : null;
-  let measured = layer ? 'record' : null;
-  const source = !layer && ctx.playwright && viewport ? renderSourceOf(part) : null;
-  if (source) {
-    const found = await remeasuredLayer(source, viewport, { ...ctx, index }, dom);
-    layer = found.layer;
-    measured = found.measured ?? measured;
-    dom = found.dom;
-  }
-  const html = dom ? fs.readFileSync(dom, 'utf8') : null;
-  const findings = [...(html ? nestedVariantFindings(html, { label }) : []), ...measureFindings(layer, { label })];
-  return { part: part.png, viewport, dom, measured: measured ?? 'unmeasured (no record layer, no re-render source or Playwright)', forms: layer?.forms ?? null, findings };
-}
-
-/**
- * The layer findings of drawn parts: [{part, viewport, findings, measured, forms}]. `playwright` (loadPlaywright) re-measures
- * a part whose record has no `layer`; without it such a part is reported unmeasured.
- */
-export async function layerFindingsForParts(parts, { playwright = null } = {}) {
-  const scratch = playwright ? makeTempDir('draw-layer-') : null;
-  try {
-    return await mapInOrder(parts, (part, index) => layerResultOf(part, { playwright, scratch }, index));
-  } finally {
-    if (scratch) safeRemove(scratch, { hold: artifactHoldReason });
-  }
-}
-
-/** The draw-layer command line: {paths, opts} or {error} for an unknown flag. */
-function parseLayerArgs(argv) {
-  const paths = [], opts = { playwright: null, json: false };
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === '--json') opts.json = true;
-    else if (argv[i] === '--playwright') opts.playwright = argv[++i];
-    else if (argv[i].startsWith('--')) return { error: `draw-layer: unknown flag ${argv[i]}\n` };
-    else paths.push(argv[i]);
-  }
-  return { paths, opts };
-}
-
-function printLayerResults(results, red) {
-  for (const r of results) {
-    const forms = r.forms ? `; forms ${r.forms.map((f) => String(Math.round(f.width)) + 'px').join(', ') || 'none'}` : '';
-    process.stdout.write(`${r.findings.length ? 'FAIL' : 'ok  '} ${r.part} [${r.measured}${forms}]\n`);
-    for (const f of r.findings) process.stdout.write(`       [${f.code}] ${f.detail}\n`);
-  }
-  process.stdout.write(`${results.length} part(s), ${red.length} red\n`);
-}
-
-async function main(argv) {
-  const { paths, opts, error } = parseLayerArgs(argv);
-  if (error) { process.stderr.write(error); return 2; }
-  if (!paths.length) { process.stderr.write('use: starci work draw-layer <render dir | part png>... [--playwright <product dir>] [--json]\n'); return 2; }
-  const parts = partsUnder(paths);
-  let playwright = null;
-  try { const { loadPlaywright } = await import('../draw-render.mjs'); playwright = loadPlaywright([opts.playwright, readEnv('STARCI_PLAYWRIGHT_DIR'), invocationDir()].filter(Boolean)); } catch { playwright = null; }
-  const results = await layerFindingsForParts(parts, { playwright });
-  const red = results.filter((r) => r.findings.length);
-  if (opts.json) process.stdout.write(`${JSON.stringify({ schema: 'starci/draw-layer@1', parts: results.length, red: red.length, results }, null, 2)}\n`);
-  else printLayerResults(results, red);
-  return red.length ? 1 : 0;
-}
-
-if (isMain(import.meta.url)) {
-  try { process.exitCode = await main(process.argv.slice(2)); } catch (e) { process.stderr.write(`draw-layer: ${e?.stack ?? e}\n`); process.exitCode = 2; }
-}

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

@@ -1,237 +0,0 @@
-// draw-rationale-page.mjs - the in-page halves of draw-rationale.mjs: measureRationale and drawRedlines run inside the
-// browser (playwright serializes each function, so each is self-contained and reads nothing of this module).
-/**
- * Measure what the render uses: every distinct gap/padding/inset, radius, font-size, font-weight and line-height of a
- * visible element (type values only where the element renders text), the colours it paints, its grids, its regions
- * and its background-image art. `arg` {tokens: ['--accent', ...], whyAttr, redlineAttr, schema}.
- */
-export function measureRationale(arg) {
-  const { tokens = [], whyAttr, redlineAttr, schema } = arg;
-  const px = (s) => { const n = Number.parseFloat(s); return Number.isFinite(n) ? Math.round(n * 100) / 100 : null; };
-  // Any CSS colour (rgb, oklch, color-mix ...) to sRGB hex through a 1px canvas; transparent is null.
-  const ctx = document.createElement('canvas').getContext('2d', { willReadFrequently: true });
-  const hexCache = new Map();
-  const hexOf = (c) => {
-    const key = String(c);
-    if (hexCache.has(key)) return hexCache.get(key);
-    let hex = null;
-    try {
-      ctx.clearRect(0, 0, 1, 1);
-      ctx.fillStyle = '#000'; ctx.fillStyle = key;
-      ctx.fillRect(0, 0, 1, 1);
-      const d = ctx.getImageData(0, 0, 1, 1).data;
-      if (d[3] > 5) hex = `#${[d[0], d[1], d[2]].map((v) => v.toString(16).padStart(2, '0')).join('')}`;
-    } catch { hex = null; }
-    hexCache.set(key, hex);
-    return hex;
-  };
-  // The inset sides an author wrote (a used value is reported for every side of a positioned element, so only the
-  // sides a matching rule or the inline style sets are the render's decisions).
-  const insetRules = [];
-  const collect = (rules) => {
-    for (const r of rules ?? []) {
-      if (r.cssRules && r.conditionText != null) { if (window.matchMedia(r.conditionText).matches) { collect(r.cssRules); } continue; }
-      if (r.cssRules && !r.selectorText) { collect(r.cssRules); continue; }
-      if (!r.selectorText || !r.style) continue;
-      const sides = ['top', 'right', 'bottom', 'left'].filter((k) => { const v = r.style.getPropertyValue(k); return v && v !== 'auto'; });
-      if (sides.length) insetRules.push({ selector: r.selectorText, sides });
-    }
-  };
-  for (const sheet of document.styleSheets) { try { collect(sheet.cssRules); } catch { /* a cross-origin sheet */ } }
-  const insetSides = (el) => {
-    const sides = new Set(['top', 'right', 'bottom', 'left'].filter((k) => { const v = el.style?.getPropertyValue(k); return v && v !== 'auto'; }));
-    for (const r of insetRules) { try { if (el.matches(r.selector)) for (const k of r.sides) sides.add(k); } catch { /* an unsupported selector */ } }
-    return [...sides];
-  };
-  const sel = (el) => {
-    const cls = typeof el.className === 'string' ? el.className.trim().split(/\s+/).filter(Boolean).slice(0, 2).join('.') : '';
-    return el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + (cls ? '.' + cls : '');
-  };
-  const whyOf = (el) => { const w = el.closest(`[${whyAttr}]`); return w ? w.getAttribute(whyAttr).split(/\s+/).filter(Boolean) : []; };
-  const excluded = (el) => Boolean(el.closest(`[${redlineAttr}],#redlines`));
-  const visible = (el) => { const r = el.getBoundingClientRect(); const cs = getComputedStyle(el); return r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none'; };
-  const values = { spacing: new Map(), radius: new Map(), fontSize: new Map(), fontWeight: new Map(), lineHeight: new Map() };
-  const put = (cls, value, el) => {
-    if (value == null || value === 0) return;
-    if (!values[cls].has(value)) values[cls].set(value, []);
-    const at = values[cls].get(value);
-    if (at.length < 3) at.push(sel(el));
-  };
-  const colours = new Map();
-  const colour = (hex, use, el) => { if (!hex) { return; } const k = `${hex}|${use}`; if (!colours.has(k)) { colours.set(k, { hex, use, at: [] }); } const c = colours.get(k); if (c.at.length < 3) { c.at.push(sel(el)); } };
-  const grids = [], art = [];
-  const all = [...document.querySelectorAll('body *')].filter((el) => !excluded(el) && !(el instanceof SVGElement && el.tagName.toLowerCase() !== 'svg') && !['SCRIPT', 'STYLE', 'TEMPLATE', 'NOSCRIPT'].includes(el.tagName) && visible(el));
-  const collectSpacing = (el, cs) => {
-    for (const side of ['Top', 'Right', 'Bottom', 'Left']) put('spacing', px(cs[`padding${side}`]), el);
-    if (/flex|grid/.test(cs.display)) { put('spacing', px(cs.rowGap), el); put('spacing', px(cs.columnGap), el); }
-    if (cs.position !== 'static') {
-      for (const side of insetSides(el)) { const v = px(cs[side]); if (v != null) put('spacing', Math.abs(v), el); }
-    }
-  };
-  const collectRadii = (el, cs) => {
-    for (const corner of ['borderTopLeftRadius', 'borderTopRightRadius', 'borderBottomRightRadius', 'borderBottomLeftRadius']) {
-      const raw = String(cs[corner]).split(' ')[0];
-      if (!raw || raw === '0px') continue;
-      if (raw.endsWith('%')) put('radius', Number.parseFloat(raw) >= 50 ? 'circle' : raw, el);
-      else { const v = px(raw); const r = el.getBoundingClientRect(); put('radius', v != null && (v >= 999 || v >= Math.min(r.width, r.height) / 2 - 0.5) && v > 8 ? 'pill' : v, el); }
-    }
-  };
-  const collectText = (el, cs) => {
-    const text = [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim());
-    if (text) {
-      put('fontSize', px(cs.fontSize), el);
-      put('fontWeight', Number(cs.fontWeight) || null, el);
-      if (cs.lineHeight !== 'normal') put('lineHeight', px(cs.lineHeight), el);
-      colour(hexOf(cs.color), 'text', el);
-    }
-  };
-  const collectBorders = (el, cs) => {
-    for (const side of ['Top', 'Right', 'Bottom', 'Left']) if (Number.parseFloat(cs[`border${side}Width`]) > 0 && cs[`border${side}Style`] !== 'none') colour(hexOf(cs[`border${side}Color`]), 'border', el);
-  };
-  // The tracks of a grid template: pieces split at whitespace unless the next parenthesis after it closes one.
-  const trackCountOf = (template) => {
-    let count = 0, from = 0;
-    const closesFirst = (at) => { const open = template.indexOf('(', at), close = template.indexOf(')', at); return close !== -1 && (open === -1 || close < open); };
-    for (const run of template.matchAll(/\s+/g)) {
-      if (closesFirst(run.index + run[0].length)) continue;
-      if (run.index > from) count += 1;
-      from = run.index + run[0].length;
-    }
-    return template.length > from ? count + 1 : count;
-  };
-  const collectGrid = (el, cs) => {
-    if (cs.display === 'grid') {
-      const kids = [...el.children].filter((k) => visible(k) && !excluded(k));
-      if (kids.length >= 2) grids.push({ selector: sel(el), why: whyOf(el), columns: trackCountOf(cs.gridTemplateColumns) });
-    }
-  };
-  const measureElement = (el) => {
-    const cs = getComputedStyle(el);
-    collectSpacing(el, cs);
-    collectRadii(el, cs);
-    collectText(el, cs);
-    colour(hexOf(cs.backgroundColor), 'background', el);
-    collectBorders(el, cs);
-    collectGrid(el, cs);
-    if (/url\(/.test(cs.backgroundImage)) art.push({ selector: sel(el), why: whyOf(el) });
-  };
-  for (const el of all) {
-    measureElement(el);
-  }
-  const pick = (m) => [...m.entries()].map(([value, at]) => ({ value, at })).sort((a, b) => String(a.value).localeCompare(String(b.value), 'en', { numeric: true }));
-  const probe = document.createElement('i');
-  document.body.appendChild(probe);
-  const tokenColours = {};
-  const rootStyle = getComputedStyle(document.documentElement);
-  for (const t of tokens) {
-    if (!rootStyle.getPropertyValue(t).trim()) continue;
-    probe.style.color = `var(${t})`;
-    const hex = hexOf(getComputedStyle(probe).color);
-    if (hex) tokenColours[t] = hex;
-  }
-  probe.remove();
-  const container = document.querySelector('[data-grammar-component="PageContainer"]') ?? document.querySelector('main') ?? document.body;
-  const regions = [...container.children].filter((k) => !excluded(k) && !['SCRIPT', 'STYLE', 'TEMPLATE'].includes(k.tagName) && visible(k));
-  return { schema, viewport: { width: innerWidth, height: innerHeight }, values: Object.fromEntries(Object.entries(values).map(([k, m]) => [k, pick(m)])),
-    colours: [...colours.values()], grids, art, tokenColours, regions: { count: regions.length, whys: regions.map(whyOf) } };
-}
-
-/**
- * Draw the redline overlay into the page (html.annotate): spacing brackets with the value and the decision's first
- * rule id for region gaps and card paddings, a DNA label at each component root, the labels kept apart (a label that
- * would overlap another is moved, else dropped). `arg` {labels: redlineLabelsOf(entries), whyAttr, redlineAttr,
- * leaf: REDLINE_LEAF_COMPONENTS}.
- */
-export function drawRedlines(arg) {
-  const { labels = {}, whyAttr, redlineAttr, leaf = [] } = arg;
-  document.documentElement.classList.add('annotate');
-  const W = Math.max(document.documentElement.scrollWidth, document.body.scrollWidth);
-  const H = Math.max(document.documentElement.scrollHeight, document.body.scrollHeight);
-  const NS = 'http://www.w3.org/2000/svg';
-  const host = document.createElement('div');
-  host.setAttribute(redlineAttr, '');
-  host.setAttribute('aria-hidden', 'true');
-  host.style.cssText = `position:absolute;left:0;top:0;width:${W}px;height:${H}px;z-index:2147483647;pointer-events:none`;
-  const svg = document.createElementNS(NS, 'svg');
-  svg.setAttribute('width', W); svg.setAttribute('height', H); svg.setAttribute('viewBox', `0 0 ${W} ${H}`);
-  svg.style.cssText = 'position:absolute;left:0;top:0;overflow:visible';
-  host.appendChild(svg);
-  document.body.appendChild(host);
-  const RED = '#d4001a', BLUE = '#1d4ed8';
-  const placed = [];
-  const hits = (r) => placed.some((p) => r.x < p.x + p.w && r.x + r.w > p.x && r.y < p.y + p.h && r.y + r.h > p.y);
-  const el = (tag, attrs) => { const n = document.createElementNS(NS, tag); for (const [k, v] of Object.entries(attrs)) { n.setAttribute(k, v); } svg.appendChild(n); return n; };
-  const line = (x1, y1, x2, y2, c) => el('line', { x1, y1, x2, y2, stroke: c, 'stroke-width': 1 });
-  const label = (x, y, text, c) => {
-    const w = text.length * 6 + 6, h = 12;
-    for (const dy of [0, 13, -13, 26, -26, 39]) {
-      const r = { x: Math.min(Math.max(0, x), W - w), y: Math.max(0, y + dy - h), w, h };
-      if (hits(r)) continue;
-      placed.push(r);
-      el('rect', { x: r.x, y: r.y, width: w, height: h, fill: 'rgba(255,255,255,0.92)', stroke: c, 'stroke-width': 0.5, rx: 2 });
-      const t = el('text', { x: r.x + 3, y: r.y + 9, fill: c, 'font-size': 9, 'font-family': 'ui-monospace,Menlo,Consolas,monospace' });
-      t.textContent = text;
-      return true;
-    }
-    return false;
-  };
-  const box = (n) => { const b = n.getBoundingClientRect(); return { x: b.left + scrollX, y: b.top + scrollY, w: b.width, h: b.height }; };
-  const visible = (n) => { const b = n.getBoundingClientRect(); const cs = getComputedStyle(n); return b.width > 1 && b.height > 1 && cs.visibility !== 'hidden' && cs.display !== 'none'; };
-  const whys = (n) => (n.getAttribute(whyAttr) ?? '').split(/\s+/).filter(Boolean);
-  const labelOf = (n) => whys(n).map((id) => labels[id]).find(Boolean) ?? null;
-  const round = (v) => Math.round(v * 10) / 10;
-  const vtick = (x, y1, y2) => { line(x, y1, x, y2, RED); line(x - 3, y1, x + 3, y1, RED); line(x - 3, y2, x + 3, y2, RED); };
-  const htick = (x1, x2, y) => { line(x1, y, x2, y, RED); line(x1, y - 3, x1, y + 3, RED); line(x2, y - 3, x2, y + 3, RED); };
-  const all = [...document.querySelectorAll(`[${whyAttr}]`)].filter((n) => !n.closest(`[${redlineAttr}],#redlines`) && !(n instanceof SVGElement) && visible(n));
-  // Spacing brackets: the gaps between the children of a layout/spacing decision's element, and its padding.
-  const gapIsDecided = (ncs, gap) => gap <= 48 || [Number.parseFloat(ncs.rowGap), Number.parseFloat(ncs.columnGap)].some((d) => Number.isFinite(d) && Math.abs(d - gap) < 1);
-  const drawGapForPair = (first, second, shown, ncs, tag) => {
-    const a = box(first), b = box(second);
-    const vgap = round(b.y - (a.y + a.h)), hgap = round(b.x - (a.x + a.w));
-    if (vgap > 0.5 && gapIsDecided(ncs, vgap) && b.y >= a.y + a.h - 1) {
-      const x = Math.max(2, a.x - 5);
-      vtick(x, a.y + a.h, b.y);
-      if (!shown.has(`v${vgap}`)) { shown.add(`v${vgap}`); label(x + 4, a.y + a.h + vgap / 2 + 6, tag(vgap), RED); }
-    } else if (hgap > 0.5 && gapIsDecided(ncs, hgap) && Math.abs(a.y - b.y) < Math.max(a.h, b.h)) {
-      const y = a.y + Math.min(a.h, b.h) / 2;
-      htick(a.x + a.w, b.x, y);
-      if (!shown.has(`h${hgap}`)) { shown.add(`h${hgap}`); label(a.x + a.w, y - 4, tag(hgap), RED); }
-    }
-  };
-  const drawPadding = (n, tag) => {
-    const cs = getComputedStyle(n), b = box(n);
-    const pt = round(Number.parseFloat(cs.paddingTop) || 0), pl = round(Number.parseFloat(cs.paddingLeft) || 0);
-    if (pl > 0.5 && b.h > 24) htick(b.x, b.x + pl, b.y + Math.min(b.h - 4, 12));
-    if (pt > 0.5 && b.w > 24) vtick(b.x + Math.min(b.w - 4, 12), b.y, b.y + pt);
-    if (pt > 0.5 || pl > 0.5) label(b.x + pl + 2, b.y + pt + 11, tag(pt === pl || !pt || !pl ? `p ${pt || pl}` : `p ${pt}/${pl}`), RED);
-  };
-  const drawSpacingForElement = (n) => {
-    const l = labelOf(n);
-    if (!l || !['layout', 'spacing'].includes(l.kind)) return;
-    const tag = (v) => `${v}${l.rule ? ' · ' + l.rule : ''}`;
-    const kids = [...n.children].filter((k) => !(k instanceof SVGElement) && visible(k));
-    const shown = new Set();
-    // A decided gap is the container's gap (or a small margin); the free space of space-between is no decision.
-    const ncs = getComputedStyle(n);
-    for (let i = 0; i < kids.length - 1; i += 1) drawGapForPair(kids[i], kids[i + 1], shown, ncs, tag);
-    drawPadding(n, tag);
-  };
-  for (const n of all) drawSpacingForElement(n);
-  // DNA labels at component roots, regions outlined.
-  const drawComponentLabels = () => {
-    for (const n of document.querySelectorAll('[data-grammar-component]')) {
-      if (n.closest(`[${redlineAttr}],#redlines`) || !visible(n)) continue;
-      const name = n.dataset.grammarComponent;
-      const upName = n.parentElement?.closest('[data-grammar-component]')?.dataset.grammarComponent;
-      if (leaf.includes(name) || (upName === name && 'grammarPart' in n.dataset)) continue;
-      const b = box(n);
-      if (b.w < 48 || b.h < 24) continue;
-      const l = labelOf(n);
-      if (l?.kind === 'layout') el('rect', { x: b.x, y: b.y, width: b.w, height: b.h, fill: 'none', stroke: BLUE, 'stroke-width': 1, 'stroke-dasharray': '3 2' });
-      const variant = n.dataset.variant ?? n.dataset.tone ?? null;
-      label(b.x + 2, b.y + 12, `${name}${variant ? ' ' + variant : ''}`, BLUE);
-    }
-  };
-  drawComponentLabels();
-  return { labels: placed.length };
-}

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

@@ -1,14 +0,0 @@
-// draw-rationale-ref.mjs - a rationale rules[] entry read apart: `[namespace:] token [case-N]`.
-const REF_RX = /^\s*(?:([a-z]+):\s*)?([^\s,;()]+)(?:\s+(case-\d+))?/i;
-
-/** The match of a rules[] entry: [entry, namespace|undefined, token, case|undefined], or null. */
-export const parseRuleRef = (text) => REF_RX.exec(text);
-
-const TRAILING_MARKS = new Set(['.', ':']);
-
-/** `token` without its trailing `.` and `:` marks. */
-export function bareRuleToken(token) {
-  const kept = [...token];
-  while (kept.length && TRAILING_MARKS.has(kept.at(-1))) kept.pop();
-  return kept.join('');
-}