@evan_zhong/browser-attach 0.0.0-stage → 0.11.1

package/extension/diagnostics.js

@@ -0,0 +1,205 @@
+const MAX_ENTRIES = 500, MAX_CHARS = 1024 * 1024;
+const clip = (value, limit = 2000) => {
+  const text = String(value ?? '');
+  return text.length > limit ? `${text.slice(0, limit - 13)}…[truncated]` : text;
+};
+
+function buffer() {
+  const entries = [];
+  let sequence = 0, chars = 0, droppedThrough = 0;
+  return {
+    add(entry) {
+      const record = { seq: ++sequence, ...entry };
+      const size = JSON.stringify(record).length;
+      entries.push({ record, size }); chars += size;
+      while (entries.length > MAX_ENTRIES || chars > MAX_CHARS) {
+        const removed = entries.shift(); chars -= removed.size; droppedThrough = removed.record.seq;
+      }
+    },
+    read(args, matches) {
+      const after = args.after_seq ?? 0, limit = args.limit ?? 100, maxChars = args.max_chars ?? 24000;
+      if (!Number.isSafeInteger(after) || after < 0 || after > sequence) throw new Error('after_seq must be a sequence from this claim (0 starts reading)');
+      if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new Error('limit must be 1..200');
+      if (!Number.isInteger(maxChars) || maxChars < 1000 || maxChars > 100000) throw new Error('max_chars must be 1000..100000');
+      const result = [];
+      let next = Math.max(after, droppedThrough), used = 2;
+      for (const { record, size } of entries) {
+        if (record.seq <= after) continue;
+        if (!matches(record)) { next = record.seq; continue; }
+        if (result.length >= limit || (used + size + 1 > maxChars && result.length)) break;
+        const output = size + used + 1 <= maxChars ? record : {
+          seq: record.seq, truncated: true, serialized_preview: JSON.stringify(record).slice(0, Math.floor((maxChars - 150) / 6)),
+        };
+        result.push(output); used += JSON.stringify(output).length + 1; next = record.seq;
+      }
+      return { entries: result, next_seq: next, latest_seq: sequence, has_more: next < sequence,
+        data_loss: after < droppedThrough, dropped_through_seq: droppedThrough };
+    },
+  };
+}
+
+function remoteText(arg) {
+  if ('value' in arg) return clip(typeof arg.value === 'string' ? arg.value : JSON.stringify(arg.value));
+  if (arg.unserializableValue) return clip(arg.unserializableValue);
+  if (arg.preview?.properties?.length) return clip(`${arg.description || arg.type} {${arg.preview.properties.slice(0, 10)
+    .map(property => `${clip(property.name, 100)}: ${clip(property.value ?? property.type, 100)}`).join(', ')}}`);
+  return clip(arg.description || arg.type);
+}
+
+function location(frame = {}) {
+  return { url: clip(frame.url), line: frame.lineNumber, column: frame.columnNumber };
+}
+
+export function createDiagnostics(cdp) {
+  const tabs = new Map();
+  function start(tabId) { tabs.set(tabId, { started: Date.now(), console: buffer(), network: buffer(), requests: new Map(), networkActivity: Date.now(), requestsOverflow: false, contexts: new Map(), capture: { enabled: false, max_body_bytes: 65536 }, captureVersion: 0, detailed: new Set(), pending: new Set() }); }
+  function event(source, method, params) {
+    const state = tabs.get(source.tabId);
+    if (!state) return;
+    const origin = { session_id: source.sessionId ?? null };
+    const contextKey = JSON.stringify([source.sessionId, params.executionContextId ?? params.context?.id ?? params.exceptionDetails?.executionContextId]);
+    if (method === 'Runtime.executionContextCreated') state.contexts.set(contextKey, params.context.auxData?.frameId);
+    if (method === 'Runtime.executionContextDestroyed') state.contexts.delete(contextKey);
+    if (method === 'Runtime.executionContextsCleared') for (const key of state.contexts.keys()) if (JSON.parse(key)[0] === (source.sessionId ?? null)) state.contexts.delete(key);
+    const timestamp = params.timestamp ?? params.entry?.timestamp;
+    if ((method.startsWith('Runtime.') || method.startsWith('Log.')) && timestamp != null && timestamp < state.started) return;
+    if (method === 'Runtime.consoleAPICalled') {
+      if (params.executionContextId === 0) return;
+      const type = params.type;
+      const level = ['warning', 'warn'].includes(type) ? 'warning' : ['error', 'assert'].includes(type) ? 'error'
+        : ['debug', 'trace'].includes(type) ? 'debug' : type === 'info' ? 'info' : 'log';
+      state.console.add({ ...origin, frame_id: state.contexts.get(contextKey), timestamp, source: 'console', type, level,
+        text: clip((params.args || []).slice(0, 20).map(remoteText).join(' '), 8000),
+        location: location(params.stackTrace?.callFrames?.[0]), execution_context_id: params.executionContextId });
+    } else if (method === 'Runtime.exceptionThrown') {
+      const details = params.exceptionDetails || {};
+      state.console.add({ ...origin, frame_id: state.contexts.get(contextKey), timestamp, source: 'exception', type: 'exception', level: 'error',
+        text: clip(details.exception?.description || details.text, 8000), location: location(details),
+        stack: (details.stackTrace?.callFrames || []).slice(0, 8).map(frame => ({ function: clip(frame.functionName, 200), ...location(frame) })) });
+    } else if (method === 'Log.entryAdded') {
+      const entry = params.entry;
+      state.console.add({ ...origin, frame_id: state.contexts.get(contextKey), timestamp, source: clip(entry.source, 100), type: 'browser', level: clip(entry.level, 100),
+        text: clip(entry.text, 8000), location: location(entry) });
+    } else if (method.startsWith('Network.')) {
+      const id = params.requestId;
+      if (!id) return;
+      state.networkActivity = Date.now();
+      const key = JSON.stringify([source.sessionId, id]);
+      let request = state.requests.get(key);
+      const add = (event, extra = {}) => state.network.add({ ...origin, event, request_id: id, timestamp, ...request, ...extra });
+      if (method === 'Network.requestWillBeSent') {
+        if (params.redirectResponse) add('redirect', { ...(state.capture.enabled ? { headers: redactHeaders(params.redirectResponse.headers) } : {}), status: params.redirectResponse.status,
+          url: clip(params.redirectResponse.url), redirect_to: clip(params.request.url) });
+        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); state.detailed.delete(removed); }
+        state.detailed.delete(key);
+        if (state.capture.enabled && ['XHR', 'Fetch'].includes(params.type)) state.detailed.add(key);
+        add('request', { wall_time: params.wallTime, ...(state.detailed.has(key) ? {
+          headers: redactHeaders(params.request.headers), ...(params.request.postData != null ? { request_body: boundedBody(params.request.postData, state.capture.max_body_bytes) } : params.request.hasPostData ? { request_body_unavailable: 'not present in bounded request event' } : {}),
+        } : {}) });
+      } 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;
+        add('response', { ...(state.detailed.has(key) ? { headers: redactHeaders(response.headers) } : {}), url: clip(response.url), status: response.status, status_text: clip(response.statusText, 200),
+          mime_type: clip(response.mimeType, 200), protocol: clip(response.protocol, 50),
+          from_cache: !!(response.fromDiskCache || response.fromPrefetchCache), from_service_worker: !!response.fromServiceWorker });
+      } else if (method === 'Network.loadingFinished' || method === 'Network.loadingFailed') {
+        const failed = method === 'Network.loadingFailed';
+        add(failed ? 'failed' : 'finished', failed ? { error: clip(params.errorText), canceled: !!params.canceled,
+          blocked_reason: clip(params.blockedReason) } : { encoded_data_length: params.encodedDataLength });
+        if (!failed && state.detailed.has(key) && state.capture.enabled && cdp) {
+          const version = state.captureVersion, requestInfo = request, maxBytes = state.capture.max_body_bytes;
+          if (requestInfo?.decodedBytes > maxBytes) add('body', { response_body_unavailable: 'decoded response exceeds capture byte limit', decoded_bytes: requestInfo.decodedBytes });
+          else if (state.pending.size >= 8) add('body', { response_body_unavailable: 'capture concurrency limit (8)' });
+          else {
+            let timer;
+            const task = Promise.race([cdp(source, 'Network.getResponseBody', { requestId: id }), new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error('body read exceeded 1500 ms')), 1500); })])
+              .then(result => {
+                if (tabs.get(source.tabId) !== state || state.captureVersion !== version) return;
+                state.network.add({ ...origin, event: 'body', request_id: id, timestamp, ...requestInfo,
+                  ...(result.base64Encoded ? { response_body_unavailable: 'binary response omitted' } : { response_body: boundedBody(result.body, maxBytes) }) });
+              }).catch(error => {
+                if (tabs.get(source.tabId) === state && state.captureVersion === version) state.network.add({ ...origin, event: 'body', request_id: id, timestamp, ...requestInfo, response_body_unavailable: clip(error.message, 500) });
+              }).finally(() => { clearTimeout(timer); state.pending.delete(task); });
+            state.pending.add(task);
+          }
+        }
+        state.requests.delete(key); state.detailed.delete(key);
+      } else if (method === 'Network.requestServedFromCache') add('cache');
+    }
+  }
+  function read(tabId, args) {
+    const state = tabs.get(tabId);
+    if (!state) throw new Error('Diagnostics are unavailable; claim the tab again');
+    const { kind } = args;
+    if (!['console', 'network'].includes(kind)) throw new Error('kind must be console or network');
+    if (kind === 'console' && args.url_contains != null) throw new Error('url_contains is only valid for kind=network');
+    if (kind === 'network' && args.level != null) throw new Error('level is only valid for kind=console');
+    if (args.level != null && !['log', 'debug', 'info', 'warning', 'error'].includes(args.level)) throw new Error('Invalid console level');
+    if (args.url_contains != null && (typeof args.url_contains !== 'string' || args.url_contains.length > 2000)) throw new Error('url_contains must be at most 2000 characters');
+    return { ...state[kind].read(args, record => kind === 'console' ? !args.level || record.level === args.level
+      : !args.url_contains || record.url?.includes(args.url_contains)),
+      kind, ...(kind === 'network' ? { capture: state.capture, pending_bodies: state.pending.size } : {}), capture_started_at: state.started, scope: 'tab_and_iframes', retained_across_navigation: true };
+  }
+  function networkOptions(tabId, config = tabs.get(tabId)?.capture) {
+    return config?.enabled ? { maxTotalBufferSize: 2097152, maxResourceBufferSize: config.max_body_bytes, maxPostDataSize: config.max_body_bytes } : { maxTotalBufferSize: 0, maxResourceBufferSize: 0, maxPostDataSize: 0 };
+  }
+  async function configure(tabId, config, targets) {
+    const state = tabs.get(tabId);
+    if (!state || typeof config?.enabled !== 'boolean') throw new Error('capture requires enabled boolean');
+    const max = config.max_body_bytes ?? 65536;
+    if (!Number.isInteger(max) || max < 1024 || max > 262144) throw new Error('max_body_bytes must be 1024..262144');
+    const next = { enabled: config.enabled, max_body_bytes: max };
+    try { for (const target of targets) await cdp(target, 'Network.enable', networkOptions(tabId, next)); }
+    catch (error) { await Promise.allSettled(targets.map(target => cdp(target, 'Network.enable', networkOptions(tabId)))); throw error; }
+    state.capture = next; state.captureVersion++; state.detailed.clear();
+  }
+  async function readDetails(tabId, args, targets) {
+    if (args.capture != null) {
+      if (args.kind !== 'network') throw new Error('capture is only valid for network logs');
+      await configure(tabId, args.capture, targets);
+    }
+    const state = tabs.get(tabId);
+    if (args.kind === 'network' && state) await Promise.allSettled([...state.pending]);
+    return read(tabId, args);
+  }
+  return { start, event, read, readDetails, networkOptions, 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 key of state.detailed) if (JSON.parse(key)[0] === sessionId) state.detailed.delete(key);
+    for (const map of [state.contexts, state.requests]) for (const key of map.keys()) if (JSON.parse(key)[0] === sessionId) map.delete(key);
+  }, forget: tabId => tabs.delete(tabId) };
+}
+
+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/drag.js

@@ -0,0 +1,163 @@
+import { deadline, delivery } from './actionability.js';
+import { targetOptions } from './locator.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 });
+  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');
+}
+
+export function createDrag(cdp, value, mouse) {
+  const pending = new Map();
+  function event(tabId, method, params, sessionId) {
+    const operation = pending.get(tabId);
+    if (!operation) return;
+    if (['DOM.documentUpdated', 'Page.frameNavigated', 'Page.frameDetached', 'Page.navigatedWithinDocument'].includes(method)) {
+      const frameId = params.frame?.id || params.frameId;
+      if ([...operation.frames].some(key => { const [session, frame] = JSON.parse(key); return session === (sessionId ?? null) && (!frameId || frame === frameId); })) {
+        operation.error = new Error('Drag document/frame changed; outcome is unknown. Observe before continuing.');
+        operation.reject(operation.error);
+      }
+    }
+    if (method === 'Page.javascriptDialogOpening') { operation.error = new Error('Drag opened a JavaScript dialog; outcome is unknown. Observe and handle the dialog.'); operation.reject(operation.error); }
+    if (method === 'Input.dragIntercepted' && !sessionId) operation.intercept(params.data);
+    if (method !== 'Runtime.bindingCalled' || params.name !== operation.name || !operation.contexts.has(JSON.stringify([sessionId, params.executionContextId]))) return;
+    try {
+      const { type, rejected } = JSON.parse(params.payload);
+      if (rejected) { operation.error = new Error('Drag target changed during dispatch; outcome is unknown. Observe before continuing.'); operation.reject(operation.error); }
+      operation.seen.add(type);
+      const required = operation.html5 ? ['mousedown', 'dragstart', 'drop', 'dragend'] : ['mousedown', 'mousemove', 'mouseup'];
+      if (required.every(type => operation.seen.has(type))) operation.resolve();
+    } catch (error) { operation.reject(error); }
+  }
+  function cancel(tabId) { const operation = pending.get(tabId); if (operation) { operation.error = new Error('Tab detached during drag; outcome is unknown.'); operation.reject(operation.error); } }
+  async function drag(tabId, args, resolve, assertCurrent = () => {}) {
+    dragOptions(args);
+    const budget = args.budget || deadline(args.timeout_ms ?? 5000), html5 = args.mode === 'html5', steps = args.steps ?? 20;
+    await mouse.assertReady(tabId, budget);
+    const source = await mouse.prepare(tabId, await resolve(args.source, budget), { ...args.source, budget });
+    const name = `__attachDrag_${crypto.randomUUID().replaceAll('-', '')}`, contexts = new Set(), guards = [], frames = new Set();
+    let intercept; const intercepted = new Promise(resolve => { intercept = resolve; });
+    const receipt = new Promise((resolve, reject) => pending.set(tabId, { name, contexts, frames, html5, seen: new Set(), resolve, reject, intercept }));
+    receipt.catch(() => {});
+    let pressed = false, releaseQueued = false, interceptEnabled = false, point = source.point;
+    const check = () => { assertCurrent(); const error = pending.get(tabId)?.error; if (error) throw error; };
+    const send = (method, params) => budget.run(() => {
+      check();
+      if (method === 'Input.dispatchMouseEvent' && params.type === 'mousePressed') pressed = true;
+      if (method === 'Input.dispatchMouseEvent' && params.type === 'mouseReleased') releaseQueued = true;
+      return delivery(cdp(tabId, method, params));
+    });
+    const move = p => send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...p, button: pressed ? 'left' : 'none', buttons: pressed ? 1 : 0 });
+    async function guard(prepared, stage) {
+      for (const item of [prepared, ...prepared.boundaries]) {
+        const { target, frameId, backendNodeId } = item;
+        frames.add(JSON.stringify([target.sessionId ?? null, frameId]));
+        check();
+        const call = (method, params) => budget.run(() => cdp(target, method, params));
+        const { executionContextId } = await call('Page.createIsolatedWorld', { frameId, worldName: 'browser-attach-input' });
+        contexts.add(JSON.stringify([target.sessionId, executionContextId]));
+        await call('Runtime.addBinding', { name, executionContextId });
+        const isolated = await call('DOM.resolveNode', { backendNodeId, executionContextId, objectGroup: 'browser-attach' });
+        const installed = await call('Runtime.callFunctionOn', { objectId: isolated.object.objectId, functionDeclaration: installDragReceipt.toString(),
+          arguments: [{ value: name }, { value: item === prepared ? stage : `${stage}_boundary` }, { value: html5 }, { value: budget.remaining() + 500 }], objectGroup: 'browser-attach' });
+        value(installed);
+        if (!installed.result?.objectId) throw new Error('Could not install drag receipt; observe before continuing');
+        guards.push({ target, objectId: installed.result.objectId });
+      }
+    }
+    try {
+      await guard(source, 'source');
+      if (html5) { interceptEnabled = true; await send('Input.setInterceptDrags', { enabled: true }); }
+      await mouse.assertReady(tabId, budget);
+      budget.dispatch();
+      await move(point);
+      await send('Input.dispatchMouseEvent', { type: 'mousePressed', ...point, button: 'left', buttons: 1, clickCount: 1 });
+      // Cross Chromium's drag threshold before scrolling to an offscreen destination.
+      const initial = { x: point.x + (point.x > 20 ? -12 : 12), y: point.y };
+      await move(initial); point = initial;
+      const data = html5 ? await budget.run(() => delivery(intercepted)) : null;
+      // Preparation scrolls the destination into view while the button remains held,
+      // including nested containers, then rechecks frame boundaries and occlusion.
+      const destination = await mouse.prepare(tabId, await resolve(args.destination, budget), { ...args.destination, budget });
+      await guard(destination, 'destination');
+      const from = point;
+      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 };
+        if (html5) await send('Input.dispatchDragEvent', { type: 'dragOver', ...point, data });
+        else await move(point);
+        await budget.run(() => new Promise(resolve => setTimeout(resolve, 16)));
+      }
+      if (html5) await send('Input.dispatchDragEvent', { type: 'drop', ...point, data });
+      await send('Input.dispatchMouseEvent', { type: 'mouseReleased', ...point, button: 'left', buttons: 0, clickCount: 1 });
+      pressed = false;
+      await budget.run(() => delivery(receipt));
+      return { dragged: true, method: html5 ? 'native_html5' : 'native_pointer', events_trusted: true, delivery_verified: true,
+        steps, from: source.point, to: point, application_result: 'not_checked', observe_again: true };
+    } finally {
+      pending.delete(tabId);
+      // Cancel/release only this gesture; cleanup is never a replay of the action.
+      const cleanup = [];
+      if (pressed && !releaseQueued) {
+        if (html5) cleanup.push(cdp(tabId, 'Input.cancelDragging'));
+        cleanup.push(cdp(tabId, 'Input.dispatchMouseEvent', { type: 'mouseReleased', ...point, button: 'left', buttons: 0, clickCount: 1 }));
+      }
+      if (interceptEnabled) cleanup.push(cdp(tabId, 'Input.setInterceptDrags', { enabled: false }));
+      for (const { target, objectId } of guards) {
+        cleanup.push(cdp(target, 'Runtime.callFunctionOn', { objectId, functionDeclaration: 'function() { this.stop(); }' }));
+        cleanup.push(cdp(target, 'Runtime.removeBinding', { name }));
+      }
+      await delivery(Promise.allSettled(cleanup), 250).catch(() => {});
+    }
+  }
+  return { drag, event, cancel };
+}
+
+function installDragReceipt(name, stage, html5, expiryMs) {
+  const target = this, win = target.ownerDocument.defaultView, report = win[name];
+  const types = stage === 'source' ? ['mousedown', 'mousemove', 'mouseup', 'dragstart', 'dragend']
+    : stage === 'source_boundary' ? ['mousedown'] : ['drop', 'mouseup'];
+  const listeners = [];
+  function listener(event, expected) {
+    if (!event.isTrusted) return;
+    const hit = event.composedPath().includes(expected);
+    if ((event.type === 'mousedown' || event.type === 'drop') && (!hit || !target.isConnected)) {
+      event.preventDefault(); event.stopImmediatePropagation(); report(JSON.stringify({ rejected: true })); return;
+    }
+    if (stage.endsWith('_boundary') || expected !== target) return;
+    if (['dragstart', 'dragend'].includes(event.type) && !hit) return;
+    if (event.type === 'mousemove' && event.buttons !== 1) return;
+    if (html5 && !['mousedown', 'dragstart', 'drop', 'dragend'].includes(event.type)) return;
+    report(JSON.stringify({ type: event.type }));
+  }
+  let expected = target;
+  while (true) {
+    const root = expected.getRootNode(), receiver = root.host ? root : win;
+    const local = expected, callback = event => listener(event, local);
+    listeners.push({ receiver, callback, types });
+    for (const type of types) receiver.addEventListener(type, callback, { capture: true, passive: false });
+    if (!root.host) break;
+    expected = root.host;
+  }
+  if (stage === 'source' && html5) {
+    const callback = event => listener(event, target), types = ['dragend'];
+    listeners.push({ receiver: target, callback, types });
+    target.addEventListener('dragend', callback, true);
+  }
+  // Pointer capture and movement can leave the source's closed shadow root.
+  if (stage === 'source' && target.getRootNode().host && !html5) {
+    const callback = event => listener(event, target), types = ['mousemove', 'mouseup'];
+    listeners.push({ receiver: win, callback, types });
+    for (const type of types) win.addEventListener(type, callback, { capture: true, passive: false });
+  }
+  let timer;
+  function stop() {
+    clearTimeout(timer);
+    for (const { receiver, callback, types } of listeners) for (const type of types) receiver.removeEventListener(type, callback, true);
+    delete win[name];
+  }
+  timer = win.setTimeout(stop, expiryMs);
+  return { stop };
+}

package/extension/evaluate.js

@@ -0,0 +1,131 @@
+// Deliberately a page expression API, not a raw CDP transport.
+const CAPTURE_CHARS = 1000000, CAPTURE_NODES = 50000;
+async function evaluatePage(cdp, tabId, args) {
+  const timeout = args.timeout_ms ?? 10000, maxChars = args.max_chars ?? 20000;
+  if (typeof args.expression !== 'string' || !args.expression.trim() || args.expression.length > 100000)
+    throw new Error('expression must contain 1..100000 characters of JavaScript');
+  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 30000) throw new Error('timeout_ms must be 100..30000');
+  if (!Number.isInteger(maxChars) || maxChars < 1 || maxChars > 100000) throw new Error('max_chars must be 1..100000');
+  let timer;
+  try {
+    const response = await Promise.race([
+      cdp(tabId, 'Runtime.evaluate', {
+        expression: `(async () => { let result = await (\n${args.expression}\n); if (typeof result === "function") result = await result(); return ${args.result_type === 'element' ? 'result' : `(${serializeEvaluation.toString()})(result, ${CAPTURE_CHARS}, ${CAPTURE_NODES})`}; })()`,
+        ...(args.result_type === 'element' ? { objectGroup: 'browser-attach-evaluation' } : {}), ...(args.context_id != null ? { contextId: args.context_id } : {}), awaitPromise: true, returnByValue: args.result_type !== 'element', userGesture: false, timeout,
+      }),
+      new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error(
+        'JavaScript evaluation timed out. It may still run or have changed the page; observe before continuing. Do not replay automatically.'
+      )), timeout); }),
+    ]);
+    if (response.exceptionDetails) throw new Error(response.exceptionDetails.exception?.description || response.exceptionDetails.text);
+    if (args.result_type === 'element') {
+      if (response.result?.subtype !== 'node' || !response.result.objectId) throw new Error('Element result must be one connected DOM element, not JSON/array/null');
+      return { element: response.result };
+    }
+    if (!response.result?.value || typeof response.result.value.truncated !== 'boolean') throw new Error('Invalid evaluation result');
+    return { ...response.result.value, scope: args.frame || args.frame_id ? 'frame' : 'main_frame', ...(args.evaluation_frame ? { frame_id: args.evaluation_frame } : {}), observe_again: true };
+  } catch (error) {
+    throw new Error(`Evaluation failed; page effects may already have occurred. ${String(error.message).slice(0, 12000)}`);
+  } finally { clearTimeout(timer); }
+}
+
+// Runs in the page. Bound traversal before transferring the result across CDP.
+// Preserve ordinary JSON; explicitly mark values that JSON cannot represent.
+export function serializeEvaluation(value, maxChars, maxNodes = 1000) {
+  const seen = new WeakSet();
+  let nodes = 0, chars = 0, truncated = false;
+  const mark = type => ({ $type: type });
+  function visit(item, depth) {
+    if (++nodes > maxNodes || depth > 8 || chars > maxChars) { truncated = true; return mark('truncated'); }
+    if (item === null || typeof item === 'boolean') return item;
+    if (typeof item === 'number') return Number.isFinite(item) && !Object.is(item, -0) ? item : { $type: 'number', value: String(Object.is(item, -0) ? '-0' : item) };
+    if (typeof item === 'string') {
+      const text = item.slice(0, Math.max(0, maxChars - chars));
+      chars += text.length;
+      if (text.length !== item.length) truncated = true;
+      return text;
+    }
+    if (typeof item === 'bigint') return { $type: 'bigint', value: visit(String(item), depth + 1) };
+    if (typeof item !== 'object') return mark(typeof item);
+    if (seen.has(item)) return mark('circular_or_repeated');
+    seen.add(item);
+    if (item instanceof Date) return { $type: 'date', value: String(item) };
+    if (item instanceof Error) return { $type: 'error', name: visit(item.name, depth + 1), message: visit(item.message, depth + 1) };
+    if (Array.isArray(item)) {
+      const output = [];
+      // Do not copy a sparse index into an array with an unbounded length.
+      for (let i = 0; i < item.length && nodes < maxNodes && chars < maxChars && depth < 8; i++) {
+        const property = Object.getOwnPropertyDescriptor(item, String(i));
+        output.push(!property ? visit(undefined, depth + 1) : 'value' in property ? visit(property.value, depth + 1) : (nodes++, mark('accessor')));
+      }
+      if (output.length < item.length) truncated = true;
+      return output;
+    }
+    const output = Object.create(null);
+    for (const key in item) {
+      if (!Object.prototype.hasOwnProperty.call(item, key)) continue;
+      if (nodes >= maxNodes || chars + key.length > maxChars || depth >= 8) { truncated = true; break; }
+      chars += key.length;
+      const property = Object.getOwnPropertyDescriptor(item, key);
+      const result = property && 'value' in property ? visit(property.value, depth + 1) : (nodes++, mark('accessor'));
+      Object.defineProperty(output, key, { value: result, enumerable: true, configurable: true, writable: true });
+    }
+    return output;
+  }
+  const result = visit(value, 0);
+  const json = JSON.stringify(result);
+  // Escaped strings and property names also count toward the transfer budget.
+  // Never emit half a serialized JSON document. Keep the payload structured,
+  // and state explicitly when the capture budget lost information.
+  if (json.length > maxChars) return { value: { $type: 'truncated', reason: 'serialized_size', required_chars: json.length }, truncated: true };
+  return { value: result, truncated };
+}
+
+// One bounded immutable result per claimed tab. Continuations never execute JS.
+export function createEvaluations(cdp) {
+  const results = new Map();
+  async function read(tabId, args) {
+    const max = args.max_chars ?? 20000;
+    if (!Number.isInteger(max) || max < 1 || max > 100000) throw new Error('max_chars must be 1..100000');
+    let state;
+    if (args.cursor != null) {
+      state = results.get(tabId);
+      if (!state || state.cursor !== args.cursor) throw new Error('Evaluation cursor is stale or unknown; results expire on navigation, release or a new evaluation.');
+      if (args.expression != null) throw new Error('Provide cursor or expression, never both');
+    } else {
+      // Navigation/detach may arrive while the CDP promise is pending. A late
+      // reply must not resurrect cached page data after cleanup.
+      const pending = { frameId: args.evaluation_frame };
+      results.set(tabId, pending);
+      let result;
+      try { result = await evaluatePage(cdp, args.target || tabId, args); }
+      catch (error) { if (results.get(tabId) === pending) results.delete(tabId); throw error; }
+      if (results.get(tabId) !== pending) throw new Error('Document or claim changed during evaluation; effects may already have occurred. Result was discarded. Observe before continuing; do not replay automatically.');
+      if (result.element) { results.delete(tabId); return result; }
+      const kind = Array.isArray(result.value) ? 'array' : typeof result.value === 'string' ? 'string' :
+        result.value && typeof result.value === 'object' ? 'object' : 'scalar';
+      state = Object.assign(pending, { result, kind, offset: 0, token: crypto.randomUUID(), cursor: null,
+        items: kind === 'object' ? Object.entries(result.value) : result.value });
+    }
+    const { kind, items, offset, result } = state;
+    const length = kind === 'scalar' ? 1 : items.length;
+    const make = end => kind === 'string' ? items.slice(offset, end) : kind === 'array' ? items.slice(offset, end) :
+      kind === 'object' ? Object.fromEntries(items.slice(offset, end)) : items;
+    let low = offset, high = length;
+    while (low < high) {
+      const mid = Math.ceil((low + high) / 2);
+      if (JSON.stringify(make(mid)).length <= max) low = mid; else high = mid - 1;
+    }
+    if ((length > offset && low === offset) || JSON.stringify(make(low)).length > max) {
+      state.cursor ??= `${state.token}@${offset}`;
+      return { scope: result.scope, ...(result.frame_id ? { frame_id: result.frame_id } : {}), result_kind: kind, budget_too_small: true, next_cursor: state.cursor,
+        required_chars: JSON.stringify(make(Math.min(length, offset + 1))).length,
+        note: 'Increase max_chars (allowed 1..100000) and continue with this cursor. Select smaller fields if an individual item exceeds 100000 characters.' };
+    }
+    state.offset = low;
+    state.cursor = low < length ? `${state.token}@${low}` : null;
+    return { ...result, value: make(low), result_kind: kind, has_more: low < length,
+      next_cursor: state.cursor, capture_truncated: result.truncated, truncated: result.truncated || low < length };
+  }
+  return { read, forgetFrame(tabId, frameId) { if (results.get(tabId)?.frameId === frameId) results.delete(tabId); }, forget: tabId => results.delete(tabId) };
+}