synthesisui 0.16.92 → 0.16.94

package/dist/commands/import.js

@@ -4,7 +4,7 @@ import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { architectureRule, describeArchitecture, describeChoice, detectArchitectures, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
-import { nestingRules, propRules, readDefinitionProps, readNesting, } from "../doctor/call-sites.js";
+import { nestingRules, propRules, readDefinitionProps, readNesting, readRuntime, } from "../doctor/call-sites.js";
 import { asCatalogueTable, describeFallback, fetchCatalogue, } from "../doctor/catalogue-fetch.js";
 import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
 import { isNearDuplicate, isNeutral, lightness, } from "../doctor/color-distance.js";
@@ -293,6 +293,10 @@ export async function takeCensus(root, opts) {
      * filtering them takes the vitrine from 271 to 29 (dono, 01/08).
      */
     const screensOf = new Map();
+    /** Quem é dono do estado de cada componente, lido da definição. */
+    const runtimeOf = new Map();
+    /** Em quais projetos (--usage roots) cada componente aparece. */
+    const projectsOf = new Map();
     /** Component → the axes its own `cva` declares. See `variant-read.ts`. */
     const variantAxes = new Map();
     /** How much came out of CSS Modules, for the coverage report. */
@@ -376,7 +380,11 @@ export async function takeCensus(root, opts) {
                 });
             }
             for (const d of found) {
-                propsOf.set(d.name, readDefinitionProps(d.name, src));
+                const props = readDefinitionProps(d.name, src);
+                propsOf.set(d.name, props);
+                const runtime = readRuntime(props, src);
+                if (Object.keys(runtime).length > 0)
+                    runtimeOf.set(d.name, runtime);
             }
             if (found.length > 0) {
                 countShape(src, found[0].name, shapes);
@@ -388,7 +396,30 @@ export async function takeCensus(root, opts) {
             // 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);
+                /**
+                 * EVERY COMPONENT THE FILE DEFINES, not just the first.
+                 *
+                 * One file in a real library defines two - `RadioCard` and
+                 * `RadioCardGroup` - and the second arrived with an empty base while its
+                 * `flex flex-col gap-3` sat six lines below the first component's return
+                 * (audit, dono, 01/08). The file-level readings (the CSS module, the
+                 * variant tables) belong to the PRIMARY definition; the root classes and
+                 * the root tag are per component, scoped by name.
+                 */
+                for (const extra of found.slice(1)) {
+                    const et = transcribe(rootClasses(src, extra.name), declaredValues);
+                    const etag = rootTag(src, extra.name);
+                    const esize = Object.keys(et.base).length +
+                        Object.keys(et.dark).length +
+                        Object.keys(et.states).length;
+                    if (esize > 0 || etag) {
+                        looks[extra.name] = {
+                            ...et,
+                            ...(etag ? { rootTag: etag } : {}),
+                        };
+                    }
+                }
+                const t = transcribe(rootClasses(src, found[0].name), declaredValues);
                 /**
                  * THE VARIANT STYLES, FOLDED IN.
                  *
@@ -472,7 +503,7 @@ export async function takeCensus(root, opts) {
                     Object.keys(states).length +
                     Object.keys(parts).length +
                     layers.length;
-                const tag = rootTag(src);
+                const tag = rootTag(src, found[0].name);
                 /**
                  * THE SKETCH travels with the look, so the reading phase never opens this
                  * file again: naming parts is a sentence over data the census already holds,
@@ -598,6 +629,17 @@ export async function takeCensus(root, opts) {
             usageSeen.add(rel);
             usageProgress?.step(rel);
             scanComponentsInto(usageTally, rel, src, [...shared, ...uInternal]);
+            // WHERE THE PAIRS LIVE. A library composes almost none of itself inside
+            // itself - `Button` goes inside `Modal` in the APP, not in the library
+            // source - so measuring nesting only on the defined loop reported zero
+            // companions on a 128-component library (e2e, 01/08).
+            readNesting(rel, src, nesting);
+            // Which PROJECT composes it - the credibility panel's number, per root.
+            for (const m of src.matchAll(/<([A-Z][A-Za-z0-9_]*)/g)) {
+                const at = projectsOf.get(m[1]) ?? new Set();
+                at.add(u.label);
+                projectsOf.set(m[1], at);
+            }
         }
     }
     usageProgress?.done();
@@ -907,10 +949,30 @@ export async function takeCensus(root, opts) {
     for (const pair of nestingRules(nesting, systemOwns)) {
         laws.set(pair.component, [...(laws.get(pair.component) ?? []), pair.text]);
     }
+    /**
+     * OS ENCAIXES, ESTRUTURADOS. nestingRules já media os pares e virava só prosa -
+     * prosa não é clicável nem consultável (dono, 01/08). O slug segue a mesma
+     * kebab-ização que o contrato usa.
+     */
+    const companionsOf = new Map();
+    for (const pair of nestingRules(nesting, systemOwns)) {
+        const kebab = (n) => n.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+        const list = companionsOf.get(pair.component) ?? [];
+        if (!list.includes(kebab(pair.child)))
+            list.push(kebab(pair.child));
+        companionsOf.set(pair.component, list);
+    }
     const components = merged.map((c) => ({
         ...c,
         ...(verdicts.get(c.name) ?? {}),
         ...(laws.has(c.name) ? { laws: laws.get(c.name) } : {}),
+        ...(runtimeOf.has(c.name) ? { runtime: runtimeOf.get(c.name) } : {}),
+        ...(companionsOf.has(c.name)
+            ? { companions: companionsOf.get(c.name) }
+            : {}),
+        ...(projectsOf.has(c.name)
+            ? { projects: [...(projectsOf.get(c.name) ?? [])] }
+            : {}),
     }));
     const pkgRaw = await readFile(join(root, "package.json"), "utf8").catch(() => null);
     let name = null;

package/dist/commands/mcp.js

@@ -1,5 +1,5 @@
-import { readFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
@@ -340,6 +340,54 @@ async function validateRecipe(name, recipe) {
  * a published package can be read by anyone, and it goes stale - the crosswalk's own copy
  * had 26 names against a catalogue of 41.
  */
+/**
+ * O CONTADOR DO AGENTE, fire-and-forget: a tela do UI Kit mostra "vezes que esta receita
+ * foi consultada pelo Agente", e este é o único ponto onde a consulta acontece de
+ * verdade. Nunca bloqueia a resposta: sem sessão ou sem rede, não conta e não quebra -
+ * telemetria que atrasa a ferramenta é telemetria que alguém desliga.
+ */
+function countAgentRead(root, component, action) {
+    void (async () => {
+        try {
+            const token = await readToken();
+            if (!token || !component)
+                return;
+            // O slug vem do .lock do sistema instalado - a mesma resolução do sync.
+            const dsDir = join(root, "_synthesisui", "ds");
+            let slug = null;
+            const entries = await readdir(dsDir, { withFileTypes: true }).catch(() => []);
+            for (const e of entries) {
+                if (!e.isDirectory())
+                    continue;
+                const raw = await readFile(join(dsDir, e.name, ".lock"), "utf8").catch(() => "");
+                try {
+                    const lock = JSON.parse(raw);
+                    if (lock.slug) {
+                        slug = lock.slug;
+                        break;
+                    }
+                }
+                catch {
+                    // lock ilegível - tenta o próximo
+                }
+            }
+            if (!slug)
+                return;
+            const base = resolveRegistry();
+            await fetch(`${base}/api/telemetry/agent-read`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({ slug, component, action }),
+            });
+        }
+        catch {
+            // offline não conta e não quebra nada
+        }
+    })();
+}
 async function askCatalogue(want, post) {
     const token = await readToken();
     if (!token) {
@@ -399,6 +447,42 @@ async function describeComponent(root, name) {
                 ? "A molecule in your own ladder - built out of your atoms, so reach for those inside it."
                 : "An organism in your own ladder - a whole region of a screen, so it is more likely to be composed than to be composed into.");
     }
+    /**
+     * O ESTADO, ANTES DO CÓDIGO. Um agente que não sabe quem é dono do estado inventa:
+     * um Toggle controlado ganha useState interno, um Input não-controlado ganha value
+     * sem onChange (dono, 01/08). Isto é a receita dizendo o comportamento.
+     */
+    if (recipe.runtime) {
+        const r = recipe.runtime;
+        const lines = [];
+        if (r.stateOwner === "caller") {
+            lines.push("State: the CALLER owns it - controlled only. Wire the pair below; do not add internal state.");
+        }
+        else if (r.stateOwner === "self") {
+            lines.push("State: the component manages itself. Do not wire external state unless you need to read it.");
+        }
+        else if (r.stateOwner === "either") {
+            lines.push("State: both modes. Pass the controlled pair to own it, or the default* prop to seed it and let the component manage.");
+        }
+        for (const c of r.controlled ?? []) {
+            lines.push(`  controlled: ${c.prop} + ${c.event}`);
+        }
+        if ((r.uncontrolled ?? []).length > 0) {
+            lines.push(`  uncontrolled seed: ${(r.uncontrolled ?? []).join(", ")}`);
+        }
+        for (const n of r.notes ?? [])
+            lines.push(`  ${n}`);
+        if (lines.length > 0)
+            out.push("", ...lines);
+    }
+    /** OS ENCAIXES - o que costuma ir junto, medido ou derivado dos layouts. */
+    if ((recipe.companions ?? []).length > 0) {
+        out.push("", `Goes with: ${(recipe.companions ?? []).join(", ")} - measured pairings; call describe_component on one before composing them together.`);
+    }
+    if (recipe.usageStats && recipe.usageStats.count > 0) {
+        const u = recipe.usageStats;
+        out.push("", `In use: ${u.count} instance${u.count === 1 ? "" : "s"} across ${u.files} file${u.files === 1 ? "" : "s"}${u.projects?.length ? ` in ${u.projects.join(", ")}` : ""}.`);
+    }
     // WHAT IT SITS ON. 17 of 23 components in a real library carry no surface of
     // their own, because the surface belongs to what they return.
     const p = recipe.preview;
@@ -492,8 +576,10 @@ async function callTool(root, name, args) {
         case "list_components":
             return text(await listComponents(root));
         case "describe_component":
+            countAgentRead(root, String(args.name ?? ""), "describe");
             return text(await describeComponent(root, String(args.name ?? "")));
         case "add_component":
+            countAgentRead(root, String(args.name ?? ""), "add");
             return text(await addComponent(root, String(args.name ?? "")));
         case "recipe_vocabulary":
             return text(await recipeVocabulary());

package/dist/doctor/call-sites.js

@@ -37,7 +37,7 @@
  * version tried to consume the arrow, and `([^)]*)` swallowed the destructure it was
  * trying to reach, so every arrow component read as declaring no props (spec, 01/08).
  */
-const DESTRUCTURED = /(?:function\s+([A-Z][A-Za-z0-9_]*)\s*\(\s*\{([^}]*)\}|(?:const|let)\s+([A-Z][A-Za-z0-9_]*)\s*(?::[^=]*)?=\s*(?:function\s*)?\(\s*\{([^}]*)\})/g;
+const DESTRUCTURED = /(?:function\s+([A-Z][A-Za-z0-9_]*)\s*\(\s*\{([^}]*)\}|(?:const|let)\s+([A-Z][A-Za-z0-9_]*)\s*(?::[^=]*)?=\s*(?:function\s*)?\(\s*\{([^}]*)\}|(?:const|let)\s+([A-Z][A-Za-z0-9_]*)\s*=\s*(?:React\.)?(?:forwardRef|memo)(?:<[^>]*>)?\s*\(\s*(?:function\s*[A-Za-z0-9_]*\s*)?\(\s*\{([^}]*)\})/g;
 /** `{...rest}` / `{...props}` on a JSX element - the forwarding, in the markup. */
 const SPREAD_ONTO = /\{\s*\.\.\.\s*([A-Za-z_$][\w$]*)\s*\}/g;
 /**
@@ -62,13 +62,16 @@ export function readDefinitionProps(name, source) {
      */
     DESTRUCTURED.lastIndex = 0;
     const matches = [...source.matchAll(DESTRUCTURED)];
-    const exact = matches.filter((m) => (m[1] ?? m[3]) === name);
+    // The third alternative is the forwardRef-inline idiom: a real Toggle is
+    // `const Toggle = React.forwardRef<…>(({ checked, onCheckedChange, … }, ref) =>`,
+    // and both earlier shapes read past it (test16, 01/08).
+    const exact = matches.filter((m) => (m[1] ?? m[3] ?? m[5]) === name);
     const prefixed = matches.filter((m) => {
-        const found = m[1] ?? m[3];
+        const found = m[1] ?? m[3] ?? m[5];
         return found !== name && found?.startsWith(name);
     });
     for (const m of exact.length > 0 ? exact : prefixed) {
-        const body = m[2] ?? m[4] ?? "";
+        const body = m[2] ?? m[4] ?? m[6] ?? "";
         for (const raw of body.split(",")) {
             const part = raw.trim();
             if (!part)
@@ -187,3 +190,48 @@ export function propRules(name, read) {
     }
     return out;
 }
+/**
+ * WHO OWNS THE STATE - read off the definition, deterministically.
+ *
+ * The recipe said everything about the LOOK and nothing about behaviour, so an agent
+ * writing code in the client invented it: a controlled Toggle grew an internal
+ * useState, an uncontrolled Input got a value with no onChange (dono, 01/08). The
+ * patterns are machine-readable in the props themselves:
+ *
+ *     checked + onChange          the CONTROLLED pair - the caller owns the state
+ *     defaultOpen, defaultValue   the UNCONTROLLED seed - the component owns it
+ *     useState in the body        the component manages something itself
+ *
+ * `either` is both at once, which is exactly how a well-made input is written.
+ */
+export function readRuntime(read, source) {
+    const props = new Set(read.explicit);
+    const controlled = [];
+    for (const prop of read.explicit) {
+        if (/^(on[A-Z]|default[A-Z])/.test(prop))
+            continue;
+        const cap = prop[0].toUpperCase() + prop.slice(1);
+        // `checked`+`onChange` is the DOM's own spelling; `open`+`onOpenChange` is the
+        // primitive libraries'. Both are the same claim.
+        const event = [`on${cap}Change`, "onChange", `on${cap}`].find((e) => props.has(e));
+        if (event)
+            controlled.push({ prop, event });
+    }
+    const uncontrolled = read.explicit.filter((p) => /^default[A-Z]/.test(p));
+    const managesItself = /\buseState\s*[<(]/.test(source);
+    const out = {};
+    if (controlled.length > 0)
+        out.controlled = controlled;
+    if (uncontrolled.length > 0)
+        out.uncontrolled = uncontrolled;
+    if (controlled.length > 0 && (uncontrolled.length > 0 || managesItself)) {
+        out.stateOwner = "either";
+    }
+    else if (controlled.length > 0) {
+        out.stateOwner = "caller";
+    }
+    else if (managesItself || uncontrolled.length > 0) {
+        out.stateOwner = "self";
+    }
+    return out;
+}

package/dist/doctor/sketch.js

@@ -23,6 +23,56 @@ import { scanTags } from "./css-modules.js";
 const MAX_NODES = 60;
 /** `className="..."` or className={"..."} / {`...`} with no interpolation. */
 const CLASS_ATTR = /className=\{?["'`]([^"'`{}$]*)["'`]\}?/;
+/**
+ * `className={cn("a b", "c", cond && "d", record[x])}` - the STATIC strings.
+ *
+ * The plain-attr regex above sees a call expression and reads nothing, and
+ * 19 of 36 components in a real library style exactly this way - so their
+ * elements arrived in the sketch with no classes at all, and the Tooltip's
+ * popup carried none when the base had to be transcribed by hand
+ * (not-expressed.md, dono, 01/08). The always-on string arguments ARE the
+ * element's resting classes; the conditional halves are variants, which the
+ * variant readers already read - so only TOP-LEVEL string literals count.
+ * Template literals with `${}` and computed values stay out: a class we
+ * cannot see in full is a class we would be guessing at.
+ *
+ * THE NAMESPACE COUNTS. Measured on the real library: 64 calls are a bare
+ * `cn(`, 11 are `twUtils.cn(` and 2 are `clsx(` - and the first version of this
+ * regex read only the bare form, so a Modal's whole surface (its fill, border,
+ * radius and padding) stayed invisible while its siblings read fine
+ * (e2e, dono, 01/08).
+ */
+const CLASS_CALL = /className=\{\s*(?:[A-Za-z_$][\w$]*\.)?(?:cn|clsx|classNames|cx|twMerge|twJoin|classcat)\(/;
+function staticCallClasses(body) {
+    const call = CLASS_CALL.exec(body);
+    if (!call)
+        return null;
+    const start = call.index + call[0].length;
+    // Walk the call's arguments at depth 0, collecting bare string literals.
+    let depth = 1;
+    let argStart = start;
+    const args = [];
+    for (let i = start; i < body.length && depth > 0; i++) {
+        const ch = body[i];
+        if (ch === "(" || ch === "{" || ch === "[")
+            depth += 1;
+        else if (ch === ")" || ch === "}" || ch === "]") {
+            depth -= 1;
+            if (depth === 0)
+                args.push(body.slice(argStart, i));
+        }
+        else if (ch === "," && depth === 1) {
+            args.push(body.slice(argStart, i));
+            argStart = i + 1;
+        }
+    }
+    const classes = args
+        .map((a) => a.trim())
+        .filter((a) => /^(["'`]).*\1$/.test(a) && !a.includes("${"))
+        .map((a) => a.slice(1, -1).trim())
+        .filter(Boolean);
+    return classes.length > 0 ? classes.join(" ") : null;
+}
 /**
  * The sketch of one component file.
  *
@@ -47,6 +97,11 @@ export function sketchOf(source) {
         const cls = CLASS_ATTR.exec(event.body);
         if (cls?.[1].trim())
             node.classes = cls[1].trim();
+        else {
+            const called = staticCallClasses(event.body);
+            if (called)
+                node.classes = called;
+        }
         // Literal text: the slice between this open and the next event, when it is prose.
         const next = events[i + 1];
         if (next) {

package/dist/doctor/transcribe.js

@@ -1090,15 +1090,40 @@ export function transcribe(classes, declared) {
  * which is still a signal, just a weaker one, so it travels as written and the
  * platform decides what to do with it.
  */
-export function rootTag(source) {
-    const ret = source.search(/return\s*\(/);
+/**
+ * WHERE *THIS* COMPONENT'S `return (` IS.
+ *
+ * Both readers below took the FIRST `return (` in the file, which is right for
+ * the 34 files that define one component and wrong for the one that defines
+ * two: `RadioCard.tsx` exports `RadioCard` and `RadioCardGroup`, and the group
+ * - a real `flex flex-col gap-3` - arrived with an empty base and the screen
+ * said "Not written yet" over it (audit, dono, 01/08).
+ *
+ * Scoped by NAME when a name is given: find that declaration, then its return.
+ * Absent or unfound, the old behaviour stands exactly - which keeps every
+ * single-component file reading byte-identically.
+ */
+function returnAt(source, name) {
+    if (name) {
+        const decl = new RegExp(`(?:function|const|let|var)\\s+${name}\\b|${name}\\s*[:=]\\s*(?:function|\\()`).exec(source);
+        if (decl) {
+            const from = source.slice(decl.index);
+            const ret = from.search(/return\s*\(/);
+            if (ret !== -1)
+                return decl.index + ret;
+        }
+    }
+    return source.search(/return\s*\(/);
+}
+export function rootTag(source, name) {
+    const ret = returnAt(source, name);
     if (ret === -1)
         return null;
     const m = /<([A-Za-z][A-Za-z0-9.]*)/.exec(source.slice(ret));
     return m ? m[1] : null;
 }
-export function rootClasses(source) {
-    const ret = source.search(/return\s*\(/);
+export function rootClasses(source, name) {
+    const ret = returnAt(source, name);
     if (ret === -1)
         return [];
     const open = source.indexOf("<", ret);

package/package.json

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