pi-chrome 0.7.0 → 0.9.1

package/extensions/chrome-profile-bridge/browser-extension/service_worker.js

@@ -4,8 +4,6 @@ const POLL_ERROR_BACKOFF_MS = 2000;
 let polling = false;
 
 function armKeepaliveAlarm() {
-  // MV3 service workers can be suspended; alarms are the supported way to
-  // wake the extension again. Chrome's minimum period is 0.5 minutes.
   chrome.alarms.create("pi-bridge-keepalive", { periodInMinutes: 0.5 });
 }
 
@@ -41,17 +39,19 @@ async function pollLoop() {
   polling = true;
   try {
     while (true) {
-      // Long-poll /next continuously. The bridge holds the request for up to ~25s when no
-      // command is pending and returns {type:"none"}; we immediately re-issue the fetch so
-      // commands sent while the SW is otherwise idle still get picked up promptly. The open
-      // fetch also keeps the MV3 service worker alive between alarm wake-ups.
       const response = await fetch(`${BRIDGE_URL}/next?name=${encodeURIComponent(CLIENT_NAME)}`, {
         cache: "no-store",
       });
       if (!response.ok) throw new Error(`bridge /next HTTP ${response.status}`);
+      const expected = response.headers.get("x-pi-chrome-version");
+      const ours = chrome.runtime.getManifest().version;
+      if (expected && expected !== ours && isVersionOlder(ours, expected)) {
+        console.warn(`[pi-chrome] extension v${ours} behind pi-chrome v${expected}; reloading extension`);
+        try { chrome.runtime.reload(); } catch {}
+        return;
+      }
       const payload = await response.json();
       if (payload.type === "command") await handleCommand(payload.command);
-      // Otherwise (type:"none"), loop and re-issue the long-poll.
     }
   } catch (error) {
     await sleep(POLL_ERROR_BACKOFF_MS);
@@ -81,6 +81,18 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function isVersionOlder(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  const n = Math.max(pa.length, pb.length);
+  for (let i = 0; i < n; i++) {
+    const x = pa[i] ?? 0, y = pb[i] ?? 0;
+    if (x < y) return true;
+    if (x > y) return false;
+  }
+  return false;
+}
+
 async function dispatch(action, params) {
   switch (action) {
     case "tab.version":
@@ -107,17 +119,30 @@ async function dispatch(action, params) {
       return { closed: tab.id };
     }
     case "page.snapshot":
-      return executeInTab(params, snapshotPage, [params.maxElements || 80]);
+      return executeInTab(params, snapshotPage, [
+        params.maxElements || 80,
+        params.containingText ?? null,
+        params.roleFilter ?? null,
+        params.nearUid ?? null,
+      ]);
     case "page.evaluate":
-      return executeInTab(params, evaluateExpression, [params.expression, params.awaitPromise !== false]);
+      return evaluateInTab(params);
     case "page.click":
       return executeActionInTab(params, clickPage, [params.selector ?? null, params.uid ?? null, params.x ?? null, params.y ?? null]);
+    case "page.hover":
+      return executeActionInTab(params, hoverPage, [params.selector ?? null, params.uid ?? null, params.x ?? null, params.y ?? null]);
+    case "page.drag":
+      return executeActionInTab(params, dragPage, [params.fromUid ?? null, params.fromSelector ?? null, params.fromX ?? null, params.fromY ?? null, params.toUid ?? null, params.toSelector ?? null, params.toX ?? null, params.toY ?? null, params.steps ?? 12]);
+    case "page.upload":
+      return executeActionInTab(params, uploadFiles, [params.selector ?? null, params.uid ?? null, params.files || []]);
     case "page.type":
       return executeActionInTab(params, typeIntoPage, [params.selector ?? null, params.uid ?? null, params.text || "", Boolean(params.pressEnter)]);
     case "page.fill":
       return executeActionInTab(params, fillPage, [params.selector ?? null, params.uid ?? null, params.text || "", params.submit === true]);
     case "page.key":
       return executeActionInTab(params, pressKeyInPage, [params.key]);
+    case "page.scroll":
+      return executeActionInTab(params, scrollPage, [params.selector ?? null, params.uid ?? null, params.deltaY ?? 0, params.deltaX ?? 0, params.steps ?? null]);
     case "page.console.list":
       return executeInTab(params, listConsoleMessages, [params.clear === true]);
     case "page.network.list":
@@ -126,38 +151,27 @@ async function dispatch(action, params) {
       return executeInTab(params, getNetworkRequest, [params.requestId]);
     case "page.waitFor":
       return executeInTab(params, waitForPage, [params.kind, params.value, params.timeoutMs || 10000, params.intervalMs || 250]);
+    case "page.probe":
+      // Lightweight capability probe for /chrome-doctor. Runs in MAIN world.
+      return executeInTab(params, probePage, []);
     case "page.navigate": {
       const tab = await getTabByParams(params);
       if (params.foreground) await bringToFront(tab);
+      if (params.initScript) {
+        // Register a one-shot document_start content script. We register, navigate, wait, then unregister.
+        await registerInitScript(tab.id, params.initScript);
+      }
       const wait = params.waitUntilLoad !== false ? waitForTabComplete(tab.id, params.timeoutMs || 15000) : Promise.resolve(undefined);
       const updated = await chrome.tabs.update(tab.id, { url: params.url });
-      await wait;
-      return formatTab(await chrome.tabs.get(updated.id));
-    }
-    case "page.screenshot": {
-      const tab = await getTabByParams(params);
-      if (params.foreground) await bringToFront(tab);
-      // captureVisibleTab requires the target tab to be the active tab in its window. Activate it
-      // without focusing the window so other apps don't get pushed behind Chrome, and restore the
-      // previous active tab afterwards to minimize disruption.
-      let previousActiveId;
-      if (!tab.active) {
-        const activeBefore = await chrome.tabs.query({ active: true, windowId: tab.windowId });
-        previousActiveId = activeBefore[0]?.id;
-        await chrome.tabs.update(tab.id, { active: true });
-      }
       try {
-        const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {
-          format: params.format || "png",
-          quality: params.format === "jpeg" ? params.quality : undefined,
-        });
-        return { dataUrl, tab: formatTab(tab) };
+        await wait;
       } finally {
-        if (previousActiveId !== undefined && previousActiveId !== tab.id) {
-          await chrome.tabs.update(previousActiveId, { active: true }).catch(() => undefined);
-        }
+        if (params.initScript) await unregisterInitScript(tab.id).catch(() => undefined);
       }
+      return formatTab(await chrome.tabs.get(updated.id));
     }
+    case "page.screenshot":
+      return takeScreenshot(params);
     default:
       throw new Error(`Unknown action: ${action}`);
   }
@@ -198,26 +212,49 @@ async function getTabByParams(params) {
   return tab;
 }
 
+// Helper sources that get concatenated into the injected MAIN-world script. Kept as separate
+// functions so callers below can reference them by `.toString()`. The helpers do not perform any
+// eval themselves — they're plain function declarations.
+const HELPER_FUNCS = [
+  getPiChromeState,
+  rememberElement,
+  elementBySelectorOrUid,
+  installPiChromeInstrumentation,
+  resolvePoint,
+  dispatchInputEvents,
+  setNativeValue,
+  normalizeKey,
+  isElementVisible,
+  occluderAt,
+  pageHash,
+  pointerEventSequence,
+  sleepPage,
+  rand,
+  dispatchPointerLikeEvent,
+  humanMoveTo,
+  humanClickPoint,
+  printableKeyCode,
+  dispatchKeyEvent,
+  typeCharacter,
+  scrollPage,
+];
+
 async function executeInTab(params, func, args) {
   const tab = await getTabByParams(params);
   if (params.foreground) await bringToFront(tab);
-  const helperSource = [
-    getPiChromeState,
-    rememberElement,
-    elementBySelectorOrUid,
-    installPiChromeInstrumentation,
-    resolvePoint,
-    dispatchInputEvents,
-    setNativeValue,
-    normalizeKey,
-  ].map((helper) => helper.toString()).join("\n");
+  const helperSource = HELPER_FUNCS.map((helper) => helper.toString()).join("\n");
   const results = await chrome.scripting.executeScript({
     target: { tabId: tab.id },
     world: "MAIN",
     func: async (helperSource, source, invocationArgs) => {
       try {
-        (0, eval)(helperSource);
-        const injected = (0, eval)(`(${source})`);
+        // Helpers are plain function declarations; injecting them via Function constructor avoids
+        // running through `eval` (which is restricted under strict CSP) and keeps them isolated.
+        new Function(helperSource).call(globalThis);
+        // The action itself is reconstructed from its source text. We use `new Function` rather
+        // than `eval` because the latter is blocked by `script-src 'self'` (no `'unsafe-eval'`)
+        // CSPs that are common on production sites.
+        const injected = new Function(helperSource + "\nreturn (" + source + ");").call(globalThis);
         return { ok: true, value: await injected(...invocationArgs) };
       } catch (error) {
         return { ok: false, error: error?.stack || error?.message || String(error) };
@@ -237,15 +274,108 @@ async function executeInTab(params, func, args) {
   return envelope?.value;
 }
 
+// Dedicated executor for page.evaluate. Doesn't go through the helper-source injection chain;
+// that chain was the root cause of `chrome_evaluate` silently returning null on pages with strict
+// CSP. We build a single Function in MAIN world and invoke it directly.
+async function evaluateInTab(params) {
+  const tab = await getTabByParams(params);
+  if (params.foreground) await bringToFront(tab);
+  const expression = String(params.expression ?? "");
+  const awaitPromise = params.awaitPromise !== false;
+  const results = await chrome.scripting.executeScript({
+    target: { tabId: tab.id },
+    world: "MAIN",
+    func: async (expression, awaitPromise) => {
+      const stringify = (v) => {
+        if (v === undefined) return { kind: "undefined" };
+        if (typeof v === "function") return { kind: "function", source: v.toString().slice(0, 500) };
+        if (typeof v === "symbol") return { kind: "symbol", description: v.description };
+        if (typeof v === "bigint") return { kind: "bigint", value: v.toString() };
+        if (v instanceof Error) return { kind: "error", name: v.name, message: v.message, stack: v.stack };
+        return v;
+      };
+      // Compile via the Function constructor. We try expression form first so callers can pass
+      // `1+1` or `document.title` without a `return`; if that's a SyntaxError we retry with the
+      // statement form so callers can use multi-statement bodies (loops, var decls, etc).
+      const compile = (src) => {
+        try {
+          return { fn: new Function(`return (async () => (${src}))();`), mode: "expression" };
+        } catch (e1) {
+          if (e1 && e1.name === "SyntaxError") {
+            try {
+              return { fn: new Function(`return (async () => { ${src} })();`), mode: "statement" };
+            } catch (e2) {
+              throw e2;
+            }
+          }
+          throw e1;
+        }
+      };
+      try {
+        const { fn } = compile(expression);
+        const value = await fn.call(globalThis);
+        const resolved = awaitPromise && value && typeof value.then === "function" ? await value : value;
+        return { ok: true, value: stringify(resolved) };
+      } catch (error) {
+        return { ok: false, error: error?.stack || error?.message || String(error) };
+      }
+    },
+    args: [expression, awaitPromise],
+  });
+  const first = results?.[0];
+  if (first?.error) {
+    const message = typeof first.error === "string" ? first.error : (first.error.message || JSON.stringify(first.error));
+    throw new Error(`chrome_evaluate failed: ${message}`);
+  }
+  const envelope = first?.result;
+  if (!envelope) throw new Error("chrome_evaluate returned no envelope from MAIN world");
+  if (envelope.ok === false) throw new Error(envelope.error || "chrome_evaluate failed");
+  const v = envelope.value;
+  // Unwrap special markers from MAIN world
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    if (v.kind === "undefined") return undefined;
+    if (v.kind === "function") return `[Function: ${v.source}]`;
+    if (v.kind === "symbol") return `[Symbol: ${v.description}]`;
+    if (v.kind === "bigint") return v.value;
+    if (v.kind === "error") throw new Error(`${v.name}: ${v.message}\n${v.stack || ""}`);
+  }
+  return v;
+}
+
 async function executeActionInTab(params, func, args) {
   const result = await executeInTab(params, func, args);
   if (params.includeSnapshot) {
-    const snapshot = await executeInTab({ ...params, foreground: false }, snapshotPage, [params.maxElements || 80]);
+    const snapshot = await executeInTab({ ...params, foreground: false }, snapshotPage, [params.maxElements || 80, null, null, null]);
     return { result, snapshot };
   }
   return result;
 }
 
+// One-shot init script registry, scoped per tab. The script source is injected at
+// document_start of the next committed navigation in that tab, in MAIN world, then cleared.
+const initScriptIds = new Map();
+async function registerInitScript(tabId, source) {
+  initScriptIds.set(tabId, source);
+}
+async function unregisterInitScript(tabId) {
+  initScriptIds.delete(tabId);
+}
+
+if (chrome.webNavigation && chrome.webNavigation.onCommitted) {
+  chrome.webNavigation.onCommitted.addListener((details) => {
+    if (details.frameId !== 0) return;
+    const source = initScriptIds.get(details.tabId);
+    if (!source) return;
+    chrome.scripting.executeScript({
+      target: { tabId: details.tabId, frameIds: [0] },
+      world: "MAIN",
+      injectImmediately: true,
+      func: (code) => { try { new Function(code).call(globalThis); } catch (e) { console.error("[pi-chrome init script]", e); } },
+      args: [source],
+    }).catch(() => undefined);
+  });
+}
+
 async function bringToFront(tab) {
   await chrome.windows.update(tab.windowId, { focused: true });
   await chrome.tabs.update(tab.id, { active: true });
@@ -268,6 +398,56 @@ function waitForTabComplete(tabId, timeoutMs) {
   });
 }
 
+async function takeScreenshot(params) {
+  const tab = await getTabByParams(params);
+  if (params.foreground) await bringToFront(tab);
+  let previousActiveId;
+  if (!tab.active) {
+    const activeBefore = await chrome.tabs.query({ active: true, windowId: tab.windowId });
+    previousActiveId = activeBefore[0]?.id;
+    await chrome.tabs.update(tab.id, { active: true });
+  }
+  try {
+    if (params.fullPage) {
+      // Tile-stitched full page capture: scroll, capture, paste, repeat.
+      const tiles = await executeInTab({ ...params, foreground: false }, captureFullPageTiles, []);
+      // captureFullPageTiles only computes scroll positions / metrics; we capture per scroll here
+      // (chrome.tabs.captureVisibleTab can't be called from MAIN world).
+      const captured = [];
+      for (const tile of tiles.tiles) {
+        await executeInTab({ ...params, foreground: false }, scrollToY, [tile.scrollY]);
+        // Small settle delay; many sites have on-scroll animations / lazy-load.
+        await sleep(120);
+        const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {
+          format: params.format || "png",
+          quality: params.format === "jpeg" ? params.quality : undefined,
+        });
+        captured.push({ y: tile.y, dataUrl });
+      }
+      await executeInTab({ ...params, foreground: false }, scrollToY, [tiles.originalScrollY]);
+      return {
+        fullPage: true,
+        tab: formatTab(tab),
+        dimensions: { width: tiles.width, height: tiles.height, viewportHeight: tiles.viewportHeight, dpr: tiles.dpr },
+        tiles: captured,
+      };
+    }
+    const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {
+      format: params.format || "png",
+      quality: params.format === "jpeg" ? params.quality : undefined,
+    });
+    return { dataUrl, tab: formatTab(tab) };
+  } finally {
+    if (previousActiveId !== undefined && previousActiveId !== tab.id) {
+      await chrome.tabs.update(previousActiveId, { active: true }).catch(() => undefined);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MAIN-world helpers (function declarations injected into the page).
+// ---------------------------------------------------------------------------
+
 function getPiChromeState() {
   const state = window.__PI_CHROME_STATE__ || {
     nextElementUid: 1,
@@ -302,6 +482,139 @@ function elementBySelectorOrUid(selector, uid) {
   return null;
 }
 
+function isElementVisible(element) {
+  if (!element || !element.getBoundingClientRect) return false;
+  const style = getComputedStyle(element);
+  if (style.visibility === "hidden" || style.display === "none") return false;
+  const rect = element.getBoundingClientRect();
+  if (rect.width === 0 || rect.height === 0) return false;
+  if (rect.bottom < 0 || rect.right < 0) return false;
+  if (rect.top > innerHeight || rect.left > innerWidth) return false;
+  return true;
+}
+
+function occluderAt(x, y, expected) {
+  const top = document.elementFromPoint(x, y);
+  if (!top || top === expected) return null;
+  if (expected && expected.contains(top)) return null;
+  if (top.contains(expected)) return null;
+  return {
+    tag: top.tagName.toLowerCase(),
+    id: top.id || undefined,
+    className: typeof top.className === "string" ? top.className : undefined,
+  };
+}
+
+function pageHash() {
+  // Cheap rolling hash used for `pageMutated`. Combines first 4kb of body innerText with the
+  // current values of inputs/textareas (which are not part of innerText) and the count of
+  // descendants of <body>. This catches: text changes, input value edits, and DOM structure
+  // changes — the three things a click/type/fill might cause.
+  const body = document.body;
+  const text = (body ? body.innerText : "").slice(0, 4000);
+  let h = 0;
+  for (let i = 0; i < text.length; i++) h = (h * 31 + text.charCodeAt(i)) | 0;
+  if (body) {
+    const inputs = body.querySelectorAll("input,textarea,select");
+    let valueBlob = "";
+    for (let i = 0; i < inputs.length && valueBlob.length < 4000; i++) {
+      const v = inputs[i].value;
+      if (typeof v === "string") valueBlob += v + "\x00";
+    }
+    for (let i = 0; i < valueBlob.length; i++) h = (h * 31 + valueBlob.charCodeAt(i)) | 0;
+    h = (h * 31 + body.getElementsByTagName("*").length) | 0;
+  }
+  return h;
+}
+
+function sleepPage(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function rand(min, max) {
+  return min + Math.random() * (max - min);
+}
+
+function dispatchPointerLikeEvent(element, type, x, y, prevX, prevY, opts = {}) {
+  const isPointer = type.startsWith("pointer");
+  const Ctor = isPointer ? PointerEvent : MouseEvent;
+  const isMove = type === "pointermove" || type === "mousemove";
+  const isUpOrClick = type === "pointerup" || type === "mouseup" || type === "click";
+  const init = {
+    bubbles: true,
+    cancelable: true,
+    view: window,
+    clientX: x,
+    clientY: y,
+    screenX: x + (window.screenX || 0),
+    screenY: y + (window.screenY || 0),
+    movementX: Number.isFinite(prevX) ? x - prevX : 0,
+    movementY: Number.isFinite(prevY) ? y - prevY : 0,
+    button: 0,
+    buttons: isMove || isUpOrClick ? 0 : 1,
+  };
+  if (isPointer) {
+    init.pointerType = "mouse";
+    init.pointerId = 1;
+    init.isPrimary = true;
+    init.width = 1;
+    init.height = 1;
+    init.pressure = opts.pressure ?? (type === "pointerdown" ? 0.5 : 0);
+    init.tangentialPressure = 0;
+    init.tiltX = 0;
+    init.tiltY = 0;
+  }
+  const ev = new Ctor(type, init);
+  element.dispatchEvent(ev);
+  return ev.defaultPrevented;
+}
+
+function pointerEventSequence(element, x, y, sequence) {
+  let defaultPrevented = false;
+  const state = getPiChromeState();
+  const prevX = state.pointer?.x;
+  const prevY = state.pointer?.y;
+  for (const type of sequence) {
+    defaultPrevented = dispatchPointerLikeEvent(element, type, x, y, prevX, prevY) || defaultPrevented;
+  }
+  state.pointer = { x, y, t: performance.now() };
+  return defaultPrevented;
+}
+
+async function humanMoveTo(x, y, steps) {
+  const state = getPiChromeState();
+  const startX = Number.isFinite(state.pointer?.x) ? state.pointer.x : rand(12, Math.max(24, innerWidth - 12));
+  const startY = Number.isFinite(state.pointer?.y) ? state.pointer.y : rand(12, Math.max(24, innerHeight - 12));
+  const n = steps || Math.max(12, Math.min(42, Math.round(Math.hypot(x - startX, y - startY) / 18)));
+  let prevX = startX, prevY = startY;
+  let defaultPrevented = false;
+  for (let i = 1; i <= n; i++) {
+    const t = i / n;
+    const ease = t * t * (3 - 2 * t);
+    const wobble = Math.sin(t * Math.PI) * 8;
+    const px = startX + (x - startX) * ease + rand(-wobble, wobble);
+    const py = startY + (y - startY) * ease + rand(-wobble, wobble);
+    const el = document.elementFromPoint(px, py) || document.body || document.documentElement;
+    defaultPrevented = dispatchPointerLikeEvent(el, "pointermove", px, py, prevX, prevY) || defaultPrevented;
+    defaultPrevented = dispatchPointerLikeEvent(el, "mousemove", px, py, prevX, prevY) || defaultPrevented;
+    prevX = px; prevY = py;
+    await sleepPage(rand(4, 18));
+  }
+  state.pointer = { x, y, t: performance.now() };
+  return defaultPrevented;
+}
+
+function humanClickPoint(point) {
+  if (!point.rect) return { x: point.x, y: point.y };
+  const rect = point.rect;
+  const insetX = Math.min(rect.width * 0.35, Math.max(2, rect.width / 2 - 1));
+  const insetY = Math.min(rect.height * 0.35, Math.max(2, rect.height / 2 - 1));
+  return {
+    x: rect.left + rect.width / 2 + rand(-insetX, insetX),
+    y: rect.top + rect.height / 2 + rand(-insetY, insetY),
+  };
+}
+
 function installPiChromeInstrumentation() {
   const state = getPiChromeState();
   if (state.instrumentationInstalled) return;
@@ -407,7 +720,7 @@ function installPiChromeInstrumentation() {
   }
 }
 
-function snapshotPage(maxElements) {
+function snapshotPage(maxElements, containingText, roleFilter, nearUid) {
   installPiChromeInstrumentation();
   const unique = (selector) => {
     try { return document.querySelectorAll(selector).length === 1; } catch { return false; }
@@ -434,11 +747,7 @@ function snapshotPage(maxElements) {
     }
     return parts.join(" > ");
   };
-  const visible = (element) => {
-    const style = getComputedStyle(element);
-    const rect = element.getBoundingClientRect();
-    return style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
-  };
+  const visible = (element) => isElementVisible(element);
   const labelFor = (element) => (
     element.getAttribute("aria-label") ||
     element.getAttribute("title") ||
@@ -448,9 +757,41 @@ function snapshotPage(maxElements) {
     element.textContent ||
     ""
   ).trim().replace(/\s+/g, " ").slice(0, 160);
-  const candidates = Array.from(document.querySelectorAll('a, button, input, textarea, select, summary, [role="button"], [role="link"], [contenteditable="true"], [tabindex]:not([tabindex="-1"])'));
+  let candidates = Array.from(document.querySelectorAll('a, button, input, textarea, select, summary, [role="button"], [role="link"], [role="menuitem"], [role="tab"], [role="checkbox"], [contenteditable="true"], [tabindex]:not([tabindex="-1"])'));
+  if (containingText) {
+    const needle = String(containingText).toLowerCase();
+    candidates = candidates.filter((element) => labelFor(element).toLowerCase().includes(needle));
+  }
+  if (roleFilter) {
+    const wanted = String(roleFilter).toLowerCase();
+    candidates = candidates.filter((element) => {
+      const role = (element.getAttribute("role") || element.tagName).toLowerCase();
+      return role === wanted;
+    });
+  }
+  let near;
+  if (nearUid) {
+    const state = getPiChromeState();
+    near = state.elements[nearUid];
+  }
+  if (near) {
+    const nearRect = near.getBoundingClientRect();
+    const cx = nearRect.left + nearRect.width / 2;
+    const cy = nearRect.top + nearRect.height / 2;
+    candidates.sort((a, b) => {
+      const ra = a.getBoundingClientRect();
+      const rb = b.getBoundingClientRect();
+      const da = Math.hypot(ra.left + ra.width / 2 - cx, ra.top + ra.height / 2 - cy);
+      const db = Math.hypot(rb.left + rb.width / 2 - cx, rb.top + rb.height / 2 - cy);
+      return da - db;
+    });
+  }
   const elements = candidates.filter(visible).slice(0, maxElements).map((element, index) => {
     const rect = element.getBoundingClientRect();
+    const style = getComputedStyle(element);
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const occluded = occluderAt(cx, cy, element);
     return {
       index,
       uid: rememberElement(element),
@@ -461,6 +802,9 @@ function snapshotPage(maxElements) {
       type: element.getAttribute("type") || undefined,
       role: element.getAttribute("role") || undefined,
       disabled: Boolean(element.disabled || element.getAttribute("aria-disabled") === "true"),
+      inert: Boolean(element.closest?.("[inert]")),
+      pointerEvents: style.pointerEvents,
+      occluded: occluded || undefined,
       rect: { x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height) },
     };
   });
@@ -470,14 +814,44 @@ function snapshotPage(maxElements) {
     viewport: { width: innerWidth, height: innerHeight, scrollX, scrollY },
     text: document.body ? document.body.innerText.replace(/\s+\n/g, "\n").trim().slice(0, 30000) : "",
     elements,
+    filter: { containingText: containingText || undefined, roleFilter: roleFilter || undefined, nearUid: nearUid || undefined },
   };
 }
 
-async function evaluateExpression(expression, awaitPromise) {
-  installPiChromeInstrumentation();
-  const indirectEval = (0, eval);
-  const value = indirectEval(expression);
-  return awaitPromise && value && typeof value.then === "function" ? await value : value;
+function probePage() {
+  // Sanity probe used by /chrome-doctor. Returns evidence that MAIN-world execution works.
+  return {
+    arithmetic: 1 + 1,
+    location: location.href,
+    title: document.title,
+    documentReady: document.readyState,
+    userAgent: navigator.userAgent.slice(0, 200),
+    webdriver: !!navigator.webdriver,
+  };
+}
+
+function captureFullPageTiles() {
+  // Returns the *plan* for tile capture; the actual chrome.tabs.captureVisibleTab calls happen
+  // in the SW. We just report the scroll positions and metrics.
+  const html = document.documentElement;
+  const body = document.body;
+  const width = Math.max(html.scrollWidth, body ? body.scrollWidth : 0, innerWidth);
+  const height = Math.max(html.scrollHeight, body ? body.scrollHeight : 0, innerHeight);
+  const viewportHeight = innerHeight;
+  const dpr = window.devicePixelRatio || 1;
+  const originalScrollY = scrollY;
+  const tiles = [];
+  let y = 0;
+  while (y < height) {
+    tiles.push({ y, scrollY: y });
+    y += viewportHeight;
+  }
+  return { width, height, viewportHeight, dpr, originalScrollY, tiles };
+}
+
+function scrollToY(y) {
+  window.scrollTo({ top: y, left: 0, behavior: "instant" });
+  return { scrollY };
 }
 
 function resolvePoint(selector, uid, x, y) {
@@ -491,13 +865,202 @@ function resolvePoint(selector, uid, x, y) {
   return { element: document.elementFromPoint(x, y), x, y, rect: undefined };
 }
 
-function clickPage(selector, uid, x, y) {
+async function clickPage(selector, uid, x, y) {
+  installPiChromeInstrumentation();
+  const before = pageHash();
   const point = resolvePoint(selector, uid, x, y);
   if (!point.element) throw new Error("No element at click point");
-  for (const type of ["pointerdown", "mousedown", "pointerup", "mouseup", "click"]) {
-    point.element.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, view: window, clientX: point.x, clientY: point.y, button: 0 }));
+  const clickPoint = humanClickPoint(point);
+  point.x = clickPoint.x;
+  point.y = clickPoint.y;
+  point.element = document.elementFromPoint(point.x, point.y) || point.element;
+  const visible = isElementVisible(point.element);
+  const occluded = occluderAt(point.x, point.y, point.element);
+  let defaultPrevented = await humanMoveTo(point.x, point.y);
+  const state = getPiChromeState();
+  const prevX = state.pointer?.x;
+  const prevY = state.pointer?.y;
+  defaultPrevented = dispatchPointerLikeEvent(point.element, "pointerdown", point.x, point.y, prevX, prevY, { pressure: 0.5 }) || defaultPrevented;
+  defaultPrevented = dispatchPointerLikeEvent(point.element, "mousedown", point.x, point.y, prevX, prevY) || defaultPrevented;
+  if (typeof point.element.focus === "function" && /^(A|BUTTON|INPUT|TEXTAREA|SELECT|SUMMARY)$/.test(point.element.tagName)) {
+    try { point.element.focus({ preventScroll: true }); } catch { try { point.element.focus(); } catch {} }
+  }
+  await sleepPage(rand(45, 140));
+  defaultPrevented = dispatchPointerLikeEvent(point.element, "pointerup", point.x, point.y, prevX, prevY) || defaultPrevented;
+  defaultPrevented = dispatchPointerLikeEvent(point.element, "mouseup", point.x, point.y, prevX, prevY) || defaultPrevented;
+  defaultPrevented = dispatchPointerLikeEvent(point.element, "click", point.x, point.y, prevX, prevY) || defaultPrevented;
+  state.pointer = { x: point.x, y: point.y, t: performance.now() };
+  // Heuristic: if the clicked thing looks like a media play affordance and the page has paused
+  // audio/video, the synthetic click may not unlock autoplay. Surface a warning.
+  let autoplayHint;
+  const label = (point.element.getAttribute("aria-label") || point.element.textContent || "").toLowerCase();
+  if (/^(play|start|begin|next|continue|unmute)/.test(label.trim())) {
+    const idleMedia = Array.from(document.querySelectorAll("audio,video")).some((m) => m.paused);
+    if (idleMedia) autoplayHint = "This element looks like a media affordance and the page has paused media. Synthetic clicks do not satisfy user-activation gates; audio/video may not start.";
   }
-  return { x: point.x, y: point.y, selector, uid, tag: point.element.tagName };
+  return {
+    x: point.x,
+    y: point.y,
+    selector,
+    uid,
+    tag: point.element.tagName,
+    isTrusted: false,
+    defaultPrevented,
+    elementVisible: visible,
+    occludedBy: occluded || undefined,
+    pageMutated: pageHash() !== before,
+    autoplayHint,
+  };
+}
+
+async function hoverPage(selector, uid, x, y) {
+  installPiChromeInstrumentation();
+  const point = resolvePoint(selector, uid, x, y);
+  if (!point.element) throw new Error("No element to hover");
+  await humanMoveTo(point.x, point.y);
+  const state = getPiChromeState();
+  const prevX = state.pointer?.x, prevY = state.pointer?.y;
+  let defaultPrevented = false;
+  for (const type of ["pointerover", "mouseover", "pointerenter", "mouseenter"]) {
+    defaultPrevented = dispatchPointerLikeEvent(point.element, type, point.x, point.y, prevX, prevY) || defaultPrevented;
+  }
+  // Small dwell so hover-intent handlers fire.
+  await sleepPage(rand(80, 220));
+  return { x: point.x, y: point.y, selector, uid, tag: point.element.tagName, defaultPrevented, isTrusted: false };
+}
+
+async function dragPage(fromUid, fromSelector, fromX, fromY, toUid, toSelector, toX, toY, steps) {
+  installPiChromeInstrumentation();
+  const before = pageHash();
+  const from = resolvePoint(fromSelector, fromUid, fromX, fromY);
+  const to = resolvePoint(toSelector, toUid, toX, toY);
+  if (!from.element) throw new Error("Drag source element not found");
+  if (!to.element) throw new Error("Drag target element not found");
+  // Move to source.
+  await humanMoveTo(from.x, from.y);
+  const state = getPiChromeState();
+  let prevX = state.pointer?.x, prevY = state.pointer?.y;
+  // Build a shared DataTransfer so HTML5 drag-and-drop handlers can populate / read it.
+  const dt = new DataTransfer();
+  const dragInit = (type, target, x, y) => {
+    const ev = new DragEvent(type, {
+      bubbles: true, cancelable: true, composed: true,
+      clientX: x, clientY: y,
+      screenX: x + (window.screenX || 0), screenY: y + (window.screenY || 0),
+      button: 0, buttons: 1, view: window,
+      dataTransfer: dt,
+    });
+    target.dispatchEvent(ev);
+    return ev;
+  };
+  dispatchPointerLikeEvent(from.element, "pointerover", from.x, from.y, prevX, prevY);
+  dispatchPointerLikeEvent(from.element, "pointerdown", from.x, from.y, prevX, prevY, { pressure: 0.5 });
+  dispatchPointerLikeEvent(from.element, "mousedown", from.x, from.y, prevX, prevY);
+  await sleepPage(rand(40, 110));
+  dragInit("dragstart", from.element, from.x, from.y);
+  dragInit("drag", from.element, from.x, from.y);
+  let lastOver = from.element;
+  const n = steps || 18;
+  for (let i = 1; i <= n; i++) {
+    const t = i / n;
+    const ease = t * t * (3 - 2 * t);
+    const wobble = Math.sin(t * Math.PI) * 6;
+    const x = from.x + (to.x - from.x) * ease + rand(-wobble, wobble);
+    const y = from.y + (to.y - from.y) * ease + rand(-wobble, wobble);
+    const overEl = document.elementFromPoint(x, y) || to.element;
+    dispatchPointerLikeEvent(overEl, "pointermove", x, y, prevX, prevY);
+    dispatchPointerLikeEvent(overEl, "mousemove", x, y, prevX, prevY);
+    if (overEl !== lastOver) {
+      dragInit("dragleave", lastOver, x, y);
+      dragInit("dragenter", overEl, x, y);
+      lastOver = overEl;
+    }
+    dragInit("dragover", overEl, x, y);
+    dragInit("drag", from.element, x, y);
+    prevX = x; prevY = y;
+    await sleepPage(rand(8, 26));
+  }
+  dispatchPointerLikeEvent(to.element, "pointerover", to.x, to.y, prevX, prevY);
+  dispatchPointerLikeEvent(to.element, "mouseover", to.x, to.y, prevX, prevY);
+  dragInit("drop", to.element, to.x, to.y);
+  dragInit("dragend", from.element, to.x, to.y);
+  dispatchPointerLikeEvent(to.element, "pointerup", to.x, to.y, prevX, prevY);
+  dispatchPointerLikeEvent(to.element, "mouseup", to.x, to.y, prevX, prevY);
+  state.pointer = { x: to.x, y: to.y, t: performance.now() };
+  return {
+    from: { x: from.x, y: from.y },
+    to: { x: to.x, y: to.y },
+    steps: n,
+    pageMutated: pageHash() !== before,
+    note: "Synthetic drag with HTML5 DragEvent + shared DataTransfer. isTrusted is still false.",
+  };
+}
+
+async function scrollPage(selector, uid, deltaY, deltaX, steps) {
+  installPiChromeInstrumentation();
+  const before = pageHash();
+  let target;
+  if (selector || uid) {
+    target = elementBySelectorOrUid(selector, uid);
+  } else {
+    target = document.scrollingElement || document.documentElement || document.body;
+  }
+  if (!target) throw new Error("No scroll target");
+  const rect = target.getBoundingClientRect ? target.getBoundingClientRect() : { left: 0, top: 0, width: innerWidth, height: innerHeight };
+  const cx = Math.max(0, Math.min(innerWidth - 1, rect.left + Math.min(rect.width, innerWidth) / 2));
+  const cy = Math.max(0, Math.min(innerHeight - 1, rect.top + Math.min(rect.height, innerHeight) / 2));
+  const n = Math.max(3, Math.min(40, steps || Math.max(3, Math.ceil(Math.abs(deltaY || 0) / 100))));
+  // Front-loaded wheel deltas, momentum-style.
+  const totalY = deltaY || 0;
+  const totalX = deltaX || 0;
+  const weights = [];
+  for (let i = 1; i <= n; i++) weights.push(1 / i);
+  const sumW = weights.reduce((a, b) => a + b, 0);
+  let movedY = 0, movedX = 0;
+  for (let i = 0; i < n; i++) {
+    const dy = totalY * (weights[i] / sumW);
+    const dx = totalX * (weights[i] / sumW);
+    const ev = new WheelEvent("wheel", {
+      bubbles: true, cancelable: true, composed: true, view: window,
+      clientX: cx, clientY: cy,
+      deltaX: dx, deltaY: dy, deltaMode: 0,
+    });
+    target.dispatchEvent(ev);
+    if (!ev.defaultPrevented) {
+      // Apply scroll ourselves; mirrors what the browser would do.
+      if (target === document.scrollingElement || target === document.documentElement || target === document.body) {
+        window.scrollBy({ left: dx, top: dy, behavior: "instant" });
+      } else {
+        target.scrollTop += dy;
+        target.scrollLeft += dx;
+      }
+    }
+    movedY += dy; movedX += dx;
+    await sleepPage(rand(12, 28));
+  }
+  return {
+    deltaX: movedX, deltaY: movedY, steps: n,
+    scrollTop: target.scrollTop, scrollLeft: target.scrollLeft,
+    pageMutated: pageHash() !== before,
+    isTrusted: false,
+  };
+}
+
+function uploadFiles(selector, uid, files) {
+  installPiChromeInstrumentation();
+  const element = elementBySelectorOrUid(selector, uid);
+  if (!element || element.tagName !== "INPUT" || element.type !== "file") {
+    throw new Error("Target must be <input type=file>");
+  }
+  const dt = new DataTransfer();
+  for (const f of files) {
+    const bytes = Uint8Array.from(atob(f.base64 || ""), (c) => c.charCodeAt(0));
+    dt.items.add(new File([bytes], f.name, { type: f.type || "application/octet-stream" }));
+  }
+  element.files = dt.files;
+  element.dispatchEvent(new Event("input", { bubbles: true }));
+  element.dispatchEvent(new Event("change", { bubbles: true }));
+  return { uploaded: files.map((f) => ({ name: f.name, type: f.type, size: (f.base64 || "").length })) };
 }
 
 function dispatchInputEvents(element, data, inputType = "insertText") {
@@ -513,28 +1076,102 @@ function setNativeValue(element, value) {
   else element.value = value;
 }
 
-function typeIntoPage(selector, uid, text, pressEnter) {
-  installPiChromeInstrumentation();
-  let element = elementBySelectorOrUid(selector, uid) || document.activeElement;
-  if (!element) throw new Error(selector || uid ? `No element for ${selector || uid}` : "No active element");
-  element.focus();
+function printableKeyCode(ch) {
+  if (ch === " ") return 32;
+  const upper = ch.toUpperCase();
+  if (/^[A-Z]$/.test(upper)) return upper.charCodeAt(0);
+  if (/^[0-9]$/.test(ch)) return ch.charCodeAt(0);
+  return ch.charCodeAt(0) || 0;
+}
+
+function dispatchKeyEvent(element, type, key, mods = {}) {
+  const code = key.length === 1 && /^[a-z]$/i.test(key) ? `Key${key.toUpperCase()}` :
+    key.length === 1 && /^[0-9]$/.test(key) ? `Digit${key}` :
+    key === " " ? "Space" : key;
+  const SPECIAL = { Enter: 13, Tab: 9, Backspace: 8, Delete: 46, Escape: 27,
+    ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40, " ": 32, Shift: 16, Control: 17, Alt: 18, Meta: 91 };
+  const keyCode = key.length === 1 ? printableKeyCode(key) : (SPECIAL[key] ?? 0);
+  const ev = new KeyboardEvent(type, {
+    key,
+    code,
+    keyCode,
+    which: keyCode,
+    charCode: type === "keypress" && key.length === 1 ? key.charCodeAt(0) : 0,
+    shiftKey: !!mods.shiftKey,
+    ctrlKey: !!mods.ctrlKey,
+    altKey: !!mods.altKey,
+    metaKey: !!mods.metaKey,
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    view: window,
+  });
+  element.dispatchEvent(ev);
+  return ev;
+}
+
+async function typeCharacter(element, ch) {
+  const needShift = ch.length === 1 && (/^[A-Z]$/.test(ch) || "~!@#$%^&*()_+{}|:\"<>?".includes(ch));
+  if (needShift) {
+    dispatchKeyEvent(element, "keydown", "Shift", { shiftKey: true });
+    await sleepPage(rand(8, 24));
+  }
+  const mods = { shiftKey: needShift };
+  const down = dispatchKeyEvent(element, "keydown", ch, mods);
+  if (down.defaultPrevented) {
+    if (needShift) dispatchKeyEvent(element, "keyup", "Shift", { shiftKey: false });
+    return { defaultPrevented: true };
+  }
+  if (ch.length === 1) dispatchKeyEvent(element, "keypress", ch, mods);
+
   if (element.isContentEditable) {
-    document.execCommand("insertText", false, text);
+    // execCommand("insertText") fires its own beforeinput + input. Don't double-dispatch.
+    document.execCommand("insertText", false, ch);
   } else if ("value" in element) {
     const start = element.selectionStart ?? element.value.length;
     const end = element.selectionEnd ?? element.value.length;
-    setNativeValue(element, element.value.slice(0, start) + text + element.value.slice(end));
-    element.selectionStart = element.selectionEnd = start + text.length;
-    dispatchInputEvents(element, text, "insertText");
+    const next = element.value.slice(0, start) + ch + element.value.slice(end);
+    const before = new InputEvent("beforeinput", { bubbles: true, cancelable: true, inputType: "insertText", data: ch });
+    element.dispatchEvent(before);
+    if (!before.defaultPrevented) {
+      setNativeValue(element, next);
+      try { element.selectionStart = element.selectionEnd = start + ch.length; } catch {}
+      element.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: ch }));
+    }
   } else {
     throw new Error("Focused element is not text-editable");
   }
+
+  await sleepPage(rand(25, 95));
+  dispatchKeyEvent(element, "keyup", ch, mods);
+  if (needShift) {
+    await sleepPage(rand(5, 18));
+    dispatchKeyEvent(element, "keyup", "Shift", { shiftKey: false });
+  }
+  await sleepPage(rand(35, 140));
+  return { defaultPrevented: false };
+}
+
+async function typeIntoPage(selector, uid, text, pressEnter) {
+  installPiChromeInstrumentation();
+  const before = pageHash();
+  let element = elementBySelectorOrUid(selector, uid) || document.activeElement;
+  if (!element) throw new Error(selector || uid ? `No element for ${selector || uid}` : "No active element");
+  element.focus();
+  if (!(element.isContentEditable || "value" in element)) throw new Error("Focused element is not text-editable");
+  for (const ch of Array.from(text)) await typeCharacter(element, ch);
   if (pressEnter) pressKeyInPage("Enter");
-  return { selector, uid, length: text.length, pressEnter };
+  return {
+    selector, uid, length: text.length, pressEnter,
+    isTrusted: false,
+    valueMatches: "value" in element ? element.value.includes(text) : undefined,
+    pageMutated: pageHash() !== before,
+  };
 }
 
 function fillPage(selector, uid, text, submit) {
   installPiChromeInstrumentation();
+  const before = pageHash();
   let element = elementBySelectorOrUid(selector, uid) || document.activeElement;
   if (!element) throw new Error(selector || uid ? `No element for ${selector || uid}` : "No active element");
   element.focus();
@@ -550,19 +1187,66 @@ function fillPage(selector, uid, text, submit) {
     throw new Error("Focused element is not text-editable");
   }
   if (submit) pressKeyInPage("Enter");
-  return { selector, uid, length: String(text).length, submit };
+  return {
+    selector, uid, length: String(text).length, submit,
+    isTrusted: false,
+    valueMatches: "value" in element ? element.value === String(text) : undefined,
+    pageMutated: pageHash() !== before,
+  };
 }
 
-function pressKeyInPage(key) {
+async function pressKeyInPage(key) {
   const normalized = normalizeKey(key);
   const target = document.activeElement || document.body;
-  target.dispatchEvent(new KeyboardEvent("keydown", { key: normalized, bubbles: true, cancelable: true }));
-  target.dispatchEvent(new KeyboardEvent("keyup", { key: normalized, bubbles: true, cancelable: true }));
+  const before = pageHash();
+  const down = dispatchKeyEvent(target, "keydown", normalized);
+  if (normalized.length === 1) dispatchKeyEvent(target, "keypress", normalized);
+  // Character insertion for printable keys when focus is in an editable.
+  if (normalized.length === 1 && !down.defaultPrevented && (target.isContentEditable || ("value" in target && (target.tagName === "INPUT" || target.tagName === "TEXTAREA")))) {
+    if (target.isContentEditable) {
+      const bi = new InputEvent("beforeinput", { bubbles: true, cancelable: true, inputType: "insertText", data: normalized });
+      target.dispatchEvent(bi);
+      if (!bi.defaultPrevented) {
+        document.execCommand("insertText", false, normalized);
+        target.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: normalized }));
+      }
+    } else {
+      const start = target.selectionStart ?? target.value.length;
+      const end = target.selectionEnd ?? target.value.length;
+      const bi = new InputEvent("beforeinput", { bubbles: true, cancelable: true, inputType: "insertText", data: normalized });
+      target.dispatchEvent(bi);
+      if (!bi.defaultPrevented) {
+        setNativeValue(target, target.value.slice(0, start) + normalized + target.value.slice(end));
+        try { target.selectionStart = target.selectionEnd = start + 1; } catch {}
+        target.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: normalized }));
+      }
+    }
+  } else if (normalized === "Backspace" && "value" in target) {
+    const start = target.selectionStart ?? target.value.length;
+    const end = target.selectionEnd ?? target.value.length;
+    if (start > 0 || end > start) {
+      const from = start === end ? start - 1 : start;
+      const bi = new InputEvent("beforeinput", { bubbles: true, cancelable: true, inputType: "deleteContentBackward" });
+      target.dispatchEvent(bi);
+      if (!bi.defaultPrevented) {
+        setNativeValue(target, target.value.slice(0, from) + target.value.slice(end));
+        try { target.selectionStart = target.selectionEnd = from; } catch {}
+        target.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "deleteContentBackward" }));
+      }
+    }
+  }
+  await sleepPage(rand(25, 95));
+  const up = dispatchKeyEvent(target, "keyup", normalized);
   if (normalized === "Enter") {
     const form = target.closest?.("form");
     if (form) form.requestSubmit?.();
   }
-  return { key: normalized };
+  return {
+    key: normalized,
+    isTrusted: false,
+    defaultPrevented: down.defaultPrevented || up.defaultPrevented,
+    pageMutated: pageHash() !== before,
+  };
 }
 
 function listConsoleMessages(clear) {
@@ -581,7 +1265,7 @@ function listNetworkRequests(includePreservedRequests, clear) {
     .filter((request) => includePreservedRequests || request.pageUrl === currentUrl)
     .map(({ responseBody, ...summary }) => ({ ...summary, hasResponseBody: responseBody !== undefined }));
   if (clear) state.network = [];
-  return { requests, count: requests.length, note: "Captures fetch/XHR after instrumentation is installed (snapshot/evaluate/network/console tools install it). Browser-initiated document/static asset requests are not captured." };
+  return { requests, count: requests.length, note: "Captures fetch/XHR after instrumentation is installed. Browser-initiated document/static asset requests are not captured." };
 }
 
 function getNetworkRequest(requestId) {
@@ -596,7 +1280,9 @@ async function waitForPage(kind, value, timeoutMs, intervalMs) {
   while (Date.now() - started < timeoutMs) {
     let ok = false;
     if (kind === "selector") ok = Boolean(document.querySelector(value));
-    else ok = Boolean((0, eval)(value));
+    else {
+      try { ok = Boolean(new Function("return (" + value + ");").call(globalThis)); } catch { ok = false; }
+    }
     if (ok) return { elapsedMs: Date.now() - started };
     await new Promise((resolve) => setTimeout(resolve, intervalMs));
   }