synthesisui 0.16.35 → 0.16.37

package/dist/commands/import.js

@@ -1,13 +1,40 @@
 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";
 import { walk, walkAll } from "./doctor.js";
-/** How many distinct values travel. A census is a vocabulary, not a log: past
- *  the first few dozen repeats the tail is noise nobody will name. */
-const MAX_VALUES = 120;
+/**
+ * How many distinct values travel, PER KIND.
+ *
+ * It was one global cap of 120, and a real app broke it (30/07): 2876 files,
+ * 3976 findings, and the payload came back holding exactly 120 - ranked by
+ * frequency with every kind competing for the same slots. Two things went wrong
+ * there, and the second is the serious one:
+ *
+ *   - radius and spacing lost their slots to colour, so the scale downstream
+ *     would have been built from a partial set
+ *   - the NEAR-DUPLICATE colours - a fifth grey used three times, the twin of
+ *     the brand blue - are by definition low-frequency, which is exactly what a
+ *     frequency-ranked cut throws away first. The collapse that justifies the
+ *     whole v2 lives in that tail.
+ *
+ * So colour gets a deep budget and the dimensional families get their own. The
+ * 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,
+    spacing: 60,
+    motion: 40,
+    font: 30,
+};
 /**
  * Dependencies as the project actually resolves them - which means reading
  * ANCESTOR package.json files too.
@@ -111,16 +138,68 @@ function distinctValues(d) {
             token: f.token,
         });
     }
-    return [...by.values()]
-        .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value))
-        .slice(0, MAX_VALUES)
-        .map((v) => ({
-        kind: v.kind,
-        value: v.value,
-        count: v.count,
-        files: v.files.size,
-        token: v.token,
-    }));
+    // Per-kind budgets, each family ranked inside its own: colour never starves
+    // 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];
+        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,
+                count: v.count,
+                files: v.files.size,
+                token: v.token,
+            });
+        }
+    }
+    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(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" });

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.35",
+  "version": "0.16.37",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {