@weavetab/mcp 2.5.0-beta.1 → 2.5.0-beta.4

package/docs/DOCUMENTATION.md

@@ -6,11 +6,11 @@
 
 ## Overview
 
-Weavetab is a production-grade, in-process MCP (Model Context Protocol) server that grants AI agents human-like control over Chromium browsers. It communicates directly over the Chrome DevTools Protocol (CDP) at Layer 0 — no WebDriver process, no browser binary download, no Playwright/Puppeteer abstraction layer.
+Weavetab is a production-grade, in-process MCP (Model Context Protocol) server providing AI agents with direct, physical Layer 0 control across Chromium browsers and Electron desktop applications. It communicates directly over the Chrome DevTools Protocol (CDP) WebSocket at Layer 0 — no WebDriver process, no browser binary download, no cloud middleware.
 
 ### Core Capabilities
 
-- **45 Built-in MCP Tools** across 15 functional categories (Vision, Navigation, Input, Tabs, Mission Execution, Dialog, Wait, Storage, Device, Network, Canvas, Output, Evaluation, GitHub, Office Documents)
+- **44 Built-in MCP Tools** across functional categories (Vision, Navigation, Input, Tabs, Mission Execution, Dialog, Wait, Storage, Device, Network, Canvas, Output, Evaluation, GitHub, Office Documents)
 - **Direct CDP WebSocket** — 3-8ms mean latency, zero process overhead
 - **Semantic Delta Engine** — 5-10x token reduction via per-tab snapshot diffing
 - **Ghost Cursor** — Bézier curve click engine with human acceleration and jitter
@@ -20,7 +20,7 @@ Weavetab is a production-grade, in-process MCP (Model Context Protocol) server t
 - **Security Stack** — domain blacklist, RBAC (4 roles), rate limiter, loop detection, input filter, root guard
 - **Burst Mode** — chain N actions in 1 MCP call via `browser_burst`
 - **Plugin System** — Extensible plugin ecosystem supporting tool additions, overrides (with originalHandler wrapping), and tool removals across 3 trust tiers (Official, Verified, Unverified)
-- **GitHub Integration** — 4 built-in tools for repo analysis, file reading, issues, and PRs
+- **GitHub Integration** — Unified `browser_github` tool for repo analysis, file reading, issues, and PRs
 
 ### Weavetab Skills
 
@@ -61,7 +61,7 @@ MCP Client → stdio/WebSocket → WithSecurity Pipeline → CDP WebSocket → C
 
 ---
 
-## Tool Reference (44+ Tools)
+## Tool Reference (44 Tools)
 
 All tools share: Zod schema validation, `withSecurity()` pipeline (rate limiting + domain policy + RBAC), structured audit logging.
 
@@ -69,8 +69,8 @@ All tools share: Zod schema validation, `withSecurity()` pipeline (rate limiting
 
 | Tool | Description |
 |------|-------------|
-| `browser_map` | DOM enumeration with stable `w:NN` ref IDs. Supports `delta` (diff mode), `prune` (one-shot compression), `ax_tree` (Shadow DOM fallback), `scope` filtering, `query` filtering |
-| `browser_find` | Native CDP text search — ~10x cheaper than map, single CDP call |
+| `browser_map` | DOM enumeration (v3.0) with volatile `w:NN` ref IDs, Set-of-Marks visual grounding (`visual: true` / `"auto"`), entity & card container binding (`┌ Heading`), active modal hoisting (`╔═ ACTIVE DIALOG ═╗`), nav cluster collapsing, delta diffing, and scope filtering (`modal`, `form`, `main`). |
+| `browser_find` | Native CDP text search with single and multi-match (`all: true`, `limit: N`) returning bounding rects and selectors — ~10x cheaper than map |
 | `browser_scrape` | CSS/XPath structured data extraction in 1 CDP call |
 | `browser_inspect` | Computed CSS styles + inline styles + event listener types |
 | `browser_snapshot` | MHTML capture/restore of DOM state + resources |
@@ -81,21 +81,21 @@ All tools share: Zod schema validation, `withSecurity()` pipeline (rate limiting
 
 | Tool | Description |
 |------|-------------|
-| `browser_navigate` | Navigate to URL with domain blocklist enforcement. Supports `Weavetab://` protocol for persistent local playgrounds |
+| `browser_navigate` | Ultra-low latency navigation (~150-300ms) with non-blocking readyState polling, parallelized metadata, domain blocklist enforcement, and `weavetab://` protocol |
 
 ### Input (9 tools)
 
 | Tool | Description |
 |------|-------------|
-| `browser_click` | Ghost Cursor (Bézier) click with intent memory, occlusion detection, stuck-loop detection |
-| `browser_type` | Human keystroke engine with jitter, burst patterns, paste mode, stuck detection |
+| `browser_click` | Ghost Cursor (Bézier) click with direct visual mark targeting (`mark: N`), intent memory, occlusion detection, and stuck-loop detection |
+| `browser_type` | Human keystroke engine with zero-target `document.activeElement` typing, anti-unfocus click avoidance, jitter, and burst patterns |
 | `browser_type_secret` | Blind Injection from `secrets.json` — domain check before value load, Shadow DOM isolation, JS property hardening |
-| `browser_key` | Native keyboard dispatch with modifier keys (Ctrl, Shift, Alt, Meta) |
-| `browser_pointer` | Hover, double-click, drag-and-drop via native mouse events |
+| `browser_key` | Native keyboard dispatch with combo hotkeys (`"Ctrl+A"`, `"Cmd+K"`, `"Alt+Tab"`) and zero arbitrary delay |
+| `browser_pointer` | Hover, double-click, drag-and-drop, and multi-level flyout menu traversal via `hover_chain: ["File", "Export As", "PNG"]` |
 | `browser_select` | Native `<select>` dropdown selection — React/Vue safe (prototype setter + events) |
-| `browser_fill` | Smart multi-field form fill — auto-detects text, select, checkbox, radio, contenteditable |
+| `browser_fill` | Smart multi-field form batch completion with input discovery scanner (`scan: true`), flexible field selectors, and Google Sheets `grid_data` |
 | `browser_upload` | Bypass file dialogs via CDP `DOM.setFileInputFiles` |
-| `browser_scroll` | Directional + element-relative scroll via native wheel events |
+| `browser_scroll` | Fast non-blocking directional + element-relative scroll without redundant action map rebuilds |
 
 ### Tabs & Windows (2 tools)
 
@@ -104,12 +104,11 @@ All tools share: Zod schema validation, `withSecurity()` pipeline (rate limiting
 | `browser_tabs` | Open/switch/close/list/consolidate (dedup)/heal (recover crash). Also list/focus windows |
 | `browser_detect` | Detect installed browsers + CDP feature coverage per engine (Chromium, Firefox, WebKit) |
 
-### Mission Execution (3 tools)
+### Mission Execution (2 tools)
 
 | Tool | Description |
 |------|-------------|
 | `browser_burst` | Chain N actions in 1 MCP call. Supports 4 macro steps: `type_and_send`, `navigate_and_read`, `click_and_wait`, `scroll_and_read` |
-| `browser_plan` | Live task dashboard in browser Shadow DOM overlay. User sees progress, can comment |
 | `browser_automation` | Inject persistent self-running scripts — monitoring, polling, background extraction |
 
 ### Dialog & User Interaction (3 tools)
@@ -120,12 +119,11 @@ All tools share: Zod schema validation, `withSecurity()` pipeline (rate limiting
 | `browser_thought` | Green thought bubbles: feedback (one-way) or question with input (sentence/paragraph modes) |
 | `browser_clipboard` | System clipboard R/W (text + images) |
 
-### Wait & Timing (2 tools)
+### Wait & Timing (1 tool)
 
 | Tool | Description |
 |------|-------------|
-| `browser_wait` | Wait for element/text/URL/stable/network/auto — timeout configurable |
-| `browser_reset_loop_counter` | Manual loop detection override |
+| `browser_wait` | Wait for element/text/URL/stable/network/auto — timeout configurable, optional loop counter reset (`reset_loop: true`) |
 
 ### Storage & Cookies (2 tools)
 
@@ -172,20 +170,11 @@ All tools share: Zod schema validation, `withSecurity()` pipeline (rate limiting
 |------|-------------|
 | `browser_performance` | FCP, LCP, TTI metrics, resource timings |
 
-### Macro (1 tool)
+### GitHub (1 tool)
 
 | Tool | Description |
 |------|-------------|
-| `browser_macro_compile` | Compile successful trails into burst macros |
-
-### GitHub (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `github_analyze` | Repo metadata, file tree, README snippet |
-| `github_read` | Read file contents via raw.githubusercontent.com (no API limit cost) |
-| `github_issues` | List/search/fetch issues with comments |
-| `github_get_pr` | PR details + changed files + comments |
+| `browser_github` | Action-based repo metadata analysis, raw source file reading, issue triage, and PR inspection |
 
 ### Utility (2 tools)
 
@@ -261,10 +250,15 @@ The value is permanently masked as `[REDACTED]` in all subsequent DOM reads and
   "role": "admin",
   "telemetry": false,
   "attachPort": 0,
-  "disableExtensions": false,
+  "extension": true,
   "cookies": false,
   "browserFlags": [],
-  "policies": []
+  "policies": [],
+  "electron": {
+    "discord": "C:\\Users\\<user>\\AppData\\Local\\Discord\\app-<version>\\Discord.exe",
+    "antigravity": "C:\\Users\\<user>\\AppData\\Local\\Programs\\antigravity\\Antigravity.exe",
+    "vscode": "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe"
+  }
 }
 ```
 
@@ -279,10 +273,11 @@ The value is permanently masked as `[REDACTED]` in all subsequent DOM reads and
 | `role` | string | "admin" | RBAC role (admin, system, viewer, automation) |
 | `telemetry` | boolean | false | Enable anonymous usage telemetry |
 | `attachPort` | number | 0 | Chrome DevTools Protocol port |
-| `disableExtensions` | boolean | false | Disable Weavetab extension for HUD features |
+| `extension` | boolean | true | Enable Weavetab extension integration |
 | `cookies` | boolean | false | Persist cookies/storage across sessions. When `false`, `document.cookie`, `localStorage`, and `sessionStorage` are all neutered at the browser level (returns empty/null for everything) + a fresh isolated profile is used each session. When `true`, cookies/storage work normally and persist via the profile directory. |
 | `browserFlags` | string[] | `[]` | Extra Chromium command-line flags to append on launch (e.g., `["--disable-web-security"]`). The `--disable-sync` flag is mandatory and cannot be overridden — any conflicting flag is automatically dropped. |
 | `policies` | PolicyEntry[] | `[]` | Domain-level access control policies (see [Domain Policy](#domain-policy) below). Supersedes the legacy `block`/`allow` lists. |
+| `electron` | Record<string, string> | `{}` | Map of registered Electron desktop applications (e.g. Discord, VS Code, Figma, Antigravity, local dev apps) to executable paths or startup commands. |
 
 ---
 
@@ -448,10 +443,10 @@ export default plugin;
 
 ```bash
 # Official plugins
-wt plugin add @weavetab/plugin-sample
+weavetab plugin add @weavetab/plugin-sample
 
 # Community plugins (any npm name)
-wt plugin add wt-my-tool
+weavetab plugin add wt-my-tool
 # or via npm
 npm install wt-my-tool
 ```
@@ -489,6 +484,57 @@ Skills are automatically discovered by MCP clients and provide:
 
 ---
 
+## Electron & Desktop Application Automation
+
+Weavetab natively supports **generic automation of any Electron or Chromium-based desktop application** (e.g. Discord, Slack, VS Code, Antigravity IDE, Figma, Obsidian, Postman, or local developer applications running from source).
+
+### Why It Works at Layer 0
+Electron desktop applications run a bundled Chromium/Blink engine under the hood. When started with Chrome DevTools Protocol debugging enabled (either automatically via Weavetab or via `--remote-debugging-port`), Weavetab connects directly to the desktop app's internal WebSockets and exposes all 50 MCP tools without requiring external drivers or wrappers.
+
+### Registering Applications
+In `~/.weavetab/config.json` or project-scoped `.weavetab/config.json`:
+
+```json
+{
+  "electron": {
+    "discord": "C:\\Users\\<user>\\AppData\\Local\\Discord\\app-1.0.9183\\Discord.exe",
+    "antigravity": "C:\\Users\\<user>\\AppData\\Local\\Programs\\antigravity\\Antigravity.exe",
+    "vscode": "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
+    "figma": "C:\\Users\\<user>\\AppData\\Local\\Figma\\Figma.exe",
+    "obsidian": "C:\\Users\\<user>\\AppData\\Local\\Obsidian\\Obsidian.exe",
+    "my-app": "C:\\path\\to\\my-project\\node_modules\\electron\\dist\\electron.exe"
+  }
+}
+```
+
+### Automating Local / Source-Hosted Projects
+When developing an Electron app locally (e.g. `localhost:3000` or running via Vite/Webpack/Electron forge):
+
+1. **Launch with remote debugging enabled:**
+   ```bash
+   npx electron . --remote-debugging-port=9222
+   # or with npm scripts:
+   npm run dev -- --remote-debugging-port=9222
+   ```
+
+2. **Automate via MCP tools:**
+   Set `"attachPort": 9222` or register the dev script in `"electron"` config.
+
+### Tool Execution Flow with Desktop Apps
+Every Weavetab tool supports the optional `app` parameter:
+
+| Tool Call | Desktop Behavior |
+| :--- | :--- |
+| `browser_navigate({ app: "antigravity" })` | Launches or connects to Antigravity's CDP session |
+| `browser_tabs({ action: "list", app: "antigravity" })` | Lists all windows, webviews, and workbench tabs in the app |
+| `browser_tabs({ action: "switch", tabId: "<id>", app: "antigravity" })` | Switches active focus to the specified workbench or window |
+| `browser_map({ app: "antigravity" })` | Generates semantic Ref IDs (`w:NN`) for the desktop app's active window |
+| `browser_click({ ref: "w:12", app: "antigravity" })` | Sends Ghost Cursor click to the desktop app element |
+| `browser_type({ ref: "w:15", text: "...", app: "discord" })` | Types text directly into the desktop app input field |
+| `browser_eval({ expression: "...", app: "vscode" })` | Evaluates JavaScript inside the desktop app frame context |
+
+---
+
 ## Troubleshooting
 
 ### Common Issues
@@ -523,10 +569,10 @@ For detailed troubleshooting, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md).
 
 ## Additional Resources
 
+- [Tool Reference](tools/tools.md)
 - [Plugin System Guide](PLUGINS.md)
 - [Architecture Documentation](../ARCHITECTURE.md)
-- [Tool Reference](TOOLS.md)
+- [Support & Community](../SUPPORT.md)
 - [Security Policy](../SECURITY.md)
 - [Contributing Guidelines](../CONTRIBUTING.md)
 - [Troubleshooting Guide](../TROUBLESHOOTING.md)
-- [Comparison with Other Tools](../.upgrade/compare.md)