synthesisui 0.16.111 → 0.16.113

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.

package/dist/anatomy-read.js

@@ -265,6 +265,25 @@ sketch) {
                 continue;
             }
             const node_ = { as };
+            /**
+             * THE GUARD TRAVELS WITH THE NODE, off the sketch it points at - so neither a
+             * reading nor the deriver has to carry it, and both get it.
+             */
+            if (typeof node.at === "number") {
+                const measured = sketch?.[node.at];
+                const when = node.when ?? measured?.when;
+                if (when)
+                    node_.when = when;
+                const atRest = node.atRest ?? measured?.atRest;
+                if (atRest === false)
+                    node_.atRest = false;
+            }
+            else {
+                if (node.when)
+                    node_.when = node.when;
+                if (node.atRest === false)
+                    node_.atRest = false;
+            }
             /**
              * 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,
@@ -395,7 +414,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.
      *
@@ -427,7 +473,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(".")) {
@@ -439,10 +486,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/resting.js

@@ -0,0 +1,225 @@
+/**
+ * IS THIS ELEMENT THERE WHEN NOBODY HAS TOUCHED THE COMPONENT?
+ *
+ * Their markup guards elements with conditions - `{isLoading && (…)}`,
+ * `{status === "success" && (…)}` - and the preview drew every one of them. So a card
+ * that is not loading wore a loading veil across its whole surface, and a status that is
+ * `waiting` showed the ping that belongs to `success` (dono, 03/08).
+ *
+ * ANSWERED FROM THEIR OWN DECLARATIONS, or not answered at all. Three facts, all
+ * measured in their source and none of them ours:
+ *
+ *     a prop's default        `{ status = "waiting" }`
+ *     a local alias          `const isLoading = status === "loading"`
+ *     a state's first value  `useState(defaultOpen)` → the default of `defaultOpen`
+ *
+ * `null` means the condition cannot be settled - `{tag && <Tag/>}` on a component whose
+ * `tag` has no default is optional CONTENT, and drawing it is right: 56 of their 79
+ * guards are that shape, and hiding them would empty the previews out. Only a condition
+ * that resolves to FALSE takes an element off the resting view, and the blueprint says
+ * every one of them out loud either way.
+ */
+const STATE = /const\s*\[\s*([A-Za-z_$][\w$]*)\s*,[^\]]*\]\s*=\s*(?:React\.)?useState[^(]*\(\s*([^)]*?)\s*\)/g;
+const ALIAS = /const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*([^;\n]+);/g;
+/**
+ * The aliases and first-render state values a component declares about itself.
+ *
+ * A state read is honest here for one reason: its INITIAL value is what "at rest" means.
+ * `useState(defaultOpen)` with `defaultOpen = false` says a collapsible card starts
+ * closed, which is a fact about their component rather than a guess about a user.
+ */
+/**
+ * EVERY DEFAULT THE DESTRUCTURING DECLARES, not only the string ones.
+ *
+ * `readDefinitionProps` reads string literals on purpose - it answers "which option is
+ * the resting one", and a boolean is not an option. Here a boolean is the whole answer:
+ * `{ defaultOpen = false }` is what says a collapsible card starts closed.
+ */
+function paramDefaults(body) {
+    const open = body.indexOf("({");
+    if (open === -1)
+        return {};
+    let depth = 0;
+    let end = -1;
+    for (let i = open + 1; i < body.length; i++) {
+        const c = body[i];
+        if (c === "{")
+            depth++;
+        else if (c === "}") {
+            depth--;
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+        }
+    }
+    if (end === -1)
+        return {};
+    const out = {};
+    let depth2 = 0;
+    let part = "";
+    const take = () => {
+        const eq = part.indexOf("=");
+        if (eq > 0) {
+            const key = part.slice(0, eq).split(":")[0].trim();
+            const value = part.slice(eq + 1).trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(key) && value)
+                out[key] = value;
+        }
+        part = "";
+    };
+    for (const c of body.slice(open + 2, end)) {
+        if ("([{".includes(c))
+            depth2++;
+        else if (")]}".includes(c))
+            depth2--;
+        if (c === "," && depth2 === 0)
+            take();
+        else
+            part += c;
+    }
+    take();
+    return out;
+}
+export function restingFacts(body, defaults) {
+    const aliases = {};
+    ALIAS.lastIndex = 0;
+    for (const m of body.matchAll(ALIAS)) {
+        const value = m[2].trim();
+        // A function or a component is not a condition; only value-shaped reads help.
+        if (/=>|\bfunction\b/.test(value))
+            continue;
+        if (!aliases[m[1]])
+            aliases[m[1]] = value;
+    }
+    STATE.lastIndex = 0;
+    for (const m of body.matchAll(STATE)) {
+        if (!aliases[m[1]])
+            aliases[m[1]] = m[2].trim() || "undefined";
+    }
+    /**
+     * THE DESTRUCTURING WINS, because it kept the quotes.
+     *
+     * `readDefinitionProps` hands back `waiting` already unquoted, and an unquoted word is
+     * indistinguishable from a reference to something else - so `status === "success"` went
+     * unsettled while the answer sat in the source. Read verbatim, `"waiting"` is a value
+     * and `defaultOpen` is a name, and the shape says which.
+     */
+    return { defaults: { ...defaults, ...paramDefaults(body) }, aliases };
+}
+const LITERAL = /^(?:"([^"]*)"|'([^']*)'|`([^`]*)`)$/;
+/** A value their code wrote, as the string a comparison would see. */
+function literalOf(text) {
+    const t = text.trim();
+    const m = LITERAL.exec(t);
+    if (m)
+        return m[1] ?? m[2] ?? m[3] ?? "";
+    if (t === "true" || t === "false" || t === "undefined" || t === "null")
+        return t;
+    if (/^-?\d+(\.\d+)?$/.test(t))
+        return t;
+    return null;
+}
+/** Split on a top-level operator, so `a && (b || c)` reads as two halves. */
+function splitTop(text, op) {
+    let depth = 0;
+    for (let i = 0; i < text.length - 1; i++) {
+        const c = text[i];
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}")
+            depth--;
+        else if (depth === 0 && text.startsWith(op, i))
+            return [text.slice(0, i), text.slice(i + 2)];
+    }
+    return null;
+}
+/**
+ * True, false, or `null` when their own declarations do not settle it.
+ *
+ * `seen` guards a chain that refers back to itself - `const a = b; const b = a` is not
+ * something to crash on.
+ */
+export function holdsAtRest(condition, facts, seen = new Set()) {
+    const text = condition.trim();
+    if (!text)
+        return null;
+    if (text.startsWith("(") && text.endsWith(")")) {
+        const inner = text.slice(1, -1);
+        if (splitTop(inner, "&&") || splitTop(inner, "||") || !/[()]/.test(inner))
+            return holdsAtRest(inner, facts, seen);
+    }
+    const and = splitTop(text, "&&");
+    if (and) {
+        const [a, b] = [
+            holdsAtRest(and[0], facts, seen),
+            holdsAtRest(and[1], facts, seen),
+        ];
+        if (a === false || b === false)
+            return false;
+        return a === true && b === true ? true : null;
+    }
+    const or = splitTop(text, "||");
+    if (or) {
+        const [a, b] = [
+            holdsAtRest(or[0], facts, seen),
+            holdsAtRest(or[1], facts, seen),
+        ];
+        if (a === true || b === true)
+            return true;
+        return a === false && b === false ? false : null;
+    }
+    if (text.startsWith("!")) {
+        const inner = holdsAtRest(text.slice(1), facts, seen);
+        return inner === null ? null : !inner;
+    }
+    const cmp = /^(.+?)\s*(===|!==|==|!=)\s*(.+)$/.exec(text);
+    if (cmp) {
+        const left = restingValue(cmp[1], facts, seen);
+        const right = literalOf(cmp[3]) ?? restingValue(cmp[3], facts, seen);
+        if (left === null || right === null)
+            return null;
+        const same = left === right;
+        return cmp[2].startsWith("!") ? !same : same;
+    }
+    const value = restingValue(text, facts, seen);
+    if (value === null)
+        return null;
+    return (value !== "false" &&
+        value !== "undefined" &&
+        value !== "null" &&
+        value !== "");
+}
+/** What a name holds at rest, as a literal string, or null when nothing says. */
+function restingValue(name, facts, seen) {
+    const key = name.trim();
+    if (!/^[A-Za-z_$][\w$]*$/.test(key) || seen.has(key))
+        return null;
+    const direct = facts.defaults[key];
+    if (direct != null) {
+        const asLiteral = literalOf(direct);
+        if (asLiteral != null)
+            return asLiteral;
+        /**
+         * `readDefinitionProps` hands back `waiting`, already unquoted, while the
+         * destructuring reads `defaultOpen` - a NAME to follow. One is a value and the other
+         * is a reference, and the shape says which.
+         */
+        if (/^[A-Za-z_$][\w$]*$/.test(direct.trim()))
+            return restingValue(direct, facts, new Set([...seen, key]));
+        return direct.trim();
+    }
+    const alias = facts.aliases[key];
+    if (alias == null)
+        return null;
+    const next = new Set([...seen, key]);
+    const asLiteral = literalOf(alias);
+    if (asLiteral != null)
+        return asLiteral;
+    /**
+     * The alias is an expression - `const isLoading = status === "loading"`. Settling it is
+     * the same question one level down, and the answer comes back as a boolean.
+     */
+    const held = holdsAtRest(alias, facts, next);
+    return held === null ? null : String(held);
+}

package/dist/doctor/sketch.js

@@ -18,8 +18,10 @@
  * 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 { readDefinitionProps } from "./call-sites.js";
 import { scanTags } from "./css-modules.js";
 import { importMap, packageOfTag } from "./imports.js";
+import { holdsAtRest, restingFacts } from "./resting.js";
 import { definitionSpan, returnAt } from "./transcribe.js";
 /** `{children}` / `{props.children}` - the caller's content, spelled either way. */
 const CHILDREN = /\{\s*(?:props\.)?children\s*\}/;
@@ -160,6 +162,87 @@ function staticCallClasses(body) {
  * sitting directly between an open and its close - dynamic children are the caller's,
  * and the slot form already says so.
  */
+/**
+ * THE CONDITION THAT HAS TO HOLD FOR THIS ELEMENT TO EXIST.
+ *
+ * Their code guards markup with `{isLoading && (…)}` and `{imageUrl ? <img/> : <box/>}`,
+ * and the sketch recorded the element without the guard - so the preview drew a loading
+ * veil over a card that is not loading and a status ping for a status it does not have
+ * (dono, 03/08). Measured on their library: 76 guards across 22 of 36 components.
+ *
+ * VERBATIM, in their own vocabulary. This is not a condition we evaluate; it is a fact
+ * about their markup that the screen can say out loud ("only when `isLoading`"). The
+ * falsy branch of a ternary reads as the negation of the same expression, which is their
+ * logic restated rather than anything of ours.
+ */
+export function guardAt(source, at) {
+    let i = at - 1;
+    const skip = () => {
+        while (i >= 0 && /\s/.test(source[i]))
+            i--;
+    };
+    skip();
+    // `{cond && (` and `{cond ? (` both put a paren between the operator and the tag.
+    if (source[i] === "(") {
+        i--;
+        skip();
+    }
+    let negated = false;
+    if (source[i] === "&" && source[i - 1] === "&")
+        i -= 2;
+    else if (source[i] === "?")
+        i -= 1;
+    else if (source[i] === ":") {
+        // The ELSE half of `cond ? <a/> : <b/>` - it exists when the condition does not.
+        negated = true;
+        i -= 1;
+        // Walk back over the truthy branch to reach the `?`.
+        let depth = 0;
+        while (i >= 0) {
+            const c = source[i];
+            if (c === ">" || c === ")" || c === "}")
+                depth++;
+            else if (c === "<" || c === "(" || c === "{") {
+                if (depth === 0)
+                    return null;
+                depth--;
+            }
+            else if (c === "?" && depth === 0)
+                break;
+            i--;
+        }
+        if (i < 0 || source[i] !== "?")
+            return null;
+        i -= 1;
+    }
+    else
+        return null;
+    // Back to the `{` that opened the expression, minding nesting on the way.
+    let depth = 0;
+    const end = i;
+    while (i >= 0) {
+        const c = source[i];
+        if (c === ")" || c === "]" || c === "}")
+            depth++;
+        else if (c === "(" || c === "[") {
+            if (depth === 0)
+                return null;
+            depth--;
+        }
+        else if (c === "{") {
+            if (depth === 0)
+                break;
+            depth--;
+        }
+        i--;
+    }
+    if (i < 0 || source[i] !== "{")
+        return null;
+    const cond = source.slice(i + 1, end + 1).trim();
+    if (!cond || cond.length > 90 || cond.includes("\n"))
+        return null;
+    return negated ? `!(${cond})` : cond;
+}
 export function sketchOf(source, name) {
     /**
      * READ THE IMPORTS BEFORE SLICING - they live at the top of the file, and the
@@ -189,6 +272,14 @@ export function sketchOf(source, name) {
      */
     const ownReturn = returnAt(source, name);
     const rootAt = ownReturn === -1 ? -1 : source.indexOf("<", ownReturn);
+    /**
+     * WHAT THE COMPONENT DECLARES ABOUT ITSELF, read once for the whole sketch.
+     *
+     * Against the SLICED source, so a file that declares two components does not lend one
+     * of them the other's defaults - `RadioCard.tsx` declares `RadioCard` and
+     * `RadioCardGroup`, and that is the same slice the node indices are numbered against.
+     */
+    const facts = restingFacts(source, readDefinitionProps(name ?? "", source).defaults);
     const events = scanTags(source);
     const out = [];
     let depth = 0;
@@ -210,6 +301,14 @@ export function sketchOf(source, name) {
             if (pkg)
                 node.from = pkg;
         }
+        // What has to be true for this element to exist at all - see `guardAt`.
+        const guard = guardAt(source, event.at);
+        if (guard) {
+            node.when = guard;
+            // And whether their own defaults settle it - see `holdsAtRest`.
+            if (holdsAtRest(guard, facts) === false)
+                node.atRest = false;
+        }
         const cls = CLASS_ATTR.exec(event.body);
         if (cls?.[1].trim())
             node.classes = cls[1].trim();

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.111",
+  "version": "0.16.113",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {