inkhouse 0.1.0-beta.0

package/scanner/component-scanner.ts

@@ -0,0 +1,2876 @@
+/**
+ * Component Scanner
+ *
+ * Scans React component files and detects their type:
+ * - CVA: Components using class-variance-authority
+ * - Compound: Multiple sub-components with cn() classes
+ * - State: Components with Tailwind state modifiers
+ * - Simple: Components with static classes
+ */
+
+import { Project, SyntaxKind, Node, SourceFile } from 'ts-morph';
+import * as path from 'path';
+import * as fs from 'fs';
+import type {
+  ComponentAnalysis,
+  CVAComponentAnalysis,
+  CompoundComponentAnalysis,
+  StateComponentAnalysis,
+  SimpleComponentAnalysis,
+  SubComponentInfo,
+  StateInfo,
+  StoryInfo,
+  ComponentInstance,
+  ScannerConfig,
+  JsxNode,
+  JsxElement,
+  JsxText,
+  IconImportSpec,
+} from './types';
+import { groupClassesByState, STATE_MODIFIERS } from './tailwind-parser';
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const HTML_ENTITIES: Record<string, string> = {
+  '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"',
+  '&apos;': "'", '&nbsp;': '\u00a0', '&rarr;': '→', '&larr;': '←',
+  '&rArr;': '⇒', '&lArr;': '⇐', '&hellip;': '…', '&mdash;': '—', '&ndash;': '–',
+};
+
+function decodeHtmlEntities(text: string): string {
+  return text.replace(/&[a-zA-Z]+;/g, (entity) => HTML_ENTITIES[entity] ?? entity);
+}
+
+// ============================================================================
+// Component to HTML Element Mapping
+// ============================================================================
+
+/**
+ * Maps React/Next.js components to their HTML element equivalents.
+ * These components are treated as HTML elements in the JSX tree output.
+ */
+const COMPONENT_TO_HTML_MAP: Record<string, string> = {
+  Link: 'a',  // next/link
+};
+
+// ============================================================================
+// Scanner Class
+// ============================================================================
+
+export class ComponentScanner {
+  private project: Project;
+  private config: ScannerConfig;
+  private iconImports: Map<string, IconImportSpec>;
+  // 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[]>;
+
+  constructor(config: ScannerConfig) {
+    this.config = config;
+    this.project = new Project({
+      tsConfigFilePath: path.resolve(process.cwd(), 'tsconfig.json'),
+      skipAddingFilesFromTsConfig: true,
+    });
+    this.iconImports = new Map();
+    this.importedComponentCache = new Map();
+    this.arrayValueCache = new Map();
+  }
+
+  /**
+   * Scan all components in configured paths
+   */
+  async scanAll(): Promise<ComponentAnalysis[]> {
+    const analyses: ComponentAnalysis[] = [];
+    const seenPaths = new Set<string>();
+
+    for (const componentPath of this.config.componentPaths) {
+      const fullPath = path.resolve(process.cwd(), componentPath);
+      const files = this.project.addSourceFilesAtPaths(`${fullPath}/${this.config.filePattern}`);
+
+      for (const file of files) {
+        const filePath = file.getFilePath();
+        const fileName = path.basename(filePath, '.tsx');
+
+        // Deduplicate (overlapping componentPaths may match same files)
+        if (seenPaths.has(filePath)) continue;
+        seenPaths.add(filePath);
+
+        // Skip excluded components, test files, and story files
+        if (this.config.exclude.includes(fileName)) continue;
+        if (fileName.endsWith('.test') || fileName.endsWith('.stories')) continue;
+
+        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)) {
+              analysis.hasStory = true;
+              try {
+                analysis.stories = this.parseStories(storyPath);
+              } catch (storyErr) {
+                console.warn(`  Failed to parse stories for ${fileName}:`, storyErr);
+                analysis.stories = [];
+              }
+            }
+
+            analyses.push(analysis);
+          }
+        } catch (err) {
+          console.warn(`Failed to analyze ${fileName}:`, err);
+        }
+      }
+    }
+
+    if (!this.config.onlyWithStories) return analyses;
+    return this.filterAnalysesByStoryReachability(analyses);
+  }
+
+  private filterAnalysesByStoryReachability(analyses: ComponentAnalysis[]): ComponentAnalysis[] {
+    if (analyses.length === 0) return analyses;
+
+    const byName = new Map<string, ComponentAnalysis>();
+    const byNormalized = new Map<string, ComponentAnalysis[]>();
+    const normalize = (value: string): string => value.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+
+    for (const analysis of analyses) {
+      if (analysis.name) {
+        byName.set(analysis.name, analysis);
+        const key = normalize(analysis.name);
+        const list = byNormalized.get(key) || [];
+        list.push(analysis);
+        byNormalized.set(key, list);
+      }
+    }
+
+    const keep = new Set<ComponentAnalysis>();
+    const queue: ComponentAnalysis[] = [];
+    for (const analysis of analyses) {
+      if (analysis.hasStory) {
+        keep.add(analysis);
+        queue.push(analysis);
+      }
+    }
+
+    while (queue.length > 0) {
+      const current = queue.shift() as ComponentAnalysis;
+      const deps = this.collectStoryComponentRefs(current);
+      for (const depName of deps) {
+        let dep = byName.get(depName);
+        if (!dep) {
+          const normalizedHits = byNormalized.get(normalize(depName)) || [];
+          if (normalizedHits.length === 1) {
+            dep = normalizedHits[0];
+          }
+        }
+        if (!dep || keep.has(dep)) continue;
+        keep.add(dep);
+        queue.push(dep);
+      }
+    }
+
+    return analyses.filter(analysis => keep.has(analysis));
+  }
+
+  private collectStoryComponentRefs(analysis: ComponentAnalysis): Set<string> {
+    const refs = new Set<string>();
+    const stories = analysis.stories || [];
+    const visit = (node: JsxNode | undefined): void => {
+      if (!node || node.type !== 'element') return;
+      const el = node as JsxElement;
+      const tagName = el.tagName || '';
+      if (/^[A-Z]/.test(tagName)) {
+        refs.add(tagName);
+      }
+      const children = el.children || [];
+      for (let i = 0; i < children.length; i++) {
+        visit(children[i]);
+      }
+    };
+
+    for (let i = 0; i < stories.length; i++) {
+      visit(stories[i].jsxTree as JsxNode | undefined);
+    }
+    return refs;
+  }
+
+  /**
+   * Analyze a single component file
+   */
+  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);
+    if (cvaAnalysis) {
+      return cvaAnalysis;
+    }
+
+    // Check for compound component pattern (multiple exports with cn())
+    const compoundAnalysis = this.analyzeCompound(sourceFile, filePath);
+    if (compoundAnalysis) {
+      return compoundAnalysis;
+    }
+
+    // Check for state-based component (Tailwind modifiers)
+    const stateAnalysis = this.analyzeState(sourceFile, filePath);
+    if (stateAnalysis) {
+      return stateAnalysis;
+    }
+
+    // Fall back to simple component
+    const simpleAnalysis = this.analyzeSimple(sourceFile, filePath);
+    return simpleAnalysis;
+  }
+
+  // ===========================================================================
+  // CVA Analysis
+  // ===========================================================================
+
+  private analyzeCVA(sourceFile: SourceFile, filePath: string): CVAComponentAnalysis | null {
+    // Find cva() call expressions
+    const cvaCalls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)
+      .filter(call => call.getExpression().getText() === 'cva');
+
+    if (cvaCalls.length === 0) {
+      return null;
+    }
+
+    const cvaCall = cvaCalls[0];
+    const args = cvaCall.getArguments();
+
+    if (args.length < 2) {
+      return null;
+    }
+
+    // Parse base classes (first argument)
+    const baseClassesArg = args[0];
+    const baseClasses = this.extractStringValue(baseClassesArg);
+
+    // Parse config object (second argument)
+    const configArg = args[1];
+    if (!Node.isObjectLiteralExpression(configArg)) {
+      return null;
+    }
+
+    const variants: Record<string, string[]> = {};
+    const defaultVariants: Record<string, string> = {};
+    const variantClasses: Record<string, Record<string, string[]>> = {};
+
+    // Extract variants property
+    const variantsProp = configArg.getProperty('variants');
+    if (variantsProp && Node.isPropertyAssignment(variantsProp)) {
+      const variantsObj = variantsProp.getInitializer();
+      if (variantsObj && Node.isObjectLiteralExpression(variantsObj)) {
+        for (const prop of variantsObj.getProperties()) {
+          if (Node.isPropertyAssignment(prop)) {
+            const variantName = prop.getName();
+            const variantValues = prop.getInitializer();
+
+            if (variantValues && Node.isObjectLiteralExpression(variantValues)) {
+              variants[variantName] = [];
+              variantClasses[variantName] = {};
+
+              for (const valueProp of variantValues.getProperties()) {
+                if (Node.isPropertyAssignment(valueProp)) {
+                  const valueName = valueProp.getName();
+                  const classString = this.extractStringValue(valueProp.getInitializer()!);
+
+                  variants[variantName].push(valueName);
+                  variantClasses[variantName][valueName] = classString.split(/\s+/).filter(Boolean);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Extract defaultVariants property
+    const defaultVariantsProp = configArg.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)) {
+            const name = prop.getName();
+            const value = this.extractStringValue(prop.getInitializer()!);
+            defaultVariants[name] = value.replace(/['"]/g, '');
+          }
+        }
+      }
+    }
+
+    // Infer component name from variable name
+    const parent = cvaCall.getParent();
+    let name = path.basename(filePath, '.tsx');
+    if (Node.isVariableDeclaration(parent)) {
+      const varName = parent.getName();
+      // buttonVariants -> Button
+      name = varName.replace(/Variants$/, '');
+      name = name.charAt(0).toUpperCase() + name.slice(1);
+    }
+
+    return {
+      type: 'cva',
+      name,
+      filePath,
+      baseClasses: baseClasses.split(/\s+/).filter(Boolean),
+      variants,
+      defaultVariants,
+      variantClasses,
+    };
+  }
+
+  // ===========================================================================
+  // Compound Component Analysis
+  // ===========================================================================
+
+  private analyzeCompound(sourceFile: SourceFile, filePath: string): CompoundComponentAnalysis | null {
+    // Find all variable declarations that look like components
+    // Pattern: const ComponentName = React.forwardRef<...>(...) or const ComponentName = ...
+    const componentDeclarations = this.findComponentDeclarations(sourceFile);
+
+    if (componentDeclarations.length < 2) {
+      return null;
+    }
+
+    const subComponents: SubComponentInfo[] = [];
+
+    for (const { name, node } of componentDeclarations) {
+      const classes = this.extractClassesFromNode(node);
+      if (classes.length > 0) {
+        subComponents.push({
+          name,
+          classes,
+          slot: this.inferSlot(name),
+        });
+      }
+    }
+
+    if (subComponents.length < 2) {
+      return null;
+    }
+
+    // Use filename as the authoritative component name (e.g. "select.tsx" → "Select"),
+    // same convention as analyzeSimple. The old heuristic (shortest subcomponent name)
+    // breaks when the root component (e.g. "Select") has no classes and is filtered out,
+    // leaving a longer sub-component like "SelectItem" as the winner.
+    const fileBaseName = path.basename(filePath, '.tsx');
+    const mainName = fileBaseName.charAt(0).toUpperCase() + fileBaseName.slice(1);
+
+    return {
+      type: 'compound',
+      name: mainName,
+      filePath,
+      subComponents,
+    };
+  }
+
+  // ===========================================================================
+  // State-based Component Analysis
+  // ===========================================================================
+
+  private analyzeState(sourceFile: SourceFile, filePath: string): StateComponentAnalysis | null {
+    const allClasses = this.extractAllClassesFromFile(sourceFile);
+
+    if (allClasses.length === 0) {
+      return null;
+    }
+
+    // Check if any classes have state modifiers
+    const hasStateModifiers = allClasses.some(cls =>
+      STATE_MODIFIERS.some(mod => cls.startsWith(mod))
+    );
+
+    if (!hasStateModifiers) {
+      return null;
+    }
+
+    if (!this.hasRootStateModifier(sourceFile, filePath)) {
+      return null;
+    }
+
+    const groupedClasses = groupClassesByState(allClasses);
+
+    // Need at least 2 states (default + something else)
+    if (Object.keys(groupedClasses).length < 2) {
+      return null;
+    }
+
+    const states: Record<string, StateInfo> = {};
+
+    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 === 'error') trigger = 'aria-invalid:';
+      else if (stateName === 'active') trigger = 'active:';
+      else if (stateName === 'checked') trigger = 'data-[state=checked]:';
+      else if (stateName === 'open') trigger = 'data-[state=open]:';
+
+      states[stateName] = {
+        classes,
+        trigger,
+      };
+    }
+
+    const name = path.basename(filePath, '.tsx');
+
+    return {
+      type: 'state',
+      name: name.charAt(0).toUpperCase() + name.slice(1),
+      filePath,
+      baseClasses: groupedClasses.default || [],
+      states,
+    };
+  }
+
+  private hasRootStateModifier(sourceFile: SourceFile, filePath: string): boolean {
+    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 false;
+    }
+
+    const root = jsxTree as JsxElement;
+    const className = root.props && typeof root.props.className === 'string'
+      ? 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)) {
+        return false;
+      }
+      // Keep state analysis for primitives that use dynamic className builders
+      // (e.g. <input className={cn(...focus-visible:...)} />).
+      return true;
+    }
+
+    const classes = className.split(/\s+/).filter(Boolean);
+    for (const cls of classes) {
+      for (const modifier of STATE_MODIFIERS) {
+        if (cls.startsWith(modifier)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  private getComponentNameCandidates(filePath: string): string[] {
+    const rawName = path.basename(filePath, '.tsx');
+    const candidates: string[] = [];
+    const direct = rawName.charAt(0).toUpperCase() + rawName.slice(1);
+    if (direct) candidates.push(direct);
+    const pascal = rawName
+      .split(/[-_]/g)
+      .filter(Boolean)
+      .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+      .join('');
+    if (pascal && candidates.indexOf(pascal) === -1) candidates.push(pascal);
+    return candidates;
+  }
+
+  // ===========================================================================
+  // Simple Component Analysis
+  // ===========================================================================
+
+  private analyzeSimple(sourceFile: SourceFile, filePath: string): SimpleComponentAnalysis | null {
+    const classes = this.extractAllClassesFromFile(sourceFile);
+    // Don't bail on empty classes — stub components (returning null) have no classes
+    // but their stories carry all the rendering data. The onlyWithStories filter
+    // handles truly empty components downstream.
+
+    const name = path.basename(filePath, '.tsx');
+    const componentName = name.charAt(0).toUpperCase() + name.slice(1);
+
+    // Also try PascalCase (e.g. "hero-section" → "HeroSection") for components
+    // whose export name doesn't match the simple first-letter-uppercased file name.
+    const pascalName = name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())
+      .replace(/^[a-z]/, (c: string) => c.toUpperCase());
+
+    // Try to capture the component's JSX tree structure
+    const jsxTree = this.extractComponentJsxTree(sourceFile, componentName)
+      ?? (pascalName !== componentName ? this.extractComponentJsxTree(sourceFile, pascalName) : null);
+
+    const analysis: SimpleComponentAnalysis = {
+      type: 'simple',
+      name: componentName,
+      filePath,
+      classes,
+    };
+
+    if (jsxTree) {
+      analysis.jsxTree = jsxTree;
+    }
+
+    return analysis;
+  }
+
+  /**
+   * Extract the JSX tree from the main component function in a source file.
+   * This preserves the element structure including decorative elements with styles.
+   */
+  private extractComponentJsxTree(sourceFile: SourceFile, componentName: string): JsxNode | null {
+    const relativeImports = this.collectComponentImports(sourceFile);
+
+    const localComponents = this.collectLocalComponentsFromFile(sourceFile);
+
+    // Look for: export function ComponentName() { ... }
+    for (const func of sourceFile.getFunctions()) {
+      if (func.getName() === componentName && func.isExported()) {
+        const jsxTree = this.extractJsxTreeFromFunctionBody(func, relativeImports, localComponents);
+        if (jsxTree) return jsxTree;
+      }
+    }
+
+    // Look for: export const ComponentName = () => { ... } or forwardRef
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      if (!varStmt.isExported()) continue;
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        if (decl.getName() === componentName) {
+          const init = decl.getInitializer();
+          if (init) {
+            const jsxTree = this.extractJsxTreeFromFunctionBody(init, relativeImports, localComponents);
+            if (jsxTree) return jsxTree;
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract JSX tree from a function body (arrow function, function expression, or function declaration).
+   */
+  private extractJsxTreeFromFunctionBody(
+    funcNode: Node,
+    relativeImports: Map<string, string>,
+    localComponents: Map<string, Node>
+  ): JsxNode | null {
+    const jsxElements = funcNode.getDescendantsOfKind(SyntaxKind.JsxElement);
+    const selfClosing = funcNode.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+    const allJsx = [...jsxElements, ...selfClosing];
+
+    if (allJsx.length === 0) return null;
+
+    // Find root JSX (fewest ancestors)
+    let rootJsx = allJsx[0];
+    for (const el of allJsx) {
+      if (el.getAncestors().length < rootJsx.getAncestors().length) {
+        rootJsx = el;
+      }
+    }
+
+    return this.buildJsxTree(rootJsx, localComponents, relativeImports);
+  }
+
+  // ===========================================================================
+  // Story Parsing
+  // ===========================================================================
+
+  /**
+   * Parse a Storybook *.stories.tsx file and extract individual stories
+   * with their component instances, props, and layout.
+   */
+  parseStories(storyFilePath: string): StoryInfo[] {
+    const sourceFile = this.project.addSourceFileAtPath(storyFilePath);
+    const stories: StoryInfo[] = [];
+    const iconImports = this.collectReactIconImports(sourceFile);
+    let metaDecoratorWrappers: Array<{ tagName: string; classes: string[] }> = [];
+
+    // Collect import names to identify which JSX tags are component usages.
+    // Also track import targets for component expansion.
+    const importedComponents = new Set<string>();
+    const relativeImports = this.collectComponentImports(sourceFile);
+
+    for (const imp of sourceFile.getImportDeclarations()) {
+      for (const named of imp.getNamedImports()) {
+        const localName = named.getAliasNode()?.getText() || named.getName();
+        if (/^[A-Z]/.test(localName)) {
+          importedComponents.add(localName);
+        }
+      }
+      const defaultImport = imp.getDefaultImport();
+      if (defaultImport && /^[A-Z]/.test(defaultImport.getText())) {
+        importedComponents.add(defaultImport.getText());
+      }
+    }
+
+    // Collect local component definitions (const X = () => JSX)
+    // These are components defined in the story file itself
+    const localComponents = new Map<string, Node>();
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      if (varStmt.isExported()) continue; // Skip exports (these are stories)
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        const name = decl.getName();
+        if (/^[A-Z]/.test(name)) {
+          const init = decl.getInitializer();
+          if (init && Node.isArrowFunction(init)) {
+            // Find the JSX return in the arrow function
+            const body = init.getBody();
+            if (body) {
+              localComponents.set(name, body);
+            }
+          }
+        }
+      }
+    }
+
+    // Also check function declarations for local components
+    for (const func of sourceFile.getFunctions()) {
+      const name = func.getName();
+      if (name && /^[A-Z]/.test(name) && !func.isExported()) {
+        localComponents.set(name, func);
+      }
+    }
+
+    // Find the meta's component name (from `component: Button`)
+    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();
+          if (init && Node.isObjectLiteralExpression(init)) {
+            const compProp = init.getProperty('component');
+            if (compProp && Node.isPropertyAssignment(compProp)) {
+              metaComponentName = compProp.getInitializer()?.getText();
+            }
+            const decoratorsProp = init.getProperty('decorators');
+            metaDecoratorWrappers = this.extractDecoratorWrappers(decoratorsProp);
+          }
+        }
+      }
+    }
+
+    // Find all exported const declarations that are stories (not `meta` or `default`)
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      if (!varStmt.isExported()) continue;
+
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        const storyName = decl.getName();
+        if (storyName === 'meta' || storyName === 'default') continue;
+
+        const init = decl.getInitializer();
+        if (!init || !Node.isObjectLiteralExpression(init)) continue;
+
+        const story: StoryInfo = {
+          name: storyName,
+          instances: [],
+        };
+        const storyDecoratorWrappers = this.extractDecoratorWrappers(
+          init.getProperty('decorators')
+        );
+
+        // Check for `args` property
+        const argsProp = init.getProperty('args');
+        if (argsProp && Node.isPropertyAssignment(argsProp)) {
+          const argsInit = argsProp.getInitializer();
+          if (argsInit && Node.isObjectLiteralExpression(argsInit)) {
+            const args: Record<string, string> = {};
+            for (const prop of argsInit.getProperties()) {
+              if (Node.isPropertyAssignment(prop)) {
+                const propInit = prop.getInitializer();
+                if (propInit) {
+                  args[prop.getName()] = this.extractStringValue(propInit);
+                }
+              }
+            }
+            story.args = args;
+
+            if (metaComponentName) {
+              const instance: ComponentInstance = {
+                componentName: metaComponentName,
+                props: { ...args },
+                children: args.children,
+              };
+              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;
+                  }
+                  story.jsxTree = this.buildJsxTree(root, localComponents, relativeImports);
+                }
+              }
+            }
+          }
+        }
+
+        // Check for `render` property
+        const renderProp = init.getProperty('render');
+        if (renderProp && Node.isPropertyAssignment(renderProp)) {
+          const renderInit = renderProp.getInitializer();
+          if (renderInit) {
+            this.extractJsxInstances(renderInit, importedComponents, localComponents, relativeImports, story);
+          }
+        }
+
+        // Check for method-style `render()`
+        const renderMethod = init.getProperty('render');
+        if (renderMethod && Node.isMethodDeclaration(renderMethod)) {
+          this.extractJsxInstances(renderMethod, importedComponents, localComponents, relativeImports, story);
+        }
+
+        const decoratorWrappers = metaDecoratorWrappers.concat(storyDecoratorWrappers);
+        if (decoratorWrappers.length > 0) {
+          if (story.jsxTree) {
+            story.jsxTree = this.wrapJsxTreeWithDecorators(story.jsxTree, decoratorWrappers);
+          }
+          if (!story.layoutClasses || story.layoutClasses.length === 0) {
+            const merged = this.flattenDecoratorClasses(decoratorWrappers);
+            if (merged.length > 0) {
+              story.layoutClasses = merged;
+            }
+          }
+        }
+
+        if (story.jsxTree) {
+          this.collectIconUsage(story.jsxTree, iconImports);
+        }
+
+        stories.push(story);
+      }
+    }
+
+    return stories;
+  }
+
+  /**
+   * Extract component instances from JSX within a render function.
+   * Also builds the full JSX tree for recursive rendering.
+   */
+  private extractJsxInstances(
+    node: Node,
+    importedComponents: Set<string>,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>,
+    story: StoryInfo
+  ): void {
+    // Find all JSX elements
+    const jsxElements = node.getDescendantsOfKind(SyntaxKind.JsxElement);
+    const selfClosingElements = node.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+
+    // Find the root JSX element (fewest ancestors)
+    const allJsx: Node[] = [...jsxElements, ...selfClosingElements];
+    if (allJsx.length > 0) {
+      let root = allJsx[0];
+      for (const el of allJsx) {
+        if (el.getAncestors().length < root.getAncestors().length) root = el;
+      }
+
+      // Build the full JSX tree from the root, expanding local and imported components
+      story.jsxTree = this.buildJsxTree(root, localComponents, relativeImports);
+
+      // Extract layout classes from root element (any tag, not just div)
+      let attrs: any[] = [];
+      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?.();
+        return nameNode ? nameNode.getText() === 'className' : false;
+      });
+      if (classAttr) {
+        const value = classAttr.getInitializer();
+        if (value && Node.isStringLiteral(value)) {
+          story.layoutClasses = value.getLiteralValue().split(/\s+/).filter(Boolean);
+        }
+      }
+    }
+
+    // Also extract flat component instances (for backward compatibility)
+    for (const el of jsxElements) {
+      const tagName = el.getOpeningElement().getTagNameNode().getText();
+      if (importedComponents.has(tagName)) {
+        const instance = this.extractInstanceFromJsxOpening(
+          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;
+        }
+        story.instances.push(instance);
+      }
+    }
+
+    for (const el of selfClosingElements) {
+      const tagName = el.getTagNameNode().getText();
+      if (importedComponents.has(tagName)) {
+        const instance = this.extractInstanceFromSelfClosing(el, tagName);
+        story.instances.push(instance);
+      }
+    }
+  }
+
+  private extractDecoratorWrappers(
+    decoratorsProp: Node | undefined
+  ): Array<{ tagName: string; classes: string[] }> {
+    if (!decoratorsProp || !Node.isPropertyAssignment(decoratorsProp)) return [];
+    const init = decoratorsProp.getInitializer();
+    if (!init || !Node.isArrayLiteralExpression(init)) return [];
+    const wrappers: Array<{ tagName: string; classes: string[] }> = [];
+
+    for (const element of init.getElements()) {
+      let bodyNode: Node | undefined = element;
+      if (Node.isArrowFunction(element) || Node.isFunctionExpression(element)) {
+        bodyNode = element.getBody();
+        if (bodyNode && Node.isParenthesizedExpression(bodyNode)) {
+          bodyNode = bodyNode.getExpression();
+        }
+      }
+
+      if (!bodyNode) continue;
+
+      const allJsx: Node[] = [];
+      if (Node.isJsxElement(bodyNode) || Node.isJsxSelfClosingElement(bodyNode)) {
+        allJsx.push(bodyNode);
+      }
+      const jsxElements = bodyNode.getDescendantsOfKind(SyntaxKind.JsxElement);
+      const selfClosing = bodyNode.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+      allJsx.push(...jsxElements, ...selfClosing);
+      if (allJsx.length === 0) continue;
+
+      let root = allJsx[0];
+      for (const el of allJsx) {
+        if (el.getAncestors().length < root.getAncestors().length) root = el;
+      }
+
+      const result = this.extractLayoutClassesFromRoot(root);
+      if (result && result.classes.length > 0) {
+        wrappers.push(result);
+      }
+    }
+
+    return wrappers;
+  }
+
+  private flattenDecoratorClasses(wrappers: Array<{ tagName: string; classes: string[] }>): string[] {
+    const out: string[] = [];
+    for (const wrapper of wrappers) {
+      for (const cls of wrapper.classes) {
+        out.push(cls);
+      }
+    }
+    return out;
+  }
+
+  private wrapJsxTreeWithDecorators(tree: JsxNode, wrappers: Array<{ tagName: string; classes: string[] }>): JsxNode {
+    let current = tree;
+    for (const wrapper of wrappers) {
+      if (!wrapper || wrapper.classes.length === 0) continue;
+      current = {
+        type: 'element',
+        tagName: wrapper.tagName,
+        isComponent: false,
+        props: { className: wrapper.classes.join(' ') },
+        children: [current],
+      };
+    }
+    return current;
+  }
+
+  private static readonly DECORATOR_BLOCK_TAGS = new Set([
+    'div', 'header', 'nav', 'section', 'main', 'footer', 'article', 'aside',
+  ]);
+
+  private extractLayoutClassesFromRoot(root: Node): { tagName: string; classes: string[] } | null {
+    let tagName = '';
+    let attrs: any[] = [];
+    if (Node.isJsxElement(root)) {
+      tagName = root.getOpeningElement().getTagNameNode().getText();
+      attrs = root.getOpeningElement().getDescendantsOfKind(SyntaxKind.JsxAttribute);
+    } else if (Node.isJsxSelfClosingElement(root)) {
+      tagName = root.getTagNameNode().getText();
+      attrs = root.getDescendantsOfKind(SyntaxKind.JsxAttribute);
+    }
+    if (!ComponentScanner.DECORATOR_BLOCK_TAGS.has(tagName.toLowerCase())) return null;
+    const classAttr = attrs.find(a => {
+      const nameNode = (a as any).getNameNode?.();
+      return nameNode ? nameNode.getText() === 'className' : false;
+    });
+    if (!classAttr) return null;
+    const value = classAttr.getInitializer();
+    if (value && Node.isStringLiteral(value)) {
+      const classes = value.getLiteralValue().split(/\s+/).filter(Boolean);
+      return { tagName: tagName.toLowerCase(), classes };
+    }
+    return null;
+  }
+
+  private resolveImportedComponentPath(baseDir: string, moduleSpec: string): string | null {
+    let importBasePath: string | null = null;
+
+    if (moduleSpec.startsWith('./') || moduleSpec.startsWith('../')) {
+      importBasePath = path.resolve(baseDir, moduleSpec);
+    } else if (moduleSpec.startsWith('~/')) {
+      importBasePath = path.resolve(process.cwd(), 'src', moduleSpec.slice(2));
+    }
+
+    if (!importBasePath) return null;
+
+    const candidates = [
+      importBasePath,
+      `${importBasePath}.tsx`,
+      `${importBasePath}.ts`,
+      path.join(importBasePath, 'index.tsx'),
+      path.join(importBasePath, 'index.ts'),
+    ];
+
+    for (const candidate of candidates) {
+      if (!fs.existsSync(candidate)) continue;
+      const stat = fs.statSync(candidate);
+      if (stat.isFile()) return candidate;
+    }
+
+    return null;
+  }
+
+  private collectComponentImports(sourceFile: SourceFile): Map<string, string> {
+    const imports = new Map<string, string>();
+    const fileDir = path.dirname(sourceFile.getFilePath());
+
+    for (const imp of sourceFile.getImportDeclarations()) {
+      const moduleSpec = imp.getModuleSpecifierValue();
+      const resolvedPath = this.resolveImportedComponentPath(fileDir, moduleSpec);
+      if (!resolvedPath) continue;
+
+      for (const named of imp.getNamedImports()) {
+        const localName = named.getAliasNode()?.getText() || named.getName();
+        if (/^[A-Z]/.test(localName)) {
+          imports.set(localName, resolvedPath);
+        }
+      }
+
+      const defaultImport = imp.getDefaultImport();
+      if (defaultImport) {
+        const localName = defaultImport.getText();
+        if (/^[A-Z]/.test(localName)) {
+          imports.set(localName, resolvedPath);
+        }
+      }
+    }
+
+    return imports;
+  }
+
+  /**
+   * Recursively build a JSX tree from a ts-morph JSX node.
+   * Expands local component definitions and imported view components inline.
+   * @param propsContext - Resolved prop values from parent context (e.g., arrays passed from story)
+   */
+  private buildJsxTree(
+    node: Node,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string> = new Map(),
+    propsContext: Map<string, any> = new Map()
+  ): JsxNode {
+    if (Node.isJsxElement(node)) {
+      const rawTagName = node.getOpeningElement().getTagNameNode().getText();
+      // Map known components to HTML elements (e.g., Link -> a)
+      const tagName = COMPONENT_TO_HTML_MAP[rawTagName] || rawTagName;
+      const props = this.extractPropsFromNode(node.getOpeningElement(), rawTagName, propsContext).props;
+      const children: JsxNode[] = [];
+
+      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);
+        } else if (Node.isJsxText(child)) {
+          const text = decodeHtmlEntities(child.getText().trim());
+          if (text) {
+            children.push({ type: 'text', content: text });
+          }
+        } else if (Node.isJsxExpression(child)) {
+          const expr = child.getExpression();
+          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
+            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 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() });
+              }
+            }
+          } else if (expr && Node.isPropertyAccessExpression(expr)) {
+            // Resolve {plan.name} style expressions when `plan` is an object in propsContext
+            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(children, obj[propName]);
+              }
+            }
+          } else if (expr) {
+            const exprText = expr.getText();
+            // Skip conditional expressions - they don't render well in Figma design system
+            const isConditional = exprText.includes('?') || exprText.includes('&&') || exprText.includes('||');
+            const isFunction = exprText.includes('=>') || exprText.includes('function');
+            if (exprText && !isConditional && !isFunction) {
+              // Only include simple variable references like {userName}
+              children.push({ type: 'text', content: `{${exprText}}` });
+            }
+          }
+        }
+      }
+
+      if (/^[A-Z]/.test(rawTagName)) {
+        const evaluatedProps = this.resolveInvocationProps(props, node.getSourceFile(), propsContext);
+        if (children.length > 0) {
+          evaluatedProps.children = children;
+        }
+
+        const localDef = localComponents.get(rawTagName);
+        if (localDef) {
+          const expandedLocal = this.expandLocalComponentWithProps(localDef, evaluatedProps, localComponents, relativeImports);
+          if (expandedLocal) {
+            return expandedLocal;
+          }
+        }
+
+        const importedFilePath = relativeImports.get(rawTagName);
+        const SKIP_EXPANSION_MAIN = ['Skeleton', 'SkeletonText'];
+        if (importedFilePath && !SKIP_EXPANSION_MAIN.includes(rawTagName)) {
+          const resolvedProps = new Map<string, any>();
+          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;
+            }
+            if (!this.isUnresolvedExpandedComponent(expandedImported, localComponents, relativeImports)) {
+              return expandedImported;
+            }
+          }
+        }
+      }
+
+      const outputProps = { ...props } as Record<string, any>;
+      delete outputProps.children;
+      return {
+        type: 'element',
+        tagName,
+        isComponent: /^[A-Z]/.test(tagName),
+        props: outputProps,
+        children,
+      };
+    } else if (Node.isJsxSelfClosingElement(node)) {
+      const rawTagName = node.getTagNameNode().getText();
+      // Map known components to HTML elements (e.g., Link -> a)
+      const tagName = COMPONENT_TO_HTML_MAP[rawTagName] || rawTagName;
+      const props = this.extractPropsFromNode(node, rawTagName, propsContext).props;
+      const evaluatedProps = this.resolveInvocationProps(props, node.getSourceFile(), propsContext);
+      const children: JsxNode[] = [];
+      if (Object.prototype.hasOwnProperty.call(evaluatedProps, 'children')) {
+        this.pushResolvedPropValue(children, evaluatedProps.children);
+      }
+
+      // Check if this is a local component that should be expanded
+      const localDef = localComponents.get(rawTagName);
+      if (localDef) {
+        const expandedLocal = this.expandLocalComponentWithProps(localDef, evaluatedProps, localComponents, relativeImports);
+        if (expandedLocal) {
+          return expandedLocal;
+        }
+      }
+
+      // 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 importedFilePath = relativeImports.get(rawTagName);
+      if (importedFilePath && !SKIP_EXPANSION_MAIN.includes(rawTagName)) {
+        const resolvedProps = new Map<string, any>();
+        for (const [key, value] of Object.entries(evaluatedProps)) {
+          resolvedProps.set(key, value);
+        }
+
+        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;
+          }
+          if (!this.isUnresolvedExpandedComponent(expandedJsx, localComponents, relativeImports)) {
+            return expandedJsx;
+          }
+        }
+      }
+
+      const outputProps = { ...props } as Record<string, any>;
+      delete outputProps.children;
+      return {
+        type: 'element',
+        tagName,
+        isComponent: /^[A-Z]/.test(tagName),
+        props: outputProps,
+        children,
+      };
+    }
+
+    // Fallback for unexpected node types
+    return { type: 'text', content: '' };
+  }
+
+  private cloneJsxNode(node: JsxNode): JsxNode {
+    if (node.type === 'text') {
+      return { type: 'text', content: (node as JsxText).content };
+    }
+    const el = node as JsxElement;
+    const children: JsxNode[] = [];
+    for (let i = 0; i < (el.children || []).length; i++) {
+      children.push(this.cloneJsxNode(el.children[i]));
+    }
+    return {
+      type: 'element',
+      tagName: el.tagName,
+      isComponent: el.isComponent,
+      props: Object.assign({}, el.props || {}),
+      children,
+    };
+  }
+
+  private pushResolvedPropValue(children: JsxNode[], value: any): void {
+    if (value == null || value === '') return;
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        if (item == null || item === '') continue;
+        if (typeof item === 'object' && item.type && (item.type === 'text' || item.type === 'element')) {
+          children.push(this.cloneJsxNode(item as JsxNode));
+        } else {
+          children.push({ type: 'text', content: String(item) });
+        }
+      }
+      return;
+    }
+    if (typeof value === 'object' && value.type && (value.type === 'text' || value.type === 'element')) {
+      children.push(this.cloneJsxNode(value as JsxNode));
+      return;
+    }
+    children.push({ type: 'text', content: String(value) });
+  }
+
+  private resolveInvocationProps(
+    props: Record<string, string>,
+    sourceFile: SourceFile,
+    propsContext: Map<string, any>
+  ): Record<string, any> {
+    const resolved: Record<string, any> = {};
+    for (const [propName, propValue] of Object.entries(props)) {
+      if (typeof propValue !== 'string') {
+        resolved[propName] = propValue;
+        continue;
+      }
+      if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(propValue)) {
+        if (propsContext.has(propValue)) {
+          resolved[propName] = propsContext.get(propValue);
+          continue;
+        }
+        const arrayValue = this.findArrayValue(propValue, sourceFile);
+        if (arrayValue) {
+          resolved[propName] = arrayValue;
+          continue;
+        }
+      }
+      resolved[propName] = propValue;
+    }
+    return resolved;
+  }
+
+  /**
+   * Build a propsContext Map from a map-callback item so that resolveClassNameExpression
+   * can substitute item.field references inside template literals and ternaries.
+   * 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>();
+    if (!itemParamName || itemValue == null) return ctx;
+    if (itemParamName === '__destructured__') {
+      if (typeof itemValue === 'object') {
+        for (const [k, v] of Object.entries(itemValue)) ctx.set(k, v);
+      }
+    } else {
+      ctx.set(itemParamName, itemValue);
+    }
+    return ctx;
+  }
+
+  private resolveSubstitutionProps(
+    props: Record<string, string>,
+    itemParamName: string,
+    itemValue: any
+  ): Record<string, any> {
+    const resolved: Record<string, any> = {};
+    for (const [propName, propValue] of Object.entries(props)) {
+      if (propValue.startsWith(itemParamName + '.')) {
+        const propPath = propValue.slice(itemParamName.length + 1);
+        resolved[propName] = itemValue && typeof itemValue === 'object'
+          ? itemValue[propPath]
+          : undefined;
+      } else {
+        resolved[propName] = propValue;
+      }
+    }
+    return resolved;
+  }
+
+  /**
+   * Collect local component definitions from a source file.
+   * Looks for function declarations and arrow function variable declarations.
+   */
+  private collectLocalComponentsFromFile(sourceFile: SourceFile): Map<string, Node> {
+    const localComponents = new Map<string, Node>();
+
+    // Check function declarations
+    for (const func of sourceFile.getFunctions()) {
+      const name = func.getName();
+      if (name && /^[A-Z]/.test(name)) {
+        localComponents.set(name, func);
+      }
+    }
+
+    // Check variable declarations with arrow functions
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        const name = decl.getName();
+        if (/^[A-Z]/.test(name)) {
+          const init = decl.getInitializer();
+          if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+            localComponents.set(name, init);
+          }
+        }
+      }
+    }
+
+    return localComponents;
+  }
+
+  /**
+   * Expand a .map() call by finding the source array and generating JSX for each item.
+   * Handles patterns like: {features.map((feature) => (<li>...</li>))}
+   * @param propsContext - Resolved prop values that may contain the array (e.g., from story)
+   */
+  private expandMapCall(
+    callExpr: Node,
+    sourceFile: SourceFile,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>,
+    propsContext: Map<string, any> = new Map()
+  ): JsxNode[] {
+    const results: JsxNode[] = [];
+
+    try {
+      if (!Node.isCallExpression(callExpr)) return results;
+
+      // Get the property access (e.g., features.map)
+      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 map callback function
+      const args = callExpr.getArguments();
+      if (args.length === 0) return results;
+
+      const callback = args[0];
+      if (!Node.isArrowFunction(callback) && !Node.isFunctionExpression(callback)) return results;
+
+      // Get the callback parameter — may be a simple name or object destructuring pattern.
+      // For destructuring ({ icon: Icon, label, shortcut }), we build a local→sourceKey map
+      // and use itemParamName = '__destructured__' so substitution uses flat property lookup.
+      const params = callback.getParameters();
+      if (params.length === 0) return results;
+
+      let itemParamName: string;
+      let destructuringBindings: Map<string, string> | null = null;
+      const firstParamNameNode = params[0].getNameNode();
+      if (Node.isObjectBindingPattern(firstParamNameNode)) {
+        destructuringBindings = new Map();
+        for (const element of firstParamNameNode.getElements()) {
+          const propNameNode = element.getPropertyNameNode();
+          const elemNameNode = element.getNameNode();
+          const localName = elemNameNode.getText();
+          const sourceKey = propNameNode ? propNameNode.getText() : localName;
+          destructuringBindings.set(localName, sourceKey);
+        }
+        itemParamName = '__destructured__';
+      } else {
+        itemParamName = params[0].getName();
+      }
+
+      // Find the JSX in the callback body
+      const body = callback.getBody();
+      if (!body) return results;
+
+      // Find the root JSX element in the callback
+      let callbackJsx: Node | null = null;
+      if (Node.isJsxElement(body) || Node.isJsxSelfClosingElement(body)) {
+        callbackJsx = body;
+      } else if (Node.isParenthesizedExpression(body)) {
+        const inner = body.getExpression();
+        if (Node.isJsxElement(inner) || Node.isJsxSelfClosingElement(inner)) {
+          callbackJsx = inner;
+        }
+      } else {
+        // Block body - look for return statement or JSX
+        const jsxElements = body.getDescendantsOfKind(SyntaxKind.JsxElement);
+        const selfClosing = body.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+        const allJsx = [...jsxElements, ...selfClosing];
+        if (allJsx.length > 0) {
+          // Find root JSX (fewest ancestors)
+          callbackJsx = allJsx[0];
+          for (const el of allJsx) {
+            if (el.getAncestors().length < (callbackJsx as Node).getAncestors().length) {
+              callbackJsx = el;
+            }
+          }
+        }
+      }
+
+      if (!callbackJsx) return results;
+
+      // Find the array's value - inline literal first, then propsContext, then source file
+      let arrayValue: any[] | null = null;
+
+      // Inline array literal: [{ ... }, ...].map(...)
+      if (arrayName === '__inline__' && Node.isArrayLiteralExpression(arrayExpr)) {
+        arrayValue = this.parseArrayLiteral(arrayExpr);
+      }
+
+      // Check if array was passed via props (e.g., features={minimalFeatures} from story)
+      if (!arrayValue && propsContext.has(arrayName)) {
+        const fromProps = propsContext.get(arrayName);
+        if (Array.isArray(fromProps)) {
+          arrayValue = fromProps;
+        } else if (typeof fromProps === 'string' && /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(fromProps)) {
+          // Prop may still be an unresolved identifier (e.g. features={defaultFeatures}).
+          // Resolve that identifier in the current component source before falling back.
+          arrayValue = this.findArrayValue(fromProps, sourceFile);
+        }
+      }
+
+      if (!arrayValue) {
+        // Look in source file for default value
+        arrayValue = this.findArrayValue(arrayName, sourceFile);
+      }
+
+      if (!arrayValue || arrayValue.length === 0) {
+        // If we can't find the array value, generate one iteration as a template
+        const templateJsx = this.buildJsxTreeWithSubstitution(
+          callbackJsx,
+          itemParamName,
+          { name: 'Item', description: 'Description' }, // Placeholder values
+          localComponents,
+          relativeImports
+        );
+        if (templateJsx) {
+          results.push(templateJsx);
+        }
+        return results;
+      }
+
+      // Collect local components from the source file (for expanding things like FeatureCheck)
+      const fileLocalComponents = this.collectLocalComponentsFromFile(sourceFile);
+      // Merge with provided localComponents (story file components take precedence)
+      const mergedLocalComponents = new Map([...fileLocalComponents, ...localComponents]);
+
+      // Generate JSX for each item in the array (limit to prevent huge outputs)
+      const maxItems = Math.min(arrayValue.length, 7);
+      for (let i = 0; i < maxItems; i++) {
+        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> = {};
+          for (const [localName, sourceKey] of destructuringBindings) {
+            flatItem[localName] = item[sourceKey];
+          }
+          item = flatItem;
+        }
+        const itemJsx = this.buildJsxTreeWithSubstitution(
+          callbackJsx,
+          itemParamName,
+          item,
+          mergedLocalComponents,
+          relativeImports
+        );
+        if (itemJsx) {
+          results.push(itemJsx);
+        }
+      }
+    } catch (err) {
+      console.warn('Failed to expand .map() call:', err);
+    }
+
+    return results;
+  }
+
+  /**
+   * 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 {
+    // 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()) {
+      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;
+          }
+        }
+      }
+    }
+
+    // Look for default parameter value in function: function Comp({ features = defaultFeatures })
+    for (const func of sourceFile.getFunctions()) {
+      const params = func.getParameters();
+      for (const param of params) {
+        // Check if it's an object binding pattern: { features = defaultFeatures }
+        const bindingName = param.getNameNode();
+        if (Node.isObjectBindingPattern(bindingName)) {
+          for (const element of bindingName.getElements()) {
+            const elemName = element.getNameNode();
+            if (Node.isIdentifier(elemName) && elemName.getText() === arrayName) {
+              const defaultInit = this.unwrapStaticValueExpression(element.getInitializer());
+              if (defaultInit && Node.isIdentifier(defaultInit)) {
+                // Recursively find the referenced array
+                const referencedName = defaultInit.getText();
+                const result = this.findArrayValue(referencedName, sourceFile);
+                if (result) {
+                  this.arrayValueCache.set(cacheKey, result);
+                  return result;
+                }
+              } else if (defaultInit && Node.isArrayLiteralExpression(defaultInit)) {
+                const value = this.parseArrayLiteral(defaultInit);
+                this.arrayValueCache.set(cacheKey, value);
+                return value;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Also check variable declarations with arrow functions
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        const init = decl.getInitializer();
+        if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+          const params = init.getParameters();
+          for (const param of params) {
+            const bindingName = param.getNameNode();
+            if (Node.isObjectBindingPattern(bindingName)) {
+              for (const element of bindingName.getElements()) {
+                const elemName = element.getNameNode();
+                if (Node.isIdentifier(elemName) && elemName.getText() === arrayName) {
+                  const defaultInit = this.unwrapStaticValueExpression(element.getInitializer());
+                  if (defaultInit && Node.isIdentifier(defaultInit)) {
+                    const referencedName = defaultInit.getText();
+                    const result = this.findArrayValue(referencedName, sourceFile);
+                    if (result) {
+                      this.arrayValueCache.set(cacheKey, result);
+                      return result;
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    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)) {
+        current = current.getExpression();
+        continue;
+      }
+      if (Node.isAsExpression(current)) {
+        current = current.getExpression();
+        continue;
+      }
+      if (typeof nodeApi.isTypeAssertion === 'function' && nodeApi.isTypeAssertion(current)) {
+        current = current.getExpression();
+        continue;
+      }
+      if (typeof nodeApi.isSatisfiesExpression === 'function' && nodeApi.isSatisfiesExpression(current)) {
+        current = current.getExpression();
+        continue;
+      }
+      break;
+    }
+
+    return current;
+  }
+
+  /**
+   * Parse an array literal expression into JavaScript values.
+   */
+  private parseArrayLiteral(arrayLit: Node): any[] {
+    const result: any[] = [];
+
+    if (!Node.isArrayLiteralExpression(arrayLit)) return result;
+
+    for (const element of arrayLit.getElements()) {
+      if (Node.isObjectLiteralExpression(element)) {
+        const obj: Record<string, any> = {};
+        for (const prop of element.getProperties()) {
+          if (Node.isPropertyAssignment(prop)) {
+            const name = prop.getName();
+            const init = prop.getInitializer();
+            if (init) {
+              if (Node.isStringLiteral(init)) {
+                obj[name] = init.getLiteralValue();
+              } else if (Node.isNumericLiteral(init)) {
+                obj[name] = Number(init.getLiteralText());
+              } else if (init.getKind() === SyntaxKind.TrueKeyword) {
+                obj[name] = true;
+              } else if (init.getKind() === SyntaxKind.FalseKeyword) {
+                obj[name] = false;
+              } else {
+                obj[name] = init.getText();
+              }
+            }
+          }
+        }
+        result.push(obj);
+      } else if (Node.isStringLiteral(element)) {
+        result.push(element.getLiteralValue());
+      } else if (Node.isNumericLiteral(element)) {
+        result.push(Number(element.getLiteralText()));
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Build a JSX tree with value substitution for map callback items.
+   * Replaces {item.prop} expressions with actual values.
+   */
+  private buildJsxTreeWithSubstitution(
+    node: Node,
+    itemParamName: string,
+    itemValue: any,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>
+  ): 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 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);
+          if (childJsx) children.push(childJsx);
+        } else if (Node.isJsxText(child)) {
+          const text = decodeHtmlEntities(child.getText().trim());
+          if (text) {
+            children.push({ type: 'text', content: text });
+          }
+        } else if (Node.isJsxExpression(child)) {
+          const expr = child.getExpression();
+          if (expr) {
+            // Handle conditional JSX: {condition && <JSX>} or {condition && (<JSX>)}
+            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);
+              if (condValue && (Node.isJsxElement(right) || Node.isJsxSelfClosingElement(right))) {
+                const jsxChild = this.buildJsxTreeWithSubstitution(right, itemParamName, itemValue, localComponents, relativeImports);
+                if (jsxChild) children.push(jsxChild);
+              }
+            // Handle ternary JSX: {condition ? <JSX1> : <JSX2>}
+            } else if (Node.isConditionalExpression(expr)) {
+              const condition = expr.getCondition();
+              let whenTrue = expr.getWhenTrue();
+              let whenFalse = expr.getWhenFalse();
+              // Unwrap parenthesized expressions
+              if (Node.isParenthesizedExpression(whenTrue)) {
+                whenTrue = whenTrue.getExpression();
+              }
+              if (Node.isParenthesizedExpression(whenFalse)) {
+                whenFalse = whenFalse.getExpression();
+              }
+              const condValue = this.substituteExpression(condition, itemParamName, itemValue);
+              const branch = condValue ? whenTrue : whenFalse;
+              if (Node.isJsxElement(branch) || Node.isJsxSelfClosingElement(branch)) {
+                const jsxChild = this.buildJsxTreeWithSubstitution(branch, itemParamName, itemValue, localComponents, relativeImports);
+                if (jsxChild) children.push(jsxChild);
+              } else {
+                // Non-JSX ternary result - substitute as text
+                const substituted = this.substituteExpression(branch, itemParamName, itemValue);
+                if (substituted !== null && substituted !== undefined && substituted !== '') {
+                  children.push({ type: 'text', content: String(substituted) });
+                }
+              }
+            } else {
+              const substituted = this.substituteExpression(expr, itemParamName, itemValue);
+              if (substituted !== null && substituted !== undefined && substituted !== '') {
+                children.push({ type: 'text', content: String(substituted) });
+              }
+            }
+          }
+        }
+      }
+
+      if (/^[A-Z]/.test(rawTagName)) {
+        const evaluatedProps = this.resolveSubstitutionProps(props, itemParamName, itemValue);
+        if (children.length > 0) {
+          evaluatedProps.children = children;
+        }
+
+        const localDef = localComponents.get(rawTagName);
+        if (localDef) {
+          const expandedLocal = this.expandLocalComponentWithProps(
+            localDef,
+            evaluatedProps,
+            localComponents,
+            relativeImports
+          );
+          if (expandedLocal) {
+            return expandedLocal;
+          }
+        }
+
+        const importedFilePath = relativeImports.get(rawTagName);
+        const SKIP_EXPANSION = ['Skeleton', 'SkeletonText'];
+        if (importedFilePath && !SKIP_EXPANSION.includes(rawTagName)) {
+          const resolvedProps = new Map<string, any>();
+          for (const [key, value] of Object.entries(evaluatedProps)) {
+            resolvedProps.set(key, value);
+          }
+          const expandedImported = this.expandImportedComponent(
+            rawTagName,
+            importedFilePath,
+            relativeImports,
+            resolvedProps
+          );
+          if (expandedImported && !this.isUnresolvedExpandedComponent(expandedImported, localComponents, relativeImports)) {
+            return expandedImported;
+          }
+        }
+      }
+
+      const outputProps = { ...props } as Record<string, any>;
+      delete outputProps.children;
+      return {
+        type: 'element',
+        tagName,
+        isComponent: /^[A-Z]/.test(tagName),
+        props: outputProps,
+        children,
+      };
+    } else if (Node.isJsxSelfClosingElement(node)) {
+      let rawTagName = node.getTagNameNode().getText();
+      // Resolve dynamic component names from destructured map items:
+      // e.g. { icon: Icon } where Icon = 'UserIcon' → use 'UserIcon' as the actual tag
+      if (itemParamName === '__destructured__' && /^[A-Z]/.test(rawTagName)
+          && typeof itemValue === 'object' && itemValue !== null && typeof itemValue[rawTagName] === 'string'
+          && /^[A-Z]/.test(itemValue[rawTagName])) {
+        rawTagName = itemValue[rawTagName];
+      }
+      const tagName = COMPONENT_TO_HTML_MAP[rawTagName] || rawTagName;
+      const itemPropsContext = this.buildItemPropsContext(itemParamName, itemValue);
+      const props = this.extractPropsFromNode(node, rawTagName, itemPropsContext).props;
+
+      // Check for local component expansion
+      const localDef = localComponents.get(rawTagName);
+      if (localDef) {
+        const evaluatedProps = this.resolveSubstitutionProps(props, itemParamName, itemValue);
+
+        // Find the JSX in the component, handling ternary expressions based on props
+        const expandedJsx = this.expandLocalComponentWithProps(localDef, evaluatedProps, localComponents, relativeImports);
+        if (expandedJsx) {
+          return expandedJsx;
+        }
+      }
+
+      // 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 importedFilePath = relativeImports.get(rawTagName);
+      if (importedFilePath && !SKIP_EXPANSION.includes(rawTagName)) {
+        const evaluatedProps = this.resolveSubstitutionProps(props, itemParamName, itemValue);
+        const resolvedProps = new Map<string, any>();
+        for (const [key, value] of Object.entries(evaluatedProps)) {
+          resolvedProps.set(key, value);
+        }
+        const expandedJsx = this.expandImportedComponent(rawTagName, importedFilePath, relativeImports, resolvedProps);
+        if (expandedJsx && !this.isUnresolvedExpandedComponent(expandedJsx, localComponents, relativeImports)) {
+          return expandedJsx;
+        }
+      }
+
+      const outputProps = { ...props } as Record<string, any>;
+      delete outputProps.children;
+      return {
+        type: 'element',
+        tagName,
+        isComponent: /^[A-Z]/.test(tagName),
+        props: outputProps,
+        children: [],
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Expand a local component with evaluated props.
+   * Handles ternary expressions based on prop values.
+   */
+  private expandLocalComponentWithProps(
+    componentDef: Node,
+    evaluatedProps: Record<string, any>,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>
+  ): JsxNode | null {
+    // Find return statement or JSX in the component
+    let jsxToExpand: Node | null = null;
+
+    // Look for return statement with JSX or conditional
+    const returnStatements = componentDef.getDescendantsOfKind(SyntaxKind.ReturnStatement);
+    for (const ret of returnStatements) {
+      const expr = ret.getExpression();
+      if (!expr) continue;
+
+      // Handle ternary: return condition ? <JSX1> : <JSX2>
+      if (Node.isConditionalExpression(expr)) {
+        const condition = expr.getCondition();
+        const whenTrue = expr.getWhenTrue();
+        const whenFalse = expr.getWhenFalse();
+
+        // Evaluate the condition based on props
+        const condText = condition.getText();
+        const condValue = evaluatedProps[condText];
+
+        // Choose the appropriate branch
+        let branch = condValue ? whenTrue : whenFalse;
+        // Unwrap parentheses
+        if (Node.isParenthesizedExpression(branch)) {
+          branch = branch.getExpression();
+        }
+
+        if (Node.isJsxElement(branch) || Node.isJsxSelfClosingElement(branch)) {
+          jsxToExpand = branch;
+          break;
+        }
+      }
+
+      // Handle direct JSX return
+      let jsxExpr = expr;
+      if (Node.isParenthesizedExpression(jsxExpr)) {
+        jsxExpr = jsxExpr.getExpression();
+      }
+      if (Node.isJsxElement(jsxExpr) || Node.isJsxSelfClosingElement(jsxExpr)) {
+        jsxToExpand = jsxExpr;
+        break;
+      }
+    }
+
+    // Fallback: find any JSX in the component
+    if (!jsxToExpand) {
+      const jsxElements = componentDef.getDescendantsOfKind(SyntaxKind.JsxElement);
+      const selfClosing = componentDef.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+      const allJsx = [...jsxElements, ...selfClosing];
+      if (allJsx.length > 0) {
+        jsxToExpand = allJsx[0];
+        for (const el of allJsx) {
+          if (el.getAncestors().length < jsxToExpand.getAncestors().length) {
+            jsxToExpand = el;
+          }
+        }
+      }
+    }
+
+    if (!jsxToExpand) return null;
+
+    const propsMap = new Map<string, any>();
+    for (const [key, value] of Object.entries(evaluatedProps)) {
+      propsMap.set(key, value);
+    }
+
+    const parameterNodes = this.getComponentParameterNodes(componentDef);
+
+    if (parameterNodes.length > 0) {
+      const firstParam = parameterNodes[0];
+      const nameNode = firstParam.getNameNode?.();
+      if (nameNode && Node.isIdentifier(nameNode)) {
+        // Function signature uses a plain `props` identifier.
+        propsMap.set(nameNode.getText(), { ...evaluatedProps });
+      } else if (nameNode && Node.isObjectBindingPattern(nameNode)) {
+        const consumedKeys = new Set<string>();
+        const restBindings: string[] = [];
+
+        for (const element of nameNode.getElements()) {
+          if (element.getDotDotDotToken()) {
+            restBindings.push(element.getName());
+            continue;
+          }
+
+          const sourceKey = element.getPropertyNameNode?.()?.getText() || element.getName();
+          consumedKeys.add(sourceKey);
+          if (Object.prototype.hasOwnProperty.call(evaluatedProps, sourceKey)) {
+            propsMap.set(element.getName(), evaluatedProps[sourceKey]);
+            continue;
+          }
+
+          const defaultInit = this.unwrapStaticValueExpression(element.getInitializer?.());
+          if (!defaultInit) continue;
+
+          const defaultValue = this.resolveExpressionValue(defaultInit, propsMap);
+          if (defaultValue !== undefined) {
+            propsMap.set(element.getName(), defaultValue);
+            continue;
+          }
+
+          if (Node.isStringLiteral(defaultInit) || Node.isNoSubstitutionTemplateLiteral(defaultInit)) {
+            propsMap.set(element.getName(), defaultInit.getLiteralValue());
+          } else if (Node.isNumericLiteral(defaultInit)) {
+            propsMap.set(element.getName(), defaultInit.getLiteralValue());
+          } else {
+            const defaultText = defaultInit.getText();
+            if (defaultText === 'true') propsMap.set(element.getName(), true);
+            if (defaultText === 'false') propsMap.set(element.getName(), false);
+          }
+        }
+
+        if (restBindings.length > 0) {
+          const restObject: Record<string, any> = {};
+          for (const [key, value] of Object.entries(evaluatedProps)) {
+            if (!consumedKeys.has(key)) {
+              restObject[key] = value;
+            }
+          }
+          for (const restBinding of restBindings) {
+            propsMap.set(restBinding, restObject);
+          }
+        }
+      }
+    }
+
+    return this.buildJsxTree(jsxToExpand, localComponents, relativeImports, propsMap);
+  }
+
+  private getComponentParameterNodes(componentDef: Node): any[] {
+    if (typeof (componentDef as any).getParameters === 'function') {
+      return (componentDef as any).getParameters();
+    }
+
+    if (Node.isCallExpression(componentDef)) {
+      for (const arg of componentDef.getArguments()) {
+        if (Node.isArrowFunction(arg) || Node.isFunctionExpression(arg)) {
+          return arg.getParameters();
+        }
+      }
+    }
+
+    return [];
+  }
+
+  /**
+   * 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.
+   */
+  private isPortalRootedNode(node: JsxNode): boolean {
+    if (node.type !== 'element') return false;
+    return node.tagName.toLowerCase().includes('portal');
+  }
+
+  private isUnresolvedExpandedComponent(
+    node: JsxNode,
+    localComponents: Map<string, Node>,
+    relativeImports: Map<string, string>
+  ): boolean {
+    if (node.type !== 'element') return false;
+    const el = node as JsxElement;
+    const tagName = el.tagName;
+
+    if (!/^[A-Z]/.test(tagName)) return false;
+    // Namespaced tags like `AccordionPrimitive.Trigger` come from imported
+    // third-party primitives. Keep expanded trees in this case so nested
+    // children (e.g. icons/text) are not dropped.
+    if (tagName.includes('.')) return false;
+    if (Object.prototype.hasOwnProperty.call(COMPONENT_TO_HTML_MAP, tagName)) return false;
+    if (localComponents.has(tagName)) return false;
+    if (relativeImports.has(tagName)) return false;
+
+    const children = el.children || [];
+    if (children.length === 0) return true;
+
+    // Generic pass-through wrapper heuristic:
+    // unresolved uppercase tag + one rendered child + no visual class/style props.
+    // This catches dynamic aliases like `const Comp = asChild ? Slot : "button"`
+    // where static expansion cannot resolve the className expression reliably.
+    const props = el.props || {};
+    const className = typeof props.className === 'string' ? props.className.trim() : '';
+    const styleProp = typeof props.style === 'string' ? props.style.trim() : '';
+    const hasVisualProps = className.length > 0 || styleProp.length > 0;
+    const hasSingleChild = children.length === 1;
+    if (!hasVisualProps && hasSingleChild) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * 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 {
+    const text = expr.getText();
+
+    // Handle property access: feature.name, feature.description
+    if (Node.isPropertyAccessExpression(expr)) {
+      const objExpr = expr.getExpression();
+      const propName = expr.getName();
+
+      if (objExpr.getText() === itemParamName && typeof itemValue === 'object') {
+        return itemValue[propName];
+      }
+    }
+
+    // Handle simple variable reference: feature (if it's the whole item)
+    if (Node.isIdentifier(expr) && text === itemParamName) {
+      return typeof itemValue === 'object' ? JSON.stringify(itemValue) : itemValue;
+    }
+
+    // Handle destructured variable reference: {label}, {shortcut}, etc.
+    // When itemParamName === '__destructured__', item is already keyed by local name.
+    if (itemParamName === '__destructured__' && Node.isIdentifier(expr) && typeof itemValue === 'object' && itemValue !== null) {
+      const val = itemValue[text];
+      if (val !== undefined) return val;
+    }
+
+    // Handle conditional: feature.description && <p>...</p>
+    if (Node.isBinaryExpression(expr)) {
+      const left = expr.getLeft();
+      const operator = expr.getOperatorToken().getText();
+      const right = expr.getRight();
+
+      if (operator === '&&') {
+        const leftValue = this.substituteExpression(left, itemParamName, itemValue);
+        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)) {
+            // Get text content from the JSX
+            const textNodes = right.getDescendantsOfKind(SyntaxKind.JsxText);
+            const exprNodes = right.getDescendantsOfKind(SyntaxKind.JsxExpression);
+            let textContent = '';
+            for (const textNode of textNodes) {
+              textContent += decodeHtmlEntities(textNode.getText().trim()) + ' ';
+            }
+            for (const exprNode of exprNodes) {
+              const innerExpr = exprNode.getExpression();
+              if (innerExpr) {
+                const val = this.substituteExpression(innerExpr, itemParamName, itemValue);
+                if (val !== null && val !== undefined) {
+                  textContent += String(val) + ' ';
+                }
+              }
+            }
+            return textContent.trim();
+          }
+          return this.substituteExpression(right, itemParamName, itemValue);
+        }
+        return null;
+      }
+    }
+
+    // Handle ternary: feature.free ? <Check /> : <Cross />
+    if (Node.isConditionalExpression(expr)) {
+      const condition = expr.getCondition();
+      const condValue = this.substituteExpression(condition, itemParamName, itemValue);
+      // Return indication of which branch (for components like Check/Cross)
+      if (condValue) {
+        return 'true';
+      } else {
+        return 'false';
+      }
+    }
+
+    // Handle string literal
+    if (Node.isStringLiteral(expr)) {
+      return expr.getLiteralValue();
+    }
+
+    return null;
+  }
+
+  /**
+   * Expand an imported component by reading its source file and extracting JSX.
+   * Always expands the component structure - the plugin will handle className merging.
+   * @param resolvedProps - Props resolved from the story file (e.g., arrays passed to the component)
+   */
+  private expandImportedComponent(
+    componentName: string,
+    filePath: string,
+    relativeImports: Map<string, string>,
+    resolvedProps: Map<string, any> = new Map()
+  ): JsxNode | null {
+    try {
+      // Check cache first
+      const cacheKey = `${filePath}:${componentName}`;
+      let sourceFile: SourceFile;
+
+      if (this.importedComponentCache.has(cacheKey)) {
+        const cached = this.importedComponentCache.get(cacheKey)!;
+        sourceFile = cached.sourceFile;
+      } else {
+        // Add the source file to the project
+        sourceFile = this.project.addSourceFileAtPath(filePath);
+        this.importedComponentCache.set(cacheKey, { sourceFile, componentName });
+      }
+
+      // Collect icon imports from the component file and merge into main registry
+      const componentIcons = this.collectReactIconImports(sourceFile);
+      for (const [name, spec] of componentIcons.entries()) {
+        this.iconImports.set(name, spec);
+      }
+
+      // Always expand - the plugin will handle className merging with component definitions
+      return this.extractComponentJsx(sourceFile, componentName, relativeImports, resolvedProps);
+    } catch (err) {
+      console.warn(`Failed to expand imported component ${componentName} from ${filePath}:`, err);
+      return null;
+    }
+  }
+
+  /**
+   * Extract JSX from a component function in a source file.
+   * @param resolvedProps - Props resolved from the caller (e.g., arrays passed from story)
+   */
+  private extractComponentJsx(
+    sourceFile: SourceFile,
+    componentName: string,
+    relativeImports: Map<string, string>,
+    resolvedProps: Map<string, any> = new Map()
+  ): JsxNode | null {
+    const localComponents = this.collectLocalComponentsFromFile(sourceFile);
+    const mergedRelativeImports = new Map(relativeImports);
+    for (const [name, filePath] of this.collectComponentImports(sourceFile)) {
+      mergedRelativeImports.set(name, filePath);
+    }
+
+    // Find the component function (exported function or const)
+    // Look for: export function ComponentName() { ... }
+    for (const func of sourceFile.getFunctions()) {
+      if (func.getName() === componentName) {
+        const evaluatedProps = Object.fromEntries(resolvedProps.entries());
+        const expanded = this.expandLocalComponentWithProps(
+          func,
+          evaluatedProps,
+          localComponents,
+          mergedRelativeImports
+        );
+        if (expanded) {
+          return expanded;
+        }
+
+        const jsxElements = func.getDescendantsOfKind(SyntaxKind.JsxElement);
+        const selfClosing = func.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+        const allJsx = [...jsxElements, ...selfClosing];
+
+        if (allJsx.length > 0) {
+          let rootJsx = allJsx[0];
+              for (const el of allJsx) {
+                if (el.getAncestors().length < rootJsx.getAncestors().length) {
+                  rootJsx = el;
+                }
+              }
+          return this.buildJsxTree(rootJsx, localComponents, mergedRelativeImports, resolvedProps);
+        }
+      }
+    }
+
+    // Look for: export const ComponentName = () => { ... } or forwardRef
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        if (decl.getName() === componentName) {
+          const init = decl.getInitializer();
+          if (init) {
+            const evaluatedProps = Object.fromEntries(resolvedProps.entries());
+            const expanded = this.expandLocalComponentWithProps(
+              init,
+              evaluatedProps,
+              localComponents,
+              mergedRelativeImports
+            );
+            if (expanded) {
+              return expanded;
+            }
+
+            const jsxElements = init.getDescendantsOfKind(SyntaxKind.JsxElement);
+            const selfClosing = init.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+            const allJsx = [...jsxElements, ...selfClosing];
+
+            if (allJsx.length > 0) {
+              let rootJsx = allJsx[0];
+              for (const el of allJsx) {
+                if (el.getAncestors().length < rootJsx.getAncestors().length) {
+                  rootJsx = el;
+                }
+              }
+              return this.buildJsxTree(rootJsx, localComponents, mergedRelativeImports, resolvedProps);
+            }
+          }
+        }
+      }
+    }
+
+    // Follow barrel re-exports: `export * from "./hero"` or `export { Hero } from "./hero"`
+    const fileDir = path.dirname(sourceFile.getFilePath());
+    for (const exportDecl of sourceFile.getExportDeclarations()) {
+      const moduleSpec = exportDecl.getModuleSpecifierValue();
+      if (!moduleSpec) continue;
+      const namedExports = exportDecl.getNamedExports();
+      // Only follow if it's a wildcard export OR exports the specific component name
+      const isWildcard = namedExports.length === 0;
+      const exportsComponent = namedExports.some(
+        (ne) => (ne.getAliasNode()?.getText() || ne.getName()) === componentName
+      );
+      if (!isWildcard && !exportsComponent) continue;
+      const resolvedPath = this.resolveImportedComponentPath(fileDir, moduleSpec);
+      if (!resolvedPath) continue;
+      try {
+        const reExportedFile = this.project.addSourceFileAtPath(resolvedPath);
+        const result = this.extractComponentJsx(reExportedFile, componentName, relativeImports, resolvedProps);
+        if (result) return result;
+      } catch {
+        // ignore unresolvable re-exports
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract props from a JsxOpeningElement
+   */
+  private extractInstanceFromJsxOpening(
+    opening: Node,
+    componentName: string
+  ): ComponentInstance {
+    return this.extractPropsFromNode(opening, componentName);
+  }
+
+  /**
+   * Extract props from a JsxSelfClosingElement
+   */
+  private extractInstanceFromSelfClosing(
+    el: Node,
+    componentName: string
+  ): ComponentInstance {
+    return this.extractPropsFromNode(el, componentName);
+  }
+
+  /**
+   * 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?.() ?? []) {
+      if (!Node.isPropertyAssignment(prop)) continue;
+      const key = (prop as any).getName?.();
+      if (!key) continue;
+      const val = (prop as any).getInitializer?.();
+      if (!val) continue;
+      result[key] = this.parseLiteralValue(val);
+    }
+    return result;
+  }
+
+  /**
+   * Parse a literal AST node into a plain JS value (string, number, boolean, array, object).
+   */
+  private parseLiteralValue(val: Node): any {
+    const unwrapped = this.unwrapStaticValueExpression(val);
+    if (unwrapped && unwrapped !== val) {
+      return this.parseLiteralValue(unwrapped);
+    }
+    if (Node.isStringLiteral(val)) return val.getLiteralValue();
+    if (Node.isNumericLiteral(val)) return val.getLiteralValue();
+    const text = val.getText();
+    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));
+    }
+    if (Node.isObjectLiteralExpression(val)) {
+      return this.parseObjectLiteralExpression(val);
+    }
+    return text;
+  }
+
+  private coerceBoolean(value: any): boolean | null {
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'number') return value !== 0;
+    if (typeof value === 'string') {
+      const normalized = value.trim().toLowerCase();
+      if (normalized === 'true') return true;
+      if (normalized === 'false') return false;
+      if (normalized === '1') return true;
+      if (normalized === '0') return false;
+      if (normalized.length > 0) return true;
+      return false;
+    }
+    return null;
+  }
+
+  private resolveExpressionValue(expr: Node, propsContext: Map<string, any>): any {
+    if (Node.isParenthesizedExpression(expr)) {
+      return this.resolveExpressionValue(expr.getExpression(), propsContext);
+    }
+    if (Node.isStringLiteral(expr) || Node.isNoSubstitutionTemplateLiteral(expr)) {
+      return expr.getLiteralValue();
+    }
+    if (Node.isNumericLiteral(expr)) {
+      return expr.getLiteralValue();
+    }
+    const exprText = expr.getText();
+    if (exprText === 'true') return true;
+    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 = "...")
+      const varDecl = expr.getSourceFile().getVariableDeclaration(exprText);
+      if (varDecl) {
+        const init = varDecl.getInitializer();
+        if (init && Node.isStringLiteral(init)) return init.getLiteralValue();
+      }
+      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];
+        }
+      }
+      return undefined;
+    }
+    if (Node.isConditionalExpression(expr)) {
+      const conditionValue = this.resolveExpressionValue(expr.getCondition(), propsContext);
+      const conditionBool = this.coerceBoolean(conditionValue);
+      if (conditionBool == null) return undefined;
+      return this.resolveExpressionValue(
+        conditionBool ? expr.getWhenTrue() : expr.getWhenFalse(),
+        propsContext
+      );
+    }
+    if (Node.isBinaryExpression(expr)) {
+      const op = expr.getOperatorToken().getText();
+      if (op === '===' || op === '==') {
+        const left = this.resolveExpressionValue(expr.getLeft(), propsContext);
+        const right = this.resolveExpressionValue(expr.getRight(), propsContext);
+        if (left === undefined || right === undefined) return undefined;
+        return left === right;
+      }
+      if (op === '!==' || op === '!=') {
+        const left = this.resolveExpressionValue(expr.getLeft(), propsContext);
+        const right = this.resolveExpressionValue(expr.getRight(), propsContext);
+        if (left === undefined || right === undefined) return undefined;
+        return left !== right;
+      }
+      if (op === '&&') {
+        const left = this.coerceBoolean(this.resolveExpressionValue(expr.getLeft(), propsContext));
+        if (left === false) return false;
+        if (left === true) return this.resolveExpressionValue(expr.getRight(), propsContext);
+        return undefined;
+      }
+      if (op === '||') {
+        const leftValue = this.resolveExpressionValue(expr.getLeft(), propsContext);
+        const leftBool = this.coerceBoolean(leftValue);
+        if (leftBool === true) return leftValue;
+        if (leftBool === false) return this.resolveExpressionValue(expr.getRight(), propsContext);
+        return undefined;
+      }
+      if (op === '+') {
+        const left = this.resolveExpressionValue(expr.getLeft(), propsContext);
+        const right = this.resolveExpressionValue(expr.getRight(), propsContext);
+        if (left === undefined || right === undefined) return undefined;
+        return String(left) + String(right);
+      }
+    }
+    return undefined;
+  }
+
+  private resolveClassNameExpression(expr: Node, propsContext: Map<string, any>): string {
+    if (Node.isParenthesizedExpression(expr)) {
+      return this.resolveClassNameExpression(expr.getExpression(), propsContext);
+    }
+    if (Node.isStringLiteral(expr) || Node.isNoSubstitutionTemplateLiteral(expr)) {
+      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 ?? ''];
+      for (const span of expr.getTemplateSpans()) {
+        parts.push(this.resolveClassNameExpression(span.getExpression(), propsContext));
+        parts.push((span.getLiteral().compilerNode as any).text ?? '');
+      }
+      return parts.join(' ').trim().replace(/\s+/g, ' ');
+    }
+    if (Node.isIdentifier(expr) || Node.isPropertyAccessExpression(expr)) {
+      const resolved = this.resolveExpressionValue(expr, propsContext);
+      return typeof resolved === 'string' ? resolved : '';
+    }
+    if (Node.isConditionalExpression(expr)) {
+      const conditionValue = this.resolveExpressionValue(expr.getCondition(), propsContext);
+      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(' ');
+    }
+    if (Node.isBinaryExpression(expr)) {
+      const op = expr.getOperatorToken().getText();
+      if (op === '&&') {
+        const leftBool = this.coerceBoolean(this.resolveExpressionValue(expr.getLeft(), propsContext));
+        if (leftBool === false) return '';
+        if (leftBool === true) return this.resolveClassNameExpression(expr.getRight(), propsContext);
+        return '';
+      }
+      if (op === '||') {
+        const left = this.resolveClassNameExpression(expr.getLeft(), propsContext);
+        if (left.trim()) return left;
+        return this.resolveClassNameExpression(expr.getRight(), propsContext);
+      }
+      if (op === '+') {
+        const left = this.resolveClassNameExpression(expr.getLeft(), propsContext);
+        const right = this.resolveClassNameExpression(expr.getRight(), propsContext);
+        return `${left} ${right}`.trim();
+      }
+    }
+    if (Node.isArrayLiteralExpression(expr)) {
+      const parts: string[] = [];
+      for (const element of expr.getElements()) {
+        const value = this.resolveClassNameExpression(element, propsContext).trim();
+        if (value) parts.push(value);
+      }
+      return parts.join(' ').trim();
+    }
+    if (Node.isObjectLiteralExpression(expr)) {
+      const enabled: string[] = [];
+      for (const prop of expr.getProperties()) {
+        if (!Node.isPropertyAssignment(prop)) continue;
+        const keyNode = prop.getNameNode();
+        const className = Node.isStringLiteral(keyNode) ? keyNode.getLiteralValue() : keyNode.getText();
+        const init = prop.getInitializer();
+        if (!init) continue;
+        const boolValue = this.coerceBoolean(this.resolveExpressionValue(init, propsContext));
+        if (boolValue === true) enabled.push(className);
+      }
+      return enabled.join(' ');
+    }
+    if (Node.isCallExpression(expr)) {
+      const callee = expr.getExpression().getText();
+      if (['cn', 'clsx', 'cva', 'twMerge'].includes(callee)) {
+        const parts: string[] = [];
+        for (const arg of expr.getArguments()) {
+          const value = this.resolveClassNameExpression(arg, propsContext).trim();
+          if (value) parts.push(value);
+        }
+        return parts.join(' ').trim();
+      }
+    }
+    return '';
+  }
+
+  /**
+   * Extract props from a JSX node (opening element or self-closing element).
+   * Uses getDescendantsOfKind to safely get only JsxAttribute nodes,
+   * filtering to direct attributes only (depth 1 from the JsxAttributes container).
+   */
+  private extractPropsFromNode(
+    jsxNode: Node,
+    componentName: string,
+    propsContext: Map<string, any> = new Map()
+  ): ComponentInstance {
+    const props: Record<string, any> = {};
+
+    const directAttributes =
+      typeof (jsxNode as any).getAttributes === 'function'
+        ? ((jsxNode as any).getAttributes() as Node[])
+        : [];
+    const attributes = directAttributes.length > 0
+      ? directAttributes
+      : (jsxNode.getChildrenOfKind(SyntaxKind.JsxAttributes)[0]?.getChildren().filter(
+          child => Node.isJsxAttribute(child) || Node.isJsxSpreadAttribute(child)
+        ) ?? []);
+
+    if (attributes.length === 0) return { componentName, props };
+
+    for (const attr of attributes) {
+      if (Node.isJsxSpreadAttribute(attr)) {
+        const expr = attr.getExpression();
+        if (!expr) continue;
+        const resolved = this.resolveExpressionValue(expr, propsContext);
+        if (resolved && typeof resolved === 'object' && !Array.isArray(resolved)) {
+          for (const [key, value] of Object.entries(resolved)) {
+            props[key] = value;
+          }
+        }
+        continue;
+      }
+
+      const nameNode = (attr as any).getNameNode?.();
+      if (!nameNode) continue;
+      const name = nameNode.getText();
+      const init = attr.getInitializer();
+      if (name === 'className') {
+        if (init && Node.isStringLiteral(init)) {
+          props[name] = init.getLiteralValue();
+        } else if (init && Node.isJsxExpression(init)) {
+          const expr = init.getExpression();
+          if (expr && Node.isStringLiteral(expr)) {
+            props[name] = expr.getLiteralValue();
+          } else if (expr) {
+            const resolved = this.resolveClassNameExpression(expr, propsContext);
+            if (resolved) {
+              props[name] = resolved;
+            }
+          }
+        }
+        continue;
+      }
+
+      if (!init) {
+        props[name] = 'true';
+      } else if (Node.isStringLiteral(init)) {
+        props[name] = init.getLiteralValue();
+      } else if (Node.isJsxExpression(init)) {
+        const expr = init.getExpression();
+        if (expr && Node.isStringLiteral(expr)) {
+          props[name] = expr.getLiteralValue();
+        } else if (expr && Node.isObjectLiteralExpression(expr)) {
+          props[name] = this.parseObjectLiteralExpression(expr);
+        } 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();
+        }
+      }
+    }
+
+    return { componentName, props };
+  }
+
+  public getIconRegistry(): Record<string, IconImportSpec> {
+    const out: Record<string, IconImportSpec> = {};
+    for (const [key, value] of this.iconImports.entries()) {
+      out[key] = value;
+    }
+    return out;
+  }
+
+  private collectReactIconImports(sourceFile: SourceFile): Map<string, IconImportSpec> {
+    const imports = new Map<string, IconImportSpec>();
+    const iconPackages = this.config.iconPackages || ['lucide-react', 'react-icons/'];
+    for (const decl of sourceFile.getImportDeclarations()) {
+      const moduleSpec = decl.getModuleSpecifierValue();
+      if (!moduleSpec) continue;
+      const isIconModule = iconPackages.some(pkg =>
+        pkg.endsWith('/') ? moduleSpec.startsWith(pkg) : moduleSpec === pkg
+      );
+      if (!isIconModule) continue;
+      for (const named of decl.getNamedImports()) {
+        const exportName = named.getNameNode().getText();
+        const aliasNode = named.getAliasNode();
+        const localName = aliasNode ? aliasNode.getText() : exportName;
+        imports.set(localName, { module: moduleSpec, exportName });
+      }
+    }
+    return imports;
+  }
+
+  private collectIconUsage(node: JsxNode | undefined, iconImports: Map<string, IconImportSpec>): void {
+    if (!node) return;
+    if (node.type === 'element') {
+      const el = node as JsxElement;
+      const icon = iconImports.get(el.tagName);
+      if (icon) {
+        this.iconImports.set(el.tagName, icon);
+      }
+      for (const child of el.children || []) {
+        this.collectIconUsage(child, iconImports);
+      }
+    }
+  }
+
+  // ===========================================================================
+  // Helper Methods
+  // ===========================================================================
+
+  /**
+   * Find all component declarations in a file
+   */
+  private findComponentDeclarations(sourceFile: SourceFile): Array<{ name: string; node: Node }> {
+    const components: Array<{ name: string; node: Node }> = [];
+
+    // Find variable statements that export 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)) {
+          components.push({ name, node: decl });
+        }
+      }
+    }
+
+    return components;
+  }
+
+  /**
+   * Extract Tailwind classes from all string-like expressions in a node.
+   * Handles: string literals, template literals (with and without interpolation),
+   * ternary expressions with class strings, and clsx/cn/cva calls.
+   */
+  private extractClassesFromNode(node: Node): string[] {
+    const classes: string[] = [];
+    this.collectClassesFromNode(node, classes);
+    return [...new Set(classes)];
+  }
+
+  /**
+   * Extract all Tailwind classes from the entire source file
+   */
+  private extractAllClassesFromFile(sourceFile: SourceFile): string[] {
+    const classes: string[] = [];
+    this.collectClassesFromNode(sourceFile, classes);
+    return [...new Set(classes)];
+  }
+
+  /**
+   * Recursively collect Tailwind classes from a node and all its descendants.
+   * Extracts from:
+   * - String literals
+   * - Template literals (no interpolation)
+   * - Template expressions (head + spans - extracts static parts + ternary branches)
+   * - clsx() / cn() call arguments
+   */
+  private collectClassesFromNode(node: Node, classes: string[]): void {
+    const CLASS_UTIL_NAMES = new Set(['cn', 'clsx', 'cva', 'twMerge', 'tv', 'cx', 'ctl']);
+
+    // 1. className / class JSX attributes
+    const jsxAttrs = node.getDescendantsOfKind(SyntaxKind.JsxAttribute);
+    for (const attr of jsxAttrs) {
+      const nameNode = attr.getNameNode();
+      const attrName = Node.isIdentifier(nameNode) ? nameNode.getText() : '';
+      if (attrName !== 'className' && attrName !== 'class') continue;
+      const initializer = attr.getInitializer();
+      if (!initializer) continue;
+      if (Node.isStringLiteral(initializer)) {
+        const value = initializer.getLiteralValue();
+        classes.push(...value.split(/\s+/).filter(Boolean));
+      } else if (Node.isJsxExpression(initializer)) {
+        const expr = initializer.getExpression();
+        if (expr) this.extractClassesFromExpression(expr, classes);
+      }
+    }
+
+    // 2. cn() / clsx() / cva() / twMerge() call arguments
+    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of calls) {
+      const expr = call.getExpression();
+      const fnName = Node.isIdentifier(expr) ? expr.getText() :
+                     Node.isPropertyAccessExpression(expr) ? expr.getName() : '';
+      if (!CLASS_UTIL_NAMES.has(fnName)) continue;
+      for (const arg of call.getArguments()) {
+        this.extractClassesFromExpression(arg, classes);
+      }
+    }
+
+    // 3. NoSubstitutionTemplateLiteral directly assigned to className (caught via JSX above),
+    //    but also handle bare template literals inside class utility calls (already covered by
+    //    extractClassesFromExpression). Nothing extra needed here.
+  }
+
+  /**
+   * Extract Tailwind classes from an expression node.
+   * Follows ternary branches and collects string literals from both sides.
+   */
+  private extractClassesFromExpression(expr: Node, classes: string[]): void {
+    // Ternary (ConditionalExpression): condition ? "classes-a" : "classes-b"
+    if (Node.isConditionalExpression(expr)) {
+      this.extractClassesFromExpression(expr.getWhenTrue(), classes);
+      this.extractClassesFromExpression(expr.getWhenFalse(), classes);
+      return;
+    }
+
+    // String literal value
+    if (Node.isStringLiteral(expr)) {
+      const value = expr.getLiteralValue();
+      if (this.looksLikeTailwindClasses(value)) {
+        classes.push(...value.split(/\s+/).filter(Boolean));
+      }
+      return;
+    }
+
+    // Template literal without interpolation
+    if (Node.isNoSubstitutionTemplateLiteral(expr)) {
+      const value = expr.getLiteralValue();
+      if (this.looksLikeTailwindClasses(value)) {
+        classes.push(...value.split(/\s+/).filter(Boolean));
+      }
+      return;
+    }
+
+    // Template literal with ${} interpolations: `flex ${condition ? 'gap-4' : 'gap-2'}`
+    if (Node.isTemplateExpression(expr)) {
+      const headText = expr.getHead().getLiteralText();
+      if (headText.trim()) classes.push(...headText.split(/\s+/).filter(Boolean));
+      for (const span of expr.getTemplateSpans()) {
+        const tailText = span.getLiteral().getLiteralText();
+        if (tailText.trim()) classes.push(...tailText.split(/\s+/).filter(Boolean));
+        this.extractClassesFromExpression(span.getExpression(), classes);
+      }
+      return;
+    }
+
+    // Parenthesized expression: unwrap
+    if (Node.isParenthesizedExpression(expr)) {
+      this.extractClassesFromExpression(expr.getExpression(), classes);
+      return;
+    }
+
+    // Binary expression with + concatenation: "class-a " + variable
+    if (Node.isBinaryExpression(expr)) {
+      this.extractClassesFromExpression(expr.getLeft(), classes);
+      this.extractClassesFromExpression(expr.getRight(), classes);
+      return;
+    }
+
+    // Call expression: cn(...), clsx(...) - extract string arguments
+    if (Node.isCallExpression(expr)) {
+      const callee = expr.getExpression().getText();
+      if (['cn', 'clsx', 'cva', 'twMerge'].includes(callee)) {
+        for (const arg of expr.getArguments()) {
+          this.extractClassesFromExpression(arg, classes);
+        }
+      }
+      return;
+    }
+
+    // Array literal: [condition && "class", "class-b"]
+    if (Node.isArrayLiteralExpression(expr)) {
+      for (const element of expr.getElements()) {
+        this.extractClassesFromExpression(element, classes);
+      }
+      return;
+    }
+
+    // Logical AND: condition && "classes"
+    if (Node.isBinaryExpression(expr) && expr.getOperatorToken().getText() === '&&') {
+      this.extractClassesFromExpression(expr.getRight(), classes);
+      return;
+    }
+  }
+
+  /**
+   * Check if a string looks like it contains Tailwind classes
+   */
+  private looksLikeTailwindClasses(value: string): boolean {
+    if (!value || value.length < 2) return false;
+
+    // Common Tailwind utility patterns (applied to the raw word after optional modifier stripping)
+    const tailwindPatterns = [
+      // Layout
+      /^(flex|grid|block|inline|hidden|table|contents)/,
+      /^(columns-|col-span-|row-span-)/,
+      // Flexbox / Grid alignment
+      /^(items-|justify-|self-|place-|content-|order-)/,
+      // Spacing
+      /^(bg-|text-|border-|rounded|shadow|ring-)/,
+      /^(p-|px-|py-|pt-|pb-|pl-|pr-|ps-|pe-)/,
+      /^(m-|mx-|my-|mt-|mb-|ml-|mr-|ms-|me-)/,
+      // Sizing
+      /^(w-|h-|min-w-|min-h-|max-w-|max-h-|size-)/,
+      // Spacing between children
+      /^(gap-|space-)/,
+      // Typography
+      /^(font-|leading-|tracking-|text-|truncate|line-clamp-)/,
+      // Positioning
+      /^(absolute|relative|fixed|sticky|static|inset-|top-|right-|bottom-|left-)/,
+      // Overflow / Visibility
+      /^(overflow-|z-|opacity-|visible|invisible|collapse)/,
+      // Transforms / Transitions / Animations
+      /^(transform|translate-|rotate-|scale-|skew-|origin-)/,
+      /^(transition-|duration-|ease-|delay-|animate-)/,
+      // Cursor / Pointer
+      /^(cursor-|pointer-events-|select-|touch-|scroll-)/,
+      // Aspect ratio / Object fit
+      /^(aspect-|object-)/,
+      // Modifiers (responsive, state, pseudo, dark)
+      /^(sm:|md:|lg:|xl:|2xl:|max-|min-\[)/,
+      /^(hover:|focus:|disabled:|active:|aria-|data-\[)/,
+      /^(dark:|placeholder:|file:|selection:|before:|after:)/,
+      /^(group-|peer-|first:|last:|odd:|even:)/,
+      // Colors with opacity modifier (bg-muted/50)
+      /\/.+$/,
+      // Arbitrary values (text-[13px], left-[calc(...)])
+      /\[.+\]/,
+      // Important modifier
+      /^!/,
+      // Negative values
+      /^-[a-z]/,
+      // Flex shorthand
+      /^(flex-1|flex-auto|flex-initial|flex-none|flex-shrink|flex-grow|flex-row|flex-col|flex-wrap|flex-nowrap)/,
+      // Container
+      /^container$/,
+      // sr-only
+      /^(sr-only|not-sr-only)$/,
+    ];
+
+    const words = value.split(/\s+/).filter(Boolean);
+    if (words.length === 0) return false;
+
+    // Strip modifier prefixes before matching utility core
+    const stripModifiers = (word: string): string => {
+      let w = word;
+      // Peel off known modifier layers (e.g. sm:hover:bg-primary -> bg-primary)
+      let changed = true;
+      while (changed) {
+        changed = false;
+        // Bracket-based modifiers
+        const bracketMatch = w.match(/^[a-z@-]*\[[^\]]*\]:(.*)/);
+        if (bracketMatch) { w = bracketMatch[1]; changed = true; continue; }
+        // Fixed modifiers (check common prefixes)
+        for (const prefix of ['sm:', 'md:', 'lg:', 'xl:', '2xl:', 'dark:', 'hover:', 'focus:', 'focus-visible:', 'focus-within:', 'active:', 'disabled:', 'group-hover:', 'group-focus:', 'peer-focus:', 'peer-disabled:', 'aria-invalid:', 'aria-selected:', 'aria-expanded:', 'placeholder:', 'file:', 'selection:', 'before:', 'after:', 'first:', 'last:', 'odd:', 'even:', 'required:', 'optional:', 'valid:', 'invalid:', 'checked:', 'open:', 'print:', 'motion-safe:', 'motion-reduce:', 'ltr:', 'rtl:', 'portrait:', 'landscape:', 'contrast-more:', 'contrast-less:', 'forced-colors:', 'autofill:', 'read-only:', 'max-sm:', 'max-md:', 'max-lg:', 'max-xl:', 'max-2xl:']) {
+          if (w.startsWith(prefix)) { w = w.slice(prefix.length); changed = true; break; }
+        }
+      }
+      return w;
+    };
+
+    // Check if at least one word matches a Tailwind pattern
+    return words.some(word => {
+      const stripped = stripModifiers(word);
+      return tailwindPatterns.some(pattern => pattern.test(stripped)) ||
+             tailwindPatterns.some(pattern => pattern.test(word));
+    });
+  }
+
+  /**
+   * Extract string value from a node (handles string literals, template literals, etc.)
+   */
+  private extractStringValue(node: Node): string {
+    if (Node.isStringLiteral(node)) {
+      return node.getLiteralValue();
+    }
+    if (Node.isNoSubstitutionTemplateLiteral(node)) {
+      return node.getLiteralValue();
+    }
+    if (Node.isTemplateExpression(node)) {
+      // For template expressions, just get the head text
+      return node.getHead().getLiteralText();
+    }
+    // Fallback: try to get text and strip quotes
+    const text = node.getText();
+    return text.replace(/^["'`]|["'`]$/g, '');
+  }
+
+  /**
+   * Infer the slot type from component name
+   */
+  private inferSlot(name: string): SubComponentInfo['slot'] {
+    const lower = name.toLowerCase();
+    if (lower.includes('header')) return 'header';
+    if (lower.includes('footer')) return 'footer';
+    if (lower.includes('title')) return 'title';
+    if (lower.includes('description')) return 'description';
+    if (lower.includes('content')) return 'content';
+    if (lower.includes('trigger')) return 'trigger';
+    if (lower.includes('item')) return 'item';
+    return 'container';
+  }
+}