synthesisui 0.16.97 → 0.16.99

package/dist/anatomy-read.js

@@ -123,7 +123,14 @@ function frontierClasses(node, sketch) {
 export function resolveAnatomy(read, declared, deps, 
 /** Their name → the slug it reaches in this system. See `RefResolver`. */
 resolve, 
-/** What the component returns, when the skill said and it is not a plain tag. */
+/**
+ * What the component returns, when the skill said and it is not a plain tag.
+ *
+ * A STRING or an object: `{ name, at }` / `{ name, classes }` carries what the
+ * PARENT paints on the root at the call site. `MetricCard` returns
+ * `<Card className="flex-1 dark:bg-darkgray-300">` and that override had
+ * nowhere to travel (not-expressed.md, dono, 01/08).
+ */
 root, 
 /** This component's sketch, so a node can name its classes by INDEX instead
  *  of retyping them - see `AnatomyRead.at`. */
@@ -290,15 +297,39 @@ sketch) {
      * through the crosswalk exactly like a child frontier does.
      */
     let rootOut;
-    const rootRaw = String(root ?? "").trim();
-    if (rootRaw && /^[A-Z]/.test(rootRaw)) {
+    const rootObj = typeof root === "object" && root ? root : null;
+    const rootRaw = String((rootObj ? rootObj.name : root) ?? "").trim();
+    // The parent's own override on the root it returns, by index or as written.
+    const rootPainted = rootObj
+        ? (frontierClasses(rootObj, sketch).classes ??
+            "")
+        : "";
+    const paints = rootPainted ? { classes: rootPainted } : {};
+    /**
+     * A LIBRARY ROOT WHOSE NAME IS NOT DOTTED.
+     *
+     * Three components return a Base UI primitive imported under a single word -
+     * `Pill` and `SelectionCard` return `Toggle`, `RadioCardGroup` returns
+     * `RadioGroup` - and `"root": "Toggle"` would point at THEIR own Toggle (a
+     * switch), inventing a relation that does not exist. There was no way to say
+     * "a library component with a bare name", so `root` was left out on all three
+     * (not-expressed.md, dono, 01/08).
+     *
+     * `from` says it: the PACKAGE disambiguates what the name cannot. It wins over
+     * the name, because a caller that sends both is telling us where it came from.
+     */
+    const rootFrom = String(rootObj?.from ?? "").trim();
+    if (rootFrom) {
+        rootOut = { from: rootFrom, ...paints };
+    }
+    else if (rootRaw && /^[A-Z]/.test(rootRaw)) {
         if (rootRaw.includes(".")) {
-            rootOut = { from: rootRaw };
+            rootOut = { from: rootRaw, ...paints };
         }
         else {
             const slug = resolve?.(rootRaw) ?? safePartName(rootRaw);
             if (slug)
-                rootOut = { ref: slug, name: rootRaw };
+                rootOut = { ref: slug, name: rootRaw, ...paints };
         }
     }
     if (coerced > 0) {

package/dist/commands/mcp.js

@@ -393,19 +393,83 @@ async function resolveAtNodes(root, entries) {
         // better than refusing to validate at all.
         return entries;
     }
-    /** Their spelling → the sketch, matched the way the contract kebabs a name. */
-    const sketchFor = (name) => {
-        if (looks[name]?.sketch)
-            return looks[name].sketch;
+    /** Their spelling → the look, matched the way the contract kebabs a name. */
+    const lookFor = (name) => {
+        if (looks[name])
+            return looks[name];
         const slug = name.replace(/[^a-z0-9]/gi, "").toLowerCase();
         for (const [theirs, look] of Object.entries(looks)) {
             if (theirs.replace(/[^a-z0-9]/gi, "").toLowerCase() === slug)
-                return look.sketch;
+                return look;
         }
         return undefined;
     };
     return entries.map((entry) => {
-        const sketch = sketchFor(String(entry.name ?? ""));
+        const look = lookFor(String(entry.name ?? ""));
+        const sketch = look?.sketch;
+        /**
+         * THE STYLES THE IMPORT WILL MERGE - so the floor measured is the floor the
+         * component arrives with.
+         *
+         * The reading sends an ANATOMY: a tree of `at` indices, deliberately without
+         * the classes, because retyping them is the loss the index exists to prevent.
+         * The styles are the census's measured `base` and `layers`, merged at import.
+         * So the validator was judging a recipe whose look had not arrived yet, and
+         * all 35 components came back BELOW THE FLOOR with the same four lines - a
+         * verdict about a payload nobody will ever send (not-expressed.md, dono,
+         * 01/08).
+         *
+         * Merged UNDER what the payload carries: a base the reader authored on
+         * purpose still wins over the measurement.
+         */
+        const recipe0 = entry.recipe;
+        const withLook = recipe0
+            ? {
+                ...recipe0,
+                ...(look?.base && Object.keys(look.base).length > 0
+                    ? { base: { ...look.base, ...(recipe0.base ?? {}) } }
+                    : {}),
+                ...(look?.layers?.length
+                    ? {
+                        layers: [
+                            ...look.layers,
+                            ...(recipe0.layers ?? []),
+                        ],
+                    }
+                    : {}),
+                /**
+                 * THE PARTS, which is where a provider-rooted component keeps
+                 * EVERYTHING.
+                 *
+                 * `Tooltip` returns `<BaseTooltip.Provider>` - a context provider that
+                 * renders no element and carries no style - and its whole look (fill,
+                 * radius, padding, shadow) is on the popup PART. The merge carried
+                 * `base` and `layers` and stopped there, so the validator judged a
+                 * component with no declarations anywhere and said BELOW THE FLOOR
+                 * about one that draws fine (not-expressed.md, dono, 01/08).
+                 */
+                ...(look?.parts && Object.keys(look.parts).length > 0
+                    ? {
+                        parts: {
+                            ...look.parts,
+                            ...(recipe0.parts ?? {}),
+                        },
+                    }
+                    : {}),
+                /**
+                 * THE ROOT TAG TRAVELS, so the validator can name the KIND.
+                 *
+                 * It falls back to `surface` when the payload declares none, and every
+                 * one of 35 components got the surface checklist - including a Button,
+                 * two fields, a control and two pills (not-expressed.md, dono, 01/08).
+                 * The kind is arithmetic from the name and the root tag; the tag is
+                 * here and the arithmetic lives on the side that owns the contract, so
+                 * this sends the evidence rather than a second implementation of it.
+                 */
+                ...(look?.rootTag ? { rootTag: look.rootTag } : {}),
+            }
+            : recipe0;
+        entry = { ...entry, recipe: withLook };
         if (!sketch)
             return entry;
         const walk = (nodes) => {

package/dist/doctor/sketch.js

@@ -82,8 +82,24 @@ function staticCallClasses(body) {
             argStart = i + 1;
         }
     }
+    /**
+     * A COMMENT BEFORE THE STRING IS STILL THE STRING.
+     *
+     * Real code annotates these lists - `// Light mode`, `// Shadow with subtle
+     * brand tint` - and the argument then reads as `// Light mode\n"bg-darkgray-800
+     * …"`, which is not a bare literal, so it was dropped. The Tooltip kept only
+     * its last two arguments (the two with no comment above them) and lost its
+     * fill, radius, padding and shadow - and it only came to light because the
+     * floor check flagged it (not-expressed.md, dono, 01/08). Measured: SIX of 36
+     * components in that library annotate a `cn()` this way.
+     */
     const classes = args
-        .map((a) => a.trim())
+        .map((a) => a
+        // block comments first, so a `/* … */` spanning the line cannot leave
+        // a stray `*/` behind for the line rule to keep
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/(^|\n)\s*\/\/[^\n]*/g, "$1")
+        .trim())
         .filter((a) => /^(["'`]).*\1$/.test(a) && !a.includes("${"))
         .map((a) => a.slice(1, -1).trim())
         .filter(Boolean);

package/dist/doctor/transcribe.js

@@ -1135,6 +1135,44 @@ export function transcribe(classes, declared) {
  * Absent or unfound, the old behaviour stands exactly - which keeps every
  * single-component file reading byte-identically.
  */
+/**
+ * AN EXPORT THAT IS AN ALIAS - follow it to the function it wraps.
+ *
+ * `export const Chat = Object.assign(React.forwardRef(ChatContainerComponent), …)`
+ * declares the NAME the census knows and none of the markup: the styles live in
+ * `ChatContainerComponent`, declared above. Measured on a real library, EIGHT of
+ * 36 exports are this shape - seven `forwardRef(Fn)` and one
+ * `Object.assign(forwardRef(Fn))` - and Chat arrived with an empty look, which
+ * forced the one hand-read of the whole run (not-expressed.md, dono, 01/08).
+ *
+ * They used to work by accident: with no body brace to find, the reader fell
+ * back to the first `return (` in the file, which for a one-component file is
+ * the right one. Removing that fallback - correctly, because it let a helper
+ * borrow a sibling's return - would have broken all eight. So the alias is
+ * followed on purpose instead: the first capitalised identifier inside the call
+ * is the function this name IS.
+ */
+function aliasTarget(source, name) {
+    const decl = new RegExp(`(?:const|let|var)\\s+${name}\\s*(?::[^=]*)?=\\s*([^;\\n]{0,200})`).exec(source);
+    if (!decl)
+        return null;
+    const rhs = decl[1];
+    // Only a WRAPPER call aliases: `forwardRef`, `memo`, `Object.assign`,
+    // `styled(...)`. A plain arrow is the component itself and has no target.
+    if (!/^(?:React\.)?(?:forwardRef|memo|Object\.assign|styled)\b/.test(rhs))
+        return null;
+    for (const m of rhs.matchAll(/\b([A-Z][A-Za-z0-9_]*)\b/g)) {
+        const candidate = m[1];
+        if (/^(React|Object|Component)$/.test(candidate))
+            continue;
+        if (candidate === name)
+            continue;
+        // It has to be declared in this file, or it is a type argument or an import.
+        if (new RegExp(`(?:function|const|let|var)\\s+${candidate}\\b`).test(source))
+            return candidate;
+    }
+    return null;
+}
 function returnAt(source, name) {
     if (name) {
         const decl = new RegExp(`(?:function|const|let|var)\\s+${name}\\b|${name}\\s*[:=]\\s*(?:function|\\()`).exec(source);
@@ -1150,6 +1188,16 @@ function returnAt(source, name) {
             const arrow = /=>\s*\(/.exec(source.slice(decl.index, decl.index + 400));
             if (arrow)
                 return decl.index + arrow.index;
+            /**
+             * AN ALIAS POINTS AT THE FUNCTION THAT HAS THE MARKUP - follow it once.
+             * `const Chat = Object.assign(forwardRef(ChatContainerComponent), …)`.
+             */
+            const target = aliasTarget(source, name);
+            if (target) {
+                const viaAlias = ownReturn(source, source.search(new RegExp(`(?:function|const|let|var)\\s+${target}\\b`)));
+                if (viaAlias !== -1)
+                    return viaAlias;
+            }
             /**
              * FOUND THE NAME AND IT RETURNS NO JSX IN PARENTHESES - so say nothing.
              *
@@ -1200,13 +1248,36 @@ export function definitionSpan(source, name) {
     if (!decl)
         return null;
     const brace = bodyBrace(source, decl.index);
-    if (brace === -1)
+    if (brace === -1) {
+        // The export is an alias; the body belongs to what it wraps.
+        const target = aliasTarget(source, name);
+        if (target)
+            return definitionSpan(source, target);
         return null;
+    }
     const end = matchingBrace(source, brace);
     return { from: decl.index, to: end === -1 ? source.length : end + 1 };
 }
 /** The `{` that opens a function body declared at `declAt`, or -1. */
 function bodyBrace(source, declAt) {
+    /**
+     * A BODY INLINE INSIDE A WRAPPER: `forwardRef<A, B>((props, ref) => { … })`.
+     *
+     * Toggle is written this way and the plain walk below cannot find it - the
+     * wrapper's own parenthesis never closes before the body starts, so it looked
+     * for a `{` that is not there and the component read empty. There is no named
+     * function to alias to either: the body IS the argument.
+     */
+    const head = source.slice(declAt, declAt + 400);
+    const wrapper = /=\s*(?:React\.)?(?:forwardRef|memo|styled\([^)]*\))\s*(?:<[^>(]*>)?\s*\(/.exec(head);
+    if (wrapper) {
+        const arrow = /(?:=>|function\s*[A-Za-z0-9_]*\s*\([^)]*\))\s*\{/.exec(source.slice(declAt + wrapper.index));
+        if (arrow) {
+            const at = declAt + wrapper.index + arrow.index + arrow[0].length - 1;
+            if (source[at] === "{")
+                return at;
+        }
+    }
     let i = declAt;
     let paren = 0;
     let opened = false;

package/dist/skill-import.js

@@ -614,10 +614,32 @@ depth appears anyway.
   "Modal": {
     "root": "BaseDialog.Root",
     "anatomy": [ … ]
+  },
+  "MetricCard": {
+    "root": { "name": "Card", "at": 1 },
+    "anatomy": [ … ]
   }
 }
 \`\`\`
 
+**A library root whose name is not dotted needs its PACKAGE.** \`Pill\` returns Base UI's
+\`Toggle\`, and \`"root": "Toggle"\` would point at THEIR own Toggle - a switch - inventing a
+relation that does not exist. Send where it came from instead:
+
+\`\`\`json
+"Pill": { "root": { "from": "@base-ui/react/toggle" }, "anatomy": [ … ] }
+\`\`\`
+
+\`Radio.Root\` needs none of this: the dot already says it is somebody's namespace. Leaving the
+root out was the old workaround and it cost the surface its name (not-expressed.md, dono, 01/08).
+
+**The root takes what the PARENT paints on it.** When the returned root carries an override at
+the call site - \`MetricCard\` returns \`<Card className="flex-1 dark:bg-darkgray-300">\` - send the
+object form and point \`at\` the sketch node: \`{ "name": "Card", "at": 1 }\`. The string form still
+works and means "no override". Sending the root as an anatomy node instead would make it a leaf
+and orphan the content inside it, which is why it is a field on the root rather than a node
+(not-expressed.md, dono, 01/08).
+
 **Say what the component RETURNS when it is not a plain tag.** Measured on a real library
 (dono, 01/08): 14 of 23 components return one of their own - \`ArticleCard\` returns a \`<Card>\`,
 \`Button\` and \`Text\` return a \`<Component>\` - and 17 of 23 have no style of their own at all,

package/package.json

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