@evan_zhong/browser-attach 0.20.0 → 0.22.0

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.20.0",
+  "version": "0.22.0",
   "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); }
+    },
+  };
+}

package/extension/outcomes.js

@@ -1,15 +1,71 @@
-// Observation can confirm a dialog/navigation/mutation, never absence of delivery.
-export async function boundedRead(operation, ms = 300) {
-  let timer;
-  try { return await Promise.race([Promise.resolve().then(operation), new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error('observation did not respond')), ms); })]); }
-  finally { clearTimeout(timer); }
-}
-export function installOutcomeObserver() {
-  let mutations = 0;
-  const observer = new MutationObserver(records => { mutations += records.length; });
-  observer.observe(document, { childList: true, subtree: true, attributes: true, characterData: true });
-  const startUrl = location.href;
-  let expiry = setTimeout(() => observer.disconnect(), 55000);
-  return { read() { mutations += observer.takeRecords().length; return { dom_changed: mutations > 0, mutation_records: mutations, start_url: startUrl, current_url: location.href }; },
-    stop() { clearTimeout(expiry); observer.disconnect(); } };
-}
+import { deadline } from './actionability.js';
+import { resolveFrame } from './locator.js';
+
+// Observation can confirm a dialog/navigation/mutation, never absence of delivery.
+export async function boundedRead(operation, ms = 300) {
+  let timer;
+  try { return await Promise.race([Promise.resolve().then(operation), new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error('observation did not respond')), ms); })]); }
+  finally { clearTimeout(timer); }
+}
+export function installOutcomeObserver() {
+  let mutations = 0;
+  const observer = new MutationObserver(records => { mutations += records.length; });
+  observer.observe(document, { childList: true, subtree: true, attributes: true, characterData: true });
+  const startUrl = location.href;
+  let expiry = setTimeout(() => observer.disconnect(), 55000);
+  return { read() { mutations += observer.takeRecords().length; return { dom_changed: mutations > 0, mutation_records: mutations, start_url: startUrl, current_url: location.href }; },
+    stop() { clearTimeout(expiry); observer.disconnect(); } };
+}
+
+export function createOutcomes(cdp, value, sessions, observations, getTab, getDialog) {
+  async function begin(tabId, command, args) {
+    const version = observations.version(tabId), startTab = await getTab(tabId);
+    const watch = ['click', 'fill', 'type', 'press_key', 'hover', 'scroll', 'select_option', 'upload_file', 'evaluate', 'navigate'].includes(command) && !(command === 'evaluate' && args.cursor != null);
+    let observer, observationError, observationFrame = observations.mainFrame(tabId), observationTarget = { tabId }, observedVersion = observations.frameVersion(tabId, observationFrame);
+    const startObservation = async () => { if (!watch || observer || getDialog(tabId)) return; try {
+      observer = await boundedRead(async () => {
+        if (args.ref) observationFrame = observations.refFrame(tabId, args.ref) || observationFrame;
+        else if (args.frame || args.frame_id) observationFrame = await resolveFrame(cdp, value, sessions, tabId, args, deadline(Math.max(100, Math.min(200, args.budget?.remaining() ?? 200))), { wait: false });
+        observationTarget = sessions.target(tabId, observationFrame);
+        observedVersion = observations.frameVersion(tabId, observationFrame);
+        const { executionContextId } = await cdp(observationTarget, 'Page.createIsolatedWorld', { frameId: observationFrame, worldName: 'browser-attach-outcome' });
+        const result = await cdp(observationTarget, 'Runtime.evaluate', { contextId: executionContextId, expression: `(${installOutcomeObserver.toString()})()`, objectGroup: 'browser-attach-outcome' });
+        if (!result.result?.objectId) throw new Error('DOM outcome observer could not be installed');
+        return result.result.objectId;
+      }, Math.min(200, args.budget?.remaining() ?? 200));
+    } catch (error) { observationError = error.message; } };
+
+    async function enrich(error, messages) {
+      if (!watch || error.input_dispatched === false || !error.outcome_unknown) return false;
+      let current, dom, tabError, domError = observationError;
+      await Promise.allSettled([
+        boundedRead(() => getTab(tabId)).then(result => { if (result) current = result; else tabError = 'Tab is unavailable'; }, error => { tabError = error.message; }),
+        observer ? boundedRead(async () => {
+          const result = value(await cdp(observationTarget, 'Runtime.callFunctionOn', { objectId: observer, functionDeclaration: 'function() { return this.read(); }', returnByValue: true }));
+          if (typeof result?.dom_changed !== 'boolean') throw new Error('DOM outcome observation is unavailable');
+          return result;
+        }).then(result => { dom = result; }, error => { domError = error.message; }) : Promise.resolve(),
+      ]);
+      const frameChanged = observations.frameVersion(tabId, observationFrame) !== observedVersion;
+      const navigationObserved = observations.version(tabId) !== version || !!current && current.url !== startTab.url;
+      error.post_action = { delivery: 'unknown', frame_id: observationFrame, frame_navigation_observed: frameChanged, dialog: getDialog(tabId) || null, dialogs: messages,
+        navigation_observed: navigationObserved,
+        current_url: current?.url ?? null, dom_changed: dom?.dom_changed ?? null,
+        observations: { tab: { available: !!current, ...(tabError ? { error: tabError } : {}) },
+          dom: { available: !!dom, ...(!dom ? { error: domError || 'DOM outcome observer is unavailable' } : {}) } },
+        assessment: !!getDialog(tabId) || messages.length || navigationObserved || frameChanged || dom?.dom_changed ? 'observable_effects'
+          : dom && current ? 'no_observable_effects' : 'observation_unavailable',
+        note: 'These observations do not prove business success or that an unchanged page received no input. Do not replay automatically.' };
+
+      return true;
+    }
+    async function stop() {
+      if (observer) await boundedRead(async () => {
+        await cdp(observationTarget, 'Runtime.callFunctionOn', { objectId: observer, functionDeclaration: 'function() { this.stop(); }' });
+        await cdp(observationTarget, 'Runtime.releaseObject', { objectId: observer });
+      }, 100).catch(() => {});
+    }
+    return { start: startObservation, enrich, stop };
+  }
+  return { begin };
+}

package/extension/page-url.js

@@ -5,3 +5,11 @@ export function pageUrl(url) {
   }
   return parsed.href;
 }
+
+export function httpUrl(url) {
+  const parsed = new URL(url);
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) {
+    throw new Error('Only http(s) pages without URL credentials can be controlled');
+  }
+  return parsed.href;
+}