@weavetab/mcp 2.5.0-beta.0 → 2.5.0-beta.2

package/dist/tools/tabs.js

@@ -8,7 +8,13 @@ import { readLock } from "../cdp/lock.js";
 import { resetLoopCounter } from "../intelligence/trail.js";
 import { getConfigAgentId, getConfigMaxTabs } from "../config/loader.js";
 /** Resolve the active CDP port — live > lock file */
-function resolvePort(_config) {
+function resolvePort(_config, appName) {
+    if (appName) {
+        const lock = readLock(appName);
+        if (lock && lock.port)
+            return lock.port;
+        throw new Error(`[!] No active session for Electron app "${appName}". Launch it first.`);
+    }
     const port = getPort() || readLock()?.port;
     if (!port)
         throw new Error("[!] No active browser session. Run browser_go first.");
@@ -44,9 +50,9 @@ function calculateSemanticScore(url, title) {
         score += 30;
     return Math.min(score, 100);
 }
-export async function evaluateTabSemantics(targetId) {
+export async function evaluateTabSemantics(targetId, appName) {
     try {
-        const client = await connectToTab(targetId);
+        const client = await connectToTab(targetId, undefined, undefined, undefined, appName);
         const result = await client.session.Runtime.evaluate({
             expression: `JSON.stringify({ title: document.title, url: location.href })`,
             returnByValue: true
@@ -104,17 +110,17 @@ async function enforceMaxTabs(config) {
     logAction("browser_tabs", victim.id, `auto-closed idle tab: ${victim.title}`);
 }
 // ─── Tools ────────────────────────────────────────────────────────────────────
-export async function WeavetabOpen(url, config, reuse = true) {
-    const port = resolvePort(config);
+export async function WeavetabOpen(url, config, reuse = true, appName) {
+    const port = resolvePort(config, appName);
     // Tab reuse: if same URL is already open, focus it instead of duplicating
     if (reuse && url) {
         try {
-            const targets = await getTabList(getConfigAgentId(config));
+            const targets = await getTabList(getConfigAgentId(config), appName);
             const existing = targets.find((t) => t.url === url);
             if (existing) {
-                const client = await connectToTab(existing.id);
+                const client = await connectToTab(existing.id, undefined, undefined, undefined, appName);
                 await client.session.Target.activateTarget({ targetId: existing.id });
-                sessionRegistry.setActive(existing.id, getConfigAgentId(config));
+                sessionRegistry.setActive(existing.id, getConfigAgentId(config), appName);
                 recordTabActivity(existing.id);
                 logAction("browser_tabs", url, `reused existing tab ${existing.id}`);
                 return { success: true, tabId: existing.id, url, reused: true };
@@ -122,22 +128,24 @@ export async function WeavetabOpen(url, config, reuse = true) {
         }
         catch { /* fall through to open new */ }
     }
-    await enforceMaxTabs(config);
-    const bctxId = sessionRegistry.getBrowserContextIdForAgent(getConfigAgentId(config));
+    if (!appName) {
+        await enforceMaxTabs(config);
+    }
+    const bctxId = appName ? undefined : sessionRegistry.getBrowserContextIdForAgent(getConfigAgentId(config));
     const metaSession = await CDP({ host: "127.0.0.1", port });
     const { targetId } = await metaSession.Target.createTarget({ url, browserContextId: bctxId });
     await metaSession.close();
     recordTabActivity(targetId);
-    await connectToTab(targetId, port, getConfigAgentId(config), bctxId);
-    await evaluateTabSemantics(targetId);
+    await connectToTab(targetId, port, getConfigAgentId(config), bctxId, appName);
+    await evaluateTabSemantics(targetId, appName);
     logAction("browser_tabs", url, `opened ${targetId}`);
     return { success: true, tabId: targetId, url };
 }
-export async function WeavetabSwitch(tabId, config) {
-    const client = await connectToTab(tabId);
+export async function WeavetabSwitch(tabId, config, appName) {
+    const client = await connectToTab(tabId, undefined, undefined, undefined, appName);
     const startSwitch = Date.now();
     await client.session.Target.activateTarget({ targetId: tabId });
-    sessionRegistry.setActive(tabId, getConfigAgentId(config));
+    sessionRegistry.setActive(tabId, getConfigAgentId(config), appName);
     recordTabActivity(tabId);
     const { frameTree } = await client.session.Page.getFrameTree();
     let title = tabId;
@@ -154,9 +162,9 @@ export async function WeavetabSwitch(tabId, config) {
     resetLoopCounter("tab_switch");
     return { success: true, tab_id: tabId, title, url, contextSwitchCostMs: cost };
 }
-export async function WeavetabList(config) {
-    const targets = await getTabList(getConfigAgentId(config));
-    const activeTargetId = sessionRegistry.getActive(getConfigAgentId(config))?.targetId;
+export async function WeavetabList(config, appName) {
+    const targets = await getTabList(getConfigAgentId(config), appName);
+    const activeTargetId = sessionRegistry.getActive(getConfigAgentId(config), appName)?.targetId;
     const tabs = targets
         .map((t) => ({
         id: t.id,
@@ -174,12 +182,12 @@ export async function WeavetabList(config) {
     }));
     return { tabs };
 }
-export async function WeavetabClose(tabId, config, force = false) {
+export async function WeavetabClose(tabId, config, force = false, appName) {
     const score = semanticScores.get(tabId) ?? 10;
     if (score >= 70 && !force) {
         throw new Error(`[!] Tab Armor block: This tab is semantically protected (score: ${score}). It likely contains a login, checkout, or critical work. Do not close it! If the user explicitly requested this closure, pass force: true.`);
     }
-    const port = resolvePort(config);
+    const port = resolvePort(config, appName);
     await CDP.Close({ host: "127.0.0.1", port, id: tabId });
     clearTabCache(tabId);
     sessionRegistry.unregister(tabId);
@@ -192,12 +200,12 @@ export async function WeavetabClose(tabId, config, force = false) {
 /**
  * Batch close multiple tabs at once — saves multiple round-trips.
  */
-export async function WeavetabCloseBatch(tabIds, config, force = false) {
+export async function WeavetabCloseBatch(tabIds, config, force = false, appName) {
     const closed = [];
     const skipped = [];
     for (const tabId of tabIds) {
         try {
-            await WeavetabClose(tabId, config, force);
+            await WeavetabClose(tabId, config, force, appName);
             closed.push(tabId);
         }
         catch {
@@ -209,14 +217,14 @@ export async function WeavetabCloseBatch(tabIds, config, force = false) {
 /**
  * Consolidate: deduplicate tabs by URL, close duplicates.
  */
-export async function WeavetabConsolidate(config) {
-    const port = resolvePort(config);
+export async function WeavetabConsolidate(config, appName) {
+    const port = resolvePort(config, appName);
     const targets = await CDP.List({ host: "127.0.0.1", port });
-    const pages = targets.filter((t) => t.type === "page");
+    const pages = targets.filter((t) => t.type === "page" || t.type === "webview" || t.type === "app");
     const tabsBefore = pages.length;
     const seenUrls = new Set();
     let closedDuplicates = 0;
-    const activeTargetId = sessionRegistry.getActive(getConfigAgentId(config))?.targetId;
+    const activeTargetId = sessionRegistry.getActive(getConfigAgentId(config), appName)?.targetId;
     for (const page of pages) {
         if (page.id === activeTargetId) {
             seenUrls.add(page.url);
@@ -240,17 +248,17 @@ export async function WeavetabConsolidate(config) {
         }
     }
     const afterTargets = await CDP.List({ host: "127.0.0.1", port });
-    const tabsAfter = afterTargets.filter((t) => t.type === "page").length;
+    const tabsAfter = afterTargets.filter((t) => t.type === "page" || t.type === "webview" || t.type === "app").length;
     logAction("browser_tabs", "consolidate", `${tabsBefore}→${tabsAfter} (closed ${closedDuplicates} duplicates)`);
     return { success: true, tabs_before: tabsBefore, tabs_after: tabsAfter, closed_duplicates: closedDuplicates };
 }
 /**
  * Heal: check all tabs for crashed state and reload them.
  */
-export async function WeavetabHeal(config) {
-    const port = resolvePort(config);
+export async function WeavetabHeal(config, appName) {
+    const port = resolvePort(config, appName);
     const targets = await CDP.List({ host: "127.0.0.1", port });
-    const pages = targets.filter((t) => t.type === "page");
+    const pages = targets.filter((t) => t.type === "page" || t.type === "webview" || t.type === "app");
     let healed = 0;
     const healthSummary = {};
     for (const page of pages) {
@@ -269,7 +277,7 @@ export async function WeavetabHeal(config) {
             continue;
         }
         try {
-            const client = await connectToTab(page.id);
+            const client = await connectToTab(page.id, undefined, undefined, undefined, appName);
             const { result } = await client.session.Runtime.evaluate({
                 expression: `document.readyState`,
                 returnByValue: true,
@@ -292,10 +300,10 @@ export async function WeavetabHeal(config) {
     logAction("browser_tabs", "heal", `healed ${healed}/${pages.length} tabs`);
     return { success: true, healed, tabs_checked: pages.length, health_summary: healthSummary };
 }
-export async function weaveWindowList(config) {
-    const port = resolvePort(config);
+export async function weaveWindowList(config, appName) {
+    const port = resolvePort(config, appName);
     const targets = await CDP.List({ host: "127.0.0.1", port });
-    const pages = targets.filter((t) => t.type === "page");
+    const pages = targets.filter((t) => t.type === "page" || t.type === "webview" || t.type === "app");
     // Group by process — each unique window has its own set of tabs
     // We approximate via CDP Target.getTargets windowId if available
     const windows = [];
@@ -307,7 +315,7 @@ export async function weaveWindowList(config) {
                 const { windowId, bounds } = await session.Browser.getWindowForTarget({ targetId: page.id });
                 if (!seenWindowIds.has(windowId)) {
                     seenWindowIds.add(windowId);
-                    const activeId = sessionRegistry.getActive(getConfigAgentId(config))?.targetId;
+                    const activeId = sessionRegistry.getActive(getConfigAgentId(config), appName)?.targetId;
                     windows.push({
                         windowId,
                         state: bounds.windowState || "normal",
@@ -324,12 +332,12 @@ export async function weaveWindowList(config) {
     }
     return { windows };
 }
-export async function weaveFocusWindow(windowId, config) {
-    const port = resolvePort(config);
+export async function weaveFocusWindow(windowId, config, appName) {
+    const port = resolvePort(config, appName);
     const targets = await CDP.List({ host: "127.0.0.1", port });
-    const page = targets.find((t) => t.type === "page");
+    const page = targets.find((t) => t.type === "page" || t.type === "webview" || t.type === "app");
     if (!page)
-        throw new Error("No page target found to focus window");
+        throw new Error("No page or window target found to focus window");
     const session = await CDP({ host: "127.0.0.1", port, target: page.id });
     try {
         await session.Browser.setWindowBounds({ windowId, bounds: { windowState: "normal" } });

package/dist/tools/type.js

@@ -657,10 +657,10 @@ export async function weaveType(session, args, config) {
             // Vue/React controlled inputs re-render the DOM node during focus, making
             // Ctrl+V land on the old (detached) node. If el.value is still empty,
             // fallback to Input.insertText which targets the currently-focused element.
-            if (selector && selector !== 'document.activeElement') {
+            if (selector) {
                 const pasteCheck = await session.Runtime.evaluate({
                     expression: `(function(sel) {
-            var el = document.querySelector(sel) || (window.__Weavetab_shadowQuery ? window.__Weavetab_shadowQuery(sel) : null);
+            var el = (sel === 'document.activeElement') ? document.activeElement : (document.querySelector(sel) || (window.__Weavetab_shadowQuery ? window.__Weavetab_shadowQuery(sel) : null));
             if (!el) return null;
             return el.value !== undefined ? el.value : (el.textContent || null);
           })(${JSON.stringify(selector)})`,

package/docs/DOCUMENTATION.md

@@ -6,7 +6,7 @@
 
 ## 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
 
@@ -261,10 +261,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-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"
+  }
 }
 ```
 
@@ -279,10 +284,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 +454,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 +495,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 45+ 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

package/docs/architecture/blind-injection.md

@@ -0,0 +1,20 @@
+---
+title: "Blind Injection"
+description: "Enterprise-grade credential injection that never exposes secrets to the LLM."
+product: mcp
+section: architecture
+icon: Lock
+slug: blind-injection
+---
+
+# Blind Injection
+
+The `browser_type_secret` tool resolves passwords, tokens, and 2FA credentials directly from `secrets.json` on the server — **never exposing sensitive values to the AI model's context stream**.
+
+## How It Works
+
+1. Store a secret via `weavetab secrets set MY_KEY` or by editing `secrets.json`
+2. The agent calls `browser_type_secret({ id: "w:2", envKey: "MY_KEY" })`
+3. Weavetab resolves the secret from `secrets.json` in-process on the local machine
+4. The value is typed directly into the DOM input field over CDP
+5. All subsequent `browser_map` outputs, DOM snapshots, and audit logs permanently display `[REDACTED]` for that element

package/docs/architecture/dual-injection.md

@@ -0,0 +1,32 @@
+---
+title: "Dual Injection"
+description: "CDP early-script + Manifest V3 extension working in tandem."
+product: mcp
+section: architecture
+icon: Combine
+slug: dual-injection
+---
+
+# Dual Injection Strategy
+
+Weavetab delivers overlay UI and stealth capabilities through **two complementary channels** that cover each other's blind spots.
+
+## 1. CDP Early-Script Injection
+
+```typescript
+await session.Page.addScriptToEvaluateOnNewDocument({ source: STEALTH_SCRIPT });
+await session.Runtime.evaluate({ expression: STEALTH_SCRIPT }).catch(() => {});
+```
+
+Runs **before any page JavaScript executes**. Handles:
+- **Stealth patches**: `navigator.webdriver` → `undefined`, fake plugin arrays, WebGL/Canvas fingerprint noise
+- **Shadow DOM bootstrap**: `#weavetab-root` host container created in every page
+- **Config binding**: `window.__wt_setConfig`, `window.__wt_config` for live runtime updates
+
+## 2. Manifest V3 Extension
+
+Loaded dynamically with `--load-extension=${extPath}`. Owns:
+- **Ghost Cursor animation** (Bézier curve path rendering via canvas overlay)
+- **Thought bubble HUD** (agent status messages during tool execution)
+- **Interactive Ask Modal** (user interaction with response queue)
+- **SPA navigation persistence** — survives framework router transitions without flashing

package/docs/architecture/overview.md

@@ -0,0 +1,49 @@
+---
+title: "Overview"
+description: "Five layers, deterministic pipeline, zero cloud."
+product: mcp
+section: architecture
+icon: Layers
+slug: overview
+---
+
+# Architecture Overview
+
+Weavetab is decomposed into **five functional layers**, all running in-process without external daemon dependencies.
+
+## Layer Map
+
+| # | Layer | Responsibility |
+|---|---|---|
+| 1 | **Transport** | JSON-RPC 2.0 over stdio or WebSocket (`--ws --port 3000`) |
+| 2 | **Security & Governance** | Domain blacklist, rate limiter (mutex), RBAC roles, policy engine, root guard |
+| 3 | **Intelligence Engine** | Session memory, semantic delta diffing, DOM pruner, loop detection, intent intercept |
+| 4 | **Sensor Systems** | Network telemetry, DOM mutation observer, human pacing, agent state machine |
+| 5 | **CDP Bridge** | DOM walker, Ghost Cursor (Bézier trajectories), keystroke engine, shadow-DOM injector |
+
+## Tool Execution Pipeline
+
+```text
+Agent → withSecurity()
+        ├── Rate limiter (mutex)
+        ├── Domain policy check (allow/deny/audit/read-only)
+        ├── RBAC role verification
+        ├── User-stop polling
+        ├── Chat queue draining
+        ├── Agent state transition (idle → weaving → reading)
+        └── Tool handler → CDP Bridge → Browser / Desktop App
+```
+
+Any validation or security failure short-circuits the pipeline immediately and returns a structured `WeaveError` — no partial side-effects are left on the browser.
+
+## Why Direct CDP
+
+| Feature | Weavetab | Playwright | Puppeteer | Selenium |
+|---|---|---|---|---|
+| **Architecture** | Direct CDP Layer 0 | Node bridge abstraction | CDP wrapper | WebDriver |
+| **Mean latency** | **3–8 ms** | 15–40 ms | 10–25 ms | 50–150 ms |
+| **Token efficiency** | **Semantic Deltas (97% reduction)** | Full DOM dumps | Full DOM dumps | Full DOM dumps |
+| **Desktop Electron Apps** | **Native (any Electron app)** | Experimental | Limited | Third-party driver |
+| **CAPTCHA Solver** | **Autonomous Zero-API** | None | None | None |
+| **MCP native** | **Yes (45 tools)** | No | No | No |
+| **Cloud dependency** | **Zero** | Optional | Optional | Grid required |

package/docs/architecture/security.md

@@ -0,0 +1,35 @@
+---
+title: "Security Model"
+description: "Layered defenses that gate every tool invocation."
+product: mcp
+section: architecture
+icon: ShieldCheck
+slug: security
+---
+
+# Security Model
+
+Weavetab executes direct Layer 0 CDP commands — security is layered and **deny-by-default for risky surfaces**.
+
+## Defense-in-Depth Mechanisms
+
+| Mechanism | Description |
+|---|---|
+| **Domain Blacklist** | Hard-blocked high-risk domains (banking, IAM consoles, internal infrastructure). |
+| **Domain Policy Engine** | Per-domain enforcement modes: `allow`, `read-only`, `deny`, `audit`. |
+| **Localhost Binding** | WebSocket server and CDP endpoints strictly bound to `127.0.0.1`. |
+| **Rate Limiting** | Mutex-enforced actions-per-minute rate limiter. |
+| **RBAC Roles** | 4 strict roles gating tool access (`admin`, `operator`, `viewer`, `automation`). |
+| **Root Guard** | Prevents execution as root/superuser on Unix systems. |
+| **Blind Injection** | Credential injection from `secrets.json` without exposing raw text to LLM context. |
+| **Shadow DOM Isolation** | All injected HUD and modal overlays run in isolated Shadow DOM trees. |
+| **Path Traversal Guard** | File upload and download paths strictly validated against path traversal. |
+
+## RBAC Role Matrix
+
+| Tool Category | admin | operator | viewer | automation |
+|---|:---:|:---:|:---:|:---:|
+| Mutation tools (`click`, `type`, `fill`, etc.) | yes | yes | no | yes |
+| Read-only tools (`map`, `find`, `scrape`, `screenshot`) | yes | yes | yes | yes |
+| High-level orchestration (`burst`, `plan`, `wait`) | yes | yes | no | yes |
+| System management (`detect`, `reset_loop_counter`) | yes | no | no | no |

package/docs/architecture/transport.md

@@ -0,0 +1,37 @@
+---
+title: "Transport Modes"
+description: "stdio vs WebSocket — pick the right wire for your client."
+product: mcp
+section: architecture
+icon: Cable
+slug: transport
+---
+
+# Transport Modes
+
+| Mode | Flag | Protocol | Use Case |
+|---|---|---|---|
+| **stdio** | *(default)* | JSON-RPC 2.0 / stdio | Claude Desktop, Cursor, VS Code Copilot, Antigravity |
+| **WebSocket** | `--ws` | JSON-RPC 2.0 / WebSocket | Custom agents, Python/Go backends, remote daemons, n8n |
+
+## stdio (Default)
+
+The MCP client spawns Weavetab as a child process and pipes messages over stdin/stdout. No network port is opened:
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "weavetab"
+    }
+  }
+}
+```
+
+## WebSocket
+
+```bash
+weavetab --ws --port 3000
+```
+
+WebSocket mode binds strictly to `127.0.0.1` for local security. Front it with your own TLS/auth layer if exposing across a private network.

package/docs/captcha-stealth/captcha-solver.md

@@ -0,0 +1,75 @@
+---
+title: "CAPTCHA Solver"
+description: "Autonomous zero-API solver for Turnstile, GeeTest, and reCAPTCHA."
+product: mcp
+section: captcha-stealth
+badge: new
+icon: ShieldAlert
+slug: captcha-solver
+---
+
+# Autonomous Zero-API CAPTCHA Solver
+
+Weavetab features a built-in **Autonomous Zero-API CAPTCHA Solver** via the `browser_captcha` tool. It solves complex challenges locally using real CDP pointer physics, Bézier kinematics, and DOM heuristics — requiring **$0 external solver API costs** and zero third-party subscription keys (no 2Captcha, Anti-Captcha, or CapSolver needed).
+
+```typescript
+// Detect and solve active challenge automatically
+browser_captcha({ action: "solve", timeout: 60000 })
+```
+
+---
+
+## Supported Challenge Matrix
+
+| Challenge Type | Target Systems | Solving Technique | Zero API Cost |
+|---|---|---|:---:|
+| **Cloudflare Turnstile** | Cloudflare protected surfaces | Sustained mousedown + micro-jitter physics | Yes |
+| **GeeTest Slider** | GeeTest v3 / v4 puzzle sliders | Bézier velocity drag + momentum overshoot correction | Yes |
+| **Google reCAPTCHA v2** | Checkbox & iframe challenges | Nested cross-origin iframe pointer penetration | Yes |
+| **Google reCAPTCHA v3** | Invisible score-based barriers | High-entropy behavioral simulation bursts | Yes |
+| **Arkose Labs / FunCAPTCHA** | Interactive verification | Synthetic CDP pointer kinematics + rotation solver | Yes |
+| **hCaptcha** | Checkbox challenges | Cross-domain iframe dispatch + heuristic click | Yes |
+| **Math / Text Challenges** | Inline security prompts | DOM arithmetic evaluation + synthetic input | Yes |
+
+---
+
+## How It Works
+
+### 1. Cloudflare Turnstile & Interactive Checkboxes
+Cloudflare Turnstile evaluates the physical trajectory and hold duration of the click. Weavetab:
+- Calculates a randomized human Bézier path from current cursor coordinates to the checkbox center.
+- Dispatches CDP `Input.dispatchMouseEvent` with `mousePressed` event.
+- Applies **micro-jitter displacement** (1–3 pixel variations) for 120–280 ms simulating organic finger tremor.
+- Releases `mouseReleased` event and monitors CDP DOM mutations for success tokens.
+
+### 2. GeeTest & Slider Puzzles
+For slider challenges, Weavetab calculates the drag distance, applies variable velocity profiling (rapid acceleration, mid-flight coasting, deceleration), and introduces subtle overshoot correction:
+
+```text
+Start (0px) ──[Fast Accel]──► Mid (70%) ──[Decel]──► Target (100%) ──[Overshoot +2px]──► Final Lock
+```
+
+### 3. reCAPTCHA v2 & Cross-Origin Iframes
+reCAPTCHA isolates the checkbox inside cross-origin iframes (`anchor` frame). Weavetab penetrates the isolated iframe context via CDP `DOM.describeNode` and dispatches synthetic pointer events directly to the inner target.
+
+---
+
+## Tool API Reference: `browser_captcha`
+
+**Parameters:**
+| Parameter | Type | Description |
+|---|---|---|
+| `action` | `"detect" | "solve" | "wait_for_user" | "status"` *(required)* | Operation to perform. |
+| `timeout` | `number?` | Maximum timeout in milliseconds (default `120000`). |
+
+### Example Usage
+
+```typescript
+// Step 1: Detect if a CAPTCHA exists on page
+const detection = await browser_captcha({ action: "detect" });
+if (detection.detected) {
+  // Step 2: Solve autonomously
+  const result = await browser_captcha({ action: "solve", timeout: 45000 });
+  console.log("Solved:", result.success);
+}
+```

package/docs/captcha-stealth/stealth-physics.md

@@ -0,0 +1,60 @@
+---
+title: "Stealth & Physics"
+description: "Ghost Cursor Bézier kinematics, typing jitter, and anti-fingerprinting."
+product: mcp
+section: captcha-stealth
+icon: Sparkles
+slug: stealth-physics
+---
+
+# Stealth & Kinematic Physics
+
+Weavetab is built from the ground up to make AI automation indistinguishable from human input at the browser and DOM event levels.
+
+## 1. Ghost Cursor Bézier Kinematics
+
+Standard automation tools warp cursor coordinates instantaneously (`x: 0` → `x: 500` in 0ms), which triggers modern anti-bot heuristics.
+
+Weavetab's **Ghost Cursor** engine generates dynamic **cubic Bézier curves** with randomized control points for every movement:
+
+```text
+P0 (Current Pos) ──────► P1 (Control Pt 1) ──────► P2 (Control Pt 2) ──────► P3 (Target)
+```
+
+- **Acceleration Profiling**: Gaussian velocity distribution with natural ramp-up and ramp-down.
+- **Micro-Jitter**: Per-frame sub-pixel deviations mimicking human muscle tremor.
+- **Overshoot & Correction**: Intentional minor overshoots past the target element followed by corrective micro-adjustments.
+- **Visual Overlay**: Real-time canvas overlay rendering the glowing Ghost Cursor path in the browser window.
+
+---
+
+## 2. Human Keystroke Synthesis
+
+The `browser_type` engine dispatches native CDP `Input.dispatchKeyEvent` calls with realistic human timing profiles:
+
+- **Temporal Jitter**: Per-character delays sampled between 35 ms and 95 ms.
+- **Burst Profiling**: Common character digraphs (e.g., `th`, `er`, `ing`) are typed faster in bursts.
+- **Word Boundary Pauses**: Natural pauses (120–250 ms) after spaces and punctuation marks.
+- **Stuck-Input Breaking**: DOM diffing detects if keystrokes are failing to register and breaks out of deadlocks.
+
+---
+
+## 3. Layer 0 Fingerprint Spoofing
+
+Weavetab's early-script CDP injection guarantees that the following patches execute **before any page JavaScript runs**:
+
+```typescript
+// navigator.webdriver is permanently undefined
+Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+
+// Native plugin and mime-type arrays spoofed
+Object.defineProperty(navigator, 'plugins', { get: () => [1, 2, 3, 4, 5] });
+
+// WebGL vendor and renderer noise injection
+const getParameter = WebGLRenderingContext.prototype.getParameter;
+WebGLRenderingContext.prototype.getParameter = function(parameter) {
+  if (parameter === 37445) return 'Google Inc. (Intel)';
+  if (parameter === 37446) return 'ANGLE (Intel, Intel(R) UHD Graphics Direct3D11)';
+  return getParameter.apply(this, arguments);
+};
+```