@weave-apps/sdk 0.1.0

package/templates/WEAVE_SPEC.md

@@ -0,0 +1,3703 @@
+# Weave App Development Specification
+
+> **AI Assistant Guide**: This document provides the complete specification for building Weave applications. Use this as your reference when helping developers create apps.
+
+## Architecture Overview
+
+Weave apps are **Web Components** that run in an **iframe** inside a browser extension sidebar. They interact with two secure APIs:
+
+1. **Weave Backend API** - AI services and data storage
+2. **DOM Bridge API** - Parent page DOM manipulation
+
+```
+[Weave Backend] ←→ [Sidebar: API Bridge] ←→ [Iframe: Weave App]
+                                                        ↕
+[Parent Page] ←→ [Content Script: DOMBridge] ←→ [Iframe: Weave App]
+```
+
+### Key Constraints
+
+- ✅ Apps run in an **isolated iframe** (different origin)
+- ✅ Apps use **Shadow DOM** for style isolation
+- ✅ **Tailwind CSS is available** for styling
+- ✅ **No direct DOM access** to parent page
+- ✅ **No arbitrary HTTP requests** to external APIs
+- ✅ All backend calls go through **`weaveAPI`** (AI, data storage)
+- ✅ All parent page interactions go through **`weaveDOM`** (DOM manipulation)
+- ✅ Apps are uploaded as **plain JavaScript strings** (not modules)
+- ✅ SDK is available on **window globals** (not imported)
+
+## App Structure
+
+### Important: App Header Already Displayed
+
+**The Weave sidebar automatically displays your app's name as a header at the top of the drawer.** You do NOT need to include your app name as a header in your render method. Including it would create a duplicate header.
+
+✅ **CORRECT:**
+```typescript
+protected render(): void {
+  this.renderHTML(`
+    <div class="p-4">
+      <!-- No need for app name header - it's already shown by the sidebar -->
+      <p>Your app content starts here...</p>
+    </div>
+  `);
+}
+```
+
+❌ **WRONG - Creates duplicate header:**
+```typescript
+protected render(): void {
+  this.renderHTML(`
+    <div class="p-4">
+      <h1>My App Name</h1>  <!-- ❌ Duplicate! Sidebar already shows this -->
+      <p>Your app content...</p>
+    </div>
+  `);
+}
+```
+
+### Base Class: `WeaveBaseApp`
+
+All apps **must** extend `WeaveBaseApp` (available as `window.WeaveBaseApp`):
+
+```typescript
+import { WeaveBaseApp } from '@weave/app-sdk';
+
+class MyApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      name: 'My App',             // Display name
+      version: '1.0.0',           // Semantic version
+      category: 'utility',        // App category
+      description: 'Description', // What the app does
+      tags: ['tag1', 'tag2']      // Optional tags
+    });
+    
+    // Initialize state
+    this.state = {
+      // Your app state here
+    };
+  }
+
+  protected render(): void {
+    // Render your UI
+    this.renderHTML(`
+      <style>
+        /* Scoped styles */
+      </style>
+      <div>Your HTML</div>
+    `);
+  }
+
+  protected setupEventListeners(): void {
+    // Setup event listeners
+    this.query('#myButton')?.addEventListener('click', () => {
+      this.handleClick();
+    });
+  }
+
+  protected cleanup(): void {
+    // Optional: cleanup when app unmounts
+  }
+}
+
+// Register the custom element
+customElements.define('my-app', MyApp);
+```
+
+### Required Methods
+
+#### `constructor(appInfo: WeaveAppInfo)`
+- Initialize app metadata
+- Set initial state
+- **Do NOT** render or setup listeners here
+
+#### `render(): void`
+- Called automatically when app is added to DOM
+- Use `this.renderHTML(html)` to inject content
+- Include `<style>` tags for scoped CSS
+
+#### `setupEventListeners(): void` (Optional)
+- Called after `render()`
+- Attach event listeners to shadow DOM elements
+- Use `this.query()` to find elements
+
+#### `cleanup(): void` (Optional)
+- Called when app is removed from DOM
+- Clear intervals, remove listeners, etc.
+
+## App Settings
+
+### Overview
+
+App Settings provide a way for **Enterprise Admins** to configure app behavior without modifying code. Settings are simple **key-value pairs** (both key and value are strings) that are:
+
+- 🔧 **Configured in Enterprise Admin Console** - Admins set values per app
+- 🚀 **Automatically injected at runtime** - Available in `this.appSettings` before any app code runs
+- 🔒 **Read-only in apps** - Apps cannot modify settings (admin-controlled)
+- 🌍 **Company-scoped** - Each company can have different settings for the same app
+- 💡 **Perfect for configuration** - URLs, API keys, feature flags, thresholds, etc.
+
+### How It Works
+
+```
+1. Admin uploads app to Enterprise Console
+2. Admin configures settings (key-value pairs)
+3. User loads sidebar → Apps are instantiated
+4. BackgroundAppManager automatically calls setAppSettings()
+5. Settings available in this.appSettings throughout app lifecycle
+```
+
+### Architecture
+
+**Enterprise Admin Console** → Sets settings → **Weave API** → Stores in database
+                                                        ↓
+**Sidebar loads** → Fetches app data → **BackgroundAppManager** → Calls `setAppSettings()`
+                                                        ↓
+                                            **Your App** → Access via `this.appSettings`
+
+### Accessing Settings in Your App
+
+Settings are automatically available in the `this.appSettings` property:
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      name: 'My App',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Configurable app',
+      tags: ['config']
+    });
+  }
+
+  async onBackgroundService() {
+    // ✅ Settings are already available here
+    const apiUrl = this.appSettings?.apiEndpoint || 'https://default-api.com';
+    const maxRetries = parseInt(this.appSettings?.maxRetries || '3');
+    const featureEnabled = this.appSettings?.enableFeature === 'true';
+    
+    console.log('API URL:', apiUrl);
+    console.log('Max Retries:', maxRetries);
+    console.log('Feature Enabled:', featureEnabled);
+  }
+
+  render() {
+    // ✅ Settings available in render too
+    const theme = this.appSettings?.theme || 'light';
+    
+    this.renderHTML(`
+      <div class="p-4">
+        <p>Current theme: ${theme}</p>
+      </div>
+    `);
+  }
+}
+```
+
+### Setting Types and Parsing
+
+**Important:** All setting values are **strings**. You must parse them for other types:
+
+```typescript
+// String values (no parsing needed)
+const apiUrl = this.appSettings?.apiUrl || 'https://default.com';
+const userName = this.appSettings?.userName || 'Guest';
+
+// Numeric values (parse to number)
+const timeout = parseInt(this.appSettings?.timeout || '5000');
+const maxItems = parseFloat(this.appSettings?.maxItems || '100');
+
+// Boolean values (compare string)
+const isEnabled = this.appSettings?.featureFlag === 'true';
+const debugMode = this.appSettings?.debug === '1'; // or '1', 'yes', etc.
+
+// JSON values (parse JSON string)
+const config = JSON.parse(this.appSettings?.config || '{}');
+const allowedRoles = JSON.parse(this.appSettings?.roles || '[]');
+```
+
+### Common Use Cases
+
+#### 1. Configurable URLs
+
+```typescript
+class DataExportApp extends WeaveBaseApp {
+  async injectButton() {
+    const buttonId = await window.weaveDOM.injectElement(
+      '.header',
+      'beforeend',
+      '<button>Export Data</button>',
+      {
+        onClick: async () => {
+          // ✅ Use setting for target system domain (admin-configurable)
+          const targetDomain = this.appSettings?.targetSystemUrl || 'https://app.example.com';
+          
+          // Open target system with configured domain
+          window.open(`${targetDomain}/import`, '_blank');
+        }
+      }
+    );
+  }
+}
+```
+
+**Why this is useful:**
+- Different companies may use different system instances (staging, production, custom domains)
+- Admin can configure without code changes
+- Same app works for all companies with different URLs
+
+#### 2. Feature Flags
+
+```typescript
+class SmartFormApp extends WeaveBaseApp {
+  async onBackgroundService() {
+    // Check if AI suggestions feature is enabled
+    const aiEnabled = this.appSettings?.enableAiSuggestions === 'true';
+    const autoFillEnabled = this.appSettings?.enableAutoFill === 'true';
+    
+    if (aiEnabled) {
+      await this.setupAiSuggestions();
+    }
+    
+    if (autoFillEnabled) {
+      await this.setupAutoFill();
+    }
+  }
+}
+```
+
+#### 3. API Keys and Credentials
+
+```typescript
+class IntegrationApp extends WeaveBaseApp {
+  async callExternalService() {
+    // ✅ Admin configures API key per company
+    const apiKey = this.appSettings?.apiKey;
+    
+    if (!apiKey) {
+      console.error('API key not configured');
+      return;
+    }
+    
+    // Use API key in requests
+    const response = await this.weaveAPI.ai.chat({
+      prompt: `Call external service with key: ${apiKey}`,
+      context: 'Integration request'
+    });
+  }
+}
+```
+
+#### 4. Thresholds and Limits
+
+```typescript
+class MonitoringApp extends WeaveBaseApp {
+  async checkMetrics() {
+    // Admin-configurable thresholds
+    const warningThreshold = parseInt(this.appSettings?.warningThreshold || '80');
+    const criticalThreshold = parseInt(this.appSettings?.criticalThreshold || '95');
+    const checkInterval = parseInt(this.appSettings?.checkIntervalMs || '60000');
+    
+    setInterval(() => {
+      const currentValue = this.getCurrentMetric();
+      
+      if (currentValue > criticalThreshold) {
+        this.showAlert('critical');
+      } else if (currentValue > warningThreshold) {
+        this.showAlert('warning');
+      }
+    }, checkInterval);
+  }
+}
+```
+
+#### 5. UI Customization
+
+```typescript
+class CustomDashboard extends WeaveBaseApp {
+  render() {
+    // Admin-configurable UI elements
+    const primaryColor = this.appSettings?.primaryColor || '#4f46e5';
+    const logoUrl = this.appSettings?.logoUrl || '';
+    const welcomeMessage = this.appSettings?.welcomeMessage || 'Welcome!';
+    
+    this.renderHTML(`
+      <style>
+        .header { background: ${primaryColor}; }
+      </style>
+      <div class="p-4">
+        ${logoUrl ? `<img src="${logoUrl}" alt="Logo" />` : ''}
+        <h2>${welcomeMessage}</h2>
+      </div>
+    `);
+  }
+}
+```
+
+### Setting Key Naming Conventions
+
+**Best Practices:**
+- Use **camelCase** for keys: `apiEndpoint`, `maxRetries`, `enableFeature`
+- Be **descriptive**: `dcpDomain` not `url`, `enableAiSuggestions` not `ai`
+- Use **prefixes** for grouped settings: `email_host`, `email_port`, `email_username`
+- Keep keys **short but clear**: `timeout` not `t`, `maxItems` not `maximumNumberOfItems`
+
+**Valid Key Format:**
+- Must start with a letter (a-z, A-Z)
+- Can contain letters, numbers, and underscores
+- Examples: `apiKey`, `max_retries`, `feature1_enabled`
+
+### Default Values Pattern
+
+**Always provide defaults** to handle missing settings:
+
+```typescript
+// ✅ CORRECT - Provides fallback
+const timeout = parseInt(this.appSettings?.timeout || '5000');
+const apiUrl = this.appSettings?.apiUrl || 'https://default-api.com';
+const enabled = this.appSettings?.enabled === 'true'; // false if not set
+
+// ❌ WRONG - Will crash if setting not configured
+const timeout = parseInt(this.appSettings.timeout); // Error if undefined
+```
+
+### Checking if Settings Exist
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async onBackgroundService() {
+    // Check if settings object exists
+    if (!this.appSettings) {
+      console.log('No settings configured for this app');
+      return;
+    }
+    
+    // Check if specific setting exists
+    if (!this.appSettings.apiKey) {
+      console.error('API key not configured - app cannot function');
+      this.showConfigurationError();
+      return;
+    }
+    
+    // Proceed with configured settings
+    await this.initialize();
+  }
+}
+```
+
+### Settings Lifecycle
+
+```
+1. Sidebar loads
+   ↓
+2. BackgroundAppManager fetches app data from API
+   ↓
+3. For each app with settings:
+   - BackgroundAppManager calls app.setAppSettings(settings)
+   - this.appSettings is populated
+   ↓
+4. App constructor runs
+   - this.appSettings already available
+   ↓
+5. onBackgroundService() called
+   - this.appSettings available
+   ↓
+6. App continues running
+   - this.appSettings available throughout lifecycle
+```
+
+**Key Point:** Settings are injected **before** your constructor runs, so they're available everywhere in your app.
+
+### Real-World Example: Medical Notes Export Integration
+
+This example shows how an app uses settings for configurable target system domain:
+
+```typescript
+class MedicalNotesExportApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      name: 'Medical Notes Export',
+      version: '1.0.0',
+      category: 'integration',
+      description: 'Export medical notes to external system',
+      tags: ['medical', 'export', 'integration']
+    });
+    
+    this.state = {
+      buttonInjected: false,
+      buttonElementId: null
+    };
+  }
+
+  async onBackgroundService() {
+    const pageUrl = await window.weaveDOM.getPageUrl();
+    
+    // Only inject on medical records pages
+    if (pageUrl.includes('medical-records.example.com')) {
+      await this.injectButton();
+    }
+  }
+
+  async injectButton() {
+    if (this.state.buttonInjected) return;
+    
+    const self = this;
+    
+    this.state.buttonElementId = await window.weaveDOM.injectElement(
+      '.toolbar',
+      'beforeend',
+      '<button class="export-btn">📋 Export Notes</button>',
+      {
+        onClick: async () => {
+          try {
+            // Get content from page
+            const content = await window.weaveDOM.query('[data-testid="notes-editor"]');
+            
+            if (content && content.textContent) {
+              // Save content via API
+              await self.saveContent(content.textContent);
+              
+              // ✅ Use configurable target system domain from settings
+              // Admin can set different domains per company:
+              // - Production: https://app.target-system.com
+              // - Staging: https://staging.target-system.com
+              // - Custom: https://custom-instance.example.com
+              const targetDomain = self.appSettings?.targetSystemUrl || 'https://app.target-system.com';
+              
+              // Open target system with configured domain
+              window.open(`${targetDomain}/import`, '_blank');
+            }
+          } catch (error) {
+            console.error('Error exporting notes:', error);
+          }
+        }
+      }
+    );
+    
+    this.state.buttonInjected = true;
+  }
+
+  async saveContent(content: string) {
+    const apiClient = this.weaveAPI;
+    
+    // Save to app data
+    await apiClient.appData.create({
+      dataKey: 'exported-note',
+      data: { content, timestamp: Date.now() }
+    });
+  }
+}
+
+customElements.define('medical-notes-export-app', MedicalNotesExportApp);
+```
+
+**What the admin configures:**
+```
+Key: targetSystemUrl
+Value: https://staging.target-system.com
+```
+
+**Result:** All users in that company will have notes exported to the staging instance instead of production.
+
+### Settings vs State
+
+**App Settings (`this.appSettings`):**
+- ✅ Configured by **Enterprise Admin**
+- ✅ **Read-only** in app code
+- ✅ **Company-scoped** (different per company)
+- ✅ **Persistent** (stored in database)
+- ✅ Use for: URLs, API keys, feature flags, thresholds
+- ❌ Cannot be modified by app
+
+**App State (`this.state`):**
+- ✅ Managed by **app code**
+- ✅ **Read-write** in app
+- ✅ **User-scoped** (per user instance)
+- ✅ **Temporary** (lost on sidebar reload)
+- ✅ Use for: UI state, counters, flags, temporary data
+- ❌ Not persisted across sessions
+
+### Best Practices
+
+#### ✅ DO:
+- Always provide **default values** using `||` operator
+- **Parse** string values to appropriate types (number, boolean, JSON)
+- **Validate** settings before use (check if exists, check format)
+- Use settings for **configuration** (URLs, keys, flags, limits)
+- Document **expected settings** in your app description
+- Use **descriptive key names** (camelCase)
+
+#### ❌ DON'T:
+- Don't assume settings exist (always check or provide defaults)
+- Don't try to modify `this.appSettings` (read-only)
+- Don't use settings for **user data** (use `this.weaveAPI.appData` instead)
+- Don't use settings for **temporary state** (use `this.state` instead)
+- Don't forget to **parse** non-string values
+- Don't use generic key names like `url`, `key`, `value`
+
+### Troubleshooting
+
+**Settings are undefined:**
+```typescript
+// Problem: this.appSettings is undefined
+console.log(this.appSettings); // undefined
+
+// Solution: Admin hasn't configured settings yet
+// Always provide defaults:
+const apiUrl = this.appSettings?.apiUrl || 'https://default.com';
+```
+
+**Settings not updating:**
+```typescript
+// Problem: Changed settings in admin console but app still uses old values
+// Solution: Reload sidebar (settings are loaded on sidebar initialization)
+// Users need to refresh the page or reload the extension
+```
+
+**Type conversion issues:**
+```typescript
+// Problem: Setting is string but need number
+const timeout = this.appSettings?.timeout; // "5000" (string)
+setTimeout(() => {}, timeout); // Wrong! Expects number
+
+// Solution: Parse to number
+const timeout = parseInt(this.appSettings?.timeout || '5000');
+setTimeout(() => {}, timeout); // Correct!
+```
+
+### Summary
+
+- **App Settings** = Admin-configured key-value pairs (strings)
+- **Automatically injected** by BackgroundAppManager before app runs
+- **Available everywhere** via `this.appSettings`
+- **Read-only** in apps (admin controls values)
+- **Perfect for configuration** (URLs, keys, flags, limits)
+- **Always provide defaults** to handle missing settings
+- **Parse values** for non-string types (numbers, booleans, JSON)
+
+## Background Services & URL Change Detection
+
+### Overview
+
+Apps run as **single instances** that serve both background and foreground purposes. When the sidebar loads, all apps are instantiated immediately and can run background tasks **before** being attached to the DOM. This enables powerful use cases like:
+
+- 🔧 **Auto-inject UI elements** based on URL patterns
+- 🔄 **React to SPA navigation** without page reload
+- 💾 **Maintain persistent state** across open/close cycles
+- 🎯 **Monitor page changes** and trigger actions
+- 🤖 **Run background logic** without user interaction
+
+### App Lifecycle
+
+```
+Sidebar loads
+    ↓
+Apps instantiated (in memory, not attached to DOM)
+    ↓
+onBackgroundService() called ← Background tasks start
+    ↓
+App runs in background...
+    ↓
+User clicks app → Attach to DOM → render() called
+    ↓
+User closes app → Detach from DOM
+    ↓
+Background continues running with same state
+```
+
+### Background Service Method
+
+#### `onBackgroundService(): void` (Optional)
+
+Called **immediately** after app instantiation, before DOM attachment. Use this for:
+- Injecting UI elements onto the page
+- Setting up event listeners on the parent page
+- Monitoring page state
+- Running background logic
+
+**Important:** This method runs even when the app is not open in the drawer.
+
+```typescript
+class AutoButtonInjector extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'auto-button-injector',
+      name: 'Auto Button Injector',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Automatically injects buttons based on URL',
+      tags: ['automation']
+    });
+    
+    this.state = {
+      buttonInjected: false,
+      clickCount: 0
+    };
+  }
+
+  // 🔧 Background service - runs immediately
+  async onBackgroundService() {
+    console.log('🔧 Background service started');
+    
+    // Get the actual page URL (not iframe URL)
+    const pageUrl = await weaveDOM.getPageUrl();
+    console.log('Current page:', pageUrl);
+    
+    // Check current URL and inject if needed
+    this.checkAndInject(pageUrl);
+  }
+
+  async checkAndInject(url) {
+    // Define your URL pattern
+    const shouldInject = url.includes('/dashboard');
+    
+    if (shouldInject && !this.state.buttonInjected) {
+      // Inject button with onClick listener using injectElement
+      const buttonId = await weaveDOM.injectElement(
+        'body',
+        'beforeend',
+        '<button style="position: fixed; top: 10px; right: 10px; z-index: 9999; padding: 10px 20px; background: #4f46e5; color: white; border: none; border-radius: 6px; cursor: pointer; font-family: system-ui;">🚀 Quick Action</button>',
+        {
+          onClick: (data) => {
+            // This callback fires when the button is clicked!
+            this.state.clickCount++;
+            console.log(`Button clicked! Total clicks: ${this.state.clickCount}`);
+            console.log('Click position:', data.event.clientX, data.event.clientY);
+            
+            // Update UI if app is open
+            if (this.isConnected) {
+              this.render();
+            }
+            
+            // You can do anything here:
+            // - Call an API
+            // - Show a notification
+            // - Trigger other actions
+          }
+        }
+      );
+      
+      this.state.buttonInjected = buttonId;
+      console.log('✅ Button injected with click listener');
+      
+      // Update UI if app is open
+      if (this.isConnected) {
+        this.render();
+      }
+    } else if (!shouldInject && this.state.buttonInjected) {
+      // Remove button when URL doesn't match
+      await weaveDOM.removeInjectedElement(this.state.buttonInjected);
+      this.state.buttonInjected = false;
+      console.log('❌ Button removed');
+      
+      // Update UI if app is open
+      if (this.isConnected) {
+        this.render();
+      }
+    }
+  }
+
+  // 🎨 Foreground - renders when user opens app
+  render() {
+    this.renderHTML(`
+      <style>
+        .status { padding: 20px; font-family: system-ui; }
+        .status p { margin: 10px 0; }
+        .status strong { color: #4f46e5; }
+      </style>
+      <div class="status">
+        <h2>Background Service Status</h2>
+        <p>Button injected: <strong>${this.state.buttonInjected ? 'Yes' : 'No'}</strong></p>
+        <p>Click count: <strong>${this.state.clickCount}</strong></p>
+        <p><em>Navigate to /dashboard to see button injection</em></p>
+      </div>
+    `);
+  }
+}
+
+customElements.define('auto-button-injector', AutoButtonInjector);
+```
+
+### URL Change Detection
+
+#### `onUrlChange(url: string): void` (Optional)
+
+Called when the page URL changes (SPA navigation). This detects:
+- `history.pushState()` - SPA route changes
+- `history.replaceState()` - SPA route replacements
+- `popstate` events - Back/forward button navigation
+- `hashchange` events - Hash changes
+
+**Use cases:**
+- React to navigation in single-page applications
+- Inject/remove UI elements based on current route
+- Track user navigation patterns
+- Trigger actions on specific pages
+
+```typescript
+class SmartNavigationHelper extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'smart-nav-helper',
+      name: 'Smart Navigation Helper',
+      version: '1.0.0',
+      category: 'productivity',
+      description: 'Provides contextual help based on current page',
+      tags: ['navigation', 'help']
+    });
+    
+    this.state = {
+      currentPage: '',
+      helpBubbleId: null
+    };
+  }
+
+  async onBackgroundService() {
+    console.log('🔧 Navigation helper started');
+    const pageUrl = await weaveDOM.getPageUrl();
+    this.handlePageChange(pageUrl);
+  }
+
+  // 🔄 Called on every URL change (SPA navigation)
+  onUrlChange(newUrl) {
+    console.log('🔄 URL changed to:', newUrl);
+    this.handlePageChange(newUrl);
+  }
+
+  handlePageChange(url) {
+    // Remove old help bubble if exists
+    if (this.state.helpBubbleId) {
+      weaveDOM.removeElement(`#${this.state.helpBubbleId}`);
+      this.state.helpBubbleId = null;
+    }
+
+    // Determine page type
+    let pageType = 'unknown';
+    let helpText = '';
+    
+    if (url.includes('/dashboard')) {
+      pageType = 'dashboard';
+      helpText = '📊 Dashboard: View your analytics and metrics';
+    } else if (url.includes('/settings')) {
+      pageType = 'settings';
+      helpText = '⚙️ Settings: Configure your preferences';
+    } else if (url.includes('/profile')) {
+      pageType = 'profile';
+      helpText = '👤 Profile: Manage your account information';
+    }
+
+    this.state.currentPage = pageType;
+
+    // Inject contextual help if we have help text
+    if (helpText) {
+      const helpHTML = `
+        <div id="weave-help-bubble" style="
+          position: fixed;
+          bottom: 20px;
+          left: 20px;
+          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+          color: white;
+          padding: 15px 20px;
+          border-radius: 10px;
+          box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+          z-index: 9999;
+          max-width: 300px;
+          font-family: system-ui;
+          font-size: 14px;
+        ">${helpText}</div>
+      `;
+      
+      weaveDOM.insertHTML('body', helpHTML, 'beforeend');
+      this.state.helpBubbleId = 'weave-help-bubble';
+    }
+
+    // Update UI if app is open
+    if (this.isConnected) {
+      this.render();
+    }
+  }
+
+  render() {
+    this.renderHTML(`
+      <style>
+        .nav-status { padding: 20px; font-family: system-ui; }
+        .page-badge {
+          display: inline-block;
+          padding: 5px 10px;
+          background: #4f46e5;
+          color: white;
+          border-radius: 4px;
+          font-size: 12px;
+          font-weight: 600;
+        }
+      </style>
+      <div class="nav-status">
+        <h2>Navigation Helper</h2>
+        <p>Current page: <span class="page-badge">${this.state.currentPage}</span></p>
+        <p>Help bubble: ${this.state.helpBubbleId ? '✅ Active' : '❌ Inactive'}</p>
+        <p><em>Navigate to different pages to see contextual help</em></p>
+      </div>
+    `);
+  }
+}
+
+customElements.define('smart-nav-helper', SmartNavigationHelper);
+```
+
+### Shared State Between Background and Foreground
+
+The same app instance serves both background and foreground, so `this.state` is shared:
+
+```typescript
+class SharedStateExample extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'shared-state-example',
+      name: 'Shared State Example',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Demonstrates shared state',
+      tags: ['example']
+    });
+    
+    this.state = {
+      backgroundClicks: 0,
+      foregroundClicks: 0
+    };
+  }
+
+  // Background: Inject button and track clicks
+  onBackgroundService() {
+    const buttonHTML = `
+      <button id="bg-button" style="position: fixed; top: 10px; right: 10px; z-index: 9999; padding: 10px; background: #10b981; color: white; border: none; border-radius: 6px; cursor: pointer;">
+        Background Button
+      </button>
+    `;
+    
+    weaveDOM.insertHTML('body', buttonHTML, 'beforeend');
+    
+    // Listen for clicks on injected button
+    // Note: You'd typically use injectElement with onClick callback
+    // This is simplified for demonstration
+  }
+
+  // Foreground: Show state from background
+  render() {
+    this.renderHTML(`
+      <style>
+        .container { padding: 20px; font-family: system-ui; }
+        button { padding: 10px 20px; background: #4f46e5; color: white; border: none; border-radius: 6px; cursor: pointer; margin: 10px 0; }
+      </style>
+      <div class="container">
+        <h2>Shared State Demo</h2>
+        <p>Background clicks: <strong>${this.state.backgroundClicks}</strong></p>
+        <p>Foreground clicks: <strong>${this.state.foregroundClicks}</strong></p>
+        <button id="fg-button">Click Me (Foreground)</button>
+        <p><em>State is shared between background and foreground!</em></p>
+      </div>
+    `);
+  }
+
+  setupEventListeners() {
+    this.query('#fg-button')?.addEventListener('click', () => {
+      this.state.foregroundClicks++;
+      this.render(); // Re-render to show updated count
+    });
+  }
+}
+
+customElements.define('shared-state-example', SharedStateExample);
+```
+
+### Checking if App is Attached to DOM
+
+Use `this.isConnected` to check if the app is currently attached to the DOM (visible in drawer):
+
+```typescript
+onBackgroundService() {
+  // Background logic runs
+  this.state.data = 'some value';
+  
+  // Only update UI if app is currently open
+  if (this.isConnected) {
+    this.render();
+  }
+}
+
+onUrlChange(url) {
+  // Update state
+  this.state.currentUrl = url;
+  
+  // Re-render if app is open
+  if (this.isConnected) {
+    this.render();
+  }
+}
+```
+
+### Best Practices
+
+#### ✅ DO:
+- Use `onBackgroundService()` for auto-injection and monitoring
+- Use `onUrlChange()` to react to SPA navigation
+- Check `this.isConnected` before calling `render()`
+- Clean up injected elements in `cleanup()`
+- Use shared state for communication between background and foreground
+
+#### ❌ DON'T:
+- Don't call `render()` in `onBackgroundService()` (app not attached to DOM yet)
+- Don't assume app is always open when background logic runs
+- Don't forget to remove injected elements when no longer needed
+- Don't inject elements without checking if they already exist
+
+### Complete Example: Smart Form Assistant
+
+```typescript
+class SmartFormAssistant extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'smart-form-assistant',
+      name: 'Smart Form Assistant',
+      version: '1.0.0',
+      category: 'productivity',
+      description: 'Automatically detects forms and offers AI-powered assistance',
+      tags: ['forms', 'ai', 'automation']
+    });
+    
+    this.state = {
+      formsDetected: 0,
+      currentUrl: '',
+      assistButtonInjected: false
+    };
+  }
+
+  // 🔧 Background: Start monitoring
+  async onBackgroundService() {
+    console.log('🔧 Form assistant started');
+    const pageUrl = await weaveDOM.getPageUrl();
+    this.checkForForms(pageUrl);
+  }
+
+  // 🔄 URL changes: Re-check for forms
+  onUrlChange(newUrl) {
+    console.log('🔄 URL changed, checking for forms');
+    this.state.currentUrl = newUrl;
+    this.checkForForms(newUrl);
+  }
+
+  async checkForForms(url) {
+    // Remove old assist button if exists
+    if (this.state.assistButtonInjected) {
+      await weaveDOM.removeElement('#form-assist-btn');
+      this.state.assistButtonInjected = false;
+    }
+
+    // Query for forms on the page
+    try {
+      const forms = await weaveDOM.queryAll('form');
+      this.state.formsDetected = forms.length;
+
+      // If forms exist, inject assist button
+      if (forms.length > 0) {
+        const buttonHTML = `
+          <button id="form-assist-btn" style="
+            position: fixed;
+            bottom: 20px;
+            right: 20px;
+            padding: 15px 25px;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            border: none;
+            border-radius: 8px;
+            box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+            cursor: pointer;
+            font-size: 16px;
+            font-weight: 600;
+            z-index: 9999;
+          ">🤖 AI Form Help</button>
+        `;
+
+        await weaveDOM.insertHTML('body', buttonHTML, 'beforeend');
+        this.state.assistButtonInjected = true;
+        console.log('✅ Form assist button injected');
+      }
+
+      // Update UI if app is open
+      if (this.isConnected) {
+        this.render();
+      }
+    } catch (error) {
+      console.error('Error checking for forms:', error);
+    }
+  }
+
+  // 🎨 Foreground: Show status
+  render() {
+    this.renderHTML(`
+      <style>
+        .container { padding: 20px; font-family: system-ui; }
+        .stat { margin: 15px 0; }
+        .stat strong { color: #4f46e5; }
+        .badge {
+          display: inline-block;
+          padding: 5px 10px;
+          background: #10b981;
+          color: white;
+          border-radius: 4px;
+          font-size: 12px;
+          font-weight: 600;
+        }
+      </style>
+      <div class="container">
+        <h2>Smart Form Assistant</h2>
+        <div class="stat">
+          <p>Forms detected: <strong>${this.state.formsDetected}</strong></p>
+        </div>
+        <div class="stat">
+          <p>Assist button: ${this.state.assistButtonInjected ? '<span class="badge">Active</span>' : '<span style="color: #6b7280;">Inactive</span>'}</p>
+        </div>
+        <div class="stat">
+          <p>Current URL: <code style="font-size: 12px; color: #6b7280;">${this.state.currentUrl}</code></p>
+        </div>
+        <p style="margin-top: 20px; color: #6b7280; font-size: 14px;">
+          <em>Navigate to pages with forms to see the AI assist button</em>
+        </p>
+      </div>
+    `);
+  }
+
+  // 🧹 Cleanup: Remove injected elements
+  async cleanup() {
+    if (this.state.assistButtonInjected) {
+      await weaveDOM.removeElement('#form-assist-btn');
+    }
+  }
+}
+
+customElements.define('smart-form-assistant', SmartFormAssistant);
+```
+
+### Key Takeaways
+
+1. **Single Instance Architecture**: One app instance serves both background and foreground
+2. **Persistent State**: `this.state` persists across open/close cycles
+3. **Background Service**: `onBackgroundService()` runs immediately, before DOM attachment
+4. **URL Monitoring**: `onUrlChange()` detects SPA navigation automatically
+5. **Shared Context**: Background and foreground share the same instance and state
+6. **DOM Check**: Use `this.isConnected` to check if app is attached to DOM
+7. **No User Interaction Required**: Apps can run and inject UI automatically
+
+### Helper Methods (Available in `this`)
+
+```typescript
+// Render HTML into shadow root
+this.renderHTML(html: string): void
+
+// Query single element in shadow root
+this.query<T>(selector: string): T | null
+
+// Query all elements in shadow root
+this.queryAll<T>(selector: string): NodeListOf<T>
+
+// Update app state
+this.setState(updates: object): void
+
+// Access current state
+this.state: Record<string, any>
+
+// Access app metadata
+this.appInfo: WeaveAppInfo
+
+// Access shadow root
+this.shadowRoot: ShadowRoot
+```
+
+## Weave Backend API
+
+### ⚠️ CRITICAL: API Access Restrictions
+
+Apps **CANNOT** make arbitrary HTTP requests to external APIs. Apps can **ONLY** interact with:
+
+1. **Weave Backend API** via `window.weaveAPI` (AI, data storage)
+2. **Parent Page DOM** via `window.weaveDOM` (read/write page elements)
+
+❌ **BLOCKED:**
+```typescript
+// ❌ WRONG - Cannot make arbitrary API calls
+await fetch('https://api.example.com/data');
+await axios.get('https://some-api.com');
+```
+
+✅ **ALLOWED:**
+```typescript
+// ✅ CORRECT - Use Weave API
+await weaveAPI.ai.chat({ appName: 'my-app', prompt: '...' });
+await weaveAPI.appData.create({ appId: 'my-app', dataKey: 'key', data: {} });
+
+// ✅ CORRECT - Use DOM Bridge
+await weaveDOM.getText('h1');
+```
+
+### Weave API Client
+
+Access Weave backend services via `window.weaveAPI`:
+
+```typescript
+// Available globally at runtime
+const weaveAPI = window.weaveAPI;
+```
+
+### ⚠️ CRITICAL: App-Specific API Client (`this.weaveAPI`)
+
+**IMPORTANT:** Each app instance has its own dedicated API client accessible via `this.weaveAPI`. This ensures that API calls are made with the correct app ID, especially critical for background services.
+
+#### Why Use `this.weaveAPI`?
+
+When multiple apps run simultaneously (especially as background services), using the global `window.weaveAPI` can cause **app ID conflicts**. Each app needs its own API client instance to ensure data is saved/loaded with the correct app ID.
+
+#### ✅ CORRECT: Use `this.weaveAPI`
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async saveData() {
+    // ✅ CORRECT - Uses app-specific API client
+    const data = await this.weaveAPI.appData.create({
+      dataKey: 'my-data',
+      data: { value: 'hello' }
+    });
+  }
+  
+  async loadData() {
+    // ✅ CORRECT - Uses app-specific API client
+    const response = await this.weaveAPI.appData.getAll();
+    const allData = response.data;
+    return allData.find(d => d.dataKey === 'my-data');
+  }
+  
+  async askAI() {
+    // ✅ CORRECT - Uses app-specific API client
+    const response = await this.weaveAPI.ai.chat({
+      prompt: 'Hello AI',
+      context: 'User greeting'
+    });
+    return response.response;
+  }
+}
+```
+
+#### ❌ WRONG: Using Global `window.weaveAPI`
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async saveData() {
+    // ❌ WRONG - May use wrong app ID if multiple apps are running
+    const data = await window.weaveAPI.appData.create({
+      dataKey: 'my-data',
+      data: { value: 'hello' }
+    });
+  }
+}
+```
+
+#### Context Preservation in Async Methods
+
+When using `await` with `this.weaveAPI`, the context can be lost in certain scenarios (especially in callbacks). To prevent this, **capture the API client reference in a local variable**:
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async saveContent(content: string) {
+    try {
+      // ✅ CORRECT - Capture reference to avoid context loss
+      const apiClient = this.weaveAPI;
+      
+      // Now use apiClient consistently
+      const response = await apiClient.appData.getAll();
+      const allData = response.data;
+      const existing = allData.find(d => d.dataKey === 'content');
+      
+      if (existing) {
+        await apiClient.appData.update(existing._id, {
+          data: { content }
+        });
+      } else {
+        await apiClient.appData.create({
+          dataKey: 'content',
+          data: { content }
+        });
+      }
+    } catch (error) {
+      console.error('Save failed:', error);
+    }
+  }
+}
+```
+
+#### Context Preservation in Callbacks
+
+When using callbacks (e.g., button click handlers via DOM Bridge), capture both `this` and the API client:
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async injectButton() {
+    // ✅ CORRECT - Capture 'this' reference for callback
+    const self = this;
+    
+    const buttonId = await window.weaveDOM.injectElement(
+      'body',
+      'beforeend',
+      '<button>Save Data</button>',
+      {
+        onClick: async () => {
+          // Use captured 'self' reference
+          const apiClient = self.weaveAPI;
+          
+          await apiClient.appData.create({
+            dataKey: 'clicked',
+            data: { timestamp: Date.now() }
+          });
+          
+          // Update UI if app is open
+          if (self.isConnected) {
+            self.render();
+          }
+        }
+      }
+    );
+  }
+}
+```
+
+#### Key Rules for API Client Usage
+
+1. **Always use `this.weaveAPI`** instead of `window.weaveAPI`
+2. **Capture in local variable** when using multiple `await` calls: `const apiClient = this.weaveAPI;`
+3. **Capture `this` in callbacks** using `const self = this;` before async callbacks
+4. **Use captured references** consistently throughout the method
+5. **Never mix** `this.weaveAPI` and `window.weaveAPI` in the same app
+
+#### How It Works
+
+When your app is instantiated, `WeaveBaseApp` automatically:
+1. Creates a dedicated `WeaveAPIClient` instance for your app
+2. Sets the correct app UUID on this instance
+3. Assigns it to `this.weaveAPI`
+
+This ensures all API calls from your app include the correct app ID, preventing data from being saved to the wrong app.
+
+### AI Service
+
+Call the Weave AI service to get intelligent responses:
+
+**Note:** Your app's UUID is automatically included. Always use `this.weaveAPI` in your app methods.
+
+```typescript
+import { type AIChatRequest, type AIChatResponse } from '@weave/app-sdk';
+
+class MyApp extends WeaveBaseApp {
+  async summarizeText(text: string) {
+    // ✅ Use this.weaveAPI (app-specific client)
+    const request: AIChatRequest = {
+      prompt: `Summarize this text: ${text}`,
+      context: 'User is reading an article',
+      disableJsonExtraction: false
+    };
+
+    const response: AIChatResponse = await this.weaveAPI.ai.chat(request);
+    return response.response;  // AI's response text
+  }
+}
+```
+
+**Example Use Cases:**
+- Summarize page content
+- Answer questions about data
+- Generate suggestions
+- Analyze text
+- Extract information
+
+### App Data Service
+
+Store and retrieve app-specific data in the Weave backend:
+
+```typescript
+import { 
+  type AppData, 
+  type CreateAppDataRequest, 
+  type UpdateAppDataRequest,
+  type PaginatedResponse,
+  type PaginationMeta
+} from '@weave/app-sdk';
+```
+
+#### Create Data
+
+**Note:** Your app's UUID is automatically included. Always use `this.weaveAPI`.
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async savePreferences(theme: string, language: string) {
+    // ✅ Use this.weaveAPI (app-specific client)
+    const request: CreateAppDataRequest = {
+      dataKey: 'user-preferences',
+      data: {
+        theme,
+        language,
+        notifications: true
+      }
+    };
+
+    const saved: AppData = await this.weaveAPI.appData.create(request);
+    console.log('Created with ID:', saved._id);
+    return saved;
+  }
+}
+```
+
+#### Get All Data (Paginated)
+
+**Important:** The API returns paginated responses to handle large datasets efficiently (500-5000+ rows).
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async loadPreferences() {
+    // ✅ Use this.weaveAPI (app-specific client)
+    // Get all data for your app (scoped to current company/user)
+    // Returns: { data: AppData[], meta: { offset, limit, totalResultCount } }
+    const response: PaginatedResponse<AppData> = await this.weaveAPI.appData.getAll();
+    
+    // Access the array of items from response.data
+    const allData = response.data;
+    
+    // Check pagination metadata
+    console.log('Total items:', response.meta.totalResultCount);
+    console.log('Current page limit:', response.meta.limit);
+    console.log('Current offset:', response.meta.offset);
+
+    // Find specific data by key
+    const prefs = allData.find(d => d.dataKey === 'user-preferences');
+    return prefs?.data;
+  }
+}
+```
+
+**Pagination Details:**
+- **Default limit:** 25 items per page
+- **Response structure:** `{ data: AppData[], meta: PaginationMeta }`
+- **Why paginated:** Apps can store 500-5000+ rows of data. Pagination prevents performance issues and reduces memory usage.
+- **Access data:** Always use `response.data` to get the array of items
+
+#### Get Specific Data
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async getDataById(id: string) {
+    // ✅ Use this.weaveAPI (app-specific client)
+    const data: AppData = await this.weaveAPI.appData.get(id);
+    return data.data;  // Your stored data object
+  }
+}
+```
+
+#### Update Data
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async updateTheme(id: string, theme: string) {
+    // ✅ Use this.weaveAPI (app-specific client)
+    const updates: UpdateAppDataRequest = {
+      data: {
+        theme  // Partial or full update
+      }
+    };
+
+    const updated: AppData = await this.weaveAPI.appData.update(id, updates);
+    return updated;
+  }
+}
+```
+
+#### Delete Data
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async deleteData(id: string) {
+    // ✅ Use this.weaveAPI (app-specific client)
+    await this.weaveAPI.appData.delete(id);
+  }
+}
+```
+
+### AppData Structure
+
+```typescript
+interface AppData {
+  _id: string;           // Unique ID
+  appId: string;         // Your app's ID
+  companyId: string;     // Auto-injected (user's company)
+  userId: string;        // Auto-injected (current user)
+  dataKey: string;       // Your organization key
+  data: Record<string, any>;  // Your data (any structure)
+  createdAt: Date;
+  updatedAt: Date;
+  createdBy: string;
+}
+```
+
+### API Error Handling
+
+All API methods return promises. Always use try-catch:
+
+```typescript
+try {
+  const response = await weaveAPI.ai.chat({
+    appName: 'my-app',
+    prompt: 'Hello'
+  });
+  console.log(response.response);
+} catch (error) {
+  console.error('API call failed:', error.message);
+  // Show user-friendly error message
+}
+```
+
+### API Timeouts
+
+- All API requests timeout after **30 seconds**
+- Requests will reject with timeout error if exceeded
+
+### Security & Scoping
+
+- **Authentication**: Automatic (uses current user's session)
+- **Company Scoping**: Data is automatically scoped to user's company
+- **User Scoping**: Each user sees only their own data
+- **App Scoping**: Apps can only access their own data (via `appId`)
+
+## Parent Page DOM Interaction
+
+### DOMBridge API
+
+Access parent page DOM via `window.weaveDOM`:
+
+```typescript
+// All methods return Promises
+const weaveDOM = window.weaveDOM;
+```
+
+### Read Operations
+
+```typescript
+// Query element (returns serialized snapshot)
+const element = await weaveDOM.query('h1');
+// Returns: { tagName, id, className, textContent, attributes, exists }
+
+// Query all elements
+const elements = await weaveDOM.queryAll('.item');
+// Returns: Array of element snapshots
+
+// Get text content
+const text = await weaveDOM.getText('h1');
+// Returns: string
+
+// Get attribute value
+const href = await weaveDOM.getAttribute('a', 'href');
+// Returns: string | null
+
+// Get input/textarea value
+const value = await weaveDOM.getValue('input[name="email"]');
+// Returns: string
+
+// Check if element has class
+const hasClass = await weaveDOM.hasClass('.button', 'active');
+// Returns: boolean
+
+// Get current page URL
+const pageUrl = await weaveDOM.getPageUrl();
+// Returns: string (e.g., 'https://example.com/dashboard')
+```
+
+**Important:** Apps run in an iframe, so `window.location.href` returns the iframe URL, not the parent page URL. Use `weaveDOM.getPageUrl()` to get the actual page URL.
+
+### Write Operations
+
+```typescript
+// Set text content
+await weaveDOM.setText('h1', 'New Title');
+
+// Set attribute
+await weaveDOM.setAttribute('input', 'placeholder', 'Enter text');
+
+// Set input/textarea value
+await weaveDOM.setValue('input[name="email"]', 'user@example.com');
+
+// Add CSS class
+await weaveDOM.addClass('.button', 'active');
+
+// Remove CSS class
+await weaveDOM.removeClass('.button', 'active');
+
+// Toggle CSS class
+await weaveDOM.toggleClass('.button', 'active');
+
+// Set inline style
+await weaveDOM.setStyle('h1', 'color', 'red');
+await weaveDOM.setStyle('h1', 'font-size', '24px');
+```
+
+### DOM Manipulation
+
+```typescript
+// Insert HTML
+await weaveDOM.insertHTML(
+  '.container',           // Target selector
+  '<p>New content</p>',   // HTML to insert
+  'beforeend'             // Position: beforebegin | afterbegin | beforeend | afterend
+);
+
+// Remove element
+await weaveDOM.removeElement('.old-element');
+
+// Click an element
+await weaveDOM.clickElement('button#submit');
+await weaveDOM.clickElement('a.nav-item[href="/dashboard"]');
+await weaveDOM.clickElement('.custom-button');
+```
+
+**Click Element Use Cases:**
+- Trigger button clicks programmatically
+- Navigate by clicking links
+- Activate UI controls (tabs, toggles, etc.)
+- Automate user interactions
+- Trigger form submissions
+
+**Example - Auto-click a button after form fill:**
+```typescript
+// Fill form fields
+await weaveDOM.setFormFieldValue('input[name="email"]', 'user@example.com');
+await weaveDOM.setFormFieldValue('input[name="password"]', 'password123');
+
+// Click the submit button
+await weaveDOM.clickElement('button[type="submit"]');
+```
+
+### Form Detection & Auto-Fill
+
+The DOM Bridge provides powerful form interaction capabilities for detecting form clicks and automatically filling form fields.
+
+#### Form Click Detection
+
+Listen for clicks on form elements and receive complete form data:
+
+```typescript
+// Start listening for form clicks
+await weaveDOM.startFormClickListener((data) => {
+  console.log('Form clicked!', data);
+  
+  // Access form metadata
+  const formData = data.formData;
+  console.log('Form ID:', formData.formId);
+  console.log('Form Name:', formData.formName);
+  console.log('Form Action:', formData.formAction);
+  console.log('Form Method:', formData.formMethod);
+  
+  // Access all form fields
+  formData.fields.forEach(field => {
+    console.log(`Field: ${field.name} (${field.type})`);
+    console.log(`  Label: ${field.label}`);
+    console.log(`  Value: ${field.value}`);
+    console.log(`  Required: ${field.required}`);
+  });
+  
+  // Access clicked element info
+  console.log('Clicked:', data.clickedElement.tagName);
+  console.log('Type:', data.clickedElement.type);
+});
+
+// Stop listening when done
+await weaveDOM.stopFormClickListener();
+```
+
+**Callback Data Structure:**
+```typescript
+{
+  formData: {
+    formId: string;           // Form's ID attribute
+    formName: string;         // Form's name attribute
+    formAction: string;       // Form's action URL
+    formMethod: string;       // Form's method (get/post)
+    fields: FormFieldData[];  // All form fields
+  },
+  clickedElement: {
+    tagName: string;          // Element tag (input, select, etc.)
+    name: string;             // Element name attribute
+    id: string;               // Element ID
+    type: string;             // Input type (text, email, etc.)
+  }
+}
+```
+
+**Form Field Data:**
+```typescript
+interface FormFieldData {
+  name: string;               // Field name attribute
+  id: string;                 // Field ID attribute
+  type: string;               // Input type (text, email, checkbox, toggleButtonGroup, etc.)
+  value: string | string[];   // Current value(s)
+  label: string;              // Associated label text
+  placeholder: string;        // Placeholder text
+  required: boolean;          // Is field required?
+  disabled: boolean;          // Is field disabled?
+  readonly: boolean;          // Is field readonly?
+  pattern: string;            // Validation pattern
+  min: string;                // Min value (numbers/dates)
+  max: string;                // Max value (numbers/dates)
+  minLength: number;          // Min length
+  maxLength: number;          // Max length
+  checked?: boolean;          // For checkboxes/radios
+  options?: Array<{           // For select elements
+    value: string;
+    text: string;
+    selected: boolean;
+  }>;
+  buttons?: Array<{           // For toggle button groups (MUI, etc.)
+    value: string;
+    text: string;
+    selected: boolean;
+    id: string;
+  }>;
+}
+```
+
+#### Manual Form Data Retrieval
+
+Get form data without waiting for a click:
+
+```typescript
+// Get data from a specific form
+const formData = await weaveDOM.getFormData('#login-form');
+
+// Get data from a form containing a specific input
+const formData = await weaveDOM.getFormData('input[name="email"]');
+```
+
+#### Auto-Fill Form Fields
+
+Set form field values programmatically. Automatically triggers validation events (`input`, `change`, `blur`):
+
+```typescript
+// Text inputs
+await weaveDOM.setFormFieldValue('input[name="email"]', 'user@example.com');
+await weaveDOM.setFormFieldValue('#username', 'johndoe');
+
+// Number inputs
+await weaveDOM.setFormFieldValue('input[name="age"]', '25');
+
+// Checkboxes (use boolean)
+await weaveDOM.setFormFieldValue('input[name="terms"]', true);
+await weaveDOM.setFormFieldValue('input[name="newsletter"]', false);
+
+// Radio buttons (use the value of the radio to select)
+await weaveDOM.setFormFieldValue('input[name="gender"][value="female"]', 'female');
+
+// Select dropdowns
+await weaveDOM.setFormFieldValue('select[name="country"]', 'US');
+
+// Multi-select (use array)
+await weaveDOM.setFormFieldValue('select[name="interests"]', ['sports', 'music']);
+
+// Textareas
+await weaveDOM.setFormFieldValue('textarea[name="bio"]', 'This is my bio...');
+
+// Date inputs
+await weaveDOM.setFormFieldValue('input[name="birthdate"]', '1990-01-15');
+
+// Toggle button groups (MUI, Ant Design, etc.)
+await weaveDOM.setFormFieldValue('#other_creators_involved', 'true');
+
+// For IDs with dots, use attribute selector instead of escaping
+await weaveDOM.setFormFieldValue('[id="dependency_level.level"]', 'High');
+```
+
+**Supported Field Types:**
+- Text inputs: `text`, `email`, `password`, `tel`, `url`, `search`
+- Number inputs: `number`, `range`
+- Date/time inputs: `date`, `datetime-local`, `time`, `month`, `week`
+- Checkboxes: `checkbox` (use boolean values)
+- Radio buttons: `radio` (use string value to select)
+- Select elements: single and multi-select
+- Textareas
+- **Toggle button groups**: `toggleButtonGroup` (MUI ToggleButtonGroup, custom button groups)
+
+**Event Triggering:**
+The `setFormFieldValue` method automatically triggers these events to ensure page validation runs:
+- `input` event
+- `change` event
+- `blur` event
+- `InputEvent` (for modern frameworks)
+- **Button clicks** (for toggle button groups)
+
+**Visual Feedback with Scroll Into View:**
+
+The `setFormFieldValue` method accepts an optional third parameter `scrollIntoView` that scrolls the element to the center of the viewport before setting its value. This provides visual feedback to users, showing them what's being filled in real-time.
+
+```typescript
+// Scroll element to center before filling (great for AI form filling)
+await weaveDOM.setFormFieldValue('input[name="email"]', 'user@example.com', true);
+
+// Scroll checkbox into view before checking it
+await weaveDOM.setFormFieldValue('input[name="terms"]', true, true);
+
+// Default behavior - no scroll (backward compatible)
+await weaveDOM.setFormFieldValue('input[name="username"]', 'johndoe');
+```
+
+**How it works:**
+1. When `scrollIntoView: true` is passed, the element scrolls to the **center** of the viewport (not top)
+2. Uses smooth animation for better UX
+3. Waits 300ms for scroll animation to complete
+4. Then sets the field value and triggers events
+
+**Use cases:**
+- **AI form filling** - Show users what fields are being filled as the AI works
+- **Long forms** - Ensure each field is visible as it's being filled
+- **User guidance** - Draw attention to specific fields being auto-filled
+- **Debugging** - Visually verify which fields are being set
+
+```typescript
+// Example: Fill form with visual feedback
+async function fillFormWithVisualFeedback(formData, values) {
+  for (const field of formData.fields) {
+    const selector = field.id ? `#${field.id}` : `[name="${field.name}"]`;
+    const value = values[field.name];
+    
+    if (value !== undefined) {
+      // Scroll to show user what's being filled
+      await weaveDOM.setFormFieldValue(selector, value, true);
+      
+      // Optional: small delay between fields for better UX
+      await new Promise(resolve => setTimeout(resolve, 200));
+    }
+  }
+}
+```
+
+#### Complete Example: AI Form Filler
+
+```typescript
+class AIFormFiller extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'ai-form-filler',
+      name: 'AI Form Filler',
+      version: '1.0.0',
+      category: 'productivity',
+      description: 'Automatically fills forms using AI',
+      tags: ['forms', 'ai', 'automation']
+    });
+    
+    this.state = {
+      formData: null,
+      filling: false
+    };
+  }
+  
+  async connectedCallback() {
+    super.connectedCallback();
+    
+    // Listen for form clicks
+    await window.weaveDOM.startFormClickListener(async (data) => {
+      this.state.formData = data.formData;
+      this.render();
+      
+      // Automatically fill the form
+      await this.fillFormWithAI(data.formData);
+    });
+  }
+  
+  async disconnectedCallback() {
+    super.disconnectedCallback();
+    await window.weaveDOM.stopFormClickListener();
+  }
+  
+  async fillFormWithAI(formData) {
+    this.state.filling = true;
+    this.render();
+    
+    try {
+      // Get AI-generated values for each field
+      const aiValues = await this.getAIValues(formData);
+      
+      // Fill each field with visual feedback
+      for (const field of formData.fields) {
+        if (aiValues[field.name]) {
+          // Construct selector from field ID or name
+          const selector = field.id 
+            ? `#${field.id}` 
+            : `[name="${field.name}"]`;
+          
+          // Set the value with scroll for visual feedback
+          await window.weaveDOM.setFormFieldValue(
+            selector, 
+            aiValues[field.name],
+            true  // Scroll into view so user can see what's being filled
+          );
+          
+          // Optional: small delay between fields for better UX
+          await new Promise(resolve => setTimeout(resolve, 200));
+        }
+      }
+      
+      this.showSuccess('Form filled successfully!');
+    } catch (error) {
+      this.showError(`Error: ${error.message}`);
+    } finally {
+      this.state.filling = false;
+      this.render();
+    }
+  }
+  
+  async getAIValues(formData) {
+    // Use Weave AI to generate form values
+    const prompt = `Generate appropriate values for this form:
+      ${JSON.stringify(formData.fields.map(f => ({
+        name: f.name,
+        type: f.type,
+        label: f.label,
+        required: f.required
+      })))}`;
+    
+    const response = await window.weaveAPI.ai.chat({
+      prompt,
+      context: 'Filling form fields with appropriate test data'
+    });
+    
+    // Parse AI response to get field values
+    return JSON.parse(response.response);
+  }
+}
+
+customElements.define('ai-form-filler', AIFormFiller);
+```
+
+#### Use Cases
+
+**AI-Powered Autofill:**
+- User clicks a form field
+- App sends form structure to AI
+- AI generates appropriate values
+- App fills all fields automatically
+
+**Form Validation Helper:**
+- Detect form interactions
+- Validate fields in real-time
+- Show helpful suggestions
+- Auto-correct common mistakes
+
+**Data Extraction:**
+- Capture form structures
+- Analyze form patterns
+- Export form data
+- Generate form documentation
+
+**Automated Testing:**
+- Fill forms with test data
+- Verify form behavior
+- Test validation rules
+- Simulate user interactions
+
+#### Toggle Button Groups (MUI & Custom Controls)
+
+Many modern frameworks (Material-UI, Ant Design, etc.) use **button-based form controls** instead of traditional radio buttons or checkboxes. These are automatically detected and extracted by the DOM Bridge.
+
+**What are Toggle Button Groups?**
+
+Toggle button groups are `<div role="group">` containers with multiple `<button type="button">` elements that act like radio buttons. Selection is managed through:
+- `aria-pressed="true"` attribute
+- CSS classes like `Mui-selected`
+- React/framework event handlers
+
+**Example HTML Structure:**
+```html
+<div role="group" id="dependency_level.level" aria-label="dependency_level.level">
+  <button type="button" value="Low" aria-pressed="true" class="Mui-selected">Low</button>
+  <button type="button" value="Medium" aria-pressed="false">Medium</button>
+  <button type="button" value="High" aria-pressed="false">High</button>
+</div>
+```
+
+**Extracted Form Data:**
+```typescript
+{
+  name: "dependency_level.level",
+  type: "toggleButtonGroup",  // Special type for button groups
+  value: "Low",                // Currently selected value
+  label: "Dependency Level",
+  buttons: [                   // All available options
+    { value: "Low", text: "Low", selected: true, id: "dependency_level.level-Low" },
+    { value: "Medium", text: "Medium", selected: false, id: "dependency_level.level-Medium" },
+    { value: "High", text: "High", selected: false, id: "dependency_level.level-High" }
+  ]
+}
+```
+
+**How to Use in Your App:**
+
+1. **Recognize as choice field** - Similar to radio buttons or select dropdowns
+2. **Use `buttons` array** - To see all available options
+3. **Set values by button value** - Use the `value` attribute, not the `text`
+
+```typescript
+// AI analyzes the field
+const field = formData.fields.find(f => f.type === 'toggleButtonGroup');
+
+if (field) {
+  console.log('Available options:', field.buttons.map(b => b.text));
+  // Output: ['Low', 'Medium', 'High']
+  
+  console.log('Current selection:', field.value);
+  // Output: 'Low'
+  
+  // AI decides to select 'High'
+  await weaveDOM.setFormFieldValue(`#${field.id}`, 'High');
+  // This clicks the "High" button, triggering React handlers
+}
+```
+
+**Setting Values:**
+
+When you set a value on a toggle button group, the DOM Bridge:
+1. Finds the group by selector
+2. Searches for the button with matching `value` attribute
+3. **Clicks the button** to trigger framework event handlers
+4. Framework updates UI and state automatically
+
+```typescript
+// Yes/No toggle buttons
+await weaveDOM.setFormFieldValue('#other_creators_involved', 'true');
+
+// Multi-option toggle buttons with dots in ID
+// Use attribute selector for IDs with special characters (dots, colons, etc.)
+await weaveDOM.setFormFieldValue('[id="dependency_level.level"]', 'High');
+```
+
+**Common Patterns:**
+
+```typescript
+// Yes/No questions (boolean-like)
+{
+  type: "toggleButtonGroup",
+  value: "true",  // or "false"
+  buttons: [
+    { value: "true", text: "Yes", selected: false },
+    { value: "false", text: "No", selected: false }
+  ]
+}
+
+// Multiple choice (Low/Medium/High)
+{
+  type: "toggleButtonGroup",
+  value: "Medium",
+  buttons: [
+    { value: "Low", text: "Low", selected: false },
+    { value: "Medium", text: "Medium", selected: true },
+    { value: "High", text: "High", selected: false }
+  ]
+}
+```
+
+**AI Decision Making:**
+
+```typescript
+// AI analyzes user needs and selects appropriate option
+async function fillDependencyLevel(userNeeds, formData) {
+  const field = formData.fields.find(f => f.name === 'dependency_level.level');
+  
+  if (field.type === 'toggleButtonGroup') {
+    // AI sees available options
+    const options = field.buttons.map(b => b.value);
+    // ['Low', 'Medium', 'High']
+    
+    // AI makes decision based on criteria
+    let selectedLevel;
+    if (userNeeds.requiresMedication && userNeeds.noFamilySupport) {
+      selectedLevel = 'High';
+    } else if (userNeeds.requiresPersonalCare) {
+      selectedLevel = 'Medium';
+    } else {
+      selectedLevel = 'Low';
+    }
+    
+    // Set the value (clicks the button)
+    await weaveDOM.setFormFieldValue(`#${field.id}`, selectedLevel);
+  }
+}
+```
+
+**Supported Frameworks:**
+- Material-UI (MUI) - ToggleButtonGroup component
+- Ant Design - Button groups with radio behavior
+- Bootstrap - Button groups with data-toggle
+- Custom implementations - Any `div[role="group"]` with buttons
+
+**Key Points:**
+- ✅ Automatically detected - No special handling needed
+- ✅ Works with React/Vue/Angular - Clicks trigger framework handlers
+- ✅ AI-friendly format - Clear options and values
+- ✅ Same API as other fields - Use `setFormFieldValue()`
+- ⚠️ Use button **values**, not text - "true"/"false" for Yes/No, not "Yes"/"No"
+- ⚠️ **IDs with dots** - Use `[id="field.name"]` attribute selector, not `#field\\.name`
+
+### Error Handling
+
+All DOM operations can fail. Always use try-catch:
+
+```typescript
+try {
+  await weaveDOM.setText('h1', 'New Title');
+} catch (error) {
+  console.error('Failed to update title:', error.message);
+  // Handle error (show user message, etc.)
+}
+```
+
+### Element Injection with Event Listeners
+
+Apps can inject custom HTML elements onto the parent page with click event listeners. This is useful for adding floating buttons, overlays, badges, or any interactive UI elements.
+
+#### `injectElement(targetSelector, position, html, options)`
+
+Injects an element onto the parent page with optional click event listener.
+
+**Parameters:**
+- `targetSelector` (string) - CSS selector for the element to inject relative to
+- `position` (InsertPosition) - Position relative to target: `'beforebegin'`, `'afterbegin'`, `'beforeend'`, `'afterend'`
+- `html` (string) - HTML string to inject (will be sanitized)
+- `options` (object, optional)
+  - `onClick` (function) - Callback function invoked when element is clicked
+  - `elementId` (string) - Custom element ID (auto-generated if not provided)
+
+**Returns:** Promise<string> - The element ID
+
+**Example: Floating Action Button**
+
+```typescript
+class FloatingButtonApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'floating-button-app',
+      name: 'Floating Button',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Adds a floating action button',
+      tags: ['button']
+    });
+    
+    this.state = {
+      buttonId: null,
+      clickCount: 0
+    };
+  }
+
+  async connectedCallback() {
+    super.connectedCallback();
+    await this.injectButton();
+  }
+
+  async injectButton() {
+    const buttonHTML = `
+      <button style="
+        position: fixed;
+        bottom: 20px;
+        right: 20px;
+        width: 60px;
+        height: 60px;
+        border-radius: 50%;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        color: white;
+        border: none;
+        box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+        cursor: pointer;
+        font-size: 24px;
+        z-index: 9999;
+      ">✨</button>
+    `;
+
+    const elementId = await weaveDOM.injectElement(
+      'body',
+      'beforeend',
+      buttonHTML,
+      {
+        onClick: (data) => {
+          this.state.clickCount++;
+          console.log('Button clicked!', data);
+          this.render();
+        }
+      }
+    );
+
+    this.state.buttonId = elementId;
+    this.render();
+  }
+
+  async disconnectedCallback() {
+    // Clean up: remove button when app is closed
+    if (this.state.buttonId) {
+      await weaveDOM.removeInjectedElement(this.state.buttonId);
+    }
+    super.disconnectedCallback();
+  }
+}
+
+customElements.define('floating-button-app', FloatingButtonApp);
+```
+
+#### `removeInjectedElement(elementId)`
+
+Removes an injected element from the parent page.
+
+**Parameters:**
+- `elementId` (string) - ID of the element to remove (returned from `injectElement`)
+
+**Example:**
+```typescript
+await weaveDOM.removeInjectedElement('weave-injected-1');
+```
+
+#### Click Event Data
+
+When an injected element is clicked, the callback receives:
+
+```typescript
+{
+  elementId: 'weave-injected-1',  // ID of the clicked element
+  event: {
+    clientX: 450,                     // Mouse X position
+    clientY: 300,                     // Mouse Y position
+    target: {
+      tagName: 'button',              // Element tag name
+      id: 'weave-injected-1',      // Element ID
+      className: 'my-button'          // Element classes
+    }
+  }
+}
+```
+
+#### Common Use Cases
+
+**1. Floating Action Button**
+```typescript
+const buttonId = await weaveDOM.injectElement(
+  'body',
+  'beforeend',
+  '<button class="fab">🚀</button>',
+  {
+    onClick: () => console.log('Action triggered!')
+  }
+);
+```
+
+**2. Page Banner/Overlay**
+```typescript
+const bannerId = await weaveDOM.injectElement(
+  'body',
+  'afterbegin',
+  `<div style="position: fixed; top: 0; left: 0; right: 0; 
+    background: #3b82f6; color: white; padding: 15px; 
+    text-align: center; z-index: 9999;">
+    🎉 Special Offer! Click to learn more
+  </div>`,
+  {
+    onClick: () => {
+      // Handle banner click
+      console.log('Banner clicked!');
+    }
+  }
+);
+```
+
+**3. Notification Badge**
+```typescript
+const badgeId = await weaveDOM.injectElement(
+  '#user-profile',
+  'afterbegin',
+  `<span style="position: absolute; top: -5px; right: -5px;
+    background: red; color: white; border-radius: 50%;
+    width: 20px; height: 20px; display: flex;
+    align-items: center; justify-content: center;
+    font-size: 12px;">3</span>`,
+  {
+    onClick: () => console.log('Show notifications')
+  }
+);
+```
+
+**4. Inline Action Buttons**
+```typescript
+// Add quick action buttons next to specific elements
+const quickBuyId = await weaveDOM.injectElement(
+  '.product-card',
+  'beforeend',
+  '<button class="quick-buy">Quick Buy</button>',
+  {
+    onClick: (data) => {
+      console.log('Quick buy clicked!');
+      // Handle purchase
+    }
+  }
+);
+```
+
+#### Security & Best Practices
+
+**Security Features:**
+- ✅ HTML is sanitized (scripts and inline event handlers removed)
+- ✅ Click listeners registered via `addEventListener` (not inline)
+- ✅ All injected elements tracked for cleanup
+- ✅ Elements marked with `data-weave-injected="true"`
+- ✅ Automatic cleanup when DOMBridge is destroyed
+
+**Best Practices:**
+1. **Always clean up** - Remove injected elements when app is closed
+2. **Use high z-index** - Use 9999+ for overlays to ensure visibility
+3. **Handle errors** - Wrap injection calls in try-catch blocks
+4. **Unique IDs** - Provide custom element IDs if tracking multiple elements
+5. **Responsive design** - Use fixed positioning and responsive units
+6. **Accessibility** - Add ARIA labels and keyboard support
+
+**Limitations:**
+- ⚠️ Only click events supported (more events can be added if needed)
+- ⚠️ Inline event handlers removed for security
+- ⚠️ HTML should contain one root element
+- ⚠️ No direct DOM access to injected elements
+
+### Element Watching (MutationObserver)
+
+Apps can watch elements on the parent page for changes using the browser's native MutationObserver API. This allows you to react to attribute changes, element removal, and child node changes.
+
+#### What Can Be Watched
+
+1. **Attribute Changes** - Detect when element attributes change (class, data-*, style, etc.)
+2. **Element Removal** - Detect when an element is removed from the DOM
+3. **Child Changes** - Detect when child nodes are added/removed (optional)
+
+#### `watchElement(selector, callback, options)`
+
+Watch an element for changes.
+
+**Parameters:**
+- `selector` (string) - CSS selector for the element to watch
+- `callback` (function) - Function called when element changes
+- `options` (object, optional)
+  - `watchAttributes` (boolean) - Watch for attribute changes (default: true)
+  - `watchChildren` (boolean) - Watch for child node changes (default: false)
+  - `attributeFilter` (string[]) - Optional array of specific attributes to watch
+
+**Returns:** Promise<string> - The watcher ID (use to stop watching)
+
+**Callback Data:**
+```typescript
+{
+  changeType: 'attribute' | 'removed' | 'childList',
+  element: ElementSnapshot,        // Current state of element
+  attributeName?: string,          // Only for 'attribute' changes
+  attributeValue?: string          // Only for 'attribute' changes
+}
+```
+
+#### `unwatchElement(watcherId)`
+
+Stop watching an element.
+
+**Parameters:**
+- `watcherId` (string) - ID of the watcher to stop (returned from `watchElement`)
+
+#### Example: Watch for Attribute Changes
+
+```typescript
+class AttributeWatcherApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'attribute-watcher',
+      name: 'Attribute Watcher',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Watches element attributes',
+      tags: ['monitoring']
+    });
+    
+    this.state = {
+      watcherId: null
+    };
+  }
+
+  async onBackgroundService() {
+    // Watch for class changes on a button
+    this.state.watcherId = await window.weaveDOM.watchElement(
+      '#submit-button',
+      (data) => {
+        if (data.changeType === 'attribute' && data.attributeName === 'class') {
+          console.log(`Button class changed to: ${data.attributeValue}`);
+          
+          // React to specific class changes
+          if (data.element.className.includes('disabled')) {
+            console.log('Button was disabled!');
+            this.showWarning('Submit button is now disabled');
+          }
+        }
+      },
+      {
+        watchAttributes: true,
+        attributeFilter: ['class'] // Only watch class attribute
+      }
+    );
+  }
+
+  cleanup() {
+    if (this.state.watcherId) {
+      window.weaveDOM.unwatchElement(this.state.watcherId);
+    }
+  }
+}
+```
+
+#### Example: Watch for Element Removal
+
+```typescript
+async onBackgroundService() {
+  const watcherId = await window.weaveDOM.watchElement(
+    '#notification-banner',
+    (data) => {
+      if (data.changeType === 'removed') {
+        console.log('Notification banner was removed!');
+        // Re-inject your custom UI or take other action
+        this.reinjectCustomBanner();
+      }
+    }
+  );
+}
+```
+
+#### Example: Watch Multiple Attributes
+
+```typescript
+await window.weaveDOM.watchElement(
+  '#status-indicator',
+  (data) => {
+    if (data.changeType === 'attribute') {
+      console.log(`${data.attributeName} changed to: ${data.attributeValue}`);
+      
+      // React to specific attributes
+      if (data.attributeName === 'data-status') {
+        this.handleStatusChange(data.attributeValue);
+      } else if (data.attributeName === 'aria-busy') {
+        this.handleLoadingChange(data.attributeValue === 'true');
+      }
+    }
+  },
+  {
+    watchAttributes: true,
+    attributeFilter: ['data-status', 'aria-busy', 'class']
+  }
+);
+```
+
+#### Example: Watch Child Node Changes
+
+```typescript
+await window.weaveDOM.watchElement(
+  '#message-container',
+  (data) => {
+    if (data.changeType === 'childList') {
+      console.log('Children changed in message container');
+      // New messages might have been added
+      this.checkForNewMessages();
+    }
+  },
+  {
+    watchChildren: true
+  }
+);
+```
+
+#### Example: Auto-Reinject UI When Removed
+
+```typescript
+class AutoReinjectApp extends WeaveBaseApp {
+  private buttonElementId: string | null = null;
+  private watcherId: string | null = null;
+
+  async onBackgroundService() {
+    await this.injectButton();
+    await this.watchForRemoval();
+  }
+
+  private async injectButton() {
+    this.buttonElementId = await window.weaveDOM.injectElement(
+      '#toolbar',
+      'beforeend',
+      '<button id="my-button">My Action</button>',
+      {
+        onClick: () => this.handleClick()
+      }
+    );
+  }
+
+  private async watchForRemoval() {
+    // Watch the parent container for child changes
+    this.watcherId = await window.weaveDOM.watchElement(
+      '#toolbar',
+      async (data) => {
+        if (data.changeType === 'childList') {
+          // Check if our button still exists
+          const buttonExists = data.element.outerHTML.includes('my-button');
+          if (!buttonExists && this.buttonElementId) {
+            console.log('Button was removed, re-injecting...');
+            await this.injectButton();
+          }
+        }
+      },
+      {
+        watchChildren: true
+      }
+    );
+  }
+
+  cleanup() {
+    if (this.watcherId) {
+      window.weaveDOM.unwatchElement(this.watcherId);
+    }
+  }
+}
+```
+
+#### Example: React to Loading States
+
+```typescript
+async onBackgroundService() {
+  await window.weaveDOM.watchElement(
+    '#main-content',
+    (data) => {
+      if (data.changeType === 'attribute' && data.attributeName === 'aria-busy') {
+        const isLoading = data.attributeValue === 'true';
+        
+        if (isLoading) {
+          console.log('Page is loading...');
+          this.showLoadingIndicator();
+        } else {
+          console.log('Page finished loading');
+          this.hideLoadingIndicator();
+          this.processPageContent();
+        }
+      }
+    },
+    {
+      watchAttributes: true,
+      attributeFilter: ['aria-busy']
+    }
+  );
+}
+```
+
+#### Common Use Cases
+
+**1. Monitor Form Validation States**
+```typescript
+// Watch for validation class changes
+await window.weaveDOM.watchElement(
+  'form#checkout-form',
+  (data) => {
+    if (data.changeType === 'attribute' && data.attributeName === 'class') {
+      if (data.element.className.includes('has-errors')) {
+        this.showFormHelp();
+      } else if (data.element.className.includes('is-valid')) {
+        this.hideFormHelp();
+      }
+    }
+  },
+  { watchAttributes: true, attributeFilter: ['class'] }
+);
+```
+
+**2. Detect Dynamic Content Loading**
+```typescript
+// Watch for new items being added to a list
+await window.weaveDOM.watchElement(
+  '#product-list',
+  (data) => {
+    if (data.changeType === 'childList') {
+      console.log('New products loaded');
+      this.processNewProducts();
+    }
+  },
+  { watchChildren: true }
+);
+```
+
+**3. Monitor Status Changes**
+```typescript
+// Watch for status attribute changes
+await window.weaveDOM.watchElement(
+  '#order-status',
+  (data) => {
+    if (data.changeType === 'attribute' && data.attributeName === 'data-status') {
+      const status = data.attributeValue;
+      if (status === 'completed') {
+        this.notifyOrderComplete();
+      }
+    }
+  },
+  { watchAttributes: true, attributeFilter: ['data-status'] }
+);
+```
+
+**4. Persistent UI Injection**
+```typescript
+// Re-inject button if removed by page updates
+async onBackgroundService() {
+  await this.injectCustomButton();
+  
+  // Watch parent for changes
+  await window.weaveDOM.watchElement(
+    '#button-container',
+    async (data) => {
+      if (data.changeType === 'childList') {
+        const hasButton = data.element.outerHTML.includes('my-custom-button');
+        if (!hasButton) {
+          await this.injectCustomButton();
+        }
+      }
+    },
+    { watchChildren: true }
+  );
+}
+```
+
+#### Best Practices
+
+**✅ Do:**
+- Always clean up watchers in the `cleanup()` method
+- Use `attributeFilter` when you only care about specific attributes (more efficient)
+- Check `changeType` before accessing attribute-specific fields
+- Store watcher IDs as class properties for cleanup
+- Watch parent elements to detect child removal
+
+**❌ Don't:**
+- Don't watch too many elements - each watcher uses resources
+- Don't forget to unwatch - memory leaks can occur
+- Don't watch `document.body` with `watchChildren: true` - too many events
+- Don't assume element exists - check `data.element.exists`
+
+#### Performance Considerations
+
+1. **Attribute Filters**: Always use `attributeFilter` when possible - reduces event volume
+2. **Child Watching**: Use `watchChildren` sparingly - can fire many events
+3. **Cleanup**: Always unwatch when done - observers consume memory
+4. **Selector Specificity**: Use specific selectors to avoid watching wrong elements
+
+#### Automatic Cleanup
+
+Watchers are automatically cleaned up when:
+- Element is removed from DOM (parent observer detects and cleans up)
+- `unwatchElement()` is called
+- DOMBridge is destroyed (e.g., page unload)
+
+#### Error Handling
+
+```typescript
+try {
+  const watcherId = await window.weaveDOM.watchElement(
+    '#my-element',
+    (data) => console.log(data)
+  );
+} catch (error) {
+  // Element not found or watcher already exists
+  console.error('Failed to watch element:', error.message);
+}
+```
+
+#### Comparison to Polling
+
+**MutationObserver (Element Watching) ✅**
+- Native browser API
+- Event-driven (no polling)
+- Efficient (only fires when changes occur)
+- Detects exact attribute changes
+- Automatic cleanup on removal
+
+**setInterval Polling ❌**
+- Custom implementation
+- Constant CPU usage
+- Inefficient (checks even when nothing changes)
+- Must manually compare values
+- Must manually check if element exists
+
+### Security Restrictions
+
+The DOMBridge **blocks** dangerous operations:
+
+❌ **Blocked Selectors:**
+- `*` (universal selector)
+- `body`
+- `html`
+- Selectors targeting `<script>` tags
+
+❌ **Blocked HTML:**
+- `<script>` tags
+- Event handler attributes (`onclick`, `onload`, etc.)
+- `javascript:` URLs
+
+❌ **Blocked Attributes:**
+- `onclick`, `onload`, `onerror`, etc.
+- `href` with `javascript:`
+- `src` on certain elements
+
+✅ **Allowed:**
+- CSS selectors (class, id, attribute, etc.)
+- Safe HTML content
+- Style manipulation
+- Class/attribute manipulation
+- Text content changes
+- Element injection with event listeners (via `injectElement`)
+
+## Shadow DOM & Styling
+
+### Style Isolation
+
+Apps use Shadow DOM for complete style isolation:
+
+```typescript
+this.renderHTML(`
+  <style>
+    /* These styles ONLY affect your app */
+    .button {
+      background: blue;
+      color: white;
+    }
+    
+    /* Parent page styles do NOT leak in */
+    /* Your styles do NOT leak out */
+  </style>
+  
+  <button class="button">Click Me</button>
+`);
+```
+
+### Tailwind CSS Available
+
+**Tailwind CSS is available to all apps!** The sidebar iframe loads Tailwind, so you can use Tailwind utility classes directly in your HTML:
+
+```typescript
+this.renderHTML(`
+  <div class="p-4 bg-white rounded-lg shadow-md">
+    <h1 class="text-2xl font-bold text-gray-800 mb-4">My App</h1>
+    <button class="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
+      Click Me
+    </button>
+  </div>
+`);
+```
+
+**You can mix Tailwind with custom CSS:**
+
+```typescript
+this.renderHTML(`
+  <style>
+    /* Custom styles for specific needs */
+    .custom-gradient {
+      background: linear-gradient(to right, #667eea, #764ba2);
+    }
+  </style>
+  
+  <div class="p-6 space-y-4">
+    <div class="custom-gradient text-white p-4 rounded-lg">
+      <h2 class="text-xl font-semibold">Gradient Header</h2>
+    </div>
+    
+    <div class="flex gap-2">
+      <button class="flex-1 px-4 py-2 bg-green-500 text-white rounded">
+        Save
+      </button>
+      <button class="flex-1 px-4 py-2 bg-gray-300 text-gray-700 rounded">
+        Cancel
+      </button>
+    </div>
+  </div>
+`);
+```
+
+**Common Tailwind Patterns:**
+
+```typescript
+// Card layout
+<div class="bg-white rounded-lg shadow p-4">
+  <h3 class="text-lg font-semibold mb-2">Card Title</h3>
+  <p class="text-gray-600">Card content</p>
+</div>
+
+// Form inputs
+<input 
+  type="text" 
+  class="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+  placeholder="Enter text"
+/>
+
+// Buttons
+<button class="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 active:bg-blue-700 transition">
+  Primary Button
+</button>
+
+// Flex layouts
+<div class="flex items-center justify-between">
+  <span>Label</span>
+  <button>Action</button>
+</div>
+
+// Grid layouts
+<div class="grid grid-cols-2 gap-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+
+// Spacing
+<div class="space-y-4">  <!-- Vertical spacing between children -->
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+### Best Practices
+
+1. **Prefer Tailwind utilities for common styles:**
+   ```typescript
+   // ✅ Good - Use Tailwind
+   <button class="px-4 py-2 bg-blue-500 text-white rounded">Click</button>
+   
+   // ❌ Less ideal - Custom CSS for simple styles
+   <style>
+     .my-button { padding: 0.5rem 1rem; background: blue; }
+   </style>
+   <button class="my-button">Click</button>
+   ```
+
+2. **Use custom CSS for complex/unique styles:**
+   ```typescript
+   this.renderHTML(`
+     <style>
+       .custom-animation {
+         animation: slideIn 0.3s ease-out;
+       }
+       @keyframes slideIn {
+         from { transform: translateX(-100%); }
+         to { transform: translateX(0); }
+       }
+     </style>
+     <div class="custom-animation p-4 bg-white rounded">Content</div>
+   `);
+   ```
+
+3. **Combine Tailwind with custom CSS variables:**
+   ```typescript
+   this.renderHTML(`
+     <style>
+       :host {
+         --primary-color: #4f46e5;
+       }
+       .custom-primary {
+         background-color: var(--primary-color);
+       }
+     </style>
+     <button class="custom-primary px-4 py-2 text-white rounded hover:opacity-90">
+       Custom Primary
+     </button>
+   `);
+   ```
+
+4. **Use Tailwind's responsive classes:**
+   ```typescript
+   // Mobile-first responsive design
+   <div class="p-2 md:p-4 lg:p-6">
+     <h1 class="text-xl md:text-2xl lg:text-3xl">Responsive Title</h1>
+   </div>
+   ```
+
+5. **Leverage Tailwind's dark mode (if needed):**
+   ```typescript
+   <div class="bg-white dark:bg-gray-800 text-gray-900 dark:text-white">
+     Content that adapts to dark mode
+   </div>
+   ```
+
+### CSS Variables & Tailwind Customization
+
+**CSS variables can be overridden in shadow DOM!** This is one of the few things that crosses the shadow boundary because CSS variables are inherited properties.
+
+#### How It Works
+
+Tailwind uses CSS variables for theme values (colors, spacing, etc.). You can override these variables in your app's shadow DOM, and Tailwind classes will respect your custom values:
+
+```typescript
+this.renderHTML(`
+  <style>
+    /* Override Tailwind's CSS variables in your shadow DOM */
+    :host {
+      --color-primary: #ff6b6b;
+      --color-secondary: #4ecdc4;
+      --spacing-unit: 8px;
+    }
+    
+    /* Or override for specific elements */
+    .custom-section {
+      --color-primary: #95e1d3;
+    }
+    
+    /* Create your own variables */
+    :host {
+      --app-accent: #f38181;
+      --app-border-radius: 12px;
+    }
+    
+    .custom-card {
+      background: var(--color-primary);
+      border-radius: var(--app-border-radius);
+      padding: calc(var(--spacing-unit) * 2);
+    }
+  </style>
+  
+  <div class="p-4">
+    <!-- Tailwind classes work normally -->
+    <div class="bg-blue-500 text-white p-4 rounded">
+      Standard Tailwind
+    </div>
+    
+    <!-- Custom classes using your variables -->
+    <div class="custom-card">
+      Uses custom CSS variables
+    </div>
+    
+    <!-- Override variables for nested elements -->
+    <div class="custom-section">
+      <div class="custom-card">
+        Uses overridden primary color
+      </div>
+    </div>
+  </div>
+`);
+```
+
+#### Cascading Overrides
+
+CSS variables follow the cascade, so you can override them at different levels:
+
+```typescript
+this.renderHTML(`
+  <style>
+    /* Root level for entire app */
+    :host {
+      --btn-color: blue;
+      --btn-padding: 12px;
+    }
+    
+    /* Override for specific section */
+    .danger-zone {
+      --btn-color: red;
+    }
+    
+    /* Override for specific element */
+    .special-button {
+      --btn-color: purple;
+      --btn-padding: 20px;
+    }
+    
+    /* Use the variables */
+    .btn {
+      background: var(--btn-color);
+      padding: var(--btn-padding);
+      color: white;
+      border: none;
+      border-radius: 4px;
+    }
+  </style>
+  
+  <div class="p-4 space-y-4">
+    <!-- Uses blue (from :host) -->
+    <button class="btn">Normal Button</button>
+    
+    <!-- Uses red (overridden in .danger-zone) -->
+    <div class="danger-zone">
+      <button class="btn">Danger Button</button>
+    </div>
+    
+    <!-- Uses purple (overridden in .special-button) -->
+    <button class="btn special-button">Special Button</button>
+  </div>
+`);
+```
+
+#### Theming Your App
+
+Create a complete theme system using CSS variables:
+
+```typescript
+this.renderHTML(`
+  <style>
+    :host {
+      /* Color palette */
+      --theme-primary: #3b82f6;
+      --theme-secondary: #8b5cf6;
+      --theme-success: #10b981;
+      --theme-danger: #ef4444;
+      --theme-warning: #f59e0b;
+      
+      /* Neutral colors */
+      --theme-bg: #ffffff;
+      --theme-surface: #f3f4f6;
+      --theme-border: #e5e7eb;
+      --theme-text: #111827;
+      --theme-text-muted: #6b7280;
+      
+      /* Spacing scale */
+      --space-xs: 4px;
+      --space-sm: 8px;
+      --space-md: 16px;
+      --space-lg: 24px;
+      --space-xl: 32px;
+      
+      /* Typography */
+      --font-size-sm: 0.875rem;
+      --font-size-base: 1rem;
+      --font-size-lg: 1.125rem;
+      --font-size-xl: 1.25rem;
+      
+      /* Border radius */
+      --radius-sm: 4px;
+      --radius-md: 8px;
+      --radius-lg: 12px;
+      
+      /* Shadows */
+      --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+      --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+      --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+    }
+    
+    /* Apply theme variables */
+    .card {
+      background: var(--theme-surface);
+      border: 1px solid var(--theme-border);
+      border-radius: var(--radius-md);
+      padding: var(--space-lg);
+      box-shadow: var(--shadow-sm);
+    }
+    
+    .btn-primary {
+      background: var(--theme-primary);
+      color: white;
+      padding: var(--space-sm) var(--space-md);
+      border-radius: var(--radius-sm);
+      font-size: var(--font-size-base);
+      border: none;
+      cursor: pointer;
+    }
+    
+    .btn-primary:hover {
+      filter: brightness(1.1);
+    }
+    
+    .text-muted {
+      color: var(--theme-text-muted);
+      font-size: var(--font-size-sm);
+    }
+  </style>
+  
+  <div class="p-4 space-y-4">
+    <div class="card">
+      <h2 class="text-xl font-bold mb-2">Themed Card</h2>
+      <p class="text-muted mb-4">Using custom CSS variables</p>
+      <button class="btn-primary">Primary Action</button>
+    </div>
+  </div>
+`);
+```
+
+#### Dark Mode with CSS Variables
+
+Implement dark mode by overriding variables based on a class or state:
+
+```typescript
+this.renderHTML(`
+  <style>
+    :host {
+      /* Light mode (default) */
+      --theme-bg: #ffffff;
+      --theme-text: #111827;
+      --theme-surface: #f3f4f6;
+      --theme-border: #e5e7eb;
+    }
+    
+    /* Dark mode overrides */
+    :host(.dark-mode) {
+      --theme-bg: #1f2937;
+      --theme-text: #f9fafb;
+      --theme-surface: #374151;
+      --theme-border: #4b5563;
+    }
+    
+    .container {
+      background: var(--theme-bg);
+      color: var(--theme-text);
+      min-height: 100vh;
+      padding: 20px;
+    }
+    
+    .card {
+      background: var(--theme-surface);
+      border: 1px solid var(--theme-border);
+      padding: 16px;
+      border-radius: 8px;
+    }
+  </style>
+  
+  <div class="container">
+    <div class="card">
+      <h2>Theme-aware Card</h2>
+      <p>Automatically adapts to light/dark mode</p>
+    </div>
+  </div>
+`);
+
+// Toggle dark mode
+toggleDarkMode() {
+  if (this.classList.contains('dark-mode')) {
+    this.classList.remove('dark-mode');
+  } else {
+    this.classList.add('dark-mode');
+  }
+}
+```
+
+#### Key Benefits
+
+1. **Inheritance Across Shadow Boundary**: CSS variables are one of the few things that cross shadow DOM boundaries
+2. **Cascade Support**: Variables can be overridden at any DOM level
+3. **Dynamic Theming**: Change variables programmatically for instant theme updates
+4. **Tailwind Integration**: Override Tailwind's variables to customize its utility classes
+5. **Scoped Customization**: Different parts of your app can have different themes
+
+#### Important Notes
+
+- **Tailwind classes themselves don't cross shadow boundaries** - they must be available in the shadow DOM
+- **CSS variables DO cross shadow boundaries** - they're inherited
+- **Override specificity follows CSS cascade rules** - more specific selectors win
+- **Use `:host` to target the shadow root** - this is your app's top-level element
+
+## State Management
+
+### Using `this.state`
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  constructor() {
+    super({ /* ... */ });
+    
+    // Initialize state
+    this.state = {
+      count: 0,
+      items: [],
+      isLoading: false
+    };
+  }
+  
+  private increment(): void {
+    // Update state
+    this.setState({ count: this.state.count + 1 });
+    
+    // Update UI
+    this.updateDisplay();
+  }
+  
+  private updateDisplay(): void {
+    const countEl = this.query('#count');
+    if (countEl) {
+      countEl.textContent = String(this.state.count);
+    }
+  }
+}
+```
+
+### State Updates
+
+- Use `this.setState()` to update state
+- State updates are **not reactive** - manually update UI
+- State is **not persisted** - use localStorage if needed
+
+## Event Handling
+
+### Internal Events (Shadow DOM)
+
+```typescript
+protected setupEventListeners(): void {
+  // Button clicks
+  this.query('#myButton')?.addEventListener('click', () => {
+    this.handleClick();
+  });
+  
+  // Input changes
+  this.query<HTMLInputElement>('#myInput')?.addEventListener('input', (e) => {
+    const value = (e.target as HTMLInputElement).value;
+    this.handleInput(value);
+  });
+  
+  // Form submission
+  this.query('form')?.addEventListener('submit', (e) => {
+    e.preventDefault();
+    this.handleSubmit();
+  });
+}
+```
+
+### Cleanup
+
+```typescript
+protected cleanup(): void {
+  // Clear intervals
+  if (this.intervalId) {
+    clearInterval(this.intervalId);
+  }
+  
+  // Remove external listeners (if any)
+  // Note: Shadow DOM listeners are auto-cleaned
+}
+```
+
+## TypeScript Types
+
+### Available Types
+
+```typescript
+import { 
+  WeaveBaseApp,
+  WeaveAppInfo,
+  ElementSnapshot,
+  InsertPosition 
+} from '@weave/app-sdk';
+
+// App metadata
+interface WeaveAppInfo {
+  id: string;
+  name: string;
+  version: string;
+  category: string;
+  description: string;
+  author: string;
+  tags?: string[];
+}
+
+// Element from parent page
+interface ElementSnapshot {
+  tagName: string;
+  id: string;
+  className: string;
+  textContent: string;
+  attributes: Record<string, string>;
+  exists: boolean;
+}
+
+// HTML insertion position
+type InsertPosition = 'beforebegin' | 'afterbegin' | 'beforeend' | 'afterend';
+```
+
+## Build Process
+
+### Development Workflow
+
+```bash
+# Write TypeScript in src/app.ts
+npm run build
+
+# Output: dist/{app-name}.js (plain JavaScript)
+```
+
+### What Happens During Build
+
+1. **TypeScript Compilation** → JavaScript (ES2020)
+2. **Import Removal** → SDK is on window globals
+3. **Reference Replacement:**
+   - `WeaveBaseApp` → `window.WeaveBaseApp`
+   - `weaveDOM` → `window.weaveDOM`
+4. **Clean Output** → Readable, unobfuscated JavaScript
+
+### Final Output Format
+
+```javascript
+/**
+ * my-app
+ * 
+ * Built with Weave App SDK
+ * Generated: 2025-01-01T00:00:00.000Z
+ */
+
+// Access SDK from window globals
+const { WeaveBaseApp, weaveDOM } = window;
+
+class MyApp extends window.WeaveBaseApp {
+  // Your compiled code here
+}
+
+customElements.define('my-app', MyApp);
+```
+
+## Common Patterns
+
+### Loading State
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  constructor() {
+    super({ /* ... */ });
+    this.state = { isLoading: false, data: null };
+  }
+  
+  private async loadData(): Promise<void> {
+    this.setState({ isLoading: true });
+    this.updateUI();
+    
+    try {
+      const text = await window.weaveDOM.getText('h1');
+      this.setState({ data: text, isLoading: false });
+    } catch (error) {
+      this.setState({ isLoading: false });
+      console.error('Failed to load:', error);
+    }
+    
+    this.updateUI();
+  }
+}
+```
+
+### Form Handling
+
+```typescript
+protected setupEventListeners(): void {
+  this.query('form')?.addEventListener('submit', async (e) => {
+    e.preventDefault();
+    await this.handleSubmit();
+  });
+}
+
+private async handleSubmit(): Promise<void> {
+  const input = this.query<HTMLInputElement>('#textInput');
+  if (!input) return;
+  
+  const value = input.value.trim();
+  if (!value) return;
+  
+  try {
+    await window.weaveDOM.setText('h1', value);
+    input.value = '';
+    this.showSuccess('Updated!');
+  } catch (error) {
+    this.showError('Failed to update');
+  }
+}
+```
+
+### List Rendering
+
+```typescript
+private renderList(): void {
+  const items = this.state.items;
+  const html = items.map(item => `
+    <li data-id="${item.id}">
+      ${item.name}
+      <button class="delete-btn" data-id="${item.id}">Delete</button>
+    </li>
+  `).join('');
+  
+  const list = this.query('#itemList');
+  if (list) {
+    list.innerHTML = html;
+  }
+}
+
+protected setupEventListeners(): void {
+  // Event delegation
+  this.query('#itemList')?.addEventListener('click', (e) => {
+    const target = e.target as HTMLElement;
+    if (target.classList.contains('delete-btn')) {
+      const id = target.dataset.id;
+      this.deleteItem(id);
+    }
+  });
+}
+```
+
+## Limitations & Constraints
+
+### What You CANNOT Do
+
+❌ **Direct DOM Access**
+```typescript
+// ❌ WRONG - No access to parent page DOM
+document.querySelector('h1');
+window.parent.document;
+```
+
+❌ **Arbitrary HTTP Requests**
+```typescript
+// ❌ WRONG - Cannot make external API calls
+await fetch('https://api.example.com/data');
+await axios.get('https://some-api.com');
+
+// ✅ CORRECT - Use Weave API instead
+await weaveAPI.ai.chat({ appName: 'my-app', prompt: '...' });
+await weaveAPI.appData.getAll();
+```
+
+❌ **ES6 Module Imports in Final Output**
+```typescript
+// ❌ WRONG - Will be removed during build
+import { something } from 'some-library';
+```
+
+❌ **External Dependencies**
+```typescript
+// ❌ WRONG - No npm packages in final output
+import axios from 'axios';
+import lodash from 'lodash';
+```
+
+❌ **Dangerous HTML**
+```typescript
+// ❌ WRONG - Will be sanitized/blocked
+await weaveDOM.insertHTML('.container', '<script>alert("xss")</script>');
+```
+
+### What You CAN Do
+
+✅ **Use Weave APIs**
+```typescript
+// Backend API - AI and data storage
+await weaveAPI.ai.chat({ appName: 'my-app', prompt: 'Hello' });
+await weaveAPI.appData.create({ appId: 'my-app', dataKey: 'key', data: {} });
+
+// DOM API - Parent page manipulation
+await weaveDOM.getText('h1');
+await weaveDOM.setText('.status', 'Updated!');
+```
+
+✅ **Use Browser APIs**
+```typescript
+localStorage.setItem('key', 'value');
+setTimeout(() => {}, 1000);
+new Date();
+console.log('Debug message');
+```
+
+✅ **Use Modern JavaScript**
+```typescript
+const items = [1, 2, 3].map(x => x * 2);
+const { name, age } = person;
+async/await, promises, etc.
+```
+
+## Testing & Debugging
+
+### Console Logging
+
+```typescript
+console.log('✅ App initialized');
+console.error('❌ Error:', error);
+console.warn('⚠️ Warning:', message);
+```
+
+### Debugging DOM Operations
+
+```typescript
+try {
+  const element = await window.weaveDOM.query('h1');
+  console.log('Element found:', element);
+  
+  if (!element.exists) {
+    console.warn('Element does not exist on page');
+  }
+} catch (error) {
+  console.error('DOM operation failed:', error);
+}
+```
+
+### Check App Lifecycle
+
+```typescript
+connectedCallback(): void {
+  console.log('✅ App connected to DOM');
+  super.connectedCallback();
+}
+
+disconnectedCallback(): void {
+  console.log('🔌 App disconnected from DOM');
+  super.disconnectedCallback();
+}
+```
+
+## Best Practices
+
+### 1. No Duplicate Headers
+The sidebar automatically displays your app name as a header. Do NOT add your app name as an `<h1>` in your render method.
+
+### 2. Error Handling
+Always wrap DOM operations in try-catch blocks.
+
+### 3. User Feedback
+Show loading states and error messages to users.
+
+### 4. Performance
+- Debounce frequent operations
+- Avoid unnecessary DOM queries
+- Cache element references when possible
+
+### 5. Accessibility
+- Use semantic HTML
+- Include ARIA labels
+- Support keyboard navigation
+
+### 6. Responsive Design
+- Use relative units (rem, em, %)
+- Test different sidebar widths
+- Mobile-friendly touch targets
+
+### 7. Clean Code
+- Use TypeScript types
+- Comment complex logic
+- Follow consistent naming conventions
+
+## Example: Complete App
+
+```typescript
+import { WeaveBaseApp } from '@weave/app-sdk';
+
+class PageTitleEditor extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'page-title-editor',
+      name: 'Page Title Editor',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Edit the page title',
+      author: 'Developer Name',
+      tags: ['editor', 'title']
+    });
+    
+    this.state = {
+      currentTitle: '',
+      isLoading: false,
+      error: null
+    };
+  }
+
+  protected render(): void {
+    this.renderHTML(`
+      <div class="p-5 font-sans">
+        <!-- Note: App name header is already shown by the sidebar, no need to duplicate it -->
+        
+        <div class="mb-4">
+          <label for="titleInput" class="block mb-2 font-medium text-gray-700">
+            New Title:
+          </label>
+          <input 
+            type="text" 
+            id="titleInput" 
+            placeholder="Enter new title"
+            class="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+          />
+        </div>
+        
+        <div class="flex gap-2 mb-4">
+          <button 
+            id="updateBtn"
+            class="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 active:bg-blue-700 transition disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Update Title
+          </button>
+          <button 
+            id="loadBtn"
+            class="px-4 py-2 bg-gray-500 text-white rounded hover:bg-gray-600 active:bg-gray-700 transition"
+          >
+            Load Current Title
+          </button>
+        </div>
+        
+        <div id="message"></div>
+      </div>
+    `);
+  }
+
+  protected setupEventListeners(): void {
+    this.query('#updateBtn')?.addEventListener('click', () => this.updateTitle());
+    this.query('#loadBtn')?.addEventListener('click', () => this.loadTitle());
+    
+    this.query('#titleInput')?.addEventListener('keypress', (e) => {
+      if (e.key === 'Enter') this.updateTitle();
+    });
+  }
+
+  private async loadTitle(): Promise<void> {
+    this.setState({ isLoading: true, error: null });
+    this.showMessage('Loading...', 'info');
+    
+    try {
+      const title = await window.weaveDOM.getText('title');
+      this.setState({ currentTitle: title, isLoading: false });
+      
+      const input = this.query<HTMLInputElement>('#titleInput');
+      if (input) input.value = title;
+      
+      this.showMessage('Title loaded!', 'success');
+    } catch (error) {
+      this.setState({ isLoading: false, error: error.message });
+      this.showMessage('Failed to load title', 'error');
+    }
+  }
+
+  private async updateTitle(): Promise<void> {
+    const input = this.query<HTMLInputElement>('#titleInput');
+    if (!input) return;
+    
+    const newTitle = input.value.trim();
+    if (!newTitle) {
+      this.showMessage('Please enter a title', 'error');
+      return;
+    }
+    
+    this.setState({ isLoading: true, error: null });
+    this.showMessage('Updating...', 'info');
+    
+    try {
+      await window.weaveDOM.setText('title', newTitle);
+      this.setState({ currentTitle: newTitle, isLoading: false });
+      this.showMessage('Title updated!', 'success');
+    } catch (error) {
+      this.setState({ isLoading: false, error: error.message });
+      this.showMessage('Failed to update title', 'error');
+    }
+  }
+
+  private showMessage(text: string, type: 'success' | 'error' | 'info'): void {
+    const messageEl = this.query('#message');
+    if (messageEl) {
+      messageEl.textContent = text;
+      
+      // Use Tailwind classes for styling
+      const baseClasses = 'p-3 rounded-md';
+      const typeClasses = {
+        success: 'bg-green-100 text-green-800 border border-green-200',
+        error: 'bg-red-100 text-red-800 border border-red-200',
+        info: 'bg-blue-100 text-blue-800 border border-blue-200'
+      };
+      
+      messageEl.className = `${baseClasses} ${typeClasses[type]}`;
+    }
+  }
+}
+
+customElements.define('page-title-editor', PageTitleEditor);
+```
+
+---
+
+## Quick Reference
+
+### SDK Globals
+- `window.WeaveBaseApp` - Base class
+- `window.weaveAPI` - Backend API (AI, data storage)
+- `window.weaveDOM` - DOM API (parent page manipulation)
+
+### Styling
+- **Tailwind CSS** - Available for all utility classes
+- **Custom CSS** - Use `<style>` tags in `renderHTML()` for custom styles
+- **Shadow DOM** - Complete style isolation from parent page
+
+### Base Class Methods
+- `this.renderHTML(html)` - Render UI
+- `this.query(selector)` - Find element
+- `this.queryAll(selector)` - Find all elements
+- `this.setState(updates)` - Update state
+- **`this.weaveAPI`** - ⚠️ **CRITICAL:** App-specific API client (use instead of `window.weaveAPI`)
+
+### Backend API Methods (`this.weaveAPI`)
+- **⚠️ ALWAYS use `this.weaveAPI` instead of `window.weaveAPI`**
+- **AI Service:**
+  - `this.weaveAPI.ai.chat(request)` - Call Weave AI
+- **App Data Service:**
+  - `this.weaveAPI.appData.getAll()` - Get all app data (returns `PaginatedResponse<AppData>`)
+  - `this.weaveAPI.appData.create(request)` - Create new data
+  - `this.weaveAPI.appData.get(id)` - Get specific data
+  - `this.weaveAPI.appData.update(id, request)` - Update data
+  - `this.weaveAPI.appData.delete(id)` - Delete data
+
+### DOM API Methods (`weaveDOM`)
+- **Read:** `query`, `queryAll`, `getText`, `getAttribute`, `getValue`, `hasClass`, `getPageUrl`
+- **Write:** `setText`, `setAttribute`, `setValue`, `addClass`, `removeClass`, `toggleClass`, `setStyle`
+- **Manipulate:** `insertHTML`, `removeElement`, `clickElement`
+- **Forms:** `getFormData`, `startFormClickListener`, `stopFormClickListener`, `setFormFieldValue`
+- **Element Injection:** `injectElement`, `removeInjectedElement`
+- **Element Listeners:** `startElementClickListener`, `stopElementClickListener`
+
+### Lifecycle
+1. `constructor()` - Initialize
+2. `connectedCallback()` - Added to DOM
+3. `render()` - Render UI
+4. `setupEventListeners()` - Attach listeners
+5. `disconnectedCallback()` - Removed from DOM
+6. `cleanup()` - Cleanup resources
+
+---
+
+## ⚠️ Critical Rules for AI Assistants
+
+When helping developers build Weave apps, **ALWAYS enforce these rules:**
+
+### 1. **ALWAYS Use `this.weaveAPI`**
+- ❌ **NEVER** use `window.weaveAPI` in app methods
+- ✅ **ALWAYS** use `this.weaveAPI` for all API calls
+- This prevents app ID conflicts when multiple apps run simultaneously
+
+### 2. **Capture Context in Async Methods**
+- When using multiple `await` calls, capture the API client:
+  ```typescript
+  const apiClient = this.weaveAPI;
+  const response = await apiClient.appData.getAll();
+  const allData = response.data;  // Access paginated data
+  await apiClient.appData.create(...);
+  ```
+
+### 3. **Capture Context in Callbacks**
+- When using callbacks (e.g., DOM Bridge click handlers):
+  ```typescript
+  const self = this;
+  onClick: async () => {
+    const apiClient = self.weaveAPI;
+    await apiClient.appData.create(...);
+  }
+  ```
+
+### 4. **No Arbitrary API Calls**
+- Apps can **ONLY** use `this.weaveAPI` and `window.weaveDOM`
+- NO `fetch()`, NO `axios`, NO external HTTP requests
+- All backend calls go through `this.weaveAPI`
+
+### 5. **Check `this.isConnected` Before Rendering**
+- Background services run before DOM attachment
+- Always check if app is attached before calling `render()`:
+  ```typescript
+  if (this.isConnected) {
+    this.render();
+  }
+  ```
+
+---
+
+**Remember:** 
+- Apps are isolated, secure, and communicate through secure message bridges
+- Always handle errors and provide user feedback
+- Use `this.weaveAPI` for ALL API calls (never `window.weaveAPI`)