synthesisui 0.16.91 → 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";
@@ -18,6 +18,7 @@ import { describeConvention, describeRemainder, detectConventions, } from "../do
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
+import { sketchOf } from "../doctor/sketch.js";
 import { buildTable } from "../doctor/tokens.js";
 import { readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
@@ -292,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. */
@@ -375,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);
@@ -472,8 +481,16 @@ export async function takeCensus(root, opts) {
                     Object.keys(parts).length +
                     layers.length;
                 const tag = rootTag(src);
+                /**
+                 * 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,
+                 * and a file read whose content is here is a pipeline optimization failure -
+                 * the owner's rule, adopted verbatim (dono, 01/08).
+                 */
+                const sketch = sketchOf(src);
                 if (size > 0 || tag) {
                     looks[found[0].name] = {
+                        ...(sketch.length > 0 ? { sketch } : {}),
                         ...t,
                         base,
                         states,
@@ -589,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();
@@ -898,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/dist/doctor/css-modules.js

@@ -267,7 +267,7 @@ function looksLikeTypeArg(source, at) {
     }
     return false;
 }
-function scanTags(source) {
+export function scanTags(source) {
     const out = [];
     for (let i = 0; i < source.length; i++) {
         if (source[i] !== "<")

package/dist/doctor/sketch.js

@@ -0,0 +1,68 @@
+/**
+ * THE ANATOMY SKETCH - the component's own markup, carried by the census so nobody
+ * reads the file twice.
+ *
+ * The owner's directive, verbatim in intent (dono, 01/08): the census is the ONLY
+ * source of truth about the project's tree; iterative per-layer sweeps are forbidden;
+ * and any file read whose content the census already carries is a pipeline
+ * optimization failure. The reading phase was the last consumer of raw files - it
+ * opened every component to see its JSX before naming parts, which is most of the
+ * tokens and most of the minutes of a run.
+ *
+ * The sketch is everything that reading extracted, minus the one thing that is
+ * genuinely a judgment: the NAMES. Tag, class string, depth, text, and the
+ * capitalised frontiers, per element, in document order. A reader holding this names
+ * `trigger`/`status-dot`/`panel` without opening anything - and naming is a sentence,
+ * not a sweep.
+ *
+ * GENERALIZED BY CONSTRUCTION: it reads JSX shape, not folder layout, so it works the
+ * same in an atomic library, a feature-foldered app, or a single flat directory.
+ */
+import { scanTags } from "./css-modules.js";
+/** Past this a component is a page in disguise, and the gate already said no. */
+const MAX_NODES = 60;
+/** `className="..."` or className={"..."} / {`...`} with no interpolation. */
+const CLASS_ATTR = /className=\{?["'`]([^"'`{}$]*)["'`]\}?/;
+/**
+ * The sketch of one component file.
+ *
+ * Depth comes from the same tag scanner the CSS-module reader trusts (brace-counting,
+ * quote-aware, type-argument-proof). Text is captured only when it is a short literal
+ * sitting directly between an open and its close - dynamic children are the caller's,
+ * and the slot form already says so.
+ */
+export function sketchOf(source) {
+    const events = scanTags(source);
+    const out = [];
+    let depth = 0;
+    for (let i = 0; i < events.length; i++) {
+        const event = events[i];
+        if (event.kind === "close") {
+            depth = Math.max(0, depth - 1);
+            continue;
+        }
+        if (out.length >= MAX_NODES)
+            break;
+        const node = { tag: event.tag, depth };
+        const cls = CLASS_ATTR.exec(event.body);
+        if (cls?.[1].trim())
+            node.classes = cls[1].trim();
+        // Literal text: the slice between this open and the next event, when it is prose.
+        const next = events[i + 1];
+        if (next) {
+            const between = source
+                .slice(event.at + event.tag.length, next.at)
+                .replace(/^[^>]*>/, "")
+                .trim();
+            if (between &&
+                between.length <= 60 &&
+                !between.includes("{") &&
+                !between.includes("<")) {
+                node.text = between;
+            }
+        }
+        out.push(node);
+        depth += 1;
+    }
+    return out;
+}

package/dist/doctor/transcribe.js

@@ -610,6 +610,20 @@ export function readUtility(utility, declared) {
             if (size)
                 return { property: axisProp, value: size };
         }
+        /**
+         * THEIR OWN SPACING STEP IS A LIVE UTILITY IN v4: `gap-sm` compiles to
+         * `var(--spacing-sm)` the moment the theme declares it. A real Label uses exactly
+         * that, and the reading filed it under "known typos in their source" - the typo
+         * was ours (test15, 01/08). Their name first, the numeric formula second.
+         */
+        const own = `--spacing-${sizeRest}`;
+        if (declared.has(own)) {
+            return {
+                property: spaceProp,
+                value: `{spacing.${sizeRest}}`,
+                token: own,
+            };
+        }
         const size = SPACING[sizeRest] ?? numericSpacing(sizeRest);
         if (size)
             return { property: spaceProp, value: size };

package/dist/skill-import.js

@@ -669,6 +669,41 @@ what shows while it loads     a skeleton, a blur, or the surface colour
 what shows when it is missing a missing asset must never look broken
 \`\`\`
 
+### The census is the ONLY source of truth - four universal rules
+
+These hold in ANY project, whatever its folders, and they exist because a run spent most
+of its tokens re-reading what the census already carried (dono, 01/08):
+
+1. **No iterative sweeps by layer or folder.** Never walk atoms/, then molecules/, then
+   organisms/ reading files - the census walked everything once.
+2. **Batch over the census's own data.** Everything you consume comes out of
+   \`_synthesisui/census.json\` - the looks, the sketch, the signals, the coverage.
+3. **Metadata is one pass, already done.** Theme, fonts, page, libraries, architecture
+   arrive counted. You confirm in a sentence; you never re-derive.
+4. **A file read whose content the census carries is a PIPELINE FAILURE.** Say so in
+   not-expressed.md when you catch yourself - that report is how the census grows.
+
+### Name the parts from the SKETCH - the file is already in the census
+
+Every component's look carries \`sketch\`: its own markup as data - tag, class string,
+depth and text per element, in document order. That is everything you used to open the
+file for, minus the one thing that is genuinely yours: the NAMES.
+
+\`\`\`json
+"sketch": [
+  { "tag": "div",  "depth": 0, "classes": "rounded-md border ..." },
+  { "tag": "button", "depth": 1, "classes": "flex w-full ..." },
+  { "tag": "span", "depth": 2, "classes": "size-2 rounded-full bg-success-500" },
+  { "tag": "span", "depth": 2, "text": "Status" },
+  { "tag": "ChevronDownIcon", "depth": 2 }
+]
+\`\`\`
+
+Read that and write the anatomy: depth 1 is \`trigger\`, the dot is \`status-dot\`, the
+capitalised tag is a frontier. **Do not open the component file** - if the sketch is
+missing or visibly truncated (60-node cap), say so in not-expressed.md and only then
+read, because that gap is the census's to close.
+
 ### What the CLI now reads for you, so do not spend a turn on it
 
 **The rule under all of this: you are given EVIDENCE and asked to DECIDE.** You are never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.91",
+  "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": {