High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: comprehensive review — CHANGELOG, updated all docs, skill, Docker
Mario1f0fd58a579d
diff --git a/CHANGELOG.md b/CHANGELOG.mdnew file mode 100644index 00000000..8933a2fb--- /dev/null+++ b/CHANGELOG.md@@ -0,0 +1,55 @@+# Changelog++## Unreleased (v0.4.0)++### Added+- **Tab locking** — `POST /tab/lock`, `POST /tab/unlock` with timeout-based deadlock prevention for multi-agent coordination+- **Tab ownership** — `/tabs` shows `owner` and `lockedUntil` on locked tabs+- **Token optimization** — `maxTokens`, `selector`, `format=compact` params on `/snapshot`+- **CSS animation disabling** — `BRIDGE_NO_ANIMATIONS` env var + `?noAnimations=true` per-request+- **Stealth levels** — `BRIDGE_STEALTH=light` (default) vs `full`; light mode works with X.com and most sites+- **Welcome page** — headed mode shows 🦀 branding on startup+- **`CHROME_BINARY`** — custom Chrome/Chromium path support+- **`CHROME_FLAGS`** — extra Chrome flags (space-separated)+- **`BRIDGE_BLOCK_MEDIA`** — block all media (images + fonts + CSS + video)+- **`/welcome` endpoint** — serves embedded welcome page++### Fixed+- **K10** — Profile hang on startup (lock file cleanup, unclean exit detection, 15s timeout, auto-retry)+- **K11** — File output `path` param now honored, auto-creates parent dirs+- **`blockImages` on `CreateTab`** — global image/media blocking applied to new tabs+- **`Date.getTimezoneOffset` infinite recursion** — stealth script was calling itself; saved original method reference+- **UA mismatch detection** — removed hardcoded User-Agent override, Chrome uses native UA++### Changed+- Default stealth level changed from `full` to `light` (compatibility over fingerprint resistance)+- Dockerfile Go version updated to 1.26+- Coverage improved from 28.9% to 36%+++## v0.3.0++- Stealth suite (navigator, WebGL, canvas noise, font metrics, WebRTC, timezone, plugins, Chrome flags)+- Human interaction (bezier mouse, typing simulation)+- Fingerprint rotation via CDP+- Image blocking (`BRIDGE_BLOCK_IMAGES`)+- Stealth injection on all tabs (CreateTab + TabContext)+- Multi-agent concurrency verified (MA1-MA8)+- 92 unit tests + ~100 integration tests++## v0.2.0++- Session persistence (cookies, tabs survive restarts)+- Config file support+- Readability `/text` endpoint+- Smart diff (`?diff=true`)+- YAML/file output formats+- Handler split (4 files)++## v0.1.0++- Initial release+- Core HTTP API (16 endpoints)+- Accessibility tree snapshots with stable refs+- Chrome DevTools Protocol bridge+- Tab management+- Basic stealth (webdriver, chrome.runtime, plugins)diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 6ac78745..48681114 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -19,7 +19,7 @@ BRIDGE_HEADLESS=true ./pinchtabgit config core.hooksPath .githooks```-Requires **Go 1.24+** and **Google Chrome**.+Requires **Go 1.25+** and **Google Chrome**.## Development Workflow@@ -48,13 +48,22 @@ Tests don't require a running Chrome instance.Single Go package, all files in root:- `main.go` — entry point, Chrome launch, routes-- `handlers.go` — HTTP handlers-- `snapshot.go` — accessibility tree parsing+- `handlers.go` — HTTP handlers (navigate, screenshot, tabs, lock)+- `handler_snapshot.go` — snapshot handler (a11y tree, format, file output)+- `handler_actions.go` — action/actions handlers+- `handler_cookies.go` — cookie get/set+- `handler_stealth.go` — stealth status, fingerprint rotation+- `snapshot.go` — a11y tree parsing- `cdp.go` — Chrome DevTools Protocol helpers-- `bridge.go` — tab management-- `config.go` — environment config+- `bridge.go` — tab management, Chrome lifecycle+- `config.go` — environment config, embedded assets+- `lock.go` — tab locking for multi-agent coordination+- `animations.go` — CSS animation disabling+- `human.go` — human-like interaction (bezier mouse, typing)- `state.go` — session persistence-- `middleware.go` — auth, CORS+- `middleware.go` — auth, CORS, logging+- `stealth.js` — stealth script (light/full modes)+- `welcome.html` — headed mode welcome page## Stylediff --git a/Dockerfile b/Dockerfileindex a9798d91..f955f80b 100644--- a/Dockerfile+++ b/Dockerfile@@ -1,5 +1,5 @@# Build stage-FROM golang:1.25-alpine AS builder+FROM golang:1.26-alpine AS builderRUN apk add --no-cache gitWORKDIR /buildCOPY go.mod go.sum ./diff --git a/README.md b/README.mdindex 2b182f1b..a69579c0 100644--- a/README.md+++ b/README.md@@ -178,17 +178,19 @@ All via environment variables:|----------|---------|-------------|| `BRIDGE_PORT` | `9867` | HTTP server port || `BRIDGE_TOKEN` | *(none)* | Bearer token for auth |-| `BRIDGE_HEADLESS` | `false` | Run Chrome in headless mode (no window). Default is headed (visible). |+| `BRIDGE_HEADLESS` | `false` | Run Chrome headless (no window) || `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile directory || `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage || `BRIDGE_NO_RESTORE` | `false` | Skip restoring tabs from previous session |-| `BRIDGE_CHROME_VERSION` | `133.0.6943.98` | Chrome version in User-Agent strings (keep current to avoid detection) |-| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading (faster, lower bandwidth) |+| `BRIDGE_STEALTH` | `light` | Stealth level: `light` (basic) or `full` (canvas/WebGL/font spoofing) |+| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |+| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) || `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions globally || `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) || `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |-| `BRIDGE_CHROME_VERSION` | `133.0.6943.98` | Chrome UA version string || `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file |+| `CHROME_BINARY` | *(auto)* | Path to Chrome/Chromium binary |+| `CHROME_FLAGS` | *(none)* | Extra Chrome flags (space-separated) || `CDP_URL` | *(none)* | Connect to existing Chrome instead of launching |## Architecturediff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.mdindex f6fdea17..b1eac910 100644--- a/THIRD_PARTY_LICENSES.md+++ b/THIRD_PARTY_LICENSES.md@@ -54,6 +54,12 @@ Pinchtab depends on the following open-source packages. All are compatible with- **URL:** https://github.com/golang/sys- **Purpose:** Go system call wrappers+### gopkg.in/yaml.v3+- **License:** Apache 2.0 / MIT+- **Copyright:** (c) 2006-2011 Kirill Simonov, (c) 2011-2019 Canonical Ltd+- **URL:** https://github.com/go-yaml/yaml+- **Purpose:** YAML output format for snapshots+## Summary| Package | License | Compatible |@@ -66,5 +72,6 @@ Pinchtab depends on the following open-source packages. All are compatible with| gobwas/httphead | MIT | ✅ || gobwas/pool | MIT | ✅ || golang.org/x/sys | BSD 3-Clause | ✅ |+| gopkg.in/yaml.v3 | Apache 2.0/MIT | ✅ |-All dependencies are MIT or BSD 3-Clause licensed, fully compatible with Pinchtab's MIT license.+All dependencies are MIT, BSD 3-Clause, or Apache 2.0 licensed, fully compatible with Pinchtab's MIT license.diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 362bdec1..17b6f32d 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -32,15 +32,21 @@ pinchtab/├── config.go # Configuration: env vars, config file, embedded assets├── bridge.go # Bridge struct: tab management, Chrome lifecycle├── interfaces.go # BridgeAPI interface (for test mocking)-├── handlers.go # HTTP handlers: navigate, action, evaluate, cookies, stealth+├── handlers.go # HTTP handlers: navigate, screenshot, tabs, lock, shutdown├── handler_snapshot.go # Snapshot handler: a11y tree fetch, format, file output+├── handler_actions.go # Action/actions handlers: click, type, press, fill, etc.+├── handler_cookies.go # Cookie get/set handlers+├── handler_stealth.go # Stealth status, fingerprint rotation├── snapshot.go # A11y tree parsing: CDP response → flat A11yNode list+├── lock.go # Tab locking for multi-agent coordination+├── animations.go # CSS animation disabling (global + per-request)├── human.go # Human-like interaction: bezier mouse, natural typing├── cdp.go # Raw CDP helpers: navigate, readyState polling├── state.go # Session persistence: save/restore tabs to disk├── middleware.go # HTTP middleware: logging, auth token, CORS-├── stealth.js # Stealth script: injected into every page via CDP+├── stealth.js # Stealth script: light/full modes, injected via CDP├── readability.js # Readability extraction for /text endpoint+├── welcome.html # Headed mode welcome page (🦀 branding)├── Dockerfile # Alpine + Chromium container image└── scripts/├── install-autostart.sh # LaunchAgent/systemd installerdiff --git a/docs/docker.md b/docs/docker.mdindex 17887490..8faba882 100644--- a/docs/docker.md+++ b/docs/docker.md@@ -50,8 +50,14 @@ docker run -d \Environment variables:- `BRIDGE_PORT` - HTTP port (default: 9867)- `BRIDGE_TOKEN` - Auth token (optional)-- `BRIDGE_HEADLESS` - Run Chrome headless (default: true)+- `BRIDGE_HEADLESS` - Run Chrome headless (default: true in Docker)- `BRIDGE_STATE_DIR` - State directory (default: /data)+- `BRIDGE_STEALTH` - Stealth level: `light` (default) or `full`+- `BRIDGE_BLOCK_IMAGES` - Block image loading (default: false)+- `BRIDGE_BLOCK_MEDIA` - Block all media (default: false)+- `BRIDGE_NO_ANIMATIONS` - Disable CSS animations (default: false)+- `CHROME_BINARY` - Set automatically in Docker (`/usr/bin/chromium-browser`)+- `CHROME_FLAGS` - Set automatically in Docker (`--no-sandbox --disable-gpu`)## Architecturediff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.mdindex 2454abfa..2e9d2dae 100644--- a/skill/pinchtab/SKILL.md+++ b/skill/pinchtab/SKILL.md@@ -33,12 +33,24 @@ metadata:- name: BRIDGE_NO_RESTOREoptional: truedescription: "Skip restoring tabs from previous session (true/false)"- - name: BRIDGE_CHROME_VERSION+ - name: BRIDGE_STEALTHoptional: true- description: "Chrome UA version string (default: 133.0.6943.98)"+ description: "Stealth level: light (default, basic) or full (canvas/WebGL/font spoofing)"- name: BRIDGE_BLOCK_IMAGESoptional: truedescription: "Block image loading for faster, lower-bandwidth browsing (true/false)"+ - name: BRIDGE_BLOCK_MEDIA+ optional: true+ description: "Block all media: images + fonts + CSS + video (true/false)"+ - name: BRIDGE_NO_ANIMATIONS+ optional: true+ description: "Disable CSS animations/transitions globally (true/false)"+ - name: CHROME_BINARY+ optional: true+ description: "Path to Chrome/Chromium binary (auto-detected if not set)"+ - name: CHROME_FLAGS+ optional: true+ description: "Extra Chrome flags, space-separated"- name: BRIDGE_CONFIGoptional: truedescription: "Path to config JSON file (default: ~/.pinchtab/config.json)"@@ -118,16 +130,31 @@ curl "http://localhost:9867/snapshot?diff=true"# Text format — indented tree, ~40-60% fewer tokens than JSONcurl "http://localhost:9867/snapshot?format=text"+# Compact format — one-line-per-node, 56-64% fewer tokens than JSON (recommended)+curl "http://localhost:9867/snapshot?format=compact"+# YAML formatcurl "http://localhost:9867/snapshot?format=yaml"+# Scope to CSS selector (e.g. main content only)+curl "http://localhost:9867/snapshot?selector=main"++# Truncate to ~N tokens+curl "http://localhost:9867/snapshot?maxTokens=2000"++# Combine for maximum efficiency+curl "http://localhost:9867/snapshot?format=compact&selector=main&maxTokens=2000&filter=interactive"++# Disable animations before capture+curl "http://localhost:9867/snapshot?noAnimations=true"+# Write to filecurl "http://localhost:9867/snapshot?output=file&path=/tmp/snapshot.json"```Returns flat JSON array of nodes with `ref`, `role`, `name`, `depth`, `value`, `nodeId`.-**Token optimization**: Use `?filter=interactive` for action-oriented tasks (~75% fewer tokens). Use `?diff=true` on multi-step workflows to see only what changed. Use `?format=text` for cheapest structured output. Use full snapshot only when you need complete page understanding.+**Token optimization**: Use `?format=compact` for best token efficiency. Add `?filter=interactive` for action-oriented tasks (~75% fewer nodes). Use `?selector=main` to scope to relevant content. Use `?maxTokens=2000` to cap output. Use `?diff=true` on multi-step workflows to see only changes. Combine all params freely.### Act on elements@@ -235,6 +262,22 @@ curl -X POST http://localhost:9867/tab \Multi-tab: pass `?tabId=TARGET_ID` to snapshot/screenshot/text, or `"tabId"` in POST body.+### Tab locking (multi-agent)++```bash+# Lock a tab (default 30s timeout, max 5min)+curl -X POST http://localhost:9867/tab/lock \+ -H 'Content-Type: application/json' \+ -d '{"tabId": "TARGET_ID", "owner": "agent-1", "timeoutSec": 60}'++# Unlock+curl -X POST http://localhost:9867/tab/unlock \+ -H 'Content-Type: application/json' \+ -d '{"tabId": "TARGET_ID", "owner": "agent-1"}'+```++Locked tabs show `owner` and `lockedUntil` in `/tabs`. Returns 409 on conflict.+### Batch actions```bash@@ -282,7 +325,8 @@ curl http://localhost:9867/health| `/text` | ~800 | Reading page content || `/snapshot?filter=interactive` | ~3,600 | Finding buttons/links to click || `/snapshot?diff=true` | varies | Multi-step workflows (only changes) |-| `/snapshot?format=text` | ~40-60% less | Structured tree, cheaper than JSON |+| `/snapshot?format=compact` | ~56-64% less | One-line-per-node, best token efficiency |+| `/snapshot?format=text` | ~40-60% less | Indented tree, cheaper than JSON || `/snapshot` | ~10,500 | Full page understanding || `/screenshot` | ~2K (vision) | Visual verification |@@ -298,8 +342,12 @@ curl http://localhost:9867/health| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile dir || `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage || `BRIDGE_NO_RESTORE` | `false` | Skip tab restore on startup |-| `BRIDGE_CHROME_VERSION` | `133.0.6943.98` | Chrome UA version string |-| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading (faster, lower bandwidth) |+| `BRIDGE_STEALTH` | `light` | Stealth level: `light` or `full` |+| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |+| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |+| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions |+| `CHROME_BINARY` | (auto) | Path to Chrome/Chromium binary |+| `CHROME_FLAGS` | (none) | Extra Chrome flags (space-separated) || `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file || `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) || `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |