@evan_zhong/browser-attach 0.21.0 → 0.22.1

package/extension/locator.js

@@ -1,3 +1,5 @@
+import { checkedValue } from './errors.js';
+
 // Selectors are reusable queries, never identities inferred from old AX text.
 export function targetOptions(args, { coordinates = false, focused = false } = {}) {
   const hasRef = args.ref != null, hasSelector = args.selector != null;
@@ -19,19 +21,26 @@ export function targetOptions(args, { coordinates = false, focused = false } = {
 
 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)');
+  const failure = (message, reason, detail = {}) => Object.assign(new Error(message), {
+    diagnostics: { reason, selector_type: type, ...detail },
+  });
   let element, count, at;
-  if (type === 'xpath') {
-    const result = document.evaluate(selector, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
-    count = result.snapshotLength; at = index => result.snapshotItem(index);
-  } else {
-    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];
+  try {
+    if (type === 'xpath') {
+      const result = document.evaluate(selector, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+      count = result.snapshotLength; at = index => result.snapshotItem(index);
+    } else {
+      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];
+    }
+  } catch (error) {
+    throw failure(error.message, 'selector_invalid');
   }
   if (waitForMatch && (count === 0 || (nth != null && nth >= count))) return null;
   if (nth == null && count !== 1) {
@@ -43,11 +52,12 @@ export function queryElement(selector, type = 'css', nth, waitForMatch = false)
         disabled: node.matches(':disabled') || !!node.closest('[inert], [aria-disabled="true"]'),
         visible: rect.width > 0 && rect.height > 0 && style.visibility === 'visible' };
     });
-    throw new Error(`Selector must match exactly one element; matched ${count}. Scope the selector or provide an explicit zero-based nth. Candidates: ${JSON.stringify(candidates)}${count > candidates.length ? ` (${count - candidates.length} more omitted)` : ''}`);
+    throw failure(`Selector must match exactly one element; matched ${count}. Scope the selector or provide an explicit zero-based nth. Candidates: ${JSON.stringify(candidates)}${count > candidates.length ? ` (${count - candidates.length} more omitted)` : ''}`,
+      count ? 'selector_ambiguous' : 'selector_not_found', { matched: count, candidates, omitted_candidates: Math.max(0, count - candidates.length) });
   }
-  if (nth != null && nth >= count) throw new Error(`Selector nth=${nth} is out of range; matched ${count}`);
+  if (nth != null && nth >= count) throw failure(`Selector nth=${nth} is out of range; matched ${count}`, 'selector_not_found', { matched: count, nth });
   element = at(nth ?? 0);
-  if (element.nodeType !== 1) throw new Error('Selector must resolve to an element');
+  if (element.nodeType !== 1) throw failure('Selector must resolve to an element', 'selector_not_element');
   return element;
 }
 
@@ -66,22 +76,27 @@ export async function resolveSelector(cdp, value, sessions, tabId, args, budget,
     } 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);
+      await checkedValue(result, send, value);
       if (result.result?.subtype !== 'null') {
-        if (!result.result?.objectId) throw new Error('Selector did not resolve to an element');
+        if (!result.result?.objectId) throw Object.assign(new Error('Selector did not resolve to an element'), {
+          diagnostics: { reason: 'selector_not_element', frame_id: frameId },
+        });
         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`);
+    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`,
+      { reason: 'selector_not_found', selector_type: args.selector_type ?? 'css', frame_id: frameId, ...(args.nth == null ? {} : { nth: args.nth }) });
     await budget.run(() => new Promise(resolve => setTimeout(resolve, 20)));
   }
   // 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, objectGroup: 'browser-attach' });
-  if (!resolved.object?.objectId) throw new Error('Selector target detached before resolution; no input was dispatched');
+  if (!resolved.object?.objectId) throw Object.assign(new Error('Selector target detached before resolution; no input was dispatched'), {
+    diagnostics: { reason: 'element_detached', frame_id: frameId },
+  });
   return { target, frameId, objectId: resolved.object.objectId, backendNodeId };
 }
 
@@ -98,7 +113,13 @@ export function matchRole(nodes, args) {
     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) })))}`);
+  if (args.nth == null && candidates.length > 1) {
+    const preview = candidates.slice(0, 10).map((node, nth) => ({ nth, role: node.role?.value, name: String(node.name?.value || '').slice(0, 120) }));
+    throw Object.assign(new Error(`Role selector must match exactly one element; matched ${candidates.length}. Provide name or an explicit zero-based nth. Candidates: ${JSON.stringify(preview)}`), {
+      diagnostics: { reason: 'selector_ambiguous', selector_type: 'role', matched: candidates.length,
+        candidates: preview, omitted_candidates: Math.max(0, candidates.length - preview.length) },
+    });
+  }
   return candidates[args.nth ?? 0] || null;
 }
 
@@ -116,7 +137,7 @@ async function resolveFrameOnce(cdp, value, sessions, tabId, args, budget) {
   const frames = await budget.run(() => sessions.frames(tabId));
   const failure = (error, scope = {}) => {
     const candidates = frames.slice(0, 10).map(frame => ({ frame_id: frame.id, parent_frame_id: frame.parentId ?? null, url: frame.url }));
-    error.diagnostics = { reason: 'frame_locator', ...scope, candidates, omitted_candidates: Math.max(0, frames.length - candidates.length) };
+    error.diagnostics = { reason: 'frame_locator', ...(error.diagnostics ? { cause: error.diagnostics.reason, selector_diagnostics: error.diagnostics } : {}), ...scope, candidates, omitted_candidates: Math.max(0, frames.length - candidates.length) };
     error.message += `; frame scope=${JSON.stringify(scope)}; current frames=${JSON.stringify(candidates)}${frames.length > candidates.length ? ` (${frames.length - candidates.length} more omitted)` : ''}`;
     return error;
   };
@@ -134,7 +155,7 @@ async function resolveFrameOnce(cdp, value, sessions, tabId, args, budget) {
       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);
+      await checkedValue(result, send, value);
       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');

package/extension/log-data.js

@@ -0,0 +1,29 @@
+export const clip = (value, limit = 2000) => {
+  const text = String(value ?? '');
+  return text.length > limit ? `${text.slice(0, limit - 13)}…[truncated]` : text;
+};
+
+const SECRET = /^(authorization|proxy-authorization|cookie|set-cookie|password|passwd|access_token|refresh_token|token|secret|api[_-]?key)$/i;
+export function redactHeaders(headers = {}) {
+  return Object.fromEntries(Object.entries(headers).slice(0, 200).map(([key, value]) => [key, SECRET.test(key) ? '[REDACTED]' : clip(value, 2000)]));
+}
+export function boundedBody(body, maxBytes) {
+  let text = String(body ?? ''), format = 'text';
+  function scrub(value, depth = 0) {
+    if (depth > 16) return '[DEPTH LIMIT]';
+    if (Array.isArray(value)) return value.map(item => scrub(item, depth + 1));
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, SECRET.test(key) ? '[REDACTED]' : scrub(item, depth + 1)]));
+    return value;
+  }
+  try { text = JSON.stringify(scrub(JSON.parse(text))); format = 'json'; }
+  catch {
+    if (/^[^=\s&]+=/.test(text)) {
+      const params = new URLSearchParams(text);
+      for (const key of [...params.keys()]) if (SECRET.test(key)) params.set(key, '[REDACTED]');
+      text = params.toString(); format = 'form';
+    } else text = text.replace(/\b(Authorization|Proxy-Authorization|Cookie|Set-Cookie)\s*:[^\r\n]*/gi, '$1: [REDACTED]');
+  }
+  const bytes = new TextEncoder().encode(text), truncated = bytes.length > maxBytes;
+  const output = new TextDecoder().decode(bytes.slice(0, maxBytes), { stream: true });
+  return { text: output, format, truncated, bytes: new TextEncoder().encode(output).length };
+}

package/extension/manifest.json

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

package/extension/navigation.js

@@ -1,74 +1,74 @@
-import { NAVIGATION_MAX_TIMEOUT_MS } from './limits.js';
-import { pageUrl } from './page-url.js';
-
-// Lifecycle events can precede the Page.navigate reply. Keep them until its loader is known.
-export function createNavigation(cdp, validateUrl = pageUrl) {
-  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(operation) {
-      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([operation(), 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(() => cdp(tabId, 'Page.getNavigationHistory'));
-      entry = history.entries[history.currentIndex + (direction === 'back' ? -1 : 1)];
-      if (!entry) throw new Error(`No ${direction} history entry; no navigation was dispatched`);
-      await prepare(() => validateUrl(entry.url));
-      mainId = (await prepare(() => cdp(tabId, 'Page.getFrameTree'))).frameTree.frame.id;
-    } else url = await prepare(() => validateUrl(url));
-    let result, currentDocument, completedDocument, 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 client-side redirect can replace the loader before the original reply.
-      const current = currentDocument || result;
-      if (wait_until === 'commit' || !current.loaderId || events.some(event =>
-        event.frameId === current.frameId && event.loaderId === current.loaderId &&
-        event.name === (wait_until === 'load' ? 'load' : 'DOMContentLoaded'))) {
-        completedDocument ??= current;
-        resolveDone(result);
-      }
-    }
-    pending.set(tabId, {
-      event(method, params) {
-        if (!direction && method === 'Page.frameNavigated' && !params.frame.parentId && params.frame.loaderId) currentDocument = { frameId: params.frame.id, loaderId: params.frame.loaderId };
-        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(Object.assign(new Error(`Navigation did not reach ${wait_until} within ${timeout_ms} ms. It may still be loading; observe the tab before another action.`), { code: 'NAVIGATION_TIMEOUT' })), 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 Object.assign(new Error(`Navigation failed: ${reply.errorText}`), { code: 'NAVIGATION_FAILED', navigation_error: 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]);
-      const document = completedDocument || result;
-      return { navigated_to: entry?.url || url, ...(direction ? { direction } : {}), wait_until, same_document: !result.loaderId,
-        document: { frameId: document.frameId, loaderId: document.loaderId } };
-    } finally { clearTimeout(timer); pending.delete(tabId); }
-  }
-  return { event, cancel, navigate };
-}
+import { NAVIGATION_MAX_TIMEOUT_MS } from './limits.js';
+import { pageUrl } from './page-url.js';
+
+// Lifecycle events can precede the Page.navigate reply. Keep them until its loader is known.
+export function createNavigation(cdp, validateUrl = pageUrl) {
+  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(operation) {
+      const remaining = end - Date.now(); let timer;
+      try {
+        if (remaining <= 0) throw Object.assign(new Error('Navigation preparation timed out; no navigation was dispatched'), { input_dispatched: false });
+        return await Promise.race([operation(), new Promise((resolve, reject) => { timer = setTimeout(() => reject(Object.assign(new Error('Navigation preparation timed out; no navigation was dispatched'), { input_dispatched: false })), 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(() => cdp(tabId, 'Page.getNavigationHistory'));
+      entry = history.entries[history.currentIndex + (direction === 'back' ? -1 : 1)];
+      if (!entry) throw new Error(`No ${direction} history entry; no navigation was dispatched`);
+      await prepare(() => validateUrl(entry.url));
+      mainId = (await prepare(() => cdp(tabId, 'Page.getFrameTree'))).frameTree.frame.id;
+    } else url = await prepare(() => validateUrl(url));
+    let result, currentDocument, completedDocument, 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 client-side redirect can replace the loader before the original reply.
+      const current = currentDocument || result;
+      if (wait_until === 'commit' || !current.loaderId || events.some(event =>
+        event.frameId === current.frameId && event.loaderId === current.loaderId &&
+        event.name === (wait_until === 'load' ? 'load' : 'DOMContentLoaded'))) {
+        completedDocument ??= current;
+        resolveDone(result);
+      }
+    }
+    pending.set(tabId, {
+      event(method, params) {
+        if (!direction && method === 'Page.frameNavigated' && !params.frame.parentId && params.frame.loaderId) currentDocument = { frameId: params.frame.id, loaderId: params.frame.loaderId };
+        if (['Page.lifecycleEvent', 'Page.frameNavigated', 'Page.navigatedWithinDocument'].includes(method)) { events.push({ method, ...params }); check(); }
+      },
+      cancel(reason) { rejectDone(reason || Object.assign(new Error('Tab detached during navigation; outcome is unknown.'), { outcome_unknown: true })); },
+    });
+    timer = setTimeout(() => rejectDone(Object.assign(new Error(`Navigation did not reach ${wait_until} within ${timeout_ms} ms. It may still be loading; observe the tab before another action.`), { outcome_unknown: true, code: 'NAVIGATION_TIMEOUT' })), 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 Object.assign(new Error(`Navigation failed: ${reply.errorText}`), { code: 'NAVIGATION_FAILED', navigation_error: 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]);
+      const document = completedDocument || result;
+      return { navigated_to: entry?.url || url, ...(direction ? { direction } : {}), wait_until, same_document: !result.loaderId,
+        document: { frameId: document.frameId, loaderId: document.loaderId } };
+    } finally { clearTimeout(timer); pending.delete(tabId); }
+  }
+  return { event, cancel, navigate };
+}

package/extension/network.js

@@ -0,0 +1,79 @@
+import { clip } from './log-data.js';
+
+const MAX_ENTRIES = 500;
+
+// Passive request/document facts are independent of diagnostic log retention.
+export function createNetworkTracker() {
+  const tabs = new Map();
+  function start(tabId) {
+    tabs.set(tabId, { requests: new Map(), documentResponses: new Map(), pendingDocumentExtraInfo: new Map(), networkActivity: Date.now(), requestsOverflow: false });
+  }
+  function event(source, method, params) {
+    const state = tabs.get(source.tabId), id = params.requestId;
+    if (!state || !method.startsWith('Network.') || !id) return;
+    state.networkActivity = Date.now();
+    const key = JSON.stringify([source.sessionId, id]);
+    let request = state.requests.get(key), evicted;
+    const previous = request;
+    if (method === 'Network.requestWillBeSent') {
+      if (params.type === 'Document') state.documentResponses.delete(JSON.stringify([source.sessionId ?? null, params.frameId]));
+      request = { url: clip(params.request.url), method: clip(params.request.method, 50), resource_type: clip(params.type, 50),
+        frame_id: params.frameId, hop: request ? request.hop + 1 : 0 };
+      Object.defineProperty(request, 'decodedBytes', { value: 0, writable: true });
+      state.requests.delete(key); state.requests.set(key, request);
+      if (state.requests.size > MAX_ENTRIES) { state.requestsOverflow = true; const removed = state.requests.keys().next().value; state.requests.delete(removed); evicted = removed; }
+    } else if (method === 'Network.dataReceived') {
+      if (request && Number.isFinite(params.dataLength) && params.dataLength > 0) request.decodedBytes += params.dataLength;
+    } else if (method === 'Network.responseReceived') {
+      const response = params.response;
+      if (params.type === 'Document') {
+        const documentKey = JSON.stringify([source.sessionId ?? null, params.frameId]);
+        state.documentResponses.delete(documentKey);
+        const header = name => Object.entries(response.headers || {}).find(([key]) => key.toLowerCase() === name)?.[1];
+        const pendingKey = JSON.stringify([source.sessionId ?? null, id, response.status]);
+        const extra = state.pendingDocumentExtraInfo.get(pendingKey);
+        const length = extra?.length ?? header('content-length');
+        state.pendingDocumentExtraInfo.delete(pendingKey);
+        state.documentResponses.set(documentKey, { requestId: id, loaderId: params.loaderId, status: response.status, url: response.url,
+          contentType: response.mimeType || String(header('content-type') || '').split(';')[0] || null, empty_body: String(length ?? '').trim() === '0' });
+        if (state.documentResponses.size > MAX_ENTRIES) state.documentResponses.delete(state.documentResponses.keys().next().value);
+      }
+    } else if (method === 'Network.responseReceivedExtraInfo') {
+      // ExtraInfo can arrive on either side of responseReceived. Enrich only
+      // its matching status, never a redirect hop or a wire-level cache 304.
+      const length = Object.entries(params.headers || {}).find(([key]) => key.toLowerCase() === 'content-length')?.[1];
+      if (length != null) {
+        let matched = false;
+        for (const [documentKey, response] of state.documentResponses) if (JSON.parse(documentKey)[0] === (source.sessionId ?? null) && response.requestId === id && response.status === params.statusCode) {
+          response.empty_body = String(length).trim() === '0'; matched = true;
+        }
+        if (!matched && state.requests.get(key)?.resource_type === 'Document') {
+          state.pendingDocumentExtraInfo.set(JSON.stringify([source.sessionId ?? null, id, params.statusCode]), { length });
+          if (state.pendingDocumentExtraInfo.size > MAX_ENTRIES) state.pendingDocumentExtraInfo.delete(state.pendingDocumentExtraInfo.keys().next().value);
+        }
+      }
+    } else if (method === 'Network.loadingFinished' || method === 'Network.loadingFailed') {
+      const failed = method === 'Network.loadingFailed';
+      if (failed) for (const [documentKey, response] of state.documentResponses) {
+        if (JSON.parse(documentKey)[0] === (source.sessionId ?? null) && response.requestId === id && (!response.error || params.errorText === 'net::ERR_HTTP_RESPONSE_CODE_FAILURE')) response.error = params.errorText;
+      }
+      state.requests.delete(key);
+    }
+    return { key, request, previous, evicted };
+  }
+  return { start, event, documentStatus(tabId, frame) {
+    const response = tabs.get(tabId)?.documentResponses.get(JSON.stringify([null, frame.id]));
+    return frame.loaderId && response?.loaderId === frame.loaderId && Number.isInteger(response.status) && response.status >= 100 && response.status <= 599 ? response.status : null;
+  }, failedDocument(tabId, frameId) {
+    const response = tabs.get(tabId)?.documentResponses.get(JSON.stringify([null, frameId]));
+    return response?.error === 'net::ERR_HTTP_RESPONSE_CODE_FAILURE' && Number.isInteger(response.status) && response.status >= 100 && response.status <= 599 ? { ...response } : null;
+  }, networkStatus(tabId) {
+    const state = tabs.get(tabId);
+    if (!state) throw new Error('Tab control ended while waiting for network idle');
+    return { inflight: state.requests.size, idle_ms: Date.now() - state.networkActivity, tracking_overflow: state.requestsOverflow };
+  }, detach(tabId, sessionId) {
+    const state = tabs.get(tabId);
+    if (!state) return;
+    for (const map of [state.requests, state.documentResponses, state.pendingDocumentExtraInfo]) for (const key of map.keys()) if (JSON.parse(key)[0] === sessionId) map.delete(key);
+  }, forget: tabId => tabs.delete(tabId) };
+}

package/extension/observation.js

@@ -0,0 +1,232 @@
+import { renderAX, snapshotOptions, snapshotPage } from './snapshot.js';
+
+// Observation identity is separate from debugger session ownership.
+export function createObservations(cdp, value, sessions, viewport, currentClaim, changed) {
+  const snapshots = new Map(), retiredRefs = new Map(), documents = new Map();
+  const pageContexts = new Map(), frameStates = new Map();
+  function retireRef(tabId, ref, cause, frameId) {
+    let history = retiredRefs.get(tabId);
+    if (!history) retiredRefs.set(tabId, history = new Map());
+    history.set(ref, { cause, frame_id: frameId });
+    if (history.size > 1000) history.delete(history.keys().next().value);
+  }
+
+  function invalidateSnapshot(tabId, cause) {
+    const state = snapshots.get(tabId);
+    if (state) for (const [ref, node] of state.refs) retireRef(tabId, ref, cause, node.frameId);
+    snapshots.delete(tabId);
+  }
+
+  async function getObject(tabId, ref, budget) {
+    const refError = (cause, frameId, message) => {
+      const dispatched = budget.has_dispatched();
+      return Object.assign(new Error(`${message}. Take a new browser_snapshot. ${dispatched ? 'Input was already dispatched; outcome is unknown. Do not replay automatically.' : 'No input was dispatched.'}`), { outcome_unknown: true,
+        input_dispatched: dispatched, diagnostics: { reason: 'stale_ref', cause, ref, ...(frameId ? { frame_id: frameId } : {}) },
+      });
+    };
+    const node = snapshots.get(tabId)?.refs.get(ref);
+    if (!node) {
+      const failure = retiredRefs.get(tabId)?.get(ref);
+      throw refError(failure?.cause || 'unknown_ref', failure?.frame_id, 'Element ref is stale or unknown');
+    }
+    const target = sessions.target(tabId, node.frameId);
+    if (target.sessionId !== node.sessionId) throw refError('frame_session_changed', node.frameId, 'Frame session changed');
+    let resolved, nodes;
+    try {
+      resolved = await budget.run(() => cdp(target, 'DOM.resolveNode', { backendNodeId: node.backendNodeId, objectGroup: 'browser-attach' }));
+      if (!resolved.object?.objectId) throw refError('element_detached', node.frameId, 'Element no longer exists');
+      ({ nodes } = await budget.run(() => cdp(target, 'Accessibility.getPartialAXTree', { backendNodeId: node.backendNodeId, fetchRelatives: false })));
+    }
+    catch (error) {
+      const retired = retiredRefs.get(tabId)?.get(ref);
+      if (retired) throw refError(retired.cause, retired.frame_id, 'Element ref became stale during resolution');
+      if (/no node|could not find node|node.*(detached|not found)/i.test(error.message)) throw refError('element_detached', node.frameId, 'Element is detached or no longer exists');
+      throw error;
+    }
+    if (snapshots.get(tabId)?.refs.get(ref) !== node) {
+      const retired = retiredRefs.get(tabId)?.get(ref);
+      throw refError(retired?.cause || 'unknown_ref', node.frameId, 'Element ref became stale during resolution');
+    }
+    const current = nodes?.find(item => item.backendDOMNodeId === node.backendNodeId);
+    if (!current || !!current.ignored !== !!node.ignored || current.role?.value !== node.role || String(current.name?.value || '') !== node.name) {
+      throw refError('identity_changed', node.frameId, 'Element ref identity changed (role/name or accessibility)');
+    }
+    return { ...node, target, objectId: resolved.object.objectId };
+  }
+
+  async function rememberElement(tabId, target, objectId, frameId, budget) {
+    const version = documents.get(tabId), claim = currentClaim(tabId), frameVersion = frameStates.get(tabId)?.versions.get(frameId);
+    const send = (method, params) => budget.run(() => cdp(target, method, params));
+    const { node } = await send('DOM.describeNode', { objectId, depth: 0 });
+    if (node.nodeType !== 1) throw new Error('Result must be a DOM element');
+    const { nodes } = await send('Accessibility.getPartialAXTree', { backendNodeId: node.backendNodeId, fetchRelatives: false });
+    const ax = nodes?.find(item => item.backendDOMNodeId === node.backendNodeId);
+    if (!ax) throw new Error('Element accessibility identity is unavailable; observe again');
+    const connected = value(await send('Runtime.callFunctionOn', { objectId, functionDeclaration: 'function() { return this.isConnected; }', returnByValue: true }));
+    if (!connected) throw new Error('Element is detached; no ref was created');
+    if (documents.get(tabId) !== version || currentClaim(tabId) !== claim || frameStates.get(tabId)?.versions.get(frameId) !== frameVersion) throw new Error('Element document/frame/control changed; no ref was created');
+    let state = snapshots.get(tabId);
+    if (!state) {
+      state = { id: crypto.randomUUID().slice(0, 8), refs: new Map(), entries: [], invalidFrames: new Set(), totalNodes: 0, nextCursor: null, metadata: { omitted_frames: [] } };
+      snapshots.set(tabId, state);
+    }
+    if ((state.extraRefs || 0) >= 500) throw new Error('Element ref budget exhausted; take a new snapshot');
+    state.extraRefs = (state.extraRefs || 0) + 1;
+    const ref = `${state.id}:element:${state.extraRefs}`;
+    state.refs.set(ref, { backendNodeId: node.backendNodeId, frameId, sessionId: target.sessionId, role: ax.role?.value, name: String(ax.name?.value || ''), ignored: !!ax.ignored });
+    return { ref, frame_id: frameId, role: ax.role?.value, name: String(ax.name?.value || '') };
+  }
+
+  function invalidateFrame(tabId, frameId) {
+    const frames = frameStates.get(tabId);
+    if (!frames || !frameId) return;
+    const affected = new Set([frameId]);
+    // Descendant documents disappear with their parent, even without individual events.
+    let size;
+    do {
+      size = affected.size;
+      for (const [id, parent] of frames.parents) if (affected.has(parent)) affected.add(id);
+    } while (size !== affected.size);
+    const state = snapshots.get(tabId);
+    for (const id of affected) {
+      frames.versions.set(id, (frames.versions.get(id) || 0) + 1);
+      if (state) omitFrame(tabId, state, id, 'Frame navigated or detached after observation');
+    }
+    changed(tabId, affected);
+  }
+
+  function omitFrame(tabId, state, frameId, reason) {
+    if (state.invalidFrames.has(frameId)) return;
+    state.invalidFrames.add(frameId);
+    for (const [ref, node] of state.refs) if (node.frameId === frameId) {
+      retireRef(tabId, ref, 'frame_changed', frameId);
+      state.refs.delete(ref);
+    }
+    state.totalNodes -= state.entries.filter(entry => entry.frameId === frameId && entry.node).length;
+    state.metadata.omitted_frames.push({ frame_id: frameId, reason });
+  }
+
+  function expireCursor(tabId) {
+    const state = snapshots.get(tabId);
+    if (state) state.nextCursor = null;
+  }
+
+  async function snapshot(tabId, args = {}, budget) {
+    const send = (...params) => budget ? budget.run(() => cdp(...params)) : cdp(...params);
+    if (args.cursor != null) {
+      const state = snapshots.get(tabId);
+      if (!state) throw new Error('Snapshot cursor is stale or unknown. Take a new browser_snapshot.');
+      return snapshotPage(state, args);
+    }
+    const options = snapshotOptions(args);
+    invalidateSnapshot(tabId, 'snapshot_replaced');
+    const documentVersion = documents.get(tabId);
+    const versions = new Map(frameStates.get(tabId)?.versions);
+    await (budget ? budget.run(() => sessions.settle(tabId)) : sessions.settle(tabId));
+    for (const target of sessions.targets(tabId)) await send(target, 'Runtime.releaseObjectGroup', { objectGroup: 'browser-attach' });
+    const frames = await (budget ? budget.run(() => sessions.frames(tabId, send)) : sessions.frames(tabId, send));
+    const mainId = frameStates.get(tabId).mainId;
+    for (const frame of frames) if (frame.parentId) frameStates.get(tabId).parents.set(frame.id, frame.parentId);
+    const knownFrames = new Set(frames.map(frame => frame.id));
+    const token = crypto.randomUUID().slice(0, 8);
+    const refs = new Map(), entries = [], omittedFrames = [];
+    for (const frame of frames) {
+      let nodes;
+      let target;
+      try {
+        target = sessions.target(tabId, frame.id);
+        frameStates.get(tabId).sessions.set(frame.id, target.sessionId);
+        ({ nodes } = await send(target, 'Accessibility.getFullAXTree', { frameId: frame.id }));
+      }
+      catch (error) {
+        if (frame.id === mainId) throw error;
+        omittedFrames.push({ frame_id: frame.id, url: frame.url, reason: error.message });
+        continue;
+      }
+      // Report cross-process frames that are missing from Page.getFrameTree.
+      for (const node of nodes) {
+        if (!/^iframe$/i.test(node.role?.value || '') || !node.backendDOMNodeId) continue;
+        const { node: owner } = await send(target, 'DOM.describeNode', { backendNodeId: node.backendDOMNodeId, depth: 0 });
+        const childId = owner.frameId || owner.contentDocument?.frameId;
+        if (!childId) continue;
+        frameStates.get(tabId)?.parents.set(childId, frame.id);
+        sessions.rememberParent(tabId, childId, frame.id);
+        if (knownFrames.has(childId)) continue;
+        const attributes = owner.attributes || [], srcIndex = attributes.indexOf('src');
+        const url = srcIndex >= 0 ? new URL(attributes[srcIndex + 1], frame.url).href : 'about:blank';
+        knownFrames.add(childId); frames.push({ id: childId, url });
+      }
+      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}` });
+      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,
+    }));
+    const state = { id: token, options, refs, entries, invalidFrames: new Set(), totalNodes: entries.filter(entry => entry.node).length,
+      metadata: { title: metadata.title, url: metadata.url, viewport: await (budget ? budget.run(() => viewport(tabId)) : viewport(tabId)), omitted_frames: omittedFrames } };
+    if (documentVersion !== documents.get(tabId)) throw new Error('Document changed while reading the snapshot. Take a new browser_snapshot.');
+    for (const frame of frames) if (versions.get(frame.id) !== frameStates.get(tabId)?.versions.get(frame.id)) {
+      omitFrame(tabId, state, frame.id, 'Frame changed while reading the snapshot; take a new snapshot to observe it');
+    }
+    const page = snapshotPage(state, args);
+    snapshots.set(tabId, state);
+    return page;
+  }
+
+
+  function documentChanged(tabId, cause) {
+    documents.set(tabId, (documents.get(tabId) || 0) + 1);
+    invalidateSnapshot(tabId, cause);
+    changed(tabId);
+  }
+  function contextEvent(source, method, params) {
+    const contextKey = JSON.stringify([source.tabId, source.sessionId]);
+    if (method === 'Runtime.executionContextCreated' && params.context.auxData?.isDefault) pageContexts.set(JSON.stringify([source.tabId, source.sessionId, params.context.auxData.frameId]), params.context.id);
+    if (method === 'Runtime.executionContextDestroyed' || method === 'Runtime.executionContextsCleared') {
+      for (const [key, id] of pageContexts) if (key.startsWith(contextKey.slice(0, -1) + ',') && (method.endsWith('Cleared') || id === params.executionContextId)) pageContexts.delete(key);
+    }
+  }
+  function event(source, method, params) {
+    const frames = frameStates.get(source.tabId);
+    if (method === 'Page.frameAttached') frames?.parents.set(params.frameId, params.parentFrameId);
+    const mainNavigation = !source.sessionId && method === 'Page.frameNavigated' && params.frame && !params.frame.parentId;
+    if (mainNavigation && frames) {
+      frames.mainId = params.frame.id;
+      frames.parents.clear(); frames.versions.clear(); frames.sessions.clear();
+    }
+    if (method === 'Page.frameNavigated' && params.frame?.parentId) frames?.parents.set(params.frame.id, params.frame.parentId);
+    const sameDocumentMain = method === 'Page.navigatedWithinDocument' && params.frameId === frames?.mainId;
+    if ((!source.sessionId && method === 'DOM.documentUpdated') || mainNavigation || sameDocumentMain) {
+      documentChanged(source.tabId, sameDocumentMain ? 'same_document_navigation' : mainNavigation ? 'document_navigation' : 'document_updated');
+    } else if (source.sessionId && method === 'DOM.documentUpdated') {
+      for (const [frame, session] of frameStates.get(source.tabId)?.sessions || []) if (session === source.sessionId) invalidateFrame(source.tabId, frame);
+    } else if (method === 'Page.frameNavigated' || method === 'Page.navigatedWithinDocument' || method === 'Page.frameDetached') {
+      invalidateFrame(source.tabId, params.frame?.id || params.frameId);
+    }
+  }
+  function initialize(tabId, frameTree) {
+    const state = { mainId: frameTree.frame.id, parents: new Map(), versions: new Map(), sessions: new Map() };
+    const remember = tree => {
+      if (tree.frame.parentId) state.parents.set(tree.frame.id, tree.frame.parentId);
+      (tree.childFrames || []).forEach(remember);
+    };
+    remember(frameTree); frameStates.set(tabId, state);
+  }
+  function forget(tabId) {
+    snapshots.delete(tabId); retiredRefs.delete(tabId); documents.delete(tabId);
+    for (const key of pageContexts.keys()) if (JSON.parse(key)[0] === tabId) pageContexts.delete(key);
+    frameStates.delete(tabId);
+  }
+  return { snapshot, resolve: getObject, rememberElement, invalidate: invalidateSnapshot, expireCursor,
+    initialize, invalidateFrame, documentChanged, event, contextEvent, forget,
+    version: tabId => documents.get(tabId),
+    mainFrame: tabId => frameStates.get(tabId)?.mainId,
+    frameVersion: (tabId, frameId) => frameStates.get(tabId)?.versions.get(frameId),
+    refFrame: (tabId, ref) => snapshots.get(tabId)?.refs.get(ref)?.frameId,
+    context: (tabId, sessionId, frameId) => pageContexts.get(JSON.stringify([tabId, sessionId, frameId])),
+    detachSession(tabId, sessionId) {
+      for (const key of pageContexts.keys()) { const [tab, session] = JSON.parse(key); if (tab === tabId && session === sessionId) pageContexts.delete(key); }
+    },
+  };
+}