synthesisui 0.16.119 → 0.16.121

package/dist/anatomy-from-sketch.js

@@ -317,27 +317,30 @@ versionOf) {
          * 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.
+         * the Canvas to draw, and an element the snippet emits.
+         *
+         * A MOTION WRAPPER IS THE SAME CASE, and it was flattened on the grounds that its
+         * element is "genuinely absent from the output". True of the Canvas, which draws no box
+         * for it; false of the code, where `AnimatePresence` is the difference between an
+         * `exit` animation that runs and one that cannot. Their panel carries
+         * `exit={{ height: 0 }}`, we copied it faithfully into the snippet, and with the
+         * wrapper flattened away it could never fire - the element unmounts before anything
+         * animates (dono, 04/08).
          */
-        if (kind === "headless" && rendersNothing(tag, classes)) {
+        if ((kind === "headless" || kind === "motion") &&
+            (rendersNothing(tag, classes) || (!classes && children.length > 0))) {
             const held = children.flatMap((child) => build(child, depth + 1));
             return [
                 {
                     as: held.length > 0 ? "stack" : "text",
                     from: String(node.from ?? tag),
                     refName: tag,
+                    /** Its own index, so its guard and its props are still reachable - see `at`. */
+                    at: index,
                     ...(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.
-        if (kind === "motion" && !classes && children.length > 0) {
-            return children.flatMap((child) => build(child, depth));
-        }
         const descend = () => children.flatMap((child) => build(child, depth + 1));
         /**
          * THEIR OWN COMPONENT, and a library that draws itself: a reference, and it
@@ -349,7 +352,20 @@ versionOf) {
                 {
                     as: "component",
                     ref: tag,
-                    ...(classes ? { at: index } : {}),
+                    /**
+                     * THE INDEX IS THE NODE'S IDENTITY ON THE SKETCH, not a pointer to its classes.
+                     *
+                     * Gated on `classes`, it meant a class-less node had no way back to what the
+                     * sketch measured about it - and that is five facts, not one: the guard, the
+                     * resting verdict, the animation props, the expression it writes and the props
+                     * that make it inert. Their `Collapsible.Panel` carries no class and is guarded
+                     * by `isOpen && !isLoading`, so the snippet showed an open panel as the resting
+                     * state of a card that starts closed (dono, 04/08).
+                     *
+                     * Costs nothing: the two places that read `at` for styles take the classes at
+                     * that index, and at a class-less index that is the empty string it already was.
+                     */
+                    at: index,
                     ...(children.length > 0 ? { children: descend() } : {}),
                 },
             ];
@@ -364,13 +380,30 @@ versionOf) {
                 {
                     as: "external",
                     from: String(node.from ?? tag),
-                    ...(classes ? { at: index } : {}),
+                    at: index,
                     ...(children.length > 0 ? { children: descend() } : {}),
                 },
             ];
         }
         if (kind === "icon") {
-            return [{ as: "icon", name: nameOfTag(tag), at: index }];
+            /**
+             * AN ICON IS THEIR ELEMENT WEARING OUR CLASS.
+             *
+             * `<ChevronUp className="size-5 …" />` - the glyph is the library's and every pixel
+             * of size and colour is in their class list, which is why it is a part of ours. The
+             * snippet emitted `<span className="ds-collapsible-card-chevron-up">…</span>`: the
+             * right box in the right place, drawing nothing, and nothing in his repo spelled
+             * that way (dono, 04/08). The name of the part is already their tag; the element
+             * should be too.
+             */
+            return [
+                {
+                    as: "icon",
+                    name: nameOfTag(tag),
+                    at: index,
+                    ...(node.from ? { from: String(node.from), refName: tag } : {}),
+                },
+            ];
         }
         /**
          * EVERYTHING ELSE IS DRAWN: plain HTML, a headless primitive, and a
@@ -467,13 +500,19 @@ versionOf) {
          * 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
+        /**
+         * MOTION COUNTS THE SAME WAY. `AnimatePresence` carries no class and draws no pixel,
+         * and it is what lets the panel's `exit` animation run at all - without it the exit
+         * props are copied into the snippet and can never fire, because the element unmounts
+         * before anything animates. Headless-only dropped it (dono, 04/08).
+         */
+        const fromLib = (kind === "headless" || kind === "motion") && node.from
             ? { from: String(node.from), refName: tag }
             : {};
         const built = {
             as,
             ...(name ? { name } : {}),
-            ...(classes ? { at: index } : {}),
+            at: index,
             ...fromLib,
             ...(node.text ? { text: node.text } : {}),
         };

package/dist/anatomy-read.js

@@ -278,6 +278,16 @@ sketch) {
                 const atRest = node.atRest ?? measured?.atRest;
                 if (atRest === false)
                     node_.atRest = false;
+                /**
+                 * WHAT THE NODE WRITES AND WHICH BEHAVIOUR PROPS IT CARRIES - the two facts that
+                 * turn a styled shell into a component somebody can rebuild. Same lookup as the
+                 * guard, one line up: measured on the sketch, dropped by every seam after it.
+                 */
+                if (measured?.contentFrom)
+                    node_.contentFrom = measured.contentFrom;
+                if (measured?.behaviourProps &&
+                    Object.keys(measured.behaviourProps).length > 0)
+                    node_.behaviourProps = measured.behaviourProps;
             }
             else {
                 if (node.when)
@@ -325,6 +335,16 @@ sketch) {
                     node_.from = measured.from;
                     node_.refName = measured.tag;
                 }
+            }
+            /**
+             * THE ANIMATION PROPS COME OFF THE SKETCH WHATEVER ELSE IS KNOWN.
+             *
+             * They used to hang off the branch that had to GUESS the element from the sketch, so
+             * a node whose reading already named its package - which is every restored library
+             * wrapper - lost them.
+             */
+            if (typeof node.at === "number" && !node_.motionProps) {
+                const measured = sketch?.[node.at];
                 if (measured?.motionProps)
                     node_.motionProps = measured.motionProps;
             }

package/dist/commands/import.js

@@ -14,6 +14,7 @@ import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, }
 import { countShape, describeCoverage, summarizeCoverage, } from "../doctor/coverage.js";
 import { crosswalk, floorSize, isLibrary, observedRules, useLiveCatalogue, } from "../doctor/crosswalk.js";
 import { keyframeOffsets, moduleImports, readModuleCss, readModuleUsage, transcribeModule, } from "../doctor/css-modules.js";
+import { dataContract } from "../doctor/data-contract.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";
@@ -24,7 +25,7 @@ import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "
 import { sketchOf } from "../doctor/sketch.js";
 import { describeForeign, readStyleIslands, } from "../doctor/style-island.js";
 import { buildTable } from "../doctor/tokens.js";
-import { readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
+import { definitionSpan, readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
 import { frontierKind } from "../frontier-kind.js";
 import { withLibraryStructure } from "../library-structure.js";
@@ -441,6 +442,7 @@ export async function takeCensus(root, opts) {
                             ...et,
                             ...(etag ? { rootTag: etag } : {}),
                             ...rootPackage(etag, esketch),
+                            ...rootBehaviour(etag, esketch),
                         };
                     }
                 }
@@ -659,6 +661,7 @@ export async function takeCensus(root, opts) {
                         ...(tree.length > 0 ? { tree } : {}),
                         ...(tag ? { rootTag: tag } : {}),
                         ...rootPackage(tag, sketch),
+                        ...rootBehaviour(tag, sketch),
                         ...(placed.length > 0 ? { layers: placed } : {}),
                         ...(Object.keys(islandStyle).length > 0 ? { islandStyle } : {}),
                         ...(v.unslotted.length > 0
@@ -1206,35 +1209,63 @@ export async function takeCensus(root, opts) {
      * as not exported. See `publicApi`.
      */
     const api = await publicApi(root);
-    if (api) {
-        for (const c of components) {
-            const file = defined.find((d) => d.name === c.name)?.file;
-            const source = file
-                ? sources.find((s) => s.file.endsWith(file))?.source
-                : undefined;
-            const required = source ? requiredProps(source, c.name) : [];
-            c.api = {
-                /**
-                 * SILENCE WHEN THE ENTRY WAS NOT READ. An unreadable entry gives an empty export
-                 * set, and calling that "internal" would have marked every component internal at
-                 * once - see `PublicApi.read`.
-                 */
-                ...(!api.read
-                    ? {}
-                    : api.exports.has(c.name)
-                        ? { from: api.from }
-                        : { exported: false }),
-                /**
-                 * REPO-RELATIVE, so the answer needs no second search. `defined[].file` is
-                 * relative to the scope; joined with the scope it is a path anybody can check
-                 * with one `stat` - which is how `component` knows they already have it without
-                 * walking a monorepo (their component sits six levels below `packages/`, and the
-                 * shallow walk that guards against shadowing never reached it).
-                 */
-                ...(file ? { file: scopeLabel ? `${scopeLabel}/${file}` : file } : {}),
-                ...(required.length > 0 ? { required } : {}),
-            };
-        }
+    for (const c of components) {
+        const file = defined.find((d) => d.name === c.name)?.file;
+        const source = file
+            ? sources.find((s) => s.file.endsWith(file))?.source
+            : undefined;
+        const required = source ? requiredProps(source, c.name) : [];
+        /**
+         * THE COMPONENT'S DATA CONTRACT - its props, its derivations, the copy an option
+         * carries, and the type that names an axis's options.
+         *
+         * The owner asked whether the recipe was enough to rebuild the component in a new
+         * project, and it was not: everything missing was LOGIC, and all of it sits in the
+         * file already open here. See `dataContract`.
+         *
+         * Stamped whether or not the folder is a package: a `src/components` with no
+         * manifest of its own has no specifier to offer and its components still have props.
+         */
+        const span = source ? definitionSpan(source, c.name) : null;
+        const contract = source
+            ? dataContract(source, span ? source.slice(span.from, span.to) : source, c.name, (c.declaredAxes ?? {}))
+            : null;
+        c.api = {
+            /**
+             * SILENCE WHEN THE ENTRY WAS NOT READ. An unreadable entry gives an empty export
+             * set, and calling that "internal" would have marked every component internal at
+             * once - see `PublicApi.read`.
+             */
+            ...(!api?.read
+                ? {}
+                : api.exports.has(c.name)
+                    ? { from: api.from }
+                    : { exported: false }),
+            /**
+             * REPO-RELATIVE, so the answer needs no second search. `defined[].file` is
+             * relative to the scope; joined with the scope it is a path anybody can check
+             * with one `stat` - which is how `component` knows they already have it without
+             * walking a monorepo (their component sits six levels below `packages/`, and the
+             * shallow walk that guards against shadowing never reached it).
+             */
+            ...(file ? { file: scopeLabel ? `${scopeLabel}/${file}` : file } : {}),
+            ...(required.length > 0 ? { required } : {}),
+            ...(contract && contract.props.length > 0
+                ? { props: contract.props }
+                : {}),
+            ...(contract && Object.keys(contract.derived).length > 0
+                ? { derived: contract.derived }
+                : {}),
+            ...(contract && Object.keys(contract.optionText).length > 0
+                ? { optionText: contract.optionText }
+                : {}),
+            ...(contract && Object.keys(contract.axisType).length > 0
+                ? { axisType: contract.axisType }
+                : {}),
+        };
+        // An api with nothing in it is not a fact - it is an empty object on 36 components.
+        if (Object.keys(c.api).length === 0)
+            c.api = undefined;
     }
     const brokenRefs = findBrokenRefs(sources, declaredNames);
     const conventions = detectConventions(sources);
@@ -1878,6 +1909,27 @@ function rootPackage(tag, sketch) {
         ? { rootFrom: first.from }
         : {};
 }
+/**
+ * THE PROPS ON THE ELEMENT THE COMPONENT RETURNS, when their value is a condition.
+ *
+ * 6 of their 27 conditional props sit on the root, and every one of the six is the prop
+ * that makes the component controlled: `open={isOpen && !isLoading}` on their
+ * `Collapsible.Root`, `checked={isChecked}` on a `Switch.Root`, `disabled` on a
+ * `Field.Root`. Those are what somebody rebuilding it in another project has to wire, and
+ * the root travelled with its tag, its package and its classes and none of its props
+ * (dono, 04/08).
+ *
+ * Off the FIRST sketch node, which is the returned element - the same lookup `rootPackage`
+ * makes one line up, guarded the same way.
+ */
+function rootBehaviour(tag, sketch) {
+    const first = sketch[0];
+    if (!tag || !first || first.tag !== tag)
+        return {};
+    return first.behaviourProps && Object.keys(first.behaviourProps).length > 0
+        ? { rootProps: first.behaviourProps }
+        : {};
+}
 async function resolveReadParts(census, root) {
     /**
      * A READING IS OPTIONAL HERE. THE SKETCH IS NOT.

package/dist/doctor/data-contract.js

@@ -0,0 +1,170 @@
+/**
+ * THE COMPONENT'S DATA CONTRACT - what it takes, what it derives, what it writes.
+ *
+ * The pipeline reads appearance and structure well, and a recipe made of those two can be
+ * RECONSTRUCTED here and not REGENERATED somewhere else. The owner asked for the second
+ * thing (dono, 04/08): from the recipe, in a new project, Claude should write a component
+ * that behaves the same in that project's own vocabulary.
+ *
+ * What was missing is all logic, and all of it is in the file we already open:
+ *
+ *     the props, with their types and which are required     29 of their 38 declare one
+ *     the derivations                `const isLoading = status === "loading"`      9
+ *     the text a lookup table holds  `statusConfig.waiting.text = "Waiting"`       6
+ *     the exported type of an axis   `type CollapsibleCardStatus = "waiting" | …`  3
+ *
+ * NONE OF IT IS INFERRED. A prop with no type says no type; a table with no text says no
+ * text. The one thing this refuses to do is invent a shape - a component whose props come
+ * from `React.ComponentProps<"div">` gets an empty list, because guessing which props
+ * somebody must pass is worse than saying nothing.
+ */
+/** `export type CollapsibleCardStatus = "waiting" | "fail" | …` */
+const UNION = /export\s+type\s+([A-Za-z_$][\w$]*)\s*=\s*((?:"[^"]*"\s*\|\s*)+"[^"]*")\s*;/g;
+/** The first `{ … }` of a `({ … })` parameter list, balanced. */
+function paramBlock(body) {
+    const open = body.indexOf("({");
+    if (open === -1)
+        return null;
+    let depth = 0;
+    for (let i = open + 1; i < body.length; i++) {
+        if (body[i] === "{")
+            depth++;
+        else if (body[i] === "}") {
+            depth--;
+            if (depth === 0)
+                return body.slice(open + 2, i);
+        }
+    }
+    return null;
+}
+/** Split on top-level commas, so `{ a = { b: 1 }, c }` reads as two entries. */
+function topLevel(text) {
+    const out = [];
+    let depth = 0;
+    let part = "";
+    for (const c of text) {
+        if ("([{".includes(c))
+            depth++;
+        else if (")]}".includes(c))
+            depth--;
+        if (c === "," && depth === 0) {
+            out.push(part);
+            part = "";
+        }
+        else
+            part += c;
+    }
+    out.push(part);
+    return out;
+}
+/**
+ * Their props interface, field by field - name, type, and whether it is required.
+ *
+ * Named after the component when they name it that way (29 of their 38 do), and the first
+ * `*Props` in the file otherwise. Nothing at all when they extend a library's type: the
+ * fields are not there to read and a list of ours would be an invention.
+ */
+function propsFromType(source, name) {
+    const scoped = new RegExp(`(?:export\\s+)?(?:interface|type)\\s+${name}Props\\s*(?:extends [^{]+)?(?:=\\s*)?\\{([\\s\\S]*?)\\n\\}`).exec(source);
+    const generic = /(?:export\s+)?(?:interface|type)\s+\w*Props\s*(?:extends [^{]+)?(?:=\s*)?\{([\s\S]*?)\n\}/.exec(source);
+    const block = scoped?.[1] ?? generic?.[1];
+    if (!block)
+        return [];
+    const out = [];
+    for (const line of block.split("\n")) {
+        const m = /^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)(\?)?\s*:\s*(.+?);?\s*$/.exec(line);
+        if (!m)
+            continue;
+        const type = m[3].replace(/;$/, "").trim();
+        out.push({
+            name: m[1],
+            ...(type ? { type: type.slice(0, 80) } : {}),
+            ...(m[2] ? {} : { required: true }),
+        });
+    }
+    return out;
+}
+/**
+ * THE WHOLE CONTRACT, from the file and the component's own body.
+ *
+ * `body` is the definition span - the component's own function - so a file that declares
+ * two components does not lend one of them the other's defaults. `source` is the whole
+ * file, because a type and a lookup table live outside the function.
+ */
+export function dataContract(source, body, name, 
+/** Axis → options, from the census - so a table is only read against a real axis. */
+axes) {
+    const props = propsFromType(source, name);
+    const byName = new Map(props.map((p) => [p.name, p]));
+    /** The destructuring says which props have a default, and names the ones with no type. */
+    const block = paramBlock(body);
+    if (block) {
+        for (const entry of topLevel(block)) {
+            const eq = entry.indexOf("=");
+            const key = (eq === -1 ? entry : entry.slice(0, eq)).split(":")[0].trim();
+            if (!/^[A-Za-z_$][\w$]*$/.test(key))
+                continue;
+            const found = byName.get(key) ?? { name: key };
+            if (!byName.has(key)) {
+                props.push(found);
+                byName.set(key, found);
+            }
+            if (eq !== -1) {
+                const value = entry.slice(eq + 1).trim();
+                if (value)
+                    found.default = value.slice(0, 60);
+            }
+        }
+    }
+    /**
+     * THE DERIVATIONS. Only the ones whose expression is a CONDITION - a comparison or a
+     * boolean chain - because those are what the conditional look gates on. A `const config
+     * = statusConfig[status]` is a lookup, and the table it reads is captured below instead.
+     */
+    const derived = {};
+    for (const m of body.matchAll(/const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*([^;\n]*(?:===|!==|&&|\|\|)[^;\n]*);/g)) {
+        const expression = m[2].trim();
+        if (!derived[m[1]] && expression.length <= 120)
+            derived[m[1]] = expression;
+    }
+    /**
+     * THE COPY A LOOKUP TABLE HOLDS, per axis option. Read only against an axis the census
+     * declared, and only for a field whose value is prose rather than a class list - which is
+     * what separates `text: "Waiting"` from `dotClass: "bg-lightgray-500"`.
+     */
+    const optionText = {};
+    for (const table of source.matchAll(/const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*\{([\s\S]*?)\n\}\s*;/g)) {
+        const axis = Object.keys(axes).find((a) => new RegExp(`\\b${table[1]}\\s*\\[\\s*${a}\\s*\\]`).test(source));
+        if (!axis)
+            continue;
+        for (const entry of topLevel(table[2])) {
+            const option = /^\s*"?([\w-]+)"?\s*:\s*\{([\s\S]*)\}\s*$/.exec(entry);
+            if (!option || !axes[axis].includes(option[1]))
+                continue;
+            for (const field of topLevel(option[2])) {
+                const kv = /^\s*(\w+)\s*:\s*"([^"]+)"\s*$/.exec(field);
+                if (!kv)
+                    continue;
+                // A class list is a look and travels as one; prose is copy.
+                if (/^(?:[a-z-]+:)?[a-z][\w-]*(?:\s+(?:[a-z-]+:)?[a-z][\w-]*)*$/.test(kv[2]) &&
+                    /class/i.test(kv[1]))
+                    continue;
+                if (/class/i.test(kv[1]))
+                    continue;
+                (optionText[axis] ??= {})[option[1]] = kv[2].slice(0, 80);
+            }
+        }
+    }
+    /** The exported union that lists an axis's options, when they declared one. */
+    const axisType = {};
+    UNION.lastIndex = 0;
+    for (const m of source.matchAll(UNION)) {
+        const options = [...m[2].matchAll(/"([^"]*)"/g)].map((o) => o[1]);
+        for (const [axis, declared] of Object.entries(axes)) {
+            if (declared.length === options.length &&
+                declared.every((o) => options.includes(o)))
+                axisType[axis] = m[1];
+        }
+    }
+    return { props, derived, optionText, axisType };
+}

package/dist/doctor/sketch.js

@@ -280,6 +280,77 @@ export function motionPropsOf(body) {
     const out = parts.join(" ");
     return out.length > 400 ? null : out;
 }
+/**
+ * The expression an element writes as its own content - `{title}`, `{a || b.c}`.
+ *
+ * Only what sits DIRECTLY between this tag and the next event, so a parent does not claim
+ * its child's content. `{children}` is the caller's and already travels as a slot.
+ */
+export function contentExpressionOf(source, open) {
+    // A tag that closes itself has no content, and what follows it is its PARENT's.
+    if (open.body.trimEnd().endsWith("/"))
+        return null;
+    /** `<` + name + body + `>` - the scan reports `body` without the name or the brackets. */
+    const from = open.at + 1 + open.tag.length + open.body.length + 1;
+    /**
+     * UP TO THIS ELEMENT'S OWN CLOSING TAG, and no further. Bounding by the next OPENING tag
+     * instead swept `</h3>` into the slice, and every one of their 22 read as nothing.
+     *
+     * A slice that does not close - `{isLoading && (` before a nested element - fails the
+     * balanced test below and says nothing, which is right: that is a guard, and a guard
+     * already travels as `when`.
+     */
+    const close = source.indexOf("<", from);
+    const to = Math.min(close === -1 ? source.length : close, from + 200);
+    if (to <= from)
+        return null;
+    const between = source.slice(from, to);
+    const m = /^\s*\{([^{}]*(?:\{[^{}]*\}[^{}]*)*)\}\s*$/.exec(between);
+    if (!m)
+        return null;
+    const expression = m[1].replace(/\s+/g, " ").trim();
+    if (!expression || expression === "children")
+        return null;
+    /**
+     * `{/* Header Section *``/}` IS A COMMENT, not content. Their WidgetCard opens with one
+     * and it arrived as the expression its root writes - a note to a human, presented as the
+     * prop that feeds an element.
+     */
+    if (expression.startsWith("/*") || expression.startsWith("//"))
+        return null;
+    // A whole JSX subtree is not content; a call is not a name we can attribute.
+    if (/[<>]/.test(expression) || expression.length > 90)
+        return null;
+    return expression;
+}
+/** The state props: `disabled={isLoading}`, `open={isOpen && !isLoading}`. */
+const STATE_PROP = /\b(disabled|readOnly|checked|open|selected|required|expanded|active|loading|indeterminate)=\{([^}]{1,60})\}/g;
+/**
+ * The handler that closes the loop on one of them: `onOpenChange={setIsOpen}`.
+ *
+ * A controlled `open` with no `onOpenChange` is a disclosure that opens once and never
+ * closes - which is what somebody pasting the snippet would have got. Only a NAME as the
+ * value: an inline arrow is a function body, and copying one means copying whatever it
+ * calls, which is not in the recipe.
+ */
+const HANDLER_PROP = /\b(on[A-Z]\w*)=\{([A-Za-z_$][\w$.]{0,40})\}/g;
+export function conditionalPropsOf(body) {
+    const out = {};
+    STATE_PROP.lastIndex = 0;
+    for (const m of body.matchAll(STATE_PROP)) {
+        const value = m[2].replace(/\s+/g, " ").trim();
+        // A literal is not behaviour, and an inline function is a body we cannot copy.
+        if (/^(true|false)$/.test(value) || /=>/.test(value))
+            continue;
+        if (!out[m[1]])
+            out[m[1]] = value;
+    }
+    HANDLER_PROP.lastIndex = 0;
+    for (const m of body.matchAll(HANDLER_PROP))
+        if (!out[m[1]])
+            out[m[1]] = m[2].trim();
+    return Object.keys(out).length > 0 ? out : null;
+}
 export function sketchOf(source, name) {
     /**
      * READ THE IMPORTS BEFORE SLICING - they live at the top of the file, and the
@@ -352,6 +423,16 @@ export function sketchOf(source, name) {
         const motion = motionPropsOf(event.body);
         if (motion)
             node.motionProps = motion;
+        /**
+         * WHICH PROP FEEDS THIS ELEMENT, and which behaviour props it carries - the two facts
+         * a class list cannot hold. See `contentFrom` and `behaviourProps`.
+         */
+        const feeds = contentExpressionOf(source, event);
+        if (feeds)
+            node.contentFrom = feeds;
+        const conditional = conditionalPropsOf(event.body);
+        if (conditional)
+            node.behaviourProps = conditional;
         // What has to be true for this element to exist at all - see `guardAt`.
         const guard = guardAt(source, event.at);
         if (guard) {

package/dist/guide.js

@@ -33,6 +33,102 @@ function customFontFamilies(families) {
     }
     return out;
 }
+/**
+ * THE STRUCTURE, WITH WHAT EACH PART IS FOR AND WHEN IT EXISTS.
+ *
+ * A flat list of class names is enough to STYLE and not enough to BUILD: an agent in
+ * another project reading fifteen of them cannot tell which is the thing you press, which
+ * one holds the revealed content, or which two are not always there. The recipe carries
+ * both facts per node and the guide was printing neither (dono, 04/08).
+ */
+function anatomyLines(cname, nodes, depth = 1) {
+    const out = [];
+    for (const node of nodes ?? []) {
+        if (depth > 6)
+            break;
+        const pad = "  ".repeat(depth);
+        const name = node.part
+            ? `\`.ds-${kebab(cname)}-${kebab(node.part)}\``
+            : node.refName
+                ? `\`<${node.refName}>\``
+                : node.ref
+                    ? `your \`${node.refName ?? node.ref}\``
+                    : node.as;
+        const facts = [node.as];
+        if (node.role && node.role !== node.as)
+            facts.push(node.role);
+        if (node.refName && node.from)
+            facts.push(`from \`${node.from}\``);
+        if (node.expects)
+            facts.push(`holds ${node.expects}`);
+        /**
+         * WHEN IT EXISTS, in the recipe's own words rather than in theirs - see
+         * `PreviewNode.only`. Their `isLoading` means nothing in another project; "only in a
+         * state this component has" is actionable anywhere.
+         */
+        const only = node.only;
+        if (only && "axis" in only)
+            facts.push(`only when \`data-${kebab(only.axis)}="${only.option}"\``);
+        else if (only && "state" in only)
+            facts.push("only in that state");
+        else if (only && "caller" in only)
+            facts.push("only when you pass it");
+        /**
+         * WHICH PROP FEEDS IT, AND WHAT MAKES IT INERT - the link between a list of parts and
+         * a list of props, which nothing carried.
+         *
+         * `{title}` is their name, said as `writes` rather than as an instruction: an agent
+         * reading fifteen parts needs to know THIS is where the heading text goes, and the
+         * prop that carries it in the new project is that project's to name.
+         */
+        if (node.contentFrom)
+            facts.push(`writes \`${node.contentFrom}\``);
+        for (const [prop, value] of Object.entries(node.behaviourProps ?? {}))
+            facts.push(`\`${prop}\` while \`${value}\``);
+        out.push(`${pad}- ${name} - ${facts.join(" · ")}`);
+        out.push(...anatomyLines(cname, node.children, depth + 1));
+    }
+    return out;
+}
+/**
+ * WHAT THE COMPONENT DOES, said without naming a package.
+ *
+ * The recipe says `@base-ui/react/collapsible`. In a project that uses Radix - or nothing -
+ * that is evidence and not an instruction. What travels is the SHAPE of the interaction,
+ * and it is derivable from two facts the recipe already carries: the behaviour belongs to
+ * a headless library, and one part has the `action` role while another holds the content.
+ *
+ * Derived, never invented: with no `action` part and no headless library there is nothing
+ * to say, and this says nothing.
+ */
+function behaviourLine(cname, recipe) {
+    const headless = (recipe.libraries ?? []).some((l) => l.kind === "headless");
+    if (!headless)
+        return null;
+    const flat = [];
+    const walk = (nodes) => {
+        for (const node of nodes ?? []) {
+            flat.push(node);
+            walk(node.children);
+        }
+    };
+    walk(recipe.preview?.parts);
+    const action = flat.find((n) => n.role === "action");
+    if (!action)
+        return null;
+    /**
+     * A part that exists only in a STATE, or a slot, is the region an action reveals - which
+     * is what separates a disclosure from a button that merely has a name.
+     */
+    const revealed = flat.find((n) => n.as === "slot" || (n.only && "state" in n.only));
+    const press = action.part
+        ? `\`.ds-${kebab(cname)}-${kebab(action.part)}\``
+        : "the action";
+    if (!revealed) {
+        return `the interaction: ${press} is the pressable one - wire it yourself or with any headless primitive, and give it the ARIA the pattern calls for.`;
+    }
+    return `the interaction: ${press} is pressed and reveals the region below it. Whatever drives that - a headless library or your own state - the pressable element announces \`aria-expanded\` and points at the region with \`aria-controls\`; the region carries the matching \`id\`. This recipe styles both and drives neither.`;
+}
 /** One entry per component: class, variant data-*, states, and multi-part anatomy. */
 function componentEntry(cname, recipe) {
     const cls = `.ds-${kebab(cname)}`;
@@ -50,7 +146,101 @@ function componentEntry(cname, recipe) {
         });
         partsText = `\n  parts: ${items.join(", ")}`;
     }
-    return `- **${cname}** (\`${cls}\`)${variantsText}\n  ${recipe.description}${partsText}${statesText}`;
+    /**
+     * EVERYTHING ELSE THE RECIPE ALREADY KNOWS, and this entry was throwing away.
+     *
+     * Measured on a real system: the recipe holds 15 fields and the guide read 4 of them, so
+     * an agent in another project got a list of class names and had to invent the rest -
+     * which is the difference between styling this component and building one that behaves
+     * like it (dono, 04/08).
+     */
+    const facts = [];
+    if (recipe.tier)
+        facts.push(`a ${recipe.tier}`);
+    if (recipe.api?.name) {
+        facts.push(recipe.api.from
+            ? `their own \`${recipe.api.name}\`, imported from \`${recipe.api.from}\``
+            : `their own \`${recipe.api.name}\``);
+    }
+    /**
+     * WHO OWNS THE STATE, which is the first question anybody rebuilding it asks. A recipe
+     * that manages itself needs no props to work; one the caller drives needs the pair.
+     */
+    const runtime = recipe.runtime;
+    if (runtime?.stateOwner) {
+        const owner = runtime.stateOwner === "self"
+            ? "manages its own state"
+            : runtime.stateOwner === "caller"
+                ? "the caller owns its state"
+                : "works controlled or uncontrolled";
+        const pairs = (runtime.controlled ?? [])
+            .map((c) => `\`${c.prop}\` + \`${c.event}\``)
+            .join(", ");
+        facts.push(pairs ? `${owner} (${pairs})` : owner);
+    }
+    /**
+     * WHOSE BEHAVIOUR IT IS, and what that means for somebody rebuilding it. `headless` is
+     * the one that changes the answer: the pixels are in this recipe and the interaction is
+     * a library's, so ANY headless primitive of that shape will do - it does not have to be
+     * the one they used.
+     */
+    for (const lib of recipe.libraries ?? []) {
+        if (lib.kind === "headless")
+            facts.push(`behaviour from \`${lib.from}\` - a headless library: every pixel is in this recipe, the interaction is not. Any equivalent primitive works`);
+        else if (lib.kind === "opaque")
+            facts.push(`\`${lib.from}\` draws part of it, and that part is not in this recipe`);
+    }
+    const defaults = Object.entries(recipe.defaults ?? {})
+        .map(([axis, option]) => `\`data-${kebab(axis)}="${option}"\``)
+        .join(", ");
+    const defaultsText = defaults ? `\n  at rest: ${defaults}` : "";
+    const factsText = facts.length ? `\n  ${facts.join("\n  ")}` : "";
+    /** Its own laws, computed from its own usage - and nothing read them (dono, 04/08). */
+    const laws = (recipe.usage ?? []).map((law) => `\n  - ${law}`).join("");
+    const lawsText = laws ? `\n  it obeys:${laws}` : "";
+    const behaviour = behaviourLine(cname, recipe);
+    const behaviourText = behaviour ? `\n  ${behaviour}` : "";
+    /**
+     * THE DATA CONTRACT, in prose an agent can act on.
+     *
+     * The owner's question was whether this recipe is enough to rebuild the component in a
+     * NEW project, and the answer was no: everything missing was logic. The classes and the
+     * nesting say what it looks like; these four lines say what it takes, what it computes,
+     * and what its options actually SAY (dono, 04/08).
+     *
+     * Their names, verbatim, presented as evidence: in the new project the props are named
+     * for that project's domain, and what transfers is the shape - which props are required,
+     * which condition gates which element, and what copy each option carries.
+     */
+    const contract = [];
+    const props = recipe.api?.props ?? [];
+    if (props.length > 0) {
+        contract.push(`props, as their own type declares them: ${props
+            .map((prop) => `\`${prop.name}${prop.required ? "" : "?"}${prop.type ? `: ${prop.type}` : ""}\`${prop.default ? ` (default \`${prop.default}\`)` : ""}`)
+            .join(", ")}`);
+    }
+    const derived = Object.entries(recipe.api?.derived ?? {});
+    if (derived.length > 0) {
+        contract.push(`it computes ${derived
+            .map(([name_, expression]) => `\`${name_}\` = \`${expression}\``)
+            .join(", ")} - the conditions below are written in those names`);
+    }
+    for (const [axis, byOption] of Object.entries(recipe.api?.optionText ?? {})) {
+        const said = Object.entries(byOption)
+            .map(([option, text]) => `${option} → "${text}"`)
+            .join(", ");
+        if (said)
+            contract.push(`each \`${axis}\` carries its own copy: ${said} - reword these for the new domain, keep one per option`);
+    }
+    for (const [axis, type] of Object.entries(recipe.api?.axisType ?? {})) {
+        contract.push(`\`${axis}\` is a named union in their code (\`${type}\`) - export the same kind of type rather than inlining the strings`);
+    }
+    const contractText = contract.length ? `\n  ${contract.join("\n  ")}` : "";
+    const anatomy = anatomyLines(cname, recipe.preview?.parts);
+    const anatomyText = anatomy.length
+        ? `\n  anatomy, in this nesting:\n${anatomy.join("\n")}`
+        : "";
+    return `- **${cname}** (\`${cls}\`)${variantsText}\n  ${recipe.description}${factsText}${defaultsText}${partsText}${statesText}${behaviourText}${contractText}${anatomyText}${lawsText}`;
 }
 /**
  * Builds GUIDE.md - instructions *for the agent* on how to build components

package/dist/library-structure.js

@@ -27,6 +27,7 @@
  * it, and re-inserting it would be a second opinion about a styled element.
  */
 import { frontierKind } from "./frontier-kind.js";
+/** A restored wrapper points at its own sketch node - see the `at` stamped in `flush`. */
 /** Index → the index of its parent, or -1. Read off `depth`, which is the nesting. */
 function parents(sketch) {
     const out = [];
@@ -49,13 +50,21 @@ function claimed(read, into = new Set()) {
     }
     return into;
 }
-/** Behaviour with no appearance: their element, no class list, nobody's part. */
+/**
+ * Behaviour with no appearance: their element, no class list, nobody's part.
+ *
+ * MOTION COUNTS AS BEHAVIOUR. `AnimatePresence` carries no class and draws no pixel, and
+ * it is the element that lets an `exit` animation run at all - without it the panel's
+ * `exit={{height:0}}` is copied into the snippet and can never fire, because the element
+ * unmounts before anything animates (dono, 04/08). Headless-only left it out.
+ */
 function isBehaviour(node) {
     if (!node)
         return false;
     if ((node.classes ?? "").trim())
         return false;
-    return frontierKind(node.from) === "headless";
+    const kind = frontierKind(node.from);
+    return kind === "headless" || kind === "motion";
 }
 /**
  * Put the missing library frame back around the nodes it wraps.
@@ -110,6 +119,18 @@ wrapped) {
                     as: "stack",
                     from: String(node.from ?? node.tag),
                     refName: node.tag,
+                    /**
+                     * THE INDEX TRAVELS WITH THE RESTORED ELEMENT, so everything the sketch measured
+                     * about it reaches the recipe by the same lookup every named node uses: the
+                     * guard, the resting fact, the animation props.
+                     *
+                     * Their panel is guarded - `{isOpen && !isLoading && (<Collapsible.Panel>` - and
+                     * a restored wrapper with no index arrived unconditional, so the snippet showed
+                     * an open panel as the resting state of a card that starts closed (dono, 04/08).
+                     * It also makes this idempotent for free: a second pass finds the index already
+                     * claimed.
+                     */
+                    at,
                     children: built,
                 },
             ];

package/package.json

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