@browserbridge/bbx 1.11.5 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.11.5",
+  "version": "1.12.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -56,6 +56,8 @@
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "fixture:browser": "node tests/fixtures/browser-reliability/server.mjs",
+    "fixture:interaction": "node tests/fixtures/agent-interaction/server.mjs",
+    "bench:interaction": "node tests/fixtures/agent-interaction/bench.mjs",
     "test:runtime": "node --import tsx --test packages/*/test/*.test.ts packages/integration-tests/*.test.ts tests/fixtures/*/*.test.ts",
     "test": "c8 node --import tsx --test packages/*/test/*.test.ts packages/integration-tests/*.test.ts tests/fixtures/*/*.test.ts",
     "coverage": "c8 report --reporter=text --reporter=text-summary",

package/packages/agent-client/src/client.js

@@ -139,6 +139,18 @@ async function writeSocketLine(socket, line, signal) {
   }
 }
 
+/**
+ * Agent session that keeps tab routing sticky across separate CLI processes.
+ * Set `BBX_SESSION` to give one agent its own working tab; unset callers share
+ * the extension's default session.
+ *
+ * @returns {string | null}
+ */
+export function getDefaultAgentSession() {
+  const value = process.env.BBX_SESSION?.trim();
+  return value ? value : null;
+}
+
 export class BridgeClient extends EventEmitter {
   /**
    * @param {BridgeClientOptions} [options={}]
@@ -156,6 +168,7 @@ export class BridgeClient extends EventEmitter {
     exitProcessOnNpmUpdate = false,
     updateCompatibleNpmPackageFn = updateCompatibleNpmPackage,
     authToken = undefined,
+    agentSession = getDefaultAgentSession(),
   } = {}) {
     super();
     this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
@@ -171,6 +184,7 @@ export class BridgeClient extends EventEmitter {
     this.exitProcessOnNpmUpdate = exitProcessOnNpmUpdate;
     this.updateCompatibleNpmPackageFn = updateCompatibleNpmPackageFn;
     this.authToken = authToken;
+    this.agentSession = agentSession;
     this.socket = null;
     this.connected = false;
     this.protocolCompatibility = null;
@@ -488,7 +502,10 @@ export class BridgeClient extends EventEmitter {
       method,
       params,
       tabId,
-      meta,
+      meta:
+        this.agentSession && meta.agent_session === undefined
+          ? { ...meta, agent_session: this.agentSession }
+          : meta,
     });
 
     if (method === 'page.extract_content') {

package/packages/agent-client/src/types.ts

@@ -124,6 +124,8 @@ export interface BridgeClientOptions {
     supportedVersions: readonly string[];
   }) => Promise<NpmUpdateResult>;
   authToken?: string | null;
+  /** Stable agent session id used for sticky working-tab routing. */
+  agentSession?: string | null;
 }
 
 export interface ShortcutCommand {

package/packages/mcp-server/src/handlers-capture.js

@@ -326,10 +326,17 @@ export const INPUT_ACTION_METHODS = {
  *
  * @param {unknown} elementRef
  * @param {unknown} selector
+ * @param {unknown} [locator]
  * @returns {import('../../protocol/src/types.js').InputTarget | null}
  */
-function createInputTarget(elementRef, selector) {
+function createInputTarget(elementRef, selector, locator) {
   if (typeof elementRef === 'string' && elementRef) return { elementRef };
+  if (locator && typeof locator === 'object' && Object.keys(locator).length) {
+    return {
+      ...(typeof selector === 'string' && selector ? { selector } : {}),
+      .../** @type {Record<string, unknown>} */ (locator),
+    };
+  }
   if (typeof selector === 'string' && selector) return { selector };
   return null;
 }
@@ -337,18 +344,20 @@ function createInputTarget(elementRef, selector) {
 /**
  * Avoid changing legacy handler payloads when new options are omitted.
  *
- * @param {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean }} args
- * @returns {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean }}
+ * @param {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean, timeoutMs?: number, observe?: boolean | { settleMs?: number } }} args
+ * @returns {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean, timeoutMs?: number, observe?: boolean | { settleMs?: number } }}
  */
 function createInputOptions(args) {
   return {
     ...(args.executionMode ? { executionMode: args.executionMode } : {}),
     ...(typeof args.recoverStale === 'boolean' ? { recoverStale: args.recoverStale } : {}),
+    ...(typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : {}),
+    ...(args.observe !== undefined ? { observe: args.observe } : {}),
   };
 }
 
 /**
- * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, holdMs?: number, text?: string, value?: string, mode?: 'auto' | 'setter' | 'keystrokes', executionMode?: 'dom' | 'cdp', recoverStale?: boolean, clear?: boolean, submit?: boolean, key?: string, code?: string, modifiers?: string[], checked?: boolean, values?: string[], labels?: string[], indexes?: number[], duration?: number, sourceElementRef?: string, sourceSelector?: string, destinationElementRef?: string, destinationSelector?: string, offsetX?: number, offsetY?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, holdMs?: number, text?: string, value?: string, mode?: 'auto' | 'setter' | 'keystrokes', executionMode?: 'dom' | 'cdp', recoverStale?: boolean, clear?: boolean, submit?: boolean, key?: string, code?: string, modifiers?: string[], checked?: boolean, values?: string[], labels?: string[], indexes?: number[], duration?: number, sourceElementRef?: string, sourceSelector?: string, destinationElementRef?: string, destinationSelector?: string, offsetX?: number, offsetY?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep', locator?: Record<string, unknown>, timeoutMs?: number, observe?: boolean | { settleMs?: number } }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleInputTool(args) {
@@ -374,9 +383,9 @@ export async function handleInputTool(args) {
     async (client) => {
       const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
       const elementTarget = () => {
-        const target = createInputTarget(args.elementRef, args.selector);
+        const target = createInputTarget(args.elementRef, args.selector, args.locator);
         if (!target) {
-          throw new BridgeError('INVALID_REQUEST', 'Provide either elementRef or selector.');
+          throw new BridgeError('INVALID_REQUEST', 'Provide elementRef, selector, or locator.');
         }
         return target;
       };
@@ -457,7 +466,8 @@ export async function handleInputTool(args) {
           return summarizeToolResponse(response, 'input.fill');
         }
         case 'press_key': {
-          const target = args.elementRef || args.selector ? elementTarget() : undefined;
+          const target =
+            args.elementRef || args.selector || args.locator ? elementTarget() : undefined;
           const response = await requestBridgeWithRetry(
             client,
             'input.press_key',

package/packages/mcp-server/src/handlers-dom.js

@@ -87,6 +87,7 @@ export const DOM_ACTIONS = {
       exact: a.exact,
       selector: a.selector,
       maxResults: a.maxResults,
+      ...(a.includeHidden !== undefined ? { includeHidden: a.includeHidden } : {}),
     }),
   },
   find_role: {
@@ -95,8 +96,10 @@ export const DOM_ACTIONS = {
     params: (a) => ({
       role: a.role,
       name: a.name,
+      ...(a.exact !== undefined ? { exact: a.exact } : {}),
       selector: a.selector,
       maxResults: a.maxResults,
+      ...(a.includeHidden !== undefined ? { includeHidden: a.includeHidden } : {}),
     }),
   },
   html: {
@@ -117,12 +120,14 @@ export const DOM_ACTIONS = {
       maxDepth: a.maxDepth,
       compact: a.compact,
       interactiveOnly: a.interactiveOnly,
+      ...(a.source !== undefined ? { source: a.source } : {}),
+      ...(a.format !== undefined ? { format: a.format } : {}),
     }),
   },
 };
 
 /**
- * @param {{ action: string, baselineId?: string, maxChanges?: number, selector?: string, elementRef?: string, withinRef?: string, maxNodes?: number, maxDepth?: number, compact?: boolean, interactiveOnly?: boolean, textBudget?: number, includeBbox?: boolean, attributeAllowlist?: string[], attributes?: string[], text?: string, exact?: boolean, maxResults?: number, role?: string, name?: string, state?: string, timeoutMs?: number, outer?: boolean, maxLength?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, baselineId?: string, maxChanges?: number, selector?: string, elementRef?: string, withinRef?: string, maxNodes?: number, maxDepth?: number, compact?: boolean, interactiveOnly?: boolean, source?: 'cdp' | 'dom', format?: 'tree' | 'outline', includeHidden?: boolean, textBudget?: number, includeBbox?: boolean, attributeAllowlist?: string[], attributes?: string[], text?: string, exact?: boolean, maxResults?: number, role?: string, name?: string, state?: string, timeoutMs?: number, outer?: boolean, maxLength?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleDomTool(args) {

package/packages/mcp-server/src/handlers-utils.js

@@ -47,6 +47,8 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-clie
 
 export const REQUEST_SOURCE = 'mcp';
 const MCP_CLIENT_ID = `mcp_${randomUUID()}`;
+// One MCP server process serves one agent conversation, so it owns one working tab.
+const MCP_AGENT_SESSION = process.env.BBX_SESSION?.trim() || MCP_CLIENT_ID;
 /** @type {AsyncLocalStorage<{ era: import('../../protocol/src/types.js').McpProtocolEra, signal?: AbortSignal }>} */
 const MCP_REQUEST_ERA = new AsyncLocalStorage();
 
@@ -346,6 +348,7 @@ export async function withMcpRequestClient(callback, options = {}) {
   const client = await createBridgeClientForDestination(options.destinationId, {
     checkProtocolOnConnect: false,
     clientId: MCP_CLIENT_ID,
+    agentSession: MCP_AGENT_SESSION,
   });
   let completed = false;
   try {

package/packages/mcp-server/src/server.js

@@ -284,7 +284,7 @@ export function createBridgeMcpServer(options = {}) {
     {
       title: 'Browser DOM',
       description:
-        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed and depth-limited - use query/find first.',
+        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For a page overview to act on, use accessibility_tree with source "dom": a compact outline (`- role "name" [ref]`) whose refs work directly as input targets, with no debugger. find_text/find_role search shadow DOM, use real accessible names (labels, aria-*), and skip hidden matches. For full-page text, use browser_page action "text".',
       inputSchema: z.object({
         action: z
           .enum([
@@ -350,6 +350,16 @@ export function createBridgeMcpServer(options = {}) {
           .describe(
             'Return semantically interactive AX nodes; actionable state is reported separately'
           ),
+        source: z
+          .enum(['dom', 'cdp'])
+          .optional()
+          .describe(
+            'accessibility_tree source: dom = actionable outline with refs, no debugger (recommended); cdp = Chrome AX tree (default)'
+          ),
+        format: z
+          .enum(['outline', 'tree'])
+          .optional()
+          .describe('accessibility_tree format (outline is default for source dom)'),
         textBudget: z
           .number()
           .int()
@@ -381,6 +391,10 @@ export function createBridgeMcpServer(options = {}) {
           .describe('Maximum search results (default: 10)'),
         role: z.string().optional().describe('ARIA role to search for (for find_role action)'),
         name: z.string().optional().describe('Accessible name to match with role'),
+        includeHidden: z
+          .boolean()
+          .optional()
+          .describe('Include hidden matches in find_text/find_role (default: false; counted)'),
         state: z
           .enum(['attached', 'detached', 'visible', 'hidden'])
           .optional()
@@ -658,7 +672,7 @@ export function createBridgeMcpServer(options = {}) {
     {
       title: 'Browser Input',
       description:
-        'Dispatch browser input. Targeted click, focus, type, fill, press_key, set_checked, select_option, hover, and drag actions perform actionability checks and report resolution/execution metadata. cdp_press_key and scroll_into_view use separate contracts. Reuse elementRef values and verify application state after mutations.',
+        'Dispatch browser input. Target by elementRef, selector, or a semantic locator ({role,name} / text / label / placeholder / testId) in one call. Targeted actions auto-wait for the element to become actionable (timeoutMs) and click/press_key/set_checked/select_option/submits return observed effects (URL change, dialogs, alerts, focus, DOM churn, target state), so a follow-up read is usually unnecessary. cdp_press_key and scroll_into_view use separate contracts.',
       inputSchema: z.object({
         action: z
           .enum([
@@ -769,6 +783,39 @@ export function createBridgeMcpServer(options = {}) {
           .describe('Drag destination selector (alternative to destinationElementRef)'),
         offsetX: z.number().optional().describe('Drag drop offset X (default: 0)'),
         offsetY: z.number().optional().describe('Drag drop offset Y (default: 0)'),
+        locator: z
+          .object({
+            role: z.string().max(500).optional().describe('ARIA role, e.g. button, textbox, link'),
+            name: z.string().max(500).optional().describe('Accessible name (labels, aria-*, text)'),
+            text: z.string().max(500).optional().describe('Visible text of the element'),
+            label: z.string().max(500).optional().describe('Form control label text'),
+            placeholder: z.string().max(500).optional(),
+            testId: z.string().max(500).optional().describe('data-testid / data-test / data-qa'),
+            exact: z.boolean().optional().describe('Exact instead of substring match'),
+            nth: z.number().int().min(0).max(49).optional().describe('Pick the nth visible match'),
+          })
+          .optional()
+          .describe(
+            'Find the target semantically in the same call (instead of elementRef/selector); selector narrows candidates'
+          ),
+        timeoutMs: z
+          .number()
+          .int()
+          .min(0)
+          .max(15000)
+          .optional()
+          .describe(
+            'Wait for the target to appear and become actionable (default: 2500; 0 = no wait)'
+          ),
+        observe: z
+          .union([
+            z.boolean(),
+            z.object({ settleMs: z.number().int().min(0).max(5000).optional() }),
+          ])
+          .optional()
+          .describe(
+            'Report effects (URL, dialogs, alerts, focus, DOM churn, target state) after the action; default on for click, press_key, set_checked, select_option, and submits'
+          ),
       }),
     },
     handleInputTool

package/packages/protocol/src/protocol.js

@@ -415,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,
     },
   };
 }
@@ -456,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);
@@ -526,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':
@@ -535,13 +541,13 @@ 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':
@@ -625,9 +631,23 @@ export function getBridgeOperationTimeoutMs(method, params = {}) {
     case 'input.perform':
       return normalizeInputPerformParams(params).timeoutMs;
     case 'input.click':
-    case 'input.press_key': {
+    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);
-      return holdMs > 0 ? holdMs + INPUT_HOLD_TIMEOUT_MARGIN_MS : null;
+      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;
@@ -754,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),
+  };
 }
 
 /**
@@ -770,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';
 }
 
 /**
@@ -992,9 +1104,14 @@ export function normalizeInputPerformParams(params = {}) {
       );
     }
     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: normalizeRequestParams(stepMethod, stepParams),
+      params: normalizedStepParams,
       delayMs: delayMs ?? 0,
       atMs,
     };
@@ -1342,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,
   };
 }
 
@@ -1353,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,
   };
 }
 
@@ -1604,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,
@@ -1611,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':
@@ -522,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
   ),
@@ -530,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
   ),
@@ -546,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
   ),