feat(trace): split API requests into a separate network stream

the existing `.network` stream mixed browser traffic with `APIRequestContext` traffic

record `_apiRequest` entries in `.api.network`, archive it as `trace.api.network`, and ingest it alongside `.network`

bump the trace format to `9` so older viewers reject traces that have the new stream

Author: dcrousso

.claude/skills/playwright-dev/trace_system_guide.md

@@ -297,7 +297,8 @@ When a trace is recorded, it creates this structure in the traces directory:
 ```
 traces-dir/
 ├── <traceName>.trace        # Main events (JSONL format)
-├── <traceName>.network      # Network events (JSONL format)
+├── <traceName>.network      # Browser network events (JSONL format)
+├── <traceName>.api.network  # APIRequestContext events (JSONL format)
 ├── <traceName>-chunk1.trace # Additional chunks (if multiple)
 ├── <traceName>.stacks       # Stack trace metadata (optional)
 └── resources/
@@ -306,7 +307,7 @@ traces-dir/
 ```
 
 ### File Formats
-- **`.trace` and `.network`**: JSONL (JSON Lines) - one event per line
+- **`.trace`, `.network`, and `.api.network`**: JSONL (JSON Lines), one event per line
 - **`.zip`**: Optional archive containing all above files
 - **`resources/`**: Binary blobs indexed by SHA1 hash
 
@@ -415,6 +416,7 @@ type RecordingState = {
   options: TracerOptions,
   traceName: string,
   networkFile: string,
+  apiNetworkFile: string,
   traceFile: string,
   tracesDir: string,
   resourcesDir: string,
@@ -457,10 +459,11 @@ async load(backend: TraceLoaderBackend, unzipProgress) {
   1. Find .trace files (ordinals: "0", "1", etc.)
   2. For each ordinal:
      a. Read ordinal.trace (events)
-     b. Read ordinal.network (network events)
-     c. Parse with TraceModernizer
-     d. Read ordinal.stacks (if exists)
-     e. Sort actions by startTime
+     b. Read ordinal.network (browser network events)
+     c. Read ordinal.api.network (APIRequestContext events)
+     d. Parse with TraceModernizer
+     e. Read ordinal.stacks (if exists)
+     f. Sort actions by startTime
   3. Terminate incomplete actions
   4. Finalize snapshot storage
   5. Build resource content-type map

packages/isomorphic/trace/traceLoader.ts

@@ -70,6 +70,8 @@ export class TraceLoader {
 
       const network = await this._backend.readText(prefix + '.network') || '';
       modernizer.appendTrace(network);
+      const apiNetwork = await this._backend.readText(prefix + '.api.network') || '';
+      modernizer.appendTrace(apiNetwork);
       unzipProgress?.(++done, total);
 
       contextEntry.actions = modernizer.actions().sort((a1, a2) => a1.startTime - a2.startTime);

packages/isomorphic/trace/traceModernizer.ts

@@ -21,6 +21,7 @@ import type * as traceV5 from './versions/traceV5';
 import type * as traceV6 from './versions/traceV6';
 import type * as traceV7 from './versions/traceV7';
 import type * as traceV8 from './versions/traceV8';
+import type * as traceV9 from './versions/traceV9';
 import type { ActionEntry, ContextEntry, PageEntry } from './entries';
 import type { SnapshotStorage } from './snapshotStorage';
 
@@ -33,7 +34,8 @@ export class TraceVersionError extends Error {
 
 // 6 => 10/2023 ~1.40
 // 7 => 05/2024 ~1.45
-const latestVersion: trace.VERSION = 8;
+// 8 => 05/2025 ~1.53
+const latestVersion: trace.VERSION = 9;
 
 export class TraceModernizer {
   private _contextEntry: ContextEntry;
@@ -439,4 +441,8 @@ export class TraceModernizer {
     }
     return result;
   }
+
+  _modernize_8_to_9(events: traceV8.TraceEvent[]): traceV9.TraceEvent[] {
+    return events;
+  }
 }

packages/isomorphic/trace/versions/traceV9.ts

@@ -0,0 +1,264 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Entry as ResourceSnapshot } from '@trace/har';
+
+type Language = 'javascript' | 'python' | 'java' | 'csharp' | 'jsonl';
+type Point = { x: number, y: number };
+type Size = { width: number, height: number };
+
+type StackFrame = {
+  file: string,
+  line: number,
+  column: number,
+  function?: string,
+};
+
+type Binary = Buffer;
+
+type SerializedValue = {
+  n?: number,
+  b?: boolean,
+  s?: string,
+  v?: 'null' | 'undefined' | 'NaN' | 'Infinity' | '-Infinity' | '-0',
+  d?: string,
+  u?: string,
+  bi?: string,
+  ta?: {
+    b: Binary,
+    k: 'i8' | 'ui8' | 'ui8c' | 'i16' | 'ui16' | 'i32' | 'ui32' | 'f32' | 'f64' | 'bi64' | 'bui64',
+  },
+  e?: {
+    m: string,
+    n: string,
+    s: string,
+  },
+  r?: {
+    p: string,
+    f: string,
+  },
+  a?: SerializedValue[],
+  o?: {
+    k: string,
+    v: SerializedValue,
+  }[],
+  h?: number,
+  id?: number,
+  ref?: number,
+};
+
+type SerializedError = {
+  error?: {
+    message: string,
+    name: string,
+    stack?: string,
+  },
+  value?: SerializedValue,
+};
+
+// Text node.
+type TextNodeSnapshot = string;
+// Subtree reference, "x snapshots ago, node #y". Could point to a text node.
+// Only nodes that are not references are counted, starting from zero, using post-order traversal.
+type SubtreeReferenceSnapshot = [ [number, number] ];
+// Node name, and optional attributes and child nodes.
+type NodeNameAttributesChildNodesSnapshot = [ string ] | [ string, Record<string, string>, ...NodeSnapshot[] ];
+
+type NodeSnapshot =
+  TextNodeSnapshot |
+  SubtreeReferenceSnapshot |
+  NodeNameAttributesChildNodesSnapshot;
+
+type ResourceOverride = {
+  url: string,
+  sha1?: string,
+  ref?: number
+};
+
+type FrameSnapshot = {
+  snapshotName?: string,
+  callId: string,
+  pageId: string,
+  frameId: string,
+  frameUrl: string,
+  timestamp: number,
+  wallTime?: number,
+  collectionTime: number,
+  doctype?: string,
+  html: NodeSnapshot,
+  resourceOverrides: ResourceOverride[],
+  viewport: { width: number, height: number },
+  isMainFrame: boolean,
+};
+
+type BrowserContextEventOptions = {
+  baseURL?: string,
+  viewport?: Size,
+  deviceScaleFactor?: number,
+  isMobile?: boolean,
+  userAgent?: string,
+};
+
+export type ContextCreatedTraceEvent = {
+  version: number,
+  type: 'context-options',
+  origin: 'testRunner' | 'library',
+  browserName: string,
+  channel?: string,
+  platform: string,
+  playwrightVersion?: string,
+  wallTime: number,
+  monotonicTime: number,
+  title?: string,
+  options: BrowserContextEventOptions,
+  sdkLanguage?: Language,
+  testIdAttributeName?: string,
+  contextId?: string,
+  testTimeout?: number,
+  annotations?: TraceEventAnnotation[],
+};
+
+export type ScreencastFrameTraceEvent = {
+  type: 'screencast-frame',
+  pageId: string,
+  sha1: string,
+  width: number,
+  height: number,
+  timestamp: number,
+  frameSwapWallTime?: number,
+};
+
+export type BeforeActionTraceEvent = {
+  type: 'before',
+  callId: string;
+  startTime: number;
+  title?: string;
+  class: string;
+  method: string;
+  params: Record<string, any>;
+  stepId?: string;
+  beforeSnapshot?: string;
+  stack?: StackFrame[];
+  pageId?: string;
+  parentId?: string;
+  group?: string;
+};
+
+export type InputActionTraceEvent = {
+  type: 'input',
+  callId: string;
+  inputSnapshot?: string;
+  point?: Point;
+};
+
+export type AfterActionTraceEventAttachment = {
+  name: string;
+  contentType: string;
+  path?: string;
+  sha1?: string;
+  base64?: string;
+};
+
+export type TraceEventAnnotation = {
+  type: string,
+  description?: string
+};
+
+export type AfterActionTraceEvent = {
+  type: 'after',
+  callId: string;
+  endTime: number;
+  afterSnapshot?: string;
+  error?: SerializedError['error'];
+  attachments?: AfterActionTraceEventAttachment[];
+  annotations?: TraceEventAnnotation[];
+  result?: any;
+  point?: Point;
+};
+
+export type LogTraceEvent = {
+  type: 'log',
+  callId: string;
+  time: number;
+  message: string;
+};
+
+export type EventTraceEvent = {
+  type: 'event',
+  time: number;
+  class: string;
+  method: string;
+  params: any;
+  pageId?: string;
+};
+
+export type ConsoleMessageTraceEvent = {
+  type: 'console';
+  time: number;
+  pageId?: string;
+  messageType: string,
+  text: string,
+  args?: { preview: string, value: any }[],
+  location: {
+    url: string,
+    lineNumber: number,
+    columnNumber: number,
+  },
+};
+
+export type ResourceSnapshotTraceEvent = {
+  type: 'resource-snapshot',
+  snapshot: ResourceSnapshot,
+};
+
+export type FrameSnapshotTraceEvent = {
+  type: 'frame-snapshot',
+  snapshot: FrameSnapshot,
+};
+
+export type ActionTraceEvent = {
+  type: 'action',
+} & Omit<BeforeActionTraceEvent, 'type'>
+  & Omit<AfterActionTraceEvent, 'type'>
+  & Omit<InputActionTraceEvent, 'type'>;
+
+export type StdioTraceEvent = {
+  type: 'stdout' | 'stderr';
+  timestamp: number;
+  text?: string;
+  base64?: string;
+};
+
+export type ErrorTraceEvent = {
+  type: 'error';
+  message: string;
+  stack?: StackFrame[];
+};
+
+export type TraceEvent =
+    ContextCreatedTraceEvent |
+    ScreencastFrameTraceEvent |
+    ActionTraceEvent |
+    BeforeActionTraceEvent |
+    InputActionTraceEvent |
+    AfterActionTraceEvent |
+    EventTraceEvent |
+    LogTraceEvent |
+    ConsoleMessageTraceEvent |
+    ResourceSnapshotTraceEvent |
+    FrameSnapshotTraceEvent |
+    StdioTraceEvent |
+    ErrorTraceEvent;