@codedesignai/nextjs-live-edit-plugin 1.0.0

package/README.md

@@ -0,0 +1,144 @@
+# @codedesignai/nextjs-live-edit-plugin
+
+A Next.js plugin for live editing React components with AST-powered source mapping. Enables precise, character-level updates to your source files directly from the browser.
+
+This is the Next.js port of `@codedesignai/vite-live-edit-plugin` with 100% feature parity.
+
+## Features
+
+- 🎯 **AST-Powered Source Mapping** — Injects precise location data into JSX elements via a custom webpack loader
+- 📝 **Text Content Editing** — Edit text content directly from the browser
+- 🖼️ **Image Source Editing** — Update image sources with validation
+- ✅ **Full Validation** — Pre and post-update validation with rollback capability
+- 🔒 **Security** — Validates URLs and content before applying changes
+- ⚡ **Fast Refresh Integration** — Changes trigger Next.js Fast Refresh automatically
+
+## Installation
+
+```bash
+npm install @codedesignai/nextjs-live-edit-plugin
+```
+
+Or from Git:
+
+```bash
+npm install git+https://github.com/codedesignapp/ai-companion-live-edit-plugin.git#nextjs
+```
+
+## Setup
+
+### 1. Update `next.config.js`
+
+```javascript
+const { withLiveEdit } = require('@codedesignai/nextjs-live-edit-plugin');
+
+module.exports = withLiveEdit({
+  // your existing Next.js config options
+});
+```
+
+Or with TypeScript/ESM (`next.config.ts`):
+
+```typescript
+import { withLiveEdit } from '@codedesignai/nextjs-live-edit-plugin';
+
+export default withLiveEdit({
+  // your existing Next.js config options
+});
+```
+
+#### Custom Source Directories
+
+By default, the plugin processes `.jsx` and `.tsx` files in `app/`, `components/`, and `src/`. To customize:
+
+```javascript
+module.exports = withLiveEdit(
+  { /* next config */ },
+  { sourceDirs: ['app', 'components', 'src', 'features'] }
+);
+```
+
+### 2. Add the API Route
+
+#### App Router (`app/api/live-edit/route.js`)
+
+```javascript
+const { createLiveEditHandler } = require('@codedesignai/nextjs-live-edit-plugin/live-edit-handler');
+
+const { POST, OPTIONS } = createLiveEditHandler();
+
+module.exports = { POST, OPTIONS };
+```
+
+Or with TypeScript/ESM:
+
+```typescript
+import { createLiveEditHandler } from '@codedesignai/nextjs-live-edit-plugin/live-edit-handler';
+
+export const { POST, OPTIONS } = createLiveEditHandler();
+```
+
+#### Pages Router (`pages/api/live-edit.js`)
+
+```javascript
+const { createPagesApiHandler } = require('@codedesignai/nextjs-live-edit-plugin/live-edit-handler');
+
+module.exports = createPagesApiHandler();
+```
+
+## How It Works
+
+1. **Source Mapping** (build time): The webpack loader parses `.jsx`/`.tsx` files with `@babel/parser`, walks the AST, and injects `data-element-id` and `data-source-loc` attributes into JSX elements that contain text or image sources.
+
+2. **Live Editing** (runtime): The `/api/live-edit` endpoint receives update requests from the browser, validates the location data against the actual source file (including AST-level verification), applies the text/image change, and lets Next.js Fast Refresh handle the reload.
+
+### API Endpoint
+
+```
+POST /api/live-edit
+Content-Type: application/json
+
+{
+  "element": {
+    "tagName": "P",
+    "elementId": "Home-p-L5-0",
+    "sourceLoc": {
+      "file": "page.tsx",
+      "start": 123,
+      "end": 145,
+      "text": "Original text",
+      "type": "text-content"
+    }
+  },
+  "content": "New text content"
+}
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Next.js >= 13.0.0
+- React (for JSX support)
+
+## Configuration
+
+The plugin automatically:
+- Only runs in development mode
+- Only processes `.jsx` and `.tsx` files in configured source directories
+- Only adds the webpack loader for client-side builds (not server-side)
+- Injects source mapping data into JSX elements for browser interaction
+
+No additional configuration is required beyond the two setup steps above.
+
+## Comparison with Vite Plugin
+
+| Concept | Vite Plugin | Next.js Plugin |
+|---|---|---|
+| Source mapping | `sourceMapperPlugin()` (Vite transform hook) | Custom webpack loader |
+| Live edit API | `enhancedLiveEditPlugin()` (dev server middleware) | Next.js API route |
+| Hot reload | `server.reloadModule()` | Automatic Fast Refresh |
+| File filter | `src/` directory | `app/`, `components/`, `src/` (configurable) |
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,63 @@
+const path = require('path');
+
+/**
+ * Next.js config wrapper that enables the live edit plugin.
+ * 
+ * Usage in next.config.js (CommonJS):
+ * 
+ *   const { withLiveEdit } = require('@codedesignai/nextjs-live-edit-plugin');
+ *   module.exports = withLiveEdit({
+ *     // your normal Next.js config
+ *   });
+ * 
+ * Usage in next.config.ts (ESM):
+ * 
+ *   import { withLiveEdit } from '@codedesignai/nextjs-live-edit-plugin';
+ *   export default withLiveEdit({
+ *     // your normal Next.js config
+ *   });
+ * 
+ * @param {Object} nextConfig - Your Next.js configuration object
+ * @param {Object} pluginOptions - Plugin-specific options
+ * @param {string[]} pluginOptions.sourceDirs - Directories to process (default: ['app', 'components', 'src'])
+ * @returns {Object} Modified Next.js configuration
+ */
+function withLiveEdit(nextConfig = {}, pluginOptions = {}) {
+  const sourceDirs = pluginOptions.sourceDirs || ['app', 'components', 'src'];
+
+  return {
+    ...nextConfig,
+    webpack(config, context) {
+      const { dev, isServer } = context;
+
+      // Only add the source mapper in development mode and for client builds
+      // (source mapping attributes are only needed in the browser)
+      if (dev && !isServer) {
+        // Add our source mapper loader for JSX/TSX files
+        config.module.rules.push({
+          test: /\.(jsx|tsx)$/,
+          // Only process files in the configured source directories
+          include: sourceDirs.map(dir => path.resolve(process.cwd(), dir)),
+          use: [
+            {
+              loader: path.resolve(__dirname, 'source-mapper-loader.js'),
+              options: {
+                sourceDirs,
+                projectRoot: process.cwd(),
+              },
+            },
+          ],
+        });
+      }
+
+      // Call the user's webpack config if they provided one
+      if (typeof nextConfig.webpack === 'function') {
+        return nextConfig.webpack(config, context);
+      }
+
+      return config;
+    },
+  };
+}
+
+module.exports = { withLiveEdit };

package/live-edit-handler.js

@@ -0,0 +1,512 @@
+const path = require('path');
+const fs = require('fs');
+const parser = require('@babel/parser');
+const _traverse = require('@babel/traverse');
+
+// Handle both ES module and CommonJS exports
+const traverse = _traverse.default || _traverse;
+
+/**
+ * Convert character position to line number and character position within line
+ * Returns 0-based indexing (line 0 = first line, char 0 = first character in line)
+ */
+function getLineAndCharPosition(content, charPosition) {
+  const lines = content.split('\n');
+  let currentPos = 0;
+  
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const lineLength = lines[lineIndex].length + 1; // +1 for newline character
+    
+    if (charPosition < currentPos + lineLength) {
+      const charInLine = charPosition - currentPos;
+      return {
+        line: lineIndex,
+        character: charInLine
+      };
+    }
+    
+    currentPos += lineLength;
+  }
+  
+  return {
+    line: lines.length - 1,
+    character: lines[lines.length - 1].length
+  };
+}
+
+/**
+ * Validate that the location data is correct in the current source file
+ * Returns validation result with details
+ */
+function validateLocationInSource(originalContent, location) {
+  // 1. Basic bounds checking
+  if (location.start < 0 || location.end < 0) {
+    return { valid: false, error: 'Invalid location: negative positions' };
+  }
+  
+  if (location.start >= location.end) {
+    return { valid: false, error: 'Invalid location: start >= end' };
+  }
+  
+  if (location.end > originalContent.length) {
+    return { valid: false, error: `Invalid location: end position ${location.end} exceeds file length ${originalContent.length}` };
+  }
+
+  // 2. Verify the text at the location matches what we expect
+  const actualText = originalContent.substring(location.start, location.end);
+  const expectedText = location.text;
+  
+  if (actualText !== expectedText) {
+    return { 
+      valid: false, 
+      error: `Location mismatch: expected "${expectedText}" but found "${actualText}". Source file may have changed.` 
+    };
+  }
+
+  // 3. AST verification based on type
+  const locationType = location.type || 'text-content';
+  
+  try {
+    const ast = parser.parse(originalContent, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+    });
+
+    let foundMatchingNode = false;
+
+    if (locationType === 'text-content') {
+      // Validate JSXText node
+      traverse(ast, {
+        JSXText(astPath) {
+          const { node } = astPath;
+          if (node.start === location.start && node.end === location.end) {
+            foundMatchingNode = true;
+            astPath.stop();
+          }
+        }
+      });
+
+      if (!foundMatchingNode) {
+        return {
+          valid: false,
+          error: `AST structure mismatch: no JSXText node found at position ${location.start}-${location.end}. Source structure may have changed.`
+        };
+      }
+    } else if (locationType === 'image-src') {
+      // Validate img src attribute
+      traverse(ast, {
+        JSXAttribute(astPath) {
+          const { node } = astPath;
+          if (node.name.name === 'src' && node.value) {
+            let valueNode = node.value;
+            
+            // Handle string literals and expression containers
+            if (valueNode.type === 'JSXExpressionContainer') {
+              valueNode = valueNode.expression;
+            }
+            
+            if (valueNode.type === 'StringLiteral') {
+              const actualStart = valueNode.start + 1;
+              const actualEnd = valueNode.end - 1;
+              
+              if (actualStart === location.start && actualEnd === location.end) {
+                foundMatchingNode = true;
+                astPath.stop();
+              }
+            }
+          }
+        }
+      });
+
+      if (!foundMatchingNode) {
+        return {
+          valid: false,
+          error: `AST structure mismatch: no img src attribute found at position ${location.start}-${location.end}. Source structure may have changed.`
+        };
+      }
+    }
+  } catch (parseError) {
+    return {
+      valid: false,
+      error: `Source file has syntax errors: ${parseError.message}`
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate that the updated content is syntactically valid
+ */
+function validateUpdatedContent(content, filePath) {
+  try {
+    parser.parse(content, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+    });
+    return { valid: true };
+  } catch (error) {
+    return { 
+      valid: false, 
+      error: `Syntax error in updated content: ${error.message}`,
+      details: error
+    };
+  }
+}
+
+/**
+ * Validate image URL for security and correctness
+ */
+function validateImageUrl(url) {
+  // Reject potentially harmful protocols
+  const dangerousProtocols = ['javascript:', 'data:text/html', 'vbscript:'];
+  const lowerUrl = url.toLowerCase();
+  
+  for (const protocol of dangerousProtocols) {
+    if (lowerUrl.startsWith(protocol)) {
+      return { valid: false, error: `Dangerous protocol detected: ${protocol}` };
+    }
+  }
+
+  // Basic length check
+  if (url.length > 2000) {
+    return { valid: false, error: 'Image URL too long (max 2000 characters)' };
+  }
+
+  // Allow relative paths, http(s), data:image, and common protocols
+  const validPatterns = [
+    /^https?:\/\//,           // http:// or https://
+    /^\/[^\/]/,               // Absolute path (starts with single /)
+    /^\.\.?\//,               // Relative path (starts with ./ or ../)
+    /^[a-zA-Z0-9]/,           // Relative path (no protocol)
+    /^data:image\//,          // Data URI for images only
+  ];
+
+  const isValid = validPatterns.some(pattern => pattern.test(url));
+  
+  if (!isValid) {
+    return { valid: false, error: 'Invalid image URL format' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Handle text and image updates using AST-injected location data
+ * PRODUCTION-READY with full validation and rollback capability
+ * 
+ * @param {Object} data - The update data from the client
+ * @param {Object} options - Configuration options
+ * @param {string[]} options.sourceDirs - Source directories to search (default: ['app', 'components', 'src'])
+ * @param {string} options.projectRoot - Project root directory (default: process.cwd())
+ */
+async function handleEnhancedTextUpdate(data, options = {}) {
+  const { element, content, imageUrl, updateType } = data;
+  const { sourceDirs = ['app', 'components', 'src'], projectRoot = process.cwd() } = options;
+  
+  // Normalize content field - handle both 'content' and 'imageUrl'
+  const actualContent = content || imageUrl;
+  
+  // === INPUT VALIDATION ===
+  if (!element || !actualContent) {
+    console.error('❌ Live edit failed: Missing element or content data');
+    console.error('   Received data:', { hasElement: !!element, hasContent: !!content, hasImageUrl: !!imageUrl, updateType });
+    return { success: false, error: 'Missing element or content data' };
+  }
+
+  if (typeof actualContent !== 'string' || actualContent.length === 0) {
+    console.error('❌ Live edit failed: Invalid content type or empty');
+    return { success: false, error: 'Invalid content: must be a non-empty string' };
+  }
+
+  // Extract location data from element
+  const sourceLocAttr = element.sourceLoc || element['data-source-loc'];
+  const elementId = element.elementId || element['data-element-id'];
+  
+  console.log(`📥 Live edit request for element: ${elementId}, tagName: ${element.tagName}`);
+  
+  if (!sourceLocAttr) {
+    console.error(`❌ Live edit failed: No source location data for element ${elementId}`);
+    console.error('   Element data:', JSON.stringify(element, null, 2));
+    return { success: false, error: 'No source location data available - element may not have been compiled with source mapping' };
+  }
+
+  let originalContent = null; // Backup for rollback
+  let fullFilePath = null;
+
+  try {
+    // Parse the location data (it's a JSON string)
+    const location = typeof sourceLocAttr === 'string' 
+      ? JSON.parse(sourceLocAttr.replace(/&apos;/g, "'")) 
+      : sourceLocAttr;
+    
+    // Validate location object structure
+    if (!location || !location.file || typeof location.start !== 'number' || typeof location.end !== 'number') {
+      return { success: false, error: 'Invalid location data structure' };
+    }
+
+    const locationType = location.type || 'text-content';
+    
+    console.log(`🎯 Updating ${location.file} [${locationType}] at characters ${location.start}-${location.end}`);
+    
+    // Try to find the file in any of the source directories
+    fullFilePath = null;
+    for (const dir of sourceDirs) {
+      const candidate = path.resolve(projectRoot, dir, location.file);
+      if (fs.existsSync(candidate)) {
+        fullFilePath = candidate;
+        break;
+      }
+    }
+
+    // Also try resolving directly from project root
+    if (!fullFilePath) {
+      const directPath = path.resolve(projectRoot, location.file);
+      if (fs.existsSync(directPath)) {
+        fullFilePath = directPath;
+      }
+    }
+
+    if (!fullFilePath) {
+      return { success: false, error: `Source file not found: ${location.file}` };
+    }
+
+    // === READ & BACKUP ORIGINAL ===
+    originalContent = fs.readFileSync(fullFilePath, 'utf-8');
+    
+    // === PRE-FLIGHT VALIDATION ===
+    const preValidation = validateLocationInSource(originalContent, location);
+    if (!preValidation.valid) {
+      console.error(`❌ Pre-flight validation failed: ${preValidation.error}`);
+      return { success: false, error: `Validation failed: ${preValidation.error}` };
+    }
+    
+    console.log('✓ Pre-flight validation passed');
+    
+    // === EXTRACT NEW CONTENT ===
+    let newContent;
+    
+    if (locationType === 'image-src') {
+      // For images, extract the src value
+      if (actualContent.startsWith('<img')) {
+        const srcMatch = actualContent.match(/src=["']([^"']+)["']/);
+        if (srcMatch) {
+          newContent = srcMatch[1];
+        } else {
+          return { success: false, error: 'Could not extract src from img tag' };
+        }
+      } else {
+        newContent = actualContent;
+      }
+
+      // Validate image URL
+      const urlValidation = validateImageUrl(newContent);
+      if (!urlValidation.valid) {
+        return { success: false, error: `Image URL validation failed: ${urlValidation.error}` };
+      }
+    } else {
+      // For text content, extract text from HTML if needed
+      newContent = actualContent;
+      if (actualContent.startsWith('<') && actualContent.endsWith('>')) {
+        newContent = actualContent.replace(/<[^>]*>/g, '');
+      }
+
+      // Sanitize text content
+      if (newContent.length > 10000) {
+        return { success: false, error: 'Content too large (max 10000 characters)' };
+      }
+    }
+
+    // === APPLY UPDATE ===
+    const updatedContent = 
+      originalContent.substring(0, location.start) + 
+      newContent + 
+      originalContent.substring(location.end);
+    
+    // === POST-UPDATE VALIDATION ===
+    const postValidation = validateUpdatedContent(updatedContent, fullFilePath);
+    if (!postValidation.valid) {
+      console.error(`❌ Post-update validation failed: ${postValidation.error}`);
+      return { 
+        success: false, 
+        error: `Updated content has syntax errors: ${postValidation.error}. Changes not applied.` 
+      };
+    }
+    
+    console.log('✓ Post-update validation passed');
+    
+    // === WRITE CHANGES (only after all validation passes) ===
+    fs.writeFileSync(fullFilePath, updatedContent, 'utf-8');
+
+    // Next.js Fast Refresh will automatically detect the file change
+    // No need to manually trigger HMR like in Vite
+
+    const updateLabel = locationType === 'image-src' ? '🖼️  Image' : '📝 Text';
+    console.log(`✅ ${updateLabel} updated in ${location.file}`);
+    console.log(`   "${location.text}" → "${newContent}"`);
+    
+    return { 
+      success: true, 
+      message: `Updated ${path.basename(fullFilePath)}`,
+      file: fullFilePath,
+      type: locationType
+    };
+
+  } catch (error) {
+    console.error('❌ Error updating source file:', error);
+    
+    // === ROLLBACK ON ERROR ===
+    if (originalContent && fullFilePath) {
+      try {
+        fs.writeFileSync(fullFilePath, originalContent, 'utf-8');
+        console.log('↩️  Rolled back to original content');
+      } catch (rollbackError) {
+        console.error('❌ Failed to rollback:', rollbackError);
+      }
+    }
+    
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * CORS headers for the live-edit API
+ */
+const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type',
+};
+
+/**
+ * Create a Next.js App Router API route handler for live editing.
+ * 
+ * Usage in app/api/live-edit/route.js:
+ * 
+ *   const { createLiveEditHandler } = require('@codedesignai/nextjs-live-edit-plugin/live-edit-handler');
+ *   const { POST, OPTIONS } = createLiveEditHandler();
+ *   module.exports = { POST, OPTIONS };
+ * 
+ * Or for ES modules (app/api/live-edit/route.ts):
+ * 
+ *   import { createLiveEditHandler } from '@codedesignai/nextjs-live-edit-plugin/live-edit-handler';
+ *   export const { POST, OPTIONS } = createLiveEditHandler();
+ * 
+ * @param {Object} options
+ * @param {string[]} options.sourceDirs - Directories to search for source files
+ * @param {string} options.projectRoot - Project root directory
+ */
+function createLiveEditHandler(options = {}) {
+  const handlerOptions = {
+    sourceDirs: options.sourceDirs || ['app', 'components', 'src'],
+    projectRoot: options.projectRoot || process.cwd(),
+  };
+
+  async function POST(request) {
+    // Only allow in development
+    if (process.env.NODE_ENV === 'production') {
+      return new Response(
+        JSON.stringify({ success: false, error: 'Live editing is only available in development mode' }),
+        { status: 403, headers: { 'Content-Type': 'application/json', ...corsHeaders } }
+      );
+    }
+
+    try {
+      const data = await request.json();
+      console.log('🔄 Received enhanced live edit request:', JSON.stringify(data, null, 2));
+
+      const result = await handleEnhancedTextUpdate(data, handlerOptions);
+      
+      if (result.success) {
+        return new Response(
+          JSON.stringify({ success: true, message: result.message }),
+          { status: 200, headers: { 'Content-Type': 'application/json', ...corsHeaders } }
+        );
+      } else {
+        return new Response(
+          JSON.stringify({ success: false, error: result.error }),
+          { status: 400, headers: { 'Content-Type': 'application/json', ...corsHeaders } }
+        );
+      }
+    } catch (error) {
+      console.error('❌ Error processing enhanced live edit request:', error);
+      return new Response(
+        JSON.stringify({ success: false, error: error.message }),
+        { status: 500, headers: { 'Content-Type': 'application/json', ...corsHeaders } }
+      );
+    }
+  }
+
+  async function OPTIONS() {
+    return new Response(null, {
+      status: 200,
+      headers: corsHeaders,
+    });
+  }
+
+  return { POST, OPTIONS };
+}
+
+/**
+ * Create a Pages Router API handler (for pages/api/live-edit.js)
+ * 
+ * Usage:
+ *   const { createPagesApiHandler } = require('@codedesignai/nextjs-live-edit-plugin/live-edit-handler');
+ *   module.exports = createPagesApiHandler();
+ */
+function createPagesApiHandler(options = {}) {
+  const handlerOptions = {
+    sourceDirs: options.sourceDirs || ['app', 'components', 'src'],
+    projectRoot: options.projectRoot || process.cwd(),
+  };
+
+  return async function handler(req, res) {
+    // Set CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    // Handle OPTIONS preflight
+    if (req.method === 'OPTIONS') {
+      res.status(200).end();
+      return;
+    }
+
+    // Only allow POST
+    if (req.method !== 'POST') {
+      res.status(405).json({ success: false, error: 'Method Not Allowed' });
+      return;
+    }
+
+    // Only allow in development
+    if (process.env.NODE_ENV === 'production') {
+      res.status(403).json({ success: false, error: 'Live editing is only available in development mode' });
+      return;
+    }
+
+    try {
+      const data = req.body;
+      console.log('🔄 Received enhanced live edit request:', JSON.stringify(data, null, 2));
+
+      const result = await handleEnhancedTextUpdate(data, handlerOptions);
+      
+      if (result.success) {
+        res.status(200).json({ success: true, message: result.message });
+      } else {
+        res.status(400).json({ success: false, error: result.error });
+      }
+    } catch (error) {
+      console.error('❌ Error processing enhanced live edit request:', error);
+      res.status(500).json({ success: false, error: error.message });
+    }
+  };
+}
+
+module.exports = {
+  handleEnhancedTextUpdate,
+  validateLocationInSource,
+  validateUpdatedContent,
+  validateImageUrl,
+  createLiveEditHandler,
+  createPagesApiHandler,
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@codedesignai/nextjs-live-edit-plugin",
+  "version": "1.0.0",
+  "description": "Next.js plugin for live editing React components with AST-powered source mapping",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./live-edit-handler": "./live-edit-handler.js",
+    "./source-mapper-loader": "./source-mapper-loader.js"
+  },
+  "files": [
+    "index.js",
+    "source-mapper-loader.js",
+    "live-edit-handler.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "nextjs",
+    "next",
+    "plugin",
+    "live-edit",
+    "react",
+    "ast",
+    "source-mapping",
+    "code-editing",
+    "webpack-loader"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codedesignapp/ai-companion-live-edit-plugin.git",
+    "directory": "nextjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.28.4",
+    "@babel/traverse": "^7.28.4"
+  }
+}

package/source-mapper-loader.js

@@ -0,0 +1,234 @@
+const path = require('path');
+const parser = require('@babel/parser');
+const _traverse = require('@babel/traverse');
+
+// Handle both ES module and CommonJS exports
+const traverse = _traverse.default || _traverse;
+
+/**
+ * Convert character position to line number and character position within line
+ * Returns 0-based indexing (line 0 = first line, char 0 = first character in line)
+ */
+function getLineAndCharPosition(content, charPosition) {
+  const lines = content.split('\n');
+  let currentPos = 0;
+  
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const lineLength = lines[lineIndex].length + 1; // +1 for newline character
+    
+    if (charPosition < currentPos + lineLength) {
+      const charInLine = charPosition - currentPos;
+      return {
+        line: lineIndex,        // 0-based line number
+        character: charInLine   // 0-based character position within line
+      };
+    }
+    
+    currentPos += lineLength;
+  }
+  
+  // Fallback - shouldn't happen with valid positions
+  return {
+    line: lines.length - 1,
+    character: lines[lines.length - 1].length
+  };
+}
+
+/**
+ * Generate a unique element ID
+ */
+function generateElementId(filePath, lineNumber, elementName, index = 0) {
+  const fileName = path.basename(filePath, path.extname(filePath));
+  const cleanFileName = fileName.replace(/[^a-zA-Z0-9]/g, '');
+  return `${cleanFileName}-${elementName}-L${lineNumber}-${index}`;
+}
+
+/**
+ * Custom webpack loader that injects AST-powered source mapping data
+ * into JSX elements. This is the Next.js equivalent of the Vite
+ * sourceMapperPlugin() transform hook.
+ *
+ * Injects `data-element-id` and `data-source-loc` attributes into:
+ * - Text content elements (JSXText nodes)
+ * - Image elements (<img> and <Image>) with src attributes
+ */
+module.exports = function sourceMapperLoader(source) {
+  // Only run in development mode
+  if (process.env.NODE_ENV === 'production') {
+    return source;
+  }
+
+  const resourcePath = this.resourcePath;
+  const options = this.getOptions() || {};
+  
+  // Configurable source directories (default: app, components, src)
+  const sourceDirs = options.sourceDirs || ['app', 'components', 'src'];
+  const projectRoot = options.projectRoot || process.cwd();
+
+  // Only process JSX/TSX files
+  if (!/\.(jsx|tsx)$/.test(resourcePath)) {
+    return source;
+  }
+
+  // Check if the file is in one of the configured source directories
+  const relativePath = path.relative(projectRoot, resourcePath);
+  const isInSourceDir = sourceDirs.some(dir => relativePath.startsWith(dir + path.sep) || relativePath.startsWith(dir + '/'));
+  
+  if (!isInSourceDir) {
+    return source;
+  }
+
+  // Use the first matching source dir to compute the relative path for element IDs
+  const matchingDir = sourceDirs.find(dir => relativePath.startsWith(dir + path.sep) || relativePath.startsWith(dir + '/'));
+  const relativeToSrcDir = matchingDir ? path.relative(matchingDir, relativePath) : relativePath;
+
+  const modifications = [];
+
+  try {
+    const ast = parser.parse(source, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+    });
+
+    traverse(ast, {
+      JSXElement(astPath) {
+        const { node } = astPath;
+        const openingElement = node.openingElement;
+        
+        // Handle JSXIdentifier and JSXMemberExpression
+        let tagName;
+        if (openingElement.name.type === 'JSXIdentifier') {
+          tagName = openingElement.name.name;
+        } else if (openingElement.name.type === 'JSXMemberExpression') {
+          // e.g., motion.div → use the property name
+          tagName = openingElement.name.property.name;
+        } else {
+          return; // Skip unsupported tag name types
+        }
+        
+        const { line } = openingElement.loc.start;
+
+        // === HANDLE IMAGE ELEMENTS (both <img> and <Image>) ===
+        const isImageElement = tagName === 'img' || tagName === 'Image';
+        
+        if (isImageElement) {
+          // Find the src attribute
+          const srcAttribute = openingElement.attributes.find(attr => 
+            attr.type === 'JSXAttribute' && attr.name && attr.name.name === 'src'
+          );
+
+          if (srcAttribute && srcAttribute.value) {
+            let srcValue, srcStart, srcEnd;
+
+            // Handle different src value types
+            if (srcAttribute.value.type === 'StringLiteral') {
+              // src="image.jpg"
+              srcValue = srcAttribute.value.value;
+              srcStart = srcAttribute.value.start + 1; // Skip opening quote
+              srcEnd = srcAttribute.value.end - 1;     // Skip closing quote
+            } else if (srcAttribute.value.type === 'JSXExpressionContainer') {
+              // src={variable} or src={`template`}
+              const expression = srcAttribute.value.expression;
+              if (expression.type === 'StringLiteral') {
+                srcValue = expression.value;
+                srcStart = expression.start + 1;
+                srcEnd = expression.end - 1;
+              } else if (expression.type === 'TemplateLiteral') {
+                // For template literals, we'll skip for now as they're dynamic
+                return;
+              } else {
+                // Skip dynamic expressions (variables, etc.)
+                return;
+              }
+            }
+
+            if (srcValue !== undefined) {
+              // Get line-based positions for chat AI mode
+              const startLinePos = getLineAndCharPosition(source, srcStart);
+              const endLinePos = getLineAndCharPosition(source, srcEnd);
+              
+              const locationData = {
+                file: relativeToSrcDir,
+                start: srcStart,
+                end: srcEnd,
+                text: srcValue,
+                type: 'image-src', // Mark this as an image source
+                // Line-based information for chat AI mode (0-based indexing)
+                line: startLinePos.line,
+                character: startLinePos.character,
+                endLine: endLinePos.line,
+                endCharacter: endLinePos.character
+              };
+
+              const elementId = generateElementId(relativeToSrcDir, line, tagName, 0);
+              
+              const insertPosition = openingElement.selfClosing 
+                ? openingElement.end - 2  // Before '/>'
+                : openingElement.end - 1; // Before '>'
+
+              const attributes = ` data-element-id="${elementId}" data-source-loc='${JSON.stringify(locationData).replace(/'/g, "&apos;")}'`;
+
+              modifications.push({ position: insertPosition, text: attributes });
+            }
+          }
+          return; // Done processing this image element
+        }
+
+        // === HANDLE TEXT CONTENT ELEMENTS ===
+        // Find text content children
+        const textChildren = node.children.filter(child => 
+          child.type === 'JSXText' && child.value.trim().length > 0
+        );
+
+        // Skip if no text content
+        if (textChildren.length === 0) return;
+
+        // Only inject once per element, using the FIRST text child
+        const firstTextNode = textChildren[0];
+        
+        // Get line-based positions for chat AI mode
+        const startLinePos = getLineAndCharPosition(source, firstTextNode.start);
+        const endLinePos = getLineAndCharPosition(source, firstTextNode.end);
+        
+        const locationData = {
+          file: relativeToSrcDir,
+          start: firstTextNode.start,
+          end: firstTextNode.end,
+          text: firstTextNode.value.trim(),
+          type: 'text-content', // Mark this as text content
+          // Line-based information for chat AI mode (0-based indexing)
+          line: startLinePos.line,
+          character: startLinePos.character,
+          endLine: endLinePos.line,
+          endCharacter: endLinePos.character
+        };
+
+        const elementId = generateElementId(relativeToSrcDir, line, tagName, 0);
+        
+        // Inject attributes into the opening tag
+        const insertPosition = openingElement.selfClosing 
+          ? openingElement.end - 2  // Before '/>'
+          : openingElement.end - 1; // Before '>'
+
+        const attributes = ` data-element-id="${elementId}" data-source-loc='${JSON.stringify(locationData).replace(/'/g, "&apos;")}'`;
+
+        modifications.push({ position: insertPosition, text: attributes });
+      },
+    });
+
+    // Apply modifications from end to start to preserve positions
+    if (modifications.length > 0) {
+      let transformedCode = source.split('');
+      modifications.sort((a, b) => b.position - a.position).forEach(mod => {
+        transformedCode.splice(mod.position, 0, mod.text);
+      });
+      return transformedCode.join('');
+    }
+
+  } catch (e) {
+    // Don't break the build on parse errors - just skip transformation
+    console.error(`❌ [nextjs-live-edit] Failed to parse ${relativePath}:`, e.message);
+  }
+
+  return source;
+};