synthesisui 0.16.108 → 0.16.110

package/dist/anatomy-read.js

@@ -167,6 +167,7 @@ sketch) {
     const composes = [];
     const external = [];
     const notes = [];
+    const partAt = {};
     let budget = MAX_NODES;
     let coerced = 0;
     /**
@@ -295,6 +296,27 @@ sketch) {
                     notes.push(`part \`${key}\`: \`${cls}\` starts like a design decision and reads as nothing - usually a typo in the source, and the element renders without it today`);
                 }
                 node_.part = key;
+                /**
+                 * WHICH SKETCH NODE BECAME THIS PART.
+                 *
+                 * The only place both facts exist at once. A lookup table whose value is an
+                 * object carries one field per element - their `statusConfig` has `dotClass`
+                 * for the dot and `colorClass` for the label - and the reader can say WHICH
+                 * element by the call site's class string, which is an index. Turning that
+                 * index into a part name is this walk's job and nobody else's.
+                 */
+                if (typeof node.at === "number")
+                    partAt[node.at] = key;
+                /**
+                 * A HAND-WRITTEN READ NAMES ITS CLASSES, not an index - the skill's own
+                 * examples do. The string is the sketch's own, so matching it back is exact,
+                 * and without this the per-part attribution would work on a derived anatomy
+                 * and quietly do nothing on an authored one.
+                 */ else if (raw) {
+                    const found = (sketch ?? []).findIndex((n) => n.classes === raw);
+                    if (found >= 0 && !partAt[found])
+                        partAt[found] = key;
+                }
             }
             const text = typeof node.text === "string" ? node.text.trim() : "";
             if (text)
@@ -434,6 +456,7 @@ sketch) {
         composes,
         external,
         notes,
+        partAt,
         ...(rootOut ? { root: rootOut } : {}),
     };
 }
@@ -454,5 +477,5 @@ export function resolveFlatParts(read, declared) {
         const t = transcribe(part.classes.split(/\s+/).filter(Boolean), declared);
         parts[name] = { base: t.base, dark: t.dark, states: t.states };
     }
-    return { parts, tree: [], composes: [], external: [], notes: [] };
+    return { parts, tree: [], composes: [], external: [], notes: [], partAt: {} };
 }

package/dist/commands/import.js

@@ -16,6 +16,7 @@ import { crosswalk, floorSize, isLibrary, observedRules, useLiveCatalogue, } fro
 import { moduleImports, readModuleCss, readModuleUsage, transcribeModule, } from "../doctor/css-modules.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
+import { callSiteNode, placeLayers, } from "../doctor/place-layers.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
@@ -427,6 +428,12 @@ export async function takeCensus(root, opts) {
                     }
                 }
                 const t = transcribe(rootClasses(src, found[0].name), declaredValues);
+                /**
+                 * The transcription carries `dark` too, and spreading it put the key back after
+                 * the conditional below decided to leave it out. Two writers for one field is
+                 * how a decision gets undone by the line above it.
+                 */
+                const { dark: _measuredDark, ...withoutDark } = t;
                 /**
                  * THE VARIANT STYLES, FOLDED IN.
                  *
@@ -518,18 +525,49 @@ export async function takeCensus(root, opts) {
                  * the owner's rule, adopted verbatim (dono, 01/08).
                  */
                 const sketch = sketchOf(src, found[0].name);
+                /**
+                 * A PER-PART LAYER FINDS ITS NODE, by the class string of the call site that
+                 * consumes the field. See `ReadLayer.onClasses`: the reader knows a
+                 * `statusConfig.dotClass` is written on the element whose `className` reads
+                 * `cn("relative size-2 rounded-full", config.dotClass)`, and that literal is
+                 * exactly what the sketch stored - so this is a lookup, not a second parse.
+                 *
+                 * An index rather than the string, because the anatomy already names nodes by
+                 * index and `resolveReadParts` moves the layer onto the part that node became.
+                 */
+                const placed = layers.map((layer) => {
+                    const on = layer.onClasses;
+                    if (!on)
+                        return layer;
+                    const { onClasses: _drop, ...rest } = layer;
+                    const at = callSiteNode(sketch, on);
+                    return at === null ? rest : { ...rest, on: at };
+                });
                 if (size > 0 || tag) {
                     looks[found[0].name] = {
                         ...(sketch.length > 0 ? { sketch } : {}),
-                        ...t,
+                        ...withoutDark,
                         base,
                         states,
-                        dark,
+                        /**
+                         * OMITTED WHEN EMPTY, so a real loss is legible.
+                         *
+                         * `dark` is a field of the READING, not of the contract - the platform
+                         * converts it into a `{when:{scheme:"dark"}}` layer, which is the one way
+                         * a recipe says dark. Emitting the key regardless made a validator report
+                         * all 36 components as "not arriving whole" for a key with nothing in it,
+                         * and the 7 that carry a real value were buried in the noise
+                         * (not-expressed.md, dono, 03/08). 29 of 36 were empty.
+                         */
+                        ...(Object.keys(dark).length > 0 ? { dark } : {}),
                         ...(Object.keys(parts).length > 0 ? { parts } : {}),
                         ...(tree.length > 0 ? { tree } : {}),
                         ...(tag ? { rootTag: tag } : {}),
                         ...rootPackage(tag, sketch),
-                        ...(layers.length > 0 ? { layers } : {}),
+                        ...(placed.length > 0 ? { layers: placed } : {}),
+                        ...(v.unslotted.length > 0
+                            ? { unplaced: [...new Set(v.unslotted)] }
+                            : {}),
                         ...(Object.keys(v.axes).length > 0 ? { declaredAxes: v.axes } : {}),
                         ...(Object.keys(defaults).length > 0 ? { defaults } : {}),
                     };
@@ -842,7 +880,7 @@ export async function takeCensus(root, opts) {
      */
     const coverage = summarizeCoverage(shapes, componentFiles, Object.keys(looks).length, Object.values(looks).reduce((n, look) => n +
         Object.keys(look.base).length +
-        Object.keys(look.dark).length +
+        Object.keys(look.dark ?? {}).length +
         Object.values(look.states).reduce((m, block) => m + Object.keys(block).length, 0) +
         // The LAYERS count: the record and ternary readers produce layers rather than a
         // base, so leaving them out reported a Tag with eight colours as three
@@ -873,6 +911,31 @@ export async function takeCensus(root, opts) {
             console.log(body(line));
         console.log(body(paint.faint("Do not go looking for any of this - it is measured, and a sweep would bring back a different slice than the next one.")));
     }
+    /**
+     * WHAT THE READER UNDERSTOOD AND REFUSED TO PLACE.
+     *
+     * The other half of the same honesty: a look with nowhere to go is not put on the
+     * component, and a component that quietly lost a decision looks like our bug. See
+     * `Transcription.unplaced` for what earns a line here.
+     */
+    const unplacedByComponent = Object.entries(looks)
+        .filter(([, look]) => (look.unplaced ?? []).length > 0)
+        .map(([component, look]) => ({
+        component,
+        lines: look.unplaced ?? [],
+    }));
+    if (unplacedByComponent.length > 0) {
+        const total = unplacedByComponent.reduce((n, u) => n + u.lines.length, 0);
+        console.log("");
+        console.log(section("Conditional looks that were read and not placed"));
+        console.log(body(`${total} decision${total === 1 ? "" : "s"} across ${unplacedByComponent.length} component${unplacedByComponent.length === 1 ? "" : "s"} were understood and left off, because putting them on the component would paint the wrong element:`));
+        for (const u of unplacedByComponent.slice(0, 8)) {
+            console.log(body(paint.faint(`  ${u.component}: ${u.lines[0]}`)));
+        }
+        if (unplacedByComponent.length > 8) {
+            console.log(body(paint.faint(`  and ${unplacedByComponent.length - 8} more components`)));
+        }
+    }
     /**
      * THE DROPS, SAID OUT LOUD. `p-spacing-sm` on a real menu popup read as nothing and
      * the popup shipped with no padding, invisibly - "if the compiler drops them, the drop
@@ -1774,8 +1837,34 @@ async function resolveReadParts(census, root) {
                 ...(lib.kind !== "own" ? { kind: lib.kind } : {}),
             })),
         ];
+        /**
+         * A PER-PART LAYER LANDS ON ITS PART.
+         *
+         * The reader attributed it to a sketch INDEX (see `Transcription.layers[].on`);
+         * the anatomy is what turns an index into a part name. So this is the first
+         * moment both halves exist - the same reason the reading is resolved here at all.
+         *
+         * A layer whose node no part claims stays OFF the component: pinning it to the
+         * root is exactly the bug, and it is reported instead.
+         */
+        const partAt = resolved.partAt ?? {};
+        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. */
+        for (const [part, list] of split.perPart) {
+            const target = resolved.parts[part];
+            if (!target || !list)
+                continue;
+            target.layers = [
+                ...(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 } : {}),
             ...(resolved.tree.length > 0 ? { tree: resolved.tree } : {}),
             ...(resolved.composes.length > 0 ? { composes: resolved.composes } : {}),
             ...(libraries.length > 0 ? { external: libraries } : {}),

package/dist/doctor/broken-refs.js

@@ -17,8 +17,51 @@
  * this product has (dono, 01/08: "a normalização será de acordo com cada
  * projeto").
  */
+import { frontierKind } from "../frontier-kind.js";
+import { importMap } from "./imports.js";
 /** `var(--x)`, including inside a Tailwind arbitrary value: `bg-[var(--x)]`. */
 const VAR_REF = /var\(\s*(--[a-zA-Z0-9_-]+)/g;
+/**
+ * VARIABLES A HEADLESS LIBRARY SETS AT RUNTIME, which no stylesheet can declare.
+ *
+ * Base UI measures the trigger and writes `--anchor-width` on the positioner element
+ * before paint, so `min-w-[var(--anchor-width)]` on their Select is correct and works.
+ * Counting it as a broken reference told the owner their own code was defective, and it
+ * cost the report its credibility on the twelve that ARE broken (not-expressed.md,
+ * dono, 03/08). Two of their thirteen were this.
+ *
+ * The list is the SHARED vocabulary of headless positioning - Base UI, Radix, Ark and
+ * Floating UI all name the anchor's width `--anchor-width` - plus the self-identifying
+ * per-library prefixes. Same reasoning as `NON_RENDERING` in `frontier-kind.ts`: a name
+ * is only read after the PACKAGE has answered.
+ */
+const RUNTIME_ANCHOR = new Set([
+    "--anchor-width",
+    "--anchor-height",
+    "--available-width",
+    "--available-height",
+    "--transform-origin",
+    "--popup-width",
+    "--popup-height",
+    "--trigger-width",
+    "--trigger-height",
+]);
+/** `--radix-popper-anchor-width` and its siblings in the other libraries. */
+const RUNTIME_PREFIX = /^--(?:radix|reka|ark|kb|floating|reactour)-/;
+/**
+ * Does this file import a library that supplies such a variable?
+ *
+ * THE PACKAGE DECIDES, never the variable name on its own: a project that declares no
+ * headless dependency and writes `var(--anchor-width)` really has written a reference
+ * to nothing, and saying so is the whole value of this scan.
+ */
+function importsHeadless(source) {
+    for (const spec of Object.values(importMap(source))) {
+        if (frontierKind(spec) === "headless")
+            return true;
+    }
+    return false;
+}
 /**
  * PREFIXES A DECLARATION MAY CARRY that a reference dropped.
  *
@@ -46,10 +89,13 @@ const NAMESPACES = [
 export function findBrokenRefs(sources, declared) {
     const seen = new Map();
     for (const { file, source } of sources) {
+        const runtime = importsHeadless(source);
         for (const m of source.matchAll(VAR_REF)) {
             const name = m[1];
             if (declared.has(name))
                 continue;
+            if (runtime && (RUNTIME_ANCHOR.has(name) || RUNTIME_PREFIX.test(name)))
+                continue;
             const hit = seen.get(name) ?? { count: 0, files: new Set() };
             hit.count += 1;
             hit.files.add(file);

package/dist/doctor/place-layers.js

@@ -0,0 +1,78 @@
+/**
+ * WHOSE LOOK IS IT - the step between reading a lookup table and styling anything.
+ *
+ * A conditional look read off a record is not automatically the component's. Their
+ * CollapsibleCard keeps one table for four statuses:
+ *
+ *     statusConfig.success = { dotClass: "bg-success-500 shadow-[…]",
+ *                              colorClass: "text-success-500", text: "Completed" }
+ *
+ * `dotClass` is worn by a 8px dot and `colorClass` by the label beside it, and merging
+ * them onto the component painted a white card with the dot's grey - four runs in a row
+ * where the owner saw a grey card and a status that had nothing to do with it
+ * (dono, 03/08). The same shape with a plain string is the bigger half: their
+ * HorizontalProgress writes `variantColors[variant]` on the FILL, so six colours landed
+ * on the outer wrapper and the whole component turned ocean-500.
+ *
+ * Measured across their library, 36 component files (dono, 03/08):
+ *
+ *     65   conditional looks come off a lookup table
+ *     28   belong to an element INSIDE the component  <- painted the component before
+ *     37   belong to the returned element             <- already correct, unchanged
+ *      0   could not be resolved
+ *
+ * THE READER SAYS WHICH ELEMENT BY ITS CLASS STRING, because that is the one thing
+ * both halves of the pipeline already hold: `ReadLayer.onClasses` is the unconditional
+ * part of the `className` call that consumes the field, and the sketch stored exactly
+ * that string for the node. So this is a lookup rather than a second parse of the JSX.
+ */
+/**
+ * The sketch index of the element whose `className` call was read, or null.
+ *
+ * Exact on the whole string: the sketch and the reader build it from the same
+ * unconditional literals, so a partial match would mean one of them changed its rule
+ * and guessing past that is how a look lands on the wrong element.
+ */
+export function callSiteNode(sketch, onClasses) {
+    const at = sketch.findIndex((node) => node.classes === onClasses);
+    return at >= 0 ? at : null;
+}
+/** True when this index is the element the component returns. */
+export function isRootNode(sketch, at) {
+    const stamped = sketch.findIndex((node) => node.root);
+    return stamped >= 0 ? at === stamped : at === 0;
+}
+/**
+ * Split the layers into the ones the component wears and the ones its parts wear.
+ *
+ * `partAt` is the anatomy's answer - sketch index → the part name that node became,
+ * from `resolveAnatomy`. A layer whose node is the ROOT stays on the component, which
+ * is where a table indexed on the returned element belongs. A layer whose node no part
+ * names goes into `unplaced` instead of onto the component: pinning it to the root is
+ * exactly the bug this exists for.
+ */
+export function placeLayers(layers, partAt, sketch) {
+    const root = [];
+    const perPart = new Map();
+    const unplaced = [];
+    for (const layer of layers) {
+        const { on, ...rest } = layer;
+        if (typeof on !== "number") {
+            root.push(rest);
+            continue;
+        }
+        const part = partAt[on];
+        if (part) {
+            const list = perPart.get(part) ?? [];
+            list.push(rest);
+            perPart.set(part, list);
+            continue;
+        }
+        if (isRootNode(sketch, on)) {
+            root.push(rest);
+            continue;
+        }
+        unplaced.push(`a conditional look belongs to an element the anatomy does not name, so it is not applied to the component - that would paint the wrong element`);
+    }
+    return { root, perPart, unplaced };
+}

package/dist/doctor/variant-read.js

@@ -548,11 +548,120 @@ export function readInlineConditions(source) {
 const LOOKUP_RECORD = /(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::\s*(?:Record|Partial<Record)<[^>]*>+)?\s*=\s*\{/g;
 /** `colorStyles[color]` - the record, and the prop that indexes it. */
 const RECORD_INDEX = /([A-Za-z_$][\w$]*)\s*\[\s*([A-Za-z_$][\w$]*)\s*\]/g;
+/**
+ * The FIELDS of an option whose value is an object, or `[]` when it is a plain
+ * string. `{ dotClass: "bg-x", text: "Waiting" }` → two entries.
+ */
+function objectFields(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("{"))
+        return [];
+    const end = endOf(trimmed, 0);
+    if (end === -1)
+        return [];
+    return topLevelEntries(trimmed.slice(1, end - 1));
+}
+/**
+ * THE STATIC CLASSES OF THE `className` CALL THAT CONSUMES A LOOKUP.
+ *
+ * `cn("relative size-2 rounded-full", config.dotClass)` identifies the element
+ * without a second parse of the JSX: that literal is exactly what the sketch stored
+ * for the node, so the caller can resolve it to an index and move the layer onto the
+ * part it belongs to.
+ *
+ * TWO SPELLINGS, because both are real in one library. A field is matched by the FIELD
+ * name and the symbol is matched loosely, since their code reads the record into a
+ * local first (`const config = statusConfig[status]`); a record whose value is a plain
+ * string has no field, and there the indexing expression is what is written at the call
+ * site (`variantColors[variant]`), so the SYMBOL is the reliable half.
+ */
+function callSiteClasses(source, symbol, field) {
+    const use = field
+        ? new RegExp(`\\b[A-Za-z_$][\\w$]*(?:\\[[^\\]]*\\])?\\.${field}\\b`)
+        : new RegExp(`\\b${symbol}\\s*\\[`);
+    for (const m of source.matchAll(/className=\{\s*(?:[A-Za-z_$][\w$]*\.)?(?:cn|clsx|classNames|cx|twMerge|twJoin|classcat)\(/g)) {
+        const open = (m.index ?? 0) + m[0].length - 1;
+        const end = endOf(source, open);
+        if (end === -1)
+            continue;
+        const call = source.slice(open + 1, end - 1);
+        if (!use.test(call))
+            continue;
+        const statics = unconditionalClasses(call);
+        return statics.length > 0 ? statics.join(" ") : null;
+    }
+    return null;
+}
+/**
+ * THE CLASSES THE ELEMENT ALWAYS HAS, which is the only half that identifies it.
+ *
+ * Every string literal in the call is not the answer: their Card writes
+ * `borderColor === "vibrant" && variant === "full-border" && "dark:after:…"`, so a
+ * blanket read picks up the mask gradient AND the two comparison operands, and the
+ * result matches no element in the sketch. The sketch stores the unconditional
+ * literals, so this has to read the same thing or the lookup cannot land.
+ *
+ * An argument is unconditional when it is a string and nothing else - one literal,
+ * no `&&`, no `?:`, no identifier.
+ */
+function unconditionalClasses(call) {
+    const out = [];
+    let depth = 0;
+    let quote = "";
+    let start = 0;
+    const args = [];
+    for (let i = 0; i < call.length; i++) {
+        const c = call[i];
+        if (quote) {
+            if (c === "\\")
+                i++;
+            else if (c === quote)
+                quote = "";
+            continue;
+        }
+        if (c === '"' || c === "'" || c === "`")
+            quote = c;
+        else if ("([{".includes(c))
+            depth++;
+        else if (")]}".includes(c))
+            depth--;
+        else if (c === "," && depth === 0) {
+            args.push(call.slice(start, i));
+            start = i + 1;
+        }
+    }
+    args.push(call.slice(start));
+    for (const arg of args) {
+        const trimmed = arg.trim();
+        if (!/^(["'`])/.test(trimmed))
+            continue;
+        // A literal followed by anything else is a condition, not a constant.
+        const closed = endOfString(trimmed);
+        if (closed === -1 || trimmed.slice(closed).trim())
+            continue;
+        out.push(...literalClasses(trimmed));
+    }
+    return out;
+}
+/** The index just past the closing quote of the string that starts at 0, or -1. */
+function endOfString(text) {
+    const quote = text[0];
+    for (let i = 1; i < text.length; i++) {
+        if (text[i] === "\\")
+            i++;
+        else if (text[i] === quote)
+            return i + 1;
+    }
+    return -1;
+}
 export function readLookupRecords(source, 
 /** Filled with axis → options, because the axis NAMES have to travel too: a first pass
  *  sent the styles and not the names, so a Tag with eight colours reported no axis at
  *  all (probe, 01/08). */
-axesOut) {
+axesOut, 
+/** Fields of a per-part table that no `className` call claims - said out loud
+ *  rather than pinned to the root. See `ReadLayer.onClasses`. */
+unattributed) {
     const clean = stripComments(source);
     // Which prop indexes which record. Read first, because a record nobody indexes is a
     // constant rather than a variant axis.
@@ -584,10 +693,49 @@ axesOut) {
             axesOut[axis] = [...new Set([...(axesOut[axis] ?? []), ...names])];
         }
         for (const option of options) {
-            const per = splitByCondition(literalClasses(option.value), {
-                [axis]: option.key,
-            });
-            layers.push(...per.layers);
+            /**
+             * A VALUE THAT IS AN OBJECT IS A PER-PART TABLE, and merging its fields is
+             * what painted a card with its status dot's grey. Read field by field, and
+             * attribute each one to the element that consumes it.
+             */
+            const fields = objectFields(option.value);
+            if (fields.length === 0) {
+                /**
+                 * A STRING-VALUED RECORD IS STILL SOMEBODY'S ELEMENT, and it is the bigger
+                 * half of the form: their HorizontalProgress writes `variantColors[variant]`
+                 * on the FILL, and six colours landed on the outer wrapper - the whole
+                 * component painted ocean-500 instead of the bar inside it.
+                 *
+                 * Unattributed here means the call site could not be found, and that is the
+                 * old behaviour: the layer stays on the component, which is where a record
+                 * consumed at the root belongs anyway.
+                 */
+                const on = callSiteClasses(clean, symbol);
+                const per = splitByCondition(literalClasses(option.value), {
+                    [axis]: option.key,
+                });
+                for (const layer of per.layers)
+                    layers.push(on ? { ...layer, onClasses: on } : layer);
+                continue;
+            }
+            for (const field of fields) {
+                const classes = literalClasses(field.value);
+                if (classes.length === 0)
+                    continue;
+                const on = callSiteClasses(clean, symbol, field.key);
+                if (!on) {
+                    /**
+                     * NOWHERE TO PUT IT IS NOT THE ROOT. A field no `className` claims is a
+                     * decision we cannot place, and placing it on the component would paint
+                     * the wrong element - which is the whole bug this reads around.
+                     */
+                    unattributed?.push(`\`${symbol}.${field.key}\` is a field of a per-element table that no \`className\` call consumes, so there is no element to put it on`);
+                    continue;
+                }
+                const per = splitByCondition(classes, { [axis]: option.key });
+                for (const layer of per.layers)
+                    layers.push({ ...layer, onClasses: on });
+            }
         }
     }
     return layers;
@@ -645,17 +793,17 @@ export function readClassTernaries(source) {
 export function transcribeVariants(source, declared) {
     const reads = readVariants(source);
     const fromRecords = {};
+    const unslotted = [];
     const inline = [
         ...readInlineConditions(source),
         // The two shapes the enumeration found to be five times more common than `cva`.
-        ...readLookupRecords(source, fromRecords),
+        ...readLookupRecords(source, fromRecords, unslotted),
         ...readClassTernaries(source),
     ];
     const axes = {};
     const defaults = {};
     const allLayers = [];
     const baseClasses = [];
-    const unslotted = [];
     for (const read of reads) {
         baseClasses.push(...read.base);
         allLayers.push(...read.layers);
@@ -674,6 +822,51 @@ export function transcribeVariants(source, declared) {
         if (options.length >= 2)
             axes[axis] = options;
     }
+    /**
+     * AN AXIS A LAYER GATES ON MUST BE DECLARED - or the default cannot be emitted.
+     *
+     * The same pass emitted a layer gated on `variant` and did not register `variant`
+     * as an axis: measured on a real library, 30 of 148 root layers name an axis
+     * `declaredAxes` never lists, and four of those are REAL option axes
+     * (`Input.variant`, `Textarea.variant`, `SelectionCard.size`, `RadioCard.status`).
+     * Undeclared means `defaults` cannot name it, so the compiler never emits the
+     * resting option at the bare selector - the same mechanism that made a button
+     * arrive with no fill (dono, 03/08).
+     *
+     * A gate whose values are only `true`/`false` is a BOOLEAN condition, not a design
+     * axis: `isLoading`, `isUser`, `darkMode`, and even an `onInfoClick` handler read
+     * that way. Those keep their layer - their code really does change look - and are
+     * named in `unslotted`, because a consumer has to set the attribute for it to fire
+     * and silence would make it dead CSS nobody knows about.
+     */
+    const BOOLEANISH = new Set(["true", "false"]);
+    const gated = {};
+    for (const layer of allLayers) {
+        for (const [axis, option] of Object.entries(layer.when?.variant ?? {})) {
+            const seen = gated[axis] ?? new Set();
+            seen.add(option);
+            gated[axis] = seen;
+        }
+    }
+    for (const [axis, options] of Object.entries(gated)) {
+        if (axes[axis])
+            continue;
+        const named = [...options].filter((o) => !BOOLEANISH.has(o));
+        /**
+         * TWO OPTIONS IS WHAT MAKES AN AXIS, and that rule is older than this one: one
+         * option is not a closed set somebody chose from, it is how the component is
+         * always used - and declaring it would turn every other value into drift on the
+         * strength of a single sighting.
+         */
+        if (named.length >= 2) {
+            axes[axis] = named;
+            continue;
+        }
+        const attr = axis.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+        unslotted.push(named.length === 0
+            ? `\`${axis}\` gates a look and is a boolean rather than an axis - the layer is kept, and \`data-${attr}\` has to be set for it to apply`
+            : `\`${axis}\` gates a look on one option (\`${named[0]}\`) - one option is not an axis, so the layer is kept and \`data-${attr}="${named[0]}"\` has to be set for it to apply`);
+    }
     const layers = allLayers
         .map((layer) => {
         /**
@@ -690,6 +883,7 @@ export function transcribeVariants(source, declared) {
         return {
             ...(layer.when ? { when: layer.when } : {}),
             ...(layer.at ? { at: layer.at } : {}),
+            ...(layer.onClasses ? { onClasses: layer.onClasses } : {}),
             style,
         };
     })

package/dist/skill-import.js

@@ -388,9 +388,15 @@ Open the project and answer the questions below. Then add a \`reading\` object t
           "name": "body",
           "at": 2,
           "children": [
-            { "as": "text", "name": "label", "at": 3 },
+            { "as": "component", "ref": "Text", "at": 3 },
             { "as": "heading", "name": "value", "at": 4 }
           ]
+        },
+        {
+          "as": "component",
+          "ref": "Tooltip",
+          "at": 5,
+          "children": [{ "as": "icon", "name": "info", "at": 6 }]
         }
       ]
     },
@@ -399,7 +405,7 @@ Open the project and answer the questions below. Then add a \`reading\` object t
       "anatomy": [
         { "as": "image", "name": "cover", "at": 1 },
         { "as": "heading", "name": "title", "at": 2 },
-        { "as": "component", "ref": "TextEditor" },
+        { "as": "component", "ref": "TextEditor", "at": 5 },
         {
           "as": "row",
           "name": "footer",
@@ -702,6 +708,21 @@ because a button's content model is *phrasing* and an icon is phrasing. So an \`
 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\`.
 
+**A frontier keeps its own \`at\`, so it keeps its own classes.** This is the one that gets
+talked out of: \`<Text className="text-lightgray-500 font-medium">\` is one of THEIR
+components, so it is a \`component\` node - and pointing \`at\` its sketch index carries the
+typography onto it exactly as a part would. Reading it as a \`text\` part instead is a
+downgrade with a real cost: \`composes\` is built from \`component\` nodes, so a library whose
+most-used atom is composed 363 times reported composing it ZERO times, and its strongest
+composition law became invisible (not-expressed.md, dono, 03/08).
+
+    <Tooltip><Info/></Tooltip>          frontier with a child, both survive
+    <Text className="…">Label</Text>    frontier with "at", the type survives
+
+If you find yourself writing "the contract cannot hold this, so I sent something else",
+check it against \`recipe_vocabulary\` before you write the workaround - and if the check
+disagrees with this file, the check is right and this file is old.
+
 ### \`{children}\` is a node, not an absence
 
 Four things decide what a component looks like on screen, and only the first is in its own source:
@@ -847,6 +868,18 @@ a recipe before these tools existed, and four separate readings were lost in sil
 \`dark:\` inside a variant, a state the compiler cannot spell, a part name with a dot in it,
 a layer with an empty style. Each of those was correct work that arrived as nothing.
 
+**A FIELD OF THE READING IS NOT A FIELD OF THE RECIPE.** \`looks[X].dark\` is how the census
+reports a dark half it measured; a recipe has one way to say the same thing, and it is a
+layer:
+
+\`\`\`json
+{ "when": { "scheme": "dark" }, "style": { "backgroundColor": "{color.darkgray.300}" } }
+\`\`\`
+
+Copying \`dark\` in at the top level of a recipe costs you that block, silently, on every
+component that has one - and \`import\` already converts it for the recipes IT writes, so the
+only place this can be lost is a recipe you hand-built (not-expressed.md, dono, 03/08).
+
 **In ONE call.** Build every recipe in memory, then send the whole reading to
 \`validate_recipes\` - one round trip for 35 components instead of 35. \`validate_recipe\`
 (singular) is for the one recipe you rewrote after the batch named it; reaching for it in a

package/package.json

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