High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: update README + skill for P5 features (hover/select/scroll, diff, text format, readability, correct ports)
botd14332b44702
diff --git a/QA-RETEST.md b/QA-RETEST.mdnew file mode 100644index 00000000..4707f5c3--- /dev/null+++ b/QA-RETEST.md@@ -0,0 +1,78 @@+# Pinchtab QA Retest — 2026-02-15 16:27++**Build:** latest main (no new commits since last QA)+**Tester:** Bosch (automated retest)++---++## Bug Fix Results++### 🟡 P1 — `newTab:true` → ✅ PASS+Tabs went from 3→4 after `navigate` with `newTab:true`. New tab opened correctly.++### 🟡 P1 — `/action` Unhelpful Error → ✅ PASS+Response: `{"error":"missing required field 'kind' — valid values: click, type, fill, press, focus, hover, select, scroll"}`+Lists valid values as expected.++### 🟢 P2 — `/navigate` Empty Title → ⚠️ PARTIAL+- **BBC:** ✅ returns `"BBC - Home"`+- **x.com:** ❌ still returns `"title":""`+- x.com uses heavy JS/SPA hydration — title may need longer wait or DOMContentLoaded fallback++### 🟢 P2 — `/text` Google Language Blob → ✅ PASS+Language picker blob (Afrikaans, azərbaycanca, etc.) is gone. Google /text now returns clean content.++---++## 🔴 P0 — Active Tab Tracking — STILL BROKEN++This is the **critical outstanding bug**. After `/navigate`, `/text` and `/snapshot` frequently return data from a **stale tab** instead of the most recently navigated one.++**Evidence from retest:**+| Navigated to | /text returned | /snapshot returned |+|---|---|---|+| x.com | Google data (stale) | Google snapshot (stale) |+| LinkedIn | GitHub data (stale) | GitHub snapshot (stale) |++The active tab pointer drifts, especially when navigating rapidly between sites. Sometimes it works (Google→BBC was fine), sometimes it doesn't.++---++## Performance — Token Counts (Corrected for Active Sites Only)++Only showing results where active tab was correctly tracked:++| Site | /snapshot tokens | /text tokens | Previous /snapshot | Previous /text |+|------|-----------------|-------------|-------------------|---------------|+| Google | ~848 | ~143 | ~2K | ~764 |+| GitHub | ~9,835 | ~1,249 | ~9.8K | ~1.2K |+| BBC | ~26,598 | ~3,479 | ~26.7K | ~3.5K |+| Wikipedia | ~20,474 | ~3,306 | ~20.5K | ~3.5K |+| x.com | ❌ stale | ❌ stale | ~2K | ~121 |+| LinkedIn | ❌ stale | ❌ stale | ~7.5K | ~6.1K |++**Changes from previous benchmarks:**+- Google /text dropped significantly (~764→~143 tokens) — likely the language picker fix removing bloat ✅+- Google /snapshot also smaller (~2K→~848) — same reason+- All other tracked sites are essentially unchanged+- x.com and LinkedIn couldn't be measured due to active tab bug++---++## Summary++| Fix | Status |+|-----|--------|+| `newTab:true` opens new tab | ✅ PASS |+| `/action` missing kind lists valid values | ✅ PASS |+| `/navigate` BBC returns title | ✅ PASS |+| `/navigate` x.com returns title | ❌ FAIL (still empty) |+| `/text` Google language blob removed | ✅ PASS |+| Active tab tracking (P0) | ❌ STILL BROKEN |++**3 of 4 targeted fixes confirmed working.** x.com title remains empty.++**The P0 active tab tracking bug is the main blocker** — it makes sequential navigate→read workflows unreliable. This must be fixed before Pinchtab can be used for multi-site automation.++### Go Tests+`go test ./...` → ✅ all pass (cached)diff --git a/README.md b/README.mdindex 79c0f874..e3a0d588 100644--- a/README.md+++ b/README.md@@ -78,10 +78,12 @@ Pinchtab launches its own Chrome with a persistent profile at `~/.pinchtab/chrom- 🌲 **Accessibility-first** — structured tree with stable refs (`e0`, `e1`...) for click, type, read- 🎯 **Smart filters** — `?filter=interactive` returns only buttons/links/inputs (~75% fewer tokens)-- 🖱️ **Direct actions** — click, type, fill, press, focus by ref or CSS selector+- 🖱️ **Direct actions** — click, type, fill, press, focus, hover, select, scroll by ref or CSS selector- 🕵️ **Stealth mode** — patches `navigator.webdriver`, spoofs UA, hides automation flags- 💾 **Session persistence** — cookies, auth, tabs survive restarts-- 📝 **Text extraction** — raw `innerText` for minimal token cost+- 📝 **Text extraction** — readability mode (strips nav/ads) or raw `innerText`+- 🔄 **Smart diff** — `?diff=true` returns only changes since last snapshot+- 📄 **Text format** — `?format=text` for indented tree (~40-60% fewer tokens than JSON)- ⚡ **JS evaluation** — escape hatch for anything the API doesn't cover- 📸 **Screenshots** — JPEG with quality control for visual verification@@ -93,9 +95,9 @@ Pinchtab launches its own Chrome with a persistent profile at `~/.pinchtab/chrom| `GET` | `/tabs` | List open tabs || `GET` | `/snapshot` | Accessibility tree (primary interface) || `GET` | `/screenshot` | JPEG screenshot (opt-in) |-| `GET` | `/text` | Readable page text |+| `GET` | `/text` | Readable page text (readability or raw) || `POST` | `/navigate` | Go to URL |-| `POST` | `/action` | Click, type, fill, press, focus |+| `POST` | `/action` | Click, type, fill, press, focus, hover, select, scroll || `POST` | `/evaluate` | Execute JavaScript || `POST` | `/tab` | Open/close tabs |@@ -105,6 +107,14 @@ Pinchtab launches its own Chrome with a persistent profile at `~/.pinchtab/chrom| `tabId` | Target tab (default: first tab) || `filter=interactive` | Only buttons, links, inputs || `depth=N` | Max tree depth |+| `diff=true` | Return only added/changed/removed nodes since last snapshot |+| `format=text` | Indented plain text instead of JSON (~40-60% fewer tokens) |++### Query Parameters (text)+| Param | Description |+|-------|-------------|+| `tabId` | Target tab (default: first tab) |+| `mode=raw` | Raw `innerText` instead of readability extraction |## Configuration@@ -181,17 +191,17 @@ Everything else is Go standard library.## Requirements-- **Go 1.21+** (build from source) or download a [prebuilt binary](https://github.com/pinchtab/pinchtab/releases)+- **Go 1.24+** (build from source) or download a [prebuilt binary](https://github.com/luigi-agosti/pinchtab/releases)- **Google Chrome** or Chromium installed## Install```bash# From source-go install github.com/pinchtab/pinchtab@latest+go install github.com/luigi-agosti/pinchtab@latest# Or clone and build-git clone https://github.com/pinchtab/pinchtab.git+git clone https://github.com/luigi-agosti/pinchtab.gitcd pinchtabgo build -o pinchtab .```@@ -199,12 +209,12 @@ go build -o pinchtab .## Development```bash-git clone https://github.com/pinchtab/pinchtab.git+git clone https://github.com/luigi-agosti/pinchtab.gitcd pinchtabgo build -o pinchtab ../pinchtab-# Run tests (coming soon)+# Run tests (38 tests)go test ./...```diff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.mdindex dc594830..b5f9d533 100644--- a/skill/pinchtab/SKILL.md+++ b/skill/pinchtab/SKILL.md@@ -31,10 +31,10 @@ BRIDGE_HEADLESS=true pinchtab &pinchtab &```-Default port: `18800`. Override with `BRIDGE_PORT=18801`.+Default port: `9867`. Override with `BRIDGE_PORT=9868`.Auth: set `BRIDGE_TOKEN=<secret>` and pass `Authorization: Bearer <secret>`.-Base URL for all examples: `http://localhost:18800`+Base URL for all examples: `http://localhost:9867`## Core Workflow@@ -52,7 +52,7 @@ Refs (e.g. `e0`, `e5`, `e12`) are cached per tab after each snapshot — no need### Navigate```bash-curl -X POST http://localhost:18800/navigate \+curl -X POST http://localhost:9867/navigate \-H 'Content-Type: application/json' \-d '{"url": "https://example.com"}'```@@ -61,55 +61,90 @@ curl -X POST http://localhost:18800/navigate \```bash# Full tree-curl http://localhost:18800/snapshot+curl http://localhost:9867/snapshot# Interactive elements only (buttons, links, inputs) — much smaller-curl "http://localhost:18800/snapshot?filter=interactive"+curl "http://localhost:9867/snapshot?filter=interactive"# Limit depth-curl "http://localhost:18800/snapshot?depth=5"+curl "http://localhost:9867/snapshot?depth=5"++# Smart diff — only changes since last snapshot (massive token savings)+curl "http://localhost:9867/snapshot?diff=true"++# Text format — indented tree, ~40-60% fewer tokens than JSON+curl "http://localhost:9867/snapshot?format=text"```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 full snapshot only when you need to read page content.+**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.### Act on elements```bash# Click by ref-curl -X POST http://localhost:18800/action \+curl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "click", "ref": "e5"}'# Type into focused element (click first, then type)-curl -X POST http://localhost:18800/action \+curl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "click", "ref": "e12"}'-curl -X POST http://localhost:18800/action \+curl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "type", "ref": "e12", "text": "hello world"}'# Press a key-curl -X POST http://localhost:18800/action \+curl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "press", "key": "Enter"}'# Focus an element-curl -X POST http://localhost:18800/action \+curl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "focus", "ref": "e3"}'# Fill (set value directly, no keystrokes)-curl -X POST http://localhost:18800/action \+curl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "fill", "selector": "#email", "text": "[email protected]"}'++# Hover (trigger dropdowns/tooltips)+curl -X POST http://localhost:9867/action \+ -H 'Content-Type: application/json' \+ -d '{"kind": "hover", "ref": "e8"}'++# Select dropdown option (by value or visible text)+curl -X POST http://localhost:9867/action \+ -H 'Content-Type: application/json' \+ -d '{"kind": "select", "ref": "e10", "value": "option2"}'++# Scroll to element+curl -X POST http://localhost:9867/action \+ -H 'Content-Type: application/json' \+ -d '{"kind": "scroll", "ref": "e20"}'++# Scroll by pixels (infinite scroll pages)+curl -X POST http://localhost:9867/action \+ -H 'Content-Type: application/json' \+ -d '{"kind": "scroll", "scrollY": 800}'++# Click and wait for navigation (link clicks)+curl -X POST http://localhost:9867/action \+ -H 'Content-Type: application/json' \+ -d '{"kind": "click", "ref": "e5", "waitNav": true}'```### Extract text```bash-curl http://localhost:18800/text+# Readability mode (default) — strips nav/footer/ads, keeps article/main content+curl http://localhost:9867/text++# Raw innerText (old behavior)+curl "http://localhost:9867/text?mode=raw"```Returns `{url, title, text}`. Cheapest option (~1K tokens for most pages).@@ -118,16 +153,16 @@ Returns `{url, title, text}`. Cheapest option (~1K tokens for most pages).```bash# Raw JPEG bytes-curl "http://localhost:18800/screenshot?raw=true" -o screenshot.jpg+curl "http://localhost:9867/screenshot?raw=true" -o screenshot.jpg# With quality setting (default 80)-curl "http://localhost:18800/screenshot?raw=true&quality=50" -o screenshot.jpg+curl "http://localhost:9867/screenshot?raw=true&quality=50" -o screenshot.jpg```### Evaluate JavaScript```bash-curl -X POST http://localhost:18800/evaluate \+curl -X POST http://localhost:9867/evaluate \-H 'Content-Type: application/json' \-d '{"expression": "document.title"}'```@@ -136,15 +171,15 @@ curl -X POST http://localhost:18800/evaluate \```bash# List tabs-curl http://localhost:18800/tabs+curl http://localhost:9867/tabs# Open new tab-curl -X POST http://localhost:18800/tab \+curl -X POST http://localhost:9867/tab \-H 'Content-Type: application/json' \-d '{"action": "new", "url": "https://example.com"}'# Close tab-curl -X POST http://localhost:18800/tab \+curl -X POST http://localhost:9867/tab \-H 'Content-Type: application/json' \-d '{"action": "close", "tabId": "TARGET_ID"}'```@@ -154,28 +189,31 @@ Multi-tab: pass `?tabId=TARGET_ID` to snapshot/screenshot/text, or `"tabId"` in### Health check```bash-curl http://localhost:18800/health+curl http://localhost:9867/health```## Token Cost Guide| Method | Typical tokens | When to use ||---|---|---|-| `/text` | ~1K | Reading page content |-| `/snapshot?filter=interactive` | ~5K | Finding buttons/links to click |-| `/snapshot` | ~20K | Full page understanding |+| `/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` | ~10,500 | Full page understanding || `/screenshot` | ~2K (vision) | Visual verification |-**Strategy**: Start with `/snapshot?filter=interactive`. Use full `/snapshot` only when you need to read static text or understand layout. Use `/text` when you only need the readable content.+**Strategy**: Start with `/snapshot?filter=interactive`. Use `?diff=true` on subsequent snapshots in multi-step tasks. Use `/text` when you only need the readable content. Use `?format=text` to cut token costs further. Use full `/snapshot` only for complete page understanding.## Environment Variables| Var | Default | Description ||---|---|---|-| `BRIDGE_PORT` | `18800` | HTTP port |+| `BRIDGE_PORT` | `9867` | HTTP port || `BRIDGE_HEADLESS` | `false` | Run Chrome headless || `BRIDGE_TOKEN` | (none) | Bearer auth token |-| `BRIDGE_PROFILE` | `~/.browser-bridge/chrome-profile` | Chrome profile dir |+| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile dir |+| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage || `BRIDGE_NO_RESTORE` | `false` | Skip tab restore on startup || `CDP_URL` | (none) | Connect to existing Chrome DevTools |