synthesisui 0.16.36 → 0.16.38

package/dist/commands/import.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
+import { isNearDuplicate } from "../doctor/color-distance.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { buildTable } from "../doctor/tokens.js";
 import { body, paint, section } from "../output.js";
@@ -24,6 +25,9 @@ import { walk, walkAll } from "./doctor.js";
  * worst case is ~380 entries, about 30KB of json - cheap for the one payload
  * that describes somebody's entire vocabulary.
  */
+/** How many rare colours may ride along on similarity. Bounded so a
+ *  pathological palette cannot turn the payload into a log. */
+const TWIN_BUDGET = 250;
 const MAX_PER_KIND = {
     color: 250,
     radius: 60,
@@ -95,17 +99,27 @@ async function detectStack(root) {
         stack.push("plain css");
     return stack;
 }
-/** Their own vocabulary, read from stylesheets - the same harvest the doctor
- *  runs when nothing of ours is installed. */
-async function declaredTokens(root) {
+/**
+ * Their own vocabulary, read from stylesheets - the same harvest the doctor runs
+ * when nothing of ours is installed.
+ *
+ * Returns the TABLE, not just the names, because the scan needs it. The first
+ * version harvested the names for the payload and then scanned with an EMPTY
+ * table, which made the census blind in a way a real app exposed (dono, 30/07):
+ * a project with 2416 uses of its own `var(--dashboard-*)` reported
+ * `tokenUses: 0`, `coverage: 0`, and `token: null` on every single value. The
+ * sharpest sentence the doctor knows - "your own system already has a name for
+ * this" - could not be said, and we ended up rediscovering by colour distance
+ * what their stylesheet had spelled out all along.
+ */
+async function harvestOwnTable(root) {
     let css = "";
     for await (const file of walkAll([root])) {
         if (!/\.(css|scss|sass|less)$/i.test(file))
             continue;
         css += `\n${await readFile(file, "utf8").catch(() => "")}`;
     }
-    const table = buildTable({ css, source: "yours" });
-    return Object.fromEntries(table.byName);
+    return buildTable({ css, source: "yours" });
 }
 /**
  * EVERY distinct design value, commonest first - not just the repeated ones.
@@ -135,18 +149,47 @@ function distinctValues(d) {
         });
     }
     // Per-kind budgets, each family ranked inside its own: colour never starves
-    // radius, and the low-frequency tail of colour (where near-duplicates live)
-    // survives a cut that a global cap would have made first.
+    // radius, and the low-frequency tail of colour survives a cut a global cap
+    // would have made first.
     const kept = [];
     const dropped = new Map();
+    let ridealong = 0;
     for (const kind of Object.keys(MAX_PER_KIND)) {
         const family = [...by.values()]
             .filter((v) => v.kind === kind)
             .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
         const budget = MAX_PER_KIND[kind];
-        if (family.length > budget)
-            dropped.set(kind, family.length - budget);
-        for (const v of family.slice(0, budget)) {
+        const take = family.slice(0, budget);
+        let rest = family.slice(budget);
+        /**
+         * THE TWIN RIDES ALONG (measured 30/07 on a 2876-file project: 899 distinct
+         * colours, 250 carried, 649 left behind).
+         *
+         * Frequency is the wrong sole criterion for colour. A near-duplicate is BY
+         * DEFINITION rare - the twin of a brand blue used three times - so ranking
+         * by count discards precisely the evidence the normalisation pass exists to
+         * find. Raising the budget does not fix it either; it just moves the wall.
+         *
+         * So after the budget is spent, any colour sitting within the
+         * just-noticeable difference of one we already kept comes too. It costs a
+         * little payload and it is the whole point of the payload.
+         */
+        if (kind === "color") {
+            const anchors = take.map((v) => v.value);
+            const near = [];
+            const far = [];
+            for (const v of rest) {
+                (anchors.some((a) => isNearDuplicate(a, v.value)) ? near : far).push(v);
+            }
+            // Bounded: a pathological palette could put thousands here, and a payload
+            // that large stops being a vocabulary.
+            take.push(...near.slice(0, TWIN_BUDGET));
+            ridealong += Math.min(near.length, TWIN_BUDGET);
+            rest = [...far, ...near.slice(TWIN_BUDGET)];
+        }
+        if (rest.length > 0)
+            dropped.set(kind, rest.length);
+        for (const v of take) {
             kept.push({
                 kind: v.kind,
                 value: v.value,
@@ -156,15 +199,20 @@ function distinctValues(d) {
             });
         }
     }
+    if (ridealong > 0) {
+        console.log(body(paint.dim(`(+${ridealong} rare colour${ridealong === 1 ? "" : "s"} carried anyway: each sits within the just-noticeable difference of one above, which is what normalizing is about)`)));
+    }
     // NO SILENT CAPS: a payload that quietly stops at a budget reads as "this is
     // everything you have", which is the one thing a census must never imply.
     for (const [kind, n] of dropped) {
-        console.log(body(paint.faint(`(${n} more ${kind} value${n === 1 ? "" : "s"} exist below the ${MAX_PER_KIND[kind]} we carry - each used less often than the ones above)`)));
+        console.log(body(paint.faint(kind === "color"
+            ? `(${n} more colour${n === 1 ? "" : "s"} left behind: rarer than the ${MAX_PER_KIND[kind]} above AND not close enough to any of them to matter)`
+            : `(${n} more ${kind} value${n === 1 ? "" : "s"} exist below the ${MAX_PER_KIND[kind]} we carry - each used less often than the ones above)`)));
     }
     return kept.sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
 }
 export async function takeCensus(root) {
-    const table = buildTable({ css: "", source: "yours" });
+    const table = await harvestOwnTable(root);
     const reports = [];
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
@@ -186,7 +234,7 @@ export async function takeCensus(root) {
     return {
         census: 1,
         project: { name, stack: await detectStack(root) },
-        declared: await declaredTokens(root),
+        declared: Object.fromEntries(table.byName),
         observed: distinctValues(d),
         totals: {
             scanned: d.scanned,
@@ -213,6 +261,12 @@ function summarize(c) {
     if (Object.keys(c.declared).length > 0) {
         console.log(body(`${Object.keys(c.declared).length} tokens you already declare - your names travel unchanged`));
     }
+    // The sharpest number in the report, and it only became sayable once the scan
+    // started using their own token table: not "you have drift" but "you have
+    // drift your own system already solved".
+    if (c.totals.named > 0) {
+        console.log(body(`${paint.strong(String(c.totals.named))} of those values ALREADY have a name in your system - ${c.totals.coverage}% of your design values come from it today`));
+    }
     const top = c.observed.slice(0, 5);
     if (top.length > 0) {
         console.log("");

package/dist/doctor/color-distance.js

@@ -0,0 +1,70 @@
+/**
+ * PERCEPTUAL COLOUR DISTANCE, in the CLI.
+ *
+ * ΔE76 in CIE Lab: the cheapest metric that matches what an eye calls "the same
+ * colour". Landmarks - under 1 nobody sees it, 2.3 is the just-noticeable
+ * difference, past 5 a designer defends the difference.
+ *
+ * DELIBERATE DUPLICATION. The platform has this same maths in
+ * `apps/web/src/lib/engine/near-colors.ts`, and the CLI is a standalone npm
+ * package that cannot import from the app. The two are kept honest by specs on
+ * both sides asserting the SAME landmark numbers, so a change to one that drifts
+ * from the other turns red rather than quietly producing two different opinions
+ * about whether two greys are the same grey.
+ *
+ * Why the CLI needs it at all: the census picks which values travel, and
+ * frequency alone picks wrong. A near-duplicate is by definition rare - the twin
+ * of a brand colour used three times - so a frequency-ranked cut throws away
+ * exactly the evidence the normalisation pass is looking for. With this, a rare
+ * value rides along when it sits close to one we already kept.
+ */
+const HEX6 = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+/** The just-noticeable difference for ΔE76. Same constant as the platform's. */
+export const JND = 2.3;
+function toRgb(hex) {
+    const h = hex.trim().replace("#", "");
+    if (!HEX6.test(`#${h}`))
+        return null;
+    const full = h.length === 3
+        ? h
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : h;
+    const n = Number.parseInt(full, 16);
+    if (Number.isNaN(n))
+        return null;
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+/** sRGB → CIE Lab (D65). The gamma expansion and the white point matter: skip
+ *  them and dark values read as far closer together than they look. */
+export function toLab(hex) {
+    const rgb = toRgb(hex);
+    if (!rgb)
+        return null;
+    const lin = rgb.map((c) => {
+        const s = c / 255;
+        return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    });
+    const x = (lin[0] * 0.4124 + lin[1] * 0.3576 + lin[2] * 0.1805) / 0.95047;
+    const y = lin[0] * 0.2126 + lin[1] * 0.7152 + lin[2] * 0.0722;
+    const z = (lin[0] * 0.0193 + lin[1] * 0.1192 + lin[2] * 0.9505) / 1.08883;
+    const f = (t) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);
+    const fx = f(x);
+    const fy = f(y);
+    const fz = f(z);
+    return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+}
+/** ΔE76 between two colours, or null when either cannot be read. */
+export function deltaE(a, b) {
+    const la = toLab(a);
+    const lb = toLab(b);
+    if (!la || !lb)
+        return null;
+    return Math.sqrt((la[0] - lb[0]) ** 2 + (la[1] - lb[1]) ** 2 + (la[2] - lb[2]) ** 2);
+}
+/** True when two colours are the same decision typed twice. */
+export function isNearDuplicate(a, b, threshold = JND) {
+    const d = deltaE(a, b);
+    return d != null && d <= threshold;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.36",
+  "version": "0.16.38",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {