@browserbridge/bbx 1.12.3 → 1.14.0

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

@@ -0,0 +1,136 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { BridgeError, ERROR_CODES } from '../../protocol/src/index.js';
+
+const MAX_BYTES = 128 * 1024 * 1024;
+const TOTAL_BYTES = 256 * 1024 * 1024;
+const TTL = 24 * 60 * 60 * 1000;
+const validId = /^journal_[a-f0-9]{64}$/u;
+
+/** Durable append-only journals. The random ID is a read/delete capability, never a path.
+ * Writes require the original extension connection as well as the capability.
+ * Existing files survive process restarts; the last partial line is reported by replay readers. */
+export class RecordingStore {
+  /** @param {string} directory */
+  constructor(directory) {
+    this.directory = directory;
+    /** @type {Map<string, string>} */
+    this.writers = new Map();
+  }
+  /** @param {string} id */
+  filename(id) {
+    if (!validId.test(id))
+      throw new BridgeError(ERROR_CODES.ARTIFACT_NOT_FOUND, 'Unknown recording journal.');
+    return path.join(this.directory, `${id}.jsonl`);
+  }
+  /** @returns {number} */
+  prune() {
+    fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    let bytes = 0;
+    for (const name of fs.readdirSync(this.directory)) {
+      const id = name.replace(/\.jsonl$/u, '');
+      if (!validId.test(id)) continue;
+      const filename = this.filename(id);
+      const stat = fs.lstatSync(filename);
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;
+      if (Date.now() - stat.mtimeMs > TTL) {
+        fs.unlinkSync(filename);
+        this.writers.delete(id);
+      } else bytes += stat.size;
+    }
+    return bytes;
+  }
+  /** @param {string} extensionId */
+  begin(extensionId) {
+    const used = this.prune();
+    if (used >= TOTAL_BYTES || fs.readdirSync(this.directory).length >= 32)
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_QUOTA_EXCEEDED,
+        'Recording journal quota exceeded. Delete old journals.'
+      );
+    const journalId = `journal_${randomBytes(32).toString('hex')}`;
+    const fd = fs.openSync(this.filename(journalId), 'wx', 0o600);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    this.writers.set(journalId, extensionId);
+    return { journalId, nextOffset: 0, expiresAt: new Date(Date.now() + TTL).toISOString() };
+  }
+  /** @param {string} id @param {string} extensionId @param {number} offset @param {string} data */
+  append(id, extensionId, offset, data) {
+    if (this.writers.get(id) !== extensionId)
+      throw new BridgeError(ERROR_CODES.ACCESS_DENIED, 'Journal writer connection does not match.');
+    if (
+      !Number.isSafeInteger(offset) ||
+      offset < 0 ||
+      data.length > 262144 ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(data)
+    )
+      throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Invalid journal chunk.');
+    const bytes = Buffer.from(data, 'base64');
+    if (this.prune() + bytes.length > TOTAL_BYTES || offset + bytes.length > MAX_BYTES)
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_QUOTA_EXCEEDED,
+        'Recording journal byte quota exceeded.'
+      );
+    const fd = fs.openSync(
+      this.filename(id),
+      fs.constants.O_WRONLY | (fs.constants.O_NOFOLLOW ?? 0)
+    );
+    try {
+      if (fs.fstatSync(fd).size !== offset)
+        throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Journal offset mismatch.');
+      let written = 0;
+      while (written < bytes.length) {
+        const count = fs.writeSync(fd, bytes, written, bytes.length - written, offset + written);
+        if (!count) throw new Error('Journal write made no progress.');
+        written += count;
+      }
+      fs.fsyncSync(fd);
+      return { journalId: id, nextOffset: offset + written };
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  /** @param {string} id @param {number} offset @param {number} limit */
+  read(id, offset, limit) {
+    this.prune();
+    const filename = this.filename(id);
+    const fd = fs.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const size = fs.fstatSync(fd).size;
+      if (
+        !Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        offset > size ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 196608
+      )
+        throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Invalid journal read range.');
+      const data = Buffer.alloc(Math.min(limit, size - offset));
+      const count = fs.readSync(fd, data, 0, data.length, offset);
+      return {
+        journalId: id,
+        offset,
+        byteLength: count,
+        totalBytes: size,
+        nextOffset: offset + count < size ? offset + count : null,
+        data: data.subarray(0, count).toString('base64'),
+      };
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  /** @param {string} id */
+  delete(id) {
+    fs.unlinkSync(this.filename(id));
+    this.writers.delete(id);
+    return { deleted: true };
+  }
+  /** @param {string} extensionId */
+  disconnect(extensionId) {
+    for (const [id, owner] of this.writers) if (owner === extensionId) this.writers.delete(id);
+  }
+}

package/packages/protocol/src/defaults.js

@@ -58,6 +58,9 @@ export const MAX_TOUCH_POINTS = 10;
 /** Maximum steps accepted by one input.perform sequence. */
 export const MAX_PERFORM_STEPS = 200;
 
+/** Maximum UTF-8 JSON bytes retained from the final input.perform step. */
+export const MAX_PERFORM_RESULT_BYTES = 16_384;
+
 /** Default and maximum total budget for one input.perform sequence (ms). */
 export const DEFAULT_PERFORM_TIMEOUT_MS = 30_000;
 export const MAX_PERFORM_TIMEOUT_MS = 120_000;

package/packages/protocol/src/downloads.js

@@ -0,0 +1,35 @@
+// @ts-check
+import { booleanParam, invalidWorkflow, onlyKeys, stringParam } from './emulation.js';
+
+/** @param {string} method @param {Record<string, unknown>} params */
+export function normalizeDownload(method, params) {
+  if (method !== 'download.start') {
+    onlyKeys(params, ['downloadId']);
+    return { downloadId: stringParam(params.downloadId, 'downloadId', 100) };
+  }
+  onlyKeys(params, ['url', 'filename', 'saveAs']);
+  const url = stringParam(params.url, 'url', 8192);
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return invalidWorkflow('Invalid download URL.');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password)
+    invalidWorkflow('Downloads require HTTP(S) without URL credentials.');
+  const filename =
+    params.filename === undefined ? undefined : stringParam(params.filename, 'filename', 240);
+  if (
+    filename &&
+    (/[\\/:]/u.test(filename) ||
+      [...filename].some((character) => character.charCodeAt(0) < 32) ||
+      filename === '.' ||
+      filename === '..')
+  )
+    invalidWorkflow('filename must be a single filename, not a path.');
+  return {
+    url,
+    ...(filename ? { filename } : {}),
+    saveAs: booleanParam(params.saveAs ?? false, 'saveAs'),
+  };
+}

package/packages/protocol/src/emulation.js

@@ -0,0 +1,155 @@
+// @ts-check
+
+import { BridgeError, ERROR_CODES } from './errors.js';
+
+/** @typedef {import('./workflows.js').EmulationConfig} EmulationConfig */
+
+/** Metrics presets deliberately do not impersonate a different browser engine. */
+export const DEVICE_PRESETS = Object.freeze({
+  phone: { width: 390, height: 844, deviceScaleFactor: 3, mobile: true, touch: true },
+  tablet: { width: 820, height: 1180, deviceScaleFactor: 2, mobile: true, touch: true },
+  desktop: { width: 1280, height: 800, deviceScaleFactor: 1, mobile: false, touch: false },
+});
+
+export const NETWORK_PRESETS = Object.freeze({
+  offline: { offline: true, latencyMs: 0, downloadKbps: 0, uploadKbps: 0 },
+  'slow-3g': { offline: false, latencyMs: 2000, downloadKbps: 400, uploadKbps: 400 },
+  'fast-3g': { offline: false, latencyMs: 563, downloadKbps: 1440, uploadKbps: 675 },
+  wifi: { offline: false, latencyMs: 2, downloadKbps: 30000, uploadKbps: 15000 },
+  unthrottled: { offline: false, latencyMs: 0, downloadKbps: -1, uploadKbps: -1 },
+});
+
+/** @param {string} message @returns {never} */
+export function invalidWorkflow(message) {
+  throw new BridgeError(ERROR_CODES.INVALID_REQUEST, message);
+}
+
+/** @param {unknown} value @param {string} name @returns {Record<string, unknown>} */
+export function objectParam(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    invalidWorkflow(`${name} must be an object.`);
+  }
+  return /** @type {Record<string, unknown>} */ (value);
+}
+
+/** @param {unknown} value @param {string} name @param {number} min @param {number} max @returns {number} */
+export function numberParam(value, name, min, max) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+    invalidWorkflow(`${name} must be between ${min} and ${max}.`);
+  }
+  return value;
+}
+
+/** @param {unknown} value @param {string} name @param {number} [max] @returns {string} */
+export function stringParam(value, name, max = 256) {
+  if (
+    typeof value !== 'string' ||
+    !value.length ||
+    value.length > max ||
+    [...value].some((character) => character.charCodeAt(0) < 32)
+  ) {
+    invalidWorkflow(
+      `${name} must be a nonempty string of at most ${max} characters without control characters.`
+    );
+  }
+  return value;
+}
+
+/** @param {unknown} value @param {string} name @returns {boolean} */
+export function booleanParam(value, name) {
+  if (typeof value !== 'boolean') invalidWorkflow(`${name} must be boolean.`);
+  return value;
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} keys */
+export function onlyKeys(value, keys) {
+  const unknown = Object.keys(value).find((key) => !keys.includes(key));
+  if (unknown) invalidWorkflow(`Unknown parameter: ${unknown}.`);
+}
+
+/** Validate once at the shared boundary; repeated normalization is idempotent.
+ * @param {Record<string, unknown>} params @returns {EmulationConfig} */
+export function normalizeEmulation(params) {
+  onlyKeys(params, ['device', 'network', 'cpuRate', 'locale', 'timezoneId', 'geolocation']);
+  /** @type {EmulationConfig} */
+  const config = {};
+  if (params.device !== undefined) {
+    const input =
+      typeof params.device === 'string'
+        ? { preset: params.device }
+        : objectParam(params.device, 'device');
+    onlyKeys(input, ['preset', 'width', 'height', 'deviceScaleFactor', 'mobile', 'touch']);
+    const preset =
+      input.preset === undefined
+        ? {}
+        : Object.hasOwn(DEVICE_PRESETS, String(input.preset))
+          ? DEVICE_PRESETS[/** @type {keyof typeof DEVICE_PRESETS} */ (input.preset)]
+          : null;
+    if (!preset) invalidWorkflow('device.preset must be phone, tablet, or desktop.');
+    /** @type {Record<string, unknown>} */
+    const device = { ...preset, ...input };
+    config.device = {
+      width: Math.round(numberParam(device.width, 'width', 1, 8192)),
+      height: Math.round(numberParam(device.height, 'height', 1, 8192)),
+      deviceScaleFactor: numberParam(device.deviceScaleFactor ?? 1, 'deviceScaleFactor', 0.1, 4),
+      mobile: booleanParam(device.mobile ?? false, 'mobile'),
+      touch: booleanParam(device.touch ?? device.mobile ?? false, 'touch'),
+    };
+  }
+  if (params.network !== undefined) {
+    const input =
+      typeof params.network === 'string'
+        ? { preset: params.network }
+        : objectParam(params.network, 'network');
+    onlyKeys(input, ['preset', 'offline', 'latencyMs', 'downloadKbps', 'uploadKbps']);
+    const preset =
+      input.preset === undefined
+        ? NETWORK_PRESETS.unthrottled
+        : Object.hasOwn(NETWORK_PRESETS, String(input.preset))
+          ? NETWORK_PRESETS[/** @type {keyof typeof NETWORK_PRESETS} */ (input.preset)]
+          : null;
+    if (!preset)
+      invalidWorkflow(
+        'Unknown network preset. Use offline, slow-3g, fast-3g, wifi, or unthrottled.'
+      );
+    const network = { ...preset, ...input };
+    config.network = {
+      offline: booleanParam(network.offline, 'offline'),
+      latencyMs: numberParam(network.latencyMs, 'latencyMs', 0, 60000),
+      downloadKbps: numberParam(network.downloadKbps, 'downloadKbps', -1, 10000000),
+      uploadKbps: numberParam(network.uploadKbps, 'uploadKbps', -1, 10000000),
+    };
+    for (const speed of [config.network.downloadKbps, config.network.uploadKbps]) {
+      if (speed < 0 && speed !== -1)
+        invalidWorkflow('Throughput must be nonnegative or -1 for unthrottled.');
+    }
+  }
+  if (params.cpuRate !== undefined) config.cpuRate = numberParam(params.cpuRate, 'cpuRate', 1, 100);
+  if (params.locale !== undefined) {
+    config.locale = stringParam(params.locale, 'locale', 80);
+    try {
+      Intl.getCanonicalLocales(config.locale);
+    } catch {
+      invalidWorkflow('Invalid locale.');
+    }
+  }
+  if (params.timezoneId !== undefined) {
+    config.timezoneId = stringParam(params.timezoneId, 'timezoneId', 100);
+    try {
+      new Intl.DateTimeFormat('en', { timeZone: config.timezoneId });
+    } catch {
+      invalidWorkflow('Invalid timezoneId.');
+    }
+  }
+  if (params.geolocation !== undefined) {
+    const geo = objectParam(params.geolocation, 'geolocation');
+    onlyKeys(geo, ['latitude', 'longitude', 'accuracy']);
+    config.geolocation = {
+      latitude: numberParam(geo.latitude, 'latitude', -90, 90),
+      longitude: numberParam(geo.longitude, 'longitude', -180, 180),
+      accuracy: numberParam(geo.accuracy ?? 100, 'accuracy', 0, 1000000),
+    };
+  }
+  if (!Object.keys(config).length) invalidWorkflow('Provide at least one emulation setting.');
+  return config;
+}

package/packages/protocol/src/errors.js

@@ -18,6 +18,7 @@ export const ERROR_CODES = Object.freeze({
   INPUT_UNSUPPORTED: 'INPUT_UNSUPPORTED',
   INPUT_INVALID_TARGET: 'INPUT_INVALID_TARGET',
   INPUT_FOCUS_CHANGED: 'INPUT_FOCUS_CHANGED',
+  DIALOG_BLOCKED: 'DIALOG_BLOCKED',
   DIALOG_NOT_OPEN: 'DIALOG_NOT_OPEN',
   DIALOG_ACTION_CONFLICT: 'DIALOG_ACTION_CONFLICT',
   RESULT_TRUNCATED: 'RESULT_TRUNCATED',
@@ -120,6 +121,11 @@ export const ERROR_RECOVERY = Object.freeze({
     alternativeMethod: 'dom.describe',
     hint: 'Focus moved away from the resolved editable target before native text dispatch. Inspect focus handlers or target the control that retained focus.',
   },
+  [ERROR_CODES.DIALOG_BLOCKED]: {
+    retry: false,
+    alternativeMethod: 'page.handle_dialog',
+    hint: 'A JavaScript dialog blocked the operation. Inspect it with page.handle_dialog, then explicitly accept or dismiss it. The operation may already have taken effect and may finish after the dialog closes. Inspect postconditions; never automatically replay the action or sequence.',
+  },
   [ERROR_CODES.DIALOG_NOT_OPEN]: {
     retry: false,
     alternativeMethod: 'page.handle_dialog',

package/packages/protocol/src/files.js

@@ -0,0 +1,94 @@
+// @ts-check
+
+import { invalidWorkflow, numberParam, objectParam, onlyKeys, stringParam } from './emulation.js';
+
+export const FILE_MAX_BYTES = 16 * 1024 * 1024;
+export const FILE_CHUNK_BYTES = 192 * 1024;
+export const FILE_TOTAL_BYTES = 32 * 1024 * 1024;
+export const FILE_TTL_MS = 5 * 60 * 1000;
+
+/** @param {string} method @param {Record<string, unknown>} params @returns {Record<string, unknown>} */
+export function normalizeFileParams(method, params) {
+  if (method === 'files.stage') {
+    onlyKeys(params, ['transferId', 'name', 'mimeType', 'size', 'offset', 'data']);
+    /** @type {Record<string, unknown>} */
+    const result = {};
+    if (params.transferId !== undefined)
+      result.transferId = stringParam(params.transferId, 'transferId', 80);
+    else {
+      result.name = stringParam(params.name, 'name');
+      if (/[\\/]/u.test(String(result.name)))
+        invalidWorkflow('name must be a filename, not a path.');
+      result.mimeType = stringParam(params.mimeType ?? 'application/octet-stream', 'mimeType', 120);
+      result.size = numberParam(params.size, 'size', 0, FILE_MAX_BYTES);
+      if (!Number.isInteger(result.size)) invalidWorkflow('size must be an integer.');
+    }
+    result.offset = numberParam(params.offset ?? 0, 'offset', 0, FILE_MAX_BYTES);
+    if (!Number.isInteger(result.offset)) invalidWorkflow('offset must be an integer.');
+    const data = params.data ?? '';
+    if (
+      typeof data !== 'string' ||
+      data.length > (FILE_CHUNK_BYTES * 4) / 3 ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(data)
+    )
+      invalidWorkflow('data must be base64, at most 192 KiB decoded per chunk.');
+    result.data = data;
+    return result;
+  }
+  if (method === 'files.release') {
+    onlyKeys(params, ['transferId']);
+    return { transferId: stringParam(params.transferId, 'transferId', 80) };
+  }
+  if (method === 'input.set_files') {
+    onlyKeys(params, ['target', 'files', 'paths']);
+    const target = objectParam(params.target, 'target');
+    const files = params.files;
+    const paths = params.paths;
+    if (paths !== undefined) onlyKeys(target, ['selector']);
+    if ((files === undefined) === (paths === undefined))
+      invalidWorkflow('Provide files or paths, not both. Empty files clears the input.');
+    const values = files ?? paths;
+    if (!Array.isArray(values) || values.length > 10)
+      invalidWorkflow('files/paths must be an array of at most 10 strings.');
+    const normalized = values.map((value) =>
+      stringParam(
+        value,
+        files !== undefined ? 'file handle' : 'browser path',
+        files !== undefined ? 80 : 4096
+      )
+    );
+    if (
+      paths !== undefined &&
+      normalized.some((value) => !/^(?:\/|[A-Za-z]:[\\/]|\\\\)/u.test(value))
+    )
+      invalidWorkflow('paths must be absolute paths on the browser machine.');
+    if (paths !== undefined && (typeof target.selector !== 'string' || !target.selector))
+      invalidWorkflow('Browser-local paths require target.selector in the top document.');
+    return { target, ...(files !== undefined ? { files: normalized } : { paths: normalized }) };
+  }
+  if (method === 'input.paste_image') {
+    onlyKeys(params, ['target', 'transferId']);
+    return {
+      target: objectParam(params.target, 'target'),
+      transferId: stringParam(params.transferId, 'transferId', 80),
+    };
+  }
+  if (method === 'download.resource') {
+    onlyKeys(params, ['url', 'maxBytes', 'timeoutMs']);
+    const url = stringParam(params.url, 'url', 8192);
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      invalidWorkflow('Invalid download URL.');
+    }
+    if (!['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password)
+      invalidWorkflow('Downloads require HTTP(S) without URL credentials.');
+    return {
+      url,
+      maxBytes: numberParam(params.maxBytes ?? 8 * 1024 * 1024, 'maxBytes', 1, FILE_MAX_BYTES),
+      timeoutMs: numberParam(params.timeoutMs ?? 30000, 'timeoutMs', 100, 60000),
+    };
+  }
+  return invalidWorkflow('Unknown file method.');
+}

package/packages/protocol/src/index.js

@@ -9,6 +9,7 @@ export * from './budget.js';
 export * from './capabilities.js';
 export * from './defaults.js';
 export * from './errors.js';
+export { normalizeEmulation, DEVICE_PRESETS, NETWORK_PRESETS } from './emulation.js';
 export * from './har.js';
 export * from './incidental-sanitizer.js';
 export * from './json-lines.js';

package/packages/protocol/src/protocol.js

@@ -2,6 +2,10 @@
 
 import { applyBudget } from './budget.js';
 import { normalizeWebMcpParams } from './webmcp.js';
+import { normalizeEmulation, onlyKeys } from './emulation.js';
+import { normalizeFileParams } from './files.js';
+import { normalizeDownload } from './downloads.js';
+import { normalizeRecording } from './recording.js';
 import {
   ARTIFACT_CHUNK_BYTES,
   BUDGET_PRESETS,
@@ -539,6 +543,38 @@ function normalizeAutomaticRetryMeta(source, value) {
  */
 export function normalizeRequestParams(method, params) {
   switch (method) {
+    case 'download.start':
+    case 'download.status':
+    case 'download.pause':
+    case 'download.resume':
+    case 'download.cancel':
+    case 'download.release':
+      return normalizeDownload(method, params);
+    case 'session.start':
+    case 'session.journal_read':
+    case 'session.journal_delete':
+    case 'session.status':
+    case 'session.read':
+    case 'session.stop':
+    case 'session.export':
+    case 'session.release':
+      return normalizeRecording(method, params);
+    case 'files.stage':
+    case 'files.release':
+    case 'download.resource':
+      return normalizeFileParams(method, params);
+    case 'input.set_files':
+    case 'input.paste_image':
+      return {
+        ...normalizeFileParams(method, params),
+        target: normalizeInputAction(params).target,
+      };
+    case 'emulation.apply':
+      return normalizeEmulation(params);
+    case 'emulation.status':
+    case 'emulation.reset':
+      onlyKeys(params, []);
+      return {};
     case 'webmcp.list_tools':
     case 'webmcp.get_tool':
     case 'webmcp.execute_tool': {
@@ -691,6 +727,14 @@ export function normalizeAccessRequestParams(params = {}) {
  */
 export function getBridgeOperationTimeoutMs(method, params = {}) {
   switch (method) {
+    case 'session.read':
+      return Number(normalizeRecording(method, params).waitMs) + 5000;
+    case 'session.stop':
+    case 'session.export':
+    case 'session.release':
+      return 100000;
+    case 'download.resource':
+      return Number(normalizeFileParams(method, params).timeoutMs) + 5000;
     case 'webmcp.execute_tool': {
       const normalized = normalizeWebMcpParams(params);
       return normalized.approvalTimeoutMs + normalized.timeoutMs + 10_000;
@@ -1088,7 +1132,7 @@ export function normalizeTouchParams(params = {}) {
   };
 }
 
-/** Methods that may appear as input.perform steps. */
+/** Input, wait, and bounded inspection methods allowed in input.perform steps. */
 const PERFORM_STEP_METHODS = new Set([
   'input.click',
   'input.focus',
@@ -1104,6 +1148,10 @@ const PERFORM_STEP_METHODS = new Set([
   'viewport.scroll',
   'dom.wait_for',
   'page.wait_for_load_state',
+  'page.get_state',
+  'page.get_text',
+  'dom.query',
+  'dom.get_text',
 ]);
 
 /** Step methods that accept executionMode=cdp. */
@@ -1201,7 +1249,12 @@ export function normalizeInputPerformParams(params = {}) {
       atMs,
     };
   });
-  return { steps, timeoutMs, continueOnError: params.continueOnError === true };
+  return {
+    steps,
+    timeoutMs,
+    continueOnError: params.continueOnError === true,
+    returnLastResult: params.returnLastResult === true,
+  };
 }
 
 /**
@@ -2192,6 +2245,8 @@ export function createRuntimeContext() {
       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_BLOCKED:
+        'Native JavaScript dialog blocked the operation; inspect before responding, never automatically replay',
       DIALOG_NOT_OPEN: 'No JavaScript dialog is currently observable',
       INVALID_REQUEST: 'Malformed method or params',
       TIMEOUT: 'Operation exceeded time limit',
@@ -2207,6 +2262,9 @@ export function createRuntimeContext() {
       'patch.apply_styles before patch.apply_dom',
       'Verify with get_box_model not screenshots',
       'batch independent reads',
+      'Use input.perform for known authorized multi-step flows; returnLastResult: true returns the final action or read in the same call. Stop for decisions that require new evidence; never blindly replay a partially completed flow',
+      'Input targets accept role/name or label locators and auto-wait for actionability; skip separate find and pre-action wait calls when the target is known',
+      'Read action effects before requesting more page data; sequence steps observe only with explicit observe: true',
       'Rollback all patches before finishing',
       'page.evaluate to read framework state (React, Vue, Next.js data)',
       'dom.find_by_text / dom.find_by_role for semantic element finding',

package/packages/protocol/src/recording.js

@@ -0,0 +1,70 @@
+// @ts-check
+
+import { booleanParam, invalidWorkflow, numberParam, onlyKeys, stringParam } from './emulation.js';
+
+/** @param {string} method @param {Record<string, unknown>} params @returns {Record<string, unknown>} */
+export function normalizeRecording(method, params) {
+  if (method === 'session.journal_read' || method === 'session.journal_delete') {
+    onlyKeys(params, [
+      'journalId',
+      ...(method === 'session.journal_read' ? ['offset', 'maxBytes'] : []),
+    ]);
+    const journalId = stringParam(params.journalId, 'journalId', 80);
+    if (!/^journal_[a-f0-9]{64}$/u.test(journalId)) invalidWorkflow('Invalid journal capability.');
+    if (method === 'session.journal_delete') return { journalId };
+    const offset = numberParam(params.offset ?? 0, 'offset', 0, Number.MAX_SAFE_INTEGER);
+    const maxBytes = numberParam(params.maxBytes ?? 196608, 'maxBytes', 1, 196608);
+    if (!Number.isInteger(offset) || !Number.isInteger(maxBytes))
+      invalidWorkflow('Journal ranges must be integers.');
+    return { journalId, offset, maxBytes };
+  }
+  if (method === 'session.start') {
+    onlyKeys(params, [
+      'activity',
+      'network',
+      'bodies',
+      'messages',
+      'visual',
+      'durationMs',
+      'followTabs',
+      'durable',
+      'replay',
+    ]);
+    const activity = booleanParam(params.activity ?? true, 'activity');
+    const network = booleanParam(params.network ?? false, 'network');
+    const bodies = booleanParam(params.bodies ?? false, 'bodies');
+    const messages = booleanParam(params.messages ?? false, 'messages');
+    const visual = booleanParam(params.visual ?? false, 'visual');
+    if ((bodies || messages) && !network) invalidWorkflow('bodies/messages require network:true.');
+    if (!activity && !network && !visual && params.replay !== true)
+      invalidWorkflow('Enable at least one recording source.');
+    return {
+      activity,
+      network,
+      bodies,
+      messages,
+      visual,
+      followTabs: booleanParam(params.followTabs ?? false, 'followTabs'),
+      durable: booleanParam(params.durable ?? false, 'durable'),
+      replay: booleanParam(params.replay ?? false, 'replay'),
+      durationMs: numberParam(params.durationMs ?? 60000, 'durationMs', 1000, 1800000),
+    };
+  }
+  onlyKeys(params, [
+    'sessionId',
+    ...(method === 'session.read' ? ['cursor', 'limit', 'waitMs'] : []),
+    ...(method === 'session.export' ? ['format'] : []),
+  ]);
+  const sessionId = stringParam(params.sessionId, 'sessionId', 80);
+  if (method === 'session.export') {
+    if (params.format !== undefined && params.format !== 'json' && params.format !== 'html')
+      invalidWorkflow('format must be json or html.');
+    return { sessionId, format: params.format ?? 'json' };
+  }
+  if (method !== 'session.read') return { sessionId };
+  const cursor = numberParam(params.cursor ?? 0, 'cursor', 0, Number.MAX_SAFE_INTEGER);
+  const limit = numberParam(params.limit ?? 25, 'limit', 1, 100);
+  if (!Number.isInteger(cursor) || !Number.isInteger(limit))
+    invalidWorkflow('cursor and limit must be integers.');
+  return { sessionId, cursor, limit, waitMs: numberParam(params.waitMs ?? 0, 'waitMs', 0, 25000) };
+}