@browserbridge/bbx 1.11.5 → 1.12.1

package/packages/protocol/src/summary.js

@@ -101,6 +101,126 @@ function describeTabResult(method, result) {
   }
 }
 
+const ROUTINE_STRATEGIES = new Set(['elementRef', 'selector-first', 'locator-first']);
+
+/**
+ * Keep input evidence lean: resolution/execution metadata only when something
+ * notable happened (scroll, wait, ranking, recovery, CDP, fallback), plus any
+ * observed effects. Routine successes cost a few tokens instead of ~100.
+ *
+ * @param {Record<string, unknown>} r
+ * @param {Record<string, unknown>} [extra]
+ * @returns {Record<string, unknown>}
+ */
+function compactInputEvidence(r, extra = {}) {
+  /** @type {Record<string, unknown>} */
+  const evidence = { elementRef: r.elementRef ?? null, ...extra };
+  const resolution = toRecord(r.resolution);
+  if (
+    resolution.scrolled === true ||
+    resolution.recovered === true ||
+    (typeof resolution.waitedMs === 'number' && resolution.waitedMs > 0) ||
+    (typeof resolution.strategy === 'string' && !ROUTINE_STRATEGIES.has(resolution.strategy))
+  ) {
+    /** @type {Record<string, unknown>} */
+    const notable = { strategy: resolution.strategy };
+    for (const key of ['scrolled', 'recovered', 'waitedMs', 'candidateCount', 'oldRef', 'newRef']) {
+      const value = resolution[key];
+      if (value !== undefined && value !== false && !(key === 'candidateCount' && value === 1)) {
+        notable[key] = value;
+      }
+    }
+    evidence.resolution = notable;
+  }
+  const execution = toRecord(r.execution);
+  if (execution.actualMode === 'cdp' || execution.fallbackReason) {
+    evidence.execution = {
+      actualMode: execution.actualMode,
+      ...(execution.fallbackReason ? { fallbackReason: execution.fallbackReason } : {}),
+    };
+  }
+  if (r.effects && typeof r.effects === 'object') evidence.effects = r.effects;
+  return Object.fromEntries(Object.entries(evidence).filter(([, value]) => value !== undefined));
+}
+
+/**
+ * Health evidence without idle diagnostics: zero-valued recovery counters,
+ * internal latency stats, and idle debugger/capture state are dropped, which
+ * cuts a routine health check from ~1k tokens to ~200.
+ *
+ * @param {Record<string, unknown>} result
+ * @returns {Record<string, unknown>}
+ */
+function compactHealthEvidence(result) {
+  const { recovery, domBaselines, debugger: debuggerState, capture, ...rest } = result;
+  /** @type {Record<string, unknown>} */
+  const evidence = { ...rest };
+  /** @type {Record<string, Record<string, unknown>>} */
+  const activeRecovery = {};
+  for (const [scope, value] of Object.entries(toRecord(recovery))) {
+    const events = toRecord(toRecord(value).events);
+    for (const [event, stats] of Object.entries(events)) {
+      const record = toRecord(stats);
+      if (record.attempts || record.pending || record.activeLoop) {
+        activeRecovery[`${scope}.${event}`] = {
+          attempts: record.attempts,
+          failures: record.failures,
+          ...(record.activeLoop ? { activeLoop: true } : {}),
+        };
+      }
+    }
+  }
+  if (Object.keys(activeRecovery).length) evidence.recovery = activeRecovery;
+  const baselineCount = toRecord(domBaselines).baselineCount;
+  if (typeof baselineCount === 'number' && baselineCount > 0) {
+    evidence.domBaselines = { baselineCount, bytes: toRecord(domBaselines).bytes };
+  }
+  const debuggerRecord = toRecord(debuggerState);
+  if (debuggerState && (debuggerRecord.status !== 'idle' || debuggerRecord.attachedTabCount)) {
+    evidence.debugger = debuggerState;
+  }
+  const captureRecord = toRecord(capture);
+  if (capture && captureRecord.state !== 'stopped') evidence.capture = capture;
+  return evidence;
+}
+
+/**
+ * One-line digest of observed post-action effects.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeEffects(value) {
+  if (!value || typeof value !== 'object') return '';
+  const effects = /** @type {Record<string, unknown>} */ (value);
+  /** @type {string[]} */
+  const parts = [];
+  if (effects.navigation === 'unloading') parts.push('page is navigating');
+  if (typeof effects.url === 'string') parts.push(`URL → ${truncateUrl(effects.url)}`);
+  for (const dialog of Array.isArray(effects.dialogs) ? effects.dialogs : []) {
+    const record = toRecord(dialog);
+    parts.push(
+      `${record.role ?? 'dialog'}${record.name ? ` "${record.name}"` : ''} opened [${record.ref}]`
+    );
+  }
+  for (const message of Array.isArray(effects.messages) ? effects.messages : []) {
+    const record = toRecord(message);
+    parts.push(`${record.role ?? 'status'}: "${record.text}"`);
+  }
+  const focused = toRecord(effects.focused);
+  if (focused.ref)
+    parts.push(
+      `focus → ${focused.role ?? ''}${focused.name ? ` "${focused.name}"` : ''} [${focused.ref}]`
+    );
+  const dom = toRecord(effects.dom);
+  if (typeof dom.added === 'number' || typeof dom.removed === 'number') {
+    parts.push(`DOM +${dom.added ?? 0}/-${dom.removed ?? 0}`);
+  }
+  if (toRecord(effects.target).removed === true) parts.push('target removed');
+  if (!parts.length) return effects.changed === false ? ' No visible effect.' : '';
+  return ` Effects: ${parts.join('; ')}.`;
+}
+
 /** @type {Record<string, ActionSummary>} */
 const ACTION_SUMMARIES = {
   performed: {
@@ -118,8 +238,9 @@ const ACTION_SUMMARIES = {
     evidence: (r) => r,
   },
   hovered: {
-    text: (r) => `Hover ${r.hovered ? 'active' : 'failed'} on ${r.elementRef}.`,
-    evidence: (r) => r,
+    text: (r) =>
+      `Hover ${r.hovered ? 'active' : 'failed'} on ${r.elementRef}.${describeEffects(r.effects)}`,
+    evidence: (r) => compactInputEvidence(r),
   },
   dragged: {
     text: (r) =>
@@ -130,33 +251,25 @@ const ACTION_SUMMARIES = {
   clicked: {
     text: (r) => {
       const mode = toRecord(r.execution).actualMode;
-      return `Clicked ${r.elementRef ?? 'element'}${typeof mode === 'string' ? ` via ${mode}` : ''}.`;
+      return `Clicked ${r.elementRef ?? 'element'}${typeof mode === 'string' ? ` via ${mode}` : ''}.${describeEffects(r.effects)}`;
     },
-    evidence: (r) => ({
-      elementRef: r.elementRef,
-      resolution: r.resolution,
-      execution: r.execution,
-    }),
+    evidence: (r) => compactInputEvidence(r),
   },
   focused: {
-    text: (r) => `Focused ${r.elementRef ?? 'element'}.`,
-    evidence: (r) => ({
-      elementRef: r.elementRef,
-      resolution: r.resolution,
-      execution: r.execution,
-    }),
+    text: (r) => `Focused ${r.elementRef ?? 'element'}.${describeEffects(r.effects)}`,
+    evidence: (r) => compactInputEvidence(r),
   },
   typed: {
-    text: (r) => `Typed into ${r.elementRef ?? 'element'}.`,
-    evidence: (r) => ({
-      elementRef: r.elementRef,
-      resolution: r.resolution,
-      execution: r.execution,
-    }),
+    text: (r) => `Typed into ${r.elementRef ?? 'element'}.${describeEffects(r.effects)}`,
+    evidence: (r) => compactInputEvidence(r, { value: r.value }),
   },
   pressed: {
-    text: (r) => `Key pressed${r.key ? ` (${r.key})` : ''}.`,
-    evidence: (r) => r,
+    text: (r) => `Key pressed${r.key ? ` (${r.key})` : ''}.${describeEffects(r.effects)}`,
+    evidence: (r) => {
+      const { resolution: _resolution, execution: _execution, effects: _effects, ...rest } = r;
+      const { elementRef: _elementRef, ...compact } = compactInputEvidence(r);
+      return { ...rest, ...compact };
+    },
   },
   navigated: {
     text: (r) => `Navigated to ${r.url ?? 'page'}.`,
@@ -242,6 +355,19 @@ function getMetaCostClass(meta, field) {
  * @returns {BridgeSummary}
  */
 export function summarizeBridgeResponse(response, method) {
+  const summarized = summarizeBridgeResponseBody(response, method);
+  const routingNote = response.ok ? getTabRoutingNote(response.meta) : null;
+  return routingNote
+    ? { ...summarized, summary: `${summarized.summary} ${routingNote}` }
+    : summarized;
+}
+
+/**
+ * @param {BridgeResponse} response
+ * @param {string} [method]
+ * @returns {BridgeSummary}
+ */
+function summarizeBridgeResponseBody(response, method) {
   const protocolWarning = getProtocolWarning(response.meta);
   if (!response.ok) {
     const recovery = response.error.recovery ?? getErrorRecovery(response.error.code);
@@ -350,7 +476,7 @@ export function summarizeBridgeResponse(response, method) {
       access == null
         ? ''
         : access.enabled
-          ? ` Access: ${access.routeReady ? `ready on tab ${access.routeTabId}.` : `enabled${typeof access.reason === 'string' ? ` (${access.reason})` : '.'}`}`
+          ? ` Access: ${access.routeReady ? `ready on tab ${access.routeTabId}.` : `enabled${typeof access.reason === 'string' ? ` (${access.reason})` : '.'}`}${typeof access.workingTabId === 'number' && access.workingTabId !== access.routeTabId ? ` Your working tab is ${access.workingTabId}.` : ''}`
           : ' Access: disabled.';
     const connectedExtensions = Array.isArray(result.connectedExtensions)
       ? /** @type {Array<Record<string, unknown>>} */ (result.connectedExtensions)
@@ -369,7 +495,7 @@ export function summarizeBridgeResponse(response, method) {
         `Daemon: ${result.daemon}. Extension: ${extensionSummary}.${accessSummary}`,
         protocolWarning
       ),
-      evidence: result,
+      evidence: compactHealthEvidence(result),
     };
   }
   if (Array.isArray(result.mcpClients) && Array.isArray(result.skillTargets)) {
@@ -470,6 +596,18 @@ export function summarizeBridgeResponse(response, method) {
       })),
     };
   }
+  if (typeof result.outline === 'string') {
+    const count = typeof result.count === 'number' ? result.count : 0;
+    const refs = result.source === 'dom' ? '; refs work as input targets' : '';
+    return {
+      ok: true,
+      summary: appendProtocolWarning(
+        `Accessibility outline: ${count} node(s)${result.truncated === true ? ', truncated' : ''}${refs}.`,
+        protocolWarning
+      ),
+      evidence: result.outline,
+    };
+  }
   if (
     Array.isArray(result.nodes) &&
     typeof result.total === 'number' &&
@@ -528,6 +666,7 @@ export function summarizeBridgeResponse(response, method) {
       if (Array.isArray(n.children) && n.children.length) {
         entry.childCount = n.children.length;
       }
+      if (n.visible === false) entry.visible = false;
       return entry;
     });
     const isFind = method === 'dom.find_by_text' || method === 'dom.find_by_role';
@@ -545,6 +684,9 @@ export function summarizeBridgeResponse(response, method) {
       } else {
         summary = `Found ${count} matching element(s)${scanned === null ? '' : ` after scanning ${scanned}`}.`;
       }
+      if (typeof result.hiddenMatches === 'number' && result.hiddenMatches > 0) {
+        summary += ` ${result.hiddenMatches} hidden match(es) omitted (includeHidden: true to list).`;
+      }
       return {
         ok: true,
         summary: appendProtocolWarning(summary, protocolWarning),
@@ -754,20 +896,18 @@ export function summarizeBridgeResponse(response, method) {
     return {
       ok: true,
       summary: appendProtocolWarning(
-        `${method} completed via ${execution.actualMode ?? 'dom'}${result.elementRef ? ` on ${result.elementRef}` : ''}.`,
+        `${method} completed via ${execution.actualMode ?? 'dom'}${result.elementRef ? ` on ${result.elementRef}` : ''}.${describeEffects(result.effects)}`,
         protocolWarning
       ),
-      evidence: {
-        elementRef: result.elementRef ?? null,
-        sourceRef: result.sourceRef ?? null,
-        destinationRef: result.destinationRef ?? null,
+      evidence: compactInputEvidence(result, {
+        sourceRef: result.sourceRef ?? undefined,
+        destinationRef: result.destinationRef ?? undefined,
         typed: result.typed,
         checked: result.checked,
         selectedValues: result.selectedValues,
         mode: result.mode,
-        resolution: result.resolution,
-        execution: result.execution,
-      },
+        value: result.value,
+      }),
     };
   }
   if (typeof result.tabId === 'number' && typeof result.url === 'string') {
@@ -1006,6 +1146,18 @@ function getProtocolWarning(meta) {
     : null;
 }
 
+/**
+ * Tell the agent when it kept working in its own tab while the user looked at
+ * a different one, so "this tab" requests can be redirected explicitly.
+ *
+ * @param {Record<string, unknown> | null | undefined} meta
+ * @returns {string | null}
+ */
+function getTabRoutingNote(meta) {
+  if (typeof meta?.tab_id !== 'number' || typeof meta.active_tab_id !== 'number') return null;
+  return `Ran in working tab ${meta.tab_id}; the user's active tab is ${meta.active_tab_id} (pass tabId to switch).`;
+}
+
 /**
  * @param {string} summary
  * @param {string | null} warning

package/packages/protocol/src/types.ts

@@ -166,6 +166,14 @@ export interface BridgeMeta {
   continuation_hint?: string | null;
   automatic_retry?: { attempt: 2; reason: 'retryable_error' };
   stale_recovery?: 'success' | 'failure';
+  /** Agent session for sticky working-tab routing; unset callers share a default. */
+  agent_session?: string;
+  /** Tab the request ran in. */
+  tab_id?: number;
+  /** How the tab was chosen: explicit tabId, the agent's working tab, or the active tab. */
+  tab_routing?: 'explicit' | 'working' | 'active';
+  /** Present when the user's active tab differs from the tab the request ran in. */
+  active_tab_id?: number;
   [key: string]: unknown;
 }
 
@@ -444,13 +452,42 @@ export interface NormalizedStyleQuery extends BridgeParams {
 
 export interface InputTarget {
   elementRef?: string;
+  /** CSS selector; with a locator it narrows the locator's candidates. */
   selector?: string;
+  /** ARIA role, e.g. "button" or "textbox". */
+  role?: string;
+  /** Accessible name (substring, case-insensitive unless exact). */
+  name?: string;
+  /** Visible text of the innermost matching element. */
+  text?: string;
+  /** Associated label text for form controls. */
+  label?: string;
+  placeholder?: string;
+  /** data-testid / data-test-id / data-test / data-qa value. */
+  testId?: string;
+  exact?: boolean;
+  /** Zero-based index among visible locator matches. */
+  nth?: number;
 }
 
-export type InputExecutionMode = 'dom' | 'cdp';
+export interface InputWaitObserveParams {
+  /** Wait up to this long for the target to exist and become actionable (0 disables). */
+  timeoutMs?: number;
+  /** Report post-action effects; true or { settleMs }. Defaults on for click/press_key/select/check. */
+  observe?: boolean | { settleMs?: number } | null;
+}
+
+/** auto picks cdp only when trusted input is likely required (or the debugger is already attached). */
+export type InputExecutionMode = 'dom' | 'cdp' | 'auto';
 
 export interface InputResolutionMetadata {
-  strategy: 'elementRef' | 'selector-first' | 'selector-ranked' | 'stale-recovery';
+  strategy:
+    | 'elementRef'
+    | 'selector-first'
+    | 'selector-ranked'
+    | 'locator-first'
+    | 'locator-ranked'
+    | 'stale-recovery';
   candidateCount: number;
   evaluatedCount: number;
   scrolled: boolean;
@@ -460,6 +497,8 @@ export interface InputResolutionMetadata {
   newRef?: string;
   matchedFields?: string[];
   confidenceBasis?: string;
+  /** Time spent waiting for the target to become actionable. */
+  waitedMs?: number;
 }
 
 export interface InputExecutionMetadata {
@@ -470,7 +509,7 @@ export interface InputExecutionMetadata {
   targetCoordinates?: { x: number; y: number };
 }
 
-export interface InputActionParams {
+export interface InputActionParams extends InputWaitObserveParams {
   target?: InputTarget;
   button?: 'left' | 'middle' | 'right';
   clickCount?: number;
@@ -625,7 +664,7 @@ export interface NormalizedCdpDomSnapshotParams extends BridgeParams {
   computedStyles: string[];
 }
 
-export interface CheckedActionParams {
+export interface CheckedActionParams extends InputWaitObserveParams {
   target?: InputTarget;
   checked?: boolean;
   executionMode?: InputExecutionMode;
@@ -639,7 +678,7 @@ export interface NormalizedCheckedAction extends BridgeParams {
   recoverStale: boolean;
 }
 
-export interface SelectActionParams {
+export interface SelectActionParams extends InputWaitObserveParams {
   target?: InputTarget;
   values?: string[];
   labels?: string[];
@@ -816,6 +855,7 @@ export interface FindByTextParams {
   exact?: boolean;
   selector?: string;
   maxResults?: number;
+  includeHidden?: boolean;
 }
 
 export interface NormalizedFindByTextParams extends BridgeParams {
@@ -823,20 +863,25 @@ export interface NormalizedFindByTextParams extends BridgeParams {
   exact: boolean;
   selector: string;
   maxResults: number;
+  includeHidden: boolean;
 }
 
 export interface FindByRoleParams {
   role?: string;
   name?: string;
+  exact?: boolean;
   selector?: string;
   maxResults?: number;
+  includeHidden?: boolean;
 }
 
 export interface NormalizedFindByRoleParams extends BridgeParams {
   role: string;
   name: string;
+  exact: boolean;
   selector: string;
   maxResults: number;
+  includeHidden: boolean;
 }
 
 export interface GetHtmlParams {
@@ -853,7 +898,7 @@ export interface NormalizedGetHtmlParams extends BridgeParams {
   maxLength: number;
 }
 
-export interface HoverParams {
+export interface HoverParams extends InputWaitObserveParams {
   target?: InputTarget;
   duration?: number;
   modifiers?: string[];
@@ -869,7 +914,7 @@ export interface NormalizedHoverParams extends BridgeParams {
   recoverStale: boolean;
 }
 
-export interface DragParams {
+export interface DragParams extends InputWaitObserveParams {
   source?: InputTarget;
   destination?: InputTarget;
   offsetX?: number;
@@ -1053,6 +1098,10 @@ export interface AccessibilityTreeParams {
   maxNodes?: number;
   compact?: boolean;
   interactiveOnly?: boolean;
+  /** cdp (default): Chrome's AX tree via the debugger. dom: content-script outline with elementRefs, no debugger. */
+  source?: 'cdp' | 'dom';
+  /** outline: one compact `- role "name" [ref]` line per node (default for source=dom). */
+  format?: 'tree' | 'outline';
 }
 
 export interface NormalizedAccessibilityTreeParams extends BridgeParams {
@@ -1061,6 +1110,8 @@ export interface NormalizedAccessibilityTreeParams extends BridgeParams {
   maxNodes: number;
   compact: boolean;
   interactiveOnly: boolean;
+  source?: 'dom';
+  format?: 'outline';
 }
 
 export interface AccessibilityTreeNode {

package/packages/protocol/src/window-access.ts

@@ -0,0 +1,29 @@
+/** Window access metadata shared by the native relay and extension UI. */
+export type EnabledWindowInfo = {
+  windowId: number;
+  title: string;
+  enabledAt: number;
+};
+
+export type BrowserWindowAccess = {
+  extensionId: string;
+  browserName: string | null;
+  profileLabel: string | null;
+  window: EnabledWindowInfo | null;
+  canControl?: boolean;
+};
+
+/** Local extension UI actions. These are not agent RPC methods. */
+export type WindowAction = 'focus' | 'disable';
+
+export type WindowActionCommand = {
+  requestId: string;
+  action: WindowAction;
+  windowId: number;
+  enabledAt: number;
+};
+
+export type WindowActionRequest = WindowActionCommand & { extensionId: string };
+
+export type WindowActionResult = { requestId: string; ok: boolean; error?: string };
+export type WindowActionUiResult = { action: WindowAction; ok: boolean; error?: string };

package/packages/protocol/src/window-actions.js

@@ -0,0 +1,46 @@
+// @ts-check
+
+/**
+ * @param {unknown} value
+ * @returns {import('./window-access.js').WindowActionCommand | null}
+ */
+export function parseWindowActionCommand(value) {
+  if (!value || typeof value !== 'object') return null;
+  const message = /** @type {Record<string, unknown>} */ (value);
+  if (
+    typeof message.requestId !== 'string' ||
+    !message.requestId ||
+    message.requestId.length > 80 ||
+    (message.action !== 'focus' && message.action !== 'disable') ||
+    typeof message.windowId !== 'number' ||
+    !Number.isSafeInteger(message.windowId) ||
+    message.windowId <= 0 ||
+    typeof message.enabledAt !== 'number' ||
+    !Number.isFinite(message.enabledAt) ||
+    message.enabledAt < 0
+  )
+    return null;
+  return {
+    requestId: message.requestId,
+    action: message.action,
+    windowId: message.windowId,
+    enabledAt: message.enabledAt,
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {import('./window-access.js').WindowActionRequest | null}
+ */
+export function parseWindowActionRequest(value) {
+  const command = parseWindowActionCommand(value);
+  if (!command) return null;
+  const message = /** @type {Record<string, unknown>} */ (value);
+  if (
+    typeof message.extensionId !== 'string' ||
+    !message.extensionId ||
+    message.extensionId.length > 80
+  )
+    return null;
+  return { ...command, extensionId: message.extensionId };
+}

package/skills/browser-bridge/SKILL.md

@@ -53,7 +53,8 @@ bbx box <ref>                        # box model dimensions
 bbx find <text>                      # find by text content
 bbx find-role <role> [name]          # find by ARIA role
 bbx wait <selector> [timeoutMs]      # wait for DOM element
-bbx a11y-tree [maxNodes] [maxDepth]  # accessibility tree
+bbx a11y-tree [maxNodes] [maxDepth]  # accessibility tree (CDP)
+bbx call dom.get_accessibility_tree '{"source":"dom","interactiveOnly":true}' # actionable outline with refs
 ```
 
 ### Page & Evaluate
@@ -90,6 +91,8 @@ bbx press-key <key> [ref]            # send key event
 bbx cdp-press-key --tab <id> Escape  # CDP key event without foreground focus
 bbx hover <ref>                      # hover over element
 bbx call input.scroll_into_view '{"target":{"elementRef":"el_123"}}' # ensure target is visible
+bbx call input.click '{"target":{"role":"button","name":"Save"}}' # find + wait + click + effects in one call
+bbx call input.fill '{"target":{"label":"Email"},"value":"a@b.co"}' # locate a field by its label
 bbx call input.click '{"target":{"elementRef":"el_123"},"executionMode":"cdp"}' # optional native click
 bbx patch-style <ref> prop=val...    # apply style patch
 bbx patch-text <ref> <text...>       # apply text patch
@@ -131,10 +134,13 @@ After the Enable cue appears:
 
 After access is enabled:
 
-1. Default routing follows the active tab in that enabled window.
-2. If the user switches tabs in that window, Browser Bridge follows automatically.
-3. Use `tabId` only when you intentionally need a non-active tab in the same enabled window.
-4. Do not stop at a generic "no access" message before making a real Browser Bridge call, because the first denied call is what triggers the UI cue.
+1. Your first tab-bound call binds your session to the active tab: that becomes your **working tab**.
+2. The working tab is sticky. If the user switches to another tab (to read mail, say), your calls keep running in your working tab; they never navigate or type into the tab the user is looking at.
+3. Responses report `meta.tab_id`; when the user's active tab differs, the summary says so (`Ran in working tab 12; the user's active tab is 34`). If the user asks you to work in "this tab", pass that `tabId` once; the explicit tab becomes your new working tab. `tabs.create` and `tabs.activate` also move your working tab.
+4. If your working tab was closed, calls fail with `TAB_MISMATCH` (`reason: working_tab_closed`) instead of silently using another tab; pick a tab with `tabId` or `tabs.list` (which marks `working: true`).
+5. The binding expires after 15 idle minutes.
+6. Do not stop at a generic "no access" message before making a real Browser Bridge call, because the first denied call is what triggers the UI cue.
+7. CLI agents running separate `bbx` processes share one working tab unless each sets `BBX_SESSION=<name>`; MCP sessions are separated automatically.
 
 ## Error Recovery
 
@@ -148,7 +154,7 @@ After access is enabled:
 | `INPUT_FOCUS_CHANGED`     | No       | Inspect focus handlers; do not replay native text automatically                           |
 | `DIALOG_NOT_OPEN`         | No       | Trigger or inspect the dialog again                                                       |
 | `DIALOG_ACTION_CONFLICT`  | No       | Inspect current dialog state; never auto-repeat accept/dismiss                            |
-| `TAB_MISMATCH`            | No       | Tab closed or not found - use `tabs.list` to find an available tab                        |
+| `TAB_MISMATCH`            | No       | Tab closed or not found (`working_tab_closed`: your working tab is gone) - pass `tabId` or use `tabs.list` |
 | `TIMEOUT`                 | Once     | Retry once; if still failing, simplify (smaller `maxNodes`, narrower selector)            |
 | `CONTENT_SCRIPT_UNAVAILABLE` | No     | Switch to a normal http(s) page in the enabled window                                    |
 | `EXTENSION_DISCONNECTED`  | After 3s | Check Chrome is running; `bbx status` to verify, then retry                               |
@@ -181,22 +187,22 @@ they contain no page data, URLs, selectors, payloads, errors, or group names.
 10. **Avoid debugger first** - prefer DOM/content-script methods (`dom.*`, `styles.*`, `layout.get_box_model`, `page.get_console`, `page.get_text`, `page.get_storage`, `page.get_network`) before any debugger-backed method. Escalate to CDP only when those cannot answer the question.
 11. **Evaluate only when needed** - `page.evaluate` is powerful but debugger-backed; use it only when DOM, storage, console, network, or text reads cannot expose the needed state.
 12. **Treat exact storage as sensitive** - use `page.get_storage` for metadata first. Call `sensitive.read` for one exact key only when necessary; never batch or automatically retry it, and never repeat a failed attempt without new evidence.
-12. **Debugger-backed methods are last resort** - treat `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, `page.get_network` with `source: 'cdp'`, input with `executionMode: 'cdp'`, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and all `cdp.*` methods as escalation steps because they attach `chrome.debugger`. `performance.get_metrics` is a raw browser-maintained CDP counter point sample, not Web Vitals.
+12. **Debugger-backed methods are last resort** - treat `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree` with the default CDP source, `page.get_network` with `source: 'cdp'`, input with `executionMode: 'cdp'`, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and all `cdp.*` methods as escalation steps because they attach `chrome.debugger`. `performance.get_metrics` is a raw browser-maintained CDP counter point sample, not Web Vitals.
 13. **Wait after change** - after editing source, wait for expected new text, a selector matching the changed attribute, or a detach/attach remount; waiting for `attached` on a selector that already exists does not prove HMR ran. Use `page.wait_for_load_state` for navigation, not HMR.
 14. **Prime event buffers** - before reproducing a console or fetch/XHR issue, call `page.get_console` and default `page.get_network` once with `clear: true`; then reproduce and read without clearing. CDP all-resource capture instead requires explicit `start`, reproduce, `read`, and `stop` calls.
-15. **Semantic finding** - use `dom.find_by_text` / `dom.find_by_role` when you know the label but not the selector.
+15. **Act on what you can name** - when you know the label but not the selector, put a locator straight into the input target (`{"role":"button","name":"Save"}`, `{"label":"Email"}`, `{"text":"Load more"}`, `{"placeholder":"Search"}`, `{"testId":"submit"}`; add `nth` to pick among matches). Use `dom.find_by_text` / `dom.find_by_role` only when you need to look before acting. Locators and finders search shadow DOM and iframes, use real accessible names (`<label for>`, wrapping labels, `aria-*`, `alt`), and skip hidden matches (`hiddenMatches` counts them; `includeHidden: true` lists them).
 16. **Text extraction** - use `page.extract_content` for articles/documentation, or `page.get_text` for all visible UI text, instead of `dom.query` on body.
 17. **Network monitoring** - use `page.get_network` to inspect API calls; auto-installs interceptor.
-18. **Accessibility tree only when necessary** - `dom.get_accessibility_tree` is debugger-backed; use it when semantic structure cannot be inferred from DOM queries and role/text search.
+18. **Overview with the DOM outline** - for "what can I do on this page?", call `dom.get_accessibility_tree` with `source: "dom"` (add `interactiveOnly: true` for controls only). It returns compact lines like `- button "Save" [el_k7q2_1f] disabled` whose refs work directly as input targets, includes shadow DOM and iframes, and needs no debugger. Reserve the default CDP source for accessibility audits.
 19. **Tailwind-aware** - when `page.get_state` returns `hints.tailwind: true`, load `references/tailwind.md`; avoid selecting by utility classes, prefer `find_by_text`/`find_by_role`; `dom.query` auto-escapes `[]` brackets.
-20. **Verify after input** - a dispatched DOM or CDP event does not prove application state changed. Follow it with the cheapest relevant wait or structured read.
-21. **Do not guess input targets** - for targeted click, focus, type, fill, press-key, checked-state, option-selection, hover, and drag calls, honor actionability errors and returned `resolution` metadata. `cdp_press_key` and `scroll_into_view` use separate contracts. `executionMode` is only `dom` or `cdp`; `input.fill.mode: auto` is a separate DOM setter/keystroke strategy.
+20. **Read the effects before reading the page** - click, press_key, set_checked, select_option, and submitting type/fill return `effects` after a short settle: same-document `url` changes, `navigation: "unloading"`, newly opened `dialogs`, alert/status/live-region `messages`, the `focused` element, `dom` churn, and the target's new state (`value`, `checked`, `expanded`, `removed`). The summary digests them (`Effects: URL → /done; alert: "Saved"`). Only follow up with a read when the effects do not answer the question; `changed: false` means nothing visible happened. Pass `observe: true` to other actions, or `observe: false` to skip the settle.
+21. **Let actions wait** - targeted actions wait up to `timeoutMs` (default 2500, max 15000, `0` disables) for the target to appear, become enabled/visible/unobscured, and stop animating. Do not add a separate `dom.wait_for` before an action. Honor the errors that remain after the wait, plus `resolution.waitedMs`. `cdp_press_key` and `scroll_into_view` use separate contracts; `input.fill.mode: auto` is a separate DOM setter/keystroke strategy.
 22. **Stale recovery stays opt-in** - prefer re-querying. Use `recoverStale: true` once only when the same document/URL and a strong unique semantic descriptor should still identify the target; inspect `recovered`, old/new refs, and matched fields. A scan with more than 100 same-tag candidates fails as `ELEMENT_AMBIGUOUS`/`scan_incomplete` because uniqueness is not provable.
 23. **Dialogs are explicit** - inspect first, then accept or dismiss only when intended. `expectedDialogId` is a pre-dispatch stale-decision check, not an atomic CDP binding; never auto-repeat `DIALOG_ACTION_CONFLICT`.
 24. **DOM diffs use explicit baselines** - call `dom.baseline.create` before the action, `dom.baseline.compare` afterward, then `dom.baseline.release`. Use a narrow selector and bounded evidence. Never substitute unrelated DOM reads for the retained baseline, and recreate it after `DOM_BASELINE_INVALIDATED`.
 25. **HAR export reads an armed capture** - use CDP capture `start`, reproduce, `network.export_har`/`bbx har`, then `stop`. Export never starts, stops, or clears capture. Inspect truncation plus `dropped`, `abandoned`, and `inflight` before claiming completeness.
 26. **Keep timing inside the browser** - for rhythm, games, gestures, or any steps that must happen at set times or back-to-back, send one `input.perform` with the whole schedule (`atMs` from the sequence start, or `delayMs` after the previous step). Never spread timed input across tool calls (each call costs an agent round-trip) and never issue input as parallel tool calls (they land all at once).
-27. **Use trusted input when the page needs a user gesture** - DOM-mode events are untrusted, so Chrome may refuse audio or media start, popups, clipboard writes, and fullscreen. Use `executionMode: "cdp"` (click, hover, drag, type, fill, press_key, touch) for those pages; `input.perform` accepts it once for every step.
+27. **Use trusted input when the page needs a user gesture** - DOM-mode events are untrusted, so Chrome may refuse audio or media start, popups, clipboard writes, and fullscreen. `executionMode: "auto"` picks debugger input only for file inputs, media, `target=_blank` links, rich-text editors, or when the debugger is already attached (`execution.selectionReason` says why). Use `executionMode: "cdp"` to force it (click, hover, drag, type, fill, press_key, touch); `input.perform` accepts it once for every step. If a DOM click reports `changed: false` on a page that should react, retry once with `cdp` rather than repeating the DOM click. CDP input is not available for targets inside iframes.
 28. **Simultaneous presses need touch** - a mouse has one pointer. For chords or multi-finger gestures use `input.touch` with several `points` (optionally `to` end positions for swipes and pinches); add `holdMs` to `input.click`/`input.press_key` when the press must last.
 
 ## Token Budget Quick Rules