CLAUDE.md

1# browse — `caveman-browse` browser driver
2 
3Local, agent-facing browser interaction for the open Caveman surface. It serves
4stdio MCP tools that read a real Chrome accessibility tree, compress it with the
5engine's forced-only `a11y` compressor, act on `uid` handles, and recover the
6byte-exact original AX payload through CCR. Every saving here is `inferred`;
7Browse never emits `verified`.
8 
9## Layout
10- `session.go` — MCP tool handlers, engine/CCR integration, UID target cache.
11- `cdp.go` — chromedp-backed Mode-A dedicated Chrome driver and bounded
12  actionability recipe.
13- `cmd/caveman-browse/` — stdio MCP binary.
14 
15## Gotchas
16- This package may import CDP/network/browser dependencies. `public/mcp` may not.
17- `go test ./public/browse/...` is setup-free. `make test-browse` resolves an
18  installed Playwright Chromium or system Chrome and runs the `integration`
19  build-tagged CDP contract across the package and direct CLI; `make
20  test-browser` adds extension tests and `make test-e2e` includes both.
21- The actionability layer is intentionally bounded: same-origin dashboards and
22  predictable design-system controls, not arbitrary-open-web parity.
23- Unknown handles/actions fail closed with `cave_snake_code` errors.
24- Snapshot output is compact indented text, not JSON-lines. `query` keeps at most
25  12 highest-scoring task matches plus ancestors; recovery metadata exposes only
26  UIDs actually shown. Keep `tokens_after` equal to exact agent-visible result
27  cost and `view_tokens` equal to serializer output cost.
28- Direct CLI Chrome is detached so separate `snapshot`/`act`/`eval` processes
29  can share a target. `close` must terminate it. Fresh `CAVEMAN_HOME` must work;
30  state writes stay atomic and mode `0600`.
31- CDP action acknowledgement is not application settlement. Non-wait actions
32  return `settled:false` and require a focused resnapshot for proof.
33- Navigation denies `file:`, `javascript:`, and privileged Chrome schemes.
34- Benchmark contract and reproducible Playwright comparison live in
35  `BENCHMARK.md`; keep token budgets executable in tests.
36- **The uid map is `browser_snapshot`'s contract, not a side effect of a
37  compression ratio.** On engine pass-through (no recovery handle — a tree that
38  did not get smaller, or no CCR store) `snapshotTool` fails closed with
39  `cave_browser_snapshot_uncompressed` and returns the prior page's uids intact;
40  it MUST NEVER dump the raw AX tree into `uids` (strictly worse than not using
41  Browse) nor wipe the target cache. Regressing this reopens issue #140.
42- **An `<iframe>` is a leaf, not a broken tree.** `Accessibility.getFullAXTree`
43  returns one frame at a time, so an iframe node's `childId` points at a child
44  document absent from this payload; the `a11y` compressor
45  (`engine/compressors/axtree.go`) treats an unresolvable `childId` as a leaf and
46  still curates the frame-visible nodes. Because of that the CDP driver keeps
47  Chrome's default Site Isolation (`site-per-process`) — do not disable it to
48  "fix" cross-origin iframes.
49