synthesisui 0.16.106 → 0.16.107

package/dist/anatomy-from-sketch.js

@@ -468,10 +468,20 @@ versionOf) {
      * first one's classes became `base`, so the rest are emitted as siblings
      * instead of being dropped with the fragment.
      */
-    const top = roots.length > 0 ? roots[0] : 0;
+    /**
+     * THE COMPONENT'S OWN ROOT, which is not always the first node.
+     *
+     * A file that declares a closure before the render it uses puts that closure's
+     * markup first: three of a real library's charts open with a `CustomTooltip`, so
+     * starting at node 0 made the component's anatomy the TOOLTIP's, with the real
+     * root arriving as a sibling (dono, 03/08). The reader stamps which node the
+     * component returns - see `SketchNode.root`.
+     */
+    const stamped = sketch.findIndex((node) => node?.root);
+    const top = stamped >= 0 ? stamped : roots.length > 0 ? roots[0] : 0;
     const read = [
         ...(kids[top] ?? []).flatMap((child) => build(child, 0)),
-        ...roots.slice(1).flatMap((sibling) => build(sibling, 0)),
+        ...roots.filter((at) => at !== top).flatMap((sibling) => build(sibling, 0)),
     ];
     /**
      * THE ROOT'S OWN `{children}` - the component whose entire content is the

package/dist/anatomy-read.js

@@ -44,8 +44,18 @@ const FORMS = new Set([
     "external",
     "slot",
 ]);
-/** The two that arrange, and the only two that take children. */
+/** The two that arrange, and the only two that take children of any kind. */
 const CONTAINERS = new Set(["row", "stack"]);
+/**
+ * PHRASING CONTENT - what HTML lets an inline host hold.
+ *
+ * A glyph and a run of words. This is the list the containment law is actually
+ * about: a button may hold these and may not hold a heading, a panel or a second
+ * interactive node.
+ */
+const PHRASING = new Set(["icon", "text", "image"]);
+/** Forms that are inline hosts: they hold phrasing content and nothing else. */
+const PHRASING_HOST = new Set(["button", "text", "heading"]);
 /** The two frontiers: no name, no styles - what is there is not ours to hold. */
 const FRONTIERS = new Set(["component", "external"]);
 /**
@@ -150,7 +160,9 @@ sketch) {
      * Node 0 of the sketch IS what the component returns, and the reader stamped its
      * import specifier there - see `SketchNode.from`.
      */
-    const rootPackage = sketch?.[0]?.from ?? null;
+    const rootPackage = (sketch ?? []).find((node) => node?.root)?.from ??
+        sketch?.[0]?.from ??
+        null;
     const parts = {};
     const composes = [];
     const external = [];
@@ -300,9 +312,25 @@ sketch) {
                 if (expects)
                     node_.expects = expects.slice(0, 80);
             }
-            // Only the two arrangers descend. A leaf with children is a leaf that was
-            // labelled wrongly, and its children would render nowhere.
-            if (CONTAINERS.has(as) && Array.isArray(node.children)) {
+            /**
+             * AN ACTION HOLDS ITS GLYPH, because that is valid HTML.
+             *
+             * `<button><Upload/>Upload</button>` is legal: a button's content model is
+             * PHRASING content, and an icon and a span are phrasing. The containment law
+             * forbids a BLOCK inside a button - a heading, a panel, another interactive
+             * node - and this was applying it to everything, so a real ImageUploader's two
+             * actions had their `Upload` and `Sparkles` glyphs hoisted out to become
+             * siblings: the icon left the button it belongs to (dono, 03/08).
+             *
+             * The reader upstream had already flattened them itself to obey the rule as
+             * written, which is why the census showed zero of these and the loss was
+             * invisible from here.
+             */
+            const phrasingKids = Array.isArray(node.children) &&
+                node.children.length > 0 &&
+                node.children.every((child) => PHRASING.has(String(child?.as ?? "")));
+            if ((CONTAINERS.has(as) || (PHRASING_HOST.has(as) && phrasingKids)) &&
+                Array.isArray(node.children)) {
                 const children = walk(node.children, depth + 1);
                 if (children.length > 0)
                     node_.children = children;

package/dist/doctor/sketch.js

@@ -20,7 +20,7 @@
  */
 import { scanTags } from "./css-modules.js";
 import { importMap, packageOfTag } from "./imports.js";
-import { definitionSpan } from "./transcribe.js";
+import { definitionSpan, returnAt } from "./transcribe.js";
 /** `{children}` / `{props.children}` - the caller's content, spelled either way. */
 const CHILDREN = /\{\s*(?:props\.)?children\s*\}/;
 /**
@@ -182,6 +182,13 @@ export function sketchOf(source, name) {
     const span = name ? definitionSpan(source, name) : null;
     if (span)
         source = source.slice(span.from, span.to);
+    /**
+     * WHERE THE COMPONENT'S OWN RENDER STARTS, in the same slice the nodes are
+     * numbered against - so the index the sketch stamps and the index a reading sends
+     * are the same number.
+     */
+    const ownReturn = returnAt(source, name);
+    const rootAt = ownReturn === -1 ? -1 : source.indexOf("<", ownReturn);
     const events = scanTags(source);
     const out = [];
     let depth = 0;
@@ -194,6 +201,9 @@ export function sketchOf(source, name) {
         if (out.length >= MAX_NODES)
             break;
         const node = { tag: event.tag, depth };
+        // The first element at or after the component's own `return (` IS its root.
+        if (rootAt !== -1 && event.at === rootAt)
+            node.root = true;
         // What a capitalised tag IS, from the file's own imports - see `SketchNode.from`.
         if (/^[A-Z]/.test(event.tag)) {
             const pkg = packageOfTag(event.tag, imports);

package/dist/doctor/transcribe.js

@@ -1302,7 +1302,7 @@ function aliasTarget(source, name) {
     }
     return null;
 }
-function returnAt(source, name) {
+export 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) {

package/dist/skill-import.js

@@ -681,7 +681,26 @@ external  a library        → needs "from": the package name
 slot      the CALLER's content → takes "expects": what goes there, in their words
 \`\`\`
 
-Only \`row\` and \`stack\` take \`children\`. Everything else is a leaf.
+\`row\` and \`stack\` ARRANGE their children. A \`component\` or \`external\` node HOLDS them -
+what their code nests inside a component they compose is markup THEY wrote, wearing their
+classes, and it belongs in the tree:
+
+\`\`\`json
+{ "as": "component", "ref": "Card", "at": 3, "children": [
+  { "as": "row", "name": "header", "at": 4 },
+  { "as": "external", "from": "recharts", "at": 8 } ] }
+\`\`\`
+
+A \`button\` holds a glyph and its words - \`<button><Upload/>Upload</button>\` is valid HTML,
+because a button's content model is *phrasing* and an icon is phrasing. So an \`icon\` and a
+\`text\` may sit inside one:
+
+\`\`\`json
+{ "as": "button", "name": "upload", "at": 9, "children": [{ "as": "icon", "name": "upload-icon", "at": 10 }] }
+\`\`\`
+
+Everything else is a leaf, and a leaf that holds elements has them HOISTED OUT to become
+its siblings - which destroys the nesting you read. If something arranges, say \`row\`/\`stack\`.
 
 ### \`{children}\` is a node, not an absence
 

package/package.json

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