Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

clean up TODO: condense done, add bugs, reprioritize

bot70dfb0968a11
diff --git a/TODO.md b/TODO.md
index 0477a6ba..9daf7619 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,88 +1,30 @@
# Pinchtab — TODO
-## Done ✅
-- [x] Session persistence — save/restore tabs on shutdown/startup
-- [x] Graceful shutdown — save state on SIGTERM/SIGINT
-- [x] Launch helper — self-launches Chrome, no manual CDP flags
-- [x] Snapshot pruning — `?filter=interactive`, `?depth=N`
-- [x] `/text` endpoint — body text extraction
-- [x] Ref resolution via DOM.resolveNode + backendDOMNodeId
-- [x] Stealth mode — webdriver hidden, UA spoofed, automation flags removed
-- [x] Tab registry — contexts survive across requests
-- [x] Ref stability — snapshot caches ref→nodeID mapping per tab, actions use cached refs
-- [x] Action timeouts — 15s default, prevents hung pages blocking handlers
-- [x] Tab cleanup — background goroutine removes stale entries every 30s
-- [x] Tab restore on startup — loadState() called, tabs reopened
+## Completed (P0–P5)
+Safety, file split, Go idioms, testability, features — all done.
+38 tests passing, 0 lint issues. See git history for details.
-## Done ✅ (P0)
-- [x] `http.MaxBytesReader` (1MB) on all POST handlers
-- [x] `r.Context()` propagated — `cancelOnClientDone` cancels CDP on client disconnect
-- [x] Graceful shutdown with `context.WithTimeout` (10s)
-- [x] `cleanStaleTabs` accepts `context.Context` — no goroutine leak
-- [x] `tabContext` lock — RLock fast path, Lock only on miss, double-check pattern
-- [x] Errors wrapped with `%w` consistently
-- [x] All ignored errors handled (`os.MkdirAll`, `json.Encode`, `os.WriteFile`, `json.MarshalIndent`)
+Key deliverables: session persistence, stealth mode, ref caching, action registry,
+hover/select/scroll actions, smart diff, text format, readability /text,
+BridgeAPI interface, handler tests, nil guard, deprecated flag removal.
-## Done ✅ (P1)
-Split into 8 files (single package):
-- [x] `config.go` (33 lines) — env vars, constants
-- [x] `bridge.go` (117 lines) — Bridge struct, tabContext, cleanStaleTabs
-- [x] `snapshot.go` (60 lines) — A11yNode, raw a11y types, interactiveRoles
-- [x] `cdp.go` (76 lines) — clickByNodeID, typeByNodeID, listTargets
-- [x] `state.go` (112 lines) — save/restore, markCleanExit
-- [x] `handlers.go` (545 lines) — all HTTP handlers
-- [x] `middleware.go` (53 lines) — auth, CORS, jsonResp, cancelOnClientDone
-- [x] `main.go` (152 lines) — Chrome launch, routes, signal handling
+---
-## Done ✅ (P2)
-- [x] Handlers are Bridge methods (receiver pattern, no free functions)
-- [x] Action registry `map[string]ActionFunc` replaces switch in handleAction
-- [x] `scrollIntoViewIfNeeded` before click and type actions
-- [x] Constants for magic strings (targetTypePage, filterInteractive, action/tab kinds)
-- [x] `log/slog` structured logging throughout (replaces `log.Printf`)
-- [x] Godoc comments on all exported types and methods
-- [x] `//go:embed stealth.js` — stealth script in separate file
-- [x] Chrome opts grouped by concern (profile, stealth, perf, UI, identity)
+## Bugs & In Progress
+- [ ] **Navigate timeout on some SPAs** — `navigatePage` 500ms sleep isn't enough for heavy JS pages. Consider polling `document.readyState` instead.
+- [ ] **Restore navigates all tabs at once** — can overwhelm CPU/memory on startup with many tabs. Should queue or limit concurrency.
+- [ ] **Screenshot base64 returns raw bytes** — `"base64": <bytes>` in JSON, should be actual base64 string encoding.
-## Done ✅ (P3)
-- [x] Navigate uses raw `Page.navigate` + 500ms sleep (not chromedp.Navigate full load)
-- [x] Restore is non-blocking (fire-and-forget goroutines, server starts instantly)
-- [x] Request logging middleware (method/path/status/ms via slog)
-- [x] Port changed 18800 → 9867, state dir ~/.browser-bridge → ~/.pinchtab
-- [x] ActionFunc takes full `actionRequest` struct (no more fragmented params)
-
-## Done ✅ (P4)
-- [x] Extract `Browser` interface (navigate, screenshot, evaluate) → `interfaces.go`
-- [x] Extract `TabManager` interface (get, create, close, list) → `interfaces.go`
-- [x] Extract `buildSnapshot` from handler → testable pure function in `snapshot.go`
-- [x] Add snapshot unit tests — a11y tree filtering/parsing, depth, interactive filter
-- [x] Add middleware tests — auth, CORS, logging, jsonResp, jsonErr (httptest)
-- [x] Add bridge tests — ref cache concurrency, ref lookup
-- [x] Add config tests — envOr, homeDir, constants
-- [x] **18 tests passing** — `go test ./...`
-
-## Done ✅ (P5)
-- [x] **`withElement` helper** — generic `withElement(ctx, nodeID, jsFunc)` + `withElementArg` for all element actions
-- [x] **`hover` action** — mouseover/mouseenter via ref, selector
-- [x] **`select` action** — pick `<select>` option by value or text, fires change event
-- [x] **`scroll` action** — scroll to element (ref), by pixel amount (`scrollX`/`scrollY`), or default 800px down
-- [x] **Smart diff** — `?diff=true` returns added/changed/removed nodes since last snapshot
-- [x] **Wait for navigation** — `"waitNav": true` on click action, 1s delay for page load
-- [x] **Text format** — `?format=text` returns indented tree (~40-60% fewer tokens than JSON)
-- [x] **21 tests passing** — diff, text format, all existing tests green
-
-## Done ✅ (P5c)
-- [x] **BridgeAPI interface** — `interfaces.go` with TabContext, ListTargets, CreateTab, CloseTab, Get/Set/DeleteRefCache
-- [x] **Handlers use Bridge methods** — No direct `b.mu`/`b.snapshots`/`b.tabs` access in handlers
-- [x] **CreateTab/CloseTab on Bridge** — Tab lifecycle extracted from handleTab
-- [x] **Nil browserCtx guard** — ListTargets + TabContext return error instead of panic
-- [x] **22 handler tests** — All validation/error paths tested via httptest without Chrome
-- [x] **38 total tests passing**, 0 lint issues
+## P6: Next Up
+- [ ] **Action chaining** — `POST /actions` batch multiple actions in one call (big token saver for agents)
+- [ ] **`/cookies` endpoint** — read/set cookies (auth debugging)
+- [ ] **LaunchAgent/systemd** — auto-start on boot
+- [ ] **Config file** — `~/.pinchtab/config.json` (alternative to env vars)
-## Done ✅ (P5b)
-- [x] **Remove `--disable-blink-features=AutomationControlled` flag** — deprecated in Chrome 144+, stealth.js handles it
-- [x] **Better /text** — Readability-style extraction (`readability.js`), strips nav/footer/aside/ads, prefers article/main. `?mode=raw` for old innerText.
-- [x] **Split handlers.go** — snapshot handler extracted to `handler_snapshot.go`
+## P7: Nice to Have
+- [ ] **File-based output** — `?output=file` saves snapshot to disk, returns path
+- [ ] **Compact format** — YAML or indented text instead of JSON
+- [ ] **Docker image** — `docker run pinchtab` with bundled Chromium
## Future: Desktop App Restructure
When a second binary (desktop app via Wails) is needed, restructure to:
@@ -96,15 +38,6 @@ frontend/ # dashboard HTML/JS
```
Until then, flat structure is correct. Don't premature-abstract.
-## P7: Nice to Have
-- [ ] **File-based output** — `?output=file` saves snapshot to disk, returns path (Playwright CLI approach)
-- [ ] **Compact format** — YAML or indented text instead of JSON
-- [ ] **Action chaining** — `POST /actions` batch multiple actions in one call
-- [ ] **Docker image** — `docker run pinchtab` with bundled Chromium
-- [ ] **Config file** — `~/.pinchtab/config.json`
-- [ ] **LaunchAgent/systemd** — auto-start on boot
-- [ ] **`/cookies` endpoint** — read/set cookies (useful for auth debugging)
-
## Not Doing
- Plugin system
- Proxy rotation / anti-detection