@browserbridge/bbx 1.7.8 → 1.9.0

package/packages/protocol/src/protocol.js

@@ -2,12 +2,15 @@
 
 import { applyBudget } from './budget.js';
 import {
+  ARTIFACT_CHUNK_BYTES,
   BUDGET_PRESETS,
   DEFAULT_A11Y_MAX_DEPTH,
   DEFAULT_A11Y_MAX_NODES,
   DEFAULT_CONSOLE_LIMIT,
   DEFAULT_DEVICE_SCALE_FACTOR,
   DEFAULT_EVAL_TIMEOUT_MS,
+  DEFAULT_EXTRACT_SETTLE_TIMEOUT_MS,
+  DEFAULT_HAR_LIMIT,
   DEFAULT_LOG_TAIL_LIMIT,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MAX_HTML_LENGTH,
@@ -20,11 +23,18 @@ import {
   DEFAULT_VIEWPORT_HEIGHT,
   DEFAULT_VIEWPORT_WIDTH,
   DEFAULT_WAIT_TIMEOUT_MS,
+  MAX_EXTRACT_SETTLE_TIMEOUT_MS,
+  MAX_ARTIFACT_BYTES,
+  MAX_HAR_ENTRIES,
+  MAX_SENSITIVE_VALUE_BYTES,
 } from './defaults.js';
 import { BridgeError, ERROR_CODES, getErrorRecovery } from './errors.js';
 import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry.js';
 
 /** @typedef {import('./types.js').AccessibilityTreeParams} AccessibilityTreeParams */
+/** @typedef {import('./types.js').ArtifactDeleteParams} ArtifactDeleteParams */
+/** @typedef {import('./types.js').ArtifactReadParams} ArtifactReadParams */
+/** @typedef {import('./types.js').AccessRequestParams} AccessRequestParams */
 /** @typedef {import('./types.js').BridgeFailureResponse} BridgeFailureResponse */
 /** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
@@ -32,32 +42,48 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').BridgeSuccessResponse} BridgeSuccessResponse */
 /** @typedef {import('./types.js').CheckedActionParams} CheckedActionParams */
 /** @typedef {import('./types.js').CdpDispatchKeyEventParams} CdpDispatchKeyEventParams */
+/** @typedef {import('./types.js').CdpDomSnapshotParams} CdpDomSnapshotParams */
 /** @typedef {import('./types.js').CdpNodeIdParams} CdpNodeIdParams */
 /** @typedef {import('./types.js').ConsoleParams} ConsoleParams */
 /** @typedef {import('./types.js').DomQueryParams} DomQueryParams */
+/** @typedef {import('./types.js').DomBaselineCreateParams} DomBaselineCreateParams */
+/** @typedef {import('./types.js').DomBaselineCompareParams} DomBaselineCompareParams */
+/** @typedef {import('./types.js').DomBaselineHandleParams} DomBaselineHandleParams */
 /** @typedef {import('./types.js').DragParams} DragParams */
 /** @typedef {import('./types.js').EvaluateParams} EvaluateParams */
+/** @typedef {import('./types.js').ExtractContentParams} ExtractContentParams */
 /** @typedef {import('./types.js').FindByRoleParams} FindByRoleParams */
 /** @typedef {import('./types.js').FindByTextParams} FindByTextParams */
 /** @typedef {import('./types.js').GetHtmlParams} GetHtmlParams */
 /** @typedef {import('./types.js').HoverParams} HoverParams */
+/** @typedef {import('./types.js').HarExportParams} HarExportParams */
+/** @typedef {import('./types.js').HandleDialogParams} HandleDialogParams */
 /** @typedef {import('./types.js').InputActionParams} InputActionParams */
 /** @typedef {import('./types.js').LogTailParams} LogTailParams */
 /** @typedef {import('./types.js').NavigationActionParams} NavigationActionParams */
 /** @typedef {import('./types.js').NetworkInterceptAddParams} NetworkInterceptAddParams */
 /** @typedef {import('./types.js').NetworkParams} NetworkParams */
 /** @typedef {import('./types.js').NormalizedAccessibilityTreeParams} NormalizedAccessibilityTreeParams */
+/** @typedef {import('./types.js').NormalizedArtifactReadParams} NormalizedArtifactReadParams */
+/** @typedef {import('./types.js').NormalizedAccessRequestParams} NormalizedAccessRequestParams */
 /** @typedef {import('./types.js').NormalizedCheckedAction} NormalizedCheckedAction */
 /** @typedef {import('./types.js').NormalizedCdpDispatchKeyEventParams} NormalizedCdpDispatchKeyEventParams */
+/** @typedef {import('./types.js').NormalizedCdpDomSnapshotParams} NormalizedCdpDomSnapshotParams */
 /** @typedef {import('./types.js').NormalizedCdpNodeIdParams} NormalizedCdpNodeIdParams */
 /** @typedef {import('./types.js').NormalizedConsoleParams} NormalizedConsoleParams */
 /** @typedef {import('./types.js').NormalizedDomQuery} NormalizedDomQuery */
+/** @typedef {import('./types.js').NormalizedDomBaselineCreateParams} NormalizedDomBaselineCreateParams */
+/** @typedef {import('./types.js').NormalizedDomBaselineCompareParams} NormalizedDomBaselineCompareParams */
+/** @typedef {import('./types.js').NormalizedDomBaselineHandleParams} NormalizedDomBaselineHandleParams */
 /** @typedef {import('./types.js').NormalizedDragParams} NormalizedDragParams */
 /** @typedef {import('./types.js').NormalizedEvaluateParams} NormalizedEvaluateParams */
+/** @typedef {import('./types.js').NormalizedExtractContentParams} NormalizedExtractContentParams */
 /** @typedef {import('./types.js').NormalizedFindByRoleParams} NormalizedFindByRoleParams */
 /** @typedef {import('./types.js').NormalizedFindByTextParams} NormalizedFindByTextParams */
 /** @typedef {import('./types.js').NormalizedGetHtmlParams} NormalizedGetHtmlParams */
 /** @typedef {import('./types.js').NormalizedHoverParams} NormalizedHoverParams */
+/** @typedef {import('./types.js').NormalizedHarExportParams} NormalizedHarExportParams */
+/** @typedef {import('./types.js').NormalizedHandleDialogParams} NormalizedHandleDialogParams */
 /** @typedef {import('./types.js').NormalizedInputAction} NormalizedInputAction */
 /** @typedef {import('./types.js').NormalizedLogTailParams} NormalizedLogTailParams */
 /** @typedef {import('./types.js').NormalizedNavigationAction} NormalizedNavigationAction */
@@ -66,7 +92,9 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').NormalizedPageTextParams} NormalizedPageTextParams */
 /** @typedef {import('./types.js').NormalizedPatchOperation} NormalizedPatchOperation */
 /** @typedef {import('./types.js').NormalizedSelectAction} NormalizedSelectAction */
+/** @typedef {import('./types.js').NormalizedScreenshotParams} NormalizedScreenshotParams */
 /** @typedef {import('./types.js').NormalizedStorageParams} NormalizedStorageParams */
+/** @typedef {import('./types.js').NormalizedSensitiveReadParams} NormalizedSensitiveReadParams */
 /** @typedef {import('./types.js').NormalizedStyleQuery} NormalizedStyleQuery */
 /** @typedef {import('./types.js').NormalizedTabCloseParams} NormalizedTabCloseParams */
 /** @typedef {import('./types.js').NormalizedTabCreateParams} NormalizedTabCreateParams */
@@ -77,7 +105,9 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').PageTextParams} PageTextParams */
 /** @typedef {import('./types.js').PatchOperationParams} PatchOperationParams */
 /** @typedef {import('./types.js').SelectActionParams} SelectActionParams */
+/** @typedef {import('./types.js').ScreenshotParams} ScreenshotParams */
 /** @typedef {import('./types.js').StorageParams} StorageParams */
+/** @typedef {import('./types.js').SensitiveReadParams} SensitiveReadParams */
 /** @typedef {import('./types.js').StyleQueryParams} StyleQueryParams */
 /** @typedef {import('./types.js').TabCloseParams} TabCloseParams */
 /** @typedef {import('./types.js').TabCreateParams} TabCreateParams */
@@ -234,6 +264,14 @@ export function createSuccess(id, result, meta = {}) {
  */
 export function createFailure(id, code, message, details = null, meta = {}) {
   const recovery = getErrorRecovery(code);
+  const effectiveRecovery =
+    recovery && meta.method === 'sensitive.read'
+      ? {
+          retry: false,
+          ...(recovery.alternativeMethod ? { alternativeMethod: recovery.alternativeMethod } : {}),
+          hint: `Sensitive reads are never retried automatically. ${recovery.hint}`,
+        }
+      : recovery;
   return {
     id,
     ok: false,
@@ -242,7 +280,7 @@ export function createFailure(id, code, message, details = null, meta = {}) {
       code,
       message,
       details,
-      ...(recovery && { recovery }),
+      ...(effectiveRecovery && { recovery: effectiveRecovery }),
     },
     meta: {
       protocol_version: getProtocolVersion(),
@@ -334,10 +372,28 @@ export function validateBridgeRequest(request) {
         typeof meta.protocol_version === 'string' ? meta.protocol_version : getProtocolVersion(),
       token_budget: typeof meta.token_budget === 'number' ? meta.token_budget : null,
       source: meta.source === 'cli' || meta.source === 'mcp' ? meta.source : undefined,
+      automatic_retry: normalizeAutomaticRetryMeta(meta.source, meta.automatic_retry),
     },
   };
 }
 
+/**
+ * @param {unknown} source
+ * @param {unknown} value
+ * @returns {{ attempt: 2, reason: 'retryable_error' } | undefined}
+ */
+function normalizeAutomaticRetryMeta(source, value) {
+  if (source !== 'mcp' || !isPlainRecord(value)) return undefined;
+  const keys = Object.keys(value).sort();
+  return keys.length === 2 &&
+    keys[0] === 'attempt' &&
+    keys[1] === 'reason' &&
+    value.attempt === 2 &&
+    value.reason === 'retryable_error'
+    ? { attempt: 2, reason: 'retryable_error' }
+    : undefined;
+}
+
 /**
  * Normalize request params early so malformed payloads fail at the shared
  * protocol boundary before daemon or extension dispatch.
@@ -348,22 +404,39 @@ export function validateBridgeRequest(request) {
  */
 function normalizeRequestParams(method, params) {
   switch (method) {
+    case 'access.request':
+      return normalizeAccessRequestParams(params);
     case 'log.tail':
       return normalizeLogTailParams(params);
     case 'dom.query':
       return normalizeDomQuery(params);
+    case 'dom.baseline.create':
+      return normalizeDomBaselineCreateParams(params);
+    case 'dom.baseline.compare':
+      return normalizeDomBaselineCompareParams(params);
+    case 'dom.baseline.describe':
+    case 'dom.baseline.release':
+      return normalizeDomBaselineHandleParams(params);
     case 'page.evaluate':
       return normalizeEvaluateParams(params);
     case 'page.get_console':
       return normalizeConsoleParams(params);
+    case 'page.handle_dialog':
+      return normalizeHandleDialogParams(params);
     case 'page.wait_for_load_state':
       return normalizeWaitForLoadStateParams(params);
     case 'page.get_storage':
       return normalizeStorageParams(params);
+    case 'sensitive.read':
+      return normalizeSensitiveReadParams(params);
     case 'page.get_text':
       return normalizePageTextParams(params);
+    case 'page.extract_content':
+      return normalizeExtractContentParams(params);
     case 'page.get_network':
       return normalizeNetworkParams(params);
+    case 'network.export_har':
+      return normalizeHarExportParams(params);
     case 'network.intercept.add':
       return normalizeNetworkInterceptAddParams(params);
     case 'navigation.navigate':
@@ -399,6 +472,8 @@ function normalizeRequestParams(method, params) {
     case 'cdp.get_box_model':
     case 'cdp.get_computed_styles_for_node':
       return normalizeCdpNodeIdParams(params);
+    case 'cdp.get_dom_snapshot':
+      return normalizeCdpDomSnapshotParams(params);
     case 'input.set_checked':
       return normalizeCheckedAction(params);
     case 'input.select_option':
@@ -407,6 +482,19 @@ function normalizeRequestParams(method, params) {
       return normalizeHoverParams(params);
     case 'input.drag':
       return normalizeDragParams(params);
+    case 'screenshot.capture_region':
+      return { ...params, ...normalizeScreenshotParams(params) };
+    case 'screenshot.capture_element':
+    case 'screenshot.capture_full_page':
+      return {
+        ...params,
+        ...normalizeScreenshotParams(params),
+        ...(params.scale === undefined ? { scale: undefined } : {}),
+      };
+    case 'artifact.read':
+      return normalizeArtifactReadParams(params);
+    case 'artifact.delete':
+      return normalizeArtifactDeleteParams(params);
     case 'patch.apply_styles':
     case 'patch.apply_dom':
     case 'patch.list':
@@ -422,6 +510,28 @@ function normalizeRequestParams(method, params) {
   }
 }
 
+/**
+ * @param {AccessRequestParams} [params={}]
+ * @returns {NormalizedAccessRequestParams}
+ */
+export function normalizeAccessRequestParams(params = {}) {
+  const intent = params.intent ?? 'general';
+  if (
+    intent !== 'inspect' &&
+    intent !== 'interact' &&
+    intent !== 'capture' &&
+    intent !== 'navigate' &&
+    intent !== 'debugger' &&
+    intent !== 'general'
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'intent must be one of inspect, interact, capture, navigate, debugger, or general.'
+    );
+  }
+  return { intent };
+}
+
 /**
  * Return the browser-operation timeout for methods that wait asynchronously.
  * This lets clients and the daemon keep transport deadlines outside the
@@ -442,6 +552,10 @@ export function getBridgeOperationTimeoutMs(method, params = {}) {
       return normalizeWaitForLoadStateParams(params).timeoutMs;
     case 'page.evaluate':
       return normalizeEvaluateParams(params).timeoutMs;
+    case 'page.extract_content': {
+      const normalized = normalizeExtractContentParams(params);
+      return normalized.consistency === 'settled' ? normalized.settleTimeoutMs : null;
+    }
     case 'dom.wait_for':
       return clampInt(params.timeoutMs, 100, 30_000, 5_000);
     default:
@@ -464,6 +578,82 @@ export function normalizeDomQuery(params = {}) {
   };
 }
 
+/**
+ * @param {DomBaselineCreateParams} [params={}]
+ * @returns {NormalizedDomBaselineCreateParams}
+ */
+export function normalizeDomBaselineCreateParams(params = {}) {
+  const selector = typeof params.selector === 'string' ? params.selector.trim() : '';
+  if (selector.length > 2_048) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'selector must not exceed 2,048 characters.'
+    );
+  }
+
+  const attributeAllowlist = Array.isArray(params.attributeAllowlist)
+    ? [
+        ...new Set(
+          params.attributeAllowlist
+            .filter((name) => typeof name === 'string')
+            .map((name) => name.trim().toLowerCase())
+            .filter(
+              (name) =>
+                name.length > 0 &&
+                name.length <= 128 &&
+                name !== 'value' &&
+                !name.startsWith('on') &&
+                /^[a-z_][a-z0-9_.:-]*$/u.test(name)
+            )
+        ),
+      ]
+    : [];
+  if (attributeAllowlist.length > 16) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'attributeAllowlist must contain at most 16 unique attribute names.'
+    );
+  }
+
+  return {
+    selector: selector || 'body',
+    maxNodes: clampInt(params.maxNodes, 1, 1_000, 100),
+    maxDepth: clampInt(params.maxDepth, 1, 20, 8),
+    textBudget: clampInt(params.textBudget, 32, 1_000, 160),
+    attributeAllowlist,
+  };
+}
+
+/**
+ * @param {DomBaselineCompareParams} [params={}]
+ * @returns {NormalizedDomBaselineCompareParams}
+ */
+export function normalizeDomBaselineCompareParams(params = {}) {
+  return {
+    baselineId: normalizeDomBaselineId(params.baselineId),
+    maxChanges: clampInt(params.maxChanges, 1, 200, 50),
+  };
+}
+
+/**
+ * @param {DomBaselineHandleParams} [params={}]
+ * @returns {NormalizedDomBaselineHandleParams}
+ */
+export function normalizeDomBaselineHandleParams(params = {}) {
+  return { baselineId: normalizeDomBaselineId(params.baselineId) };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normalizeDomBaselineId(value) {
+  if (typeof value !== 'string' || !/^baseline_[A-Za-z0-9_-]{32,64}$/u.test(value)) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'baselineId is invalid.');
+  }
+  return value;
+}
+
 /**
  * @param {StyleQueryParams} [params={}]
  * @returns {NormalizedStyleQuery}
@@ -499,6 +689,17 @@ function normalizeTarget(target) {
   };
 }
 
+/**
+ * @param {unknown} value
+ * @returns {import('./types.js').InputExecutionMode}
+ */
+function normalizeInputExecutionMode(value) {
+  if (value !== undefined && value !== 'dom' && value !== 'cdp') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'executionMode must be either dom or cdp.');
+  }
+  return value === 'cdp' ? 'cdp' : 'dom';
+}
+
 /**
  * @param {InputActionParams} [params={}]
  * @returns {NormalizedInputAction}
@@ -527,6 +728,8 @@ export function normalizeInputAction(params = {}) {
     modifiers: Array.isArray(params.modifiers)
       ? params.modifiers.filter((modifier) => typeof modifier === 'string' && modifier.trim())
       : [],
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -592,6 +795,25 @@ export function normalizeCdpNodeIdParams(params = {}) {
   };
 }
 
+/**
+ * @param {CdpDomSnapshotParams} [params={}]
+ * @returns {NormalizedCdpDomSnapshotParams}
+ */
+export function normalizeCdpDomSnapshotParams(params = {}) {
+  const computedStyles = Array.isArray(params.computedStyles)
+    ? params.computedStyles.filter(
+        (property) => typeof property === 'string' && property.length > 0 && property.length <= 128
+      )
+    : [];
+  if (computedStyles.length > 100) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'computedStyles must contain at most 100 CSS property names.'
+    );
+  }
+  return { computedStyles };
+}
+
 /**
  * @param {CheckedActionParams} [params={}]
  * @returns {NormalizedCheckedAction}
@@ -604,6 +826,8 @@ export function normalizeCheckedAction(params = {}) {
         : undefined
     ),
     checked: params.checked !== false,
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -629,6 +853,8 @@ export function normalizeSelectAction(params = {}) {
           .map((index) => Number(index))
           .filter((index) => Number.isInteger(index) && index >= 0)
       : [],
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -682,13 +908,30 @@ export function normalizeNavigationAction(params = {}) {
  * @returns {NormalizedPatchOperation}
  */
 export function normalizePatchOperation(params = {}) {
+  const operation = typeof params.operation === 'string' ? params.operation : null;
+  if (
+    operation !== null &&
+    ![
+      'set_text',
+      'set_attribute',
+      'remove_attribute',
+      'add_class',
+      'remove_class',
+      'toggle_class',
+    ].includes(operation)
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      `Unsupported DOM patch operation: ${operation}`
+    );
+  }
   return {
     patchId: typeof params.patchId === 'string' ? params.patchId : null,
     target:
       params.target && typeof params.target === 'object'
         ? /** @type {Record<string, unknown>} */ (params.target)
         : {},
-    operation: typeof params.operation === 'string' ? params.operation : null,
+    operation,
     name: typeof params.name === 'string' ? params.name : null,
     declarations:
       params.declarations && typeof params.declarations === 'object'
@@ -739,6 +982,62 @@ export function normalizeConsoleParams(params = {}) {
   };
 }
 
+/**
+ * @param {HandleDialogParams} [params={}]
+ * @returns {NormalizedHandleDialogParams}
+ */
+export function normalizeHandleDialogParams(params = {}) {
+  const action = params.action ?? 'inspect';
+  if (action !== 'inspect' && action !== 'accept' && action !== 'dismiss') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'action must be one of inspect, accept, or dismiss.'
+    );
+  }
+  if (
+    params.promptText !== undefined &&
+    params.promptText !== null &&
+    typeof params.promptText !== 'string'
+  ) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'promptText must be a string.');
+  }
+  if (typeof params.promptText === 'string' && params.promptText.length > 10_000) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'promptText must not exceed 10,000 characters.'
+    );
+  }
+  if (params.promptText !== undefined && params.promptText !== null && action !== 'accept') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'promptText is only valid when action is accept.'
+    );
+  }
+  if (
+    params.expectedDialogId !== undefined &&
+    params.expectedDialogId !== null &&
+    (typeof params.expectedDialogId !== 'string' ||
+      params.expectedDialogId.length === 0 ||
+      params.expectedDialogId.length > 128)
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'expectedDialogId must be a non-empty string of at most 128 characters.'
+    );
+  }
+  if (action === 'inspect' && params.expectedDialogId != null) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'expectedDialogId is only valid when action is accept or dismiss.'
+    );
+  }
+  return {
+    action,
+    promptText: typeof params.promptText === 'string' ? params.promptText : null,
+    expectedDialogId: typeof params.expectedDialogId === 'string' ? params.expectedDialogId : null,
+  };
+}
+
 /**
  * @param {WaitForParams} [params={}]
  * @returns {NormalizedWaitForParams}
@@ -823,6 +1122,8 @@ export function normalizeHoverParams(params = {}) {
     modifiers: Array.isArray(params.modifiers)
       ? params.modifiers.filter((modifier) => typeof modifier === 'string' && modifier.trim())
       : [],
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -844,6 +1145,8 @@ export function normalizeDragParams(params = {}) {
     ),
     offsetX: Number.isFinite(Number(params.offsetX)) ? Number(params.offsetX) : 0,
     offsetY: Number.isFinite(Number(params.offsetY)) ? Number(params.offsetY) : 0,
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
   };
 }
 
@@ -852,9 +1155,42 @@ export function normalizeDragParams(params = {}) {
  * @returns {NormalizedStorageParams}
  */
 export function normalizeStorageParams(params = {}) {
+  const keys = Array.isArray(params.keys)
+    ? params.keys.filter((key) => typeof key === 'string')
+    : null;
+  if (keys && keys.length > 100) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'keys must contain at most 100 strings.');
+  }
   return {
     type: params.type === 'session' ? 'session' : 'local',
-    keys: Array.isArray(params.keys) ? params.keys.filter((k) => typeof k === 'string') : null,
+    keys,
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} params
+ * @returns {NormalizedSensitiveReadParams}
+ */
+export function normalizeSensitiveReadParams(params) {
+  if (params?.source !== 'local_storage' && params?.source !== 'session_storage') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'source must be local_storage or session_storage.'
+    );
+  }
+  if (typeof params.key !== 'string') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'key must be a string.');
+  }
+  if (params.key.length > 2_048) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'key must contain at most 2,048 characters.'
+    );
+  }
+  return {
+    source: params.source,
+    key: params.key,
+    maxBytes: MAX_SENSITIVE_VALUE_BYTES,
   };
 }
 
@@ -863,12 +1199,98 @@ export function normalizeStorageParams(params = {}) {
  * @returns {NormalizedWaitForLoadStateParams}
  */
 export function normalizeWaitForLoadStateParams(params = {}) {
+  const url = typeof params.url === 'string' && params.url.length > 0 ? params.url : null;
+  const requestedMatch = params.urlMatch ?? (url ? 'exact' : null);
+  if (params.url !== undefined && params.url !== null && typeof params.url !== 'string') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'url must be a string.');
+  }
+  if (params.urlMatch !== undefined && params.urlMatch !== null && !url) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'url is required when urlMatch is set.');
+  }
+  if (
+    requestedMatch !== null &&
+    requestedMatch !== 'exact' &&
+    requestedMatch !== 'contains' &&
+    requestedMatch !== 'regex'
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'urlMatch must be one of exact, contains, or regex.'
+    );
+  }
+  if (url && url.length > 2_048) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'url condition must not exceed 2,048 characters.'
+    );
+  }
+  if (requestedMatch === 'regex' && url) {
+    validateSafeUrlRegex(url);
+  }
   return {
     waitForLoad: params.waitForLoad !== false,
     timeoutMs: clampInt(params.timeoutMs, 500, 120_000, DEFAULT_NAV_TIMEOUT_MS),
+    url,
+    urlMatch: requestedMatch,
   };
 }
 
+/**
+ * URL waits accept a deliberately linear regular-expression subset. Patterns
+ * may contain literals, escapes, anchors, dots, and character classes, but no
+ * grouping, alternation, or quantifiers. With both pattern and input bounded,
+ * the accepted subset cannot trigger backtracking through repeated matches.
+ *
+ * @param {string} pattern
+ * @returns {void}
+ */
+function validateSafeUrlRegex(pattern) {
+  if (pattern.length > 256) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'Regex URL condition must not exceed 256 characters.'
+    );
+  }
+  let escaped = false;
+  let inCharacterClass = false;
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (escaped) {
+      if (!inCharacterClass && /[1-9]/.test(character)) {
+        throw new BridgeError(
+          ERROR_CODES.INVALID_REQUEST,
+          'Regex URL condition uses an unsupported backreference.'
+        );
+      }
+      escaped = false;
+      continue;
+    }
+    if (character === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (character === '[' && !inCharacterClass) {
+      inCharacterClass = true;
+      continue;
+    }
+    if (character === ']' && inCharacterClass) {
+      inCharacterClass = false;
+      continue;
+    }
+    if (!inCharacterClass && '(){}*+?|'.includes(character)) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        'Regex URL condition uses unsupported grouping, alternation, or quantifiers.'
+      );
+    }
+  }
+  try {
+    new RegExp(pattern);
+  } catch {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Regex URL condition is invalid.');
+  }
+}
+
 /**
  * @param {TabCreateParams} [params={}]
  * @returns {NormalizedTabCreateParams}
@@ -914,16 +1336,95 @@ export function normalizeTabCloseParams(params = {}) {
  */
 export function normalizeAccessibilityTreeParams(params = {}) {
   return {
+    selector:
+      typeof params.selector === 'string' && params.selector.trim() ? params.selector.trim() : null,
     maxDepth: clampInt(params.maxDepth, 1, 20, DEFAULT_A11Y_MAX_DEPTH),
     maxNodes: clampInt(params.maxNodes, 10, 5000, DEFAULT_A11Y_MAX_NODES),
+    compact: params.compact === true,
+    interactiveOnly: params.interactiveOnly === true,
   };
 }
 
+/**
+ * @param {ScreenshotParams} [params={}]
+ * @returns {NormalizedScreenshotParams}
+ */
+export function normalizeScreenshotParams(params = {}) {
+  const format = params.format ?? 'png';
+  if (format !== 'png' && format !== 'jpeg' && format !== 'webp') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'format must be png, jpeg, or webp.');
+  }
+  const numericQuality = Number(params.quality);
+  const delivery = params.delivery ?? 'inline';
+  if (delivery !== 'auto' && delivery !== 'inline' && delivery !== 'artifact') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'delivery must be auto, inline, or artifact.'
+    );
+  }
+  return {
+    format,
+    quality:
+      format === 'png' || params.quality === undefined
+        ? null
+        : Number.isFinite(numericQuality)
+          ? Math.min(100, Math.max(0, Math.trunc(numericQuality)))
+          : 80,
+    delivery,
+    scale:
+      Number.isFinite(Number(params.scale)) && Number(params.scale) > 0
+        ? clampNumber(Number(params.scale), 0.1, 4, 1)
+        : 1,
+  };
+}
+
+/**
+ * @param {ArtifactReadParams} [params={}]
+ * @returns {NormalizedArtifactReadParams}
+ */
+export function normalizeArtifactReadParams(params = {}) {
+  return {
+    artifactId: normalizeArtifactId(params.artifactId),
+    offset: clampInt(params.offset, 0, MAX_ARTIFACT_BYTES, 0),
+    maxBytes: clampInt(params.maxBytes, 1, ARTIFACT_CHUNK_BYTES, ARTIFACT_CHUNK_BYTES),
+  };
+}
+
+/**
+ * @param {ArtifactDeleteParams} [params={}]
+ * @returns {{ artifactId: string }}
+ */
+export function normalizeArtifactDeleteParams(params = {}) {
+  return { artifactId: normalizeArtifactId(params.artifactId) };
+}
+
+/** @param {unknown} value */
+function normalizeArtifactId(value) {
+  if (typeof value !== 'string' || !/^art_[A-Za-z0-9_-]{32,64}$/u.test(value)) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'artifactId is invalid.');
+  }
+  return value;
+}
+
 /**
  * @param {NetworkParams} [params={}]
  * @returns {NormalizedNetworkParams}
  */
 export function normalizeNetworkParams(params = {}) {
+  const source = params.source ?? 'fetch-xhr';
+  if (source !== 'fetch-xhr' && source !== 'cdp') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'source must be fetch-xhr or cdp.');
+  }
+  const capture = params.capture ?? 'read';
+  if (capture !== 'read' && capture !== 'start' && capture !== 'clear' && capture !== 'stop') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'capture must be read, start, clear, or stop.'
+    );
+  }
+  if (source !== 'cdp' && params.capture !== undefined && params.capture !== 'read') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'capture is only valid with source "cdp".');
+  }
   return {
     clear: Boolean(params.clear),
     limit: clampInt(params.limit, 1, 500, DEFAULT_NETWORK_LIMIT),
@@ -931,6 +1432,56 @@ export function normalizeNetworkParams(params = {}) {
       typeof params.urlPattern === 'string' && params.urlPattern.trim()
         ? params.urlPattern.trim()
         : null,
+    source,
+    capture,
+  };
+}
+
+/**
+ * @param {HarExportParams | NormalizedHarExportParams} [params={}]
+ * @returns {NormalizedHarExportParams}
+ */
+export function normalizeHarExportParams(params = {}) {
+  if (
+    params.limit !== undefined &&
+    (typeof params.limit !== 'number' ||
+      !Number.isSafeInteger(params.limit) ||
+      params.limit < 1 ||
+      params.limit > MAX_HAR_ENTRIES)
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      `limit must be an integer between 1 and ${MAX_HAR_ENTRIES}.`
+    );
+  }
+
+  if (
+    params.urlPattern !== undefined &&
+    params.urlPattern !== null &&
+    typeof params.urlPattern !== 'string'
+  ) {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'urlPattern must be a string.');
+  }
+  const urlPattern = params.urlPattern?.trim() || null;
+  if (urlPattern && urlPattern.length > 2_048) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'urlPattern must contain at most 2048 characters.'
+    );
+  }
+
+  const delivery = params.delivery ?? 'auto';
+  if (delivery !== 'auto' && delivery !== 'inline' && delivery !== 'artifact') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'delivery must be auto, inline, or artifact.'
+    );
+  }
+
+  return {
+    limit: params.limit ?? DEFAULT_HAR_LIMIT,
+    urlPattern,
+    delivery,
   };
 }
 
@@ -1009,6 +1560,44 @@ export function normalizePageTextParams(params = {}) {
   };
 }
 
+/**
+ * @param {ExtractContentParams} [params={}]
+ * @returns {NormalizedExtractContentParams}
+ */
+export function normalizeExtractContentParams(params = {}) {
+  const format = params.format ?? 'text';
+  if (format !== 'text' && format !== 'markdown') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'format must be text or markdown.');
+  }
+  const consistency = params.consistency ?? 'best_effort';
+  if (consistency !== 'best_effort' && consistency !== 'settled') {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'consistency must be best_effort or settled.'
+    );
+  }
+  const selector = typeof params.selector === 'string' ? params.selector.trim() : '';
+  if (selector.length > 2048) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'selector must not exceed 2,048 characters.'
+    );
+  }
+  return {
+    format,
+    selector: selector || null,
+    includeMetadata: params.includeMetadata !== false,
+    consistency,
+    textBudget: clampInt(params.textBudget, 100, 100_000, DEFAULT_PAGE_TEXT_BUDGET),
+    settleTimeoutMs: clampInt(
+      params.settleTimeoutMs,
+      100,
+      MAX_EXTRACT_SETTLE_TIMEOUT_MS,
+      DEFAULT_EXTRACT_SETTLE_TIMEOUT_MS
+    ),
+  };
+}
+
 /**
  * @param {LogTailParams} [params={}]
  * @returns {NormalizedLogTailParams}
@@ -1071,9 +1660,20 @@ export function createRuntimeContext() {
         'Browser Bridge is off for this window or the page is restricted; if access is off, the first denied call surfaces an Enable cue in the extension UI',
       TAB_MISMATCH: 'Tab closed or not found',
       ELEMENT_STALE: 'Element removed from DOM - re-query',
+      ELEMENT_AMBIGUOUS: 'Input selector matched equally actionable elements - narrow selector',
+      ELEMENT_NOT_ACTIONABLE: 'Input target is hidden, disabled, inert, or not rendered',
+      ELEMENT_OBSCURED: 'Pointer target is blocked by an unrelated element',
+      ELEMENT_NOT_FOUND: 'Input selector did not match an element',
+      DOM_BASELINE_NOT_FOUND: 'DOM baseline is missing, expired, or released',
+      DOM_BASELINE_INVALIDATED: 'DOM baseline belongs to a different document or scope',
+      DOM_BASELINE_QUOTA_EXCEEDED: 'DOM baseline retention quota was exceeded',
+      INPUT_UNSUPPORTED: 'Execution mode does not support this input operation',
+      INPUT_INVALID_TARGET: 'Input target is incompatible with the requested operation',
+      INPUT_FOCUS_CHANGED: 'Focus moved before native text dispatch',
+      DIALOG_NOT_OPEN: 'No JavaScript dialog is currently observable',
       INVALID_REQUEST: 'Malformed method or params',
       TIMEOUT: 'Operation exceeded time limit',
-      RATE_LIMITED: 'Too many requests - back off',
+      CONTENT_SCRIPT_UNAVAILABLE: 'Page is restricted or cannot host the content script',
       INTERNAL_ERROR: 'Unexpected extension error',
       EXTENSION_DISCONNECTED: 'Extension not connected to daemon - check Chrome',
     },
@@ -1081,6 +1681,7 @@ export function createRuntimeContext() {
       'dom.query quick budget first; widen only if truncated',
       "Reuse elementRef; don't re-query",
       'Set attributeAllowlist for focused DOM reads',
+      'Use dom.baseline.create / compare for bounded semantic DOM change detection; release when done',
       'patch.apply_styles before patch.apply_dom',
       'Verify with get_box_model not screenshots',
       'batch independent reads',
@@ -1091,10 +1692,10 @@ export function createRuntimeContext() {
       'If a tab-bound call returns ACCESS_DENIED because access is off, ask the user to click Enable in the Browser Bridge popup or side panel, then retry once',
       'dom.wait_for after HMR / navigation to detect page updates',
       'page.get_console to catch runtime errors after interactions',
-      'page.get_network to inspect XHR/fetch API calls',
+      'page.get_network for fetch/XHR reads or explicit all-resource CDP capture',
       'page.get_text for full-page content extraction',
       'input.hover before screenshot to inspect hover states',
-      'performance.get_metrics for Core Web Vitals and load timing',
+      'performance.get_metrics returns raw Chrome/CDP counters whose names and units vary; it is a point sample with no BBX navigation window or LCP/CLS/INP measurement',
       'viewport.resize to test responsive layouts',
       'Prefer screenshot.capture_element, or a tight screenshot.capture_region when element capture cannot express the needed area',
       'page.get_storage reads localStorage/sessionStorage without evaluate',
@@ -1119,12 +1720,17 @@ export function createRuntimeContext() {
       maxHtmlLength: { min: 32, max: 50000, default: DEFAULT_MAX_HTML_LENGTH },
       a11yMaxNodes: { min: 10, max: 5000, default: DEFAULT_A11Y_MAX_NODES },
       networkLimit: { min: 1, max: 500, default: DEFAULT_NETWORK_LIMIT },
+      harLimit: { min: 1, max: MAX_HAR_ENTRIES, default: DEFAULT_HAR_LIMIT },
       consoleLimit: { min: 1, max: 200, default: DEFAULT_CONSOLE_LIMIT },
       pageTextBudget: {
         min: 100,
         max: 100000,
         default: DEFAULT_PAGE_TEXT_BUDGET,
       },
+      baselineMaxNodes: { min: 1, max: 1000, default: 100 },
+      baselineMaxDepth: { min: 1, max: 20, default: 8 },
+      baselineTextBudget: { min: 32, max: 1000, default: 160 },
+      baselineMaxChanges: { min: 1, max: 200, default: 50 },
     },
   };
 }