@evan_zhong/browser-attach 0.17.0 → 0.18.0

package/extension/batch.js

@@ -21,8 +21,8 @@ export function validateSteps(steps, startAt = 0) {
       frameOptions(step);
       scrollOptions(step);
     } else {
-      if (!step.selector || step.ref != null) throw new Error('Batch element actions require selector');
-      targetOptions(step);
+      if ((!step.selector && !(step.action === 'type' && step.focused === true)) || step.ref != null) throw new Error('Batch element actions require selector; type also accepts focused=true');
+      targetOptions(step, { focused: step.action === 'type' });
       if (['click', 'fill'].includes(step.action)) inputMode(step);
       if (step.action === 'click') clickOptions(step);
       if (step.action === 'hover') offsetOption(step);

package/extension/connection.js

@@ -126,7 +126,7 @@ export function createConnection(chrome, CONNECTION, controller) {
       respond({ ok: true });
     }
     if (message.type === 'release_all') {
-      controller.releaseAll().then(() => respond({ ok: true }));
+      release().then(() => respond({ ok: true }), error => respond({ ok: false, error: error.message }));
       return true;
     }
   });

package/extension/controller.js

@@ -343,7 +343,7 @@ export function createController(api, notify = () => {}) {
       }
       const rendered = renderAX(nodes, token, refs, frame.id, target.sessionId, options);
       if (rendered.length || options.query == null) entries.push({ node: false, frameId: frame.id, line: `Frame ${frame.id} ${frame.url}` });
-      entries.push(...rendered);
+      for (const entry of rendered) entries.push(entry);
     }
     const metadata = value(await send(tabId, 'Runtime.evaluate', {
       expression: '({title: document.title, url: location.href})', returnByValue: true,
@@ -431,6 +431,11 @@ export function createController(api, notify = () => {}) {
       });
     }
     if (command === 'read_text') {
+      if (args.selector_type === 'role') {
+        const budget = deadline(5000), node = await resolveSelector(cdp, value, sessions, tabId, args, budget);
+        try { return { ...await budget.run(() => readText(cdp, value, node.target, { ...args, node })), scope: args.frame || args.frame_id ? 'frame' : 'main_frame', frame_id: node.frameId }; }
+        finally { await boundedRead(() => cdp(node.target, 'Runtime.releaseObjectGroup', { objectGroup: 'browser-attach' }), 100).catch(() => {}); }
+      }
       if (!args.frame && !args.frame_id) return await readText(cdp, value, tabId, args);
       const budget = deadline(5000), frameId = await resolveFrame(cdp, value, sessions, tabId, args, budget), target = sessions.target(tabId, frameId);
       const contextId = pageContexts.get(JSON.stringify([tabId, target.sessionId, frameId]));
@@ -440,7 +445,7 @@ export function createController(api, notify = () => {}) {
     if (command === 'screenshot') {
       const view = await viewport(tabId);
       const hasTarget = args.ref != null || args.selector != null;
-      if (!hasTarget && (args.frame || args.frame_id || args.nth != null || args.selector_type)) throw new Error('Element screenshot frame/nth/type requires an element selector');
+      if (!hasTarget && (args.frame || args.frame_id || args.nth != null || args.selector_type || args.name != null)) throw new Error('Element screenshot frame/nth/type/name requires an element selector');
       if (hasTarget && args.full_page) throw new Error('Element target and full_page are mutually exclusive');
       const clip = hasTarget ? await elementClip(tabId, args, view) : args.full_page ? await fullPageClip(tabId) : null;
       const includeIndicators = args.include_indicators === true;
@@ -498,8 +503,8 @@ export function createController(api, notify = () => {}) {
     if (command === 'select_option') selectOptions(args);
     if (command === 'type') typeOptions(args);
     if (command === 'scroll') scrollOptions(args);
-    if (['scroll', 'upload_file'].includes(command) && ['ref', 'selector', 'frame', 'frame_id', 'selector_type', 'nth'].some(key => args[key] != null)) targetOptions(args);
-    if (['click', 'fill', 'type', 'hover', 'select_option'].includes(command)) targetOptions(args, { coordinates: command === 'hover' || command === 'click' && inputMode(args) !== 'dom' });
+    if (['scroll', 'upload_file'].includes(command) && ['ref', 'selector', 'frame', 'frame_id', 'selector_type', 'name', 'nth'].some(key => args[key] != null)) targetOptions(args);
+    if (['click', 'fill', 'type', 'hover', 'select_option'].includes(command)) targetOptions(args, { coordinates: command === 'hover' || command === 'click' && inputMode(args) !== 'dom', focused: command === 'type' });
     if (command === 'click') clickOptions(args);
     if (['click', 'fill', 'type', 'press_key', 'scroll', 'hover', 'select_option', 'upload_file'].includes(command)) args = { ...args, budget: args.budget || deadline(args.timeout_ms) };
     // Check before any renderer preparation or ref invalidation. A rejected

package/extension/evaluate.js

@@ -109,8 +109,8 @@ export function createEvaluations(cdp) {
     }
     const { kind, items, offset, result } = state;
     const length = kind === 'scalar' ? 1 : items.length;
-    const make = end => kind === 'string' ? items.slice(offset, end) : kind === 'array' ? items.slice(offset, end) :
-      kind === 'object' ? Object.fromEntries(items.slice(offset, end)) : items;
+    const make = (end, start = offset) => kind === 'string' || kind === 'array' ? items.slice(start, end) :
+      kind === 'object' ? Object.fromEntries(items.slice(start, end)) : items;
     let low = offset, high = length;
     while (low < high) {
       const mid = Math.ceil((low + high) / 2);
@@ -124,7 +124,9 @@ export function createEvaluations(cdp) {
     }
     state.offset = low;
     state.cursor = low < length ? `${state.token}@${low}` : null;
+    const nextRequired = low < length ? JSON.stringify(make(low + 1, low)).length : null;
     return { ...result, value: make(low), result_kind: kind, has_more: low < length,
+      ...(nextRequired > max ? { next_item: { ...(kind === 'object' ? { key: items[low][0] } : { index: low }), required_chars: nextRequired, exceeds_max_chars: nextRequired > 100000 } } : {}),
       next_cursor: state.cursor, capture_truncated: result.truncated, truncated: result.truncated || low < length };
   }
   return { read, forgetFrame(tabId, frameId) { if (results.get(tabId)?.frameId === frameId) results.delete(tabId); }, forget: tabId => results.delete(tabId) };

package/extension/input.js

@@ -32,6 +32,30 @@ export function createInput(cdp, value, sessions) {
   }
   function cancel(tabId) { pending.get(tabId)?.reject(new Error('Tab detached during keyboard input; outcome is unknown. Observe before retrying.')); }
 
+  async function focusedNode(tabId, budget, worlds, frames) {
+    frames ||= await budget.run(() => sessions.frames(tabId));
+    let frameId = frames[0].id;
+    const visited = new Set();
+    while (true) {
+      if (visited.has(frameId)) throw new Error('Focus frame cycle; no input was dispatched.');
+      visited.add(frameId);
+      let world = worlds?.get(frameId);
+      if (!world) {
+        if (worlds || !frames.some(frame => frame.id === frameId)) throw new Error('Focused frame is unavailable; no input was dispatched.');
+        const target = sessions.target(tabId, frameId);
+        const { executionContextId } = await budget.run(() => cdp(target, 'Page.createIsolatedWorld', { frameId, worldName: 'browser-attach-input' }));
+        world = { target, contextId: executionContextId };
+      }
+      const active = await budget.run(() => cdp(world.target, 'Runtime.evaluate', { contextId: world.contextId,
+        expression: `(${activeElement.toString()})()`, objectGroup: 'browser-attach' }));
+      value(active);
+      if (!active.result?.objectId) throw new Error('No focused page element is available; no input was dispatched.');
+      const { node } = await budget.run(() => cdp(world.target, 'DOM.describeNode', { objectId: active.result.objectId }));
+      if (node.frameId) frameId = node.frameId;
+      else return { target: world.target, frameId, objectId: active.result.objectId, backendNodeId: node.backendNodeId };
+    }
+  }
+
   async function pressKey(tabId, chord, args = {}) {
     const budget = args.budget || deadline(args.timeout_ms);
     const send = (...params) => budget.run(() => cdp(...params));
@@ -66,34 +90,20 @@ export function createInput(cdp, value, sessions) {
           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);
+      const focused = await focusedNode(tabId, budget, worlds, frames);
+      await waitForTarget(cdp, value, focused.target, focused, budget);
       if (args.expectedNode) {
         const expected = args.expectedNode;
-        const focused = focusTarget.frameId === expected.frameId && value(await send(expected.target, 'Runtime.callFunctionOn', { objectId: expected.objectId,
+        const matches = focused.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');
+        if (!matches) 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 }));
+      const commands = [send(focused.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(focused.target, 'Input.dispatchKeyEvent', { type: 'char', text, unmodifiedText: text, ...params }));
+      commands.push(send(focused.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 };
@@ -146,10 +156,13 @@ export function createInput(cdp, value, sessions) {
   async function typeText(tabId, node, args) {
     typeOptions(args);
     const budget = args.budget || deadline(args.timeout_ms);
+    if (args.focused) node = await focusedNode(tabId, budget);
     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 })));
+    if (!args.focused) {
+      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,

package/extension/locator.js

@@ -1,16 +1,18 @@
 // Selectors are reusable queries, never identities inferred from old AX text.
-export function targetOptions(args, { coordinates = false } = {}) {
+export function targetOptions(args, { coordinates = false, focused = 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 ||
+  if (args.focused != null && (args.focused !== true || !focused)) throw new Error('focused=true is only supported by type');
+  if (Number(hasRef) + Number(hasSelector) + Number(hasPoint) + Number(args.focused === true) !== 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');
+    throw new Error(focused ? 'Provide exactly one of ref, selector or focused=true' : 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');
+  if (args.selector_type != null && !['css', 'xpath', 'label', 'placeholder', 'role'].includes(args.selector_type)) throw new Error('selector_type must be css, xpath, label, placeholder or role');
+  if (args.name != null && (args.selector_type !== 'role' || typeof args.name !== 'string' || args.name.length > 10000)) throw new Error('name requires selector_type=role and must be a string of at most 10000 characters');
   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 (!hasSelector && (args.frame_id != null || args.frame != null || args.selector_type != null)) throw new Error('frame/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');
 }
@@ -22,7 +24,13 @@ export function queryElement(selector, type = 'css', nth, waitForMatch = false)
     const result = document.evaluate(selector, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
     count = result.snapshotLength; at = index => result.snapshotItem(index);
   } else {
-    const elements = document.querySelectorAll(selector);
+    const normalize = text => text.replace(/\s+/g, ' ').trim();
+    const elements = type === 'label'
+      ? Array.from(document.querySelectorAll('input,textarea,select,button,meter,output,progress')).filter(element =>
+        Array.from(element.labels || []).some(label => normalize(label.textContent || '') === normalize(selector)))
+      : type === 'placeholder'
+        ? Array.from(document.querySelectorAll('[placeholder]')).filter(element => element.getAttribute('placeholder') === selector)
+        : document.querySelectorAll(selector);
     count = elements.length; at = index => elements[index];
   }
   if (waitForMatch && (count === 0 || (nth != null && nth >= count))) return null;
@@ -43,27 +51,55 @@ export function queryElement(selector, type = 'css', nth, waitForMatch = false)
   return element;
 }
 
-export async function resolveSelector(cdp, value, sessions, tabId, args, budget) {
+export async function resolveSelector(cdp, value, sessions, tabId, args, budget, { wait = true } = {}) {
+  targetOptions(args);
   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;
+  const role = args.selector_type === 'role';
+  const context = role ? null : await send('Page.createIsolatedWorld', { frameId, worldName: 'browser-attach-locator' });
+  let backendNodeId;
   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`);
+    if (role) {
+      const { nodes } = await send('Accessibility.getFullAXTree', { frameId });
+      backendNodeId = matchRole(nodes, args)?.backendDOMNodeId;
+    } else {
+      const result = await send('Runtime.evaluate', { contextId: context.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') {
+        if (!result.result?.objectId) throw new Error('Selector did not resolve to an element');
+        const { node } = await send('DOM.describeNode', { objectId: result.result.objectId });
+        backendNodeId = node.backendNodeId;
+      }
+    }
+    if (backendNodeId != null) break;
+    if (!wait) return null;
+    budget.describe?.(`selector ${JSON.stringify(args.selector)}${args.name == null ? '' : ` name=${JSON.stringify(args.name)}`}${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' });
+  const resolved = await send('DOM.resolveNode', { 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 };
+  return { target, frameId, objectId: resolved.object.objectId, backendNodeId };
+}
+
+export function matchRole(nodes, args) {
+  const byId = new Map(nodes.map(node => [node.nodeId, node]));
+  const children = new Set(nodes.flatMap(node => node.childIds || []));
+  const pending = nodes.filter(node => !children.has(node.nodeId)).reverse(), seen = new Set(), matches = new Map();
+  while (pending.length) {
+    const node = pending.pop();
+    if (!node || seen.has(node.nodeId)) continue;
+    seen.add(node.nodeId);
+    if (!node.ignored && node.backendDOMNodeId && node.role?.value === args.selector &&
+        (args.name == null || String(node.name?.value || '') === args.name)) matches.set(node.backendDOMNodeId, node);
+    for (let i = (node.childIds?.length || 0) - 1; i >= 0; i--) pending.push(byId.get(node.childIds[i]));
+  }
+  const candidates = [...matches.values()];
+  if (args.nth == null && candidates.length > 1) throw new Error(`Role selector must match exactly one element; matched ${candidates.length}. Provide name or an explicit zero-based nth. Candidates: ${JSON.stringify(candidates.slice(0, 10).map((node, nth) => ({ nth, role: node.role?.value, name: String(node.name?.value || '').slice(0, 120) })))}`);
+  return candidates[args.nth ?? 0] || null;
 }
 
 export function frameOptions(args) {

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "BrowserAttach",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Connect existing Chrome and Edge tabs to a locally paired MCP client.",
   "minimum_chrome_version": "125",
   "permissions": [

package/extension/popup.js

@@ -4,7 +4,13 @@ async function refresh() {
   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('#release').onclick = async () => {
+  try {
+    const result = await chrome.runtime.sendMessage({ type: 'release_all' });
+    await refresh();
+    if (!result.ok) document.querySelector('#status').textContent = `释放失败：${result.error}`;
+  } catch (error) { document.querySelector('#status').textContent = `释放失败：${error.message}`; }
+};
 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

@@ -27,10 +27,16 @@ export function scrollState() {
 
 export function findScrollText(text, selector) {
   if (!this.isConnected) throw new Error('Scroll container detached');
-  const elements = Array.from(this.querySelectorAll(selector || '*'));
+  const elements = 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)));
+  const matches = [];
+  for (const element of elements) {
+    if (!(element.textContent || '').includes(text)) continue;
+    const rect = element.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0 && element.ownerDocument.defaultView.getComputedStyle(element).visibility === 'visible') matches.push(element);
+  }
+  // Document order keeps each subtree contiguous, even after filtering.
+  const leaves = matches.filter((element, index) => index === matches.length - 1 || !element.contains(matches[index + 1]));
   if (leaves.length > 1) throw new Error(`Scroll text must match one element; matched ${leaves.length}. Scope until.selector`);
   return leaves[0] || null;
 }

package/extension/snapshot.js

@@ -15,17 +15,71 @@ export function renderAX(nodes, token, refs, frameId, sessionId, options = snaps
   const textRoles = new Set(['StaticText', 'InlineTextBox', 'ListMarker']);
   const controls = new Set(['button', 'checkbox', 'combobox', 'DisclosureTriangle', 'link', 'listbox', 'menuitem',
     'menuitemcheckbox', 'menuitemradio', 'option', 'radio', 'scrollbar', 'searchbox', 'slider', 'spinbutton', 'switch', 'tab', 'textbox', 'treeitem']);
+  const fields = new Set(['checkbox', 'combobox', 'radio', 'searchbox', 'slider', 'spinbutton', 'switch', 'textbox']);
+  const parents = new Map();
+  for (const node of nodes) for (const child of node.childIds || []) parents.set(child, node.nodeId);
+  function contextText(node) {
+    const pending = [node], parts = [];
+    let visited = 0, length = 0;
+    while (pending.length && ++visited <= 32) {
+      const current = pending.pop();
+      if (!current) return null;
+      const role = current.role?.value;
+      if (current.ignored && !['none', 'generic'].includes(role)) continue;
+      if (role === 'StaticText') {
+        const text = String(current.name?.value || '');
+        const separator = parts.length ? 1 : 0;
+        if (length + text.length + separator > 160) return null;
+        parts.push(text); length += text.length + separator;
+      }
+      else {
+        if (!['none', 'generic', 'LabelText', 'paragraph'].includes(role)) return null;
+        if (visited + pending.length + (current.childIds?.length || 0) > 32) return null;
+        for (let i = (current.childIds?.length || 0) - 1; i >= 0; i--) pending.push(byId.get(current.childIds[i]));
+      }
+    }
+    const text = parts.join(' ').replace(/\s+/g, ' ').trim();
+    return !pending.length && text && text.length <= 160 ? text : null;
+  }
+  // Nearby text is observation context, never a replacement for AX identity or
+  // an inferred label locator. Bound both the ancestor search and subtree work.
+  function fieldContext(node) {
+    let child = node;
+    for (let depth = 0; depth < 4; depth++) {
+      const parent = byId.get(parents.get(child.nodeId));
+      if (!parent || !['none', 'generic', 'group'].includes(parent.role?.value)) return null;
+      const pending = [parent];
+      let count = 0, visited = 0;
+      while (pending.length && ++visited <= 64 && count < 2) {
+        const current = pending.pop();
+        if (!current) return null;
+        if (!current.ignored && controls.has(current.role?.value)) count++;
+        if (visited + pending.length + (current.childIds?.length || 0) > 64) return null;
+        for (const id of current.childIds || []) pending.push(byId.get(id));
+      }
+      if (pending.length || count !== 1) return null;
+      const index = parent.childIds.indexOf(child.nodeId);
+      if (index > 0) {
+        const text = contextText(byId.get(parent.childIds[index - 1]));
+        if (text) return text;
+      }
+      child = parent;
+    }
+    return null;
+  }
   let kept;
   if (options.profile === 'interactive') {
     kept = new Set();
-    const parents = new Map();
-    for (const node of nodes) for (const child of node.childIds || []) parents.set(child, node.nodeId);
     function keepText(node) {
-      if (!node || kept.has(node.nodeId)) return;
-      const role = node.role?.value;
-      if (!textRoles.has(role) && !node.ignored && !['none', 'generic'].includes(role)) return;
-      kept.add(node.nodeId);
-      for (const child of node.childIds || []) keepText(byId.get(child));
+      const pending = [node];
+      while (pending.length) {
+        const current = pending.pop();
+        if (!current || kept.has(current.nodeId)) continue;
+        const role = current.role?.value;
+        if (!textRoles.has(role) && !current.ignored && !['none', 'generic'].includes(role)) continue;
+        kept.add(current.nodeId);
+        for (const child of current.childIds || []) pending.push(byId.get(child));
+      }
     }
     for (const node of nodes) {
       if (node.ignored || !node.backendDOMNodeId || !(controls.has(node.role?.value) ||
@@ -37,19 +91,33 @@ export function renderAX(nodes, token, refs, frameId, sessionId, options = snaps
     }
   }
   function plainText(node) {
-    if (!node) return null;
-    const role = node.role?.value;
-    if (textRoles.has(role)) return String(node.name?.value || '');
-    if (!node.ignored && !['none', 'generic'].includes(role)) return null;
-    const parts = (node.childIds || []).map(id => plainText(byId.get(id)));
-    return parts.includes(null) ? null : parts.join(' ');
+    const pending = [node], parts = [];
+    while (pending.length) {
+      const current = pending.pop();
+      if (current === ' ') { parts.push(' '); continue; }
+      if (!current) return null;
+      const role = current.role?.value;
+      if (textRoles.has(role)) { parts.push(String(current.name?.value || '')); continue; }
+      if (!current.ignored && !['none', 'generic'].includes(role)) return null;
+      const children = current.childIds || [];
+      for (let index = children.length - 1; index >= 0; index--) {
+        pending.push(byId.get(children[index]));
+        if (index > 0) pending.push(' ');
+      }
+    }
+    return parts.join('');
   }
-  function render(node, depth, parentName = '') {
-    if (!node || visited.has(node.nodeId)) return;
+  // Preserve preorder and ref numbering without using the JavaScript call stack.
+  const children = new Set();
+  for (const node of nodes) for (const child of node.childIds || []) children.add(child);
+  const pending = nodes.filter(node => !children.has(node.nodeId)).reverse().map(node => ({ node, depth: 0, parentName: '' }));
+  while (pending.length) {
+    const { node, depth, parentName } = pending.pop();
+    if (!node || visited.has(node.nodeId)) continue;
     visited.add(node.nodeId);
-    if (kept && !kept.has(node.nodeId)) return;
+    if (kept && !kept.has(node.nodeId)) continue;
     const role = node.role?.value || 'node';
-    if (role === 'InlineTextBox') return;
+    if (role === 'InlineTextBox') continue;
     let name = String(node.name?.value || '');
     let merged = false;
     if (['listitem', 'paragraph'].includes(role) && !name) {
@@ -60,6 +128,8 @@ export function renderAX(nodes, token, refs, frameId, sessionId, options = snaps
       ['disabled', 'focused', 'expanded', 'checked', 'selected', 'required', 'invalid', 'level'].includes(prop.name)
     ).map(prop => `${prop.name}=${JSON.stringify(prop.value?.value)}`);
     if (node.value?.value != null) states.push(`value=${JSON.stringify(node.value.value)}`);
+    const context = fields.has(role) && !node.ignored ? fieldContext(node) : null;
+    if (context && context !== name) states.push(`context=${JSON.stringify(context)}`);
     const attributes = states.join(' ');
     const skip = node.ignored || (!options.text && textRoles.has(role)) || (['none', 'generic'].includes(role) && !name && !attributes) ||
       (role === 'StaticText' && name === parentName);
@@ -70,18 +140,20 @@ export function renderAX(nodes, token, refs, frameId, sessionId, options = snaps
     }
     let nextDepth = depth;
     if (!skip) {
-      if (query == null || identityName.toLowerCase().includes(query) || String(node.value?.value ?? '').toLowerCase().includes(query)) {
+      if (query == null || identityName.toLowerCase().includes(query) || String(node.value?.value ?? '').toLowerCase().includes(query) || context?.toLowerCase().includes(query)) {
         const ref = node.backendDOMNodeId ? `${token}:${refs.size + 1}` : null;
         if (ref) refs.set(ref, { backendNodeId: node.backendDOMNodeId, frameId, sessionId, role: node.role?.value, name: String(node.name?.value || '') });
         entries.push({ node: true, frameId, line: `${'  '.repeat(Math.min(depth, 24))}${ref ? `[${ref}] ` : ''}${role} ${JSON.stringify(name)}${attributes ? ' ' + attributes : ''}` });
       }
       nextDepth++;
     }
-    if (!merged) for (const child of node.childIds || []) render(byId.get(child), nextDepth, skip ? parentName : identityName);
+    if (!merged) {
+      const childIds = node.childIds || [];
+      for (let index = childIds.length - 1; index >= 0; index--) {
+        pending.push({ node: byId.get(childIds[index]), depth: nextDepth, parentName: skip ? parentName : identityName });
+      }
+    }
   }
-  // AX trees normally have a single root, but ignored roots can be disconnected.
-  const children = new Set(nodes.flatMap(node => node.childIds || []));
-  for (const node of nodes) if (!children.has(node.nodeId)) render(node, 0);
   return entries;
 }
 

package/extension/text.js

@@ -1,21 +1,23 @@
-import { queryElement } from './locator.js';
+import { queryElement, targetOptions } from './locator.js';
 
 export async function readText(cdp, value, tabId, args) {
   const max = args.max_chars ?? 20000, offset = args.offset ?? 0, mode = args.mode ?? 'visible';
   if (!Number.isInteger(max) || max < 1 || max > 100000) throw new Error('max_chars must be 1..100000');
   if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('offset must be 0..9007199254740991');
   if (!['visible', 'text_content', 'value', 'editor'].includes(mode)) throw new Error('read_text mode must be visible, text_content, value or editor');
-  if (args.selector != null && (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');
+  if (args.selector != null || args.selector_type != null || args.name != null || args.nth != null) targetOptions(args);
   if (mode === 'value' || mode === 'editor') {
     if (!args.selector) throw new Error(`${mode} requires selector to identify exactly one field/editor`);
   }
+  const options = { selector: args.selector, selector_type: args.selector_type, nth: args.nth, mode, offset, max_chars: max };
+  if (args.node) return value(await cdp(tabId, 'Runtime.callFunctionOn', { objectId: args.node.objectId, returnByValue: true,
+    functionDeclaration: `function(args) { return (${extractText.toString()})(args, () => this); }`, arguments: [{ value: options }] }));
   return value(await cdp(tabId, 'Runtime.evaluate', { returnByValue: true, ...(args.context_id != null ? { contextId: args.context_id } : {}),
-    expression: `(${extractText.toString()})(${JSON.stringify({ selector: args.selector, selector_type: args.selector_type, mode, offset, max_chars: max })},${queryElement.toString()})` }));
+    expression: `(${extractText.toString()})(${JSON.stringify(options)},${queryElement.toString()})` }));
 }
 
 export function extractText(args, query) {
-  const element = args.selector ? query(args.selector, args.selector_type ?? 'css') : document.body;
+  const element = args.selector ? query(args.selector, args.selector_type ?? 'css', args.nth) : document.body;
   let text, source = args.mode, complete = true;
   if (args.mode === 'visible') { text = element?.innerText ?? ''; complete = false; }
   else if (args.mode === 'text_content') { text = element?.textContent ?? ''; complete = false; }

package/extension/wait.js

@@ -7,7 +7,7 @@ export function waitOptions(args) {
   if (element) {
     targetOptions(args);
     if (!args.selector) throw new Error('Element waits require a reusable selector');
-  } else if (args.selector != null || args.ref != null || args.frame_id != null || args.frame != null || args.nth != null || args.selector_type != null) throw new Error('This wait condition does not use an element target');
+  } else if (args.selector != null || args.ref != null || args.frame_id != null || args.frame != null || args.nth != null || args.selector_type != null || args.name != null) throw new Error('This wait condition does not use an element target');
   if (args.condition === 'text' && (Number(typeof args.expected === 'string') + Number(typeof args.previous === 'string') !== 1)) throw new Error('text wait requires exactly one of expected (substring) or previous (full prior text)');
   if (args.condition === 'url' && typeof args.expected !== 'string') throw new Error('url wait requires expected text (substring)');
   if (args.condition !== 'text' && args.previous != null) throw new Error('previous is only valid for text waits');
@@ -18,7 +18,7 @@ export async function waitFor(cdp, value, sessions, diagnostics, mouse, tabId, a
   waitOptions(args);
   const budget = args.budget || deadline(args.timeout_ms ?? 5000, 'wait');
   let current = 'not observed', previous;
-  const description = `${args.condition}${args.selector ? ` selector=${JSON.stringify(args.selector)}` : ''}${args.expected != null ? ` expected substring=${JSON.stringify(args.expected)}` : ''}${args.previous != null ? ` text different from=${JSON.stringify(args.previous).slice(0, 500)}` : ''}`;
+  const description = `${args.condition}${args.selector ? ` selector=${JSON.stringify(args.selector)}` : ''}${args.name != null ? ` name=${JSON.stringify(args.name)}` : ''}${args.expected != null ? ` expected substring=${JSON.stringify(args.expected)}` : ''}${args.previous != null ? ` text different from=${JSON.stringify(args.previous).slice(0, 500)}` : ''}`;
   try {
     while (true) {
       if (args.condition === 'network_idle') {
@@ -31,9 +31,19 @@ export async function waitFor(cdp, value, sessions, diagnostics, mouse, tabId, a
         try {
           const frameId = await resolveFrame(cdp, value, sessions, tabId, args, budget);
           const target = sessions.target(tabId, frameId);
-          const { executionContextId } = await budget.run(() => cdp(target, 'Page.createIsolatedWorld', { frameId, worldName: 'browser-attach-locator' }));
-          current = value(await budget.run(() => cdp(target, 'Runtime.evaluate', { contextId: executionContextId, returnByValue: true,
-            expression: `(${inspectWait.toString()})((${queryElement.toString()}),(${inspectTarget.toString()}),${JSON.stringify(args)})` })));
+          if (args.selector_type === 'role') {
+            const node = await resolveSelector(cdp, value, sessions, tabId, args, budget, { wait: false });
+            try {
+              current = node ? value(await budget.run(() => cdp(node.target, 'Runtime.callFunctionOn', { objectId: node.objectId, returnByValue: true,
+                functionDeclaration: `function(args) { return (${inspectWait.toString()})(() => this, (${inspectTarget.toString()}), args); }`, arguments: [{ value: { selector: args.selector, condition: args.condition, expected: args.expected, previous: args.previous } }] }))) : { satisfied: false, state: 'absent' };
+            } finally {
+              if (node) await budget.run(() => cdp(node.target, 'Runtime.releaseObjectGroup', { objectGroup: 'browser-attach' }));
+            }
+          } else {
+            const { executionContextId } = await budget.run(() => cdp(target, 'Page.createIsolatedWorld', { frameId, worldName: 'browser-attach-locator' }));
+            current = value(await budget.run(() => cdp(target, 'Runtime.evaluate', { contextId: executionContextId, returnByValue: true,
+              expression: `(${inspectWait.toString()})((${queryElement.toString()}),(${inspectTarget.toString()}),${JSON.stringify(args)})` })));
+          }
           const stable = current?.ready && previous?.ready && JSON.stringify(current) === JSON.stringify(previous);
           if (current?.satisfied && (args.condition !== 'actionable' || stable)) {
             if (args.condition === 'actionable') {
@@ -70,7 +80,7 @@ export function inspectWait(query, inspect, args) {
   if (!element) return { satisfied: false, state: 'absent' };
   if (args.condition === 'attached') return { satisfied: true, state: 'attached' };
   if (args.condition === 'text') {
-    const text = element.textContent || '';
+    const text = element.innerText ?? '';
     return { satisfied: args.previous != null ? text !== args.previous : text.includes(args.expected), text: text.slice(0, 500) };
   }
   const bounds = inspect.call(element);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evan_zhong/browser-attach",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "MCP for existing signed-in Chrome and Edge tabs through a locally paired extension",
   "type": "module",
   "license": "MIT",

package/src/config.mjs

@@ -15,7 +15,7 @@ export const DATA_DIR = configuredHome
   : process.platform === 'win32' ? join(homedir(), '.browser-attach')
     : join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'browser-attach');
 export const DEFAULT_CONFIG = join(DATA_DIR, 'config.json');
-export const VERSION = '0.17.0';
+export const VERSION = '0.18.0';
 
 export async function loadConfig(path = DEFAULT_CONFIG) {
   let config;