@nexub/tokens 1.7.0 → 1.9.0

package/bin/README.md

@@ -0,0 +1,31 @@
+# nexub-migrate
+
+Moves app code onto current Nexub DS conventions. Ships with `@nexub/tokens`; no dependencies, Node >= 20.
+
+```sh
+npx nexub-migrate                 # dry run over ./src: diff + manual-review items
+npx nexub-migrate src app --write # apply fixes
+npx nexub-migrate --check         # CI: exit 1 if anything is found
+npx nexub-migrate --json          # machine-readable
+npx nexub-migrate --rules logical-classes --ignore 'src/legacy/**'
+```
+
+| Rule | Does |
+| --- | --- |
+| `legacy-tokens` | `var(--color-text-primary)` → `var(--color-on-surface)`, `--color-{leap,bookub,payub,founderub}-500` → `--color-{brand}`, `--color-brand-primary-500` → `--color-primary`. Map is built from the installed `@nexub/themes` (`base.css` + `light.css`), else an embedded snapshot. Color-mix aliases (`--color-*-border`) are reported, not rewritten. `--color-text-disabled` is a role and is never touched; declarations (`--color-x: …`) are left alone. |
+| `logical-classes` | `ml/mr` `pl/pr` `border-l/r` `rounded-l/r/tl/tr/bl/br` `text-left/right` → `ms/me` `ps/pe` `border-s/e` `rounded-s/e/ss/se/es/ee` `text-start/end`, keeping variants, `!` and `-`. `left-*`/`right-*` positions are reported only. |
+| `tw-animate` | Reports tailwindcss-animate classes (`animate-in`, `fade-in-0`, `zoom-in-95`, `slide-in-from-*` …). Use `nx-motion` / `nx-pop` / `nx-dialog` from `@nexub/themes/base`. |
+| `opacity-modifier` | Reports `bg-[var(--x)]/10` (Tailwind 3 emits nothing). `--fix` rewrites to `bg-[color-mix(in_srgb,var(--x)_10%,transparent)]`. |
+
+**Where classes are looked for.** `.html`/`.mdx`: `class=`/`className=` attributes. `.css`/`.scss`: `@apply`.
+JS/TS: string and template literals (static parts only) that are either in an explicit class context —
+`className=`, `class=`, the args of `cn/clsx/cva/cx/twMerge/twJoin(…)`, `tw\`…\`` — or where every
+whitespace-separated token looks like a Tailwind class (lowercase start, no quotes/braces). So `"ml-2 pe-4"`
+is rewritten, `"Align text-left please"` and identifiers like `ml` are not. Margin/padding values must be
+spacing-like (`2`, `0.5`, `px`, `auto`, `[…]`), so `"pr-review"` stays.
+
+Limits: no regex-literal or JSX-text awareness (a stray `'` can hide the rest of that line from the class
+pass); a single-token string such as a TS union member `'text-left'` is treated as a class. Docs that
+mention legacy token names in prose get rewritten too — `--ignore` them.
+
+Skips `node_modules`, `dist`, `build`, `.next`, `out`, `coverage` and files over 1 MB.

package/bin/nexub-migrate.mjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+// nexub-migrate — move app code onto current Nexub DS conventions.
+// Dependency-free (node: built-ins only), Node >= 20. See ./README.md.
+import { readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+export const RULES = ['legacy-tokens', 'logical-classes', 'tw-animate', 'opacity-modifier'];
+const EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.scss', '.html', '.mdx']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.next', 'out', 'coverage']);
+const MAX_BYTES = 1024 * 1024;
+
+// ─── legacy-tokens: alias map ────────────────────────────────────────────────
+const NEVER = new Set(['--color-text-disabled']); // the disabled-state role, not a legacy alias
+const BRAND = {
+  '--color-leap-500': '--color-leap',
+  '--color-bookub-500': '--color-bookub',
+  '--color-payub-500': '--color-payub',
+  '--color-founderub-500': '--color-founderub',
+  '--color-brand-primary-500': '--color-primary',
+};
+// Chains that end here are palette/scale tokens, not roles: leave them alone.
+const NOT_ROLE = /^--color-(palette|accent|brand)-/;
+
+/** Parse theme CSS (base.css, light.css …) into { aliases: {legacy: role}, mix: {legacy: value} }. */
+export function buildAliasMap(cssTexts) {
+  const decl = new Map();
+  for (const css of cssTexts) {
+    for (const m of css.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/(--color-[\w-]+)\s*:\s*([^;]+);/g)) decl.set(m[1], m[2].trim());
+  }
+  const resolve = (name, seen) => {
+    if (BRAND[name]) return { to: BRAND[name] };
+    const v = decl.get(name);
+    if (v === undefined) return NOT_ROLE.test(name) ? null : { to: name };
+    if (seen.has(name)) return null; // cycle
+    seen.add(name);
+    const ref = /^var\((--color-[\w-]+)\)$/.exec(v);
+    if (ref) return resolve(ref[1], seen);
+    if (v.startsWith('color-mix(')) return { mix: v };
+    return null; // literal value: not an alias
+  };
+  const aliases = { ...BRAND };
+  const mix = {};
+  for (const name of decl.keys()) {
+    if (NEVER.has(name)) continue;
+    const r = resolve(name, new Set());
+    if (r?.to && r.to !== name) aliases[name] = r.to;
+    else if (r?.mix) mix[name] = r.mix;
+  }
+  return { aliases, mix };
+}
+
+// Snapshot of buildAliasMap([@nexub/themes base.css, light.css]) at 1.8.0 — used when
+// @nexub/themes is not installed. bin/nexub-migrate.test.mjs fails if it drifts from source.
+export const SNAPSHOT = /* SNAPSHOT:BEGIN */ {
+  "aliases": {
+    "--color-leap-500": "--color-leap",
+    "--color-bookub-500": "--color-bookub",
+    "--color-payub-500": "--color-payub",
+    "--color-founderub-500": "--color-founderub",
+    "--color-brand-primary-500": "--color-primary",
+    "--color-success-500": "--color-success",
+    "--color-success-600": "--color-on-success-container",
+    "--color-success-bg": "--color-success-container",
+    "--color-error-500": "--color-error",
+    "--color-error-600": "--color-on-error-container",
+    "--color-error-bg": "--color-error-container",
+    "--color-danger-500": "--color-error",
+    "--color-danger-600": "--color-on-error-container",
+    "--color-danger-bg": "--color-error-container",
+    "--color-warning-500": "--color-warning",
+    "--color-warning-600": "--color-on-warning-container",
+    "--color-warning-bg": "--color-warning-container",
+    "--color-info-500": "--color-info",
+    "--color-info-600": "--color-on-info-container",
+    "--color-info-bg": "--color-info-container",
+    "--color-border-input": "--color-outline",
+    "--color-text-placeholder": "--color-on-surface-muted",
+    "--color-text-info": "--color-on-info-container",
+    "--color-text-success": "--color-on-success-container",
+    "--color-text-warning": "--color-on-warning-container",
+    "--color-text-danger": "--color-on-error-container",
+    "--color-accent-500": "--color-primary",
+    "--color-bg-default": "--color-surface",
+    "--color-bg-subtle": "--color-surface-container-low",
+    "--color-bg-muted": "--color-surface-container-high",
+    "--color-bg-raised": "--color-surface-elevated",
+    "--color-bg-inverse": "--color-inverse-surface",
+    "--color-text-primary": "--color-on-surface",
+    "--color-text-secondary": "--color-on-surface-variant",
+    "--color-text-muted": "--color-on-surface-muted",
+    "--color-text-subtle": "--color-outline",
+    "--color-text-inverse": "--color-inverse-on-surface",
+    "--color-text-link": "--color-primary",
+    "--color-border-default": "--color-outline-variant",
+    "--color-border-subtle": "--color-surface-container-high",
+    "--color-border-strong": "--color-outline",
+    "--color-border-inverse": "--color-inverse-on-surface",
+    "--color-ring-default": "--color-primary",
+    "--color-ring-offset": "--color-surface",
+    "--color-surface-muted": "--color-surface-container-low",
+    "--color-surface-raised": "--color-surface-elevated",
+    "--color-surface-sunken": "--color-surface-container-high",
+    "--color-surface-inverse": "--color-inverse-surface",
+    "--color-semantic-success-default": "--color-success",
+    "--color-semantic-success-strong": "--color-on-success-container",
+    "--color-semantic-success-bg": "--color-success-container",
+    "--color-semantic-error-default": "--color-error",
+    "--color-semantic-error-strong": "--color-on-error-container",
+    "--color-semantic-error-bg": "--color-error-container",
+    "--color-semantic-warning-default": "--color-warning",
+    "--color-semantic-warning-strong": "--color-on-warning-container",
+    "--color-semantic-warning-bg": "--color-warning-container",
+    "--color-semantic-info-default": "--color-info",
+    "--color-semantic-info-strong": "--color-on-info-container",
+    "--color-semantic-info-bg": "--color-info-container"
+  },
+  "mix": {
+    "--color-success-border": "color-mix(in srgb, var(--color-success) 35%, transparent)",
+    "--color-error-border": "color-mix(in srgb, var(--color-error) 35%, transparent)",
+    "--color-danger-border": "color-mix(in srgb, var(--color-error) 35%, transparent)",
+    "--color-warning-border": "color-mix(in srgb, var(--color-warning) 35%, transparent)",
+    "--color-info-border": "color-mix(in srgb, var(--color-info) 35%, transparent)",
+    "--color-semantic-success-border": "color-mix(in srgb, var(--color-success) 35%, transparent)",
+    "--color-semantic-error-border": "color-mix(in srgb, var(--color-error) 35%, transparent)",
+    "--color-semantic-warning-border": "color-mix(in srgb, var(--color-warning) 35%, transparent)",
+    "--color-semantic-info-border": "color-mix(in srgb, var(--color-info) 35%, transparent)"
+  }
+} /* SNAPSHOT:END */;
+
+export function loadAliasMap(cwd = process.cwd()) {
+  for (const from of [path.join(cwd, 'package.json'), import.meta.url]) {
+    try {
+      const req = createRequire(from);
+      const css = ['base', 'light'].map((f) => readFileSync(req.resolve(`@nexub/themes/${f}`), 'utf8'));
+      return { ...buildAliasMap(css), source: '@nexub/themes' };
+    } catch { /* not resolvable from here */ }
+  }
+  return { ...SNAPSHOT, source: 'snapshot' };
+}
+
+// ─── class-string contexts ───────────────────────────────────────────────────
+/**
+ * Find string-literal bodies in JS/TS source. Handles '…', "…", `…${…}…` (static chunks
+ * only), // and /* comments. ponytail: no regex-literal or JSX-text awareness — a stray
+ * quote (/'/ or <p>Don't</p>) can mis-pair until the end of that line.
+ */
+export function scanStrings(src) {
+  const out = [];
+  const stack = []; // brace depth at each open `${`
+  let depth = 0;
+  let i = 0;
+  const n = src.length;
+  const readTemplate = (j, tplStart, openLeft) => {
+    const start = j;
+    while (j < n && src[j] !== '`' && !(src[j] === '$' && src[j + 1] === '{')) j += src[j] === '\\' ? 2 : 1;
+    const openRight = src[j] === '$';
+    out.push({ start, end: j, quoteAt: tplStart, openLeft, openRight });
+    if (openRight) { stack.push({ depth, tplStart }); return j + 2; }
+    return j + 1;
+  };
+  while (i < n) {
+    const c = src[i];
+    if (c === '/' && src[i + 1] === '/') { i = src.indexOf('\n', i); if (i < 0) break; continue; }
+    if (c === '/' && src[i + 1] === '*') { i = src.indexOf('*/', i + 2); if (i < 0) break; i += 2; continue; }
+    if (c === "'" || c === '"') {
+      let j = i + 1;
+      while (j < n && src[j] !== c && src[j] !== '\n') j += src[j] === '\\' ? 2 : 1;
+      out.push({ start: i + 1, end: Math.min(j, n), quoteAt: i, openLeft: false, openRight: false });
+      i = j + 1;
+      continue;
+    }
+    if (c === '`') { i = readTemplate(i + 1, i, false); continue; }
+    if (c === '{') depth++;
+    else if (c === '}') {
+      if (stack.length && stack.at(-1).depth === depth) { i = readTemplate(i + 1, stack.pop().tplStart, true); continue; }
+      depth--;
+    }
+    i++;
+  }
+  return out;
+}
+
+// Explicit class contexts: className= / class= attributes, cn/clsx/cva/cx/twMerge/twJoin(…) args, tw`…`.
+const CLASS_CONTEXT = /(?:\bclass(?:Name)?\s*=\s*\{?\s*|\b(?:cn|clsx|cva|cx|twMerge|twJoin)\s*\((?:[^()]*?,)?\s*|\btw)$/;
+// Otherwise a plain string counts only when every token looks like a Tailwind class:
+// starts lowercase/digit/[/@/!/-, and has no quotes, braces or '<'. "Align text-left" is not one.
+const TW_TOKEN = /^[!-]?[a-z0-9@[][^\s"'`<{}]*$/;
+const looksLikeClassList = (text) => {
+  const t = text.trim();
+  return t !== '' && t.split(/\s+/).every((tok) => TW_TOKEN.test(tok));
+};
+
+export function classSegments(src, ext) {
+  if (ext === '.css' || ext === '.scss') {
+    return [...src.matchAll(/@apply\s+([^;}]+)/dg)].map((m) => ({ start: m.indices[1][0], end: m.indices[1][1] }));
+  }
+  if (ext === '.html' || ext === '.mdx') {
+    return [...src.matchAll(/\bclass(?:Name)?\s*=\s*(["'])([^"']*)\1/dg)].map((m) => ({ start: m.indices[2][0], end: m.indices[2][1] }));
+  }
+  return scanStrings(src).filter((s) => {
+    if (CLASS_CONTEXT.test(src.slice(Math.max(0, s.quoteAt - 120), s.quoteAt))) return true;
+    return looksLikeClassList(src.slice(s.start, s.end));
+  });
+}
+
+// ─── class-token rules ───────────────────────────────────────────────────────
+const SIDE = { l: 's', r: 'e' };
+const CORNER = { l: 's', r: 'e', tl: 'ss', tr: 'se', bl: 'es', br: 'ee' };
+const LOGICAL = [
+  // value-constrained so prose like "pr-review" never matches
+  [/^([mp])([lr])-(\d+(?:\.\d+)?|px|auto|\[[^\]]+\])$/, (_, a, s, v) => `${a}${SIDE[s]}-${v}`],
+  [/^border-([lr])(-.+)?$/, (_, s, r = '') => `border-${SIDE[s]}${r}`],
+  [/^rounded-(tl|tr|bl|br|l|r)(-.+)?$/, (_, c, r = '') => `rounded-${CORNER[c]}${r}`],
+  [/^text-(left|right)$/, (_, s) => `text-${s === 'left' ? 'start' : 'end'}`],
+];
+const POSITION = /^(left|right)-/;
+const TW_ANIMATE = /^(animate-(in|out)|(fade|zoom|spin)-(in|out)(-.+)?|slide-(in-from|out-to)-.+)$/;
+const OPACITY = /^([\w-]+)-\[var\((--[\w-]+)\)\]\/(\d+)$/;
+
+/** Split `md:hover:!-ml-2` into { prefix: 'md:hover:', imp: '!', neg: '-', base: 'ml-2' }. */
+function splitToken(tok) {
+  let depth = 0;
+  let cut = 0;
+  for (let i = 0; i < tok.length; i++) {
+    if (tok[i] === '[') depth++;
+    else if (tok[i] === ']') depth--;
+    else if (tok[i] === ':' && depth === 0) cut = i + 1;
+  }
+  let rest = tok.slice(cut);
+  const imp = rest.startsWith('!') ? '!' : '';
+  rest = rest.slice(imp.length);
+  const neg = rest.startsWith('-') ? '-' : '';
+  return { prefix: tok.slice(0, cut), imp, neg, base: rest.slice(neg.length) };
+}
+
+function rewriteClassText(text, seg, offset, rules, fix, report) {
+  return text.replace(/\S+/g, (tok, off) => {
+    if ((seg.openLeft && off === 0) || (seg.openRight && off + tok.length === text.length)) return tok; // glued to ${…}
+    const at = offset + off;
+    const { prefix, imp, neg, base } = splitToken(tok);
+    let next = base;
+    if (rules.has('logical-classes')) {
+      for (const [re, fn] of LOGICAL) if (re.test(next)) { next = next.replace(re, fn); break; }
+      if (POSITION.test(base)) report(at, 'logical-classes', `"${tok}" is a physical position; review for start-/end- (not auto-fixed)`);
+    }
+    if (rules.has('tw-animate') && TW_ANIMATE.test(base)) {
+      report(at, 'tw-animate', `"${tok}" is a tailwindcss-animate class; use nx-motion / nx-pop / nx-dialog from @nexub/themes/base`);
+    }
+    if (rules.has('opacity-modifier')) {
+      const m = OPACITY.exec(next);
+      if (m) {
+        const mixed = `${m[1]}-[color-mix(in_srgb,var(${m[2]})_${m[3]}%,transparent)]`;
+        if (fix) next = mixed;
+        else report(at, 'opacity-modifier', `"${tok}": Tailwind 3 emits nothing for /${m[3]} on a var(); use ${prefix}${imp}${neg}${mixed} (or --fix)`);
+      }
+    }
+    return next === base ? tok : prefix + imp + neg + next;
+  });
+}
+
+// ─── per-file migration ──────────────────────────────────────────────────────
+/**
+ * Migrate one file's text. Returns { output, manual: [{ line, rule, message }] }.
+ * opts: { ext, rules: Set, fix: boolean, aliasMap: { aliases, mix } }
+ */
+export function migrateSource(src, { ext, rules = new Set(RULES), fix = false, aliasMap = SNAPSHOT }) {
+  const items = [];
+  let text = src;
+  if (['logical-classes', 'tw-animate', 'opacity-modifier'].some((r) => rules.has(r))) {
+    let out = '';
+    let last = 0;
+    for (const seg of classSegments(src, ext)) {
+      out += src.slice(last, seg.start) + rewriteClassText(src.slice(seg.start, seg.end), seg, seg.start, rules, fix,
+        (at, rule, message) => items.push({ at, rule, message }));
+      last = seg.end;
+    }
+    text = out + src.slice(last);
+  }
+  if (rules.has('legacy-tokens')) {
+    // Skip definitions (`--color-x:` / `'--color-x':`) — those override the alias on purpose.
+    text = text.replace(/(?<![\w-])--color-[a-z0-9-]+(?![\w-])(?!['"]?\s*:)/g, (name, at) => {
+      if (aliasMap.aliases[name]) return aliasMap.aliases[name];
+      if (aliasMap.mix[name]) items.push({ at, rule: 'legacy-tokens', message: `${name} is a color-mix alias (${aliasMap.mix[name]}); rewrite by hand` });
+      return name;
+    });
+  }
+  // Rewrites never add or remove newlines, so offsets in src and text share line numbers.
+  const lineOf = (at) => src.slice(0, at).split('\n').length;
+  const manual = items.map(({ at, rule, message }) => ({ line: lineOf(at), rule, message })).sort((a, b) => a.line - b.line);
+  return { output: text, manual };
+}
+
+// ─── file walking ────────────────────────────────────────────────────────────
+export function globToRegExp(glob) {
+  const re = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*\/?|\*|\?/g, (m) => ({ '*': '[^/]*', '?': '[^/]', '**': '.*' })[m] ?? '(?:.*/)?');
+  return new RegExp(`^${re}$`);
+}
+
+export function collectFiles(paths, { cwd = process.cwd(), ignore = [] } = {}) {
+  const res = ignore.map(globToRegExp);
+  const ignored = (rel) => res.some((re, i) => re.test(rel) || (!ignore[i].includes('/') && re.test(path.posix.basename(rel))));
+  const files = [];
+  const walk = (abs) => {
+    const rel = path.relative(cwd, abs).split(path.sep).join('/');
+    if (rel && ignored(rel)) return;
+    let st;
+    try { st = statSync(abs); } catch { return; }
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.has(path.basename(abs)) && rel !== '') return;
+      for (const e of readdirSync(abs).sort()) walk(path.join(abs, e));
+    } else if (st.isFile() && EXTS.has(path.extname(abs)) && st.size <= MAX_BYTES) {
+      files.push(abs);
+    }
+  };
+  for (const p of paths) walk(path.resolve(cwd, p));
+  return files;
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+export const USAGE = `Usage: nexub-migrate [paths…] [options]
+
+Move app code onto current Nexub DS conventions. Paths default to ./src.
+Dry run by default: prints what would change and what needs a human.
+
+Options:
+  --write            apply fixes in place
+  --check            exit 1 if anything fixable or reportable is found (CI)
+  --json             print machine-readable results
+  --fix              also rewrite opacity-modifier hits (preview, or apply with --write)
+  --rules <a,b>      run only these rules (default: all)
+  --ignore <glob>    skip paths matching glob (repeatable; supports * and **)
+  -h, --help         show this help
+
+Rules:
+  legacy-tokens      var(--color-text-primary) -> var(--color-on-surface), brand -500 -> role;
+                     color-mix aliases (e.g. --color-semantic-success-border) reported
+  logical-classes    ml/mr, pl/pr, border-l/r, rounded-l/r/tl/tr/bl/br, text-left/right
+                     -> ms/me, ps/pe, border-s/e, rounded-s/e/ss/se/es/ee, text-start/end;
+                     left-/right- positions reported
+  tw-animate         report tailwindcss-animate enter/exit classes (use nx-motion/nx-pop/nx-dialog)
+  opacity-modifier   report [var(--x)]/NN (emits nothing in Tailwind 3); --fix rewrites to color-mix
+
+Ignored: node_modules, dist, build, .next, out, coverage, files over 1 MB.
+Exit codes: 0 ok, 1 --check found something, 2 usage error.`;
+
+export function run(argv, { cwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s) } = {}) {
+  let args;
+  try {
+    args = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        write: { type: 'boolean' }, check: { type: 'boolean' }, json: { type: 'boolean' }, fix: { type: 'boolean' },
+        rules: { type: 'string' }, ignore: { type: 'string', multiple: true }, help: { type: 'boolean', short: 'h' },
+      },
+    });
+  } catch (e) {
+    stderr(`${e.message}\n\n${USAGE}\n`);
+    return 2;
+  }
+  const { values: o, positionals } = args;
+  if (o.help) { stdout(`${USAGE}\n`); return 0; }
+  const rules = new Set(o.rules ? o.rules.split(',').map((r) => r.trim()).filter(Boolean) : RULES);
+  const unknown = [...rules].filter((r) => !RULES.includes(r));
+  if (unknown.length) { stderr(`Unknown rule(s): ${unknown.join(', ')}. Known: ${RULES.join(', ')}\n`); return 2; }
+
+  const aliasMap = rules.has('legacy-tokens') ? loadAliasMap(cwd) : SNAPSHOT;
+  const results = [];
+  for (const abs of collectFiles(positionals.length ? positionals : ['src'], { cwd, ignore: o.ignore ?? [] })) {
+    const src = readFileSync(abs, 'utf8');
+    const { output, manual } = migrateSource(src, { ext: path.extname(abs), rules, fix: !!o.fix, aliasMap });
+    const a = src.split('\n');
+    const b = output.split('\n');
+    const changes = a.flatMap((line, i) => (line === b[i] ? [] : [{ line: i + 1, before: line, after: b[i] }]));
+    if (!changes.length && !manual.length) continue;
+    if (o.write && changes.length) writeFileSync(abs, output);
+    results.push({ file: path.relative(cwd, abs).split(path.sep).join('/'), changes, manual });
+  }
+  const totals = {
+    files: results.length,
+    changes: results.reduce((n, r) => n + r.changes.length, 0),
+    manual: results.reduce((n, r) => n + r.manual.length, 0),
+  };
+
+  if (o.json) {
+    stdout(`${JSON.stringify({ written: !!o.write, aliasSource: aliasMap.source ?? 'snapshot', results, totals }, null, 2)}\n`);
+  } else {
+    for (const r of results) {
+      stdout(`--- ${r.file}\n+++ ${r.file}\n`);
+      for (const c of r.changes) stdout(`@@ ${c.line} @@\n-${c.before}\n+${c.after}\n`);
+      for (const m of r.manual) stdout(`! ${r.file}:${m.line} [${m.rule}] ${m.message}\n`);
+    }
+    const verb = o.write ? 'changed' : 'to change';
+    stdout(`\n${totals.changes} line(s) ${verb} in ${results.filter((r) => r.changes.length).length} file(s); ${totals.manual} item(s) need manual review.`);
+    stdout(!o.write && totals.changes ? ' Run with --write to apply.\n' : '\n');
+  }
+  return o.check && (totals.changes || totals.manual) ? 1 : 0;
+}
+
+const isMain = (() => {
+  try { return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch { return false; }
+})();
+if (isMain) process.exitCode = run(process.argv.slice(2));

package/dist/js/roles.d.ts

@@ -0,0 +1,17 @@
+/** Tonal palette from a hex colour: its own hue and chroma (brand fidelity).
+ * @param {string} hex */
+export function tonalPalette(hex: string): TonalPalette;
+/** @typedef {[palette: string, light: number, dark: number, highLight: number, highDark: number]} RoleTones */
+/** @typedef {'standard' | 'medium' | 'high'} ContrastLevel */
+export const TONES: number[];
+export function toneHex(pal: TonalPalette, tone: number): string;
+export function accent(pal: string): Record<string, RoleTones>;
+/** @type {Record<string, RoleTones>} */
+export const ROLES: Record<string, RoleTones>;
+export function tertiary(product: string): Record<string, RoleTones>;
+/** @type {ContrastLevel[]} */
+export const LEVELS: ContrastLevel[];
+export function tonesAt([pal, l, d, hl, hd]: RoleTones, level: ContrastLevel): [string, number, number];
+export type RoleTones = [palette: string, light: number, dark: number, highLight: number, highDark: number];
+export type ContrastLevel = "standard" | "medium" | "high";
+import { TonalPalette } from '@material/material-color-utilities';

package/dist/js/roles.js

@@ -0,0 +1,77 @@
+// @ts-check
+// Role → tone table and HCT palette generation, shared by the build
+// (scripts/generate.mjs → dist/css/roles.css) and the runtime seed theming
+// entry (@nexub/tokens/seed). Plain JS so the build script can import it
+// before tsc runs; tsc (allowJs) emits it and its .d.ts into dist/js.
+//
+// @material/material-color-utilities is pinned to 0.3.0: 0.4.0 ships broken ESM.
+import { Hct, TonalPalette, argbFromHex, hexFromArgb } from '@material/material-color-utilities';
+/** @typedef {[palette: string, light: number, dark: number, highLight: number, highDark: number]} RoleTones */
+/** @typedef {'standard' | 'medium' | 'high'} ContrastLevel */
+// 5/15/25/35/45/65/76/85 exist for data-contrast="medium" (halfway tones).
+export const TONES = [0, 4, 5, 6, 10, 12, 15, 17, 20, 22, 24, 25, 30, 35, 40, 45, 50, 60, 65, 70, 72, 76, 80, 85, 87, 90, 92, 94, 95, 96, 98, 99, 100];
+/** Tonal palette from a hex colour: its own hue and chroma (brand fidelity).
+ * @param {string} hex */
+export function tonalPalette(hex) {
+    const hct = Hct.fromInt(argbFromHex(hex));
+    return TonalPalette.fromHueAndChroma(hct.hue, hct.chroma);
+}
+/** @param {TonalPalette} pal @param {number} tone */
+export const toneHex = (pal, tone) => hexFromArgb(pal.tone(tone));
+// role → [palette, light tone, dark tone, light tone (high), dark tone (high)]
+// High contrast pushes accents/outlines/secondary text further from surfaces.
+/** @param {string} pal @returns {Record<string, RoleTones>} */
+export const accent = (pal) => ({
+    [pal]: [pal, 40, 80, 30, 90],
+    [`on-${pal}`]: [pal, 100, 20, 100, 10],
+    [`${pal}-container`]: [pal, 90, 30, 90, 30],
+    [`on-${pal}-container`]: [pal, 10, 90, 0, 100],
+});
+/** @type {Record<string, RoleTones>} */
+export const ROLES = {
+    ...accent('primary'),
+    ...accent('secondary'),
+    ...accent('error'),
+    ...accent('success'),
+    ...accent('warning'),
+    ...accent('info'),
+    // Product accents, always available (badges, dots, tags), whatever the
+    // data-product. Tertiary is the *current* product; these name each one.
+    ...accent('leap'),
+    ...accent('bookub'),
+    ...accent('payub'),
+    ...accent('founderub'),
+    surface: ['neutral', 98, 6, 98, 6],
+    'surface-dim': ['neutral', 87, 6, 87, 6],
+    'surface-bright': ['neutral', 98, 24, 98, 24],
+    'surface-container-lowest': ['neutral', 100, 4, 100, 4],
+    'surface-container-low': ['neutral', 96, 10, 96, 10],
+    'surface-container': ['neutral', 94, 12, 94, 12],
+    'surface-container-high': ['neutral', 92, 17, 92, 17],
+    'surface-container-highest': ['neutral', 90, 22, 90, 22],
+    // Not an M3 role: floating layers (menus, popovers, dialogs). White in light,
+    // lighter than the page in dark (Apple's elevated background).
+    'surface-elevated': ['neutral', 100, 17, 100, 17],
+    'on-surface': ['neutral', 10, 90, 0, 100],
+    'on-surface-variant': ['neutral-variant', 30, 80, 20, 90],
+    // Not an M3 role: tertiary text that still clears 4.5:1 on every container.
+    'on-surface-muted': ['neutral-variant', 40, 72, 30, 80],
+    outline: ['neutral-variant', 50, 60, 30, 80],
+    'outline-variant': ['neutral-variant', 80, 30, 50, 60],
+    'inverse-surface': ['neutral', 20, 90, 20, 90],
+    'inverse-on-surface': ['neutral', 95, 20, 100, 0],
+    'inverse-primary': ['primary', 80, 40, 80, 40],
+    // Behind modals and under image captions; black in both themes.
+    scrim: ['neutral', 0, 0, 0, 0],
+};
+// Product brands remap the tertiary family.
+/** @param {string} product @returns {Record<string, RoleTones>} */
+export const tertiary = (product) => Object.fromEntries(Object.entries(accent('tertiary')).map(([role, [, ...tones]]) => [role, [product, ...tones]]));
+// Contrast levels. Medium sits halfway between standard and high, snapped
+// to the nearest generated tone.
+/** @type {ContrastLevel[]} */
+export const LEVELS = ['standard', 'medium', 'high'];
+/** @param {number} t */
+const snap = (t) => TONES.reduce((a, b) => (Math.abs(b - t) < Math.abs(a - t) ? b : a));
+/** @param {RoleTones} entry @param {ContrastLevel} level @returns {[string, number, number]} */
+export const tonesAt = ([pal, l, d, hl, hd], level) => level === 'high' ? [pal, hl, hd] : level === 'medium' ? [pal, snap((l + hl) / 2), snap((d + hd) / 2)] : [pal, l, d];

package/dist/js/seed.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CSS custom properties for the accent family derived from `seed`, as
+ * `light-dark(<light>, <dark>)` values (same shape as dist/css/roles.css).
+ * target 'primary': primary, on-primary, primary-container, on-primary-container, inverse-primary.
+ * target 'tertiary': tertiary, on-tertiary, tertiary-container, on-tertiary-container.
+ * @param {string} seed Hex colour, `#rgb` or `#rrggbb`.
+ * @param {SeedThemeOptions} [options]
+ * @returns {Record<string, string>} e.g. `createSeedTheme('#4099f1')['--color-primary'] === 'light-dark(#0061a6, #a0c9ff)'`
+ */
+export function createSeedTheme(seed: string, { contrast, target }?: SeedThemeOptions): Record<string, string>;
+/**
+ * The same theme as a CSS rule, for SSR / static stylesheets (no flash, no JS):
+ * `:root {\n  --color-primary: light-dark(…);\n  …\n}\n`.
+ * @param {string} seed
+ * @param {SeedThemeOptions & { selector?: string }} [options] `selector` defaults to ':root'.
+ * @returns {string}
+ */
+export function createSeedThemeCss(seed: string, { selector, ...options }?: SeedThemeOptions & {
+    selector?: string;
+}): string;
+export type SeedThemeOptions = {
+    /**
+     * Contrast level (matches `data-contrast`). Default 'standard'.
+     */
+    contrast?: "standard" | "medium" | "high" | undefined;
+    /**
+     * Accent family to seed. 'tertiary' is the product brand. Default 'primary'.
+     */
+    target?: "primary" | "tertiary" | undefined;
+};

package/dist/js/seed.js

@@ -0,0 +1,51 @@
+// @ts-check
+// @nexub/tokens/seed — runtime brand theming from one seed colour (white-label).
+// Uses the same HCT palette generation and role → tone table as the build
+// (src/roles.js), so a seeded accent family meets the same WCAG pairs as the
+// built-in ones: roles are HCT tones, and tone gaps fix contrast for any hue.
+import { LEVELS, ROLES, accent, tonalPalette, toneHex, tonesAt } from './roles.js';
+/**
+ * @typedef {object} SeedThemeOptions
+ * @property {'standard' | 'medium' | 'high'} [contrast] Contrast level (matches `data-contrast`). Default 'standard'.
+ * @property {'primary' | 'tertiary'} [target] Accent family to seed. 'tertiary' is the product brand. Default 'primary'.
+ */
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+/**
+ * CSS custom properties for the accent family derived from `seed`, as
+ * `light-dark(<light>, <dark>)` values (same shape as dist/css/roles.css).
+ * target 'primary': primary, on-primary, primary-container, on-primary-container, inverse-primary.
+ * target 'tertiary': tertiary, on-tertiary, tertiary-container, on-tertiary-container.
+ * @param {string} seed Hex colour, `#rgb` or `#rrggbb`.
+ * @param {SeedThemeOptions} [options]
+ * @returns {Record<string, string>} e.g. `createSeedTheme('#4099f1')['--color-primary'] === 'light-dark(#0061a6, #a0c9ff)'`
+ */
+export function createSeedTheme(seed, { contrast = 'standard', target = 'primary' } = {}) {
+    if (typeof seed !== 'string' || !HEX.test(seed))
+        throw new TypeError(`@nexub/tokens/seed: seed must be a hex colour (#rgb or #rrggbb), got ${JSON.stringify(seed)}`);
+    if (!LEVELS.includes(contrast))
+        throw new TypeError(`@nexub/tokens/seed: contrast must be one of ${LEVELS.join(', ')}, got ${JSON.stringify(contrast)}`);
+    if (target !== 'primary' && target !== 'tertiary')
+        throw new TypeError(`@nexub/tokens/seed: target must be 'primary' or 'tertiary', got ${JSON.stringify(target)}`);
+    const pal = tonalPalette(seed);
+    const roles = { ...accent(target) };
+    if (target === 'primary' && ROLES['inverse-primary'])
+        roles['inverse-primary'] = ROLES['inverse-primary'];
+    /** @type {Record<string, string>} */
+    const vars = {};
+    for (const [role, entry] of Object.entries(roles)) {
+        const [, l, d] = tonesAt(entry, contrast);
+        vars[`--color-${role}`] = `light-dark(${toneHex(pal, l)}, ${toneHex(pal, d)})`;
+    }
+    return vars;
+}
+/**
+ * The same theme as a CSS rule, for SSR / static stylesheets (no flash, no JS):
+ * `:root {\n  --color-primary: light-dark(…);\n  …\n}\n`.
+ * @param {string} seed
+ * @param {SeedThemeOptions & { selector?: string }} [options] `selector` defaults to ':root'.
+ * @returns {string}
+ */
+export function createSeedThemeCss(seed, { selector = ':root', ...options } = {}) {
+    const decls = Object.entries(createSeedTheme(seed, options)).map(([k, v]) => `  ${k}: ${v};`);
+    return `${selector} {\n${decls.join('\n')}\n}\n`;
+}