@3xhaust/oh-my-design 0.16.1

package/core/ref/batch.ts

@@ -0,0 +1,94 @@
+import { relative } from 'node:path';
+import { capturePageForRef, withBrowser, parseViewport } from '../render/index.ts';
+import { normalize } from '../ir/normalize.ts';
+import { extractInvariants } from './invariants.ts';
+import { captureBlueprint } from './blueprint.ts';
+import { saveRef, refImagePath } from './store.ts';
+import { loadRules, check } from '../rules/engine.ts';
+
+/**
+ * One reference to capture in a batch. Same shape as an `omd ref add --selector … --blueprint --shot`
+ * call, minus the energy (motion) pass: batch capture is optimised for the common non-motion board,
+ * so a motion reference that needs an energy study goes through the single-ref `omd ref add` path.
+ */
+export interface RefSpec {
+  source: string;
+  as: string;
+  selector?: string;
+  blueprint?: boolean;
+  shot?: boolean;
+  fromUser?: boolean;
+  viewport?: string;
+}
+
+export interface BatchOutcome {
+  source: string;
+  as: string;
+  ok: boolean;
+  error?: string;
+  slopCount?: number;
+}
+
+export interface BatchResult {
+  concurrency: number;
+  outcomes: BatchOutcome[];
+}
+
+/**
+ * Capture many references concurrently over ONE shared browser. Each reference is one page and one
+ * navigation (IR plus an optional scoped screenshot), so the board is built in a fraction of the
+ * wall time of one-browser-launch-per-reference — and with byte-identical per-reference results,
+ * so the output the board feeds is unchanged. A single reference failing never fails the batch.
+ */
+export async function addRefsBatch(
+  cwd: string,
+  specs: RefSpec[],
+  opts: { rulesRoot: string; concurrency?: number },
+): Promise<BatchResult> {
+  const concurrency = Math.max(1, opts.concurrency ?? 4);
+  const rules = loadRules(opts.rulesRoot);
+  const outcomes: BatchOutcome[] = new Array<BatchOutcome>(specs.length);
+
+  await withBrowser(async (browser) => {
+    let next = 0;
+    const worker = async (): Promise<void> => {
+      for (;;) {
+        const i = next++;
+        if (i >= specs.length) return;
+        const spec = specs[i]!;
+        try {
+          const shotOut = spec.shot && spec.selector
+            ? refImagePath(cwd, { source: spec.source, component: spec.as })
+            : undefined;
+          const { raw, shotSaved } = await capturePageForRef(browser, spec.source, parseViewport(spec.viewport), {
+            selector: spec.selector ?? null,
+            ...(shotOut ? { shotOut } : {}),
+          });
+          const ir = normalize(raw);
+          const invariants = extractInvariants(ir);
+          const slopCount = check(ir, rules, { categories: ['slop'] }).length;
+          const blueprint = spec.blueprint && spec.selector ? captureBlueprint(raw.nodes, spec.selector) : undefined;
+          saveRef(cwd, {
+            source: spec.source,
+            component: spec.as,
+            kind: spec.selector ? 'component' : 'page',
+            capturedAt: new Date().toISOString(),
+            ...(spec.selector ? { selector: spec.selector } : {}),
+            invariants,
+            principles: [],
+            slopCount,
+            ...(spec.fromUser ? { origin: 'user' as const } : {}),
+            ...(blueprint !== undefined ? { blueprint } : {}),
+            ...(shotSaved && shotOut ? { imagePath: relative(cwd, shotOut) } : {}),
+          });
+          outcomes[i] = { source: spec.source, as: spec.as, ok: true, slopCount };
+        } catch (err) {
+          outcomes[i] = { source: spec.source, as: spec.as, ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, specs.length) }, () => worker()));
+  });
+
+  return { concurrency, outcomes };
+}

package/core/ref/blueprint.ts

@@ -0,0 +1,199 @@
+import type { RawNode } from '../types.ts';
+import type { Blueprint, BlueprintNode, ColorRole, NodeRole, TextLengthClass } from '../types.ts';
+
+/**
+ * WCAG relative luminance from a hex string like '#AABBCC'.
+ * Returns 0 for unrecognised values.
+ */
+export function relativeLuminance(hex: string): number {
+  const clean = hex.replace('#', '');
+  if (clean.length !== 6) return 0;
+  const f = (c: number): number => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  const r = f(parseInt(clean.slice(0, 2), 16) / 255);
+  const g = f(parseInt(clean.slice(2, 4), 16) / 255);
+  const b = f(parseInt(clean.slice(4, 6), 16) / 255);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * HSL saturation (0..1) from a hex string. Near-grey colors return 0.
+ * Used to identify accent colors that stand out by hue rather than by luminance.
+ */
+export function hexSaturation(hex: string): number {
+  const clean = hex.replace('#', '');
+  if (clean.length !== 6) return 0;
+  const r = parseInt(clean.slice(0, 2), 16) / 255;
+  const g = parseInt(clean.slice(2, 4), 16) / 255;
+  const b = parseInt(clean.slice(4, 6), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  if (max === min) return 0;
+  const l = (max + min) / 2;
+  const d = max - min;
+  return l > 0.5 ? d / (2 - max - min) : d / (max + min);
+}
+
+export interface ColorEntry {
+  hex: string;
+  count: number;
+  /** True for background/fill colors; false for text colors. */
+  isFill: boolean;
+}
+
+/**
+ * Cluster component colors into semantic roles using usage frequency and relative luminance.
+ * Literal hex values never leave this function; only roles are stored in the blueprint.
+ *
+ * Assignment order (each hex is claimed by the first matching rule):
+ * 1. accent  — minority color (count < max) with highest HSL saturation > 0.25;
+ *              text colors are preferred over fills since interactive elements often use text
+ * 2. bg      — most-frequent fill (darker fill wins ties)
+ * 3. surface — remaining fills (elevated panels, cards)
+ * 4. fg      — most-frequent text color (darker text wins ties)
+ * 5. muted   — remaining text colors
+ *
+ * This is a pure function: identical input → identical output.
+ */
+export function clusterColorRoles(colors: ColorEntry[]): Map<string, ColorRole> {
+  const result = new Map<string, ColorRole>();
+  if (colors.length === 0) return result;
+
+  const maxCount = Math.max(...colors.map((c) => c.count));
+
+  // Accent: a minority saturated color that stands out from the structural palette.
+  // Text colors are preferred (CTAs, links), then fills (branded buttons).
+  // A color at max frequency is structural — it cannot be an accent.
+  const accentCandidate = [...colors]
+    .filter((c) => c.count < maxCount && hexSaturation(c.hex) > 0.25)
+    .sort((a, b) => {
+      // Text colors first; within same kind, higher saturation wins.
+      if (a.isFill !== b.isFill) return a.isFill ? 1 : -1;
+      return hexSaturation(b.hex) - hexSaturation(a.hex);
+    })[0];
+  if (accentCandidate) result.set(accentCandidate.hex, 'accent');
+
+  // Fills: most-frequent → bg; rest → surface.
+  // Ties in frequency are broken by luminance (darker fill = more dominant backdrop).
+  const fills = colors
+    .filter((c) => c.isFill && !result.has(c.hex))
+    .sort((a, b) => b.count - a.count || relativeLuminance(a.hex) - relativeLuminance(b.hex));
+  fills.forEach((f, i) => result.set(f.hex, i === 0 ? 'bg' : 'surface'));
+
+  // Text colors: most-frequent → fg; rest → muted.
+  const texts = colors
+    .filter((c) => !c.isFill && !result.has(c.hex))
+    .sort((a, b) => b.count - a.count || relativeLuminance(a.hex) - relativeLuminance(b.hex));
+  texts.forEach((t, i) => result.set(t.hex, i === 0 ? 'fg' : 'muted'));
+
+  return result;
+}
+
+/** Derive the semantic role of a node from its IR fields. */
+export function deriveNodeRole(node: Pick<RawNode, 'type' | 'interactive' | 'heading' | 'name'>): NodeRole {
+  if (node.interactive) return 'interactive';
+  if (node.heading !== undefined) return 'heading';
+  if (node.type === 'TEXT') return 'text';
+  // Heuristic for image elements: the DOM extractor encodes the tag name as the first
+  // segment of node.name (tagname.firstClass). Match common image container tags.
+  const tag = (node.name.split('.')[0] ?? '').toLowerCase();
+  if (tag === 'img' || tag === 'svg' || tag === 'picture' || tag === 'figure') return 'image';
+  return 'container';
+}
+
+/** Derive the text length class from node text content. Copy is never stored. */
+export function deriveTextLength(text: string): TextLengthClass {
+  if (text.length <= 20) return 'label';
+  if (text.length <= 80) return 'phrase';
+  return 'paragraph';
+}
+
+/**
+ * Build a Blueprint from a component's raw nodes.
+ *
+ * What is stored per node: role, box dimensions, layout metrics (padding, gap, direction),
+ * typography metrics (fontSize, fontWeight, lineHeight), surface geometry (radius, shadow),
+ * color roles (bg/surface/fg/muted/accent — no literal hex values), motion timings, and a
+ * text length class (label/phrase/paragraph — no actual copy).
+ *
+ * What is NOT stored: text content, literal color values, alignment (not measured by the
+ * IR extractor), border details (not measured by the IR extractor).
+ *
+ * Inherited fills — transparent nodes that show an ancestor's backdrop — are excluded from
+ * the color inventory and from each node's fillRole so the component's own palette is what
+ * gets clustered.
+ *
+ * @param nodes     Raw nodes from extractIr, already scoped to the selector.
+ * @param selector  The CSS selector that bounded this capture (stored as metadata).
+ */
+export function captureBlueprint(nodes: RawNode[], selector: string): Blueprint {
+  // Build color frequency map. Keyed by hex+kind so the same color can appear as both a
+  // fill (background) and a text color — they are different roles in different slots.
+  const colorMap = new Map<string, ColorEntry>();
+  const trackColor = (hex: string, isFill: boolean): void => {
+    const key = `${hex}:${isFill ? 'f' : 't'}`;
+    const entry = colorMap.get(key);
+    if (entry) entry.count += 1;
+    else colorMap.set(key, { hex, count: 1, isFill });
+  };
+
+  for (const node of nodes) {
+    // Only authored (non-inherited) fills represent the node's own background.
+    const fill = node.fill;
+    if (fill && typeof fill.value === 'string' && !fill.inherited) {
+      trackColor(fill.value, true);
+    }
+    if (node.color) trackColor(node.color, false);
+  }
+
+  const colorRoleMap = clusterColorRoles([...colorMap.values()]);
+
+  const bpNodes: BlueprintNode[] = nodes.map((node): BlueprintNode => {
+    const role = deriveNodeRole(node);
+
+    const bp: BlueprintNode = {
+      id: node.id,
+      role,
+      children: [...node.children],
+      box: { w: node.box.w, h: node.box.h },
+    };
+
+    // Layout: store padding and gap only when non-trivial; direction always when present.
+    if (node.layout) {
+      bp.padding = node.layout.padding;
+      if (node.layout.gap > 0) bp.gap = node.layout.gap;
+      bp.direction = node.layout.mode;
+    }
+
+    // Typography: only the fields the extractor actually measured.
+    if (node.fontSize != null) bp.fontSize = node.fontSize;
+    if (node.fontWeight != null) bp.fontWeight = node.fontWeight;
+    if (node.lineHeight != null) bp.lineHeight = node.lineHeight;
+
+    // Surface geometry.
+    const rv = node.radius?.value;
+    if (typeof rv === 'number' && rv > 0) bp.radius = rv;
+    if (node.shadow?.value) bp.hasShadow = true;
+
+    // Color roles — literal hexes never leave this function.
+    const fillHex = node.fill?.value;
+    if (typeof fillHex === 'string' && !node.fill?.inherited) {
+      const cr = colorRoleMap.get(fillHex);
+      if (cr) bp.fillRole = cr;
+    }
+    if (node.color) {
+      const cr = colorRoleMap.get(node.color);
+      if (cr) bp.textRole = cr;
+    }
+
+    // Motion timings: durations and easings, no animation names.
+    if (node.motion?.durations?.length) bp.motionDurations = [...node.motion.durations];
+    if (node.motion?.easings?.length) bp.motionEasings = [...node.motion.easings];
+
+    // Text length class — content stripped, only length signal remains.
+    if (node.text) bp.textLength = deriveTextLength(node.text);
+
+    return bp;
+  });
+
+  return { selector, capturedAt: new Date().toISOString(), nodes: bpNodes };
+}

package/core/ref/distance.ts

@@ -0,0 +1,225 @@
+import type { Invariants, Reference, RefDistance } from '../types.ts';
+
+/**
+ * Jaccard: shared rungs over total distinct rungs.
+ *
+ * The question is not "does this page use 8px" — nearly every page does. It is "does this
+ * page have the same rhythm": the same rungs, and no others. Two designs on the 8pt grid
+ * share 4/8/16 by convention, not by copying, and Jaccard's union denominator is what
+ * charges them for the rungs they do not share.
+ *
+ * Measured against Szymkiewicz–Simpson overlap, which normalises by the shorter ladder:
+ * that scored an ordinary five-rung 8pt scale at 0.82 against Linear's thirteen rungs,
+ * because a short ladder sits inside a long one by construction. Containment is not
+ * similarity.
+ */
+function jaccard(a: number[], b: number[]): number {
+  const setA = new Set(a);
+  const setB = new Set(b);
+  if (setA.size === 0 && setB.size === 0) return 1;
+
+  let shared = 0;
+  for (const v of setA) if (setB.has(v)) shared += 1;
+  const union = setA.size + setB.size - shared;
+  return union === 0 ? 1 : shared / union;
+}
+
+/** Same idea as `jaccard`, over strings: font families, easing functions. */
+function jaccardStrings(a: string[], b: string[]): number {
+  const setA = new Set(a);
+  const setB = new Set(b);
+  if (setA.size === 0 && setB.size === 0) return 1;
+
+  let shared = 0;
+  for (const v of setA) if (setB.has(v)) shared += 1;
+  const union = setA.size + setB.size - shared;
+  return union === 0 ? 1 : shared / union;
+}
+
+const ratioDiff = (a: number, b: number): number => 1 - Math.abs(a - b) / Math.max(a, b, 1);
+
+/**
+ * Padding is felt as a proportion, not a difference: 10px against 40px is a different
+ * design, 100px against 130px is the same design. `ratioDiff` disagreed, scoring the
+ * identical 30px gap 0.25 and 0.77. Comparing logs makes the metric scale-free.
+ */
+function logRatio(a: number, b: number): number {
+  if (a === b) return 1;
+  const la = Math.log1p(Math.max(a, 0));
+  const lb = Math.log1p(Math.max(b, 0));
+  const span = Math.max(la, lb, 1);
+  return Math.max(0, 1 - Math.abs(la - lb) / span);
+}
+
+const WEIGHTS = {
+  spacingLadder: 0.12,
+  radiusLadder: 0.12,
+  typeScale: 0.13,
+  fontFamilies: 0.09,
+  weightLadder: 0.05,
+  motionDurations: 0.06,
+  easingVocab: 0.04,
+  animatedShare: 0.03,
+  elevationLevels: 0.09,
+  centeredRatio: 0.07,
+  tokenCoverage: 0.07,
+  paddingWeight: 0.07,
+  // Interaction states: hover-response and focus-visible coverage. .03 each, taken from
+  // spacingLadder/radiusLadder (.15 -> .12) so the table still sums to 1.00.
+  hoverCoverage: 0.03,
+  focusCoverage: 0.03,
+} as const;
+
+type Component = keyof typeof WEIGHTS;
+
+function componentScores(a: Invariants, b: Invariants): Record<Component, number> {
+  return {
+    spacingLadder: jaccard(a.spacingLadder, b.spacingLadder),
+    radiusLadder: jaccard(a.radiusLadder, b.radiusLadder),
+    typeScale: jaccard(a.typeScale, b.typeScale),
+    fontFamilies: jaccardStrings(a.fontFamilies, b.fontFamilies),
+    weightLadder: jaccard(a.weightLadder, b.weightLadder),
+    motionDurations: jaccard(a.motionDurations, b.motionDurations),
+    easingVocab: jaccardStrings(a.easingVocab, b.easingVocab),
+    animatedShare: 1 - Math.abs(a.animatedShare - b.animatedShare),
+    elevationLevels: ratioDiff(a.elevationLevels, b.elevationLevels),
+    centeredRatio: 1 - Math.abs(a.centeredRatio - b.centeredRatio),
+    tokenCoverage: 1 - Math.abs(a.tokenCoverage - b.tokenCoverage),
+    paddingWeight: logRatio(a.paddingWeight, b.paddingWeight),
+    hoverCoverage: 1 - Math.abs(a.hoverCoverage - b.hoverCoverage),
+    focusCoverage: 1 - Math.abs(a.focusCoverage - b.focusCoverage),
+  };
+}
+
+/**
+ * Components backed by a ladder/vocabulary array, as opposed to a scalar. Only these can
+ * be "unmeasured" on one side — a scalar always has a value (0 is a real measurement, an
+ * empty ladder is the absence of one).
+ */
+const ARRAY_COMPONENTS = [
+  'spacingLadder', 'radiusLadder', 'typeScale', 'fontFamilies', 'weightLadder',
+  'motionDurations', 'easingVocab',
+] as const satisfies readonly Component[];
+
+function arrayFor(inv: Invariants, key: (typeof ARRAY_COMPONENTS)[number]): readonly (number | string)[] {
+  return inv[key];
+}
+
+/**
+ * Scalar components where 0 is ambiguous: a page where every interactive element truly
+ * fails to respond scores identically to a page that was never probed at all (an
+ * unmeasured pre-interaction reference, or a probe failure). Both read as `hoverCoverage:
+ * 0` / `focusCoverage: 0`. Scoring a real page against an old reference with `1 -
+ * |a-b|` would then punish it for a coverage gap that was never actually measured on the
+ * reference's side — so, like the array components above, exclude the component (and
+ * renormalise) whenever either side reads exactly 0.
+ */
+const ZERO_EXCLUDABLE_COMPONENTS = ['hoverCoverage', 'focusCoverage'] as const satisfies readonly Component[];
+
+/**
+ * F1: an empty ladder is not "measured and maximally different" — it is unmeasured. A
+ * pre-typography reference defaults typeScale/fontFamilies/weightLadder/motionDurations/
+ * easingVocab to `[]` (core/ref/store.ts withInvariantDefaults). Scoring that against a
+ * populated ladder with jaccard hits the empty-vs-populated branch (0, not the
+ * both-empty-is-1 branch), which the geometric mean then floors to EPSILON and drags the
+ * whole product toward zero — collapsing an old reference's similarity to its own,
+ * identical page to ~0.08–0.15. Excluding the component when either side is empty (and
+ * renormalising the remaining weights) treats "unmeasured" as neutral instead of as a
+ * maximal mismatch. Both-empty is excluded too — no longer a reward for two designs that
+ * simply never used the feature, since there is nothing there to have agreed on.
+ */
+function excludedComponents(a: Invariants, b: Invariants): ReadonlySet<Component> {
+  const excluded = new Set<Component>();
+  for (const key of ARRAY_COMPONENTS) {
+    if (arrayFor(a, key).length === 0 || arrayFor(b, key).length === 0) excluded.add(key);
+  }
+  for (const key of ZERO_EXCLUDABLE_COMPONENTS) {
+    if (a[key] === 0 || b[key] === 0) excluded.add(key);
+  }
+  return excluded;
+}
+
+/**
+ * Weighted GEOMETRIC mean, not arithmetic.
+ *
+ * An arithmetic mean lets agreement on the cheap components hide disagreement on the
+ * expensive ones. Two pages with nothing in common but a shared centred-text ratio, token
+ * coverage and padding weight already floor at 0.50 — over half the copying threshold —
+ * before their spacing and radius ladders are even consulted. Measured: Linear's thirteen
+ * spacing rungs against an ordinary five-rung 8pt scale scored 0.632, flagged as a copy,
+ * on ladder scores of 0.385 and 0.143.
+ *
+ * A design's identity lives in its ladders. Under a geometric mean a near-zero on either
+ * one drags the product down and no amount of incidental agreement rescues it.
+ */
+export function similarity(a: Invariants, b: Invariants): number {
+  const scores = componentScores(a, b);
+  const excluded = excludedComponents(a, b);
+  const keys = (Object.keys(WEIGHTS) as Component[]).filter((key) => !excluded.has(key));
+
+  // F1: if every array component is unmeasured on one side or the other, nothing is left
+  // to compare — two totally unmeasured things cannot be distinguished, so treat them as
+  // identical rather than maximally different (the old empty-scores-0 behaviour).
+  if (keys.length === 0) return 1;
+
+  // Renormalise: the excluded components' weight is redistributed proportionally over
+  // what remains, so the included weights still sum to 1.
+  const weightSum = keys.reduce((sum, key) => sum + WEIGHTS[key], 0);
+
+  // log(0) is -Infinity, which would make every dissimilar pair score exactly 0 and lose
+  // all ordering among them. The floor keeps them comparable.
+  const EPSILON = 1e-3;
+  let logSum = 0;
+  for (const key of keys) logSum += (WEIGHTS[key] / weightSum) * Math.log(Math.max(scores[key], EPSILON));
+
+  return Math.min(1, Math.max(0, Math.exp(logSum)));
+}
+
+export interface KinshipPair {
+  /** Source URL of the first reference. */
+  a: string;
+  /** Source URL of the second reference. */
+  b: string;
+  similarity: number;
+}
+
+/**
+ * Pairwise similarity over the board. Returns the top-N pairs whose similarity meets or
+ * exceeds `threshold`, sorted most-similar first. Image references (null invariants) are
+ * excluded — pixels have no invariants to compare.
+ *
+ * A cluster of near-identical references is not breadth: it is the same average measured
+ * multiple times. When AI-generated pages dominate a search result set, they tend to
+ * cluster here. That is the contamination signal.
+ */
+export function topKinshipPairs(refs: Reference[], threshold = 0.85, topN = 3): KinshipPair[] {
+  const measured = refs.filter(
+    (r): r is Reference & { invariants: Invariants } => r.invariants !== null,
+  );
+  const pairs: KinshipPair[] = [];
+  for (let i = 0; i < measured.length; i++) {
+    for (let j = i + 1; j < measured.length; j++) {
+      const sim = similarity(measured[i]!.invariants, measured[j]!.invariants);
+      if (sim >= threshold) {
+        pairs.push({ a: measured[i]!.source, b: measured[j]!.source, similarity: sim });
+      }
+    }
+  }
+  return pairs.sort((x, y) => y.similarity - x.similarity).slice(0, topN);
+}
+
+export function distances(page: Invariants, refs: Reference[]): RefDistance[] {
+  return refs
+    .filter((ref): ref is Reference & { invariants: Invariants } => ref.invariants !== null)
+    .map((ref) => {
+      const scores = componentScores(page, ref.invariants);
+      const excluded = excludedComponents(page, ref.invariants);
+      // F1: drivers are computed from the included components only — an excluded
+      // (unmeasured) component cannot have driven the score.
+      const drivers = (Object.keys(WEIGHTS) as Component[])
+        .filter((key) => !excluded.has(key) && scores[key] >= 0.8)
+        .sort((x, y) => scores[y] - scores[x]);
+      return { reference: ref.source, similarity: similarity(page, ref.invariants), drivers };
+    })
+    .sort((a, b) => b.similarity - a.similarity);
+}

package/core/ref/invariants.ts

@@ -0,0 +1,162 @@
+import type { Ir, Invariants } from '../types.ts';
+
+/**
+ * Keeps the values that carry 90% of the uses, sorted ascending. Zero is dropped first —
+ * on a real page `padding: 0` is the majority of every spacing value and would otherwise
+ * dominate the ladder. Linear declares 11 distinct radii; the 90% cut leaves 7, which is
+ * what a designer would actually name.
+ */
+export function ladder(histogram: Record<string, number>): number[] {
+  const entries = Object.entries(histogram).filter(([key]) => key !== '0');
+  const total = entries.reduce((sum, [, count]) => sum + count, 0);
+  if (total === 0) return [];
+
+  const sorted = [...entries].sort(([, a], [, b]) => b - a);
+  const kept: number[] = [];
+  let covered = 0;
+  for (const [key, count] of sorted) {
+    kept.push(Number(key));
+    covered += count;
+    if (covered / total >= 0.9) break;
+  }
+  return kept.sort((a, b) => a - b);
+}
+
+/** Splits a comma-separated shadow list on commas that are not inside parentheses. */
+function splitLayers(shadow: string): string[] {
+  const layers: string[] = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of shadow) {
+    if (ch === '(') depth += 1;
+    else if (ch === ')') depth -= 1;
+    if (ch === ',' && depth === 0) {
+      layers.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim() !== '') layers.push(current);
+  return layers;
+}
+
+/**
+ * True when a single shadow layer has zero x-offset, zero y-offset and zero blur — a
+ * border drawn as a box-shadow. Colour and `inset` are stripped first so their digits
+ * (e.g. the `0.2` in `rgba(0, 0, 0, 0.2)`) never get mistaken for offsets.
+ */
+function isHairlineLayer(layer: string): boolean {
+  const withoutColor = layer.replace(/\([^)]*\)/g, ' ');
+  const withoutInset = withoutColor.replace(/\binset\b/g, ' ');
+  const lengths = withoutInset.trim().split(/\s+/).filter((t) => t.length > 0);
+  const [x, y, blur] = lengths;
+  if (x === undefined || y === undefined || blur === undefined) return false;
+  const toNum = (v: string): number => parseFloat(v) || 0;
+  return toNum(x) === 0 && toNum(y) === 0 && toNum(blur) === 0;
+}
+
+export function isHairline(shadow: string): boolean {
+  const layers = splitLayers(shadow).map((l) => l.trim()).filter((l) => l.length > 0);
+  if (layers.length === 0) return false;
+  return layers.every(isHairlineLayer);
+}
+
+const round = (value: number, dp: number): number => {
+  const factor = 10 ** dp;
+  return Math.round(value * factor) / factor;
+};
+
+export function extractInvariants(ir: Ir): Invariants {
+  const spacingLadder = ladder(ir.stats.spacingHistogram);
+  const radiusLadder = ladder(ir.stats.radiusHistogram);
+
+  const elevationLevels = Object.keys(ir.stats.shadowHistogram)
+    .filter((key) => key !== 'none' && !isHairline(key)).length;
+
+  const centeredRatio = ir.stats.centeredTextRatio;
+
+  const tokenableNodes = ir.nodes.filter((n) => n.fill != null || n.radius != null);
+  const tokenCoverage = tokenableNodes.length === 0
+    ? 1
+    : round(tokenableNodes.reduce((sum, n) => sum + n.computed.tokenCoverage, 0) / tokenableNodes.length, 4);
+
+  const paddedNodes = ir.nodes.filter((n) => n.layout?.padding != null);
+  const paddingWeight = paddedNodes.length === 0
+    ? 0
+    : round(
+      paddedNodes.reduce((sum, n) => sum + n.layout!.padding.reduce((s, v) => s + v, 0), 0) / paddedNodes.length,
+      2,
+    );
+
+  // Typography: histograms over text-bearing nodes, ladder-cut the same way spacing and
+  // radius are — a font-size used once in a footer should not dilute the scale.
+  const fontSizeHistogram: Record<string, number> = {};
+  const fontWeightHistogram: Record<string, number> = {};
+  const fontFamilies = new Set<string>();
+  for (const n of ir.nodes) {
+    if (n.fontSize != null) fontSizeHistogram[n.fontSize] = (fontSizeHistogram[n.fontSize] ?? 0) + 1;
+    if (n.fontWeight != null) fontWeightHistogram[n.fontWeight] = (fontWeightHistogram[n.fontWeight] ?? 0) + 1;
+    if (n.fontFamily) fontFamilies.add(n.fontFamily);
+  }
+  const typeScale = ladder(fontSizeHistogram);
+  const weightLadder = ladder(fontWeightHistogram);
+
+  // Motion: durations ladder-cut the same way; easings and families are the full sorted
+  // vocabulary — a design either uses `cubic-bezier(0.2,0,0,1)` or it does not, there is no
+  // 90th-percentile cut for a vocabulary.
+  const durationHistogram: Record<string, number> = {};
+  const easingVocabSet = new Set<string>();
+  let animatedNodes = 0;
+  for (const n of ir.nodes) {
+    if (!n.motion) continue;
+    animatedNodes += 1;
+    for (const d of n.motion.durations) durationHistogram[d] = (durationHistogram[d] ?? 0) + 1;
+    for (const e of n.motion.easings) easingVocabSet.add(e);
+  }
+  const motionDurations = ladder(durationHistogram);
+  const animatedShare = ir.nodes.length === 0 ? 0 : round(animatedNodes / ir.nodes.length, 4);
+
+  // Interaction: read defensively. The probe (core/render/index.ts) attaches
+  // ir.meta.interaction on success and null on failure; a hand-built or pre-probe IR
+  // (fixtures, old references) has no meta.interaction at all.
+  const interaction = ir.meta?.['interaction'] as
+    | { probed: number; hoverResponsive: number; tabStops: number; focusVisible: number }
+    | null
+    | undefined;
+  const hoverCoverage = interaction && interaction.probed > 0
+    ? round(interaction.hoverResponsive / interaction.probed, 2)
+    : 0;
+  const focusCoverage = interaction && interaction.tabStops > 0
+    ? round(interaction.focusVisible / interaction.tabStops, 2)
+    : 0;
+
+  // Motion probe: attached by probeMotion() in core/render/index.ts. Absent on IRs
+  // captured before the probe existed — read defensively to keep old refs loading cleanly.
+  // PROBE LIMIT: rAF-driven libs (GSAP) are not visible to getAnimations(); their absence
+  // from animatedProperties is a correct measurement, not a missing field.
+  const motionProbe = ir.meta?.['motion'] as
+    | { animatedProperties?: string[]; hasReducedMotion?: boolean; scrollChoreography?: Array<{ step: number; fired: number; entered: number }> }
+    | null
+    | undefined;
+  const animatedProperties = motionProbe?.animatedProperties
+    ? [...motionProbe.animatedProperties].sort()
+    : [];
+  const hasReducedMotion = motionProbe?.hasReducedMotion ?? false;
+  const scrollChoreography = motionProbe?.scrollChoreography ?? [];
+
+  return {
+    spacingLadder, radiusLadder, elevationLevels, centeredRatio, tokenCoverage, paddingWeight,
+    typeScale,
+    fontFamilies: Array.from(fontFamilies).sort(),
+    weightLadder,
+    motionDurations,
+    easingVocab: Array.from(easingVocabSet).sort(),
+    animatedShare,
+    hoverCoverage,
+    focusCoverage,
+    animatedProperties,
+    hasReducedMotion,
+    scrollChoreography,
+  };
+}