CLAUDE.md@browse git:20260816.f71f6dfA

Immutable. This exact content is served forever at /api/v1/blob/9349875f0e78e4e3.

# browse — `caveman-browse` browser driver

> **Repository routing:** do not continue Browse product work here. Source of
> truth is `JuliusBrussee/caveman-browse`, local checkout
> `/Users/julb/Desktop/GitHub/caveman-browse`. This directory is a consumer
> copy; edit only for pinned integration, migration/removal, or an explicit
> cross-repo sync. Accessibility-compressor work stays here in
> `engine/compressors/axtree.go` because Engine is owned by this repo.

Local, agent-facing browser interaction for the open Caveman surface. It serves
stdio MCP tools that read a real Chrome accessibility tree, compress it with the
engine's forced-only `a11y` compressor, act on `uid` handles, and recover the
byte-exact original AX payload through CCR. Every saving here is `inferred`;
Browse never emits `verified`.

## Layout
- `session.go` — MCP tool handlers, engine/CCR integration, UID target cache.
- `cdp.go` — chromedp-backed Mode-A dedicated Chrome driver and bounded
  actionability recipe.
- `cmd/caveman-browse/` — stdio MCP binary.

## Gotchas
- This package may import CDP/network/browser dependencies. `public/mcp` may not.
- `go test ./public/browse/...` is setup-free. `make test-browse` resolves an
  installed Playwright Chromium or system Chrome and runs the `integration`
  build-tagged CDP contract across the package and direct CLI; `make
  test-browser` adds extension tests and `make test-e2e` includes both.
- The actionability layer is intentionally bounded: same-origin dashboards and
  predictable design-system controls, not arbitrary-open-web parity.
- Unknown handles/actions fail closed with `cave_snake_code` errors.
- Snapshot output is compact indented text, not JSON-lines. `query` keeps at most
  12 highest-scoring task matches plus ancestors; recovery metadata exposes only
  UIDs actually shown. Keep `tokens_after` equal to exact agent-visible result
  cost and `view_tokens` equal to serializer output cost.
- Direct CLI Chrome is detached so separate `snapshot`/`act`/`eval` processes
  can share a target. `close` must terminate it. Fresh `CAVEMAN_HOME` must work;
  state writes stay atomic and mode `0600`.
- CDP action acknowledgement is not application settlement. Non-wait actions
  return `settled:false` and require a focused resnapshot for proof.
- Navigation denies `file:`, `javascript:`, and privileged Chrome schemes.
- Benchmark contract and reproducible Playwright comparison live in
  `BENCHMARK.md`; keep token budgets executable in tests.
- **The uid map is `browser_snapshot`'s contract, not a side effect of a
  compression ratio.** On engine pass-through (no recovery handle — a tree that
  did not get smaller, or no CCR store) `snapshotTool` fails closed with
  `cave_browser_snapshot_uncompressed` and returns the prior page's uids intact;
  it MUST NEVER dump the raw AX tree into `uids` (strictly worse than not using
  Browse) nor wipe the target cache. Regressing this reopens issue #140.
- **An `<iframe>` is a leaf, not a broken tree.** `Accessibility.getFullAXTree`
  returns one frame at a time, so an iframe node's `childId` points at a child
  document absent from this payload; the `a11y` compressor
  (`engine/compressors/axtree.go`) treats an unresolvable `childId` as a leaf and
  still curates the frame-visible nodes. Because of that the CDP driver keeps
  Chrome's default Site Isolation (`site-per-process`) — do not disable it to
  "fix" cross-origin iframes.