inkbridge 0.1.0-beta.21 → 0.1.0-beta.23

package/scanner/component-scanner.ts

@@ -8,7 +8,23 @@
  * - Simple: Components with static classes
  */
 
-import { Project, SyntaxKind, Node, SourceFile, type JsxAttribute } from 'ts-morph';
+import {
+  Project,
+  SyntaxKind,
+  Node,
+  SourceFile,
+  type ArrowFunction,
+  type FunctionDeclaration,
+  type FunctionExpression,
+  type JsxAttribute,
+} from 'ts-morph';
+
+// Sentinel for the user-function interpreter: distinguishes "this statement
+// produced no return value, continue with the next" from "explicit `return
+// undefined`" (which IS a valid evaluated result and should bubble up).
+const EVAL_NEXT: unique symbol = Symbol('evalNext');
+type EvalStatementResult = ResolvedExpressionValue | typeof EVAL_NEXT;
+type UserFunctionNode = ArrowFunction | FunctionExpression | FunctionDeclaration;
 import * as path from 'path';
 import * as fs from 'fs';
 import type {
@@ -219,6 +235,7 @@ export class ComponentScanner {
               }
             }
 
+            this.applyTreeTransforms(analysis);
             analyses.push(analysis);
           }
         } catch (err) {
@@ -705,13 +722,20 @@ export class ComponentScanner {
    * `{rewardSol.toFixed(4)}` need a numeric receiver to evaluate. Try
    * to parse each value as a number first; fall back to the literal
    * string for non-numeric args (`label = "Click me"`). Booleans are
-   * matched by exact "true" / "false".
+   * matched by exact "true" / "false". `null` / `undefined` keyword
+   * literals are dropped — they leave the prop unbound, which is what
+   * a conditional like `{viewingWalletLabel ? <Banner/> : null}`
+   * expects when the consumer wrote `viewingWalletLabel: null`.
+   * Without this drop, `extractStringValue("null")` returns the
+   * truthy string `"null"` and the wallet div renders with literal
+   * "null" text.
    */
   private buildArgsPropsContext(args: Record<string, string>): Map<string, ResolvedExpressionValue> {
     const out = new Map<string, ResolvedExpressionValue>();
     for (const key in args) {
       if (!Object.prototype.hasOwnProperty.call(args, key)) continue;
       const raw = args[key];
+      if (raw === 'null' || raw === 'undefined') continue;
       if (raw === 'true') { out.set(key, true); continue; }
       if (raw === 'false') { out.set(key, false); continue; }
       if (raw !== '' && !isNaN(Number(raw))) { out.set(key, Number(raw)); continue; }
@@ -886,6 +910,33 @@ export class ComponentScanner {
           init.getProperty('decorators')
         );
 
+        // Check for `parameters.inkbridge.responsive` opt-in/opt-out.
+        // Storybook idiom: { parameters: { inkbridge: { responsive: true } } }.
+        // The plugin gates responsive-breakpoint frames on this field —
+        // see preview-builder.ts and story-builder.ts. Unset = default
+        // policy (only the canonical Default story gets responsive).
+        const parametersProp = init.getProperty('parameters');
+        if (parametersProp && Node.isPropertyAssignment(parametersProp)) {
+          const paramsInit = parametersProp.getInitializer();
+          if (paramsInit && Node.isObjectLiteralExpression(paramsInit)) {
+            const inkbridgeProp = paramsInit.getProperty('inkbridge');
+            if (inkbridgeProp && Node.isPropertyAssignment(inkbridgeProp)) {
+              const inkbridgeInit = inkbridgeProp.getInitializer();
+              if (inkbridgeInit && Node.isObjectLiteralExpression(inkbridgeInit)) {
+                const responsiveProp = inkbridgeInit.getProperty('responsive');
+                if (responsiveProp && Node.isPropertyAssignment(responsiveProp)) {
+                  const responsiveInit = responsiveProp.getInitializer();
+                  if (responsiveInit) {
+                    const kind = responsiveInit.getKind();
+                    if (kind === SyntaxKind.TrueKeyword) story.responsive = true;
+                    else if (kind === SyntaxKind.FalseKeyword) story.responsive = false;
+                  }
+                }
+              }
+            }
+          }
+        }
+
         // Check for `args` property
         const argsProp = init.getProperty('args');
         if (argsProp && Node.isPropertyAssignment(argsProp)) {
@@ -934,13 +985,38 @@ export class ComponentScanner {
                 // this an args-based BlockTable story would see
                 // `blocks = "mockBlocks"` and the .map call inside the
                 // component couldn't resolve the iteration source.
+                //
+                // Handles both literal property assignments AND spread
+                // assignments (`...BASE_ARGS`). Without spread handling,
+                // shared-args patterns like
+                //   const BASE_ARGS = { marketSymbol: "SOL", ... };
+                //   export const WithLegend = { args: { ...BASE_ARGS, markers: [...] } };
+                // would silently drop every base arg, so the component
+                // body sees `marketSymbol = undefined` and renders blank.
                 for (const prop of argsInit.getProperties()) {
+                  if (Node.isSpreadAssignment(prop)) {
+                    const spreadResolved = this.resolveExpressionValue(prop.getExpression(), new Map());
+                    if (spreadResolved && typeof spreadResolved === 'object' && !Array.isArray(spreadResolved)) {
+                      for (const [k, v] of Object.entries(spreadResolved as Record<string, ResolvedExpressionValue>)) {
+                        if (v !== undefined && v !== null) argsContext.set(k, v);
+                      }
+                    }
+                    continue;
+                  }
                   if (!Node.isPropertyAssignment(prop)) continue;
                   const propInit = prop.getInitializer();
                   if (!propInit) continue;
                   const resolved = this.resolveExpressionValue(propInit, new Map());
-                  if (resolved !== undefined && resolved !== null) {
-                    argsContext.set(prop.getName(), resolved);
+                  // Fallback to parseLiteralValue for shapes resolveExpressionValue
+                  // doesn't cover (array literals, in particular — needed for
+                  // `markers: [...]` and similar inline-array story args).
+                  // `null` / `undefined` are deliberately skipped — they have
+                  // no propsContext-bearing value to thread through.
+                  const finalValue = resolved !== undefined
+                    ? resolved
+                    : this.parseLiteralValue(propInit);
+                  if (finalValue !== undefined && finalValue !== null) {
+                    argsContext.set(prop.getName(), finalValue);
                   }
                 }
                 const localCompBody = localComponents.get(metaComponentName);
@@ -2339,6 +2415,14 @@ export class ComponentScanner {
 
       let itemParamName: string;
       let destructuringBindings: Map<string, string> | null = null;
+      // Array-tuple destructuring (`([mint, meta]) =>`): ordered list of
+      // local names. Common when iterating `Object.entries(x).map(...)`
+      // where each item is a `[key, value]` tuple. Without this branch
+      // the param's `.getName()` returns the raw bracket text and
+      // references to `mint` / `meta` inside the callback don't resolve,
+      // so JSX values stay unsubstituted (e.g. `<SelectItem value={mint}>`
+      // renders with the raw string `mint`).
+      let arrayDestructuringNames: string[] | null = null;
       const firstParamNameNode = params[0].getNameNode();
       if (Node.isObjectBindingPattern(firstParamNameNode)) {
         destructuringBindings = new Map();
@@ -2350,6 +2434,18 @@ export class ComponentScanner {
           destructuringBindings.set(localName, sourceKey);
         }
         itemParamName = '__destructured__';
+      } else if (Node.isArrayBindingPattern(firstParamNameNode)) {
+        arrayDestructuringNames = [];
+        for (const element of firstParamNameNode.getElements()) {
+          // OmittedExpression for holes like `[, b]` — push '' to keep
+          // index alignment but skip binding.
+          if (Node.isBindingElement(element)) {
+            arrayDestructuringNames.push(element.getNameNode().getText());
+          } else {
+            arrayDestructuringNames.push('');
+          }
+        }
+        itemParamName = '__destructured__';
       } else {
         itemParamName = params[0].getName();
       }
@@ -2446,6 +2542,15 @@ export class ComponentScanner {
         arrayValue = this.findArrayValue(arrayName, sourceFile);
       }
 
+      // Last-resort: try the full expression-level resolver. Handles
+      // call-shape iterators like `Object.entries(X).map(...)` where
+      // `arrayName` is the raw expression text (e.g.
+      // "Object.entries(TOKEN_METADATA)") and `findArrayValue`'s
+      // name-based lookup never matches.
+      if (!arrayValue) {
+        arrayValue = this.resolveArrayFromExpression(arrayExpr, sourceFile);
+      }
+
       if (!arrayValue || arrayValue.length === 0) {
         // If we can't find the array value, generate one iteration as a template
         const templateJsx = this.buildJsxTreeWithSubstitution(
@@ -2491,6 +2596,15 @@ export class ComponentScanner {
         // depend on `index` or the current item.
         if (itemParamName && itemParamName !== '__destructured__' && item != null) {
           iterationContext.set(itemParamName, item);
+        } else if (itemParamName === '__destructured__' && arrayDestructuringNames) {
+          // Array-tuple destructuring: bind by index. Items shorter than
+          // the binding list leave the trailing names undefined.
+          if (Array.isArray(item)) {
+            for (let bi = 0; bi < arrayDestructuringNames.length; bi++) {
+              const name = arrayDestructuringNames[bi];
+              if (name) iterationContext.set(name, item[bi]);
+            }
+          }
         } else if (itemParamName === '__destructured__' && typeof item === 'object' && item !== null) {
           for (const [k, v] of Object.entries(item)) iterationContext.set(k, v);
         }
@@ -2568,6 +2682,17 @@ export class ComponentScanner {
       return jsonImported;
     }
 
+    // Named import from a TypeScript / JavaScript file. Covers the common
+    // pattern `import { PRICE_CHART_TIMEFRAMES } from "~/domains/perps/constants"`
+    // followed by `PRICE_CHART_TIMEFRAMES.map(...)` in the JSX body. Without
+    // this branch, `.map()` falls through to the placeholder-iteration path
+    // (one synthetic item) and the rendered tree shows zero buttons.
+    const fromNamedImport = this.findArrayInNamedImports(arrayName, sourceFile);
+    if (fromNamedImport) {
+      this.arrayValueCache.set(cacheKey, fromNamedImport);
+      return fromNamedImport;
+    }
+
     // Look for default parameter value in function: function Comp({ features = defaultFeatures })
     for (const func of sourceFile.getFunctions()) {
       const params = func.getParameters();
@@ -2630,6 +2755,92 @@ export class ComponentScanner {
     return null;
   }
 
+  /**
+   * Resolve a named-imported array constant by following the import
+   * declaration to its source file and recursing into `findArrayValue`
+   * against that file. Covers patterns like:
+   *
+   *     import { PRICE_CHART_TIMEFRAMES } from "~/domains/perps/constants";
+   *     ...
+   *     {PRICE_CHART_TIMEFRAMES.map((option) => <Button>{option.label}</Button>)}
+   *
+   * Without this, `findArrayValue` only inspects the current source file's
+   * declarations, returns `null` for cross-file named imports, and the
+   * `.map()` falls through to the placeholder-iteration path (one synthetic
+   * item) — so consumer JSX renders zero buttons instead of N.
+   *
+   * Returns `null` for default imports (the JSON branch handles `import x from
+   * "./foo.json"` separately) and for any import whose target file can't be
+   * resolved to disk via `resolveImportedComponentPath`.
+   */
+  private findArrayInNamedImports(name: string, sourceFile: SourceFile): ResolvedExpressionValue[] | null {
+    const fileDir = path.dirname(sourceFile.getFilePath());
+    for (const imp of sourceFile.getImportDeclarations()) {
+      const named = imp.getNamedImports().find((n) => {
+        const localName = n.getAliasNode()?.getText() || n.getName();
+        return localName === name;
+      });
+      if (!named) continue;
+      const moduleSpec = imp.getModuleSpecifierValue();
+      const importedFile = this.openImportedSourceFile(fileDir, moduleSpec);
+      if (!importedFile) return null;
+      // Resolve under the IMPORTED source's name (the export may rename
+      // via `import { Foo as Bar }` — we follow the exported name).
+      const exportedName = named.getName();
+      return this.findArrayValue(exportedName, importedFile);
+    }
+    return null;
+  }
+
+  /**
+   * Try to load the source file the import declaration points at, against
+   * both the disk (production scan) and the in-memory ts-morph project
+   * (regression fixtures that don't touch the filesystem). Returns `null`
+   * for imports whose target can't be located in either place.
+   *
+   * Built on top of `resolveImportedComponentPath`'s extension-trying logic
+   * — we re-implement the same candidate list and probe the project's
+   * tracked files when `fs.existsSync` says "not on disk". Keeps the
+   * regression fixtures self-contained (no temp-dir writes) while staying
+   * correct for real consumer scans.
+   */
+  private openImportedSourceFile(baseDir: string, moduleSpec: string): SourceFile | null {
+    // Fast path: real files on disk.
+    const onDiskPath = this.resolveImportedComponentPath(baseDir, moduleSpec);
+    if (onDiskPath) {
+      try {
+        const fromDisk = this.project.addSourceFileAtPathIfExists(onDiskPath);
+        if (fromDisk) return fromDisk;
+      } catch (_e) {
+        /* fall through to in-memory probe */
+      }
+    }
+
+    // In-memory probe: build the same candidate list (with extension
+    // variants) and check the project's tracked files. Lets fixtures call
+    // `project.createSourceFile(path, content)` and have those files be
+    // findable through normal import resolution.
+    let basePath: string | null = null;
+    if (moduleSpec.startsWith('./') || moduleSpec.startsWith('../')) {
+      basePath = path.resolve(baseDir, moduleSpec);
+    } else if (moduleSpec.startsWith('~/') || moduleSpec.startsWith('@/')) {
+      basePath = path.resolve(process.cwd(), 'src', moduleSpec.slice(2));
+    }
+    if (!basePath) return null;
+    const candidates = [
+      basePath,
+      `${basePath}.tsx`,
+      `${basePath}.ts`,
+      path.join(basePath, 'index.tsx'),
+      path.join(basePath, 'index.ts'),
+    ];
+    for (const candidate of candidates) {
+      const inProject = this.project.getSourceFile(candidate);
+      if (inProject) return inProject;
+    }
+    return null;
+  }
+
   /**
    * Resolve an expression to an array of items. Handles:
    *
@@ -2673,6 +2884,18 @@ export class ComponentScanner {
         if (PASS_THROUGH_METHODS.has(methodName)) {
           return this.resolveArrayFromExpression(callee.getExpression(), sourceFile);
         }
+        // `Object.entries(x)` / `Object.keys(x)` / `Object.values(x)` —
+        // common shape transforms used inside `.map()` callbacks to
+        // iterate POJO tables (e.g. shadcn dropdown built from
+        // `Object.entries(TOKEN_METADATA).map(...)`). The general-purpose
+        // evaluator handles these in `evaluateBuiltinCall`; resolve the
+        // call expression through it and unwrap to an array.
+        const baseExpr = callee.getExpression();
+        if (Node.isIdentifier(baseExpr) && baseExpr.getText() === 'Object'
+            && (methodName === 'entries' || methodName === 'keys' || methodName === 'values')) {
+          const resolved = this.resolveExpressionValue(unwrapped, new Map());
+          if (Array.isArray(resolved)) return resolved as ResolvedExpressionValue[];
+        }
       }
     }
 
@@ -2763,33 +2986,26 @@ export class ComponentScanner {
 
     if (!Node.isArrayLiteralExpression(arrayLit)) return result;
 
+    // Delegate each element to the full `resolveExpressionValue` resolver
+    // so identifier references (`[USDC_MINT, USDT_MINT]` → the actual mint
+    // strings), imports, casts, parens, template literals, and nested
+    // arrays/objects all collapse to their static value. The previous
+    // implementation only handled string / number / object-literal
+    // elements directly and dropped everything else, so a story arg like
+    // `allowedInputMints: [USDC_MINT, USDT_MINT]` came back as `[]` and a
+    // downstream `.map()` over it expanded to a single placeholder
+    // iteration with `value = { name: "Item", description: "Description" }`
+    // instead of the two real mint values. Same class of bug we hit on
+    // DecreasePositionModal with Object.entries — and on IncreasePosition
+    // when the array was identifier-typed rather than literal-typed.
+    //
+    // The recursion is safe: each element is one syntactic level deeper
+    // than the array literal, and `resolveExpressionValue` only re-enters
+    // `parseArrayLiteral` for nested ArrayLiteralExpression elements.
     for (const element of arrayLit.getElements()) {
-      if (Node.isObjectLiteralExpression(element)) {
-        const obj: Record<string, ResolvedExpressionValue> = {};
-        for (const prop of element.getProperties()) {
-          if (Node.isPropertyAssignment(prop)) {
-            const name = prop.getName();
-            const init = prop.getInitializer();
-            if (init) {
-              if (Node.isStringLiteral(init)) {
-                obj[name] = init.getLiteralValue();
-              } else if (Node.isNumericLiteral(init)) {
-                obj[name] = Number(init.getLiteralText());
-              } else if (init.getKind() === SyntaxKind.TrueKeyword) {
-                obj[name] = true;
-              } else if (init.getKind() === SyntaxKind.FalseKeyword) {
-                obj[name] = false;
-              } else {
-                obj[name] = init.getText();
-              }
-            }
-          }
-        }
-        result.push(obj);
-      } else if (Node.isStringLiteral(element)) {
-        result.push(element.getLiteralValue());
-      } else if (Node.isNumericLiteral(element)) {
-        result.push(Number(element.getLiteralText()));
+      const resolved = this.resolveExpressionValue(element, new Map());
+      if (resolved !== undefined) {
+        result.push(resolved);
       }
     }
 
@@ -3212,6 +3428,261 @@ export class ComponentScanner {
     return [];
   }
 
+  /**
+   * Apply scanner-level tree transforms to a JSX tree. Returns the
+   * transformed tree (input is not mutated).
+   *
+   * Transforms run here mirror the `__fromPortal` pattern: the tree gets
+   * annotated with data props that downstream render code reads, and
+   * "logical-only" wrapper components (Radix `*.Root` aliases that render
+   * `display: contents` in the browser) are flattened away so they don't
+   * trap their children in a hugging frame at render time.
+   *
+   * Today: just `propagateSelectRootContext`. Extend here for Tabs,
+   * RadioGroup, Accordion, etc.
+   */
+  private transformJsxTree(tree: JsxNode | null | undefined): JsxNode | null | undefined {
+    if (!tree || tree.type !== 'element') return tree;
+    let next = this.propagateSelectRootContext(tree);
+    if (next.type === 'element') {
+      next = this.propagateDialogRootContext(next);
+    }
+    return next;
+  }
+
+  /**
+   * Apply tree-level transforms to every JSX tree carried by an
+   * analysis: the component's own `jsxTree` and each story's
+   * `jsxTree`. Called once per analysis right before it lands in the
+   * scanned components list, so the persisted JSON already reflects
+   * the transformed trees and downstream consumers (ui-builder,
+   * symbol policy, story-builder) see a single canonical shape.
+   */
+  private applyTreeTransforms(analysis: ComponentAnalysis): void {
+    if ('jsxTree' in analysis && analysis.jsxTree) {
+      const transformed = this.transformJsxTree(analysis.jsxTree);
+      if (transformed && transformed.type === 'element') {
+        analysis.jsxTree = transformed;
+      }
+    }
+    const stories = ('stories' in analysis && Array.isArray(analysis.stories))
+      ? analysis.stories
+      : null;
+    if (stories) {
+      for (const story of stories) {
+        if (story && story.jsxTree) {
+          const transformed = this.transformJsxTree(story.jsxTree);
+          if (transformed && transformed.type === 'element') {
+            story.jsxTree = transformed;
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Hoist children of transparent `<Select>` / `<SelectPrimitive.Root>`
+   * wrappers up to their parent, annotating each hoisted child with
+   * `__selectRoot*` data props that carry the Select's context
+   * (`value`, `open`, the resolved selected label, the highlighted item).
+   *
+   * The render-time `isSelectRootTag` handler in `ui-builder.ts` was the
+   * only place that set `selectIsOpen` / `selectSelectedLabel` etc. on
+   * the render context. With the wrapper preserved, Figma would render
+   * an empty hugging frame around `<SelectTrigger>` and the trigger's
+   * `w-full` would only fill the wrapper — making the dropdown look
+   * narrower than its sibling inputs in a form grid.
+   *
+   * Flattening here mirrors how CSS `display: contents` makes the
+   * wrapper layout-transparent in the browser. Downstream renderers see
+   * `<SelectTrigger>` and `<SelectContent>` as direct siblings of the
+   * Label / form fields, so existing full-width / stretch logic applies
+   * without special-casing the Radix wrapper.
+   */
+  private propagateSelectRootContext(node: JsxNode): JsxNode {
+    if (node.type !== 'element') return node;
+    const el = node;
+    const newChildren: JsxNode[] = [];
+    for (const child of el.children || []) {
+      const transformed = this.propagateSelectRootContext(child);
+      if (transformed.type === 'element' && this.isTransparentSelectRoot(transformed)) {
+        for (const hoisted of this.hoistSelectRootChildren(transformed)) {
+          newChildren.push(hoisted);
+        }
+      } else {
+        newChildren.push(transformed);
+      }
+    }
+    return Object.assign({}, el, { children: newChildren });
+  }
+
+  /**
+   * Annotate every `DialogContent` descendant with an
+   * `__dialogRootIsOpen` data prop derived from the nearest enclosing
+   * `<Dialog>` / `<DialogPrimitive.Root>`'s `open` / `defaultOpen`
+   * props. The render-time gate in `ui-builder.ts` uses this signal
+   * to suppress closed nested dialogs (the info-button Dialog inside
+   * `DialogHeader`, the secondary-confirmation Dialog, etc.).
+   *
+   * Without this, every nested DialogContent rendered inline next to
+   * its parent's content — visible as an "Open position / Overview"
+   * sliver floating top-right of `IncreasePositionModal` in Figma,
+   * and as the vertical-letter description text on mobile.
+   *
+   * Why scanner-level instead of render-context inheritance: the
+   * outer DialogContent is portal-extracted at scan time (loses its
+   * direct child-of-Root relationship). By the time ui-builder
+   * processes a DialogContent the parent Dialog Root is no longer
+   * on the recursion ancestor chain — annotating at scan time, when
+   * we still see the wrapping Root, is the universal fix.
+   */
+  private propagateDialogRootContext(node: JsxNode): JsxNode {
+    const annotate = (n: JsxNode, isOpen: boolean | null): JsxNode => {
+      if (n.type !== 'element') return n;
+      const el = n;
+      const tag = el.tagName;
+      // Entering a new Dialog Root — recompute isOpen from its props.
+      const isDialogRoot = tag === 'Dialog' || tag === 'DialogPrimitive.Root';
+      const nextIsOpen = isDialogRoot
+        ? (this.isScannerTruthyStateProp(el.props && el.props.open)
+            || this.isScannerTruthyStateProp(el.props && el.props.defaultOpen))
+        : isOpen;
+      const isDialogContent = tag === 'DialogContent' || tag === 'DialogPrimitive.Content';
+      let nextProps = el.props;
+      if (isDialogContent && nextIsOpen != null) {
+        nextProps = Object.assign({}, el.props || {}, {
+          __dialogRootIsOpen: nextIsOpen ? 'true' : 'false',
+        });
+      }
+      const newChildren: JsxNode[] = [];
+      for (const c of el.children || []) {
+        newChildren.push(annotate(c, nextIsOpen));
+      }
+      return Object.assign({}, el, { props: nextProps, children: newChildren });
+    };
+    return annotate(node, null);
+  }
+
+  private isTransparentSelectRoot(node: JsxElement): boolean {
+    const tag = node.tagName;
+    if (tag !== 'Select' && tag !== 'SelectPrimitive.Root') return false;
+    const className = node.props && node.props.className;
+    if (typeof className === 'string' && className.trim().length > 0) return false;
+    return Array.isArray(node.children) && node.children.length > 0;
+  }
+
+  private hoistSelectRootChildren(rootEl: JsxElement): JsxNode[] {
+    const props = rootEl.props || {};
+    const selectedValue = (props.value != null && String(props.value).length > 0)
+      ? String(props.value)
+      : (props.defaultValue != null && String(props.defaultValue).length > 0)
+        ? String(props.defaultValue)
+        : null;
+    const isOpen = this.isScannerTruthyStateProp(props.open)
+      || this.isScannerTruthyStateProp(props.defaultOpen);
+    const selectedLabel = selectedValue != null
+      ? this.findSelectItemLabel(rootEl, selectedValue)
+      : null;
+    const highlightedValue = (!selectedValue && isOpen)
+      ? this.findFirstSelectItemValue(rootEl)
+      : null;
+    // Annotations are strings because `JsxElement.props` is
+    // `Record<string, string>`. Render-time consumers re-parse via
+    // `isTruthyStateProp` / `normalizeSelectableValue`.
+    const annotations: Record<string, string> = {};
+    if (selectedValue != null) annotations.__selectRootSelectedValue = selectedValue;
+    if (selectedLabel != null) annotations.__selectRootSelectedLabel = selectedLabel;
+    if (isOpen) annotations.__selectRootIsOpen = 'true';
+    if (highlightedValue != null) annotations.__selectRootHighlightedValue = highlightedValue;
+
+    const out: JsxNode[] = [];
+    for (const child of rootEl.children) {
+      if (child.type !== 'element') {
+        out.push(child);
+        continue;
+      }
+      const childEl = child as JsxElement;
+      const mergedProps = Object.assign({}, childEl.props || {}, annotations);
+      out.push(Object.assign({}, childEl, { props: mergedProps }));
+    }
+    return out;
+  }
+
+  private isScannerTruthyStateProp(value: string | undefined | null): boolean {
+    if (value == null) return false;
+    const s = String(value).trim().toLowerCase();
+    return s === 'true' || s === '"true"' || s === "'true'" || s === '1';
+  }
+
+  /**
+   * Walk a Select Root's subtree to find the first `SelectItem` whose
+   * `value` prop matches the requested value, and return the first text
+   * descendant (the label). Mirrors `findSelectedSelectLabel` in
+   * `src/design-system/render-context.ts` but operates on the static
+   * scanner JSX tree at scan time, so the label is baked into the
+   * `__selectRootSelectedLabel` annotation.
+   *
+   * The label is rarely a direct text child of `SelectItem`: shadcn's
+   * `<SelectItem>` inlines into `<SelectPrimitive.Item>` containing a
+   * decorative indicator span AND a `<SelectPrimitive.ItemText>` wrapper
+   * around the actual label text. Walk the whole subtree of the matched
+   * item rather than peeking only at direct children — anything else
+   * silently drops the annotation for shadcn-shaped Selects and the
+   * Trigger renders the raw value (e.g. a mint address) instead of the
+   * symbol.
+   */
+  private findSelectItemLabel(rootEl: JsxElement, value: string): string | null {
+    const findFirstText = (node: JsxNode): string | null => {
+      if (node.type === 'text') {
+        const text = (node as { content?: string }).content || '';
+        const trimmed = text.trim();
+        return trimmed.length > 0 ? trimmed : null;
+      }
+      if (node.type !== 'element') return null;
+      for (const c of (node as JsxElement).children || []) {
+        const t = findFirstText(c);
+        if (t != null) return t;
+      }
+      return null;
+    };
+    const walk = (node: JsxNode): string | null => {
+      if (node.type !== 'element') return null;
+      const el = node as JsxElement;
+      const tag = el.tagName;
+      if (tag === 'SelectItem' || tag === 'SelectPrimitive.Item') {
+        const itemValue = el.props && el.props.value;
+        if (itemValue != null && String(itemValue) === value) {
+          const labelText = findFirstText(el);
+          if (labelText != null) return labelText;
+        }
+      }
+      for (const c of el.children || []) {
+        const found = walk(c);
+        if (found != null) return found;
+      }
+      return null;
+    };
+    return walk(rootEl);
+  }
+
+  private findFirstSelectItemValue(rootEl: JsxElement): string | null {
+    const walk = (node: JsxNode): string | null => {
+      if (node.type !== 'element') return null;
+      const el = node as JsxElement;
+      const tag = el.tagName;
+      if (tag === 'SelectItem' || tag === 'SelectPrimitive.Item') {
+        const v = el.props && el.props.value;
+        if (v != null && String(v).length > 0) return String(v);
+      }
+      for (const c of el.children || []) {
+        const found = walk(c);
+        if (found != null) return found;
+      }
+      return null;
+    };
+    return walk(rootEl);
+  }
+
   /**
    * Returns true if the expanded node's root is a portal wrapper (renders outside the DOM tree).
    * Used to unwrap components like DialogContent, SelectContent, SheetContent, DropdownMenuContent.
@@ -3238,8 +3709,14 @@ export class ComponentScanner {
   /**
    * Strips portal-specific CSS classes that are meaningless or harmful in Figma:
    * fixed/absolute positioning, transforms, z-index, state-variant animations,
-   * transition durations, complex calc() max-widths, and responsive max-w variants
-   * (the story's own max-w prop is the authoritative width constraint).
+   * transition durations, and complex calc() max-widths (can't be evaluated
+   * to a pixel value).
+   *
+   * Responsive `max-w-*` variants (e.g. shadcn DialogContent's `sm:max-w-lg`)
+   * are KEPT — they're the only signal that tells the renderer the dialog
+   * intends to render at 512px, not the 900px Story Layout fallback. A
+   * consumer-supplied unprefixed `max-w-*` still wins via `extractMaxWidth`
+   * Pass 1.
    *
    * Called on the extracted portal content node so the renderer sees only the
    * visual layout classes (grid, gap, padding, border, shadow, bg, etc.).
@@ -3275,8 +3752,6 @@ export class ComponentScanner {
         if (/^ease-/.test(cls)) return false;
         // Complex calc/min/max max-w (can't be evaluated to a pixel value)
         if (/^max-w-\[(?:calc|min|max)\(/.test(cls)) return false;
-        // Responsive max-w variants — the story's explicit max-w is authoritative
-        if (/^(?:sm|md|lg|xl|2xl):max-w-/.test(cls)) return false;
         return true;
       })
       .join(' ');
@@ -3321,6 +3796,73 @@ export class ComponentScanner {
       }
       return;
     }
+    // Fragment branch `<>…</>` — flatten its children inline. React fragments
+    // are layout-transparent (they have no DOM); the children participate
+    // directly in the surrounding parent's layout. Canonical real-world
+    // shape:
+    //   {isLong ? (<><svg/>Long / Buy</>) : (<><svg/>Short / Sell</>)}
+    // — the submit Button's body. Without flattening, the chosen Fragment
+    // fell through to `resolveExpressionValue` and the whole branch was
+    // dropped, so the Button rendered empty (no icon, no label).
+    if (Node.isJsxFragment(chosen)) {
+      // `.getChildren()` on a JsxFragment returns syntax tokens (the
+      // opening / closing fragment tags + a SyntaxList). `.getJsxChildren()`
+      // is the one that returns the actual JSX children (elements, text,
+      // expressions) — that's what we need to flatten into the parent.
+      for (const fragChild of chosen.getJsxChildren()) {
+        if (Node.isJsxElement(fragChild) || Node.isJsxSelfClosingElement(fragChild) || Node.isJsxFragment(fragChild)) {
+          this.pushChosenJsxBranch(fragChild, children, localComponents, relativeImports, propsContext);
+        } else if (Node.isJsxText(fragChild)) {
+          const text = decodeHtmlEntities(normalizeJsxText(fragChild.getFullText()));
+          if (text) children.push({ type: 'text', content: text });
+        } else if (Node.isJsxExpression(fragChild)) {
+          const inner = fragChild.getExpression();
+          if (inner) this.pushChosenJsxBranch(inner, children, localComponents, relativeImports, propsContext);
+        }
+      }
+      return;
+    }
+    // Nested ternary `a ? x : (b ? y : z)` — the outer branch is itself a
+    // ConditionalExpression that the .map-context handler would unpack
+    // recursively. Mirror that here so multi-level conditionals don't get
+    // silently dropped. Canonical real-world shape (IncreasePositionModal
+    // Position impact card):
+    //   {previewLoading ? <skel/> : previewMetrics ? <metrics/> : <empty/>}
+    // — the outer-false branch is `previewMetrics ? metrics : empty`,
+    // another ConditionalExpression. Without recursion it landed in
+    // `resolveExpressionValue` which returned `undefined` for JSX
+    // expressions, and the entire card body disappeared.
+    if (Node.isConditionalExpression(chosen)) {
+      const condValue = this.resolveExpressionValue(chosen.getCondition(), propsContext);
+      if (condValue !== undefined) {
+        const nested = this.isExpressionTruthy(condValue)
+          ? chosen.getWhenTrue()
+          : chosen.getWhenFalse();
+        this.pushChosenJsxBranch(nested, children, localComponents, relativeImports, propsContext);
+      }
+      return;
+    }
+    // CallExpression `arr.map(...)` inside a ternary branch must expand the
+    // same way it would as a direct JSX child. Without this case the
+    // walker drops it silently because `resolveExpressionValue` doesn't
+    // know how to iterate `.map`. Canonical repro: a table body shaped
+    //   {rows.length ? rows.map(row => <Row/>) : <EmptyRow/>}
+    // — the truthy branch is the CallExpression, gets routed here, and
+    // disappeared.
+    if (Node.isCallExpression(chosen)) {
+      const callee = chosen.getExpression();
+      if (Node.isPropertyAccessExpression(callee) && callee.getName() === 'map') {
+        const expanded = this.expandMapCall(
+          chosen,
+          chosen.getSourceFile(),
+          localComponents,
+          relativeImports,
+          propsContext,
+        );
+        for (const c of expanded) children.push(c);
+        return;
+      }
+    }
     const resolved = this.resolveExpressionValue(chosen, propsContext);
     if (resolved !== undefined && resolved !== null) {
       this.pushResolvedPropValue(children, resolved);
@@ -3861,7 +4403,33 @@ export class ComponentScanner {
         continue;
       }
       if (!Node.isPropertyAssignment(prop)) continue;
-      const key = prop.getName();
+      // String-literal keys (`{ "So111...": value }`) — `prop.getName()`
+      // returns the raw text INCLUDING the surrounding quotes, which would
+      // store the entry under `"\"So111...\""` and break any
+      // bracket-lookup with the unquoted string. Unwrap the literal so
+      // the stored key matches what the consumer's `obj[mintString]`
+      // access actually looks up.
+      const nameNode = prop.getNameNode();
+      let key: string | undefined;
+      if (nameNode && (Node.isStringLiteral(nameNode) || Node.isNoSubstitutionTemplateLiteral(nameNode))) {
+        key = nameNode.getLiteralValue();
+      } else if (nameNode && Node.isNumericLiteral(nameNode)) {
+        key = String(nameNode.getLiteralValue());
+      } else if (nameNode && Node.isComputedPropertyName(nameNode)) {
+        // Computed property names (`{ [USDC_MINT]: ... }`) — evaluate
+        // the inner expression and use the resolved value as the key.
+        // Common in token tables that key off an exported constant
+        // (greenhouse-app's TOKEN_METADATA uses `[USDC_MINT]` so the
+        // map is keyed by the actual mint string, not the identifier
+        // text "USDC_MINT").
+        const inner = nameNode.getExpression();
+        const resolvedKey = this.resolveExpressionValue(inner, propsContext);
+        if (resolvedKey != null) {
+          key = String(resolvedKey);
+        }
+      } else {
+        key = prop.getName();
+      }
       if (!key) continue;
       const val = prop.getInitializer();
       if (!val) continue;
@@ -3884,6 +4452,14 @@ export class ComponentScanner {
     const text = val.getText();
     if (text === 'true') return true;
     if (text === 'false') return false;
+    // `null` / `undefined` keywords resolve to their JS values, not the
+    // strings "null" / "undefined". Previously they fell through to the
+    // `return text` branch and (since "null" is a non-empty truthy string)
+    // caused conditionals like `{error && <Banner>{error}</Banner>}` to
+    // render the banner with literal "null" text when stories passed
+    // `error: null`.
+    if (text === 'null') return null;
+    if (text === 'undefined') return undefined;
     if (Node.isArrayLiteralExpression(val)) {
       return val.getElements().map((el) => this.parseLiteralValue(el));
     }
@@ -3893,7 +4469,7 @@ export class ComponentScanner {
     return text;
   }
 
-  private coerceBoolean(value: unknown): boolean | null {
+  private coerceBoolean(value: unknown): boolean {
     if (typeof value === 'boolean') return value;
     if (typeof value === 'number') return value !== 0;
     if (typeof value === 'string') {
@@ -3905,7 +4481,15 @@ export class ComponentScanner {
       if (normalized.length > 0) return true;
       return false;
     }
-    return null;
+    // null / undefined match JS truthiness — falsy. Treating them as
+    // "can't determine" (previous behaviour, returning null) made
+    // optional-prop guards like `activeGroups && X` and
+    // `activeGroups?.length ? a : b` evaluate to undefined and the
+    // entire conditional branch dropped from the JSX tree — instead of
+    // picking the "else" branch the way runtime React would. Match JS.
+    if (value === null || value === undefined) return false;
+    // Objects, arrays, functions, etc. are truthy in JS.
+    return true;
   }
 
   /**
@@ -3965,15 +4549,36 @@ export class ComponentScanner {
     if (Node.isParenthesizedExpression(expr)) {
       return this.resolveExpressionValue(expr.getExpression(), propsContext);
     }
+    // TypeScript type-only constructs that don't affect runtime value —
+    // unwrap to the inner expression. Without this, common consumer
+    // idioms like `(position as any).field` and `position!.field` cause
+    // the entire chain to bail (the cast wrapper isn't one of the
+    // recognised expression shapes).
+    if (Node.isAsExpression(expr) || Node.isSatisfiesExpression(expr) || Node.isNonNullExpression(expr) || Node.isTypeAssertion(expr)) {
+      return this.resolveExpressionValue(expr.getExpression(), propsContext);
+    }
     if (Node.isStringLiteral(expr) || Node.isNoSubstitutionTemplateLiteral(expr)) {
       return expr.getLiteralValue();
     }
     if (Node.isNumericLiteral(expr)) {
       return expr.getLiteralValue();
     }
+    if (Node.isArrayLiteralExpression(expr)) {
+      return this.parseArrayLiteral(expr);
+    }
+    if (Node.isObjectLiteralExpression(expr)) {
+      // Inline object literals appearing as call/new arguments (e.g. the
+      // options bag in `new Intl.NumberFormat("en-US", { style: "currency",
+      // currency: "USD" })`). Without this case the evaluator returned
+      // undefined for the options arg, so the Intl instance fell back to
+      // its default formatting (no currency, no fraction digits).
+      return this.parseObjectLiteralExpression(expr, propsContext);
+    }
     const exprText = expr.getText();
     if (exprText === 'true') return true;
     if (exprText === 'false') return false;
+    if (exprText === 'null') return null;
+    if (exprText === 'undefined') return undefined;
     if (Node.isIdentifier(expr)) {
       if (propsContext.has(exprText)) return propsContext.get(exprText);
       // Resolve function-body-local consts FIRST so they shadow module-level
@@ -4002,7 +4607,51 @@ export class ComponentScanner {
           if (Node.isObjectLiteralExpression(unwrapped)) {
             return this.parseObjectLiteralExpression(unwrapped, propsContext);
           }
+          // Module-level pure-constructor instances (e.g.
+          // `const usdFormatter = new Intl.NumberFormat(...)`). Evaluating
+          // the NewExpression returns the live JS object so subsequent
+          // `usdFormatter.format(N)` calls dispatch against its prototype.
+          if (Node.isNewExpression(unwrapped)) {
+            return this.evaluateNewExpression(unwrapped, propsContext);
+          }
+        }
+      }
+      // Cross-module identifier: follow a named import to the source file
+      // and try the same module-level resolution there. Enables
+      // `import { usdFormatter } from './utils'` patterns to find the
+      // remote Intl.NumberFormat instance.
+      for (const importDecl of expr.getSourceFile().getImportDeclarations()) {
+        const match = importDecl.getNamedImports().find(
+          ni => (ni.getAliasNode()?.getText() ?? ni.getName()) === exprText
+        );
+        if (!match) continue;
+        const sourceModule = importDecl.getModuleSpecifierSourceFile();
+        if (!sourceModule) break;
+        const importedName = match.getName();
+        const importedVar = sourceModule.getVariableDeclaration(importedName);
+        if (!importedVar) break;
+        const init = importedVar.getInitializer();
+        if (!init) break;
+        const unwrapped = this.unwrapStaticValueExpression(init) || init;
+        if (Node.isStringLiteral(unwrapped) || Node.isNoSubstitutionTemplateLiteral(unwrapped)) {
+          return unwrapped.getLiteralValue();
+        }
+        if (Node.isNumericLiteral(unwrapped)) return unwrapped.getLiteralValue();
+        if (Node.isNewExpression(unwrapped)) {
+          return this.evaluateNewExpression(unwrapped, propsContext);
         }
+        // Imported object / array literals — TOKEN_METADATA / DEFAULT_ACTIVE
+        // / constant tables that consumers commonly import for lookups
+        // (`TOKEN_METADATA[mint]?.symbol`). Without this, the element-access
+        // returns undefined and falls through to fallbacks (e.g. `mint.slice(
+        // 0, 4)` → "So11" instead of "SOL").
+        if (Node.isArrayLiteralExpression(unwrapped)) {
+          return this.parseArrayLiteral(unwrapped);
+        }
+        if (Node.isObjectLiteralExpression(unwrapped)) {
+          return this.parseObjectLiteralExpression(unwrapped, propsContext);
+        }
+        break;
       }
       return undefined;
     }
@@ -4048,17 +4697,31 @@ export class ComponentScanner {
     }
     if (Node.isBinaryExpression(expr)) {
       const op = expr.getOperatorToken().getText();
-      if (op === '===' || op === '==') {
-        const left = this.resolveExpressionValue(expr.getLeft(), propsContext);
-        const right = this.resolveExpressionValue(expr.getRight(), propsContext);
+      // Equality with `undefined` / `null` literals must compare even when
+      // the resolved operand IS undefined. Otherwise common nullish guards
+      // (`if (value === undefined) return null;`) always evaluate to
+      // undefined and the interpreter incorrectly falls through, which
+      // breaks every formatter that does an early-return on missing input.
+      if (op === '===' || op === '==' || op === '!==' || op === '!=') {
+        const leftExpr = expr.getLeft();
+        const rightExpr = expr.getRight();
+        const leftText = leftExpr.getText();
+        const rightText = rightExpr.getText();
+        const leftLitUndef = leftText === 'undefined';
+        const leftLitNull = leftText === 'null';
+        const rightLitUndef = rightText === 'undefined';
+        const rightLitNull = rightText === 'null';
+        const left = this.resolveExpressionValue(leftExpr, propsContext);
+        const right = this.resolveExpressionValue(rightExpr, propsContext);
+        const strict = op === '===' || op === '!==';
+        const negate = op === '!==' || op === '!=';
+        const apply = (eq: boolean) => negate ? !eq : eq;
+        if (rightLitUndef) return apply(strict ? left === undefined : left == null);
+        if (leftLitUndef) return apply(strict ? right === undefined : right == null);
+        if (rightLitNull) return apply(strict ? left === null : left == null);
+        if (leftLitNull) return apply(strict ? right === null : right == null);
         if (left === undefined || right === undefined) return undefined;
-        return left === right;
-      }
-      if (op === '!==' || op === '!=') {
-        const left = this.resolveExpressionValue(expr.getLeft(), propsContext);
-        const right = this.resolveExpressionValue(expr.getRight(), propsContext);
-        if (left === undefined || right === undefined) return undefined;
-        return left !== right;
+        return apply(strict ? left === right : left == right);
       }
       if (op === '&&') {
         const left = this.coerceBoolean(this.resolveExpressionValue(expr.getLeft(), propsContext));
@@ -4085,15 +4748,25 @@ export class ComponentScanner {
         if (typeof left === 'number' && typeof right === 'number') return left + right;
         return String(left) + String(right);
       }
-      if (op === '-' || op === '*' || op === '/' || op === '%') {
+      if (op === '-' || op === '*' || op === '/' || op === '%' || op === '**') {
         const left = this.resolveExpressionValue(expr.getLeft(), propsContext);
         const right = this.resolveExpressionValue(expr.getRight(), propsContext);
         if (typeof left !== 'number' || typeof right !== 'number') return undefined;
         if (op === '-') return left - right;
         if (op === '*') return left * right;
+        if (op === '**') return left ** right;
         if (op === '/') return right === 0 ? undefined : left / right;
         return right === 0 ? undefined : left % right;
       }
+      if (op === '<' || op === '<=' || op === '>' || op === '>=') {
+        const left = this.resolveExpressionValue(expr.getLeft(), propsContext);
+        const right = this.resolveExpressionValue(expr.getRight(), propsContext);
+        if (typeof left !== 'number' || typeof right !== 'number') return undefined;
+        if (op === '<') return left < right;
+        if (op === '<=') return left <= right;
+        if (op === '>') return left > right;
+        return left >= right;
+      }
     }
     // Method-call expressions on resolvable bases — covers the common
     // story-args pattern `{rewardSol.toFixed(4)} SOL`. Without this the
@@ -4103,51 +4776,622 @@ export class ComponentScanner {
     // String built-in methods that have an obvious string output — we
     // are NOT a JS evaluator, just covering the high-traffic cases.
     if (Node.isCallExpression(expr)) {
+      const builtinResult = this.evaluateBuiltinCall(expr, propsContext);
+      if (builtinResult !== undefined) return builtinResult;
+      // User-function evaluator handles both Identifier callees
+      // (`formatUsd(price)`) and IIFE callees (`(() => { ... })()`).
+      // Returns undefined for shapes it can't dispatch on.
+      const interpreted = this.evaluateUserFunctionCall(expr, propsContext);
+      if (interpreted !== undefined) return interpreted;
       const calleeExpr = expr.getExpression();
-      if (Node.isPropertyAccessExpression(calleeExpr)) {
-        const methodName = calleeExpr.getName();
-        const baseValue = this.resolveExpressionValue(calleeExpr.getExpression(), propsContext);
-        if (baseValue == null) return undefined;
+      if (Node.isIdentifier(calleeExpr)) {
+        // Raw-arg fallback ONLY applies to identifier-named calls — when
+        // the user-fn interpreter couldn't follow the function (unknown
+        // helper, unsupported body construct, etc.), echo the first
+        // argument so the cell renders the raw data instead of going
+        // blank. Skip known side-effect helpers.
+        const fnName = calleeExpr.getText();
+        if (fnName === 'console' || fnName.startsWith('use')) return undefined;
+        const firstArg = expr.getArguments()[0];
+        if (firstArg) {
+          const resolved = this.resolveExpressionValue(firstArg, propsContext);
+          if (resolved !== undefined && resolved !== null) return resolved;
+        }
+      }
+    }
+    if (Node.isNewExpression(expr)) {
+      return this.evaluateNewExpression(expr, propsContext);
+    }
+    if (Node.isPrefixUnaryExpression(expr)) {
+      const op = expr.getOperatorToken();
+      const operandValue = this.resolveExpressionValue(expr.getOperand(), propsContext);
+      if (operandValue === undefined) return undefined;
+      if (op === SyntaxKind.ExclamationToken) return !this.coerceBoolean(operandValue);
+      if (op === SyntaxKind.MinusToken && typeof operandValue === 'number') return -operandValue;
+      if (op === SyntaxKind.PlusToken && typeof operandValue === 'number') return +operandValue;
+      if (op === SyntaxKind.TildeToken && typeof operandValue === 'number') return ~operandValue;
+      return undefined;
+    }
+    if (Node.isTypeOfExpression(expr)) {
+      const operandValue = this.resolveExpressionValue(expr.getExpression(), propsContext);
+      if (operandValue === undefined) return undefined;
+      if (operandValue === null) return 'object';
+      return typeof operandValue;
+    }
+    if (Node.isTemplateExpression(expr)) {
+      const parts: string[] = [expr.getHead().getLiteralText() || ''];
+      for (const span of expr.getTemplateSpans()) {
+        const resolved = this.resolveExpressionValue(span.getExpression(), propsContext);
+        if (resolved === undefined) return undefined;
+        parts.push(String(resolved));
+        parts.push(span.getLiteral().getLiteralText() || '');
+      }
+      return parts.join('');
+    }
+    return undefined;
+  }
+
+  /**
+   * Built-in JS evaluation for CallExpression — string / number / Date /
+   * Intl.NumberFormat / Boolean methods, plus global conversion functions
+   * (`Number`, `String`, `Boolean`, `parseInt`, `parseFloat`, `isNaN`,
+   * `isFinite`) and `Number.*` / `Math.*` namespace functions.
+   *
+   * Returns `undefined` when the call shape isn't recognised — that's the
+   * signal for the caller to keep trying (user-function evaluator, raw-arg
+   * fallback).
+   *
+   * Restricted to pure, side-effect-free operations so we can run them at
+   * scan time without surprising the consumer.
+   */
+  private evaluateBuiltinCall(expr: Node, propsContext: Map<string, ResolvedExpressionValue>): ResolvedExpressionValue {
+    if (!Node.isCallExpression(expr)) return undefined;
+    const calleeExpr = expr.getExpression();
+    if (Node.isPropertyAccessExpression(calleeExpr)) {
+      const methodName = calleeExpr.getName();
+      const baseExpr = calleeExpr.getExpression();
+      // `Number.isFinite(x)`, `Number.isInteger(x)`, `Number.isNaN(x)`,
+      // `Math.abs(x)`, `Math.floor(x)`, etc. — namespace dispatch, not
+      // instance method dispatch.
+      if (Node.isIdentifier(baseExpr)) {
+        const baseText = baseExpr.getText();
         const argValues = expr.getArguments().map(a => this.resolveExpressionValue(a, propsContext));
-        const NUMBER_METHODS: Record<string, boolean> = { toFixed: true, toString: true, toPrecision: true };
-        const STRING_METHODS: Record<string, boolean> = { toString: true, toUpperCase: true, toLowerCase: true, trim: true };
-        if (typeof baseValue === 'number' && NUMBER_METHODS[methodName]) {
+        if (baseText === 'Number') {
           const arg = argValues[0];
+          if (methodName === 'isFinite') return typeof arg === 'number' && Number.isFinite(arg);
+          if (methodName === 'isInteger') return typeof arg === 'number' && Number.isInteger(arg);
+          if (methodName === 'isNaN') return typeof arg === 'number' && Number.isNaN(arg);
+          if (methodName === 'isSafeInteger') return typeof arg === 'number' && Number.isSafeInteger(arg);
+        }
+        if (baseText === 'Math') {
+          if (argValues.some(v => typeof v !== 'number')) return undefined;
+          const nums = argValues as number[];
           try {
-            if (methodName === 'toFixed' && typeof arg === 'number') return baseValue.toFixed(arg);
-            if (methodName === 'toPrecision' && typeof arg === 'number') return baseValue.toPrecision(arg);
-            if (methodName === 'toString') return String(baseValue);
+            if (methodName === 'abs') return Math.abs(nums[0]);
+            if (methodName === 'floor') return Math.floor(nums[0]);
+            if (methodName === 'ceil') return Math.ceil(nums[0]);
+            if (methodName === 'round') return Math.round(nums[0]);
+            if (methodName === 'trunc') return Math.trunc(nums[0]);
+            if (methodName === 'sign') return Math.sign(nums[0]);
+            if (methodName === 'sqrt') return Math.sqrt(nums[0]);
+            if (methodName === 'pow') return Math.pow(nums[0], nums[1]);
+            if (methodName === 'min') return Math.min(...nums);
+            if (methodName === 'max') return Math.max(...nums);
           } catch (_e) { return undefined; }
         }
-        if (typeof baseValue === 'string' && STRING_METHODS[methodName]) {
+        // `Object.entries(x)` / `Object.keys(x)` / `Object.values(x)` /
+        // `Object.fromEntries(pairs)` — pure, predictable shape transforms.
+        // Real-world trigger: shadcn Select dropdowns built via
+        // `Object.entries(TOKEN_METADATA).map(([k, v]) => <SelectItem ...>)`
+        // — without this the scanner can't expand the .map() into actual
+        // SelectItem nodes, so `findSelectedSelectLabel` can't resolve the
+        // selected value's label and the Figma render shows the raw value
+        // (mint address) instead of the label ("USDC").
+        if (baseText === 'Object') {
+          const arg = argValues[0];
+          try {
+            if (methodName === 'keys') {
+              if (arg && typeof arg === 'object') return Object.keys(arg as object);
+              return undefined;
+            }
+            if (methodName === 'values') {
+              if (arg && typeof arg === 'object') return Object.values(arg as object);
+              return undefined;
+            }
+            if (methodName === 'entries') {
+              if (arg && typeof arg === 'object') return Object.entries(arg as object);
+              return undefined;
+            }
+            if (methodName === 'fromEntries') {
+              if (Array.isArray(arg)) return Object.fromEntries(arg as Iterable<[PropertyKey, unknown]>);
+              return undefined;
+            }
+          } catch (_e) { return undefined; }
+        }
+      }
+      const baseValue = this.resolveExpressionValue(baseExpr, propsContext);
+      if (baseValue == null) return undefined;
+      const argValues = expr.getArguments().map(a => this.resolveExpressionValue(a, propsContext));
+      // Intl.NumberFormat / Intl.DateTimeFormat / Date / Set / Map instances.
+      // The resolver returns the live JS object for `new Intl.NumberFormat(...)`
+      // / `new Date(...)` / `new Set(...)` / `new Map(...)` expressions so we
+      // can dispatch on the prototype here.
+      if (typeof baseValue === 'object') {
+        // `.size` is a getter, not a method — handled by the
+        // PropertyAccessExpression branch above. Only the method calls
+        // (`.has`, `.get`) live here.
+        if (baseValue instanceof Set && methodName === 'has') {
+          try { return baseValue.has(argValues[0]); } catch (_e) { return undefined; }
+        }
+        if (baseValue instanceof Map) {
+          try {
+            if (methodName === 'has') return baseValue.has(argValues[0]);
+            if (methodName === 'get') return baseValue.get(argValues[0]);
+          } catch (_e) { return undefined; }
+        }
+        if (baseValue instanceof Intl.NumberFormat && methodName === 'format' && typeof argValues[0] === 'number') {
+          try { return baseValue.format(argValues[0]); } catch (_e) { return undefined; }
+        }
+        if (baseValue instanceof Intl.DateTimeFormat && methodName === 'format' && argValues[0] instanceof Date) {
+          try { return baseValue.format(argValues[0]); } catch (_e) { return undefined; }
+        }
+        if (baseValue instanceof Date) {
+          try {
+            if (methodName === 'toISOString') return baseValue.toISOString();
+            if (methodName === 'toUTCString') return baseValue.toUTCString();
+            if (methodName === 'toDateString') return baseValue.toDateString();
+            if (methodName === 'toTimeString') return baseValue.toTimeString();
+            if (methodName === 'toString') return baseValue.toString();
+            if (methodName === 'toLocaleString') return baseValue.toLocaleString();
+            if (methodName === 'toLocaleDateString') return baseValue.toLocaleDateString();
+            if (methodName === 'toLocaleTimeString') return baseValue.toLocaleTimeString();
+            if (methodName === 'getTime') return baseValue.getTime();
+            if (methodName === 'valueOf') return baseValue.valueOf();
+            if (methodName === 'getFullYear') return baseValue.getFullYear();
+            if (methodName === 'getMonth') return baseValue.getMonth();
+            if (methodName === 'getDate') return baseValue.getDate();
+          } catch (_e) { return undefined; }
+        }
+      }
+      // String instance methods.
+      if (typeof baseValue === 'string') {
+        try {
+          if (methodName === 'toString' || methodName === 'valueOf') return baseValue;
           if (methodName === 'toUpperCase') return baseValue.toUpperCase();
           if (methodName === 'toLowerCase') return baseValue.toLowerCase();
           if (methodName === 'trim') return baseValue.trim();
-          if (methodName === 'toString') return baseValue;
+          if (methodName === 'trimStart' || methodName === 'trimLeft') return baseValue.trimStart();
+          if (methodName === 'trimEnd' || methodName === 'trimRight') return baseValue.trimEnd();
+          if (methodName === 'slice' && typeof argValues[0] === 'number') {
+            return argValues.length >= 2 && typeof argValues[1] === 'number'
+              ? baseValue.slice(argValues[0] as number, argValues[1] as number)
+              : baseValue.slice(argValues[0] as number);
+          }
+          if (methodName === 'substring' && typeof argValues[0] === 'number') {
+            return argValues.length >= 2 && typeof argValues[1] === 'number'
+              ? baseValue.substring(argValues[0] as number, argValues[1] as number)
+              : baseValue.substring(argValues[0] as number);
+          }
+          if (methodName === 'substr' && typeof argValues[0] === 'number') {
+            // `String.prototype.substr` is deprecated but still used in the
+            // wild; map it onto `substring`-equivalent semantics (start +
+            // length) so consumer code that uses it still resolves.
+            const start = argValues[0] as number;
+            const len = typeof argValues[1] === 'number' ? (argValues[1] as number) : baseValue.length;
+            return baseValue.substring(start, start + len);
+          }
+          if (methodName === 'replace' && typeof argValues[0] === 'string' && typeof argValues[1] === 'string') {
+            return baseValue.replace(argValues[0] as string, argValues[1] as string);
+          }
+          if (methodName === 'replaceAll' && typeof argValues[0] === 'string' && typeof argValues[1] === 'string') {
+            // String.prototype.replaceAll requires es2021 in the lib target;
+            // emulate via split/join so we keep the current tsconfig target.
+            return baseValue.split(argValues[0] as string).join(argValues[1] as string);
+          }
+          if (methodName === 'concat') {
+            const allStrings = argValues.every(v => typeof v === 'string');
+            if (allStrings) return baseValue.concat(...(argValues as string[]));
+          }
+          if (methodName === 'repeat' && typeof argValues[0] === 'number') {
+            return baseValue.repeat(argValues[0] as number);
+          }
+          if (methodName === 'padStart' && typeof argValues[0] === 'number') {
+            const pad = typeof argValues[1] === 'string' ? (argValues[1] as string) : ' ';
+            return baseValue.padStart(argValues[0] as number, pad);
+          }
+          if (methodName === 'padEnd' && typeof argValues[0] === 'number') {
+            const pad = typeof argValues[1] === 'string' ? (argValues[1] as string) : ' ';
+            return baseValue.padEnd(argValues[0] as number, pad);
+          }
+          if (methodName === 'startsWith' && typeof argValues[0] === 'string') {
+            return baseValue.startsWith(argValues[0] as string);
+          }
+          if (methodName === 'endsWith' && typeof argValues[0] === 'string') {
+            return baseValue.endsWith(argValues[0] as string);
+          }
+          if (methodName === 'includes' && typeof argValues[0] === 'string') {
+            return baseValue.includes(argValues[0] as string);
+          }
+          if (methodName === 'indexOf' && typeof argValues[0] === 'string') {
+            return baseValue.indexOf(argValues[0] as string);
+          }
+          if (methodName === 'lastIndexOf' && typeof argValues[0] === 'string') {
+            return baseValue.lastIndexOf(argValues[0] as string);
+          }
+          if (methodName === 'charAt' && typeof argValues[0] === 'number') {
+            return baseValue.charAt(argValues[0] as number);
+          }
+          if (methodName === 'at' && typeof argValues[0] === 'number') {
+            return baseValue.at(argValues[0] as number);
+          }
+          if (methodName === 'split' && typeof argValues[0] === 'string') {
+            return baseValue.split(argValues[0] as string);
+          }
+          if (methodName === 'normalize') return baseValue.normalize();
+        } catch (_e) { return undefined; }
+      }
+      // Number instance methods.
+      if (typeof baseValue === 'number') {
+        try {
+          if (methodName === 'toString') {
+            const radix = argValues[0];
+            return typeof radix === 'number' ? baseValue.toString(radix) : String(baseValue);
+          }
+          if (methodName === 'valueOf') return baseValue;
+          if (methodName === 'toFixed' && typeof argValues[0] === 'number') return baseValue.toFixed(argValues[0] as number);
+          if (methodName === 'toPrecision' && typeof argValues[0] === 'number') return baseValue.toPrecision(argValues[0] as number);
+          if (methodName === 'toExponential' && typeof argValues[0] === 'number') return baseValue.toExponential(argValues[0] as number);
+          if (methodName === 'toLocaleString') return baseValue.toLocaleString();
+        } catch (_e) { return undefined; }
+      }
+      // Boolean instance methods.
+      if (typeof baseValue === 'boolean') {
+        if (methodName === 'toString') return String(baseValue);
+        if (methodName === 'valueOf') return baseValue;
+      }
+      // Array instance methods (limited subset — read-only / pure transforms).
+      if (Array.isArray(baseValue)) {
+        try {
+          if (methodName === 'join') {
+            const sep = typeof argValues[0] === 'string' ? (argValues[0] as string) : ',';
+            return baseValue.join(sep);
+          }
+          if (methodName === 'slice') {
+            const start = typeof argValues[0] === 'number' ? (argValues[0] as number) : undefined;
+            const end = typeof argValues[1] === 'number' ? (argValues[1] as number) : undefined;
+            return baseValue.slice(start, end);
+          }
+          if (methodName === 'concat') {
+            return baseValue.concat(...(argValues.filter(v => v !== undefined) as ResolvedExpressionValue[]));
+          }
+          if (methodName === 'includes') return baseValue.includes(argValues[0]);
+          if (methodName === 'indexOf') return baseValue.indexOf(argValues[0]);
+          if (methodName === 'lastIndexOf') return baseValue.lastIndexOf(argValues[0]);
+          if (methodName === 'at' && typeof argValues[0] === 'number') return baseValue.at(argValues[0] as number);
+        } catch (_e) { return undefined; }
+      }
+      return undefined;
+    }
+    // Global identifier calls: `Number(x)`, `String(x)`, `Boolean(x)`,
+    // `parseInt(x, 10)`, `parseFloat(x)`, `isNaN(x)`, `isFinite(x)`.
+    if (Node.isIdentifier(calleeExpr)) {
+      const fnName = calleeExpr.getText();
+      const argValues = expr.getArguments().map(a => this.resolveExpressionValue(a, propsContext));
+      const first = argValues[0];
+      try {
+        if (fnName === 'Number') {
+          if (typeof first === 'number') return first;
+          if (typeof first === 'string' || typeof first === 'boolean') return Number(first);
+          if (first === null) return 0;
+          return undefined;
         }
-      } else if (Node.isIdentifier(calleeExpr)) {
-        // User-defined function call (e.g. `truncateHash(block.blockHash)`,
-        // `formatTimestamp(block.timestamp)`). We can't execute the
-        // function — that'd require evaluating arbitrary JS — but we
-        // CAN resolve the first argument and return it as a graceful
-        // fallback. Rendering "DKjW9hX6dqBE6aDgqdX7Ytqa…" as-is is
-        // better than rendering an empty cell. If the user's function
-        // does important formatting (e.g. truncation) the value will
-        // look longer than the runtime, but it's visible and obviously
-        // points at the right field. Skip well-known *side-effect*
-        // helpers like `console.*` so we don't surface noise.
-        const fnName = calleeExpr.getText();
-        if (fnName === 'console' || fnName.startsWith('use')) return undefined;
-        const firstArg = expr.getArguments()[0];
-        if (firstArg) {
-          const resolved = this.resolveExpressionValue(firstArg, propsContext);
-          if (resolved !== undefined && resolved !== null) return resolved;
+        if (fnName === 'String') return String(first);
+        if (fnName === 'Boolean') return Boolean(first);
+        if (fnName === 'parseInt') {
+          if (typeof first !== 'string' && typeof first !== 'number') return undefined;
+          const radix = typeof argValues[1] === 'number' ? (argValues[1] as number) : 10;
+          return parseInt(String(first), radix);
+        }
+        if (fnName === 'parseFloat') {
+          if (typeof first !== 'string' && typeof first !== 'number') return undefined;
+          return parseFloat(String(first));
         }
+        if (fnName === 'isNaN') return typeof first === 'number' ? isNaN(first) : undefined;
+        if (fnName === 'isFinite') return typeof first === 'number' ? isFinite(first) : undefined;
+      } catch (_e) { return undefined; }
+    }
+    return undefined;
+  }
+
+  /**
+   * P2: handle `new Intl.NumberFormat(...)`, `new Intl.DateTimeFormat(...)`,
+   * `new Date(...)`. Returns the live JS instance so subsequent method calls
+   * (`fmt.format(123)`, `date.toLocaleString()`) can dispatch on its
+   * prototype via `evaluateBuiltinCall`.
+   *
+   * All three constructors are pure (no IO, no DOM). Safe to run at scan
+   * time. We swallow construction errors and return undefined to keep the
+   * scanner robust to oddly-shaped args.
+   */
+  private evaluateNewExpression(expr: Node, propsContext: Map<string, ResolvedExpressionValue>): ResolvedExpressionValue {
+    if (!Node.isNewExpression(expr)) return undefined;
+    const calleeExpr = expr.getExpression();
+    const args = (expr.getArguments() || []).map(a => this.resolveExpressionValue(a, propsContext));
+    // `new Intl.NumberFormat(...)` / `new Intl.DateTimeFormat(...)`
+    if (Node.isPropertyAccessExpression(calleeExpr)) {
+      const ns = calleeExpr.getExpression().getText();
+      const ctor = calleeExpr.getName();
+      if (ns === 'Intl') {
+        try {
+          if (ctor === 'NumberFormat') {
+            const locale = typeof args[0] === 'string' ? (args[0] as string) : (Array.isArray(args[0]) ? (args[0] as string[]) : undefined);
+            const opts = args[1] && typeof args[1] === 'object' ? (args[1] as Intl.NumberFormatOptions) : undefined;
+            return new Intl.NumberFormat(locale, opts);
+          }
+          if (ctor === 'DateTimeFormat') {
+            const locale = typeof args[0] === 'string' ? (args[0] as string) : undefined;
+            const opts = args[1] && typeof args[1] === 'object' ? (args[1] as Intl.DateTimeFormatOptions) : undefined;
+            return new Intl.DateTimeFormat(locale, opts);
+          }
+        } catch (_e) { return undefined; }
+      }
+    }
+    if (Node.isIdentifier(calleeExpr) && calleeExpr.getText() === 'Date') {
+      try {
+        if (args.length === 0) return new Date();
+        const a = args[0];
+        if (typeof a === 'string' || typeof a === 'number') return new Date(a);
+      } catch (_e) { return undefined; }
+    }
+    // `new Set([...])` / `new Set()` and `new Map([[k, v], ...])` / `new Map()`.
+    // Pure constructors with no IO, safe at scan time. Enables the common
+    // visibility-gate idiom `const active = new Set(activeGroups ?? DEFAULTS);
+    // active.has("price") ? <Section/> : null` — Set/Map methods then dispatch
+    // via `evaluateBuiltinCall`.
+    if (Node.isIdentifier(calleeExpr)) {
+      const ctorName = calleeExpr.getText();
+      if (ctorName === 'Set') {
+        try {
+          if (args.length === 0) return new Set();
+          if (Array.isArray(args[0])) return new Set(args[0] as Iterable<unknown>);
+          return undefined;
+        } catch (_e) { return undefined; }
+      }
+      if (ctorName === 'Map') {
+        try {
+          if (args.length === 0) return new Map();
+          if (Array.isArray(args[0])) {
+            // Validate every entry is a 2-tuple — silently drop malformed
+            // inputs rather than throwing, so the scanner remains robust.
+            const entries = args[0] as unknown[];
+            const valid: Array<[unknown, unknown]> = [];
+            for (const e of entries) {
+              if (Array.isArray(e) && e.length === 2) valid.push([e[0], e[1]]);
+            }
+            return new Map(valid);
+          }
+          return undefined;
+        } catch (_e) { return undefined; }
       }
     }
     return undefined;
   }
 
+  /**
+   * P3: evaluate a user-defined function call by walking the function body
+   * AST. Supports the common shapes used by formatter helpers in consumer
+   * code (`formatUsd`, `formatUsdFromBase`, `resolveUsdNumber`, etc.):
+   *
+   *   - Arrow functions and `function` declarations
+   *   - Single-expression bodies (`(x) => x.toFixed(2)`)
+   *   - Block bodies with `if` / `return` / `const` statements
+   *   - Default parameter values
+   *   - Recursive calls into other user functions (handled implicitly
+   *     because the interpreter calls back into `resolveExpressionValue`)
+   *
+   * Falls back to `undefined` (caller will use the raw-arg fallback) if
+   * the function isn't found, the body uses unsupported constructs, or
+   * any sub-expression resolves to undefined.
+   *
+   * Recursion is depth-limited to guard against pathological code or
+   * accidental infinite chains.
+   */
+  private evaluateUserFunctionCall(
+    callExpr: Node,
+    propsContext: Map<string, ResolvedExpressionValue>
+  ): ResolvedExpressionValue {
+    if (!Node.isCallExpression(callExpr)) return undefined;
+    const calleeExpr = callExpr.getExpression();
+
+    // IIFE form: `(() => { ... })()` or `(function() { ... })()`. The
+    // callee is an inline arrow / function expression wrapped in
+    // parentheses, with the call's args supplied (often zero — the
+    // common pattern is a no-arg IIFE used to scope local state inside
+    // a single JSX expression). We can interpret it the same way as a
+    // named user function — bind params, walk body — without needing
+    // the import / declaration lookup.
+    let inlineFn: UserFunctionNode | undefined;
+    if (Node.isParenthesizedExpression(calleeExpr)) {
+      const inner = calleeExpr.getExpression();
+      if (Node.isArrowFunction(inner) || Node.isFunctionExpression(inner)) inlineFn = inner;
+    } else if (Node.isArrowFunction(calleeExpr) || Node.isFunctionExpression(calleeExpr)) {
+      inlineFn = calleeExpr;
+    }
+    if (inlineFn) {
+      return this.evaluateFunctionLike(inlineFn, callExpr.getArguments(), propsContext, '__iife__');
+    }
+
+    if (!Node.isIdentifier(calleeExpr)) return undefined;
+    const fnName = calleeExpr.getText();
+    const fnNode = this.resolveFunctionDeclaration(fnName, callExpr);
+    if (!fnNode) return undefined;
+    return this.evaluateFunctionLike(fnNode, callExpr.getArguments(), propsContext, fnName);
+  }
+
+  /**
+   * Shared param-binding + body-interpretation entry point for both named
+   * user functions (resolved via import / declaration lookup) and inline
+   * IIFE-style invocations `(() => { ... })()`. The recursion guard keys
+   * on the function's source-file path so each call site participates in
+   * the same depth limit.
+   */
+  private evaluateFunctionLike(
+    fnNode: UserFunctionNode,
+    argExprs: Node[],
+    propsContext: Map<string, ResolvedExpressionValue>,
+    debugKey: string,
+  ): ResolvedExpressionValue {
+    if (!this.userFunctionStack) this.userFunctionStack = new Set();
+    const stackKey = fnNode.getSourceFile().getFilePath() + ':' + debugKey;
+    if (this.userFunctionStack.has(stackKey)) return undefined;
+    if (this.userFunctionStack.size > 16) return undefined;
+    this.userFunctionStack.add(stackKey);
+    try {
+      const params = fnNode.getParameters();
+      const localContext = new Map(propsContext);
+      for (let i = 0; i < params.length; i++) {
+        const paramName = params[i].getName();
+        let value: ResolvedExpressionValue = undefined;
+        if (i < argExprs.length) {
+          value = this.resolveExpressionValue(argExprs[i], propsContext);
+        }
+        if (value === undefined) {
+          const defaultInit = params[i].getInitializer();
+          if (defaultInit) value = this.resolveExpressionValue(defaultInit, propsContext);
+        }
+        localContext.set(paramName, value);
+      }
+      const body = fnNode.getBody();
+      if (!body) return undefined;
+      if (Node.isBlock(body)) {
+        return this.evaluateFunctionBlock(body, localContext);
+      }
+      // Arrow function with expression body.
+      return this.resolveExpressionValue(body, localContext);
+    } finally {
+      this.userFunctionStack.delete(stackKey);
+    }
+  }
+
+  /**
+   * Find the function declaration for a given identifier, following one
+   * level of `import { name } from '...'` indirection.
+   *
+   * Resolution order:
+   *   1. Variable declaration in the same source file whose initializer is
+   *      an arrow function or function expression.
+   *   2. Top-level `function` declaration in the same file.
+   *   3. Single-named import — follow the module specifier to the source
+   *      file and repeat the search there.
+   *
+   * Returns the function-or-arrow node, or undefined when not resolvable.
+   */
+  private resolveFunctionDeclaration(name: string, originExpr: Node): UserFunctionNode | undefined {
+    const sourceFile = originExpr.getSourceFile();
+    const localVar = sourceFile.getVariableDeclaration(name);
+    if (localVar) {
+      const init = localVar.getInitializer();
+      if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+        return init;
+      }
+    }
+    const localFn = sourceFile.getFunction(name);
+    if (localFn) return localFn;
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+      const namedImports = importDecl.getNamedImports();
+      const match = namedImports.find(ni => (ni.getAliasNode()?.getText() ?? ni.getName()) === name);
+      if (!match) continue;
+      const sourceModule = importDecl.getModuleSpecifierSourceFile();
+      if (!sourceModule) return undefined;
+      const importedName = match.getName();
+      const importedVar = sourceModule.getVariableDeclaration(importedName);
+      if (importedVar) {
+        const init = importedVar.getInitializer();
+        if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+          return init;
+        }
+      }
+      const importedFn = sourceModule.getFunction(importedName);
+      if (importedFn) return importedFn;
+      return undefined;
+    }
+    return undefined;
+  }
+
+  /**
+   * Mini-interpreter for the body of a user function. Supports the
+   * narrow set of statements that appear in pure formatter helpers:
+   *
+   *   - `if (cond) { ... } else { ... }` — early returns work because we
+   *     surface the inner block's return value.
+   *   - `if (cond) return ...;` — single-statement consequent without block.
+   *   - `const x = expr;` / `let x = expr;` — variable bindings shadow
+   *     the caller's context for subsequent statements.
+   *   - `return expr;` — terminates evaluation with the resolved value.
+   *
+   * Returns the value of the executed `return`, or `undefined` if the
+   * body uses an unsupported construct (which the caller treats as
+   * "couldn't interpret, fall through").
+   *
+   * Uses a sentinel symbol to distinguish "block fell through with no
+   * return" (continue interpreting outer statements) from "explicit
+   * return undefined" — only the latter is a successful evaluation.
+   */
+  private evaluateFunctionBlock(
+    block: Node,
+    context: Map<string, ResolvedExpressionValue>
+  ): ResolvedExpressionValue {
+    if (!Node.isBlock(block)) return undefined;
+    for (const stmt of block.getStatements()) {
+      const result = this.evaluateStatement(stmt, context);
+      if (result === EVAL_NEXT) continue;
+      return result;
+    }
+    return undefined;
+  }
+
+  private evaluateStatement(
+    stmt: Node,
+    context: Map<string, ResolvedExpressionValue>
+  ): EvalStatementResult {
+    if (Node.isReturnStatement(stmt)) {
+      const expr = stmt.getExpression();
+      if (!expr) return undefined;
+      return this.resolveExpressionValue(expr, context);
+    }
+    if (Node.isVariableStatement(stmt)) {
+      for (const decl of stmt.getDeclarationList().getDeclarations()) {
+        const init = decl.getInitializer();
+        if (!init) return EVAL_NEXT;
+        const value = this.resolveExpressionValue(init, context);
+        context.set(decl.getName(), value);
+      }
+      return EVAL_NEXT;
+    }
+    if (Node.isIfStatement(stmt)) {
+      const condValue = this.resolveExpressionValue(stmt.getExpression(), context);
+      const condBool = this.coerceBoolean(condValue);
+      if (condBool == null) return undefined;
+      const branch = condBool ? stmt.getThenStatement() : stmt.getElseStatement();
+      if (!branch) return EVAL_NEXT;
+      if (Node.isBlock(branch)) {
+        return this.evaluateFunctionBlock(branch, context);
+      }
+      return this.evaluateStatement(branch, context);
+    }
+    if (Node.isBlock(stmt)) {
+      return this.evaluateFunctionBlock(stmt, context);
+    }
+    if (Node.isExpressionStatement(stmt)) {
+      // No side effects to model; just evaluate for any assignments we
+      // might add in the future. For now, treat as a fall-through.
+      return EVAL_NEXT;
+    }
+    return undefined;
+  }
+
+  private userFunctionStack?: Set<string>;
+
   private resolveClassNameExpression(expr: Node, propsContext: Map<string, ResolvedExpressionValue>): string {
     if (Node.isParenthesizedExpression(expr)) {
       return this.resolveClassNameExpression(expr.getExpression(), propsContext);
@@ -4327,6 +5571,18 @@ export class ComponentScanner {
               }
             }
           }
+
+          // cva()'s special pass-through args: `className` and `class` are
+          // merged into the output verbatim. Without this, shadcn's
+          // `cn(buttonVariants({ variant, size, className }))` lost the
+          // user's className override entirely — the `+` / `−` buttons in
+          // greenhouse-app's LeverageSlider rendered as rounded-md ghost
+          // buttons instead of the rounded-full bordered circles the
+          // consumer asked for. cva treats className/class as the final
+          // merge step on top of base + variant classes, so append them
+          // at the end of our resolved class list.
+          const passThrough = requestedVariants.className || requestedVariants.class;
+          if (passThrough) classes.push(passThrough);
         }
 
         return resolveClassConflicts(classes.filter(Boolean).join(' '));