ultimate-playwright-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2025 Patrick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This software includes code extracted from OpenClaw (https://github.com/openclaw/openclaw),
+which is also MIT licensed. See individual source files for attribution.

package/README.md

@@ -0,0 +1,286 @@
+# Ultimate Playwright MCP
+
+Multi-agent Playwright MCP server with tab isolation via `targetId`. Allows multiple Claude instances (or other MCP clients) to share a single Chrome browser while maintaining isolated tab groups.
+
+## Features
+
+- ✅ **Tab Isolation** - Each agent gets its own tabs via unique `targetId`
+- ✅ **Shared Cookies** - All agents share the same BrowserContext (cookies, sessions, localStorage)
+- ✅ **Parallel Execution** - Multiple agents can operate simultaneously without interference
+- ✅ **CDP Connection** - Connects to existing Chrome via Chrome DevTools Protocol
+- ✅ **Battle-Tested** - Extracted from [OpenClaw](https://github.com/openclaw/openclaw) (MIT licensed)
+
+## Installation
+
+```bash
+npm install -g ultimate-playwright-mcp
+```
+
+Or run directly with npx:
+
+```bash
+npx ultimate-playwright-mcp --cdp-endpoint http://localhost:9222
+```
+
+## Quick Start
+
+### 1. Launch Chrome with Remote Debugging
+
+```bash
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-debug
+
+# Linux
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
+
+# Windows
+"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" ^
+  --remote-debugging-port=9222 ^
+  --user-data-dir=C:\\temp\\chrome-debug
+```
+
+### 2. Configure Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ultimate-playwright": {
+      "command": "npx",
+      "args": [
+        "ultimate-playwright-mcp",
+        "--cdp-endpoint",
+        "http://localhost:9222"
+      ]
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+Claude will now have access to browser control tools with tab isolation.
+
+## Usage Example
+
+```
+User: Open two tabs and navigate them independently
+
+Claude: I'll create two tabs with separate targetIds:
+
+1. browser_tabs({ action: "new" })
+   → **targetId: ABC123...**
+
+2. browser_tabs({ action: "new" })
+   → **targetId: XYZ789...**
+
+3. browser_navigate({ targetId: "ABC123...", url: "https://github.com" })
+4. browser_navigate({ targetId: "XYZ789...", url: "https://google.com" })
+
+Both tabs are now navigated independently!
+```
+
+## Available Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `browser_tab_group` | Create/list/delete tab groups for isolation | `action`, `name`, `color`, `groupId` |
+| `browser_tabs` | List, create, close, or select tabs | `action`, `groupId`, `targetId`, `index` |
+| `browser_navigate` | Navigate to a URL | `url`, `targetId` |
+| `browser_snapshot` | Capture accessibility tree with refs | `targetId` |
+| `browser_click` | Click an element | `ref`, `targetId` |
+| `browser_type` | Type text into an element | `ref`, `text`, `targetId` |
+| `browser_hover` | Hover over an element | `ref`, `targetId` |
+| `browser_press_key` | Press a keyboard key | `key`, `targetId` |
+| `browser_fill_form` | Fill multiple form fields | `fields`, `targetId` |
+| `browser_wait_for` | Wait for conditions | `text`, `selector`, `url`, `loadState`, `targetId` |
+
+## Tab Groups (Multi-User Isolation)
+
+When multiple users or agents share one browser instance, tab groups keep everyone's
+tabs isolated. Each session creates its own group, and all tab operations are scoped
+to that group.
+
+```
+User: Research product pricing
+
+Claude: I'll create a tab group first, then open tabs within it.
+
+1. browser_tab_group({ action: "create", name: "pricing-research", color: "blue" })
+   → **groupId: g_a1b2c3d4e5f6**
+
+2. browser_tabs({ action: "new", groupId: "g_a1b2c3d4e5f6", url: "https://example.com/pricing" })
+   → **targetId: ABC123...**
+
+3. browser_tabs({ action: "list", groupId: "g_a1b2c3d4e5f6" })
+   → Only shows tabs in this group (not other users' tabs)
+```
+
+Meanwhile, another user on the same server:
+
+```
+1. browser_tab_group({ action: "create", name: "docs-review", color: "green" })
+   → **groupId: g_x9y8z7w6v5u4**
+
+2. browser_tabs({ action: "new", groupId: "g_x9y8z7w6v5u4", url: "https://docs.example.com" })
+   → **targetId: XYZ789...**
+```
+
+Both users share the same cookies/sessions but only see their own tabs!
+
+### Tab Group Lifecycle
+
+1. **Create** a group at the start of your session
+2. **Open tabs** within the group using `groupId`
+3. **Work** with tabs using `targetId` as before
+4. **Delete** the group when done (optionally closes all tabs)
+
+Group state is persisted to `~/.ultimate-playwright-mcp/tab-groups.json` so it
+survives MCP server restarts.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│        Single Chrome Process                │
+│    (--remote-debugging-port=9222)           │
+│  ┌─────────────────────────────────────┐   │
+│  │     Single BrowserContext            │   │
+│  │  (shared cookies, storage)           │   │
+│  │                                      │   │
+│  │  Group: alice (blue)                 │   │
+│  │  ┌─────┐ ┌─────┐                    │   │
+│  │  │ Tab │ │ Tab │                    │   │
+│  │  │  A  │ │  B  │                    │   │
+│  │  └─────┘ └─────┘                    │   │
+│  │                                      │   │
+│  │  Group: bob (green)                  │   │
+│  │  ┌─────┐ ┌─────┐ ┌─────┐            │   │
+│  │  │ Tab │ │ Tab │ │ Tab │            │   │
+│  │  │  C  │ │  D  │ │  E  │            │   │
+│  │  └─────┘ └─────┘ └─────┘            │   │
+│  └─────────────────────────────────────┘   │
+└─────────────────────────────────────────────┘
+                   ↑
+           CDP Connection
+                   ↓
+┌─────────────────────────────────────────────┐
+│    ultimate-playwright-mcp (MCP Server)     │
+│    - Tab routing via targetId               │
+│    - Tab groups via groupId                 │
+│    - Shared ownership registry (JSON file)  │
+│    - Stdio transport                        │
+└─────────────────────────────────────────────┘
+         ↓           ↓           ↓
+   ┌─────────┐ ┌─────────┐ ┌─────────┐
+   │ Alice   │ │  Bob    │ │ Charlie │
+   │ (Claude)│ │ (Claude)│ │ (Cursor)│
+   └─────────┘ └─────────┘ └─────────┘
+```
+
+## CLI Options
+
+```bash
+ultimate-playwright-mcp [options]
+
+Options:
+  --cdp-endpoint <url>  CDP endpoint URL (e.g., http://localhost:9222)
+                        Can also use CDP_ENDPOINT env var
+  --agent-id <id>       Optional agent ID for logging/debugging
+                        Can also use AGENT_ID env var
+  -V, --version         Output version number
+  -h, --help            Display help
+```
+
+## Multi-Agent Setup
+
+### Running Multiple Claude Code Instances
+
+Each instance connects to the same MCP server and gets isolated tabs:
+
+**Terminal 1:**
+```bash
+claude-code --mcp-config ./mcp-config.json
+# Agent A creates tabs with targetIds starting from ABC...
+```
+
+**Terminal 2:**
+```bash
+claude-code --mcp-config ./mcp-config.json
+# Agent B creates tabs with targetIds starting from XYZ...
+```
+
+Both agents share cookies and sessions but operate on different tabs!
+
+## Persistent Chrome Setup (macOS)
+
+For a Chrome instance that auto-starts with debug port:
+
+Create `~/Library/LaunchAgents/com.user.chrome-debug.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.user.chrome-debug</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</string>
+        <string>--remote-debugging-port=9222</string>
+        <string>--user-data-dir=/Users/YOUR_USERNAME/chrome-debug-profile</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+</dict>
+</plist>
+```
+
+Load with:
+```bash
+launchctl load ~/Library/LaunchAgents/com.user.chrome-debug.plist
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Type check
+npm run type-check
+
+# Lint
+npm run lint
+
+# Watch mode
+npm run watch
+```
+
+## License
+
+MIT
+
+## Attribution
+
+This project extracts browser control code from [OpenClaw](https://github.com/openclaw/openclaw) (MIT licensed), which provides battle-tested tab isolation and Playwright integration.
+
+Key extracted components:
+- CDP session management (`pw-session.ts`)
+- Browser operations (`pw-tools-*.ts`)
+- Role-based element refs (`pw-role-snapshot.ts`)
+
+## Links
+
+- [OpenClaw](https://github.com/openclaw/openclaw) - Source of browser control code
+- [MCP Specification](https://spec.modelcontextprotocol.io/) - Model Context Protocol
+- [Playwright](https://playwright.dev/) - Browser automation library

package/dist/browser/cdp.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Extracted from OpenClaw (https://github.com/openclaw/openclaw)
+ * Original: src/browser/cdp.ts
+ * License: MIT
+ *
+ * Modified for ultimate-playwright-mcp:
+ * - Extracted only AriaSnapshot types and formatting needed by pw-tools-snapshot.ts
+ * - Removed WebSocket-based CDP operations (Playwright handles this)
+ */
+export type AriaSnapshotNode = {
+    ref: string;
+    role: string;
+    name: string;
+    value?: string;
+    description?: string;
+    backendDOMNodeId?: number;
+    depth: number;
+};
+export type RawAXNode = {
+    nodeId?: string;
+    role?: {
+        value?: string;
+    };
+    name?: {
+        value?: string;
+    };
+    value?: {
+        value?: string;
+    };
+    description?: {
+        value?: string;
+    };
+    childIds?: string[];
+    backendDOMNodeId?: number;
+};
+export declare function formatAriaSnapshot(nodes: RawAXNode[], limit: number): AriaSnapshotNode[];
+//# sourceMappingURL=cdp.d.ts.map

package/dist/browser/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../src/browser/cdp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,WAAW,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAgBF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAyDxF"}

package/dist/browser/cdp.helpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Extracted from OpenClaw (https://github.com/openclaw/openclaw)
+ * Original: src/browser/cdp.helpers.ts
+ * License: MIT
+ *
+ * Modified for ultimate-playwright-mcp:
+ * - Removed WebSocket-based CDP sender (Playwright handles this)
+ * - Removed extension relay dependencies
+ * - Kept only URL/auth helpers needed by pw-session.ts
+ */
+export declare function isLoopbackHost(host: string): boolean;
+export declare function getHeadersWithAuth(url: string, headers?: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=cdp.helpers.d.ts.map

package/dist/browser/cdp.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.helpers.d.ts","sourceRoot":"","sources":["../../src/browser/cdp.helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,WAW1C;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,0BAiBnF"}

package/dist/browser/cdp.helpers.js

@@ -0,0 +1,38 @@
+/**
+ * Extracted from OpenClaw (https://github.com/openclaw/openclaw)
+ * Original: src/browser/cdp.helpers.ts
+ * License: MIT
+ *
+ * Modified for ultimate-playwright-mcp:
+ * - Removed WebSocket-based CDP sender (Playwright handles this)
+ * - Removed extension relay dependencies
+ * - Kept only URL/auth helpers needed by pw-session.ts
+ */
+export function isLoopbackHost(host) {
+    const h = host.trim().toLowerCase();
+    return (h === "localhost" ||
+        h === "127.0.0.1" ||
+        h === "0.0.0.0" ||
+        h === "[::1]" ||
+        h === "::1" ||
+        h === "[::]" ||
+        h === "::");
+}
+export function getHeadersWithAuth(url, headers = {}) {
+    try {
+        const parsed = new URL(url);
+        const hasAuthHeader = Object.keys(headers).some((key) => key.toLowerCase() === "authorization");
+        if (hasAuthHeader) {
+            return headers;
+        }
+        if (parsed.username || parsed.password) {
+            const auth = Buffer.from(`${parsed.username}:${parsed.password}`).toString("base64");
+            return { ...headers, Authorization: `Basic ${auth}` };
+        }
+    }
+    catch {
+        // ignore
+    }
+    return headers;
+}
+//# sourceMappingURL=cdp.helpers.js.map

package/dist/browser/cdp.helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.helpers.js","sourceRoot":"","sources":["../../src/browser/cdp.helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,CACL,CAAC,KAAK,WAAW;QACjB,CAAC,KAAK,WAAW;QACjB,CAAC,KAAK,SAAS;QACf,CAAC,KAAK,OAAO;QACb,CAAC,KAAK,KAAK;QACX,CAAC,KAAK,MAAM;QACZ,CAAC,KAAK,IAAI,CACX,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,UAAkC,EAAE;IAClF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAC7C,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,eAAe,CAC/C,CAAC;QACF,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACrF,OAAO,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC;QACxD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/browser/cdp.js

@@ -0,0 +1,77 @@
+/**
+ * Extracted from OpenClaw (https://github.com/openclaw/openclaw)
+ * Original: src/browser/cdp.ts
+ * License: MIT
+ *
+ * Modified for ultimate-playwright-mcp:
+ * - Extracted only AriaSnapshot types and formatting needed by pw-tools-snapshot.ts
+ * - Removed WebSocket-based CDP operations (Playwright handles this)
+ */
+function axValue(v) {
+    if (!v || typeof v !== "object") {
+        return "";
+    }
+    const value = v.value;
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return "";
+}
+export function formatAriaSnapshot(nodes, limit) {
+    const byId = new Map();
+    for (const n of nodes) {
+        if (n.nodeId) {
+            byId.set(n.nodeId, n);
+        }
+    }
+    // Heuristic: pick a root-ish node (one that is not referenced as a child), else first.
+    const referenced = new Set();
+    for (const n of nodes) {
+        for (const c of n.childIds ?? []) {
+            referenced.add(c);
+        }
+    }
+    const root = nodes.find((n) => n.nodeId && !referenced.has(n.nodeId)) ?? nodes[0];
+    if (!root?.nodeId) {
+        return [];
+    }
+    const out = [];
+    const stack = [{ id: root.nodeId, depth: 0 }];
+    while (stack.length && out.length < limit) {
+        const popped = stack.pop();
+        if (!popped) {
+            break;
+        }
+        const { id, depth } = popped;
+        const n = byId.get(id);
+        if (!n) {
+            continue;
+        }
+        const role = axValue(n.role);
+        const name = axValue(n.name);
+        const value = axValue(n.value);
+        const description = axValue(n.description);
+        const ref = `ax${out.length + 1}`;
+        out.push({
+            ref,
+            role: role || "unknown",
+            name: name || "",
+            ...(value ? { value } : {}),
+            ...(description ? { description } : {}),
+            ...(typeof n.backendDOMNodeId === "number" ? { backendDOMNodeId: n.backendDOMNodeId } : {}),
+            depth,
+        });
+        const children = (n.childIds ?? []).filter((c) => byId.has(c));
+        for (let i = children.length - 1; i >= 0; i--) {
+            const child = children[i];
+            if (child) {
+                stack.push({ id: child, depth: depth + 1 });
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=cdp.js.map

package/dist/browser/cdp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../src/browser/cdp.ts"],"names":[],"mappings":"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"}

package/dist/browser/chrome-tab-groups.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Chrome visual tab groups via the companion extension.
+ *
+ * Connects to the "UltimatePW Tab Grouper" extension's service worker
+ * via CDP and calls its global helpers (groupTabs, ungroupTabs, etc.)
+ * to manage native Chrome tab groups with titles and colors.
+ *
+ * Falls back gracefully — if the extension isn't loaded, visual grouping
+ * is simply skipped and a warning is returned.
+ */
+/**
+ * Compute a Chrome unpacked extension ID from its absolute directory path.
+ * Chrome uses SHA-256 of the path, maps each nibble to a-p.
+ */
+export declare function computeExtensionId(extensionPath: string): string;
+/**
+ * Pre-seed the extension ID from a known path. Call this during server init
+ * so the wake mechanism works even before the first probe succeeds.
+ */
+export declare function seedExtensionIdFromPath(extensionPath: string): void;
+export declare class ExtensionNotFoundError extends Error {
+    constructor();
+}
+/**
+ * Check whether the companion extension is available.
+ */
+/**
+ * Warm up: discover and cache the extension ID while the SW is still alive
+ * (should be called soon after Chrome starts). Best-effort, non-blocking.
+ */
+export declare function warmupTabGrouper(cdpUrl: string): Promise<void>;
+export declare function isTabGrouperAvailable(cdpUrl: string): Promise<boolean>;
+/**
+ * Get the Chrome tab ID for a given URL + title combo.
+ * We need this to bridge CDP targetId → Chrome tab ID.
+ */
+export declare function getChromeTabId(cdpUrl: string, targetUrl: string, targetTitle?: string): Promise<number | null>;
+/**
+ * Map CDP targetIds to Chrome tab IDs by correlating URL/title.
+ * Returns a map of targetId → chromeTabId.
+ */
+export declare function mapTargetIdsToChromeTabIds(cdpUrl: string, targets: Array<{
+    targetId: string;
+    url: string;
+    title: string;
+}>): Promise<Map<string, number>>;
+/**
+ * Group Chrome tabs visually with a title and color.
+ * @param chromeTabIds - Chrome internal tab IDs (not CDP targetIds)
+ * @param title - Group title
+ * @param color - grey|blue|red|yellow|green|pink|purple|cyan
+ * @param existingGroupId - If provided, add to an existing Chrome group
+ * @returns Chrome's groupId
+ */
+export declare function groupTabsVisually(cdpUrl: string, chromeTabIds: number[], title: string, color: string, existingGroupId?: number): Promise<{
+    groupId: number;
+}>;
+/**
+ * Remove tabs from their Chrome visual group.
+ */
+export declare function ungroupTabsVisually(cdpUrl: string, chromeTabIds: number[]): Promise<void>;
+/**
+ * Update a Chrome visual group's title/color/collapsed state.
+ */
+export declare function updateVisualGroup(cdpUrl: string, chromeGroupId: number, updates: {
+    title?: string;
+    color?: string;
+    collapsed?: boolean;
+}): Promise<void>;
+/**
+ * List all Chrome visual tab groups.
+ */
+export declare function listVisualTabGroups(cdpUrl: string): Promise<Array<{
+    id: number;
+    title: string;
+    color: string;
+    collapsed: boolean;
+}>>;
+/**
+ * Create a tab via the extension (gives us the Chrome tab ID directly).
+ * This avoids the unreliable URL-based mapping from CDP targetIds.
+ * Returns both the Chrome tabId and the CDP targetId.
+ */
+export declare function createTabViaExtension(cdpUrl: string, url: string): Promise<{
+    chromeTabId: number;
+    targetId: string;
+    url: string;
+}>;
+/**
+ * Close a tab via the extension using its Chrome tab ID.
+ */
+export declare function closeTabViaExtension(cdpUrl: string, chromeTabId: number): Promise<void>;
+//# sourceMappingURL=chrome-tab-groups.d.ts.map

package/dist/browser/chrome-tab-groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome-tab-groups.d.ts","sourceRoot":"","sources":["../../src/browser/chrome-tab-groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0CH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAInE;AAsSD,qBAAa,sBAAuB,SAAQ,KAAK;;CAQhD;AAID;;GAEG;AACH;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG5E;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqBxB;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAC/D,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAkC9B;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EAAE,EACtB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ9B;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/D,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CAOlF;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CA4CjE;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAEf"}