Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / browser-analysis

Browser analysis

Browser analysis gives an engineer bounded evidence about a live web or Electron page and the code and traffic that support it. It combines passive inspection, controlled browser scenarios, source and module discovery, DOM access, visual evidence, and offline inspection of retained network captures.

Capability model

Browser analysis has three related paths. Passive inspection observes a selected page that is already open. Controlled capture runs an explicit action sequence in a launched or connected browser. Historical capture inspection reads a retained network artifact without contacting the recorded destinations.

This diagram shows how the paths produce evidence for later analysis.

flowchart LR
    A[Browser or capture artifact] --> B[Scope and selection]
    B --> C{Analysis path}
    C --> D[Passive page inspection]
    C --> E[Controlled browser scenario]
    C --> F[Historical network inspection]
    D --> G[Runtime, source, DOM, visual, and network evidence]
    E --> G
    F --> G
    G --> H[Comparison or downstream analysis]

The common result is evidence with explicit scope and coverage. This lets later analysis distinguish an observed absence from data that was not requested, outside policy, unavailable after attach, or truncated.

Browser access

Passive browser inspection

Passive inspection uses the Chrome DevTools Protocol (CDP) to observe a page that is already open. The product discovers eligible targets, selects one target, and limits capture to its current origin unless the request supplies exact allowed origins.

It does not navigate, evaluate page code, click, close the page, invoke page tools, or control the browser. A loopback CDP endpoint or browser WebSocket is required. The attached browser remains owned by the caller. The provider authorizes the target before it attaches and closes or reuses only REA-owned transport after the operation.

CDP operations use bounded discovery, command, protocol-message, and cleanup windows. A shared healthy browser socket can serve compatible operations. A failed, protocol-invalid, over-sized, or uncertain transport is removed from reuse and remains owned until cleanup is confirmed. The provider also waits for active observations and bundle analysis to finish before it closes, so shutdown does not interrupt an admitted operation.

References: src/…/BrowserObservationService.ts• L34-58 src/…/CdpBrowserProvider.ts• L110-200 src/…/CdpBrowserProvider.ts• L206-287 src/…/CdpBrowserProvider.ts• L499-685 src/…/CdpTargetSessionOwner.ts• L107-184 src/…/CdpTargetSessionOwner.ts• L321-419

Controlled browser capture

Controlled capture is the active path for questions that need a user action, navigation, form input, or a known starting state. A scenario declares the browser mode, start URL, actions, environment, optional storage and secrets, and the artifacts or event families to retain.

The result contains an initial state and one record for each action. Each record links the action to its before and after URL, event range, selected artifacts, and completeness. Scenario runs are serialized so one run does not overlap another. Launch mode owns a temporary profile and process. Connect mode uses an external loopback browser, applies temporary state to the selected target, restores that state, and disconnects without closing the caller's browser.

Scenario requests can use values declared as secrets, values saved from earlier JSON responses, or values read from page storage. Saved response values must be exact strings or numbers from bounded JSON. The system redacts declared and learned sensitive values from later evidence and withholds screenshots when a scenario may expose such values. It also rejects request expansion that exceeds the current serialization allowance.

Response-value capture reads only bounded UTF-8 JSON and keeps source privacy tied to the exact response that supplied the value. Selected fields and later learned secret spellings are structurally redacted before response content is retained; if the body cannot be read or redacted safely, the related source and content remain withheld.

When an action, cancellation, or provider step fails, the system retains typed partial observations only when their recorded steps and coverage support that claim. Cleanup failures stay visible and are retried before later scenario work can proceed.

See browser runtime inspection for the runtime and DOM view and browser network capture for event and body capture choices.

References: src/…/browserScenario.ts• L16-36 src/…/browserScenario.ts• L104-137 src/…/BrowserScenarioResponseValues.ts• L34-117 src/…/BrowserScenarioResponseValues.ts• L125-181 src/…/BrowserScenarioSecrets.ts• L301-388 src/…/BrowserScenarioSecrets.ts• L492-570 src/…/PlaywrightBrowserScenarioProvider.ts• L77-145 src/…/PlaywrightBrowserScenarioProvider.ts• L262-405 src/…/PlaywrightBrowserScenarioProvider.ts• L408-563 src/…/PlaywrightScenarioBrowser.ts• L79-191

Active Electron inspection

Active Electron inspection launches an application for a bounded scenario and records its initial state, declared actions, and final state. It uses a selected launch environment and an ownership record so the product can separate the inspected application from unrelated processes and report whether cleanup was proven.

The capture checks that the application supports the required inspection path before launch. If the executable declares that Node inspector arguments are disabled, capture fails before launch and points to passive inspection as the alternative. During the run, it tracks selected windows, renderer actions, deep links, process metrics, IPC or runtime hook retention, and Electron version.

It records one outcome for each declared action. Actions after a failed or cancelled action are marked not executed. A final state read has a bounded cancellation grace period. If a read, action, cancellation, or cleanup step fails, the system retains the evidence already collected with a limitation or cleanup state instead of claiming a full application result.

References: src/…/PlaywrightElectronActiveFuses.ts• L30-109 src/…/PlaywrightElectronActiveProvider.ts• L71-165 src/…/PlaywrightElectronActiveProvider.ts• L167-342 src/…/PlaywrightElectronActiveActions.ts• L72-185 src/…/PlaywrightElectronActiveActions.ts• L264-328 src/…/PlaywrightElectronActiveActions.ts• L384-518

Historical network capture inspection

Historical inspection reads a caller-selected HAR, mitmproxy, SAZ, qlog, or Playwright trace artifact through an offline capture adapter. It can inspect every retained record or selected producer ordinals. It preserves producer record and stream identity instead of inventing live browser attribution.

The service snapshots the artifact, decodes it in an owned bounded process, validates the reply, and projects selected records into Evidence with historical authority. Input size, reply size, nesting, decoder time, and decoder memory are separate controls. The selected format and decoder identity remain visible. This path never contacts the recorded destinations. A Playwright trace can retain known stream facts with diagnostics when a record or resource is partial, but a missing stream does not prove that traffic was absent.

Format-specific projections preserve useful producer facts while redacting credentials and caller-declared sensitive values. Retained binary fields can remain available as evidence. JSON parsing preserves numeric spelling and rejects duplicate members instead of silently changing the producer document. Failed HAR requests retain their failure and timing sentinels instead of receiving invented timings. Optional Protobuf interpretation applies only after source bytes, transport metadata, framing, and credential checks are complete. A malformed or over-budget capture does not return an apparently complete result; trace-level record issues remain visible as diagnostics when known facts are still safe to retain.

References: src/…/CaptureBudgets.ts• L1-18 src/…/CaptureFailures.ts• L51-185 src/…/CaptureFailures.ts• L292-364 src/…/CaptureJson.ts• L16-141 src/…/HarCapture.ts• L29-111 src/…/HarSchema.ts• L33-137 src/…/PlaywrightTraceDecoder.ts• L85-231 src/…/PlaywrightTraceDecoder.ts• L137-230 src/…/TraceStream.ts• L86-299 src/…/ProtobufSchema.ts• L239-316

Evidence surfaces

Runtime and page state

Runtime inspection describes what the page exposes at capture time. It can retain frame relationships, DOM structure, accessibility structure, resources, workers, storage names or fingerprints, console metadata, WebSocket activity, selected response metadata, and safe page metadata.

The default capture favors structure over content. Accessibility names, console primitive text, script text, JSON body shapes, WebSocket shapes, storage keys, and storage fingerprints require separate selection because they can reveal sensitive application data. Response metadata projects safe declarations such as media type, content policy, links, and agent-related headers without retaining raw credential headers. Storage values are not returned as plain content; selected storage content is represented by stable hashes and marked incomplete when a provider response is missing or malformed.

Page-declared agent hints remain untrusted evidence. They describe possible page capabilities but do not grant permission to invoke tools or expand the origin boundary.

References: src/…/browserObservationSchemas.ts• L44-73 src/…/browserObservationSchemas.ts• L126-160 src/…/browserObservationSchemas.ts• L197-275 src/…/CdpCaptureEvents.ts• L19-107 src/…/CdpCaptureStorage.ts• L18-113 src/…/CdpCaptureStorageFingerprints.ts• L67-111 src/…/CdpSafeMetadata.ts• L15-74

Source and module discovery

Source discovery connects loaded script resources to the page that used them. Bundle analysis then reads selected JavaScript without executing it and derives module edges, chunk relationships, route and endpoint candidates, vendor signals, source-map relationships, and page-declared WebMCP metadata.

The analysis worker runs inert source analysis in an owned bounded process. It checks source and result identity before accepting facts, validates startup and control output, and reports completed script facts when later scripts fail. A host-owned admission can limit several providers together. Separate admissions keep independent hosts from blocking one another.

Source maps are optional evidence. Approved credential-free URLs are fetched with their own time and size limits. A map can be included, partial, invalid, policy-filtered, or fetch-failed without turning an unresolved source into a guessed result. A completed response keeps its byte count and digest even when later decoding fails. Selected local source and map artifacts keep acquisition facts such as path, size, and digest when later decoding fails.

Native module resolution answers a separate question: how a selected importer resolves selected specifiers in a supported Chromium. It uses an owned isolated browser context, blocks unrelated requests, validates that the returned importer and specifier order match the request, and reports the browser identity with the result.

References: src/…/CdpRuntimeSources.ts• L26-204 src/…/IsolatedWebBundleAnalyzer.ts• L36-128 src/…/WebBundleAnalysisWorker.ts• L187-324 src/…/WebBundleAnalysisWorker.ts• L330-621 src/…/WebSourceMapFetcher.ts• L113-187 src/…/WebSourceMapFetcher.ts• L568-746 src/…/WebSourceMapFetcher.ts• L1024-1231 src/…/NativeModuleResolver.ts• L95-313 src/…/NativeModuleResolver.ts• L352-511

DOM and visual evidence

DOM and accessibility artifacts answer what the page rendered and how that state is exposed to users and assistive tools. A screenshot supplies the visible viewport when layout, styling, canvas output, or other visual state matters.

Passive DOM inspection records structure and value lengths by default. Controlled scenarios can request DOM, accessibility, URL, history, storage, or screenshot artifacts at the end of the run or after selected steps. A screenshot checks viewport and document stability before it is accepted. Screenshot comparison reports exact pixel and channel metrics, or an explicit dimension, format, or resource result when comparison is not possible.

An artifact that is not requested is marked as such and does not prove that no page state existed. A captured image covers the current viewport only; the product does not scroll or infer semantic layout from pixels.

References: src/…/browserObservationSchemas.ts• L50-73 src/…/CdpScreenshot.ts• L43-233 src/…/CdpScreenshot.ts• L235-347 src/…/PngVisualDiff.ts• L33-99 src/…/PlaywrightBrowserScenarioProvider.ts• L89-118 src/…/PlaywrightBrowserScenarioProvider.ts• L149-172

Network evidence

Network evidence links page behavior to requests, responses, redirects, failures, WebSocket frames, and the step that caused them. Passive inspection captures metadata from the attach window. Controlled scenarios select event families and can separately request request bodies, response bodies, and header values. A failed request is a terminal network observation, while an unfinished or unreadable body is a separate content state.

Captured content keeps transaction links, byte counts, media types, and digests. Request identity links phases even when same-URL requests finish out of order. Credential headers and cookies are redacted. A body that was not requested, not exposed, unfinished, omitted by a budget, or unreadable stays in an explicit state, so it cannot be mistaken for an empty body. Body reads have their own time, size, allocation, and privacy limits.

The capture ties events to the authorized target document and tracks request occurrences separately. A root navigation or an unreadable frame identity can therefore mark the related evidence as changed or uncertain instead of mixing events from different page generations. Scenario events are ordered and attributed to the current step. Shared-context capture excludes requests whose page ownership is not known. Popup discovery, event budgets, opaque redirects, response privacy gaps, unfinished requests, and late body reads are reported as limitations rather than silently treated as complete coverage.

See browser network capture for capture choices, retained content, and recovery limits.

References: src/…/CdpNetworkEventFacts.ts• L35-107 src/…/PlaywrightScenarioEvents.ts• L105-210 src/…/PlaywrightScenarioEvents.ts• L232-313 src/…/PlaywrightNetworkContent.ts• L126-202 src/…/PlaywrightNetworkContent.ts• L204-340 src/…/PlaywrightScenarioNetwork.ts• L132-213 src/…/PlaywrightScenarioNetwork.ts• L258-384 src/…/browserNetworkEvidence.ts• L7-101

Passive Electron file inspection

Passive Electron file inspection applies the browser evidence model to a selected local file page without driving the application. It keeps only authorized file frames and resources, captures DOM structure without node values, and can retain script and worker evidence when requested. This is separate from active Electron inspection, which launches the application and runs declared actions.

The inspection checks that the main file frame remains stable during the observation window. A navigation, changed document generation, unproven ancestry, or out-of-scope frame is reported as a boundary failure or limitation instead of being merged into the result. Local file paths remain visible in the observation and are therefore part of the trust boundary.

References: src/…/CdpElectronInspection.ts• L96-128 src/…/CdpElectronInspection.ts• L158-232 src/…/CdpElectronInspection.ts• L247-352 src/…/CdpElectronProvider.ts• L121-249 src/…/CdpElectronProvider.ts• L252-393

Investigation flow

Target selection and scope

An investigation starts by discovering page targets at a loopback browser endpoint. The caller selects a target ID and can restrict evidence to exact HTTP(S) origins. If no origin list is supplied, the selected target's current origin becomes the default boundary.

The boundary is checked before attach and again during capture. A target document tracker follows root and subframe navigation events and compares frame and loader identity with the selected document. The final document identity is checked with frame and loader facts when the provider can prove them. If the page changes origin or document during a stability-sensitive operation, the mixed result is rejected. Missing identity is retained as attach-limited evidence instead of being treated as stable.

Response events apply the same origin policy to producer-owned URLs. Malformed, unsupported, unattributed, and outside-policy responses remain distinct from approved responses so network evidence does not imply access to data outside the selected scope.

References: src/…/CdpBrowserProvider.ts• L206-267 src/…/CdpBrowserProvider.ts• L526-685 src/…/CdpNetworkEventFacts.ts• L63-107 src/…/CdpTargetDocument.ts• L37-170 src/…/CdpTargetDocument.ts• L176-274

Action and evidence capture

Controlled capture resolves the declared browser setup, creates or connects to the requested session, and runs the action sequence in order. Each completed step can carry selected artifacts and event families. The final report records which parts of the run are complete.

Scenario requests run from the page's start origin and use the page's own session where required. Request actions do not follow redirects. They can save exact JSON string or number values for later steps, but values that lose numeric identity, cannot be read safely, or exceed a bounded retention budget are not saved.

The application layer validates provider output before it exposes Evidence. It rejects malformed output and incomplete scenario steps rather than publishing partial data as a complete result. A retained partial observation remains linked to the operation that failed and to any unresolved cleanup lease.

This diagram shows the relationship between a scenario step and its evidence record.

sequenceDiagram
    participant C as Caller
    participant S as Scenario capture
    participant B as Browser session
    participant E as Evidence
    C->>S: Declare start state and actions
    S->>B: Launch or connect
    loop Each action
        S->>B: Run action
        B-->>S: State and selected events
        S-->>E: Store step result
    end
    S-->>C: Ordered capture with coverage

References: src/…/BrowserScenarioResponseValues.ts• L57-106 src/…/PlaywrightBrowserScenarioProvider.ts• L149-243 src/…/PlaywrightBrowserScenarioProvider.ts• L262-405 src/…/PlaywrightScenarioEvents.ts• L232-274 src/…/PlaywrightScenarioNetwork.ts• L339-384

Evidence comparison

Comparison turns two captures into a change result without treating missing evidence as equality. Passive captures compare page structure, scripts, resources, storage, network activity, and related observations. Scenario captures align by exact step IDs and compare each requested artifact and event family. Screenshots use deterministic pixel metrics.

The result can say changed, unchanged, or unknown. Different capture selections, incomplete coverage, missing steps, truncated data, or unsupported image input preserve the unknown or explicit failure result because the system cannot prove that the two observations are equivalent.

References: src/…/BrowserObservationService.ts• L176-194 src/…/browserScenarioCaptureValues.ts• L268-340 src/…/PngVisualDiff.ts• L37-99

Boundaries and trust

Completeness and limitations

Every browser result reports the condition of its coverage. Complete within window means the requested sections were collected in the observation window. Policy filtered, attach limited, unavailable, and truncated sections identify why a result cannot answer a broader question.

Network and console observations begin only after the provider attaches. A page can therefore expose scripts that were parsed before attach while their earlier fetch requests are absent from the network record. Root navigation, missing loader identity, and unreadable child-frame events can add a document or frame coverage limit without proving that the page had no such state. Historical capture inspection has a separate limit: a deadline, byte budget, nesting cap, memory limit, or decoder failure can prevent a complete offline result. A trace may also report known events with stream or resource limitations instead of claiming that omitted traffic or files were absent.

Source, event, storage, screenshot, and historical-capture budgets are independent. Raising one budget does not prove that another surface is complete. Comparisons use these coverage states and do not convert an omitted or unavailable surface into equality.

References: src/…/browserCompleteness.ts• L5-88 src/…/PlaywrightScenarioEvents.ts• L249-273 src/…/PlaywrightScenarioNetwork.ts• L339-397 src/…/CaptureFailures.ts• L292-364 src/…/TraceStream.ts• L220-299

Data handling and trust

Browser analysis preserves useful local evidence while limiting direct secret exposure. URL userinfo credentials, credential headers, storage values, declared scenario secrets, and learned secret response values are removed or redacted. Query values and fragments remain unless they match a declared secret policy. Historical capture inspection also removes declared sensitive values from payloads, producer coordinates, artifact paths, digests, and diagnostic text.

Page-declared data is evidence, not authority. Script text, accessibility text, console text, WebMCP declarations, response links, and agent hints can describe application behavior, but they do not grant permission to invoke tools or expand the origin boundary. WebMCP discovery records page declarations without invoking them. Use a dedicated browser profile because CDP access reaches the privileges of that browser session.

Launched Chromium uses the sandbox when the host supports it. Android disables it because the host cannot provide a usable sandbox. Other hosts opt out only through REA_BROWSER_NO_SANDBOX=true. Native module resolution and controlled capture use caller-selected executables and report the browser identity used for the observation.

References: src/…/BrowserScenarioSecrets.ts• L301-388 src/…/BrowserScenarioSecrets.ts• L534-631 src/…/PlaywrightNetworkContent.ts• L126-190 src/…/HarCapture.ts• L114-261 src/…/TraceEventProjection.ts• L105-181 src/…/ChromiumSandbox.ts• L1-32

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep passive inspection selections aligned across input schemas, application operations, provider output, and completeness sections that describe omitted evidence.
  • Keep target identity, origin scope, response-event scoping, document tracking, final stability checks, and screenshot or WebMCP admission aligned so a navigation cannot produce mixed evidence.
  • Keep CDP payload admission, protocol validation, pending-command failure, shared-socket reuse, and cleanup ownership aligned. A transport that reports invalid or over-sized wire data must not remain reusable.
  • Keep scenario step and event attribution aligned when adding an artifact or event family. A new capture facet must remain tied to its step and completeness state.
  • Keep scenario serialization, provider shutdown admission, cleanup retry, and connected-browser ownership aligned. A later run must not start while an earlier run still owns an unresolved browser resource.
  • Keep scenario secret resolution, learned response values, structural body redaction, screenshot withholding, saved-value limits, and request serialization limits aligned across validation, execution, and final privacy passes.
  • Keep request-response attribution aligned when a request saves response values. Ambiguous matches, late route cleanup, redirects, unavailable bodies, and inexact JSON numbers must not publish saved or private data.
  • Keep network content states, event omissions, provenance limitations, and comparison rules aligned. not_requested, not_exposed, unavailable, omitted, and captured content must not collapse into one result.
  • Keep offline capture budgets aligned across the public input, async decoder context, owned process, reply reader, lossless JSON parser, and optional Protobuf projection. A larger input budget must not silently raise reply or output budgets.
  • Keep offline capture projection aligned with producer identity. Selected ordinals, artifact format, record order, digest, redaction, binary fields, and historical authority must remain consistent.
  • Keep historical decoder identities aligned with format adapters and capability declarations. A changed decoder profile must remain visible in the reported identity and version.
  • Keep historical trace member pairing, stream version checks, event projection, resource references, CRC verification, and partial diagnostics aligned. A missing network member or resource file must remain unknown rather than becoming an empty result.
  • Keep HAR producer adaptations aligned with validation and reported records. Failed-request sentinels may be accepted only for the matching observed producer profile and must remain unchanged in Evidence.
  • Keep Protobuf descriptor admission, raw wire facts, schema annotations, credential checks, and per-call budgets aligned. Schema interpretation must not replace the original bytes or make an unverified message appear decoded.
  • Keep source-map acquisition facts aligned with URL policy, redirects, response identity, decode limits, and partial status. A completed response body identity must survive a later decode failure.
  • Keep web-bundle worker admission aligned with startup identity, source and result budgets, worker protocol identity, completed prefixes, unstarted scripts, and cleanup ownership.
  • Keep native module resolution aligned with its browser capability, importer identity, specifier order, request block list, import map, and cleanup state.
  • Keep browser launch and attach ownership aligned. Launch mode terminates its owned process and profile. Connect mode restores target state and disconnects without closing the caller's browser.
  • Keep active Electron preflight, launch arguments, process lineage, window identity, hook retention, final-state grace, and cleanup states aligned. An unsupported executable must fail before launch and an unproven process must not be treated as owned.

Important failure modes

TriggerConsequenceGuard
The browser exposes no accepted loopback CDP endpoint or browser WebSocketNo page target can be discoveredStart a browser with an explicit debugging endpoint and use a dedicated profile
A CDP message is invalid UTF-8, invalid JSON, or larger than the protocol budgetPending operations fail and the transport is no longer reusableKeep protocol payloads within the selected limit and recapture on a healthy connection
The selected page changes origin or document during a stability-sensitive captureThe mixed observation is rejectedSet an exact origin scope and recapture the final page state
A root navigation has an unreadable frame or loader identityThe affected evidence is unidentified or attach-limitedRetry after the selected page has finished loading and use the reported limitation
A child frame changes document without a comparable loaderFacts from that frame remain uncertain rather than being assigned to the new documentRecapture after the frame is stable and do not treat unknown as unchanged
The Electron executable disables EnableNodeCliInspectArgumentsActive capture fails before launchUse passive Electron inspection or an executable that accepts the required inspector arguments
The Electron main file frame navigates or its ancestry cannot be provenThe inspection fails or marks frame, script, and worker attribution incompleteKeep the selected target stable and use the reported boundary limitation
A requested page, source, event, storage, or screenshot surface exceeds its budgetThe affected facts are omitted or marked incompleteReduce the selected scope or raise the matching surface budget only
A scenario reads a secret page value or secret response field before later captureLater evidence is redacted, and planned screenshots can be withheldDeclare sensitive fields and treat the result as privacy-limited when readiness is incomplete
A saved response is not bounded, is not valid JSON, or contains an inexact selected numberNo saved value is published and later steps cannot use itReturn a bounded JSON response with an exact string or number at the requested pointer
A scenario request leaves its start origin, follows an opaque redirect, or is cancelled before dispatchThe request is not sent or its result has unknown redirect factsReturn to the start origin and use an explicit expected status; do not treat the step as a confirmed write
A matching response for save_response is ambiguous, non-2xx, too large, late, or its route cleanup failsNo saved value is publishedNarrow the response path and keep the response within the step deadline and size limit
A historical capture exceeds its input, reply, nesting, memory, or decoder-time budgetNo complete offline capture result is returnedSelect a smaller complete artifact or raise the matching per-call budget
Historical JSON is malformed or contains duplicate membersThe selected capture is rejected as malformedPreserve valid producer JSON and inspect the reported pointer
A Playwright trace has no unambiguous version, a missing network member, or an unavailable referenced fileThe affected stream or resource stays unknown and diagnostics limit coverageSupply a supported trace archive with its paired members and retained resources
A HAR failed-request sentinel does not match its declared producer profileThe capture fails validation rather than changing the failure into a successPreserve the producer declaration and original failure and timing values
A Protobuf descriptor is malformed, names a missing message, or conflicts with wire factsSchema labels are withheld while raw wire evidence remains available, or the decode is rejectedUse a bounded descriptor set that defines the selected message and matches the recorded wire data
Historical records are reordered, omitted from the declared total, or mapped to a different artifactThe selected evidence is rejected as malformed or changedPreserve producer ordinals, artifact identity, and record sequence
A retained network body is unfinished, not exposed, privacy-blocked, or unreadableNetwork evidence remains unavailable instead of proving an empty bodyWait for the page-specific ready condition or treat the result as unknown
A web source map redirects outside approved origins or exceeds a fetch or decode limitThe map is policy-filtered or fetch-failed and its source edges remain unknownUse a credential-free approved source-map URL and the reported recovery limit
A web-bundle worker fails startup, times out, emits invalid control data, exhausts memory, or fails cleanupCompleted script facts may remain, but the overall analysis is partial or cleanup-incompleteTreat unstarted scripts as unknown and resolve the retained worker cleanup before retrying
The selected Chromium lacks native import.meta.resolve support or returns another importer/specifier setModule resolution is unavailable or its result is rejectedUse a supported absolute executable and preserve the exact request identity
A connected browser cannot restore emulation or service-worker policyThe external browser remains owned and the scenario reports cleanup incompleteRetry cleanup before another attach and do not close the caller's browser
Owned Electron process lineage, window ownership, or an ASAR descriptor cannot be verified or closedCleanup is not confirmed and the related lease remains pendingRestore process and file access, then retry the exact cleanup owner

Key files

FileWhy to read it
src/…/BrowserObservationService.tsShows the passive analysis operations, bundle analysis, session observation, screenshots, comparison, output validation, and partial-observation rules
src/…/CdpBrowserProvider.tsShows how target scope, page capture, bundle analysis, sessions, WebMCP discovery, screenshots, shared admission, and cleanup fit together
src/…/CdpTargetSessionOwner.tsShows CDP transport ownership, reuse, eviction, coalesced connections, and cleanup confirmation
src/…/CdpNetworkEventFacts.tsShows how CDP request and response facts receive origin scope and remain distinct when producer data is malformed or outside policy
src/…/CdpSafeMetadata.tsShows the safe response metadata and untrusted agent-hint surface
src/…/CdpElectronProvider.tsShows local-file target authorization, passive Electron inspection, and file cleanup ownership
src/…/BrowserScenarioResponseValues.tsShows bounded response-value admission, exact JSON values, and structural redaction boundaries
src/…/BrowserScenarioSecrets.tsShows declared and learned secret handling across text, bytes, URLs, storage fingerprints, screenshots, and response bodies
src/…/PlaywrightBrowserScenarioProvider.tsShows how controlled actions become ordered steps with artifacts, completeness, partial results, serialized execution, and cleanup state
src/…/PlaywrightScenarioBrowser.tsShows browser mode ownership, event finalization, release gates, and cleanup retry behavior
src/…/PlaywrightScenarioEvents.tsShows ordered runtime and network event capture, privacy finalization, event budgets, and omissions
src/…/PlaywrightScenarioNetwork.tsShows request identity, event ordering, selected body reads, content states, privacy handling, and network budgets
src/…/PlaywrightNetworkContent.tsShows bounded header and body reads, media type handling, digest creation, and body failure states
src/…/WebBundleAnalysisWorker.tsShows bounded inert source analysis, startup protocol, result admission, and validation of worker source and result identities
src/…/WebSourceMapFetcher.tsShows approved source-map fetching, response identity, bounded decoding, and partial map status
src/…/CaptureFailures.tsShows how capture read, decoder, memory, integrity, and cleanup failures become typed results
src/…/CaptureJson.tsShows bounded lossless parsing for retained JSON capture formats
src/…/HarCapture.tsShows HAR record projection, numeric literal preservation, binary evidence, and redaction
src/…/HarSchema.tsShows producer-aware HAR validation and the narrow adaptations allowed for failed requests
src/…/PlaywrightTraceDecoder.tsShows offline trace archive identity, paired stream reading, partial observations, and cleanup
src/…/TraceStream.tsShows trace version admission, event projection, record diagnostics, and stream coverage
src/…/TraceEventProjection.tsShows the small set of trace actions, console, network, and screenshot facts exposed as evidence
src/…/ProtobufSchema.tsShows bounded descriptor admission and schema annotations that preserve raw wire facts
src/…/PngVisualDiff.tsShows deterministic screenshot comparison and working-memory admission
docs/browser-runtime-inspection.mdExplains runtime, source, DOM, storage, and visual inspection in more detail
docs/browser-network-capture.mdExplains live and historical network capture choices, content states, and recovery limits