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_viewparent-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
| Trigger | Consequence | Guard |
|---|---|---|
| Capture ends while a request is open | The request is unfinished and response content can be unavailable | Read completeness and unfinished reason before claiming a full response path |
| A selected body or header read fails or times out | Lifecycle facts remain, but selected content is unavailable | Do not treat unavailable content as an empty body or absent header |
| The browser materializes a body above the retained-body or allocation limit | The body is withheld even though the network transaction remains valid | Read the body state and limit reason before using content claims |
| Redaction would make a JSON body invalid | The body is withheld instead of returning unsafe JSON | Treat body-read failure as unavailable content |
| Before and after captures use different content selections | Network comparison cannot establish equality | Use the same body and header choices on both sides |
| A source artifact changes during historical read | Inspection reports a retryable integrity failure | Use a stable capture file and preserve the original artifact |
| A decoder reaches an input, output, nesting, parser-node, or memory limit | No complete historical result is available | Use a smaller producer export or raise only the needed per-operation budget |
| A depth policy leaves too little room for returned Evidence | The request is rejected before inspection | Select 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 provide | Historical inspection is unavailable for that format | Run the supported decoder runtime or select another format |
| A runtime exits with an unrecognized failure pattern | The failure is reported as execution failure rather than a memory limit | Read the reported failure phase and process diagnostics |
| The decoder reply is invalid UTF-8, malformed JSON, or outside its schema | The historical result is rejected as untrusted output | Keep the reply bounded UTF-8 JSON and validate its byte count |
| A HAR declares base64 but contains non-canonical content | The historical record is rejected | Preserve valid canonical base64 for binary content |
| A HAR contains malformed timing or schema facts | The source is rejected instead of producing misleading partial records | Validate producer facts before projection |
| A failed HAR request uses an unrecognized producer profile for unavailable timing sentinels | The source is rejected instead of being broadly normalized | Admit only known producer representations and retain original failed-request values |
| A SAZ archive contains duplicate names, encryption, links, or unknown raw members | The archive is rejected instead of producing ambiguous session records | Preserve native archive member identity and export an unencrypted supported SAZ |
| A SAZ request or response member is empty | The related message is reported as null with a limitation | Treat the empty member state as unknown content, not as an empty HTTP message |
| A qlog stream or loss event has hidden or incomplete required fields | The related derived fact is incomplete or unknown | Read incomplete-fact records with stream and loss summaries |
| A Playwright trace has no supported stream or declares an unsupported version | The trace inventory is unavailable or unsupported | Export a Playwright version 10 trace with required stream members |
| A trace member path occurs more than once | Resource references become ambiguous | Use member occurrence identity and do not infer one payload from the path |
| A trace import reaches its archive, stream, fact, line, or concurrency limit | Import fails or retains only verified partial observation | Use a smaller recorder chunk and wait for an active import to finish |
| A trace stream fails archive verification | Its network facts are not promoted to the inventory | Keep only facts from fully verified streams |
| A trace record has malformed JSON or no known stream profile | The record is diagnosed and its facts are not interpreted | Use source line diagnostics and require a verified version 10 context |
| A trace resource reference is missing, encrypted, ambiguous, or present-unread | The event does not prove that resource bytes are available or valid | Use the reference state and retain the original archive |
| A selected Protocol Buffer body has invalid framing, credential data, or sensitive bytes | The body is withheld or decoding is partial | Read protobuf status, redactions, and coverage before using fields |
| A selected Protocol Buffer body has unknown or conflicting MIME metadata | Automatic applicability is unknown and the body may remain uninterpreted | Use explicit framing only when the retained bytes and transport rules support that choice |
| A descriptor set is malformed or does not define the selected message | Schema annotations are unavailable, while raw wire facts can remain available | Check schema admission before relying on field names or types |
| A descriptor has duplicate type or field identity | Schema admission fails before annotations are applied | Use 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 value | Valid earlier trailers may remain, but the trailer view is partial | Use the trailer status and examined byte count before treating the block as complete |
Key files
| File | Why to read it |
|---|---|
| src/…/browserScenarioToolContracts.ts | Defines the controlled-capture purpose and content-selection contract. |
| src/…/browserScenarioCaptureValues.ts | Shows the step, lifecycle-event, content-state, and completeness model. |
| src/…/PlaywrightScenarioNetwork.ts | Explains how request transactions, redirects, completion, and bounded reads become events. |
| src/…/PlaywrightNetworkContent.ts | Defines bounded header and body reads, redaction, and retained byte integrity. |
| src/…/browserNetworkEvidence.ts | Defines retained body and header evidence states and integrity fields. |
| src/…/CdpPageCapture.ts | Defines the passive observation window and normalized network result. |
| src/…/CdpCaptureEventHandlers.ts | Shows how passive requests, responses, shapes, and WebSocket frames become evidence. |
| src/…/WebNetworkCaptureService.ts | Defines historical selection, projection, Evidence creation, and provenance checks. |
| src/…/CaptureBudgets.ts | Shares one admitted budget policy across the historical operation and its decoder consumers. |
| src/…/HistoricalCaptureDecoder.ts | Shows stable artifact reading, offline decoding, runtime limits, partial observations, cleanup ownership, and retry handling. |
| src/…/NodeCaptureProcess.ts | Defines the owned decoder boundary and the bounded reply contract. |
| src/…/HistoricalCaptureReply.ts | Validates decoder replies and applies the final sensitive-number boundary. |
| src/…/NodeCaptureAdapter.ts | Defines the bounded Node profile for package-backed capture formats. |
| src/…/CaptureRelease.ts | Defines decoder heap settings and the runtime-dependent memory boundary. |
| src/…/CaptureFailures.ts | Defines historical read, path, decoder, memory, cancellation, provider-output, and cleanup failure meaning. |
| src/…/CaptureRedaction.ts | Defines structural capture-record checks and literal, URL, credential, number, and byte redaction. |
| src/…/CaptureJson.ts | Defines bounded JSON admission, UTF-8 handling, duplicate-member rejection, lossless number parsing, and parser memory behavior. |
| src/…/HarCapture.ts | Shows how HAR records, producer-specific representations, numeric values, and binary content become historical evidence. |
| src/…/HarSchema.ts | Defines the supported HAR profile and the narrow producer adaptations used for validation. |
| src/…/QlogCapture.ts | Defines the supported qlog profile and derived QUIC stream, byte-range, and loss facts. |
| src/…/SazCapture.ts | Shows how native SAZ members become ordered session records without replay or HAR conversion. |
| src/…/SazMetadata.ts | Defines the retained SAZ metadata tree and its encoding and depth limits. |
| src/…/SazProjection.ts | Applies shared redaction and byte-sidecar rules to SAZ values. |
| src/…/ProtobufTrailers.ts | Defines gRPC-Web trailer parsing and partial-prefix behavior. |
| src/…/ProtobufCapture.ts | Connects retained body selection, MIME admission, redaction, schema use, and coverage. |
| src/…/ProtobufFraming.ts | Defines frame boundaries and source-first credential checks for protobuf bodies. |
| src/…/ProtobufWire.ts | Defines bounded wire-field facts, offsets, interpretations, and integer handling. |
| src/…/ProtobufSchema.ts | Defines descriptor admission and optional field names and type annotations without replacing wire facts. |
| src/…/PlaywrightTraceDecoder.ts | Defines offline trace ZIP reading, archive identity, stream verification, cleanup, capacity, and partial observations. |
| src/…/TraceInventory.ts | Defines trace members, streams, events, diagnostics, ordering, references, and coverage. |
| src/…/TraceStream.ts | Shows how Playwright v10 stream records become bounded browser and network facts. |
| src/…/TraceEventProjection.ts | Defines the selected event facts, source references, redaction, and unknown headline states. |
| src/…/playwrightTrace.ts | Defines trace Evidence, limits, source coverage, and unknown states. |
| src/…/PlaywrightTraceService.ts | Connects trace import to Evidence and preserves partial observations on failure. |
| src/…/playwrightTraceView.ts | Defines summary and paged retrieval of retained trace inventory. |
| src/…/browserScenarioDiffEvidence.ts | Explains completeness-aware comparison of scenario network evidence. |
| src/…/webCaptureDiff.ts | Explains comparison of passive page network and WebSocket observations. |
| docs/web-network-captures.md | Provides user-facing detail for offline historical capture inspection. |