@weft-js/warp-core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# @weft-js/warp-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.1).** APIs will change between minor versions.
+
+warp's behaviour, tokens and CSS, with no components: plain TypeScript over the DOM. `@weft-js/warp` builds its components
+on it. Nothing in the main entry imports a framework, so it works under weft, React, Solid or no framework at all.
+
+```bash
+npm install @weft-js/warp-core
+```
+
+## When to skip it
+
+Most weft apps should skip it.
+
+- **You want finished components:** install `@weft-js/warp`. It brings this package with it.
+- **You want no warp at all:** you need neither package. `npm create @weft-js -- --ui none` and `--ui tailwind` install
+  neither.
+- **You want your own markup and warp's keyboard, focus and motion:** this package is for you. `npm create @weft-js -- --ui headless`
+  sets it up.
+
+## What's in it
+
+- **Behaviour:** `menu`, `dialog`, `popover`, `tooltip`, `indicator`, `roving`, `slider` and more.
+  Each is an action, `(el, options) => { update, destroy }`.
+- **Helpers:** pure functions such as `nextIndex`, `place` and `uid`.
+- **CSS:** `@weft-js/warp-core/styles/warp.css` has the tokens. Each component has its own file, such as
+  `@weft-js/warp-core/styles/components/tabs.css`. Skip them and bring your own CSS if you like.
+- **Other entries:** `/motion`, `/charts`, `/canvas`, `/dither` and `/search`.
+
+## `use`: an action in a weft component
+
+`use` comes from `@weft-js/warp-core/weft`, the one entry that needs `@weft-js/core`. It starts the action once the element is in the
+document, never on the server. It calls `update` when the options change and `destroy` with the component.
+
+```ts
+use(action, () => element, () => options)
+```
+
+`update` runs only when the value from the options getter changes. An option the action doesn't read still counts, so
+read a box there to re-run it, like `at` in the tabs below.
+
+Outside weft, make the action yourself:
+
+```ts
+const bar = indicator(list, { selected: '[aria-selected="true"]' })
+bar.update() // after the selection changes
+bar.destroy() // when the element goes
+```
+
+## Tabs
+
+`nextIndex` turns a key into the tab to move to: arrows wrap, and Home and End jump. It returns -1 for any other key.
+`indicator` slides the `data-part="indicator"` element to the selected tab.
+
+```tsx
+import { indicator, nextIndex } from '@weft-js/warp-core'
+import { use } from '@weft-js/warp-core/weft'
+import '@weft-js/warp-core/styles/warp.css'
+import '@weft-js/warp-core/styles/components/tabs.css'
+import { state } from '@weft-js/core'
+
+const names = ['Plan', 'Billing', 'Team']
+
+export function Settings() {
+  const at = state(0)
+  let list: HTMLDivElement | undefined
+  use(indicator, () => list, () => ({ selected: '[aria-selected="true"]', at: at.value }))
+
+  const onKey = (e: KeyboardEvent) => {
+    const to = nextIndex(e.key, at.value, names.length)
+    if (to < 0) return
+    e.preventDefault()
+    at.value = to
+    list?.querySelectorAll<HTMLElement>('[role="tab"]')[to]?.focus()
+  }
+
+  return (
+    <div data-scope="tabs" data-part="root">
+      <div ref={(n: any) => (list = n)} data-part="list" role="tablist" aria-label="Settings" onKeyDown={onKey}>
+        {names.map((name, i) => (
+          <button
+            key={name}
+            data-part="trigger"
+            role="tab"
+            type="button"
+            aria-selected={at.value === i ? 'true' : 'false'}
+            tabindex={at.value === i ? undefined : '-1'}
+            onClick={() => (at.value = i)}
+          >
+            {name}
+          </button>
+        ))}
+        <span data-part="indicator" aria-hidden="true"></span>
+      </div>
+      <div data-part="content" role="tabpanel" tabindex="0">{names[at.value]}</div>
+    </div>
+  )
+}
+```
+
+## A menu
+
+`menu` moves focus in when `open` turns true. It handles arrows, typeahead, Enter, Escape, Tab and an outside press, and
+calls `onClose`. Showing and hiding the panel is yours. Here that's `hidden`. Items need `tabindex="-1"`.
+
+```tsx
+import { menu } from '@weft-js/warp-core'
+import { use } from '@weft-js/warp-core/weft'
+import { state } from '@weft-js/core'
+
+export function AccountMenu() {
+  const open = state(false)
+  let button: HTMLButtonElement | undefined
+  let panel: HTMLDivElement | undefined
+  use(menu, () => panel, () => ({ open: open.value, trigger: () => button, onClose: () => (open.value = false) }))
+
+  const pick = (run: () => void) => {
+    open.value = false
+    button?.focus()
+    run()
+  }
+
+  return (
+    <div>
+      <button ref={(n: any) => (button = n)} type="button" aria-haspopup="menu" aria-expanded={open.value ? 'true' : 'false'} onClick={() => (open.value = !open.value)}>
+        Account
+      </button>
+      <div ref={(n: any) => (panel = n)} role="menu" hidden={!open.value}>
+        <button role="menuitem" tabindex="-1" type="button" onClick={() => pick(() => (location.hash = 'profile'))}>Profile</button>
+        <button role="menuitem" tabindex="-1" type="button" onClick={() => pick(() => (location.hash = 'out'))}>Sign out</button>
+      </div>
+    </div>
+  )
+}
+```

package/bindings/weft.ts

@@ -0,0 +1,23 @@
+// The weft binding, and the one file in this package that imports a framework. `@weft-js/warp-core` itself never does
+// (test/agnostic.test.mjs), so this stays behind its own subpath: `@weft-js/warp-core/weft`.
+import { onCleanup, onMount, untrack, watch } from '@weft-js/core'
+import type { Action } from '../src/store'
+
+/**
+ * Attach a warp-core action to an element once it is in the document (never on the server), feed it `opts` whenever
+ * they change, and destroy it with the component. Call it in a component's setup. `el` is read after mount, so a `ref`
+ * variable works. The action is made a microtask after mount, so hydration itself writes nothing: what an action
+ * writes (a counter, a tooltip's aria-describedby) lands just after the server HTML is adopted.
+ */
+export function use<E extends Element, O>(make: (el: E, o: O) => Action<O>, el: () => E | undefined, opts: () => O = () => undefined as O) {
+  onMount(() => {
+    let action: Action<O> | undefined
+    let live = true
+    queueMicrotask(() => {
+      const node = live && el()
+      if (node) action = make(node, untrack(opts))
+    })
+    watch(opts, (o, prev) => { if (prev !== undefined) action?.update(o) })
+    onCleanup(() => { live = false; action?.destroy() })
+  })
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@weft-js/warp-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "warp core: tokens, CSS and framework-agnostic behaviour",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "src",
+    "styles",
+    "bindings",
+    "scripts/contrast-check.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./weft": "./bindings/weft.ts",
+    "./motion": "./src/motion.ts",
+    "./charts": "./src/charts/index.ts",
+    "./canvas": "./src/canvas.ts",
+    "./stage": "./src/stage.ts",
+    "./dither": "./src/dither/index.ts",
+    "./search": "./src/search.ts",
+    "./styles/*": "./styles/*"
+  },
+  "peerDependencies": {
+    "@weft-js/core": "^0.1.1"
+  },
+  "peerDependenciesMeta": {
+    "weft": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ]
+}

package/scripts/contrast-check.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// warp contrast check: parses tokens/warp.css, resolves every sys colour for each
+// theme × expression, and checks the text/fill, UI and focus-ring pairs against
+// WCAG 2.x. Plain Node, no dependencies.
+//
+//   node scripts/contrast-check.mjs            summary + failures (exit 1 on any failure)
+//   node scripts/contrast-check.mjs --full     every pair, every combination
+//   node scripts/contrast-check.mjs --md       markdown summary (pasted into 01-foundations.md)
+//   node scripts/contrast-check.mjs --json     resolved colours + results
+//   node scripts/contrast-check.mjs path/to/other.css
+//
+// It also reads the sibling component files (tokens/warp-*.css) for every rule that re-points a
+// control's resting border (--_base / --warp-color-sweep-base) and checks the full-accent sweep
+// against that base (review 03 M9): fields and controls need sweep-vs-base >= 3:1. Surfaces
+// (cards, panels, stat tiles) may rest on the hairline (SIGNATURE, surfaces exception).
+
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const flag = (f) => args.includes(f);
+const cssPath = args.find((a) => !a.startsWith("--")) ?? resolve(here, "../tokens/warp.css");
+const css = readFileSync(cssPath, "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+
+const THEMES = ["light", "dark"];
+const EXPRESSIONS = ["quiet", "balanced", "vivid"];
+
+// ---------------------------------------------------------------- CSS parsing
+// Collect custom-property declarations with their selector and enclosing @media.
+function parseBlocks(src, media = [], out = []) {
+  let i = 0;
+  while (i < src.length) {
+    const open = src.indexOf("{", i);
+    const semi = src.indexOf(";", i);
+    if (open === -1) break;
+    if (semi !== -1 && semi < open && src.slice(i, semi).trim().startsWith("@")) { i = semi + 1; continue; }
+    const prelude = src.slice(i, open).trim();
+    let depth = 1, j = open + 1;
+    while (j < src.length && depth) { if (src[j] === "{") depth++; else if (src[j] === "}") depth--; j++; }
+    const body = src.slice(open + 1, j - 1);
+    if (prelude.startsWith("@media")) parseBlocks(body, [...media, prelude.slice(6).trim()], out);
+    else if (/^@(container|supports)/.test(prelude)) parseBlocks(body, [...media, prelude], out);
+    else if (prelude.startsWith("@layer")) parseBlocks(body, media, out);
+    else if (prelude.startsWith("@")) { /* keyframes etc. */ }
+    else {
+      for (const d of splitTop(body, ";")) {
+        const m = d.match(/^\s*(--[\w-]+)\s*:\s*([\s\S]*)$/);
+        if (m) out.push({ selector: prelude, media, prop: m[1], value: m[2].trim(), order: out.length });
+      }
+    }
+    i = j;
+  }
+  return out;
+}
+
+function splitTop(s, sep) {
+  const parts = []; let depth = 0, cur = "";
+  for (const ch of s) {
+    if (ch === "(" || ch === "[") depth++;
+    else if (ch === ")" || ch === "]") depth--;
+    if (ch === sep && depth === 0) { parts.push(cur); cur = ""; } else cur += ch;
+  }
+  if (cur.trim()) parts.push(cur);
+  return parts;
+}
+
+// Match a selector against the root element carrying env attributes.
+// Returns specificity (number) or -1. Only compound selectors on the root count.
+function matchSelector(sel, attrs) {
+  let best = -1;
+  for (const raw of splitTop(sel, ",")) {
+    const s = raw.trim();
+    if (/[\s>+~]/.test(s.replace(/\[[^\]]*\]/g, "").replace(/\([^)]*\)/g, ""))) continue;
+    const r = matchCompound(s, attrs);
+    if (r > best) best = r;
+  }
+  return best;
+}
+function matchCompound(s, attrs) {
+  let spec = 0, rest = s;
+  const take = (re) => { const m = rest.match(re); if (m) rest = rest.slice(m[0].length); return m; };
+  while (rest.length) {
+    let m;
+    if ((m = take(/^:root/))) spec += 1;
+    else if ((m = take(/^:where\(([^)]*)\)/))) { if (matchSelector(m[1], attrs) < 0) return -1; }
+    else if ((m = take(/^:not\(\[([\w-]+)(?:="([^"]*)")?\]\)/))) { if (attrTest(attrs, m[1], m[2])) return -1; spec += 1; }
+    else if ((m = take(/^\[([\w-]+)(?:="([^"]*)")?\]/))) { if (!attrTest(attrs, m[1], m[2])) return -1; spec += 1; }
+    else return -1;
+  }
+  return spec;
+}
+const attrTest = (a, k, v) => (v === undefined ? k in a : a[k] === v);
+
+// The cascade for one environment: highest specificity, then latest, wins.
+function resolveEnv(decls, attrs) {
+  const winners = new Map();
+  for (const d of decls) {
+    if (d.media.length) continue; // media inputs (viewport, pointer, reduced motion) don't touch colour
+    const spec = matchSelector(d.selector, attrs);
+    if (spec < 0) continue;
+    const prev = winners.get(d.prop);
+    if (!prev || spec > prev.spec || (spec === prev.spec && d.order > prev.order)) winners.set(d.prop, { ...d, spec });
+  }
+  return new Map([...winners].map(([k, v]) => [k, v.value]));
+}
+
+function substitute(value, vars, theme, depth = 0) {
+  if (depth > 40) throw new Error("var() cycle near " + value);
+  let out = value.replace(/var\((--[\w-]+)\s*(?:,\s*([^()]*))?\)/g, (_, name, fb) => {
+    const v = vars.get(name) ?? fb;
+    if (v === undefined) throw new Error("undefined " + name);
+    return substitute(v, vars, theme, depth + 1);
+  });
+  // light-dark(a, b) → the theme's branch (innermost first)
+  let guard = 0;
+  while (out.includes("light-dark(") && guard++ < 50) {
+    const start = out.lastIndexOf("light-dark(");
+    let depthP = 0, j = start + "light-dark".length;
+    for (; j < out.length; j++) { if (out[j] === "(") depthP++; else if (out[j] === ")" && --depthP === 0) break; }
+    const [a, b] = splitTop(out.slice(start + 11, j), ",");
+    out = out.slice(0, start) + (theme === "light" ? a : b).trim() + out.slice(j + 1);
+  }
+  return out;
+}
+
+// --------------------------------------------------------------- colour maths
+const num = (expr) => {
+  const e = expr.replace(/calc\(/g, "(").replace(/\b(min|max)\(/g, "Math.$1(").trim();
+  if (!/^(?:[\d.\s+\-*/(),e%]|Math\.min|Math\.max)+$/.test(e)) throw new Error("not numeric: " + expr);
+  if (e.endsWith("%")) return Number(e.slice(0, -1)) / 100;
+  return Function(`"use strict";return (${e});`)();
+};
+
+// color-mix(in oklab, A p%, B): mixed in OKLab, returned as OKLCH (what the browser does)
+const toLab = ({ L, C, H }) => [L, C * Math.cos((H * Math.PI) / 180), C * Math.sin((H * Math.PI) / 180)];
+const fromLab = ([L, a, b]) => ({ L, C: Math.hypot(a, b), H: ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360 });
+function parseColor(str) {
+  const s = str.trim();
+  let m;
+  if ((m = s.match(/^color-mix\(\s*in\s+oklab\s*,([\s\S]*)\)$/))) {
+    const [a, b] = splitTop(m[1], ",").map((x) => x.trim());
+    const pct = (x) => { const k = x.match(/\s([\d.]+)%$/); return k ? [x.slice(0, k.index).trim(), Number(k[1]) / 100] : [x, null]; };
+    let [ca, pa] = pct(a), [cb, pb] = pct(b);
+    if (pa === null && pb === null) pa = pb = 0.5; else if (pa === null) pa = 1 - pb; else if (pb === null) pb = 1 - pa;
+    const A = parseColor(ca), B = parseColor(cb);
+    if (A.lin || B.lin) throw new Error("color-mix needs oklch operands: " + s);
+    const la = toLab(A), lb = toLab(B), t = pa + pb;
+    const mixed = fromLab(la.map((v, i) => (v * pa + lb[i] * pb) / t));
+    return { ...mixed, alpha: 1 };
+  }
+  if ((m = s.match(/^oklch\(([\s\S]*)\)$/))) {
+    const [main, alpha] = splitTop(m[1], "/");
+    const [L, C, H] = splitTop(main.trim().replace(/\s+/g, " "), " ").filter(Boolean).map(num);
+    return { L, C, H, alpha: alpha ? num(alpha) : 1 };
+  }
+  if ((m = s.match(/^#([0-9a-f]{6})$/i))) {
+    const n = parseInt(m[1], 16);
+    return fromSrgb([(n >> 16) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255]);
+  }
+  throw new Error("unsupported colour: " + s);
+}
+
+function oklchToLinear({ L, C, H }) {
+  const h = (H * Math.PI) / 180, a = C * Math.cos(h), b = C * Math.sin(h);
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+const inGamut = (rgb) => rgb.every((c) => c >= -1e-4 && c <= 1 + 1e-4);
+// CSS Color 4 style gamut mapping: reduce chroma until it fits.
+function toLinearSrgb(c) {
+  let rgb = oklchToLinear(c);
+  if (inGamut(rgb)) return { rgb, clipped: false };
+  let lo = 0, hi = c.C;
+  for (let k = 0; k < 24; k++) { const mid = (lo + hi) / 2; inGamut(oklchToLinear({ ...c, C: mid })) ? (lo = mid) : (hi = mid); }
+  rgb = oklchToLinear({ ...c, C: lo }).map((v) => Math.min(1, Math.max(0, v)));
+  return { rgb, clipped: c.C - lo > 0.004 };
+}
+function fromSrgb(srgb) {
+  const lin = srgb.map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
+  return { lin, alpha: 1 };
+}
+const luminance = ([r, g, b]) => 0.2126 * r + 0.7152 * g + 0.0722 * b;
+const ratio = (y1, y2) => (Math.max(y1, y2) + 0.05) / (Math.min(y1, y2) + 0.05);
+const toHex = (lin) => "#" + lin.map((v) => {
+  const s = v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+  return Math.round(Math.min(1, Math.max(0, s)) * 255).toString(16).padStart(2, "0");
+}).join("");
+
+function resolveColor(name, vars, theme, warnings, combo) {
+  const raw = vars.get(name);
+  if (raw === undefined) throw new Error(`${name} not defined`);
+  const c = parseColor(substitute(raw, vars, theme));
+  if (c.lin) return { ...c, hex: toHex(c.lin) };
+  const { rgb, clipped } = toLinearSrgb(c);
+  if (clipped) warnings.add(`${combo} ${name} oklch(${c.L} ${c.C.toFixed(3)} ${c.H}) is outside sRGB; chroma mapped`);
+  return { ...c, lin: rgb, hex: toHex(rgb) };
+}
+const over = (fg, bg) => fg.lin.map((v, i) => v * fg.alpha + bg.lin[i] * (1 - fg.alpha));
+
+// ------------------------------------------------------------------ the pairs
+const T = "--warp-color-";
+const SURFACES = ["page", "surface", "surface-raised", "surface-overlay", "surface-sunken", "surface-hover"];
+const TONES = ["neutral", "accent", "positive", "caution", "critical", "info", "highlight"];
+const pairs = [];
+for (const fg of ["text", "text-subtle"]) for (const bg of SURFACES) pairs.push({ group: "Text on surfaces", fg, bg, min: 4.5 });
+// text-faint is the third ink (meta, timestamps). It may carry information, so it is held to text contrast
+// on every surface text sits on (review 03 M8); disabled ink is opacity, not faint.
+for (const bg of ["page", "surface", "surface-raised", "surface-overlay", "surface-sunken"]) pairs.push({ group: "Faint text (meta, AA)", fg: "text-faint", bg, min: 4.5 });
+pairs.push({ group: "Text on surfaces", fg: "on-inverse", bg: "surface-inverse", min: 4.5 });
+for (const bg of ["page", "surface", "surface-raised", "surface-sunken"]) pairs.push({ group: "Control boundary", fg: "border-control", bg, min: 3 });
+for (const bg of ["page", "surface", "surface-raised", "surface-overlay", "surface-sunken"]) pairs.push({ group: "Focus ring", fg: "focus", bg, min: 3 });
+for (const t of TONES) {
+  pairs.push({ group: "On-solid ink", fg: `${t}-on-solid`, bg: `${t}-solid`, min: 4.5 });
+  pairs.push({ group: "On-solid ink", fg: `${t}-on-solid`, bg: `${t}-solid-hover`, min: 4.5 });
+  for (const bg of ["page", "surface", "surface-raised", "surface-sunken", `${t}-soft`])
+    pairs.push({ group: "Tone text (on surfaces + own soft)", fg: `${t}-text`, bg, min: 4.5 });
+}
+// pressed state layer (--warp-state-press, ink at 11% over the fill): ink must still pass
+for (const t of TONES) pairs.push({ group: "Pressed state layer", fg: `${t}-text`, bg: `${t}-soft+${t}-text@0.11`, min: 4.5 });
+for (const bg of ["surface", "surface-raised"]) pairs.push({ group: "Pressed state layer", fg: "text", bg: `${bg}+text@0.11`, min: 4.5 });
+for (const bg of ["page", "surface", "surface-raised"]) pairs.push({ group: "Accent fill as UI (checkbox, switch)", fg: "accent-solid", bg, min: 3 });
+// signature: sweep stroke + resting border are the field's boundary (UI ≥ 3:1);
+// the floated label sits in the notch on the field's background (text ≥ 4.5:1)
+for (const bg of ["page", "surface", "surface-raised", "field", "field-active"]) {
+  pairs.push({ group: "Sweep stroke + resting border (UI)", fg: "sweep", bg, min: 3 });
+  pairs.push({ group: "Sweep stroke + resting border (UI)", fg: "sweep-base", bg, min: 3 });
+}
+for (const bg of ["page", "surface", "surface-raised", "field-invalid"]) pairs.push({ group: "Sweep stroke + resting border (UI)", fg: "sweep-critical", bg, min: 3 });
+// the sweep must read against what it replaces: accent stroke vs ink base, ≥ 3:1 at every stop
+// (a 1px dark-on-dark swap reads as "no change"); and vs every surface a field sits on
+pairs.push({ group: "Sweep vs resting border (visible swap)", fg: "sweep", bg: "sweep-base", min: 3 });
+pairs.push({ group: "Sweep vs resting border (visible swap)", fg: "sweep", bg: "surface-sunken", min: 3 });
+for (const fg of ["label-rest", "label-active", "critical-text"]) for (const bg of ["page", "surface", "surface-raised", "surface-sunken"])
+  pairs.push({ group: "Floating label (notch + field)", fg, bg, min: 4.5 });
+for (const fg of ["text", "label", "label-active"]) for (const bg of ["field", "field-active", "field-invalid"]) pairs.push({ group: "Floating label (notch + field)", fg, bg, min: 4.5 });
+for (const fg of ["label-rest", "critical-text"]) pairs.push({ group: "Floating label (notch + field)", fg, bg: "field", min: 4.5 });
+for (let i = 1; i <= 8; i++) for (const bg of ["surface", "page"]) pairs.push({ group: "Data-viz marks", fg: `data-${i}`, bg, min: 3 });
+
+// control hosts in the component files: sweep vs the base they actually rest on
+const CONTROLS = ["field", "checkbox", "radio", "switch", "segmented", "chip", "choice-card", "otp", "dropzone", "quantity",
+  "editable", "knob", "xy-pad", "icon-tile", "button", "select", "combobox", "command", "toggle", "toggle-group", "slider",
+  "date-field", "stepper", "tag-input", "search"];
+const BASE_PROPS = new Set(["--_base", "--warp-color-sweep-base"]);
+const controlHosts = [], advisories = [];
+if (!args.find((a) => !a.startsWith("--"))) {
+  const dir = resolve(here, "../tokens");
+  for (const f of readdirSync(dir).filter((n) => /^warp-.+\.css$/.test(n)).sort()) {
+    const src = readFileSync(resolve(dir, f), "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+    for (const d of parseBlocks(src)) {
+      if (!BASE_PROPS.has(d.prop)) continue;
+      const tok = d.value.match(/^var\(--warp-color-([\w-]+)\)$/);
+      if (!tok || !/^(border|border-strong|border-control|text-subtle|text-faint)$/.test(tok[1])) continue;  // ink, accent or transparent: fine
+      const scopes = [...d.selector.matchAll(/data-scope="([\w-]+)"/g)].map((m) => m[1]);
+      const part = d.selector.match(/data-part="(switcher|command|trigger)"/)?.[1];
+      const scope = scopes.find((x) => CONTROLS.includes(x)) || (part && `${scopes.at(-1) ?? ""} ${part}`.trim());
+      if (!scope || (!part && scopes.some((x) => /surface|card|panel|stat|tile|kanban|plan/.test(x) && !CONTROLS.includes(x)))) continue;
+      // a control *part* (shell switcher, command trigger) is advisory: it has a visible label (review 03 m13)
+      if (part) { advisories.push(`${f} ${scope} rests on ${tok[1]}; sweep-vs-base below 3:1 (advisory, labelled control)`); continue; }
+      const key = `${f} ${scope} → ${tok[1]}`;
+      if (controlHosts.some((h) => h.key === key)) continue;
+      controlHosts.push({ key, file: f, scope, base: tok[1] });
+      pairs.push({ group: "Control sweep vs its base (component files)", fg: "sweep", bg: tok[1], min: 3, where: key });
+    }
+  }
+}
+
+// --------------------------------------------------------------------- run it
+const decls = parseBlocks(css);
+const warnings = new Set();
+const results = [];
+const resolved = {};
+for (const theme of THEMES) for (const expression of EXPRESSIONS) {
+  const combo = `${theme}/${expression}`;
+  const vars = resolveEnv(decls, { "data-theme": theme, "data-expression": expression });
+  const cache = new Map();
+  const one = (n) => cache.get(n) ?? cache.set(n, resolveColor(T + n, vars, theme, warnings, combo)).get(n);
+  // "base+layer@alpha" = layer composited over base (state layers)
+  const get = (n) => {
+    const m = n.match(/^(.+)\+(.+)@([\d.]+)$/);
+    if (!m) return one(n);
+    const base = one(m[1]), layer = { ...one(m[2]), alpha: Number(m[3]) };
+    const lin = over(layer, base);
+    return { lin, hex: toHex(lin) };
+  };
+  resolved[combo] = {};
+  for (const p of pairs) {
+    const fg = get(p.fg), bg = get(p.bg);
+    const r = ratio(luminance(over(fg, bg)), luminance(bg.lin));
+    resolved[combo][p.fg] = fg.hex; resolved[combo][p.bg] = bg.hex;
+    const res = { ...p, combo, theme, expression, ratio: r, pass: r >= p.min, fgHex: fg.hex, bgHex: bg.hex };
+    if (!res.pass) res.suggest = suggest(fg, bg, p.min);
+    results.push(res);
+  }
+}
+
+// On failure: the same search the token build runs to *compute* ink —
+// walk OKLCH lightness away from the background until the ratio passes.
+function suggest(fg, bg, min) {
+  if (fg.L === undefined) return null;
+  const yb = luminance(bg.lin), dir = luminance(fg.lin) > yb ? 1 : -1;
+  for (let L = fg.L; L >= 0 && L <= 1; L += dir * 0.005) {
+    const { rgb } = toLinearSrgb({ ...fg, L });
+    if (ratio(luminance(rgb), yb) >= min) return `L ${L.toFixed(3)}`;
+  }
+  return "flip ink direction";
+}
+
+const fails = results.filter((r) => !r.pass);
+const fmt = (n) => n.toFixed(2);
+
+if (flag("--json")) {
+  console.log(JSON.stringify({ file: cssPath, resolved, results }, null, 2));
+} else if (flag("--md")) {
+  const groups = [...new Set(results.map((r) => r.group))];
+  console.log(`Checked ${results.length} pairs (${pairs.length} × ${THEMES.length * EXPRESSIONS.length} combinations): ` +
+    `**${results.length - fails.length} pass, ${fails.length} fail.**\n`);
+  console.log("| Group | Need | Pairs | Lowest | Where | light q/b/v (min) | dark q/b/v (min) |");
+  console.log("|---|---|---|---|---|---|---|");
+  for (const g of groups) {
+    const rs = results.filter((r) => r.group === g);
+    const low = rs.reduce((a, b) => (b.ratio < a.ratio ? b : a));
+    const col = (th) => EXPRESSIONS.map((e) => fmt(Math.min(...rs.filter((r) => r.theme === th && r.expression === e).map((r) => r.ratio)))).join(" / ");
+    console.log(`| ${g} | ${low.min}:1 | ${rs.length} | **${fmt(low.ratio)}** | ${low.combo} \`${low.fg}\` on \`${low.bg}\` | ${col("light")} | ${col("dark")} |`);
+  }
+  if (warnings.size) console.log(`\nGamut notes: ${warnings.size} colour(s) chroma-mapped into sRGB.`);
+} else {
+  for (const combo of Object.keys(resolved)) {
+    const rs = results.filter((r) => r.combo === combo);
+    const f = rs.filter((r) => !r.pass);
+    const low = rs.reduce((a, b) => (b.ratio / b.min < a.ratio / a.min ? b : a));
+    console.log(`${combo.padEnd(15)} ${String(rs.length - f.length).padStart(3)}/${rs.length} pass   tightest: ${low.fg} on ${low.bg} ${fmt(low.ratio)} (need ${low.min})`);
+    if (flag("--full")) for (const r of rs) console.log(`   ${r.pass ? "ok  " : "FAIL"} ${fmt(r.ratio).padStart(6)}  ${r.fg} ${r.fgHex} on ${r.bg} ${r.bgHex}`);
+  }
+  for (const r of fails) console.log(`FAIL ${r.combo} ${r.fg} on ${r.bg}: ${fmt(r.ratio)} < ${r.min}  (try ${r.suggest})${r.where ? "  [" + r.where + "]" : ""}`);
+  for (const a of new Set(advisories)) console.log("advisory " + a);
+  console.log(`control hosts re-pointing their base in component files: ${controlHosts.length ? controlHosts.map((h) => h.key).join("; ") : "none below ink"}`);
+  for (const w of warnings) console.log("note " + w);
+  console.log(`\n${results.length} checks, ${fails.length} failures.`);
+}
+process.exitCode = fails.length ? 1 : 0; // not process.exit(): lets piped stdout flush