@evan_zhong/browser-attach 0.21.0 → 0.22.0

package/extension/pointer.js

@@ -0,0 +1,243 @@
+import { deadline, waitForTarget } from './actionability.js';
+import { offsetOption } from './motion.js';
+
+export function createPointer(cdp, value, viewport, position, sessions, getTab, getWindow) {
+  async function assertReady(tabId, budget, action, args = {}) {
+    const inactiveClick = action === 'click' && (args.button ?? 'left') === 'left' &&
+      (args.click_count ?? 1) === 1 && (args.modifiers ?? []).length === 0;
+    const timeout = Math.min(500, budget.remaining());
+    const guidance = 'Call browser_tab_control action=activate with this tab_handle, then browser_snapshot and retry the requested pointer action. If focus is still unavailable, restore/focus the browser window. No input was dispatched.';
+    let timer;
+    try {
+      if (timeout <= 0) throw new Error('input deadline expired before the readiness check');
+      return await Promise.race([
+        (async () => {
+          const tab = await getTab(tabId);
+          if ((!tab.active && !inactiveClick) || tab.discarded || tab.frozen) throw new Error(`tab not active or renderer suspended (active=${tab.active}, discarded=${!!tab.discarded}, frozen=${!!tab.frozen})`);
+          const window = await getWindow(tab.windowId);
+          if (window.state === 'minimized') throw new Error('browser window is minimized');
+          const state = value(await cdp(tabId, 'Runtime.evaluate', {
+            expression: '({visibility_state: document.visibilityState, has_focus: document.hasFocus()})', returnByValue: true,
+          }));
+          if (typeof state?.visibility_state !== 'string' || typeof state.has_focus !== 'boolean') throw new Error('page readiness unavailable');
+          // A hidden renderer can still receive a complete click, while an
+          // isolated move or drag may stall. Delivery still needs a trusted receipt.
+          return { ...state, tab_active: tab.active, window_focused: window.focused };
+        })(),
+        new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error(`readiness check did not respond within ${timeout} ms`)), timeout); }),
+      ]);
+    } catch (error) {
+      throw Object.assign(new Error(`TAB_NOT_READY: Native pointer input not dispatched: ${error.message}. ${guidance}`), { input_dispatched: false });
+    } finally { clearTimeout(timer); }
+  }
+  async function prepare(tabId, node, args) {
+    offsetOption(args);
+    if (!!node === (args.x != null || args.y != null)) throw new Error('Provide either ref/selector or x/y');
+    if (args.coordinate_space != null && !['viewport', 'document'].includes(args.coordinate_space)) throw new Error('coordinate_space must be viewport or document');
+    if (node && args.coordinate_space != null) throw new Error('coordinate_space applies to coordinate clicks only');
+    const budget = args.budget || deadline(args.timeout_ms);
+    const obstruction = (detail, diagnostics) => Object.assign(new Error(`${detail}. ${budget.has_dispatched()
+      ? 'Input has already been dispatched. Outcome is unknown; observe before continuing. Do not replay automatically.'
+      : 'No input was dispatched.'}`), { outcome_unknown: budget.has_dispatched(), input_dispatched: budget.has_dispatched(), diagnostics });
+    let target = node?.target || { tabId };
+    const send = (method, params) => budget.run(() => cdp(target, method, params));
+    let point, view;
+    if (node) {
+      await waitForTarget(cdp, value, target, node, budget);
+      if (args.scroll !== false) await send('DOM.scrollIntoViewIfNeeded', { backendNodeId: node.backendNodeId });
+      await waitForTarget(cdp, value, target, node, budget);
+      const { quads } = await send('DOM.getContentQuads', { backendNodeId: node.backendNodeId });
+      view = await budget.run(() => viewport(target));
+      for (const quad of quads || []) {
+        point = clippedPoint(quad, view, args.offset);
+        if (point) break;
+      }
+      if (!point) throw obstruction('Element has no visible click point. Inspect a screenshot', {
+        reason: 'no_visible_click_point', frame_id: node.frameId, viewport: view, quads: quads || [],
+      });
+    } else {
+      view = await budget.run(() => viewport(target));
+      if (args.coordinate_space === 'document') {
+        if (!Number.isFinite(args.x) || !Number.isFinite(args.y) || args.x < 0 || args.y < 0) throw new Error('Document coordinates must be finite and nonnegative');
+        const x = args.x - view.scroll_x, y = args.y - view.scroll_y;
+        if (args.scroll !== false && (x < 0 || y < 0 || x >= view.width || y >= view.height)) {
+          const left = x < 0 || x >= view.width ? Math.max(0, args.x - view.width / 2) : view.scroll_x;
+          const top = y < 0 || y >= view.height ? Math.max(0, args.y - view.height / 2) : view.scroll_y;
+          value(await send('Runtime.evaluate', { returnByValue: true,
+            expression: `scrollTo({left:${left},top:${top},behavior:'instant'})` }));
+          view = await budget.run(() => viewport(target));
+        }
+        point = position(view, args.x - view.scroll_x, args.y - view.scroll_y);
+      } else point = position(view, args.x, args.y);
+    }
+    // DOM hit testing uses document CSS coordinates; Input uses viewport CSS coordinates.
+    let hitNode = await send('DOM.getNodeForLocation', {
+      x: Math.floor(point.x + view.scroll_x), y: Math.floor(point.y + view.scroll_y), includeUserAgentShadowDOM: true,
+    });
+    // Coordinate input starts in the root viewport; descend into a remote frame
+    // before resolving backend ids or installing isolated-world verification.
+    const visited = new Set();
+    while (!node) {
+      const description = await send('DOM.describeNode', { backendNodeId: hitNode.backendNodeId, depth: 0 });
+      const childId = description.node.frameId, child = childId && sessions.target(tabId, childId);
+      if (!child?.sessionId || child.sessionId === target.sessionId) break;
+      if (visited.has(child.sessionId)) throw new Error('Frame hit-test cycle; no input was dispatched.');
+      visited.add(child.sessionId);
+      const { model } = await send('DOM.getBoxModel', { backendNodeId: hitNode.backendNodeId });
+      const childView = await budget.run(() => viewport(child));
+      point = framePoint(point, model.content, childView, true);
+      target = child; view = childView;
+      hitNode = await send('DOM.getNodeForLocation', { x: Math.floor(point.x + view.scroll_x), y: Math.floor(point.y + view.scroll_y), includeUserAgentShadowDOM: true });
+    }
+    let { backendNodeId } = hitNode;
+    const { frameId } = hitNode;
+    let hit = await send('DOM.resolveNode', { backendNodeId, objectGroup: 'browser-attach' });
+    const pseudo = hit.object.className === 'CSSPseudoElement';
+    if (pseudo || hit.object.className === 'ShadowRoot') {
+      let localPoint = point;
+      if (!pseudo && frameId && (await send('Page.getFrameTree')).frameTree.frame.id !== frameId) {
+        // Same-process frame quads are session-relative, while ShadowRoot hit
+        // testing expects the owning document's viewport coordinates.
+        const owner = await send('DOM.getFrameOwner', { frameId });
+        const { model } = await send('DOM.getBoxModel', { backendNodeId: owner.backendNodeId });
+        const { executionContextId } = await send('Page.createIsolatedWorld', { frameId, worldName: 'browser-attach-locator' });
+        const frameView = value(await send('Runtime.evaluate', { contextId: executionContextId,
+          expression: '({width: innerWidth, height: innerHeight})', returnByValue: true }));
+        localPoint = framePoint(point, model.content, frameView, true);
+      }
+      const normalized = await send('Runtime.callFunctionOn', { objectId: hit.object.objectId,
+        functionDeclaration: normalizeHit.toString(), arguments: [{ value: localPoint.x }, { value: localPoint.y }], objectGroup: 'browser-attach' });
+      value(normalized);
+      if (!normalized.result?.objectId) throw new Error('Hit element could not be resolved; no input was dispatched.');
+      hit = { object: normalized.result };
+      const { node: origin } = await send('DOM.describeNode', { objectId: hit.object.objectId });
+      backendNodeId = origin.backendNodeId;
+    }
+    const hitTarget = value(await send('Runtime.callFunctionOn', { objectId: hit.object.objectId,
+      functionDeclaration: describeHit.toString(), returnByValue: true }));
+    if (pseudo) hitTarget.pseudo_element = true;
+    let relation = null;
+    if (node) {
+      relation = value(await send('Runtime.callFunctionOn', {
+        objectId: node.objectId, functionDeclaration: hitRelation.toString(),
+        arguments: [{ objectId: hit.object.objectId }], returnByValue: true,
+      }));
+      if (!relation) throw obstruction(`Another element covers this ref. hit_target=${JSON.stringify(hitTarget)}; point=${JSON.stringify(point)}; frame_id=${JSON.stringify(node.frameId)}`,
+        { reason: 'obstructed', hit_target: hitTarget, point, coordinate_space: 'session_viewport_css_pixels', frame_id: node.frameId, hit_relation: null });
+    }
+    // Dispatch through the root widget so overlays in ancestor documents cannot
+    // be bypassed by sending directly to an OOPIF widget. Guard every boundary.
+    const boundaries = [];
+    let rootPoint = point, current = target, currentView = view;
+    while (current.sessionId) {
+      const parent = sessions.parent(tabId, current.sessionId);
+      const owner = await budget.run(() => cdp(parent.target, 'DOM.getFrameOwner', { frameId: parent.frameId }));
+      const { model } = await budget.run(() => cdp(parent.target, 'DOM.getBoxModel', { backendNodeId: owner.backendNodeId }));
+      rootPoint = framePoint(rootPoint, model.content, currentView);
+      const parentView = await budget.run(() => viewport(parent.target));
+      position(parentView, rootPoint.x, rootPoint.y);
+      const parentHit = await budget.run(() => cdp(parent.target, 'DOM.getNodeForLocation', {
+        x: Math.floor(rootPoint.x + parentView.scroll_x), y: Math.floor(rootPoint.y + parentView.scroll_y), includeUserAgentShadowDOM: true,
+      }));
+      if (parentHit.backendNodeId !== owner.backendNodeId) {
+        let blocker;
+        try {
+          const diagnostic = budget.child(200);
+          const resolved = await diagnostic.run(() => cdp(parent.target, 'DOM.resolveNode', { backendNodeId: parentHit.backendNodeId, objectGroup: 'browser-attach' }));
+          blocker = value(await diagnostic.run(() => cdp(parent.target, 'Runtime.callFunctionOn', { objectId: resolved.object.objectId,
+            functionDeclaration: describeHit.toString(), returnByValue: true })));
+        } catch { /* Preserve the obstruction error even if its node disappears. */ }
+        throw obstruction(`Another element covers this frame. hit_target=${JSON.stringify(blocker ?? { backend_node_id: parentHit.backendNodeId })}; point=${JSON.stringify(rootPoint)}; blocked_frame_id=${JSON.stringify(parent.frameId)}`,
+          { reason: 'frame_obstructed', hit_target: blocker ?? null, point: rootPoint, coordinate_space: 'session_viewport_css_pixels', blocked_frame_id: parent.frameId });
+      }
+      const ownerFrameId = parent.ownerFrameId || (await budget.run(() => cdp(parent.target, 'Page.getFrameTree'))).frameTree.frame.id;
+      boundaries.push({ target: parent.target, backendNodeId: owner.backendNodeId, frameId: ownerFrameId });
+      current = parent.target; currentView = parentView;
+    }
+    return { target, point: rootPoint, hitTarget, relation, frameId: node?.frameId || frameId, backendNodeId: node?.backendNodeId || backendNodeId, boundaries };
+  }
+  return { assertReady, prepare };
+}
+
+export function describeHit() {
+  const element = this.nodeType === 3 ? this.parentElement : this;
+  if (element?.nodeType !== 1) throw new Error('Hit target is not an Element; no input was dispatched.');
+  let clickable, disabled = false, nativeSelect = false;
+  for (let parent = element; parent; parent = parent.assignedSlot || parent.parentElement || parent.getRootNode().host) {
+    if (parent.tagName === 'SELECT' || parent.tagName === 'LABEL' && parent.control?.tagName === 'SELECT') nativeSelect = true;
+    if (!clickable && parent.matches('button,a[href],input,select,textarea,summary,[role="button"],[role="link"],[onclick]')) clickable = parent;
+    if (parent.matches(':disabled,[inert],[aria-disabled="true"]')) disabled = true;
+  }
+  const rect = element.getBoundingClientRect(), style = element.ownerDocument.defaultView.getComputedStyle(element);
+  return { tag: element.tagName?.toLowerCase(), id: element.id || null, text: (element.innerText || element.textContent || '').slice(0, 300),
+    rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, coordinate_space: 'frame_viewport_css_pixels',
+    position: style.position, z_index: style.zIndex, visibility: style.visibility,
+    role: element.getAttribute('role'), disabled, clickable_hint: !!clickable,
+    native_select: nativeSelect,
+    clickable_target: clickable ? { tag: clickable.tagName.toLowerCase(), role: clickable.getAttribute('role'),
+      text: (clickable.innerText || clickable.textContent || '').slice(0, 300) } : null };
+}
+
+export function normalizeHit(x, y) {
+  let element = this.element || (this.nodeType === 3 ? this.parentElement : this);
+  if (element?.nodeType === 11 && element.host) element = element.elementFromPoint(x, y);
+  if (element?.nodeType !== 1) throw new Error('Hit test did not resolve an Element; no input was dispatched.');
+  return element;
+}
+
+export function hitRelation(hit) {
+  if (hit === this) return 'same_node';
+  for (let node = hit; node; node = node.assignedSlot || node.parentNode || node.host) {
+    if (node === this) return 'composed_descendant';
+  }
+  return null;
+}
+
+export function clippedPoint(quad, view, offset) {
+  if (offset) {
+    const { x_ratio: x, y_ratio: y } = offset;
+    const point = { x: (1 - y) * ((1 - x) * quad[0] + x * quad[2]) + y * ((1 - x) * quad[6] + x * quad[4]),
+      y: (1 - y) * ((1 - x) * quad[1] + x * quad[3]) + y * ((1 - x) * quad[7] + x * quad[5]) };
+    return point.x >= 0 && point.y >= 0 && point.x < view.width && point.y < view.height ? point : null;
+  }
+  let polygon = Array.from({ length: 4 }, (_, i) => ({ x: quad[i * 2], y: quad[i * 2 + 1] }));
+  for (const [axis, bound, lower] of [['x', 0, true], ['x', view.width - 0.01, false], ['y', 0, true], ['y', view.height - 0.01, false]]) {
+    const input = polygon; polygon = [];
+    for (let i = 0; i < input.length; i++) {
+      const a = input[i], b = input[(i + 1) % input.length];
+      const insideA = lower ? a[axis] >= bound : a[axis] <= bound;
+      const insideB = lower ? b[axis] >= bound : b[axis] <= bound;
+      if (insideA) polygon.push(a);
+      if (insideA !== insideB) {
+        const t = (bound - a[axis]) / (b[axis] - a[axis]);
+        polygon.push({ x: a.x + t * (b.x - a.x), y: a.y + t * (b.y - a.y) });
+      }
+    }
+  }
+  const twiceArea = polygon.reduce((sum, a, i) => {
+    const b = polygon[(i + 1) % polygon.length]; return sum + a.x * b.y - b.x * a.y;
+  }, 0);
+  if (Math.abs(twiceArea) < 2) return null;
+  const point = { x: 0, y: 0 };
+  for (let i = 0; i < polygon.length; i++) {
+    const a = polygon[i], b = polygon[(i + 1) % polygon.length], cross = a.x * b.y - b.x * a.y;
+    point.x += (a.x + b.x) * cross; point.y += (a.y + b.y) * cross;
+  }
+  return { x: point.x / (3 * twiceArea), y: point.y / (3 * twiceArea) };
+}
+
+// Affine transforms cover translation, scale, rotation and skew. Reject
+// perspective rather than silently clicking a wrongly transformed position.
+export function framePoint(point, quad, view, inverse = false) {
+  const [x, y, x1, y1, x2, y2, x3, y3] = quad;
+  const ax = x1 - x, ay = y1 - y, bx = x3 - x, by = y3 - y;
+  if (Math.abs(x2 - x1 - x3 + x) > 0.5 || Math.abs(y2 - y1 - y3 + y) > 0.5) throw new Error('Perspective iframe transforms are unsupported; no input was dispatched.');
+  const determinant = ax * by - ay * bx;
+  if (Math.abs(determinant) < 0.001) throw new Error('Frame has no visible content area; no input was dispatched.');
+  if (inverse) {
+    const dx = point.x - x, dy = point.y - y;
+    return { x: (dx * by - dy * bx) / determinant * view.width, y: (dy * ax - dx * ay) / determinant * view.height };
+  }
+  return { x: x + point.x / view.width * ax + point.y / view.height * bx,
+    y: y + point.x / view.width * ay + point.y / view.height * by };
+}

package/extension/screenshot.js

@@ -0,0 +1,64 @@
+import { targetOptions } from './locator.js';
+import { deadline } from './actionability.js';
+import { framePoint } from './pointer.js';
+
+export function createScreenshots(cdp, value, viewport, sessions, clickVisuals, resolveNode) {
+  async function capture(tabId, args) {
+    const view = await viewport(tabId);
+    const hasTarget = args.ref != null || args.selector != null;
+    if (!hasTarget && (args.frame || args.frame_id || args.nth != null || args.selector_type || args.name != null)) throw new Error('Element screenshot frame/nth/type/name requires an element selector');
+    if (hasTarget && args.full_page) throw new Error('Element target and full_page are mutually exclusive');
+    const clip = hasTarget ? await elementClip(tabId, args, view) : args.full_page ? await fullPageClip(tabId) : null;
+    const includeIndicators = args.include_indicators === true;
+    const hiddenError = includeIndicators ? null : await clickVisuals.visible(tabId, false);
+    if (hiddenError) throw new Error(`Could not hide click feedback for a clean screenshot: ${hiddenError}`);
+    try {
+      // Render an explicit target surface without activating its tab or window.
+      const captureClip = clip || { x: view.scroll_x, y: view.scroll_y, width: view.width, height: view.height, scale: 1 };
+      let timer;
+      let result;
+      try {
+        result = await Promise.race([
+          cdp(tabId, 'Page.captureScreenshot', { format: 'png', fromSurface: true,
+            captureBeyondViewport: true, optimizeForSpeed: true, clip: captureClip }),
+          new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error(
+            'Screenshot did not finish within 5 seconds. An inactive or occluded Chromium page may not render. Use browser_tab_control action=activate before requesting another screenshot, or use DOM/AX.'
+          )), 5000); }),
+        ]);
+      } finally { clearTimeout(timer); }
+      return { ...result, capture: { scope: hasTarget ? 'element' : clip ? 'full_page' : 'viewport', viewport: view,
+        css_width: clip?.width ?? view.width, css_height: clip?.height ?? view.height,
+        image_origin_css: { x: clip?.x ?? view.scroll_x, y: clip?.y ?? view.scroll_y },
+        click_coordinate_space: 'viewport_css_pixels', agent_indicators_included: includeIndicators } };
+    } finally { await clickVisuals.visible(tabId, true); }
+  }
+
+  async function elementClip(tabId, args, view) {
+    targetOptions(args);
+    const budget = deadline(5000);
+    const node = await resolveNode(tabId, args, budget);
+    const { model } = await budget.run(() => cdp(node.target, 'DOM.getBoxModel', { backendNodeId: node.backendNodeId }));
+    if (!model?.border) throw new Error('Element has no rendered box');
+    let points = Array.from({ length: 4 }, (_, i) => ({ x: model.border[i * 2], y: model.border[i * 2 + 1] })), target = node.target;
+    while (target.sessionId) {
+      const parent = sessions.parent(tabId, target.sessionId);
+      const owner = await budget.run(() => cdp(parent.target, 'DOM.getFrameOwner', { frameId: parent.frameId }));
+      const box = await budget.run(() => cdp(parent.target, 'DOM.getBoxModel', { backendNodeId: owner.backendNodeId }));
+      const childView = await budget.run(() => viewport(target));
+      points = points.map(p => framePoint(p, box.model.content, childView));
+      target = parent.target;
+    }
+    const x = Math.min(...points.map(p => p.x)) + view.scroll_x, y = Math.min(...points.map(p => p.y)) + view.scroll_y;
+    const width = Math.max(...points.map(p => p.x)) + view.scroll_x - x, height = Math.max(...points.map(p => p.y)) + view.scroll_y - y;
+    if (width <= 0 || height <= 0 || width * height > 40000000 || x < 0 || y < 0) throw new Error('Element capture requires a positive box within the document and at most 40 million pixels');
+    return { x, y, width, height, scale: 1 };
+  }
+
+  async function fullPageClip(tabId) {
+    const { cssContentSize } = await cdp(tabId, 'Page.getLayoutMetrics');
+    if (cssContentSize.width * cssContentSize.height > 40000000) throw new Error('Full-page capture exceeds 40 million pixels; use viewport capture');
+    return { x: 0, y: 0, width: cssContentSize.width, height: cssContentSize.height, scale: 1 };
+  }
+
+  return { capture };
+}

package/extension/scroll.js

@@ -1,42 +1,142 @@
-export function scrollOptions(args) {
-  if (!['dom', 'wheel'].includes(args.mode ?? 'dom')) throw new Error('Scroll mode must be dom or wheel');
-  if (!Number.isFinite(args.delta_x ?? 0) || args.delta_y != null && !Number.isFinite(args.delta_y)) throw new Error('Scroll deltas must be finite');
-  if (!args.until && !Number.isFinite(args.delta_y)) throw new Error('delta_y is required without until');
-  if (args.until) {
-    if (args.mode === 'wheel') throw new Error('until search requires explicit DOM scroll mode');
-    const { text, selector } = args.until;
-    if (typeof text !== 'string' || !text || text.length > 2000 || selector != null && (typeof selector !== 'string' || !selector)) throw new Error('until requires nonempty text and optional CSS selector');
-    if (!Number.isInteger(args.max_steps ?? 100) || (args.max_steps ?? 100) < 1 || (args.max_steps ?? 100) > 500) throw new Error('max_steps must be 1..500');
-  }
-}
-
-export function scrollElement(dx, dy) {
-  if (!this.isConnected) throw new Error('Scroll container is detached');
-  const before = { x: this.scrollLeft, y: this.scrollTop };
-  this.scrollBy({ left: dx, top: dy ?? Math.max(1, this.clientHeight * 0.8), behavior: 'instant' });
-  const after = { x: this.scrollLeft, y: this.scrollTop, width: this.scrollWidth, height: this.scrollHeight,
-    client_width: this.clientWidth, client_height: this.clientHeight };
-  return { scrolled: before.x !== after.x || before.y !== after.y, before, after, method: 'dom_scroll', scope: 'element' };
-}
-
-export function scrollState() {
-  if (!this.isConnected) throw new Error('Scroll container is detached');
-  return { x: this.scrollLeft, y: this.scrollTop, width: this.scrollWidth, height: this.scrollHeight,
-    client_width: this.clientWidth, client_height: this.clientHeight };
-}
-
-export function findScrollText(text, selector) {
-  if (!this.isConnected) throw new Error('Scroll container detached');
-  const elements = this.querySelectorAll(selector || '*');
-  if (elements.length > 10000) throw new Error('Scroll search exceeds 10000 candidates; scope until.selector');
-  const matches = [];
-  for (const element of elements) {
-    if (!(element.textContent || '').includes(text)) continue;
-    const rect = element.getBoundingClientRect();
-    if (rect.width > 0 && rect.height > 0 && element.ownerDocument.defaultView.getComputedStyle(element).visibility === 'visible') matches.push(element);
-  }
-  // Document order keeps each subtree contiguous, even after filtering.
-  const leaves = matches.filter((element, index) => index === matches.length - 1 || !element.contains(matches[index + 1]));
-  if (leaves.length > 1) throw new Error(`Scroll text must match one element; matched ${leaves.length}. Scope until.selector`);
-  return leaves[0] || null;
-}
+import { resolveSelector } from './locator.js';
+
+export function scrollOptions(args) {
+  if (!['dom', 'wheel'].includes(args.mode ?? 'dom')) throw new Error('Scroll mode must be dom or wheel');
+  if (!Number.isFinite(args.delta_x ?? 0) || args.delta_y != null && !Number.isFinite(args.delta_y)) throw new Error('Scroll deltas must be finite');
+  if (!args.until && !Number.isFinite(args.delta_y)) throw new Error('delta_y is required without until');
+  if (args.until) {
+    if (args.mode === 'wheel') throw new Error('until search requires explicit DOM scroll mode');
+    const { text, selector } = args.until;
+    if (typeof text !== 'string' || !text || text.length > 2000 || selector != null && (typeof selector !== 'string' || !selector)) throw new Error('until requires nonempty text and optional CSS selector');
+    if (!Number.isInteger(args.max_steps ?? 100) || (args.max_steps ?? 100) < 1 || (args.max_steps ?? 100) > 500) throw new Error('max_steps must be 1..500');
+  }
+}
+
+export function scrollElement(dx, dy) {
+  if (!this.isConnected) throw new Error('Scroll container is detached');
+  const before = { x: this.scrollLeft, y: this.scrollTop };
+  this.scrollBy({ left: dx, top: dy ?? Math.max(1, this.clientHeight * 0.8), behavior: 'instant' });
+  const after = { x: this.scrollLeft, y: this.scrollTop, width: this.scrollWidth, height: this.scrollHeight,
+    client_width: this.clientWidth, client_height: this.clientHeight };
+  return { scrolled: before.x !== after.x || before.y !== after.y, before, after, method: 'dom_scroll', scope: 'element' };
+}
+
+export function scrollState() {
+  if (!this.isConnected) throw new Error('Scroll container is detached');
+  return { x: this.scrollLeft, y: this.scrollTop, width: this.scrollWidth, height: this.scrollHeight,
+    client_width: this.clientWidth, client_height: this.clientHeight };
+}
+
+export function findScrollText(text, selector) {
+  if (!this.isConnected) throw new Error('Scroll container detached');
+  const elements = this.querySelectorAll(selector || '*');
+  if (elements.length > 10000) throw new Error('Scroll search exceeds 10000 candidates; scope until.selector');
+  const matches = [];
+  for (const element of elements) {
+    if (!(element.textContent || '').includes(text)) continue;
+    const rect = element.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0 && element.ownerDocument.defaultView.getComputedStyle(element).visibility === 'visible') matches.push(element);
+  }
+  // Document order keeps each subtree contiguous, even after filtering.
+  const leaves = matches.filter((element, index) => index === matches.length - 1 || !element.contains(matches[index + 1]));
+  if (leaves.length > 1) throw new Error(`Scroll text must match one element; matched ${leaves.length}. Scope until.selector`);
+  return leaves[0] || null;
+}
+
+export function createScrolling(cdp, value, sessions, pointer, viewport, position, observations, currentClaim) {
+  async function scroll(tabId, node, args) {
+    if (args.until != null) {
+      const { text, selector } = args.until;
+      const maxSteps = args.max_steps ?? 100;
+      const root = node || await resolveSelector(cdp, value, sessions, tabId, { selector: 'html' }, args.budget);
+      const claim = currentClaim(tabId), version = observations.version(tabId), frameVersion = observations.frameVersion(tabId, root.frameId);
+      let last;
+      for (let step = 0; step <= maxSteps;) {
+        if (currentClaim(tabId) !== claim || observations.version(tabId) !== version || observations.frameVersion(tabId, root.frameId) !== frameVersion) throw new Error('Document/frame/control changed during scroll search; observe before continuing');
+        const found = await args.budget.run(() => cdp(root.target, 'Runtime.callFunctionOn', { objectId: root.objectId,
+          functionDeclaration: findScrollText.toString(), arguments: [{ value: text }, { value: selector }], objectGroup: 'browser-attach-search' }));
+        value(found);
+        if (found.result?.objectId) {
+          const result = await observations.rememberElement(tabId, root.target, found.result.objectId, root.frameId, args.budget);
+          await args.budget.run(() => cdp(root.target, 'Runtime.releaseObjectGroup', { objectGroup: 'browser-attach-search' }));
+          return { found: true, ...result, scroll_steps: step, application_result: 'not_checked', observe_again: true };
+        }
+        if (step === maxSteps) break;
+        if (last?.scrolled === false) {
+          // A boundary may precede lazy loading. Observe without repeating a
+          // no-op scroll until content grows, a match appears, or time runs out.
+          const current = value(await args.budget.run(() => cdp(root.target, 'Runtime.callFunctionOn', { objectId: root.objectId,
+            functionDeclaration: scrollState.toString(), returnByValue: true })));
+          if (JSON.stringify(current) === JSON.stringify(last.after)) { await args.budget.run(() => new Promise(resolve => setTimeout(resolve, 50))); continue; }
+        }
+        args.budget.dispatch();
+        last = value(await args.budget.run(() => cdp(root.target, 'Runtime.callFunctionOn', { objectId: root.objectId,
+          functionDeclaration: scrollElement.toString(), arguments: [{ value: args.delta_x ?? 0 }, { value: args.delta_y ?? null }], returnByValue: true })));
+        step++;
+        await args.budget.run(() => new Promise(resolve => setTimeout(resolve, 50)));
+      }
+      throw Object.assign(new Error(`Scroll search did not find ${JSON.stringify(text)} within ${maxSteps} steps; current=${JSON.stringify(last)}. Content may still load later. Scrolling may already have occurred.`), { outcome_unknown: true });
+    }
+    const mode = args.mode ?? 'dom';
+    const budget = args.budget;
+    const view = await budget.run(() => viewport(tabId));
+    if (node && mode === 'dom') {
+      budget.dispatch();
+      return { ...value(await budget.run(() => cdp(node.target, 'Runtime.callFunctionOn', { objectId: node.objectId,
+        functionDeclaration: scrollElement.toString(), arguments: [{ value: args.delta_x ?? 0 }, { value: args.delta_y }], returnByValue: true }))), observe_again: true };
+    }
+    const point = node ? (await pointer.prepare(tabId, node, { budget })).point : position(view, args.x ?? view.width / 2, args.y ?? view.height / 2);
+    budget.dispatch();
+    if (mode === 'wheel') {
+      // Root-widget routing respects ancestor overlays and OOPIF boundaries.
+      // A protocol acknowledgement does not prove a page handler ran or scrolled.
+      await budget.run(() => cdp(tabId, 'Input.dispatchMouseEvent', {
+        type: 'mouseWheel', ...point, deltaX: args.delta_x ?? 0, deltaY: args.delta_y,
+        button: 'none', buttons: 0, modifiers: 0,
+      }));
+      return { dispatched: true, method: 'native_wheel', at: point, coordinate_space: 'viewport_css_pixels',
+        application_result: 'not_checked', observe_again: true };
+    }
+    const result = value(await budget.run(() => cdp(tabId, 'Runtime.evaluate', { returnByValue: true,
+      expression: `(${scrollAtPoint.toString()})(${point.x},${point.y},${args.delta_x ?? 0},${args.delta_y})` })));
+    return { ...result, observe_again: true };
+  }
+  return { scroll };
+}
+
+function scrollAtPoint(x, y, dx, dy) {
+  let doc = document;
+  let element = doc.elementFromPoint(x, y);
+  const enteredShadowHosts = new Set();
+  while (element) {
+    if (element.tagName === 'IFRAME') {
+      const frame = element;
+      const rect = frame.getBoundingClientRect();
+      try { doc = frame.contentDocument; } catch { doc = null; }
+      if (!doc) throw new Error('Cross-origin iframe scrolling is unavailable; scroll the outer page or use the website controls.');
+      x -= rect.left + frame.clientLeft; y -= rect.top + frame.clientTop;
+      element = doc.elementFromPoint(x, y);
+      continue;
+    }
+    if (element.shadowRoot && !enteredShadowHosts.has(element)) {
+      enteredShadowHosts.add(element);
+      const inner = element.shadowRoot.elementFromPoint(x, y);
+      if (inner && inner !== element) { element = inner; continue; }
+    }
+    const style = doc.defaultView.getComputedStyle(element);
+    const canX = /auto|scroll|overlay/.test(style.overflowX) && element.scrollWidth > element.clientWidth &&
+      ((dx > 0 && element.scrollLeft < element.scrollWidth - element.clientWidth) || (dx < 0 && element.scrollLeft > 0));
+    const canY = /auto|scroll|overlay/.test(style.overflowY) && element.scrollHeight > element.clientHeight &&
+      ((dy > 0 && element.scrollTop < element.scrollHeight - element.clientHeight) || (dy < 0 && element.scrollTop > 0));
+    if (canX || canY) break;
+    const parent = element.parentElement || element.getRootNode().host;
+    if (!parent) { element = doc.scrollingElement; break; }
+    element = parent;
+  }
+  if (!element) element = doc.scrollingElement;
+  const before = { x: element.scrollLeft, y: element.scrollTop };
+  element.scrollBy({ left: dx, top: dy, behavior: 'instant' });
+  const after = { x: element.scrollLeft, y: element.scrollTop };
+  return { scrolled: before.x !== after.x || before.y !== after.y, before, after,
+    method: 'dom_scroll', scope: element === doc.scrollingElement ? 'document' : 'element' };
+}

package/extension/upload.js

@@ -0,0 +1,57 @@
+export function createUploads(cdp, value) {
+  const fileChoosers = new Map();
+  async function upload(tabId, node, args) {
+    const send = (target, method, params) => args.budget.run(() => cdp(target, method, params));
+    if (!Array.isArray(args.files) || args.files.length > 100 || args.files.some(file => typeof file !== 'string' || !file || file.includes('\0'))) {
+      throw new Error('files must contain at most 100 valid absolute file paths; [] clears selection');
+    }
+    const chooser = fileChoosers.get(tabId);
+    let target = node;
+    if (!target) {
+      if (!chooser) throw new Error('No pending file chooser. Supply a fresh file-input/label ref, or click the upload button first.');
+      const resolved = await send({ tabId, ...(chooser.sessionId ? { sessionId: chooser.sessionId } : {}) }, 'DOM.resolveNode', { backendNodeId: chooser.backendNodeId, objectGroup: 'browser-attach' });
+      if (!resolved.object?.objectId) throw new Error('File chooser input no longer exists. Observe again.');
+      target = { objectId: resolved.object.objectId, target: { tabId, ...(chooser.sessionId ? { sessionId: chooser.sessionId } : {}) } };
+    }
+    const resolved = await send(target.target, 'Runtime.callFunctionOn', {
+      objectId: target.objectId, arguments: [{ value: args.files.length }],
+      functionDeclaration: `function(count) {
+        const input = this.tagName === 'LABEL' ? this.control : this;
+        if (!input || input.tagName !== 'INPUT' || input.type !== 'file') throw new Error('Ref is not a file input or associated label');
+        if (!input.isConnected) throw new Error('File input is detached');
+        if (input.matches(':disabled')) throw new Error('File input is disabled');
+        if (input.webkitdirectory) throw new Error('Directory upload is unsupported; use a regular file input');
+        if (count > 1 && !input.multiple) throw new Error('Single-file input cannot accept multiple files');
+        return input;
+      }`, objectGroup: 'browser-attach',
+    });
+    if (resolved.exceptionDetails) value(resolved);
+    if (!resolved.result?.objectId) throw new Error('Could not resolve the file input');
+    args.budget.dispatch();
+    if (args.files.length === 0) {
+      // Chromium's native empty-path assignment does not emit input/change.
+      // Like Playwright's empty payload path, explicitly clear and notify the app.
+      value(await send(target.target, 'Runtime.callFunctionOn', { objectId: resolved.result.objectId, returnByValue: true,
+        functionDeclaration: `function() {
+          this.value = '';
+          const Event = this.ownerDocument.defaultView.Event;
+          this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+          this.dispatchEvent(new Event('change', { bubbles: true }));
+          return true;
+        }` }));
+    } else {
+      // Native CDP assignment emits input/change and preserves actual file metadata.
+      await send(target.target, 'DOM.setFileInputFiles', { objectId: resolved.result.objectId, files: args.files });
+    }
+    fileChoosers.delete(tabId);
+    return { files_set: args.files.length, cleared: args.files.length === 0, events_trusted: args.files.length > 0, observe_again: true };
+  }
+  return { upload,
+    opened(tabId, params, sessionId) {
+      if (params.backendNodeId) fileChoosers.set(tabId, { sessionId, backendNodeId: params.backendNodeId, mode: params.mode, frame_id: params.frameId });
+    },
+    pending: tabId => fileChoosers.get(tabId),
+    forget: tabId => fileChoosers.delete(tabId),
+    forgetFrames(tabId, affected) { if (affected.has(fileChoosers.get(tabId)?.frame_id)) fileChoosers.delete(tabId); },
+  };
+}