pi-chrome 0.15.47 → 0.15.49

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable user-facing changes to `pi-chrome`.
 
+## 0.15.49 — 2026-09-10
+
+- **Validation scope.** Node regression suites passed. Live browser validation remains incomplete: an input attempt encountered `Input.dispatchMouseEvent: Detached while handling command.`; a subsequent retest was blocked by a disconnected companion. No live-browser pass is claimed for these changes.
+
+- **Upload node fallback.** When Chrome cannot convert a file input's remote object to a DOM node ID, use that same `objectId` directly. Release the remote object after success or failure and reject stale snapshot UIDs. No native file picker or new permissions.
+- **Native rich-editor insertion.** `chrome_type` and `chrome_fill` use one CDP `Input.insertText` for focused contenteditables. Inputs/textareas keep individual key events; `perCharacter:true` preserves that path for rich editors needing `keydown` events. Results report `typing` as `insertText`, `keys`, or `none`. Existing DOM-fallback controls and background policy remain intact.
+- **Complete rich-editor fill and single Enter.** Select all requested contenteditable contents before deletion, not only one paragraph. `pressEnter` sends one Enter instead of two; Enter after type/fill stays pinned to the resolved tab.
+- **Shift-only typing.** Shift+a, Shift+1, and other US-layout printable chords now carry shifted text. Ctrl/Meta/Alt shortcuts still suppress literal insertion.
+- **Input regressions.** Added worker fault-injection tests and challenge 44. Challenge 16 explicitly tests per-character typing; challenge 21 waits for Shift release before grading.
+
+## 0.15.48 — 2026-09-09
+
+- **Existing background mode is now hard background.** `/chrome background on` (still the default) overrides per-call foreground requests, keeps new tabs inactive, and blocks `chrome_tab activate`. Use the existing `/chrome background off` for foreground/watch mode; no new command or lock state.
+- **Screenshots without tab activation.** PNG/JPEG and full-page tiles use CDP instead of `captureVisibleTab`. Debugger/capture failures never fall back to switching tabs. Old companions reject background creation/capture with a reload instruction. Screenshot tools now require debugger access.
+- **Trusted input preserved.** Background policy does not replace Chrome input with synthetic events. It blocks explicit focus/activation, not page/native/Chrome/OS side effects; inactive-page rendering and focus-gated workflows can still vary by environment.
+- **Regression coverage.** Added policy/worker/screenshot unit tests and challenge 43 for inactive-tab visibility plus trusted input. Full-page capture restores both scroll axes best-effort after success or failure.
+- **Live validation and unresolved limitation.** Chrome 152/macOS checks passed for inactive tab creation, blocked activation, background PNG/JPEG/full-page capture, and scroll restoration. The trusted-click check encountered debugger detachment, then a visibility failure on retry; the cause remains unresolved and human interference was not ruled out. This release does not promise zero focus changes during trusted input. Chrome-behind-another-app and macOS Spaces behavior remain unverified.
+
 ## 0.15.47 — 2026-09-09
 
 - **Bounded session cleanup.** On exit, Pi waits up to two seconds for cleanup before stopping the bridge. Reload preserves browser resources; revoke remains non-blocking.

package/README.md

@@ -74,6 +74,12 @@ Second doctor run should show all checks passing.
 
 Tool parameters and gotchas are documented inline in Pi.
 
+### Typing into rich editors
+
+`chrome_type` and `chrome_fill` use one native CDP `Input.insertText` operation for focused contenteditables. This avoids per-character delays for long text and preserves Unicode/newlines. Ordinary inputs and textareas retain individual key events.
+
+For an editor that needs a `keydown` for every character, pass `perCharacter:true`. Bulk insertion still uses Chrome's input system, but does not emit per-character key events or a clipboard `paste` event. Use `includeSnapshot:true` to verify the result; `chrome_fill` still honors `domFallback:false` when synthetic fallback is unwanted.
+
 ---
 
 ## Safety model
@@ -108,13 +114,21 @@ Security details: [`SECURITY.md`](./SECURITY.md). Architecture details: [`docs/A
 /chrome status              # connection + auth + background state
 /chrome authorize [duration]
 /chrome revoke
-/chrome background on       # default: don't steal focus
+/chrome background on       # default: hard background policy
 /chrome background off      # foreground/watch mode
 /chrome background status
 ```
 
 If loaded extension is older than installed `pi-chrome`, `/chrome doctor` tells you to reload it from `chrome://extensions`.
 
+### Background policy
+
+`/chrome background on` is enforced, not an overridable default. Per-call `background:false` cannot bring Chrome forward, new tabs stay inactive, and `chrome_tab activate` is blocked. Use the existing `/chrome background off` for foreground/watch mode; per-call `background:true` still works when that mode is off.
+
+Screenshots use CDP without activating background tabs. Debugger/capture failures return errors, never an activation fallback. Reload both Pi and the Chrome companion after upgrading; old companions reject background tab creation/screenshots rather than silently switching tabs.
+
+This prevents explicit pi-chrome focus/activation, not every Chrome/OS side effect. Trusted input, page popups, native prompts, debugger banners, and macOS Spaces can still affect focus. Inactive pages may throttle rendering or reject focus-gated actions. See [scope and risks](./docs/ARCHITECTURE.md#scope-and-risks).
+
 ---
 
 ## Limits

package/SECURITY.md

@@ -27,7 +27,7 @@ The Chrome extension under `extensions/chrome-profile-bridge/browser-extension/`
 - Loopback bridge only. No remote port. No telemetry.
 - Chrome real input layer for interactive controls.
 - Chrome control locked by default; `/chrome authorize` unlocks current Pi session after terminal confirmation, `/chrome revoke` locks it again.
-- Run-in-background optional; tab/window focus is observable by default (the user can see Pi acting).
+- Hard background mode is on by default: tools cannot override it to explicitly focus windows or activate tabs. `/chrome background off` allows foreground/watch mode. This is not a security sandbox: trusted input, page scripts, native prompts, and Chrome/OS behavior can still affect focus.
 
 ## Custom ports
 

package/docs/ARCHITECTURE.md

@@ -46,14 +46,26 @@ To point pi-chrome at an existing tab, pass `targetId`, `urlIncludes`, or `title
 
 ## Background mode
 
-By default, chrome calls run in background so Chrome does not steal focus.
+The existing background setting is a hard session policy, enabled by default. No separate lock/unlock command is needed.
 
 ```text
-/chrome background on       # background mode
-/chrome background off      # foreground/watch mode
+/chrome background on       # enforce no explicit window focus/tab activation
+/chrome background off      # allow foreground/watch mode
 ```
 
-Per-call `background: false` brings Chrome forward for that action. Per-call `background: true` forces background.
+- With background on, per-call `background:false` and legacy `foreground:true` cannot override the policy. `chrome_tab activate` errors with instructions to ask the user to turn background off.
+- With background off, calls may focus Chrome; per-call `background:true` still avoids explicit focus/tab activation.
+- Policy is applied in `authorizedBridgeSend` for every tool, including `chrome_launch(url)`, tab creation, and tools without a background parameter. Each session sends its own effective `background`/`foreground` flags through the shared bridge.
+- All worker window-focus/tab-activation writes go through a guarded helper. Background tab creation uses `active:false`; implicit automation windows remain `focused:false`.
+- Screenshots use CDP `Page.captureScreenshot` with `fromSurface:true` and `captureBeyondViewport:false`. They target a tab, not whichever tab happens to be visible. There is no `captureVisibleTab`/activation fallback on debugger or capture failure. PNG/JPEG output is unchanged; full-page capture retains tiles plus a JSON manifest and restores scroll position best-effort, including on failure.
+- Background tab creation and screenshots use internal `tab.new.background` / `page.screenshot.background` wire actions. Old companions reject them before changing tabs; Pi reports a reload instruction instead of retrying an unsafe legacy action. No capability-probe race or extra round trip is needed.
+- Real CDP input and existing explicit DOM-fallback controls are unchanged. Background mode never silently substitutes synthetic input to avoid focus.
+
+### Scope and risks
+
+This is a policy against **explicit pi-chrome focus/activation**, not an OS focus sandbox. Page scripts (`window.open`, `window.focus`), trusted input, native dialogs, debugger banners, Chrome window/Spaces behavior, and closing an active tab can still change focus or selection. Other sessions and human actions remain independent. Requests already dispatched before a mode change keep their earlier policy.
+
+Inactive/minimized tabs can throttle timers or rendering, and clipboard/fullscreen/other focus-gated workflows may fail. Screenshots now require debugger attachment, which can conflict with DevTools or other extensions; hidden-tab rendering can differ or be unavailable. No automatic foreground retry is allowed. Full-page capture temporarily scrolls the target page. Reload both Pi and the Chrome companion after upgrading, and live-test tab selection, OS focus, and screenshot fidelity on supported Chrome/OS versions.
 
 ## Authorization
 

package/docs/COMPARISON.md

@@ -134,7 +134,7 @@ If your threat model excludes extensions with broad permissions, neither approac
 
 ## Public benchmarks worth knowing (for axis 2 / axis 3 comparison)
 
-Pi-chrome itself ships a benchmark suite ([`../test-suite/`](../test-suite)) of **42 primitive challenges** plus **4 hermetic BrowserGym-style long-horizon tasks** covering trusted input, pointer humanization, keyboard fidelity, drag/drop, Shadow DOM, iframes, file uploads, strict-CSP screenshot fallback and CDP eval/snapshot bypass, dynamic waits, tab lifecycle, network observability, fingerprint leaks, and agent-safety honeypots. Scoring tracks expected outcomes per challenge instead of raw PASS count, with `core`, `conditional`, and `quality` gate buckets. That's **driver-level** grading.
+Pi-chrome itself ships a benchmark suite ([`../test-suite/`](../test-suite)) of **43 primitive challenges** plus **4 hermetic BrowserGym-style long-horizon tasks** covering trusted input, pointer humanization, keyboard fidelity, drag/drop, Shadow DOM, iframes, file uploads, strict-CSP screenshot fallback and CDP eval/snapshot bypass, dynamic waits, tab lifecycle, network observability, fingerprint leaks, and agent-safety honeypots. Scoring tracks expected outcomes per challenge instead of raw PASS count, with `core`, `conditional`, and `quality` gate buckets. That's **driver-level** grading.
 
 For **agent-level** comparison (axis 2), the public benchmarks worth citing:
 

package/extensions/chrome-profile-bridge/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Pi Chrome Connector",
-  "version": "0.15.47",
+  "version": "0.15.49",
   "description": "Lets Pi control tabs in Chrome via a local connector at 127.0.0.1.",
   "permissions": [
     "tabs",

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

@@ -681,7 +681,13 @@ function cdpKeyInfo(key, shifted) {
   };
   if (SPECIAL[key]) return { key, ...SPECIAL[key] };
   if (key.length === 1) {
-    const ch = key;
+    // Explicit Shift chords need shifted text as well as a modifier bit. CDP does
+    // not derive printable text from code/windowsVirtualKeyCode for us.
+    const SHIFTED = {
+      "`": "~", "1": "!", "2": "@", "3": "#", "4": "$", "5": "%", "6": "^", "7": "&", "8": "*", "9": "(", "0": ")",
+      "-": "_", "=": "+", "[": "{", "]": "}", "\\": "|", ";": ":", "'": "\"", ",": "<", ".": ">", "/": "?",
+    };
+    const ch = shifted ? (/^[a-z]$/.test(key) ? key.toUpperCase() : SHIFTED[key] || key) : key;
     const layout = usKeyLayoutForChar(ch);
     return { key: ch, code: layout.code, windowsVirtualKeyCode: layout.keyCode, text: ch };
   }
@@ -745,7 +751,7 @@ async function domClickFallback(tabId, params, cause) {
 
 async function chromeInputClick(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   try {
     await attachDebugger(tab.id);
     const resolved = await resolveTargetInTab(tab.id, params);
@@ -782,7 +788,7 @@ async function chromeInputClick(params) {
 
 async function chromeInputHover(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   await attachDebugger(tab.id);
   const resolved = await resolveTargetInTab(tab.id, params);
   const point = resolved.rect ? pickInsideRect(resolved.rect) : { x: resolved.x, y: resolved.y };
@@ -793,7 +799,7 @@ async function chromeInputHover(params) {
 
 async function chromeInputKey(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   await attachDebugger(tab.id);
   const key = String(params.key || "");
   if (!key) throw new Error("chrome.key: missing key");
@@ -809,13 +815,14 @@ async function chromeInputKey(params) {
     await cdp(tab.id, "Input.dispatchKeyEvent", { type: "keyDown", key: m.key, code: m.code, windowsVirtualKeyCode: m.vk, modifiers: modBits });
     await sleep(rng(6, 18));
   }
-  const info = cdpKeyInfo(key);
-  // When modifiers are active, browsers usually emit "rawKeyDown" (no text) so chords like Cmd+V don't insert the literal char.
-  const downType = modBits ? "rawKeyDown" : "keyDown";
+  const info = cdpKeyInfo(key, mods.shiftKey);
+  // Ctrl/Meta/Alt chords must not insert literal text (e.g. Cmd+V). Shift alone
+  // still types: Shift+a -> A, Shift+1 -> !, and Shift+Enter carries a newline.
+  const shortcut = !!(mods.ctrlKey || mods.metaKey || mods.altKey);
   await cdp(tab.id, "Input.dispatchKeyEvent", {
-    type: downType, key: info.key, code: info.code,
+    type: shortcut ? "rawKeyDown" : "keyDown", key: info.key, code: info.code,
     windowsVirtualKeyCode: info.windowsVirtualKeyCode, nativeVirtualKeyCode: info.windowsVirtualKeyCode,
-    text: modBits ? "" : info.text, unmodifiedText: modBits ? "" : info.text, modifiers: modBits,
+    text: shortcut ? "" : info.text, unmodifiedText: shortcut ? "" : info.text, modifiers: modBits,
   });
   await sleep(rng(25, 90));
   await cdp(tab.id, "Input.dispatchKeyEvent", {
@@ -829,9 +836,52 @@ async function chromeInputKey(params) {
   return { input: "chrome", key: info.key, modifiers: mods };
 }
 
+// Read the actual focused editor, not a role=textbox lookalike. For fill, select
+// the requested editor's entire contents: triple-click only selects a paragraph.
+// Selection uses the DOM; deletion and insertion still use Chrome's input layer.
+async function contentEditableInTab(tabId, selectAllParams = null) {
+  const results = await executeScriptTimed({
+    target: { tabId, frameIds: [0] },
+    world: "MAIN",
+    func: (selector, uid, selectAll) => {
+      const active = document.activeElement;
+      if (selectAll) {
+        const state = window.__PI_CHROME_STATE__;
+        const el = uid ? state?.elements?.[uid] : document.querySelector(selector);
+        if (uid && (!el || !el.isConnected)) throw new Error(`snapshot uid ${uid} is stale; refresh chrome_snapshot`);
+        if (!el?.isContentEditable) return false;
+        if (!active?.isContentEditable || !(el === active || el.contains(active) || active.contains(el))) {
+          throw new Error("chrome.fill: requested contenteditable is not focused");
+        }
+        const selection = window.getSelection();
+        if (!selection) throw new Error("Could not select contenteditable contents");
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        selection.removeAllRanges();
+        selection.addRange(range);
+      }
+      return active?.isContentEditable === true;
+    },
+    args: [selectAllParams?.selector ?? null, selectAllParams?.uid ?? null, selectAllParams !== null],
+  }, `inspect contenteditable in tab ${tabId}`);
+  return results?.[0]?.result === true;
+}
+
+async function typeTextInTab(tabId, text, perCharacter) {
+  if (!text) return "none";
+  if (!perCharacter && await contentEditableInTab(tabId)) {
+    // One native edit avoids per-character delays and rich-editor render races.
+    // Do not retry as keystrokes if insertion fails: it may already have applied.
+    await cdp(tabId, "Input.insertText", { text });
+    return "insertText";
+  }
+  for (const ch of Array.from(text)) await cdpTypeChar(tabId, ch);
+  return "keys";
+}
+
 async function chromeInputType(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   await attachDebugger(tab.id);
   if (params.selector || params.uid) {
     // Focus target by clicking it first.
@@ -844,12 +894,9 @@ async function chromeInputType(params) {
     await sleep(rng(50, 120));
   }
   const text = String(params.text || "");
-  for (const ch of Array.from(text)) await cdpTypeChar(tab.id, ch);
-  if (params.pressEnter) {
-    await cdpTypeChar(tab.id, "\r").catch(() => undefined);
-    await chromeInputKey({ ...params, key: "Enter" });
-  }
-  return { input: "chrome", length: text.length };
+  const typing = await typeTextInTab(tab.id, text, params.perCharacter);
+  if (params.pressEnter) await chromeInputKey({ ...params, targetId: tab.id, key: "Enter" });
+  return { input: "chrome", length: text.length, typing };
 }
 
 async function domFillFallback(tabId, params, cause) {
@@ -894,7 +941,7 @@ async function domFillFallback(tabId, params, cause) {
 
 async function chromeInputFill(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   try {
     await attachDebugger(tab.id);
     if (!(params.selector || params.uid)) throw new Error("chrome.fill: selector or uid required");
@@ -908,14 +955,15 @@ async function chromeInputFill(params) {
       await cdp(tab.id, "Input.dispatchMouseEvent", { type: "mouseReleased", x: point.x, y: point.y, button: "left", buttons: 0, clickCount: i, pointerType: "mouse" });
       await sleep(rng(20, 60));
     }
+    await contentEditableInTab(tab.id, params);
     // Delete selection.
     await cdp(tab.id, "Input.dispatchKeyEvent", { type: "keyDown", key: "Delete", code: "Delete", windowsVirtualKeyCode: 46 });
     await cdp(tab.id, "Input.dispatchKeyEvent", { type: "keyUp", key: "Delete", code: "Delete", windowsVirtualKeyCode: 46 });
     await sleep(rng(20, 60));
     const text = String(params.text || "");
-    for (const ch of Array.from(text)) await cdpTypeChar(tab.id, ch);
-    if (params.submit) await chromeInputKey({ ...params, key: "Enter" });
-    return { input: "chrome", length: text.length };
+    const typing = await typeTextInTab(tab.id, text, params.perCharacter);
+    if (params.submit) await chromeInputKey({ ...params, targetId: tab.id, key: "Enter" });
+    return { input: "chrome", length: text.length, typing };
   } catch (error) {
     if (params.domFallback === false) throw error;
     return domFillFallback(tab.id, params, error);
@@ -924,7 +972,7 @@ async function chromeInputFill(params) {
 
 async function chromeInputScroll(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   await attachDebugger(tab.id);
   const resolved = (params.selector || params.uid) ? await resolveTargetInTab(tab.id, params) : { x: 100, y: 100, rect: null };
   const x = resolved.rect ? resolved.rect.left + Math.min(resolved.rect.width, 800) / 2 : resolved.x;
@@ -974,7 +1022,7 @@ async function chromeInputScroll(params) {
 
 async function chromeInputTap(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   await attachDebugger(tab.id);
   const resolved = (params.selector || params.uid || (typeof params.x === "number" && typeof params.y === "number"))
     ? await resolveTargetInTab(tab.id, params)
@@ -990,7 +1038,7 @@ async function chromeInputTap(params) {
 
 async function chromeInputDrag(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   await attachDebugger(tab.id);
   const from = await resolveTargetInTab(tab.id, { selector: params.fromSelector ?? null, uid: params.fromUid ?? null, x: params.fromX ?? null, y: params.fromY ?? null });
   const to = await resolveTargetInTab(tab.id, { selector: params.toSelector ?? null, uid: params.toUid ?? null, x: params.toX ?? null, y: params.toY ?? null });
@@ -1015,7 +1063,7 @@ async function chromeInputDrag(params) {
 
 async function chromeInputUpload(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   await attachDebugger(tab.id);
   if (!(params.selector || params.uid)) throw new Error("chrome.upload: selector or uid required");
   const paths = Array.isArray(params.paths) ? params.paths.map(String) : [];
@@ -1024,25 +1072,31 @@ async function chromeInputUpload(params) {
     const selector = ${JSON.stringify(params.selector ?? null)};
     const uid = ${JSON.stringify(params.uid ?? null)};
     const state = window.__PI_CHROME_STATE__;
-    const el = uid && state && state.elements ? state.elements[uid] : (selector ? document.querySelector(selector) : null);
+    const el = uid ? state?.elements?.[uid] : (selector ? document.querySelector(selector) : null);
+    if (uid && (!el || !el.isConnected)) throw new Error("snapshot uid " + uid + " is stale; refresh chrome_snapshot");
     if (!el || el.tagName !== "INPUT" || el.type !== "file") throw new Error("Target must be <input type=file>");
     el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
     return el;
   })()`;
   const evaluated = await cdp(tab.id, "Runtime.evaluate", { expression, objectGroup: "pi-chrome-upload", includeCommandLineAPI: false, returnByValue: false });
-  if (evaluated.exceptionDetails) throw new Error(evaluated.exceptionDetails.text || "Could not resolve file input");
+  if (evaluated.exceptionDetails) throw new Error(cdpExceptionText(evaluated.exceptionDetails) || "Could not resolve file input");
   const objectId = evaluated.result?.objectId;
   if (!objectId) throw new Error("Could not resolve file input object");
-  await cdp(tab.id, "DOM.enable", {}).catch(() => undefined);
-  const requested = await cdp(tab.id, "DOM.requestNode", { objectId });
-  if (!requested.nodeId) throw new Error("Could not resolve file input node");
-  await cdp(tab.id, "DOM.setFileInputFiles", { nodeId: requested.nodeId, files: paths });
-  await cdp(tab.id, "Runtime.callFunctionOn", {
-    objectId,
-    functionDeclaration: `function() { this.dispatchEvent(new Event("input", { bubbles: true })); this.dispatchEvent(new Event("change", { bubbles: true })); return this.files ? this.files.length : 0; }`,
-    returnByValue: true,
-  }).catch(() => undefined);
-  await cdp(tab.id, "Runtime.releaseObject", { objectId }).catch(() => undefined);
+  try {
+    await cdp(tab.id, "DOM.enable", {}).catch(() => undefined);
+    // Some DOM agents return nodeId:0 (or reject conversion) for a valid remote
+    // element. CDP accepts that same objectId directly, before any file mutation.
+    const requested = await cdp(tab.id, "DOM.requestNode", { objectId }).catch(() => null);
+    const target = requested?.nodeId ? { nodeId: requested.nodeId } : { objectId };
+    await cdp(tab.id, "DOM.setFileInputFiles", { ...target, files: paths });
+    await cdp(tab.id, "Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function() { this.dispatchEvent(new Event("input", { bubbles: true })); this.dispatchEvent(new Event("change", { bubbles: true })); return this.files ? this.files.length : 0; }`,
+      returnByValue: true,
+    }).catch(() => undefined);
+  } finally {
+    await cdp(tab.id, "Runtime.releaseObject", { objectId }).catch(() => undefined);
+  }
   return { input: "chrome", uploaded: paths.map((path) => ({ path })) };
 }
 // ===============================================================
@@ -1208,22 +1262,29 @@ async function dispatch(action, params) {
         extensionVersion: chrome.runtime.getManifest().version,
         bridgeUrl: BRIDGE_URL,
         userAgent: navigator.userAgent,
+        capabilities: { hardBackground: true },
       };
     case "tab.list": {
       const tabs = await chrome.tabs.query({});
       return Promise.all(tabs.map(formatTab));
     }
+    case "tab.new.background":
+    case "page.screenshot.background":
+      // Older workers reject these action names before touching tabs. Do not replace this with
+      // a capability probe followed by an old action: a reload/profile change can race the probe.
+      return dispatch(action.slice(0, -".background".length), { ...params, background: true, foreground: false });
     case "tab.new": {
       // Every Pi-opened tab must join a tab group. There is intentionally no opt-out: an ungrouped
       // Pi-created tab is easy to lose among user tabs. If grouping fails after creation, close the
       // tab best-effort before surfacing the error so tab.new never leaves an ungrouped Pi tab.
       const groupTitle = params.groupTitle || "Pi";
       const existingGroup = await findGroupRecordByTitle(groupTitle);
-      const createParams = { url: params.url || "about:blank", active: true };
+      const createParams = { url: params.url || "about:blank", active: foregroundRequested(params) };
       if (existingGroup && typeof existingGroup.windowId === "number") createParams.windowId = existingGroup.windowId;
       const tab = await chrome.tabs.create(createParams);
       await trackSessionTab(sessionKeyOf(params), tab.id, true);
       try {
+        await bringToFront(tab, params);
         return await groupTab(tab, groupTitle, params.groupColor);
       } catch (error) {
         if (typeof tab.id === "number") await chrome.tabs.remove(tab.id).catch(() => {});
@@ -1231,12 +1292,14 @@ async function dispatch(action, params) {
       }
     }
     case "tab.activate": {
+      if (!foregroundRequested(params)) {
+        throw new Error("Tab activation is blocked by background mode. Ask the user to run /chrome background off to allow foreground work.");
+      }
       // Management actions never auto-create an automation target (createOwnedTarget:false): with
       // no explicit target they act on an owned target if one exists, else error — they must never
       // fall back to (or spawn a tab just to touch) the user's active tab.
       const tab = await getTabByParams(params, { createOwnedTarget: false });
-      await chrome.windows.update(tab.windowId, { focused: true });
-      return formatTab(await chrome.tabs.update(tab.id, { active: true }));
+      return formatTab(await bringToFront(tab, params));
     }
     case "tab.group": {
       const tab = await getTabByParams(params, { createOwnedTarget: false });
@@ -1292,7 +1355,7 @@ async function dispatch(action, params) {
       // Poll from the service worker via CDP (bypasses CSP). The old approach ran the polling
       // loop in-page with new Function() for expression checks, which fails under strict CSP.
       const tab = await getTabByParams(params);
-      if (params.foreground) await bringToFront(tab);
+      await bringToFront(tab, params);
       const timeoutMs = params.timeoutMs || 10000;
       const intervalMs = params.intervalMs || 250;
       const started = Date.now();
@@ -1316,7 +1379,7 @@ async function dispatch(action, params) {
       return executeInTab(params, probePage, []);
     case "page.navigate": {
       const tab = await getTabByParams(params);
-      if (params.foreground) await bringToFront(tab);
+      await bringToFront(tab, params);
       if (params.initScript) {
         // Register a one-shot document_start content script. We register, navigate, wait, then unregister.
         await registerInitScript(tab.id, params.initScript);
@@ -1477,7 +1540,7 @@ const HELPER_FUNCS = [
 
 async function executeInTab(params, func, args) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
 
   // Phase 1: define the helpers and the action function as page globals via CDP
   // Runtime.evaluate. This bypasses page CSP (no `eval`/`new Function`), which is the
@@ -1544,7 +1607,7 @@ function piEvalStringify(v) {
 // pages that ship `script-src 'self'` without `'unsafe-eval'` (which blocks `eval`/`new Function`).
 async function evaluateInTab(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   const expression = String(params.expression ?? "");
   const stringifySrc = `(${piEvalStringify.toString()})`;
   // Wrap the user expression so the result is run through piEvalStringify in-page before it
@@ -1591,7 +1654,7 @@ async function withOptionalSnapshot(params, actionFn) {
 // It shares window.__PI_CHROME_STATE__ (same el- uid scheme) with the CDP-injected input helpers.
 async function snapshotInTab(params) {
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   const args = [
     params.maxElements || 80,
     params.containingText ?? null,
@@ -1635,7 +1698,7 @@ async function snapshotInTab(params) {
 async function inspectInTab(params) {
   if (!params.uid && !params.selector) throw new Error("chrome_inspect requires uid or selector");
   const tab = await getTabByParams(params);
-  if (params.foreground) await bringToFront(tab);
+  await bringToFront(tab, params);
   const args = [params.uid ?? null, params.selector ?? null, params.scrollIntoView === true];
   await executeScriptTimed({
     target: { tabId: tab.id, frameIds: [0] },
@@ -1705,9 +1768,15 @@ if (chrome.webNavigation && chrome.webNavigation.onCommitted) {
   });
 }
 
-async function bringToFront(tab) {
+function foregroundRequested(params) {
+  // Fail quiet when unspecified, and let background veto even a contradictory foreground flag.
+  return params?.foreground === true && params.background !== true;
+}
+
+async function bringToFront(tab, params) {
+  if (!foregroundRequested(params)) return tab;
   await chrome.windows.update(tab.windowId, { focused: true });
-  await chrome.tabs.update(tab.id, { active: true });
+  return chrome.tabs.update(tab.id, { active: true });
 }
 
 function waitForTabComplete(tabId, timeoutMs) {
@@ -1727,50 +1796,51 @@ 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 });
-  }
+async function captureTabScreenshot(tabId, params) {
+  const format = params.format || "png";
   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 = [];
+    await attachDebugger(tabId);
+    const captureParams = { format, fromSurface: true, captureBeyondViewport: false };
+    if (format === "jpeg" && params.quality !== undefined) captureParams.quality = params.quality;
+    const result = await cdp(tabId, "Page.captureScreenshot", captureParams);
+    if (typeof result?.data !== "string" || !result.data) throw new Error("CDP returned no screenshot data");
+    return `data:image/${format};base64,${result.data}`;
+  } catch (error) {
+    // captureVisibleTab requires activation and can race with the user switching tabs. Never
+    // use it as a fallback, even when debugger attachment or background rendering fails.
+    throw new Error(`Chrome screenshot via CDP failed; no tab-activation fallback was attempted. ${error?.message || error}`);
+  }
+}
+
+async function takeScreenshot(params) {
+  const tab = await bringToFront(await getTabByParams(params), params);
+  if (params.fullPage) {
+    // Preserve the existing tile + manifest contract. Every tile captures the same resolved tab,
+    // without activation; selector/title changes during capture must not retarget later tiles.
+    const targetParams = { ...params, targetId: tab.id, foreground: false };
+    const tiles = await executeInTab(targetParams, captureFullPageTiles, []);
+    const captured = [];
+    try {
       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(targetParams, scrollToY, [tile.scrollY]);
+        await sleep(120); // Let scroll/lazy-load handlers settle.
+        captured.push({ y: tile.y, dataUrl: await captureTabScreenshot(tab.id, params) });
       }
-      await executeInTab({ ...params, foreground: false }, scrollToY, [tiles.originalScrollY]);
-      return {
-        fullPage: true,
-        tab: await 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: await formatTab(tab) };
-  } finally {
-    if (previousActiveId !== undefined && previousActiveId !== tab.id) {
-      await chrome.tabs.update(previousActiveId, { active: true }).catch(() => undefined);
+    } finally {
+      // A failed tile must not strand the page at a new scroll position. Restore both axes
+      // best-effort, without masking the capture error if the tab/debugger is gone.
+      await executeInTab(targetParams, scrollToY, [tiles.originalScrollY, tiles.originalScrollX]).catch(() => undefined);
     }
+    return {
+      fullPage: true,
+      method: "cdp",
+      tab: await formatTab(tab),
+      dimensions: { width: tiles.width, height: tiles.height, viewportHeight: tiles.viewportHeight, dpr: tiles.dpr },
+      tiles: captured,
+    };
   }
+  const dataUrl = await captureTabScreenshot(tab.id, params);
+  return { dataUrl, method: "cdp", tab: await formatTab(tab) };
 }
 
 // ---------------------------------------------------------------------------
@@ -2197,8 +2267,7 @@ function probePage() {
 }
 
 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.
+  // Returns the plan for CDP tile capture in the worker: scroll positions and page metrics.
   const html = document.documentElement;
   const body = document.body;
   const width = Math.max(html.scrollWidth, body ? body.scrollWidth : 0, innerWidth);
@@ -2206,17 +2275,18 @@ function captureFullPageTiles() {
   const viewportHeight = innerHeight;
   const dpr = window.devicePixelRatio || 1;
   const originalScrollY = scrollY;
+  const originalScrollX = scrollX;
   const tiles = [];
   let y = 0;
   while (y < height) {
     tiles.push({ y, scrollY: y });
     y += viewportHeight;
   }
-  return { width, height, viewportHeight, dpr, originalScrollY, tiles };
+  return { width, height, viewportHeight, dpr, originalScrollY, originalScrollX, tiles };
 }
 
-function scrollToY(y) {
-  window.scrollTo({ top: y, left: 0, behavior: "instant" });
+function scrollToY(y, x = 0) {
+  window.scrollTo({ top: y, left: x, behavior: "instant" });
   return { scrollY };
 }