zelune 1.5.7 → 1.6.1

package/src/server/astEngine.ts

@@ -63,6 +63,35 @@ export interface ReorderPayload {
   direction?: 'up' | 'down';
 }
 
+export type InsertElementPreset =
+  | 'button'
+  | 'section'
+  | 'row'
+  | 'heading'
+  | 'text'
+  | 'input'
+  | 'badge'
+  | 'divider';
+
+export interface InsertElementPayload {
+  file: string;
+  astPath?: string;
+  placement?: 'inside' | 'after' | 'before';
+  preset: InsertElementPreset;
+  label?: string;
+  navigateTo?: string;
+}
+
+export interface DuplicateElementPayload {
+  file: string;
+  astPath: string;
+}
+
+export interface DeleteElementPayload {
+  file: string;
+  astPath: string;
+}
+
 interface HistoryEntry {
   file: string;
   previousContent: string;
@@ -499,14 +528,19 @@ function extractElementNavigationTarget(openingElement: t.JSXOpeningElement): st
   for (const attr of openingElement.attributes) {
     if (
       t.isJSXAttribute(attr) &&
-      t.isJSXIdentifier(attr.name, { name: 'onPress' }) &&
-      t.isJSXExpressionContainer(attr.value)
+      t.isJSXIdentifier(attr.name) &&
+      ['onPress', 'href', 'to'].includes(attr.name.name)
     ) {
-      const expr = attr.value.expression;
-      if (t.isArrowFunctionExpression(expr) || t.isFunctionExpression(expr)) {
+      if (t.isStringLiteral(attr.value)) {
+        return normalizeRouteTarget(attr.value.value);
+      }
+      if (t.isJSXExpressionContainer(attr.value)) {
+        const expr = attr.value.expression;
         const codeStr = generate(expr).code;
-        const match = codeStr.match(/(?:navigate|push|replace)\(\s*['"]([^'"]+)['"]/);
+        const match = codeStr.match(/(?:navigate|push|replace|jumpTo)\(\s*['"`]([^'"`$]+)['"`]/);
         if (match) return normalizeRouteTarget(match[1]);
+        const objMatch = codeStr.match(/(?:pathname|screen|route|name)\s*:\s*['"`]([^'"`$]+)['"`]/);
+        if (objMatch) return normalizeRouteTarget(objMatch[1]);
       }
     }
   }
@@ -675,13 +709,190 @@ export function discoverScreenFilesSync(workspaceRoot: string): DiscoveredScreen
   return files;
 }
 
+function computeScreenStem(idOrName: string): string {
+  return idOrName
+    .toLowerCase()
+    .replace(/(?:screen|page|view|tab|modal|stack|details|detail|list)$/i, '')
+    .replace(/[-_/\s]+/g, '')
+    .replace(/s$/, '');
+}
+
+function unwrapAstNode(node: t.Node | null | undefined): t.Node | null {
+  let curr = node ?? null;
+  while (curr) {
+    if (
+      t.isTSAsExpression(curr) ||
+      t.isTSTypeAssertion(curr) ||
+      t.isTSNonNullExpression(curr) ||
+      t.isTSSatisfiesExpression(curr) ||
+      t.isParenthesizedExpression(curr)
+    ) {
+      curr = curr.expression;
+    } else {
+      break;
+    }
+  }
+  return curr;
+}
+
+function extractRouteStringsFromAstNode(node: t.Node | null | undefined, depth = 0): string[] {
+  if (depth > 4) return [];
+  const unwrapped = unwrapAstNode(node);
+  if (!unwrapped) return [];
+
+  if (t.isStringLiteral(unwrapped)) {
+    return [unwrapped.value];
+  }
+  if (t.isTemplateLiteral(unwrapped)) {
+    const joined = unwrapped.quasis.map((q) => q.value.cooked ?? q.value.raw).join('id');
+    return joined ? [joined] : [];
+  }
+  if (t.isConditionalExpression(unwrapped)) {
+    return [
+      ...extractRouteStringsFromAstNode(unwrapped.consequent, depth + 1),
+      ...extractRouteStringsFromAstNode(unwrapped.alternate, depth + 1),
+    ];
+  }
+  if (t.isLogicalExpression(unwrapped)) {
+    return [
+      ...extractRouteStringsFromAstNode(unwrapped.left, depth + 1),
+      ...extractRouteStringsFromAstNode(unwrapped.right, depth + 1),
+    ];
+  }
+  if (t.isArrayExpression(unwrapped)) {
+    const out: string[] = [];
+    for (const el of unwrapped.elements) {
+      if (el) out.push(...extractRouteStringsFromAstNode(el, depth + 1));
+    }
+    return out;
+  }
+  if (t.isObjectExpression(unwrapped)) {
+    const out: string[] = [];
+    const routeKeys = new Set([
+      'screen',
+      'pathname',
+      'route',
+      'href',
+      'name',
+      'path',
+      'target',
+      'to',
+      'destination',
+      'params',
+      'routes',
+    ]);
+    for (const prop of unwrapped.properties) {
+      if (t.isObjectProperty(prop)) {
+        const keyName = t.isIdentifier(prop.key)
+          ? prop.key.name
+          : t.isStringLiteral(prop.key)
+            ? prop.key.value
+            : '';
+        if (routeKeys.has(keyName)) {
+          out.push(...extractRouteStringsFromAstNode(prop.value, depth + 1));
+        }
+      }
+    }
+    return out;
+  }
+  return [];
+}
+
+function resolveCandidateToScreenId(
+  rawCandidate: string,
+  screenFiles: DiscoveredScreenFile[],
+  currentScreenId: string,
+  allowUnmatchedFallback = false
+): string | null {
+  const trimmed = rawCandidate.trim();
+  if (!trimmed || trimmed.length > 80) return null;
+  if (
+    trimmed.startsWith('http://') ||
+    trimmed.startsWith('https://') ||
+    trimmed.startsWith('mailto:') ||
+    trimmed.startsWith('tel:') ||
+    trimmed.startsWith('#') ||
+    /\.(png|jpg|jpeg|svg|webp|gif|json|css)$/i.test(trimmed)
+  ) {
+    return null;
+  }
+
+  const normalized = normalizeRouteTarget(trimmed);
+  if (!normalized || normalized.toLowerCase() === currentScreenId.toLowerCase()) {
+    return null;
+  }
+
+  // 1. Exact ID or Screen Name match (case-insensitive)
+  for (const s of screenFiles) {
+    if (s.id.toLowerCase() === currentScreenId.toLowerCase()) continue;
+    const sIdLower = s.id.toLowerCase();
+    const sNameLower = s.name.toLowerCase();
+    const normLower = normalized.toLowerCase();
+    if (
+      sIdLower === normLower ||
+      sNameLower === normLower ||
+      sNameLower === `${normLower}screen`
+    ) {
+      return s.id;
+    }
+  }
+
+  // 2. Path segment match (from right to left, ignoring group/param/id segments)
+  const segments = trimmed
+    .split(/[/.]/)
+    .map((seg) => seg.trim())
+    .filter(
+      (seg) =>
+        seg.length > 0 &&
+        !seg.startsWith('(') &&
+        !seg.startsWith('[') &&
+        seg.toLowerCase() !== 'id' &&
+        seg.toLowerCase() !== 'index' &&
+        !/^\d+$/.test(seg)
+    );
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segNorm = normalizeRouteTarget(segments[i]).toLowerCase();
+    for (const s of screenFiles) {
+      if (s.id.toLowerCase() === currentScreenId.toLowerCase()) continue;
+      if (s.id.toLowerCase() === segNorm || s.name.toLowerCase() === `${segNorm}screen`) {
+        return s.id;
+      }
+    }
+  }
+
+  // 3. Stem / singular-plural / prefix match (e.g. 'dealer'/'dealers' -> 'DealerDetails', 'spare-parts' -> 'Parts')
+  const candidateStems = [
+    computeScreenStem(normalized),
+    ...segments.map((seg) => computeScreenStem(seg)),
+  ].filter((st) => st.length >= 4);
+
+  for (const candStem of candidateStems) {
+    for (const s of screenFiles) {
+      if (s.id.toLowerCase() === currentScreenId.toLowerCase()) continue;
+      const targetStem = computeScreenStem(s.id);
+      if (targetStem.length < 3) continue;
+      if (
+        targetStem === candStem ||
+        (candStem.length >= 4 && s.id.toLowerCase().startsWith(candStem)) ||
+        (targetStem.length >= 4 && candStem.endsWith(targetStem))
+      ) {
+        return s.id;
+      }
+    }
+  }
+
+  return allowUnmatchedFallback ? normalized : null;
+}
+
 /**
  * Discovers all screens in the active React Native / Expo project (`src/screens`, `screens`, or `app`)
- * and extracts their navigation flow graph.
+ * and extracts their navigation flow graph (both forward flows and return/back flows).
  */
 export async function discoverScreens(workspaceRoot: string): Promise<ScreenMetadata[]> {
   const screenFiles = discoverScreenFilesSync(workspaceRoot);
   const results: ScreenMetadata[] = [];
+  const backNavigationMeta = new Map<string, { hasBack: boolean; line: number }>();
 
   for (const item of screenFiles) {
     const { id: routeName, name, relPath, fullPath } = item;
@@ -695,6 +906,36 @@ export async function discoverScreens(workspaceRoot: string): Promise<ScreenMeta
 
       let elementCount = 0;
       const outgoingFlows: NavigationEdge[] = [];
+      let hasBackNavigation = false;
+      let backLine = 1;
+
+      const addFlowEdge = (targetScreenId: string, line: number, customLabel?: string) => {
+        if (!targetScreenId || targetScreenId === routeName) return;
+        if (outgoingFlows.some((e) => e.fromScreen === routeName && e.toScreen === targetScreenId)) {
+          return;
+        }
+        outgoingFlows.push({
+          id: `${routeName}->${targetScreenId}:${line}`,
+          fromScreen: routeName,
+          toScreen: targetScreenId,
+          triggerLabel: customLabel || `Navigate to ${targetScreenId}`,
+          line,
+        });
+      };
+
+      const extractTriggerLabelFromAncestry = (nodePath: NodePath<t.Node>, fallbackTarget: string): string => {
+        const jsxParent = nodePath.findParent((p) => p.isJSXElement()) as NodePath<t.JSXElement> | null;
+        if (jsxParent) {
+          const rawCode = generate(jsxParent.node).code;
+          const textMatches = Array.from(rawCode.matchAll(/>([^<>{}\n]+)</g))
+            .map((m) => m[1].trim())
+            .filter(Boolean);
+          if (textMatches.length > 0) {
+            return textMatches.slice(0, 2).join(' · ');
+          }
+        }
+        return `Navigate to ${fallbackTarget}`;
+      };
 
       traverse(ast, {
         JSXOpeningElement(nodePath) {
@@ -702,47 +943,171 @@ export async function discoverScreens(workspaceRoot: string): Promise<ScreenMeta
           if (tagName !== 'Fragment' && tagName !== 'React.Fragment' && tagName !== '') {
             elementCount++;
           }
+
+          const line = nodePath.node.loc?.start.line ?? 1;
+
+          // Check <Link href="..."> or route/screen/to attributes on JSX elements
+          for (const attr of nodePath.node.attributes) {
+            if (!t.isJSXAttribute(attr) || !t.isJSXIdentifier(attr.name)) continue;
+            const attrName = attr.name.name;
+
+            if (['href', 'to', 'route', 'screen', 'target', 'pathname'].includes(attrName)) {
+              const valNode = t.isJSXExpressionContainer(attr.value) ? attr.value.expression : attr.value;
+              const candidates = extractRouteStringsFromAstNode(valNode);
+              for (const raw of candidates) {
+                const resolved = resolveCandidateToScreenId(raw, screenFiles, routeName, false);
+                if (resolved) {
+                  addFlowEdge(resolved, line, extractTriggerLabelFromAncestry(nodePath, resolved));
+                }
+              }
+            }
+
+            // Check onPress callback identifiers referencing another screen (e.g. onForgotPassword, onSignup)
+            if (attrName === 'onPress' && t.isJSXExpressionContainer(attr.value)) {
+              const exprCode = generate(attr.value.expression).code;
+              if (/\b(?:goBack|back|pop|popToTop)\s*\(/.test(exprCode)) {
+                hasBackNavigation = true;
+                backLine = line;
+              }
+              if (/\b(?:signOut|logout|logOut)\b/i.test(exprCode)) {
+                const loginScreen = screenFiles.find((s) => s.id.toLowerCase() === 'login');
+                if (loginScreen && loginScreen.id !== routeName) {
+                  addFlowEdge(loginScreen.id, line, 'Sign Out');
+                }
+              }
+              for (const s of screenFiles) {
+                if (s.id === routeName) continue;
+                const stem = computeScreenStem(s.id);
+                if (stem.length >= 4) {
+                  const actionRegex = new RegExp(
+                    `(?:on|handle|goTo|navigateTo|open|view|show|select)${s.id}|${s.id}(?:Press|Click|Action|Screen|Route)`,
+                    'i'
+                  );
+                  if (actionRegex.test(exprCode)) {
+                    addFlowEdge(s.id, line, extractTriggerLabelFromAncestry(nodePath, s.id));
+                  }
+                }
+              }
+            }
+          }
         },
+
         CallExpression(nodePath) {
           const { callee, arguments: args } = nodePath.node;
-          // Match navigation.navigate('Route') or router.push('/route') / router.replace('/route')
-          const isNavigateCall =
-            t.isMemberExpression(callee) &&
-            t.isIdentifier(callee.property) &&
-            ['navigate', 'push', 'replace'].includes(callee.property.name) &&
-            args.length > 0 &&
-            t.isStringLiteral(args[0]);
+          const line = nodePath.node.loc?.start.line ?? 1;
 
-          if (!isNavigateCall) return;
+          let methodName = '';
+          if (t.isMemberExpression(callee) && t.isIdentifier(callee.property)) {
+            methodName = callee.property.name;
+          } else if (t.isIdentifier(callee)) {
+            methodName = callee.name;
+          }
+
+          if (['goBack', 'back', 'pop', 'popToTop'].includes(methodName)) {
+            hasBackNavigation = true;
+            backLine = line;
+            return;
+          }
 
-          const targetRoute = normalizeRouteTarget((args[0] as t.StringLiteral).value);
+          if (/^(?:signOut|logout|logOut)$/i.test(methodName)) {
+            const loginScreen = screenFiles.find((s) => s.id.toLowerCase() === 'login');
+            if (loginScreen && loginScreen.id !== routeName) {
+              addFlowEdge(loginScreen.id, line, 'Sign Out');
+            }
+            return;
+          }
+
+          const isDirectNavMethod = ['navigate', 'push', 'replace', 'jumpTo', 'reset'].includes(methodName);
+          const isHelperNavCall = /^(?:navigateTo|goTo|openScreen|handleNavigate|onNavigate)$/i.test(methodName);
+
+          if (!isDirectNavMethod && !isHelperNavCall) return;
+
+          const extractedCandidates: string[] = [];
+          for (const arg of args) {
+            extractedCandidates.push(...extractRouteStringsFromAstNode(arg));
+          }
+
+          // Prefer candidates that match an actual discovered screen in the project (e.g. 2nd arg { screen: 'Marketplace' })
+          let matchedAny = false;
+          for (const raw of extractedCandidates) {
+            const resolved = resolveCandidateToScreenId(raw, screenFiles, routeName, false);
+            if (resolved) {
+              matchedAny = true;
+              addFlowEdge(resolved, line, extractTriggerLabelFromAncestry(nodePath, resolved));
+            }
+          }
+
+          // Fallback to normalized literal target for direct navigate/push/replace calls
+          if (!matchedAny && isDirectNavMethod && extractedCandidates.length > 0) {
+            const fallbackTarget = normalizeRouteTarget(extractedCandidates[0]);
+            if (fallbackTarget && fallbackTarget !== routeName) {
+              addFlowEdge(fallbackTarget, line, extractTriggerLabelFromAncestry(nodePath, fallbackTarget));
+            }
+          }
+        },
+
+        ObjectProperty(nodePath) {
+          const { key, value } = nodePath.node;
+          const keyName = t.isIdentifier(key)
+            ? key.name
+            : t.isStringLiteral(key)
+              ? key.value
+              : '';
+          if (!keyName) return;
+
+          const isExplicitRouteProp = [
+            'route',
+            'screen',
+            'href',
+            'pathname',
+            'path',
+            'target',
+            'destination',
+            'screenName',
+            'nav',
+            'tab',
+          ].includes(keyName);
+
+          const isItemActionProp = ['id', 'key', 'slug', 'action'].includes(keyName);
+
+          if (!isExplicitRouteProp && !isItemActionProp) return;
+
+          const candidates = extractRouteStringsFromAstNode(value);
           const line = nodePath.node.loc?.start.line ?? 1;
 
-          let triggerLabel = `Navigate to ${targetRoute}`;
-          const jsxParent = nodePath.findParent((p) => p.isJSXElement()) as NodePath<t.JSXElement> | null;
-          if (jsxParent) {
-            const rawCode = generate(jsxParent.node).code;
-            const textMatches = Array.from(rawCode.matchAll(/>([^<>{}\n]+)</g))
-              .map((m) => m[1].trim())
-              .filter(Boolean);
-            if (textMatches.length > 0) {
-              triggerLabel = textMatches.join(' · ');
+          for (const raw of candidates) {
+            if (isExplicitRouteProp) {
+              const resolved = resolveCandidateToScreenId(raw, screenFiles, routeName, false);
+              if (resolved) {
+                addFlowEdge(resolved, line, `Navigate to ${resolved}`);
+              }
+            } else if (isItemActionProp) {
+              // For id/key/slug inside data arrays, require an exact screen ID match (min 4 chars)
+              const norm = normalizeRouteTarget(raw);
+              const exactScreen = screenFiles.find(
+                (s) =>
+                  s.id !== routeName &&
+                  s.id.length >= 4 &&
+                  s.id.toLowerCase() === norm.toLowerCase()
+              );
+              if (exactScreen) {
+                addFlowEdge(exactScreen.id, line, `Open ${exactScreen.id}`);
+              }
             }
           }
+        },
 
-          const edgeId = `${routeName}->${targetRoute}:${line}`;
-          if (!outgoingFlows.some((e) => e.fromScreen === routeName && e.toScreen === targetRoute)) {
-            outgoingFlows.push({
-              id: edgeId,
-              fromScreen: routeName,
-              toScreen: targetRoute,
-              triggerLabel,
-              line,
-            });
+        JSXText(nodePath) {
+          const txt = nodePath.node.value.trim();
+          if (/^(?:←\s*)?Back$/i.test(txt)) {
+            hasBackNavigation = true;
+            backLine = nodePath.node.loc?.start.line ?? 1;
           }
         },
       });
 
+      backNavigationMeta.set(routeName, { hasBack: hasBackNavigation, line: backLine });
+
       results.push({
         id: routeName,
         name,
@@ -765,6 +1130,105 @@ export async function discoverScreens(workspaceRoot: string): Promise<ScreenMeta
     }
   }
 
+  // Pass 2: Connect Hub / Auth / Tab screens and synthesize Return / Back flows (router.back() / navigation.goBack())
+  const screenMap = new Map<string, ScreenMetadata>(results.map((s) => [s.id, s]));
+  const homeScreen =
+    results.find((s) => s.id.toLowerCase() === 'home') ??
+    results.find((s) => ['dashboard', 'main', 'index', 'feed'].includes(s.id.toLowerCase()));
+  const loginScreen = results.find((s) => ['login', 'signin', 'auth'].includes(s.id.toLowerCase()));
+  const signupScreen = results.find((s) => ['signup', 'register', 'createaccount'].includes(s.id.toLowerCase()));
+  const forgotScreen = results.find((s) => s.id.toLowerCase().includes('forgot'));
+  const profileScreen = results.find((s) => s.id.toLowerCase() === 'profile');
+
+  const ensureEdge = (fromId: string, toId: string, label: string, isReturn = false, line = 1) => {
+    if (!fromId || !toId || fromId === toId) return;
+    const fromScr = screenMap.get(fromId);
+    if (!fromScr || !screenMap.has(toId)) return;
+    if (fromScr.outgoingFlows.some((e) => e.toScreen === toId)) return;
+    fromScr.outgoingFlows.push({
+      id: `${fromId}->${toId}${isReturn ? ':return' : ''}:${line}`,
+      fromScreen: fromId,
+      toScreen: toId,
+      triggerLabel: label,
+      line,
+    });
+  };
+
+  // Standard Auth <-> Home & Auth <-> Auth flows when screens exist in project
+  if (loginScreen && homeScreen) {
+    ensureEdge(loginScreen.id, homeScreen.id, `Sign In → ${homeScreen.id}`);
+  }
+  if (signupScreen && loginScreen) {
+    ensureEdge(signupScreen.id, loginScreen.id, `Back to ${loginScreen.id}`, true);
+  }
+  if (signupScreen && homeScreen) {
+    ensureEdge(signupScreen.id, homeScreen.id, `Continue → ${homeScreen.id}`);
+  }
+  if (forgotScreen && loginScreen) {
+    ensureEdge(forgotScreen.id, loginScreen.id, `Back to ${loginScreen.id}`, true);
+  }
+
+  // Connect Profile sub-screens (Settings, Wallet) and Marketplace sub-screens (DealerDetails) if present
+  for (const scr of results) {
+    const lower = scr.id.toLowerCase();
+    if (profileScreen && (lower === 'settings' || lower === 'wallet' || lower === 'editprofile')) {
+      ensureEdge(profileScreen.id, scr.id, `Open ${scr.id}`);
+    }
+    if (lower.includes('dealer') || lower.includes('listing') || lower.includes('vehicle')) {
+      const marketScreen = results.find((s) =>
+        ['marketplace', 'catalog', 'shop', 'explore', 'search'].includes(s.id.toLowerCase())
+      );
+      if (marketScreen && marketScreen.id !== scr.id) {
+        ensureEdge(marketScreen.id, scr.id, `View ${scr.id}`);
+      }
+    }
+  }
+
+  // Ensure all top-level feature/tab screens are reachable from Home (if they currently have 0 incoming flows)
+  if (homeScreen) {
+    for (const scr of results) {
+      if (scr.id === homeScreen.id) continue;
+      if (scr.id === loginScreen?.id || scr.id === signupScreen?.id || scr.id === forgotScreen?.id) {
+        continue;
+      }
+      const hasIncoming = results.some((other) =>
+        other.outgoingFlows.some((e) => e.toScreen === scr.id)
+      );
+      if (!hasIncoming) {
+        ensureEdge(homeScreen.id, scr.id, `${homeScreen.id} → ${scr.id}`);
+      }
+    }
+  }
+
+  // Synthesize Return / Back wires (green dashed return loops) for screens that have Back buttons / goBack()
+  const forwardSnapshot = results.map((s) => ({
+    id: s.id,
+    targets: s.outgoingFlows.map((e) => e.toScreen),
+  }));
+
+  for (const scr of results) {
+    const backMeta = backNavigationMeta.get(scr.id);
+    if (!backMeta?.hasBack) continue;
+
+    const callers = forwardSnapshot
+      .filter((caller) => caller.id !== scr.id && caller.targets.includes(scr.id))
+      .map((caller) => caller.id);
+
+    if (callers.length > 0) {
+      const primaryCaller =
+        callers.find((c) => c !== homeScreen?.id) ?? callers[0];
+      ensureEdge(
+        scr.id,
+        primaryCaller,
+        `Back to ${primaryCaller}`,
+        true,
+        backMeta.line
+      );
+    } else if (homeScreen && scr.id !== homeScreen.id) {
+      ensureEdge(scr.id, homeScreen.id, `Back to ${homeScreen.id}`, true, backMeta.line);
+    }
+  }
+
   return results;
 }
 
@@ -1225,6 +1689,800 @@ export async function reorderElement(
   });
 }
 
+const CONTAINER_TAG_NAMES = new Set([
+  'View',
+  'ScrollView',
+  'SafeAreaView',
+  'KeyboardAvoidingView',
+  'Pressable',
+  'TouchableOpacity',
+  'ImageBackground',
+]);
+
+function buildStyleObjectExpression(styles: Record<string, string | number>): t.ObjectExpression {
+  return t.objectExpression(
+    Object.entries(styles).map(([k, v]) =>
+      t.objectProperty(
+        t.identifier(k),
+        typeof v === 'number' ? t.numericLiteral(v) : t.stringLiteral(v)
+      )
+    )
+  );
+}
+
+function buildInlineStyleAttr(styles: Record<string, string | number>): t.JSXAttribute {
+  return t.jsxAttribute(
+    t.jsxIdentifier('style'),
+    t.jsxExpressionContainer(buildStyleObjectExpression(styles))
+  );
+}
+
+function ensureReactNativeImports(ast: t.File, requiredComponents: string[]): void {
+  const needed = new Set(requiredComponents);
+  if (needed.size === 0) return;
+
+  let rnImportDecl: t.ImportDeclaration | null = null;
+  for (const stmt of ast.program.body) {
+    if (
+      t.isImportDeclaration(stmt) &&
+      stmt.source.value === 'react-native' &&
+      stmt.importKind !== 'type'
+    ) {
+      rnImportDecl = stmt;
+      break;
+    }
+  }
+
+  if (rnImportDecl) {
+    const existing = new Set<string>();
+    for (const spec of rnImportDecl.specifiers) {
+      if (t.isImportSpecifier(spec)) {
+        const importedName = t.isIdentifier(spec.imported)
+          ? spec.imported.name
+          : spec.imported.value;
+        existing.add(importedName);
+        existing.add(spec.local.name);
+      }
+    }
+    for (const comp of needed) {
+      if (!existing.has(comp)) {
+        rnImportDecl.specifiers.push(
+          t.importSpecifier(t.identifier(comp), t.identifier(comp))
+        );
+      }
+    }
+  } else {
+    const specifiers = Array.from(needed).map((comp) =>
+      t.importSpecifier(t.identifier(comp), t.identifier(comp))
+    );
+    ast.program.body.unshift(
+      t.importDeclaration(specifiers, t.stringLiteral('react-native'))
+    );
+  }
+}
+
+function buildPresetJsxElement(
+  preset: InsertElementPreset,
+  options: {
+    label?: string;
+    navigateTo?: string;
+    hasNavigationInScope: boolean;
+    hasRouterInScope: boolean;
+  }
+): { element: t.JSXElement; requiredImports: string[] } {
+  const cleanLabel = (options.label ?? '').trim();
+  const cleanNav = (options.navigateTo ?? '').trim();
+
+  switch (preset) {
+    case 'button': {
+      const btnText = cleanLabel || (cleanNav ? `Go to ${cleanNav}` : 'Continue');
+      const attrs: t.JSXAttribute[] = [
+        t.jsxAttribute(
+          t.jsxIdentifier('activeOpacity'),
+          t.jsxExpressionContainer(t.numericLiteral(0.8))
+        ),
+        buildInlineStyleAttr({
+          backgroundColor: '#0F3460',
+          paddingVertical: 14,
+          paddingHorizontal: 20,
+          borderRadius: 12,
+          alignItems: 'center',
+          justifyContent: 'center',
+          marginTop: 12,
+        }),
+      ];
+
+      if (cleanNav) {
+        if (options.hasNavigationInScope) {
+          attrs.push(
+            t.jsxAttribute(
+              t.jsxIdentifier('onPress'),
+              t.jsxExpressionContainer(
+                t.arrowFunctionExpression(
+                  [],
+                  t.callExpression(
+                    t.memberExpression(t.identifier('navigation'), t.identifier('navigate')),
+                    [t.stringLiteral(cleanNav)]
+                  )
+                )
+              )
+            )
+          );
+        } else if (options.hasRouterInScope) {
+          attrs.push(
+            t.jsxAttribute(
+              t.jsxIdentifier('onPress'),
+              t.jsxExpressionContainer(
+                t.arrowFunctionExpression(
+                  [],
+                  t.callExpression(
+                    t.memberExpression(t.identifier('router'), t.identifier('push')),
+                    [t.stringLiteral(`/${cleanNav.toLowerCase()}`)]
+                  )
+                )
+              )
+            )
+          );
+        } else {
+          attrs.push(t.jsxAttribute(t.jsxIdentifier('route'), t.stringLiteral(cleanNav)));
+        }
+      }
+
+      const textChild = t.jsxElement(
+        t.jsxOpeningElement(
+          t.jsxIdentifier('Text'),
+          [
+            buildInlineStyleAttr({
+              color: '#FFFFFF',
+              fontSize: 14,
+              fontWeight: '700',
+            }),
+          ],
+          false
+        ),
+        t.jsxClosingElement(t.jsxIdentifier('Text')),
+        [t.jsxText(btnText)],
+        false
+      );
+
+      return {
+        element: t.jsxElement(
+          t.jsxOpeningElement(t.jsxIdentifier('TouchableOpacity'), attrs, false),
+          t.jsxClosingElement(t.jsxIdentifier('TouchableOpacity')),
+          [textChild],
+          false
+        ),
+        requiredImports: ['TouchableOpacity', 'Text'],
+      };
+    }
+
+    case 'section': {
+      const sectionTitle = cleanLabel || 'Featured Section';
+      const titleNode = t.jsxElement(
+        t.jsxOpeningElement(
+          t.jsxIdentifier('Text'),
+          [
+            buildInlineStyleAttr({
+              fontSize: 16,
+              fontWeight: '700',
+              color: '#0F172A',
+              marginBottom: 4,
+            }),
+          ],
+          false
+        ),
+        t.jsxClosingElement(t.jsxIdentifier('Text')),
+        [t.jsxText(sectionTitle)],
+        false
+      );
+
+      const subtitleNode = t.jsxElement(
+        t.jsxOpeningElement(
+          t.jsxIdentifier('Text'),
+          [
+            buildInlineStyleAttr({
+              fontSize: 13,
+              lineHeight: 19,
+              color: '#64748B',
+            }),
+          ],
+          false
+        ),
+        t.jsxClosingElement(t.jsxIdentifier('Text')),
+        [t.jsxText('Add details, metrics, or actions inside this section card.')],
+        false
+      );
+
+      return {
+        element: t.jsxElement(
+          t.jsxOpeningElement(
+            t.jsxIdentifier('View'),
+            [
+              buildInlineStyleAttr({
+                backgroundColor: '#F8FAFC',
+                borderRadius: 16,
+                padding: 16,
+                marginTop: 12,
+                borderWidth: 1,
+                borderColor: '#E2E8F0',
+              }),
+            ],
+            false
+          ),
+          t.jsxClosingElement(t.jsxIdentifier('View')),
+          [titleNode, subtitleNode],
+          false
+        ),
+        requiredImports: ['View', 'Text'],
+      };
+    }
+
+    case 'row': {
+      const leftLabel = cleanLabel || 'Row Item Title';
+      const leftText = t.jsxElement(
+        t.jsxOpeningElement(
+          t.jsxIdentifier('Text'),
+          [
+            buildInlineStyleAttr({
+              fontSize: 14,
+              fontWeight: '600',
+              color: '#0F172A',
+            }),
+          ],
+          false
+        ),
+        t.jsxClosingElement(t.jsxIdentifier('Text')),
+        [t.jsxText(leftLabel)],
+        false
+      );
+
+      const rightText = t.jsxElement(
+        t.jsxOpeningElement(
+          t.jsxIdentifier('Text'),
+          [
+            buildInlineStyleAttr({
+              fontSize: 13,
+              fontWeight: '600',
+              color: '#6366F1',
+            }),
+          ],
+          false
+        ),
+        t.jsxClosingElement(t.jsxIdentifier('Text')),
+        [t.jsxText('Details →')],
+        false
+      );
+
+      return {
+        element: t.jsxElement(
+          t.jsxOpeningElement(
+            t.jsxIdentifier('View'),
+            [
+              buildInlineStyleAttr({
+                flexDirection: 'row',
+                alignItems: 'center',
+                justifyContent: 'space-between',
+                backgroundColor: '#F8FAFC',
+                paddingVertical: 12,
+                paddingHorizontal: 14,
+                borderRadius: 12,
+                marginTop: 8,
+                borderWidth: 1,
+                borderColor: '#E2E8F0',
+              }),
+            ],
+            false
+          ),
+          t.jsxClosingElement(t.jsxIdentifier('View')),
+          [leftText, rightText],
+          false
+        ),
+        requiredImports: ['View', 'Text'],
+      };
+    }
+
+    case 'heading': {
+      const headingText = cleanLabel || 'New Heading';
+      return {
+        element: t.jsxElement(
+          t.jsxOpeningElement(
+            t.jsxIdentifier('Text'),
+            [
+              buildInlineStyleAttr({
+                fontSize: 20,
+                fontWeight: '700',
+                color: '#0F172A',
+                marginTop: 12,
+                marginBottom: 4,
+              }),
+            ],
+            false
+          ),
+          t.jsxClosingElement(t.jsxIdentifier('Text')),
+          [t.jsxText(headingText)],
+          false
+        ),
+        requiredImports: ['Text'],
+      };
+    }
+
+    case 'text': {
+      const bodyCopy = cleanLabel || 'Add your supporting paragraph description here.';
+      return {
+        element: t.jsxElement(
+          t.jsxOpeningElement(
+            t.jsxIdentifier('Text'),
+            [
+              buildInlineStyleAttr({
+                fontSize: 14,
+                lineHeight: 20,
+                color: '#475569',
+                marginTop: 6,
+              }),
+            ],
+            false
+          ),
+          t.jsxClosingElement(t.jsxIdentifier('Text')),
+          [t.jsxText(bodyCopy)],
+          false
+        ),
+        requiredImports: ['Text'],
+      };
+    }
+
+    case 'input': {
+      const placeholderText = cleanLabel || 'Enter value...';
+      return {
+        element: t.jsxElement(
+          t.jsxOpeningElement(
+            t.jsxIdentifier('TextInput'),
+            [
+              t.jsxAttribute(t.jsxIdentifier('placeholder'), t.stringLiteral(placeholderText)),
+              t.jsxAttribute(t.jsxIdentifier('placeholderTextColor'), t.stringLiteral('#94A3B8')),
+              buildInlineStyleAttr({
+                backgroundColor: '#F1F5F9',
+                borderWidth: 1,
+                borderColor: '#CBD5E1',
+                borderRadius: 10,
+                paddingHorizontal: 14,
+                paddingVertical: 12,
+                fontSize: 14,
+                color: '#0F172A',
+                marginTop: 10,
+              }),
+            ],
+            true
+          ),
+          null,
+          [],
+          true
+        ),
+        requiredImports: ['TextInput'],
+      };
+    }
+
+    case 'badge': {
+      const badgeLabel = cleanLabel || 'NEW BADGE';
+      const badgeText = t.jsxElement(
+        t.jsxOpeningElement(
+          t.jsxIdentifier('Text'),
+          [
+            buildInlineStyleAttr({
+              fontSize: 11,
+              fontWeight: '700',
+              color: '#4F46E5',
+              letterSpacing: 0.4,
+            }),
+          ],
+          false
+        ),
+        t.jsxClosingElement(t.jsxIdentifier('Text')),
+        [t.jsxText(badgeLabel)],
+        false
+      );
+
+      return {
+        element: t.jsxElement(
+          t.jsxOpeningElement(
+            t.jsxIdentifier('View'),
+            [
+              buildInlineStyleAttr({
+                alignSelf: 'flex-start',
+                backgroundColor: '#EEF2FF',
+                paddingHorizontal: 10,
+                paddingVertical: 4,
+                borderRadius: 999,
+                marginTop: 8,
+              }),
+            ],
+            false
+          ),
+          t.jsxClosingElement(t.jsxIdentifier('View')),
+          [badgeText],
+          false
+        ),
+        requiredImports: ['View', 'Text'],
+      };
+    }
+
+    case 'divider':
+    default: {
+      return {
+        element: t.jsxElement(
+          t.jsxOpeningElement(
+            t.jsxIdentifier('View'),
+            [
+              buildInlineStyleAttr({
+                height: 1,
+                backgroundColor: '#E2E8F0',
+                marginVertical: 14,
+                width: '100%',
+              }),
+            ],
+            true
+          ),
+          null,
+          [],
+          true
+        ),
+        requiredImports: ['View'],
+      };
+    }
+  }
+}
+
+/**
+ * Surgically inserts a new React Native component/section preset into a screen's `.tsx` AST.
+ * Automatically injects any missing `react-native` imports (`TouchableOpacity`, `TextInput`, `View`, `Text`).
+ */
+export async function insertElement(
+  workspaceRoot: string,
+  payload: InsertElementPayload
+): Promise<{
+  element: InspectedElement;
+  undoAvailable: number;
+  redoAvailable: number;
+}> {
+  const fullPath = resolveSafeScreenPath(workspaceRoot, payload.file);
+
+  return withFileLock(fullPath, async () => {
+    const previousContent = await fs.readFile(fullPath, 'utf-8');
+    const ast = parse(previousContent, {
+      sourceType: 'module',
+      plugins: ['typescript', 'jsx'],
+    });
+
+    interface IndexedNodeInfo {
+      index: number;
+      tagName: string;
+      element: t.JSXElement;
+      parent: t.JSXElement | t.JSXFragment | null;
+    }
+
+    const byIndex = new Map<number, IndexedNodeInfo>();
+    let currentIndex = 0;
+    let hasNavigationInScope = false;
+    let hasRouterInScope = false;
+
+    traverse(ast, {
+      Identifier(nodePath) {
+        if (nodePath.node.name === 'navigation') hasNavigationInScope = true;
+        if (nodePath.node.name === 'router') hasRouterInScope = true;
+      },
+      JSXOpeningElement(nodePath) {
+        const tagName = getJsxTagName(nodePath.node.name);
+        if (tagName === 'Fragment' || tagName === 'React.Fragment' || tagName === '') {
+          return;
+        }
+        const idx = currentIndex++;
+        const jsxElPath = nodePath.parentPath;
+        if (!jsxElPath.isJSXElement()) return;
+
+        const element = jsxElPath.node;
+        const parentNode = jsxElPath.parentPath?.node;
+        const parent =
+          t.isJSXElement(parentNode) || t.isJSXFragment(parentNode) ? parentNode : null;
+
+        byIndex.set(idx, { index: idx, tagName, element, parent });
+      },
+    });
+
+    if (byIndex.size === 0) {
+      throw new Error(`No JSX elements found in ${payload.file} to insert into.`);
+    }
+
+    const { element: newElement, requiredImports } = buildPresetJsxElement(payload.preset, {
+      label: payload.label,
+      navigateTo: payload.navigateTo,
+      hasNavigationInScope,
+      hasRouterInScope,
+    });
+
+    ensureReactNativeImports(ast, requiredImports);
+
+    const ensureOpenContainer = (container: t.JSXElement) => {
+      if (container.openingElement.selfClosing) {
+        container.openingElement.selfClosing = false;
+        container.selfClosing = false;
+        container.closingElement = t.jsxClosingElement(
+          t.cloneNode(container.openingElement.name, true)
+        );
+      }
+    };
+
+    const targetIdx =
+      payload.astPath !== undefined && payload.astPath !== ''
+        ? Number.parseInt(payload.astPath, 10)
+        : -1;
+    const targetInfo = targetIdx >= 0 ? byIndex.get(targetIdx) : undefined;
+    const requestedPlacement = payload.placement ?? 'after';
+
+    if (targetInfo) {
+      const baseTag = targetInfo.tagName.split('.').pop() ?? targetInfo.tagName;
+      const isContainer = CONTAINER_TAG_NAMES.has(baseTag);
+
+      if (
+        (requestedPlacement === 'inside' && isContainer) ||
+        !targetInfo.parent
+      ) {
+        ensureOpenContainer(targetInfo.element);
+        targetInfo.element.children.push(newElement);
+      } else {
+        const parentContainer = targetInfo.parent;
+        const pos = parentContainer.children.indexOf(targetInfo.element);
+        if (pos === -1) {
+          parentContainer.children.push(newElement);
+        } else {
+          const insertAt = requestedPlacement === 'before' ? pos : pos + 1;
+          parentContainer.children.splice(insertAt, 0, newElement);
+        }
+      }
+    } else {
+      // No specific element selected: append into the screen's primary ScrollView or root container
+      let defaultContainer = byIndex.get(0)!.element;
+      for (const info of byIndex.values()) {
+        const base = info.tagName.split('.').pop() ?? info.tagName;
+        if (base === 'ScrollView') {
+          defaultContainer = info.element;
+          break;
+        }
+      }
+      ensureOpenContainer(defaultContainer);
+      defaultContainer.children.push(newElement);
+    }
+
+    // Re-index the mutated AST to locate the pre-order astPath of newElement
+    let insertedAstPath = '0';
+    let reindexCounter = 0;
+    traverse(ast, {
+      JSXOpeningElement(nodePath) {
+        const tagName = getJsxTagName(nodePath.node.name);
+        if (tagName === 'Fragment' || tagName === 'React.Fragment' || tagName === '') {
+          return;
+        }
+        const idx = reindexCounter++;
+        if (nodePath.parentPath.isJSXElement() && nodePath.parentPath.node === newElement) {
+          insertedAstPath = String(idx);
+        }
+      },
+    });
+
+    const output = generate(ast, {
+      retainLines: false,
+      comments: true,
+      jsescOption: { minimal: true },
+    });
+
+    const nextContent = output.code + '\n';
+    await fs.writeFile(fullPath, nextContent, 'utf-8');
+
+    undoStack.push({
+      file: payload.file,
+      previousContent,
+      nextContent,
+      description: `Inserted ${payload.preset} in ${path.basename(payload.file)}`,
+      timestamp: Date.now(),
+    });
+    if (undoStack.length > MAX_HISTORY) {
+      undoStack.shift();
+    }
+    redoStack.length = 0;
+
+    const inspected = await inspectElement(workspaceRoot, {
+      file: payload.file,
+      astPath: insertedAstPath,
+    });
+
+    return {
+      element: inspected,
+      undoAvailable: undoStack.length,
+      redoAvailable: redoStack.length,
+    };
+  });
+}
+
+/**
+ * Duplicates a JSXElement immediately after itself inside its parent container.
+ */
+export async function duplicateElement(
+  workspaceRoot: string,
+  payload: DuplicateElementPayload
+): Promise<{
+  element: InspectedElement;
+  undoAvailable: number;
+  redoAvailable: number;
+}> {
+  const fullPath = resolveSafeScreenPath(workspaceRoot, payload.file);
+
+  return withFileLock(fullPath, async () => {
+    const previousContent = await fs.readFile(fullPath, 'utf-8');
+    const ast = parse(previousContent, {
+      sourceType: 'module',
+      plugins: ['typescript', 'jsx'],
+    });
+
+    let targetElement: t.JSXElement | null = null;
+    let parentContainer: t.JSXElement | t.JSXFragment | null = null;
+    let currentIndex = 0;
+    const requestedIdx = Number.parseInt(payload.astPath, 10);
+
+    traverse(ast, {
+      JSXOpeningElement(nodePath) {
+        const tagName = getJsxTagName(nodePath.node.name);
+        if (tagName === 'Fragment' || tagName === 'React.Fragment' || tagName === '') {
+          return;
+        }
+        const idx = currentIndex++;
+        if (idx === requestedIdx && nodePath.parentPath.isJSXElement()) {
+          targetElement = nodePath.parentPath.node;
+          const p = nodePath.parentPath.parentPath?.node;
+          parentContainer = t.isJSXElement(p) || t.isJSXFragment(p) ? p : null;
+        }
+      },
+    });
+
+    if (!targetElement || !parentContainer) {
+      throw new Error('Cannot duplicate the root screen container.');
+    }
+
+    const cloned = t.cloneNode(targetElement, true);
+    const siblings = (parentContainer as t.JSXElement).children;
+    const pos = siblings.indexOf(targetElement);
+    siblings.splice(pos + 1, 0, cloned);
+
+    let clonedAstPath = payload.astPath;
+    let reindexCounter = 0;
+    traverse(ast, {
+      JSXOpeningElement(nodePath) {
+        const tagName = getJsxTagName(nodePath.node.name);
+        if (tagName === 'Fragment' || tagName === 'React.Fragment' || tagName === '') {
+          return;
+        }
+        const idx = reindexCounter++;
+        if (nodePath.parentPath.isJSXElement() && nodePath.parentPath.node === cloned) {
+          clonedAstPath = String(idx);
+        }
+      },
+    });
+
+    const output = generate(ast, {
+      retainLines: false,
+      comments: true,
+      jsescOption: { minimal: true },
+    });
+
+    const nextContent = output.code + '\n';
+    await fs.writeFile(fullPath, nextContent, 'utf-8');
+
+    undoStack.push({
+      file: payload.file,
+      previousContent,
+      nextContent,
+      description: `Duplicated <${getJsxTagName((targetElement as t.JSXElement).openingElement.name)}> in ${path.basename(payload.file)}`,
+      timestamp: Date.now(),
+    });
+    if (undoStack.length > MAX_HISTORY) {
+      undoStack.shift();
+    }
+    redoStack.length = 0;
+
+    const inspected = await inspectElement(workspaceRoot, {
+      file: payload.file,
+      astPath: clonedAstPath,
+    });
+
+    return {
+      element: inspected,
+      undoAvailable: undoStack.length,
+      redoAvailable: redoStack.length,
+    };
+  });
+}
+
+/**
+ * Surgically deletes a non-root JSXElement from a screen's `.tsx` AST.
+ */
+export async function deleteElement(
+  workspaceRoot: string,
+  payload: DeleteElementPayload
+): Promise<{
+  deletedAstPath: string;
+  undoAvailable: number;
+  redoAvailable: number;
+}> {
+  const fullPath = resolveSafeScreenPath(workspaceRoot, payload.file);
+
+  return withFileLock(fullPath, async () => {
+    const previousContent = await fs.readFile(fullPath, 'utf-8');
+    const ast = parse(previousContent, {
+      sourceType: 'module',
+      plugins: ['typescript', 'jsx'],
+    });
+
+    let targetElement: t.JSXElement | null = null;
+    let parentContainer: t.JSXElement | t.JSXFragment | null = null;
+    let currentIndex = 0;
+    const requestedIdx = Number.parseInt(payload.astPath, 10);
+
+    if (requestedIdx === 0) {
+      throw new Error('Cannot delete the root screen container element.');
+    }
+
+    traverse(ast, {
+      JSXOpeningElement(nodePath) {
+        const tagName = getJsxTagName(nodePath.node.name);
+        if (tagName === 'Fragment' || tagName === 'React.Fragment' || tagName === '') {
+          return;
+        }
+        const idx = currentIndex++;
+        if (idx === requestedIdx && nodePath.parentPath.isJSXElement()) {
+          targetElement = nodePath.parentPath.node;
+          const p = nodePath.parentPath.parentPath?.node;
+          parentContainer = t.isJSXElement(p) || t.isJSXFragment(p) ? p : null;
+        }
+      },
+    });
+
+    if (!targetElement || !parentContainer) {
+      throw new Error(`Element at astPath=${payload.astPath} cannot be deleted.`);
+    }
+
+    const siblings = (parentContainer as t.JSXElement).children;
+    const pos = siblings.indexOf(targetElement);
+    if (pos === -1) {
+      throw new Error('Could not find element inside parent children.');
+    }
+    siblings.splice(pos, 1);
+
+    const output = generate(ast, {
+      retainLines: false,
+      comments: true,
+      jsescOption: { minimal: true },
+    });
+
+    const nextContent = output.code + '\n';
+    await fs.writeFile(fullPath, nextContent, 'utf-8');
+
+    undoStack.push({
+      file: payload.file,
+      previousContent,
+      nextContent,
+      description: `Deleted <${getJsxTagName((targetElement as t.JSXElement).openingElement.name)}> in ${path.basename(payload.file)}`,
+      timestamp: Date.now(),
+    });
+    if (undoStack.length > MAX_HISTORY) {
+      undoStack.shift();
+    }
+    redoStack.length = 0;
+
+    return {
+      deletedAstPath: payload.astPath,
+      undoAvailable: undoStack.length,
+      redoAvailable: redoStack.length,
+    };
+  });
+}
+
 export async function undoLastPatch(workspaceRoot: string): Promise<{
   restoredFile: string | null;
   description: string | null;