From 921fa03fca7181af5d69ccc10a4ceadc22c9c9e0 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Fri, 16 Oct 2026 04:41:40 +0800 Subject: [PATCH] docs(browser): explain CDP detach effects on caller emulation Describe Chromium platform-emulation reset across connected page workflows and recovery by the owning client. Browser survival does not imply state preservation; the upstream limitation remains unresolved. Refs: #4089 --- docs/browser-observation.md | 27 +++++++++++++++++++-------- docs/browser-scenario-contract.md | 9 +++++++++ docs/electron-observation.md | 6 ++++++ 3 files changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/browser-observation.md b/docs/browser-observation.md index 355d7f98ea..c14485bea4 100644 --- a/docs/browser-observation.md +++ b/docs/browser-observation.md @@ -66,14 +66,25 @@ Electron `file://` pages use a separate provider and target boundary; see [elect ## Provider authorities -CDP page capture, V8 Inspector observation, and Playwright scenarios stay -separate providers because their authorities differ: CDP and V8 attach to an -already-running target and never launch, drive, evaluate, or mutate it, while -Playwright providers own and drive the runtime (launch browsers, run actions, -capture step snapshots). Merging them would mix attach-only and owned-process -lifecycles in one contract. What they share instead is one exclusion -vocabulary (`BrowserExclusionReason`): every denial reason in every stack maps -onto it, even where a wire schema keeps a narrower historical bucket. +CDP page capture and V8 Inspector observation attach to an already-running +target without launching it, driving actions, or evaluating target code. +Playwright scenarios drive actions and capture step snapshots in either a +provider-owned browser or a caller-selected external browser. Separate providers +preserve these authority and lifecycle differences. They share one exclusion +vocabulary (`BrowserExclusionReason`): every denial reason maps onto it, even +where a wire schema keeps a narrower historical bucket. + +CDP attachment is not a guarantee that the browser preserves all state. +Chromium can clear another client's `navigator.platform` emulation when REA's +page session disconnects, even if that session sent no emulation commands. +This affects page inspection, bundle capture, session observation, screenshots, +WebMCP discovery, and Electron page inspection; target listing alone does not +attach a page session. REA cannot read the other client's complete +user-agent/client-hint configuration and does not replay guessed settings. +Use a disposable browser when preserving externally configured emulation is +required, or have the owning client reapply its complete configuration afterward. +See [the reproduction and Chromium ownership limitation](https://github.com/morluto/rea/issues/4089). + Existing static application Evidence and passive web/Electron captures can be combined later through [JavaScript static/runtime reconciliation](javascript-runtime-reconciliation.md). diff --git a/docs/browser-scenario-contract.md b/docs/browser-scenario-contract.md index a4e223ba3c..f6d6a40a7d 100644 --- a/docs/browser-scenario-contract.md +++ b/docs/browser-scenario-contract.md @@ -144,6 +144,15 @@ distinction: it closes and deletes provider-owned profiles, but only disconnects from an external CDP browser. Real-browser verification checks both outcomes and confirms that an attached external browser remains alive. +Keeping that browser alive does not guarantee its emulation state survives. +Chromium can clear caller-owned `navigator.platform` emulation when a page CDP +session disconnects, including sessions that sent no emulation commands. REA +cannot snapshot the other client's complete user-agent/client-hint settings and +does not replay a partial reconstruction. Use launch mode to keep this effect +inside a provider-owned browser, or have the external owning client reapply its +complete configuration after capture. Connected captures report this limitation; +see [issue #4089](https://github.com/morluto/rea/issues/4089). + `environment.locale` sets Intl formatting in both modes. Launch also sets `navigator.language`, `navigator.languages`, and the request `Accept-Language`. Connect preserves the caller's page and request languages; every attached diff --git a/docs/electron-observation.md b/docs/electron-observation.md index fb5e9be838..55b8c33983 100644 --- a/docs/electron-observation.md +++ b/docs/electron-observation.md @@ -2,6 +2,12 @@ REA can attach to an Electron/Chromium CDP endpoint and inspect existing `file://` renderer pages without evaluating JavaScript or invoking Electron APIs. The request supplies the endpoint directly; REA accepts only literal-port loopback HTTP endpoints. Selecting an endpoint exposes every Electron target it serves, including local file paths and page metadata. +Disconnecting the inspection's page session can clear caller-owned +`navigator.platform` emulation inside Chromium. REA cannot restore another +client's complete user-agent/client-hint configuration. Use a disposable target +or let the owning client reapply its configuration; see the shared +[CDP state limitation](browser-observation.md#provider-authorities). + This passive runtime surface is distinct from the target-free static [`analyze_javascript_application`](javascript-artifact-reconstruction.md) workflow. Static analysis reads a local ASAR or extracted directory without