@godxjp/ui 28.13.0 → 29.0.0

package/docs/themes/index.ts

@@ -0,0 +1,200 @@
+/**
+ * The theme REGISTRY for `/showcase/theme-lab` — the one file a new theme touches.
+ *
+ * gh#882 asks that adding a theme mean "one new CSS file and one new row, never a page edit".
+ * That is what this module is: the page imports `THEMES` and `SEEDS` and knows nothing else about
+ * either. A new theme is
+ *
+ *   1. `docs/themes/<id>.css`, containing NOTHING but `--custom-property` declarations under
+ *      `[data-theme-style="<id>"]`, and
+ *   2. one row below (plus the side-effect import that puts the file in the bundle).
+ *
+ * WHY THE IMPORT IS WRITTEN OUT rather than globbed. `import.meta.glob` would make the row the
+ * only edit, but it is a Vite-only form typed by `vite/client`, and `tsconfig.json` pins
+ * `"types": ["node"]` — `tsconfig.docs.json` inherits that, so a glob here is a TS2339 that
+ * `typecheck:docs` catches and no amount of local success hides. Two lines in one non-page file is
+ * the honest cost of staying inside the type system the rest of `docs/**` is checked by.
+ *
+ * ── The constraint that makes this a MEASUREMENT (gh#882, and it is the whole exercise) ────────
+ * A theme file may declare custom properties and nothing else: no `backdrop-filter:`, no
+ * `background:`, no selector into a `.ui-*` class, no `className` or inline `style` on the page.
+ * Where a look cannot be expressed that way, the RESULT is the gap — written down in
+ * `docs/showcase/theme-lab.tsx`'s "what the token API could not reach" table — never worked around.
+ *
+ * ── Seeds ─────────────────────────────────────────────────────────────────────────────────────
+ * The second half of gh#882: nothing proved the glass theme was not tuned to violet. Every seed
+ * below goes through `tenantTheme(hex)` (`@godxjp/ui/app`), which returns the contrast-safe
+ * `--primary` / `--primary-foreground` pair plus the hover and pressed steps as real triplets, and
+ * the theme files derive their own decoration FROM `--primary` with CSS relative colour so the
+ * whole page follows the seed rather than the seed following the theme.
+ */
+import "./glassmorphism.css";
+import "./flat.css";
+
+export type ThemeRow = {
+  /**
+   * The `data-theme-style` value, or `null` for the library's own default — the control. `null`
+   * is a row, not a special case: the page writes the attribute either way and an attribute that
+   * matches no selector is exactly "no theme".
+   */
+  id: string | null;
+  /** Message key for the switch label. */
+  nameKey: string;
+  /** Message key for the one-line note under the switch. */
+  noteKey: string;
+  /**
+   * The LIGHTEST surface brand INK lands on in this theme, as hex — handed to `tenantTheme` as
+   * `options.surface`. `null` means the library's own light default (`--accent` #ebe9e5).
+   *
+   * `tenantTheme` walks the three brand inks AWAY from a surface until they clear 4.5:1, and it
+   * has to be told which surface, because it emits them as literals in `style` — which outrank a
+   * theme's own `--text-link` however carefully the theme declared it. Omitting this on a DARK
+   * theme is not a missing nicety, it is the ink walked the WRONG WAY: measured on glass/citron,
+   * `tenantTheme(#FFD400)` alone emitted `--text-link: 49.88 100% 24.4%` — rgb(124,103,0), walked
+   * dark for the light default — over a #3b382b panel, so `Button variant="link"` and a `Text`
+   * link both read **2.09:1** while the theme's own `--foreground` next to them was near-white.
+   * The library says so at `src/app/tenant-theme.ts`: "a region inside a DARK theme must pass the
+   * dark surface or its ink is walked the wrong way."
+   *
+   * WHY ONE HEX COVERS FIVE SEEDS. Every glass surface is a translucent white over
+   * `--background`, which derives its hue from the seed, so the composited panel moves per seed.
+   * Composited and measured across all five: card #312b3b..#3b382b, popover #434851..#514f43,
+   * accent #482d76..#766a2d, muted #232a39..#393523. The value below is the LIGHTEST of the
+   * twenty — glass/citron's `--accent` — because ink walked away from a dark surface goes
+   * lighter, and lighter ink on a DARKER surface only gains contrast. Clearing the worst case
+   * clears all of them.
+   *
+   * A PAIR, not one hex (gh#896): the surface above was measured while glass was reachable in ONE
+   * polarity only — the whole theme rendered permanently dark (the bug gh#896 reports), so every
+   * hex the paragraph above lists, `#766A2D` included, is a DARK-branch measurement with no light
+   * counterpart. Now that polarity is addressable, both members below are `null` until a real
+   * compositing measurement exists for EACH branch — the old single hex is not carried over into
+   * either slot, because guessing which polarity it belongs to is exactly the mistake this pair
+   * exists to prevent. `null` means the library's own default for that polarity (light `--accent`
+   * #ebe9e5; dark reads the built-in dark spine).
+   */
+  inkSurface: { light: string | null; dark: string | null };
+};
+
+export type SeedRow = {
+  /** Stable id — also the `?seed=` query value, so a measurement can address it directly. */
+  id: string;
+  /** The customer hex handed to `tenantTheme()`. */
+  hex: string;
+  /** Message key for the swatch label. */
+  nameKey: string;
+};
+
+/**
+ * The polarity axis (gh#896): the library ships light AND dark, and until this row existed the lab
+ * had no way to address the dark half of a theme × seed cell — a theme's dark branch could regress
+ * silently because nothing ever asked for it. `id` is the exact string `applyThemeAxes`
+ * (`src/app/theme-axes.ts`) resolves `data-theme` to, so it can be handed straight to
+ * `AppProvider`'s own `setTheme` — never written to `document.documentElement` by this page itself.
+ */
+export type ModeRow = {
+  /** Also the `?mode=` query value. */
+  id: "light" | "dark";
+  /** Message key for the switch label. */
+  nameKey: string;
+};
+
+/**
+ * Order is reading order in the switch. `base` leads because a control that is not first is a
+ * control nobody looks at.
+ */
+export const THEMES: readonly ThemeRow[] = [
+  {
+    id: null,
+    nameKey: "themeLab.theme.base.name",
+    noteKey: "themeLab.theme.base.note",
+    /* `null` IS ONLY CORRECT IN LIGHT, AND THE 30-CELL RUN IS WHAT SHOWED IT. I wrote "the package
+     * default IS this surface in both polarities" here and the matrix answered: every dark `base`
+     * cell read 552/562, ten failures, identical at all five seeds. `tenantTheme`'s default is
+     * `INK_SURFACE_LIGHT` (#ebe9e5) and there is no dark counterpart, so `null` in the dark slot
+     * walks the brand ink AWAY FROM A LIGHT SURFACE and lands it dark on a dark page — the same
+     * defect gh#887 found for glass, in the package's own theme, seed-independent because the
+     * surface is wrong rather than the seed.
+     *
+     * The light slot stays `null` because there the default really is right: measured, the darkest
+     * ground under brand ink is #DFE2E5 against the constant's #EBE9E5, and light `base` reads
+     * 562/562 at every seed.
+     *
+     * #3C3A34, AND THE PAINTED-PIXEL MEASUREMENT PICKED THE WRONG ONE (gh#903). Sampling the
+     * actual pixel under each brand-ink element gave #3C3619 and I took it, on the reasoning that a
+     * painted pixel beats a token composite. It does — but I sampled every element AT REST, and the
+     * ground a hovered MegaMenu trigger sits on is `--accent`, which is #3C3A34 and LIGHTER. For a
+     * dark theme the hardest ground is the LIGHTEST one, so the darker sample sent the ink the
+     * wrong way by a hair: it walked to L 74.9% instead of 76.4%, and the hovered label measured
+     * 4.23:1 on four of five seeds.
+     *
+     * The method was right and its COVERAGE was not. A ground only exists at rest if nothing ever
+     * changes it; an interaction state is a different ground and has to be sampled too. */
+    inkSurface: { light: null, dark: "#3C3A34" },
+  },
+  {
+    id: "glass",
+    nameKey: "themeLab.theme.glass.name",
+    noteKey: "themeLab.theme.glass.note",
+    /* THE LIGHT VALUE WAS MEASURED THE WRONG WAY THE FIRST TIME (gh#903). #B59FDB came from
+     * compositing the five surface TOKENS; the real ground is the PAINTED PIXEL under each
+     * brand-ink element, which includes the gradients a theme paints and the token set does not.
+     * Sampled with every glyph hidden, the darkest such ground across the five seeds is navy's
+     * #9493CC at L=0.3152 — darker than the #B59FDB (L=0.3973) I had, so the ink was not being
+     * walked far enough and 16 strings in light glass sat at 3.41-4.43:1.
+     *
+     * Measured per branch, and the two are not the same KIND of number (see the type above).
+     * `#766A2D` was right and stays on the dark side, where the hardest ground is the LIGHTEST
+     * surface; the light side is #B59FDB, the DARKEST surface, because the ink walks the other
+     * way there. Carrying one hex into both slots would have been wrong in exactly one of them. */
+    inkSurface: { light: "#9493CC", dark: "#766A2D" },
+  },
+  {
+    id: "flat",
+    nameKey: "themeLab.theme.flat.name",
+    noteKey: "themeLab.theme.flat.note",
+    /* Measured per branch now that flat has one. The light side is close enough to the package
+     * default that omitting it would very nearly work (#E4E1EA against #EBE9E5, both far above the
+     * pivot) — stated anyway, because "near enough to the default" is a fact about today's flat,
+     * not a contract it holds anyone to. */
+    inkSurface: { light: "#E4E1EA", dark: "#403D30" },
+  },
+];
+
+/**
+ * Five seeds, chosen to break a theme rather than to flatter it: one cool default, one cool blue,
+ * one warm, one at the very light end (`#FFD400`, L≈83% — a white label on it fails AA, so
+ * `tenantTheme` picks black) and one at the very dark end (`#0A1F44`, L≈15% — the opposite).
+ * A theme tuned to a mid-luminance violet fails at both ends, which is the point of including them.
+ */
+export const SEEDS: readonly SeedRow[] = [
+  { id: "violet", hex: "#7C3AED", nameKey: "themeLab.seed.violet" },
+  { id: "azure", hex: "#2563EB", nameKey: "themeLab.seed.azure" },
+  { id: "coral", hex: "#E2564A", nameKey: "themeLab.seed.coral" },
+  { id: "citron", hex: "#FFD400", nameKey: "themeLab.seed.citron" },
+  { id: "navy", hex: "#0A1F44", nameKey: "themeLab.seed.navy" },
+];
+
+/** `light` leads for the same reason `base` leads `THEMES`: the first option is the control. */
+export const MODES: readonly ModeRow[] = [
+  { id: "light", nameKey: "themeLab.mode.light" },
+  { id: "dark", nameKey: "themeLab.mode.dark" },
+];
+
+/** The `?theme=` value for a row — `"base"` stands in for the null id in the URL. */
+export const themeQueryValue = (row: ThemeRow): string => row.id ?? "base";
+
+/** Resolve `?theme=` back to a row, falling back to the first one. */
+export function themeFromQuery(value: string | null): ThemeRow {
+  return THEMES.find((row) => themeQueryValue(row) === value) ?? THEMES[0];
+}
+
+/** Resolve `?seed=` back to a row, falling back to the first one. */
+export function seedFromQuery(value: string | null): SeedRow {
+  return SEEDS.find((row) => row.id === value) ?? SEEDS[0];
+}
+
+/** Resolve `?mode=` back to a row, falling back to the first one (light). */
+export function modeFromQuery(value: string | null): ModeRow {
+  return MODES.find((row) => row.id === value) ?? MODES[0];
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "28.13.0",
-  "godxUiMcp": "28.13.0",
+  "version": "29.0.0",
+  "godxUiMcp": "29.0.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -38,6 +38,7 @@
     "scripts/postinstall.mjs",
     "scripts/_agent-setup.mjs",
     "scripts/cli.mjs",
+    "scripts/explain-token.mjs",
     "docs"
   ],
   "main": "./dist/index.js",
@@ -392,7 +393,7 @@
     "lint:fix": "eslint . --fix",
     "postinstall": "node scripts/postinstall.mjs",
     "prepublishOnly": "pnpm run build",
-    "preview": "node preview/scripts/kill-port.mjs && vite --config preview/vite.config.ts --port 6008 --strictPort",
+    "preview": "PORT=$(node preview/scripts/preview-port.mjs) && node preview/scripts/kill-port.mjs $PORT && echo \"preview: http://localhost:$PORT\" && vite --config preview/vite.config.ts --port $PORT --strictPort",
     "preview:build": "vite build --config preview/vite.config.ts && node scripts/gen-registry.mjs && node scripts/copy-agent-catalog.mjs",
     "regen": "node scripts/regen-generated.mjs",
     "release": "node scripts/release.mjs",

package/scripts/explain-token.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+/**
+ * WHO SETS THIS TOKEN, WHO READS IT, AND WHO WOULD WIN — the resolution trace.
+ *
+ * WHY THIS EXISTS. The owner's complaint, verbatim: *"tao thấy rất nhiều chỗ mày cứ đè cấu hình
+ * lung tung làm ảnh hưởng component này sang component khác"* — configuration overriding
+ * configuration until a change to one component moves another. Prose cannot settle that argument.
+ * A trace can: for one token, print every DECLARATION and every READ in the package, in cascade
+ * order, and name the rule that would win.
+ *
+ * WHAT THE ORDER IS. See docs/TOKEN-RESOLUTION.md. In short, a custom property is resolved by the
+ * ordinary cascade, so the winner at an element is the declaration from the nearest ancestor that
+ * matched, and among equals the one with the highest specificity, and among those the last:
+ *
+ *     1  inline `style` on the element            (a per-instance prop)
+ *     2  the nearest scope that declares it       ([data-tenant], .dark, a region wrapper)
+ *     3  `:root` in the consumer's own theme.css  (unlayered, so it beats every package layer)
+ *     4  `:root` in this package's token tier     (the default)
+ *
+ * THE ONE RULE THAT BREAKS IT, and the reason this script reports `FREEZE` loudly: `var()`
+ * substitutes where it is DECLARED, not where it is read. So a package default written as
+ *
+ *     :root { --card-border-color: var(--border); }      ← FROZEN
+ *
+ * resolves against the ROOT's `--border` once, and a `[data-tenant]` below root that changes
+ * `--border` can never reach it — step 2 of the chain is silently dead for that token. The shape
+ * that keeps the chain alive is a knob of `initial` plus the formula at the CALL SITE:
+ *
+ *     :root       { --card-border-color: initial; }
+ *     .ui-card    { border-color: var(--card-border-color, hsl(var(--border))); }
+ *
+ * This repo has paid for that distinction seven times (gh#687, gh#843, gh#848, gh#866, …), which
+ * is why it is a reported finding here and not a footnote.
+ *
+ * USAGE
+ *   node scripts/explain-token.mjs --card-border-color     one token, full trace
+ *   node scripts/explain-token.mjs --card                  every token matching a prefix
+ *   node scripts/explain-token.mjs --audit                 every FREEZE and every orphan
+ *   node scripts/explain-token.mjs --json <name>           machine-readable, for a gate
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const ROOT = process.cwd();
+
+/** Source of truth for what a CONSUMER can set: the published catalog, not the stylesheets. */
+function publishedTokens() {
+  try {
+    const raw = JSON.parse(readFileSync(join(ROOT, "agent/tokens.json"), "utf8"));
+    const list = Array.isArray(raw) ? raw : Object.values(raw).find(Array.isArray);
+    return new Map(list.map((t) => [t.name, t.tier ?? "component"]));
+  } catch {
+    return new Map();
+  }
+}
+
+function cssFiles() {
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (entry.endsWith(".css")) out.push(full);
+    }
+  };
+  /* BOTH LAYOUTS, because the same script runs in two places and only one of them has `src/`.
+   * In this checkout the CSS lives in `src/tokens` and `src/styles`. In the PUBLISHED package it
+   * lives in `dist/tokens` and `dist/styles` — `package.json::files` ships `dist`, never `src`.
+   * gh#893 put this file in the tarball, and shipping it was not the same as making it work: a
+   * consumer running it against `node_modules/@godxjp/ui` scanned two directories that do not
+   * exist there, found zero CSS files, and got a confident empty answer for every token. Walking
+   * both and keeping whichever is present costs one loop and removes the whole failure mode. */
+  for (const dir of ["src/tokens", "src/styles", "dist/tokens", "dist/styles"]) {
+    try {
+      walk(join(ROOT, dir));
+    } catch {
+      /* a tree that is not there is not an error here */
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Every `--x: value` declaration, with the selector it sits under and the layer that governs it.
+ *
+ * Comments are BLANKED rather than removed so byte offsets stay true — a `{`, `}` or `;` inside
+ * prose otherwise desynchronises the brace walk and silently moves every selector after it. That
+ * failure has a name in this repo: it is what `check-mcp-prop-sync` hit with `=>` (gh#857).
+ */
+function parse(file) {
+  const text = readFileSync(file, "utf8");
+  const blank = text.replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, " "));
+  const rel = relative(ROOT, file);
+  const lineAt = (i) => text.slice(0, i).split("\n").length;
+
+  const decls = [];
+  const reads = [];
+  const stack = [];
+  let selStart = 0;
+
+  for (let i = 0; i < blank.length; i += 1) {
+    const ch = blank[i];
+    if (ch === "{") {
+      stack.push(blank.slice(selStart, i).trim().replace(/\s+/g, " "));
+      selStart = i + 1;
+    } else if (ch === "}") {
+      stack.pop();
+      selStart = i + 1;
+    } else if (ch === ";") {
+      selStart = i + 1;
+    }
+  }
+
+  // Declarations: `--name: value;` — captured with their enclosing selector chain.
+  const declRe = /(--[a-z0-9-]+)\s*:\s*([^;}]+)[;}]/gi;
+  for (const m of blank.matchAll(declRe)) {
+    const line = lineAt(m.index);
+    const value = text.slice(m.index + m[1].length, m.index + m[0].length).replace(/^\s*:\s*/, "");
+    decls.push({
+      file: rel,
+      line,
+      name: m[1],
+      value: value
+        .replace(/[;}]\s*$/, "")
+        .trim()
+        .replace(/\s+/g, " "),
+      context: contextAt(blank, m.index),
+    });
+  }
+
+  // Reads: `var(--name` anywhere, including inside another declaration's value.
+  for (const m of blank.matchAll(/var\(\s*(--[a-z0-9-]+)/gi)) {
+    reads.push({
+      file: rel,
+      line: lineAt(m.index),
+      name: m[1],
+      context: contextAt(blank, m.index),
+      hasFallback: text
+        .slice(m.index, m.index + 400)
+        .replace(/\s+/g, " ")
+        .includes(`${m[1]},`),
+    });
+  }
+  return { decls, reads };
+}
+
+/** The selector chain enclosing a byte offset, outermost first. */
+function contextAt(blank, at) {
+  const chain = [];
+  let depth = 0;
+  let selStart = 0;
+  for (let i = 0; i < at; i += 1) {
+    const ch = blank[i];
+    if (ch === "{") {
+      chain.push({ depth, sel: blank.slice(selStart, i).trim().replace(/\s+/g, " ") });
+      depth += 1;
+      selStart = i + 1;
+    } else if (ch === "}") {
+      depth -= 1;
+      while (chain.length && chain[chain.length - 1].depth >= depth) chain.pop();
+      selStart = i + 1;
+    } else if (ch === ";" && depth >= 0) {
+      selStart = i + 1;
+    }
+  }
+  return chain.map((c) => c.sel).filter(Boolean);
+}
+
+/**
+ * IS THIS DECLARATION ON THE ROOT ELEMENT? — the one thing here that is mechanically decidable,
+ * and the only thing the freeze test needs.
+ *
+ * An earlier version of this file ranked every selector into four "cascade" buckets by regex and
+ * printed them "strongest last". Codex took it apart and was right: `@theme inline` and
+ * `[dir="rtl"] .ui-actions[data-fade-in-inline]` both scored TOP precedence because their text
+ * contains the substring `inline`; `:root[data-brand="crm"]` scored "descendant scope" although it
+ * matches only the root; `[data-slot="card"][data-density="tight"]` — a declaration on the
+ * component itself — scored "ambient scope". And "strongest last" sorted by ALPHABETICAL FILE
+ * ORDER, not import order, so the ordering was decoration.
+ *
+ * A tool meant to settle override disputes that manufactures precedence from substrings is worse
+ * than no tool: it sends the reader to the wrong fix with confidence. So the ranking is gone. This
+ * prints WHERE a token is declared and read, and computes only the one property it can prove.
+ */
+function isRootOnly(context) {
+  if (!context.length) return false;
+  return context.every((sel) =>
+    sel
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .every((s) =>
+        // `:root`, `:root[data-theme="dark"]`, `html` — matches the root element and nothing
+        // below it. A descendant combinator, or any selector that can match an element deeper in
+        // the tree, is NOT root-only.
+        /^(:root|html)(\[[^\]]*\]|:[a-z-]+(\([^)]*\))?)*$/.test(s),
+      ),
+  );
+}
+
+/**
+ * Every token some declaration BELOW the root can move.
+ *
+ * Deliberately wider than "a theme scope": `.ui-page-container` inside `@media (max-width: 720px)`
+ * restates `--space-section-active` (src/styles/layout.css:992), and `--card-space-inset` binds it
+ * at `:root` (src/tokens/components/card.css:6) — so below 720px a Card keeps the root's inset. The
+ * previous version missed that because it only accepted selectors that LOOKED like theme scopes.
+ * Anything not root-only counts now.
+ */
+function scopedTokenNames(decls) {
+  return new Set(decls.filter((d) => !isRootOnly(d.context)).map((d) => d.name));
+}
+
+function collect() {
+  const decls = [];
+  const reads = [];
+  for (const f of cssFiles()) {
+    const r = parse(f);
+    decls.push(...r.decls);
+    reads.push(...r.reads);
+  }
+  return { decls, reads };
+}
+
+/**
+ * A `:root` binding that a scope below root cannot reach.
+ *
+ * The naive test — "a `:root` declaration whose value contains `var()`" — reports 1028 sites here,
+ * and a finding list that long is one nobody reads. Most are harmless: `--actions-gap:
+ * var(--space-1)` freezes against a `--space-1` that no scope ever redeclares, so freezing it
+ * changes nothing that could ever have differed.
+ *
+ * The binding only COSTS something when the token it reads is itself restated somewhere below
+ * root — a `.dark` block, a `[data-tenant]`, a density or scale scope. Then the scope moves the
+ * source and the binding keeps the root's answer, which is the defect this repo has paid for
+ * seven times. So the signal is the INTERSECTION, and `scopedNames` is derived from the
+ * stylesheets on every run rather than hand-listed: a hand-kept list is what went blind in gh#854.
+ */
+function isFrozen(d, scopedNames) {
+  if (!isRootOnly(d.context)) return false;
+  if (d.value.trim() === "initial") return false;
+  const reads = [...d.value.matchAll(/var\(\s*(--[a-z0-9-]+)/gi)].map((m) => m[1]);
+  return reads.some((r) => scopedNames.has(r));
+}
+
+function trace(name, { decls, reads }, published, scopedNames) {
+  const mine = decls.filter((d) => d.name === name);
+  const myReads = reads.filter((r) => r.name === name);
+  const tier = published.get(name);
+
+  console.log(`\n${name}`);
+  console.log(
+    `  published: ${tier ? `yes (${tier} tier)` : "NO — not in agent/tokens.json, so a consumer cannot discover it"}`,
+  );
+
+  if (!mine.length) {
+    console.log("  declared:  nowhere — every read falls to its inline fallback, or to nothing");
+  } else {
+    console.log(
+      `  declared:  ${mine.length} site(s) — DECLARATION SITES, not a cascade ranking; which one`,
+    );
+    console.log(
+      "             wins at a given element depends on the DOM, and is not computed here.",
+    );
+    for (const d of mine.sort(
+      (a, b) => Number(isRootOnly(b.context)) - Number(isRootOnly(a.context)),
+    )) {
+      const frozen = isFrozen(d, scopedNames)
+        ? "  ← FREEZE: binds at :root against a token a scope below DOES restate"
+        : "";
+      console.log(
+        `    ${isRootOnly(d.context) ? "root-only " : "below root"}  ${d.file}:${d.line}`,
+      );
+      console.log(`         ${d.context.join(" ") || ":root"} { ${name}: ${d.value} }${frozen}`);
+    }
+  }
+
+  console.log(`  read by:   ${myReads.length} site(s)`);
+  for (const r of myReads.slice(0, 12)) {
+    console.log(
+      `    ${r.file}:${r.line}  ${r.context.join(" ") || "(top level)"}${r.hasFallback ? "  [has a call-site fallback]" : "  [NO fallback — undeclared means unset]"}`,
+    );
+  }
+  if (myReads.length > 12) console.log(`    … and ${myReads.length - 12} more`);
+  return { name, tier, decls: mine, reads: myReads };
+}
+
+function audit({ decls, reads }, published) {
+  const scopedNames = scopedTokenNames(decls);
+  const frozen = decls.filter((d) => isFrozen(d, scopedNames));
+  const declaredNames = new Set(decls.map((d) => d.name));
+  const orphanReads = reads.filter((r) => !declaredNames.has(r.name) && !r.hasFallback);
+  const unpublished = [...declaredNames].filter((n) => !published.has(n));
+
+  console.log(
+    `\nFROZEN — a :root binding whose SOURCE a scope below root restates (${frozen.length})`,
+  );
+  console.log(
+    `  ${scopedNames.size} token(s) are restated in some scope. A :root binding that reads one of`,
+  );
+  console.log("  them keeps the root's answer, so step 2 of the chain is dead for that token.");
+  for (const d of frozen.slice(0, 40)) {
+    console.log(`  ${d.file}:${d.line}  ${d.name}: ${d.value}`);
+  }
+  if (frozen.length > 40) console.log(`  … and ${frozen.length - 40} more`);
+
+  console.log(
+    `\nORPHAN READS — var(--x) with no declaration and no fallback (${orphanReads.length})`,
+  );
+  for (const r of orphanReads.slice(0, 20)) console.log(`  ${r.file}:${r.line}  ${r.name}`);
+  if (orphanReads.length > 20) console.log(`  … and ${orphanReads.length - 20} more`);
+
+  console.log(
+    `\nUNPUBLISHED — declared in CSS but absent from agent/tokens.json (${unpublished.length})`,
+  );
+  console.log("  A consumer cannot discover these, so they are not part of the theme API.");
+  for (const n of unpublished.slice(0, 20)) console.log(`  ${n}`);
+  if (unpublished.length > 20) console.log(`  … and ${unpublished.length - 20} more`);
+
+  console.log("\nWHAT THIS CANNOT SEE — do not read a clean run as proof of no freeze:");
+  console.log(
+    "  1. CONSUMER CSS. Only this package's own token/style trees are scanned, so a token it never",
+  );
+  console.log(
+    "     restates below root looks safe. `--shadow-md` binds `--shadow-color` at :root; a",
+  );
+  console.log(
+    "     consumer's `[data-tenant] { --shadow-color: … }` cannot recolour it, and nothing here says so.",
+  );
+  console.log("  2. `@supports` FALLBACKS. src/tokens/derived.css gives engines without relative");
+  console.log(
+    "     colour LITERAL hover/active values, so a tenant seed stops propagating — a lost derivation,",
+  );
+  console.log("     not a var() freeze, and invisible to a test that requires a var() reference.");
+  console.log(
+    "  3. CONDITIONS ARE NOT EVALUATED. A declaration inside @media/@container is counted as if it",
+  );
+  console.log(
+    "     always applies. That widens the scoped set deliberately, but it is not the cascade.",
+  );
+  console.log(
+    "  4. NO WINNER IS COMPUTED. Which declaration applies at an element depends on the DOM.",
+  );
+
+  console.log(
+    `\nsummary: ${declaredNames.size} declared · ${published.size} published · ${frozen.length} frozen · ${orphanReads.length} orphan read(s)`,
+  );
+  return {
+    frozen: frozen.length,
+    orphanReads: orphanReads.length,
+    unpublished: unpublished.length,
+  };
+}
+
+const args = process.argv.slice(2);
+const asJson = args.includes("--json");
+const query = args.filter((a) => a !== "--json" && a !== "--audit")[0];
+const model = collect();
+const published = publishedTokens();
+
+if (args.includes("--audit") || !query) {
+  if (!query && !args.includes("--audit")) {
+    console.log("usage: node scripts/explain-token.mjs <--token-name|prefix|--audit> [--json]\n");
+  }
+  audit(model, published);
+} else {
+  const names = [...new Set(model.decls.map((d) => d.name))]
+    .concat([...published.keys()])
+    .filter((n, i, a) => a.indexOf(n) === i)
+    .filter((n) => n === query || n.startsWith(query));
+  if (!names.length) {
+    console.log(`no token matches ${query}`);
+    process.exit(1);
+  }
+  const scopedNames = scopedTokenNames(model.decls);
+  const out = names
+    .sort()
+    .slice(0, 40)
+    .map((n) => trace(n, model, published, scopedNames));
+  if (asJson) console.log(JSON.stringify(out, null, 2));
+  if (names.length > 40) console.log(`\n… ${names.length - 40} more match ${query}`);
+}