@weave-apps/sdk 0.9.0 → 0.11.0

package/dist/app-sdk/src/global.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Global SDK Loader
+ *
+ * Makes the Weave SDK available globally for third-party apps
+ * that are loaded as JavaScript strings (not ES6 modules)
+ */
+import { WeaveBaseApp } from './WeaveBaseApp';
+import { WeaveDOMAPI } from './WeaveDOMAPI';
+import { WeaveAPIClient } from './WeaveAPIClient';
+import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+import { WeaveCronAPI } from './WeaveCronAPI';
+import { WeaveAppInstanceAPI } from './WeaveAppInstanceAPI';
+declare global {
+    interface Window {
+        WeaveBaseApp: typeof WeaveBaseApp;
+        WeaveDOMAPI: typeof WeaveDOMAPI;
+        weaveDOM: WeaveDOMAPI;
+        WeaveAPIClient: typeof WeaveAPIClient;
+        weaveAPI: WeaveAPIClient;
+        WeaveBackgroundAPI: typeof WeaveBackgroundAPI;
+        WeaveCronAPI: typeof WeaveCronAPI;
+        WeaveAppInstanceAPI: typeof WeaveAppInstanceAPI;
+    }
+}
+//# sourceMappingURL=global.d.ts.map

package/dist/app-sdk/src/global.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../../../src/global.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,YAAY,EAAE,OAAO,YAAY,CAAC;QAClC,WAAW,EAAE,OAAO,WAAW,CAAC;QAChC,QAAQ,EAAE,WAAW,CAAC;QACtB,cAAc,EAAE,OAAO,cAAc,CAAC;QACtC,QAAQ,EAAE,cAAc,CAAC;QACzB,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;QAC9C,YAAY,EAAE,OAAO,YAAY,CAAC;QAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;KAAG;CACtD"}

package/dist/app-sdk/src/global.js

@@ -0,0 +1,23 @@
+/**
+ * Global SDK Loader
+ *
+ * Makes the Weave SDK available globally for third-party apps
+ * that are loaded as JavaScript strings (not ES6 modules)
+ */
+import { WeaveBaseApp } from './WeaveBaseApp';
+import { WeaveDOMAPI } from './WeaveDOMAPI';
+import weavekDOM from './WeaveDOMAPI';
+import { WeaveAPIClient } from './WeaveAPIClient';
+import weaveAPI from './WeaveAPIClient';
+import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+import { WeaveCronAPI } from './WeaveCronAPI';
+import { WeaveAppInstanceAPI } from './WeaveAppInstanceAPI';
+// Make SDK available globally
+window.WeaveBaseApp = WeaveBaseApp;
+window.WeaveDOMAPI = WeaveDOMAPI;
+window.weaveDOM = weavekDOM;
+window.WeaveAPIClient = WeaveAPIClient;
+window.weaveAPI = weaveAPI;
+window.WeaveBackgroundAPI = WeaveBackgroundAPI;
+window.WeaveCronAPI = WeaveCronAPI;
+window.WeaveAppInstanceAPI = WeaveAppInstanceAPI;

package/dist/app-sdk/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Weave App SDK
+ *
+ * Main exports for third-party app development
+ */
+export { WeaveBaseApp, type WeaveAppInfo, type PendingOperation } from './WeaveBaseApp';
+export { WeaveDOMAPI, type ElementSnapshot, type InsertPosition } from './WeaveDOMAPI';
+export { default as weaveDOM } from './WeaveDOMAPI';
+export { WeaveAPIClient, type AIChatRequest, type AIChatResponse, type AppData, type CreateAppDataRequest, type UpdateAppDataRequest, type FormSubmissionFieldOption, type FormSubmissionCondition, type FormSubmissionResponseEntry, type FormSubmissionDefinitionSection, type FormSubmissionDefinitionField, type FormSubmissionDefinitionPayload, type FormSubmissionDataPayload, } from './WeaveAPIClient';
+export { default as weaveAPI } from './WeaveAPIClient';
+export { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+export { WeaveCronAPI } from './WeaveCronAPI';
+import './global';
+//# sourceMappingURL=index.d.ts.map

package/dist/app-sdk/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,+BAA+B,EACpC,KAAK,6BAA6B,EAClC,KAAK,+BAA+B,EACpC,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,UAAU,CAAC"}

package/dist/app-sdk/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * Weave App SDK
+ *
+ * Main exports for third-party app development
+ */
+export { WeaveBaseApp } from './WeaveBaseApp';
+export { WeaveDOMAPI } from './WeaveDOMAPI';
+export { default as weaveDOM } from './WeaveDOMAPI';
+export { WeaveAPIClient, } from './WeaveAPIClient';
+export { default as weaveAPI } from './WeaveAPIClient';
+export { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+export { WeaveCronAPI } from './WeaveCronAPI';
+// Import global.ts to ensure Window interface augmentation is included
+import './global';

package/dist/index.d.ts

@@ -6,7 +6,7 @@
 export { WeaveBaseApp, type WeaveAppInfo, type PendingOperation } from './WeaveBaseApp';
 export { WeaveDOMAPI, type ElementSnapshot, type InsertPosition } from './WeaveDOMAPI';
 export { default as weaveDOM } from './WeaveDOMAPI';
-export { WeaveAPIClient, type AIChatRequest, type AIChatResponse, type AppData, type CreateAppDataRequest, type UpdateAppDataRequest } from './WeaveAPIClient';
+export { WeaveAPIClient, type AIChatRequest, type AIChatResponse, type AppData, type CreateAppDataRequest, type UpdateAppDataRequest, type FormSubmissionFieldOption, type FormSubmissionCondition, type FormSubmissionResponseEntry, type FormSubmissionDefinitionSection, type FormSubmissionDefinitionField, type FormSubmissionDefinitionPayload, type FormSubmissionDataPayload, } from './WeaveAPIClient';
 export { default as weaveAPI } from './WeaveAPIClient';
 export { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
 export { WeaveCronAPI } from './WeaveCronAPI';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,+BAA+B,EACpC,KAAK,6BAA6B,EAClC,KAAK,+BAA+B,EACpC,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,UAAU,CAAC"}

package/dist/index.js

@@ -6,7 +6,7 @@
 export { WeaveBaseApp } from './WeaveBaseApp';
 export { WeaveDOMAPI } from './WeaveDOMAPI';
 export { default as weaveDOM } from './WeaveDOMAPI';
-export { WeaveAPIClient } from './WeaveAPIClient';
+export { WeaveAPIClient, } from './WeaveAPIClient';
 export { default as weaveAPI } from './WeaveAPIClient';
 export { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
 export { WeaveCronAPI } from './WeaveCronAPI';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weave-apps/sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "SDK for building Weave Micro Apps",
   "publishConfig": {
     "access": "public"
@@ -32,11 +32,11 @@
   "author": "Weave Platform",
   "license": "MIT",
   "dependencies": {
-    "esbuild": "^0.24.0",
+    "esbuild": "^0.28.0",
     "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0"
+    "@types/node": "^22.0.0"
   },
   "files": [
     "dist",

package/templates/WEAVE_SPEC.md

@@ -7,15 +7,18 @@
 
 ## Architecture Overview
 
-Weave apps are **Web Components** that run in an **iframe** inside a browser extension sidebar. They interact with two secure APIs:
+Weave apps are **Web Components** that run in an **iframe** inside a browser extension sidebar. They interact with three secure APIs:
 
 1. **Weave Backend API** - AI services, app data, forms, and company member discovery
 2. **DOM Bridge API** - Parent page DOM manipulation
+3. **Browser Extension API** - Cross-tab coordination, tab focus, state persistence via background service worker
 
 ```
 [Weave Backend] ←→ [Sidebar: API Bridge] ←→ [Iframe: Weave App]
                                                         ↕
 [Parent Page] ←→ [Content Script: DOMBridge] ←→ [Iframe: Weave App]
+                                                        ↕
+[Background SW] ←→ [Content Script: StateBridge] ←→ [Iframe: Weave App]
 ```
 
 ### Key Constraints
@@ -1789,6 +1792,407 @@ class MyApp extends WeaveBaseApp {
 }
 ```
 
+## Cross-Tab Instance Management
+
+### Overview
+
+When the same app runs in **multiple browser tabs** (e.g., user opens the same site in 3 tabs), each tab gets its own app instance. The **Instance API** (`this.instances`) lets these instances discover each other, elect a "controller" tab, and exchange messages — all through the browser extension's background service worker.
+
+**Use cases:**
+- 🎮 **Controller election** — Only one tab runs automation; others observe
+- 📡 **Cross-tab messaging** — Broadcast status, sync state, or coordinate work
+- 🔄 **Failover** — Detect when the controller tab closes and elect a new one
+- 🚫 **Deduplication** — Prevent duplicate scrapes, API calls, or UI injections
+
+### Architecture
+
+```
+Tab 1 (iframe)  ──┐
+                   │  window.parent.postMessage (APP_*)
+Tab 2 (iframe)  ──┼──► Content Script (BackgroundStateBridge)
+                   │       ──► chrome.runtime.sendMessage
+Tab 3 (iframe)  ──┘            ──► Background: AppInstanceRegistry
+                                        │
+                                        ├── Tracks all instances per appId
+                                        ├── Manages controller status
+                                        └── Routes messages between tabs
+```
+
+### Registering an Instance
+
+Call `this.instances.register()` in `onBackgroundService()` to make this tab discoverable:
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async onBackgroundService() {
+    const pageUrl = await window.weaveDOM.getPageUrl();
+
+    // Register this instance with metadata
+    const allInstances = await this.instances.register({
+      url: pageUrl,
+      startedAt: Date.now(),
+    });
+
+    console.log(`Total instances: ${allInstances.length}`);
+  }
+}
+```
+
+### Controller Election
+
+Only **one instance** can be controller at a time. Use this to decide which tab runs automations:
+
+```typescript
+// Try to become controller
+const claimed = await this.instances.claimController();
+if (claimed) {
+  console.log('This tab is the controller');
+  this.startAutomation();
+} else {
+  console.log('Another tab is already the controller');
+}
+
+// Check current controller
+const controller = await this.instances.getController();
+// Returns: { appId, tabId, url, isController, registeredAt, metadata } or null
+
+// Release controller (e.g., before page unload)
+await this.instances.releaseController();
+
+// Force-claim controller (takes over from current controller)
+await this.instances.claimController(true);
+```
+
+### Cross-Tab Messaging
+
+Send messages between instances of the same app:
+
+```typescript
+// Broadcast to ALL other instances
+await this.instances.broadcast({
+  type: 'WORKFLOW_STARTED',
+  data: { workflowName: 'daily-sync' },
+});
+
+// Send to the controller instance only
+await this.instances.sendToController({
+  type: 'REQUEST_STATUS',
+});
+
+// Send to a specific tab
+await this.instances.sendToTab(123, {
+  type: 'PING',
+});
+```
+
+### Listening for Messages & Changes
+
+```typescript
+// Listen for messages from other instances
+this.instances.onMessage((msg) => {
+  switch (msg.type) {
+    case 'WORKFLOW_STARTED':
+      console.log('Another tab started a workflow');
+      break;
+    case 'YIELD_CONTROL':
+      this.instances.releaseController();
+      break;
+  }
+});
+
+// Listen for instance changes (tab opened/closed)
+this.instances.onInstanceChange((instances) => {
+  console.log(`Now ${instances.length} instances`);
+
+  // Check if controller is still alive
+  const controller = instances.find((i) => i.isController);
+  if (!controller) {
+    // Controller tab was closed — claim control
+    this.instances.claimController();
+  }
+});
+```
+
+### Instance API Reference
+
+```typescript
+// Available via this.instances (WeaveAppInstanceAPI)
+
+// Register this tab — makes it discoverable
+await this.instances.register(metadata?: Record<string, any>): Promise<AppInstance[]>
+
+// Unregister this tab
+await this.instances.unregister(): Promise<void>
+
+// Get all instances of this app
+await this.instances.getInstances(): Promise<AppInstance[]>
+
+// Claim controller status (only one tab can be controller)
+await this.instances.claimController(force?: boolean): Promise<boolean>
+
+// Release controller status
+await this.instances.releaseController(): Promise<void>
+
+// Check if this tab is the controller
+await this.instances.isController(): Promise<boolean>
+
+// Get the current controller instance (or null)
+await this.instances.getController(): Promise<AppInstance | null>
+
+// Broadcast to all other instances of this app
+await this.instances.broadcast(message: { type: string; data?: any }): Promise<number[]>
+
+// Send to the controller instance
+await this.instances.sendToController(message: { type: string; data?: any }): Promise<number | null>
+
+// Send to a specific tab
+await this.instances.sendToTab(tabId: number, message: { type: string; data?: any }): Promise<boolean>
+
+// Listen for messages from other instances (returns unsubscribe function)
+this.instances.onMessage(callback: (msg: InstanceMessage) => void): () => void
+
+// Listen for instance list changes (returns unsubscribe function)
+this.instances.onInstanceChange(callback: (instances: AppInstance[]) => void): () => void
+
+// This tab's ID (available after register())
+this.instances.tabId: number | null
+```
+
+### AppInstance Structure
+
+```typescript
+interface AppInstance {
+  appId: string;                    // App identifier
+  tabId: number;                    // Chrome tab ID
+  url: string;                      // Page URL when registered
+  isController: boolean;            // Whether this instance is the controller
+  registeredAt: number;             // Timestamp of registration
+  metadata?: Record<string, any>;   // Custom data passed during register()
+}
+```
+
+### Best Practices
+
+#### ✅ DO:
+- Register in `onBackgroundService()` — this runs on every page load/reload
+- Use broadcast-based election (ask "who is controller?" before claiming)
+- Add jitter (random delay) when multiple tabs start simultaneously
+- Remove overlays/banners when yielding controller status
+- Handle `onInstanceChange` to detect when the controller tab closes
+
+#### ❌ DON'T:
+- Don't trust persisted `isController` state — always re-verify via the API or broadcast
+- Don't call `claimController()` without first checking if a live controller exists
+- Don't assume messages arrive in order — tabs may start at different times
+
+### Complete Example: Single-Controller Automation
+
+```typescript
+class AutoSyncApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'auto-sync',
+      name: 'Auto Sync',
+      version: '1.0.0',
+      category: 'automation',
+      description: 'Syncs data on a schedule — runs in only one tab',
+      author: 'Weave Team',
+      persistState: true,
+    });
+
+    this.state = { isController: false, syncCount: 0 };
+  }
+
+  async onBackgroundService() {
+    // Reset controller state — only register() may set it to true
+    this.setState({ isController: false });
+
+    await this.instances.register({ url: await window.weaveDOM.getPageUrl() });
+
+    // Listen for messages
+    this.instances.onMessage((msg) => {
+      if (msg.type === 'I_AM_CONTROLLER' && this.state.isController) {
+        // Another tab is also controller — yield to avoid duplicates
+        this.instances.releaseController();
+        this.setState({ isController: false });
+      }
+    });
+
+    // Listen for instance changes (e.g., controller tab closed)
+    this.instances.onInstanceChange((instances) => {
+      const controller = instances.find((i) => i.isController);
+      if (!controller) {
+        this.tryClaimController();
+      }
+    });
+
+    // Try to become controller
+    await this.tryClaimController();
+
+    if (this.state.isController) {
+      await this.cronTab('0 * * * * *', () => this.runSync(), 'sync');
+    }
+  }
+
+  private async tryClaimController(): Promise<void> {
+    // Ask if anyone is already controller
+    this.instances.broadcast({ type: 'WHO_IS_CONTROLLER' });
+
+    // Wait briefly for a response
+    await new Promise((r) => setTimeout(r, 2000));
+
+    // If no one answered, claim
+    const claimed = await this.instances.claimController();
+    if (claimed) {
+      this.setState({ isController: true });
+      this.instances.broadcast({ type: 'I_AM_CONTROLLER' });
+    }
+  }
+
+  private runSync(): void {
+    if (!this.state.isController) return;
+    this.setState({ syncCount: this.state.syncCount + 1 });
+    console.log(`Sync #${this.state.syncCount}`);
+  }
+}
+
+customElements.define('auto-sync', AutoSyncApp);
+```
+
+## Browser Extension Messaging (Advanced)
+
+### Overview
+
+Apps run inside an **iframe** within the browser extension's sidebar. The iframe cannot directly access Chrome extension APIs. However, apps can send messages to the **background service worker** via the content script relay. This unlocks capabilities that are impossible from within an iframe alone.
+
+### Message Flow
+
+```
+App (sidebar iframe)
+  │  window.parent.postMessage({ type: 'BG_*', requestId, payload })
+  ▼
+Content Script (BackgroundStateBridge)
+  │  Catches any message with type starting with 'BG_'
+  │  Forwards via chrome.runtime.sendMessage
+  ▼
+Background Service Worker (MessageHandler)
+  │  Processes the message (has full chrome.* API access)
+  │  Returns response
+  ▼
+Content Script
+  │  Wraps response in BG_STATE_RESPONSE
+  │  Posts back via window.postMessage
+  ▼
+App (sidebar iframe)
+  │  Matches response by requestId
+```
+
+### How to Send a Message
+
+All `BG_*` prefixed messages are automatically relayed by the `BackgroundStateBridge` content script. Your app sends via `window.parent.postMessage`:
+
+```typescript
+window.parent.postMessage(
+  {
+    type: 'BG_FOCUS_TAB',                      // Must start with 'BG_'
+    requestId: `my-request-${Date.now()}`,      // Unique ID for response matching
+    payload: { appId: 'my-app-id' },            // Must include appId
+  },
+  '*',
+);
+```
+
+**Required fields:**
+- **`type`** — Must start with `BG_` to be caught by the relay
+- **`requestId`** — Unique string for matching the response
+- **`payload.appId`** — Your app's ID (required by the bridge)
+
+### Available Background Messages
+
+#### `BG_FOCUS_TAB` — Focus This Browser Tab
+
+Brings the current tab **and its browser window** to the foreground. Essential when the app needs to grab the user's attention (e.g., prompting them to log in).
+
+```typescript
+// Focus this tab (bring to foreground, even from another window)
+window.parent.postMessage(
+  {
+    type: 'BG_FOCUS_TAB',
+    requestId: `focus-${Date.now()}`,
+    payload: { appId: 'my-app-id' },
+  },
+  '*',
+);
+```
+
+**What happens in the background:**
+```
+chrome.tabs.update(tabId, { active: true });    // Activate the tab
+chrome.windows.update(windowId, { focused: true }); // Focus the window
+```
+
+**Use cases:**
+- 🔐 User session expired → focus the login tab so they notice
+- ⚠️ Automation needs attention → bring the tab to the foreground
+- 🔔 Critical notification → ensure the user sees it
+
+#### `BG_SAVE_STATE` / `BG_LOAD_STATE` / `BG_CLEAR_STATE`
+
+These are used internally by the `persistState: true` feature and `this.background` API. You normally don't call these directly — use `this.setState()` or `this.background?.saveState()` instead.
+
+#### `BG_SET_PENDING_OP` / `BG_GET_PENDING_OP` / `BG_CLEAR_PENDING_OP`
+
+Used internally by `this.background?.setPendingOperation()`. You normally don't call these directly.
+
+### Example: Focus Tab on Login Page
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  async onBackgroundService() {
+    const loginPage = await this.detectLoginPage();
+
+    if (loginPage && this.state.isController) {
+      // Focus the tab so the user sees they need to log in
+      window.parent.postMessage(
+        {
+          type: 'BG_FOCUS_TAB',
+          requestId: `focus-${Date.now()}`,
+          payload: { appId: 'my-app-id' },
+        },
+        '*',
+      );
+
+      // Also inject a visual prompt
+      await window.weaveDOM.injectElement(
+        'body',
+        'beforeend',
+        '<div style="position:fixed;top:16px;left:50%;transform:translateX(-50%);z-index:999999;background:#dc2626;color:white;padding:14px 28px;border-radius:8px;font-family:system-ui;font-weight:600;pointer-events:none;">⚠️ Please log in to resume automatic sync</div>',
+        { elementId: 'login-notice' },
+      );
+    }
+  }
+
+  private async detectLoginPage(): Promise<boolean> {
+    const loginEl = await window.weaveDOM.query('.login-page');
+    return !!loginEl;
+  }
+}
+```
+
+### Best Practices
+
+#### ✅ DO:
+- Always include a unique `requestId` and `payload.appId`
+- Use `BG_FOCUS_TAB` sparingly — only when the user genuinely needs to act
+- Wrap in try/catch in case the content script relay isn't available
+- Prefer SDK methods (`this.background`, `this.instances`) over raw `postMessage` when available
+
+#### ❌ DON'T:
+- Don't send messages without the `BG_` prefix — they won't be relayed
+- Don't omit `requestId` or `payload.appId` — the bridge silently drops them
+- Don't spam `BG_FOCUS_TAB` in a loop — focus once, then wait for user action
+- Don't use raw `postMessage` for things the SDK already provides (state, cron, instances)
+
 ## Weave Backend API
 
 ### ⚠️ CRITICAL: API Access Restrictions
@@ -4418,6 +4822,18 @@ customElements.define('page-title-editor', PageTitleEditor);
 - **Element Injection:** `injectElement`, `removeInjectedElement`
 - **Element Listeners:** `startElementClickListener`, `stopElementClickListener`
 
+### Cross-Tab Instance API (`this.instances`)
+- **Registration:** `register`, `unregister`, `getInstances`
+- **Controller:** `claimController`, `releaseController`, `isController`, `getController`
+- **Messaging:** `broadcast`, `sendToController`, `sendToTab`
+- **Listeners:** `onMessage`, `onInstanceChange`
+- **Property:** `tabId` (available after `register()`)
+
+### Browser Extension Messaging (`window.parent.postMessage`)
+- **`BG_FOCUS_TAB`** — Focus this tab and its browser window (requires `requestId` + `payload.appId`)
+- **`BG_SAVE_STATE`** / **`BG_LOAD_STATE`** / **`BG_CLEAR_STATE`** — State persistence (prefer `this.background`)
+- **`BG_SET_PENDING_OP`** / **`BG_GET_PENDING_OP`** / **`BG_CLEAR_PENDING_OP`** — Pending ops (prefer `this.background`)
+
 ### Lifecycle
 1. `constructor()` - Initialize
 2. `connectedCallback()` - Added to DOM