@browserbridge/bbx 1.7.8 → 1.9.0

package/packages/protocol/src/types.ts

@@ -1,5 +1,15 @@
 export type BridgeRequestSource = 'cli' | 'mcp';
 
+export type AccessIntent = 'inspect' | 'interact' | 'capture' | 'navigate' | 'debugger' | 'general';
+
+export interface AccessRequestParams {
+  intent?: AccessIntent;
+}
+
+export interface NormalizedAccessRequestParams extends BridgeParams {
+  intent: AccessIntent;
+}
+
 export type Capability =
   | 'page.read'
   | 'page.evaluate'
@@ -19,14 +29,32 @@ export type Capability =
   | 'tabs.manage'
   | 'performance.read'
   | 'network.read'
-  | 'network.intercept';
+  | 'network.intercept'
+  | 'sensitive.read';
 
 export type ErrorCode =
   | 'ACCESS_DENIED'
   | 'TAB_MISMATCH'
   | 'ELEMENT_STALE'
+  | 'ELEMENT_AMBIGUOUS'
+  | 'ELEMENT_NOT_ACTIONABLE'
+  | 'ELEMENT_OBSCURED'
+  | 'ELEMENT_NOT_FOUND'
+  | 'INPUT_UNSUPPORTED'
+  | 'INPUT_INVALID_TARGET'
+  | 'INPUT_FOCUS_CHANGED'
+  | 'DIALOG_NOT_OPEN'
+  | 'DIALOG_ACTION_CONFLICT'
   | 'RESULT_TRUNCATED'
-  | 'RATE_LIMITED'
+  | 'RESULT_TOO_LARGE'
+  | 'SENSITIVE_TARGET_NOT_FOUND'
+  | 'CONTENT_SCRIPT_UNAVAILABLE'
+  | 'ARTIFACT_NOT_FOUND'
+  | 'ARTIFACT_QUOTA_EXCEEDED'
+  | 'ARTIFACT_TRANSFER_INVALID'
+  | 'DOM_BASELINE_NOT_FOUND'
+  | 'DOM_BASELINE_INVALIDATED'
+  | 'DOM_BASELINE_QUOTA_EXCEEDED'
   | 'INTERNAL_ERROR'
   | 'INVALID_REQUEST'
   | 'NATIVE_HOST_UNAVAILABLE'
@@ -45,10 +73,14 @@ export type BridgeMethod =
   | 'page.get_state'
   | 'page.evaluate'
   | 'page.get_console'
+  | 'page.handle_dialog'
   | 'page.wait_for_load_state'
   | 'page.get_storage'
+  | 'sensitive.read'
   | 'page.get_text'
+  | 'page.extract_content'
   | 'page.get_network'
+  | 'network.export_har'
   | 'network.intercept.add'
   | 'network.intercept.remove'
   | 'network.intercept.list'
@@ -58,6 +90,10 @@ export type BridgeMethod =
   | 'navigation.go_back'
   | 'navigation.go_forward'
   | 'dom.query'
+  | 'dom.baseline.create'
+  | 'dom.baseline.compare'
+  | 'dom.baseline.describe'
+  | 'dom.baseline.release'
   | 'dom.describe'
   | 'dom.get_text'
   | 'dom.get_attributes'
@@ -85,6 +121,8 @@ export type BridgeMethod =
   | 'screenshot.capture_region'
   | 'screenshot.capture_element'
   | 'screenshot.capture_full_page'
+  | 'artifact.read'
+  | 'artifact.delete'
   | 'patch.apply_styles'
   | 'patch.apply_dom'
   | 'patch.list'
@@ -121,9 +159,44 @@ export interface BridgeMeta {
   budget_applied?: boolean;
   budget_truncated?: boolean;
   continuation_hint?: string | null;
+  automatic_retry?: { attempt: 2; reason: 'retryable_error' };
+  stale_recovery?: 'success' | 'failure';
   [key: string]: unknown;
 }
 
+export type RecoveryScope = 'routedExtension' | 'daemon';
+
+export type RecoveryEventKind =
+  | 'automatic_mcp_retry'
+  | 'stale_ref_recovery'
+  | 'debugger_reattach'
+  | 'content_script_reinjection'
+  | 'native_host_reconnect'
+  | 'request_outcome';
+
+export interface RecoveryEventSummary {
+  attempts: number;
+  successes: number;
+  failures: number;
+  pending: number;
+  saturated: boolean;
+  successRate: number | null;
+  failureRate: number | null;
+  activeLoop: boolean;
+  lastEventAt: number | null;
+}
+
+export interface RecoveryTelemetrySummary {
+  scope: RecoveryScope;
+  windowMs: number;
+  bucketMs: number;
+  loopWindowMs: number;
+  loopThreshold: number;
+  asOf: number;
+  activeLoop: boolean;
+  events: Record<RecoveryEventKind, RecoveryEventSummary>;
+}
+
 export interface BridgeParams {
   [key: string]: unknown;
 }
@@ -202,6 +275,147 @@ export interface NormalizedDomQuery extends BridgeParams {
   budget: Budget;
 }
 
+export interface DomBaselineCreateParams {
+  selector?: string;
+  maxNodes?: number;
+  maxDepth?: number;
+  textBudget?: number;
+  attributeAllowlist?: string[];
+}
+
+export interface NormalizedDomBaselineCreateParams extends BridgeParams {
+  selector: string;
+  maxNodes: number;
+  maxDepth: number;
+  textBudget: number;
+  attributeAllowlist: string[];
+}
+
+export interface DomBaselineCompareParams {
+  baselineId?: string;
+  maxChanges?: number;
+}
+
+export interface NormalizedDomBaselineCompareParams extends BridgeParams {
+  baselineId: string;
+  maxChanges: number;
+}
+
+export interface DomBaselineHandleParams {
+  baselineId?: string;
+}
+
+export interface NormalizedDomBaselineHandleParams extends BridgeParams {
+  baselineId: string;
+}
+
+export interface DomBaselineOptions {
+  maxNodes: number;
+  maxDepth: number;
+  textBudget: number;
+  attributeAllowlist: string[];
+}
+
+export interface DomBaselineScope {
+  windowId: number;
+  tabId: number;
+  frameId: number;
+  documentToken: string;
+  selector: string;
+  representation: 'semantic-dom-v1';
+}
+
+export interface DomBaselineSnapshotStats {
+  nodeCount: number;
+  byteLength: number;
+  digest: string;
+}
+
+export interface DomBaselineDescriptor {
+  baselineId: string;
+  createdAt: string;
+  expiresAt: string;
+  scope: DomBaselineScope;
+  options: DomBaselineOptions;
+  snapshot: DomBaselineSnapshotStats;
+  evicted?: Array<{
+    baselineId: string;
+    reason: 'per_tab_quota' | 'global_quota';
+  }>;
+}
+
+export type DomBaselineCreateResult = DomBaselineDescriptor;
+export type DomBaselineDescribeResult = DomBaselineDescriptor;
+
+export interface DomBaselineSemanticNodeEvidence {
+  tag: string;
+  role: string | null;
+  name: string | null;
+  text: string;
+  attributes: Record<string, string>;
+  depth: number;
+}
+
+export type DomBaselineNodeEvidence = DomBaselineSemanticNodeEvidence;
+
+export interface DomBaselineChangedNode {
+  fields: string[];
+  before: DomBaselineSemanticNodeEvidence;
+  after: DomBaselineSemanticNodeEvidence;
+}
+
+export interface DomBaselineNodeLocation {
+  ancestry: string[];
+  order: number;
+}
+
+export interface DomBaselineMovedNode {
+  node: DomBaselineSemanticNodeEvidence;
+  from: DomBaselineNodeLocation;
+  to: DomBaselineNodeLocation;
+}
+
+export interface DomBaselineChangeCounts {
+  added: number;
+  removed: number;
+  changed: number;
+  moved: number;
+  unchanged: number;
+  total: number;
+}
+
+export interface DomBaselineReturnedCounts {
+  added: number;
+  removed: number;
+  changed: number;
+  moved: number;
+  total: number;
+}
+
+export interface DomBaselineCompareResult {
+  baselineId: string;
+  equal: boolean;
+  comparedAt: string;
+  counts: DomBaselineChangeCounts;
+  returnedCounts: DomBaselineReturnedCounts;
+  added: DomBaselineSemanticNodeEvidence[];
+  removed: DomBaselineSemanticNodeEvidence[];
+  changed: DomBaselineChangedNode[];
+  moved: DomBaselineMovedNode[];
+  truncated: boolean;
+  omittedChanges: number;
+  ambiguity: {
+    count: number;
+    examples: DomBaselineSemanticNodeEvidence[];
+  };
+  guidance: string;
+}
+
+export interface DomBaselineReleaseResult {
+  baselineId: string;
+  released: boolean;
+}
+
 export interface DomFindResult {
   found: boolean;
   nodes: Record<string, unknown>[];
@@ -228,6 +442,29 @@ export interface InputTarget {
   selector?: string;
 }
 
+export type InputExecutionMode = 'dom' | 'cdp';
+
+export interface InputResolutionMetadata {
+  strategy: 'elementRef' | 'selector-first' | 'selector-ranked' | 'stale-recovery';
+  candidateCount: number;
+  evaluatedCount: number;
+  scrolled: boolean;
+  hitTest: 'target' | 'descendant' | 'none' | 'not-required';
+  recovered: boolean;
+  oldRef?: string;
+  newRef?: string;
+  matchedFields?: string[];
+  confidenceBasis?: string;
+}
+
+export interface InputExecutionMetadata {
+  requestedMode: InputExecutionMode;
+  actualMode: InputExecutionMode;
+  fallbackReason: null;
+  debuggerUsed: boolean;
+  targetCoordinates?: { x: number; y: number };
+}
+
 export interface InputActionParams {
   target?: InputTarget;
   button?: 'left' | 'middle' | 'right';
@@ -239,6 +476,8 @@ export interface InputActionParams {
   submit?: boolean;
   key?: string;
   modifiers?: string[];
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedInputAction extends BridgeParams {
@@ -252,6 +491,8 @@ export interface NormalizedInputAction extends BridgeParams {
   submit: boolean;
   key: string;
   modifiers: string[];
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface CdpDispatchKeyEventParams {
@@ -264,6 +505,10 @@ export interface CdpNodeIdParams {
   nodeId?: number;
 }
 
+export interface CdpDomSnapshotParams {
+  computedStyles?: string[];
+}
+
 export interface NormalizedCdpDispatchKeyEventParams extends BridgeParams {
   key: string;
   code: string;
@@ -274,14 +519,22 @@ export interface NormalizedCdpNodeIdParams extends BridgeParams {
   nodeId: number;
 }
 
+export interface NormalizedCdpDomSnapshotParams extends BridgeParams {
+  computedStyles: string[];
+}
+
 export interface CheckedActionParams {
   target?: InputTarget;
   checked?: boolean;
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedCheckedAction extends BridgeParams {
   target: InputTarget;
   checked: boolean;
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface SelectActionParams {
@@ -289,6 +542,8 @@ export interface SelectActionParams {
   values?: string[];
   labels?: string[];
   indexes?: number[];
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedSelectAction extends BridgeParams {
@@ -296,6 +551,8 @@ export interface NormalizedSelectAction extends BridgeParams {
   values: string[];
   labels: string[];
   indexes: number[];
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface ViewportActionParams {
@@ -417,6 +674,21 @@ export interface ConsoleParams {
   limit?: number;
 }
 
+export type DialogAction = 'inspect' | 'accept' | 'dismiss';
+
+export interface HandleDialogParams {
+  action?: DialogAction;
+  promptText?: string;
+  /** Optional stale-decision check performed immediately before CDP dispatch. */
+  expectedDialogId?: string;
+}
+
+export interface NormalizedHandleDialogParams extends BridgeParams {
+  action: DialogAction;
+  promptText: string | null;
+  expectedDialogId: string | null;
+}
+
 export interface NormalizedConsoleParams extends BridgeParams {
   level: string;
   clear: boolean;
@@ -483,12 +755,16 @@ export interface HoverParams {
   target?: InputTarget;
   duration?: number;
   modifiers?: string[];
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedHoverParams extends BridgeParams {
   target: InputTarget;
   duration: number;
   modifiers: string[];
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface DragParams {
@@ -496,6 +772,8 @@ export interface DragParams {
   destination?: InputTarget;
   offsetX?: number;
   offsetY?: number;
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
 }
 
 export interface NormalizedDragParams extends BridgeParams {
@@ -503,6 +781,8 @@ export interface NormalizedDragParams extends BridgeParams {
   destination: InputTarget;
   offsetX: number;
   offsetY: number;
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
 }
 
 export interface StorageParams {
@@ -515,14 +795,136 @@ export interface NormalizedStorageParams extends BridgeParams {
   keys: string[] | null;
 }
 
+export type SensitiveStorageSource = 'local_storage' | 'session_storage';
+
+export interface SensitiveReadParams {
+  source: SensitiveStorageSource;
+  key: string;
+}
+
+export interface NormalizedSensitiveReadParams extends BridgeParams {
+  source: SensitiveStorageSource;
+  key: string;
+  maxBytes: number;
+}
+
+export interface SensitiveReadResult {
+  source: SensitiveStorageSource;
+  value: string;
+  exact: true;
+}
+
+export type ExtractContentFormat = 'text' | 'markdown';
+export type ExtractContentConsistency = 'best_effort' | 'settled';
+export type ExtractContentSource = 'readability' | 'semantic-root' | 'body';
+export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
+export type ScreenshotDelivery = 'auto' | 'inline' | 'artifact';
+export type ArtifactKind = 'screenshot' | 'har';
+
+export interface ExtractContentParams {
+  format?: ExtractContentFormat;
+  selector?: string;
+  includeMetadata?: boolean;
+  consistency?: ExtractContentConsistency;
+  textBudget?: number;
+  settleTimeoutMs?: number;
+}
+
+export interface NormalizedExtractContentParams extends BridgeParams {
+  format: ExtractContentFormat;
+  selector: string | null;
+  includeMetadata: boolean;
+  consistency: ExtractContentConsistency;
+  textBudget: number;
+  settleTimeoutMs: number;
+}
+
+export interface ScreenshotParams extends BridgeParams {
+  format?: ScreenshotFormat;
+  quality?: number;
+  delivery?: ScreenshotDelivery;
+  scale?: number;
+}
+
+export interface NormalizedScreenshotParams extends BridgeParams {
+  format: ScreenshotFormat;
+  quality: number | null;
+  delivery: ScreenshotDelivery;
+  scale: number;
+}
+
+export interface ArtifactDescriptor<K extends ArtifactKind = ArtifactKind> {
+  artifactId: string;
+  kind: K;
+  mimeType: string;
+  byteLength: number;
+  sha256: string;
+  chunkSize: number;
+  chunkCount: number;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface ScreenshotMetadata {
+  mimeType: `image/${ScreenshotFormat}`;
+  format: ScreenshotFormat;
+  byteLength: number;
+  dimensions: { width: number; height: number };
+  rect: { x: number; y: number; width: number; height: number; scale: number };
+  complete: boolean;
+  clipped: boolean;
+}
+
+export type ScreenshotResult =
+  | (ScreenshotMetadata & { delivery: 'inline'; image: string })
+  | (ScreenshotMetadata & {
+      delivery: 'artifact';
+      artifact: ArtifactDescriptor<'screenshot'>;
+    });
+
+export interface ArtifactReadParams extends BridgeParams {
+  artifactId?: string;
+  offset?: number;
+  maxBytes?: number;
+}
+
+export interface NormalizedArtifactReadParams extends BridgeParams {
+  artifactId: string;
+  offset: number;
+  maxBytes: number;
+}
+
+export interface ArtifactDeleteParams extends BridgeParams {
+  artifactId?: string;
+}
+
+export interface ExtractContentResult {
+  format: ExtractContentFormat;
+  content: string;
+  title?: string;
+  byline?: string;
+  excerpt?: string;
+  siteName?: string;
+  source: ExtractContentSource;
+  root?: { tag: string; selector?: string };
+  length: number;
+  truncated: boolean;
+  omitted: number;
+  settlement?: { requested: boolean; quietMs: number; timedOut: boolean };
+}
+
 export interface WaitForLoadStateParams {
   waitForLoad?: boolean;
   timeoutMs?: number;
+  url?: string;
+  urlMatch?: 'exact' | 'contains' | 'regex';
 }
 
 export interface NormalizedWaitForLoadStateParams extends BridgeParams {
   waitForLoad: boolean;
   timeoutMs: number;
+  url: string | null;
+  urlMatch: 'exact' | 'contains' | 'regex' | null;
 }
 
 export interface TabCreateParams {
@@ -544,25 +946,342 @@ export interface NormalizedTabCloseParams extends BridgeParams {
 }
 
 export interface AccessibilityTreeParams {
+  selector?: string;
   maxDepth?: number;
   maxNodes?: number;
+  compact?: boolean;
+  interactiveOnly?: boolean;
 }
 
 export interface NormalizedAccessibilityTreeParams extends BridgeParams {
+  selector: string | null;
   maxDepth: number;
   maxNodes: number;
+  compact: boolean;
+  interactiveOnly: boolean;
 }
 
+export interface AccessibilityTreeNode {
+  nodeId: string;
+  role: string;
+  name: string;
+  description: string;
+  value: string;
+  focused: boolean;
+  required: boolean;
+  checked: 'true' | 'false' | 'mixed' | null;
+  disabled: boolean;
+  interactive: boolean;
+  semanticInteractive: boolean;
+  focusable: boolean;
+  focusableAndEnabled: boolean;
+  ignored: boolean;
+  childIds: string[];
+}
+
+export interface AccessibilityTreeResult {
+  nodes: AccessibilityTreeNode[];
+  rootIds: string[];
+  count: number;
+  total: number;
+  rawTotal: number;
+  source: 'cdp-accessibility';
+  compact: boolean;
+  interactiveOnly: boolean;
+  truncated: boolean;
+  truncation: {
+    reason: 'maxNodes' | 'maxDepth';
+    reasons: Array<'maxNodes' | 'maxDepth'>;
+    maxNodes: number;
+    maxDepth: number;
+    omitted: number;
+    missingChildCount: number;
+    partialTopology: true;
+  };
+  continuationHint: string;
+}
+
+export type NetworkSource = 'fetch-xhr' | 'cdp';
+export type NetworkCaptureAction = 'read' | 'start' | 'clear' | 'stop';
+
 export interface NetworkParams {
   clear?: boolean;
   limit?: number;
   urlPattern?: string;
+  source?: NetworkSource;
+  capture?: NetworkCaptureAction;
 }
 
 export interface NormalizedNetworkParams extends BridgeParams {
   clear: boolean;
   limit: number;
   urlPattern: string | null;
+  source: NetworkSource;
+  capture: NetworkCaptureAction;
+}
+
+export interface CdpNetworkEntry {
+  requestId: string;
+  url: string;
+  method: string;
+  resourceType: string;
+  status: number;
+  mimeType: string;
+  protocol: string;
+  fromCache: boolean;
+  fromDiskCache: boolean;
+  fromServiceWorker: boolean;
+  fromPrefetchCache: boolean;
+  redirect: {
+    count: number;
+    hops: Array<{ url: string; status: number }>;
+    truncated: boolean;
+  };
+  failureReason: string;
+  duration: number;
+  timestamp: number;
+}
+
+export interface NetworkResult {
+  entries: Array<CdpNetworkEntry | Record<string, unknown>>;
+  count: number;
+  total: number;
+  filteredTotal: number;
+  dropped: number;
+  abandoned: number;
+  source: NetworkSource;
+  capture: NetworkCaptureAction | null;
+  armed: boolean;
+  armedDuringCapture: boolean;
+  captureState: 'armed' | 'stop_failed' | 'stopped' | 'instrumented';
+  ownershipHeld: boolean;
+  startedAt: number | null;
+  inflight: number;
+  truncated: boolean;
+  truncation: { reason: 'limit' | null; limit: number; omitted: number };
+}
+
+export interface CdpPerformanceMetric {
+  name: string;
+  value: number;
+}
+
+export interface PerformanceMeasurement {
+  source: 'cdp.Performance.getMetrics';
+  kind: 'raw_cdp_counters';
+  sampledAt: string;
+  timeDomain: 'timeTicks';
+  observation: 'browser_maintained_point_sample';
+  webVitals: 'not_measured';
+}
+
+export interface PerformanceMetricsResult {
+  metrics: Record<string, number>;
+  measurement: PerformanceMeasurement;
+}
+
+export type HarDelivery = 'auto' | 'inline' | 'artifact';
+export type HarCaptureState = NetworkResult['captureState'];
+
+export interface HarExportParams {
+  limit?: number;
+  urlPattern?: string;
+  delivery?: HarDelivery;
+}
+
+export interface NormalizedHarExportParams extends BridgeParams {
+  limit: number;
+  urlPattern: string | null;
+  delivery: HarDelivery;
+}
+
+export interface HarEvidenceEntry extends Record<string, unknown> {
+  url: string;
+  method: string;
+  resourceType: string;
+  status: number;
+  mimeType: string;
+  protocol: string;
+  fromCache: boolean;
+  fromDiskCache: boolean;
+  fromServiceWorker: boolean;
+  fromPrefetchCache: boolean;
+  failureReason: string;
+  redirectURL: string;
+  duration: number;
+  startedAt: number;
+}
+
+export interface HarNameValue extends Record<string, unknown> {
+  name: string;
+  value: string;
+  comment?: string;
+}
+
+export interface HarCookie extends HarNameValue {
+  path?: string;
+  domain?: string;
+  expires?: string;
+  httpOnly?: boolean;
+  secure?: boolean;
+}
+
+export interface HarPostDataParam extends HarNameValue {
+  fileName?: string;
+  contentType?: string;
+}
+
+export interface HarPostData extends Record<string, unknown> {
+  mimeType: string;
+  params?: HarPostDataParam[];
+  text?: string;
+  comment?: string;
+}
+
+export interface HarRequest extends Record<string, unknown> {
+  method: string;
+  url: string;
+  httpVersion: string;
+  cookies: HarCookie[];
+  headers: HarNameValue[];
+  queryString: HarNameValue[];
+  postData?: HarPostData;
+  headersSize: number;
+  bodySize: number;
+  comment?: string;
+}
+
+export interface HarContent extends Record<string, unknown> {
+  size: number;
+  compression?: number;
+  mimeType: string;
+  text?: string;
+  encoding?: string;
+  comment?: string;
+}
+
+export interface HarResponse extends Record<string, unknown> {
+  status: number;
+  statusText: string;
+  httpVersion: string;
+  cookies: HarCookie[];
+  headers: HarNameValue[];
+  content: HarContent;
+  redirectURL: string;
+  headersSize: number;
+  bodySize: number;
+  comment?: string;
+}
+
+export interface HarCacheInfo extends Record<string, unknown> {
+  expires?: string;
+  lastAccess: string;
+  eTag: string;
+  hitCount: number;
+  comment?: string;
+}
+
+export interface HarCache extends Record<string, unknown> {
+  beforeRequest?: HarCacheInfo;
+  afterRequest?: HarCacheInfo;
+  comment?: string;
+}
+
+export interface HarTimings extends Record<string, unknown> {
+  blocked?: number;
+  dns?: number;
+  connect?: number;
+  send: number;
+  wait: number;
+  receive: number;
+  ssl?: number;
+  comment?: string;
+}
+
+export interface HarPageTimings extends Record<string, unknown> {
+  onContentLoad?: number;
+  onLoad?: number;
+  comment?: string;
+}
+
+export interface HarPage extends Record<string, unknown> {
+  startedDateTime: string;
+  id: string;
+  title: string;
+  pageTimings: HarPageTimings;
+  comment?: string;
+}
+
+export interface HarCreator extends Record<string, unknown> {
+  name: string;
+  version: string;
+  comment?: string;
+}
+
+export interface HarEntry extends Record<string, unknown> {
+  pageref?: string;
+  startedDateTime: string;
+  time: number;
+  request: HarRequest;
+  response: HarResponse;
+  cache: HarCache;
+  timings: HarTimings;
+  serverIPAddress?: string;
+  connection?: string;
+  comment?: string;
+}
+
+export interface HarLog extends Record<string, unknown> {
+  version: '1.2';
+  creator: HarCreator;
+  browser?: HarCreator;
+  pages?: HarPage[];
+  entries: HarEntry[];
+  comment?: string;
+}
+
+export interface HarDocument extends Record<string, unknown> {
+  log: HarLog;
+}
+
+export interface HarExportTruncation {
+  reason: 'limit' | 'inline_bytes' | null;
+  limit: number;
+  omitted: number;
+  omittedByLimit: number;
+  omittedBySize: number;
+}
+
+export interface HarExportMetadata {
+  format: 'har';
+  harVersion: '1.2';
+  mimeType: 'application/json';
+  byteLength: number;
+  entryCount: number;
+  totalEntries: number;
+  dropped: number;
+  abandoned: number;
+  inflight: number;
+  startedAt: number | null;
+  captureState: HarCaptureState;
+  truncated: boolean;
+  truncation: HarExportTruncation;
+}
+
+export type HarExportResult =
+  | (HarExportMetadata & { delivery: 'inline'; har: HarDocument })
+  | (HarExportMetadata & {
+      delivery: 'artifact';
+      artifact: ArtifactDescriptor<'har'>;
+    });
+
+export interface HarExportEvidence {
+  delivery: HarExportResult['delivery'];
+  entryCount: number;
+  totalEntries: number;
+  dropped: number;
+  abandoned: number;
+  inflight: number;
 }
 
 export type NetworkInterceptAction = 'fulfill' | 'continue' | 'block';