From 0a1ad0d4658919da65d67b4f7d267aa8ae85fa96 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sat, 24 Oct 2026 02:37:41 +0800 Subject: [PATCH] docs(inspector): distinguish passive commands from uninterrupted execution --- docs/browser-observation.md | 13 +++++++++---- docs/javascript-runtime-observation.md | 9 ++++++--- src/inspector/V8InspectorCaptureProjection.ts | 3 ++- 3 files changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/browser-observation.md b/docs/browser-observation.md index 0184920972..f841dfc606 100644 --- a/docs/browser-observation.md +++ b/docs/browser-observation.md @@ -131,6 +131,11 @@ 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. +Passive page and Inspector capture enable the `Debugger` domain. A target's +`debugger` statement can then pause execution; these observation paths do not +suppress pauses with `Debugger.setSkipAllPauses` or resume the target. Their +lack of explicit pause commands does not guarantee uninterrupted execution. + 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. @@ -537,10 +542,10 @@ Network and console coverage starts only after REA attaches and enables the rele Source maps are not fetched by inspection. Bundle analysis fetches them only when `fetch_source_maps` is selected, with exact-origin redirect checks and no credentials, cookies, or referrer. Each fetch operation uses `source_map_fetch_timeout_ms` (default 30000) and a 64 MiB aggregate streamed-response budget across redirects. The byte budget has no runtime override. A fetch overrun is an item limitation, not a thrown analysis timeout. A deadline or byte-limit failure remains explicitly unavailable and makes bundle completeness partial. Source-map decoding also bounds raw resolved identities to 64 MiB and aggregate inline evidence to 32 MiB. Failed maps preserve their failure context when it fits; if another context cannot fit, collection stops with the full requested count, the returned processed count, and an explicit unknown-results limitation. Retained mappings and original sources are returned inline. See [source-location limits](web-source-location.md) for the structural decoder bounds. Original source artifacts with `.ts`, `.tsx`, `.mts`, or `.cts` suffixes carry `text/typescript`; other source names retain `text/javascript`. -source-map items retain the script's `declared_url` separately from the observed -`effective_url`. successful maps use the latter as their source-resolution base. -failed fetches retain the last response URL observed within the approved origins; -`effective_url` is `null` when no response was observed. query parameters are +Source-map items retain the script's `declared_url` separately from the observed +`effective_url`. Successful maps use the latter as their source-resolution base. +Failed fetches retain the last response URL observed within the approved origins; +`effective_url` is `null` when no response was observed. Query parameters are preserved, and both URLs count toward the inline evidence budget. Current fetches emit a string or null; historical observations may omit `effective_url` without changing their stored content or Evidence identity. diff --git a/docs/javascript-runtime-observation.md b/docs/javascript-runtime-observation.md index 4eab065373..44cc589204 100644 --- a/docs/javascript-runtime-observation.md +++ b/docs/javascript-runtime-observation.md @@ -91,9 +91,12 @@ The provider sends exactly two protocol commands: - `Debugger.enable` It never sends `Runtime.evaluate`, reads script source, installs breakpoints, -pauses or resumes execution, calls `Runtime.runIfWaitingForDebugger`, launches -the target, instruments JavaScript, or invokes Electron APIs. Closing a call -closes only REA's WebSocket. +sends pause/resume commands, calls `Runtime.runIfWaitingForDebugger`, launches +the target, instruments JavaScript, or invokes Electron APIs. Enabling +`Debugger` can make target-authored `debugger` statements pause execution. +REA does not send `Debugger.setSkipAllPauses` or resume these pauses; passive +observation is not a guarantee of uninterrupted target execution. Closing a +call closes only REA's WebSocket. Each WebSocket handshake and command response has its own 20-second deadline, separate from the caller-selected observation window. A stalled handshake or diff --git a/src/inspector/V8InspectorCaptureProjection.ts b/src/inspector/V8InspectorCaptureProjection.ts index 6dbf0870cc..ec3eab0789 100644 --- a/src/inspector/V8InspectorCaptureProjection.ts +++ b/src/inspector/V8InspectorCaptureProjection.ts @@ -29,7 +29,8 @@ export const createInspectorExclusionCounts = (): Record< export const describeInspectorTargetLimitations = ( attachmentStateUnknown = false, ): string[] => [ - "REA attaches to an already-running exact target and never launches, resumes, evaluates, pauses, or mutates it.", + "REA attaches to an already-running exact target. It does not launch the target, evaluate JavaScript, install breakpoints, or send pause/resume commands.", + "Enabling Debugger can make target-authored debugger statements pause execution; observation does not suppress or resume these pauses.", "Only Runtime.enable and Debugger.enable are sent; source text, object values, EventEmitter activity, and Electron IPC are not inspected.", "The selected endpoint and target ID authorize observation; discovery file locations can remain unresolved and do not prove filesystem identity.", "Node discovery reports a best-effort pathname rather than an encoded file URL; lossy Windows paths and ambiguous underscores are preserved without guessing a file path.",