@mcp-fe/mcp-worker 0.1.11 → 0.2.2

package/docs/multi-tab.md

@@ -1,637 +1,637 @@
-# Multi-Tab Support
-
-Comprehensive guide to multi-tab architecture and usage patterns.
-
-## Overview
-
-The MCP Worker library provides seamless multi-tab support with intelligent routing. Each browser tab can register tools independently, and the worker automatically routes tool calls to the appropriate tab.
-
-## Architecture
-
-### Tab Lifecycle
-
-```
-1. Tab Opens
-   └─> Generate UUID (crypto.randomUUID())
-   └─> Store in sessionStorage
-   └─> Register with worker (REGISTER_TAB)
-   └─> Mark as active (SET_ACTIVE_TAB)
-
-2. Tab Focus
-   └─> Update active tab (SET_ACTIVE_TAB)
-
-3. Tab Closes
-   └─> Tools remain available if other tabs have them
-   └─> Reference counting prevents premature unregistration
-```
-
-### Tab Registry
-
-The worker maintains a registry of all active tabs:
-
-```typescript
-{
-  tabId: string;        // UUID from crypto.randomUUID()
-  url: string;          // window.location.href
-  title: string;        // document.title
-  lastSeen: number;     // timestamp of last activity
-}
-```
-
-### Tool Registry Per Tab
-
-Tools are tracked per-tab using Sets:
-
-```typescript
-Map<ToolName, Set<TabId>>
-
-Example:
-{
-  "get_page_info": Set(["tab-abc", "tab-def"]),
-  "get_user_data": Set(["tab-abc"]),
-}
-```
-
-## Tool Lifecycle & Navigation
-
-### Automatic Cleanup
-
-Tools are **automatically unregistered** when:
-
-1. **Page navigation** (beforeunload event)
-2. **Page close** (pagehide event)
-3. **Page refresh** (F5)
-4. **Component unmount** (via React hooks like useMCPTool)
-
-```typescript
-// WorkerClient automatically handles cleanup
-window.addEventListener('beforeunload', () => {
-  // Unregister all tools from this tab
-  toolRegistry.forEach(tool => {
-    unregisterTool(tool.name, this.tabId);
-  });
-});
-```
-
-### How It Works
-
-**Registration:**
-```typescript
-// Tab A: Dashboard page
-await workerClient.registerTool('get_dashboard_data', ...);
-// → Worker: toolHandlersByTab.set('get_dashboard_data', Set([tabA]))
-```
-
-**Navigation (automatic cleanup):**
-```typescript
-// User navigates Tab A away from Dashboard
-// → beforeunload event fires
-// → WorkerClient.cleanupAllTools() called
-// → Sends: UNREGISTER_TOOL({ name: 'get_dashboard_data', tabId: tabA })
-// → Worker: toolHandlersByTab.get('get_dashboard_data').delete(tabA)
-```
-
-**Routing after navigation:**
-```typescript
-// Tab B still has 'get_dashboard_data' registered
-// AI calls: get_dashboard_data()
-// → Worker checks: tabA (active) has tool? NO
-// → Worker checks: other tabs have tool? YES (tabB)
-// → Routes to Tab B automatically ✓
-```
-
-### SPA Navigation Pattern
-
-In Single Page Applications, components mount/unmount frequently:
-
-```typescript
-// Dashboard component
-function DashboardPage() {
-  // Tool registers on mount
-  useMCPTool({
-    name: 'get_dashboard_data',
-    // ...
-  });
-  
-  // Tool unregisters on unmount (automatic!)
-  // - When user navigates to /settings
-  // - When component is destroyed
-  // - When route changes
-}
-```
-
-**Multi-tab behavior:**
-- Tab A: /dashboard → registers tool
-- Tab B: /dashboard → registers tool (refCount = 2)
-- Tab A navigates to /settings → unregisters tool (refCount = 1)
-- Tool still available via Tab B ✓
-
-### Edge Cases
-
-**All tabs lose tool:**
-```typescript
-// Both tabs on /dashboard
-Tab A: registers tool
-Tab B: registers tool
-
-// Both tabs navigate away
-Tab A → /settings (unregisters)
-Tab B → /profile (unregisters)
-
-// Tool completely unregistered from MCP
-get_dashboard_data()
-// → Error: "Tool not available"
-
-// User returns to /dashboard in Tab A
-// → Component mounts → registers tool again
-// → Tool available again ✓
-```
-
-**Refresh handling:**
-```typescript
-// Tab has tools registered
-// User presses F5
-
-// → beforeunload fires
-// → All tools unregistered
-// → Page reloads
-// → Components mount
-// → Tools registered again
-// → Tab ID preserved (sessionStorage)
-```
-
-### 1. Smart Routing (Default)
-
-Intelligent routing that prioritizes user intent and availability:
-
-```typescript
-// Priority order:
-1. Explicit tabId parameter (always respected)
-2. Only one tab has tool → route to it (regardless of focus)
-3. Active/focused tab has tool → use it
-4. Active tab doesn't have tool → use first available
-5. No active tab → use first available
-```
-
-**Example Scenarios:**
-
-**Scenario 1: Single tab with tool (most intuitive)**
-```typescript
-// Tab A (active): Has toolX
-// Tab B (inactive): Doesn't have toolX
-
-toolX()
-→ Routes to Tab A ✓ (active tab has it)
-
-// Now focus Tab B
-// Tab A (inactive): Has toolX
-// Tab B (active): Doesn't have toolX
-
-toolX()
-→ Routes to Tab A ✓ (only tab with tool, even though not active!)
-```
-
-**Scenario 2: Multiple tabs with tool**
-```typescript
-// Tab A (active): Has toolX
-// Tab B (inactive): Has toolX
-
-toolX()
-→ Routes to Tab A ✓ (active tab preferred when multiple available)
-
-// Now focus Tab B
-// Tab A (inactive): Has toolX
-// Tab B (active): Has toolX
-
-toolX()
-→ Routes to Tab B ✓ (new active tab)
-```
-
-**Scenario 3: Explicit targeting**
-```typescript
-// Tab A (active): Has toolX
-// Tab B (inactive): Has toolX
-
-toolX({ tabId: "tab-b-id" })
-→ Routes to Tab B ✓ (explicit parameter always wins)
-```
-
-**Scenario 4: Active tab loses tool (navigation)**
-```typescript
-// Initial state
-// Tab A (active): Has toolX
-// Tab B (inactive): Has toolX
-
-toolX()
-→ Routes to Tab A ✓ (active tab)
-
-// User navigates Tab A to different page
-// Tab A (active): No longer has toolX (page changed)
-// Tab B (inactive): Has toolX
-
-toolX()
-→ Routes to Tab B ✓ (active tab doesn't have tool, auto-fallback!)
-// No error, seamless transition
-```
-
-**Visual Flow:**
-```
-Before Navigation:
-┌─────────────┐         ┌─────────────┐
-│  Tab A      │ Active  │  Tab B      │
-│  /dashboard │   ✓     │  /dashboard │
-│  has toolX  │         │  has toolX  │
-└─────────────┘         └─────────────┘
-       ↑
-   toolX() routes here
-
-After Navigation (Tab A → /settings):
-┌─────────────┐         ┌─────────────┐
-│  Tab A      │ Active  │  Tab B      │
-│  /settings  │   ✓     │  /dashboard │
-│  NO toolX   │         │  has toolX  │
-└─────────────┘         └─────────────┘
-                              ↑
-                    toolX() auto-routes here!
-```
-
-This ensures tools continue to work even when the user navigates away from pages that provided specific tools.
-
-### 2. Built-in Discovery Tool
-
-`list_browser_tabs` provides tab discovery:
-
-```typescript
-// Always returns current tab state
-const tabs = await list_browser_tabs();
-
-[
-  {
-    tabId: "550e8400-e29b-41d4-a716-446655440000",
-    url: "https://app.example.com/dashboard",
-    title: "Dashboard - My App",
-    isActive: true,
-    lastSeen: "2026-02-04T10:30:00.000Z"
-  },
-  {
-    tabId: "6fa459ea-ee8a-3ca4-894e-db77e160355e",
-    url: "https://app.example.com/settings",
-    title: "Settings - My App",
-    isActive: false,
-    lastSeen: "2026-02-04T10:29:45.000Z"
-  }
-]
-```
-
-## Tool Schema Enhancement
-
-All registered tools automatically receive an optional `tabId` parameter:
-
-**Original Schema:**
-```json
-{
-  "type": "object",
-  "properties": {
-    "username": { "type": "string" }
-  }
-}
-```
-
-**Enhanced Schema:**
-```json
-{
-  "type": "object",
-  "properties": {
-    "username": { "type": "string" },
-    "tabId": {
-      "type": "string",
-      "description": "Optional: Target specific tab by ID. If not provided, uses the currently focused tab. Use list_browser_tabs to discover available tabs."
-    }
-  }
-}
-```
-
-The `tabId` parameter is automatically added by the library - you don't need to include it in your schema.
-
-## Use Cases
-
-### 1. Debugging Specific Tab
-
-AI can debug a specific tab while user works in another:
-
-```
-User: "Check the state of the Settings tab"
-
-AI:
-1. list_browser_tabs()
-   → Finds Settings tab ID: "6fa459ea..."
-
-2. get_react_state({ tabId: "6fa459ea..." })
-   → Gets state from Settings tab
-
-3. analyze_component({ tabId: "6fa459ea...", component: "UserForm" })
-   → Analyzes specific component
-```
-
-### 2. Cross-Tab Comparison
-
-Compare state/data across multiple tabs:
-
-```typescript
-const tabs = await list_browser_tabs();
-
-const states = await Promise.all(
-  tabs.map(tab => 
-    get_react_state({ tabId: tab.tabId })
-  )
-);
-
-// Compare states across tabs
-```
-
-### 3. Focus-Driven Interaction
-
-Natural interaction with focused tab:
-
-```
-User: "What's on this page?"
-AI: get_page_info()  // No tabId needed
-→ Automatically uses focused tab
-```
-
-### 4. Multi-Screen Workflows
-
-User has multiple monitors with different tabs:
-
-```
-Monitor 1: Dashboard (focused)
-Monitor 2: Analytics
-Monitor 3: Settings
-
-// AI can work with any tab
-get_metrics({ tabId: "analytics-tab" })      // Monitor 2
-update_settings({ tabId: "settings-tab" })   // Monitor 3
-show_alert()                                  // Monitor 1 (focused)
-```
-
-## Reference Counting
-
-Tools use reference counting to handle multiple registrations:
-
-```typescript
-// Tab 1 registers tool
-workerClient.registerTool('get_data', ...)
-// → Registered with MCP, refCount = 1
-
-// Tab 2 registers same tool
-workerClient.registerTool('get_data', ...)
-// → NOT re-registered with MCP, refCount = 2
-
-// Tab 1 closes/unregisters
-workerClient.unregisterTool('get_data')
-// → NOT unregistered from MCP, refCount = 1
-
-// Tab 2 closes/unregisters
-workerClient.unregisterTool('get_data')
-// → Unregistered from MCP, refCount = 0
-```
-
-## Tab Persistence
-
-### SessionStorage Persistence
-
-Tab IDs are stored in `sessionStorage`, which means:
-
-- ✅ **Page refresh (F5)**: Tab keeps same ID
-- ✅ **Navigation**: Tab keeps same ID
-- ❌ **Duplicate tab**: New tab gets new ID
-- ❌ **New window**: New window gets new ID
-- ❌ **Private/Incognito**: Each session independent
-
-### Tab ID Format
-
-```typescript
-// UUID v4 from crypto.randomUUID()
-"550e8400-e29b-41d4-a716-446655440000"
-
-// Fallback if crypto unavailable
-"fallback_1738668000000_xyz123"
-```
-
-## Error Handling
-
-### Tab Not Found
-
-```typescript
-get_page_info({ tabId: "invalid-id" })
-
-// Error response:
-{
-  error: "Tool 'get_page_info' not available in tab 'invalid-id'. Available tabs: tab-1, tab-2"
-}
-```
-
-### No Active Tab
-
-```typescript
-// All tabs minimized/backgrounded
-get_page_info()  // No tabId, no active tab
-
-// Behavior: Uses first available tab + warning log
-// Better than error - tool still works
-```
-
-### Tool Not Registered
-
-```typescript
-// Tab 1: Registers tool A
-// Tab 2: Registers tool B
-
-get_tool_b({ tabId: "tab-1" })
-
-// Error:
-{
-  error: "Tool 'get_tool_b' not available in tab 'tab-1'. Available tabs: tab-2"
-}
-```
-
-## API Reference
-
-### WorkerClient Methods
-
-#### `getTabId(): string`
-
-Get the unique ID of the current tab.
-
-```typescript
-const tabId = workerClient.getTabId();
-console.log(tabId); // "550e8400-e29b-41d4-a716-446655440000"
-```
-
-#### `getTabInfo(): TabInfo`
-
-Get info about current tab (for debugging).
-
-```typescript
-const info = workerClient.getTabInfo();
-// {
-//   tabId: "550e8400-...",
-//   url: "https://app.example.com/dashboard",
-//   title: "Dashboard - My App"
-// }
-```
-
-> **Note:** To check which tab is currently active, use the `list_browser_tabs` tool which queries the worker's `TabManager` (the authoritative source).
-
-#### `static clearTabId(): void`
-
-Clear tab ID from sessionStorage (for testing).
-
-```typescript
-WorkerClient.clearTabId();
-// Refresh page to generate new ID
-```
-
-### MCPController Methods
-
-#### `handleRegisterTab(data): void`
-
-Register a tab with the worker (called automatically).
-
-#### `handleSetActiveTab(data): void`
-
-Update active tab tracking (called automatically).
-
-## Best Practices
-
-### 1. Let Auto-Routing Work
-
-Don't pass `tabId` unless you need to target a specific tab:
-
-```typescript
-// ✅ Good - natural interaction
-get_page_info()
-
-// ❌ Unnecessary - harder to use
-get_page_info({ tabId: workerClient.getTabId() })
-```
-
-### 2. Use Discovery When Needed
-
-Use `list_browser_tabs` when you need tab-specific operations:
-
-```typescript
-// ✅ Good - explicit discovery
-const tabs = await list_browser_tabs();
-const settingsTab = tabs.find(t => t.url.includes('/settings'));
-await get_state({ tabId: settingsTab.tabId });
-
-// ❌ Bad - guessing tab IDs
-await get_state({ tabId: "some-random-id" });
-```
-
-### 3. Design Stateless Tools
-
-Prefer tools that don't depend heavily on local component state:
-
-```typescript
-// ✅ Good - API calls work from any tab
-registerTool('fetch_user', async (args) => {
-  const response = await fetch(`/api/users/${args.id}`);
-  return { content: [{ type: 'text', text: await response.text() }] };
-});
-
-// ⚠️ Be aware - local state might differ per tab
-registerTool('get_form_state', async () => {
-  const formState = useFormStore.getState(); // Different per tab
-  return { content: [{ type: 'text', text: JSON.stringify(formState) }] };
-});
-```
-
-### 4. Document Tab-Specific Behavior
-
-If your tool behaves differently per tab, document it:
-
-```typescript
-registerTool(
-  'get_user_preferences',
-  'Get user preferences from current tab context. NOTE: Preferences may differ per tab if user is editing in multiple tabs.',
-  schema,
-  handler
-);
-```
-
-## Migration from Single-Tab
-
-Existing single-tab code works without changes:
-
-```typescript
-// Before (single-tab)
-await workerClient.registerTool('my_tool', ...);
-
-// After (multi-tab) - same code works!
-await workerClient.registerTool('my_tool', ...);
-// Now works across multiple tabs automatically
-```
-
-The `tabId` parameter is optional, so existing tools continue to work with the focused tab.
-
-## Troubleshooting
-
-### Issue: Tool calls go to wrong tab
-
-**Solution**: Use `list_browser_tabs` to verify which tab you're targeting:
-
-```typescript
-const tabs = await list_browser_tabs();
-console.log(tabs);
-// Find the correct tabId
-```
-
-### Issue: Tab ID changes on refresh
-
-**Check**: SessionStorage might be disabled (private mode)
-
-```typescript
-// Test sessionStorage
-try {
-  sessionStorage.setItem('test', '1');
-  sessionStorage.removeItem('test');
-  console.log('SessionStorage works ✓');
-} catch {
-  console.log('SessionStorage blocked ✗');
-  // Fallback ID will be used (changes on refresh)
-}
-```
-
-### Issue: Multiple tabs show same tool registered multiple times
-
-**This is expected**: Reference counting means:
-- Tool registered once with MCP
-- Multiple tabs can have handlers
-- Worker routes to correct tab automatically
-
-## Performance
-
-Multi-tab adds minimal overhead:
-
-- Tab registration: ~1ms
-- Tab routing: ~0.1ms (Map lookup)
-- Memory per tab: ~100 bytes (tab info)
-
-Total overhead for 10 tabs: < 1ms + 1KB memory
-
-## Security
-
-Tab IDs are not secret:
-- Used for routing only
-- No authentication/authorization
-- All tabs in same browser share worker
-
-Do not use tab IDs as security tokens.
-
-## See Also
-
-- [Architecture](./architecture.md) - Detailed architecture diagrams
-- [Guide](./guide.md) - General usage guide
-- [API Reference](./api.md) - Complete API documentation
+# Multi-Tab Support
+
+Comprehensive guide to multi-tab architecture and usage patterns.
+
+## Overview
+
+The MCP Worker library provides seamless multi-tab support with intelligent routing. Each browser tab can register tools independently, and the worker automatically routes tool calls to the appropriate tab.
+
+## Architecture
+
+### Tab Lifecycle
+
+```
+1. Tab Opens
+   └─> Generate UUID (crypto.randomUUID())
+   └─> Store in sessionStorage
+   └─> Register with worker (REGISTER_TAB)
+   └─> Mark as active (SET_ACTIVE_TAB)
+
+2. Tab Focus
+   └─> Update active tab (SET_ACTIVE_TAB)
+
+3. Tab Closes
+   └─> Tools remain available if other tabs have them
+   └─> Reference counting prevents premature unregistration
+```
+
+### Tab Registry
+
+The worker maintains a registry of all active tabs:
+
+```typescript
+{
+  tabId: string;        // UUID from crypto.randomUUID()
+  url: string;          // window.location.href
+  title: string;        // document.title
+  lastSeen: number;     // timestamp of last activity
+}
+```
+
+### Tool Registry Per Tab
+
+Tools are tracked per-tab using Sets:
+
+```typescript
+Map<ToolName, Set<TabId>>
+
+Example:
+{
+  "get_page_info": Set(["tab-abc", "tab-def"]),
+  "get_user_data": Set(["tab-abc"]),
+}
+```
+
+## Tool Lifecycle & Navigation
+
+### Automatic Cleanup
+
+Tools are **automatically unregistered** when:
+
+1. **Page navigation** (beforeunload event)
+2. **Page close** (pagehide event)
+3. **Page refresh** (F5)
+4. **Component unmount** (via React hooks like useMCPTool)
+
+```typescript
+// WorkerClient automatically handles cleanup
+window.addEventListener('beforeunload', () => {
+  // Unregister all tools from this tab
+  toolRegistry.forEach(tool => {
+    unregisterTool(tool.name, this.tabId);
+  });
+});
+```
+
+### How It Works
+
+**Registration:**
+```typescript
+// Tab A: Dashboard page
+await workerClient.registerTool('get_dashboard_data', ...);
+// → Worker: toolHandlersByTab.set('get_dashboard_data', Set([tabA]))
+```
+
+**Navigation (automatic cleanup):**
+```typescript
+// User navigates Tab A away from Dashboard
+// → beforeunload event fires
+// → WorkerClient.cleanupAllTools() called
+// → Sends: UNREGISTER_TOOL({ name: 'get_dashboard_data', tabId: tabA })
+// → Worker: toolHandlersByTab.get('get_dashboard_data').delete(tabA)
+```
+
+**Routing after navigation:**
+```typescript
+// Tab B still has 'get_dashboard_data' registered
+// AI calls: get_dashboard_data()
+// → Worker checks: tabA (active) has tool? NO
+// → Worker checks: other tabs have tool? YES (tabB)
+// → Routes to Tab B automatically ✓
+```
+
+### SPA Navigation Pattern
+
+In Single Page Applications, components mount/unmount frequently:
+
+```typescript
+// Dashboard component
+function DashboardPage() {
+  // Tool registers on mount
+  useMCPTool({
+    name: 'get_dashboard_data',
+    // ...
+  });
+  
+  // Tool unregisters on unmount (automatic!)
+  // - When user navigates to /settings
+  // - When component is destroyed
+  // - When route changes
+}
+```
+
+**Multi-tab behavior:**
+- Tab A: /dashboard → registers tool
+- Tab B: /dashboard → registers tool (refCount = 2)
+- Tab A navigates to /settings → unregisters tool (refCount = 1)
+- Tool still available via Tab B ✓
+
+### Edge Cases
+
+**All tabs lose tool:**
+```typescript
+// Both tabs on /dashboard
+Tab A: registers tool
+Tab B: registers tool
+
+// Both tabs navigate away
+Tab A → /settings (unregisters)
+Tab B → /profile (unregisters)
+
+// Tool completely unregistered from MCP
+get_dashboard_data()
+// → Error: "Tool not available"
+
+// User returns to /dashboard in Tab A
+// → Component mounts → registers tool again
+// → Tool available again ✓
+```
+
+**Refresh handling:**
+```typescript
+// Tab has tools registered
+// User presses F5
+
+// → beforeunload fires
+// → All tools unregistered
+// → Page reloads
+// → Components mount
+// → Tools registered again
+// → Tab ID preserved (sessionStorage)
+```
+
+### 1. Smart Routing (Default)
+
+Intelligent routing that prioritizes user intent and availability:
+
+```typescript
+// Priority order:
+1. Explicit tabId parameter (always respected)
+2. Only one tab has tool → route to it (regardless of focus)
+3. Active/focused tab has tool → use it
+4. Active tab doesn't have tool → use first available
+5. No active tab → use first available
+```
+
+**Example Scenarios:**
+
+**Scenario 1: Single tab with tool (most intuitive)**
+```typescript
+// Tab A (active): Has toolX
+// Tab B (inactive): Doesn't have toolX
+
+toolX()
+→ Routes to Tab A ✓ (active tab has it)
+
+// Now focus Tab B
+// Tab A (inactive): Has toolX
+// Tab B (active): Doesn't have toolX
+
+toolX()
+→ Routes to Tab A ✓ (only tab with tool, even though not active!)
+```
+
+**Scenario 2: Multiple tabs with tool**
+```typescript
+// Tab A (active): Has toolX
+// Tab B (inactive): Has toolX
+
+toolX()
+→ Routes to Tab A ✓ (active tab preferred when multiple available)
+
+// Now focus Tab B
+// Tab A (inactive): Has toolX
+// Tab B (active): Has toolX
+
+toolX()
+→ Routes to Tab B ✓ (new active tab)
+```
+
+**Scenario 3: Explicit targeting**
+```typescript
+// Tab A (active): Has toolX
+// Tab B (inactive): Has toolX
+
+toolX({ tabId: "tab-b-id" })
+→ Routes to Tab B ✓ (explicit parameter always wins)
+```
+
+**Scenario 4: Active tab loses tool (navigation)**
+```typescript
+// Initial state
+// Tab A (active): Has toolX
+// Tab B (inactive): Has toolX
+
+toolX()
+→ Routes to Tab A ✓ (active tab)
+
+// User navigates Tab A to different page
+// Tab A (active): No longer has toolX (page changed)
+// Tab B (inactive): Has toolX
+
+toolX()
+→ Routes to Tab B ✓ (active tab doesn't have tool, auto-fallback!)
+// No error, seamless transition
+```
+
+**Visual Flow:**
+```
+Before Navigation:
+┌─────────────┐         ┌─────────────┐
+│  Tab A      │ Active  │  Tab B      │
+│  /dashboard │   ✓     │  /dashboard │
+│  has toolX  │         │  has toolX  │
+└─────────────┘         └─────────────┘
+       ↑
+   toolX() routes here
+
+After Navigation (Tab A → /settings):
+┌─────────────┐         ┌─────────────┐
+│  Tab A      │ Active  │  Tab B      │
+│  /settings  │   ✓     │  /dashboard │
+│  NO toolX   │         │  has toolX  │
+└─────────────┘         └─────────────┘
+                              ↑
+                    toolX() auto-routes here!
+```
+
+This ensures tools continue to work even when the user navigates away from pages that provided specific tools.
+
+### 2. Built-in Discovery Tool
+
+`list_browser_tabs` provides tab discovery:
+
+```typescript
+// Always returns current tab state
+const tabs = await list_browser_tabs();
+
+[
+  {
+    tabId: "550e8400-e29b-41d4-a716-446655440000",
+    url: "https://app.example.com/dashboard",
+    title: "Dashboard - My App",
+    isActive: true,
+    lastSeen: "2026-02-04T10:30:00.000Z"
+  },
+  {
+    tabId: "6fa459ea-ee8a-3ca4-894e-db77e160355e",
+    url: "https://app.example.com/settings",
+    title: "Settings - My App",
+    isActive: false,
+    lastSeen: "2026-02-04T10:29:45.000Z"
+  }
+]
+```
+
+## Tool Schema Enhancement
+
+All registered tools automatically receive an optional `tabId` parameter:
+
+**Original Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "username": { "type": "string" }
+  }
+}
+```
+
+**Enhanced Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "username": { "type": "string" },
+    "tabId": {
+      "type": "string",
+      "description": "Optional: Target specific tab by ID. If not provided, uses the currently focused tab. Use list_browser_tabs to discover available tabs."
+    }
+  }
+}
+```
+
+The `tabId` parameter is automatically added by the library - you don't need to include it in your schema.
+
+## Use Cases
+
+### 1. Debugging Specific Tab
+
+AI can debug a specific tab while user works in another:
+
+```
+User: "Check the state of the Settings tab"
+
+AI:
+1. list_browser_tabs()
+   → Finds Settings tab ID: "6fa459ea..."
+
+2. get_react_state({ tabId: "6fa459ea..." })
+   → Gets state from Settings tab
+
+3. analyze_component({ tabId: "6fa459ea...", component: "UserForm" })
+   → Analyzes specific component
+```
+
+### 2. Cross-Tab Comparison
+
+Compare state/data across multiple tabs:
+
+```typescript
+const tabs = await list_browser_tabs();
+
+const states = await Promise.all(
+  tabs.map(tab => 
+    get_react_state({ tabId: tab.tabId })
+  )
+);
+
+// Compare states across tabs
+```
+
+### 3. Focus-Driven Interaction
+
+Natural interaction with focused tab:
+
+```
+User: "What's on this page?"
+AI: get_page_info()  // No tabId needed
+→ Automatically uses focused tab
+```
+
+### 4. Multi-Screen Workflows
+
+User has multiple monitors with different tabs:
+
+```
+Monitor 1: Dashboard (focused)
+Monitor 2: Analytics
+Monitor 3: Settings
+
+// AI can work with any tab
+get_metrics({ tabId: "analytics-tab" })      // Monitor 2
+update_settings({ tabId: "settings-tab" })   // Monitor 3
+show_alert()                                  // Monitor 1 (focused)
+```
+
+## Reference Counting
+
+Tools use reference counting to handle multiple registrations:
+
+```typescript
+// Tab 1 registers tool
+workerClient.registerTool('get_data', ...)
+// → Registered with MCP, refCount = 1
+
+// Tab 2 registers same tool
+workerClient.registerTool('get_data', ...)
+// → NOT re-registered with MCP, refCount = 2
+
+// Tab 1 closes/unregisters
+workerClient.unregisterTool('get_data')
+// → NOT unregistered from MCP, refCount = 1
+
+// Tab 2 closes/unregisters
+workerClient.unregisterTool('get_data')
+// → Unregistered from MCP, refCount = 0
+```
+
+## Tab Persistence
+
+### SessionStorage Persistence
+
+Tab IDs are stored in `sessionStorage`, which means:
+
+- ✅ **Page refresh (F5)**: Tab keeps same ID
+- ✅ **Navigation**: Tab keeps same ID
+- ❌ **Duplicate tab**: New tab gets new ID
+- ❌ **New window**: New window gets new ID
+- ❌ **Private/Incognito**: Each session independent
+
+### Tab ID Format
+
+```typescript
+// UUID v4 from crypto.randomUUID()
+"550e8400-e29b-41d4-a716-446655440000"
+
+// Fallback if crypto unavailable
+"fallback_1738668000000_xyz123"
+```
+
+## Error Handling
+
+### Tab Not Found
+
+```typescript
+get_page_info({ tabId: "invalid-id" })
+
+// Error response:
+{
+  error: "Tool 'get_page_info' not available in tab 'invalid-id'. Available tabs: tab-1, tab-2"
+}
+```
+
+### No Active Tab
+
+```typescript
+// All tabs minimized/backgrounded
+get_page_info()  // No tabId, no active tab
+
+// Behavior: Uses first available tab + warning log
+// Better than error - tool still works
+```
+
+### Tool Not Registered
+
+```typescript
+// Tab 1: Registers tool A
+// Tab 2: Registers tool B
+
+get_tool_b({ tabId: "tab-1" })
+
+// Error:
+{
+  error: "Tool 'get_tool_b' not available in tab 'tab-1'. Available tabs: tab-2"
+}
+```
+
+## API Reference
+
+### WorkerClient Methods
+
+#### `getTabId(): string`
+
+Get the unique ID of the current tab.
+
+```typescript
+const tabId = workerClient.getTabId();
+console.log(tabId); // "550e8400-e29b-41d4-a716-446655440000"
+```
+
+#### `getTabInfo(): TabInfo`
+
+Get info about current tab (for debugging).
+
+```typescript
+const info = workerClient.getTabInfo();
+// {
+//   tabId: "550e8400-...",
+//   url: "https://app.example.com/dashboard",
+//   title: "Dashboard - My App"
+// }
+```
+
+> **Note:** To check which tab is currently active, use the `list_browser_tabs` tool which queries the worker's `TabManager` (the authoritative source).
+
+#### `static clearTabId(): void`
+
+Clear tab ID from sessionStorage (for testing).
+
+```typescript
+WorkerClient.clearTabId();
+// Refresh page to generate new ID
+```
+
+### MCPController Methods
+
+#### `handleRegisterTab(data): void`
+
+Register a tab with the worker (called automatically).
+
+#### `handleSetActiveTab(data): void`
+
+Update active tab tracking (called automatically).
+
+## Best Practices
+
+### 1. Let Auto-Routing Work
+
+Don't pass `tabId` unless you need to target a specific tab:
+
+```typescript
+// ✅ Good - natural interaction
+get_page_info()
+
+// ❌ Unnecessary - harder to use
+get_page_info({ tabId: workerClient.getTabId() })
+```
+
+### 2. Use Discovery When Needed
+
+Use `list_browser_tabs` when you need tab-specific operations:
+
+```typescript
+// ✅ Good - explicit discovery
+const tabs = await list_browser_tabs();
+const settingsTab = tabs.find(t => t.url.includes('/settings'));
+await get_state({ tabId: settingsTab.tabId });
+
+// ❌ Bad - guessing tab IDs
+await get_state({ tabId: "some-random-id" });
+```
+
+### 3. Design Stateless Tools
+
+Prefer tools that don't depend heavily on local component state:
+
+```typescript
+// ✅ Good - API calls work from any tab
+registerTool('fetch_user', async (args) => {
+  const response = await fetch(`/api/users/${args.id}`);
+  return { content: [{ type: 'text', text: await response.text() }] };
+});
+
+// ⚠️ Be aware - local state might differ per tab
+registerTool('get_form_state', async () => {
+  const formState = useFormStore.getState(); // Different per tab
+  return { content: [{ type: 'text', text: JSON.stringify(formState) }] };
+});
+```
+
+### 4. Document Tab-Specific Behavior
+
+If your tool behaves differently per tab, document it:
+
+```typescript
+registerTool(
+  'get_user_preferences',
+  'Get user preferences from current tab context. NOTE: Preferences may differ per tab if user is editing in multiple tabs.',
+  schema,
+  handler
+);
+```
+
+## Migration from Single-Tab
+
+Existing single-tab code works without changes:
+
+```typescript
+// Before (single-tab)
+await workerClient.registerTool('my_tool', ...);
+
+// After (multi-tab) - same code works!
+await workerClient.registerTool('my_tool', ...);
+// Now works across multiple tabs automatically
+```
+
+The `tabId` parameter is optional, so existing tools continue to work with the focused tab.
+
+## Troubleshooting
+
+### Issue: Tool calls go to wrong tab
+
+**Solution**: Use `list_browser_tabs` to verify which tab you're targeting:
+
+```typescript
+const tabs = await list_browser_tabs();
+console.log(tabs);
+// Find the correct tabId
+```
+
+### Issue: Tab ID changes on refresh
+
+**Check**: SessionStorage might be disabled (private mode)
+
+```typescript
+// Test sessionStorage
+try {
+  sessionStorage.setItem('test', '1');
+  sessionStorage.removeItem('test');
+  console.log('SessionStorage works ✓');
+} catch {
+  console.log('SessionStorage blocked ✗');
+  // Fallback ID will be used (changes on refresh)
+}
+```
+
+### Issue: Multiple tabs show same tool registered multiple times
+
+**This is expected**: Reference counting means:
+- Tool registered once with MCP
+- Multiple tabs can have handlers
+- Worker routes to correct tab automatically
+
+## Performance
+
+Multi-tab adds minimal overhead:
+
+- Tab registration: ~1ms
+- Tab routing: ~0.1ms (Map lookup)
+- Memory per tab: ~100 bytes (tab info)
+
+Total overhead for 10 tabs: < 1ms + 1KB memory
+
+## Security
+
+Tab IDs are not secret:
+- Used for routing only
+- No authentication/authorization
+- All tabs in same browser share worker
+
+Do not use tab IDs as security tokens.
+
+## See Also
+
+- [Architecture](./architecture.md) - Detailed architecture diagrams
+- [Guide](./guide.md) - General usage guide
+- [API Reference](./api.md) - Complete API documentation