Skip to content

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.md
new file mode 100644
index 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.md
index 6ac78745..48681114 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,7 +19,7 @@ BRIDGE_HEADLESS=true ./pinchtab
git 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
## Style
diff --git a/Dockerfile b/Dockerfile
index 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 builder
RUN apk add --no-cache git
WORKDIR /build
COPY go.mod go.sum ./
diff --git a/README.md b/README.md
index 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 |
## Architecture
diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md
index 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.md
index 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 installer
diff --git a/docs/docker.md b/docs/docker.md
index 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`)
## Architecture
diff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.md
index 2454abfa..2e9d2dae 100644
--- a/skill/pinchtab/SKILL.md
+++ b/skill/pinchtab/SKILL.md
@@ -33,12 +33,24 @@ metadata:
- name: BRIDGE_NO_RESTORE
optional: true
description: "Skip restoring tabs from previous session (true/false)"
- - name: BRIDGE_CHROME_VERSION
+ - name: BRIDGE_STEALTH
optional: 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_IMAGES
optional: true
description: "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_CONFIG
optional: true
description: "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 JSON
curl "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 format
curl "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 file
curl "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) |