@evan_zhong/browser-attach 0.0.0-stage → 0.11.1

package/extension/input.js

@@ -0,0 +1,318 @@
+import { deadline, waitForTarget, delivery } from './actionability.js';
+import { clickOptions } from './click.js';
+
+const BUSY = 'Browser UI may be capturing input (a tab drag or native menu). Finish that interaction, then observe the page before deciding whether to try again. Never replay an unknown outcome automatically.';
+
+export function inputMode(args) {
+  const mode = args.mode ?? 'native';
+  if (!['native', 'dom'].includes(mode)) throw new Error('mode must be native or dom');
+  return mode;
+}
+
+async function bounded(operation, message, ms = 5000) {
+  let timer;
+  try { return await Promise.race([operation, new Promise((resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`${message} Outcome is unknown. ${BUSY}`)), ms);
+  })]); }
+  finally { clearTimeout(timer); }
+}
+
+export function createInput(cdp, value, sessions) {
+  const pending = new Map();
+  function event(tabId, method, params, sessionId) {
+    const operation = pending.get(tabId);
+    if (!operation) return;
+    if (method === 'Page.javascriptDialogOpening') {
+      operation.reject(new Error('The key action opened a JavaScript dialog. It may already have executed; use browser_snapshot and browser_handle_dialog before continuing.'));
+    }
+    if (method !== 'Runtime.bindingCalled' || params.name !== operation.name || !operation.contexts.has(JSON.stringify([sessionId, params.executionContextId]))) return;
+    try { if (JSON.parse(params.payload).delivered === true) operation.resolve(); }
+    catch (error) { operation.reject(error); }
+  }
+  function cancel(tabId) { pending.get(tabId)?.reject(new Error('Tab detached during keyboard input; outcome is unknown. Observe before retrying.')); }
+
+  async function pressKey(tabId, chord, args = {}) {
+    const budget = args.budget || deadline(args.timeout_ms);
+    const send = (...params) => budget.run(() => cdp(...params));
+    const { params, text } = args.character != null ? characterParameters(args.character) : keyParameters(chord);
+    const name = `__attachKey_${crypto.randomUUID().replaceAll('-', '')}`;
+    const contexts = new Set(), guards = [], omittedFrames = [];
+    const receipt = new Promise((resolve, reject) => pending.set(tabId, { name, contexts, resolve, reject }));
+    receipt.catch(() => {});
+    try {
+      const frames = await budget.run(() => sessions.frames(tabId, send));
+      const worlds = new Map();
+      for (const frame of frames) {
+        const target = sessions.target(tabId, frame.id);
+        let contextId;
+        try {
+          const { executionContextId } = await send(target, 'Page.createIsolatedWorld', { frameId: frame.id, worldName: 'browser-attach-input' });
+          if (!executionContextId) throw new Error('Could not create keyboard verification context; no input was dispatched.');
+          contextId = executionContextId;
+          worlds.set(frame.id, { target, contextId, frameId: frame.id });
+          contexts.add(JSON.stringify([target.sessionId, executionContextId]));
+          await send(target, 'Runtime.addBinding', { name, executionContextId });
+          const installed = await send(target, 'Runtime.evaluate', {
+            contextId: executionContextId, expression: `(${installKeyReceipt.toString()})(${JSON.stringify(name)},${JSON.stringify(params)},${budget.remaining() + 500})`,
+            objectGroup: 'browser-attach',
+          });
+          if (installed.exceptionDetails) value(installed);
+          if (!installed.result?.objectId) throw new Error('Could not install keyboard verification; no input was dispatched.');
+          guards.push({ target, objectId: installed.result.objectId });
+        } catch (error) {
+          if (frame.id === frames[0].id) throw error;
+          contexts.delete(JSON.stringify([target.sessionId, contextId]));
+          omittedFrames.push({ frame_id: frame.id, reason: error.message });
+        }
+      }
+      let focusTarget = worlds.get(frames[0].id), focusedNode;
+      const visited = new Set();
+      while (focusTarget) {
+        const { target, contextId } = focusTarget;
+        if (visited.has(contextId + ':' + target.sessionId)) throw new Error('Focus frame cycle; no input was dispatched.');
+        visited.add(contextId + ':' + target.sessionId);
+        const active = await send(target, 'Runtime.evaluate', { contextId,
+          expression: `(${activeElement.toString()})()`, objectGroup: 'browser-attach' });
+        if (!active.result?.objectId) throw new Error('No focused page element is available; no input was dispatched.');
+        const { node } = await send(target, 'DOM.describeNode', { objectId: active.result.objectId });
+        if (node.frameId) {
+          focusTarget = worlds.get(node.frameId);
+          if (!focusTarget) throw new Error('Focused frame is unavailable; no input was dispatched.');
+        } else { focusedNode = { objectId: active.result.objectId }; break; }
+      }
+      await waitForTarget(cdp, value, focusTarget.target, focusedNode, budget);
+      if (args.expectedNode) {
+        const expected = args.expectedNode;
+        const focused = focusTarget.frameId === expected.frameId && value(await send(expected.target, 'Runtime.callFunctionOn', { objectId: expected.objectId,
+          functionDeclaration: 'function() { const a=this.getRootNode().activeElement; return this.isConnected && (a===this || this.contains(a)); }', returnByValue: true }));
+        if (!focused) throw new Error('Typing target lost focus during key preparation; no further key was dispatched');
+      }
+      budget.dispatch();
+      // Queue the complete chord before waiting for acknowledgements. Always
+      // enqueue keyUp, even if keyDown fails or opens a modal.
+      const commands = [send(focusTarget.target, 'Input.dispatchKeyEvent', { type: args.character != null ? 'keyDown' : 'rawKeyDown', ...(args.character != null ? { text, unmodifiedText: text } : {}), ...params })];
+      if (text != null && args.character == null) commands.push(send(focusTarget.target, 'Input.dispatchKeyEvent', { type: 'char', text, unmodifiedText: text, ...params }));
+      commands.push(send(focusTarget.target, 'Input.dispatchKeyEvent', { type: 'keyUp', ...params }));
+      await budget.run(() => delivery(Promise.all([Promise.all(commands), receipt])));
+      return { sent: chord, method: 'native', delivery_verified: true, application_result: 'not_checked',
+        ...(omittedFrames.length ? { verification_omitted_frames: omittedFrames } : {}), observe_again: true };
+    } finally {
+      pending.delete(tabId);
+      const cleanup = guards.flatMap(({ target, objectId }) => [cdp(target, 'Runtime.removeBinding', { name }),
+        cdp(target, 'Runtime.callFunctionOn', { objectId, functionDeclaration: 'function() { this.stop(); }' })]);
+      await bounded(Promise.allSettled(cleanup), 'Keyboard verification cleanup timed out.', 250).catch(() => {});
+    }
+  }
+
+  async function fill(tabId, node, args) {
+    if (!node || typeof args.text !== 'string') throw new Error('fill requires ref or selector, and text');
+    const mode = inputMode(args);
+    const budget = args.budget || deadline(args.timeout_ms), target = node.target;
+    const send = (method, params) => budget.run(() => cdp(target, method, params));
+    await waitForTarget(cdp, value, target, node, budget, { editable: true });
+    budget.dispatch();
+    value(await send('Runtime.callFunctionOn', { objectId: node.objectId, returnByValue: true,
+      functionDeclaration: prepareFill.toString(), arguments: [{ value: mode }, { value: args.text }] }));
+    if (mode === 'native') await send('Input.insertText', { text: args.text });
+    const matches = value(await send('Runtime.callFunctionOn', { objectId: node.objectId, returnByValue: true,
+      functionDeclaration: verifyFill.toString(), arguments: [{ value: args.text }] }));
+    if (matches !== true) throw new Error(`Fill did not retain the requested text. Input may have been swallowed, focus may have moved, or the page may have reformatted it. Outcome is unknown. ${BUSY}`);
+    return { filled: true, method: mode, value_verified: true, ...(mode === 'dom' ? { events_trusted: false } : {}), application_result: 'not_checked', observe_again: true };
+  }
+
+  async function domClick(tabId, node, args) {
+    if (!node || args.x != null || args.y != null) throw new Error('DOM click requires ref or selector; coordinates are unsupported.');
+    clickOptions(args);
+    const budget = args.budget || deadline(args.timeout_ms), target = node.target;
+    const send = (method, params) => budget.run(() => cdp(target, method, params));
+    await waitForTarget(cdp, value, target, node, budget);
+    budget.dispatch();
+    const result = value(await send('Runtime.callFunctionOn', { objectId: node.objectId, returnByValue: true,
+      functionDeclaration: clickElement.toString() }));
+    return { ...result, method: 'dom', events_trusted: false, application_result: 'not_checked', observe_again: true };
+  }
+  async function selectOption(tabId, node, args) {
+    selectOptions(args);
+    const budget = args.budget || deadline(args.timeout_ms);
+    await waitForTarget(cdp, value, node.target, node, budget);
+    budget.dispatch();
+    const result = value(await budget.run(() => cdp(node.target, 'Runtime.callFunctionOn', {
+      objectId: node.objectId, functionDeclaration: selectElement.toString(),
+      arguments: [{ value: { value: args.value, label: args.label, index: args.index } }], returnByValue: true,
+    })));
+    return { ...result, method: 'dom', events_trusted: false, application_result: 'not_checked', observe_again: true };
+  }
+  async function typeText(tabId, node, args) {
+    typeOptions(args);
+    const budget = args.budget || deadline(args.timeout_ms);
+    await waitForTarget(cdp, value, node.target, node, budget, { editable: true });
+    budget.dispatch();
+    value(await budget.run(() => cdp(node.target, 'Runtime.callFunctionOn', { objectId: node.objectId,
+      functionDeclaration: 'function() { this.focus(); if (this.getRootNode().activeElement !== this && !this.contains(this.getRootNode().activeElement)) throw new Error("Field did not receive focus"); }', returnByValue: true })));
+    let typed = 0; const length = Array.from(args.text).length;
+    for (const character of args.text) {
+      const focused = value(await budget.run(() => cdp(node.target, 'Runtime.callFunctionOn', { objectId: node.objectId,
+        functionDeclaration: 'function() { const a=this.getRootNode().activeElement; return this.isConnected && (a===this || this.contains(a)); }', returnByValue: true })));
+      if (!focused) throw new Error(`Typing stopped after ${typed} characters: original field detached or lost focus. Outcome is unknown; do not replay.`);
+      try { await pressKey(tabId, character, { budget, character, expectedNode: node }); }
+      catch (error) { error.message = `Typing stopped after ${typed} verified characters; the current character may already have been delivered. ${error.message}`; throw error; }
+      typed++;
+      if (args.delay_ms && typed < length) await budget.run(() => new Promise(resolve => setTimeout(resolve, args.delay_ms)));
+    }
+    return { typed, method: 'native', events_trusted: true, delivery_verified: true, application_result: 'not_checked', observe_again: true };
+  }
+  return { pressKey, fill, typeText, domClick, selectOption, event, cancel };
+}
+
+function installKeyReceipt(name, params, expiryMs) {
+  const report = globalThis[name];
+  function listener(event) {
+    const modifiers = (event.altKey ? 1 : 0) | (event.ctrlKey ? 2 : 0) | (event.metaKey ? 4 : 0) | (event.shiftKey ? 8 : 0);
+    if (event.isTrusted && event.code === params.code && event.key === params.key && modifiers === params.modifiers) {
+      report(JSON.stringify({ delivered: true })); stop();
+    }
+  }
+  let expiry;
+  function stop() { clearTimeout(expiry); globalThis.removeEventListener('keydown', listener, true); delete globalThis[name]; }
+  globalThis.addEventListener('keydown', listener, true);
+  expiry = setTimeout(stop, expiryMs);
+  return { stop };
+}
+
+const NAMED_KEYS = {
+  Enter: [13, 'Enter'], Tab: [9, 'Tab'], Escape: [27, 'Escape'], Backspace: [8, 'Backspace'],
+  Insert: [45, 'Insert'], Delete: [46, 'Delete'], ArrowLeft: [37, 'ArrowLeft'], ArrowRight: [39, 'ArrowRight'],
+  ArrowUp: [38, 'ArrowUp'], ArrowDown: [40, 'ArrowDown'], Home: [36, 'Home'], End: [35, 'End'],
+  PageUp: [33, 'PageUp'], PageDown: [34, 'PageDown'],
+};
+// Deterministic US keyboard mapping: [plain, shifted, virtual key, physical code].
+const PRINTABLE_KEYS = [
+  [' ', ' ', 32, 'Space'], ['0', ')', 48, 'Digit0'], ['1', '!', 49, 'Digit1'], ['2', '@', 50, 'Digit2'],
+  ['3', '#', 51, 'Digit3'], ['4', '$', 52, 'Digit4'], ['5', '%', 53, 'Digit5'], ['6', '^', 54, 'Digit6'],
+  ['7', '&', 55, 'Digit7'], ['8', '*', 56, 'Digit8'], ['9', '(', 57, 'Digit9'],
+  [';', ':', 186, 'Semicolon'], ['=', '+', 187, 'Equal'], [',', '<', 188, 'Comma'], ['-', '_', 189, 'Minus'],
+  ['.', '>', 190, 'Period'], ['/', '?', 191, 'Slash'], ['`', '~', 192, 'Backquote'],
+  ['[', '{', 219, 'BracketLeft'], ['\\', '|', 220, 'Backslash'], [']', '}', 221, 'BracketRight'], ["'", '"', 222, 'Quote'],
+];
+
+export function keyParameters(chord) {
+  if (typeof chord !== 'string') throw new Error('key must be a string');
+  const modifiers = { Alt: 1, Control: 2, Ctrl: 2, Meta: 4, Shift: 8 };
+  const parts = chord.split('+');
+  let key = parts.pop();
+  // A literal plus may appear alone or at the end of a chord: +, Control++.
+  if (key === '' && parts.at(-1) === '') { key = '+'; parts.pop(); }
+  let mask = 0;
+  for (const part of parts) {
+    if (!Object.hasOwn(modifiers, part)) throw new Error(`Unknown modifier: ${part}`);
+    mask |= modifiers[part];
+  }
+  let entry = Object.hasOwn(NAMED_KEYS, key) ? NAMED_KEYS[key] : null, text;
+  if (!entry && /^F([1-9]|1[0-2])$/.test(key)) entry = [111 + Number(key.slice(1)), key];
+  if (!entry && /^[a-zA-Z]$/.test(key)) {
+    entry = [key.toUpperCase().charCodeAt(0), `Key${key.toUpperCase()}`];
+    key = mask & 8 ? key.toUpperCase() : key.toLowerCase();
+    if ((mask & ~8) === 0) text = key;
+  }
+  if (!entry) {
+    const row = PRINTABLE_KEYS.find(([plain, shifted, , code]) => key === plain || key === shifted || key === code || (key === 'Plus' && shifted === '+'));
+    if (row) {
+      const [plain, shifted, vk, code] = row;
+      if (plain !== shifted && (key === shifted || key === 'Plus')) mask |= 8;
+      key = mask & 8 ? shifted : plain;
+      entry = [vk, code];
+      if ((mask & ~8) === 0) text = key;
+    }
+  }
+  if (!entry) throw new Error('Unsupported key. Use F1-F12, a named navigation/editing key, ASCII letter/digit or US punctuation.');
+  if ((mask & ~8) === 0 && key === 'Enter') text = '\r';
+  if (mask === 0 && key === 'Tab') text = '\t';
+  return { params: { key, code: entry[1], windowsVirtualKeyCode: entry[0], nativeVirtualKeyCode: entry[0], modifiers: mask }, text };
+}
+
+function prepareFill(mode, text) {
+  const tag = this.tagName?.toLowerCase();
+  if (!this.isConnected) throw new Error('Field is detached');
+  if (this.disabled || this.readOnly || this.closest('[inert]')) throw new Error('Field is disabled, read-only or inert');
+  if (!['input', 'textarea'].includes(tag) && !this.isContentEditable) throw new Error('Ref is not an editable field');
+  if (tag === 'input' && !['text', 'search', 'email', 'password', 'tel', 'url', ''].includes(this.type)) throw new Error('Input type cannot be filled with text');
+  if (mode === 'dom') {
+    const win = this.ownerDocument.defaultView;
+    if (this.isContentEditable) this.textContent = text;
+    else {
+      const prototype = tag === 'textarea' ? win.HTMLTextAreaElement.prototype : win.HTMLInputElement.prototype;
+      Object.getOwnPropertyDescriptor(prototype, 'value').set.call(this, text);
+    }
+    this.dispatchEvent(new win.InputEvent('input', { bubbles: true, composed: true, inputType: 'insertReplacementText', data: text }));
+    this.dispatchEvent(new win.Event('change', { bubbles: true }));
+  } else {
+    this.focus();
+    const active = this.getRootNode().activeElement;
+    if (active !== this && !this.contains(active)) throw new Error('Field did not receive focus');
+    if (this.isContentEditable) {
+      const range = this.ownerDocument.createRange(); range.selectNodeContents(this);
+      const selection = this.ownerDocument.getSelection(); selection.removeAllRanges(); selection.addRange(range);
+    } else this.select();
+  }
+  return true;
+}
+
+function verifyFill(text) {
+  // Native editing may represent line breaks using nested blocks or <br>.
+  return this.isConnected && (this.isContentEditable ? this.textContent === text || this.innerText === text : this.value === text);
+}
+
+function clickElement() {
+  const element = this.nodeType === 3 ? this.parentElement : this;
+  if (!element?.isConnected) throw new Error('Element is detached');
+  if (element.matches(':disabled') || element.closest('[inert]')) throw new Error('Element is disabled or inert');
+  const win = element.ownerDocument.defaultView, rect = element.getBoundingClientRect(), style = win.getComputedStyle(element);
+  if (style.visibility !== 'visible' || !rect.width || !rect.height) throw new Error('Element is not visible');
+  if (!(element instanceof win.HTMLElement)) throw new Error('DOM click supports HTML elements only; use native input for this ref.');
+  win.HTMLElement.prototype.click.call(element);
+  return { clicked: true };
+}
+
+function activeElement() {
+  let element = document.activeElement;
+  while (element?.shadowRoot?.activeElement) element = element.shadowRoot.activeElement;
+  return element;
+}
+
+export function selectOptions(args) {
+  if (['value', 'label', 'index'].filter(key => args[key] != null).length !== 1) throw new Error('Provide exactly one of value, label or index');
+  if (args.index != null && (!Number.isSafeInteger(args.index) || args.index < 0)) throw new Error('index must be a nonnegative safe integer');
+  for (const key of ['value', 'label']) if (args[key] != null && typeof args[key] !== 'string') throw new Error(`${key} must be a string`);
+}
+
+export function selectElement(choice) {
+  if (this.tagName !== 'SELECT' || !this.isConnected) throw new Error('Target must be a connected HTML select');
+  if (this.matches(':disabled') || this.closest('[inert]')) throw new Error('Select is disabled or inert');
+  const options = Array.from(this.options);
+  const matches = options.filter((option, index) => choice.index != null ? index === choice.index : choice.value != null ? option.value === choice.value : option.label === choice.label);
+  if (matches.length !== 1) throw new Error(`Option must match exactly once; matched ${matches.length}. Use an explicit index for duplicate labels/values. No value was set.`);
+  const option = matches[0];
+  if (option.disabled || option.parentElement?.tagName === 'OPTGROUP' && option.parentElement.disabled) throw new Error('Option is disabled; no value was set');
+  const win = this.ownerDocument.defaultView;
+  const index = options.indexOf(option);
+  Object.getOwnPropertyDescriptor(win.HTMLSelectElement.prototype, 'selectedIndex').set.call(this, index);
+  this.dispatchEvent(new win.Event('input', { bubbles: true, composed: true }));
+  this.dispatchEvent(new win.Event('change', { bubbles: true }));
+  if (!this.isConnected || this.selectedIndex !== index || this.options[index] !== option || !option.selected) throw new Error('Select did not retain the requested option. Outcome is unknown; observe before continuing.');
+  return { selected: true, index, value: option.value, label: option.label, value_verified: true };
+}
+
+export function typeOptions(args) {
+  if (typeof args.text !== 'string' || args.text.length > 10000 || /[\r\n\t\x00-\x1f]/.test(args.text)) throw new Error('type text must contain at most 10000 characters');
+  if (!Number.isInteger(args.delay_ms ?? 0) || (args.delay_ms ?? 0) < 0 || (args.delay_ms ?? 0) > 1000) throw new Error('delay_ms must be 0..1000');
+}
+
+export function characterParameters(character) {
+  if (typeof character !== 'string' || Array.from(character).length !== 1 || /[\r\n\t\x00-\x1f]/.test(character)) throw new Error('type accepts printable characters; use press_key for control keys');
+  try {
+    const result = keyParameters(/^[A-Z]$/.test(character) ? `Shift+${character}` : character);
+    return { params: { ...result.params, key: character }, text: character };
+  } catch {
+    return { params: { key: character, code: '', windowsVirtualKeyCode: 0, nativeVirtualKeyCode: 0, modifiers: 0 }, text: character };
+  }
+}

package/extension/limits.js

@@ -0,0 +1,6 @@
+// Navigation can use its full wait budget plus a bounded observation phase.
+// Leave transport headroom so this never releases an otherwise healthy claim.
+export const NAVIGATION_MAX_TIMEOUT_MS = 40000;
+export const NAVIGATION_OBSERVATION_TIMEOUT_MS = 10000;
+export const HUB_OPERATION_TIMEOUT_MS = 60000;
+export const CLIENT_RESPONSE_TIMEOUT_MS = 65000;

package/extension/locator.js

@@ -0,0 +1,115 @@
+// Selectors are reusable queries, never identities inferred from old AX text.
+export function targetOptions(args, { coordinates = false } = {}) {
+  const hasRef = args.ref != null, hasSelector = args.selector != null;
+  const hasPoint = args.x != null || args.y != null;
+  if (Number(hasRef) + Number(hasSelector) + Number(hasPoint) !== 1 ||
+      (hasPoint && (!coordinates || !Number.isFinite(args.x) || !Number.isFinite(args.y)))) {
+    throw new Error(coordinates ? 'Provide exactly one of ref, selector, or both finite x and y' : 'Provide exactly one of ref or selector');
+  }
+  if (hasRef && (typeof args.ref !== 'string' || !args.ref)) throw new Error('ref must be nonempty');
+  if (hasSelector && (typeof args.selector !== 'string' || !args.selector.trim() || args.selector.length > 10000)) throw new Error('selector must contain 1..10000 characters');
+  if (args.selector_type != null && !['css', 'xpath'].includes(args.selector_type)) throw new Error('selector_type must be css or xpath');
+  frameOptions(args);
+  if (!hasSelector && (args.frame_id != null || args.frame != null || args.selector_type != null)) throw new Error('frame_id and selector_type require selector');
+  if (args.nth != null && (!hasSelector || !Number.isSafeInteger(args.nth) || args.nth < 0)) throw new Error('nth requires selector and must be a nonnegative safe integer (zero-based)');
+  if (args.coordinate_space != null && (!hasPoint || !['viewport', 'document'].includes(args.coordinate_space))) throw new Error('coordinate_space must be viewport or document and applies to coordinate clicks only');
+}
+
+export function queryElement(selector, type = 'css', nth, waitForMatch = false) {
+  if (nth != null && (!Number.isSafeInteger(nth) || nth < 0)) throw new Error('nth must be a nonnegative safe integer (zero-based)');
+  let element, count;
+  if (type === 'xpath') {
+    const result = document.evaluate(selector, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+    count = result.snapshotLength; element = result.snapshotItem(nth ?? 0);
+  } else {
+    const elements = document.querySelectorAll(selector);
+    count = elements.length; element = elements[nth ?? 0];
+  }
+  if (waitForMatch && (count === 0 || (nth != null && nth >= count))) return null;
+  if (nth == null && count !== 1) throw new Error(`Selector must match exactly one element; matched ${count}. Scope the selector or provide an explicit zero-based nth.`);
+  if (nth != null && nth >= count) throw new Error(`Selector nth=${nth} is out of range; matched ${count}`);
+  if (element.nodeType !== 1) throw new Error('Selector must resolve to an element');
+  return element;
+}
+
+export async function resolveSelector(cdp, value, sessions, tabId, args, budget) {
+  const frameId = await resolveFrame(cdp, value, sessions, tabId, args, budget);
+  const target = sessions.target(tabId, frameId);
+  const send = (method, params) => budget.run(() => cdp(target, method, params));
+  const { executionContextId } = await send('Page.createIsolatedWorld', { frameId, worldName: 'browser-attach-locator' });
+  let result;
+  while (true) {
+    result = await send('Runtime.evaluate', { contextId: executionContextId, objectGroup: 'browser-attach',
+      expression: `(${queryElement.toString()})(${JSON.stringify(args.selector)},${JSON.stringify(args.selector_type ?? 'css')},${args.nth ?? 'undefined'},true)` });
+    value(result);
+    if (result.result?.subtype !== 'null') break;
+    budget.describe?.(`selector ${JSON.stringify(args.selector)}${args.nth == null ? '' : ` nth=${args.nth}`} to appear; current=no matching element`);
+    await budget.run(() => new Promise(resolve => setTimeout(resolve, 20)));
+  }
+  if (!result.result?.objectId) throw new Error('Selector did not resolve to an element');
+  const { node } = await send('DOM.describeNode', { objectId: result.result.objectId });
+  // Hit-test refs resolve in the default world too. CDP forbids passing object
+  // arguments between worlds, even when both wrappers refer to the same node.
+  const resolved = await send('DOM.resolveNode', { backendNodeId: node.backendNodeId, objectGroup: 'browser-attach' });
+  if (!resolved.object?.objectId) throw new Error('Selector target detached before resolution; no input was dispatched');
+  return { target, frameId, objectId: resolved.object.objectId, backendNodeId: node.backendNodeId };
+}
+
+export function frameOptions(args) {
+  if (args.frame_id != null && args.frame != null) throw new Error('Provide frame_id or frame, never both');
+  const frame = args.frame;
+  if (frame == null) return;
+  if (typeof frame !== 'object' || Array.isArray(frame) || !Object.keys(frame).length || Object.keys(frame).some(key => !['url', 'title', 'path'].includes(key))) throw new Error('frame requires url, title or a CSS iframe path');
+  for (const key of ['url', 'title']) if (frame[key] != null && (typeof frame[key] !== 'string' || !frame[key])) throw new Error(`frame.${key} must be nonempty`);
+  if (frame.path != null && (!Array.isArray(frame.path) || frame.path.length < 1 || frame.path.length > 16 || frame.path.some(s => typeof s !== 'string' || !s.trim() || s.length > 10000))) throw new Error('frame.path must contain 1..16 CSS iframe selectors');
+}
+
+async function resolveFrameOnce(cdp, value, sessions, tabId, args, budget) {
+  frameOptions(args);
+  const frames = await budget.run(() => sessions.frames(tabId));
+  if (args.frame_id != null) {
+    if (!frames.some(f => f.id === args.frame_id)) throw new Error('frame_id is unknown; take a new snapshot');
+    return args.frame_id;
+  }
+  if (!args.frame) return frames[0].id;
+  const scope = args.frame;
+  let frameId = frames[0].id;
+  for (const selector of scope.path || []) {
+    const target = sessions.target(tabId, frameId);
+    const send = (method, params) => budget.run(() => cdp(target, method, params));
+    const { executionContextId } = await send('Page.createIsolatedWorld', { frameId, worldName: 'browser-attach-locator' });
+    const result = await send('Runtime.evaluate', { contextId: executionContextId, expression: `(${queryElement.toString()})(${JSON.stringify(selector)},"css")`, objectGroup: 'browser-attach-frame' });
+    value(result);
+    try {
+      const { node } = await send('DOM.describeNode', { objectId: result.result.objectId });
+      if (!['IFRAME', 'FRAME'].includes(node.nodeName)) throw new Error('frame.path must resolve to iframe/frame elements');
+      frameId = node.frameId || node.contentDocument?.frameId;
+      if (!frameId) throw new Error('Frame document is not available yet');
+    } finally { await send('Runtime.releaseObjectGroup', { objectGroup: 'browser-attach-frame' }); }
+  }
+  const candidates = scope.path ? frames.filter(f => f.id === frameId) : frames.filter(f => f.id !== frames[0].id);
+  const matches = [];
+  for (const frame of candidates) {
+    if (scope.url != null && frame.url !== scope.url) continue;
+    if (scope.title != null) {
+      const target = sessions.target(tabId, frame.id);
+      const { executionContextId } = await budget.run(() => cdp(target, 'Page.createIsolatedWorld', { frameId: frame.id, worldName: 'browser-attach-locator' }));
+      const title = value(await budget.run(() => cdp(target, 'Runtime.evaluate', { contextId: executionContextId, expression: 'document.title', returnByValue: true })));
+      if (title !== scope.title) continue;
+    }
+    matches.push(frame.id);
+  }
+  if (matches.length !== 1) throw new Error(`Frame locator must match exactly once; matched ${matches.length}`);
+  return matches[0];
+}
+
+export async function resolveFrame(cdp, value, sessions, tabId, args, budget) {
+  while (true) {
+    try { return await resolveFrameOnce(cdp, value, sessions, tabId, args, budget); }
+    catch (error) {
+      if (!/Frame locator.*matched 0|Frame document.*not available|Selector.*matched 0|context.*destroyed|cannot find context/i.test(error.message)) throw error;
+      budget.describe?.(`frame ${JSON.stringify(args.frame)}; current=${error.message}`);
+      await budget.run(() => new Promise(resolve => setTimeout(resolve, 20)));
+    }
+  }
+}

package/extension/manifest.json

@@ -0,0 +1,34 @@
+{
+  "manifest_version": 3,
+  "name": "BrowserAttach",
+  "version": "0.11.1",
+  "description": "Connect existing Chrome and Edge tabs to a locally paired MCP client.",
+  "minimum_chrome_version": "125",
+  "permissions": [
+    "debugger",
+    "tabs",
+    "tabGroups",
+    "storage",
+    "alarms"
+  ],
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+  "action": {
+    "default_popup": "popup.html",
+    "default_title": "BrowserAttach",
+    "default_icon": {
+      "16": "icons/BrowserAttach.png",
+      "32": "icons/BrowserAttach.png"
+    }
+  },
+  "options_page": "options.html",
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs+qDiHd5PWudXHWlZavUGxYrk/oVDs8NXbgzdjGKQvJr0QUhM9OiurLQvAkNWfabdvWAT0iCl0TwZqeoe86cypci5H+mgBuSsW7LbEH5Le7eLRlgxOGIERZO+4e6ztyvsVe4QgYfNgS+uPZtovEVfbDh+VCr0EyUzXeqDR0DRdzz+3lkYtLutgBzna7XUYmKXH9tkPBL32A7Diu1RT2E3I40ydurreLTJ71TH9D8LJF4zGbG1/7VUqkxMGcIZEEvJod2achB12TQvo8tCCNeMijt4UdRudl2G1+axjjRJwyWDjes9tH4AjHyhmX3Ynn42Kf5LmkvyAsKx6yEApRF6wIDAQAB",
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:47831"
+  },
+  "icons": {
+    "128": "icons/BrowserAttach.png"
+  }
+}

package/extension/navigation.js

@@ -0,0 +1,65 @@
+import { NAVIGATION_MAX_TIMEOUT_MS } from './limits.js';
+
+// Lifecycle events can precede the Page.navigate reply. Keep them until its loader is known.
+export function createNavigation(cdp) {
+  const pending = new Map();
+  function event(tabId, method, params) { pending.get(tabId)?.event(method, params); }
+  function cancel(tabId, reason) { pending.get(tabId)?.cancel(reason); }
+  async function navigate(tabId, url, { wait_until = 'domcontentloaded', timeout_ms = 15000, direction } = {}) {
+    if (!['commit', 'domcontentloaded', 'load'].includes(wait_until)) throw new Error('wait_until must be commit, domcontentloaded or load');
+    if (!Number.isInteger(timeout_ms) || timeout_ms < 100 || timeout_ms > NAVIGATION_MAX_TIMEOUT_MS) throw new Error('timeout_ms must be 100..40000');
+    const end = Date.now() + timeout_ms;
+    async function prepare(method) {
+      const remaining = end - Date.now(); let timer;
+      try {
+        if (remaining <= 0) throw new Error('Navigation preparation timed out; no navigation was dispatched');
+        return await Promise.race([cdp(tabId, method), new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error('Navigation preparation timed out; no navigation was dispatched')), remaining); })]);
+      } finally { clearTimeout(timer); }
+    }
+    let entry, mainId;
+    if (direction != null) {
+      if (!['back', 'forward'].includes(direction) || url != null) throw new Error('Provide URL or direction=back/forward, never both');
+      const history = await prepare('Page.getNavigationHistory');
+      entry = history.entries[history.currentIndex + (direction === 'back' ? -1 : 1)];
+      if (!entry) throw new Error(`No ${direction} history entry; no navigation was dispatched`);
+      const destination = new URL(entry.url);
+      if (!['http:', 'https:'].includes(destination.protocol) || destination.username || destination.password) throw new Error('History entry is outside supported HTTP(S) scope; no navigation was dispatched');
+      mainId = (await prepare('Page.getFrameTree')).frameTree.frame.id;
+    }
+    let result, resolveDone, rejectDone, timer;
+    const events = [];
+    const done = new Promise((resolve, reject) => { resolveDone = resolve; rejectDone = reject; });
+    function check() {
+      if (!result) return;
+      if (direction) {
+        const commit = events.find(e => e.method === 'Page.frameNavigated' && e.frame.id === mainId && !e.frame.parentId || e.method === 'Page.navigatedWithinDocument' && e.frameId === mainId);
+        if (!commit) return;
+        const same = commit.method === 'Page.navigatedWithinDocument';
+        if (same || wait_until === 'commit' || commit.type === 'BackForwardCacheRestore' || events.some(e => e.method === 'Page.lifecycleEvent' && e.frameId === mainId && e.loaderId === commit.frame?.loaderId && e.name === (wait_until === 'load' ? 'load' : 'DOMContentLoaded'))) {
+          result = { frameId: mainId, ...(same ? {} : { loaderId: commit.frame.loaderId || 'history' }) }; resolveDone(result);
+        }
+        return;
+      }
+      // A successful reply without loaderId denotes a same-document navigation.
+      if (wait_until === 'commit' || !result.loaderId || events.some(event =>
+        event.frameId === result.frameId && event.loaderId === result.loaderId &&
+        event.name === (wait_until === 'load' ? 'load' : 'DOMContentLoaded'))) resolveDone(result);
+    }
+    pending.set(tabId, {
+      event(method, params) { if (['Page.lifecycleEvent', 'Page.frameNavigated', 'Page.navigatedWithinDocument'].includes(method)) { events.push({ method, ...params }); check(); } },
+      cancel(reason) { rejectDone(reason || new Error('Tab detached during navigation; outcome is unknown.')); },
+    });
+    timer = setTimeout(() => rejectDone(new Error(`Navigation did not reach ${wait_until} within ${timeout_ms} ms. It may still be loading; observe the tab before another action.`)), Math.max(0, end - Date.now()));
+    try {
+      // Attach rejection handlers immediately, including when the deadline wins first.
+      const command = cdp(tabId, direction ? 'Page.navigateToHistoryEntry' : 'Page.navigate', direction ? { entryId: entry.id } : { url }).then(reply => {
+        if (reply.errorText) throw new Error(`Navigation failed: ${reply.errorText}`);
+        if (reply.isDownload) throw new Error('Navigation started a download instead of a document.');
+        result = direction ? {} : reply; check(); return done;
+      });
+      await Promise.race([command, done]);
+      return { navigated_to: entry?.url || url, ...(direction ? { direction } : {}), wait_until, same_document: !result.loaderId };
+    } finally { clearTimeout(timer); pending.delete(tabId); }
+  }
+  return { event, cancel, navigate };
+}

package/extension/options.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<html lang="zh-CN"><meta charset="utf-8"><link rel="stylesheet" href="ui.css">
+<body><main><div class="brand"><img src="icons/BrowserAttach.png" alt="" width="36" height="36"><span>BrowserAttach</span></div><h1>浏览器配置实例</h1><p>为当前浏览器配置设置一个名称，便于 MCP 在多个 Chrome / Edge 配置中选择。</p>
+<form><label for="profile">实例名称</label><input id="profile" maxlength="80" placeholder="例如：Edge 工作账号" required><button>保存</button></form><p id="saved" role="status"></p>
+<p class="hint">名称只保存在当前浏览器配置中。连接密钥由本机安装程序生成，无需在网页输入。</p>
+<button id="reload" type="button">重新加载扩展</button><p class="hint">更新本机扩展文件后使用；会释放正在控制的标签页。</p></main><script src="options.js"></script></body></html>

package/extension/options.js

@@ -0,0 +1,15 @@
+// This non-web-accessible page is also a local maintenance entry for setup.
+if (location.hash === '#reload') {
+  history.replaceState(null, '', location.pathname);
+  chrome.runtime.reload();
+}
+document.querySelector('#reload').onclick = () => chrome.runtime.reload();
+chrome.storage.local.get('profileName').then(result => { document.querySelector('#profile').value = result.profileName || ''; });
+document.querySelector('form').onsubmit = async event => {
+  event.preventDefault();
+  const profileName = document.querySelector('#profile').value.trim();
+  if (!profileName) return;
+  await chrome.storage.local.set({ profileName });
+  await chrome.runtime.sendMessage({ type: 'reconnect' });
+  document.querySelector('#saved').textContent = '已保存，连接正在更新。';
+};

package/extension/outcomes.js

@@ -0,0 +1,15 @@
+// Observation can confirm a dialog/navigation/mutation, never absence of delivery.
+export async function boundedRead(operation, ms = 300) {
+  let timer;
+  try { return await Promise.race([Promise.resolve().then(operation), new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error('observation did not respond')), ms); })]); }
+  finally { clearTimeout(timer); }
+}
+export function installOutcomeObserver() {
+  let mutations = 0;
+  const observer = new MutationObserver(records => { mutations += records.length; });
+  observer.observe(document, { childList: true, subtree: true, attributes: true, characterData: true });
+  const startUrl = location.href;
+  let expiry = setTimeout(() => observer.disconnect(), 55000);
+  return { read() { mutations += observer.takeRecords().length; return { dom_changed: mutations > 0, mutation_records: mutations, start_url: startUrl, current_url: location.href }; },
+    stop() { clearTimeout(expiry); observer.disconnect(); } };
+}

package/extension/popup.html

@@ -0,0 +1,5 @@
+<!doctype html>
+<html lang="zh-CN"><meta charset="utf-8"><link rel="stylesheet" href="ui.css">
+<body><main><div class="brand"><img src="icons/BrowserAttach.png" alt="" width="36" height="36"><span>BrowserAttach</span></div><p id="status">正在查询连接…</p><p id="profile"></p><p id="claims"></p>
+<button id="release">释放全部标签页</button><button id="reconnect">重新连接</button><button id="settings">配置实例名称</button>
+<p class="hint">只接受本机已配对 MCP 的连接。点击浏览器的停止调试提示也可随时释放控制。</p></main><script src="popup.js"></script></body></html>

package/extension/popup.js

@@ -0,0 +1,10 @@
+async function refresh() {
+  const result = await chrome.runtime.sendMessage({ type: 'status' });
+  document.querySelector('#status').textContent = result.status === 'connected' ? '已连接本地 MCP 服务' : '尚未连接：请先启动 MCP';
+  document.querySelector('#profile').textContent = `${result.browser.family} · ${result.browser.profile_name}`;
+  document.querySelector('#claims').textContent = `正在控制 ${result.claims} 个标签页`;
+}
+document.querySelector('#release').onclick = async () => { await chrome.runtime.sendMessage({ type: 'release_all' }); await refresh(); };
+document.querySelector('#reconnect').onclick = async () => { await chrome.runtime.sendMessage({ type: 'reconnect' }); await refresh(); };
+document.querySelector('#settings').onclick = () => chrome.runtime.openOptionsPage();
+refresh().catch(error => { document.querySelector('#status').textContent = error.message; });

package/extension/scroll.js

@@ -0,0 +1,29 @@
+export function scrollOptions(args) {
+  if (!['dom', 'wheel'].includes(args.mode ?? 'dom')) throw new Error('Scroll mode must be dom or wheel');
+  if (!Number.isFinite(args.delta_x ?? 0) || args.delta_y != null && !Number.isFinite(args.delta_y)) throw new Error('Scroll deltas must be finite');
+  if (!args.until && !Number.isFinite(args.delta_y)) throw new Error('delta_y is required without until');
+  if (args.until) {
+    if (args.mode === 'wheel') throw new Error('until search requires explicit DOM scroll mode');
+    const { text, selector } = args.until;
+    if (typeof text !== 'string' || !text || text.length > 2000 || selector != null && (typeof selector !== 'string' || !selector)) throw new Error('until requires nonempty text and optional CSS selector');
+    if (!Number.isInteger(args.max_steps ?? 100) || (args.max_steps ?? 100) < 1 || (args.max_steps ?? 100) > 500) throw new Error('max_steps must be 1..500');
+  }
+}
+
+export function scrollElement(dx, dy) {
+  if (!this.isConnected) throw new Error('Scroll container is detached');
+  const before = { x: this.scrollLeft, y: this.scrollTop };
+  this.scrollBy({ left: dx, top: dy ?? Math.max(1, this.clientHeight * 0.8), behavior: 'instant' });
+  const after = { x: this.scrollLeft, y: this.scrollTop };
+  return { scrolled: before.x !== after.x || before.y !== after.y, before, after, method: 'dom_scroll', scope: 'element' };
+}
+
+export function findScrollText(text, selector) {
+  if (!this.isConnected) throw new Error('Scroll container detached');
+  const elements = Array.from(this.querySelectorAll(selector || '*'));
+  if (elements.length > 10000) throw new Error('Scroll search exceeds 10000 candidates; scope until.selector');
+  const matches = elements.filter(e => (e.textContent || '').includes(text) && e.getBoundingClientRect().width > 0 && e.getBoundingClientRect().height > 0 && e.ownerDocument.defaultView.getComputedStyle(e).visibility === 'visible');
+  const leaves = matches.filter(e => !matches.some(other => other !== e && e.contains(other)));
+  if (leaves.length > 1) throw new Error(`Scroll text must match one element; matched ${leaves.length}. Scope until.selector`);
+  return leaves[0] || null;
+}