synthesisui 0.16.118 → 0.16.120

package/dist/anatomy-read.js

@@ -310,13 +310,23 @@ sketch) {
                  * and stopped at, and a plain `div` is nobody's element.
                  */
                 const measured = sketch?.[node.at];
+                const kind = measured?.from ? frontierKind(measured.from) : "own";
+                /**
+                 * A MOTION ELEMENT IS THEIRS TO NAME TOO. `motion.div` is the element their panel
+                 * opens with, and the props that make it open have no CSS to translate to - so the
+                 * snippet emits their element and their props, verbatim. Headless for the
+                 * behaviour, motion for the animation; an opaque library is still named and
+                 * stopped at.
+                 */
                 if (measured?.from &&
                     measured.tag &&
-                    /^[A-Z]/.test(measured.tag) &&
-                    frontierKind(measured.from) === "headless") {
+                    /^[A-Za-z]/.test(measured.tag) &&
+                    (kind === "headless" || kind === "motion")) {
                     node_.from = measured.from;
                     node_.refName = measured.tag;
                 }
+                if (measured?.motionProps)
+                    node_.motionProps = measured.motionProps;
             }
             // The NAME is what carries the styles, so it is claimed even when nothing
             // resolved: the tree triggers on presence, and structure is most of the

package/dist/commands/import.js

@@ -1205,7 +1205,7 @@ export async function takeCensus(root, opts) {
      * the name - 35 of their 36, with `TypingIndicator` internal to `Message` and reported
      * as not exported. See `publicApi`.
      */
-    const api = await publicApi(root, scopeLabel);
+    const api = await publicApi(root);
     if (api) {
         for (const c of components) {
             const file = defined.find((d) => d.name === c.name)?.file;
@@ -1214,7 +1214,16 @@ export async function takeCensus(root, opts) {
                 : undefined;
             const required = source ? requiredProps(source, c.name) : [];
             c.api = {
-                ...(api.exports.has(c.name) ? { from: api.from } : { exported: false }),
+                /**
+                 * 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
@@ -1222,7 +1231,7 @@ export async function takeCensus(root, opts) {
                  * walking a monorepo (their component sits six levels below `packages/`, and the
                  * shallow walk that guards against shadowing never reached it).
                  */
-                ...(file ? { file: `${scopeLabel}/${file}` } : {}),
+                ...(file ? { file: scopeLabel ? `${scopeLabel}/${file}` : file } : {}),
                 ...(required.length > 0 ? { required } : {}),
             };
         }

package/dist/doctor/public-api.js

@@ -71,28 +71,32 @@ async function exportsOf(path, source, depth = 0, seen = new Set()) {
     return out;
 }
 /**
- * The public API of the folder being imported, or null when it has no manifest.
+ * The public API of the folder being read, or null when it has no manifest.
  *
- * `root` is the repository, `scope` the folder the census measured (`packages/ui`). A
- * scope with no `package.json` of its own is not a package and there is no specifier to
+ * `dir` is the folder the census measured - which is ALREADY `<repo>/packages/ui` on a
+ * scoped run. Joining the scope on again looked for `packages/ui/packages/ui/package.json`,
+ * found nothing and returned null, so the specifier and the required props were absent on
+ * all 36 of their components while the reading that needed them sat right there
+ * (dono, 04/08).
+ *
+ * A folder with no `package.json` of its own is not a package and there is no specifier to
  * offer - an app's `src/components` is imported by path, which is theirs to know and not
  * ours to guess.
  */
-export async function publicApi(root, scope) {
-    if (!scope)
-        return null;
-    const manifest = await readFile(join(root, scope, "package.json"), "utf8")
+export async function publicApi(dir) {
+    const manifest = await readFile(join(dir, "package.json"), "utf8")
         .then((raw) => JSON.parse(raw))
         .catch(() => null);
     if (!manifest?.name)
         return null;
     const entry = manifest.main ?? manifest.module ?? "src/index.ts";
-    const found = await readAt(join(root, scope), entry);
+    const found = await readAt(dir, entry);
     if (!found)
-        return { from: manifest.name, exports: new Set() };
+        return { from: manifest.name, exports: new Set(), read: false };
     return {
         from: manifest.name,
         exports: await exportsOf(found[0], found[1]),
+        read: true,
     };
 }
 const PROPS_BLOCK = /(?:export\s+)?(?:interface|type)\s+(\w*Props)\s*(?:=\s*)?\{([\s\S]*?)\n\}/;

package/dist/doctor/sketch.js

@@ -243,6 +243,43 @@ export function guardAt(source, at) {
         return null;
     return negated ? `!(${cond})` : cond;
 }
+/** The motion props a tag carries, as their own text. See `SketchNode.motionProps`. */
+const MOTION_PROP = /\b(initial|animate|exit|transition|whileHover|whileTap|whileFocus|whileDrag|layoutId)=\{/g;
+export function motionPropsOf(body) {
+    const parts = [];
+    MOTION_PROP.lastIndex = 0;
+    for (const m of body.matchAll(MOTION_PROP)) {
+        const open = (m.index ?? 0) + m[0].length - 1;
+        let depth = 0;
+        let end = -1;
+        for (let i = open; i < body.length; i++) {
+            if (body[i] === "{")
+                depth++;
+            else if (body[i] === "}") {
+                depth--;
+                if (depth === 0) {
+                    end = i;
+                    break;
+                }
+            }
+        }
+        if (end === -1)
+            continue;
+        const value = body
+            .slice(open, end + 1)
+            .replace(/\s+/g, " ")
+            .trim();
+        // A value that reaches outside the tag - a variable, a hook, a function - is theirs
+        // and copying its NAME would point the snippet at something it cannot see.
+        if (!/^\{\s*[[{"'\d]/.test(value))
+            continue;
+        parts.push(`${m[1]}=${value}`);
+    }
+    if (parts.length === 0)
+        return null;
+    const out = parts.join(" ");
+    return out.length > 400 ? null : out;
+}
 export function sketchOf(source, name) {
     /**
      * READ THE IMPORTS BEFORE SLICING - they live at the top of the file, and the
@@ -296,11 +333,25 @@ export function sketchOf(source, name) {
         if (rootAt !== -1 && event.at === rootAt)
             node.root = true;
         // What a capitalised tag IS, from the file's own imports - see `SketchNode.from`.
-        if (/^[A-Z]/.test(event.tag)) {
+        /**
+         * A DOT IS A NAMESPACE, and a namespace is an import - `motion.div` is lowercase and
+         * still comes from `motion/react`. Only capitalised tags were stamped, so the element
+         * their animated panel is built on had no package and the snippet emitted a plain
+         * `<div>` with their animation props on it (dono, 04/08).
+         */
+        if (/^[A-Z]/.test(event.tag) || event.tag.includes(".")) {
             const pkg = packageOfTag(event.tag, imports);
             if (pkg)
                 node.from = pkg;
         }
+        /**
+         * THE MOTION PROPS, off the opening tag - see `SketchNode.motionProps`. Kept whole and
+         * short: a prop whose value is a function or a variable is theirs to write, and a copy
+         * of `animate={controls}` would name something the snippet cannot reach.
+         */
+        const motion = motionPropsOf(event.body);
+        if (motion)
+            node.motionProps = motion;
         // 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,90 @@ 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");
+        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 +134,65 @@ 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}` : "";
+    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}${anatomyText}${lawsText}`;
 }
 /**
  * Builds GUIDE.md - instructions *for the agent* on how to build components

package/package.json

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