synthesisui 0.16.63 → 0.16.66

package/dist/commands/import.js

@@ -1,13 +1,16 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
+import { findBrokenRefs } from "../doctor/broken-refs.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";
+import { describeConvention, detectConventions, IDIOM_LABEL, } from "../doctor/idiom.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
+import { rootClasses, transcribe, } from "../doctor/transcribe.js";
 import { body, paint, section } from "../output.js";
 import { walk, walkAll } from "./doctor.js";
 /**
@@ -273,11 +276,23 @@ export async function takeCensus(root) {
     const tally = emptyTally();
     const internal = await internalSpecifiers(root);
     const defined = [];
+    // Kept for the reference check below, which needs every file at once: a name
+    // is only broken if NOTHING declares it, anywhere.
+    const sources = [];
+    // Name → value for every custom property their CSS declares, which is what
+    // turns `bg-ocean-500` into a token ref instead of a hex we looked up.
+    const declaredValues = new Map();
+    for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:\s*([^;}]+)/g)) {
+        if (!declaredValues.has(m[1]))
+            declaredValues.set(m[1], m[2].trim());
+    }
+    const looks = {};
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
         const rel = relative(root, file);
+        sources.push({ file: rel, source: src });
         reports.push(scanSource(rel, src, table));
         // Stories and tests compose components to SHOW them; counting those as the
         // product's own composition is the same lie the colour census told before
@@ -286,7 +301,20 @@ export async function takeCensus(root) {
             scanComponentsInto(tally, rel, src, internal);
             // The other half: what this file EXPORTS, with the axes its types
             // declare. A library composes almost nothing and exports everything.
-            defined.push(...scanDefinitions(rel, src));
+            const found = scanDefinitions(rel, src);
+            defined.push(...found);
+            // THE LOOK, from their own class names. One transcription per file, keyed
+            // by the component it defines - the root element's classes are the
+            // component's own look, and everything below it is a part this slice does
+            // not attempt.
+            if (found.length > 0) {
+                const t = transcribe(rootClasses(src), declaredValues);
+                const size = Object.keys(t.base).length +
+                    Object.keys(t.dark).length +
+                    Object.keys(t.states).length;
+                if (size > 0)
+                    looks[found[0].name] = t;
+            }
         }
     }
     const d = diagnose(reports);
@@ -368,10 +396,22 @@ export async function takeCensus(root) {
             // an unreadable package.json costs the name, not the run
         }
     }
+    // Every name their CSS defines, from the same harvest the token table came
+    // from - so a reference is judged against what actually exists, not against
+    // the subset we managed to read as a ramp.
+    const declaredNames = new Set();
+    for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g)) {
+        declaredNames.add(m[1]);
+    }
+    const brokenRefs = findBrokenRefs(sources, declaredNames);
+    const conventions = detectConventions(sources);
     return {
         census: 1,
         project: { name, stack: await detectStack(root) },
         declared: Object.fromEntries(table.byName),
+        ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
+        ...(conventions.length > 0 ? { conventions } : {}),
+        ...(Object.keys(looks).length > 0 ? { looks } : {}),
         ...(schemes.alt.size > 0
             ? { declaredAlt: Object.fromEntries(schemes.alt) }
             : {}),
@@ -435,6 +475,55 @@ function summarize(c) {
             console.log(body(`${paint.strong(v.value)} ${paint.faint(`${v.kind}, ${v.count}× in ${v.files} file${v.files === 1 ? "" : "s"}`)}`));
         }
     }
+    sayConventions(c);
+    sayBrokenRefs(c);
+}
+/**
+ * THEIR VOCABULARY, MEASURED. This section exists so every later finding can be
+ * phrased as "you already do X, and here you did not" instead of "adopt ours".
+ */
+function sayConventions(c) {
+    const list = c.conventions ?? [];
+    if (list.length === 0)
+        return;
+    console.log("");
+    console.log(section("How you reference a value"));
+    for (const conv of list) {
+        console.log(body(describeConvention(conv)));
+        const off = conv.offIdiom.filter((o) => o.count > 0).slice(0, 3);
+        if (off.length > 0) {
+            console.log(body(paint.faint(`  and ${off.map((o) => `${o.count} ${IDIOM_LABEL[o.idiom]}`).join(", ")}`)));
+        }
+    }
+    console.log("");
+    console.log(body(paint.faint("Nothing here is a rule we brought. It is what your own files do most, so the rest can be named against it.")));
+}
+/**
+ * NOT DRIFT - BROKEN. A `var()` no declaration answers renders nothing at all,
+ * so this goes above everything else the census has to say. It is also the one
+ * finding that needs no agreement with us: the convention being broken is
+ * theirs.
+ */
+function sayBrokenRefs(c) {
+    const broken = c.brokenRefs ?? [];
+    if (broken.length === 0)
+        return;
+    const uses = broken.reduce((n, b) => n + b.count, 0);
+    console.log("");
+    console.log(section("These resolve to nothing"));
+    console.log(body(`${uses} reference${uses === 1 ? "" : "s"} to ${broken.length} token${broken.length === 1 ? "" : "s"} your CSS never declares. A ${paint.strong("var()")} with no declaration paints no colour - not a different colour.`));
+    console.log("");
+    for (const b of broken.slice(0, 8)) {
+        const where = `${b.count}× in ${b.files} file${b.files === 1 ? "" : "s"}`;
+        console.log(body(b.meant
+            ? `${paint.strong(`var(${b.name})`)} ${paint.faint(where)} - you declare ${paint.strong(b.meant)}`
+            : `${paint.strong(`var(${b.name})`)} ${paint.faint(`${where}, and nothing close is declared`)}`));
+    }
+    if (broken.length > 8) {
+        console.log(body(paint.faint(`(${broken.length - 8} more)`)));
+    }
+    console.log("");
+    console.log(body(paint.faint("Yours to fix in your own words - nothing here asks you to adopt ours.")));
 }
 /**
  * The contract an agent needs, printed where an agent will read it.

package/dist/doctor/broken-refs.js

@@ -0,0 +1,75 @@
+/**
+ * TOKENS REFERENCED AND NEVER DECLARED.
+ *
+ * Not drift, not taste - a variable that resolves to nothing. `var(--ocean-50)`
+ * in a project whose token is `--color-ocean-50` renders no colour at all, and
+ * the component ships with no background.
+ *
+ * Found by accident (dono, 01/08) while sizing something else: seven of nine
+ * references in one real `ImageUploader` were missing the `color-` prefix, and
+ * it is live. Nobody noticed because a missing background looks like a design
+ * choice.
+ *
+ * This is the highest-value thing a first read can say, and it costs nothing to
+ * find: it is arithmetic over two sets. It also needs no adoption of anything of
+ * ours - the convention being violated is THEIRS. A person can act on it in
+ * their own vocabulary, in the next commit, without agreeing to a single idea
+ * this product has (dono, 01/08: "a normalização será de acordo com cada
+ * projeto").
+ */
+/** `var(--x)`, including inside a Tailwind arbitrary value: `bg-[var(--x)]`. */
+const VAR_REF = /var\(\s*(--[a-zA-Z0-9_-]+)/g;
+/**
+ * PREFIXES A DECLARATION MAY CARRY that a reference dropped.
+ *
+ * Tailwind v4's `@theme` is the reason this happens at all: declaring
+ * `--color-ocean-50` publishes the variable under that full name AND the
+ * utility `bg-ocean-50`, so a person who reads their own utilities and then
+ * reaches for `var()` writes the utility's name and gets nothing.
+ */
+const NAMESPACES = [
+    "color",
+    "spacing",
+    "radius",
+    "font",
+    "text",
+    "shadow",
+    "ease",
+    "animate",
+];
+/**
+ * Every reference no declaration answers, commonest first.
+ *
+ * `declared` is the set of names their own CSS defines, verbatim. Anything the
+ * scan could not attribute is left out rather than guessed at.
+ */
+export function findBrokenRefs(sources, declared) {
+    const seen = new Map();
+    for (const { file, source } of sources) {
+        for (const m of source.matchAll(VAR_REF)) {
+            const name = m[1];
+            if (declared.has(name))
+                continue;
+            const hit = seen.get(name) ?? { count: 0, files: new Set() };
+            hit.count += 1;
+            hit.files.add(file);
+            seen.set(name, hit);
+        }
+    }
+    const out = [];
+    for (const [name, hit] of seen) {
+        const bare = name.slice(2);
+        const meant = NAMESPACES.map((ns) => `--${ns}-${bare}`).find((c) => declared.has(c));
+        out.push({
+            name,
+            count: hit.count,
+            files: hit.files.size,
+            ...(meant ? { meant } : {}),
+        });
+    }
+    // A broken reference somebody typed nine times is worse than one typed once,
+    // and one we can name a target for is actionable before one we cannot.
+    return out.sort((a, b) => Number(b.meant != null) - Number(a.meant != null) ||
+        b.count - a.count ||
+        a.name.localeCompare(b.name));
+}

package/dist/doctor/idiom.js

@@ -0,0 +1,132 @@
+/**
+ * HOW THIS PROJECT REFERENCES A VALUE - and it is not one answer per project.
+ *
+ * Measured on a real monorepo (dono, 01/08), scoping by project looked like
+ * divergence and was not: `packages/ui` read 52% `var()` and 39% utility, which
+ * is one directory holding `.tsx` and `.scss` in the same bucket. Split by
+ * LANGUAGE the picture is unambiguous:
+ *
+ *     .tsx    80% tailwind utility
+ *     .scss   66% css var()
+ *     .css    67% css var()
+ *
+ * So the convention belongs to the language, the project is already chosen by
+ * `--scope`, and neither needs a person to pick it - it is measured. What a
+ * person gets instead is the useful half: what does NOT follow the idiom their
+ * own files overwhelmingly use.
+ *
+ * WHY THIS MATTERS MORE THAN OUR TOKENS (dono, 01/08). A report that says "use
+ * `{color.ocean.500}`" asks somebody to restructure a repo to suit us - in a
+ * shadcn project that is a migration with real incompatibility risk and a commit
+ * nobody wants to review. A report that says "you write `bg-ocean-500` in 80% of
+ * your JSX and here you wrote a hex" asks for nothing. Same decision, their
+ * vocabulary, a commit the size of the problem.
+ *
+ * It also explained the worst bug this census has found. `bg-[var(--ocean-50)]`
+ * is not merely a dropped `color-` prefix: it is the CSS idiom used inside the
+ * JSX idiom - a change of language mid-sentence - and the `.scss` beside it
+ * spells the same token correctly, because there that language is the right one.
+ */
+/** How each idiom reads, for the report. */
+export const IDIOM_LABEL = {
+    "tailwind-utility": "Tailwind utility",
+    "css-var": "var(--token)",
+    "raw-hex": "raw hex",
+    "tailwind-arbitrary-var": "var() inside a utility",
+    "shadcn-hsl": "hsl(var(--token))",
+};
+const PATTERNS = [
+    // Order matters where two could match the same text: the shadcn wrapper and
+    // the arbitrary-value form are both `var()` and both more specific than it.
+    ["shadcn-hsl", /hsl\(\s*var\(\s*--/g],
+    [
+        "tailwind-arbitrary-var",
+        /\b(?:bg|text|border|ring|fill|stroke|shadow|from|to|via)-\[var\(\s*--/g,
+    ],
+    [
+        "tailwind-utility",
+        /\b(?:bg|text|border|ring|fill|stroke|from|to|via)-(?:[a-z]+-)+\d{2,3}\b/g,
+    ],
+    ["css-var", /var\(\s*--/g],
+    ["raw-hex", /#[0-9a-fA-F]{6}\b/g],
+];
+/**
+ * Extensions worth reporting separately, because they are separate languages
+ * with separate correct answers. Anything else is counted and not split out.
+ */
+const LANGUAGES = new Set([".tsx", ".jsx", ".scss", ".css", ".less", ".sass"]);
+/**
+ * A custom-property declaration, whose right-hand side is a DEFINITION.
+ * Deliberately not anchored to a line start: these are written inside `:root`,
+ * `@theme` and nested blocks at every indentation.
+ */
+const DECLARATION = /--[a-zA-Z0-9_-]+\s*:[^;}]*/g;
+/**
+ * Count references per language and name the dominant idiom.
+ *
+ * A language with too few references to be conclusive is left out rather than
+ * given a convention on the strength of three sightings: claiming a project's
+ * convention from noise is worse than saying nothing, because every later
+ * finding inherits the claim.
+ */
+export function detectConventions(sources, minReferences = 20) {
+    const byLanguage = new Map();
+    for (const { file, source } of sources) {
+        const dot = file.lastIndexOf(".");
+        const ext = dot === -1 ? "" : file.slice(dot).toLowerCase();
+        if (!LANGUAGES.has(ext))
+            continue;
+        const counts = byLanguage.get(ext) ?? new Map();
+        // A DECLARATION IS NOT A REFERENCE. `--color-ocean-500: #059aed` is where a
+        // hex belongs, and counting it made a design system's own token file read as
+        // 87% raw hex - the worst drift in the repo, when it is the opposite: the one
+        // place every other value should be pointing at (dono, 01/08).
+        let rest = source.replace(DECLARATION, "");
+        // A more specific pattern claims its matches first, so the same text is
+        // never counted twice - `bg-[var(--x)]` is one arbitrary-value reference,
+        // not also a `var()` one.
+        for (const [idiom, re] of PATTERNS) {
+            const found = rest.match(re);
+            if (!found)
+                continue;
+            counts.set(idiom, (counts.get(idiom) ?? 0) + found.length);
+            rest = rest.replace(re, "");
+        }
+        byLanguage.set(ext, counts);
+    }
+    const out = [];
+    for (const [language, counts] of byLanguage) {
+        const total = [...counts.values()].reduce((n, v) => n + v, 0);
+        if (total < minReferences)
+            continue;
+        const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+        const [idiom, top] = ranked[0];
+        out.push({
+            language,
+            idiom,
+            share: top / total,
+            total,
+            offIdiom: ranked.slice(1).map(([i, count]) => ({ idiom: i, count })),
+        });
+    }
+    return out.sort((a, b) => b.total - a.total);
+}
+/**
+ * One line per language, in the report's voice and in THEIR vocabulary.
+ *
+ * A raw hex winning is NOT a convention. It is the absence of one, and saying
+ * "this language reaches for raw hex" dignifies it into a house style somebody
+ * might defend - when what the number means is that nothing there points at
+ * anything (dono, 01/08).
+ */
+export function describeConvention(c) {
+    const pct = Math.round(c.share * 100);
+    if (c.idiom === "raw-hex") {
+        return `${c.language} has no convention - ${pct}% of its ${c.total} references are values typed in place`;
+    }
+    return `${c.language} reaches for ${IDIOM_LABEL[c.idiom]} - ${pct}% of the ${c.total} references in it`;
+}
+/** True when this language's dominant answer is "no answer". */
+export function hasConvention(c) {
+    return c.idiom !== "raw-hex";
+}

package/dist/doctor/transcribe.js

@@ -0,0 +1,323 @@
+/**
+ * TRANSCRIBE A COMPONENT'S LOOK - deterministically, from their own class names.
+ *
+ * The import brings exclusive components in as contracts: axes declared, every
+ * style block empty. That was right when the alternative was inventing a look
+ * from a name. It is not right when the look is sitting in the file, spelled in
+ * a vocabulary we can read exactly.
+ *
+ * Measured before building any of this (dono, 01/08): across 23 exclusive
+ * components, 217 of 326 colour values resolve directly against their own
+ * declared tokens, and another 106 are Tailwind defaults - a fixed, published
+ * table. 99% is arithmetic. Nine of the 23 are entirely resolvable, and a single
+ * `TextEditor` holds 72% of all the ambiguity there is.
+ *
+ * So this is a transcriber, not a generator. No AI, no cost, no quota, and no
+ * chance of a value nobody wrote: every declaration it emits either points at a
+ * token they declared or carries a literal they typed.
+ *
+ * WHY NOT `refit`. That endpoint already turns arbitrary component code into a
+ * token-only recipe, and it is the right tool for its own job - bringing in
+ * code from OUTSIDE and dressing it in a system. But it maps every value to the
+ * NEAREST allowed token and never emits a raw one, which is normalisation, and
+ * v1 is a mirror. It also costs credits and has a daily quota, and a first
+ * import would spend 23 of them before anybody has seen value. It stays where
+ * it is; this runs first, for free, on what is already theirs.
+ *
+ * THE MODIFIER SAYS WHERE THE VALUE GOES, which is what makes this tractable:
+ *
+ *     bg-white                  → base
+ *     dark:bg-darkgray-500      → the dark side of base
+ *     hover:shadow-md           → states.hover
+ *     data-[checked]:bg-ocean-50 → states.checked
+ */
+/**
+ * Utility prefix → CSS property. Only the ones that carry DESIGN, which is the
+ * whole point: `flex`, `items-center` and `w-full` are structure, they are
+ * identical in every design system, and a recipe carrying them would be
+ * transcribing layout rather than a look.
+ */
+const COLOR_PROPERTY = {
+    bg: "background-color",
+    text: "color",
+    border: "border-color",
+    ring: "outline-color",
+    fill: "fill",
+    stroke: "stroke",
+    decoration: "text-decoration-color",
+};
+/** Tailwind's own spacing scale, in rem - the fixed part of the fixed table. */
+const SPACING = {
+    "0": "0",
+    px: "1px",
+    "0.5": "0.125rem",
+    "1": "0.25rem",
+    "1.5": "0.375rem",
+    "2": "0.5rem",
+    "2.5": "0.625rem",
+    "3": "0.75rem",
+    "3.5": "0.875rem",
+    "4": "1rem",
+    "5": "1.25rem",
+    "6": "1.5rem",
+    "7": "1.75rem",
+    "8": "2rem",
+    "9": "2.25rem",
+    "10": "2.5rem",
+    "11": "2.75rem",
+    "12": "3rem",
+    "14": "3.5rem",
+    "16": "4rem",
+    "20": "5rem",
+    "24": "6rem",
+};
+const SPACING_PROPERTY = {
+    p: "padding",
+    px: "padding-inline",
+    py: "padding-block",
+    pt: "padding-top",
+    pr: "padding-right",
+    pb: "padding-bottom",
+    pl: "padding-left",
+    m: "margin",
+    mx: "margin-inline",
+    my: "margin-block",
+    gap: "gap",
+};
+/** Tailwind's radius scale. */
+const RADIUS = {
+    none: "0",
+    sm: "0.125rem",
+    "": "0.25rem",
+    md: "0.375rem",
+    lg: "0.5rem",
+    xl: "0.75rem",
+    "2xl": "1rem",
+    "3xl": "1.5rem",
+    full: "9999px",
+};
+/** Tailwind's own colour table, for the values a project uses without declaring.
+ *  Only the ones that actually turn up: white, black, and the neutral ramp a
+ *  real project reached for 106 times. */
+const TAILWIND_COLOR = {
+    white: "#ffffff",
+    black: "#000000",
+    transparent: "transparent",
+    "neutral-50": "#fafafa",
+    "neutral-100": "#f5f5f5",
+    "neutral-200": "#e5e5e5",
+    "neutral-300": "#d4d4d4",
+    "neutral-400": "#a3a3a3",
+    "neutral-500": "#737373",
+    "neutral-600": "#525252",
+    "neutral-700": "#404040",
+    "neutral-800": "#262626",
+    "neutral-900": "#171717",
+    "neutral-950": "#0a0a0a",
+};
+/** States we recognise. Anything else is skipped rather than invented. */
+const STATE = /^(hover|focus|focus-visible|active|disabled|checked)$/;
+const DATA_STATE = /^data-\[([a-z-]+)\]$/;
+/**
+ * Split a class into its modifiers and the utility itself.
+ *
+ * Arbitrary values can contain colons (`bg-[url(a:b)]`), so the split stops at
+ * the first bracket - a naive split on `:` would shred them.
+ */
+export function parseClass(cls) {
+    // Bracket-aware, because BOTH sides use them: `data-[checked]:` is a modifier
+    // that contains one and `bg-[url(a:b)]` is a value that contains a colon. A
+    // first attempt stopped at the first `[`, which swallowed every `data-[…]:`
+    // modifier whole and dropped the state it named.
+    const modifiers = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < cls.length; i++) {
+        const ch = cls[i];
+        if (ch === "[")
+            depth += 1;
+        else if (ch === "]")
+            depth -= 1;
+        else if (ch === ":" && depth === 0) {
+            modifiers.push(cls.slice(start, i));
+            start = i + 1;
+        }
+    }
+    return { modifiers, utility: cls.slice(start) };
+}
+/**
+ * One utility → one declaration, or nothing.
+ *
+ * `declared` maps a token NAME to its value, so a resolved colour can be
+ * reported in their vocabulary rather than as a hex we looked up.
+ */
+export function readUtility(utility, declared) {
+    // An opacity modifier changes the value, not the property, and honouring it
+    // would mean computing a colour they never wrote. The property still belongs
+    // in the recipe, so the base colour travels and the alpha does not.
+    const [core] = utility.split("/");
+    const dash = core.indexOf("-");
+    if (dash === -1)
+        return null;
+    const prefix = core.slice(0, dash);
+    const rest = core.slice(dash + 1);
+    const colorProp = COLOR_PROPERTY[prefix];
+    if (colorProp) {
+        // Their own token first: `--color-ocean-500` for `bg-ocean-500`, which is
+        // exactly how Tailwind v4's `@theme` publishes it.
+        const own = `--color-${rest}`;
+        if (declared.has(own)) {
+            return { property: colorProp, value: refFor(rest), token: own };
+        }
+        const builtin = TAILWIND_COLOR[rest];
+        if (builtin)
+            return { property: colorProp, value: builtin };
+        return null;
+    }
+    const spaceProp = SPACING_PROPERTY[prefix];
+    if (spaceProp && SPACING[rest]) {
+        return { property: spaceProp, value: SPACING[rest] };
+    }
+    if (prefix === "rounded") {
+        const own = `--radius-${rest}`;
+        if (declared.has(own)) {
+            return {
+                property: "border-radius",
+                value: `{radius.${rest}}`,
+                token: own,
+            };
+        }
+        if (RADIUS[rest])
+            return { property: "border-radius", value: RADIUS[rest] };
+    }
+    return null;
+}
+/**
+ * A colour token ref in the document's own spelling.
+ *
+ * `ocean-500` → `{color.ocean.500}`. The step is the trailing number; anything
+ * before it is the family, hyphens intact, because `royal-blue-500` is one
+ * family called `royal-blue`.
+ */
+function refFor(name) {
+    const m = /^(.*)-(\d{2,4})$/.exec(name);
+    if (!m)
+        return `{color.${name}}`;
+    return `{color.${m[1]}.${m[2]}}`;
+}
+/**
+ * Read every class in a component's root element and route each declaration by
+ * its modifier.
+ *
+ * Unknown modifiers are skipped, not flattened into `base`: a `sm:` or
+ * `group-data-[checked]:` value written into the resting state would be a look
+ * the component never has.
+ */
+export function transcribe(classes, declared) {
+    const out = {
+        base: {},
+        states: {},
+        dark: {},
+        skipped: [],
+        fromToken: 0,
+        fromLiteral: 0,
+    };
+    for (const cls of classes) {
+        const { modifiers, utility } = parseClass(cls);
+        const isDark = modifiers.includes("dark");
+        const rest = modifiers.filter((m) => m !== "dark");
+        // THE SLOT IS DECIDED BEFORE THE VALUE IS READ. Resolving first meant a
+        // `dark:hover:` whose colour happened to be undeclared vanished in silence
+        // rather than being reported as a look we have nowhere to put - two
+        // different problems, and only one of them is theirs to hear about.
+        let target = null;
+        let unslotted = false;
+        if (rest.length === 0) {
+            target = isDark ? out.dark : out.base;
+        }
+        else if (rest.length === 1 && !isDark) {
+            const state = STATE.test(rest[0])
+                ? rest[0]
+                : (DATA_STATE.exec(rest[0])?.[1] ?? null);
+            if (state)
+                target = out.states[state] ?? (out.states[state] = {});
+            else
+                unslotted = true;
+        }
+        else {
+            // A state under `dark:` is the dark scheme's version of that state, and a
+            // recipe has no slot for it.
+            unslotted = true;
+        }
+        const decl = readUtility(utility, declared);
+        if (unslotted) {
+            // Only worth saying when it IS a design value; an unslotted `sm:flex` is
+            // layout and nobody needs to hear about it.
+            if (decl)
+                out.skipped.push(cls);
+            continue;
+        }
+        if (!decl || !target)
+            continue;
+        // First write wins, matching how a class list resolves for the properties
+        // we read: later duplicates in the same list are almost always a merge
+        // artefact rather than an override.
+        if (target[decl.property] != null)
+            continue;
+        target[decl.property] = decl.value;
+        if (decl.token)
+            out.fromToken += 1;
+        else
+            out.fromLiteral += 1;
+    }
+    return out;
+}
+/**
+ * THE ROOT ELEMENT'S CLASSES, from a component file.
+ *
+ * A component's look lives on the outermost element it returns, and everything
+ * below it is a part - which a recipe has slots for and this slice does not
+ * attempt. Finding the root without an AST: the first JSX tag after `return (`
+ * is it, and its class list runs to the first `>` at depth zero.
+ *
+ * Deliberately conservative. A file this cannot read confidently returns
+ * nothing, and nothing is a contract with an empty base - which is exactly what
+ * the import already produces, so failing here costs no ground.
+ */
+export function rootClasses(source) {
+    const ret = source.search(/return\s*\(/);
+    if (ret === -1)
+        return [];
+    const open = source.indexOf("<", ret);
+    if (open === -1)
+        return [];
+    // Walk to the end of the opening tag, tracking brackets so a `className={cn(
+    // "a", cond ? "b" : "c")}` block is read whole rather than cut at its first
+    // `>` inside a comparison.
+    let depth = 0;
+    let end = -1;
+    for (let i = open + 1; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === "{" || ch === "(" || ch === "[")
+            depth += 1;
+        else if (ch === "}" || ch === ")" || ch === "]")
+            depth -= 1;
+        else if (ch === ">" && depth <= 0) {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return [];
+    const tag = source.slice(open, end);
+    const at = tag.search(/className\s*=/);
+    if (at === -1)
+        return [];
+    // Every string literal inside the className expression. Template literals and
+    // computed values are skipped on purpose: a class we cannot see in full is a
+    // class we would be guessing at.
+    const expr = tag.slice(at);
+    return [...expr.matchAll(/["']([^"']+)["']/g)]
+        .flatMap((m) => m[1].split(/\s+/))
+        .filter((c) => c.length > 0 && !c.includes("${"));
+}

package/package.json

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