next-ai-editor 1.0.2 → 1.1.0

package/README.md

@@ -1,17 +1,31 @@
 # Next AI Editor
 
-> AI-powered React component editor for Next.js - edit your components with natural language in development mode
+> AI-powered React component editor for Next.js - chat with your UI in development mode
+
+## Overview
+
+Next AI Editor is a development tool that lets you interact with your React components using natural language. Click any component in your Next.js app and chat with an AI agent to make changes, add features, or refactor code - all while your app is running.
 
 ## Features
 
-- 🎯 **Click-to-Edit**: Click any component in your Next.js app to edit it with AI
-- 🤖 **Natural Language**: Describe changes in plain English - "make this button blue with rounded corners"
-- 🔍 **Smart Detection**: Automatically finds the exact component and element in your source code
+- 💬 **Chat Interface**: Natural conversation with AI about your components
+- 🎯 **Click-to-Select**: Click any component in your Next.js app to start editing
+- 🤖 **AI Agent**: Powered by Claude Agent SDK for intelligent code modifications
+- 🔍 **Smart Detection**: Automatically finds exact component locations in your source code
 - 📍 **Source Maps**: Works with both Server Components and Client Components using Turbopack source maps
 - 🎨 **Syntax Highlighting**: Beautiful code preview with theme-aware syntax highlighting
-- 📝 **Edit History**: Track multiple edits in a session with undo support
-- 🔄 **Live Reload**: See changes immediately in your browser
-- 🛡️ **Safe**: Only works in development mode, restricted to your project directory
+- 📜 **Task History**: Track all changes made by the AI agent
+- 🔄 **Hot Reload**: See changes immediately in your browser
+- 🛡️ **Safe**: Only works in development mode
+
+## Architecture
+
+The package is split into two parts:
+
+1. **next-ai-editor** (this package): Client-side React components and UI
+2. **next-ai-editor-service**: Background service that handles file operations, AI processing, and code analysis
+
+The client communicates with the service via HTTP/WebSocket on port 3456.
 
 ## Installation
 
@@ -25,21 +39,38 @@ yarn add next-ai-editor
 
 ## Setup
 
-### 1. Environment Variables
+### 1. Start the AI Editor Service
+
+The AI editor requires a background service to handle file operations and AI processing. The service is located in the `packages/ai-editor-service` directory of this monorepo.
 
-Add your Anthropic API key to `.env.local`:
+**Environment Variables**
+
+Create a `.env` file in the service directory:
 
 ```env
 ANTHROPIC_API_KEY=sk-ant-api03-...
+NODE_ENV=development
+NEXT_PUBLIC_AI_EDITOR_ENABLED=true
 ```
 
-### 2. Wrap Your App
+**Run the Service**
+
+```bash
+cd packages/ai-editor-service
+pnpm install
+pnpm dev
+```
+
+The service will start on port 3456 by default.
+
+### 2. Add to Your Next.js App
 
 Wrap your root layout with the `AIEditorProvider`:
 
 ```tsx
 // app/layout.tsx
 import { AIEditorProvider } from "next-ai-editor";
+import "next-ai-editor/styles";
 
 export default function RootLayout({
   children,
@@ -58,34 +89,48 @@ export default function RootLayout({
 }
 ```
 
-### 3. Add API Route
+That's it! No API routes needed - the package communicates directly with the service.
 
-Create a catch-all route handler for the AI editor API:
+## Usage
 
-```tsx
-// app/api/ai-editor/[...path]/route.ts
-import { handleAIEditorRequest } from "next-ai-editor/server";
+### Basic Chat Workflow
+
+1. **Enable AI Editor**: Press `Ctrl+Shift+E` (or `Cmd+Shift+E` on Mac)
+2. **Open Chat Panel**: Click the chat button in the bottom-right corner
+3. **Select Component**: Click the component selector tool and click any component
+4. **Chat**: Describe what you want to change, add, or refactor
+5. **Apply**: The AI agent will make the changes automatically
+
+### Example Prompts
 
-export const GET = handleAIEditorRequest;
-export const POST = handleAIEditorRequest;
+**Simple Changes**
+```
+"Change the button color to blue"
+"Add a shadow to this card"
+"Make the heading text larger"
 ```
 
-## Usage
+**Adding Features**
+```
+"Add a loading state to this button"
+"Add error handling to this form"
+"Make this component responsive"
+```
 
-1. **Enable AI Editor**: Press `Ctrl+Shift+E` (or `Cmd+Shift+E` on Mac)
-2. **Select Component**: Hover over any component to see its source location
-3. **Click to Edit**: Click the component to open the editor modal
-4. **Describe Changes**: Type what you want to change (e.g., "make the background blue")
-5. **Apply**: Press `Ctrl+Enter` (or `Cmd+Enter`) or click "Apply Changes"
-6. **Continue Editing**: Make more edits to the same component, or click "Finish & Reload"
+**Refactoring**
+```
+"Extract this form into a separate component"
+"Convert this to use TypeScript"
+"Add proper prop types to this component"
+```
 
 ## API Reference
 
-### Client
+### Client Components
 
 #### `AIEditorProvider`
 
-Wraps your app to enable the AI editor.
+Main provider component that wraps your app.
 
 ```tsx
 import { AIEditorProvider } from "next-ai-editor";
@@ -99,41 +144,91 @@ import { AIEditorProvider } from "next-ai-editor";
 - `theme?: "dark" | "light"` - UI theme (default: "dark")
 - `children: ReactNode` - Your app content
 
-### Server
+#### `ChatPanel`
+
+Standalone chat panel component for advanced use cases.
+
+```tsx
+import { ChatPanel } from "next-ai-editor";
+
+<ChatPanel
+  isExpanded={true}
+  onToggle={() => {}}
+  activeTool={null}
+  onToolChange={(tool) => {}}
+  attachedContext={null}
+  onClearContext={() => {}}
+  theme="dark"
+/>
+```
 
-#### `handleAIEditorRequest`
+#### `ControlPill`
 
-Catch-all handler for all AI editor endpoints.
+Floating control button for toggling the editor.
 
 ```tsx
-import { handleAIEditorRequest } from "next-ai-editor/server";
+import { ControlPill } from "next-ai-editor";
 
-export const GET = handleAIEditorRequest;
-export const POST = handleAIEditorRequest;
+<ControlPill
+  isEditorEnabled={true}
+  onToggle={() => {}}
+  theme="dark"
+/>
 ```
 
-#### Individual Handlers (Advanced)
+### Types
 
-For advanced use cases, you can import individual handlers:
+```tsx
+import type {
+  SourceLocation,
+  ElementContext,
+  ChatPanelProps,
+  ControlPillProps,
+  AttachedContext,
+  ToolType,
+  TaskHistoryItem,
+} from "next-ai-editor";
+```
+
+### Service Configuration
 
 ```tsx
-import {
-  handleEdit,
-  handleRead,
-  handleResolve,
-  handleUndo,
-  handleAbsolutePath,
-  handleValidateSession
-} from "next-ai-editor/server";
+import { getServiceUrl, buildServiceUrl } from "next-ai-editor";
+
+// Get the service base URL (auto-detects localhost or deployed)
+const serviceUrl = getServiceUrl(); // "http://localhost:3456"
+
+// Build full endpoint URL
+const endpoint = buildServiceUrl("api/chat"); // "http://localhost:3456/api/chat"
 ```
 
 ## How It Works
 
-1. **Component Detection**: Uses React Fiber's `_debugStack` to capture component hierarchy
-2. **Source Mapping**: Resolves compiled positions to original source using Turbopack source maps
-3. **AST Parsing**: Uses Babel to parse files and locate exact elements by tag, class, text, etc.
-4. **AI Generation**: Claude Sonnet 4.5 generates the edited code with full component context
-5. **Smart Replacement**: Replaces either the target element or full component based on the edit scope
+### 1. Component Detection
+Uses React Fiber's `_debugStack` to capture component hierarchy and location when you click an element.
+
+### 2. Source Mapping
+Resolves compiled positions to original source using Turbopack source maps. This works for both Server Components and Client Components.
+
+### 3. AI Agent
+The service runs a Claude Agent (via Claude Agent SDK) that can:
+- Read and analyze your source code
+- Make precise edits using AST parsing (Babel)
+- Understand context from previous changes
+- Handle multi-step tasks autonomously
+
+### 4. Live Updates
+Changes are written to your source files, and Next.js's hot reload automatically updates the browser.
+
+## Service Architecture
+
+The `next-ai-editor-service` package handles:
+
+- **File Operations**: Reading and writing source files safely
+- **Source Map Resolution**: Mapping compiled code positions to original source
+- **AST Parsing**: Using Babel to analyze and modify code precisely
+- **AI Processing**: Running Claude Agent SDK with access to your codebase
+- **WebSocket Streaming**: Real-time chat updates and tool execution feedback
 
 ## Requirements
 
@@ -141,62 +236,63 @@ import {
 - **React**: 18.0.0 or higher
 - **Node.js**: 18.0.0 or higher
 - **Anthropic API Key**: Required for AI functionality
+- **AI Editor Service**: Must be running on port 3456
 
 ## Development Only
 
-This package is designed for development only. All API endpoints return errors in production (`NODE_ENV=production`), and file operations are restricted to your project directory.
+This package is designed for development only. The service will refuse to run in production (`NODE_ENV=production`), and all file operations are restricted to your project directory.
 
-## Examples
+## Configuration
 
-### Simple Style Changes
+### Service URL
 
-```
-"make this button blue"
-"add rounded corners"
-"increase the font size to 18px"
-```
+By default, the package auto-detects the service URL:
+- **Local development**: `http://localhost:3456`
+- **Deployed**: `https://${hostname}:3456`
 
-### Layout Adjustments
+You can override this by setting `NEXT_PUBLIC_AI_EDITOR_SERVICE_URL` in your environment variables.
 
-```
-"center this vertically"
-"make this a flex row"
-"add 20px padding around this"
-```
+### Keyboard Shortcuts
 
-### Content Updates
+- `Ctrl+Shift+E` / `Cmd+Shift+E` - Toggle AI Editor
+- `Ctrl+Enter` / `Cmd+Enter` - Send chat message
 
-```
-"change the text to 'Hello World'"
-"add a subtitle under this heading"
-"make this bold"
-```
+## Troubleshooting
 
-### Complex Changes
+### Service Connection Issues
 
-```
-"add hover effect that changes background to blue"
-"wrap this in a card with shadow"
-"make this responsive with mobile breakpoint"
+Make sure the AI editor service is running:
+```bash
+cd packages/ai-editor-service
+pnpm dev
 ```
 
-## Troubleshooting
+Check the console for errors connecting to `http://localhost:3456`.
 
 ### Component Not Detected
 
-- Make sure you're running Next.js dev server (`npm run dev`)
-- Only React components are editable (not plain HTML)
+- Ensure you're running Next.js dev server (`npm run dev`)
+- Only React components are selectable (not plain HTML)
 - Server Components and Client Components are both supported
 
 ### Source Mapping Issues
 
 - Ensure `.next/dev/` directory exists with source maps
 - Turbopack generates `.map` files automatically in development
+- Check that your component has valid `_debugStack` in React Fiber
 
 ### API Key Issues
 
-- Verify `ANTHROPIC_API_KEY` is set in `.env.local`
-- Restart your dev server after adding environment variables
+- Verify `ANTHROPIC_API_KEY` is set in the service's `.env` file
+- Restart the service after adding environment variables
+- Check service logs for authentication errors
+
+## Examples
+
+Check out the demo apps in the monorepo:
+- `apps/patchy` - Full-featured example with the AI editor
+- `demos/blog` - Blog demo with AI editor
+- `demos/e-commerce` - E-commerce demo with AI editor
 
 ## Contributing
 
@@ -211,3 +307,4 @@ MIT © Jesse Halpern
 - [GitHub Repository](https://github.com/anon-dot-com/next-ai-editor)
 - [Issue Tracker](https://github.com/anon-dot-com/next-ai-editor/issues)
 - [Anthropic API](https://www.anthropic.com)
+- [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk)