synthesisui 0.16.110 → 0.16.112

package/dist/anatomy-from-sketch.js

@@ -308,12 +308,30 @@ versionOf) {
          */
         const local = capitalised && !node.from;
         /**
-         * A WRAPPER THAT RENDERS NOTHING passes its children up in its own place: a
-         * portal teleports and a provider is context. Keeping it would draw a box
-         * that does not exist in the client's output.
+         * A WRAPPER THAT RENDERS NOTHING DRAWS NOTHING AND IS STILL REQUIRED.
+         *
+         * A portal teleports and a provider is context, so keeping it as a box would draw
+         * something the client's output does not have. But `Collapsible.Panel`,
+         * `Dialog.Portal` and `Select.Positioner` are what make the component WORK, and the
+         * usage snippet was leaving them out: 27 of them across 8 of their components, so
+         * somebody pasting the snippet got a card that never opens (dono, 03/08).
+         *
+         * So it keeps its place in the tree with no `name` - no part, no styles, nothing for
+         * the Canvas to draw, and an element the snippet emits. A motion wrapper stays
+         * flattened: it is animation, and its element is genuinely absent from the output.
          */
-        if ((kind === "motion" || kind === "headless") &&
-            rendersNothing(tag, classes)) {
+        if (kind === "headless" && rendersNothing(tag, classes)) {
+            const held = children.flatMap((child) => build(child, depth + 1));
+            return [
+                {
+                    as: held.length > 0 ? "stack" : "text",
+                    from: String(node.from ?? tag),
+                    refName: tag,
+                    ...(held.length > 0 ? { children: held } : {}),
+                },
+            ];
+        }
+        if (kind === "motion" && rendersNothing(tag, classes)) {
             return children.flatMap((child) => build(child, depth));
         }
         // `<AnimatePresence>` and friends: no element of their own.
@@ -436,10 +454,27 @@ versionOf) {
                 },
             ];
         }
+        /**
+         * A BOX OF OURS THAT IS SOMEBODY ELSE'S ELEMENT SAYS SO.
+         *
+         * A headless primitive is ours to draw - the classes on it are the client's - and
+         * that is why it becomes a PART rather than a frontier. But the element itself is
+         * `<Collapsible.Trigger>`, and the usage snippet was emitting a plain `<div>` with
+         * our class on it: a person following it gets the look and none of the behaviour, no
+         * `aria-expanded` and no keyboard (dono, 03/08). Measured on their library: 31 parts
+         * across 9 components are a library element, plus 11 roots.
+         *
+         * The package AND their own spelling, because the snippet needs both - the import
+         * line comes from the first and the tag from the second.
+         */
+        const fromLib = kind === "headless" && node.from
+            ? { from: String(node.from), refName: tag }
+            : {};
         const built = {
             as,
             ...(name ? { name } : {}),
             ...(classes ? { at: index } : {}),
+            ...fromLib,
             ...(node.text ? { text: node.text } : {}),
         };
         const inside = hasKids ? descend() : [];

package/dist/anatomy-read.js

@@ -265,6 +265,17 @@ sketch) {
                 continue;
             }
             const node_ = { as };
+            /**
+             * A PART THAT IS A LIBRARY ELEMENT CARRIES BOTH FACTS - see `AnatomyRead.from`.
+             * Inert for the renderer, which dispatches on `as`; read by the usage snippet,
+             * which has to emit `<Collapsible.Trigger>` and the import line rather than a
+             * `<div>` that looks right and does nothing.
+             */
+            if (typeof node.from === "string" && node.from.trim()) {
+                node_.from = node.from.trim();
+                if (typeof node.refName === "string" && node.refName.trim())
+                    node_.refName = node.refName.trim();
+            }
             // The NAME is what carries the styles, so it is claimed even when nothing
             // resolved: the tree triggers on presence, and structure is most of the
             // value. A node with no name is pure structure and that is legitimate.
@@ -384,7 +395,34 @@ sketch) {
         ? (frontierClasses(rootObj, sketch).classes ??
             "")
         : "";
-    const paints = rootPainted ? { classes: rootPainted } : {};
+    /**
+     * THE OVERRIDE TRAVELS AS DECLARATIONS, AND ONLY WHEN IT IS AN OVERRIDE.
+     *
+     * Two different things were sharing one field, and both were broken by it.
+     *
+     * When the root is a FRONTIER of theirs, the class string at the call site is what
+     * the PARENT paints on it - `MetricCard` returns `<Card className="flex-1
+     * dark:bg-darkgray-300">` - and this is the whole reason the field exists. It was
+     * sent as the class NAMES, so the platform pasted `dark:bg-darkgray-300` onto its own
+     * element and the browser resolved it against OUR Tailwind, which has no such colour:
+     * the override did nothing, on 5 of 5 of their components (dono, 03/08). Transcribed,
+     * it is a declaration that applies anywhere.
+     *
+     * When the root is one we DRAW - a headless primitive, a plain element - the classes
+     * at that index are the component's OWN look and are already in `base`. Sending them
+     * again put their raw `bg-white` on our element, in a layer that outranks the compiled
+     * recipe, and two of their cards previewed white in dark mode over a recipe that said
+     * otherwise. So a drawn root sends nothing here at all.
+     */
+    const rootStyle = rootPainted
+        ? transcribe(rootPainted.split(/\s+/).filter(Boolean), declared)
+        : null;
+    const paints = rootStyle && Object.keys(rootStyle.base).length > 0
+        ? { style: rootStyle.base }
+        : {};
+    const paintsDark = rootStyle && Object.keys(rootStyle.dark).length > 0
+        ? { dark: rootStyle.dark }
+        : {};
     /**
      * A LIBRARY ROOT WHOSE NAME IS NOT DOTTED.
      *
@@ -416,7 +454,8 @@ sketch) {
     const looksLikeTag = sent !== "" && /^[A-Z]/.test(sent);
     const rootFrom = looksLikeTag ? (rootPackage ?? "") : sent;
     if (rootFrom) {
-        rootOut = { from: rootFrom, ...paints };
+        // A root we draw carries no override: its classes are the component's own.
+        rootOut = { from: rootFrom };
     }
     else if (rootRaw && /^[A-Z]/.test(rootRaw)) {
         if (!rootRaw.includes(".")) {
@@ -428,10 +467,10 @@ sketch) {
              */
             const slug = resolve?.(rootRaw) ?? safePartName(rootRaw);
             if (slug)
-                rootOut = { ref: slug, name: rootRaw, ...paints };
+                rootOut = { ref: slug, name: rootRaw, ...paints, ...paintsDark };
         }
         else if (rootPackage) {
-            rootOut = { from: rootPackage, ...paints };
+            rootOut = { from: rootPackage };
         }
     }
     /**

package/dist/commands/import.js

@@ -24,6 +24,7 @@ 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";
+import { withLibraryStructure } from "../library-structure.js";
 import { body, paint, section } from "../output.js";
 import { phase, startProgress } from "../progress.js";
 import { detectStack, resolveDeps } from "../stack.js";
@@ -1793,8 +1794,22 @@ async function resolveReadParts(census, root) {
             for (const note of derived.notes)
                 notes.add(note);
         }
-        const resolved = Array.isArray(anatomy) && anatomy.length > 0
-            ? resolveAnatomy(anatomy, declared, deps, resolveRef, entry?.root, 
+        /**
+         * THE LIBRARY'S OWN FRAME, PUT BACK BEFORE ANYTHING IS RESOLVED.
+         *
+         * A reading names what carries appearance; a headless library's `Portal`,
+         * `Positioner` and `Panel` carry none and are what make the component work. 27 of
+         * them across 8 of their components were named by nobody, so the usage snippet
+         * handed people a card that never opens (dono, 03/08). See `withLibraryStructure` -
+         * it is a lookup in the sketch, not a guess, and it is idempotent.
+         */
+        const framed = Array.isArray(anatomy) && anatomy.length > 0
+            ? withLibraryStructure(anatomy, looks[component]?.sketch, typeof entry?.root?.at === "number"
+                ? (entry?.root).at
+                : undefined)
+            : anatomy;
+        const resolved = Array.isArray(framed) && framed.length > 0
+            ? resolveAnatomy(framed, declared, deps, resolveRef, entry?.root, 
             // The component's own sketch, so a node naming itself by index reads
             // the exact class string the census measured (dono, 01/08).
             looks[component]?.sketch)
@@ -1851,20 +1866,34 @@ async function resolveReadParts(census, root) {
         const split = placeLayers((look?.layers ?? []), partAt, (look?.sketch ?? []));
         for (const line of split.unplaced)
             notes.add(line);
-        /** The per-part layers, merged into the parts the resolution just named. */
+        /**
+         * REPLACED, NOT APPENDED - because this runs more than once.
+         *
+         * A measuring pass places these onto the DERIVED parts (`box-2`); the send pass
+         * places them onto the AUTHORED ones (`status-dot`). Appending would accumulate a
+         * generation per run, and the pruning below drops the derived names anyway.
+         */
         for (const [part, list] of split.perPart) {
             const target = resolved.parts[part];
             if (!target || !list)
                 continue;
-            target.layers = [
-                ...(target.layers ?? []),
-                ...list,
-            ];
+            target.layers = list;
         }
         const carried = {
             ...(hasParts ? { parts: resolved.parts } : {}),
-            /** The root keeps only what is the root's - see the note above. */
-            ...(look?.layers ? { layers: split.root } : {}),
+            /**
+             * THE FULL LIST STAYS ON THE LOOK, EACH LAYER KEEPING ITS `on`.
+             *
+             * Writing back only the root's was destructive, and this function runs twice: the
+             * measuring pass moved 8 of their status layers onto `box-2` and wrote the
+             * remaining 2 back, then the send pass re-read those 2, had nothing to place, and
+             * the one-generation pruning dropped `box-2` - so the four status colours of their
+             * dot and label reached zero recipes, on 36 of 36 components (dono, 03/08).
+             *
+             * Keeping the source of truth here makes the split idempotent: every pass
+             * recomputes both halves from the same list. The RECIPE builder is what leaves an
+             * attributed layer off the component - see `safeLayers`.
+             */
             ...(resolved.tree.length > 0 ? { tree: resolved.tree } : {}),
             ...(resolved.composes.length > 0 ? { composes: resolved.composes } : {}),
             ...(libraries.length > 0 ? { external: libraries } : {}),

package/dist/doctor/transcribe.js

@@ -401,10 +401,44 @@ export function parseClass(cls) {
  * `declared` maps a token NAME to its value, so a resolved colour can be
  * reported in their vocabulary rather than as a hex we looked up.
  */
+/** A hex, or a ref into their colour scale - the two shapes an alpha can wrap. */
+const COLOUR_VALUE = /^(#[0-9a-f]{3,8}|\{color\.[^}]+\})$/i;
+/**
+ * `#ffffff` + `50` → `color-mix(in srgb, #ffffff 50%, transparent)`.
+ *
+ * Left alone when the value is not a colour (`shadow-lg/50` is not one) or when mixing
+ * would say nothing (`transparent`, `currentColor`).
+ */
+function withAlpha(d, alpha) {
+    if (!alpha || !/^\d{1,3}$/.test(alpha))
+        return d;
+    const pct = Number(alpha);
+    if (pct >= 100 || pct < 0)
+        return d;
+    if (!COLOUR_VALUE.test(d.value.trim()))
+        return d;
+    return { ...d, value: `color-mix(in srgb, ${d.value} ${pct}%, transparent)` };
+}
 export function readUtility(utility, declared) {
-    // An opacity modifier changes the value, not the property, and honouring it
-    // would mean computing a colour they never wrote. The property still belongs
-    // in the recipe, so the base colour travels and the alpha does not.
+    const read = readUtilityCore(utility, declared);
+    return read ? withAlpha(read, utility.split("/")[1]) : read;
+}
+function readUtilityCore(utility, declared) {
+    /**
+     * THE ALPHA TRAVELS, and it took `color-mix` to make that honest.
+     *
+     * This dropped the modifier on purpose: honouring `bg-white/50` used to mean computing
+     * a hex they never wrote, and inventing values is the one thing this reader may not
+     * do. But `color-mix(in srgb, X 50%, transparent)` computes nothing - the browser does,
+     * at paint time - and a token REF stays a ref inside it, so Token Discipline still sees
+     * the token and a re-theme still moves it.
+     *
+     * Dropping it was not neutral. Their loading veil is `bg-white/50 absolute inset-0`:
+     * as an opaque white it covered the whole card, which is the white box the owner kept
+     * asking about. Their Modal's backdrop is `bg-darkgray-900/40` - a scrim that became a
+     * wall. Measured on their library: 11 of 11 opacity modifiers lost their alpha
+     * (dono, 03/08).
+     */
     const [core] = utility.split("/");
     // A bare keyword carries a declaration with no scale behind it, so it is read
     // before the dash split that everything else needs.

package/dist/library-structure.js

@@ -0,0 +1,162 @@
+/**
+ * THE ELEMENTS THAT MAKE IT WORK, PUT BACK.
+ *
+ * A reading names the elements that carry APPEARANCE, because that is what a design
+ * system is for. A headless library's most important elements carry none: a
+ * `Dialog.Portal` teleports, a `Select.Positioner` measures, a `Collapsible.Panel` shows
+ * and hides. They have no class list, so nothing of ours styles them - and a reading that
+ * skips them is not wrong about the styling, it is just missing the frame.
+ *
+ * The usage snippet is where that costs something. Measured on the owner's library
+ * against the reading his own skill authored (dono, 03/08):
+ *
+ *     27 library elements with no classes, across 8 components, named by nobody
+ *        Modal        BaseDialog.Root, BaseDialog.Portal
+ *        Select       BaseSelect.Root, BaseSelect.Portal
+ *        Tooltip      BaseTooltip.Provider, .Root, .Portal, .Positioner
+ *        TextEditor   11 (four Popovers and a Dialog)
+ *        Menu, ColorPicker, CollapsibleCard, Toggle   the rest
+ *
+ * Somebody pasting that snippet gets a card that never opens. So this puts them back,
+ * and it is a LOOKUP rather than a guess: the sketch already recorded every element with
+ * its depth and its package, so the chain between two named nodes is a fact about their
+ * markup. Nothing is invented - a node re-inserted here carries no name, no part and no
+ * styles, only the element and where it came from.
+ *
+ * A library element that DOES carry classes is left alone: it belongs to whoever named
+ * it, and re-inserting it would be a second opinion about a styled element.
+ */
+import { frontierKind } from "./frontier-kind.js";
+/** Index → the index of its parent, or -1. Read off `depth`, which is the nesting. */
+function parents(sketch) {
+    const out = [];
+    const open = [];
+    for (const [i, node] of sketch.entries()) {
+        while (open.length > 0 && sketch[open[open.length - 1]].depth >= node.depth)
+            open.pop();
+        out.push(open.length > 0 ? open[open.length - 1] : -1);
+        open.push(i);
+    }
+    return out;
+}
+/** Every `at` the reading already points at, at any depth. */
+function claimed(read, into = new Set()) {
+    for (const node of read) {
+        if (typeof node.at === "number")
+            into.add(node.at);
+        if (node.children)
+            claimed(node.children, into);
+    }
+    return into;
+}
+/** Behaviour with no appearance: their element, no class list, nobody's part. */
+function isBehaviour(node) {
+    if (!node)
+        return false;
+    if ((node.classes ?? "").trim())
+        return false;
+    return frontierKind(node.from) === "headless";
+}
+/**
+ * Put the missing library frame back around the nodes it wraps.
+ *
+ * `boundary` is the `at` of the nearest ancestor the reading DID name (or -1 at the top),
+ * so the chain walked is exactly what sits between one named element and the next.
+ */
+function wrap(read, sketch, parentOf, named, boundary, 
+/**
+ * The library elements already standing on this path, by their own spelling.
+ *
+ * A restored wrapper carries no index - it is not a node of the reading - so the
+ * `named` set cannot see it, and without this a second run wrapped the same portal
+ * again. That matters because the derived anatomy already keeps these, and both
+ * anatomies go through here.
+ */
+wrapped) {
+    /** The missing library ancestors of `at`, outermost first. */
+    const chain = (at) => {
+        const out = [];
+        for (let p = parentOf[at]; p >= 0 && p !== boundary; p = parentOf[p]) {
+            if (named.has(p) || wrapped.has(sketch[p].tag))
+                continue;
+            if (isBehaviour(sketch[p]))
+                out.unshift(p);
+        }
+        return out;
+    };
+    const deep = read.map((node) => {
+        if (!node.children || node.children.length === 0)
+            return node;
+        const inside = node.refName ? new Set([...wrapped, node.refName]) : wrapped;
+        const inner = typeof node.at === "number"
+            ? wrap(node.children, sketch, parentOf, named, node.at, inside)
+            : wrap(node.children, sketch, parentOf, named, boundary, inside);
+        return { ...node, children: inner };
+    });
+    /**
+     * SIBLINGS THAT SHARE A WRAPPER SHARE ONE. Their Select puts a trigger and a popup
+     * inside one `BaseSelect.Root`; two wrappers would say their code has two.
+     */
+    const out = [];
+    let run = null;
+    const flush = () => {
+        if (!run)
+            return;
+        let built = run.nodes;
+        for (const at of [...run.keys].reverse()) {
+            const node = sketch[at];
+            built = [
+                {
+                    as: "stack",
+                    from: String(node.from ?? node.tag),
+                    refName: node.tag,
+                    children: built,
+                },
+            ];
+        }
+        out.push(...built);
+        run = null;
+    };
+    for (const node of deep) {
+        const keys = typeof node.at === "number" ? chain(node.at) : [];
+        if (keys.length === 0) {
+            flush();
+            out.push(node);
+            continue;
+        }
+        if (run && run.keys.join(",") === keys.join(","))
+            run.nodes.push(node);
+        else {
+            flush();
+            run = { keys, nodes: [node] };
+        }
+    }
+    flush();
+    return out;
+}
+/**
+ * The reading with the library's own structure restored around it.
+ *
+ * Idempotent: an element the reading already names is never re-inserted, so running this
+ * over a derived anatomy - which keeps them already - changes nothing.
+ */
+export function withLibraryStructure(read, sketch, 
+/** The `at` the reading gave for the element the component RETURNS, when it gave one. */
+rootAt) {
+    if (!sketch || sketch.length === 0 || read.length === 0)
+        return read;
+    /**
+     * THE ELEMENT THE COMPONENT RETURNS IS THE BOUNDARY, and it is not always given.
+     *
+     * A reading may name its root by NAME alone (`"root": "BaseDialog.Root"`), and then
+     * the walk climbed past it and restored the root as a wrapper INSIDE the anatomy -
+     * so the snippet would open `<BaseDialog.Root>` twice. The sketch stamps the returned
+     * element, so the answer is measured either way.
+     */
+    const stamped = sketch.findIndex((node) => node.root);
+    const from = typeof rootAt === "number" ? rootAt : stamped >= 0 ? stamped : -1;
+    const named = claimed(read);
+    if (from >= 0)
+        named.add(from);
+    return wrap(read, sketch, parents(sketch), named, from, new Set());
+}

package/package.json

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