Skip to content

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.md
new file mode 100644
index 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.md
index 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.git
cd pinchtab
go 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.git
cd pinchtab
go 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.md
index 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 |