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-network-capture

Browser network capture

Browser network capture records HTTP and WebSocket activity that supports browser analysis. It links observed requests to browser actions, retains selected content with clear limits, and stores the result as Evidence for later inspection or comparison. Historical inspection can also read saved capture files and Playwright traces without repeating the browser run. It complements browser runtime inspection, which focuses on in-page state rather than network effects.

Capture modes

Browser analysis uses different capture modes for different questions. Passive observation watches activity after attachment. Controlled capture runs known actions. Historical inspection reads an existing artifact without contacting its recorded destinations.

Passive page capture

Passive page capture observes one page during a short CDP attachment window. It records request identity, response facts, redirects, initiators, value-free body shapes, and WebSocket frame metadata when those facets are enabled. It does not retain raw headers, bodies, cookies, or WebSocket payloads. It cannot recover activity that happened before attachment.

This mode is useful when page interaction must remain unchanged. An empty result means that no activity was observed during the window. It does not prove that the page made no earlier or later requests.

References: src/…/browserToolContracts.ts• L186-203 src/…/browserObservationSchemas.ts• L277-318 src/…/CdpPageCapture.ts• L76-104 src/…/CdpCaptureEventHandlers.ts• L574-735

Controlled scenario capture

Controlled scenario capture runs an explicit start URL and action sequence in a browser. It groups request and response phases into transactions, preserves known redirect links, and places events on the scenario step that caused or observed them.

Request bodies, response bodies, and header values are separate choices. The default keeps network facts without keeping those content values. Response reads finish before browser cleanup, so admitted reads have a chance to complete before the result is stored. Body and header reads use bounded time and allocation budgets. A body that the browser has already materialized can still be withheld when its retained size or redaction cost is too large.

This mode is the main choice for reproducing a user flow and asking which request changed, failed, or carried a result.

flowchart LR
    A[Scenario actions] --> B[Browser network events]
    B --> C[Request and response transactions]
    C --> D[Selected headers and bodies]
    D --> E[Step-indexed Evidence]

References: src/…/PlaywrightScenarioNetwork.ts• L21-37 src/…/PlaywrightScenarioNetwork.ts• L107-141 src/…/PlaywrightScenarioNetwork.ts• L204-274 src/…/PlaywrightNetworkContent.ts• L129-285 src/…/browserScenarioCaptureValues.ts• L137-216

Historical capture inspection

Historical capture inspection reads a caller-selected HAR, mitmproxy, SAZ, or qlog file as an offline artifact. It preserves producer order and record identity, then exposes summary or record pages from retained Evidence. It does not replay requests, start a browser, or use recorded URLs.

The service first takes a stable snapshot. A format adapter decodes the complete snapshot in a bounded worker and returns one bounded reply. The service checks the adapter identity, source digest, format, record count, and producer order before it creates Evidence. Malformed input or reply, decoder failure, and resource exhaustion do not become complete results. If a valid capture exists before a later Protocol Buffer or cleanup failure, the service can retain it as a partial observation. A source change during acquisition is reported as a retryable integrity failure, while a physical read error remains an execution failure.

The decoder owns its private snapshot, runtime, and cleanup resources for one inspection. Its input, reply, nesting, time, and memory limits remain separate from other inspections. A completed decoder can still become a partial observation if reply finalization, process ownership, or resource cleanup fails. Cleanup failures remain linked to the primary result and retain a cleanup lease for retry. The reported runtime memory boundary explains whether a format used an enforced Node heap, a host process limit, or another decoder limit.

The supported formats provide different historical facts:

  • HAR keeps structured request and response facts. Valid base64 content becomes a byte sidecar with its size and digest. Reported timing and cache values stay distinct from omitted or unavailable values. Malformed producer timing and cache facts fail validation before projection. Known producer profiles may explain failed-request timing sentinels such as -1; the original failure and timing values remain in Evidence, and only a validation copy is adapted.
  • SAZ keeps native session members, stored bytes, and source archive names. Its order follows ZIP member order, not a guessed chronology or numeric session ID. A normalized logical path is recorded only when the archive reader had to adapt the source name.
  • qlog keeps event traversal order and can derive QUIC stream ranges, repeated-byte counts, final offsets, and packet-loss facts. It does not recover HTTP body bytes. The selected aioquic profile marks transport facts incomplete when required event fields are hidden or invalid. Sensitive values can hide the source of a derived fact without making the remaining record complete.
  • mitmproxy keeps native capture records through its offline decoder. Its availability depends on the host and executable profile.

HAR, SAZ, and qlog use bounded package-backed decoder profiles. The selected profile identity describes how the artifact was interpreted; it does not authenticate the producer. The decoder receives an immutable per-operation budget for source bytes, reply bytes, and nesting. Concurrent inspections keep their policies separate.

The historical JSON path rejects malformed UTF-8, comments, trailing commas, and duplicate object members. It admits parser nodes and nesting before it materializes the document, so a deeply nested or structurally large source can fail before projection. It keeps number text long enough to avoid silent rounding and flattens escaped strings without retaining avoidable parser memory. HAR binary content is retained only when its declared base64 text is valid. The Evidence keeps decoded byte count and digest beside the reported value. The worker validates the source before it emits a reply, and the service validates that reply before Evidence retention.

SAZ metadata remains an ordered XML tree rather than a guessed set of producer flags. Encrypted archives, archive links, duplicate member names, and unknown raw session members are not repaired into records. Empty request or response members remain explicit limitations.

References: src/…/WebNetworkCaptureService.ts• L38-126 src/…/WebNetworkCaptureService.ts• L128-285 src/…/CaptureBudgets.ts• L7-18 src/…/HistoricalCaptureDecoder.ts• L115-144 src/…/HistoricalCaptureDecoder.ts• L146-249 src/…/HistoricalCaptureDecoder.ts• L327-348 src/…/HistoricalCaptureDecoder.ts• L397-558 src/…/NodeCaptureProcess.ts• L15-73 src/…/CaptureJson.ts• L16-155 src/…/CaptureJson.test.ts• L6-39 src/…/HarCapture.ts• L29-104 src/…/HarCapture.ts• L125-199 src/…/HarSchema.ts• L33-63 src/…/HarSchema.ts• L76-137 src/…/QlogCapture.ts• L27-128 src/…/QlogCapture.ts• L219-370 src/…/SazCapture.ts• L29-103 src/…/SazCapture.ts• L109-201 src/…/SazMetadata.ts• L11-90 src/…/HistoricalCaptureReply.ts• L22-107 src/…/CaptureFailures.ts• L44-395 src/…/HistoricalCaptureBudgets.test.ts• L45-195

Playwright trace inventory

Playwright trace inventory reads a caller-selected trace ZIP without launching a browser or contacting recorded URLs. It turns supported version 10 trace and network streams into an offline inventory of action boundaries, console text, network headlines, screenshot references, archive members, and diagnostics.

The inventory keeps archive-member identity and source line locations so an event can be traced to its producer record. It preserves order within each source stream only. It does not infer one timeline across streams, decode resource contents, or claim that the recording contains all traffic. A missing .network member means that network coverage is unknown, not that the trace contains no network activity.

The decoder hashes and verifies the selected archive before it promotes the inventory to complete Evidence. It reads trace streams before paired network streams so network facts are marked supported only when their related trace profile is known. An import has one active archive read at a time. Queries against retained Evidence do not require another import, and an interrupted read can retain the verified inventory as a partial observation.

Trace events retain selected action, console, network, and screenshot facts. Network headlines can preserve a recorded failure status as an unknown normalized status while retaining the original producer value and failure text. Malformed records remain diagnostics when valid sibling records can still be used. Resource references remain missing, ambiguous, unavailable, or present-unread; a reference state does not prove that the related bytes are readable or valid.

This mode complements HAR and live scenario capture. It gives an investigator recorded network facts and nearby browser events when a Playwright trace already exists, but it does not provide live transaction attribution or retained response bytes. A resource reference can remain missing, ambiguous, or unread even when the related event is retained.

References: src/…/PlaywrightTraceDecoder.ts• L36-82 src/…/PlaywrightTraceDecoder.ts• L84-129 src/…/PlaywrightTraceDecoder.ts• L131-231 src/…/TraceStream.ts• L41-74 src/…/TraceStream.ts• L86-181 src/…/TraceStream.ts• L203-299 src/…/TraceEventProjection.ts• L13-51 src/…/TraceEventProjection.ts• L54-181 src/…/playwrightTrace.ts• L44-129 src/…/PlaywrightTraceDecoder.test.ts• L157-205 src/…/PlaywrightTraceDecoder.test.ts• L223-296

Capture records

The capture model separates request lifecycle facts from optional content. This lets an investigation use request identity even when a body or header read was not requested, failed, or ended at the capture cutoff.

Request lifecycle

Each controlled request can produce request, response, finished, failed, or unfinished events. A content event points to the earlier request or response event for the same transaction. Redirects link transactions when the browser exposes the predecessor. An unknown link stays unknown rather than being inferred from URL or event order.

The lifecycle tells an investigator whether a request reached a response, failed before a response, or remained open when capture stopped. It also carries method, sanitized URL, resource type, header names, response status, and failure text when available.

References: src/…/browserScenarioCaptureValues.ts• L137-216 src/…/browserScenarioCapture.ts• L38-61 src/…/PlaywrightScenarioNetwork.ts• L144-274

Content selection

Request bodies, response bodies, and header values are separate evidence choices. A selected facet can be captured, unavailable, not exposed, or not requested. These states prevent a missing body from being mistaken for an empty body.

Captured bodies are stored as base64 bytes with a byte count and SHA-256 digest. Headers keep producer order and duplicate entries. Credential headers have no retained value. A selected value can still be unavailable or omitted by a limit. Body reads report whether the browser exposed bytes, whether the read timed out or failed, and whether redaction changed the retained value. For JSON bodies, a redaction that would make the result invalid causes the body to be withheld. Passive capture stores value-free shapes for approved JSON responses and WebSocket text frames.

Historical Protocol Buffer decoding is a separate view over retained body bytes. It admits framing from visible HTTP metadata or an explicit request choice, checks the retained byte descriptor, and reports framing, wire fields, gRPC-Web trailers, and partial or unknown states. Credential and sensitive-value checks happen before schema reads or field expansion. A schema adds field names and types as an interpretation; it does not replace raw wire facts. Wire offsets and ranges remain the source facts when a schema field is unknown or does not match its wire type. Descriptor sets must be well formed and must define the selected message before they add annotations.

References: src/…/browserNetworkEvidence.ts• L4-101 src/…/PlaywrightNetworkContent.ts• L28-72 src/…/PlaywrightNetworkContent.ts• L74-127 src/…/PlaywrightNetworkContent.ts• L129-285 src/…/PlaywrightScenarioNetwork.ts• L602-671 src/…/browserScenarioCaptureValues.ts• L268-339 src/…/ProtobufCapture.ts• L98-183 src/…/ProtobufCapture.ts• L350-496 src/…/ProtobufFraming.ts• L7-143 src/…/ProtobufWire.ts• L150-293 src/…/ProtobufSchema.ts• L239-317 src/…/ProtobufSchema.ts• L327-452

Trace event identity

Trace events use the archive digest, member identity, and source line to keep action, console, network, and screenshot facts distinct. Resource references resolve only to states such as missing, ambiguous, unavailable, or present-unread. They do not prove that referenced bytes are readable or valid.

References: src/…/TraceInventory.ts• L42-99 src/…/TraceInventory.ts• L100-120 src/…/playwrightTrace.ts• L21-80

Privacy and provenance

Network records sanitize URL userinfo and remove values from known authentication headers, cookies, and transport credential fields. Controlled capture makes body and header retention explicit. Historical inspection applies the same protection to structured values, byte fields, derived numbers, and selected Protocol Buffer content.

Redaction is structural. A digest verifies retained bytes after redaction, but it does not establish deployment identity, wire-level provenance, or complete network coverage. Historical adapters validate source data before sensitive projection, and the reply boundary removes sensitive values that could appear after number normalization. Structural record checks keep redaction focused on actual capture records rather than marker-like values.

References: src/…/browserObservation.ts• L234-267 src/…/browserScenario.ts• L23-35 src/…/CaptureRedaction.ts• L7-147 src/…/HarCapture.ts• L51-102 src/…/SazProjection.ts• L15-128 src/…/HistoricalCaptureReply.ts• L69-162 src/…/ProtobufCapture.ts• L350-496 src/…/ProtobufFraming.ts• L83-143

Evidence retention

Network capture results use the shared Evidence model. Evidence gives each result a stable identity, records its provider and capture parameters, and stores limitations beside the observed result.

Scenario Evidence

capture_browser_scenario returns the normalized scenario result inline. When a session writer is present, the server also records it as session Evidence. The record includes action steps, event timeline, selected content, completeness state, and capture limits. It does not retain resolved secret values.

An Evidence ID keeps the capture available for later comparison or session review. A failed or cancelled run can retain a partial observation with incomplete cleanup or missing network sections.

References: src/…/registerBrowserScenarioTool.ts• L27-65 src/…/BrowserScenarioCaptureService.ts• L13-37 src/…/BrowserScenarioEvidence.ts• L19-45

Historical Evidence retrieval

Historical inspection can return a summary first. The summary keeps the complete capture in the session and returns a parent Evidence ID. An engineer then passes that ID to inspect_analysis_view to page previews, records, or selected Protocol Buffer views without decoding the source again.

Preview pages show record headlines and byte descriptors. Complete pages expose retained records and sidecars. Paging follows the retained record order and keeps producer ordinals stable.

References: src/…/registerWebNetworkCaptureTool.ts• L22-67 src/…/WebNetworkCaptureService.ts• L107-205 src/…/webNetworkCaptureView.ts• L454-535

Playwright trace Evidence

inspect_playwright_trace stores the offline inventory as Evidence with the archive digest and decoder profile. The initial result can provide a compact summary. inspect_analysis_view can then page retained events, streams, members, diagnostics, or event text without importing the archive again.

Trace views keep recording completeness and cross-stream order unknown. Paging changes delivery size only. It does not decode resource contents or increase the archive, stream, fact, or line limits used during import. If import stops, Evidence contains only the verified observation and keeps its partial interpretation state.

References: src/…/PlaywrightTraceService.ts• L20-39 src/…/PlaywrightTraceService.ts• L41-83 src/…/playwrightTraceView.ts• L262-350 src/…/playwrightTraceToolContracts.ts• L12-40 src/…/PlaywrightTraceLifecycle.test.ts• L13-43 src/…/PlaywrightTraceLifecycle.test.ts• L45-115

Investigation workflows

Captured requests support investigation by linking browser behavior to network effects. The useful unit is a transaction with a lifecycle, step context, redirect ancestry, and explicit coverage state.

Request tracing

Start with the scenario step or passive observation window that matters. Follow the transaction ID through request, response, completion, or failure. Inspect selected headers or bodies only when their state is captured.

Treat missing, unavailable, and unfinished content as limits on the claim. A request can prove that a browser observed a transaction without proving that its body was retained or that later activity did not occur.

References: src/…/browserScenarioCaptureValues.ts• L142-216 src/…/PlaywrightScenarioNetwork.ts• L147-230 src/…/browserScenarioCaptureValues.ts• L268-339

Capture comparison

The comparison workflow uses complete scenario captures from before and after runs. It aligns exact step IDs and compares network transactions through ordered evidence and redirect ancestry. Matching content selections are required. Different selections make the result unknown instead of treating an omitted facet as a change.

Passive page comparisons use stable request identities and compare WebSocket connections as ordered frame streams. A changed result shows an observed difference. An unknown result means the captures do not support an absence or equality claim.

flowchart LR
    A[Before capture] --> C[Completeness checks]
    B[After capture] --> C
    C --> D[Step and transaction alignment]
    D --> E[Changed, unchanged, or unknown]

References: src/…/browserToolContracts.ts• L224-248 src/…/browserScenarioDiffEvidence.ts• L103-175 src/…/browserScenarioNetworkComparison.ts• L133-221 src/…/webCaptureDiff.ts• L17-47

Coverage boundaries

Network evidence is bounded by the capture window, selected content facets, browser exposure, and resource limits. Completeness fields and limitations must be read with the records.

Incomplete collection

A capture can omit later requests when it ends, drop events when its budget is full, or retain a request without selected content. A bounded body or header read can time out while the request lifecycle remains valid. The browser may materialize a body before the retained-body limit is checked. These conditions lower coverage; they do not make captured records false.

Historical inspection reads a stable snapshot and decodes every record before selection. Input size, output size, nesting depth, parser representation, decoder time, process memory, and reply size can prevent a complete result. These limits are admitted per operation, so changing one limit does not silently change the others. A depth policy must also leave room for the returned Evidence shape. Protocol Buffer inspection adds selected-record and selected-body coverage.

Playwright trace import has separate archive, decoded-stream, retained-fact, metadata, and line budgets. Malformed or incomplete streams add diagnostics and change interpretation coverage to partial. A trace can identify network events without proving recording completeness or a total order between trace and network streams. A failed stream check does not promote its unverified network facts.

References: src/…/PlaywrightScenarioNetwork.ts• L192-231 src/…/PlaywrightNetworkContent.ts• L140-191 src/…/CdpCaptureEventHandlers.ts• L600-681 src/…/CaptureBudgets.ts• L7-18 src/…/CaptureJson.ts• L16-155 src/…/HistoricalCaptureDecoder.ts• L164-356 src/…/HistoricalCaptureDecoder.ts• L375-588 src/…/NodeCaptureProcess.ts• L21-72 src/…/PlaywrightTraceDecoder.ts• L131-225 src/…/TraceStream.ts• L251-299 src/…/TraceInventory.ts• L152-174 src/…/HistoricalCaptureBudgets.test.ts• L45-195

Historical decoder failures

Historical capture failures distinguish a changed source artifact, invalid input, access failure, cancellation, decoder failure, cleanup failure, and resource exhaustion. The error keeps the failed phase so an engineer can tell whether the source could not be read, the decoder could not process it, or the reply could not be trusted. An unresolvable selected path is an input error with a retry hint, while a physical read error remains an execution failure.

A decoder that reaches an input, output, nesting, time, or memory boundary does not return a complete result. Recognized runtime heap exhaustion and an observed host process limit are resource failures. A similar process exit without evidence of a memory limit remains an execution failure. Memory failures retain the observed worker boundary, including a Node heap limit or Windows process commit limit when that boundary caused the failure. A reply that was read but cannot be finalized or cleaned up can retain the sanitized capture as a partial observation while still reporting the failure. When cleanup also fails, the error keeps the cleanup dependency with the primary failure so the owned resources remain available for retry.

Format errors stay tied to the source or reply phase. This includes malformed JSON or HAR facts, invalid SAZ archive structure, unsupported SAZ members, invalid decoder replies, and malformed Protocol Buffer framing or schema input. A valid capture can still have an incomplete Protocol Buffer view when selected bodies, metadata, credentials, or schema fields cannot be safely interpreted.

References: src/…/CaptureFailures.ts• L40-395 src/…/HistoricalCaptureDecoder.ts• L193-329 src/…/HistoricalCaptureDecoder.ts• L397-558 src/…/HistoricalCaptureReply.ts• L43-125 src/…/NodeCaptureProcess.ts• L47-72 src/…/HarSchema.ts• L123-137 src/…/ProtobufSchema.ts• L253-317 src/…/CaptureFailures.test.ts• L16-408

Trace import failures

Trace import failures retain verified inventory facts when an import stops, but they do not turn an incomplete read into a complete trace. An unsupported version, missing required stream facts, malformed line, duplicate member path, resource limit, cancellation, or cleanup failure is reported with the affected archive or source line when known.

Archive checks occur before facts from an unverified stream become network evidence. Cancellation can preserve earlier verified streams. Cleanup failure can leave complete or partial Evidence available while its owned resources await retry, and a second import is refused while the first import is active.

References: src/…/PlaywrightTraceDecoder.ts• L95-127 src/…/PlaywrightTraceDecoder.ts• L169-231 src/…/TraceStream.ts• L146-218 src/…/TraceInventory.ts• L25-37 src/…/TraceInventory.ts• L64-99 src/…/PlaywrightTraceDecoder.test.ts• L321-365 src/…/PlaywrightTraceLifecycle.test.ts• L13-43 src/…/PlaywrightTraceLifecycle.test.ts• L225-257

Attribution limits

Passive capture is limited to activity after CDP attachment. Controlled capture links events to the selected scenario, but response-body provenance remains limited to the browser API that exposed the bytes. Historical capture preserves producer evidence without proving which live browser or deployment created it. Trace inventory preserves recorded facts without proving complete recording or cross-stream time order.

These limits make network capture strong evidence for observed differences and request facts. They do not make it proof of server source, wire bytes, causality, or complete application behavior.

References: src/…/browserObservationSchemas.ts• L306-316 src/…/browserNetworkEvidence.ts• L4-5 src/…/webNetworkCaptureView.ts• L447-464 src/…/playwrightTrace.ts• L123-128

Change checklist

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

  • Keep the three network content choices aligned between scenario input, resolved metadata, content events, and comparison coverage.
  • Keep transaction and content-event links valid when lifecycle or redirect handling changes.
  • Keep body encoding, byte count, digest, and redaction state aligned when body retention changes.
  • Keep header order, duplicate entries, credential suppression, body materialization limits, and JSON syntax checks aligned when browser content reads change.
  • Keep summary retrieval and inspect_analysis_view parent-ID links aligned when Evidence delivery changes.
  • Keep historical adapter identity, source digest, producer order, and sensitive-value projection aligned.
  • Keep the admitted budget context aligned between the public operation, worker request, format reader, reply reader, and Evidence parameters. Concurrent inspections must not share a policy.
  • Keep decoder input, reply, nesting, time, process-memory, and cleanup limits aligned with complete-evidence claims. Keep source snapshot integrity distinct from reply finalization.
  • Keep cleanup errors linked to the primary historical failure and keep cleanup leases available for retry when owned resources remain.
  • Keep runtime heap enforcement and reported memory-boundary details aligned across supported runtimes.
  • Keep JSON duplicate-member, UTF-8, lossless-number, parser-node, nesting, and canonical-base64 rules aligned with source validation and Evidence projection.
  • Keep HAR producer-profile admission, failed-request timing sentinels, IPv6 spelling adaptations, cache and timing validation, and original-value retention aligned.
  • Keep SAZ source member names, logical paths, ZIP order, session grouping, empty-message limits, and metadata tree order aligned when archive projection changes.
  • Keep qlog profile admission, event order, stream-range derivation, repeated-byte counts, loss declarations, and incomplete-fact markers aligned when transport facts change.
  • Keep Playwright trace archive identity, ZIP member occurrence identity, stream version state, source-line event identity, diagnostics, and per-stream ordering aligned when trace inventory changes.
  • Keep trace resource-reference states separate from resource-content decoding and recording-completeness claims.
  • Keep trace import budgets, verified-stream promotion, cleanup retry state, and single-import capacity aligned with retained Evidence and paging behavior.
  • Keep Protocol Buffer MIME admission, explicit framing, credential checks, byte ranges, trailer parsing, descriptor admission, schema annotations, and coverage aligned when body interpretation changes. Schema disagreement must not replace wire facts.

Important failure modes

TriggerConsequenceGuard
Capture ends while a request is openThe request is unfinished and response content can be unavailableRead completeness and unfinished reason before claiming a full response path
A selected body or header read fails or times outLifecycle facts remain, but selected content is unavailableDo not treat unavailable content as an empty body or absent header
The browser materializes a body above the retained-body or allocation limitThe body is withheld even though the network transaction remains validRead the body state and limit reason before using content claims
Redaction would make a JSON body invalidThe body is withheld instead of returning unsafe JSONTreat body-read failure as unavailable content
Before and after captures use different content selectionsNetwork comparison cannot establish equalityUse the same body and header choices on both sides
A source artifact changes during historical readInspection reports a retryable integrity failureUse a stable capture file and preserve the original artifact
A decoder reaches an input, output, nesting, parser-node, or memory limitNo complete historical result is availableUse a smaller producer export or raise only the needed per-operation budget
A depth policy leaves too little room for returned EvidenceThe request is rejected before inspectionSelect a nesting limit that can represent both the source and the normalized result
A package-backed decoder needs an enforced process memory limit that the host cannot provideHistorical inspection is unavailable for that formatRun the supported decoder runtime or select another format
A runtime exits with an unrecognized failure patternThe failure is reported as execution failure rather than a memory limitRead the reported failure phase and process diagnostics
The decoder reply is invalid UTF-8, malformed JSON, or outside its schemaThe historical result is rejected as untrusted outputKeep the reply bounded UTF-8 JSON and validate its byte count
A HAR declares base64 but contains non-canonical contentThe historical record is rejectedPreserve valid canonical base64 for binary content
A HAR contains malformed timing or schema factsThe source is rejected instead of producing misleading partial recordsValidate producer facts before projection
A failed HAR request uses an unrecognized producer profile for unavailable timing sentinelsThe source is rejected instead of being broadly normalizedAdmit only known producer representations and retain original failed-request values
A SAZ archive contains duplicate names, encryption, links, or unknown raw membersThe archive is rejected instead of producing ambiguous session recordsPreserve native archive member identity and export an unencrypted supported SAZ
A SAZ request or response member is emptyThe related message is reported as null with a limitationTreat the empty member state as unknown content, not as an empty HTTP message
A qlog stream or loss event has hidden or incomplete required fieldsThe related derived fact is incomplete or unknownRead incomplete-fact records with stream and loss summaries
A Playwright trace has no supported stream or declares an unsupported versionThe trace inventory is unavailable or unsupportedExport a Playwright version 10 trace with required stream members
A trace member path occurs more than onceResource references become ambiguousUse member occurrence identity and do not infer one payload from the path
A trace import reaches its archive, stream, fact, line, or concurrency limitImport fails or retains only verified partial observationUse a smaller recorder chunk and wait for an active import to finish
A trace stream fails archive verificationIts network facts are not promoted to the inventoryKeep only facts from fully verified streams
A trace record has malformed JSON or no known stream profileThe record is diagnosed and its facts are not interpretedUse source line diagnostics and require a verified version 10 context
A trace resource reference is missing, encrypted, ambiguous, or present-unreadThe event does not prove that resource bytes are available or validUse the reference state and retain the original archive
A selected Protocol Buffer body has invalid framing, credential data, or sensitive bytesThe body is withheld or decoding is partialRead protobuf status, redactions, and coverage before using fields
A selected Protocol Buffer body has unknown or conflicting MIME metadataAutomatic applicability is unknown and the body may remain uninterpretedUse explicit framing only when the retained bytes and transport rules support that choice
A descriptor set is malformed or does not define the selected messageSchema annotations are unavailable, while raw wire facts can remain availableCheck schema admission before relying on field names or types
A descriptor has duplicate type or field identitySchema admission fails before annotations are appliedUse a consistent descriptor set with unique qualified names and field numbers
A gRPC-Web trailer block has a blank-line suffix, forbidden control, invalid name, or opaque valueValid earlier trailers may remain, but the trailer view is partialUse the trailer status and examined byte count before treating the block as complete

Key files

FileWhy to read it
src/…/browserScenarioToolContracts.tsDefines the controlled-capture purpose and content-selection contract.
src/…/browserScenarioCaptureValues.tsShows the step, lifecycle-event, content-state, and completeness model.
src/…/PlaywrightScenarioNetwork.tsExplains how request transactions, redirects, completion, and bounded reads become events.
src/…/PlaywrightNetworkContent.tsDefines bounded header and body reads, redaction, and retained byte integrity.
src/…/browserNetworkEvidence.tsDefines retained body and header evidence states and integrity fields.
src/…/CdpPageCapture.tsDefines the passive observation window and normalized network result.
src/…/CdpCaptureEventHandlers.tsShows how passive requests, responses, shapes, and WebSocket frames become evidence.
src/…/WebNetworkCaptureService.tsDefines historical selection, projection, Evidence creation, and provenance checks.
src/…/CaptureBudgets.tsShares one admitted budget policy across the historical operation and its decoder consumers.
src/…/HistoricalCaptureDecoder.tsShows stable artifact reading, offline decoding, runtime limits, partial observations, cleanup ownership, and retry handling.
src/…/NodeCaptureProcess.tsDefines the owned decoder boundary and the bounded reply contract.
src/…/HistoricalCaptureReply.tsValidates decoder replies and applies the final sensitive-number boundary.
src/…/NodeCaptureAdapter.tsDefines the bounded Node profile for package-backed capture formats.
src/…/CaptureRelease.tsDefines decoder heap settings and the runtime-dependent memory boundary.
src/…/CaptureFailures.tsDefines historical read, path, decoder, memory, cancellation, provider-output, and cleanup failure meaning.
src/…/CaptureRedaction.tsDefines structural capture-record checks and literal, URL, credential, number, and byte redaction.
src/…/CaptureJson.tsDefines bounded JSON admission, UTF-8 handling, duplicate-member rejection, lossless number parsing, and parser memory behavior.
src/…/HarCapture.tsShows how HAR records, producer-specific representations, numeric values, and binary content become historical evidence.
src/…/HarSchema.tsDefines the supported HAR profile and the narrow producer adaptations used for validation.
src/…/QlogCapture.tsDefines the supported qlog profile and derived QUIC stream, byte-range, and loss facts.
src/…/SazCapture.tsShows how native SAZ members become ordered session records without replay or HAR conversion.
src/…/SazMetadata.tsDefines the retained SAZ metadata tree and its encoding and depth limits.
src/…/SazProjection.tsApplies shared redaction and byte-sidecar rules to SAZ values.
src/…/ProtobufTrailers.tsDefines gRPC-Web trailer parsing and partial-prefix behavior.
src/…/ProtobufCapture.tsConnects retained body selection, MIME admission, redaction, schema use, and coverage.
src/…/ProtobufFraming.tsDefines frame boundaries and source-first credential checks for protobuf bodies.
src/…/ProtobufWire.tsDefines bounded wire-field facts, offsets, interpretations, and integer handling.
src/…/ProtobufSchema.tsDefines descriptor admission and optional field names and type annotations without replacing wire facts.
src/…/PlaywrightTraceDecoder.tsDefines offline trace ZIP reading, archive identity, stream verification, cleanup, capacity, and partial observations.
src/…/TraceInventory.tsDefines trace members, streams, events, diagnostics, ordering, references, and coverage.
src/…/TraceStream.tsShows how Playwright v10 stream records become bounded browser and network facts.
src/…/TraceEventProjection.tsDefines the selected event facts, source references, redaction, and unknown headline states.
src/…/playwrightTrace.tsDefines trace Evidence, limits, source coverage, and unknown states.
src/…/PlaywrightTraceService.tsConnects trace import to Evidence and preserves partial observations on failure.
src/…/playwrightTraceView.tsDefines summary and paged retrieval of retained trace inventory.
src/…/browserScenarioDiffEvidence.tsExplains completeness-aware comparison of scenario network evidence.
src/…/webCaptureDiff.tsExplains comparison of passive page network and WebSocket observations.
docs/web-network-captures.mdProvides user-facing detail for offline historical capture inspection.