synthesisui 0.16.55 → 0.16.57

package/dist/commands/import.js

@@ -1,7 +1,7 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
-import { isNearDuplicate } from "../doctor/color-distance.js";
+import { isNearDuplicate, isNeutral, lightness, } from "../doctor/color-distance.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { crosswalk, observedRules } from "../doctor/crosswalk.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
@@ -327,13 +327,19 @@ export async function takeCensus(root) {
      * by the two-option rule, while its type declares four sizes and three
      * variants (dono, 31/07). The component would have reached the platform with
      * no contract at all, which is the exact thing reading definitions was for.
+     *
+     * Carried BESIDE the usage rather than written into it. The first attempt
+     * merged the declaration into `props` and broke the two readings that need
+     * `props` to mean "what the code passed": the composition list started
+     * showing declared options as composed, and the dead-option check went quiet
+     * because every declared option now looked used.
      */
     const declaredBy = new Map(defined.map((d) => [d.name, d]));
     const enriched = inventory.map((c) => {
         const d = declaredBy.get(c.name);
         if (!d || Object.keys(d.axes).length === 0)
             return c;
-        return { ...c, props: { ...c.props, ...d.axes } };
+        return { ...c, declaredAxes: d.axes };
     });
     const merged = [...enriched, ...fromTypes];
     // The verdict travels WITH the payload: the platform reads one reading rather
@@ -401,7 +407,12 @@ function summarize(c) {
     // started using their own token table: not "you have drift" but "you have
     // drift your own system already solved".
     if (c.declaredAlt && Object.keys(c.declaredAlt).length > 0) {
-        console.log(body(`${Object.keys(c.declaredAlt).length} of them are declared again for dark - both schemes travel`));
+        console.log(body(
+        // No promise here. Whether a second scheme actually travels depends on
+        // those declarations naming ROLES, which the platform decides - and a
+        // project with two aliased dark tokens got told "both schemes travel"
+        // and then received one (dono, 31/07).
+        `${Object.keys(c.declaredAlt).length} of them are declared again in a dark scope`));
     }
     // The inventory, phase one: what this project composes. Printed, never
     // mapped - deciding that their `Pill` is our `ds-badge` is a judgement a
@@ -596,7 +607,8 @@ function printAgentContract() {
     console.log(body(paint.faint('  "reading": {')));
     console.log(body(paint.faint('    "roles": { "canvas": "#…", "foreground": "#…", "primary": "#…" },')));
     console.log(body(paint.faint('    "fonts": { "display": "…", "body": "…" },')));
-    console.log(body(paint.faint('    "concept": "one paragraph on what this product is"')));
+    console.log(body(paint.faint('    "concept": "one paragraph on what this product is",')));
+    console.log(body(paint.faint('    "themes": { "default": "dark", "has": ["dark"] }')));
     console.log(body(paint.faint("  }")));
     console.log("");
     console.log(body("Every hex in `roles` must be one the census already observed - a value"));
@@ -662,6 +674,33 @@ const GENERIC = new Set([
     "shared",
     "common",
 ]);
+/**
+ * Which ends of the neutral ladder their own tokens reach.
+ *
+ * The bands match the ones the platform maps roles with: a surface needs to be
+ * a surface, and a near-black is the only thing that reads as a dark canvas.
+ * Both true means BOTH schemes can be built out of values they already
+ * declared - no colour borrowed, their token names intact - and the only open
+ * question is which one is the default. Exactly one true means the other mode
+ * would need colours they do not have, which is worth saying out loud rather
+ * than inventing.
+ */
+export function ladderReach(declared) {
+    let light = false;
+    let dark = false;
+    for (const value of Object.values(declared)) {
+        if (typeof value !== "string")
+            continue;
+        const L = lightness(value);
+        if (L == null || !isNeutral(value))
+            continue;
+        if (L > 0.93)
+            light = true;
+        if (L < 0.05)
+            dark = true;
+    }
+    return { light, dark };
+}
 export function deriveName(pkgName, dirName) {
     const raw = (pkgName ?? "").trim();
     const scoped = /^@([^/]+)\/(.+)$/.exec(raw);
@@ -701,6 +740,127 @@ async function askName(suggested) {
         rl.close();
     }
 }
+/**
+ * Pick the default surface, by SELECTION rather than by typing (dono, 31/07).
+ *
+ * A one-bit answer typed as a word invites a typo that inverts a whole system,
+ * and a free-text prompt reads as "compose an answer" when the answer is a
+ * choice between two things we can already name. Arrows move, Enter takes what
+ * is highlighted; `1`/`2` and `d`/`l` work too, because muscle memory differs
+ * and none of them are ambiguous here.
+ *
+ * Never blocks without a person: no TTY means the caller's `--scheme` or the
+ * measured default stands.
+ */
+async function askScheme(suggested) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return suggested;
+    const options = ["dark", "light"];
+    let at = options.indexOf(suggested);
+    if (at < 0)
+        at = 0;
+    console.log("");
+    console.log(section("Your ladder reaches both ends"));
+    console.log(body(paint.faint("Both schemes get built from tokens you already declare. Pick the default.")));
+    console.log("");
+    const render = (first) => {
+        if (!first)
+            process.stdout.write(`\u001b[${options.length}A`);
+        for (const [i, opt] of options.entries()) {
+            const label = opt === "dark" ? "dark" : "light";
+            const line = i === at
+                ? `  ${paint.strong(`> ${label}`)}`
+                : `  ${paint.faint(`  ${label}`)}`;
+            process.stdout.write(`\u001b[2K${line}\n`);
+        }
+    };
+    render(true);
+    return await new Promise((resolve) => {
+        const stdin = process.stdin;
+        const done = (value) => {
+            stdin.off("data", onData);
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+            stdin.pause();
+            // Leave the choice on screen rather than a cursor parked mid-list.
+            at = options.indexOf(value);
+            render(false);
+            console.log("");
+            resolve(value);
+        };
+        const onData = (buf) => {
+            const key = buf.toString();
+            if (key === "\u0003") {
+                // Ctrl-C during a question is a person leaving, not a value to invent.
+                if (stdin.isTTY)
+                    stdin.setRawMode(false);
+                process.exit(130);
+            }
+            if (key === "\u001b[A" || key === "k") {
+                at = (at + options.length - 1) % options.length;
+                render(false);
+                return;
+            }
+            if (key === "\u001b[B" || key === "j" || key === "\t") {
+                at = (at + 1) % options.length;
+                render(false);
+                return;
+            }
+            if (key === "1")
+                return done("dark");
+            if (key === "2")
+                return done("light");
+            if (key === "d" || key === "D")
+                return done("dark");
+            if (key === "l" || key === "L")
+                return done("light");
+            if (key === "\r" || key === "\n")
+                return done(options[at]);
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on("data", onData);
+    });
+}
+/**
+ * Which end to offer first when both are available.
+ *
+ * The ladder itself votes: a product built dark tends to declare more rungs at
+ * the dark end, because that is where its surfaces live and where it needs the
+ * separation. The real one (dono, 31/07) declares nine near-blacks and five
+ * light greys, and its dashboard is near-black - so the count agrees with the
+ * screen. It is only a default; the person confirms it either way.
+ */
+export function defaultScheme(declared) {
+    let dark = 0;
+    let light = 0;
+    for (const value of Object.values(declared)) {
+        if (typeof value !== "string" || !isNeutral(value))
+            continue;
+        const L = lightness(value);
+        if (L == null)
+            continue;
+        if (L < 0.5)
+            dark++;
+        else
+            light++;
+    }
+    return dark > light ? "dark" : "light";
+}
+/** On a dry run there is nobody to ask, so say what was measured. */
+function sayReach(c) {
+    const reach = ladderReach(c.declared);
+    console.log("");
+    if (reach.light && reach.dark) {
+        console.log(body(`Your neutrals reach both ends, so light and dark could both be built from your own tokens - but only your project knows which it actually ships. Answer ${paint.strong("themes")} below, or let the real run ask; the ladder alone would guess ${paint.strong(defaultScheme(c.declared))}.`));
+        return;
+    }
+    if (reach.dark || reach.light) {
+        const has = reach.dark ? "dark" : "light";
+        const missing = reach.dark ? "light" : "dark";
+        console.log(body(`Your neutrals only reach the ${has} end, so this system gets one scheme. A ${missing} mode would need surfaces you do not declare.`));
+    }
+}
 export async function runImport(opts) {
     const root = opts.root ?? process.cwd();
     // A census handed to us (an agent annotated it) is sent as-is; the numbers
@@ -741,6 +901,7 @@ export async function runImport(opts) {
     console.log(body(`Written to ${paint.strong(relative(root, out))}`));
     if (opts.dry) {
         console.log(body("Nothing was sent. Read the file, then run it without --dry."));
+        sayReach(census);
         printComponents(census);
         printAgentContract();
         console.log("");
@@ -748,6 +909,31 @@ export async function runImport(opts) {
     }
     const suggested = deriveName(census.project.name, basename(root) || "system");
     const chosen = opts.name?.trim() || (await askName(suggested));
+    const reach = ladderReach(census.declared);
+    // An explicit flag is a decision already made. Otherwise the person answers,
+    // starting from the agent's reading if there is one and from the ladder's own
+    // vote if there is not - and with nobody at a terminal, that same order
+    // stands unattended.
+    const read = census.reading?.themes;
+    const scheme = opts.scheme ??
+        read?.default ??
+        // Only ask when nobody has looked. A reading that names one theme has
+        // already answered this, and a second question would just be a chance to
+        // contradict it.
+        (read?.has?.length === 1
+            ? read.has[0]
+            : reach.light && reach.dark
+                ? await askScheme(defaultScheme(census.declared))
+                : reach.dark
+                    ? "dark"
+                    : reach.light
+                        ? "light"
+                        : undefined);
+    if (scheme)
+        census.scheme = scheme;
+    // The file on disk has to say what we sent, or the next person to read it is
+    // reading a different import than the one that happened.
+    await writeFile(out, `${JSON.stringify(census, null, 2)}\n`, "utf8");
     const token = await readToken();
     if (!token) {
         console.log("");

package/dist/doctor/color-distance.js

@@ -68,3 +68,57 @@ export function isNearDuplicate(a, b, threshold = JND) {
     const d = deltaE(a, b);
     return d != null && d <= threshold;
 }
+/**
+ * LIGHTNESS and NEUTRAL - carried here for the same reason the ΔE maths is:
+ * the CLI is a standalone package and cannot import from the app. These are the
+ * platform's `lightness` and its neutral test (`apps/web/src/lib/ds/census-import.ts`)
+ * to the digit, and the spec asserts the same landmarks on both sides, because
+ * the two halves deciding differently what counts as a dark canvas is worse
+ * than either of them being wrong.
+ */
+export function lightness(hex) {
+    const h = hex.trim().replace("#", "");
+    const full = h.length === 3 || h.length === 4
+        ? h
+            .slice(0, 3)
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : h.slice(0, 6);
+    if (full.length !== 6)
+        return null;
+    const n = Number.parseInt(full, 16);
+    if (Number.isNaN(n))
+        return null;
+    return ((0.2126 * ((n >> 16) & 255) +
+        0.7152 * ((n >> 8) & 255) +
+        0.0722 * (n & 255)) /
+        255);
+}
+/** Channel spread, not HSL saturation: `#f9fbfd` is 0.50 saturated and 0.016
+ *  chromatic, and treating it as coloured throws every off-white surface out of
+ *  the neutral ladder. */
+export function chroma(hex) {
+    const h = hex.trim().replace("#", "");
+    const full = h.length === 3 || h.length === 4
+        ? h
+            .slice(0, 3)
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : h.slice(0, 6);
+    if (full.length !== 6)
+        return null;
+    const n = Number.parseInt(full, 16);
+    if (Number.isNaN(n))
+        return null;
+    const r = (n >> 16) & 255;
+    const g = (n >> 8) & 255;
+    const b = n & 255;
+    return (Math.max(r, g, b) - Math.min(r, g, b)) / 255;
+}
+export const NEUTRAL_CHROMA = 0.1;
+export function isNeutral(hex) {
+    const c = chroma(hex);
+    return c != null && c < NEUTRAL_CHROMA;
+}

package/dist/index.js

@@ -66,6 +66,7 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
   --name <name>      preferred component name for generate
+  --scheme <s>       dark|light - which end of your ladder is the default
   --target <t>       template/init target: next | general (default: next)
   --pages-dir <dir>  init: folder for generated pages (default: app)
   --components-dir <dir>  init: folder where components live (default: components)
@@ -159,6 +160,11 @@ async function main() {
                 dry: flags.dry === true,
                 census: typeof flags.census === "string" ? flags.census : undefined,
                 name: typeof flags.name === "string" ? flags.name : undefined,
+                // Only these two words. Anything else is a typo that would silently
+                // invert a system, so it falls through to being measured and asked.
+                scheme: flags.scheme === "dark" || flags.scheme === "light"
+                    ? flags.scheme
+                    : undefined,
                 registry,
             });
             break;

package/package.json

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