Skip to content

feat(browser): drive real headless Chrome over the DevTools pipe (PR 1 of 2) - #72

Merged
bsommers merged 9 commits into
mainfrom
feat/browser-real-cdp
Nov 10, 2026
Merged

bsommers merged 9 commits into
mainfrom
feat/browser-real-cdp

Conversation

@bsommers

Copy link
Copy Markdown
Owner

What

The browser pane was a stub that delegated to a synthetic renderer. It now drives a real headless Chrome.

  • Chrome is launched with --remote-debugging-pipe (fd 3/4), so no TCP debugging port is opened.
  • New modules: cdp_launch, cdp_session, cdp_proto, cdp_input, url_policy, geometry, src/input/browser_keys.rs, src/wm/media_tick.rs.
  • Keyboard and mouse are forwarded to the page; Ctrl+] is the escape hatch back to bilterm.
  • URL policy: file:// is refused unless BILTERM_BROWSER_ALLOW_FILE=1.
  • Chrome is reaped before the process exits; a closed pipe is reported the same way from both threads.
  • New dependencies: serde_json, zune-jpeg (cargo deny passes).
  • Docs: docs/user-guide/14-browser-canvas.md, changelog.

Not in this PR

PR 2 will add the agent/MCP surface, kitty/sixel output and link hints.

Live test

BILTERM_BROWSER_CDP=1 cargo test --test browser_cdp_live runs end to end against a local Chrome. It is opt-in, so CI does not run it.

Verification

🤖 Generated with Claude Code

bsommers and others added 9 commits November 10, 2026 01:17
serde_json builds and parses Chrome DevTools Protocol messages (the pane
layer may not import src/api/json.rs). zune-jpeg decodes screencast
frames in pure Rust. Both pass cargo deny (MIT / Apache-2.0 / Zlib).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The browser canvas was a stub: Chrome was launched with no debugging
channel and every BrowserEngine call went to the synthetic backend.

Engine
- cdp_launch: start Chrome with --headless=new --remote-debugging-pipe
  (fd 3/4 via pre_exec dup2), own process group, per-launch profile dir
  (pid + pane + random) in the private runtime dir; creation failure
  aborts the launch; drop kills the group and reaps off the UI thread.
- cdp_proto / cdp_session: NUL-framed JSON with a 32 MiB cap, a bounded
  coalescing command queue, a reader thread (handshake, events, JPEG
  decode, newest frame only) and a writer thread. The UI thread only
  enqueues and reads shared state. Garbage or oversize input is a fatal
  backend error, never a panic.
- Navigation, real history (Page.getNavigationHistory), reload, stop,
  viewport (setDeviceMetricsOverride on open, pane resize and zoom),
  downloads denied, popups loaded in the one visible page.
- url_policy: http, https and about:blank only; file:// behind
  BILTERM_BROWSER_ALLOW_FILE=1; the URL never goes on Chrome's argv.

Wiring
- WindowManager::poll_all_ptys ticks media canvases and redraws only
  when a visible pane changed.
- Keys and bracketed paste go to the page while the viewport is focused;
  Ctrl+] is the escape hatch; Ctrl+L is no longer taken from the shell
  when the page is not focused. Mouse cells map to frame pixels by
  proportion instead of a fixed 10x18 cell.
- Status line, nav bar and browser.state report what really runs: cdp,
  cdp (starting), cdp (crashed), synthetic (Chrome not found),
  synthetic (launch failed: ...). Lock icon only for https; nav-bar
  hit-testing uses display columns.
- Test binaries never launch a browser unless BILTERM_BROWSER_CDP=1
  (cfg!(test) is false for integration tests).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Gated on BILTERM_BROWSER_CDP=1. Serves two pages from a loopback
TcpListener, then checks frame, title and URL, a click through the mouse
path, typing and paste through the key path, back/forward, the URL
policy, resize, zoom, crash detection with reload, and that Chrome and
its profile dir are gone after close.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Describes the real engine: requirements, focus and the Ctrl+] escape
hatch, status labels, allowed URLs, opt-ins and known limits. Corrects
the WEB-01/02 notes, which claimed a CDP engine that did not exist.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The reaper thread that waits for Chrome and deletes its profile dir was
cut off when bilterm quit right after closing the canvas, leaving the
profile behind until the next launch swept it. An atexit hook now gives
pending reapers a bounded 2 s to finish.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…reads

The writer saw EPIPE and the reader saw EOF for the same event, so the
failure reason depended on which thread noticed first.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Keep both changelog entries (browser engine + remote tmux link).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…group is gone

The group leader is reaped by the reaper thread, but its SIGKILLed children are
reaped by init. Until that happens the zombie still counts as a group member, so
kill(-pgid, 0) could still succeed (seen on macOS CI). Poll for up to 5 s.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…eader

A group member that is mid-fork when the first SIGKILL is delivered can miss it
and outlive the leader; the macOS CI run still found the group alive 5 s after
drop. The reaper thread now sends SIGKILL to the group three more times (20 ms
apart) before wait(): until the leader is reaped its pid pins the group id, so
the signal cannot reach an unrelated group.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@bsommers
bsommers merged commit 869c39e into main Nov 10, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant