@upstart.gg/vite-plugins 0.0.37

package/src/vite-plugin-upstart-editor/PLAN.md

@@ -0,0 +1,1391 @@
+# Prompt: Create Upstart Visual Editor Plugin
+
+## Context
+
+I have a Vite plugin (`vite-plugin-upstart-attrs.ts`) that adds `data-*` attributes to JSX elements during build time. This plugin:
+- Adds `data-upstart-hash` (content-based hash) to all JSX elements
+- Adds `data-upstart-editable-text="true"` to text leaf elements (elements containing only static text)
+- Adds `data-upstart-file`, `data-upstart-component`, and various prop tracking attributes to components
+- Tracks the source location of text nodes in a metadata registry
+
+Now I need to create a **companion plugin** that injects a visual editor into the app at runtime, allowing users to edit text content directly in the browser.
+
+## Important Architecture Note: Iframe Communication
+
+**The user's app runs inside an iframe**, embedded in a parent editor application. This means:
+
+- ❌ **NO API calls** to `/api/update-text` or any HTTP endpoints
+- ✅ **Use `window.parent.postMessage()`** to communicate with the parent editor
+- The parent editor (outside the iframe) is responsible for:
+  - Receiving edit messages
+  - Updating the source files
+  - Running `vite build` to rebuild the app
+  - Reloading the iframe with the new build
+
+**Important**: The app is always served as a **production build** (result of `vite build` with the Upstart plugins enabled), NOT from a dev server. There is no HMR - the parent editor must rebuild and reload the iframe after each change.
+
+### Two Editing Modes
+
+The iframe has **two modes** controlled by the parent window:
+
+1. **Preview Mode** (default):
+   - Users can interact with the page normally (click links, buttons, etc.)
+   - No editing handlers are active
+   - No visual indicators (hover overlays, edit affordances)
+   - Behaves like a normal website
+
+2. **Edit Mode**:
+   - Text editing enabled (double-click to edit with TipTap inside iframe)
+   - Click elements to trigger className editing (UI shown in parent window)
+   - Hover overlays show editable elements
+   - Visual affordances indicate editable content
+
+The parent window switches between modes by sending a postMessage to the iframe:
+```typescript
+// Parent sends mode change
+iframe.contentWindow.postMessage({
+  source: 'upstart-editor-parent',
+  type: 'set-mode',
+  mode: 'edit' // or 'preview'
+}, '*');
+```
+
+### Two Types of Editing
+
+1. **Text Editing** (inside iframe):
+   - Uses TipTap editor
+   - Double-click text to activate inline editor
+   - Editing happens directly in the iframe
+   - Sends `text-save` message to parent when done
+
+2. **ClassName Editing** (outside iframe):
+   - Single-click an element (in edit mode)
+   - Sends `element-clicked` message to parent with element info
+   - Parent window shows UI for editing Tailwind classes
+   - Parent updates source file, rebuilds, reloads iframe
+
+**Communication Flow:**
+```
+┌─────────────────────────────────────────────────┐
+│  Parent Editor Application                      │
+│  - Receives postMessage from iframe             │
+│  - Shows className editor UI (Radix/Shadcn)     │
+│  - Updates source files                         │
+│  - Runs vite build                              │
+│  - Reloads iframe                               │
+│  - Sends mode changes to iframe                 │
+│  ┌───────────────────────────────────────────┐  │
+│  │  <iframe>                                 │  │
+│  │  Compiled App (vite build)                │  │
+│  │  - Listens for mode changes               │  │
+│  │  - Text editing (TipTap inside)           │  │
+│  │  - Click detection (triggers parent UI)   │  │
+│  │  - Sends postMessage to parent            │  │
+│  └───────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────┘
+```
+
+## Project Structure
+
+The new plugin will live in its own directory alongside existing plugins:
+
+```
+vite-plugins/
+  src/
+    vite-plugin-upstart-attrs.ts          # Existing (attached)
+    vite-plugin-upstart-routes.ts         # Existing
+    vite-plugin-upstart-theme.ts          # Existing
+    upstart-editor-api.ts                 # Existing API helpers
+    vite-plugin-upstart-editor/           # NEW - To be created
+      plugin.ts                           # Vite plugin (build-time)
+      runtime/
+        index.ts                          # Main entry point
+        text-editor.ts                    # TipTap text editing logic
+        hover-overlay.ts                  # Visual hover indicators
+        types.ts                          # Shared TypeScript types
+    tests/
+      # ... existing tests
+```
+
+## Architecture Overview
+
+The new plugin is split into two parts:
+
+1. **Build-time plugin** (`plugin.ts`): Injects the editor initialization code during Vite build
+2. **Runtime code** (`runtime/` directory): The actual editor that runs in the browser
+
+The key insight is that the plugin references **actual TypeScript files** (not template strings) so we get:
+- Full IDE support and type checking
+- Vite's HMR and module resolution
+- Easy testing and maintenance
+- Proper code organization
+
+## Part 1: Build-Time Plugin (`vite-plugin-upstart-editor/plugin.ts`)
+
+### Purpose
+Automatically inject the editor initialization code into the user's app during development.
+
+### Requirements
+
+**Plugin Setup**:
+- Use `unplugin` (same as the attached `vite-plugin-upstart-attrs.ts`)
+- Export using `createUnplugin` pattern
+- Plugin name: `"upstart-editor"`
+- Enforce: `"pre"` (run before other transforms)
+
+**Options Interface**:
+```typescript
+interface UpstartEditorOptions {
+  enabled?: boolean;              // Enable/disable editor (default: false)
+  autoInject?: boolean;           // Auto-inject initialization (default: true)
+}
+```
+
+**Note**: This plugin is designed to be used with `vite build` (production builds), not `vite dev`. The `enabled` option should be set to `true` when building the app for use in the editor iframe.
+
+**Core Functionality**:
+
+1. **If not enabled**: Return a minimal plugin with name `"upstart-editor-disabled"`
+
+2. **Get runtime path**:
+   - Use `import.meta.url` and `fileURLToPath` to get current directory
+   - Resolve absolute path to `runtime/index.ts`
+   - Example: `path.resolve(__dirname, './runtime/index.ts')`
+
+3. **Inject runtime code using `transform` hook**:
+   ```typescript
+   transform(code, id) {
+     // Only inject in main entry file (main.tsx, main.ts, or index.tsx)
+     if (!id.includes('main.') && !id.includes('index.')) {
+       return null;
+     }
+
+     // Check if user has manually imported editor
+     if (code.includes('initUpstartEditor')) {
+       return null; // User is handling initialization manually
+     }
+
+     // Inject import and initialization at the top of the file
+     const injection = `
+   import { initUpstartEditor } from '${runtimePath}';
+
+   // Auto-initialize editor when DOM is ready
+   if (typeof window !== 'undefined') {
+     if (document.readyState === 'loading') {
+       document.addEventListener('DOMContentLoaded', () => initUpstartEditor());
+     } else {
+       initUpstartEditor();
+     }
+   }
+
+   ${code}
+     `;
+
+     return {
+       code: injection,
+       map: null,
+     };
+   }
+   ```
+
+**Important Implementation Details**:
+- Use absolute path resolution so Vite can find the runtime files
+- The runtime files will be processed normally by Vite (bundling, HMR, etc.)
+- Do NOT inject code as template strings - reference actual `.ts` files
+- Only inject once (check for existing imports)
+
+**Export Pattern**:
+```typescript
+import { createUnplugin } from "unplugin";
+
+export const upstartEditor = createUnplugin<UpstartEditorOptions>((options = {}) => {
+  // Plugin implementation
+});
+
+export default upstartEditor.vite;
+```
+
+---
+
+## Part 2: Runtime Entry Point (`vite-plugin-upstart-editor/runtime/index.ts`)
+
+### Purpose
+Main entry point that initializes all editor features and manages edit/preview modes.
+
+### Requirements
+
+**State management**:
+```typescript
+let currentMode: 'preview' | 'edit' = 'preview'; // Default to preview mode
+
+export function getCurrentMode() {
+  return currentMode;
+}
+
+export function setMode(mode: 'preview' | 'edit') {
+  currentMode = mode;
+
+  if (mode === 'edit') {
+    enableEditMode();
+  } else {
+    disableEditMode();
+  }
+}
+```
+
+**Listen for mode changes from parent**:
+```typescript
+window.addEventListener('message', (event) => {
+  const message = event.data;
+
+  // Only accept messages from parent
+  if (message.source !== 'upstart-editor-parent') return;
+
+  if (message.type === 'set-mode') {
+    setMode(message.mode);
+  }
+});
+```
+
+**Export main initialization function**:
+```typescript
+export function initUpstartEditor() {
+  console.log('[Upstart Editor] Initializing...');
+
+  // Start in preview mode (no handlers active)
+  currentMode = 'preview';
+
+  // Listen for mode changes from parent
+  window.addEventListener('message', handleParentMessage);
+
+  // Initialize features (but they only activate in edit mode)
+  initTextEditor();
+  initClickHandler();
+  initHoverOverlay();
+
+  // Notify parent that editor is ready
+  sendToParent({ type: 'editor-ready' });
+}
+
+function handleParentMessage(event: MessageEvent) {
+  const message = event.data;
+
+  if (message.source !== 'upstart-editor-parent') return;
+
+  if (message.type === 'set-mode') {
+    setMode(message.mode);
+  }
+}
+
+function enableEditMode() {
+  console.log('[Upstart Editor] Edit mode enabled');
+  // Event handlers will check getCurrentMode() before activating
+}
+
+function disableEditMode() {
+  console.log('[Upstart Editor] Preview mode enabled');
+  // Clean up any active editors
+  destroyAllActiveEditors();
+  hideOverlays();
+}
+```
+
+**Export individual functions** for advanced users:
+```typescript
+export { initTextEditor } from './text-editor';
+export { initClickHandler } from './click-handler';
+export { initHoverOverlay } from './hover-overlay';
+export { sendToParent } from './utils';
+export type { EditorMessage, UpstartEditorMessage } from './types';
+```
+
+**Graceful error handling**:
+- Wrap initialization in try-catch
+- Log errors clearly with `[Upstart Editor]` prefix
+- Don't crash if elements aren't found
+
+---
+
+## Part 3: Text Editor (`vite-plugin-upstart-editor/runtime/text-editor.ts`)
+
+### Purpose
+Enable inline text editing using TipTap editor library.
+
+### Core Functionality
+
+**Find editable elements**:
+```typescript
+const editables = document.querySelectorAll('[data-upstart-editable-text="true"]');
+```
+
+**For each editable element**:
+
+1. **Add visual affordances** (only visible in edit mode):
+   - Hover: `outline: 1px dashed #3b82f6`
+   - Cursor: `cursor: text`
+   - Transition: `transition: outline 0.15s ease`
+
+2. **Enable editing on double-click** (only in edit mode):
+   ```typescript
+   element.addEventListener('dblclick', (e) => {
+     // IMPORTANT: Only activate in edit mode
+     if (getCurrentMode() !== 'edit') return;
+
+     e.preventDefault();
+     e.stopPropagation();
+
+     const hash = element.dataset.upstartHash;
+     if (!hash) return;
+
+     // Prevent duplicate editors
+     if (activeEditors.has(hash)) return;
+
+     activateEditor(element, hash);
+   });
+   ```
+
+3. **Show hover effects** (only in edit mode):
+   ```typescript
+   element.addEventListener('mouseenter', () => {
+     if (getCurrentMode() !== 'edit') return;
+     element.style.outline = '1px dashed #3b82f6';
+   });
+
+   element.addEventListener('mouseleave', () => {
+     if (!activeEditors.has(hash)) {
+       element.style.outline = '';
+     }
+   });
+   ```
+
+3. **Determine editor type**:
+   ```typescript
+   function shouldUseRichText(element: HTMLElement): boolean {
+     const tagName = element.tagName.toLowerCase();
+     const plainTextTags = ['button', 'a', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'label'];
+     return !plainTextTags.includes(tagName);
+   }
+   ```
+
+### TipTap Configuration
+
+**Install these packages** (add to package.json dependencies):
+```json
+{
+  "@tiptap/core": "^2.8.0",
+  "@tiptap/starter-kit": "^2.8.0",
+  "@tiptap/extension-placeholder": "^2.8.0",
+  "@tiptap/extension-bubble-menu": "^2.8.0"
+}
+```
+
+**Import statements**:
+```typescript
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import Placeholder from '@tiptap/extension-placeholder';
+import { BubbleMenu } from '@tiptap/extension-bubble-menu';
+```
+
+**For Plain Text Elements** (buttons, links, headings):
+```typescript
+const editor = new Editor({
+  element: htmlElement,
+  extensions: [
+    StarterKit.configure({
+      // Disable all formatting for plain text
+      heading: false,
+      bold: false,
+      italic: false,
+      strike: false,
+      blockquote: false,
+      bulletList: false,
+      orderedList: false,
+      listItem: false,
+      codeBlock: false,
+      horizontalRule: false,
+    }),
+    Placeholder.configure({
+      placeholder: 'Click to edit...',
+    }),
+  ],
+  content: htmlElement.innerHTML,
+  editorProps: {
+    attributes: {
+      class: 'upstart-editor-active',
+      style: 'outline: 2px solid #3b82f6; outline-offset: 2px;',
+    },
+  },
+  onUpdate: ({ editor }) => {
+    debouncedSave(hash, editor.getText());
+  },
+  onBlur: ({ editor }) => {
+    saveText(hash, editor.getText());
+    destroyEditor(hash);
+  },
+  onCreate: ({ editor }) => {
+    editor.commands.focus('end');
+  },
+});
+```
+
+**For Rich Text Elements** (paragraphs, divs, articles):
+```typescript
+const editor = new Editor({
+  element: htmlElement,
+  extensions: [
+    StarterKit, // All formatting enabled
+    Placeholder.configure({
+      placeholder: 'Start typing...',
+    }),
+    BubbleMenu.configure({
+      // Bubble menu appears on text selection
+      element: createBubbleMenuElement(),
+    }),
+  ],
+  content: htmlElement.innerHTML,
+  editorProps: {
+    attributes: {
+      class: 'upstart-editor-active',
+      style: 'outline: 2px solid #3b82f6; outline-offset: 2px;',
+    },
+  },
+  onUpdate: ({ editor }) => {
+    debouncedSave(hash, editor.getHTML()); // Use HTML for rich text
+  },
+  onBlur: ({ editor }) => {
+    saveText(hash, editor.getHTML());
+    destroyEditor(hash);
+  },
+  onCreate: ({ editor }) => {
+    editor.commands.focus('end');
+  },
+});
+```
+
+### Editor Instance Management
+
+**Track active editors**:
+```typescript
+const activeEditors = new Map<string, EditorInstance>();
+
+interface EditorInstance {
+  editor: Editor;
+  element: HTMLElement;
+  hash: string;
+}
+```
+
+**Activate editor**:
+```typescript
+function activateEditor(element: HTMLElement, hash: string) {
+  const isRichText = shouldUseRichText(element);
+
+  const editor = new Editor({
+    // ... configuration based on isRichText
+  });
+
+  // Store instance
+  activeEditors.set(hash, { editor, element, hash });
+}
+```
+
+**Destroy editor**:
+```typescript
+function destroyEditor(hash: string) {
+  const instance = activeEditors.get(hash);
+  if (instance) {
+    instance.editor.destroy();
+    instance.element.style.outline = '';
+    activeEditors.delete(hash);
+  }
+}
+```
+
+### Save Mechanism via postMessage
+
+**Message Types** to send to parent:
+
+```typescript
+// Type definitions for messages
+type EditorMessage =
+  | { type: 'text-update', hash: string, newText: string }
+  | { type: 'text-save', hash: string, newText: string }
+  | { type: 'editor-ready' }
+  | { type: 'editor-error', error: string };
+```
+
+**Debounced auto-save** (during typing):
+```typescript
+let saveTimeout: number | undefined;
+
+function debouncedSave(hash: string, content: string) {
+  if (saveTimeout) {
+    clearTimeout(saveTimeout);
+  }
+
+  saveTimeout = window.setTimeout(() => {
+    // Send update message (non-critical, for preview)
+    sendToParent({
+      type: 'text-update',
+      hash,
+      newText: content,
+    });
+  }, 1000); // 1 second delay
+}
+```
+
+**Immediate save** (on blur or Cmd+Enter):
+```typescript
+function saveText(hash: string, newText: string) {
+  try {
+    // Send save message (critical, must update source file)
+    sendToParent({
+      type: 'text-save',
+      hash,
+      newText,
+    });
+
+    console.log('[Upstart Editor] Text save message sent:', hash);
+  } catch (error) {
+    console.error('[Upstart Editor] Failed to send save message:', error);
+
+    // Notify parent of error
+    sendToParent({
+      type: 'editor-error',
+      error: error instanceof Error ? error.message : 'Unknown error',
+    });
+  }
+}
+```
+
+**Helper function to send messages to parent**:
+```typescript
+function sendToParent(message: EditorMessage) {
+  if (window.parent === window) {
+    // Not in iframe, log warning
+    console.warn('[Upstart Editor] Not running in iframe, cannot send message:', message);
+    return;
+  }
+
+  // Send to parent with origin check (use '*' for development, specific origin for production)
+  window.parent.postMessage(
+    {
+      source: 'upstart-editor',
+      ...message,
+    },
+    '*' // TODO: Use specific origin in production for security
+  );
+}
+```
+
+**Notify parent when editor is ready**:
+```typescript
+// In initTextEditor(), after setup
+export function initTextEditor() {
+  console.log('[Upstart Editor] Initializing text editor...');
+
+  // ... setup code ...
+
+  // Notify parent that editor is ready
+  sendToParent({ type: 'editor-ready' });
+}
+```
+```
+
+### Additional Features
+
+**Keyboard shortcuts**:
+- `Escape`: Cancel editing (blur without saving)
+- `Cmd/Ctrl + Enter`: Save and close editor
+
+```typescript
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape') {
+    // Blur all active editors
+    activeEditors.forEach((instance) => {
+      instance.editor.commands.blur();
+    });
+  }
+
+  if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+    // Save and close
+    activeEditors.forEach((instance) => {
+      instance.editor.commands.blur();
+    });
+  }
+});
+```
+
+**Visual feedback states**:
+- Default: No outline
+- Hover: `1px dashed #3b82f6`
+- Active editing: `2px solid #3b82f6` with slight offset
+- Saving: Could add a "saving..." indicator (future enhancement)
+
+---
+
+## Part 4: Click Handler (`vite-plugin-upstart-editor/runtime/click-handler.ts`)
+
+### Purpose
+Detect clicks on elements to trigger className editing in the parent window.
+
+### Requirements
+
+**Click detection**:
+```typescript
+import { getCurrentMode } from './index';
+import { sendToParent } from './utils';
+
+export function initClickHandler() {
+  console.log('[Upstart Editor] Initializing click handler...');
+
+  document.addEventListener('click', handleClick, true); // Use capture phase
+}
+
+function handleClick(e: MouseEvent) {
+  // Only handle clicks in edit mode
+  if (getCurrentMode() !== 'edit') return;
+
+  const target = e.target as HTMLElement;
+
+  // Find the nearest component element
+  const component = target.closest('[data-upstart-component]');
+
+  if (!component) return;
+
+  // Prevent default behavior (like link navigation)
+  e.preventDefault();
+  e.stopPropagation();
+
+  const htmlElement = component as HTMLElement;
+  const hash = htmlElement.dataset.upstartHash;
+  const componentName = htmlElement.dataset.upstartComponent;
+  const filePath = htmlElement.dataset.upstartFile;
+
+  if (!hash || !componentName) return;
+
+  // Get current className
+  const currentClassName = htmlElement.className;
+
+  // Get element bounds for positioning parent UI
+  const rect = htmlElement.getBoundingClientRect();
+
+  // Send click event to parent
+  sendToParent({
+    type: 'element-clicked',
+    hash,
+    componentName,
+    filePath: filePath || '',
+    currentClassName,
+    bounds: {
+      top: rect.top,
+      left: rect.left,
+      width: rect.width,
+      height: rect.height,
+      right: rect.right,
+      bottom: rect.bottom,
+    },
+  });
+
+  console.log('[Upstart Editor] Element clicked:', componentName, hash);
+}
+```
+
+**Cleanup function**:
+```typescript
+export function cleanupClickHandler() {
+  document.removeEventListener('click', handleClick, true);
+}
+```
+
+**Important notes**:
+- Use capture phase (`true` parameter) to catch clicks before they reach the target
+- Prevent default behavior to stop navigation
+- Only components with `data-upstart-component` are clickable for className editing
+- Text elements with `data-upstart-editable-text` use double-click for text editing
+
+---
+
+## Part 5: Hover Overlay (`vite-plugin-upstart-editor/runtime/hover-overlay.ts`)
+
+### Purpose
+Show visual feedback when hovering over components, indicating they're part of the editable system. Only active in edit mode.
+
+### Requirements
+
+**Create overlay element**:
+```typescript
+import { getCurrentMode } from './index';
+import { sendToParent } from './utils';
+
+let overlay: HTMLDivElement | null = null;
+let currentTarget: HTMLElement | null = null;
+
+function createOverlay() {
+  overlay = document.createElement('div');
+  overlay.id = 'upstart-hover-overlay';
+  overlay.style.cssText = `
+    position: absolute;
+    pointer-events: none;
+    border: 2px solid #3b82f6;
+    background: rgba(59, 130, 246, 0.05);
+    border-radius: 4px;
+    z-index: 9999;
+    transition: all 0.1s ease;
+    display: none;
+  `;
+  document.body.appendChild(overlay);
+}
+```
+
+**Position overlay over element**:
+```typescript
+function positionOverlay(element: HTMLElement) {
+  if (!overlay) return;
+
+  const rect = element.getBoundingClientRect();
+
+  overlay.style.top = `${rect.top + window.scrollY}px`;
+  overlay.style.left = `${rect.left + window.scrollX}px`;
+  overlay.style.width = `${rect.width}px`;
+  overlay.style.height = `${rect.height}px`;
+  overlay.style.display = 'block';
+}
+```
+
+**Show overlay on hover** (only in edit mode):
+```typescript
+document.addEventListener('mouseover', (e) => {
+  // Only show in edit mode
+  if (getCurrentMode() !== 'edit') return;
+
+  const target = e.target as HTMLElement;
+
+  // Only show on elements with data-upstart-component
+  if (target.hasAttribute('data-upstart-component')) {
+    if (!overlay) createOverlay();
+    currentTarget = target;
+    positionOverlay(target);
+
+    // Notify parent about hovered element
+    const hash = target.dataset.upstartHash;
+    if (hash) {
+      const rect = target.getBoundingClientRect();
+      sendToParent({
+        type: 'element-hovered',
+        hash,
+        bounds: {
+          top: rect.top,
+          left: rect.left,
+          width: rect.width,
+          height: rect.height,
+          right: rect.right,
+          bottom: rect.bottom,
+        },
+      });
+    }
+  }
+});
+```
+
+**Hide overlay on mouseout**:
+```typescript
+document.addEventListener('mouseout', (e) => {
+  const target = e.target as HTMLElement;
+
+  if (target.hasAttribute('data-upstart-component')) {
+    if (overlay) {
+      overlay.style.display = 'none';
+      currentTarget = null;
+    }
+  }
+});
+```
+
+**Update position on scroll/resize**:
+```typescript
+let rafId: number | null = null;
+
+function updateOverlayPosition() {
+  if (currentTarget && overlay && overlay.style.display === 'block') {
+    positionOverlay(currentTarget);
+  }
+  rafId = null;
+}
+
+window.addEventListener('scroll', () => {
+  if (rafId === null) {
+    rafId = requestAnimationFrame(updateOverlayPosition);
+  }
+}, { passive: true });
+
+window.addEventListener('resize', () => {
+  if (rafId === null) {
+    rafId = requestAnimationFrame(updateOverlayPosition);
+  }
+}, { passive: true });
+```
+
+**Export initialization**:
+```typescript
+export function initHoverOverlay() {
+  console.log('[Upstart Editor] Initializing hover overlay...');
+
+  // Event listeners are registered when this function is called
+  // Overlay is created lazily on first hover
+  // They only activate when getCurrentMode() === 'edit'
+}
+
+export function hideOverlays() {
+  if (overlay) {
+    overlay.style.display = 'none';
+    currentTarget = null;
+  }
+}
+```
+
+---
+
+## Part 6: Types (`vite-plugin-upstart-editor/runtime/types.ts`)
+
+### Purpose
+Shared TypeScript types for the editor system.
+
+### Required Types
+
+```typescript
+import type { Editor } from '@tiptap/core';
+
+/**
+ * Represents an active editor instance
+ */
+export interface EditorInstance {
+  editor: Editor;
+  element: HTMLElement;
+  hash: string;
+}
+
+/**
+ * Messages sent from iframe to parent editor
+ */
+export type EditorMessage =
+  | { type: 'text-update'; hash: string; newText: string }
+  | { type: 'text-save'; hash: string; newText: string }
+  | { type: 'editor-ready' }
+  | { type: 'editor-error'; error: string }
+  | { type: 'element-hovered'; hash: string; bounds: DOMRect }
+  | {
+      type: 'element-clicked';
+      hash: string;
+      componentName: string;
+      filePath: string;
+      currentClassName: string;
+      bounds: DOMRect;
+    };
+
+/**
+ * Messages sent from parent to iframe
+ */
+export type ParentMessage =
+  | { type: 'set-mode'; mode: 'edit' | 'preview' };
+
+/**
+ * Message wrapper sent via postMessage from iframe
+ */
+export interface UpstartEditorMessage {
+  source: 'upstart-editor';
+  type: EditorMessage['type'];
+  [key: string]: any;
+}
+
+/**
+ * Message wrapper sent via postMessage from parent
+ */
+export interface UpstartParentMessage {
+  source: 'upstart-editor-parent';
+  type: ParentMessage['type'];
+  [key: string]: any;
+}
+
+/**
+ * Configuration options for the Upstart Editor
+ */
+export interface UpstartEditorOptions {
+  /**
+   * Elements that should use rich text editing (with formatting)
+   * @default ['p', 'div', 'article', 'section']
+   */
+  richTextElements?: string[];
+
+  /**
+   * Elements that should use plain text editing (no formatting)
+   * @default ['button', 'a', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'label']
+   */
+  plainTextElements?: string[];
+
+  /**
+   * Enable bubble menu for text selection
+   * @default true
+   */
+  bubbleMenu?: boolean;
+
+  /**
+   * Placeholder text for empty editors
+   * @default 'Start typing...'
+   */
+  placeholder?: string;
+
+  /**
+   * Auto-save delay in milliseconds
+   * @default 1000
+   */
+  autoSaveDelay?: number;
+}
+
+/**
+ * Build-time plugin options
+ */
+export interface UpstartEditorPluginOptions {
+  /**
+   * Enable or disable the editor
+   * @default false
+   */
+  enabled?: boolean;
+
+  /**
+   * Automatically inject editor initialization code
+   * @default true
+   */
+  autoInject?: boolean;
+}
+
+/**
+ * Editor mode
+ */
+export type EditorMode = 'preview' | 'edit';
+```
+
+---
+
+## Part 7: Utility Functions (`vite-plugin-upstart-editor/runtime/utils.ts`)
+
+### Purpose
+Shared utility functions for postMessage communication.
+
+### Requirements
+
+```typescript
+import type { EditorMessage } from './types';
+
+/**
+ * Send a message to the parent window
+ */
+export function sendToParent(message: EditorMessage) {
+  if (window.parent === window) {
+    // Not in iframe, log warning
+    console.warn('[Upstart Editor] Not running in iframe, cannot send message:', message);
+    return;
+  }
+
+  // Send to parent with origin check (use '*' for development, specific origin for production)
+  window.parent.postMessage(
+    {
+      source: 'upstart-editor',
+      ...message,
+    },
+    '*' // TODO: Use specific origin in production for security
+  );
+}
+
+/**
+ * Check if running inside an iframe
+ */
+export function isInIframe(): boolean {
+  return window.parent !== window;
+}
+```
+
+---
+
+## Package Configuration
+
+### Update `package.json`
+
+Add new dependencies:
+```json
+{
+  "dependencies": {
+    "@tiptap/core": "^2.8.0",
+    "@tiptap/starter-kit": "^2.8.0",
+    "@tiptap/extension-placeholder": "^2.8.0",
+    "@tiptap/extension-bubble-menu": "^2.8.0"
+  }
+}
+```
+
+### Update Build Configuration
+
+If using `tsdown.config.ts`, add new entry points:
+```typescript
+export default {
+  entry: [
+    'src/vite-plugin-upstart-attrs.ts',
+    'src/vite-plugin-upstart-routes.ts',
+    'src/vite-plugin-upstart-theme.ts',
+    'src/upstart-editor-api.ts',
+    // New entries
+    'src/vite-plugin-upstart-editor/plugin.ts',
+    'src/vite-plugin-upstart-editor/runtime/index.ts',
+    'src/vite-plugin-upstart-editor/runtime/text-editor.ts',
+    'src/vite-plugin-upstart-editor/runtime/click-handler.ts',
+    'src/vite-plugin-upstart-editor/runtime/hover-overlay.ts',
+    'src/vite-plugin-upstart-editor/runtime/types.ts',
+    'src/vite-plugin-upstart-editor/runtime/utils.ts',
+  ],
+  // ... rest of config
+};
+```
+
+### Export in Main Package
+
+Update the package exports to include the new plugin:
+```json
+{
+  "exports": {
+    "./upstart-attrs": {
+      "import": "./dist/vite-plugin-upstart-attrs.js",
+      "types": "./dist/vite-plugin-upstart-attrs.d.ts"
+    },
+    "./upstart-editor": {
+      "import": "./dist/vite-plugin-upstart-editor/plugin.js",
+      "types": "./dist/vite-plugin-upstart-editor/plugin.d.ts"
+    },
+    "./upstart-editor/runtime": {
+      "import": "./dist/vite-plugin-upstart-editor/runtime/index.js",
+      "types": "./dist/vite-plugin-upstart-editor/runtime/index.d.ts"
+    }
+  }
+}
+```
+
+---
+
+## User Experience Flow
+
+1. **Developer embeds user's app in iframe** within the parent editor application
+   - The iframe loads a production build of the app (from `vite build`)
+   - Plugin is initialized in **preview mode** by default
+
+2. **User switches to edit mode**:
+   - Parent sends `set-mode` message with `mode: 'edit'`
+   - Editor plugin activates all handlers
+
+3. **User sees app** with visual editing affordances:
+   - Hover overlays appear on components
+   - Text elements show cursor and outline hints
+
+4. **User hovers over components** (in edit mode):
+   - Blue overlay appears in iframe
+   - `element-hovered` message sent to parent with element bounds
+   - Parent could show element info in sidebar
+
+5. **User clicks an element** (in edit mode):
+   - `element-clicked` message sent to parent
+   - Parent shows className editor UI (outside iframe)
+   - User edits Tailwind classes in parent UI
+   - Parent updates source file, rebuilds, reloads iframe
+
+6. **User double-clicks text** (in edit mode):
+   - TipTap editor activates inside iframe
+   - Plain text elements: Basic editor, no formatting
+   - Rich text elements: Full editor with formatting toolbar
+
+7. **User types** (text editing):
+   - Changes are debounced (1 second)
+   - `text-update` message sent to parent (optional, for live preview)
+
+8. **User clicks away or presses Escape** (text editing):
+   - `text-save` message sent to parent
+   - Parent editor updates source file
+   - Parent runs `vite build` to rebuild the app
+   - Parent reloads the iframe with the new build
+
+9. **User switches to preview mode**:
+   - Parent sends `set-mode` message with `mode: 'preview'`
+   - All handlers deactivate
+   - User can interact with page normally (click links, test functionality)
+
+10. **Parent editor responsibilities**:
+   - Listen for `postMessage` events from iframe
+   - Filter messages by `source: 'upstart-editor'`
+   - Send mode changes to iframe
+   - Show className editor UI on `element-clicked`
+   - Update source files based on `text-save` or className changes
+   - Run `vite build` to create new production build
+   - Reload iframe (e.g., by updating iframe `src` with cache-busting query param)
+
+**Parent Editor Message Handler Example**:
+```typescript
+// In parent editor application
+window.addEventListener('message', async (event) => {
+  const message = event.data;
+
+  // Verify message is from our editor
+  if (message.source !== 'upstart-editor') return;
+
+  switch (message.type) {
+    case 'editor-ready':
+      console.log('Editor initialized in iframe');
+      // Optionally set initial mode
+      setIframeMode('preview'); // or 'edit'
+      break;
+
+    case 'text-update':
+      // Optional: Show live preview (without rebuilding)
+      console.log('Text being edited:', message.hash);
+      break;
+
+    case 'text-save':
+      // Update source file
+      await updateSourceFile(message.hash, message.newText);
+
+      // Rebuild the app
+      await runViteBuild();
+
+      // Reload iframe with cache busting
+      const iframe = document.querySelector('iframe');
+      const currentSrc = iframe.src.split('?')[0];
+      iframe.src = `${currentSrc}?t=${Date.now()}`;
+      break;
+
+    case 'element-clicked':
+      // Show className editor UI
+      showClassNameEditor({
+        hash: message.hash,
+        componentName: message.componentName,
+        currentClassName: message.currentClassName,
+        bounds: message.bounds,
+      });
+      break;
+
+    case 'element-hovered':
+      // Optional: Highlight in layer tree or show properties
+      showElementProperties(message.hash, message.bounds);
+      break;
+
+    case 'editor-error':
+      console.error('Editor error:', message.error);
+      break;
+  }
+});
+
+// Function to send mode changes to iframe
+function setIframeMode(mode: 'edit' | 'preview') {
+  const iframe = document.querySelector('iframe');
+  iframe?.contentWindow?.postMessage({
+    source: 'upstart-editor-parent',
+    type: 'set-mode',
+    mode,
+  }, '*');
+}
+```
+
+---
+
+## Edge Cases to Handle
+
+### Multiple Editors
+- **Problem**: User might double-click multiple elements
+- **Solution**: Track active editors in a Map, prevent duplicate editors on same element
+
+### Memory Leaks
+- **Problem**: Editor instances not properly cleaned up
+- **Solution**: Always call `editor.destroy()` and remove from Map on blur
+
+### Event Bubbling
+- **Problem**: Clicks/double-clicks propagate to parent elements
+- **Solution**: Use `e.stopPropagation()` on editor activation
+
+### Scroll/Resize
+- **Problem**: Hover overlay doesn't update position
+- **Solution**: Use `requestAnimationFrame` to efficiently update position
+
+### Iframe Reload
+- **Problem**: Editor state is lost when iframe reloads after build
+- **Solution**: This is expected behavior - the iframe loads fresh HTML after each build
+
+### Nested Elements
+- **Problem**: Hovering nested components shows multiple overlays
+- **Solution**: Only show overlay for the directly hovered element (current implementation handles this)
+
+### Empty Text Elements
+- **Problem**: Can't click on empty elements
+- **Solution**: TipTap's Placeholder extension handles this
+
+### Not in Iframe
+- **Problem**: Plugin might run when not embedded in iframe
+- **Solution**: Check `window.parent === window` before sending messages, log warning if not in iframe
+
+### Cross-Origin Issues
+- **Problem**: postMessage might be blocked by CORS
+- **Solution**: Use `'*'` for development (with security warning), document how to configure specific origin for production
+
+### Message Loss
+- **Problem**: postMessage might be sent before parent is ready to receive
+- **Solution**: Parent should send ready signal first (optional), or use retry logic
+
+### Large Text Content
+- **Problem**: Very large text might cause performance issues with postMessage
+- **Solution**: Consider chunking or compression for large content (future enhancement)
+
+### Build Performance
+- **Problem**: Running `vite build` on every text change is slow
+- **Solution**:
+  - Use debouncing (1 second delay before save)
+  - Only trigger build on `text-save`, not on `text-update`
+  - Parent editor should queue builds if multiple saves happen quickly
+
+---
+
+## Success Criteria
+
+The implementation is successful when:
+
+1. ✅ Plugin injects code during `vite build` without manual user setup
+2. ✅ Double-clicking text elements activates TipTap editor
+3. ✅ Plain text elements get basic editor (no formatting)
+4. ✅ Rich text elements get full editor (with formatting toolbar)
+5. ✅ Changes trigger `text-update` messages (debounced) via postMessage
+6. ✅ Blur triggers `text-save` messages (immediate) via postMessage
+7. ✅ All messages include `source: 'upstart-editor'` identifier
+8. ✅ Hover overlay shows on component elements
+9. ✅ Hover triggers `element-hovered` messages with bounds
+10. ✅ Overlay updates smoothly on scroll/resize
+11. ✅ No memory leaks (editors are properly cleaned up)
+12. ✅ Full TypeScript support with proper types
+13. ✅ Works correctly in production builds (from `vite build`)
+14. ✅ No global namespace pollution
+15. ✅ Visual feedback is clear and non-intrusive
+16. ✅ Keyboard shortcuts work (Escape, Cmd+Enter)
+17. ✅ No duplicate editors on same element
+18. ✅ Event propagation handled correctly
+19. ✅ Graceful handling when not in iframe (warning logged)
+20. ✅ `editor-ready` message sent when initialization complete
+
+---
+
+## Code Style Guidelines
+
+Follow the same patterns as the attached `vite-plugin-upstart-attrs.ts`:
+
+- Use `unplugin` with `createUnplugin`
+- Use early returns for clarity
+- Add comprehensive JSDoc comments
+- Use descriptive variable names
+- Handle errors gracefully with try-catch
+- Log with consistent prefix: `[Upstart Editor]`
+- Use TypeScript strict mode
+- Export types alongside functions
+- Use `const` for immutable values
+- Prefer `async/await` over Promises
+
+---
+
+## Additional Notes
+
+- All runtime code must be in actual `.ts` files (NOT template strings)
+- Use Vite's module resolution during the build process
+- Keep the plugin build-time logic separate from runtime logic
+- Make the API extensible for future features (class editing, layout editing, etc.)
+- Provide clear error messages for debugging
+- The code should be production-ready and maintainable
+- The plugin is designed for production builds (`vite build`), not dev server
+- Each text change requires a full rebuild and iframe reload (no HMR)
+
+---
+
+## Deliverables
+
+Please create the following files with complete, production-ready code:
+
+1. `src/vite-plugin-upstart-editor/plugin.ts` - Build-time Vite plugin
+2. `src/vite-plugin-upstart-editor/runtime/index.ts` - Runtime entry point with mode management
+3. `src/vite-plugin-upstart-editor/runtime/text-editor.ts` - TipTap text editing logic
+4. `src/vite-plugin-upstart-editor/runtime/click-handler.ts` - Click detection for className editing
+5. `src/vite-plugin-upstart-editor/runtime/hover-overlay.ts` - Visual hover overlay
+6. `src/vite-plugin-upstart-editor/runtime/types.ts` - TypeScript type definitions
+7. `src/vite-plugin-upstart-editor/runtime/utils.ts` - Utility functions for postMessage
+
+Each file should:
+- Include comprehensive JSDoc comments
+- Handle all edge cases mentioned
+- Follow the code style of existing plugins
+- Be fully typed with TypeScript
+- Include error handling and logging
+- Be ready for production use
+- Respect preview/edit mode appropriately
+
+---
+
+## Security Considerations for postMessage
+
+Since the plugin uses `window.parent.postMessage()` for iframe communication, there are important security considerations:
+
+### Development vs Production
+
+**Development** (current implementation):
+```typescript
+window.parent.postMessage(message, '*'); // Accept any origin
+```
+
+**Production** (future enhancement):
+```typescript
+const ALLOWED_ORIGINS = ['https://editor.upstart.com', 'https://app.upstart.com'];
+window.parent.postMessage(message, ALLOWED_ORIGINS[0]);
+```
+
+### Message Validation
+
+The parent editor should validate incoming messages:
+
+```typescript
+window.addEventListener('message', (event) => {
+  // 1. Check origin (in production)
+  // if (!ALLOWED_ORIGINS.includes(event.origin)) return;
+
+  // 2. Verify message structure
+  if (typeof event.data !== 'object' || !event.data) return;
+
+  // 3. Check source identifier
+  if (event.data.source !== 'upstart-editor') return;
+
+  // 4. Validate message type
+  const validTypes = ['text-update', 'text-save', 'editor-ready', 'editor-error', 'element-hovered'];
+  if (!validTypes.includes(event.data.type)) return;
+
+  // Now safe to process
+  handleEditorMessage(event.data);
+});
+```
+
+### Recommendations
+
+1. **For now**: Use `'*'` origin for development simplicity
+2. **Document**: Add clear comments warning about security implications
+3. **Future**: Make origin configurable via plugin options
+4. **Parent**: Always validate messages on the parent side
+
+---
+
+## Questions for Clarification (Optional)
+
+If you need clarification on any of the following, please ask:
+
+1. Should the bubble menu for rich text have specific formatting buttons?
+2. Should there be a visual "saving..." indicator during auto-save?
+3. Should the editor support undo/redo history?
+4. Should there be a setting to disable auto-save?
+5. Should keyboard shortcuts be configurable?
+
+Otherwise, use sensible defaults as specified in this document.