@evan_zhong/browser-attach 0.15.0 → 0.17.0

package/extension/click.js

@@ -1,4 +1,5 @@
 import { deadline, waitForTarget, delivery } from './actionability.js';
+import { offsetOption, timingOption, pause } from './motion.js';
 
 // Native mouse dispatch stays in protocol order without serial compositor acknowledgments.
 export function createClick(cdp, value, viewport, position, sessions, getTab, getWindow) {
@@ -45,10 +46,14 @@ export function createClick(cdp, value, viewport, position, sessions, getTab, ge
   }
   function cancel(tabId) { pending.get(tabId)?.reject(new Error('Tab detached during click; outcome is unknown. Observe before retrying.')); }
   async function prepare(tabId, node, args) {
+    offsetOption(args);
     if (!!node === (args.x != null || args.y != null)) throw new Error('Provide either ref/selector or x/y');
     if (args.coordinate_space != null && !['viewport', 'document'].includes(args.coordinate_space)) throw new Error('coordinate_space must be viewport or document');
     if (node && args.coordinate_space != null) throw new Error('coordinate_space applies to coordinate clicks only');
     const budget = args.budget || deadline(args.timeout_ms);
+    const obstruction = detail => Object.assign(new Error(`${detail}. ${budget.has_dispatched()
+      ? 'Input has already been dispatched. Outcome is unknown; observe before continuing. Do not replay automatically.'
+      : 'No input was dispatched.'}`), { input_dispatched: budget.has_dispatched() });
     let target = node?.target || { tabId };
     const send = (method, params) => budget.run(() => cdp(target, method, params));
     let point, view;
@@ -59,7 +64,7 @@ export function createClick(cdp, value, viewport, position, sessions, getTab, ge
       const { quads } = await send('DOM.getContentQuads', { backendNodeId: node.backendNodeId });
       view = await budget.run(() => viewport(target));
       for (const quad of quads || []) {
-        point = clippedPoint(quad, view);
+        point = clippedPoint(quad, view, args.offset);
         if (point) break;
       }
       if (!point) throw new Error('Element has no visible click point. Inspect a screenshot.');
@@ -120,7 +125,7 @@ export function createClick(cdp, value, viewport, position, sessions, getTab, ge
         objectId: node.objectId, functionDeclaration: 'function(hit) { for (let e = hit; e; e = e.parentNode || e.host) if (e === this) return true; return false; }',
         arguments: [{ objectId: hit.object.objectId }], returnByValue: true,
       }));
-      if (!unblocked) throw new Error('Another element covers this ref. Inspect a new snapshot or screenshot.');
+      if (!unblocked) throw obstruction(`Another element covers this ref. hit_target=${JSON.stringify(hitTarget)}; point=${JSON.stringify(point)}; frame_id=${JSON.stringify(node.frameId)}`);
     }
     // Dispatch through the root widget so overlays in ancestor documents cannot
     // be bypassed by sending directly to an OOPIF widget. Guard every boundary.
@@ -136,7 +141,16 @@ export function createClick(cdp, value, viewport, position, sessions, getTab, ge
       const parentHit = await budget.run(() => cdp(parent.target, 'DOM.getNodeForLocation', {
         x: Math.floor(rootPoint.x + parentView.scroll_x), y: Math.floor(rootPoint.y + parentView.scroll_y), includeUserAgentShadowDOM: true,
       }));
-      if (parentHit.backendNodeId !== owner.backendNodeId) throw new Error('Another element covers this frame. Inspect a new snapshot or screenshot.');
+      if (parentHit.backendNodeId !== owner.backendNodeId) {
+        let blocker;
+        try {
+          const diagnostic = budget.child(200);
+          const resolved = await diagnostic.run(() => cdp(parent.target, 'DOM.resolveNode', { backendNodeId: parentHit.backendNodeId, objectGroup: 'browser-attach' }));
+          blocker = value(await diagnostic.run(() => cdp(parent.target, 'Runtime.callFunctionOn', { objectId: resolved.object.objectId,
+            functionDeclaration: describeHit.toString(), returnByValue: true })));
+        } catch { /* Preserve the obstruction error even if its node disappears. */ }
+        throw obstruction(`Another element covers this frame. hit_target=${JSON.stringify(blocker ?? { backend_node_id: parentHit.backendNodeId })}; point=${JSON.stringify(rootPoint)}; blocked_frame_id=${JSON.stringify(parent.frameId)}`);
+      }
       const ownerFrameId = parent.ownerFrameId || (await budget.run(() => cdp(parent.target, 'Page.getFrameTree'))).frameTree.frame.id;
       boundaries.push({ target: parent.target, backendNodeId: owner.backendNodeId, frameId: ownerFrameId });
       current = parent.target; currentView = parentView;
@@ -151,7 +165,8 @@ export function createClick(cdp, value, viewport, position, sessions, getTab, ge
     if (!options.hover && hitTarget.native_select) throw new Error("Native select popup is unsupported. No input was dispatched. Use browser_select_option by label/value/index; press Esc if a native popup is already open.");
     const name = `__attachClick_${crypto.randomUUID().replaceAll('-', '')}`;
     const guards = [], contexts = new Set();
-    const receipt = new Promise((resolve, reject) => pending.set(tabId, { name, contexts, resolve, reject }));
+    let failure;
+    const receipt = new Promise((resolve, reject) => pending.set(tabId, { name, contexts, resolve, reject(error) { failure = error; reject(error); } }));
     receipt.catch(() => {});
     try {
       const targets = [{ target, frameId: node?.frameId || frameId, backendNodeId: node?.backendNodeId || backendNodeId, leaf: true }, ...boundaries];
@@ -173,7 +188,10 @@ export function createClick(cdp, value, viewport, position, sessions, getTab, ge
       }
       // Recheck the root page after target preparation: a user may have changed
       // tabs/focus while we resolved a frame or installed the event guards.
+      await pause(budget, args.settle_ms);
+      if (failure) throw failure;
       const pageState = await assertReady(tabId, budget);
+      if (failure) throw failure;
       budget.dispatch();
       const dispatch = params => budget.run(() => cdp(tabId, 'Input.dispatchMouseEvent', { ...params, ...rootPoint }));
       const commands = [dispatch({ type: 'mouseMoved', button: 'none', buttons: 0, modifiers: options.modifiers })];
@@ -259,7 +277,13 @@ function installGuard(name, options, expiryMs, verifyDelivery) {
   return { stop };
 }
 
-export function clippedPoint(quad, view) {
+export function clippedPoint(quad, view, offset) {
+  if (offset) {
+    const { x_ratio: x, y_ratio: y } = offset;
+    const point = { x: (1 - y) * ((1 - x) * quad[0] + x * quad[2]) + y * ((1 - x) * quad[6] + x * quad[4]),
+      y: (1 - y) * ((1 - x) * quad[1] + x * quad[3]) + y * ((1 - x) * quad[7] + x * quad[5]) };
+    return point.x >= 0 && point.y >= 0 && point.x < view.width && point.y < view.height ? point : null;
+  }
   let polygon = Array.from({ length: 4 }, (_, i) => ({ x: quad[i * 2], y: quad[i * 2 + 1] }));
   for (const [axis, bound, lower] of [['x', 0, true], ['x', view.width - 0.01, false], ['y', 0, true], ['y', view.height - 0.01, false]]) {
     const input = polygon; polygon = [];
@@ -287,6 +311,11 @@ export function clippedPoint(quad, view) {
 }
 
 export function clickOptions(args) {
+  offsetOption(args);
+  if (args.settle_ms != null) {
+    timingOption(args.settle_ms, 'settle_ms');
+    if (args.mode === 'dom') throw new Error('settle_ms requires native pointer input');
+  }
   const button = args.button ?? 'left', click_count = args.click_count ?? 1, modifiers = args.modifiers ?? [];
   const buttons = { left: [1, 0], middle: [4, 1], right: [2, 2] }, masks = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
   if (!Object.hasOwn(buttons, button)) throw new Error('button must be left, middle or right');

package/extension/connection.js

@@ -0,0 +1,142 @@
+import { compareVersions } from './version.js';
+
+export function createConnection(chrome, CONNECTION, controller) {
+  let socket;
+  let connecting = false;
+  let keepAlive;
+  let reconnect;
+  let status = 'disconnected';
+  let identity;
+  let maintenance = false;
+  let cleanup = Promise.resolve();
+
+  async function release() {
+    const result = await controller.releaseAll();
+    if (result.errors?.length) throw new Error(`Extension cleanup failed: ${result.errors.join('; ')}`);
+  }
+
+  async function prepareReload(version) {
+    const current = chrome.runtime.getManifest().version;
+    if (compareVersions(version, current) <= 0) throw new Error('Reload target must be newer than the running extension');
+    const response = await fetch(chrome.runtime.getURL('manifest.json'), { cache: 'no-store' });
+    if (!response.ok || (await response.json()).version !== version) throw new Error('Extension files do not match the Hub; reload was not attempted');
+    const previous = (await chrome.storage.local.get('reloadAttempt')).reloadAttempt;
+    if (previous?.from === current && previous.target === version) throw new Error('Extension reload did not apply the update; reload manually after checking the extension directory');
+    maintenance = true;
+    await release();
+    await chrome.storage.local.set({ reloadAttempt: { from: current, target: version } });
+  }
+
+  async function getIdentity() {
+    const local = await chrome.storage.local.get(['instanceId', 'profileName']);
+    const session = await chrome.storage.session.get('runId');
+    const instanceId = local.instanceId || crypto.randomUUID();
+    const runId = session.runId || crypto.randomUUID();
+    if (!local.instanceId) await chrome.storage.local.set({ instanceId });
+    if (!session.runId) await chrome.storage.session.set({ runId });
+    const family = /Edg\//.test(navigator.userAgent) ? 'edge' : 'chrome';
+    return { instance_id: instanceId, run_id: runId, family,
+      profile_name: local.profileName || (family === 'edge' ? 'Edge' : 'Chrome'),
+      user_agent: navigator.userAgent, extension_id: chrome.runtime.id, extension_version: chrome.runtime.getManifest().version };
+  }
+
+  async function connect() {
+    if (connecting || socket?.readyState === WebSocket.OPEN) return;
+    connecting = true;
+    try {
+      await cleanup;
+      await release();
+      identity = await getIdentity();
+      const ws = new WebSocket(CONNECTION.url);
+      socket = ws;
+      ws.onopen = () => {
+        ws.send(JSON.stringify({ type: 'hello', token: CONNECTION.token, browser: identity }));
+        keepAlive = setInterval(() => {
+          if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'ping' }));
+        }, 20000);
+      };
+      ws.onmessage = async event => {
+        let request;
+        try {
+          request = JSON.parse(event.data);
+          if (request.type === 'connected') {
+            maintenance = false;
+            status = 'connected';
+            await chrome.storage.local.remove('reloadAttempt');
+            await chrome.action.setBadgeText({ text: 'ON' });
+            await chrome.action.setBadgeBackgroundColor({ color: '#13755b' });
+            return;
+          }
+          if (!request.id) return;
+          let result;
+          if (request.command === 'prepare_upgrade') {
+            maintenance = true;
+            await release();
+            result = { prepared: true };
+          } else if (request.command === 'resume') {
+            maintenance = false;
+            result = { resumed: true };
+          } else if (request.command === 'reload_extension') {
+            await prepareReload(request.arguments?.version);
+            if (ws.readyState !== WebSocket.OPEN) return;
+            ws.send(JSON.stringify({ id: request.id, result: { reloading: true } }));
+            chrome.runtime.reload();
+            return;
+          } else {
+            if (maintenance) throw new Error('Extension is preparing an upgrade');
+            result = await controller.execute(request.owner, request.command, request.arguments || {});
+          }
+          if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ id: request.id, result }));
+        } catch (error) {
+          if (request?.id && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ id: request.id, error: error.message || String(error) }));
+          }
+        }
+      };
+      ws.onclose = () => {
+        clearInterval(keepAlive);
+        status = 'disconnected';
+        connecting = false;
+        cleanup = release().catch(error => { status = error.message; });
+        chrome.action.setBadgeText({ text: 'OFF' }).catch(() => {});
+        scheduleReconnect();
+      };
+      ws.onerror = () => ws.close();
+    } catch (error) {
+      connecting = false;
+      status = error.message;
+      scheduleReconnect();
+    }
+  }
+
+  function scheduleReconnect() {
+    clearTimeout(reconnect);
+    reconnect = setTimeout(connect, 2000);
+  }
+
+  chrome.runtime.onMessage.addListener((message, sender, respond) => {
+    if (sender.id !== chrome.runtime.id) return;
+    if (message.type === 'status') {
+      getIdentity().then(browser => respond({ status, browser, claims: controller.claimedCount() }));
+      return true;
+    }
+    if (message.type === 'reconnect') {
+      if (socket?.readyState === WebSocket.OPEN) socket.close();
+      else connect();
+      respond({ ok: true });
+    }
+    if (message.type === 'release_all') {
+      controller.releaseAll().then(() => respond({ ok: true }));
+      return true;
+    }
+  });
+  chrome.alarms.onAlarm.addListener(alarm => { if (alarm.name === 'connect') connect(); });
+  chrome.runtime.onStartup.addListener(connect);
+  chrome.runtime.onInstalled.addListener(async () => {
+    await chrome.alarms.create('connect', { periodInMinutes: 0.5 });
+    connect();
+  });
+  chrome.alarms.create('connect', { periodInMinutes: 0.5 });
+  connect();
+  return { send(event) { if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify(event)); } };
+}

package/extension/controller.js

@@ -341,8 +341,9 @@ export function createController(api, notify = () => {}) {
         const url = srcIndex >= 0 ? new URL(attributes[srcIndex + 1], frame.url).href : 'about:blank';
         knownFrames.add(childId); frames.push({ id: childId, url });
       }
-      entries.push({ node: false, frameId: frame.id, line: `Frame ${frame.id} ${frame.url}` });
-      entries.push(...renderAX(nodes, token, refs, frame.id, target.sessionId, options));
+      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);
     }
     const metadata = value(await send(tabId, 'Runtime.evaluate', {
       expression: '({title: document.title, url: location.href})', returnByValue: true,

package/extension/drag.js

@@ -1,14 +1,18 @@
 import { deadline, delivery } from './actionability.js';
 import { targetOptions } from './locator.js';
+import { offsetOption, timingOption, pause, trajectoryOption, dragPath } from './motion.js';
 
 export function dragOptions(args) {
   if (!args.source || !args.destination) throw new Error('drag requires source and destination');
   for (const target of [args.source, args.destination]) {
     targetOptions(target, { coordinates: true });
+    offsetOption(target);
     if (target.coordinate_space === 'document' && (target.x < 0 || target.y < 0)) throw new Error('Document coordinates must be finite and nonnegative');
   }
   if (!['pointer', 'html5'].includes(args.mode ?? 'pointer')) throw new Error('drag mode must be pointer or html5');
   if (!Number.isInteger(args.steps ?? 20) || (args.steps ?? 20) < 2 || (args.steps ?? 20) > 100) throw new Error('steps must be 2..100');
+  timingOption(args.settle_ms ?? 0, 'settle_ms');
+  trajectoryOption(args.trajectory);
 }
 
 export function createDrag(cdp, value, mouse, viewport) {
@@ -87,6 +91,7 @@ export function createDrag(cdp, value, mouse, viewport) {
     try {
       await guard(source, 'source');
       if (html5) { interceptEnabled = true; await send('Input.setInterceptDrags', { enabled: true }); }
+      await pause(budget, args.settle_ms);
       await mouse.assertReady(tabId, budget);
       budget.dispatch();
       await move(point);
@@ -100,12 +105,19 @@ export function createDrag(cdp, value, mouse, viewport) {
       const destination = await mouse.prepare(tabId, await resolve(args.destination, budget), { ...args.destination, budget });
       await guard(destination, 'destination');
       const from = point;
+      const path = dragPath(from, destination.point, steps, args.trajectory);
+      if (args.trajectory) {
+        const view = await budget.run(() => viewport(tabId));
+        if (path.some(({ point }) => point.x < 0 || point.y < 0 || point.x >= view.width || point.y >= view.height)) {
+          throw new Error('Drag trajectory leaves the viewport. Outcome is unknown; observe before continuing.');
+        }
+      }
       if (html5) await send('Input.dispatchDragEvent', { type: 'dragEnter', ...point, data });
-      for (let index = 1; index <= steps; index++) {
-        point = { x: from.x + (destination.point.x - from.x) * index / steps, y: from.y + (destination.point.y - from.y) * index / steps };
+      for (const sample of path) {
+        point = sample.point;
         if (html5) await send('Input.dispatchDragEvent', { type: 'dragOver', ...point, data });
         else await move(point);
-        await budget.run(() => new Promise(resolve => setTimeout(resolve, 16)));
+        await budget.run(() => new Promise(resolve => setTimeout(resolve, sample.dt)));
       }
       if (html5) await send('Input.dispatchDragEvent', { type: 'drop', ...point, data });
       await send('Input.dispatchMouseEvent', { type: 'mouseReleased', ...point, button: 'left', buttons: 0, clickCount: 1 });

package/extension/input.js

@@ -1,5 +1,6 @@
 import { deadline, waitForTarget, delivery } from './actionability.js';
 import { clickOptions } from './click.js';
+import { timingOption, pause } from './motion.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.';
 
@@ -157,7 +158,7 @@ export function createInput(cdp, value, sessions) {
       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)));
+      if (typed < length) await pause(budget, args.delay_ms);
     }
     return { typed, method: 'native', events_trusted: true, delivery_verified: true, application_result: 'not_checked', observe_again: true };
   }
@@ -304,7 +305,7 @@ export function selectElement(choice) {
 
 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');
+  timingOption(args.delay_ms ?? 0, 'delay_ms');
 }
 
 export function characterParameters(character) {

package/extension/manifest.json

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

package/extension/motion.js

@@ -0,0 +1,50 @@
+export function timingOption(value, name, max = 1000) {
+  const values = Array.isArray(value) ? value : [value];
+  if ((Array.isArray(value) && value.length !== 2) || values.some(n => !Number.isInteger(n) || n < 0 || n > max) || values.length === 2 && values[0] > values[1]) {
+    throw new Error(`${name} must be 0..${max} or an ordered [min, max] integer pair`);
+  }
+}
+
+export function sampleTiming(value = 0) {
+  return Array.isArray(value) ? value[0] + Math.floor(Math.random() * (value[1] - value[0] + 1)) : value;
+}
+
+export async function pause(budget, value) {
+  const ms = sampleTiming(value);
+  if (ms) await budget.run(() => new Promise(resolve => setTimeout(resolve, ms)));
+}
+
+export function offsetOption(args) {
+  if (args.offset == null) return;
+  if ((!args.ref && !args.selector) || args.mode === 'dom') throw new Error('offset requires a native element target');
+  const offset = args.offset;
+  if (typeof offset !== 'object' || Array.isArray(offset) || Object.keys(offset).some(key => !['x_ratio', 'y_ratio'].includes(key)) ||
+      ![offset.x_ratio, offset.y_ratio].every(n => Number.isFinite(n) && n >= 0 && n <= 1)) throw new Error('offset requires x_ratio and y_ratio in 0..1');
+}
+
+export function trajectoryOption(trajectory) {
+  if (trajectory == null) return;
+  if (typeof trajectory !== 'object' || Array.isArray(trajectory) || Object.keys(trajectory).some(key => !['curve_px', 'duration_ms'].includes(key)) ||
+      !Number.isFinite(trajectory.curve_px) || Math.abs(trajectory.curve_px) > 100) throw new Error('trajectory requires curve_px in -100..100 and duration_ms in 100..5000');
+  if (!Number.isInteger(trajectory.duration_ms) || trajectory.duration_ms < 100 || trajectory.duration_ms > 5000) throw new Error('trajectory duration_ms must be 100..5000');
+}
+
+// Keep both endpoints exact; vary progress and per-step timing only when opted in.
+export function dragPath(from, to, steps, trajectory) {
+  const dx = to.x - from.x, dy = to.y - from.y, length = Math.hypot(dx, dy);
+  if (!trajectory) return Array.from({ length: steps }, (_, index) => ({
+    point: { x: from.x + dx * (index + 1) / steps, y: from.y + dy * (index + 1) / steps }, dt: 16,
+  }));
+  const weights = Array.from({ length: steps }, () => 0.5 + Math.random());
+  const total = weights.reduce((sum, n) => sum + n, 0);
+  let elapsed = 0;
+  return Array.from({ length: steps }, (_, index) => {
+    const dt = weights[index] / total * trajectory.duration_ms;
+    elapsed += dt;
+    const t = index === steps - 1 ? 1 : elapsed / trajectory.duration_ms;
+    const progress = t * t * (3 - 2 * t);
+    const bend = length ? 2 * progress * (1 - progress) * trajectory.curve_px : 0;
+    return { point: index === steps - 1 ? { ...to } : { x: from.x + dx * progress - (length ? dy / length * bend : 0),
+      y: from.y + dy * progress + (length ? dx / length * bend : 0) }, dt };
+  });
+}

package/extension/snapshot.js

@@ -1,15 +1,17 @@
 // Render semantic AX nodes once; page through the same observation without losing refs.
-export function snapshotOptions({ profile = 'full', text = true, text_limit } = {}) {
+export function snapshotOptions({ profile = 'full', text = true, text_limit, query } = {}) {
   if (!['full', 'interactive'].includes(profile)) throw new Error('profile must be full or interactive');
   if (typeof text !== 'boolean') throw new Error('text must be a boolean');
   if (text_limit != null && (!Number.isInteger(text_limit) || text_limit < 0 || text_limit > 10000)) throw new Error('text_limit must be 0..10000');
-  return { profile, text, text_limit: text_limit ?? (profile === 'interactive' ? 80 : null) };
+  if (query != null && (typeof query !== 'string' || !query.trim() || query.length > 2000)) throw new Error('query must contain 1..2000 characters and not be blank');
+  return { profile, text, text_limit: text_limit ?? (profile === 'interactive' ? 80 : null), ...(query != null ? { query } : {}) };
 }
 
 export function renderAX(nodes, token, refs, frameId, sessionId, options = snapshotOptions()) {
   const byId = new Map(nodes.map(node => [node.nodeId, node]));
   const visited = new Set();
   const entries = [];
+  const query = options.query?.toLowerCase();
   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']);
@@ -68,9 +70,11 @@ export function renderAX(nodes, token, refs, frameId, sessionId, options = snaps
     }
     let nextDepth = depth;
     if (!skip) {
-      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 : ''}` });
+      if (query == null || identityName.toLowerCase().includes(query) || String(node.value?.value ?? '').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);
@@ -81,14 +85,15 @@ export function renderAX(nodes, token, refs, frameId, sessionId, options = snaps
   return entries;
 }
 
-export function snapshotPage(state, { max_nodes = 600, max_chars = 24000, cursor, ...view } = {}) {
+export function snapshotPage(state, { max_nodes = 600, max_chars = 24000, cursor, verbose = false, ...view } = {}) {
   if (!Number.isInteger(max_nodes) || max_nodes < 1 || max_nodes > 3000) throw new Error('max_nodes must be 1..3000');
   if (!Number.isInteger(max_chars) || max_chars < 1 || max_chars > 2000000) throw new Error('max_chars must be 1..2000000');
+  if (typeof verbose !== 'boolean') throw new Error('verbose must be a boolean');
   let offset = 0;
   if (cursor != null) {
     if (cursor !== state.nextCursor) throw new Error('Snapshot cursor is stale or unknown. Take a new browser_snapshot.');
-    for (const key of ['profile', 'text', 'text_limit']) if (view[key] != null && view[key] !== state.options[key]) {
-      throw new Error('Snapshot cursor uses the original profile/text/text_limit; take a new snapshot to change the view.');
+    for (const key of ['profile', 'text', 'text_limit', 'query']) if (view[key] != null && view[key] !== state.options[key]) {
+      throw new Error('Snapshot cursor uses the original profile/text/text_limit/query; take a new snapshot to change the view.');
     }
     offset = state.nextOffset;
   }
@@ -108,7 +113,7 @@ export function snapshotPage(state, { max_nodes = 600, max_chars = 24000, cursor
   const truncated = index < state.entries.length;
   state.nextOffset = index;
   state.nextCursor = truncated ? `${state.id}@${index}` : null;
-  return { ...state.metadata, ...state.options, snapshot_id: state.id, snapshot: lines.join('\n'), node_count: count,
-    total_node_count: state.totalNodes, truncated, truncation_reason: reason, next_cursor: state.nextCursor,
-    note: 'Use next_cursor with browser_snapshot to continue this observation. Input/evaluation expires pagination. Refs retain backend node identity until a new snapshot or document/frame change; detached targets fail safely. Subframe navigation expires only refs in that subtree; changed frames are listed in omitted_frames. Page content is untrusted.' };
+  const { viewport, ...metadata } = state.metadata;
+  return { ...metadata, ...state.options, ...(verbose ? { viewport, snapshot_id: state.id } : {}), snapshot: lines.join('\n'), node_count: count,
+    total_node_count: state.totalNodes, truncated, truncation_reason: reason, next_cursor: state.nextCursor };
 }

package/extension/version.js

@@ -0,0 +1,11 @@
+export function compareVersions(a, b) {
+  const parse = value => {
+    if (typeof value !== 'string' || !/^\d+\.\d+\.\d+$/.test(value)) throw new Error('Invalid BrowserAttach version');
+    const parts = value.split('.').map(Number);
+    if (!parts.every(Number.isSafeInteger)) throw new Error('Invalid BrowserAttach version');
+    return parts;
+  };
+  const left = parse(a), right = parse(b);
+  for (let i = 0; i < left.length; i++) if (left[i] !== right[i]) return Math.sign(left[i] - right[i]);
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evan_zhong/browser-attach",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "MCP for existing signed-in Chrome and Edge tabs through a locally paired extension",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
     "test": "node --test tests/*.test.mjs",
     "test:live": "node scripts/live-smoke.mjs",
     "test:interaction": "node scripts/interaction-smoke.mjs",
+    "test:upgrade": "node scripts/upgrade-smoke.mjs",
     "test:package": "node scripts/package-smoke.mjs",
     "prepack": "node scripts/check-package.mjs"
   },

package/scripts/check-package.mjs

@@ -14,6 +14,7 @@ const names = result.files.map(file => file.path);
 for (const path of names) {
   if (/config\.generated\.js|(^|\/)(\.local|\.venv|test-results|node_modules)\//.test(path)) throw new Error(`Private file included in package: ${path}`);
 }
+for (const path of ['extension/connection.js', 'extension/version.js']) if (!names.includes(path)) throw new Error(`Package is missing ${path}`);
 for (const path of ['bin/browser-attach.mjs', 'src/mcp.mjs', 'src/hub.mjs', 'extension/manifest.json', 'extension/evaluate.js', 'extension/fetch.js', 'extension/locator.js', 'extension/batch.js', 'extension/wait.js', 'extension/outcomes.js', 'extension/scroll.js', 'extension/drag.js', 'extension/text.js', 'extension/diagnostics.js', 'extension/sessions.js', 'extension/actionability.js', 'extension/limits.js', 'extension/icons/BrowserAttach.png']) {
   if (!names.includes(path)) throw new Error(`Package is missing ${path}`);
 }

package/src/client.mjs

@@ -5,43 +5,86 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import WebSocket from 'ws';
 import { loadConfig, VERSION } from './config.mjs';
+import { compareVersions } from '../extension/version.js';
 
-export async function hubIsRunning(config) {
+async function hubHealth(config) {
   let response;
   try {
     response = await fetch(`http://127.0.0.1:${config.port}/health`, {
       headers: { Authorization: `Bearer ${config.token}` }, signal: AbortSignal.timeout(1000),
     });
   } catch (error) {
-    if (error.cause?.code === 'ECONNREFUSED' || error.name === 'TimeoutError') return false;
+    if (['ECONNREFUSED', 'ECONNRESET', 'ECONNABORTED', 'UND_ERR_SOCKET'].includes(error.cause?.code) || error.name === 'TimeoutError') return null;
     throw error;
   }
   if (!response.ok) throw new Error('BrowserAttach port is occupied by an unpaired service');
   const health = await response.json();
-  if (health.service !== 'browser-attach' || health.version !== VERSION)
-    throw new Error('Hub version differs from this package; stop the hub and start again.');
-  return true;
+  if (health.service !== 'browser-attach') throw new Error('BrowserAttach port is occupied by another service');
+  compareVersions(health.version, VERSION);
+  return health;
+}
+
+export async function hubIsRunning(config) {
+  const health = await hubHealth(config);
+  if (!health) return false;
+  if (health.version !== VERSION) throw new Error(`Hub ${health.version} differs from this package ${VERSION}; reconnect MCP to coordinate an upgrade`);
+  return health.state === 'ready';
 }
 
 export async function ensureHub(configPath) {
   configPath = resolve(configPath);
   const config = await loadConfig(configPath);
-  if (await hubIsRunning(config)) return config;
+  const deadline = Date.now() + 18000;
+  const expected = new Set();
+  let spawned = false, requested = false, readyAfter = 0, spawnError;
+  while (Date.now() < deadline) {
+    if (spawnError) throw spawnError;
+    const health = await hubHealth(config);
+    if (!health) {
+      if (!spawned) {
+        spawned = true;
+        await spawnHub(configPath, error => { spawnError = error; });
+        readyAfter = Date.now() + 2500;
+      }
+    } else {
+      const comparison = compareVersions(health.version, VERSION);
+      if (comparison > 0) throw new Error(`Hub ${health.version} is newer than this package ${VERSION}; refusing to downgrade`);
+      if (comparison < 0 && health.state == null) {
+        throw new Error(`Hub ${health.version} predates coordinated upgrades; run browser-attach stop, restart MCP, and reload the extension manually if it was already loaded`);
+      }
+      if (comparison < 0 && health.state === 'ready' && !requested) {
+        requested = true;
+        for (const item of health.extensions) expected.add(item.instance_id);
+        const response = await fetch(`http://127.0.0.1:${config.port}/upgrade`, { method: 'POST',
+          headers: { Authorization: `Bearer ${config.token}`, 'X-Browser-Attach-Version': VERSION }, signal: AbortSignal.timeout(10000) });
+        const result = await response.json();
+        if (!response.ok) {
+          const current = await hubHealth(config);
+          if (current && compareVersions(current.version, VERSION) < 0 && !['upgrading', 'stopping'].includes(current.state)) throw new Error(result.error);
+        } else for (const id of result.extensions) expected.add(id);
+      } else if (comparison < 0 && health.state === 'ready' && requested) {
+        throw new Error(health.upgrade_error || 'Hub upgrade did not complete; reconnect MCP to retry');
+      } else if (comparison === 0 && health.state === 'ready') {
+        const failure = health.extensions.find(item => item.error);
+        if (failure) throw new Error(`Extension upgrade failed (${failure.instance_id}): ${failure.error}`);
+        for (const item of health.extensions) if (item.ready) expected.delete(item.instance_id);
+        if (!expected.size && health.extensions.every(item => item.ready) && Date.now() >= readyAfter) return config;
+      }
+    }
+    await new Promise(resolve => setTimeout(resolve, 150));
+  }
+  throw new Error(`Hub/extension upgrade did not become ready${expected.size ? `; waiting for ${[...expected].join(', ')}` : ''}. See ${join(dirname(configPath), 'hub.log')}`);
+}
+
+async function spawnHub(configPath, onError) {
   await mkdir(dirname(configPath), { recursive: true, mode: 0o700 });
   const log = await open(join(dirname(configPath), 'hub.log'), 'a', 0o600);
   const child = spawn(process.execPath, [fileURLToPath(new URL('../bin/browser-attach.mjs', import.meta.url)), 'hub', '--config', configPath], {
     detached: true, windowsHide: true, stdio: ['ignore', log.fd, log.fd],
     env: { ...process.env, BROWSER_ATTACH_HOME: dirname(configPath) },
   });
-  let spawnError;
-  child.on('error', error => { spawnError = error; });
+  child.on('error', onError);
   child.unref(); await log.close();
-  for (let i = 0; i < 40; i++) {
-    if (spawnError) throw spawnError;
-    await new Promise(resolve => setTimeout(resolve, 150));
-    if (await hubIsRunning(config)) return config;
-  }
-  throw new Error(`Hub did not start. See ${join(dirname(configPath), 'hub.log')}`);
 }
 
 export class AttachClient {
@@ -51,7 +94,7 @@ export class AttachClient {
     if (this.connecting) return this.connecting;
     this.connecting = new Promise((resolve, reject) => {
       const ws = new WebSocket(`ws://127.0.0.1:${this.config.port}/client`, {
-        headers: { Authorization: `Bearer ${this.config.token}` }, maxPayload: 24 * 1024 * 1024,
+        headers: { Authorization: `Bearer ${this.config.token}`, 'X-Browser-Attach-Version': VERSION }, maxPayload: 24 * 1024 * 1024,
       });
       this.socket = ws;
       ws.once('open', resolve); ws.once('error', reject);

package/src/config.mjs

@@ -15,13 +15,17 @@ 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.15.0';
+export const VERSION = '0.17.0';
 
 export async function loadConfig(path = DEFAULT_CONFIG) {
   let config;
   try { config = JSON.parse(await readFile(path, 'utf8')); }
   catch (error) { throw new Error(`Cannot read pairing config ${path}${error.code ? ` (${error.code})` : ''}. Run browser-attach setup.`, { cause: error }); }
+  // Pre-0.17 pairings did not record the extension directory; their setup default
+  // was a sibling `extension` directory next to the pairing file.
+  if (config.extension_dir === undefined) config.extension_dir = join(dirname(resolve(path)), 'extension');
   if (typeof config.token !== 'string' || config.token.length < 32 ||
+      typeof config.extension_dir !== 'string' || !isAbsolute(config.extension_dir) ||
       !Number.isInteger(config.port) || config.port < 1024 || config.port > 65535 ||
       !/^[a-p]{32}$/.test(config.extension_id)) throw new Error('Invalid pairing config. Run browser-attach setup.');
   return config;