From e425a63a07de77ec6a9c20fbbc0a5089f19ab443 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 27 May 2026 08:47:08 -0700 Subject: [PATCH] docs: update project documentation for v1.51.0.0 Add $B memory command to BROWSER.md server lifecycle table. Document the new createSseEndpoint helper + CDP session lifecycle helpers (withCdpSession, getOrCreateCdpSession) in CLAUDE.md alongside the existing server hardening notes, with the static-grep tripwire callout so future contributors route through the helpers. Co-Authored-By: Claude Opus 4.7 (1M context) --- BROWSER.md | 1 + CLAUDE.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/BROWSER.md b/BROWSER.md index fa7448f9a..2c57f1d6e 100644 --- a/BROWSER.md +++ b/BROWSER.md @@ -317,6 +317,7 @@ from `snapshot`, or `@c` refs from `snapshot -C`. Full table: | `disconnect` | Close headed Chrome, return to headless | | `focus [@ref]` | Bring headed Chrome to foreground (macOS); `@ref` also scrolls into view | | `state save\|load ` | Save or load browser state (cookies + URLs) | +| `memory [--json]` | Snapshot Bun heap + per-tab JS heap + Chromium process tree + bounded buffer sizes. Use `--json` for programmatic consumers; text mode renders sorted top-10 tabs with "and N more" tail. | ### Handoff diff --git a/CLAUDE.md b/CLAUDE.md index a002c124b..2e08f1113 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -294,6 +294,26 @@ response in `server.ts`, read `browse/test/server-sanitize-surrogates.test.ts` pins the wiring with invariant tests, so bypasses fail CI. +**SSE endpoint helper** (v1.51.0.0+). New SSE endpoints in `server.ts` MUST route +through `createSseEndpoint(req, config)` from `browse/src/sse-helpers.ts`. The +helper owns the cleanup contract (abort + enqueue-throw + heartbeat-throw, all +idempotent) and bakes in `sanitizeLoneSurrogates` on every JSON.stringify, so +new subscribers can't accidentally regress either invariant. Inline +`ReadableStream` wiring leaked subscribers when the TCP connection died without +firing `req.signal.abort` (Chromium MV3 service-worker suspend, intermediate +proxy half-close). `/activity/stream`, `/inspector/events`, and `/memory` +(SSE-eligible) all route through it. `browse/test/sse-helpers.test.ts` pins the +cleanup contract. + +**CDP session lifecycle** (v1.51.0.0+). Direct `page.context().newCDPSession(page)` +calls outside `browse/src/cdp-bridge.ts` fail CI via the static-grep tripwire in +`browse/test/cdp-session-cleanup.test.ts`. Use `withCdpSession(page, async (s) => {...})` +for one-shot CDP work (try/finally detach) or `getOrCreateCdpSession(page, cache)` +for cached sessions tied to a page's lifetime (close-detach via `Map`). +Three sites migrated: cdp-bridge frame events, write-commands archive capture, +cdp-inspector. The helpers prevent the per-session leak class where successful-path +detach happened but error-path detach was missed. + **Setup symlink hardening** (v1.38.0.0+). Every link site in `setup` MUST route through the `_link_or_copy SRC DST` helper near the `IS_WINDOWS` detection. On Windows without Developer Mode, plain `ln -snf` produces frozen file copies that