synthesisui 0.16.112 → 0.16.116

package/dist/anatomy-read.js

@@ -30,6 +30,7 @@
  * of the three outcomes this pipeline has paid for twice.
  */
 import { transcribe, } from "./doctor/transcribe.js";
+import { frontierKind } from "./frontier-kind.js";
 /** The ten forms, closed. A renderer that accepts any tag draws anything. */
 const FORMS = new Set([
     "image",
@@ -265,6 +266,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,
@@ -276,6 +296,28 @@ sketch) {
                 if (typeof node.refName === "string" && node.refName.trim())
                     node_.refName = node.refName.trim();
             }
+            else if (typeof node.at === "number") {
+                /**
+                 * OR OFF THE SKETCH, WHICH IS THE CASE THAT ACTUALLY HAPPENS.
+                 *
+                 * The deriver stamps this on the read; an AUTHORED reading never does - it names
+                 * `trigger` at index 1 and says nothing about `Collapsible.Trigger`, because it
+                 * has no reason to. So the snippet kept emitting `<div>` on the very path the
+                 * owner runs, and I read my own probe as proof of the opposite (dono, 04/08).
+                 *
+                 * The sketch measured the tag and the package, so this is the same lookup
+                 * `when` already does one line up. Gated on HEADLESS: an opaque library is named
+                 * and stopped at, and a plain `div` is nobody's element.
+                 */
+                const measured = sketch?.[node.at];
+                if (measured?.from &&
+                    measured.tag &&
+                    /^[A-Z]/.test(measured.tag) &&
+                    frontierKind(measured.from) === "headless") {
+                    node_.from = measured.from;
+                    node_.refName = measured.tag;
+                }
+            }
             // The NAME is what carries the styles, so it is claimed even when nothing
             // resolved: the tree triggers on presence, and structure is most of the
             // value. A node with no name is pure structure and that is legitimate.

package/dist/commands/component.js

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { emitCn, readVocabulary } from "../cn-codegen.js";
@@ -84,6 +85,34 @@ export async function component(slug, name, opts) {
             .filter(Boolean)
             .map((p) => p[0].toUpperCase() + p.slice(1))
             .join("");
+        /**
+         * THEY ALREADY HAVE THIS COMPONENT, and the recipe says where.
+         *
+         * `findCollision` guards against shadowing by walking `packages` three levels down;
+         * their `CollapsibleCard` sits six levels below it, so the guard never reached it and
+         * `component` would write a second, worse copy of a component in their own
+         * `packages/ui`. The recipe carries the path now - repo-relative, so this is one
+         * `stat` rather than a walk - and the import line their own manifest declares.
+         *
+         * Only refuses when the file is actually HERE: the same system installed in another
+         * project has no such component, and there generating is exactly right.
+         */
+        const theirs = res.recipe?.api;
+        const already = theirs?.file && existsSync(join(root, theirs.file)) ? theirs : null;
+        if (already && !opts.force) {
+            console.log(section("You already have this component"));
+            console.log(body(`\`${already.name}\` lives in ${already.file} - writing another one would leave you with two.`));
+            if (already.from) {
+                console.log("");
+                console.log(snippet([`import { ${already.name} } from "${already.from}";`]));
+            }
+            else if (already.exported === false) {
+                console.log(body(`It is not re-exported from that folder's entry, so import it by path.`));
+            }
+            console.log("");
+            console.log(body("The recipe and the compiled CSS are on disk either way - only the .tsx was not written. Pass --force to write it anyway."));
+            return;
+        }
         const clash = await findCollision(root, config.componentsDir, res.name, pascalName);
         if (!opts.force && (clash.exported || (clash.file && !clash.ours))) {
             console.log(section("This name is already taken in your project"));

package/dist/commands/import.js

@@ -17,6 +17,7 @@ import { moduleImports, readModuleCss, readModuleUsage, transcribeModule, } from
 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 { publicApi, requiredProps } from "../doctor/public-api.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
@@ -1083,6 +1084,42 @@ export async function takeCensus(root, opts) {
     for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g)) {
         declaredNames.add(m[1]);
     }
+    /**
+     * HOW SOMEBODY CALLS THE COMPONENT THEY ALREADY HAVE.
+     *
+     * The usage panel was handing people the markup of a component rebuilt out of our
+     * compiled classes, for a component sitting in their own `packages/ui` with a name and
+     * props - "você inventou diversas classes que não existem" (dono, 04/08), and the half
+     * that lands is that those classes appear nowhere in his repo. He has
+     * `<CollapsibleCard>`; the usage is its props.
+     *
+     * Measured, never inferred: the specifier is the name in THEIR manifest for the folder
+     * being imported, and a component only carries it when the entry actually re-exports
+     * the name - 35 of their 36, with `TypingIndicator` internal to `Message` and reported
+     * as not exported. See `publicApi`.
+     */
+    const api = await publicApi(root, scopeLabel);
+    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 = {
+                ...(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}/${file}` } : {}),
+                ...(required.length > 0 ? { required } : {}),
+            };
+        }
+    }
     const brokenRefs = findBrokenRefs(sources, declaredNames);
     const conventions = detectConventions(sources);
     const classStyle = detectClassStyle(sources);

package/dist/doctor/public-api.js

@@ -0,0 +1,119 @@
+/**
+ * HOW SOMEBODY CALLS THE COMPONENT THEY ALREADY HAVE.
+ *
+ * The usage panel was emitting the markup of a component rebuilt out of our compiled
+ * classes - `<div className="ds-collapsible-card-trigger">` and twenty lines like it. The
+ * owner's objection was exact (dono, 04/08): "você inventou diversas classes que não
+ * existem". They exist in our stylesheet and they exist NOWHERE in his repo, which is the
+ * half that matters. He has `<CollapsibleCard>`; the usage is its props.
+ *
+ * That question has a measured answer and we were not reading it:
+ *
+ *     the package name      their own `package.json` for the scope being imported
+ *     is it exported        follow `export * from` out of the entry - 35 of their 36
+ *     which props           the destructuring, already read (36 of 36)
+ *     which are required    their `interface XProps` - 23 of 38 files declare one
+ *
+ * Nothing here is inferred. A component the barrel does not reach is reported as not
+ * exported, which is a fact worth having - their `TypingIndicator` is internal to
+ * `Message`, and telling somebody to import it would be the invention.
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, join, normalize } from "node:path";
+const NAMED = /export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
+const DECLARED = /export\s+(?:const|function|class)\s+([A-Za-z_$][\w$]*)/g;
+const STAR = /export\s+\*\s+from\s*["']([^"']+)["']/g;
+async function readAt(base, rel) {
+    for (const candidate of [
+        rel,
+        `${rel}.ts`,
+        `${rel}.tsx`,
+        join(rel, "index.ts"),
+        join(rel, "index.tsx"),
+    ]) {
+        const path = normalize(join(base, candidate));
+        const source = await readFile(path, "utf8").catch(() => null);
+        if (source != null)
+            return [path, source];
+    }
+    return null;
+}
+/**
+ * Every name the entry exposes, following `export *` as far as it goes.
+ *
+ * Depth-capped and cycle-guarded: a barrel chain is somebody's folder layout, and
+ * `packages/ui` reaches its components through three of them.
+ */
+async function exportsOf(path, source, depth = 0, seen = new Set()) {
+    const out = new Set();
+    if (depth > 6 || seen.has(path))
+        return out;
+    seen.add(path);
+    NAMED.lastIndex = 0;
+    for (const m of source.matchAll(NAMED)) {
+        for (const part of m[1].split(",")) {
+            const name = part.split(" as ").pop()?.trim();
+            if (name && name !== "default")
+                out.add(name);
+        }
+    }
+    DECLARED.lastIndex = 0;
+    for (const m of source.matchAll(DECLARED))
+        out.add(m[1]);
+    STAR.lastIndex = 0;
+    for (const m of source.matchAll(STAR)) {
+        const next = await readAt(dirname(path), m[1]);
+        if (!next)
+            continue;
+        for (const name of await exportsOf(next[0], next[1], depth + 1, seen))
+            out.add(name);
+    }
+    return out;
+}
+/**
+ * The public API of the folder being imported, 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
+ * 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")
+        .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);
+    if (!found)
+        return { from: manifest.name, exports: new Set() };
+    return {
+        from: manifest.name,
+        exports: await exportsOf(found[0], found[1]),
+    };
+}
+const PROPS_BLOCK = /(?:export\s+)?(?:interface|type)\s+(\w*Props)\s*(?:=\s*)?\{([\s\S]*?)\n\}/;
+/**
+ * WHICH PROPS THEIR TYPE MARKS AS REQUIRED.
+ *
+ * The one thing that makes a call snippet copy-pasteable: `title: string` has to be
+ * filled and `subtitle?: string` does not. 23 of their 38 files declare a readable
+ * `interface XProps`; the rest extend a library's type or use generics, and there we say
+ * nothing rather than guessing which props somebody must pass.
+ */
+export function requiredProps(source, name) {
+    const scoped = new RegExp(`(?:export\\s+)?(?:interface|type)\\s+${name}Props\\s*(?:=\\s*)?\\{([\\s\\S]*?)\\n\\}`).exec(source);
+    const body = scoped?.[1] ?? PROPS_BLOCK.exec(source)?.[2];
+    if (!body)
+        return [];
+    const out = [];
+    for (const line of body.split("\n")) {
+        const m = /^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)(\?)?\s*:/.exec(line);
+        if (m && !m[2])
+            out.push(m[1]);
+    }
+    return out;
+}

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

@@ -90,7 +90,36 @@ const SPACING_PROPERTY = {
     m: "margin",
     mx: "marginInline",
     my: "marginBlock",
+    /**
+     * THE FOUR SIDES, which had no entry - so `mt-1` read as nothing.
+     *
+     * On their card it is the 4px between the eyebrow and the title; across the library it
+     * is 20 utilities in 12 components. A margin is a spacing decision and the contract
+     * always held it; only the table was short (dono, 04/08).
+     */
+    mt: "marginTop",
+    mr: "marginRight",
+    mb: "marginBottom",
+    ml: "marginLeft",
     gap: "gap",
+    "gap-x": "columnGap",
+    "gap-y": "rowGap",
+    /**
+     * `space-y-1` sets a margin on the CHILDREN, which is not a declaration on the parent.
+     * As a row/column gap it is exact wherever the parent arranges - which is every one of
+     * their uses - and inert where it does not, so it never paints a wrong pixel.
+     */
+    "space-y": "rowGap",
+    "space-x": "columnGap",
+    /** Position offsets - what makes `absolute inset-0` cover its parent. */
+    inset: "inset",
+    "inset-x": "insetInline",
+    "inset-y": "insetBlock",
+    top: "top",
+    right: "right",
+    bottom: "bottom",
+    left: "left",
+    basis: "flexBasis",
     /**
      * SIZE, which the first version had no entry for at all.
      *
@@ -330,6 +359,119 @@ const TYPE_KEYWORD = {
     italic: { property: "fontStyle", value: "italic" },
     underline: { property: "textDecoration", value: "underline" },
 };
+/**
+ * THE DECLARATIONS THAT ARE A WHOLE WORD, and were being dropped as layout.
+ *
+ * The rule that keeps layout out of a recipe is right about `flex` and `gap` - identical
+ * in every design system, and a recipe full of them is a recipe about nothing. It was
+ * wrong about everything that came along for the ride. Swept across their 36 components,
+ * 564 of 1443 utilities produced no declaration at all, and the biggest groups were not
+ * arrangement but PLACE: 116 distribution utilities in 25 components, 69 position ones in
+ * 17 (dono, 04/08).
+ *
+ * The cost was visible on one card: the loading veil is `absolute inset-0 bg-white/50`,
+ * and without the position it stopped being a veil and became a block in the flow; the
+ * chevron's `justify-between` is what puts it at the far edge of the header.
+ *
+ * `flex` and `flex-col` stay OUT on purpose - they travel as the node's own form
+ * (`row`/`stack`), and declaring the same thing twice is how two sources of truth start
+ * disagreeing. What comes in here is the DIMENSION (`flex-1`, `shrink-0`) and the PLACE.
+ */
+const PLACE_KEYWORD = {
+    // Position: what makes an overlay an overlay.
+    relative: { property: "position", value: "relative" },
+    absolute: { property: "position", value: "absolute" },
+    fixed: { property: "position", value: "fixed" },
+    sticky: { property: "position", value: "sticky" },
+    static: { property: "position", value: "static" },
+    // Flex dimension. The direction is the node's form; how it grows is a decision.
+    "flex-1": { property: "flex", value: "1 1 0%" },
+    "flex-auto": { property: "flex", value: "1 1 auto" },
+    "flex-initial": { property: "flex", value: "0 1 auto" },
+    "flex-none": { property: "flex", value: "none" },
+    grow: { property: "flexGrow", value: "1" },
+    "grow-0": { property: "flexGrow", value: "0" },
+    "flex-grow": { property: "flexGrow", value: "1" },
+    "flex-grow-0": { property: "flexGrow", value: "0" },
+    shrink: { property: "flexShrink", value: "1" },
+    "shrink-0": { property: "flexShrink", value: "0" },
+    "flex-shrink": { property: "flexShrink", value: "1" },
+    "flex-shrink-0": { property: "flexShrink", value: "0" },
+    // Overflow: what makes a clip clip, and a scroller scroll.
+    "overflow-hidden": { property: "overflow", value: "hidden" },
+    "overflow-auto": { property: "overflow", value: "auto" },
+    "overflow-visible": { property: "overflow", value: "visible" },
+    "overflow-scroll": { property: "overflow", value: "scroll" },
+    "overflow-x-auto": { property: "overflowX", value: "auto" },
+    "overflow-y-auto": { property: "overflowY", value: "auto" },
+    "overflow-x-hidden": { property: "overflowX", value: "hidden" },
+    "overflow-y-hidden": { property: "overflowY", value: "hidden" },
+    "overflow-x-scroll": { property: "overflowX", value: "scroll" },
+    "overflow-y-scroll": { property: "overflowY", value: "scroll" },
+    // Display, when it is not the arrangement we already carry as a form.
+    "inline-flex": { property: "display", value: "inline-flex" },
+    "inline-block": { property: "display", value: "inline-block" },
+    inline: { property: "display", value: "inline" },
+    block: { property: "display", value: "block" },
+    hidden: { property: "display", value: "none" },
+    // Focus and the pointer: real decisions, and `outline-none` is 21 of theirs.
+    "outline-none": { property: "outline", value: "none" },
+    "cursor-pointer": { property: "cursor", value: "pointer" },
+    "cursor-default": { property: "cursor", value: "default" },
+    "cursor-not-allowed": { property: "cursor", value: "not-allowed" },
+    "cursor-text": { property: "cursor", value: "text" },
+    "cursor-grab": { property: "cursor", value: "grab" },
+    "cursor-wait": { property: "cursor", value: "wait" },
+    "pointer-events-none": { property: "pointerEvents", value: "none" },
+    "pointer-events-auto": { property: "pointerEvents", value: "auto" },
+    "select-none": { property: "userSelect", value: "none" },
+    "select-text": { property: "userSelect", value: "text" },
+    "select-all": { property: "userSelect", value: "all" },
+    // Text that has to fit, and numbers that have to line up.
+    "whitespace-nowrap": { property: "whiteSpace", value: "nowrap" },
+    "whitespace-pre": { property: "whiteSpace", value: "pre" },
+    "whitespace-pre-wrap": { property: "whiteSpace", value: "pre-wrap" },
+    "break-words": { property: "overflowWrap", value: "break-word" },
+    "break-all": { property: "wordBreak", value: "break-all" },
+    "tabular-nums": { property: "fontVariantNumeric", value: "tabular-nums" },
+    // How an image fills its frame.
+    "object-cover": { property: "objectFit", value: "cover" },
+    "object-contain": { property: "objectFit", value: "contain" },
+    "object-fill": { property: "objectFit", value: "fill" },
+    "object-none": { property: "objectFit", value: "none" },
+    "object-scale-down": { property: "objectFit", value: "scale-down" },
+    /**
+     * ONE UTILITY, THREE DECLARATIONS - and any one of them alone paints nothing, which is
+     * why this needed the `prop:value|…` form rather than the pair form.
+     */
+    truncate: {
+        property: "overflow+textOverflow+whiteSpace",
+        value: "overflow:hidden|textOverflow:ellipsis|whiteSpace:nowrap",
+    },
+};
+/** `justify-between` → `space-between`, and the four that are not a straight copy. */
+const ALIGNMENT = {
+    start: "flex-start",
+    end: "flex-end",
+    between: "space-between",
+    around: "space-around",
+    evenly: "space-evenly",
+    center: "center",
+    stretch: "stretch",
+    baseline: "baseline",
+};
+/** Which property each alignment prefix sets. */
+const ALIGN_PROP = {
+    justify: "justifyContent",
+    items: "alignItems",
+    self: "alignSelf",
+    content: "alignContent",
+    "justify-items": "justifyItems",
+    "justify-self": "justifySelf",
+    "place-items": "placeItems",
+    "place-content": "placeContent",
+    "place-self": "placeSelf",
+};
 /** States we recognise. Anything else is skipped rather than invented. */
 /**
  * A MODIFIER'S STATE, IN THE CONTRACT'S SPELLING.
@@ -419,7 +561,22 @@ function withAlpha(d, alpha) {
         return d;
     return { ...d, value: `color-mix(in srgb, ${d.value} ${pct}%, transparent)` };
 }
+/** `w-1/2`, `basis-2/3` - a fraction is a width, and the `/` is not an alpha. */
+const FRACTION = /^(w|h|basis|max-w|max-h|min-w|min-h|top|right|bottom|left|inset)-(\d+)\/(\d+)$/;
 export function readUtility(utility, declared) {
+    /**
+     * BEFORE THE ALPHA SPLIT, because the two share a slash and only one of them is a
+     * colour. `w-1/2` was reaching the size reader as `w-1` and coming back `0.25rem` -
+     * silently wrong, which is worse than unread. Their `packages/ui` has none; two of
+     * their apps do (dono, 04/08).
+     */
+    const fraction = FRACTION.exec(utility);
+    if (fraction) {
+        const property = SPACING_PROPERTY[fraction[1]];
+        const pct = (Number(fraction[2]) / Number(fraction[3])) * 100;
+        if (property)
+            return { property, value: `${Number(pct.toFixed(4))}%` };
+    }
     const read = readUtilityCore(utility, declared);
     return read ? withAlpha(read, utility.split("/")[1]) : read;
 }
@@ -442,9 +599,36 @@ function readUtilityCore(utility, declared) {
     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.
-    const keyword = TYPE_KEYWORD[core];
+    const keyword = TYPE_KEYWORD[core] ?? PLACE_KEYWORD[core];
     if (keyword)
         return keyword;
+    /**
+     * A BARE `rounded` IS TAILWIND'S OWN DEFAULT RADIUS, and it read as nothing - so six
+     * elements across their library arrived square. Their token wins if they declared one
+     * under that name, exactly as the scaled form already does.
+     */
+    if (core === "rounded") {
+        return declared.has("--radius-DEFAULT")
+            ? {
+                property: "borderRadius",
+                value: "{radius.DEFAULT}",
+                token: "--radius-DEFAULT",
+            }
+            : { property: "borderRadius", value: "0.25rem" };
+    }
+    /**
+     * ALIGNMENT - `justify-between`, `items-center`, `self-end`.
+     *
+     * 116 of these across 25 of their components, and they are not arrangement: they are
+     * WHERE the thing sits. The chevron on their card is at the far edge because of one.
+     */
+    const align = /^(place-items|place-content|place-self|justify-items|justify-self|justify|items|self|content)-([a-z]+)$/.exec(core);
+    if (align) {
+        const property = ALIGN_PROP[align[1]];
+        const value = ALIGNMENT[align[2]];
+        if (property && value)
+            return { property, value };
+    }
     /**
      * BORDER WIDTH - `border`, `border-2`, `border-b`, `border-t-4`.
      *
@@ -533,6 +717,18 @@ function readUtilityCore(utility, declared) {
             return { property: "borderCollapse", value: rest };
         }
     }
+    /**
+     * `ring-1` IS A WIDTH, and it reached the colour reader first - which looked for a
+     * colour called `1`, found none, and returned null for all three of theirs. Its colour
+     * already reads as `outlineColor`, so the width belongs on the same family; a bare
+     * `ring` is 3px, Tailwind's own default.
+     */
+    if (prefix === "ring" && (rest === "" || /^\d+$/.test(rest))) {
+        return { property: "outlineWidth", value: `${rest || 3}px` };
+    }
+    if (core === "ring") {
+        return { property: "outlineWidth", value: "3px" };
+    }
     const colorProp = COLOR_PROPERTY[prefix];
     if (colorProp) {
         /**
@@ -677,6 +873,14 @@ function readUtilityCore(utility, declared) {
             sizeRest = axis[2];
         }
     }
+    /** The same recombination for the axis-suffixed families: `space-y-1`, `inset-x-0`. */
+    if (prefix === "space" || prefix === "inset") {
+        const axis = /^([xy])-(.+)$/.exec(rest);
+        if (axis) {
+            sizePrefix = `${prefix}-${axis[1]}`;
+            sizeRest = axis[2];
+        }
+    }
     const spaceProp = SPACING_PROPERTY[sizePrefix];
     if (spaceProp) {
         /** `gap-x-6` / `gap-y-2` - the two halves of gap, which one prefix cannot say. */
@@ -716,7 +920,87 @@ function readUtilityCore(utility, declared) {
         if (MAX_WIDTH[sizeRest] && /^(max-w|max-h)$/.test(sizePrefix)) {
             return { property: spaceProp, value: MAX_WIDTH[sizeRest] };
         }
+        /**
+         * `top-full`, `inset-0`, `basis-auto` - the words an offset takes and a padding does
+         * not. Their Menu positions its popup with `top-full`, and a positioner that does not
+         * position is not the component.
+         */
+        const OFFSET_WORD = {
+            full: "100%",
+            auto: "auto",
+            px: "1px",
+        };
+        if (OFFSET_WORD[sizeRest] &&
+            /^(inset|inset-x|inset-y|top|right|bottom|left|basis)$/.test(sizePrefix)) {
+            return { property: spaceProp, value: OFFSET_WORD[sizeRest] };
+        }
+    }
+    /**
+     * `z-50` - the stacking order, which is the difference between an overlay above the
+     * content and one behind it. Tailwind's own scale is the numbers themselves.
+     */
+    if (prefix === "z" && (/^\d+$/.test(rest) || rest === "auto")) {
+        return { property: "zIndex", value: rest };
     }
+    /**
+     * `backdrop-blur-[1px]`, `backdrop-blur-sm` - the frosted layer behind an overlay.
+     * Their loading veil is `bg-white/50 backdrop-blur-[1px]`, and without the blur the
+     * veil is a flat wash.
+     */
+    const BLUR = {
+        none: "0",
+        sm: "4px",
+        "": "8px",
+        md: "12px",
+        lg: "16px",
+        xl: "24px",
+    };
+    const backdrop = /^backdrop-blur(?:-(.+))?$/.exec(core);
+    if (backdrop) {
+        const arg = backdrop[1] ?? "";
+        const arbitrary = /^\[(.+)\]$/.exec(arg);
+        const value = arbitrary ? arbitrary[1] : BLUR[arg];
+        if (value)
+            return { property: "backdropFilter", value: `blur(${value})` };
+    }
+    const blur = /^blur(?:-(.+))?$/.exec(core);
+    if (blur) {
+        const arg = blur[1] ?? "";
+        const arbitrary = /^\[(.+)\]$/.exec(arg);
+        const value = arbitrary ? arbitrary[1] : BLUR[arg];
+        if (value)
+            return { property: "filter", value: `blur(${value})` };
+    }
+    /**
+     * `rotate-180`, `scale-[0.98]` - a static transform, which is a state and not motion:
+     * their chevron points up when the card is open. Each one lands on `transform` whole,
+     * so two on the same element would overwrite - none of their 3 co-occur, and saying
+     * one of them is better than saying neither.
+     */
+    const rotate = /^-?rotate-(.+)$/.exec(core);
+    if (rotate) {
+        const arbitrary = /^\[(.+)\]$/.exec(rotate[1]);
+        const deg = arbitrary ? arbitrary[1] : `${rotate[1]}deg`;
+        return {
+            property: "transform",
+            value: `rotate(${core.startsWith("-") ? `-${deg}` : deg})`,
+        };
+    }
+    const scale = /^scale-(.+)$/.exec(core);
+    if (scale) {
+        const arbitrary = /^\[(.+)\]$/.exec(scale[1]);
+        const factor = arbitrary
+            ? arbitrary[1]
+            : /^\d+$/.test(scale[1])
+                ? String(Number(scale[1]) / 100)
+                : null;
+        if (factor)
+            return { property: "transform", value: `scale(${factor})` };
+    }
+    /** `line-clamp-2` - how many lines survive before the ellipsis. */
+    const clamp = /^line-clamp-(\d+)$/.exec(core);
+    if (clamp)
+        return { property: "WebkitLineClamp", value: clamp[1] };
     if (prefix === "rounded") {
         /**
          * `rounded-t-lg` - one side, two corners. The side names which half; the scale is
@@ -1239,6 +1523,25 @@ export function transcribe(classes, declared) {
         // `rounded-t-lg` names two corners: the reader returns them joined with `+`, and
         // the write splits - the same shape the `size` expansion above uses.
         if (decl.property.includes("+")) {
+            /**
+             * AND WITH ITS OWN VALUE EACH, when one utility means three things.
+             *
+             * `truncate` is `overflow:hidden; text-overflow:ellipsis; white-space:nowrap` - any
+             * one of the three alone paints nothing, so the pair form (same value, two
+             * properties) could not carry it. `prop:value|prop:value` says both halves.
+             */
+            if (decl.value.includes("|")) {
+                for (const pair of decl.value.split("|")) {
+                    const [property, value] = pair.split(":");
+                    if (property && value && target[property] == null)
+                        target[property] = value;
+                }
+                if (decl.token)
+                    out.fromToken += 1;
+                else
+                    out.fromLiteral += 1;
+                continue;
+            }
             for (const property of decl.property.split("+")) {
                 if (target[property] == null)
                     target[property] = decl.value;

package/package.json

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