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-runtime-inspection

Browser runtime inspection

Browser runtime inspection gives an engineer a bounded view of what a selected page contains and does. It combines page and DOM capture with focused runtime, script, module, source-location, listener, and execution views, then exposes the results as MCP Evidence tools. See Browser analysis for the wider browser capability and Browser network capture for request and response collection.

Inspection boundary

The inspection boundary connects to a user-owned Chromium DevTools Protocol (CDP) endpoint and selects one page target plus an origin scope. Its transport turns untrusted protocol messages into validated commands and events, rejects malformed or oversized messages, and keeps each operation within its own deadline. Each operation returns normalized Evidence with browser and target identity, completeness information, and explicit limits. The page remains external to REA, so inspection does not navigate, click, close, or run application code. Runtime sessions also own their temporary protocol domains, remote objects, instrumentation, and transport cleanup without taking ownership of the page.

The boundary supports two kinds of input:

  • Live page input: a CDP endpoint, target ID, and optional exact allowed origins.
  • Captured artifact input: a local script manifest and selected source bytes from an earlier page capture.

The MCP layer registers the operations with shared contracts. Provider availability is checked when a live browser tool runs. A missing provider becomes a capability error instead of a partial result. Successful results can also be recorded in the active analysis session.

References: src/…/CdpConnection.ts• L345-527 src/…/CdpConnection.ts• L530-705 src/…/BrowserObservationPort.ts• L36-69 src/…/BrowserObservationService.ts• L24-68 src/…/registerBrowserTools.ts• L48-76 src/…/createServer.ts• L864-885

Page and DOM inspection

The page inspection flow captures a stable, policy-filtered view of the selected document. It joins the page's frame tree, bounded DOM structure, optional accessibility text, script inventory and source, resource inventory, safe network and console metadata, workers, response metadata, URL hints, and redacted storage information. The result describes the page at the capture window. It does not claim prior activity or prove that a displayed node caused an action.

The primary MCP tool is inspect_web_page. It uses the current target origin when no origin list is supplied. The capture starts after REA attaches. A navigation or origin change during capture invalidates the observation rather than mixing documents. Missing or malformed protocol data is reported through completeness limits instead of being treated as an empty document.

list_browser_targets is the entry point when the caller does not yet know which page to inspect. It lists connectable page targets and reports excluded non-page, unsupported-URL, and out-of-scope targets.

The flow from target selection to normalized page evidence is:

flowchart LR
    A[CDP endpoint] --> B[list_browser_targets]
    B --> C[Select target and origin]
    C --> D[inspect_web_page]
    D --> E[Capture DOM, scripts, resources, metadata, workers, storage]
    E --> F[Verify document stability]
    F --> G[Evidence]

References: src/…/browserToolContracts.ts• L125-161 src/…/CdpBrowserProvider.ts• L84-139 src/…/CdpBrowserProvider.ts• L294-357 src/…/CdpPageCapture.ts• L70-194 src/…/browserObservationSchemas.ts• L277-352

DOM structure

The DOM view is a structural snapshot of the selected page. It reports node relationships and safe attribute names instead of treating page text or URLs as trusted instructions. DOM URLs are resolved against the document or base URL and retained only when they use an approved HTTP(S) origin. Unsupported or outside-policy values remain excluded from the approved view.

Accessibility data is a separate view and can include text only when the request allows it. Storage values are redacted. The inspection can retain names and content fingerprints without exposing the values. Some SVG link facts need a bounded follow-up read, so an unavailable follow-up is recorded as incomplete rather than guessed.

This view helps locate a page element and understand its accessible shape. It is not a live DOM handle. A node in the snapshot may change or disappear after capture.

References: src/…/CdpCaptureDocuments.ts• L199-379 src/…/CdpCaptureDocuments.ts• L423-539 src/…/CdpCaptureDocuments.ts• L594-714 src/…/browserObservationSchemas.ts• L44-73 src/…/browserObservationSchemas.ts• L288-300 src/…/browserObservationSchemas.ts• L319-350

Browser scenario capture

Browser scenario capture records a sequence of external page actions with a snapshot at the start and after the requested steps. Each step keeps its action status, elapsed time, before and after URLs, event range, requested artifacts, and completeness state. A failed or cancelled action stops later actions from running and marks their requested artifacts as unavailable.

The scenario provider preserves collected steps when an action or browser cleanup fails. It returns partial observation for cleanup failure and retains the cleanup resource for a later retry. This makes a scenario useful as a source of page and script evidence without claiming that an incomplete run represents the full action sequence.

References: src/…/PlaywrightBrowserScenarioProvider.ts• L77-144 src/…/PlaywrightBrowserScenarioProvider.ts• L172-240 src/…/PlaywrightBrowserScenarioProvider.ts• L259-403 src/…/PlaywrightBrowserScenarioProvider.ts• L405-563

Script capture and export

Script inspection turns debugger-retained page sources into stable local artifacts for later analysis. A captured script carries its URL, frame and module hints, source-map declaration, producer metadata, and an independent digest of the retained text. The inventory reconciles scripts with page resources using exact identities and keeps ambiguous or unavailable matches visible.

The MCP tool export_web_scripts reads a saved inspect_web_page or browser-scenario capture. It writes the retained JavaScript and a digest-checked manifest to a new local output directory. It never refetches website assets or executes the captured code. Source reads use a bounded budget, so a selected source can remain in the inventory while its bytes are omitted with an explicit completeness reason. The inventory is finalized after the last protocol read, which keeps scripts that arrive late from being silently mistaken for absent scripts.

The manifest can feed module and source-location tools, or static JavaScript analysis when source bytes are present. Page inspection records source-map declarations but does not fetch them. The separate analyze_web_bundle operation analyzes approved captured script input and can collect source maps for bundle analysis. It reports unavailable or partial results when time, byte, decoding, or output limits prevent safe retention.

The script path is a handoff from live browser evidence to offline investigation:

flowchart LR
    A[inspect_web_page or scenario capture] --> B[Retained script inventory]
    B --> C[export_web_scripts]
    C --> D[Local source files and manifest]
    D --> E[Module import trace]
    D --> F[Source-map location trace]
    B --> G[analyze_web_bundle]
    G --> H[Approved source-map evidence]

References: src/…/webScriptToolContracts.ts• L65-81 src/…/WebScriptExportService.ts• L58-125 src/…/PageScriptCapture.ts• L4-38 src/…/CdpPageCapture.ts• L70-100 src/…/CdpPageCaptureScripts.ts• L57-138 src/…/CdpPageCaptureScripts.ts• L171-264 src/…/CdpBrowserProvider.ts• L162-200 src/…/PlaywrightBrowserScenarioProvider.ts• L259-403 src/…/browserObservationSchemas.ts• L74-117 src/…/webScriptArtifacts.ts• L6-49

Bundle analysis

Bundle analysis turns one retained script into bounded static facts without treating the script as trusted running code. The analysis runs in an owned worker boundary. The worker admits only valid, bounded control input, checks the source identity before parsing, validates the per-script result, carries partial facts for refused work, and writes a digest-checked result within the admitted output budget. Resource, input, output, and I/O failures remain typed outcomes rather than unbounded host work.

Source-map collection is a separate input path within bundle analysis. It fetches without browser credentials and accepts only HTTP(S) URLs on approved exact origins. It follows only redirects that remain approved. It records the effective response identity even when the map is invalid or its text is not retained. When embedded original source is available, it can also report static module edges from that source. The fetch, decoded representation, source identities, records, output, and deadline each have bounds. The result keeps completed map items and marks unprocessed, invalid, filtered, or failed items instead of publishing truncated map data. Cancellation or incomplete response cleanup remains visible with the completed partial maps.

References: src/…/WebBundleAnalysisWorkerServer.ts• L53-113 src/…/WebBundleAnalysisWorkerServer.ts• L115-264 src/…/WebBundleAnalysisWorker.ts• L187-338 src/…/WebBundleAnalysisWorker.ts• L332-624 src/…/WebBundleAnalysisWorker.ts• L852-1041 src/…/WebSourceMapFetcher.ts• L113-305 src/…/WebSourceMapFetcher.ts• L531-745 src/…/WebSourceMapFetcher.ts• L762-943 src/…/WebSourceMapFetcher.ts• L1024-1231

Runtime execution observation

Runtime observation measures externally triggered execution during one finite armed window. The MCP tool observe_web_execution arms precise coverage on the selected page, tells the caller when the window is ready, and then records nested function and block ranges, retained script sources, and request initiator locations. It resets the browser's execution counters and changes optimization behavior for the window. The result therefore describes that instrumented interval rather than a timeless execution history.

The operation does not execute selected code or perform the external action. It records what happens while the user or another external actor operates the page. The window starts at the actual armed point, before progress delivery can delay the external action. A document change, target termination, or detached debugging session ends collection. A child-frame navigation does not end the selected main-document window. Cancellation and transport loss also settle the window and release its local timer and abort listener.

The CDP provider owns the temporary session and instrumentation. Each protocol command has its own deadline, while the source-join and completion phase has a separate bound. Before live node data or final coverage is joined, the session checks that the selected document is still the same. Cleanup then gets its own grace period to stop coverage, release objects, disable domains, detach, and close the transport. A successful provider run marks cleanup as confirmed; cleanup failures remain visible and can carry a partial observation.

sequenceDiagram
    participant E as Engineer or client
    participant M as observe_web_execution
    participant B as Selected page
    E->>M: Select target and observation window
    M->>B: Arm instrumentation
    M-->>E: Report armed window
    E->>B: Perform external action
    B-->>M: Coverage and request initiator data
    M->>B: Stop instrumentation and clean up
    M-->>E: Evidence with ranges, sources, and limits

Runtime locations use CDP's zero-based resource lines and UTF-16 columns. A location is joined to source by session script identity when possible. URL equality alone does not prove that two records are the same script. Requests are retained only for the selected main frame and allowed origins. Their producer-reported initiators and nested callsites are sanitized and joined after source collection, while unresolved asynchronous parent IDs remain explicit. Repeated observations of one request identity remain separate records. The result reports initiator associations, but it does not prove UI causality.

References: src/…/webRuntimeToolContracts.ts• L13-52 src/…/WebRuntimeService.ts• L22-124 src/…/CdpWebRuntimeProvider.ts• L36-146 src/…/CdpRuntimeSession.ts• L43-325 src/…/CdpExecutionCapture.ts• L18-170 src/…/CdpExecutionWindow.ts• L29-132 src/…/CdpRuntimeProtocol.ts• L9-64 src/…/CdpRuntimeRequests.ts• L25-148 src/…/CdpRuntimeInitiator.ts• L9-29 src/…/CdpRuntimeSources.ts• L24-287 src/…/CdpRuntimeRetention.ts• L5-28 src/…/webExecution.ts• L11-92 src/…/webRuntime.ts• L35-77

JavaScript runtime observation

JavaScript runtime observation provides a separate passive view of Node and Electron V8 Inspector targets. It discovers eligible targets from an explicit loopback Inspector endpoint, then attaches to one selected target for a bounded window to record loaded scripts and execution-context metadata without evaluating, pausing, resuming, reading source, or instrumenting the target.

Runtime target discovery

The MCP tool list_javascript_runtime_targets returns the runtime version, eligible target IDs, target locations, and counts for excluded or unconnectable targets. A reported discovery location can remain unresolved when the provider cannot verify a file path. It is not proof of filesystem identity.

References: src/…/javascriptRuntimeObservationToolContracts.ts• L11-30 src/…/JavaScriptRuntimeObservationService.ts• L22-50 src/…/javascriptRuntimeObservation.ts• L12-112 src/…/V8InspectorProvider.ts• L79-140

Runtime observation

The MCP tool observe_javascript_runtime rechecks the selected target before attach and records observed-loaded scripts, execution contexts, event counts, truncation state, direct observations, and explicit unknowns. The caller can declare a runtime kind such as Node or Electron, but the result records that declaration as unverified. Require/import edges, EventEmitter activity, and Electron IPC stay unknown unless another evidence source establishes them.

The two runtime tools are registered even when the optional Inspector provider is unavailable. In that case the client receives a capability-unavailable result instead of a missing tool or a false observation. Active analysis admission, request cancellation, logging, and Evidence delivery use the common MCP registration path.

References: src/…/javascriptRuntimeObservationToolContracts.ts• L31-50 src/…/JavaScriptRuntimeObservationService.ts• L52-137 src/…/V8InspectorProvider.ts• L142-204 src/…/registerJavaScriptRuntimeObservationTools.ts• L28-105 src/…/createServer.ts• L912-917 src/…/javascriptRuntimeObservation.ts• L115-176

Event-listener inspection

Event-listener inspection identifies callbacks registered directly on the first main-document element that matches a CSS selector. The MCP tool inspect_web_event_listeners returns listener flags, callback locations, and associated retained source text when CDP can prove the source identity. It does not dispatch an event, evaluate JavaScript, or invoke a handler.

The operation answers which direct listeners are registered on the first main-document node that matches the selector. It does not enumerate delegated ancestor listeners, framework registries, descendants, or closed shadow roots. A callback location is a declaration point. Its dispatch history and execution remain unknown. The provider uses an owned remote object group and reports cleanup only after that group and the enabled protocol domains are released.

References: src/…/webRuntimeToolContracts.ts• L35-50 src/…/WebRuntimeService.ts• L57-89 src/…/CdpEventListeners.ts• L11-112 src/…/CdpWebRuntimeProvider.ts• L69-83 src/…/webEventListeners.ts• L10-43

Module relationship tracing

Module tracing explains the outgoing native ES module relationships of one exported script. The MCP tool trace_web_module_imports reads a selected local manifest and source, then optionally reads a caller-selected local import map. It parses static imports, re-exports, and dynamic import expressions, and resolves literal specifiers in an explicit HTTP(S) importer context.

The selected script and manifest are checked before tracing. When an import map is supplied, its file identity, digest, bounded size, and base URL remain part of the evidence, and the map is treated as caller-selected local input rather than fetched from the website. The trace reports resolved URLs, rejected specifiers, matching captured script candidates, source positions, and computed specifiers as unknown.

The trace is a static relationship report. A resolved URL or captured candidate does not prove that the browser loaded or executed the module. Bundler IDs, computed imports, workers, and unsupported importer schemes remain outside the trace. An optional native resolver uses a caller-supplied Chromium executable in an owned context. It fulfills only the selected document, importer, and import-map inputs, blocks other requests, and reports the browser engine and blocked requests. This context is isolated from the captured application and exists only to resolve trusted input. The resolver processes work in order and does not accept new work after shutdown starts. Cancellation and engine failure still trigger owned-browser cleanup, while cleanup failure remains visible and can preserve a completed resolution as partial evidence.

References: src/…/webScriptToolContracts.ts• L43-63 src/…/WebModuleTraceService.ts• L42-60 src/…/WebModuleTraceService.ts• L80-246 src/…/WebModuleArtifacts.ts• L18-107 src/…/NativeModuleResolver.ts• L75-133 src/…/NativeModuleResolver.ts• L167-318 src/…/NativeModuleResolver.ts• L321-479 src/…/NativeModuleResolver.test.ts• L13-104 src/…/NativeModuleResolver.test.ts• L221-322 src/…/LocalWebScriptArtifacts.ts• L21-143 src/…/WebModulePorts.ts• L14-53 src/…/webModuleTrace.ts• L10-125

Source-location tracing

Source-location tracing maps one generated position in an exported script to its original source through an explicitly selected local source map. The MCP tool trace_web_source_location verifies the manifest, script, and map byte identities before decoding the map. It returns all mappings at the greatest generated position not greater than the requested point, including duplicate or generated-only entries and any embedded original source content.

The caller supplies the source-map URL context because local pairing does not prove deployment authenticity. Positions use one-based lines and zero-based UTF-16 columns. The result describes a source relationship, not execution or a UI cause. No original source is fetched and no application code runs.

References: src/…/webScriptToolContracts.ts• L18-41 src/…/WebSourceLocationService.ts• L67-182 src/…/WebSourceLocationPorts.ts• L12-41 src/…/webSourceLocation.ts• L11-140

MCP tool surface

The MCP surface separates live page inspection, passive runtime observation, and local artifact analysis. Shared tool contracts define the input and output shapes. Registration connects each name to an application service and records successful results as Evidence when a session is active. This keeps the client-facing capability stable while the CDP, Inspector, and local artifact providers remain replaceable.

Investigation goalMCP toolMain result
Find an inspectable pagelist_browser_targetsPolicy-filtered page targets
Inspect page and DOM stateinspect_web_pageDOM, accessibility, scripts, resources, safe metadata, workers, and redacted storage
Save retained script bytesexport_web_scriptsLocal scripts and a digest-verified manifest
Analyze captured web bundlesanalyze_web_bundleStatic bundle relationships and approved source-map evidence
Observe externally triggered executionobserve_web_executionPrecise coverage, script sources, and request initiator locations
Inspect direct DOM listenersinspect_web_event_listenersListener declarations and callback source locations
Trace native module relationshipstrace_web_module_importsImport syntax, resolutions, captured candidates, and unknown execution state
Map generated code to sourcetrace_web_source_locationSource-map matches for one generated position
Find Node or Electron runtime targetslist_javascript_runtime_targetsEligible V8 Inspector targets and exclusions
Observe one Node or Electron runtimeobserve_javascript_runtimePassive loaded-script and execution-context evidence

These tools follow the common MCP registration path described in MCP tool registration. Live browser tools need a configured browser observation provider. JavaScript runtime tools need the optional V8 Inspector provider. Local script, module, and source-location tools work from retained capture artifacts and do not require a live page.

References: src/…/browserToolContracts.ts• L125-221 src/…/javascriptRuntimeObservationToolContracts.ts• L13-50 src/…/webRuntimeToolContracts.ts• L13-52 src/…/webScriptToolContracts.ts• L17-82 src/…/registerBrowserTools.ts• L48-76 src/…/registerJavaScriptRuntimeObservationTools.ts• L36-68 src/…/registerWebRuntimeTools.ts• L13-73 src/…/registerWebScriptTool.ts• L13-52 src/…/registerWebModuleTool.ts• L11-31 src/…/registerWebSourceLocationTool.ts• L11-31 src/…/createServer.ts• L729-749

Change checklist

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

  • Keep the MCP contract name, input schema, output schema, and registration handler aligned for each runtime or artifact operation.
  • Preserve the distinction between CDP resource coordinates and local source-map coordinates when changing location models or conversion rules.
  • Keep script manifest identity and independently read artifact digests aligned with module and source-location selection.
  • Keep origin admission and target-change checks aligned across target discovery, page capture, runtime observation, and listener inspection.
  • Keep source-map fetch policy, redirect handling, response identity, cleanup ownership, and public output limits aligned with the completeness status and limitations reported by bundle analysis.
  • Keep the optional V8 Inspector provider's unavailable result aligned with the fact that its tools remain registered.
  • Keep the armed execution window's timer, cancellation, target-change handling, command deadlines, source-join deadline, and cleanup grace aligned with the coverage result and progress messages.
  • Keep execution metadata collection open through the final precise-coverage sample, then freeze the identity set used for retained source joins.
  • Keep main-document frame identity checks distinct from child-frame navigation checks when changing execution-window event handling.
  • Keep request filtering, initiator sanitization, late source binding, and retained-byte limits aligned so discarded wire fields do not change the request evidence contract.
  • Keep source ownership tied to stable script and execution-context identity. A changed identity must not retain a prior frame attribution or source join.
  • Keep confirmed cleanup status tied to successful release of coverage, remote objects, domains, target attachment, and transport.
  • Keep CDP wire validation, payload limits, listener failure handling, and cleanup-only transport commands aligned when changing protocol event or command admission.
  • Keep scenario step status, requested snapshot state, event ranges, partial observation, and retained cleanup leases aligned when changing scenario capture behavior.
  • Keep the web-bundle worker's control-frame encoding, source identity checks, per-script result validation, refusal and partial-fact handling, route-fact admission, result digest, and cleanup state aligned with bundle analysis results.
  • Keep source-map response admission, manual redirect policy, response identity, original-source module edges, response-body cancellation, late-fetch cleanup, source-map identities, and independent fetch and output limits aligned.
  • Keep the selected import-map path, digest, base URL, and HTTP(S) context aligned across artifact loading and module resolution.
  • Keep the native module resolver's caller-supplied browser requirement, request allowlist, report shape, deadline, serialized shutdown, and cleanup state aligned with module-resolution evidence.
  • Update Evidence limitations when a provider changes what execution, source ownership, or DOM causality can claim.

Important failure modes

TriggerConsequenceGuard
The selected page navigates or leaves the allowed origin during captureThe observation is rejected instead of combining records from different documentsAttach to one target, enforce origin scope, and verify the document again before publishing
A live browser provider or optional V8 Inspector provider is not configuredThe related MCP tools return capability-unavailable errorsCheck provider availability at tool execution time while keeping the tool contract registered
CDP receives malformed JSON, an invalid envelope, an unexpected reply, or an oversized messageThe connection is poisoned and active observations fail instead of consuming untrusted protocol dataValidate wire encoding, message shape, command identity, event schemas, and payload size at the transport boundary
Script source capture exceeds its command or byte budgetThe script remains in the inventory but its source is omitted with a completeness limitBound source reads and preserve the omission reason rather than treating the script as missing
Script source or source-map bytes do not match the selected digest or sizeModule or source-location evidence is rejected as stale or mismatchedRe-read and verify the manifest, script, and map identities
A source-map URL or redirect leaves the approved exact originsThe map is marked policy-filtered and no unapproved bytes are retainedAdmit every fetch URL and redirect before reading its response
A source-map response is invalid, exceeds its fetch or representation budget, or cannot finish before its item deadlineThe item is marked invalid or fetch-failed, or the collection becomes partial; truncated map data is not publishedRecord response identity separately, use bounded reads and decoding, and keep item status distinct from the overall analysis deadline
A source-map response arrives after cancellation or its body cannot be releasedThe completed map evidence stays partial and cleanup failure remains visibleRetain the response owner until the body is cancelled and its reader is released
Precise coverage ends because the target changes or terminatesFinal coverage can be unavailable; missing coverage does not mean no executionPublish the end reason and explicit unavailable state
A runtime command, source join, or cleanup phase exceeds its boundThe operation returns a timeout or cleanup failure instead of waiting without a limitApply separate command, completion, and cleanup deadlines and retain the failure state
The armed execution window is cancelled, loses transport, or was already ended before armingThe operation fails or returns the existing end reason without a misleading armed interval; local wait resources are releasedSettle pre-arm and active termination through the window state, then close owned instrumentation in all outcomes
The CDP runtime session cannot complete cleanupThe result includes a cleanup failure and may retain partial observationClose owned sessions on every outcome and preserve cleanup errors
A retained runtime request or initiator exceeds its allowanceThe runtime operation returns a typed capacity error instead of a partial runtime resultMeasure the retained representation after projection and preserve discarded request-body fields as absent
A script or execution context changes identity during source collectionIts source and frame association become unknownRevalidate known identities during asynchronous reads and join locations by script ID rather than URL
A scenario action fails or is cancelledLater actions are not run and their requested artifacts are marked unavailablePreserve step status and completeness instead of presenting later steps as successful
Browser scenario cleanup cannot be confirmedCollected steps are retained as partial observation and the cleanup lease remains ownedRetry retained cleanup before accepting another scenario or completing provider shutdown
A bundle-analysis worker receives malformed control input, a mismatched source descriptor, or an invalid resultThe job returns an input or output failure instead of analyzing unverified data; malformed control input can stop further jobsUse bounded strict input decoding, verify source bytes and digest before parsing, validate the result, and bound the result artifact
A bundle-analysis worker exceeds its memory, transfer, result, or control-frame allowanceAnalysis returns a resource or output failure and may retain only validated completed factsIsolate the worker, bound each representation, validate result identity, and retain cleanup state
A selector matches no main-document nodeListener evidence contains no listener set for the requested selectorReturn the selected-node match state as not_found
An import is computed or uses an unsupported module contextThe relationship stays unknown or the operation is unavailablePreserve the expression and require an explicit supported importer context
The selected import map cannot be read, is not a JSON object, or changes identityModule tracing fails before resolution and does not use unverified map dataRead the caller-selected artifact under bounds and retain its digest, byte count, and base URL
A V8 Inspector target location cannot be verifiedThe target remains unresolved rather than being treated as a trusted fileReport the raw discovery URL with its unresolved reason
The native module resolver has no absolute caller-supplied browser executableModule tracing cannot use native resolutionRequire the configured executable and return a capability-unavailable result
The selected Chromium engine does not support native module resolutionModule resolution is unavailable instead of producing guessed URLsValidate the resolver result and report the engine capability
The resolver page requests an unselected resourceThe resolution run cannot use website data or unexpected network stateFulfill only the resolver document and selected importer, then block other requests
Native browser cleanup fails during cancellation, startup failure, or finalizationThe result can become cleanup-incomplete, and a completed resolution can remain partial until cleanup succeedsKeep the owned browser lease pending, reject queued work during shutdown, and retry cleanup before allowing shutdown to complete

Key files

FileWhy to read it
src/…/createServer.tsShows how browser, V8 Inspector, and local web analysis services become MCP tools and how provider cleanup connects to server shutdown.
src/…/registerBrowserTools.tsShows the shared registration path for live browser target, page, and DOM-facing tools.
src/…/registerJavaScriptRuntimeObservationTools.tsShows how passive Node and Electron runtime tools stay registered when their optional provider is unavailable.
src/…/CdpConnection.tsShows the validated CDP transport, operation deadlines, failure states, payload boundary, and transport-only cleanup.
src/…/CdpBrowserProvider.tsShows the CDP boundary for target authorization, page capture, origin scope, bundle analysis, and cleanup.
src/…/CdpPageCapture.tsShows the high-level page evidence assembled from DOM, scripts, resources, metadata, workers, and storage.
src/…/CdpPageCaptureScripts.tsShows how retained script sources are budgeted, reconciled with resources, keyed, and finalized.
src/…/CdpCaptureDocuments.tsShows how frames, resources, DOM structure, accessibility, and DOM-declared URLs become bounded evidence.
src/…/PlaywrightBrowserScenarioProvider.tsShows how action steps and snapshots become scenario evidence and how partial observations and retained cleanup are handled.
src/…/CdpWebRuntimeProvider.tsShows the provider boundary for execution windows, direct listener inspection, validation, cancellation, and cleanup.
src/…/CdpRuntimeSession.tsShows the selected-document session, command and completion deadlines, instrumentation ownership, and cleanup grace.
src/…/CdpExecutionCapture.tsShows how one armed coverage window becomes execution, request, source, and limitation evidence.
src/…/CdpExecutionCollection.tsShows how execution metadata, request events, failure events, and cleanup are collected around the final coverage sample.
src/…/CdpExecutionWindow.tsShows the finite document-scoped window and its timer, cancellation, pre-arm termination, frame-change, and cleanup states.
src/…/CdpRuntimeProtocol.tsDefines the validated protocol shapes for precise coverage, runtime stacks, listener data, and frame identity.
src/…/CdpRuntimeRequests.tsShows how selected-frame requests become bounded evidence with initiator callsites, repeated occurrences, and late source binding.
src/…/CdpRuntimeInitiator.tsShows how producer initiator URLs and stack frames are sanitized without treating declarations as proven source identity.
src/…/CdpRuntimeRetention.tsShows the shared capacity boundary for retained runtime metadata, requests, and sources.
src/…/CdpRuntimeSources.tsShows how script and execution-context identity controls source ownership and source joins.
src/…/WebRuntimeService.tsShows the public browser runtime workflows and their output checks.
src/…/V8InspectorProvider.tsShows the passive Node and Electron Inspector target discovery and observation boundary.
src/…/JavaScriptRuntimeObservationService.tsShows how Inspector observations become validated Evidence and partial results.
src/…/WebModuleTraceService.tsShows how retained scripts, selected import maps, and importer context become static module evidence.
src/…/WebModuleArtifacts.tsShows how selected local script and import-map artifacts enter module tracing without website requests.
src/…/NativeModuleResolver.tsShows the isolated native module-resolution context, serialized work, request blocking, deadline, and cleanup boundary.
src/…/NativeModuleResolver.test.tsShows the expected behavior for cancellation, queued work, shutdown, partial results, and cleanup failure.
src/…/WebSourceLocationService.tsShows how a selected generated point becomes source-map evidence.
src/…/WebScriptExportService.tsShows the handoff from saved browser captures to local script artifacts.
src/…/WebBundleAnalysisWorker.tsShows the bounded worker boundary for inert script analysis, result admission, failure projection, and cleanup.
src/…/WebBundleAnalysisWorkerServer.tsShows how the worker admits bounded control input, validates source and output artifacts, fits per-script results to budget, and reports typed job failures.
src/…/WebSourceMapFetcher.tsShows the bounded, credential-free, origin-approved source-map input, response identity, original-source module edges, partial collection, and cleanup boundary used by bundle analysis.
src/…/javascriptRuntimeObservationToolContracts.tsDefines the MCP contract for passive JavaScript runtime discovery and observation.
src/…/webRuntimeToolContracts.tsDefines the MCP contract for browser runtime and event-listener inspection.
src/…/webScriptToolContracts.tsDefines the MCP contract for script export, bundle analysis, module tracing, and source-location tracing.