@browserbridge/bbx 1.11.3 → 1.12.0

package/packages/protocol/src/protocol.js

@@ -19,19 +19,25 @@ import {
   DEFAULT_NETWORK_INTERCEPT_ACTION,
   DEFAULT_NETWORK_LIMIT,
   DEFAULT_PAGE_TEXT_BUDGET,
+  DEFAULT_PERFORM_TIMEOUT_MS,
   DEFAULT_TEXT_BUDGET,
+  DEFAULT_TOUCH_HOLD_MS,
   DEFAULT_VIEWPORT_HEIGHT,
   DEFAULT_VIEWPORT_WIDTH,
   DEFAULT_WAIT_TIMEOUT_MS,
   MAX_EXTRACT_SETTLE_TIMEOUT_MS,
   MAX_ARTIFACT_BYTES,
   MAX_HAR_ENTRIES,
+  MAX_INPUT_HOLD_MS,
   MAX_INTERCEPT_BODY_BYTES,
   MAX_INTERCEPT_HEADER_BYTES,
   MAX_INTERCEPT_HEADERS,
   MAX_INTERCEPT_HEADER_VALUE_BYTES,
   MAX_INTERCEPT_URL_PATTERN_LENGTH,
+  MAX_PERFORM_STEPS,
+  MAX_PERFORM_TIMEOUT_MS,
   MAX_SENSITIVE_VALUE_BYTES,
+  MAX_TOUCH_POINTS,
 } from './defaults.js';
 import { BridgeError, ERROR_CODES, getErrorRecovery } from './errors.js';
 import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry.js';
@@ -96,6 +102,8 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').NormalizedNetworkParams} NormalizedNetworkParams */
 /** @typedef {import('./types.js').NormalizedPageTextParams} NormalizedPageTextParams */
 /** @typedef {import('./types.js').NormalizedPatchOperation} NormalizedPatchOperation */
+/** @typedef {import('./types.js').NormalizedPerformParams} NormalizedPerformParams */
+/** @typedef {import('./types.js').NormalizedPerformStep} NormalizedPerformStep */
 /** @typedef {import('./types.js').NormalizedSelectAction} NormalizedSelectAction */
 /** @typedef {import('./types.js').NormalizedScreenshotParams} NormalizedScreenshotParams */
 /** @typedef {import('./types.js').NormalizedStorageParams} NormalizedStorageParams */
@@ -103,11 +111,17 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').NormalizedStyleQuery} NormalizedStyleQuery */
 /** @typedef {import('./types.js').NormalizedTabCloseParams} NormalizedTabCloseParams */
 /** @typedef {import('./types.js').NormalizedTabCreateParams} NormalizedTabCreateParams */
+/** @typedef {import('./types.js').NormalizedTouchParams} NormalizedTouchParams */
+/** @typedef {import('./types.js').NormalizedTouchPoint} NormalizedTouchPoint */
+/** @typedef {import('./types.js').NormalizedTouchPosition} NormalizedTouchPosition */
 /** @typedef {import('./types.js').NormalizedViewportAction} NormalizedViewportAction */
 /** @typedef {import('./types.js').NormalizedViewportResizeParams} NormalizedViewportResizeParams */
 /** @typedef {import('./types.js').NormalizedWaitForLoadStateParams} NormalizedWaitForLoadStateParams */
 /** @typedef {import('./types.js').NormalizedWaitForParams} NormalizedWaitForParams */
 /** @typedef {import('./types.js').PageTextParams} PageTextParams */
+/** @typedef {import('./types.js').PerformParams} PerformParams */
+/** @typedef {import('./types.js').PerformStepMethod} PerformStepMethod */
+/** @typedef {import('./types.js').TouchParams} TouchParams */
 /** @typedef {import('./types.js').PatchOperationParams} PatchOperationParams */
 /** @typedef {import('./types.js').SelectActionParams} SelectActionParams */
 /** @typedef {import('./types.js').ScreenshotParams} ScreenshotParams */
@@ -401,6 +415,11 @@ export function validateBridgeRequest(request) {
       source: meta.source === 'cli' || meta.source === 'mcp' ? meta.source : undefined,
       mcp_era: normalizeMcpEra(meta.source, meta.mcp_era),
       automatic_retry: normalizeAutomaticRetryMeta(meta.source, meta.automatic_retry),
+      agent_session:
+        typeof meta.agent_session === 'string' &&
+        /^[A-Za-z0-9_.:-]{1,128}$/.test(meta.agent_session.trim())
+          ? meta.agent_session.trim()
+          : undefined,
     },
   };
 }
@@ -442,13 +461,14 @@ function normalizeAutomaticRetryMeta(source, value) {
 
 /**
  * Normalize request params early so malformed payloads fail at the shared
- * protocol boundary before daemon or extension dispatch.
+ * protocol boundary before daemon or extension dispatch. Exported so later
+ * stages re-normalize with the same per-method options (auto-wait, observe).
  *
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} params
  * @returns {Record<string, unknown>}
  */
-function normalizeRequestParams(method, params) {
+export function normalizeRequestParams(method, params) {
   switch (method) {
     case 'access.request':
       return normalizeAccessRequestParams(params);
@@ -512,7 +532,7 @@ function normalizeRequestParams(method, params) {
     case 'input.type':
     case 'input.fill':
     case 'input.press_key':
-      return normalizeInputAction(params);
+      return withInputOptions(method, normalizeInputAction(params), params);
     case 'cdp.dispatch_key_event':
       return normalizeCdpDispatchKeyEventParams(params);
     case 'cdp.get_box_model':
@@ -521,13 +541,17 @@ function normalizeRequestParams(method, params) {
     case 'cdp.get_dom_snapshot':
       return normalizeCdpDomSnapshotParams(params);
     case 'input.set_checked':
-      return normalizeCheckedAction(params);
+      return withInputOptions(method, normalizeCheckedAction(params), params);
     case 'input.select_option':
-      return normalizeSelectAction(params);
+      return withInputOptions(method, normalizeSelectAction(params), params);
     case 'input.hover':
-      return normalizeHoverParams(params);
+      return withInputOptions(method, normalizeHoverParams(params), params);
     case 'input.drag':
-      return normalizeDragParams(params);
+      return withInputOptions(method, normalizeDragParams(params), params);
+    case 'input.touch':
+      return normalizeTouchParams(params);
+    case 'input.perform':
+      return normalizeInputPerformParams(params);
     case 'screenshot.capture_region':
       return { ...params, ...normalizeScreenshotParams(params) };
     case 'screenshot.capture_element':
@@ -604,11 +628,37 @@ export function getBridgeOperationTimeoutMs(method, params = {}) {
     }
     case 'dom.wait_for':
       return clampInt(params.timeoutMs, 100, 30_000, 5_000);
+    case 'input.perform':
+      return normalizeInputPerformParams(params).timeoutMs;
+    case 'input.click':
+    case 'input.press_key':
+    case 'input.focus':
+    case 'input.type':
+    case 'input.fill':
+    case 'input.set_checked':
+    case 'input.select_option':
+    case 'input.hover':
+    case 'input.drag': {
+      const normalized =
+        /** @type {{ timeoutMs?: number, observe?: { settleMs: number } | null }} */ (
+          normalizeRequestParams(method, params)
+        );
+      const holdMs = normalizeHoldMs(params.holdMs, 0);
+      const waitMs = normalized.timeoutMs ?? 0;
+      const settleMs = normalized.observe?.settleMs ?? 0;
+      const total = holdMs + waitMs + settleMs;
+      return total > 0 ? total + INPUT_HOLD_TIMEOUT_MARGIN_MS : null;
+    }
+    case 'input.touch':
+      return normalizeHoldMs(params.holdMs, DEFAULT_TOUCH_HOLD_MS) + INPUT_HOLD_TIMEOUT_MARGIN_MS;
     default:
       return null;
   }
 }
 
+/** Resolution and dispatch allowance added around an input hold (ms). */
+const INPUT_HOLD_TIMEOUT_MARGIN_MS = 5_000;
+
 /**
  * @param {DomQueryParams} [params={}]
  * @returns {NormalizedDomQuery}
@@ -724,15 +774,107 @@ export function normalizeStyleQuery(params = {}) {
   };
 }
 
+const TARGET_LOCATOR_KEYS = /** @type {const} */ ([
+  'role',
+  'name',
+  'text',
+  'label',
+  'placeholder',
+  'testId',
+]);
+const MAX_LOCATOR_VALUE_LENGTH = 500;
+
 /**
- * @param {{ elementRef?: string, selector?: string } | null | undefined} target
+ * Normalize an input target. Besides `elementRef` and `selector`, a target can
+ * be a semantic locator (`role` + `name`, `text`, `label`, `placeholder`,
+ * `testId`) so one action call can find and act on an element. `selector`
+ * then narrows locator candidates; `nth` picks one of several matches.
+ *
+ * @param {Record<string, unknown> | null | undefined} target
  * @returns {import('./types.js').InputTarget}
  */
 function normalizeTarget(target) {
-  return {
+  /** @type {import('./types.js').InputTarget} */
+  const normalized = {
     elementRef: typeof target?.elementRef === 'string' ? target.elementRef : undefined,
     selector: typeof target?.selector === 'string' ? target.selector : undefined,
   };
+  if (!target) return normalized;
+  for (const key of TARGET_LOCATOR_KEYS) {
+    const value = target[key];
+    if (typeof value !== 'string' || !value.trim()) continue;
+    if (value.length > MAX_LOCATOR_VALUE_LENGTH) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `target.${key} must not exceed ${MAX_LOCATOR_VALUE_LENGTH} characters.`
+      );
+    }
+    normalized[key] = value.trim();
+  }
+  if (target.exact === true) normalized.exact = true;
+  if (target.nth !== undefined && target.nth !== null) {
+    const nth = Number(target.nth);
+    if (!Number.isInteger(nth) || nth < 0 || nth > 49) {
+      throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'target.nth must be an integer 0-49.');
+    }
+    normalized.nth = nth;
+  }
+  return normalized;
+}
+
+/** Default bounded wait for a target to exist and become actionable (ms). */
+export const DEFAULT_INPUT_WAIT_MS = 2_500;
+export const MAX_INPUT_WAIT_MS = 15_000;
+/** Default and maximum post-action settle window used by `observe` (ms). */
+export const DEFAULT_OBSERVE_SETTLE_MS = 500;
+export const MAX_OBSERVE_SETTLE_MS = 5_000;
+
+/** Actions that report their observed effects unless `observe: false`. */
+const OBSERVE_BY_DEFAULT_METHODS = new Set([
+  'input.click',
+  'input.press_key',
+  'input.select_option',
+  'input.set_checked',
+]);
+
+/**
+ * @param {string} method
+ * @param {unknown} value
+ * @param {{ submit?: boolean }} normalized
+ * @returns {{ settleMs: number } | null}
+ */
+function normalizeObserveOption(method, value, normalized) {
+  if (value === false || value === null) return null;
+  if (value && typeof value === 'object') {
+    const settleMs = /** @type {{ settleMs?: unknown }} */ (value).settleMs;
+    return {
+      settleMs: clampInt(settleMs, 0, MAX_OBSERVE_SETTLE_MS, DEFAULT_OBSERVE_SETTLE_MS),
+    };
+  }
+  const observeByDefault =
+    OBSERVE_BY_DEFAULT_METHODS.has(method) ||
+    ((method === 'input.type' || method === 'input.fill') && normalized.submit === true);
+  return value === true || observeByDefault ? { settleMs: DEFAULT_OBSERVE_SETTLE_MS } : null;
+}
+
+/**
+ * Add the shared auto-wait and observation options to normalized input params.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {string} method
+ * @param {T} normalized
+ * @param {Record<string, unknown>} raw
+ * @returns {T & { timeoutMs: number, observe: { settleMs: number } | null }}
+ */
+function withInputOptions(method, normalized, raw) {
+  return {
+    ...normalized,
+    timeoutMs:
+      typeof raw.timeoutMs === 'number' && Number.isFinite(raw.timeoutMs)
+        ? Math.round(clampNumber(raw.timeoutMs, 0, MAX_INPUT_WAIT_MS, DEFAULT_INPUT_WAIT_MS))
+        : DEFAULT_INPUT_WAIT_MS,
+    observe: normalizeObserveOption(method, raw.observe, normalized),
+  };
 }
 
 /**
@@ -740,10 +882,10 @@ function normalizeTarget(target) {
  * @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.');
+  if (value !== undefined && value !== 'dom' && value !== 'cdp' && value !== 'auto') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'executionMode must be dom, cdp, or auto.');
   }
-  return value === 'cdp' ? 'cdp' : 'dom';
+  return value === 'cdp' || value === 'auto' ? value : 'dom';
 }
 
 /**
@@ -774,11 +916,209 @@ export function normalizeInputAction(params = {}) {
     modifiers: Array.isArray(params.modifiers)
       ? params.modifiers.filter((modifier) => typeof modifier === 'string' && modifier.trim())
       : [],
+    holdMs: normalizeHoldMs(params.holdMs, 0),
     executionMode: normalizeInputExecutionMode(params.executionMode),
     recoverStale: params.recoverStale === true,
   };
 }
 
+/**
+ * Normalize a press-and-hold duration, honoring an explicit zero.
+ *
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function normalizeHoldMs(value, fallback) {
+  return Math.round(clampNumber(value, 0, MAX_INPUT_HOLD_MS, fallback));
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {NormalizedTouchPosition}
+ */
+function normalizeTouchPosition(value, label) {
+  if (!isPlainRecord(value)) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      `${label} must be an object with either target or numeric x and y.`
+    );
+  }
+  const hasTarget = isPlainRecord(value.target);
+  const hasPoint =
+    typeof value.x === 'number' &&
+    Number.isFinite(value.x) &&
+    typeof value.y === 'number' &&
+    Number.isFinite(value.y);
+  if (hasTarget === hasPoint) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      `${label} needs exactly one of target or numeric x and y.`
+    );
+  }
+  if (hasTarget) {
+    return {
+      target: normalizeTarget(
+        /** @type {{ elementRef?: string, selector?: string }} */ (value.target)
+      ),
+      x: null,
+      y: null,
+    };
+  }
+  return { target: null, x: /** @type {number} */ (value.x), y: /** @type {number} */ (value.y) };
+}
+
+/**
+ * Normalize a simultaneous touch gesture: one to MAX_TOUCH_POINTS fingers,
+ * each placed on a target or viewport point and optionally moved to an end
+ * position while all fingers stay down for holdMs.
+ *
+ * @param {TouchParams} [params={}]
+ * @returns {NormalizedTouchParams}
+ */
+export function normalizeTouchParams(params = {}) {
+  const rawPoints = params.points;
+  if (!Array.isArray(rawPoints) || rawPoints.length < 1 || rawPoints.length > MAX_TOUCH_POINTS) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      `points must be an array of 1 to ${MAX_TOUCH_POINTS} touch points.`
+    );
+  }
+  /** @type {NormalizedTouchPoint[]} */
+  const points = rawPoints.map((point, index) => {
+    const start = normalizeTouchPosition(point, `points[${index}]`);
+    const rawEnd = isPlainRecord(point) ? point.to : undefined;
+    return {
+      ...start,
+      to: rawEnd == null ? null : normalizeTouchPosition(rawEnd, `points[${index}].to`),
+    };
+  });
+  return {
+    points,
+    holdMs: normalizeHoldMs(params.holdMs, DEFAULT_TOUCH_HOLD_MS),
+    moveSteps: clampInt(params.moveSteps, 1, 60, 10),
+    executionMode: normalizeInputExecutionMode(params.executionMode),
+    recoverStale: params.recoverStale === true,
+  };
+}
+
+/** Methods that may appear as input.perform steps. */
+const PERFORM_STEP_METHODS = new Set([
+  'input.click',
+  'input.focus',
+  'input.type',
+  'input.fill',
+  'input.press_key',
+  'input.set_checked',
+  'input.select_option',
+  'input.hover',
+  'input.drag',
+  'input.touch',
+  'input.scroll_into_view',
+  'viewport.scroll',
+  'dom.wait_for',
+  'page.wait_for_load_state',
+]);
+
+/** Step methods that accept executionMode=cdp. */
+const CDP_CAPABLE_STEP_METHODS = new Set([
+  'input.click',
+  'input.hover',
+  'input.drag',
+  'input.type',
+  'input.fill',
+  'input.press_key',
+  'input.touch',
+]);
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {number} maximum
+ * @returns {number | null}
+ */
+function normalizeStepTiming(value, label, maximum) {
+  if (value == null) return null;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > maximum) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      `${label} must be a number between 0 and the sequence timeoutMs (${maximum}).`
+    );
+  }
+  return Math.round(value);
+}
+
+/**
+ * Normalize an ordered, timed input sequence. Each step reuses an existing
+ * bridge method and its own normalizer; the sequence adds only scheduling.
+ *
+ * @param {PerformParams} [params={}]
+ * @returns {NormalizedPerformParams}
+ */
+export function normalizeInputPerformParams(params = {}) {
+  const timeoutMs = clampInt(
+    params.timeoutMs,
+    100,
+    MAX_PERFORM_TIMEOUT_MS,
+    DEFAULT_PERFORM_TIMEOUT_MS
+  );
+  const executionMode =
+    params.executionMode === undefined ? null : normalizeInputExecutionMode(params.executionMode);
+  const rawSteps = params.steps;
+  if (!Array.isArray(rawSteps) || rawSteps.length < 1 || rawSteps.length > MAX_PERFORM_STEPS) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      `steps must be an array of 1 to ${MAX_PERFORM_STEPS} steps.`
+    );
+  }
+  /** @type {NormalizedPerformStep[]} */
+  const steps = rawSteps.map((step, index) => {
+    if (!isPlainRecord(step)) {
+      throw new BridgeError(ERROR_CODES.INVALID_REQUEST, `steps[${index}] must be an object.`);
+    }
+    const method = step.method;
+    if (typeof method !== 'string' || !PERFORM_STEP_METHODS.has(method)) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `steps[${index}].method must be one of ${[...PERFORM_STEP_METHODS].join(', ')}.`
+      );
+    }
+    if (step.params !== undefined && !isPlainRecord(step.params)) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `steps[${index}].params must be an object.`
+      );
+    }
+    const rawParams = /** @type {Record<string, unknown>} */ (step.params ?? {});
+    const stepParams =
+      executionMode && CDP_CAPABLE_STEP_METHODS.has(method) && rawParams.executionMode === undefined
+        ? { ...rawParams, executionMode }
+        : rawParams;
+    const delayMs = normalizeStepTiming(step.delayMs, `steps[${index}].delayMs`, timeoutMs);
+    const atMs = normalizeStepTiming(step.atMs, `steps[${index}].atMs`, timeoutMs);
+    if (delayMs && atMs !== null) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `steps[${index}] accepts either delayMs or atMs, not both.`
+      );
+    }
+    const stepMethod = /** @type {PerformStepMethod} */ (method);
+    const normalizedStepParams = normalizeRequestParams(stepMethod, stepParams);
+    // Timed sequences keep their schedule: steps observe effects only on request.
+    if (rawParams.observe === undefined && 'observe' in normalizedStepParams) {
+      normalizedStepParams.observe = null;
+    }
+    return {
+      method: stepMethod,
+      params: normalizedStepParams,
+      delayMs: delayMs ?? 0,
+      atMs,
+    };
+  });
+  return { steps, timeoutMs, continueOnError: params.continueOnError === true };
+}
+
 /**
  * @param {CdpDispatchKeyEventParams} [params={}]
  * @returns {NormalizedCdpDispatchKeyEventParams}
@@ -1119,6 +1459,7 @@ export function normalizeFindByTextParams(params = {}) {
     exact: Boolean(params.exact),
     selector: typeof params.selector === 'string' && params.selector.trim() ? params.selector : '*',
     maxResults: clampInt(params.maxResults, 1, 50, 10),
+    includeHidden: params.includeHidden === true,
   };
 }
 
@@ -1130,8 +1471,10 @@ export function normalizeFindByRoleParams(params = {}) {
   return {
     role: typeof params.role === 'string' ? params.role : '',
     name: typeof params.name === 'string' ? params.name : '',
+    exact: Boolean(params.exact),
     selector: typeof params.selector === 'string' && params.selector.trim() ? params.selector : '*',
     maxResults: clampInt(params.maxResults, 1, 50, 10),
+    includeHidden: params.includeHidden === true,
   };
 }
 
@@ -1381,6 +1724,14 @@ export function normalizeTabCloseParams(params = {}) {
  * @returns {NormalizedAccessibilityTreeParams}
  */
 export function normalizeAccessibilityTreeParams(params = {}) {
+  const source = params.source ?? 'cdp';
+  if (source !== 'cdp' && source !== 'dom') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'source must be cdp or dom.');
+  }
+  const format = params.format ?? (source === 'dom' ? 'outline' : 'tree');
+  if (format !== 'tree' && format !== 'outline') {
+    throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'format must be tree or outline.');
+  }
   return {
     selector:
       typeof params.selector === 'string' && params.selector.trim() ? params.selector.trim() : null,
@@ -1388,6 +1739,9 @@ export function normalizeAccessibilityTreeParams(params = {}) {
     maxNodes: clampInt(params.maxNodes, 10, 5000, DEFAULT_A11Y_MAX_NODES),
     compact: params.compact === true,
     interactiveOnly: params.interactiveOnly === true,
+    // Omitted at defaults so existing CDP callers see an unchanged shape.
+    ...(source === 'dom' ? { source } : {}),
+    ...(format === 'outline' ? { format } : {}),
   };
 }
 

package/packages/protocol/src/registry.js

@@ -140,11 +140,13 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'dom.get_text': 'Read bounded text for one element.',
   'dom.get_attributes': 'Read selected attributes for one element.',
   'dom.wait_for': 'Wait for a selector or text condition in the DOM.',
-  'dom.find_by_text': 'Find elements by visible text.',
-  'dom.find_by_role': 'Find elements by ARIA role and optional name.',
+  'dom.find_by_text':
+    'Find the innermost visible elements by text, including open/closed shadow DOM.',
+  'dom.find_by_role':
+    'Find visible elements by ARIA role and accessible name (labels, aria-*, alt, content).',
   'dom.get_html': 'Read inner or outer HTML for one element.',
   'dom.get_accessibility_tree':
-    'Read a depth-limited accessibility tree with optional compact or interactive filtering.',
+    'Read an accessibility tree; source=dom returns a compact actionable outline with elementRefs and no debugger.',
   'layout.get_box_model': 'Read the box model for one element.',
   'layout.hit_test': 'Resolve the topmost element at a viewport point.',
   'styles.get_computed':
@@ -153,16 +155,22 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
     'Read element classes and inline style context (not stylesheet cascade data).',
   'viewport.scroll': 'Scroll the viewport or a scrollable element.',
   'viewport.resize': 'Resize or reset the tab viewport.',
-  'input.click': 'Actionability-check and click an element through DOM or optional CDP input.',
+  'input.click':
+    'Actionability-check and click an element through DOM or optional CDP input; holdMs keeps the button pressed.',
   'input.focus': 'Actionability-check and focus an element through DOM input.',
   'input.type': 'Actionability-check and type through DOM or optional CDP text input.',
   'input.fill':
     'Fill an editable target using a DOM strategy or optional CDP text input; verify afterward.',
-  'input.press_key': 'Send a key press to the page or an element.',
+  'input.press_key':
+    'Send a key press to the page or an element through DOM or optional CDP input; holdMs keeps the key down.',
   'input.set_checked': 'Set checkbox or radio checked state.',
   'input.select_option': 'Select options in a select element.',
   'input.hover': 'Actionability-check and hover through DOM or optional CDP pointer input.',
   'input.drag': 'Actionability-check and drag through DOM or optional CDP pointer input.',
+  'input.touch':
+    'Press one or more touch points at the same time (chords, multi-finger taps, swipes, pinches) through DOM or optional CDP touch input.',
+  'input.perform':
+    'Run an ordered, timed sequence of input steps inside the browser in one call; use for rhythm, games, gestures, and multi-step flows.',
   'input.scroll_into_view': 'Scroll an element into the visible viewport.',
   'screenshot.capture_region': 'Capture a screenshot of a viewport region.',
   'screenshot.capture_element': 'Capture a screenshot of one element.',
@@ -516,7 +524,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.find_by_text',
     'inspect',
     true,
-    ['text', 'exact', 'selector', 'maxResults'],
+    ['text', 'exact', 'selector', 'maxResults', 'includeHidden'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -524,7 +532,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.find_by_role',
     'inspect',
     true,
-    ['role', 'name', 'selector', 'maxResults'],
+    ['role', 'name', 'exact', 'selector', 'maxResults', 'includeHidden'],
     'low',
     METHOD_POLICIES.domRead
   ),
@@ -540,7 +548,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'dom.get_accessibility_tree',
     'inspect',
     true,
-    ['selector', 'maxNodes', 'maxDepth', 'compact', 'interactiveOnly'],
+    ['selector', 'maxNodes', 'maxDepth', 'compact', 'interactiveOnly', 'source', 'format'],
     'moderate',
     METHOD_POLICIES.domReadDebugger
   ),
@@ -600,7 +608,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.click',
     'interact',
     true,
-    ['target', 'button', 'clickCount', 'modifiers', 'executionMode', 'recoverStale'],
+    ['target', 'button', 'clickCount', 'modifiers', 'holdMs', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -632,7 +640,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'input.press_key',
     'interact',
     true,
-    ['target', 'key', 'modifiers', 'executionMode', 'recoverStale'],
+    ['target', 'key', 'modifiers', 'holdMs', 'executionMode', 'recoverStale'],
     'low',
     METHOD_POLICIES.automationInput
   ),
@@ -668,6 +676,22 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'moderate',
     METHOD_POLICIES.automationInput
   ),
+  'input.touch': createRegistryEntry(
+    'input.touch',
+    'interact',
+    true,
+    ['points', 'holdMs', 'moveSteps', 'executionMode', 'recoverStale'],
+    'moderate',
+    METHOD_POLICIES.automationInput
+  ),
+  'input.perform': createRegistryEntry(
+    'input.perform',
+    'interact',
+    true,
+    ['steps', 'executionMode', 'timeoutMs', 'continueOnError'],
+    'moderate',
+    METHOD_POLICIES.automationInput
+  ),
   'input.scroll_into_view': createRegistryEntry(
     'input.scroll_into_view',
     'interact',