@browserbridge/bbx 1.8.0 → 1.9.0

package/packages/protocol/src/types.ts

@@ -29,7 +29,8 @@ export type Capability =
   | 'tabs.manage'
   | 'performance.read'
   | 'network.read'
-  | 'network.intercept';
+  | 'network.intercept'
+  | 'sensitive.read';
 
 export type ErrorCode =
   | 'ACCESS_DENIED'
@@ -45,7 +46,15 @@ export type ErrorCode =
   | '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'
@@ -67,9 +76,11 @@ export type BridgeMethod =
   | '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'
@@ -79,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'
@@ -106,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'
@@ -142,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;
 }
@@ -223,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>[];
@@ -312,6 +505,10 @@ export interface CdpNodeIdParams {
   nodeId?: number;
 }
 
+export interface CdpDomSnapshotParams {
+  computedStyles?: string[];
+}
+
 export interface NormalizedCdpDispatchKeyEventParams extends BridgeParams {
   key: string;
   code: string;
@@ -322,6 +519,10 @@ export interface NormalizedCdpNodeIdParams extends BridgeParams {
   nodeId: number;
 }
 
+export interface NormalizedCdpDomSnapshotParams extends BridgeParams {
+  computedStyles: string[];
+}
+
 export interface CheckedActionParams {
   target?: InputTarget;
   checked?: boolean;
@@ -594,10 +795,31 @@ 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;
@@ -620,22 +842,62 @@ export interface NormalizedExtractContentParams extends BridgeParams {
 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 ScreenshotResult {
-  image: string;
+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;
@@ -799,6 +1061,229 @@ export interface NetworkResult {
   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';
 
 export interface NetworkInterceptAddParams {

package/skills/browser-bridge/SKILL.md

@@ -59,11 +59,13 @@ bbx a11y-tree [maxNodes] [maxDepth]  # accessibility tree
 bbx eval [--await] <expression>      # JS eval (--await for promises, - for stdin)
 bbx console [level]                  # console output
 bbx network [limit]                  # recent fetch/XHR requests
+bbx har [options] [outPath]          # export armed CDP capture as sanitized HAR 1.2
 bbx intercept add <pattern> [--respond <body>] [--status <code>] [--block]  # intercept matching requests
 bbx intercept list|remove <id>|clear # manage interception rules
 bbx page-text [budget]               # full page text
-bbx storage [local|session] [keys]   # browser storage
-bbx perf                             # performance metrics
+bbx storage [local|session] [keys]   # storage key/presence metadata
+bbx call sensitive.read '{"source":"local_storage","key":"name"}' # deliberate exact value
+bbx perf                             # raw Chrome/CDP counter point sample
 bbx navigate <url>                   # navigate to URL
 bbx reload                           # reload current page
 bbx back                             # navigate back
@@ -145,7 +147,7 @@ After access is enabled:
 | `DIALOG_ACTION_CONFLICT`  | No       | Inspect current dialog state; never auto-repeat accept/dismiss                            |
 | `TAB_MISMATCH`            | No       | Tab closed or not found - use `tabs.list` to find an available tab                        |
 | `TIMEOUT`                 | Once     | Retry once; if still failing, simplify (smaller `maxNodes`, narrower selector)            |
-| `RATE_LIMITED`            | After 2s | Back off 2 seconds, then retry                                                            |
+| `CONTENT_SCRIPT_UNAVAILABLE` | No     | Switch to a normal http(s) page in the enabled window                                    |
 | `EXTENSION_DISCONNECTED`  | After 3s | Check Chrome is running; `bbx status` to verify, then retry                               |
 | `NATIVE_HOST_UNAVAILABLE` | No       | Run `bbx doctor` to diagnose the installation                                             |
 | `INTERNAL_ERROR`          | Once     | Retry once; if persistent, check `page.get_console` for details                           |
@@ -155,6 +157,13 @@ After access is enabled:
 
 Error responses now include a machine-readable `error.recovery` field with `retry`, `retryAfterMs`, `alternativeMethod`, and `hint`.
 
+`health.ping`, `daemon.metrics`, and `bbx doctor` also expose process-local
+five-minute recovery summaries for six fixed, content-free categories. Three
+failures in the same hidden group within 60 seconds marks an active loop. Stop
+repeating the action and follow Doctor's fixed category guidance. Extension
+summaries reset on service-worker restart and daemon summaries on daemon restart;
+they contain no page data, URLs, selectors, payloads, errors, or group names.
+
 ## Core Rules
 
 1. **Work in existing tabs** - Never create new tabs unless the user explicitly asks for it, or the task absolutely requires a fresh page (e.g., testing a clean state, comparing across URLs). Prefer `tabs.list` to find an appropriate existing tab.
@@ -168,7 +177,8 @@ Error responses now include a machine-readable `error.recovery` field with `retr
 9. **Batch reads** - combine independent reads with `bbx batch` in CLI mode or `browser_batch` in MCP mode; do not pass `batch` as a `browser_call` method.
 10. **Avoid debugger first** - prefer DOM/content-script methods (`dom.*`, `styles.*`, `layout.get_box_model`, `page.get_console`, `page.get_text`, `page.get_storage`, `page.get_network`) before any debugger-backed method. Escalate to CDP only when those cannot answer the question.
 11. **Evaluate only when needed** - `page.evaluate` is powerful but debugger-backed; use it only when DOM, storage, console, network, or text reads cannot expose the needed state.
-12. **Debugger-backed methods are last resort** - treat `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, `page.get_network` with `source: 'cdp'`, input with `executionMode: 'cdp'`, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and all `cdp.*` methods as escalation steps because they attach `chrome.debugger`.
+12. **Treat exact storage as sensitive** - use `page.get_storage` for metadata first. Call `sensitive.read` for one exact key only when necessary; never batch or automatically retry it, and never repeat a failed attempt without new evidence.
+12. **Debugger-backed methods are last resort** - treat `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, `page.get_network` with `source: 'cdp'`, input with `executionMode: 'cdp'`, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and all `cdp.*` methods as escalation steps because they attach `chrome.debugger`. `performance.get_metrics` is a raw browser-maintained CDP counter point sample, not Web Vitals.
 13. **Wait after change** - after editing source, wait for expected new text, a selector matching the changed attribute, or a detach/attach remount; waiting for `attached` on a selector that already exists does not prove HMR ran. Use `page.wait_for_load_state` for navigation, not HMR.
 14. **Prime event buffers** - before reproducing a console or fetch/XHR issue, call `page.get_console` and default `page.get_network` once with `clear: true`; then reproduce and read without clearing. CDP all-resource capture instead requires explicit `start`, reproduce, `read`, and `stop` calls.
 15. **Semantic finding** - use `dom.find_by_text` / `dom.find_by_role` when you know the label but not the selector.
@@ -180,6 +190,8 @@ Error responses now include a machine-readable `error.recovery` field with `retr
 21. **Do not guess input targets** - for targeted click, focus, type, fill, press-key, checked-state, option-selection, hover, and drag calls, honor actionability errors and returned `resolution` metadata. `cdp_press_key` and `scroll_into_view` use separate contracts. `executionMode` is only `dom` or `cdp`; `input.fill.mode: auto` is a separate DOM setter/keystroke strategy.
 22. **Stale recovery stays opt-in** - prefer re-querying. Use `recoverStale: true` once only when the same document/URL and a strong unique semantic descriptor should still identify the target; inspect `recovered`, old/new refs, and matched fields. A scan with more than 100 same-tag candidates fails as `ELEMENT_AMBIGUOUS`/`scan_incomplete` because uniqueness is not provable.
 23. **Dialogs are explicit** - inspect first, then accept or dismiss only when intended. `expectedDialogId` is a pre-dispatch stale-decision check, not an atomic CDP binding; never auto-repeat `DIALOG_ACTION_CONFLICT`.
+24. **DOM diffs use explicit baselines** - call `dom.baseline.create` before the action, `dom.baseline.compare` afterward, then `dom.baseline.release`. Use a narrow selector and bounded evidence. Never substitute unrelated DOM reads for the retained baseline, and recreate it after `DOM_BASELINE_INVALIDATED`.
+25. **HAR export reads an armed capture** - use CDP capture `start`, reproduce, `network.export_har`/`bbx har`, then `stop`. Export never starts, stops, or clears capture. Inspect truncation plus `dropped`, `abandoned`, and `inflight` before claiming completeness.
 
 ## Token Budget Quick Rules
 
@@ -251,12 +263,12 @@ bbx page-text 2000                                  # extract page content
 | Find        | `dom.find_by_text`, `dom.find_by_role`, `dom.wait_for`, `dom.get_accessibility_tree`                                                                |
 | Page State  | `page.get_console`, `page.get_storage`, `page.get_text`, `page.wait_for_load_state`, `page.evaluate` (debugger-backed)                              |
 | Dialogs     | `page.handle_dialog` (debugger-backed; explicit inspect/accept/dismiss only)                                                                  |
-| Network     | `page.get_network` (fetch/XHR default; optional CDP lifecycle), `network.intercept.add/remove/list/clear` (debugger-backed)                         |
+| Network     | `page.get_network` (fetch/XHR default; optional CDP lifecycle), `network.export_har`, `network.intercept.add/remove/list/clear` (debugger-backed)   |
 | Interact    | `input.click`, `input.type`, `input.fill`, `input.focus`, `input.press_key`, `cdp.dispatch_key_event`, `input.hover`, `input.drag`, `input.scroll_into_view` |
 | Tabs        | `tabs.list` (preferred), `tabs.create` (avoid unless necessary), `tabs.close`, `tabs.activate`                                                      |
 | Patch       | `patch.apply_styles`, `patch.apply_dom`, `patch.rollback`                                                                                           |
 | Navigate    | `navigation.navigate`, `viewport.scroll`, `viewport.resize`                                                                                         |
-| Performance | `performance.get_metrics` (debugger-backed)                                                                                                         |
+| Performance | `performance.get_metrics` (raw Chrome/CDP counter point sample; debugger-backed)                                                                    |
 | Escalate    | `dom.get_accessibility_tree`, `screenshot.capture_element`, `screenshot.capture_region` (tight crops only), `screenshot.capture_full_page`, `cdp.*` |
 
 ## Dev-Server Workflow (HMR-aware)
@@ -336,8 +348,9 @@ Every CLI shortcut command produces consistent `{ok, summary, evidence}` JSON. U
 - `input.drag` uses `source`, `destination`, and optional destination offsets `offsetX` / `offsetY`.
 - `executionMode` accepts `dom` or `cdp` and defaults to `dom`; CDP supports only click, hover, drag, type, and fill. `input.fill.mode` (`auto`, `setter`, `keystrokes`) is a separate DOM strategy.
 - `page.get_network` defaults to low-cost fetch/XHR instrumentation. All-resource CDP capture must be armed before the activity with `source: "cdp", capture: "start"`, read later, and explicitly stopped.
+- `network.export_har` requires that explicit capture to still be armed. Params are `limit` (1-200), sanitized-URL substring `urlPattern`, and `delivery` (`auto`, `inline`, `artifact`). Inline bounds remove whole oldest entries; export never changes capture state. `bbx har` uses the same client to download, length/SHA-256 verify, delete, validate, and atomically write artifacts locally.
 - `page.handle_dialog` mutations are not atomically bound to `expectedDialogId`; treat `commandDispatched` as dispatch evidence and verify follow-up state.
-- Raw `screenshot.capture_region` and `screenshot.capture_full_page` return base64 JSON; prefer `bbx screenshot <ref> [outPath]` when one element is enough.
+- Raw screenshot calls default to inline base64. Use `delivery: "auto"` for size-aware artifact fallback, or explicit `inline` when MCP image content is required; prefer `bbx screenshot <ref> [outPath]` when one element is enough because the CLI downloads and verifies artifacts locally.
 
 ## Response Shapes
 
@@ -360,13 +373,14 @@ Shortcut commands intentionally expose only the common case. Use `bbx call <meth
 | Computed styles  | `result.properties + elementRef` | `Computed N style(s) for ref.`                               |
 | Box model        | `result.content + border`        | `Box model: W×H at (x, y).`                                  |
 | Network          | `result.source + entries`        | `Network: N requests.`                                       |
+| HAR export       | `result.format === "har"`        | `HAR export delivered mode: N/M entries.`                    |
 | Console          | `entries` (no type field)        | `Console: N entries.`                                        |
 | Logs             | `entries[0].at + method`         | `Log: N entries.`                                            |
 | Patch apply      | `result.patchId`                 | `Patch id applied.`                                          |
 | Patch rollback   | `result.rolled_back`             | `Patch rolled back.`                                         |
 | Patch list       | `result.patches`                 | `N active patch(es).`                                        |
 | HTML             | `result.html`                    | `HTML fragment: N chars.`                                    |
-| Performance      | `result.metrics`                 | `Performance: N metrics collected.`                          |
+| Performance      | `result.metrics`                 | `Raw CDP performance counters: N collected; Web Vitals not measured.` |
 | Storage          | `result.type + count + entries`  | `Storage (type): N entries.`                                 |
 | Click/Focus/Type | `result.clicked/focused/typed`   | `Clicked/Focused/Typed ref.`                                 |
 | Key press        | `result.pressed`                 | `Key pressed (key).`                                         |