inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/scanner/component-scanner.ts

@@ -8,7 +8,7 @@
  * - Simple: Components with static classes
  */
 
-import { Project, SyntaxKind, Node, SourceFile } from 'ts-morph';
+import { Project, SyntaxKind, Node, SourceFile, type JsxAttribute } from 'ts-morph';
 import * as path from 'path';
 import * as fs from 'fs';
 import type {
@@ -27,7 +27,24 @@ import type {
   JsxText,
   IconImportSpec,
 } from './types';
-import { groupClassesByState, STATE_MODIFIERS } from './tailwind-parser';
+import { groupClassesByState, OWN_STATE_MODIFIERS } from './tailwind-parser';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Apply tailwind-merge to a space-joined class string to resolve conflicting utilities
+ * (e.g. `w-3/4 w-full` → `w-full`). Runs on the output of resolved `cn()` / `clsx()` /
+ * `twMerge()` / `cva()` call expressions so Figma renders the same class set the browser
+ * would. Falls back to the raw input on any parsing error to stay defensive.
+ */
+function resolveClassConflicts(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return '';
+  try {
+    return twMerge(trimmed);
+  } catch {
+    return trimmed;
+  }
+}
 
 // ============================================================================
 // Helpers
@@ -43,6 +60,46 @@ function decodeHtmlEntities(text: string): string {
   return text.replace(/&[a-zA-Z]+;/g, (entity) => HTML_ENTITIES[entity] ?? entity);
 }
 
+/**
+ * Normalize JsxText whitespace the same way Babel/React do.
+ *
+ * IMPORTANT: callers must pass `child.getFullText()`, NOT `child.getText()`.
+ * ts-morph's `getText()` strips leading trivia from JsxText nodes — for the
+ * JsxText between `</span>` and `are`, getText() returns "are the design..."
+ * with the leading space LOST. That breaks inter-segment spacing
+ * (`Your <span>foo</span> bar` collapses to `Your foobar`). `getFullText()`
+ * preserves all whitespace, which is exactly what Babel's transform needs.
+ *
+ * Algorithm (mirrors babel's cleanJSXElementLiteralChild):
+ *   - Tabs become spaces.
+ *   - Leading whitespace is stripped on every line EXCEPT the first.
+ *   - Trailing whitespace is stripped on every line EXCEPT the last.
+ *   - Whitespace-only lines are dropped.
+ *   - Non-empty lines are joined with a single space, except the last
+ *     non-empty line which is appended without a trailing separator.
+ *
+ * Result: `Your\n  bar` → "Your bar"; ` are the design\n  system.` →
+ * " are the design system." (leading space preserved).
+ */
+function normalizeJsxText(raw: string): string {
+  const lines = raw.split(/\r\n|\n|\r/);
+  let lastNonEmpty = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/[^ \t]/.test(lines[i])) lastNonEmpty = i;
+  }
+  if (lastNonEmpty < 0) return '';
+  let out = '';
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i].replace(/\t/g, ' ');
+    if (i !== 0) line = line.replace(/^[ ]+/, '');
+    if (i !== lines.length - 1) line = line.replace(/[ ]+$/, '');
+    if (!line) continue;
+    out += line;
+    if (i !== lastNonEmpty) out += ' ';
+  }
+  return out;
+}
+
 // ============================================================================
 // Component to HTML Element Mapping
 // ============================================================================
@@ -55,6 +112,21 @@ const COMPONENT_TO_HTML_MAP: Record<string, string> = {
   Link: 'a',  // next/link
 };
 
+// Internal-only marker variant of JsxElement used as a transient sentinel
+// when expanding portal trees: nodes flagged with `__portalSkip` are
+// dropped before the JSX tree is returned to consumers, so the flag
+// never surfaces in scanner output.
+type PortalSkipFlagged = { __portalSkip?: boolean };
+
+// Generic expression-evaluation result used by the prop-context resolution path.
+// The scanner threads JS literal values (string | number | boolean | null | array
+// | object) through the AST walk; consumers later branch on `typeof` / `Array.isArray`.
+// Kept as `any` so the call sites can index / access without a manual narrowing
+// dance — the alias documents intent and keeps the literal `any` keyword out of
+// the rest of the file.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ResolvedExpressionValue = any;
+
 // ============================================================================
 // Scanner Class
 // ============================================================================
@@ -66,17 +138,39 @@ export class ComponentScanner {
   // Cache for resolved imported component JSX trees
   private importedComponentCache: Map<string, { sourceFile: SourceFile; componentName: string }>;
   // Cache for array values found in source files (for .map() expansion)
-  private arrayValueCache: Map<string, any[]>;
+  private arrayValueCache: Map<string, ResolvedExpressionValue[]>;
+  // Cache: component definition node → set of prop names that the
+  // component cascades to its children via a `<*.Provider value={{ ... }}>`
+  // wrapper. Keyed by Node identity (not name) so two different `Group`
+  // functions in unrelated source files don't collide. Empty set means
+  // "analyzed, no cascade detected" — still cached to skip the body walk
+  // on subsequent invocations of the same component.
+  private providerCascadeNamesCache: WeakMap<Node, Set<string>>;
+  // Re-entry guard for `resolveLocalIdentifier` — prevents infinite recursion
+  // when a local const's initializer references another local const that
+  // (directly or transitively) references the first one. Keyed by
+  // `${filePath}:${name}` so unrelated identifiers don't block each other.
+  private localResolutionStack: Set<string> = new Set();
 
   constructor(config: ScannerConfig) {
     this.config = config;
     this.project = new Project({
       tsConfigFilePath: path.resolve(process.cwd(), 'tsconfig.json'),
       skipAddingFilesFromTsConfig: true,
+      // Scanner doesn't need full TS semantic analysis — it operates on
+      // the AST shape (`getJsxChildren`, `getOpeningElement`, etc.) and
+      // resolves imports by walking ts-morph's source files directly.
+      // Default settings load DOM / Node typings + traverse every
+      // import for type-checking, which is the lion's share of scan
+      // time. Skipping them cuts scan time substantially with no loss
+      // of scan correctness (regression suite covers the AST traversal).
+      skipFileDependencyResolution: true,
+      skipLoadingLibFiles: true,
     });
     this.iconImports = new Map();
     this.importedComponentCache = new Map();
     this.arrayValueCache = new Map();
+    this.providerCascadeNamesCache = new WeakMap();
   }
 
   /**
@@ -105,9 +199,17 @@ export class ComponentScanner {
         try {
           const analysis = this.analyzeFile(filePath);
           if (analysis) {
-            // Check for co-located story file
-            const storyPath = filePath.replace(/\.tsx$/, '.stories.tsx');
-            if (fs.existsSync(storyPath)) {
+            // Check for co-located story file — accept either `.stories.tsx`
+            // or `.stories.ts`. Storybook's `npx storybook init` for React
+            // projects emits `.stories.ts` by default; older Inkbridge
+            // versions only matched `.tsx` and silently reported "0 stories".
+            // The story parser is JSX-aware (ts-morph) and handles both.
+            const storyPathTsx = filePath.replace(/\.tsx$/, '.stories.tsx');
+            const storyPathTs = filePath.replace(/\.tsx$/, '.stories.ts');
+            const storyPath = fs.existsSync(storyPathTsx)
+              ? storyPathTsx
+              : (fs.existsSync(storyPathTs) ? storyPathTs : null);
+            if (storyPath) {
               analysis.hasStory = true;
               try {
                 analysis.stories = this.parseStories(storyPath);
@@ -202,7 +304,6 @@ export class ComponentScanner {
    */
   analyzeFile(filePath: string): ComponentAnalysis | null {
     const sourceFile = this.project.addSourceFileAtPath(filePath);
-    const fileName = path.basename(filePath, '.tsx');
 
     // Check for CVA usage first (most structured)
     const cvaAnalysis = this.analyzeCVA(sourceFile, filePath);
@@ -232,6 +333,10 @@ export class ComponentScanner {
   // ===========================================================================
 
   private analyzeCVA(sourceFile: SourceFile, filePath: string): CVAComponentAnalysis | null {
+    if (this.shouldDeferCvaToCompound(sourceFile, filePath)) {
+      return null;
+    }
+
     // Find cva() call expressions
     const cvaCalls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)
       .filter(call => call.getExpression().getText() === 'cva');
@@ -376,15 +481,20 @@ export class ComponentScanner {
   // ===========================================================================
 
   private analyzeState(sourceFile: SourceFile, filePath: string): StateComponentAnalysis | null {
-    const allClasses = this.extractAllClassesFromFile(sourceFile);
+    const rootClasses = this.getRootClassesForStateAnalysis(sourceFile, filePath);
+    const allClasses = rootClasses.length > 0
+      ? rootClasses
+      : this.extractAllClassesFromFile(sourceFile);
 
     if (allClasses.length === 0) {
       return null;
     }
 
-    // Check if any classes have state modifiers
+    // Check if any classes have an OWN state modifier (excludes
+    // `group-*:` / `peer-*:` — those are passive reactions to a
+    // parent's state, not the component's own variant axis).
     const hasStateModifiers = allClasses.some(cls =>
-      STATE_MODIFIERS.some(mod => cls.startsWith(mod))
+      OWN_STATE_MODIFIERS.some(mod => cls.startsWith(mod))
     );
 
     if (!hasStateModifiers) {
@@ -403,15 +513,19 @@ export class ComponentScanner {
     }
 
     const states: Record<string, StateInfo> = {};
+    const hasDataDisabledState = allClasses.some(cls => cls.startsWith('data-[disabled]:') || cls.startsWith('group-data-[disabled]:'));
+    const hasNativeDisabledState = allClasses.some(cls => cls.startsWith('disabled:') || cls.startsWith('peer-disabled:'));
+    const hasDataCheckedState = allClasses.some(cls => cls.startsWith('data-[checked]:') || cls.startsWith('data-[state=checked]:') || cls.startsWith('group-data-[checked]:'));
+    const hasNativeCheckedState = allClasses.some(cls => cls.startsWith('checked:'));
 
     for (const [stateName, classes] of Object.entries(groupedClasses)) {
       let trigger = '';
       if (stateName === 'hover') trigger = 'hover:';
       else if (stateName === 'focus') trigger = 'focus-visible:';
-      else if (stateName === 'disabled') trigger = 'disabled:';
+      else if (stateName === 'disabled') trigger = hasDataDisabledState ? 'data-[disabled]:' : (hasNativeDisabledState ? 'disabled:' : 'disabled:');
       else if (stateName === 'error') trigger = 'aria-invalid:';
       else if (stateName === 'active') trigger = 'active:';
-      else if (stateName === 'checked') trigger = 'data-[state=checked]:';
+      else if (stateName === 'checked') trigger = hasDataCheckedState ? 'data-[checked]:' : (hasNativeCheckedState ? 'checked:' : 'data-[checked]:');
       else if (stateName === 'open') trigger = 'data-[state=open]:';
 
       states[stateName] = {
@@ -431,6 +545,25 @@ export class ComponentScanner {
     };
   }
 
+  private getRootClassesForStateAnalysis(sourceFile: SourceFile, filePath: string): string[] {
+    const nameCandidates = this.getComponentNameCandidates(filePath);
+    let jsxTree: JsxNode | null = null;
+    for (const candidate of nameCandidates) {
+      jsxTree = this.extractComponentJsxTree(sourceFile, candidate);
+      if (jsxTree) break;
+    }
+    if (!jsxTree || jsxTree.type !== 'element') {
+      return [];
+    }
+
+    const root = jsxTree as JsxElement;
+    const className = root.props && typeof root.props.className === 'string'
+      ? root.props.className
+      : '';
+    if (!className) return [];
+    return className.split(/\s+/).filter(Boolean);
+  }
+
   private hasRootStateModifier(sourceFile: SourceFile, filePath: string): boolean {
     const nameCandidates = this.getComponentNameCandidates(filePath);
     let jsxTree: JsxNode | null = null;
@@ -447,9 +580,14 @@ export class ComponentScanner {
       ? root.props.className
       : '';
     if (!className) {
-      // Wrapper components (root tag is another component like <Hero>) should not
-      // be marked as state components from nested hover/focus classes.
-      if (/^[A-Z]/.test(root.tagName)) {
+      // Wrapper components (root tag is another component like <Hero>) and
+      // fragment wrappers (`<>...</>`, emitted as an element with empty
+      // tagName) are not state primitives — any nested hover/focus class
+      // belongs to a deeply nested element (e.g. a chip with hover styles
+      // inside a marketing section), not to the component itself. This
+      // prevents marketing molecules like HeroSection from being wrongly
+      // classified as `state` and rendered as a symbol/state matrix.
+      if (root.tagName === '' || /^[A-Z]/.test(root.tagName)) {
         return false;
       }
       // Keep state analysis for primitives that use dynamic className builders
@@ -459,7 +597,7 @@ export class ComponentScanner {
 
     const classes = className.split(/\s+/).filter(Boolean);
     for (const cls of classes) {
-      for (const modifier of STATE_MODIFIERS) {
+      for (const modifier of OWN_STATE_MODIFIERS) {
         if (cls.startsWith(modifier)) {
           return true;
         }
@@ -554,11 +692,77 @@ export class ComponentScanner {
 
   /**
    * Extract JSX tree from a function body (arrow function, function expression, or function declaration).
+   * `propsContext` is the outer-scope context. The function's own parameters
+   * (e.g. `field` in `<FormField render={({ field }) => ...} />`) shadow but
+   * the rest of the outer scope is still resolvable via the parent's
+   * propsContext — pass it through so closure variables like `errors` keep
+   * resolving inside the callback body.
+   */
+  /**
+   * Build a `propsContext` map from a story's `args` object. Args
+   * extracted from the source code are always strings (the scanner
+   * keeps `args.foo = "0.1482"`), but JSX expressions like
+   * `{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".
    */
+  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 === '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; }
+      out.set(key, raw);
+    }
+    return out;
+  }
+
+  /**
+   * Open the imported component's source file (already discovered via
+   * `relativeImports`), find its function declaration, and walk its
+   * JSX body with `argsContext` so per-story expressions like
+   * `{rewardSol.toFixed(4)}` resolve to concrete text. Returns `null`
+   * when the file can't be loaded or no exported component matches.
+   */
+  private buildStoryJsxTreeFromImportedComponent(
+    importedPath: string,
+    componentName: string,
+    argsContext: Map<string, ResolvedExpressionValue>,
+  ): JsxNode | null {
+    let sourceFile: SourceFile | null = null;
+    try {
+      sourceFile = this.project.addSourceFileAtPathIfExists(importedPath) || null;
+    } catch (_e) {
+      sourceFile = null;
+    }
+    if (!sourceFile) return null;
+
+    const localComponents = new Map<string, Node>();
+    for (const func of sourceFile.getFunctions()) {
+      const name = func.getName();
+      if (name) localComponents.set(name, func);
+    }
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        const name = decl.getName();
+        const init = decl.getInitializer();
+        if (init) localComponents.set(name, init);
+      }
+    }
+    const relativeImports = this.collectComponentImports(sourceFile);
+    const compNode = localComponents.get(componentName);
+    if (!compNode) return null;
+    return this.extractJsxTreeFromFunctionBody(compNode, relativeImports, localComponents, argsContext);
+  }
+
   private extractJsxTreeFromFunctionBody(
     funcNode: Node,
     relativeImports: Map<string, string>,
-    localComponents: Map<string, Node>
+    localComponents: Map<string, Node>,
+    propsContext: Map<string, ResolvedExpressionValue> = new Map()
   ): JsxNode | null {
     const jsxElements = funcNode.getDescendantsOfKind(SyntaxKind.JsxElement);
     const selfClosing = funcNode.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
@@ -574,7 +778,7 @@ export class ComponentScanner {
       }
     }
 
-    return this.buildJsxTree(rootJsx, localComponents, relativeImports);
+    return this.buildJsxTree(rootJsx, localComponents, relativeImports, propsContext);
   }
 
   // ===========================================================================
@@ -637,12 +841,19 @@ export class ComponentScanner {
       }
     }
 
-    // Find the meta's component name (from `component: Button`)
+    // Find the meta's component name (from `component: Button`).
+    // Unwrap `as` and `satisfies` casts — Storybook templates ship with
+    // `const meta = { ... } satisfies Meta<typeof X>`, which would
+    // otherwise hide the ObjectLiteralExpression we walk to find
+    // `component`. Missing this meant args-only stories synthesised no
+    // instance, so "simple"-typed components (e.g. a plain function
+    // component with props rendered via `args`) showed up empty on the
+    // generated design system page.
     let metaComponentName: string | undefined;
     for (const varStmt of sourceFile.getVariableStatements()) {
       for (const decl of varStmt.getDeclarationList().getDeclarations()) {
         if (decl.getName() === 'meta') {
-          const init = decl.getInitializer();
+          const init = this.unwrapStaticValueExpression(decl.getInitializer()) || decl.getInitializer();
           if (init && Node.isObjectLiteralExpression(init)) {
             const compProp = init.getProperty('component');
             if (compProp && Node.isPropertyAssignment(compProp)) {
@@ -663,7 +874,8 @@ export class ComponentScanner {
         const storyName = decl.getName();
         if (storyName === 'meta' || storyName === 'default') continue;
 
-        const init = decl.getInitializer();
+        // Unwrap `as`/`satisfies` casts (same reason as `meta` above).
+        const init = this.unwrapStaticValueExpression(decl.getInitializer()) || decl.getInitializer();
         if (!init || !Node.isObjectLiteralExpression(init)) continue;
 
         const story: StoryInfo = {
@@ -699,21 +911,70 @@ export class ComponentScanner {
               delete instance.props.children;
               story.instances.push(instance);
 
-              // For args-based stories, build jsxTree from the local component definition
-              const localCompBody = localComponents.get(metaComponentName);
-              if (localCompBody && !story.jsxTree) {
-                // Find the root JSX element within the component body
-                // (handles arrow functions like `() => (<div>...</div>)`)
-                const jsxElements = localCompBody.getDescendantsOfKind(SyntaxKind.JsxElement);
-                const selfClosingElements = localCompBody.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
-                const allJsx: Node[] = [...jsxElements, ...selfClosingElements];
-                if (allJsx.length > 0) {
-                  // Find root (fewest ancestors)
-                  let root = allJsx[0];
-                  for (const el of allJsx) {
-                    if (el.getAncestors().length < root.getAncestors().length) root = el;
+              // For args-based stories, build a story-specific jsxTree
+              // with the story's args plumbed through as `propsContext`.
+              // This lets JSX expressions like `{rewardSol.toFixed(4)}`
+              // resolve to concrete text in the rendered design system
+              // page (previously they were silently dropped, leaving the
+              // component looking empty even when args were supplied).
+              //
+              // Two source-locations to handle:
+              //   1. `localComponents.get(name)` — component defined in
+              //      the same story file (unusual, but supported).
+              //   2. The imported component's source file (typical
+              //      shadcn / project layout: `<Component>.stories.tsx`
+              //      next to `<Component>.tsx`). Resolved via
+              //      `relativeImports`.
+              if (!story.jsxTree) {
+                const argsContext = this.buildArgsPropsContext(args);
+                // Walk the args initializer AST so prop values that are
+                // arrays, objects, or identifiers referencing such
+                // (e.g. `blocks: mockBlocks`) resolve to their real
+                // structure — not the string-coerced text. Without
+                // this an args-based BlockTable story would see
+                // `blocks = "mockBlocks"` and the .map call inside the
+                // component couldn't resolve the iteration source.
+                for (const prop of argsInit.getProperties()) {
+                  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);
+                  }
+                }
+                const localCompBody = localComponents.get(metaComponentName);
+                if (localCompBody) {
+                  story.jsxTree = this.extractJsxTreeFromFunctionBody(
+                    localCompBody, relativeImports, localComponents, argsContext,
+                  ) || undefined;
+                } else {
+                  const importedPath = relativeImports.get(metaComponentName);
+                  if (importedPath) {
+                    story.jsxTree = this.buildStoryJsxTreeFromImportedComponent(
+                      importedPath, metaComponentName, argsContext,
+                    ) || undefined;
                   }
-                  story.jsxTree = this.buildJsxTree(root, localComponents, relativeImports);
+                }
+
+                // Inject `args.children` as a text node when the
+                // built tree has no element/text children of its own.
+                // Many shadcn primitives use `<Primitive {...props} />`
+                // to forward children, so the scanner sees a bare
+                // element — the children value lives in the args
+                // object but never makes it into the rendered tree.
+                // Without this an args-based `<Label>Email</Label>`
+                // story renders as an empty Label frame in Figma.
+                if (
+                  story.jsxTree
+                  && story.jsxTree.type === 'element'
+                  && (!story.jsxTree.children || story.jsxTree.children.length === 0)
+                  && typeof args.children === 'string'
+                  && args.children.length > 0
+                ) {
+                  story.jsxTree.children = [
+                    { type: 'text', content: args.children },
+                  ];
                 }
               }
             }
@@ -786,14 +1047,14 @@ export class ComponentScanner {
       story.jsxTree = this.buildJsxTree(root, localComponents, relativeImports);
 
       // Extract layout classes from root element (any tag, not just div)
-      let attrs: any[] = [];
+      let attrs: JsxAttribute[] = [];
       if (Node.isJsxElement(root)) {
         attrs = root.getOpeningElement().getDescendantsOfKind(SyntaxKind.JsxAttribute);
       } else if (Node.isJsxSelfClosingElement(root)) {
         attrs = root.getDescendantsOfKind(SyntaxKind.JsxAttribute);
       }
       const classAttr = attrs.find(a => {
-        const nameNode = (a as any).getNameNode?.();
+        const nameNode = a.getNameNode();
         return nameNode ? nameNode.getText() === 'className' : false;
       });
       if (classAttr) {
@@ -812,13 +1073,23 @@ export class ComponentScanner {
           el.getOpeningElement(),
           tagName
         );
-        const textChildren = el.getJsxChildren()
-          .filter(child => Node.isJsxText(child))
-          .map(child => decodeHtmlEntities(child.getText().trim()))
-          .filter(Boolean)
-          .join(' ');
-        if (textChildren) {
-          instance.children = textChildren;
+        const structuredChildren = this.extractStructuredChildrenFromJsxElement(
+          el,
+          localComponents,
+          relativeImports,
+          new Map()
+        );
+        if (structuredChildren.length > 0) {
+          instance.props.__jsxChildren = structuredChildren;
+        }
+        const literalChildren = this.extractLiteralChildrenText(el.getJsxChildren());
+        if (literalChildren) {
+          instance.children = literalChildren;
+        } else {
+          const contextualLabel = this.extractContextualInstanceLabel(el);
+          if (contextualLabel) {
+            instance.children = contextualLabel;
+          }
         }
         story.instances.push(instance);
       }
@@ -828,11 +1099,226 @@ export class ComponentScanner {
       const tagName = el.getTagNameNode().getText();
       if (importedComponents.has(tagName)) {
         const instance = this.extractInstanceFromSelfClosing(el, tagName);
+        const contextualLabel = this.extractContextualInstanceLabel(el);
+        if (contextualLabel) {
+          instance.children = contextualLabel;
+        }
         story.instances.push(instance);
       }
     }
   }
 
+  private extractStructuredChildrenFromJsxElement(
+    element: Node,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>,
+    propsContext: Map<string, ResolvedExpressionValue> = new Map()
+  ): JsxNode[] {
+    if (!Node.isJsxElement(element)) return [];
+
+    const out: JsxNode[] = [];
+    for (const child of element.getJsxChildren()) {
+      if (Node.isJsxElement(child) || Node.isJsxSelfClosingElement(child)) {
+        const childNode = this.buildJsxTree(child, localComponents, relativeImports, propsContext);
+        if ((childNode as JsxNode & PortalSkipFlagged).__portalSkip) continue;
+        out.push(childNode);
+        continue;
+      }
+
+      if (Node.isJsxText(child)) {
+        // JSX collapses internal whitespace (including newlines) to a single
+        // space — matching Babel / React's transform. Naive `.trim()` would
+        // leave a literal newline embedded between e.g. "design\nsystem",
+        // which the Figma plugin renders as a hard line break. Naive
+        // `.replace(/\s+/g, ' ').trim()` drops boundary whitespace and
+        // breaks inter-segment spacing for `Your <span>foo</span> bar`.
+        const text = decodeHtmlEntities(normalizeJsxText(child.getFullText()));
+        if (text) out.push({ type: 'text', content: text });
+        continue;
+      }
+
+      if (!Node.isJsxExpression(child)) continue;
+      const expr = child.getExpression();
+      if (!expr) continue;
+
+      if (Node.isBinaryExpression(expr) && expr.getOperatorToken().getText() === '??') {
+        let chosen: Node = expr.getLeft();
+        const leftValue = this.resolveExpressionValue(expr.getLeft(), propsContext);
+        if (leftValue === undefined || leftValue === null) {
+          chosen = expr.getRight();
+        }
+        if (Node.isParenthesizedExpression(chosen)) {
+          chosen = chosen.getExpression();
+        }
+        if (Node.isJsxElement(chosen) || Node.isJsxSelfClosingElement(chosen)) {
+          const chosenNode = this.buildJsxTree(chosen, localComponents, relativeImports, propsContext);
+          if (!(chosenNode as JsxNode & PortalSkipFlagged).__portalSkip) out.push(chosenNode);
+          continue;
+        }
+        const resolvedChosen = this.resolveExpressionValue(chosen, propsContext);
+        if (resolvedChosen !== undefined && resolvedChosen !== null) {
+          this.pushResolvedPropValue(out, resolvedChosen);
+          continue;
+        }
+      }
+
+      if (Node.isStringLiteral(expr) || Node.isNoSubstitutionTemplateLiteral(expr)) {
+        out.push({ type: 'text', content: decodeHtmlEntities(expr.getLiteralValue()) });
+        continue;
+      }
+
+      if (Node.isCallExpression(expr)) {
+        const callExpr = expr.getExpression();
+        if (Node.isPropertyAccessExpression(callExpr) && callExpr.getName() === 'map') {
+          const expandedChildren = this.expandMapCall(
+            expr,
+            element.getSourceFile(),
+            localComponents,
+            relativeImports,
+            propsContext
+          );
+          if (expandedChildren.length > 0) out.push(...expandedChildren);
+          continue;
+        }
+      }
+
+      if (Node.isIdentifier(expr) && propsContext.has(expr.getText())) {
+        this.pushResolvedPropValue(out, propsContext.get(expr.getText()));
+        continue;
+      }
+
+      if (Node.isPropertyAccessExpression(expr)) {
+        const objExpr = expr.getExpression();
+        const propName = expr.getName();
+        if (Node.isIdentifier(objExpr) && propsContext.has(objExpr.getText())) {
+          const obj = propsContext.get(objExpr.getText());
+          if (obj !== null && typeof obj === 'object' && !Array.isArray(obj) && propName in obj) {
+            this.pushResolvedPropValue(out, obj[propName]);
+            continue;
+          }
+        }
+      }
+
+      const resolved = this.resolveExpressionValue(expr, propsContext);
+      if (resolved !== undefined) {
+        this.pushResolvedPropValue(out, resolved);
+        continue;
+      }
+
+      const exprText = expr.getText();
+      const isConditional = exprText.includes('?') || exprText.includes('&&') || exprText.includes('||');
+      const isFunction = exprText.includes('=>') || exprText.includes('function');
+      if (exprText && !isConditional && !isFunction) {
+        out.push({ type: 'text', content: `{${exprText}}` });
+      }
+    }
+    return out;
+  }
+
+  private extractLiteralChildrenText(children: Node[]): string {
+    if (!Array.isArray(children) || children.length === 0) return '';
+    const parts: string[] = [];
+    for (const child of children) {
+      const text = this.extractLiteralTextFromJsxNode(child, { includeComponentSubtrees: false });
+      if (text) parts.push(text);
+    }
+    return parts.join(' ').replace(/\s+/g, ' ').trim();
+  }
+
+  private extractContextualInstanceLabel(node: Node): string | null {
+    const parent = node.getParent();
+    if (!parent || !Node.isJsxElement(parent)) return null;
+
+    const parentTagName = parent.getOpeningElement().getTagNameNode().getText().toLowerCase();
+    const jsxChildren = parent.getJsxChildren();
+    const parts: string[] = [];
+    let siblingComponentCount = 0;
+
+    for (const child of jsxChildren) {
+      if (child.getPos() === node.getPos() && child.getEnd() === node.getEnd()) continue;
+
+      if (Node.isJsxElement(child) || Node.isJsxSelfClosingElement(child)) {
+        const tagName = Node.isJsxElement(child)
+          ? child.getOpeningElement().getTagNameNode().getText()
+          : child.getTagNameNode().getText();
+        const isComponentTag = /^[A-Z]/.test(tagName) || tagName.includes('.');
+        if (isComponentTag) {
+          siblingComponentCount++;
+          continue;
+        }
+        const nestedText = this.extractLiteralTextFromJsxNode(child);
+        if (nestedText) parts.push(nestedText);
+        continue;
+      }
+
+      if (Node.isJsxText(child)) {
+        const text = decodeHtmlEntities(child.getText().replace(/\s+/g, ' ').trim());
+        if (text) parts.push(text);
+        continue;
+      }
+
+      if (Node.isJsxExpression(child)) {
+        const expr = child.getExpression();
+        if (!expr) continue;
+        if (Node.isStringLiteral(expr) || Node.isNoSubstitutionTemplateLiteral(expr)) {
+          const text = decodeHtmlEntities(expr.getLiteralValue().trim());
+          if (text) parts.push(text);
+          continue;
+        }
+        const resolved = this.resolveExpressionValue(expr, new Map());
+        if (resolved == null) continue;
+        const text = decodeHtmlEntities(String(resolved).replace(/\s+/g, ' ').trim());
+        if (text) parts.push(text);
+      }
+    }
+
+    const label = parts.join(' ').replace(/\s+/g, ' ').trim();
+    if (!label) return null;
+
+    if (parentTagName === 'label') return label;
+    if (siblingComponentCount === 0) return label;
+    return null;
+  }
+
+  private extractLiteralTextFromJsxNode(
+    node: Node,
+    options?: { includeComponentSubtrees?: boolean }
+  ): string {
+    if (Node.isJsxText(node)) {
+      return decodeHtmlEntities(node.getText().replace(/\s+/g, ' ').trim());
+    }
+
+    if (Node.isJsxExpression(node)) {
+      const expr = node.getExpression();
+      if (!expr) return '';
+      if (Node.isStringLiteral(expr) || Node.isNoSubstitutionTemplateLiteral(expr)) {
+        return decodeHtmlEntities(expr.getLiteralValue().replace(/\s+/g, ' ').trim());
+      }
+      const resolved = this.resolveExpressionValue(expr, new Map());
+      if (resolved == null) return '';
+      return decodeHtmlEntities(String(resolved).replace(/\s+/g, ' ').trim());
+    }
+
+    if (Node.isJsxElement(node)) {
+      const includeComponentSubtrees = options && options.includeComponentSubtrees === false ? false : true;
+      if (!includeComponentSubtrees) {
+        const tagName = node.getOpeningElement().getTagNameNode().getText();
+        if (/^[A-Z]/.test(tagName)) {
+          return '';
+        }
+      }
+      const parts: string[] = [];
+      const children = node.getJsxChildren();
+      for (const child of children) {
+        const text = this.extractLiteralTextFromJsxNode(child, options);
+        if (text) parts.push(text);
+      }
+      return parts.join(' ').replace(/\s+/g, ' ').trim();
+    }
+
+    return '';
+  }
+
   private extractDecoratorWrappers(
     decoratorsProp: Node | undefined
   ): Array<{ tagName: string; classes: string[] }> {
@@ -906,7 +1392,7 @@ export class ComponentScanner {
 
   private extractLayoutClassesFromRoot(root: Node): { tagName: string; classes: string[] } | null {
     let tagName = '';
-    let attrs: any[] = [];
+    let attrs: JsxAttribute[] = [];
     if (Node.isJsxElement(root)) {
       tagName = root.getOpeningElement().getTagNameNode().getText();
       attrs = root.getOpeningElement().getDescendantsOfKind(SyntaxKind.JsxAttribute);
@@ -916,7 +1402,7 @@ export class ComponentScanner {
     }
     if (!ComponentScanner.DECORATOR_BLOCK_TAGS.has(tagName.toLowerCase())) return null;
     const classAttr = attrs.find(a => {
-      const nameNode = (a as any).getNameNode?.();
+      const nameNode = a.getNameNode();
       return nameNode ? nameNode.getText() === 'className' : false;
     });
     if (!classAttr) return null;
@@ -933,7 +1419,11 @@ export class ComponentScanner {
 
     if (moduleSpec.startsWith('./') || moduleSpec.startsWith('../')) {
       importBasePath = path.resolve(baseDir, moduleSpec);
-    } else if (moduleSpec.startsWith('~/')) {
+    } else if (moduleSpec.startsWith('~/') || moduleSpec.startsWith('@/')) {
+      // Both ~/* and @/* are common conventions for the `src/*` path alias in
+      // Next.js projects. inkbridge uses ~/, inkbridge-starter uses @/. Treat
+      // them identically so the scanner resolves component imports in either
+      // layout.
       importBasePath = path.resolve(process.cwd(), 'src', moduleSpec.slice(2));
     }
 
@@ -993,7 +1483,8 @@ export class ComponentScanner {
     node: Node,
     localComponents: Map<string, Node>,
     relativeImports: Map<string, string> = new Map(),
-    propsContext: Map<string, any> = new Map()
+    propsContext: Map<string, ResolvedExpressionValue> = new Map(),
+    providerStack: ReadonlyArray<Record<string, ResolvedExpressionValue>> = []
   ): JsxNode {
     if (Node.isJsxElement(node)) {
       const rawTagName = node.getOpeningElement().getTagNameNode().getText();
@@ -1002,40 +1493,116 @@ export class ComponentScanner {
       const props = this.extractPropsFromNode(node.getOpeningElement(), rawTagName, propsContext).props;
       const children: JsxNode[] = [];
 
+      // If this is a component invocation whose body wraps children in
+      // `<*.Provider value={{ ... }}>`, pre-resolve the cascade values
+      // from this invocation's props and push them onto the providerStack
+      // so descendants pick them up as defaults. This statically models
+      // the React Context cascade pattern shadcn uses for `ToggleGroup`'s
+      // variant/size, `RadioGroup`'s value, etc.
+      let childProviderStack: ReadonlyArray<Record<string, ResolvedExpressionValue>> = providerStack;
+      if (/^[A-Z]/.test(rawTagName)) {
+        const cascadeNames = this.detectProviderCascadeNamesForComponent(rawTagName, localComponents, relativeImports);
+        if (cascadeNames.size > 0) {
+          const earlyEvaluatedProps = this.resolveInvocationProps(props, node.getSourceFile(), propsContext);
+          const cascadeValues: Record<string, ResolvedExpressionValue> = {};
+          let hasAny = false;
+          for (const name of cascadeNames) {
+            if (earlyEvaluatedProps[name] !== undefined) {
+              cascadeValues[name] = earlyEvaluatedProps[name];
+              hasAny = true;
+            }
+          }
+          if (hasAny) {
+            childProviderStack = providerStack.concat([cascadeValues]);
+          }
+        }
+      }
+
       for (const child of node.getJsxChildren()) {
         if (Node.isJsxElement(child) || Node.isJsxSelfClosingElement(child)) {
-          const childNode = this.buildJsxTree(child, localComponents, relativeImports, propsContext);
-          if ((childNode as any).__portalSkip) continue;
-          children.push(childNode);
+          const childNode = this.buildJsxTree(child, localComponents, relativeImports, propsContext, childProviderStack);
+          if ((childNode as JsxNode & PortalSkipFlagged).__portalSkip) continue;
+          this.pushFlatteningTransparentProvider(children, childNode);
         } else if (Node.isJsxText(child)) {
-          const text = decodeHtmlEntities(child.getText().trim());
+          const text = decodeHtmlEntities(normalizeJsxText(child.getFullText()));
           if (text) {
             children.push({ type: 'text', content: text });
           }
         } else if (Node.isJsxExpression(child)) {
           const expr = child.getExpression();
-          if (expr && Node.isStringLiteral(expr)) {
+          if (expr && Node.isBinaryExpression(expr)) {
+            const op = expr.getOperatorToken().getText();
+            if (op === '??') {
+              const leftValue = this.resolveExpressionValue(expr.getLeft(), propsContext);
+              const chosen = (leftValue === undefined || leftValue === null)
+                ? expr.getRight()
+                : expr.getLeft();
+              this.pushChosenJsxBranch(chosen, children, localComponents, relativeImports, propsContext);
+            } else if (op === '&&') {
+              // Short-circuit: render the right side only when the left is
+              // statically truthy. If the left can't be resolved, skip — the
+              // design-system render shouldn't speculate about runtime state.
+              const leftValue = this.resolveExpressionValue(expr.getLeft(), propsContext);
+              if (this.isExpressionTruthy(leftValue)) {
+                this.pushChosenJsxBranch(expr.getRight(), children, localComponents, relativeImports, propsContext);
+              }
+            } else if (op === '||') {
+              const leftValue = this.resolveExpressionValue(expr.getLeft(), propsContext);
+              if (this.isExpressionTruthy(leftValue)) {
+                this.pushChosenJsxBranch(expr.getLeft(), children, localComponents, relativeImports, propsContext);
+              } else if (leftValue !== undefined) {
+                this.pushChosenJsxBranch(expr.getRight(), children, localComponents, relativeImports, propsContext);
+              }
+              // Unresolvable left → skip
+            }
+          } else if (expr && Node.isConditionalExpression(expr)) {
+            // Ternary `cond ? a : b` — pick a branch when the condition is
+            // statically resolvable. Same conservative policy as `&&`/`||`:
+            // unresolvable condition skips both branches.
+            const condValue = this.resolveExpressionValue(expr.getCondition(), propsContext);
+            if (condValue !== undefined) {
+              const chosen = this.isExpressionTruthy(condValue)
+                ? expr.getWhenTrue()
+                : expr.getWhenFalse();
+              this.pushChosenJsxBranch(chosen, children, localComponents, relativeImports, propsContext);
+            }
+          } else if (expr && Node.isStringLiteral(expr)) {
             children.push({ type: 'text', content: expr.getLiteralValue() });
           } else if (expr && Node.isCallExpression(expr)) {
-            // Check if this is a .map() call
+            // .map() calls expand into multiple children; every other
+            // CallExpression (e.g. `{rewardSol.toFixed(4)}`) is resolved
+            // via `resolveExpressionValue` which knows how to evaluate
+            // common Number/String methods against the prop values in
+            // `propsContext`. Without this fallback the expression was
+            // silently dropped and args-based stories rendered the
+            // component shell with the runtime values missing.
             const callExpr = expr.getExpression();
             if (Node.isPropertyAccessExpression(callExpr) && callExpr.getName() === 'map') {
-              // Try to expand the .map() call, passing propsContext for array resolution
               const expandedChildren = this.expandMapCall(expr, node.getSourceFile(), localComponents, relativeImports, propsContext);
               if (expandedChildren.length > 0) {
                 children.push(...expandedChildren);
               }
+            } else {
+              const resolved = this.resolveExpressionValue(expr, propsContext);
+              if (resolved !== undefined && resolved !== null) {
+                this.pushResolvedPropValue(children, resolved);
+              }
             }
           } else if (expr && Node.isIdentifier(expr) && propsContext.has(expr.getText())) {
             this.pushResolvedPropValue(children, propsContext.get(expr.getText()));
           } else if (expr && Node.isIdentifier(expr)) {
-            // Try to resolve as a module-level const string (e.g. const LONG = "...")
-            const varDecl = node.getSourceFile().getVariableDeclaration(expr.getText());
-            if (varDecl) {
-              const init = varDecl.getInitializer();
-              if (init && Node.isStringLiteral(init)) {
-                children.push({ type: 'text', content: init.getLiteralValue() });
-              }
+            // Delegate to resolveExpressionValue so function-body-local `const`
+            // declarations (e.g. `const statusText = sourceLabel === "db" ? ...`)
+            // resolve the same way they do for className identifiers. Without
+            // this, a JSX text child like `<span>{statusText}</span>` falls
+            // through to the "unresolved" branch and renders nothing — even
+            // when the local const's initializer would resolve fine against
+            // the current propsContext. Same scope-walk fix as the className
+            // path; the bug only shows on JSX *children* because the children
+            // pipeline used a custom (module-level-only) lookup here.
+            const resolved = this.resolveExpressionValue(expr, propsContext);
+            if (resolved !== undefined && resolved !== null) {
+              this.pushResolvedPropValue(children, resolved);
             }
           } else if (expr && Node.isPropertyAccessExpression(expr)) {
             // Resolve {plan.name} style expressions when `plan` is an object in propsContext
@@ -1060,12 +1627,87 @@ export class ComponentScanner {
         }
       }
 
+      // Selection-match pressed-state injection: when an element has a
+      // `defaultValue` (or `value`) prop containing an array or string,
+      // mark each child whose own `value` prop matches with
+      // `defaultPressed="true"`. The variant engine's data-pressed alias
+      // then activates `data-[pressed]:*` CSS at render time. Mirrors
+      // base-ui's ToggleGroup / RadioGroup runtime behaviour, which
+      // compares the group's value(s) against each item's value and
+      // pushes `data-pressed`/`data-checked` to the matching items.
+      //
+      // Only fires when defaultValue/value is a parsed array or string —
+      // i.e. the scanner could statically resolve the prop. Dynamic
+      // values stay unhandled (acceptable for design-system previews).
+      const selectionDefault =
+        (props as Record<string, unknown>).defaultValue
+        ?? (props as Record<string, unknown>).value;
+      if (selectionDefault !== undefined && selectionDefault !== null) {
+        const acceptableArray = Array.isArray(selectionDefault)
+          ? selectionDefault.map((v) => String(v))
+          : (typeof selectionDefault === 'string' || typeof selectionDefault === 'number')
+            ? [String(selectionDefault)]
+            : null;
+        if (acceptableArray && acceptableArray.length > 0) {
+          for (let i = 0; i < children.length; i++) {
+            const child = children[i];
+            if (!child || child.type !== 'element' || !child.props) continue;
+            const childValue = (child.props as Record<string, unknown>).value;
+            if (childValue === undefined || childValue === null) continue;
+            if (acceptableArray.indexOf(String(childValue)) === -1) continue;
+            if (child.props.defaultPressed !== undefined || child.props['data-pressed'] !== undefined) continue;
+            child.props.defaultPressed = 'true';
+          }
+        }
+      }
+
+      // React Context.Provider is a non-rendering wrapper (it only sets a
+      // context value). Unwrap to its single child so the plugin doesn't
+      // emit an empty frame around the actual content. Common after
+      // expanding shadcn primitives like <FormItem> →
+      // <FormItemContext.Provider><div/></FormItemContext.Provider>.
+      if (rawTagName.endsWith('.Provider') && children.length === 1 && children[0].type === 'element') {
+        return children[0];
+      }
+
       if (/^[A-Z]/.test(rawTagName)) {
         const evaluatedProps = this.resolveInvocationProps(props, node.getSourceFile(), propsContext);
+        // Apply provider-cascade defaults: for each provider value pushed
+        // by an ancestor invocation (see childProviderStack assembly
+        // above), inject any prop the invocation hasn't already set. This
+        // is the static analog of React's `useContext` — at runtime
+        // descendants would read the context value; here we propagate it
+        // through the expansion's resolved props instead.
+        if (providerStack.length > 0) {
+          for (let i = 0; i < providerStack.length; i++) {
+            const provider = providerStack[i];
+            for (const key in provider) {
+              if (!Object.prototype.hasOwnProperty.call(provider, key)) continue;
+              if (evaluatedProps[key] === undefined) {
+                evaluatedProps[key] = provider[key];
+              }
+            }
+          }
+        }
         if (children.length > 0) {
           evaluatedProps.children = children;
         }
 
+        // Pre-expansion: a callback-style render prop (e.g. shadcn's <FormField
+        // render={({ field }) => <FormItem/>}>) becomes invisible after
+        // expansion because the wrapper expands to a Controller-like internal
+        // tree that has no Trigger leaf for attachRenderPropToExpanded to fill.
+        // Use the callback's JSX directly instead.
+        const callbackContent = this.extractRenderPropCallbackJsxNode(
+          node.getOpeningElement(),
+          localComponents,
+          relativeImports,
+          propsContext
+        );
+        if (callbackContent) {
+          return callbackContent;
+        }
+
         const localDef = localComponents.get(rawTagName);
         if (localDef) {
           const expandedLocal = this.expandLocalComponentWithProps(localDef, evaluatedProps, localComponents, relativeImports);
@@ -1075,26 +1717,89 @@ export class ComponentScanner {
         }
 
         const importedFilePath = relativeImports.get(rawTagName);
-        const SKIP_EXPANSION_MAIN = ['Skeleton', 'SkeletonText'];
+        const SKIP_EXPANSION_MAIN = ['Skeleton'];
         if (importedFilePath && !SKIP_EXPANSION_MAIN.includes(rawTagName)) {
-          const resolvedProps = new Map<string, any>();
+          const resolvedProps = new Map<string, ResolvedExpressionValue>();
           for (const [key, value] of Object.entries(evaluatedProps)) {
             resolvedProps.set(key, value);
           }
           const expandedImported = this.expandImportedComponent(rawTagName, importedFilePath, relativeImports, resolvedProps);
           if (expandedImported) {
             if (this.isPortalRootedNode(expandedImported)) {
-              return { type: 'element', tagName: '__portal_skip__', isComponent: false, props: {}, children: [], __portalSkip: true } as any;
+              // Unwrap portal: return the content node(s) inside the portal (skipping overlays).
+              // This allows stories to use <SheetContent>, <DialogContent> etc. directly.
+              // Nodes are marked __fromPortal so the plugin can filter them in trigger-only stories.
+              const contentNodes = this.extractPortalContentNodes(expandedImported);
+              if (contentNodes.length > 0) {
+                const contentNode: JsxElement = contentNodes.length === 1
+                  ? contentNodes[0] as JsxElement
+                  : { type: 'element', tagName: 'div', isComponent: false, props: {}, children: contentNodes };
+                // Strip portal-positioning classes before marking — fixed/translate/z-index/
+                // animate etc. are meaningless in Figma and cause width/layout bugs.
+                const cleanedClassName = this.stripPortalPositioningClasses(contentNode.props?.className || '');
+                contentNode.props = Object.assign({}, contentNode.props || {}, {
+                  __fromPortal: true,
+                  className: cleanedClassName,
+                });
+                return contentNode as JsxNode;
+              }
+              return { type: 'element', tagName: '__portal_skip__', isComponent: false, props: {}, children: [], __portalSkip: true } as JsxElement & PortalSkipFlagged;
             }
             if (!this.isUnresolvedExpandedComponent(expandedImported, localComponents, relativeImports)) {
+              this.attachRenderPropToExpanded(
+                expandedImported,
+                node.getOpeningElement(),
+                localComponents,
+                relativeImports,
+                propsContext
+              );
               return expandedImported;
             }
+            // Expansion produced an unresolved wrapper (e.g. <Slot> from
+            // @radix-ui — used internally by shadcn's <FormControl>). If the
+            // user wrapped exactly one child and added no visual className,
+            // the wrapper is a pass-through. Drop it and return the child so
+            // the inner primitive (e.g. <Input>) renders normally.
+            if (this.isPassThroughInvocation(props, children)) {
+              return children[0];
+            }
+            // Otherwise: the expansion may still contain useful content
+            // beneath an unresolved root wrapper (e.g. <Form><form>...).
+            // Walk down through the unresolved single-child wrappers and
+            // use the resolved inner node so the story tree gets the real
+            // content instead of the bare `<Component/>` placeholder.
+            const innerImported = this.unwrapUnresolvedSingleChildRoots(
+              expandedImported,
+              localComponents,
+              relativeImports
+            );
+            if (innerImported && innerImported !== expandedImported) {
+              this.attachRenderPropToExpanded(
+                innerImported,
+                node.getOpeningElement(),
+                localComponents,
+                relativeImports,
+                propsContext
+              );
+              return innerImported;
+            }
           }
         }
       }
 
-      const outputProps = { ...props } as Record<string, any>;
+      if (children.length === 0) {
+        const renderChild = this.extractRenderPropJsxNode(
+          node.getOpeningElement(),
+          localComponents,
+          relativeImports,
+          propsContext
+        );
+        if (renderChild) children.push(renderChild);
+      }
+
+      const outputProps = { ...props } as Record<string, ResolvedExpressionValue>;
       delete outputProps.children;
+      delete outputProps.render;
       return {
         type: 'element',
         tagName,
@@ -1108,11 +1813,37 @@ export class ComponentScanner {
       const tagName = COMPONENT_TO_HTML_MAP[rawTagName] || rawTagName;
       const props = this.extractPropsFromNode(node, rawTagName, propsContext).props;
       const evaluatedProps = this.resolveInvocationProps(props, node.getSourceFile(), propsContext);
+      // Apply provider-cascade defaults: see the JsxElement branch above
+      // for the full rationale. Self-closing elements are the common
+      // shape for cascade-receiving items (e.g. `<ToggleGroupItem />`
+      // inside a `<ToggleGroup variant="outline">`).
+      if (providerStack.length > 0) {
+        for (let i = 0; i < providerStack.length; i++) {
+          const provider = providerStack[i];
+          for (const key in provider) {
+            if (!Object.prototype.hasOwnProperty.call(provider, key)) continue;
+            if (evaluatedProps[key] === undefined) {
+              evaluatedProps[key] = provider[key];
+            }
+          }
+        }
+      }
       const children: JsxNode[] = [];
       if (Object.prototype.hasOwnProperty.call(evaluatedProps, 'children')) {
         this.pushResolvedPropValue(children, evaluatedProps.children);
       }
 
+      // Pre-expansion: see JsxElement branch above for rationale.
+      const callbackContent = this.extractRenderPropCallbackJsxNode(
+        node,
+        localComponents,
+        relativeImports,
+        propsContext
+      );
+      if (callbackContent) {
+        return callbackContent;
+      }
+
       // Check if this is a local component that should be expanded
       const localDef = localComponents.get(rawTagName);
       if (localDef) {
@@ -1125,10 +1856,10 @@ export class ComponentScanner {
       // Check if this is an imported component from a relative path
       // Skip expansion for simple components that the ui-builder handles directly
       // (e.g., Skeleton uses clsx with props that we can't statically evaluate)
-      const SKIP_EXPANSION_MAIN = ['Skeleton', 'SkeletonText'];
+      const SKIP_EXPANSION_MAIN = ['Skeleton'];
       const importedFilePath = relativeImports.get(rawTagName);
       if (importedFilePath && !SKIP_EXPANSION_MAIN.includes(rawTagName)) {
-        const resolvedProps = new Map<string, any>();
+        const resolvedProps = new Map<string, ResolvedExpressionValue>();
         for (const [key, value] of Object.entries(evaluatedProps)) {
           resolvedProps.set(key, value);
         }
@@ -1136,16 +1867,70 @@ export class ComponentScanner {
         const expandedJsx = this.expandImportedComponent(rawTagName, importedFilePath, relativeImports, resolvedProps);
         if (expandedJsx) {
           if (this.isPortalRootedNode(expandedJsx)) {
-            return { type: 'element', tagName: '__portal_skip__', isComponent: false, props: {}, children: [], __portalSkip: true } as any;
+            const contentNodes = this.extractPortalContentNodes(expandedJsx);
+            if (contentNodes.length > 0) {
+              const contentNode: JsxElement = contentNodes.length === 1
+                ? contentNodes[0] as JsxElement
+                : { type: 'element', tagName: 'div', isComponent: false, props: {}, children: contentNodes };
+              const cleanedClassName = this.stripPortalPositioningClasses(contentNode.props?.className || '');
+              contentNode.props = Object.assign({}, contentNode.props || {}, {
+                __fromPortal: true,
+                className: cleanedClassName,
+              });
+              return contentNode as JsxNode;
+            }
+            return { type: 'element', tagName: '__portal_skip__', isComponent: false, props: {}, children: [], __portalSkip: true } as JsxElement & PortalSkipFlagged;
           }
           if (!this.isUnresolvedExpandedComponent(expandedJsx, localComponents, relativeImports)) {
+            // Base UI asChild pattern: the outer JSX may have `render={<Button/>}`
+            // which expandImportedComponent loses through the {...props} spread
+            // (extractPropsFromNode captured `render` as a text string). Pull
+            // the JSX value off the outer AST and inject it as the deepest
+            // empty trigger's child so the trigger content shows in Figma.
+            this.attachRenderPropToExpanded(
+              expandedJsx,
+              node,
+              localComponents,
+              relativeImports,
+              propsContext
+            );
             return expandedJsx;
           }
+          // Pass-through wrapper unwrap: see JsxElement branch above.
+          if (this.isPassThroughInvocation(props, children)) {
+            return children[0];
+          }
+          const innerSelfClosing = this.unwrapUnresolvedSingleChildRoots(
+            expandedJsx,
+            localComponents,
+            relativeImports
+          );
+          if (innerSelfClosing && innerSelfClosing !== expandedJsx) {
+            this.attachRenderPropToExpanded(
+              innerSelfClosing,
+              node,
+              localComponents,
+              relativeImports,
+              propsContext
+            );
+            return innerSelfClosing;
+          }
         }
       }
 
-      const outputProps = { ...props } as Record<string, any>;
+      if (children.length === 0) {
+        const renderChild = this.extractRenderPropJsxNode(
+          node,
+          localComponents,
+          relativeImports,
+          propsContext
+        );
+        if (renderChild) children.push(renderChild);
+      }
+
+      const outputProps = { ...props } as Record<string, ResolvedExpressionValue>;
       delete outputProps.children;
+      delete outputProps.render;
       return {
         type: 'element',
         tagName,
@@ -1153,12 +1938,176 @@ export class ComponentScanner {
         props: outputProps,
         children,
       };
+    } else if (Node.isJsxFragment(node)) {
+      // `<>...</>` — no wrapper element. Emit an element with an empty tagName
+      // so the NodeIR converter collapses it into a transparent fragment node.
+      const children: JsxNode[] = [];
+      for (const child of node.getJsxChildren()) {
+        if (Node.isJsxElement(child) || Node.isJsxSelfClosingElement(child) || Node.isJsxFragment(child)) {
+          const childNode = this.buildJsxTree(child, localComponents, relativeImports, propsContext);
+          if ((childNode as JsxNode & PortalSkipFlagged).__portalSkip) continue;
+          children.push(childNode);
+        } else if (Node.isJsxText(child)) {
+          const text = decodeHtmlEntities(normalizeJsxText(child.getFullText()));
+          if (text) children.push({ type: 'text', content: text });
+        } else if (Node.isJsxExpression(child)) {
+          const expr = child.getExpression();
+          if (expr && Node.isCallExpression(expr)) {
+            const mapped = this.expandMapCall(expr, node.getSourceFile(), localComponents, relativeImports, propsContext);
+            for (const m of mapped) children.push(m);
+          } else if (expr) {
+            const resolved = this.resolveExpressionValue(expr, propsContext);
+            if (resolved !== undefined && resolved !== null) {
+              this.pushResolvedPropValue(children, resolved);
+            }
+          }
+        }
+      }
+      return {
+        type: 'element',
+        tagName: '',
+        isComponent: false,
+        props: {},
+        children,
+      };
     }
 
     // Fallback for unexpected node types
     return { type: 'text', content: '' };
   }
 
+  /**
+   * Walk an expanded JSX tree and inject the outer `render` prop's JSX
+   * value into the first empty trigger-like descendant. Used when the outer
+   * call site has `render={<Button/>}` but expansion flattens it away through
+   * {...props} spread — extractPropsFromNode can only capture the raw source
+   * text, so we parse the JSX off the original AST and graft it onto the
+   * expansion result.
+   */
+  private attachRenderPropToExpanded(
+    expanded: JsxNode,
+    outerAstNode: Node,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>,
+    propsContext: Map<string, ResolvedExpressionValue>
+  ): void {
+    const renderChild = this.extractRenderPropJsxNode(
+      outerAstNode,
+      localComponents,
+      relativeImports,
+      propsContext
+    );
+    if (!renderChild) return;
+    const target = this.findFirstEmptyTriggerNode(expanded);
+    if (target) {
+      target.children = [renderChild];
+      if (target.props) {
+        delete target.props.render;
+      }
+    }
+  }
+
+  private findFirstEmptyTriggerNode(node: JsxNode): JsxElement | null {
+    if (!node || node.type !== 'element') return null;
+    const el = node;
+    const tag = String(el.tagName || '').toLowerCase();
+    if (tag.endsWith('trigger') && (!el.children || el.children.length === 0)) {
+      return el;
+    }
+    if (Array.isArray(el.children)) {
+      for (let i = 0; i < el.children.length; i++) {
+        const found = this.findFirstEmptyTriggerNode(el.children[i]);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Like `extractRenderPropJsxNode` but only matches *callback*-style render
+   * props (arrow functions / function expressions). Used as a pre-expansion
+   * guard: if a component has a callback render prop, expansion of the
+   * wrapper would discard the render content (see <FormField> from
+   * react-hook-form: it expands to `<FormFieldContext.Provider><Controller/></...>`,
+   * and `attachRenderPropToExpanded` only injects literals into Trigger leaves).
+   * Returning the callback's JSX directly skips expansion and matches React's
+   * actual visual output.
+   */
+  private extractRenderPropCallbackJsxNode(
+    openingOrSelfClosing: Node,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>,
+    propsContext: Map<string, ResolvedExpressionValue>
+  ): JsxNode | null {
+    const attrs =
+      Node.isJsxOpeningElement(openingOrSelfClosing) || Node.isJsxSelfClosingElement(openingOrSelfClosing)
+        ? openingOrSelfClosing.getAttributes()
+        : [];
+    for (const attr of attrs) {
+      if (!Node.isJsxAttribute(attr)) continue;
+      const nameNode = attr.getNameNode();
+      if (!nameNode || nameNode.getText() !== 'render') continue;
+      const init = attr.getInitializer();
+      if (!init || !Node.isJsxExpression(init)) continue;
+      let expr = init.getExpression();
+      if (!expr) continue;
+      if (Node.isParenthesizedExpression(expr)) expr = expr.getExpression();
+      if (Node.isArrowFunction(expr) || Node.isFunctionExpression(expr)) {
+        const built = this.extractJsxTreeFromFunctionBody(expr, relativeImports, localComponents, propsContext);
+        if (built && !(built as JsxNode & PortalSkipFlagged).__portalSkip) return built;
+      }
+      return null;
+    }
+    return null;
+  }
+
+  /**
+   * Components can expose a `render` prop in two shapes:
+   *
+   * 1. JSX literal (Base UI / Radix asChild pattern):
+   *      <PopoverPrimitive.Trigger render={<Button>Open</Button>} />
+   *
+   * 2. Render-prop callback (react-hook-form's <FormField>, headless UI patterns):
+   *      <FormField render={({ field }) => (<FormItem>...</FormItem>)} />
+   *
+   * Extract the inner JSX in either case so the plugin can render the wrapper's
+   * actual content. For callbacks the inner-scope arguments (e.g. `field`) are
+   * not resolvable, so the JSX is rendered with whatever literal props it has.
+   */
+  private extractRenderPropJsxNode(
+    openingOrSelfClosing: Node,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>,
+    propsContext: Map<string, ResolvedExpressionValue>
+  ): JsxNode | null {
+    const attrs =
+      Node.isJsxOpeningElement(openingOrSelfClosing) || Node.isJsxSelfClosingElement(openingOrSelfClosing)
+        ? openingOrSelfClosing.getAttributes()
+        : [];
+    for (const attr of attrs) {
+      if (!Node.isJsxAttribute(attr)) continue;
+      const nameNode = attr.getNameNode();
+      if (!nameNode || nameNode.getText() !== 'render') continue;
+      const init = attr.getInitializer();
+      if (!init || !Node.isJsxExpression(init)) continue;
+      let expr = init.getExpression();
+      if (!expr) continue;
+      if (Node.isParenthesizedExpression(expr)) expr = expr.getExpression();
+      if (Node.isJsxElement(expr) || Node.isJsxSelfClosingElement(expr) || Node.isJsxFragment(expr)) {
+        const built = this.buildJsxTree(expr, localComponents, relativeImports, propsContext);
+        if (built && !(built as JsxNode & PortalSkipFlagged).__portalSkip) return built;
+        return null;
+      }
+      if (Node.isArrowFunction(expr) || Node.isFunctionExpression(expr)) {
+        const built = this.extractJsxTreeFromFunctionBody(expr, relativeImports, localComponents, propsContext);
+        if (built && !(built as JsxNode & PortalSkipFlagged).__portalSkip) return built;
+        return null;
+      }
+      return null;
+    }
+    return null;
+  }
+
   private cloneJsxNode(node: JsxNode): JsxNode {
     if (node.type === 'text') {
       return { type: 'text', content: (node as JsxText).content };
@@ -1177,7 +2126,7 @@ export class ComponentScanner {
     };
   }
 
-  private pushResolvedPropValue(children: JsxNode[], value: any): void {
+  private pushResolvedPropValue(children: JsxNode[], value: ResolvedExpressionValue): void {
     if (value == null || value === '') return;
     if (Array.isArray(value)) {
       for (let i = 0; i < value.length; i++) {
@@ -1201,9 +2150,9 @@ export class ComponentScanner {
   private resolveInvocationProps(
     props: Record<string, string>,
     sourceFile: SourceFile,
-    propsContext: Map<string, any>
-  ): Record<string, any> {
-    const resolved: Record<string, any> = {};
+    propsContext: Map<string, ResolvedExpressionValue>
+  ): Record<string, ResolvedExpressionValue> {
+    const resolved: Record<string, ResolvedExpressionValue> = {};
     for (const [propName, propValue] of Object.entries(props)) {
       if (typeof propValue !== 'string') {
         resolved[propName] = propValue;
@@ -1231,8 +2180,18 @@ export class ComponentScanner {
    * For a normal param (`item`): adds `item → itemValue` so `item.selected` resolves.
    * For destructured params (`__destructured__`): adds each key directly.
    */
-  private buildItemPropsContext(itemParamName: string, itemValue: any): Map<string, any> {
-    const ctx = new Map<string, any>();
+  private buildItemPropsContext(
+    itemParamName: string,
+    itemValue: ResolvedExpressionValue,
+    extraContext?: Map<string, ResolvedExpressionValue>
+  ): Map<string, ResolvedExpressionValue> {
+    const ctx = new Map<string, ResolvedExpressionValue>();
+    // Start with any outer context (propsContext from map callbacks, etc.) so
+    // the callback body can resolve identifiers that aren't the item itself
+    // (e.g. `widths`, `WIDTH_CLASSNAMES`, the iteration index).
+    if (extraContext) {
+      for (const [k, v] of extraContext) ctx.set(k, v);
+    }
     if (!itemParamName || itemValue == null) return ctx;
     if (itemParamName === '__destructured__') {
       if (typeof itemValue === 'object') {
@@ -1245,13 +2204,13 @@ export class ComponentScanner {
   }
 
   private resolveSubstitutionProps(
-    props: Record<string, string>,
+    props: Record<string, ResolvedExpressionValue>,
     itemParamName: string,
-    itemValue: any
-  ): Record<string, any> {
-    const resolved: Record<string, any> = {};
+    itemValue: ResolvedExpressionValue
+  ): Record<string, ResolvedExpressionValue> {
+    const resolved: Record<string, ResolvedExpressionValue> = {};
     for (const [propName, propValue] of Object.entries(props)) {
-      if (propValue.startsWith(itemParamName + '.')) {
+      if (typeof propValue === 'string' && propValue.startsWith(itemParamName + '.')) {
         const propPath = propValue.slice(itemParamName.length + 1);
         resolved[propName] = itemValue && typeof itemValue === 'object'
           ? itemValue[propPath]
@@ -1304,7 +2263,7 @@ export class ComponentScanner {
     sourceFile: SourceFile,
     localComponents: Map<string, Node>,
     relativeImports: Map<string, string>,
-    propsContext: Map<string, any> = new Map()
+    propsContext: Map<string, ResolvedExpressionValue> = new Map()
   ): JsxNode[] {
     const results: JsxNode[] = [];
 
@@ -1315,9 +2274,55 @@ export class ComponentScanner {
       const propAccess = callExpr.getExpression();
       if (!Node.isPropertyAccessExpression(propAccess)) return results;
 
-      // Get the array expression (may be a variable name or an inline array literal)
-      const arrayExpr = propAccess.getExpression();
-      const arrayName = Node.isArrayLiteralExpression(arrayExpr) ? '__inline__' : arrayExpr.getText();
+      // Get the array expression (may be a variable name or an inline array literal).
+      // Unwrap ParenthesizedExpression and AsExpression so patterns like
+      // `(["a", "b"] as const).map(...)` resolve to the inline array literal.
+      let arrayExpr: Node = propAccess.getExpression();
+      while (
+        Node.isParenthesizedExpression(arrayExpr)
+        || Node.isAsExpression(arrayExpr)
+        || Node.isTypeAssertion(arrayExpr)
+        || Node.isNonNullExpression(arrayExpr)
+      ) {
+        arrayExpr = arrayExpr.getExpression();
+      }
+
+      // Detect `Array.from({ length: N })` as a synthetic array source. Used
+      // by patterns like `Array.from({length: lines}).map((_, i) => <Row>)`.
+      // We only care about the length; items are placeholder nulls and the
+      // callback must derive values from `index` or surrounding propsContext.
+      let syntheticArrayLength: number | null = null;
+      if (Node.isCallExpression(arrayExpr)) {
+        const arrayFromCallee = arrayExpr.getExpression();
+        if (
+          Node.isPropertyAccessExpression(arrayFromCallee)
+          && arrayFromCallee.getExpression().getText() === 'Array'
+          && arrayFromCallee.getName() === 'from'
+        ) {
+          const fromArgs = arrayExpr.getArguments();
+          const firstArg = fromArgs[0];
+          if (firstArg && Node.isObjectLiteralExpression(firstArg)) {
+            for (const prop of firstArg.getProperties()) {
+              if (!Node.isPropertyAssignment(prop)) continue;
+              const key = prop.getName();
+              if (key !== 'length') continue;
+              const init = prop.getInitializer();
+              if (!init) continue;
+              const resolved = this.resolveExpressionValue(init, propsContext);
+              const num = typeof resolved === 'number'
+                ? resolved
+                : (typeof resolved === 'string' && /^\d+$/.test(resolved) ? parseInt(resolved, 10) : NaN);
+              if (Number.isFinite(num) && num >= 0) {
+                syntheticArrayLength = Math.min(num as number, 7);
+              }
+            }
+          }
+        }
+      }
+
+      const arrayName = Node.isArrayLiteralExpression(arrayExpr)
+        ? '__inline__'
+        : (syntheticArrayLength != null ? '__synthetic__' : arrayExpr.getText());
 
       // Get the map callback function
       const args = callExpr.getArguments();
@@ -1349,6 +2354,17 @@ export class ComponentScanner {
         itemParamName = params[0].getName();
       }
 
+      // Second parameter is the iteration index (`(item, index)` or `(_, i)`).
+      // Pattern is common for callbacks that derive per-iteration values from
+      // the index — e.g. `widths[index % widths.length]` in SkeletonText.
+      let indexParamName: string | null = null;
+      if (params.length >= 2) {
+        const secondNameNode = params[1].getNameNode();
+        if (secondNameNode && Node.isIdentifier(secondNameNode)) {
+          indexParamName = secondNameNode.getText();
+        }
+      }
+
       // Find the JSX in the callback body
       const body = callback.getBody();
       if (!body) return results;
@@ -1380,11 +2396,36 @@ export class ComponentScanner {
 
       if (!callbackJsx) return results;
 
+      // Collect `const X = <expr>;` declarations in the callback body so they
+      // are available as additional context per iteration (e.g.
+      // `const width = widths[index % widths.length];`). The initializers are
+      // re-evaluated per iteration because they often depend on `index`.
+      const callbackConstDecls: { name: string; initializer: Node }[] = [];
+      if (Node.isBlock(body)) {
+        const statements = body.getStatements();
+        for (const stmt of statements) {
+          if (!Node.isVariableStatement(stmt)) continue;
+          const declList = stmt.getDeclarationList();
+          for (const decl of declList.getDeclarations()) {
+            const nameNode = decl.getNameNode();
+            if (!Node.isIdentifier(nameNode)) continue;
+            const init = decl.getInitializer();
+            if (!init) continue;
+            callbackConstDecls.push({ name: nameNode.getText(), initializer: init });
+          }
+        }
+      }
+
       // Find the array's value - inline literal first, then propsContext, then source file
-      let arrayValue: any[] | null = null;
+      let arrayValue: ResolvedExpressionValue[] | null = null;
+
+      // Synthetic array from `Array.from({length: N})` — items are placeholders.
+      if (arrayName === '__synthetic__' && syntheticArrayLength != null) {
+        arrayValue = new Array(syntheticArrayLength).fill(null);
+      }
 
       // Inline array literal: [{ ... }, ...].map(...)
-      if (arrayName === '__inline__' && Node.isArrayLiteralExpression(arrayExpr)) {
+      if (!arrayValue && arrayName === '__inline__' && Node.isArrayLiteralExpression(arrayExpr)) {
         arrayValue = this.parseArrayLiteral(arrayExpr);
       }
 
@@ -1431,18 +2472,41 @@ export class ComponentScanner {
         let item = arrayValue[i];
         // When the callback uses destructuring, flatten the item to use local names as keys
         if (destructuringBindings && typeof item === 'object' && item !== null) {
-          const flatItem: Record<string, any> = {};
+          const flatItem: Record<string, ResolvedExpressionValue> = {};
           for (const [localName, sourceKey] of destructuringBindings) {
             flatItem[localName] = item[sourceKey];
           }
           item = flatItem;
         }
+        // Carry the outer propsContext plus the iteration index through the
+        // recursion so dynamic per-line expressions (e.g. `widths[index % N]`,
+        // `WIDTH_CLASSNAMES[width]`) can resolve against the caller's props.
+        const iterationContext = new Map<string, ResolvedExpressionValue>(propsContext);
+        if (indexParamName) {
+          iterationContext.set(indexParamName, i);
+        }
+        // Include the callback's local `const` declarations (e.g.
+        // `const width = widths[index % widths.length];`) so the JSX body
+        // can reference them. Evaluated per-iteration because they usually
+        // depend on `index` or the current item.
+        if (itemParamName && itemParamName !== '__destructured__' && item != null) {
+          iterationContext.set(itemParamName, item);
+        } else if (itemParamName === '__destructured__' && typeof item === 'object' && item !== null) {
+          for (const [k, v] of Object.entries(item)) iterationContext.set(k, v);
+        }
+        for (const decl of callbackConstDecls) {
+          const resolved = this.resolveExpressionValue(decl.initializer, iterationContext);
+          if (resolved !== undefined) {
+            iterationContext.set(decl.name, resolved);
+          }
+        }
         const itemJsx = this.buildJsxTreeWithSubstitution(
           callbackJsx,
           itemParamName,
           item,
           mergedLocalComponents,
-          relativeImports
+          relativeImports,
+          iterationContext
         );
         if (itemJsx) {
           results.push(itemJsx);
@@ -1459,27 +2523,51 @@ export class ComponentScanner {
    * Find the value of an array variable in the source file.
    * Looks for const declarations and default prop values.
    */
-  private findArrayValue(arrayName: string, sourceFile: SourceFile): any[] | null {
+  private findArrayValue(arrayName: string, sourceFile: SourceFile): ResolvedExpressionValue[] | null {
     // Check cache first
     const cacheKey = `${sourceFile.getFilePath()}:${arrayName}`;
     if (this.arrayValueCache.has(cacheKey)) {
       return this.arrayValueCache.get(cacheKey)!;
     }
 
-    // Look for const declaration: const features = [...]
-    for (const varStmt of sourceFile.getVariableStatements()) {
+    // Look for `const features = [...]` style declarations. Walks ALL
+    // variable statements in the source file (top-level AND inside
+    // function bodies) so locally-scoped arrays like
+    // `function BlockTable() { const sortedBlocks = [...blocks].sort(...); ... }`
+    // resolve too — the canonical case is greenhouse-app's block-table
+    // where the .map source is a local sort over an imported JSON file.
+    //
+    // Initializer may be a direct array literal, a spread literal
+    // (`[...other]`), a method chain on an existing array
+    // (`[...blocks].sort(...)`, `data.filter(...).slice(0, N)`), or
+    // simply an identifier that points at another array (re-export).
+    // All of those routes funnel into `resolveArrayFromExpression`.
+    const allVarStatements = sourceFile.getDescendantsOfKind(SyntaxKind.VariableStatement);
+    for (const varStmt of allVarStatements) {
       for (const decl of varStmt.getDeclarationList().getDeclarations()) {
         if (decl.getName() === arrayName) {
-          const init = this.unwrapStaticValueExpression(decl.getInitializer());
-          if (init && Node.isArrayLiteralExpression(init)) {
-            const value = this.parseArrayLiteral(init);
-            this.arrayValueCache.set(cacheKey, value);
-            return value;
+          const init = this.unwrapStaticValueExpression(decl.getInitializer()) || decl.getInitializer();
+          if (init) {
+            const value = this.resolveArrayFromExpression(init, sourceFile);
+            if (value) {
+              this.arrayValueCache.set(cacheKey, value);
+              return value;
+            }
           }
         }
       }
     }
 
+    // If the name is a default import of a `.json` file, load it from
+    // disk. Covers patterns like `import data from '~/constants/blocks.json'`
+    // followed by `.map(item => …)` over the imported array (block-table
+    // is the canonical case in greenhouse-app).
+    const jsonImported = this.resolveImportedJsonValue(arrayName, sourceFile);
+    if (Array.isArray(jsonImported)) {
+      this.arrayValueCache.set(cacheKey, jsonImported);
+      return jsonImported;
+    }
+
     // Look for default parameter value in function: function Comp({ features = defaultFeatures })
     for (const func of sourceFile.getFunctions()) {
       const params = func.getParameters();
@@ -1542,13 +2630,107 @@ export class ComponentScanner {
     return null;
   }
 
+  /**
+   * Resolve an expression to an array of items. Handles:
+   *
+   *   - `[a, b, c]`               — direct array literal (parsed verbatim)
+   *   - `[...items]`              — spread of another array (resolved
+   *                                 recursively against the source file)
+   *   - `items.sort(...)`         — array-returning method chains
+   *                                 (`sort`, `filter`, `slice`, `reverse`,
+   *                                 `toSorted`, `toReversed`, `with`) are
+   *                                 unwrapped to the receiver. We do not
+   *                                 *apply* the operation — for design-
+   *                                 system rendering, any non-empty sample
+   *                                 of items is good enough.
+   *   - identifier                — recurses through `findArrayValue`
+   *                                 (local var) and JSON-import resolution.
+   *
+   * Returns `null` when nothing resolvable is found; the caller then
+   * falls back to its placeholder-iteration path.
+   */
+  private resolveArrayFromExpression(expr: Node, sourceFile: SourceFile): ResolvedExpressionValue[] | null {
+    const unwrapped = this.unwrapStaticValueExpression(expr) || expr;
+
+    if (Node.isArrayLiteralExpression(unwrapped)) {
+      const elements = unwrapped.getElements();
+      if (elements.length === 1 && Node.isSpreadElement(elements[0])) {
+        // `[...items]` — unwrap to `items` and resolve that.
+        const spreadInner = (elements[0] as import('ts-morph').SpreadElement).getExpression();
+        return this.resolveArrayFromExpression(spreadInner, sourceFile);
+      }
+      return this.parseArrayLiteral(unwrapped);
+    }
+
+    if (Node.isCallExpression(unwrapped)) {
+      const callee = unwrapped.getExpression();
+      if (Node.isPropertyAccessExpression(callee)) {
+        const methodName = callee.getName();
+        const PASS_THROUGH_METHODS = new Set([
+          'sort', 'filter', 'slice', 'reverse',
+          'toSorted', 'toReversed', 'with', 'concat', 'flat', 'flatMap',
+        ]);
+        if (PASS_THROUGH_METHODS.has(methodName)) {
+          return this.resolveArrayFromExpression(callee.getExpression(), sourceFile);
+        }
+      }
+    }
+
+    if (Node.isIdentifier(unwrapped)) {
+      const name = unwrapped.getText();
+      const fromCache = this.findArrayValue(name, sourceFile);
+      if (fromCache) return fromCache;
+      const fromJson = this.resolveImportedJsonValue(name, sourceFile);
+      if (Array.isArray(fromJson)) return fromJson;
+    }
+
+    return null;
+  }
+
+  /**
+   * If `name` is a default-imported JSON file in `sourceFile` (e.g.
+   * `import blocks from '~/constants/blocks.json'`), load + parse the
+   * file from disk and return the value. Returns `null` for any other
+   * import shape (named imports, non-JSON files, unresolvable paths).
+   *
+   * Path-alias resolution piggybacks on the existing
+   * `resolveImportedComponentPath`, plus a JSON-only branch that probes
+   * the literal path (without `.tsx`/`.ts` candidates).
+   */
+  private resolveImportedJsonValue(name: string, sourceFile: SourceFile): unknown {
+    const fileDir = path.dirname(sourceFile.getFilePath());
+    for (const imp of sourceFile.getImportDeclarations()) {
+      const defaultImport = imp.getDefaultImport();
+      if (!defaultImport || defaultImport.getText() !== name) continue;
+      const moduleSpec = imp.getModuleSpecifierValue();
+      if (!moduleSpec.endsWith('.json')) return null;
+
+      let absPath: string | null = null;
+      if (moduleSpec.startsWith('./') || moduleSpec.startsWith('../')) {
+        absPath = path.resolve(fileDir, moduleSpec);
+      } else if (moduleSpec.startsWith('~/') || moduleSpec.startsWith('@/')) {
+        absPath = path.resolve(process.cwd(), 'src', moduleSpec.slice(2));
+      } else {
+        return null;
+      }
+
+      if (!fs.existsSync(absPath)) return null;
+      try {
+        const raw = fs.readFileSync(absPath, 'utf-8');
+        return JSON.parse(raw);
+      } catch (_e) {
+        return null;
+      }
+    }
+    return null;
+  }
+
   /**
    * Unwrap syntax wrappers around static values so declarations like
    * `const FAQS = [...] as const` still resolve to the underlying literal.
    */
   private unwrapStaticValueExpression(expr: Node | undefined): Node | undefined {
     let current = expr;
-    const nodeApi = Node as any;
 
     while (current) {
       if (Node.isParenthesizedExpression(current)) {
@@ -1559,11 +2741,11 @@ export class ComponentScanner {
         current = current.getExpression();
         continue;
       }
-      if (typeof nodeApi.isTypeAssertion === 'function' && nodeApi.isTypeAssertion(current)) {
+      if (Node.isTypeAssertion(current)) {
         current = current.getExpression();
         continue;
       }
-      if (typeof nodeApi.isSatisfiesExpression === 'function' && nodeApi.isSatisfiesExpression(current)) {
+      if (Node.isSatisfiesExpression(current)) {
         current = current.getExpression();
         continue;
       }
@@ -1576,14 +2758,14 @@ export class ComponentScanner {
   /**
    * Parse an array literal expression into JavaScript values.
    */
-  private parseArrayLiteral(arrayLit: Node): any[] {
-    const result: any[] = [];
+  private parseArrayLiteral(arrayLit: Node): ResolvedExpressionValue[] {
+    const result: ResolvedExpressionValue[] = [];
 
     if (!Node.isArrayLiteralExpression(arrayLit)) return result;
 
     for (const element of arrayLit.getElements()) {
       if (Node.isObjectLiteralExpression(element)) {
-        const obj: Record<string, any> = {};
+        const obj: Record<string, ResolvedExpressionValue> = {};
         for (const prop of element.getProperties()) {
           if (Node.isPropertyAssignment(prop)) {
             const name = prop.getName();
@@ -1621,40 +2803,59 @@ export class ComponentScanner {
   private buildJsxTreeWithSubstitution(
     node: Node,
     itemParamName: string,
-    itemValue: any,
+    itemValue: ResolvedExpressionValue,
     localComponents: Map<string, Node>,
-    relativeImports: Map<string, string>
+    relativeImports: Map<string, string>,
+    extraContext?: Map<string, ResolvedExpressionValue>
   ): JsxNode | null {
     if (Node.isJsxElement(node)) {
       const rawTagName = node.getOpeningElement().getTagNameNode().getText();
       const tagName = COMPONENT_TO_HTML_MAP[rawTagName] || rawTagName;
-      const itemPropsContext = this.buildItemPropsContext(itemParamName, itemValue);
+      const itemPropsContext = this.buildItemPropsContext(itemParamName, itemValue, extraContext);
       const props = this.extractPropsFromNode(node.getOpeningElement(), rawTagName, itemPropsContext).props;
       const children: JsxNode[] = [];
 
       for (const child of node.getJsxChildren()) {
         if (Node.isJsxElement(child) || Node.isJsxSelfClosingElement(child)) {
-          const childJsx = this.buildJsxTreeWithSubstitution(child, itemParamName, itemValue, localComponents, relativeImports);
+          const childJsx = this.buildJsxTreeWithSubstitution(child, itemParamName, itemValue, localComponents, relativeImports, extraContext);
           if (childJsx) children.push(childJsx);
         } else if (Node.isJsxText(child)) {
-          const text = decodeHtmlEntities(child.getText().trim());
+          const text = decodeHtmlEntities(normalizeJsxText(child.getFullText()));
           if (text) {
             children.push({ type: 'text', content: text });
           }
         } else if (Node.isJsxExpression(child)) {
           const expr = child.getExpression();
           if (expr) {
+            if (Node.isBinaryExpression(expr) && expr.getOperatorToken().getText() === '??') {
+              let chosen: Node = expr.getLeft();
+              const leftValue = this.substituteExpression(expr.getLeft(), itemParamName, itemValue, extraContext);
+              if (leftValue === null || leftValue === undefined) {
+                chosen = expr.getRight();
+              }
+              if (Node.isParenthesizedExpression(chosen)) {
+                chosen = chosen.getExpression();
+              }
+              if (Node.isJsxElement(chosen) || Node.isJsxSelfClosingElement(chosen)) {
+                const jsxChild = this.buildJsxTreeWithSubstitution(chosen, itemParamName, itemValue, localComponents, relativeImports, extraContext);
+                if (jsxChild) children.push(jsxChild);
+              } else {
+                const substituted = this.substituteExpression(chosen, itemParamName, itemValue, extraContext);
+                if (substituted !== null && substituted !== undefined && substituted !== '') {
+                  children.push({ type: 'text', content: String(substituted) });
+                }
+              }
             // Handle conditional JSX: {condition && <JSX>} or {condition && (<JSX>)}
-            if (Node.isBinaryExpression(expr) && expr.getOperatorToken().getText() === '&&') {
+            } else if (Node.isBinaryExpression(expr) && expr.getOperatorToken().getText() === '&&') {
               const left = expr.getLeft();
               let right = expr.getRight();
               // Unwrap parenthesized expression
               if (Node.isParenthesizedExpression(right)) {
                 right = right.getExpression();
               }
-              const condValue = this.substituteExpression(left, itemParamName, itemValue);
+              const condValue = this.substituteExpression(left, itemParamName, itemValue, extraContext);
               if (condValue && (Node.isJsxElement(right) || Node.isJsxSelfClosingElement(right))) {
-                const jsxChild = this.buildJsxTreeWithSubstitution(right, itemParamName, itemValue, localComponents, relativeImports);
+                const jsxChild = this.buildJsxTreeWithSubstitution(right, itemParamName, itemValue, localComponents, relativeImports, extraContext);
                 if (jsxChild) children.push(jsxChild);
               }
             // Handle ternary JSX: {condition ? <JSX1> : <JSX2>}
@@ -1669,20 +2870,40 @@ export class ComponentScanner {
               if (Node.isParenthesizedExpression(whenFalse)) {
                 whenFalse = whenFalse.getExpression();
               }
-              const condValue = this.substituteExpression(condition, itemParamName, itemValue);
+              const condValue = this.substituteExpression(condition, itemParamName, itemValue, extraContext);
               const branch = condValue ? whenTrue : whenFalse;
               if (Node.isJsxElement(branch) || Node.isJsxSelfClosingElement(branch)) {
-                const jsxChild = this.buildJsxTreeWithSubstitution(branch, itemParamName, itemValue, localComponents, relativeImports);
+                const jsxChild = this.buildJsxTreeWithSubstitution(branch, itemParamName, itemValue, localComponents, relativeImports, extraContext);
                 if (jsxChild) children.push(jsxChild);
               } else {
                 // Non-JSX ternary result - substitute as text
-                const substituted = this.substituteExpression(branch, itemParamName, itemValue);
+                const substituted = this.substituteExpression(branch, itemParamName, itemValue, extraContext);
                 if (substituted !== null && substituted !== undefined && substituted !== '') {
                   children.push({ type: 'text', content: String(substituted) });
                 }
               }
+            } else if (Node.isCallExpression(expr)) {
+              // Support nested `.map()` calls inside iteration callbacks so
+              // patterns like Array.from({length}).map(...) expand through the
+              // current propsContext (items/index) to resolve dynamic classes.
+              const callee = expr.getExpression();
+              const isMapCall = Node.isPropertyAccessExpression(callee)
+                && callee.getName() === 'map';
+              if (isMapCall) {
+                const nestedPropsContext = new Map<string, ResolvedExpressionValue>(extraContext);
+                if (itemParamName && itemParamName !== '__destructured__' && itemValue != null) {
+                  nestedPropsContext.set(itemParamName, itemValue);
+                }
+                const nestedChildren = this.expandMapCall(expr, node.getSourceFile(), localComponents, relativeImports, nestedPropsContext);
+                for (const nested of nestedChildren) children.push(nested);
+                continue;
+              }
+              const substituted = this.substituteExpression(expr, itemParamName, itemValue, extraContext);
+              if (substituted !== null && substituted !== undefined && substituted !== '') {
+                children.push({ type: 'text', content: String(substituted) });
+              }
             } else {
-              const substituted = this.substituteExpression(expr, itemParamName, itemValue);
+              const substituted = this.substituteExpression(expr, itemParamName, itemValue, extraContext);
               if (substituted !== null && substituted !== undefined && substituted !== '') {
                 children.push({ type: 'text', content: String(substituted) });
               }
@@ -1711,9 +2932,9 @@ export class ComponentScanner {
         }
 
         const importedFilePath = relativeImports.get(rawTagName);
-        const SKIP_EXPANSION = ['Skeleton', 'SkeletonText'];
+        const SKIP_EXPANSION = ['Skeleton'];
         if (importedFilePath && !SKIP_EXPANSION.includes(rawTagName)) {
-          const resolvedProps = new Map<string, any>();
+          const resolvedProps = new Map<string, ResolvedExpressionValue>();
           for (const [key, value] of Object.entries(evaluatedProps)) {
             resolvedProps.set(key, value);
           }
@@ -1729,7 +2950,7 @@ export class ComponentScanner {
         }
       }
 
-      const outputProps = { ...props } as Record<string, any>;
+      const outputProps = { ...props } as Record<string, ResolvedExpressionValue>;
       delete outputProps.children;
       return {
         type: 'element',
@@ -1748,7 +2969,7 @@ export class ComponentScanner {
         rawTagName = itemValue[rawTagName];
       }
       const tagName = COMPONENT_TO_HTML_MAP[rawTagName] || rawTagName;
-      const itemPropsContext = this.buildItemPropsContext(itemParamName, itemValue);
+      const itemPropsContext = this.buildItemPropsContext(itemParamName, itemValue, extraContext);
       const props = this.extractPropsFromNode(node, rawTagName, itemPropsContext).props;
 
       // Check for local component expansion
@@ -1766,11 +2987,11 @@ export class ComponentScanner {
       // Check for imported component expansion
       // Skip expansion for simple components that the ui-builder handles directly
       // (e.g., Skeleton uses clsx with props that we can't statically evaluate)
-      const SKIP_EXPANSION = ['Skeleton', 'SkeletonText'];
+      const SKIP_EXPANSION = ['Skeleton'];
       const importedFilePath = relativeImports.get(rawTagName);
       if (importedFilePath && !SKIP_EXPANSION.includes(rawTagName)) {
         const evaluatedProps = this.resolveSubstitutionProps(props, itemParamName, itemValue);
-        const resolvedProps = new Map<string, any>();
+        const resolvedProps = new Map<string, ResolvedExpressionValue>();
         for (const [key, value] of Object.entries(evaluatedProps)) {
           resolvedProps.set(key, value);
         }
@@ -1780,7 +3001,7 @@ export class ComponentScanner {
         }
       }
 
-      const outputProps = { ...props } as Record<string, any>;
+      const outputProps = { ...props } as Record<string, ResolvedExpressionValue>;
       delete outputProps.children;
       return {
         type: 'element',
@@ -1800,7 +3021,7 @@ export class ComponentScanner {
    */
   private expandLocalComponentWithProps(
     componentDef: Node,
-    evaluatedProps: Record<string, any>,
+    evaluatedProps: Record<string, ResolvedExpressionValue>,
     localComponents: Map<string, Node>,
     relativeImports: Map<string, string>
   ): JsxNode | null {
@@ -1841,7 +3062,7 @@ export class ComponentScanner {
       if (Node.isParenthesizedExpression(jsxExpr)) {
         jsxExpr = jsxExpr.getExpression();
       }
-      if (Node.isJsxElement(jsxExpr) || Node.isJsxSelfClosingElement(jsxExpr)) {
+      if (Node.isJsxElement(jsxExpr) || Node.isJsxSelfClosingElement(jsxExpr) || Node.isJsxFragment(jsxExpr)) {
         jsxToExpand = jsxExpr;
         break;
       }
@@ -1851,7 +3072,8 @@ export class ComponentScanner {
     if (!jsxToExpand) {
       const jsxElements = componentDef.getDescendantsOfKind(SyntaxKind.JsxElement);
       const selfClosing = componentDef.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
-      const allJsx = [...jsxElements, ...selfClosing];
+      const fragments = componentDef.getDescendantsOfKind(SyntaxKind.JsxFragment);
+      const allJsx = [...jsxElements, ...selfClosing, ...fragments];
       if (allJsx.length > 0) {
         jsxToExpand = allJsx[0];
         for (const el of allJsx) {
@@ -1864,7 +3086,7 @@ export class ComponentScanner {
 
     if (!jsxToExpand) return null;
 
-    const propsMap = new Map<string, any>();
+    const propsMap = new Map<string, ResolvedExpressionValue>();
     for (const [key, value] of Object.entries(evaluatedProps)) {
       propsMap.set(key, value);
     }
@@ -1876,7 +3098,45 @@ export class ComponentScanner {
       const nameNode = firstParam.getNameNode?.();
       if (nameNode && Node.isIdentifier(nameNode)) {
         // Function signature uses a plain `props` identifier.
-        propsMap.set(nameNode.getText(), { ...evaluatedProps });
+        const paramName = nameNode.getText();
+        propsMap.set(paramName, { ...evaluatedProps });
+
+        // Many components destructure inside the body with defaults, e.g.
+        //   function X(props) { const { lines = 3, widths = DEFAULT_WIDTHS } = props; ... }
+        // Treat these destructurings equivalently to in-signature destructuring
+        // so defaults populate propsMap and are available to the JSX tree.
+        const bodyBlock = Node.isFunctionDeclaration(componentDef)
+          || Node.isFunctionExpression(componentDef)
+          || Node.isArrowFunction(componentDef)
+          || Node.isMethodDeclaration(componentDef)
+          ? componentDef.getBody()
+          : undefined;
+        if (bodyBlock && Node.isBlock(bodyBlock)) {
+          for (const stmt of bodyBlock.getStatements()) {
+            if (!Node.isVariableStatement(stmt)) continue;
+            for (const decl of stmt.getDeclarationList().getDeclarations()) {
+              const bindingName = decl.getNameNode();
+              if (!Node.isObjectBindingPattern(bindingName)) continue;
+              const sourceIdent = decl.getInitializer();
+              if (!sourceIdent || sourceIdent.getText() !== paramName) continue;
+              for (const element of bindingName.getElements()) {
+                if (element.getDotDotDotToken()) continue;
+                const sourceKey = element.getPropertyNameNode?.()?.getText() || element.getName();
+                const localName = element.getName();
+                if (Object.prototype.hasOwnProperty.call(evaluatedProps, sourceKey)) {
+                  propsMap.set(localName, evaluatedProps[sourceKey]);
+                  continue;
+                }
+                const defaultInit = this.unwrapStaticValueExpression(element.getInitializer?.());
+                if (!defaultInit) continue;
+                const defaultValue = this.resolveExpressionValue(defaultInit, propsMap);
+                if (defaultValue !== undefined) {
+                  propsMap.set(localName, defaultValue);
+                }
+              }
+            }
+          }
+        }
       } else if (nameNode && Node.isObjectBindingPattern(nameNode)) {
         const consumedKeys = new Set<string>();
         const restBindings: string[] = [];
@@ -1915,7 +3175,7 @@ export class ComponentScanner {
         }
 
         if (restBindings.length > 0) {
-          const restObject: Record<string, any> = {};
+          const restObject: Record<string, ResolvedExpressionValue> = {};
           for (const [key, value] of Object.entries(evaluatedProps)) {
             if (!consumedKeys.has(key)) {
               restObject[key] = value;
@@ -1931,9 +3191,14 @@ export class ComponentScanner {
     return this.buildJsxTree(jsxToExpand, localComponents, relativeImports, propsMap);
   }
 
-  private getComponentParameterNodes(componentDef: Node): any[] {
-    if (typeof (componentDef as any).getParameters === 'function') {
-      return (componentDef as any).getParameters();
+  private getComponentParameterNodes(componentDef: Node): import('ts-morph').ParameterDeclaration[] {
+    if (
+      Node.isFunctionDeclaration(componentDef)
+      || Node.isFunctionExpression(componentDef)
+      || Node.isArrowFunction(componentDef)
+      || Node.isMethodDeclaration(componentDef)
+    ) {
+      return componentDef.getParameters();
     }
 
     if (Node.isCallExpression(componentDef)) {
@@ -1949,13 +3214,296 @@ export class ComponentScanner {
 
   /**
    * Returns true if the expanded node's root is a portal wrapper (renders outside the DOM tree).
-   * Used to skip components like DialogContent, SelectContent, SheetContent, DropdownMenuContent.
+   * Used to unwrap components like DialogContent, SelectContent, SheetContent, DropdownMenuContent.
    */
   private isPortalRootedNode(node: JsxNode): boolean {
     if (node.type !== 'element') return false;
     return node.tagName.toLowerCase().includes('portal');
   }
 
+  /**
+   * Extracts the renderable content nodes from inside a portal wrapper,
+   * skipping overlay/backdrop elements that are irrelevant in Figma.
+   */
+  private extractPortalContentNodes(portalNode: JsxNode): JsxNode[] {
+    if (portalNode.type !== 'element') return [];
+    const el = portalNode as JsxElement;
+    return (el.children || []).filter((child: JsxNode) => {
+      if (child.type !== 'element') return true;
+      const tag = (child as JsxElement).tagName.toLowerCase();
+      return !tag.includes('overlay') && !tag.includes('backdrop');
+    });
+  }
+
+  /**
+   * 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).
+   *
+   * Called on the extracted portal content node so the renderer sees only the
+   * visual layout classes (grid, gap, padding, border, shadow, bg, etc.).
+   */
+  private stripPortalPositioningClasses(className: string): string {
+    if (!className) return className;
+    return className
+      .split(/\s+/)
+      .filter(cls => {
+        if (!cls) return false;
+        // State-variant animations: data-[state=open]:animate-in etc.
+        if (cls.includes('[state=')) return false;
+        // Arbitrary selector variants: strip SVG-targeting and pointer-events selectors
+        // (e.g. [&_svg]:pointer-events-none, [&_svg]:shrink-0, [&_svg:not([class*='size-'])]:size-4)
+        // but KEEP direct-child layout selectors like [&>*]:w-full, [&>button]:px-4.
+        if (cls.startsWith('[&')) {
+          const selectorMatch = cls.match(/^\[([^\]]+)\]/);
+          const selector = selectorMatch ? selectorMatch[1] : '';
+          if (selector.includes('svg') || selector.includes('pointer-events')) return false;
+        }
+        // Positioning
+        if (cls === 'fixed' || cls === 'absolute' || cls === 'sticky') return false;
+        // Directional offsets
+        if (/^-?(top|left|right|bottom)-/.test(cls)) return false;
+        // CSS transforms
+        if (/^-?translate-/.test(cls)) return false;
+        // Z-index
+        if (/^z-/.test(cls)) return false;
+        // Inset utilities
+        if (/^-?inset/.test(cls)) return false;
+        // Transition duration/ease (irrelevant in Figma)
+        if (/^duration-/.test(cls)) return false;
+        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(' ');
+  }
+
+  /**
+   * JS-style truthiness for a statically resolved expression value.
+   * Used by the `&&` / `||` / ternary handlers in JSX expressions to decide
+   * which branch to render. `undefined` means unresolvable, not falsy — the
+   * caller treats unresolvable values separately so the design-system render
+   * doesn't speculate about runtime state.
+   */
+  private isExpressionTruthy(value: unknown): boolean {
+    if (value === undefined || value === null) return false;
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'number') return value !== 0 && !Number.isNaN(value);
+    if (typeof value === 'string') return value.length > 0;
+    return true;
+  }
+
+  /**
+   * Materialize a chosen JSX-expression branch as scanner children.
+   * If the branch is a JsxElement, build its subtree; otherwise resolve it
+   * as a value and push as text/children. Shared by the `??`/`&&`/`||` and
+   * ternary handlers.
+   */
+  private pushChosenJsxBranch(
+    chosenIn: Node,
+    children: JsxNode[],
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>,
+    propsContext: Map<string, ResolvedExpressionValue>
+  ): void {
+    let chosen: Node = chosenIn;
+    if (Node.isParenthesizedExpression(chosen)) {
+      chosen = chosen.getExpression();
+    }
+    if (Node.isJsxElement(chosen) || Node.isJsxSelfClosingElement(chosen)) {
+      const childNode = this.buildJsxTree(chosen, localComponents, relativeImports, propsContext);
+      if (!(childNode as JsxNode & PortalSkipFlagged).__portalSkip) {
+        children.push(childNode);
+      }
+      return;
+    }
+    const resolved = this.resolveExpressionValue(chosen, propsContext);
+    if (resolved !== undefined && resolved !== null) {
+      this.pushResolvedPropValue(children, resolved);
+    }
+  }
+
+  /**
+   * Walk down through unresolved single-child wrappers at the root of an
+   * expanded tree until we reach a resolved node. Returns `null` when no
+   * resolved inner node is reachable (i.e. the whole tree is opaque).
+   *
+   * Why this exists: when a component imported into a story expands to
+   * something like `<Form><form>...</form></Form>` where `<Form>` is an
+   * alias to an external import (e.g. `const Form = FormProvider`),
+   * `<Form>` looks "unresolved" relative to the story file's imports —
+   * but the inner `<form>` and its descendants are perfectly fine. Without
+   * this unwrap the whole expansion gets discarded and the story tree
+   * keeps the `<SignupForm/>` placeholder with empty children.
+   */
+  private unwrapUnresolvedSingleChildRoots(
+    node: JsxNode,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>
+  ): JsxNode | null {
+    let current: JsxNode = node;
+    let safety = 16;
+    while (safety-- > 0 && this.isUnresolvedExpandedComponent(current, localComponents, relativeImports)) {
+      if (current.type !== 'element') return null;
+      const el = current as JsxElement;
+      if (!Array.isArray(el.children) || el.children.length !== 1) return null;
+      if (el.children[0].type !== 'element') return null;
+      current = el.children[0];
+    }
+    return current;
+  }
+
+  /**
+   * Detect a pass-through wrapper invocation: the user wrote
+   * `<Wrapper>{singleChild}</Wrapper>` and added no visual className.
+   * Used after `isUnresolvedExpandedComponent` confirms the wrapper's
+   * implementation expands to an unresolvable Slot-style root, so we
+   * can drop the wrapper and render the inner primitive directly.
+   */
+  /**
+   * Pre-analyse a component's body for `<*.Provider value={{ ... }}>`
+   * wrappers and return the set of prop names that get cascaded through.
+   *
+   * Mirrors React's Context.Provider semantics statically — the canonical
+   * shadcn pattern is `<ToggleGroup variant={x} size={y}><...item.../>...</ToggleGroup>`
+   * where ToggleGroup wraps its children in `<ToggleGroupContext.Provider
+   * value={{ variant, size }}>{children}</...>`. At runtime descendants
+   * read those values via `useContext`. Statically we can't simulate
+   * `useContext`, but we CAN detect the wrapping Provider's value-keys and
+   * inject the invocation's matching props into descendant invocations.
+   *
+   * Cached per component name — the body walk runs once.
+   *
+   * Returns an empty set when the component has no Provider wrapper or
+   * the value isn't an object literal we can statically analyse.
+   */
+  // Shared "no cascade" sentinel — avoids allocating a new empty Set when a
+  // component isn't found (e.g. an imported component whose source file
+  // doesn't load). Read-only by convention; callers only check `.size`.
+  private static readonly EMPTY_PROVIDER_CASCADE_NAMES: Set<string> = new Set();
+
+  private detectProviderCascadeNamesForComponent(
+    componentName: string,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>
+  ): Set<string> {
+    const bodyNode = this.findComponentDefinitionNode(componentName, localComponents, relativeImports);
+    if (!bodyNode) return ComponentScanner.EMPTY_PROVIDER_CASCADE_NAMES;
+    if (this.providerCascadeNamesCache.has(bodyNode)) {
+      return this.providerCascadeNamesCache.get(bodyNode)!;
+    }
+    const result = new Set<string>();
+    // Cache by Node identity so different `Group` functions in unrelated
+    // source files don't collide. Cache early to short-circuit recursion.
+    this.providerCascadeNamesCache.set(bodyNode, result);
+
+    bodyNode.forEachDescendant((node) => {
+      if (!Node.isJsxOpeningElement(node) && !Node.isJsxSelfClosingElement(node)) return;
+      const tagText = node.getTagNameNode().getText();
+      if (!tagText.endsWith('.Provider')) return;
+      const attrs = node.getAttributes();
+      for (const attr of attrs) {
+        if (!Node.isJsxAttribute(attr)) continue;
+        const nameNode = attr.getNameNode();
+        if (nameNode.getText() !== 'value') continue;
+        const init = attr.getInitializer();
+        if (!init || !Node.isJsxExpression(init)) continue;
+        const expr = init.getExpression();
+        if (!expr || !Node.isObjectLiteralExpression(expr)) continue;
+        for (const prop of expr.getProperties()) {
+          if (Node.isShorthandPropertyAssignment(prop)) {
+            result.add(prop.getName());
+          } else if (Node.isPropertyAssignment(prop)) {
+            const propNameNode = prop.getNameNode();
+            const propName = propNameNode.getText();
+            if (propName) result.add(propName);
+          }
+        }
+      }
+    });
+    return result;
+  }
+
+  /**
+   * Locate a component's function-definition Node, whether the component
+   * is defined locally in the same file (in `localComponents`) or imported
+   * from another module (looked up via `relativeImports`).
+   */
+  private findComponentDefinitionNode(
+    componentName: string,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>
+  ): Node | null {
+    const localDef = localComponents.get(componentName);
+    if (localDef) return localDef;
+    const filePath = relativeImports.get(componentName);
+    if (!filePath) return null;
+    const cacheKey = `${filePath}:${componentName}`;
+    let sourceFile: SourceFile | undefined;
+    const cached = this.importedComponentCache.get(cacheKey);
+    if (cached) {
+      sourceFile = cached.sourceFile;
+    } else {
+      try {
+        sourceFile = this.project.addSourceFileAtPath(filePath);
+        this.importedComponentCache.set(cacheKey, { sourceFile, componentName });
+      } catch (_err) {
+        return null;
+      }
+    }
+    if (!sourceFile) return null;
+    for (const func of sourceFile.getFunctions()) {
+      if (func.getName() === componentName) return func;
+    }
+    for (const variable of sourceFile.getVariableDeclarations()) {
+      if (variable.getName() !== componentName) continue;
+      const init = variable.getInitializer();
+      if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) return init;
+    }
+    return null;
+  }
+
+  /**
+   * Recursively push `child` into `out`, expanding any transparent React
+   * Context Providers (`*.Provider`) into their own children. Providers
+   * exist only to inject context — they produce no DOM. Single-child
+   * Providers are already stripped at the buildJsxTree return point;
+   * this handles the multi-child case (e.g. a `ToggleGroup` that wraps
+   * multiple items in a `*.Provider` to cascade `variant`/`size`). The
+   * skipped wrapper would otherwise become an unsized inner frame that
+   * collapses the parent's auto-layout — see toggle-group rendering bug.
+   */
+  private pushFlatteningTransparentProvider(out: JsxNode[], child: JsxNode): void {
+    if (
+      child.type === 'element'
+      && child.tagName.endsWith('.Provider')
+      && !(typeof child.props?.className === 'string' && child.props.className.trim().length > 0)
+    ) {
+      for (const grandchild of child.children) {
+        this.pushFlatteningTransparentProvider(out, grandchild);
+      }
+      return;
+    }
+    out.push(child);
+  }
+
+  private isPassThroughInvocation(
+    props: Record<string, ResolvedExpressionValue>,
+    children: JsxNode[]
+  ): boolean {
+    if (children.length !== 1) return false;
+    if (children[0].type !== 'element') return false;
+    const className = typeof props.className === 'string' ? props.className.trim() : '';
+    if (className.length > 0) return false;
+    const styleProp = typeof props.style === 'string' ? props.style.trim() : '';
+    if (styleProp.length > 0) return false;
+    return true;
+  }
+
   private isUnresolvedExpandedComponent(
     node: JsxNode,
     localComponents: Map<string, Node>,
@@ -1997,7 +3545,12 @@ export class ComponentScanner {
    * Substitute an expression with values from the map item.
    * Handles: feature.name, feature.description, feature.free, etc.
    */
-  private substituteExpression(expr: Node, itemParamName: string, itemValue: any): any {
+  private substituteExpression(
+    expr: Node,
+    itemParamName: string,
+    itemValue: ResolvedExpressionValue,
+    extraContext?: Map<string, ResolvedExpressionValue>
+  ): ResolvedExpressionValue {
     const text = expr.getText();
 
     // Handle property access: feature.name, feature.description
@@ -2008,6 +3561,13 @@ export class ComponentScanner {
       if (objExpr.getText() === itemParamName && typeof itemValue === 'object') {
         return itemValue[propName];
       }
+      // Outer context lookup: `propsContext.someObject.prop`
+      if (extraContext && Node.isIdentifier(objExpr)) {
+        const baseValue = extraContext.get(objExpr.getText());
+        if (baseValue != null && typeof baseValue === 'object' && propName in baseValue) {
+          return baseValue[propName];
+        }
+      }
     }
 
     // Handle simple variable reference: feature (if it's the whole item)
@@ -2022,6 +3582,36 @@ export class ComponentScanner {
       if (val !== undefined) return val;
     }
 
+    // Handle identifiers bound in outer propsContext (e.g. `index`, `widths`).
+    if (extraContext && Node.isIdentifier(expr) && extraContext.has(text)) {
+      return extraContext.get(text);
+    }
+
+    // Fall back to the scanner's general expression resolver so complex
+    // expressions — property/element access, arithmetic, ternaries, clsx —
+    // can evaluate against the combined context.
+    if (extraContext || itemValue != null) {
+      const merged = new Map<string, ResolvedExpressionValue>();
+      if (extraContext) for (const [k, v] of extraContext) merged.set(k, v);
+      if (itemParamName && itemValue != null) {
+        if (itemParamName === '__destructured__' && typeof itemValue === 'object') {
+          for (const [k, v] of Object.entries(itemValue)) merged.set(k, v);
+        } else {
+          merged.set(itemParamName, itemValue);
+        }
+      }
+      const resolved = this.resolveExpressionValue(expr, merged);
+      if (resolved !== undefined) return resolved;
+    }
+
+    if (Node.isBinaryExpression(expr) && expr.getOperatorToken().getText() === '??') {
+      const leftValue = this.substituteExpression(expr.getLeft(), itemParamName, itemValue, extraContext);
+      if (leftValue !== null && leftValue !== undefined) {
+        return leftValue;
+      }
+      return this.substituteExpression(expr.getRight(), itemParamName, itemValue, extraContext);
+    }
+
     // Handle conditional: feature.description && <p>...</p>
     if (Node.isBinaryExpression(expr)) {
       const left = expr.getLeft();
@@ -2029,7 +3619,7 @@ export class ComponentScanner {
       const right = expr.getRight();
 
       if (operator === '&&') {
-        const leftValue = this.substituteExpression(left, itemParamName, itemValue);
+        const leftValue = this.substituteExpression(left, itemParamName, itemValue, extraContext);
         if (leftValue) {
           // If right side is JSX, we'd need to render it - for now just return text
           if (Node.isJsxElement(right) || Node.isJsxSelfClosingElement(right)) {
@@ -2043,7 +3633,7 @@ export class ComponentScanner {
             for (const exprNode of exprNodes) {
               const innerExpr = exprNode.getExpression();
               if (innerExpr) {
-                const val = this.substituteExpression(innerExpr, itemParamName, itemValue);
+                const val = this.substituteExpression(innerExpr, itemParamName, itemValue, extraContext);
                 if (val !== null && val !== undefined) {
                   textContent += String(val) + ' ';
                 }
@@ -2051,7 +3641,7 @@ export class ComponentScanner {
             }
             return textContent.trim();
           }
-          return this.substituteExpression(right, itemParamName, itemValue);
+          return this.substituteExpression(right, itemParamName, itemValue, extraContext);
         }
         return null;
       }
@@ -2060,7 +3650,7 @@ export class ComponentScanner {
     // Handle ternary: feature.free ? <Check /> : <Cross />
     if (Node.isConditionalExpression(expr)) {
       const condition = expr.getCondition();
-      const condValue = this.substituteExpression(condition, itemParamName, itemValue);
+      const condValue = this.substituteExpression(condition, itemParamName, itemValue, extraContext);
       // Return indication of which branch (for components like Check/Cross)
       if (condValue) {
         return 'true';
@@ -2086,7 +3676,7 @@ export class ComponentScanner {
     componentName: string,
     filePath: string,
     relativeImports: Map<string, string>,
-    resolvedProps: Map<string, any> = new Map()
+    resolvedProps: Map<string, ResolvedExpressionValue> = new Map()
   ): JsxNode | null {
     try {
       // Check cache first
@@ -2124,7 +3714,7 @@ export class ComponentScanner {
     sourceFile: SourceFile,
     componentName: string,
     relativeImports: Map<string, string>,
-    resolvedProps: Map<string, any> = new Map()
+    resolvedProps: Map<string, ResolvedExpressionValue> = new Map()
   ): JsxNode | null {
     const localComponents = this.collectLocalComponentsFromFile(sourceFile);
     const mergedRelativeImports = new Map(relativeImports);
@@ -2248,15 +3838,35 @@ export class ComponentScanner {
    * Parse an ObjectLiteralExpression AST node into a plain JS object.
    * Handles string, number, boolean, nested object, and array values.
    */
-  private parseObjectLiteralExpression(expr: Node): Record<string, any> {
-    const result: Record<string, any> = {};
-    for (const prop of (expr as any).getProperties?.() ?? []) {
+  private parseObjectLiteralExpression(
+    expr: Node,
+    propsContext: Map<string, ResolvedExpressionValue> = new Map()
+  ): Record<string, ResolvedExpressionValue> {
+    const result: Record<string, ResolvedExpressionValue> = {};
+    if (!Node.isObjectLiteralExpression(expr)) return result;
+    for (const prop of expr.getProperties()) {
+      if (Node.isShorthandPropertyAssignment(prop)) {
+        // `{ color }` shorthand: resolve the identifier against the callback's
+        // propsContext (map iteration, etc.) so values from destructured items
+        // are captured. Falls back to the literal identifier text if unresolved.
+        const key = prop.getName();
+        if (!key) continue;
+        const nameNode = prop.getNameNode();
+        const resolved = nameNode
+          ? this.resolveExpressionValue(nameNode, propsContext)
+          : undefined;
+        if (resolved !== undefined) {
+          result[key] = resolved;
+        }
+        continue;
+      }
       if (!Node.isPropertyAssignment(prop)) continue;
-      const key = (prop as any).getName?.();
+      const key = prop.getName();
       if (!key) continue;
-      const val = (prop as any).getInitializer?.();
+      const val = prop.getInitializer();
       if (!val) continue;
-      result[key] = this.parseLiteralValue(val);
+      const resolved = this.resolveExpressionValue(val, propsContext);
+      result[key] = resolved !== undefined ? resolved : this.parseLiteralValue(val);
     }
     return result;
   }
@@ -2264,7 +3874,7 @@ export class ComponentScanner {
   /**
    * Parse a literal AST node into a plain JS value (string, number, boolean, array, object).
    */
-  private parseLiteralValue(val: Node): any {
+  private parseLiteralValue(val: Node): ResolvedExpressionValue {
     const unwrapped = this.unwrapStaticValueExpression(val);
     if (unwrapped && unwrapped !== val) {
       return this.parseLiteralValue(unwrapped);
@@ -2275,7 +3885,7 @@ export class ComponentScanner {
     if (text === 'true') return true;
     if (text === 'false') return false;
     if (Node.isArrayLiteralExpression(val)) {
-      return (val as any).getElements().map((el: Node) => this.parseLiteralValue(el));
+      return val.getElements().map((el) => this.parseLiteralValue(el));
     }
     if (Node.isObjectLiteralExpression(val)) {
       return this.parseObjectLiteralExpression(val);
@@ -2283,7 +3893,7 @@ export class ComponentScanner {
     return text;
   }
 
-  private coerceBoolean(value: any): boolean | null {
+  private coerceBoolean(value: unknown): boolean | null {
     if (typeof value === 'boolean') return value;
     if (typeof value === 'number') return value !== 0;
     if (typeof value === 'string') {
@@ -2298,7 +3908,60 @@ export class ComponentScanner {
     return null;
   }
 
-  private resolveExpressionValue(expr: Node, propsContext: Map<string, any>): any {
+  /**
+   * Resolve an identifier against function-body / block-scoped `const`
+   * declarations, walking ancestor scopes from the reference site outward.
+   * Returns `undefined` if no scope-local declaration is found so the caller
+   * can fall back to module-level lookup.
+   *
+   * Necessary because `SourceFile.getVariableDeclaration` only sees top-level
+   * statements — anything declared inside a function body (the common
+   * `const dotClass = sourceLabel === "db" ? "..." : "..."` pattern used to
+   * derive Tailwind classes from a prop value) is invisible to it. Without
+   * this helper such derived classes silently collapse to "no class" in the
+   * scanner output even though the runtime evaluates them fine.
+   *
+   * Forward references (a `const` declared AFTER the reference site in the
+   * same scope) are skipped to match real JavaScript TDZ semantics.
+   *
+   * Cycle protection via `localResolutionStack` — re-entering the same
+   * `${filePath}:${name}` returns `undefined` instead of recursing forever.
+   */
+  private resolveLocalIdentifier(
+    name: string,
+    fromNode: Node,
+    propsContext: Map<string, ResolvedExpressionValue>,
+  ): ResolvedExpressionValue {
+    const filePath = fromNode.getSourceFile().getFilePath();
+    const stackKey = `${filePath}:${name}`;
+    if (this.localResolutionStack.has(stackKey)) return undefined;
+    const fromStart = fromNode.getStart();
+    let cursor: Node | undefined = fromNode.getParent();
+    while (cursor && !Node.isSourceFile(cursor)) {
+      if (Node.isBlock(cursor) || Node.isCaseClause(cursor) || Node.isDefaultClause(cursor)) {
+        for (const stmt of cursor.getStatements()) {
+          if (!Node.isVariableStatement(stmt)) continue;
+          // Skip forward references — match TDZ semantics.
+          if (stmt.getEnd() > fromStart) continue;
+          for (const decl of stmt.getDeclarationList().getDeclarations()) {
+            if (decl.getName() !== name) continue;
+            const init = decl.getInitializer();
+            if (!init) return undefined;
+            this.localResolutionStack.add(stackKey);
+            try {
+              return this.resolveExpressionValue(init, propsContext);
+            } finally {
+              this.localResolutionStack.delete(stackKey);
+            }
+          }
+        }
+      }
+      cursor = cursor.getParent();
+    }
+    return undefined;
+  }
+
+  private resolveExpressionValue(expr: Node, propsContext: Map<string, ResolvedExpressionValue>): ResolvedExpressionValue {
     if (Node.isParenthesizedExpression(expr)) {
       return this.resolveExpressionValue(expr.getExpression(), propsContext);
     }
@@ -2313,22 +3976,64 @@ export class ComponentScanner {
     if (exprText === 'false') return false;
     if (Node.isIdentifier(expr)) {
       if (propsContext.has(exprText)) return propsContext.get(exprText);
-      // Resolve module-level const string (e.g. const navLinkCls = "...")
+      // Resolve function-body-local consts FIRST so they shadow module-level
+      // names — same rule JavaScript scoping enforces. Without this, a
+      // pattern like `const dotClass = sourceLabel === "db" ? "bg-emerald-500"
+      // : "bg-sky-400"` followed by `<span className={cn(base, dotClass)}/>`
+      // collapses to just `base` and the conditional color is dropped.
+      const localValue = this.resolveLocalIdentifier(exprText, expr, propsContext);
+      if (localValue !== undefined) return localValue;
+      // Resolve module-level consts: strings, object literals (e.g.
+      // `const WIDTH_CLASSNAMES = {...} as const;`), and array literals
+      // (e.g. `const DEFAULT_WIDTHS = [...]`). Returning the parsed value
+      // lets downstream element-access / property-access resolve correctly.
       const varDecl = expr.getSourceFile().getVariableDeclaration(exprText);
       if (varDecl) {
         const init = varDecl.getInitializer();
-        if (init && Node.isStringLiteral(init)) return init.getLiteralValue();
+        if (init) {
+          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.isArrayLiteralExpression(unwrapped)) {
+            return this.parseArrayLiteral(unwrapped);
+          }
+          if (Node.isObjectLiteralExpression(unwrapped)) {
+            return this.parseObjectLiteralExpression(unwrapped, propsContext);
+          }
+        }
       }
       return undefined;
     }
     if (Node.isPropertyAccessExpression(expr)) {
       const baseExpr = expr.getExpression();
       const propName = expr.getName();
-      if (Node.isIdentifier(baseExpr) && propsContext.has(baseExpr.getText())) {
-        const baseValue = propsContext.get(baseExpr.getText());
-        if (baseValue && typeof baseValue === 'object' && propName in baseValue) {
-          return (baseValue as any)[propName];
+      const baseValue = this.resolveExpressionValue(baseExpr, propsContext);
+      if (baseValue != null) {
+        if (Array.isArray(baseValue) && propName === 'length') return baseValue.length;
+        if (typeof baseValue === 'object' && propName in baseValue) {
+          return baseValue[propName];
         }
+        if (typeof baseValue === 'string') {
+          if (propName === 'length') return baseValue.length;
+        }
+      }
+      return undefined;
+    }
+    if (Node.isElementAccessExpression(expr)) {
+      // `WIDTH_CLASSNAMES[width]`, `widths[index]`, `widths[index % N]`, etc.
+      const baseExpr = expr.getExpression();
+      const argExpr = expr.getArgumentExpression();
+      if (!argExpr) return undefined;
+      const baseValue = this.resolveExpressionValue(baseExpr, propsContext);
+      const argValue = this.resolveExpressionValue(argExpr, propsContext);
+      if (baseValue == null || argValue == null) return undefined;
+      if (Array.isArray(baseValue) && typeof argValue === 'number') {
+        return baseValue[argValue];
+      }
+      if (typeof baseValue === 'object' && (typeof argValue === 'string' || typeof argValue === 'number')) {
+        return baseValue[argValue as string];
       }
       return undefined;
     }
@@ -2368,17 +4073,82 @@ export class ComponentScanner {
         if (leftBool === false) return this.resolveExpressionValue(expr.getRight(), propsContext);
         return undefined;
       }
+      if (op === '??') {
+        const leftValue = this.resolveExpressionValue(expr.getLeft(), propsContext);
+        if (leftValue !== undefined && leftValue !== null) return leftValue;
+        return this.resolveExpressionValue(expr.getRight(), propsContext);
+      }
       if (op === '+') {
         const left = this.resolveExpressionValue(expr.getLeft(), propsContext);
         const right = this.resolveExpressionValue(expr.getRight(), propsContext);
         if (left === undefined || right === undefined) return undefined;
+        if (typeof left === 'number' && typeof right === 'number') return left + right;
         return String(left) + String(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 right === 0 ? undefined : left / right;
+        return right === 0 ? undefined : left % right;
+      }
+    }
+    // Method-call expressions on resolvable bases — covers the common
+    // story-args pattern `{rewardSol.toFixed(4)} SOL`. Without this the
+    // expression returns undefined and the JSX walker drops it from
+    // the captured tree, so a `<RewardDisplay rewardSol={0.1482}>` story
+    // renders just " SOL" with the number missing. Limited to Number /
+    // 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 calleeExpr = expr.getExpression();
+      if (Node.isPropertyAccessExpression(calleeExpr)) {
+        const methodName = calleeExpr.getName();
+        const baseValue = this.resolveExpressionValue(calleeExpr.getExpression(), propsContext);
+        if (baseValue == null) return undefined;
+        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]) {
+          const arg = argValues[0];
+          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);
+          } catch (_e) { return undefined; }
+        }
+        if (typeof baseValue === 'string' && STRING_METHODS[methodName]) {
+          if (methodName === 'toUpperCase') return baseValue.toUpperCase();
+          if (methodName === 'toLowerCase') return baseValue.toLowerCase();
+          if (methodName === 'trim') return baseValue.trim();
+          if (methodName === 'toString') return baseValue;
+        }
+      } 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;
+        }
+      }
     }
     return undefined;
   }
 
-  private resolveClassNameExpression(expr: Node, propsContext: Map<string, any>): string {
+  private resolveClassNameExpression(expr: Node, propsContext: Map<string, ResolvedExpressionValue>): string {
     if (Node.isParenthesizedExpression(expr)) {
       return this.resolveClassNameExpression(expr.getExpression(), propsContext);
     }
@@ -2386,15 +4156,15 @@ export class ComponentScanner {
       return expr.getLiteralValue();
     }
     if (Node.isTemplateExpression(expr)) {
-      // Use compilerNode.text to get the raw literal content of template head/middle/tail
-      const parts: string[] = [(expr.getHead().compilerNode as any).text ?? ''];
+      // Use getLiteralText() to get the raw literal content of template head/middle/tail.
+      const parts: string[] = [expr.getHead().getLiteralText() || ''];
       for (const span of expr.getTemplateSpans()) {
         parts.push(this.resolveClassNameExpression(span.getExpression(), propsContext));
-        parts.push((span.getLiteral().compilerNode as any).text ?? '');
+        parts.push(span.getLiteral().getLiteralText() || '');
       }
       return parts.join(' ').trim().replace(/\s+/g, ' ');
     }
-    if (Node.isIdentifier(expr) || Node.isPropertyAccessExpression(expr)) {
+    if (Node.isIdentifier(expr) || Node.isPropertyAccessExpression(expr) || Node.isElementAccessExpression(expr)) {
       const resolved = this.resolveExpressionValue(expr, propsContext);
       return typeof resolved === 'string' ? resolved : '';
     }
@@ -2403,9 +4173,11 @@ export class ComponentScanner {
       const conditionBool = this.coerceBoolean(conditionValue);
       if (conditionBool === true) return this.resolveClassNameExpression(expr.getWhenTrue(), propsContext);
       if (conditionBool === false) return this.resolveClassNameExpression(expr.getWhenFalse(), propsContext);
-      const fallbackClasses: string[] = [];
-      this.extractClassesFromExpression(expr, fallbackClasses);
-      return [...new Set(fallbackClasses)].join(' ');
+      // Unresolvable condition: prefer the "else" branch so components render in their
+      // neutral/rest state (e.g. inactive nav links without forced `bg-muted`). Active /
+      // hover / focus / error styles are expected to live on the truthy branch and
+      // surface through the dedicated state preview blocks, not the default render.
+      return this.resolveClassNameExpression(expr.getWhenFalse(), propsContext);
     }
     if (Node.isBinaryExpression(expr)) {
       const op = expr.getOperatorToken().getText();
@@ -2420,6 +4192,13 @@ export class ComponentScanner {
         if (left.trim()) return left;
         return this.resolveClassNameExpression(expr.getRight(), propsContext);
       }
+      if (op === '??') {
+        const leftValue = this.resolveExpressionValue(expr.getLeft(), propsContext);
+        if (leftValue !== undefined && leftValue !== null) {
+          return this.resolveClassNameExpression(expr.getLeft(), propsContext);
+        }
+        return this.resolveClassNameExpression(expr.getRight(), propsContext);
+      }
       if (op === '+') {
         const left = this.resolveClassNameExpression(expr.getLeft(), propsContext);
         const right = this.resolveClassNameExpression(expr.getRight(), propsContext);
@@ -2455,12 +4234,107 @@ export class ComponentScanner {
           const value = this.resolveClassNameExpression(arg, propsContext).trim();
           if (value) parts.push(value);
         }
-        return parts.join(' ').trim();
+        return resolveClassConflicts(parts.join(' '));
       }
+      // Try to resolve as a CVA variant function call (e.g., alertVariants({ variant }))
+      const cvaResult = this.resolveCvaFunctionCall(expr, propsContext);
+      if (cvaResult !== null) return cvaResult;
     }
     return '';
   }
 
+  /**
+   * Resolve a CVA variant function call like `alertVariants({ variant })` to its
+   * combined class string. Looks up the function definition in the same source file,
+   * then merges base classes with the appropriate variant classes.
+   */
+  private resolveCvaFunctionCall(callExpr: Node, propsContext: Map<string, ResolvedExpressionValue>): string | null {
+    if (!Node.isCallExpression(callExpr)) return null;
+    const funcName = callExpr.getExpression().getText();
+    const sourceFile = callExpr.getSourceFile();
+
+    // Find `const funcName = cva(...)` in the source file
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        if (decl.getName() !== funcName) continue;
+        const init = decl.getInitializer();
+        if (!init || !Node.isCallExpression(init)) continue;
+        if (init.getExpression().getText() !== 'cva') continue;
+
+        const cvaArgs = init.getArguments();
+        if (cvaArgs.length === 0) return '';
+
+        const baseClasses = this.extractStringValue(cvaArgs[0]);
+        const classes: string[] = baseClasses ? [baseClasses] : [];
+
+        if (cvaArgs.length >= 2 && Node.isObjectLiteralExpression(cvaArgs[1])) {
+          const configObj = cvaArgs[1];
+
+          // Parse the call argument object e.g. { variant } or { variant: "destructive" }
+          const callArgs = callExpr.getArguments();
+          const requestedVariants: Record<string, string> = {};
+          if (callArgs.length > 0 && Node.isObjectLiteralExpression(callArgs[0])) {
+            for (const prop of callArgs[0].getProperties()) {
+              if (Node.isPropertyAssignment(prop)) {
+                const key = prop.getName();
+                const valInit = prop.getInitializer();
+                if (!valInit) continue;
+                const resolved = this.resolveExpressionValue(valInit, propsContext);
+                if (typeof resolved === 'string') requestedVariants[key] = resolved;
+                else if (Node.isStringLiteral(valInit)) requestedVariants[key] = valInit.getLiteralValue();
+              } else if (Node.isShorthandPropertyAssignment(prop)) {
+                // { variant } shorthand — look up value from propsContext
+                const key = prop.getName();
+                const resolved = propsContext.get(key);
+                if (typeof resolved === 'string') requestedVariants[key] = resolved;
+              }
+            }
+          }
+
+          // Extract defaultVariants
+          const defaultVariants: Record<string, string> = {};
+          const defaultVariantsProp = configObj.getProperty('defaultVariants');
+          if (defaultVariantsProp && Node.isPropertyAssignment(defaultVariantsProp)) {
+            const defaultObj = defaultVariantsProp.getInitializer();
+            if (defaultObj && Node.isObjectLiteralExpression(defaultObj)) {
+              for (const prop of defaultObj.getProperties()) {
+                if (!Node.isPropertyAssignment(prop)) continue;
+                const val = this.extractStringValue(prop.getInitializer()!);
+                defaultVariants[prop.getName()] = val.replace(/['"]/g, '');
+              }
+            }
+          }
+
+          // Look up each variant and add its classes
+          const variantsProp = configObj.getProperty('variants');
+          if (variantsProp && Node.isPropertyAssignment(variantsProp)) {
+            const variantsObj = variantsProp.getInitializer();
+            if (variantsObj && Node.isObjectLiteralExpression(variantsObj)) {
+              for (const variantProp of variantsObj.getProperties()) {
+                if (!Node.isPropertyAssignment(variantProp)) continue;
+                const variantName = variantProp.getName();
+                const selectedValue = requestedVariants[variantName] ?? defaultVariants[variantName];
+                if (!selectedValue) continue;
+
+                const variantValuesObj = variantProp.getInitializer();
+                if (!variantValuesObj || !Node.isObjectLiteralExpression(variantValuesObj)) continue;
+
+                const matchedProp = variantValuesObj.getProperty(selectedValue);
+                if (matchedProp && Node.isPropertyAssignment(matchedProp)) {
+                  const variantClassStr = this.extractStringValue(matchedProp.getInitializer()!);
+                  if (variantClassStr) classes.push(variantClassStr);
+                }
+              }
+            }
+          }
+        }
+
+        return resolveClassConflicts(classes.filter(Boolean).join(' '));
+      }
+    }
+    return null;
+  }
+
   /**
    * Extract props from a JSX node (opening element or self-closing element).
    * Uses getDescendantsOfKind to safely get only JsxAttribute nodes,
@@ -2469,13 +4343,13 @@ export class ComponentScanner {
   private extractPropsFromNode(
     jsxNode: Node,
     componentName: string,
-    propsContext: Map<string, any> = new Map()
+    propsContext: Map<string, ResolvedExpressionValue> = new Map()
   ): ComponentInstance {
-    const props: Record<string, any> = {};
+    const props: Record<string, ResolvedExpressionValue> = {};
 
     const directAttributes =
-      typeof (jsxNode as any).getAttributes === 'function'
-        ? ((jsxNode as any).getAttributes() as Node[])
+      Node.isJsxOpeningElement(jsxNode) || Node.isJsxSelfClosingElement(jsxNode)
+        ? jsxNode.getAttributes()
         : [];
     const attributes = directAttributes.length > 0
       ? directAttributes
@@ -2498,7 +4372,8 @@ export class ComponentScanner {
         continue;
       }
 
-      const nameNode = (attr as any).getNameNode?.();
+      if (!Node.isJsxAttribute(attr)) continue;
+      const nameNode = attr.getNameNode();
       if (!nameNode) continue;
       const name = nameNode.getText();
       const init = attr.getInitializer();
@@ -2528,12 +4403,24 @@ export class ComponentScanner {
         if (expr && Node.isStringLiteral(expr)) {
           props[name] = expr.getLiteralValue();
         } else if (expr && Node.isObjectLiteralExpression(expr)) {
-          props[name] = this.parseObjectLiteralExpression(expr);
+          props[name] = this.parseObjectLiteralExpression(expr, propsContext);
         } else if (expr && Node.isArrayLiteralExpression(expr)) {
           props[name] = this.parseLiteralValue(expr);
         } else if (expr) {
           const resolved = this.resolveExpressionValue(expr, propsContext);
-          props[name] = resolved !== undefined ? resolved : expr.getText();
+          if (resolved !== undefined) {
+            props[name] = resolved;
+          }
+          // Unresolved expression (typically an unresolved identifier like a
+          // function parameter with no default — e.g. `data-inset={inset}`
+          // where `inset` is undefined in the story). Falling back to
+          // `expr.getText()` here used to serialise the identifier *name*
+          // as the attribute's value (`"inset"`), which the variant engine
+          // mistook for "data-inset is present" and activated every
+          // `data-[inset]:` utility (e.g. DropdownMenuItem's
+          // `data-[inset]:pl-8`, leaving every item indented 32px when no
+          // story used `inset`). Omitting the prop matches React's runtime
+          // behaviour: `data-x={undefined}` renders no attribute.
         }
       }
     }
@@ -2587,26 +4474,73 @@ export class ComponentScanner {
   // Helper Methods
   // ===========================================================================
 
+  private shouldDeferCvaToCompound(sourceFile: SourceFile, filePath: string): boolean {
+    const topLevelNames = this.getTopLevelComponentNames(sourceFile);
+    if (topLevelNames.length < 2) return false;
+
+    const fileBaseName = path.basename(filePath, '.tsx');
+    const fileComponentName = fileBaseName
+      .split(/[-_]/g)
+      .filter(Boolean)
+      .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+      .join('');
+    if (!fileComponentName) return false;
+
+    // Prefer compound analysis when the file clearly defines a main component
+    // plus subcomponents (e.g. pagination.tsx, dialog.tsx).
+    return topLevelNames.indexOf(fileComponentName) !== -1;
+  }
+
+  private getTopLevelComponentNames(sourceFile: SourceFile): string[] {
+    const names = new Set<string>();
+
+    for (const statement of sourceFile.getVariableStatements()) {
+      const declarations = statement.getDeclarationList().getDeclarations();
+      for (const decl of declarations) {
+        const name = decl.getName();
+        if (/^[A-Z]/.test(name)) names.add(name);
+      }
+    }
+
+    for (const func of sourceFile.getFunctions()) {
+      const name = func.getName();
+      if (name && /^[A-Z]/.test(name)) names.add(name);
+    }
+
+    return Array.from(names);
+  }
+
   /**
    * Find all component declarations in a file
    */
   private findComponentDeclarations(sourceFile: SourceFile): Array<{ name: string; node: Node }> {
     const components: Array<{ name: string; node: Node }> = [];
+    const seen = new Set<string>();
 
-    // Find variable statements that export components
+    // Find variable declarations that look like components.
     const variableStatements = sourceFile.getDescendantsOfKind(SyntaxKind.VariableStatement);
 
     for (const statement of variableStatements) {
       const declarations = statement.getDeclarationList().getDeclarations();
       for (const decl of declarations) {
         const name = decl.getName();
-        // Component names start with uppercase
-        if (/^[A-Z]/.test(name)) {
+        if (/^[A-Z]/.test(name) && !seen.has(name)) {
           components.push({ name, node: decl });
+          seen.add(name);
         }
       }
     }
 
+    // Also include function declarations (shadcn files often use function syntax).
+    const functions = sourceFile.getFunctions();
+    for (const func of functions) {
+      const name = func.getName();
+      if (name && /^[A-Z]/.test(name) && !seen.has(name)) {
+        components.push({ name, node: func });
+        seen.add(name);
+      }
+    }
+
     return components;
   }