BrowserPaw v3.2.7: Chained Snapshot Feedback, Stacking Occlusion Pruning & Zero-Conflict Third-Party Coexistence

📦 GitHub Release: BrowserPaw v3.2.7

• Tag: v3.2.7
• Title: BrowserPaw v3.2.7: Chained Snapshot Feedback, Stacking Occlusion Pruning & Zero-Conflict Third-Party Coexistence
• Target: main

---

🚀 Overview

BrowserPaw v3.2.7 is a major feature and reliability release that introduces chained incremental snapshots (slashing redundant DOM inspection round-trips), stacking & modal occlusion pruning (eliminating phantom clicks through dialog backdrops), zero-conflict third-party download coexistence (IDM, Aria2, FDM), and hardened Native Messaging UTF-8 protocol slicing.

---

🪲 What's Changed

1. ⚡ Chained Incremental Snapshot (interact-index.ts, fill-index.ts, delta-helper.ts)

• Single-Turn Perception & Action Fusion: chrome_interact_index and chrome_fill_index now capture and return a lightweight chainedSnapshot payload by default.
• Immediate State Feedback: Automatically surfaces current activeElement (tag, ID, role, input value), URL transition status (urlChanged), modal detection flags, and up to 10 prioritized DOM changes.
• 50% Turn Reduction: Eliminates the mandatory secondary chrome_read_dom call previously required after every interaction. Supports includeDelta: false for backward compatibility.

2. 🛡️ Stacking Context & Modal Occlusion Pruning (dom-indexer.ts)

• Viewport Boundary Clipping Fix: Fixed geometric bug where elements partially intersecting the viewport boundary escaped occlusion checks, restoring precise 9-point sub-pixel grid verification.
• Dialog & Backdrop Occlusion Filtering: Recognizes pointer-blocking overlays, semi-transparent masks (opacity ≥ 0.35), and modal dialogs ([role="dialog"], [aria-modal="true"], .modal-backdrop), pruning occluded background elements and preventing accidental click-throughs.

3. ⚡ Zero-Conflict Download Pipeline & IDM Coexistence

• Eradicated Global Listener: Completely removed chrome.downloads.onDeterminingFilename and internal filename registry.
• Third-Party Manager Coexistence: Eliminates filename determination collisions with external download managers (IDM, Aria2, Free Download Manager).
• Zero Disk Pollution: Visual media inspections operate strictly in-memory; download tracking runs non-invasively via onCreated and onChanged observers.

4. 🛡️ Native Tab Signature Validation & Red Error Badge Elimination (chrome_switch_tab)

• Integer Sanitation & Probing: Sanitizes tab ID parameters and verifies target existence before dispatching Chromium tab switch commands.
• Console Warning Demotion: Prevents fatal C++ binding exceptions (No matching signature) from triggering red "Error" badges in chrome://extensions.

5. 🔌 Protocol Hardening & Native Messaging UTF-8 Slicing

• Safe Byte Slicing (safe-post-message.ts): Implemented TextEncoder UTF-8 byte boundary slicing (850 KB/slice) with surrogate pair protection, preventing Chrome's 1 MB physical message limit from crashing the host pipe.
• Host Outbound Stream Transparency (native-messaging-host.ts): Removed premature 1 MB hard-rejection; large payloads stream transparently through chunking with EPIPE error guards.
• Keepalive Ref-Counting (keepalive-manager.ts): Upgraded to Map<string, number> reference counting to eliminate premature Service Worker suspension.

6. ⚖️ Legal & Governance Compliance

• AGPL-3.0 SPDX Standardization: Upgraded all package.json license fields to standard "AGPL-3.0-or-later" and aligned root LICENSE for automated GitHub licensee detection.
• Upstream Attribution (NOTICE): Added dedicated NOTICE preserving upstream MIT copyright for mcp-chrome (hangye).

---

📦 Release Assets & Checksums

Asset	Size	SHA256 Checksum
browserpaw-extension-v3.2.7.zip	611 KB	bba3dd2702d0cd7b6c03196bdf30020f69a23b0b1ddf4edbd6b83ee7852cbb4b
browserpaw-skill-v3.2.7.zip	36 KB	1a0d4e1c6fc4759a880184978a2beb2741afc10cc0828c9af18a7dd91c62cd1c

BrowserPaw v3.2.0: Physics Kinetic Cursor, Momentum Scrolling & Lockstep Lifecycle Binding

📦 GitHub Release: BrowserPaw v3.2.0

Important Notice: BrowserClaw has officially been renamed to BrowserPaw. All tool names, schemas, skills, and documentation are now unified under the BrowserPaw namespace with backward-compatible aliases preserved.

• Tag: v3.2.0
• Title: BrowserPaw v3.2.0: Physics Kinetic Cursor, Momentum Scrolling & Lockstep Lifecycle Binding
• Target: main

---

🚀 Overview

BrowserPaw v3.2.0 delivers a major upgrade focused on physics-based kinetic animations, zero-teleportation virtual cursor continuity, lockstep execution synchronization, hardware-adaptive autonomous intelligence (Dual-Brain Jev Engine), and leak-free tab group lifecycle management.

Key highlights of this release:

1. Eliminates cursor snapping and integer scroll drift with fluid spring kinematics and momentum scrolling.
2. Introduces a dynamic typewriter action tooltip with accent caret and viewport collision flipping.
3. Upgrades auto-mode human takeover to track true user interactions (including trackpad/wheel scrolls) without intrusive interference.
4. Firmly locks the execution lifecycle between visual perception, CDP hardware events, and MCP tool responses.
5. Embeds a hardware-adaptive, resident local Jev Decider engine with CUDA/MPS acceleration and CPU fallback.
6. Eliminates tab group residue and fixes Combobox text input handling across rich web apps.

All 842 automated monorepo tests (561 Vitest, 128 Jest, 153 E2E) pass with 100% compliance, zero TypeScript compilation errors, and zero ESLint warnings.

---

🌟 Key Highlights & Major Additions

1. 🎯 Zero-Teleportation Cursor Physics

• Cross-Domain Navigation Coordinate Relay: Virtual cursor positions are tracked globally across origin boundaries by the background service worker (lastTabCursorPositions). When navigating across domains, the destination content script seamlessly picks up fromX and fromY, gliding in smoothly rather than snapping.
• Dynamic Pre-Click Glide: When click actions are dispatched while the cursor is still in motion, the engine glides smoothly to target coordinates before releasing the ripple.
• Visual Continuity on Movement: All movements strictly execute natural bezier arc trajectories instead of instant frame-jumping.

2. 🪄 Action Tooltip & Typewriter Animation

• Refined Capsule Aesthetics: Aligned with modern system UI standards—dark charcoal rounded rectangle (rgba(24, 24, 27, 0.94)) with drop shadow.
• Dynamic Typewriter Reveal: Action notes (e.g. --note "Scrolling down timeline") render character-by-character at ~20ms/char with a blinking accent cursor (.codex-agent-caret).
• Collision-Aware Flipping: Centered below pointer tip; automatically flips above cursor when approaching the bottom viewport boundary.

3. 🌊 Momentum Scrolling & Delta Precision (chrome_smart_scroll)

• Momentum Deceleration Curve: Replaced rigid fixed steps with an adaptive 10–14 step decelerating curve spanning 180–260ms.
• Zero Rounding Drift: Replaced lossy integer rounding with continuous floating-point accumulation, guaranteeing exact pixel travel matching the requested delta.

4. 🧠 Intelligent Auto-Mode Human Takeover

• Sensory Perception: Detects authentic user interactions (e.isTrusted) across mousemove (with >18px filtering), mousedown, keydown, and wheel trackpad/mouse scroll events.
• Graceful Deferral: Automatically yields to human activity, deferring agent actions by 80ms to avoid intrusive cursor interference.

5. 🔒 Lockstep Lifecycle Synchronization (Animation <-> Action <-> Response)

• Multi-Click Lockstep: Double and triple clicks bind individual CDP mousePressed events to distinct visual click ripples with natural press duration.
• Concentric Multi-Ripple Cloning: Dynamically spawns independent ripple DOM instances (cloneNode(true)) with individual lifecycles.
• Arrival Guard: Unified arrival timeout ensuring CDP events never fire before visual cursor arrival.

6. ⚡ Hardware-Adaptive Resident Local Jev Engine

• Daemon Lifecycle: In local mode, BrowserPaw native server manages and health-checks the local decider daemon.
• Hardware Acceleration with Fallback: Automatically detects and leverages dedicated GPU acceleration (CUDA on Windows/Linux, MPS on macOS) while cleanly falling back to CPU when no discrete accelerator is available.
• Idle Offload Watchdog: Automatic 10-minute idle watchdog unloads models to release system memory and VRAM when inactive.

---

🪲 Bug Fixes & Architectural Hardening

• Fastify Local Token Authentication Guard: Hardened server/index.ts preHandler hook to reject unauthorized header bypasses, ensuring all tool calls require valid Bridge Token authentication.
• Searchbox Combobox Input Fix: Resolved issue in fill-core.ts where search inputs with role="combobox" were erroneously handled as select widgets; standard text typing is now guaranteed.
• Cursor State Continuity: Fixed cursor snapping caused by premature position deletion during tab navigation loading states.
• DOM Selector Escaping: Applied CSS.escape to element index selectors in action-watchdog.ts to prevent syntax crashes on complex node attributes.
• In-Page Engine Slot Isolation: Eliminated concurrent slot eviction race conditions in single-turn in-page executions.
• Media Asset Garbage Collection: Attached periodic unref'd timer to mediaAssetStore to prevent long-running buffer accumulation.

---

🧪 Verification Matrix

Test Suite	Framework	Target / Scope	Result
Extension Unit & Integration	Vitest	57 files, DOM indexer, form pipeline, agent cursor	561/561 PASS (100%)
Native Bridge & Jev Engine	Jest	7 suites, Stdio/HTTP dispatch, Jev model manager	128/128 PASS (100%)
E2E Modernization Suite	Node Test Runner	4 tiers (Feature coverage, boundaries, workflows)	153/153 PASS (100%)
TypeScript Typecheck	tsc --noEmit	Full Monorepo workspace packages	0 Errors (PASS)
ESLint Compliance	ESLint 9	Monorepo root, shared packages, extension	0 Errors (PASS)
Total Automated Tests	—	—	842 / 842 PASS (100%)

---

📦 What's Changed (Commit Log)

• feat(core): rename BrowserClaw to BrowserPaw across codebase and monorepo
• feat(cursor): zero-teleportation cross-navigation coordinate relay and glide-on-click mechanics
• feat(cursor): dynamic typewriter action tooltip with accent caret and dynamic viewport flip
• feat(scroll): 10–14 step momentum deceleration with zero rounding drift
• feat(cursor): upgraded auto mode with wheel event takeover and graceful yielding
• feat(sync): lockstep lifecycle synchronization across animations, CDP events, and MCP responses
• feat(jev): resident local Jev Decider daemon with hardware auto-detection and idle memory release
• fix(fill): resolve searchbox combobox false-positive widget interception in fill-core.ts
• fix(auth): harden Fastify local loopback authentication against header-only bypass
• fix(watchdog): add CSS.escape to element selectors and initial settle grace period
• release: bump all monorepo package versions to v3.2.0

---

🚀 Quick Installation (Zero-Compile, Ready-to-Use)

1. Chrome Extension Installation (Direct Download)

1. Download browserpaw-extension-v3.2.0.zip from the Assets section below.
2. Unzip the downloaded file to a local directory (e.g. C:\\browserpaw-extension or ~/browserpaw-extension).
3. Open Google Chrome (or Edge/Brave/Chromium), navigate to chrome://extensions/.
4. Turn on the Developer mode toggle in the top-right corner.
5. Click Load unpacked in the top-left toolbar, and select the unzipped directory containing manifest.json.
   (If updating from an existing installation, simply replace the folder contents and click the Reload button on the extension card).

2. Connect Your AI Agent / MCP Client

Add BrowserPaw to your MCP client configuration (Claude Desktop, Cursor, Windsurf, Codex, etc.):

Streamable HTTP (Recommended):

{
  "mcpServers": {
    "browserpaw": {
      "url": "http://127.0.0.1:12306/mcp"
    }
  }
}

Whenever Google Chrome is open with the BrowserPaw extension enabled, the MCP server on port 12306 will be available automatically.

---

🛠️ Developer Source Build (Optional)

If building directly from Git source:

pnpm install
pnpm build

v3.1.0 - Deep Shadow DOM Piercing, Anti-Timeout Protocol & 50-Tool Suite

BrowserClaw v3.1.0 Release Notes

Release Date: September 23, 2026
Tag: v3.1.0

---

🚀 Overview

BrowserClaw v3.1.0 represents a major architectural milestone. This release synthesizes the best design principles and engineering patterns from leading browser automation projects (jev-ultrafast, browser-use, browser-harness), implements full Deep Shadow DOM piercing, introduces client-side virtual DOM scroll resolution, hardens input commitment and anti-timeout protocols, expands the tool catalog to 50 canonical tools, and brings the complete Hermes 49-Tool Canonical Display & Rich Previews specification.

---

🌟 Key Highlights & Major Additions

1. 🎴 Hermes 49-Tool Canonical Display & Rich Card Previews

• Unified Tool Display Specs (BROWSERCLAW_SPECS): Injected native emoji icons, human-friendly action verbs, and concise input summaries across all canonical tools in plugins/browserclaw/__init__.py.
• Intelligent Rich Previews: Specialized extractors for interactive DOM trees, keyword grep results, element interactions, screenshot previews, Jev fast-decision loops, and CDP execution.
• Cross-Platform Parity: Identical visual structure rendered in Hermes native card widgets and standard MCP web/chat surfaces.

2. 🔮 Deep Shadow DOM Piercing & Visual Drift Compensation

• Closed & Nested Shadow DOM Piercing: Non-invasive shadow boundary traversal using chrome.dom.openOrClosedShadowRoot (dom-indexer), eliminating invasive main-world monkey-patching while giving agents 100% visibility into custom elements, web components, and nested shadow trees.
• Sub-Pixel Coordinate Calibration: Automatic viewport scale, device pixel ratio (DPR), and zoom level compensation for visual click and coordinate-based fallback execution.

3. 🛡️ Architectural Resilience & Anti-Timeout Protocol (Batches B1–B12)

• B1. Strict URL Scheme Sanitizer (url-sanitizer.ts): Rejection of hazardous protocols (javascript:, file:, chrome:) with URL parameter sanitization preventing credential leakage.
• B2. Correlated Action Network Capture (action-network-capture.ts): Correlation IDs linking network requests and responses directly to the user/agent action that triggered them.
• B3. Isolated PostMessage Protocol (safe-post-message.ts): Cryptographic session tokens and origin-validated communication channels between content scripts and in-page engines.
• B4. Tab Cleanup Session Affinity (chrome_close_tabs): Graceful teardown of agent-spawned background tabs without risking closure of user foreground tabs.
• B5. Fast DOM Snapshot Engine (fast-snapshot.ts): Lightweight, sub-15ms initial orientation snapshots bypassing heavyweight tree serialization.
• B6. Smart Scroll-Until-Found (chrome_scroll_until_found): 50th canonical tool utilizing client-side requestAnimationFrame scrolling to locate virtualized DOM items, dynamic feeds, and lazy-loaded components before indexing.
• B7. Operation Watchdog System (watchdogs/): Independent observers tracking dialog popups, downloads, and extension health to abort hung CDP or JS evaluations cleanly.
• B8. In-Page Event Loop & Microtask Draining (in-page-engine.ts): Enforces DOM and layout settlement after typing and clicking.
• B9. Unified Element Locator (unified-locator.ts): Hierarchical element targeting falling back gracefully between CSS selectors, XPath expressions, text patterns, and spatial coordinates.
• B10. Native Messaging Chunking Protocol (native-messaging-host.ts): Streamed multi-chunk protocol supporting payloads exceeding 1MB across Chrome Native Messaging boundaries.
• B11. Jev Fast Decision Engine Refinements (fast-decision-engine.ts): Tuned confidence thresholds, heuristics, and fallback policies for on-page semantic micro-loops.
• B12. Multi-Tab Session Snapshot Invalidation (snapshot-cache-manager.ts): Automatic cache invalidation on page mutations and navigation events ensuring DOM cache coherency.

4. 🪲 Core Defect Fixes & Precision Guards

• Anti-Deadlock Inline Auto-Submit: Configured skipLock: true when chrome_fill_index auto-submits a detected submit button, preventing concurrent lock contention.
• Destructive Guard Precision (extractTargetVisibleText): Keyword inspection runs against the element's human-visible label/text only—stripping technical attributes (id, class, href) to prevent false positives (e.g. Reddit flair button #reddit-post-flair-button no longer falsely triggers destructive post keyword).
• Navigation Race Resolution: findTab now resolves tab.pendingUrl during in-flight navigations.
• Baseline Pre-Interaction Snapshots: Captures pre-interaction DOM state prior to mutation to ensure exact delta calculation.

5. 📚 Skill Architecture & Documentation Modernization

• Progressive Disclosure Architecture: Re-architected SKILL.md for high information density (~1,800 tokens) with zero fluff, complemented by deep modular references:
  • tool-cheatsheet.md: Comprehensive 50-tool parameter and contract guide.
  • dual-brain-jev.md: Jev micro-loop mechanics, escalation thresholds, and safety breakpoints.
  • batch-pipeline.md: Atomic multi-action sequences, assertions, and inline network capture.
  • visual-fallback.md: Coordinate clicking, grid calibration, and vision fallbacks.
• Automated Synchronization: Guaranteed byte-for-byte synchronization across all 6 skill mirrors via scripts/sync-skills.mjs.

---

🧪 Verification & Test Metrics

• Unit Tests (chrome-mcp-server): 56 test files, 537/537 tests passed (100%).
• Bridge Tests (mcp-chrome-bridge): 6 test suites, 102/102 tests passed (100%).
• E2E Modern Test Runner: 4 tiers (F01–F13, boundary cases, pairwise, real-world workflows), 153/153 tests passed (100%).
• Python Plugin Tests (plugins/browserclaw): 20/20 tests passed (100%).
• TypeScript Typecheck (pnpm typecheck): 0 errors across all workspace packages.
• BrowserClaw Doctor Diagnostics: 7/7 checks passed (Node environment, bridge token, bridge server, MCP initialization, extension build, standalone sync, native host registration).

---

📦 Release Assets

• browserclaw-extension-v3.1.0.zip: Pre-built Chrome Extension (Manifest V3) ready for developer-mode unpacking or distribution.
• browserclaw-skill-v3.1.0.zip: Standalone AI Agent skill package with full progressive disclosure references.

v3.0.0 - Production Milestone Release

BrowserClaw v3.0.0 - Production Milestone Release

Milestone Release: Industrial-grade, anti-ghosting DOM perception and execution pipeline, true input commitment, non-intrusive active tab protection, and complete excision of legacy dead code.

---

Important

🚨 Strongly Recommended: Update BOTH the Extension and the Agent Skill

Due to breaking architectural consolidation, it is strongly recommended that all users update BOTH the Chrome Extension and the Agent Skill simultaneously:

1. Update Chrome Extension (browserclaw-extension-v3.0.0.zip):

   • Download, unzip to a persistent folder, and reload in chrome://extensions.
   • Why: Activates the 1ms active element focus guard (eliminating keystroke leakage in SPAs like Facebook registration), enables background silent operation that never steals user focus, and equips the browser with the F1–M3 atomic execution pipeline.

2. Update Agent Skill (browserclaw-skill-v3.0.0.zip):

   • Overwrite your agent skill directory (e.g. ~/.gemini/antigravity/skills/browserclaw, ~/.claude/skills/browserclaw, or your workspace skill folder).
   • Deeply Optimized Skill Architecture:
     • -84% Prompt Token Overhead: Overhauled with 153-line progressive disclosure, preventing context pollution while maintaining deep mastery of 49 canonical tools.
     • Tool Namespace Alignment: 100% synchronized with the registered browserclaw_* namespace.
     • Purged Dead Tools: Completely eliminates deprecated tools (chrome_scroll, chrome_fill_form, chrome_scroll_to_text), guiding agents straight to chrome_smart_scroll and chrome_batch_actions.
     • Added Production Recipes & Cheatsheets: Bundles batch-pipeline.md, dual-brain-jev.md, visual-fallback.md, and tool-cheatsheet.md.

---

🌟 Key Highlights & Major Enhancements

1. True Input Commitment & Anti-Ghosting Pipeline (Resolved GitHub Issue #3)

• Active Element Focus Guard (inPageVerifyActiveElement): Performs strict 1ms pre-CDP verification ensuring the target element is actively focused before Input.insertText executes. Aborts immediately with FocusVerificationError if focus cannot be established, eliminating keystroke leakage into previously focused fields on dynamic SPAs (e.g. Facebook registration).
• Anti-Concatenation Strict Verification (inPageVerifyInputCommitment): Replaced permissive .includes() checks with dual-track strict equality and clean formatting tolerance (e.g. phone number normalization, punctuation tolerance, currency prefixes $ , +1 ), while strictly rejecting cross-field string concatenations.
• Custom ARIA Combobox Support (inPageSelectCustomCombobox): Seamlessly controls div[role="combobox"] and [role="listbox"] dropdowns using word-boundary regular expressions, avoiding digit collision traps (e.g. selecting "1" instead of "10").
• Batch Pipeline Fault Barrier & Settling Window: Added a 60ms dynamic settling window in chrome_batch_actions and implemented instant failure propagation that halts execution when any form field fails.

2. Non-Intrusive Active Tab Protection & Silent Background Operation

• Active Tab Protection Guard: Browser automation requests default to background execution (active: false, focused: false). Prevents accidental overwrites of user-browsed foreground tabs.
• Task-Intent Tab Group Naming: Tab groups dynamically extract meaningful semantic titles from user intent and destination domains (e.g., "Best 4K Monitors on Amazon"), eliminating generic "Agent" fallback labels with cross-lifecycle session persistence.
• W3C Standard Composite Card Flattening: Automatically aggregates multi-node product cards and feed list items into concise, single-line summaries, slashing prompt token consumption by 60%–80%.
• Cross-Platform UTF-8 & Unicode PUA Filtering: Automatically purges Unicode Private Use Area (PUA) icon font characters to prevent fatal UnicodeEncodeError crashes on Windows GBK consoles.

3. Atomic High-Precision DOM Perception & Execution Pipeline (Phases F1 – M3)

• Phase F1 (Atomic Fast Snapshot): Introduces chrome_fast_snapshot and fast: true mode in chrome_read_dom, providing 10–30ms snapshots via weak-mapped node tracking and native visibility checks.
• Phase F2 (Controlled Component Penetration): Directly traverses prototype descriptors via getNativeValueSetter to bypass React 16–19 and Vue 3 controlled input traps with synthetic InputEvent sequences.
• Phase M1 (Pre-CDP Occlusion Circuit Breaker): Injects 1ms pre-flight elementFromPoint sampling before mouse dispatch, tripping a circuit breaker if target elements are occluded by modal backdrops or floating overlays.
• Phase M2 (Smart Micro-Wait Engine): Replaces fixed sleep delays with dynamic requestAnimationFrame + MutationObserver convergence, adding ARIA candidate watchdogs for combobox dropdowns.
• Phase M3 (HTML5 DataTransfer Upload Fallback): Automatically falls back to in-page HTML5 DataTransfer file uploads with Shadow DOM penetration when CDP or native messaging is restricted.

4. Complete Codebase Sanitization & 49 Canonical Tool Surface

• Physical Excision of Dead Tools: Completely removed legacy dead code (scroll.ts, fill-form.ts, scroll-to-text.ts, setFormValueNative, inPageScrollByIndex, and raw network capture constants).
• Tool Profiles Governance: 49 Canonical Tools organized into core (14 high-frequency tools, ~11.5k tokens), crawl (12 extraction tools, ~5.8k tokens), and full (49 tools) profiles, with dynamic session unlocking via chrome_tool_docs.
• English-Primary Standardization: Regenerated docs/TOOLS.md with 100% English descriptions and zero CJK leakage.

---

🧪 Verification & Quality Assurance

• Chrome Extension Vitest Suite: 52 files, 479 / 479 passed (100%)
• Native Bridge Jest Suite: 5 suites, 94 / 94 passed (100%)
• Master E2E Suite (Tier 1–4): 153 / 153 passed (100%)
• Node Platform Suite: 161 / 161 passed (100%)
• Total Automated Tests: 887 / 887 passed (0 failures)
• TypeScript Typecheck: 0 errors across all workspaces
• System Diagnostic (doctor.mjs): 7 / 7 Passed ([HEALTHY])

---

📦 Release Assets

• browserclaw-extension-v3.0.0.zip: Production Chrome Manifest V3 extension bundle (unzip and load via chrome://extensions).
• browserclaw-skill-v3.0.0.zip: Deeply optimized Agent Skill bundle with recipes, cheatsheets, and progressive disclosure references.

v2.9.3 - Architectural Hardening, Security Sandbox & Jev Engine Optimization

BrowserClaw v2.9.3 - Architectural Hardening, Security Sandbox & Jev Engine Optimization

TL;DR: Comprehensive hardening across security, browser control lifecycle, Jev/Heuristic decision engines, and packaging pipelines. Eliminates silent dialog auto-confirmation, restricts media file reading to a secure sandbox, fixes 401 token authentication on streamed media insertion, upgrades multi-word and mixed-script tokenization, removes dead state machine code, and synchronizes the tri-directory Agent Skill system.

Key Enhancements

1. Security & Safety Hardening

• CDP Dialog Protection: Removed indiscriminate automatic confirmation of Page.javascriptDialogOpening. Secondary confirmation prompts (deletions, payments, irreversible actions) are no longer silently auto-accepted, restoring full explicit control to agents via chrome_handle_dialog.
• Media File Read Sandbox: Enforced a strict extension whitelist (images, videos, PDFs) and directory traversal guards (.ssh, .aws, .env, .chrome-mcp) in readMediaFile, preventing unauthorized host file disclosure.
• Streamed Media Auth: Appended ?token= authorization to local media streaming requests (/media-asset/:assetId), unblocking insertion of assets larger than 650KB through Fastify's authentication gate.
• Anti-Deadlock Message Dispatch: Eliminated an un-raced await in sendMessageToTab when communicating with subframes, guaranteeing the 5000ms timeout guard always triggers if a frame is unresponsive.

2. Jev & Heuristic Decision Engine Optimization (Tier 1 Micro-Loop)

• Role-Aware Heuristic Actions: Prevented search/input intent keywords from overriding native element roles; buttons (role="button") are strictly clicked rather than erroneously filled with text.
• CJK / Latin Mixed Tokenization: Script-boundary tokenization preserves embedded alphanumeric entities (e.g. iPhone15) and eliminates spurious cross-word bigrams.
• State-Transition Goal Verification: Required verified state progression (urlChanged: true) before isGoalDone triggers keyword-based completion, preventing false-positive early exits on static pages.
• Perception Tree Sensitive Filter Refinement: Restricts password masking strictly to actual credential inputs, keeping non-input helper elements (e.g. 'Forgot password?') visible to Jev.
• Multi-Word Text Payload Extraction: Enhanced trailing keyword extraction with preposition boundaries (into, in, to, 到, 进) to prevent space truncation.
• Dead Code Pruning: Removed redundant 32-line safety breakpoint check from FastDecisionEngine and aligned fallback confidence thresholds with caller parameters.

3. Platform, Packaging & Lifecycle Hardening

• NPM Global Install Robustness: Packaged postinstall-guard.js into dist/scripts and exported main() from postinstall.ts, ensuring zero-error global installation.
• Native Host Parameter Forwarding: Added %* and "$@" forwarding in run_host.bat and run_host.sh to preserve Chrome-injected origin and parent-window context.
• CLI Robustness: Fixed argument parsing for URLs with multiple = signs and aligned non-zero exit codes on RPC errors.
• Asset Store Memory Management: Added 10-minute sliding TTL auto-cleanup to MediaAssetStore to prevent heap accumulation.
• Skill Architecture Synchronization: Aligned skills/browserclaw to match skill/ and plugin skill bundles (progressive disclosure 153-line structure).

Verification Record

• Monorepo Boost & Hardening Suite: 134/134 passed in 2.2s.
• Native Bridge Jest Suite: 4/4 suites, 89/89 passed in 6.2s.
• Chrome Extension Vitest Suite: 44/44 suites, 344/344 passed in 19.1s.
• TypeScript & Vue-TSC: 0 errors across entire workspace.
• Total Automated Tests: 567/567 passed (100% green).

Release Assets

• browserclaw-extension-v2.9.3.zip - Production Chrome MV3 extension package
• browserclaw-skill-v2.9.3.zip - Complete Agent Skill pack with reference guides

v2.9.2 - Robust MCP 2024-11-05 Session Handshake & Auto-Recovery

BrowserClaw v2.9.2 — Robust MCP 2024-11-05 Session Handshake & Auto-Recovery

TL;DR: Resolves the upstream Python plugin HTTP 400 session rejection by fully implementing standard MCP 2024-11-05 Streamable HTTP session initialization, header persistence, automatic recovery on expired sessions, and diagnostic transparency.

Key Enhancements

1. Standard MCP 2024-11-05 Session Handshake in Python Plugin

• Initial Handshake Protocol: Executes standard JSON-RPC 2.0 initialize request with client capabilities (protocolVersion: 2024-11-05) before dispatching tool calls.
• Header Tracking: Captures and persists the mcp-session-id response header returned from the server.
• Protocol Headers: Forwards both mcp-session-id and mcp-protocol-version: 2024-11-05 on
  otifications/initialized and all subsequent ools/call requests.
• Thread-Safe Session Cache: Synchronized session establishment with thread-safe locking and support for pre-configured session ID environment variables.

2. Self-Healing Automatic Session Recovery

• Transparent Recovery: Intercepts HTTP 400 (Invalid MCP request or session) and HTTP 404 (Session expired or not found), automatically resets the cached session ID, performs a fresh initialize handshake, and retries the tool call with zero caller intervention.
• Stale Pinned Session Invalidation: Blacklists stale session IDs configured via environment variables upon 400/404 errors, preventing infinite retry loops.

3. High-Fidelity Error Diagnostics & Native Server Hints

• Server Error Transparency: Preserves and surfaces exact server diagnostic JSON payloads and hints from HTTP errors instead of masking them behind generic connection failure notices.
• Native Server Actionable Hints: Enhances Native Server's Fastify HTTP transport with clear troubleshooting guidance when a client sends requests without an active session.

Verification Record

• Python Plugin Tests: 19/19 passed in 0.20s across both workspaces.
• Native Server Jest Suite: 4/4 suites, 89/89 passed in 6.61s.
• Monorepo E2E Runner: 4/4 tiers (T1-T4), 153/153 passed in 10.49s (100% compliance).
• TypeScript Typecheck: 0 errors across monorepo.
• Hash Parity: Byte-for-byte SHA256 verified between repository and runtime mirror.

Release Assets

• �rowserclaw-extension-v2.9.2.zip — Production Chrome MV3 extension package
• �rowserclaw-skill-v2.9.2.zip — Complete Agent Skill pack with reference guides

v2.9.1 - Hardened Deep Shadow DOM Piercing, Contextual Grep & Visual Drift Compensation

BrowserClaw v2.9.1 — Hardened Deep Shadow DOM Piercing, Contextual Grep & Visual Drift Compensation

TL;DR: Version 2.9.1 delivers production-grade hardening for deep multi-level Shadow DOM piercing (tested on complex Web Components like Reddit Shreddit / Faceplate), contextual Grep matching snippets, zero-drift visual fallback coordinate alignment with real-time scroll offset compensation, and unified documentation for all 48 canonical tools.

Key Architectural Fixes & Enhancements

1. Deep Shadow DOM Piercing & Web Component Accessibility Recovery

• Multi-Level Shadow Root Descent (deepElementFromPoint): Descends through nested open and closed Shadow DOM boundaries across arbitrary depths (e.g. <shreddit-comment> -> <faceplate-tracker> -> <button>), ensuring pointer hit tests resolve directly to the active interactive target rather than the outer custom element host.
• Accessible Name & Semantic Recovery: Enhanced extractCleanElementText to resolve aria-labelledby, aria-label, title, aria-description, inner <svg><title>, svg[aria-label], and parent custom element wrapper attributes (data-action, action), completely eliminating false positive decorative icon button pruning.
• Pointer-Events Gating Fix: Removed container-level pointer-events: none early-exit that previously halted traversal into child elements that re-enable pointer-events: auto.
• Closed Shadow Host Strategy: Candidate custom elements without accessible open shadow roots are tagged with isClosedShadowHost and rendered with [closed-shadow-host] in both DOM tree and compact perception formats, routing click interactions to the host bounding box where native CDP events bubble via composed: true.

2. Deep Text Extraction & Contextual Snippets in chrome_grep

• Contextual Centered Match Snippets: Fixed chrome_grep in page_text mode to extract centered contextual windows (...prefix [match] suffix...) around the matched substring instead of slicing from the beginning of the line.
• Deep Shadow Text Traversal (inPageExtractDeepPageText): Recursively extracts deep text across light DOM and shadow roots, resolving <slot> projections via assignedNodes({ flatten: true }) and including accessible [aria-label] attributes.
• Automatic Fallback for Interactive Queries: When searchType: 'interactive_only' yields 0 matches, chrome_grep automatically falls back to searching deep page text, returning matching text snippets with guidance on coordinate interaction.
• Extended Grep Key Coverage: Added matching for data-testid, data-action, aria-description, and data-click-id.

3. Visual Fallback Coordinate Alignment & Drift Elimination

• Document-Space Preservation: scaleCoordinates preserves absolute document space (isDocumentSpace: true) when processing fullpage screenshots (captureMode: 'fullpage'), avoiding coordinate compression into the 800px viewport.
• Real-Time Scroll Drift Compensation (alignVisualCoordinate): Converts visual targets to absolute document space and applies real-time scroll offset correction. If the target has scrolled out of view, BrowserClaw instantly auto-scrolls (inPageInstantScrollTo) to center the target before CDP click dispatch.
• Scroll Racing Lock (inPageLockScroll): Locks smooth scrolling to auto during CDP mouse press/release bursts, eliminating race conditions with inertia scrolling.
• Magnetic Snapping Edge-Case Fix: inPageSnapCoordinate auto-scrolls clipped or edge-straddling elements comfortably into view before computing the safe click center.

4. Full-Spectrum Docs & Skill Parity

• Re-verified all 48 canonical tools (including chrome_insert_media) across all documentation and references.
• Synchronized all 6 skill directories via scripts/sync-skills.mjs with verified byte-for-byte SHA-256 equivalence.

Verification Record

• TypeScript Compilation: 0 errors across monorepo (pnpm typecheck).
• Chrome Extension Tests: 44/44 test files passed, 344/344 tests passed (vitest).
• Native Bridge Tests: 4/4 test suites passed, 89/89 tests passed (jest).
• End-to-End Tests: 4/4 tiers passed, 153/153 tests passed (runner.ts).
• Total Automated Tests: 586/586 tests passing with 100% compliance.

Release Assets

• browserclaw-extension-v2.9.1.zip — Production Chrome MV3 extension package
• browserclaw-skill-v2.9.1.zip — Complete Agent Skill pack with reference guides

v2.9.0 - Deep Shadow DOM Piercing, Visual Coordinate Drift Compensation & 48-Tool Catalog

BrowserClaw v2.9.0 — Deep Shadow DOM Piercing, Visual Coordinate Drift Compensation & 48-Tool Catalog

TL;DR: Version 2.9.0 brings architectural solutions to two core automation challenges identified in complex modern Web Components (e.g. Reddit Shreddit, YouTube, X): Deep Shadow DOM penetration with semantic accessibility property extraction, and zero-drift visual fallback coordinate alignment with real-time scroll offset compensation. Additionally, all project documentation, skills, and schemas have been unified to 48 canonical tools.

Key Enhancements

1. Deep Shadow DOM Piercing & Web Component Accessibility Recovery

• Multi-Layer Shadow DOM Traversal: Implemented recursive querySelectorAllDeep and querySelectorDeep functions that penetrate arbitrary depths of open and closed Shadow DOM roots (including <shreddit-comment>, <faceplate-tracker>, <faceplate-button>), plus flattened <slot> element resolution via assignedElements({ flatten: true }).
• Semantic Name Recovery for Icon-Only Buttons: Enhanced extractCleanElementText to recover accessible text from aria-label, title, aria-description, and inner <svg><title> or svg[aria-label], completely preventing interactive icon buttons from being pruned as decorative noise.
• Closed Shadow Host Candidate Discovery: Detects custom elements with closed/null shadow roots (isCustomElement(node) && getShadowRoot(node) === null), retains them as indexed candidates, and leverages CDP native event dispatch at the host's bounding box where events bubble up through composed: true.
• Composed Tree Ancestry in Hit Testing: Exported composedParent and composedContains helpers, ensuring occlusion grid testing and magnetic snapping correctly traverse across shadow boundaries without misreporting shadow children as occluded by their own host elements.
• Deep Text Search in chrome_grep: Recursive shadow tree text extraction in page_text and interactive modes, expanding query matches across title, id, and name attributes.

2. Visual Fallback Coordinate Alignment & Real-Time Scroll Drift Compensation

• True Document Space for Full-Page Screenshots: Added isDocumentSpace to ScreenshotContext. Fullpage screenshots (captureMode: 'fullpage') now map coordinates directly to absolute document space without compressing long pages into the 800px viewport.
• Dynamic Scroll Delta Compensation (alignVisualCoordinate): Click execution measures page scroll position in real time via inPageGetScrollState and compensates for any scroll movement occurring during the network RTT window between screenshot capture and click execution.
• Automatic Scroll Centering: Document-space coordinates automatically trigger instant auto-scroll (inPageInstantScrollTo) to center the target coordinate in the viewport before dispatching physical CDP mouse events.
• Scroll Racing Lock (inPageLockScroll): Temporarily disables smooth/inertia scrolling during CDP mouse down/up sequences to eliminate race conditions between page motion and click delivery.

3. Full-Spectrum Project Documentation & 48 Canonical Tools Unification

• Updated all project documentation (README.md, README.zh-CN.md, PROJECT.md, PROJECT.zh-CN.md, docs/MAP.md, docs/TOOLS.md, docs/mcp-cli-config.md, docs/TROUBLESHOOTING.zh-CN.md, GitHub repository description, and extension manifests) to reflect all 48 canonical tools (including chrome_insert_media).
• Executed scripts/sync-skills.mjs and verified byte-for-byte SHA-256 equivalence across all 6 skill directories.

Test & Verification Record

• TypeScript Typecheck: Zero errors across monorepo (pnpm typecheck).
• Chrome Extension Vitest Suite: 44/44 test files passed, 336/336 tests passed (100% compliance, including new deep-shadow-and-visual-drift.test.ts).
• Native Bridge Jest Suite: 4/4 test suites passed, 89/89 tests passed (100% compliance).
• End-to-End Suite: 4/4 tiers passed, 153/153 tests passed (100% compliance).
• Total Tests Passed: 578 automated tests passing across all layers.

Release Assets

• browserclaw-extension-v2.9.0.zip — Production Chrome MV3 extension package
• browserclaw-skill-v2.9.0.zip — Complete Agent Skill pack with reference guides

v2.8.3 - Priority Scroll, Safety Breakpoints, Multiline Preservation & Media Injection

BrowserClaw v2.8.3 — Priority Scroll Engine, Safety Breakpoints, Multiline Preservation & Media Injection

TL;DR: Version 2.8.3 addresses critical user-testing feedback and production edge cases in real-world agent automation (e.g. Reddit, X/Twitter, complex rich-text editors), introducing an intelligent Priority Scroll Engine that eliminates sidebar hijacking, fine-grained Safety Breakpoints in System 1 autonomous loops, robust multiline newline preservation for modern rich-text composers, and native high-resolution media/diagram injection (chrome_insert_media) up to 50MB.

Key Enhancements

1. Priority Scroll Engine in chrome_smart_scroll (Sidebar Hijacking Fix)

• Problem: When attempting to scroll through main feeds or comment sections (e.g. Reddit), narrow sidebars (such as reddit-sidebar-nav) were frequently misidentified as the scroll target and scrolled to 100% bottom while the primary content remained motionless.
• Solution: Implemented an intelligent multi-signal scoring algorithm in inPageFindSmartScrollTarget:
  • Horizontal Center-Proximity Weight: Prioritizes containers positioned along the central reading axis of the viewport.
  • Sidebar Penalty: Heavily penalizes narrow vertical columns (width < 300px) and semantic navigation tags (<nav>, <aside>, role="navigation").
  • Semantic Main Boost: Adds positive weight to <main>, <article>, and role="main" containers.
  • Center Probe Fallback: Probes document.elementFromPoint(window.innerWidth / 2, window.innerHeight / 2) to discover scrollable containers directly under the central viewing area.
  • Default to Root Window: Falls back smoothly to window scroll (window.scrollBy) if no main container meets scrollability thresholds.

2. Safety Breakpoints in chrome_act_toward_goal (pauseBeforeKeywords: string[])

• Problem: Users need System 1 (Jev/heuristic) to autonomously navigate forms, select tags, and type draft text without human intervention, but require the agent to stop immediately before triggering irreversible commit actions (e.g. "Post", "Submit", "Pay", "Delete").
• Solution: Added pauseBeforeKeywords?: string[] to chrome_act_toward_goal:
  • When the next intended element matches any keyword in pauseBeforeKeywords, execution halts prior to action dispatch.
  • Returns status: "paused", pausedBeforeAction: { action, target: { index, text, role } }, and fresh currentElements.
  • Prioritized ahead of destructive escalations, enabling System 2 (Macro Supervisor) or the human user to review draft state and commit via chrome_interact_index with zero DOM re-reads.

3. Multiline Newline Preservation in chrome_fill_index

• Problem: Modern rich-text composers and frameworks (Draft.js, Lexical, ProseMirror, Slate, Quill, CodeMirror) frequently collapse \n characters into single spaces or ignore them when filled via standard value assignment or single input events.
• Solution:
  • Detects multiline input strings containing \n.
  • Splits text by paragraphs and dispatches physical CDP Enter events (rawKeyDown + keyUp, keyCode 13) between segments.
  • Dispatches beforeinput events with inputType: 'insertParagraph' and in-page DOM paragraph mutations.
  • Normalized newline verification in inPageVerifyInputCommitment to guarantee robust commit detection across both plain textareas and rich-text nodes.

4. Native Asset & Image Injection (chrome_insert_media — 48 Canonical Tools)

• New Tool: Introduced canonical tool #48: chrome_insert_media (INSERT_MEDIA).
• Input Sources: Supports local disk file paths (filePath), local file URLs (fileUrl), remote URLs (mediaUrl), and raw base64 payloads (base64Data).
• High-Capacity Streaming: Native Server streams files larger than 650KB (up to 50MB, including high-res 4K diagrams and screen captures) via an in-memory loopback HTTP endpoint (/media-asset/:assetId), cleanly bypassing the 1MB Chrome Native Messaging IPC ceiling.
• Native DOM Event Synthesis: Synthesizes authentic ClipboardEvent('paste') and DragEvent('drop') containing native File and DataTransfer objects, seamlessly accepted by drag-and-drop zones, file paste handlers, and image upload dropboxes.

5. Skill & Documentation Synchronization

• Synchronized tool documentation across all repositories and guides to reflect 48 canonical tools.
• Updated skill/SKILL.md, skill/references/dual-brain-jev.md, and all mirror skill registries (~/.gemini/config/skills/browserclaw/, ~/.gemini/config/skills/mcp-chrome/).
• Updated .browserclaw-managed.json content hashes.

Test & Verification Record

• TypeScript Typecheck: Zero errors across monorepo (pnpm typecheck).
• Chrome Extension Test Suite: 43/43 test files passed, 325/325 tests passed (vitest run, including new comprehensive tests for priority scroll, multiline newline preservation, and media injection).
• Native Bridge Jest Suite: 4/4 test suites passed, 89/89 tests passed.
• E2E Test Runner: 4/4 tiers passed, 153/153 tests passed (100% compliance).

Release Assets

• browserclaw-extension-v2.8.3.zip — Production Chrome MV3 extension package
• browserclaw-skill-v2.8.3.zip — Complete Agent Skill pack with reference guides

BrowserClaw v2.8.2 - Progressive Disclosure Skill Architecture & Dual-Brain Optimization

BrowserClaw v2.8.2 — Progressive Disclosure Skill Architecture & Dual-Brain Optimization

TL;DR: Version 2.8.2 delivers a major architectural refactoring and deep optimization of the Agent Skill system, establishing the Hierarchical Dual-Brain execution workflow (Macro Planner System 2 + Fast Semantic Micro-Loop System 1 Jev) with an industry-standard Progressive Disclosure architecture (~2,000 tokens), zero-redundancy trigger matrix, complete elimination of ghost parameters, and byte-level synchronization across all skill mirrors.

Key Enhancements

1. Progressive Disclosure Agent Skill Architecture

• High Information Density: Main SKILL.md (~2,000 tokens) provides complete coverage of trigger scenarios, tool selection matrix, explicit input/output contracts, and hard operational constraints without attention dilution or token bloat.
• Hierarchical Dual-Brain Execution:
  • Macro Planner (System 2 / Caller LLM): Focuses on high-level goal formulation, multi-page strategy, navigation, and supervisory escalation handling.
  • Semantic Micro-Loop (System 1 / Fast Brain / Jev): Operates locally in Native Server at 200–400ms/step via chrome_act_toward_goal, eliminating 80%+ remote network roundtrips.
• Explicit 5-Step Execution Workflow:
  • Step 1: Navigate & Orient (chrome_navigate, chrome_get_markdown)
  • Step 2: Delegate Sub-Goal to System 1 (chrome_act_toward_goal)
  • Step 3: Handle Status (done vs. escalate vs. stuck vs. blocked)
  • Step 4: Precision Macro Intervention & Recovery (Zero-Read candidate reuse from currentElements)
  • Step 5: Verify & Stale Index Recovery (includeDelta: true, mutated, STALE_ELEMENT_INDEX)
• 6-Tier Routing Hierarchy:
  • Tier 1: Semantic Micro-Loop (chrome_act_toward_goal — default 70% for on-page action goals)
  • Tier 0: Deterministic Primitives (chrome_get_markdown, chrome_batch_actions, chrome_interact_index, chrome_fill_index — 20%)
  • Tier 2: In-Page Scripting & API Bypass (chrome_javascript, chrome_network_request — 5%)
  • Tier 3: Visual Fallback (chrome_screenshot, chrome_computer — 3%)
  • Tier 4: Human Handoff (chrome_request_human_intervention — 1%)
  • Tier 5: Raw CDP Escape Hatch (chrome_cdp_execute — <0.1%)
• Specialized Reference Guides (skill/references/):
  • references/dual-brain-jev.md: Local Jev System 1 scoring contracts, heuristic fallback, escalation guards, and Macro Supervisor Recovery Protocol.
  • references/batch-pipeline.md: Atomic interaction pipelines, assertions (assert), extractions (extract), inline network capture, and autonomous wizard filling (chrome_form_pipeline).
  • references/visual-fallback.md: DPR 1:1 viewport normalization, calibrated grid rulers, Set-of-Mark 2.0, GoFullPage captures, and PCIE polymorphic coordinates.
  • config/TROUBLESHOOTING.md: Port conflicts, token authorization, and automated self-repair scripts.

2. Strict Operational Constraints & Parameter Integrity

• 1-Based Index Integrity: Strict adherence to 1-based indices ([1], [2], [3]) from chrome_read_dom and currentElements.
• Parameter Invariants: Complete elimination of ghost parameters; exact schema alignment (index, grid: true, action: 'accept', code: in chrome_javascript, coordinates in chrome_computer, query in chrome_form_pipeline).
• Background Tab Isolation: All background tabs enforce background: true (creating tabs with active: false and windows with focused: false) to safeguard user foreground focus.
• Native Event Fidelity: Dispatches physical CDP events (isTrusted: true) natively compatible with modern web frameworks (React 18/19, Vue, Angular, Shadow DOM).
• Active Tab Closure Protection: chrome_close_tabs requires confirm: true or explicit IDs.
• Zero-RTT Commits: pressEnter: true on chrome_fill_index enables 1-turn search and submission.

3. Complete Multi-Platform Mirror Synchronization

• Byte-for-byte exact synchronization across all authoritative repositories and user configuration registries:
  • skill/
  • plugins/browserclaw/skills/browserclaw/
  • Production distribution mirror (D:\workspace\browserclaw\)
  • Global Agent skill registries (~/.gemini/config/skills/browserclaw/, ~/.gemini/config/skills/mcp-chrome/)

Test & Quality Verification

• TypeScript Typecheck: 0 errors across all monorepo packages (pnpm typecheck)
• Vitest Extension Suite: 42/42 test files passed, 320/320 tests passed (vitest run, +14 schema guard tests)
• Native Bridge Jest Suite: 4/4 test suites passed, 86/86 tests passed
• E2E Test Suites: 153/153 tests passed (100% compliance across Tier 1–4 suites)
• Monorepo Build: Complete clean production build for packages/shared, app/chrome-extension, and app/native-server

Release Assets

• browserclaw-extension-v2.8.2.zip — Production Chrome MV3 extension build
• browserclaw-skill-v2.8.2.zip — Optimized Progressive Disclosure Agent Skill pack with reference guides