@sun-asterisk/sungen 1.0.0

package/src/generators/ui-model-builder/react-scanner.ts

@@ -0,0 +1,959 @@
+/**
+ * React/Next.js UI Model Builder
+ * Scans React/Next.js source code to extract UI elements using heuristic analysis
+ */
+
+import * as parser from '@babel/parser';
+import traverse, { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import * as fs from 'fs';
+import * as path from 'path';
+import { glob } from 'glob';
+import { UIModel, UIElement, FrameworkType } from '../types';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+interface ScanConfig {
+  sourceRoot: string;
+  framework: FrameworkType;
+  verbose?: boolean;
+  maxDepth?: number;  // Maximum depth for component scanning (default: 999 = unlimited)
+}
+
+// ============================================================================
+// React Scanner Class
+// ============================================================================
+
+interface ComponentInfo {
+  name: string;           // Component name (e.g., "ChatInput")
+  importPath: string;     // Import path (e.g., "@/components/ChatInput")
+  sourceFile: string;     // File where component was used
+}
+
+export class ReactScanner {
+  private config: ScanConfig;
+  private elements: UIElement[] = [];
+  private elementCounter = 0;
+  private detectedComponents: ComponentInfo[] = [];
+  private scannedComponentPaths = new Set<string>(); // Avoid duplicate scans
+
+  constructor(config: ScanConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Discover all routes/screens in Next.js app directory
+   */
+  async discoverScreens(): Promise<string[]> {
+    const appDir = this.config.sourceRoot;
+
+    // Find all page.tsx/page.jsx files (Next.js 13+ app directory)
+    const pageFiles = await glob('**/page.{tsx,jsx}', {
+      cwd: appDir,
+      absolute: false,
+      ignore: ['**/node_modules/**', '**/api/**']
+    });
+
+    // Extract screen IDs from paths
+    // Example: "login/page.tsx" -> "login"
+    // Example: "auth/login/page.tsx" -> "auth-login"
+    // Example: "page.tsx" -> "home"
+    const screens = pageFiles.map(file => {
+      const dir = path.dirname(file);
+      return dir === '.' ? 'home' : dir.replace(/\//g, '-');
+    });
+
+    return screens;
+  }
+
+  /**
+   * Build UI Model for a specific screen
+   */
+  async buildUIModel(screenId: string): Promise<UIModel> {
+    // Reset state for new screen
+    this.elements = [];
+    this.elementCounter = 0;
+    this.detectedComponents = [];
+    this.scannedComponentPaths.clear();
+
+    // Determine route path from screen ID
+    // "home" -> "" (root)
+    // "auth-login" -> "auth/login"
+    const routePath = screenId === 'home' ? '' : screenId.replace(/-/g, '/');
+    const routeDir = path.join(this.config.sourceRoot, routePath);
+
+    // Collect source files to scan
+    const sourceFiles: string[] = [];
+
+    // 1. App root layout
+    const rootLayout = path.join(this.config.sourceRoot, 'layout.tsx');
+    if (fs.existsSync(rootLayout)) {
+      sourceFiles.push(rootLayout);
+    }
+
+    // 2. Route-specific layout (if exists)
+    const routeLayout = path.join(routeDir, 'layout.tsx');
+    if (fs.existsSync(routeLayout)) {
+      sourceFiles.push(routeLayout);
+    }
+
+    // 3. Page component
+    const pageTsx = path.join(routeDir, 'page.tsx');
+    const pageJsx = path.join(routeDir, 'page.jsx');
+    if (fs.existsSync(pageTsx)) {
+      sourceFiles.push(pageTsx);
+    } else if (fs.existsSync(pageJsx)) {
+      sourceFiles.push(pageJsx);
+    } else {
+      throw new Error(`Page component not found for screen: ${screenId} at ${routeDir}`);
+    }
+
+    // Phase 1: Scan all source files (page components)
+    for (const filePath of sourceFiles) {
+      await this.scanFile(filePath);
+    }
+
+    // Phase 2: Scan detected components (unlimited depth by default)
+    const maxDepth = this.config.maxDepth !== undefined ? this.config.maxDepth : 999; // Default unlimited
+    const depthLabel = maxDepth === 999 ? 'unlimited' : maxDepth.toString();
+    if (this.config.verbose && this.detectedComponents.length > 0) {
+      console.log(`  Detected ${this.detectedComponents.length} component(s), scanning with depth=${depthLabel}...`);
+    }
+
+    await this.scanComponentsRecursive(this.detectedComponents, 1, maxDepth);
+
+    // Build and return UI Model
+    const uiModel: UIModel = {
+      screenId,
+      routeId: routePath || 'home',
+      framework: this.config.framework,
+      sourceFiles: sourceFiles.map(f => path.relative(this.config.sourceRoot, f)),
+      elements: this.elements,
+      metadata: {
+        scannedAt: new Date().toISOString(),
+        version: '1.0.0',
+        hash: this.generateHash(this.elements)
+      }
+    };
+
+    return uiModel;
+  }
+
+  /**
+   * Scan a single file and extract UI elements
+   */
+  private async scanFile(filePath: string): Promise<void> {
+    const sourceFileName = path.basename(filePath);
+    const importMap = new Map<string, string>(); // componentName → importPath
+
+    if (this.config.verbose) {
+      console.log(`  Scanning: ${filePath}`);
+    }
+
+    const code = fs.readFileSync(filePath, 'utf-8');
+
+    // Parse with Babel
+    const ast = parser.parse(code, {
+      sourceType: 'module',
+      plugins: ['typescript', 'jsx']
+    });
+
+    // Traverse AST to extract imports and JSX elements
+    traverse(ast, {
+      // Detect imports
+      ImportDeclaration: (path: NodePath<t.ImportDeclaration>) => {
+        const importPath = path.node.source.value;
+
+        // Extract default import: import ChatInput from '...'
+        const defaultSpecifier = path.node.specifiers.find(s => t.isImportDefaultSpecifier(s));
+        if (defaultSpecifier && t.isImportDefaultSpecifier(defaultSpecifier)) {
+          const componentName = defaultSpecifier.local.name;
+          importMap.set(componentName, importPath);
+        }
+
+        // Extract named imports: import { Button } from '...'
+        path.node.specifiers
+          .filter(s => t.isImportSpecifier(s))
+          .forEach(specifier => {
+            if (t.isImportSpecifier(specifier) && t.isIdentifier(specifier.imported)) {
+              const componentName = specifier.imported.name;
+              importMap.set(componentName, importPath);
+            }
+          });
+      },
+
+      // Extract JSX elements
+      JSXElement: (path: NodePath<t.JSXElement>) => {
+        this.extractElement(path, sourceFileName, filePath, importMap);
+      },
+
+      // PHASE 1: Detect conditional rendering patterns
+      JSXExpressionContainer: (path: NodePath<t.JSXExpressionContainer>) => {
+        this.detectConditionalElements(path, sourceFileName, filePath, importMap);
+      }
+    });
+  }
+
+  /**
+   * Smart element filter - determines if element should be scanned
+   */
+  private shouldScanElement(
+    tagName: string,
+    attributes: Record<string, string>,
+    textContent: string | null,
+    path?: NodePath<t.JSXElement>
+  ): boolean {
+    const lowercaseTag = tagName.toLowerCase();
+
+    // 1. Always scan form elements
+    const formElements = ['input', 'button', 'textarea', 'select', 'form'];
+    if (formElements.includes(lowercaseTag)) return true;
+
+    // 2. Always scan links (a, Link)
+    if (lowercaseTag === 'a' || tagName === 'Link') return true;
+
+    // 3. Scan headings with text content
+    if (/^h[1-6]$/.test(lowercaseTag) && textContent) return true;
+
+    // 4. Scan images with alt text
+    if (lowercaseTag === 'img' && attributes['alt']) return true;
+
+    // 5. Scan elements with identifying attributes
+    const hasIdentifier =
+      attributes['id'] ||
+      attributes['name'] ||
+      attributes['data-testid'] ||
+      attributes['data-test-id'] ||
+      attributes['aria-label'] ||
+      attributes['ariaLabel'];
+    if (hasIdentifier) return true;
+
+    // 6. Scan semantic components (ChatInput, SubmitButton, UserProfile, etc.)
+    // Pattern: *Input, *Field, *TextArea, *Select, *Button, *Link, *Form
+    const semanticPatterns = [
+      /Input$/,      // ChatInput, MessageInput
+      /Field$/,      // TextField, EmailField
+      /TextArea$/,   // MessageTextArea
+      /Select$/,     // CountrySelect
+      /Button$/,     // SubmitButton, CancelButton
+      /Link$/,       // NavLink
+      /Form$/,       // LoginForm
+      /Avatar$/,     // UserAvatar
+      /Icon$/,       // SearchIcon
+      /Image$/,      // ProfileImage
+      /Card$/,       // UserCard
+      /List$/,       // MessageList
+      /Item$/        // ListItem
+    ];
+
+    if (semanticPatterns.some(pattern => pattern.test(tagName))) {
+      return true;
+    }
+
+    // 7. Scan text containers with content
+    const textContainers = ['p', 'span', 'div', 'section', 'article'];
+    if (textContainers.includes(lowercaseTag) && textContent && textContent.length > 0) {
+      return true;
+    }
+
+    // 7.5. PHASE 1.5: Scan error/success message elements by className pattern (even without text)
+    const className = attributes['className'] || '';
+    const isErrorOrSuccessMessage =
+      className.includes('text-red') ||
+      className.includes('text-green') ||
+      className.includes('bg-red') ||
+      className.includes('bg-green') ||
+      className.includes('error') ||
+      className.includes('success') ||
+      className.includes('alert');
+
+    if (textContainers.includes(lowercaseTag) && isErrorOrSuccessMessage) {
+      return true;
+    }
+
+    // 7.6. PHASE 1.6: Scan timestamp/metadata elements by className pattern
+    // Fix for elements with dynamic expressions like {timestamp.toLocaleTimeString()}
+    const isTimestampOrMetadata =
+      className.includes('timestamp') ||
+      className.includes('time') ||
+      (className.includes('text-xs') && className.includes('text-gray')) ||
+      (className.includes('text-sm') && className.includes('text-gray') && className.includes('mt-'));
+
+    if (textContainers.includes(lowercaseTag) && isTimestampOrMetadata) {
+      return true;
+    }
+
+    // 8. NEW: Smart container detection for structural elements
+    if (['div', 'section', 'article', 'main', 'aside', 'nav'].includes(lowercaseTag)) {
+      if (path && this.shouldScanContainer(tagName, attributes, path)) {
+        return true;
+      }
+    }
+
+    return false; // Skip everything else
+  }
+
+  /**
+   * Smart container detection - checks if container is structurally important
+   * NEW: Phase 1 - Task 1
+   */
+  private shouldScanContainer(
+    tagName: string,
+    attributes: Record<string, string>,
+    path: NodePath<t.JSXElement>
+  ): boolean {
+
+    // 1. Has important children (form elements, buttons, custom components)?
+    const children = path.node.children.filter(child => t.isJSXElement(child)) as t.JSXElement[];
+
+    for (const child of children) {
+      const childTag = this.getTagName(child.openingElement.name);
+      const childTagLower = childTag.toLowerCase();
+
+      // Has form elements
+      if (['input', 'button', 'textarea', 'select', 'form'].includes(childTagLower)) {
+        return true;
+      }
+
+      // Has custom components (PascalCase)
+      if (/^[A-Z]/.test(childTag)) {
+        return true;
+      }
+    }
+
+    // 2. Semantic className keywords
+    const className = attributes['className'] || '';
+    const semanticKeywords = [
+      'message', 'messages', 'chat',
+      'list', 'items',
+      'container', 'wrapper', 'content',
+      'scroll', 'overflow',
+      'grid', 'flex'
+    ];
+
+    const hasSemanticClass = semanticKeywords.some(keyword =>
+      className.toLowerCase().includes(keyword)
+    );
+    if (hasSemanticClass) {
+      return true;
+    }
+
+    // 3. Has scroll behavior (overflow-auto, overflow-y-auto, etc.)
+    if (className.includes('overflow')) {
+      return true;
+    }
+
+    // 4. Has ARIA role
+    if (attributes['role']) {
+      return true;
+    }
+
+    // 5. Has ref (often used for important containers)
+    if (attributes['ref']) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Extract UI element from JSX node
+   */
+  private extractElement(
+    path: NodePath<t.JSXElement>,
+    sourceFile: string,
+    fullFilePath: string,
+    importMap: Map<string, string>
+  ): void {
+    const openingElement = path.node.openingElement;
+    const tagName = this.getTagName(openingElement.name);
+
+    // Extract attributes and text first (needed for filtering)
+    const attributes = this.extractAttributes(openingElement.attributes);
+    const textContent = this.extractTextContent(path.node);
+
+    // Check if this is a custom component (starts with uppercase)
+    const isCustomComponent = /^[A-Z]/.test(tagName);
+
+    // If it's a custom component and we have an import for it, track it for scanning
+    // UPDATED: Phase 1 - Task 2 - Track ALL PascalCase components, not just semantic patterns
+    if (isCustomComponent && importMap.has(tagName)) {
+      const importPath = importMap.get(tagName)!;
+
+      // Check if not already tracked
+      const alreadyTracked = this.detectedComponents.some(c => c.name === tagName && c.importPath === importPath);
+      if (!alreadyTracked) {
+        this.detectedComponents.push({
+          name: tagName,
+          importPath,
+          sourceFile: fullFilePath
+        });
+
+        if (this.config.verbose) {
+          console.log(`    Found component: ${tagName} from ${importPath}`);
+        }
+      }
+    }
+
+    // Use smart filter instead of static whitelist (pass path for container detection)
+    if (!this.shouldScanElement(tagName, attributes, textContent, path)) {
+      return; // Skip non-scannable elements
+    }
+
+    // Build UI Element
+    const element: UIElement = {
+      key: `e${++this.elementCounter}`,
+      tag: tagName.toLowerCase(),
+      role: attributes['role'] || this.inferRole(tagName),
+      name: attributes['name'],
+      id: attributes['id'],
+      placeholder: attributes['placeholder'],
+      ariaLabel: attributes['aria-label'] || attributes['ariaLabel'],
+      testId: attributes['data-testid'] || attributes['data-test-id'],
+      text: textContent || attributes['value'],
+      source: sourceFile,
+      props: attributes
+    };
+
+    // Add label if associated
+    if (attributes['aria-labelledby']) {
+      element.label = `[ref:${attributes['aria-labelledby']}]`;
+    }
+
+    this.elements.push(element);
+  }
+
+  /**
+   * PHASE 1: Detect and extract conditionally rendered elements
+   * Handles patterns: {condition && <Element />}, {condition ? <A /> : <B />}, {arr.map(...)}
+   * PHASE 1.5: Now also traverses nested children
+   */
+  private detectConditionalElements(
+    path: NodePath<t.JSXExpressionContainer>,
+    sourceFile: string,
+    fullFilePath: string,
+    importMap: Map<string, string>
+  ): void {
+    const expr = path.node.expression;
+
+    // Pattern 1: Logical AND (condition && <Element />)
+    if (t.isLogicalExpression(expr, { operator: '&&' })) {
+      const rightSide = expr.right;
+
+      if (t.isJSXElement(rightSide)) {
+        // Extract the direct element
+        this.extractConditionalElement(rightSide, sourceFile, fullFilePath, importMap, 'conditional-and');
+
+        // PHASE 1.5: Also traverse nested children
+        this.traverseConditionalChildren(rightSide, sourceFile, fullFilePath, importMap, 'conditional-nested');
+      } else if (t.isJSXFragment(rightSide)) {
+        // Handle {condition && (<><Element1 /><Element2 /></>)}
+        this.extractFragmentElements(rightSide, sourceFile, fullFilePath, importMap, 'conditional-and');
+      }
+    }
+
+    // Pattern 2: Ternary operator (condition ? <A /> : <B />)
+    if (t.isConditionalExpression(expr)) {
+      const consequent = expr.consequent;
+      const alternate = expr.alternate;
+
+      if (t.isJSXElement(consequent)) {
+        this.extractConditionalElement(consequent, sourceFile, fullFilePath, importMap, 'conditional-true');
+        // PHASE 1.5: Traverse nested children
+        this.traverseConditionalChildren(consequent, sourceFile, fullFilePath, importMap, 'conditional-nested');
+      }
+
+      if (t.isJSXElement(alternate)) {
+        this.extractConditionalElement(alternate, sourceFile, fullFilePath, importMap, 'conditional-false');
+        // PHASE 1.5: Traverse nested children
+        this.traverseConditionalChildren(alternate, sourceFile, fullFilePath, importMap, 'conditional-nested');
+      }
+    }
+
+    // Pattern 3: Array.map() rendering (arr.map(item => <Element />))
+    if (t.isCallExpression(expr)) {
+      const callee = expr.callee;
+
+      // Check if it's a .map() call
+      if (t.isMemberExpression(callee) && t.isIdentifier(callee.property, { name: 'map' })) {
+        const mapCallback = expr.arguments[0];
+
+        if (t.isArrowFunctionExpression(mapCallback) || t.isFunctionExpression(mapCallback)) {
+          const body = mapCallback.body;
+
+          // Case 1: Direct return - arr.map(item => <Element />)
+          if (t.isJSXElement(body)) {
+            this.extractConditionalElement(body, sourceFile, fullFilePath, importMap, 'loop-item');
+          }
+
+          // Case 2: Block with return - arr.map(item => { return <Element /> })
+          if (t.isBlockStatement(body)) {
+            for (const statement of body.body) {
+              if (t.isReturnStatement(statement) && statement.argument && t.isJSXElement(statement.argument)) {
+                this.extractConditionalElement(statement.argument, sourceFile, fullFilePath, importMap, 'loop-item');
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract elements from JSX Fragment
+   */
+  private extractFragmentElements(
+    fragment: t.JSXFragment,
+    sourceFile: string,
+    fullFilePath: string,
+    importMap: Map<string, string>,
+    renderType: string
+  ): void {
+    for (const child of fragment.children) {
+      if (t.isJSXElement(child)) {
+        this.extractConditionalElement(child, sourceFile, fullFilePath, importMap, renderType);
+      }
+    }
+  }
+
+  /**
+   * PHASE 1.5: Traverse nested children of conditional elements
+   * Example: {error && <div><p>{error}</p></div>} - detect the nested <p> tag
+   */
+  private traverseConditionalChildren(
+    element: t.JSXElement,
+    sourceFile: string,
+    fullFilePath: string,
+    importMap: Map<string, string>,
+    renderType: string
+  ): void {
+    for (const child of element.children) {
+      // Traverse nested JSX elements
+      if (t.isJSXElement(child)) {
+        const openingElement = child.openingElement;
+        const tagName = this.getTagName(openingElement.name);
+        const attributes = this.extractAttributes(openingElement.attributes);
+        const textContent = this.extractTextContent(child);
+
+        // Check if this nested element should be scanned
+        if (this.shouldScanElement(tagName, attributes, textContent, undefined)) {
+          this.extractConditionalElement(child, sourceFile, fullFilePath, importMap, renderType);
+        }
+
+        // Recursively traverse deeper children
+        this.traverseConditionalChildren(child, sourceFile, fullFilePath, importMap, renderType);
+      }
+
+      // Traverse JSX expression containers (for nested dynamic content)
+      if (t.isJSXExpressionContainer(child)) {
+        const expr = child.expression;
+
+        // Handle nested JSX elements in expressions
+        if (t.isJSXElement(expr)) {
+          this.extractConditionalElement(expr, sourceFile, fullFilePath, importMap, renderType);
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract a conditionally rendered JSX element
+   */
+  private extractConditionalElement(
+    jsxElement: t.JSXElement,
+    sourceFile: string,
+    fullFilePath: string,
+    importMap: Map<string, string>,
+    renderType: string
+  ): void {
+    const openingElement = jsxElement.openingElement;
+    const tagName = this.getTagName(openingElement.name);
+
+    // Extract attributes and text
+    const attributes = this.extractAttributes(openingElement.attributes);
+    const textContent = this.extractTextContent(jsxElement);
+
+    // Check if this is a custom component
+    const isCustomComponent = /^[A-Z]/.test(tagName);
+    if (isCustomComponent && importMap.has(tagName)) {
+      const importPath = importMap.get(tagName)!;
+      const alreadyTracked = this.detectedComponents.some(c => c.name === tagName && c.importPath === importPath);
+      if (!alreadyTracked) {
+        this.detectedComponents.push({
+          name: tagName,
+          importPath,
+          sourceFile: fullFilePath
+        });
+      }
+    }
+
+    // Use smart filter to decide if we should scan this element
+    if (!this.shouldScanElement(tagName, attributes, textContent, undefined)) {
+      return;
+    }
+
+    // Build UI Element with conditional marker
+    const element: UIElement = {
+      key: `e${++this.elementCounter}`,
+      tag: tagName.toLowerCase(),
+      role: attributes['role'] || this.inferRole(tagName),
+      name: attributes['name'],
+      id: attributes['id'],
+      placeholder: attributes['placeholder'],
+      ariaLabel: attributes['aria-label'] || attributes['ariaLabel'],
+      testId: attributes['data-testid'] || attributes['data-test-id'],
+      text: textContent || attributes['value'],
+      source: sourceFile,
+      props: {
+        ...attributes,
+        isConditional: renderType // Mark as conditional with type
+      }
+    };
+
+    if (attributes['aria-labelledby']) {
+      element.label = `[ref:${attributes['aria-labelledby']}]`;
+    }
+
+    this.elements.push(element);
+
+    if (this.config.verbose) {
+      console.log(`    Found conditional element: ${tagName} (${renderType})`);
+    }
+  }
+
+  /**
+   * Get tag name from JSX element
+   */
+  private getTagName(name: t.JSXElement['openingElement']['name']): string {
+    if (t.isJSXIdentifier(name)) {
+      return name.name;
+    }
+    if (t.isJSXMemberExpression(name)) {
+      // Handle cases like <Form.Input />
+      return this.getTagName(name.property);
+    }
+    return 'unknown';
+  }
+
+  /**
+   * Extract attributes from JSX element
+   */
+  private extractAttributes(attributes: (t.JSXAttribute | t.JSXSpreadAttribute)[]): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const attr of attributes) {
+      if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name)) {
+        const name = attr.name.name;
+        const value = this.getAttributeValue(attr.value);
+        if (value !== null) {
+          result[name] = value;
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get attribute value
+   */
+  private getAttributeValue(value: t.JSXAttribute['value']): string | null {
+    if (!value) return null;
+
+    if (t.isStringLiteral(value)) {
+      return value.value;
+    }
+
+    if (t.isJSXExpressionContainer(value)) {
+      const expr = value.expression;
+
+      // Handle string literals in expressions
+      if (t.isStringLiteral(expr)) {
+        return expr.value;
+      }
+
+      // Handle template literals
+      if (t.isTemplateLiteral(expr) && expr.quasis.length === 1) {
+        return expr.quasis[0].value.cooked || '';
+      }
+
+      // For complex expressions, return placeholder
+      return '[expression]';
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract text content from JSX element
+   * PHASE 1 ENHANCED: Extract text from dynamic expressions
+   */
+  private extractTextContent(node: t.JSXElement): string | null {
+    const children = node.children;
+    const textParts: string[] = [];
+
+    for (const child of children) {
+      if (t.isJSXText(child)) {
+        const text = child.value.trim();
+        if (text) textParts.push(text);
+      }
+
+      if (t.isJSXExpressionContainer(child)) {
+        const expr = child.expression;
+
+        // Static string literal
+        if (t.isStringLiteral(expr)) {
+          textParts.push(expr.value);
+        }
+
+        // PHASE 1: Extract text from ternary (condition ? 'Text A' : 'Text B')
+        if (t.isConditionalExpression(expr)) {
+          const texts: string[] = [];
+
+          if (t.isStringLiteral(expr.consequent)) {
+            texts.push(expr.consequent.value);
+          }
+
+          if (t.isStringLiteral(expr.alternate)) {
+            texts.push(expr.alternate.value);
+          }
+
+          if (texts.length > 0) {
+            textParts.push(texts.join(' / ')); // e.g., "Copy / Copied!"
+          }
+        }
+
+        // PHASE 1: Extract text from logical OR (defaultValue || 'Fallback')
+        if (t.isLogicalExpression(expr, { operator: '||' })) {
+          if (t.isStringLiteral(expr.right)) {
+            textParts.push(expr.right.value);
+          }
+        }
+      }
+    }
+
+    return textParts.length > 0 ? textParts.join(' ') : null;
+  }
+
+  /**
+   * Infer ARIA role from tag name
+   */
+  private inferRole(tagName: string): string | undefined {
+    const roleMap: Record<string, string> = {
+      'button': 'button',
+      'input': 'textbox',
+      'textarea': 'textbox',
+      'select': 'combobox',
+      'a': 'link',
+      'form': 'form'
+    };
+
+    return roleMap[tagName.toLowerCase()];
+  }
+
+  /**
+   * Resolve component import path to actual file path
+   */
+  private resolveComponentPath(importPath: string, sourceFile: string): string | null {
+    try {
+      // Handle different import path formats
+      let resolvedPath: string;
+
+      if (importPath.startsWith('@/')) {
+        // Alias import: @/components/ChatInput → PROJECT_ROOT/components/ChatInput.tsx
+        // Note: @ alias points to project root, not sourceRoot (app/)
+        const projectRoot = path.resolve(this.config.sourceRoot, '..');
+        const relativePath = importPath.replace('@/', '');
+        resolvedPath = path.join(projectRoot, relativePath);
+      } else if (importPath.startsWith('./') || importPath.startsWith('../')) {
+        // Relative import: ./components/ChatInput
+        const sourceDir = path.dirname(sourceFile);
+        resolvedPath = path.join(sourceDir, importPath);
+      } else {
+        // Absolute or node_modules import - skip
+        return null;
+      }
+
+      // Try different file extensions
+      const extensions = ['.tsx', '.ts', '.jsx', '.js'];
+      for (const ext of extensions) {
+        const fullPath = resolvedPath + ext;
+        if (fs.existsSync(fullPath)) {
+          return fullPath;
+        }
+      }
+
+      // Try index files
+      for (const ext of extensions) {
+        const indexPath = path.join(resolvedPath, `index${ext}`);
+        if (fs.existsSync(indexPath)) {
+          return indexPath;
+        }
+      }
+
+      return null;
+    } catch (error) {
+      if (this.config.verbose) {
+        console.log(`    Could not resolve: ${importPath}`);
+      }
+      return null;
+    }
+  }
+
+  /**
+   * NEW: Recursively scan components at multiple depths
+   * @param components - List of components to scan
+   * @param currentDepth - Current depth level
+   * @param maxDepth - Maximum depth to scan
+   */
+  private async scanComponentsRecursive(
+    components: ComponentInfo[],
+    currentDepth: number,
+    maxDepth: number
+  ): Promise<void> {
+    if (currentDepth > maxDepth) {
+      return; // Stop recursion at max depth
+    }
+
+    const startTime = Date.now();
+    const componentsScanned: ComponentInfo[] = [];
+
+    // Scan all components at current level
+    for (const component of components) {
+      const componentPath = this.resolveComponentPath(component.importPath, component.sourceFile);
+
+      if (!componentPath) {
+        continue; // Skip if path cannot be resolved
+      }
+
+      // Skip node_modules
+      if (componentPath.includes('node_modules')) {
+        if (this.config.verbose) {
+          console.log(`    Skipping node_modules: ${componentPath}`);
+        }
+        continue;
+      }
+
+      // Skip if already scanned (avoid duplicates)
+      if (this.scannedComponentPaths.has(componentPath)) {
+        continue;
+      }
+
+      // Mark as scanned
+      this.scannedComponentPaths.add(componentPath);
+
+      // Store the count of detected components before scanning
+      const detectedCountBefore = this.detectedComponents.length;
+
+      // Scan the component file
+      await this.scanComponentFile(componentPath, component.name);
+
+      // Track newly detected components from this scan
+      const newlyDetected = this.detectedComponents.slice(detectedCountBefore);
+      componentsScanned.push(...newlyDetected);
+    }
+
+    const elapsed = Date.now() - startTime;
+    if (this.config.verbose && componentsScanned.length > 0) {
+      console.log(`    [Depth ${currentDepth}] Scanned ${components.length} component(s), found ${componentsScanned.length} sub-component(s) (${elapsed}ms)`);
+    }
+
+    // Recursively scan newly detected components at next depth
+    if (componentsScanned.length > 0 && currentDepth < maxDepth) {
+      await this.scanComponentsRecursive(componentsScanned, currentDepth + 1, maxDepth);
+    }
+  }
+
+  /**
+   * Scan component file and extract elements
+   */
+  private async scanComponentFile(componentPath: string, componentName: string): Promise<void> {
+    if (this.config.verbose) {
+      console.log(`    Scanning component: ${componentName} at ${componentPath}`);
+    }
+
+    const code = fs.readFileSync(componentPath, 'utf-8');
+
+    // Parse with Babel
+    const ast = parser.parse(code, {
+      sourceType: 'module',
+      plugins: ['typescript', 'jsx']
+    });
+
+    const importMap = new Map<string, string>(); // Empty import map for component scanning
+
+    // Traverse AST and extract JSX elements (no nested component scanning)
+    traverse(ast, {
+      JSXElement: (path: NodePath<t.JSXElement>) => {
+        const openingElement = path.node.openingElement;
+        const tagName = this.getTagName(openingElement.name);
+
+        // Extract attributes and text
+        const attributes = this.extractAttributes(openingElement.attributes);
+        const textContent = this.extractTextContent(path.node);
+
+        // Use smart filter (pass path for container detection)
+        if (!this.shouldScanElement(tagName, attributes, textContent, path)) {
+          return;
+        }
+
+        // Build UI Element with component context
+        const element: UIElement = {
+          key: `e${++this.elementCounter}`,
+          tag: tagName.toLowerCase(),
+          role: attributes['role'] || this.inferRole(tagName),
+          name: attributes['name'],
+          id: attributes['id'],
+          placeholder: attributes['placeholder'],
+          ariaLabel: attributes['aria-label'] || attributes['ariaLabel'],
+          testId: attributes['data-testid'] || attributes['data-test-id'],
+          text: textContent || attributes['value'],
+          source: `${componentName}.tsx`, // Mark as from component
+          props: attributes
+        };
+
+        // Add label if associated
+        if (attributes['aria-labelledby']) {
+          element.label = `[ref:${attributes['aria-labelledby']}]`;
+        }
+
+        this.elements.push(element);
+      },
+
+      // PHASE 1: Detect conditional rendering in components too
+      JSXExpressionContainer: (path: NodePath<t.JSXExpressionContainer>) => {
+        this.detectConditionalElements(path, `${componentName}.tsx`, componentPath, importMap);
+      }
+    });
+  }
+
+  /**
+   * Generate hash for cache key
+   */
+  private generateHash(elements: UIElement[]): string {
+    const crypto = require('crypto');
+    const content = JSON.stringify(elements);
+    return crypto.createHash('sha256').update(content).digest('hex');
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export async function buildUIModel(
+  screenId: string,
+  config: ScanConfig
+): Promise<UIModel> {
+  const scanner = new ReactScanner(config);
+  return scanner.buildUIModel(screenId);
+}
+
+export async function discoverScreens(
+  config: ScanConfig
+): Promise<string[]> {
+  const scanner = new ReactScanner(config);
+  return scanner.discoverScreens();
+}