@browserbridge/bbx 1.8.0 → 1.10.0

package/packages/native-host/src/dom-baseline-owners.js

@@ -0,0 +1,210 @@
+// @ts-check
+
+import { DOM_BASELINE_TTL_MS, MAX_DOM_BASELINES_GLOBAL } from '../../protocol/src/index.js';
+
+/**
+ * Ownership bookkeeping for retained semantic DOM baselines.
+ *
+ * A baseline lives in the extension's memory, but the daemon has to know which
+ * extension socket owns it so a later `compare`/`describe`/`release` is routed
+ * back to the same document, and so the state is dropped when that socket goes
+ * away. This module owns only that mapping and its expiry rules; sending the
+ * release request over the wire stays with the daemon, which owns transport.
+ *
+ * @typedef {import('./daemon.js').ClientSocket} ClientSocket
+ * @typedef {{ socket: ClientSocket, expiresAt: number }} BaselineOwner
+ */
+
+/**
+ * Baseline IDs are minted by the extension. The daemon re-validates the shape
+ * before trusting one as a map key so a malformed response cannot grow state.
+ */
+const BASELINE_ID_PATTERN = /^baseline_[A-Za-z0-9_-]{32,64}$/u;
+
+/**
+ * Expiry timestamps are allowed a small skew over the nominal TTL to absorb
+ * clock jitter between the extension and the daemon.
+ */
+const EXPIRY_SKEW_MS = 10_000;
+
+/** Cap on tracked mappings per socket, and on abandoned-create entries. */
+const MAX_OWNER_MAPPINGS = MAX_DOM_BASELINES_GLOBAL * 4;
+
+/**
+ * @param {unknown} baselineId
+ * @returns {boolean}
+ */
+export function isValidBaselineId(baselineId) {
+  return typeof baselineId === 'string' && BASELINE_ID_PATTERN.test(baselineId);
+}
+
+export class DomBaselineOwnerRegistry {
+  /**
+   * @param {{ isCurrentExtensionSocket: (socket: ClientSocket) => boolean }} options
+   */
+  constructor({ isCurrentExtensionSocket }) {
+    /** @type {Map<string, BaselineOwner>} */
+    this.owners = new Map();
+    /**
+     * Creates whose agent went away before the extension replied. The response
+     * still arrives later, and the baseline it reports has to be released.
+     * @type {Map<string, BaselineOwner>}
+     */
+    this.abandonedCreates = new Map();
+    this.isCurrentExtensionSocket = isCurrentExtensionSocket;
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this.owners.size;
+  }
+
+  /** Drop every mapping whose TTL has passed. */
+  prune() {
+    const now = Date.now();
+    for (const [baselineId, owner] of this.owners) {
+      if (owner.expiresAt <= now) this.owners.delete(baselineId);
+    }
+  }
+
+  /**
+   * Resolve the socket that owns a baseline, or null when the owner is gone,
+   * has lost access, or has been replaced by a newer socket for the same
+   * extension.
+   *
+   * @param {string} baselineId
+   * @returns {ClientSocket | null}
+   */
+  get(baselineId) {
+    this.prune();
+    const owner = this.owners.get(baselineId);
+    if (!owner || !owner.socket.__extensionId || !owner.socket.__accessEnabled) return null;
+    if (!this.isCurrentExtensionSocket(owner.socket)) {
+      this.owners.delete(baselineId);
+      return null;
+    }
+    return owner.socket;
+  }
+
+  /**
+   * Record ownership for a freshly created baseline.
+   *
+   * Returns false when the reported ID or expiry is unusable, or when another
+   * socket already claims the ID; the caller releases the orphan in that case.
+   *
+   * @param {string} baselineId
+   * @param {ClientSocket} socket
+   * @param {unknown} expiresAt
+   * @returns {boolean}
+   */
+  register(baselineId, socket, expiresAt) {
+    this.prune();
+    const parsedExpiry = typeof expiresAt === 'string' ? Date.parse(expiresAt) : Number.NaN;
+    const now = Date.now();
+    if (
+      !isValidBaselineId(baselineId) ||
+      !socket.__extensionId ||
+      !Number.isFinite(parsedExpiry) ||
+      parsedExpiry <= now ||
+      parsedExpiry > now + DOM_BASELINE_TTL_MS + EXPIRY_SKEW_MS
+    ) {
+      return false;
+    }
+    const existing = this.owners.get(baselineId);
+    if (existing && existing.socket !== socket) return false;
+    while (
+      !existing &&
+      [...this.owners.values()].filter((owner) => owner.socket === socket).length >=
+        MAX_OWNER_MAPPINGS
+    ) {
+      const oldest = [...this.owners].find(([, owner]) => owner.socket === socket);
+      if (!oldest) break;
+      this.owners.delete(oldest[0]);
+    }
+    this.owners.set(baselineId, { socket, expiresAt: parsedExpiry });
+    return true;
+  }
+
+  /**
+   * @param {string} baselineId
+   * @returns {boolean}
+   */
+  delete(baselineId) {
+    return this.owners.delete(baselineId);
+  }
+
+  /**
+   * Drop a mapping only when the given socket still owns it, so one extension
+   * cannot evict another's baseline by reporting its ID.
+   *
+   * @param {string} baselineId
+   * @param {ClientSocket} socket
+   * @returns {boolean}
+   */
+  deleteIfOwnedBy(baselineId, socket) {
+    if (this.owners.get(baselineId)?.socket !== socket) return false;
+    return this.owners.delete(baselineId);
+  }
+
+  /**
+   * Forget every baseline and abandoned create belonging to a socket.
+   *
+   * @param {ClientSocket} socket
+   */
+  clearForSocket(socket) {
+    for (const [baselineId, owner] of this.owners) {
+      if (owner.socket === socket) this.owners.delete(baselineId);
+    }
+    for (const [requestId, abandoned] of this.abandonedCreates) {
+      if (abandoned.socket === socket) this.abandonedCreates.delete(requestId);
+    }
+  }
+
+  /**
+   * Remember a `dom.baseline.create` whose agent disconnected before the
+   * extension replied, so the eventual response can be released rather than
+   * leaking a retained snapshot in the page.
+   *
+   * @param {string} requestId
+   * @param {{ method?: string, targets: Set<ClientSocket> }} pending
+   */
+  markAbandonedCreate(requestId, pending) {
+    if (pending.method !== 'dom.baseline.create') return;
+    const target = pending.targets.values().next().value;
+    if (!target) return;
+    const now = Date.now();
+    for (const [id, entry] of this.abandonedCreates) {
+      if (entry.expiresAt <= now) this.abandonedCreates.delete(id);
+    }
+    this.abandonedCreates.set(requestId, {
+      socket: target,
+      expiresAt: now + DOM_BASELINE_TTL_MS,
+    });
+    while (this.abandonedCreates.size > MAX_OWNER_MAPPINGS) {
+      const oldestId = this.abandonedCreates.keys().next().value;
+      if (typeof oldestId !== 'string') break;
+      this.abandonedCreates.delete(oldestId);
+    }
+  }
+
+  /**
+   * Claim an abandoned create for the socket that is answering it. Returns
+   * false when the request was not abandoned or belongs to another socket.
+   *
+   * @param {string} requestId
+   * @param {ClientSocket} socket
+   * @returns {boolean}
+   */
+  takeAbandonedCreate(requestId, socket) {
+    const abandoned = this.abandonedCreates.get(requestId);
+    if (abandoned?.socket !== socket) return false;
+    this.abandonedCreates.delete(requestId);
+    return true;
+  }
+
+  /** Drop all tracked state, used on daemon shutdown. */
+  clear() {
+    this.owners.clear();
+    this.abandonedCreates.clear();
+  }
+}

package/packages/native-host/src/native-host.js

@@ -2,7 +2,12 @@
 
 import net from 'node:net';
 
-import { createFailure, ERROR_CODES, MAX_JSON_LINE_BYTES } from '../../protocol/src/index.js';
+import {
+  createFailure,
+  ERROR_CODES,
+  parseJsonLines,
+  sanitizeIncidentalText,
+} from '../../protocol/src/index.js';
 import { readBridgeAuthToken } from './auth-token.js';
 import { createSocketBridgeTransport, getBridgeTransport } from './config.js';
 import { spawnBridgeDaemonProcess } from './daemon-process.js';
@@ -110,6 +115,16 @@ function isHostActivity(message) {
   );
 }
 
+/** @param {unknown} message */
+function isHostArtifactMessage(message) {
+  return Boolean(
+    message &&
+    typeof message === 'object' &&
+    typeof (/** @type {Record<string, unknown>} */ (message).type) === 'string' &&
+    String(/** @type {Record<string, unknown>} */ (message).type).startsWith('host.artifact.')
+  );
+}
+
 /**
  * @param {{ transport?: BridgeTransport, socketPath?: string }} [options={}]
  * @returns {Promise<void>}
@@ -130,7 +145,7 @@ export async function runNativeHost({
       response: createFailure(
         'native_bootstrap',
         ERROR_CODES.NATIVE_HOST_UNAVAILABLE,
-        error instanceof Error ? error.message : String(error)
+        sanitizeIncidentalText(error instanceof Error ? error.message : String(error))
       ),
     });
     return;
@@ -155,32 +170,10 @@ export async function runNativeHost({
     ...(authToken ? { authToken } : {}),
   });
 
-  let lineBuffer = '';
-  socket.on('data', (chunk) => {
-    lineBuffer += chunk;
-    if (!lineBuffer.includes('\n') && Buffer.byteLength(lineBuffer, 'utf8') > MAX_JSON_LINE_BYTES) {
-      console.error(`native-host: daemon JSON line exceeded ${MAX_JSON_LINE_BYTES} bytes`);
-      socket.destroy();
-      return;
-    }
-    while (lineBuffer.includes('\n')) {
-      const index = lineBuffer.indexOf('\n');
-      const line = lineBuffer.slice(0, index).trim();
-      lineBuffer = lineBuffer.slice(index + 1);
-      if (!line) {
-        continue;
-      }
-      if (Buffer.byteLength(line, 'utf8') > MAX_JSON_LINE_BYTES) {
-        console.error(`native-host: daemon JSON line exceeded ${MAX_JSON_LINE_BYTES} bytes`);
-        socket.destroy();
-        return;
-      }
-      let message;
-      try {
-        message = JSON.parse(line);
-      } catch {
-        continue;
-      }
+  parseJsonLines(
+    socket,
+    (raw) => {
+      const message = /** @type {Record<string, unknown>} */ (raw);
       void (async () => {
         if (message.type === 'extension.request') {
           await writeNativeMessageQueued(message.request);
@@ -213,8 +206,16 @@ export async function runNativeHost({
           err instanceof Error ? err.message : err
         );
       });
+    },
+    {
+      onProtocolError: (error) => {
+        console.error(`native-host: ${error.message}`);
+      },
+      onInvalidLine: (error) => {
+        console.error(`native-host: ignoring malformed daemon JSON line: ${error.message}`);
+      },
     }
-  });
+  );
 
   createNativeMessageReader(
     process.stdin,
@@ -257,6 +258,14 @@ export async function runNativeHost({
           });
           return;
         }
+        if (isHostArtifactMessage(message)) {
+          const record = /** @type {Record<string, unknown>} */ (message);
+          await writeJsonLine(socket, {
+            ...record,
+            type: String(record.type).replace(/^host\./u, 'extension.'),
+          });
+          return;
+        }
         await writeJsonLine(socket, {
           type: 'extension.response',
           response: message,

package/packages/protocol/src/budget-presets.js

@@ -0,0 +1,182 @@
+// @ts-check
+
+/**
+ * Shared budget-preset merge helpers. Presets fill gaps in method params;
+ * explicit per-call params always win. Used by both the MCP server and the
+ * agent CLI so `budgetPreset`/`--preset` behave identically.
+ */
+
+import {
+  DEFAULT_CONSOLE_LIMIT,
+  DEFAULT_HAR_LIMIT,
+  DEFAULT_LOG_TAIL_LIMIT,
+  DEFAULT_MAX_HTML_LENGTH,
+  DEFAULT_NETWORK_LIMIT,
+  DEFAULT_PAGE_TEXT_BUDGET,
+  getBudgetPreset,
+  isBudgetPresetName,
+} from './defaults.js';
+
+/**
+ * @param {unknown} value
+ * @returns {import('./defaults.js').BudgetPresetName | null}
+ */
+export function getBudgetPresetName(value) {
+  return isBudgetPresetName(value) ? value : null;
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, maxNodes?: unknown, maxDepth?: unknown, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyTreeBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const preset = getBudgetPreset(presetName);
+  return /** @type {T} */ ({
+    ...args,
+    maxNodes: args.maxNodes ?? preset.maxNodes,
+    maxDepth: args.maxDepth ?? preset.maxDepth,
+    textBudget: args.textBudget ?? preset.textBudget,
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyTextBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const preset = getBudgetPreset(presetName);
+  return /** @type {T} */ ({
+    ...args,
+    textBudget: args.textBudget ?? preset.textBudget,
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyPageTextBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const textBudgetByPreset = {
+    quick: 2000,
+    normal: DEFAULT_PAGE_TEXT_BUDGET,
+    deep: DEFAULT_PAGE_TEXT_BUDGET * 2,
+  };
+  return /** @type {T} */ ({
+    ...args,
+    textBudget: args.textBudget ?? textBudgetByPreset[presetName],
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, limit?: unknown }} T
+ * @param {T} args
+ * @param {{ quick: number, normal: number, deep: number }} defaults
+ * @returns {T}
+ */
+export function applyLimitBudgetPreset(args, defaults) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  return /** @type {T} */ ({
+    ...args,
+    limit: args.limit ?? defaults[presetName],
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, maxLength?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyHtmlBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const maxLengthByPreset = {
+    quick: 600,
+    normal: DEFAULT_MAX_HTML_LENGTH,
+    deep: 6000,
+  };
+  return /** @type {T} */ ({
+    ...args,
+    maxLength: args.maxLength ?? maxLengthByPreset[presetName],
+  });
+}
+
+/**
+ * Apply a preset to method parameters before dispatch. Explicit method params
+ * always win over preset defaults.
+ *
+ * @param {import('./types.js').BridgeMethod} method
+ * @param {Record<string, unknown>} params
+ * @param {unknown} budgetPreset
+ * @returns {Record<string, unknown>}
+ */
+export function applyMethodBudgetPreset(method, params, budgetPreset) {
+  const args = { ...params, budgetPreset };
+  /** @type {Record<string, unknown>} */
+  let normalized = args;
+  if (
+    method === 'dom.query' ||
+    method === 'dom.get_accessibility_tree' ||
+    method === 'dom.baseline.create'
+  ) {
+    normalized = applyTreeBudgetPreset(args);
+  } else if (method === 'dom.baseline.compare') {
+    const preset = getBudgetPresetName(budgetPreset);
+    const defaults = { quick: 10, normal: 50, deep: 100 };
+    normalized = {
+      ...args,
+      maxChanges: params.maxChanges ?? (preset ? defaults[preset] : undefined),
+    };
+  } else if (method === 'dom.get_text') {
+    normalized = applyTextBudgetPreset(args);
+  } else if (method === 'dom.get_html') {
+    normalized = applyHtmlBudgetPreset(args);
+  } else if (method === 'page.get_text' || method === 'page.extract_content') {
+    normalized = applyPageTextBudgetPreset(args);
+  } else if (method === 'page.get_console') {
+    normalized = applyLimitBudgetPreset(args, {
+      quick: 10,
+      normal: DEFAULT_CONSOLE_LIMIT,
+      deep: 100,
+    });
+  } else if (method === 'page.get_network') {
+    normalized = applyLimitBudgetPreset(args, {
+      quick: 10,
+      normal: DEFAULT_NETWORK_LIMIT,
+      deep: 100,
+    });
+  } else if (method === 'network.export_har') {
+    normalized = applyLimitBudgetPreset(args, {
+      quick: 20,
+      normal: DEFAULT_HAR_LIMIT,
+      deep: 100,
+    });
+  } else if (method === 'log.tail') {
+    normalized = applyLimitBudgetPreset(args, {
+      quick: 10,
+      normal: DEFAULT_LOG_TAIL_LIMIT,
+      deep: 100,
+    });
+  }
+  const { budgetPreset: _budgetPreset, ...methodParams } = normalized;
+  return methodParams;
+}

package/packages/protocol/src/capability-values.js

@@ -20,6 +20,7 @@ export const CAPABILITIES = Object.freeze({
   PERFORMANCE_READ: 'performance.read',
   NETWORK_READ: 'network.read',
   NETWORK_INTERCEPT: 'network.intercept',
+  SENSITIVE_READ: 'sensitive.read',
 });
 
 export const DEFAULT_CAPABILITIES = Object.freeze([
@@ -42,4 +43,5 @@ export const DEFAULT_CAPABILITIES = Object.freeze([
   CAPABILITIES.PERFORMANCE_READ,
   CAPABILITIES.NETWORK_READ,
   CAPABILITIES.NETWORK_INTERCEPT,
+  CAPABILITIES.SENSITIVE_READ,
 ]);

package/packages/protocol/src/defaults.js

@@ -21,6 +21,9 @@ export const DEFAULT_MAX_HTML_LENGTH = 2000;
 export const DEFAULT_A11Y_MAX_NODES = 500;
 export const DEFAULT_A11Y_MAX_DEPTH = 6;
 export const DEFAULT_NETWORK_LIMIT = 50;
+export const DEFAULT_HAR_LIMIT = 50;
+export const MAX_HAR_ENTRIES = 200;
+export const HAR_AUTO_INLINE_BYTES = 262_144;
 export const DEFAULT_CONSOLE_LIMIT = 50;
 export const DEFAULT_VIEWPORT_WIDTH = 1280;
 export const DEFAULT_VIEWPORT_HEIGHT = 720;
@@ -34,6 +37,31 @@ export const MAX_NATIVE_MESSAGE_BYTES = 1_048_576;
 /** Maximum size of one newline-delimited daemon socket message in bytes. */
 export const MAX_JSON_LINE_BYTES = MAX_NATIVE_MESSAGE_BYTES;
 
+/** Maximum UTF-8 size of an exact sensitive value returned atomically. */
+export const MAX_SENSITIVE_VALUE_BYTES = 262_144;
+
+/** Maximum calls accepted by any read-only batch surface. */
+export const MAX_BATCH_CALLS = 20;
+
+/** Maximum read-only batch calls executing concurrently. */
+export const MAX_BATCH_CONCURRENCY = 5;
+export const SCREENSHOT_AUTO_INLINE_BYTES = 262_144;
+export const SCREENSHOT_MAX_INLINE_BYTES = 524_288;
+export const ARTIFACT_CHUNK_BYTES = 196_608;
+export const MAX_ARTIFACT_BYTES = 33_554_432;
+export const MAX_ARTIFACT_CLIENT_BYTES = 67_108_864;
+export const MAX_ARTIFACT_TOTAL_BYTES = 268_435_456;
+export const MAX_ARTIFACTS_PER_CLIENT = 16;
+export const ARTIFACT_TTL_MS = 300_000;
+
+/** DOM baseline retention and storage limits. */
+export const DOM_BASELINE_TTL_MS = 300_000;
+export const MAX_DOM_BASELINES_PER_TAB = 8;
+export const MAX_DOM_BASELINES_GLOBAL = 32;
+export const MAX_DOM_BASELINE_BYTES_PER_TAB = 1_048_576;
+export const MAX_DOM_BASELINE_BYTES_GLOBAL = 4_194_304;
+export const MAX_DOM_BASELINE_BYTES = 262_144;
+
 /** Default timeout for a bridge request awaiting an extension response (ms). */
 export const DEFAULT_DAEMON_PENDING_TIMEOUT_MS = 30_000;
 

package/packages/protocol/src/errors.js

@@ -16,7 +16,15 @@ export const ERROR_CODES = Object.freeze({
   DIALOG_NOT_OPEN: 'DIALOG_NOT_OPEN',
   DIALOG_ACTION_CONFLICT: 'DIALOG_ACTION_CONFLICT',
   RESULT_TRUNCATED: 'RESULT_TRUNCATED',
-  RATE_LIMITED: 'RATE_LIMITED',
+  RESULT_TOO_LARGE: 'RESULT_TOO_LARGE',
+  SENSITIVE_TARGET_NOT_FOUND: 'SENSITIVE_TARGET_NOT_FOUND',
+  CONTENT_SCRIPT_UNAVAILABLE: 'CONTENT_SCRIPT_UNAVAILABLE',
+  ARTIFACT_NOT_FOUND: 'ARTIFACT_NOT_FOUND',
+  ARTIFACT_QUOTA_EXCEEDED: 'ARTIFACT_QUOTA_EXCEEDED',
+  ARTIFACT_TRANSFER_INVALID: 'ARTIFACT_TRANSFER_INVALID',
+  DOM_BASELINE_NOT_FOUND: 'DOM_BASELINE_NOT_FOUND',
+  DOM_BASELINE_INVALIDATED: 'DOM_BASELINE_INVALIDATED',
+  DOM_BASELINE_QUOTA_EXCEEDED: 'DOM_BASELINE_QUOTA_EXCEEDED',
   INTERNAL_ERROR: 'INTERNAL_ERROR',
   INVALID_REQUEST: 'INVALID_REQUEST',
   NATIVE_HOST_UNAVAILABLE: 'NATIVE_HOST_UNAVAILABLE',
@@ -38,6 +46,15 @@ export const ERROR_RECOVERY = Object.freeze({
     retry: false,
     hint: 'Result was truncated to fit the response budget. Narrow the query or raise the relevant budget if more detail is required.',
   },
+  [ERROR_CODES.RESULT_TOO_LARGE]: {
+    retry: false,
+    hint: 'The result exceeds its atomic delivery limit. For screenshots, use artifact delivery, a smaller region, lower scale, or lossy compression. For sensitive reads, use a narrower exact target; partial values are never returned.',
+  },
+  [ERROR_CODES.SENSITIVE_TARGET_NOT_FOUND]: {
+    retry: false,
+    alternativeMethod: 'page.get_storage',
+    hint: 'The exact storage key does not exist. Use page.get_storage to inspect metadata before another deliberate sensitive read.',
+  },
   [ERROR_CODES.ELEMENT_STALE]: {
     retry: false,
     alternativeMethod: 'dom.query',
@@ -97,10 +114,36 @@ export const ERROR_RECOVERY = Object.freeze({
     retryAfterMs: 1000,
     hint: 'Operation exceeded the time limit. Retry once, or simplify the request (smaller maxNodes, narrower selector).',
   },
-  [ERROR_CODES.RATE_LIMITED]: {
-    retry: true,
-    retryAfterMs: 2000,
-    hint: 'Too many requests. Back off and retry after a short delay.',
+  [ERROR_CODES.CONTENT_SCRIPT_UNAVAILABLE]: {
+    retry: false,
+    hint: 'The page cannot host the Browser Bridge content script. Switch to a normal http(s) page in the enabled window.',
+  },
+  [ERROR_CODES.ARTIFACT_NOT_FOUND]: {
+    retry: false,
+    hint: 'The artifact is missing, expired, deleted, or owned by another client. Capture it again.',
+  },
+  [ERROR_CODES.ARTIFACT_QUOTA_EXCEEDED]: {
+    retry: false,
+    hint: 'Artifact storage quota was exceeded. Delete unneeded artifacts or retry after expiry.',
+  },
+  [ERROR_CODES.ARTIFACT_TRANSFER_INVALID]: {
+    retry: false,
+    hint: 'Artifact transfer validation failed. Capture the screenshot again.',
+  },
+  [ERROR_CODES.DOM_BASELINE_NOT_FOUND]: {
+    retry: false,
+    alternativeMethod: 'dom.baseline.create',
+    hint: 'The DOM baseline is missing, expired, or released. Create a new baseline before comparing or describing it.',
+  },
+  [ERROR_CODES.DOM_BASELINE_INVALIDATED]: {
+    retry: false,
+    alternativeMethod: 'dom.baseline.create',
+    hint: 'The page document or baseline scope changed. Create a new baseline in the current document.',
+  },
+  [ERROR_CODES.DOM_BASELINE_QUOTA_EXCEEDED]: {
+    retry: false,
+    alternativeMethod: 'dom.baseline.release',
+    hint: 'DOM baseline storage quota was exceeded. Release unneeded baselines, narrow the selector, or reduce maxNodes and textBudget before creating another baseline.',
   },
   [ERROR_CODES.EXTENSION_DISCONNECTED]: {
     retry: true,

package/packages/protocol/src/har.js

@@ -0,0 +1,34 @@
+// @ts-check
+
+/**
+ * Minimal structural validation for HAR 1.2 documents shared by the CLI and
+ * the MCP server. Only the envelope is validated (`log.version` and the
+ * `entries` array); deeper field checks are left to HAR consumers.
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {value is import('./types.js').HarLog}
+ */
+export function isHarLog(value) {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Reflect.get(value, 'version') === '1.2' &&
+    Array.isArray(Reflect.get(value, 'entries'))
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is import('./types.js').HarDocument}
+ */
+export function isHarDocument(value) {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    isHarLog(Reflect.get(value, 'log'))
+  );
+}