@browserbridge/bbx 1.8.0 → 1.9.0

package/packages/protocol/src/protocol.js

@@ -2,6 +2,7 @@
 
 import { applyBudget } from './budget.js';
 import {
+  ARTIFACT_CHUNK_BYTES,
   BUDGET_PRESETS,
   DEFAULT_A11Y_MAX_DEPTH,
   DEFAULT_A11Y_MAX_NODES,
@@ -9,6 +10,7 @@ import {
   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,
@@ -22,11 +24,16 @@ import {
   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 */
@@ -35,9 +42,13 @@ 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 */
@@ -45,6 +56,7 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @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 */
@@ -52,12 +64,17 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @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 */
@@ -65,6 +82,7 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @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 */
@@ -76,6 +94,7 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @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 */
@@ -88,6 +107,7 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @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 */
@@ -244,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,
@@ -252,7 +280,7 @@ export function createFailure(id, code, message, details = null, meta = {}) {
       code,
       message,
       details,
-      ...(recovery && { recovery }),
+      ...(effectiveRecovery && { recovery: effectiveRecovery }),
     },
     meta: {
       protocol_version: getProtocolVersion(),
@@ -344,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.
@@ -364,6 +410,13 @@ function normalizeRequestParams(method, params) {
       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':
@@ -374,12 +427,16 @@ function normalizeRequestParams(method, params) {
       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':
@@ -415,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':
@@ -424,9 +483,18 @@ function normalizeRequestParams(method, 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) };
+      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':
@@ -510,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}
@@ -651,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}
@@ -745,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'
@@ -975,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,
   };
 }
 
@@ -1142,6 +1355,13 @@ export function normalizeScreenshotParams(params = {}) {
     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:
@@ -1150,9 +1370,42 @@ export function normalizeScreenshotParams(params = {}) {
         : 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}
@@ -1184,6 +1437,54 @@ export function normalizeNetworkParams(params = {}) {
   };
 }
 
+/**
+ * @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,
+  };
+}
+
 /**
  * @param {NetworkInterceptAddParams} [params={}]
  * @returns {NormalizedNetworkInterceptAddParams}
@@ -1363,13 +1664,16 @@ export function createRuntimeContext() {
       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',
     },
@@ -1377,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',
@@ -1390,7 +1695,7 @@ export function createRuntimeContext() {
       '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',
@@ -1415,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 },
     },
   };
 }