synthesisui 0.16.112 → 0.16.113

package/dist/anatomy-read.js

@@ -265,6 +265,25 @@ sketch) {
                 continue;
             }
             const node_ = { as };
+            /**
+             * THE GUARD TRAVELS WITH THE NODE, off the sketch it points at - so neither a
+             * reading nor the deriver has to carry it, and both get it.
+             */
+            if (typeof node.at === "number") {
+                const measured = sketch?.[node.at];
+                const when = node.when ?? measured?.when;
+                if (when)
+                    node_.when = when;
+                const atRest = node.atRest ?? measured?.atRest;
+                if (atRest === false)
+                    node_.atRest = false;
+            }
+            else {
+                if (node.when)
+                    node_.when = node.when;
+                if (node.atRest === false)
+                    node_.atRest = false;
+            }
             /**
              * A PART THAT IS A LIBRARY ELEMENT CARRIES BOTH FACTS - see `AnatomyRead.from`.
              * Inert for the renderer, which dispatches on `as`; read by the usage snippet,

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/package.json

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