synthesisui 0.16.92 → 0.16.93

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);
@@ -598,6 +606,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 +926,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/package.json

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