pi-chrome 0.15.32 → 0.15.34

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable user-facing changes to `pi-chrome`.
 
+## 0.15.34 — 2026-06-01
+
+- **Every tab Pi uses now joins the session group.** Previously only `chrome_tab new`/`group` created/used the `Pi Session: <name-or-id>` group; tabs Pi drove via `page.*` actions (navigate, click, type, snapshot, screenshot, etc.) on the existing/active tab stayed ungrouped. Now any ungrouped tab Pi interacts with is pulled into this session's group, so the user can see exactly which tabs Pi is driving. Tabs already in a group (the user's or another session's) are left untouched.
+- **Fixed punctuation being dropped by `chrome_type`/`chrome_key`.** Printable punctuation derived its `code`/virtual-keyCode from `charCodeAt()`, so `.` mapped to keyCode 46 (VK_DELETE), `-` to 45 (VK_INSERT), shifted symbols to wrong codes, and `code` was the raw char (`"."`) instead of the physical key (`"Period"`). Apps with keydown handlers (e.g. Gmail's filter address field) saw a Delete/Insert key and silently rejected the character. Both the CDP and DOM-event input paths now resolve keys through a proper US-keyboard layout map.
+
+## 0.15.33 — 2026-05-31
+
+- **Background is now the default.** `chrome_*` tools run silently without focusing Chrome unless you opt in. Pass `background: false` per call, or run `/chrome background off`, to bring Chrome forward and watch. Tool/param descriptions and docs updated to match.
+
 ## 0.15.32 — 2026-05-31
 
 - **Session tab-group naming tweak.** Per-session groups are now titled `Pi Session: <name-or-id>` (added a colon separator).

package/README.md

@@ -176,15 +176,15 @@ This protects your signed-in Chrome profile from accidental agent use. The loopb
 
 ### Run in background / watch modes
 
-By default, every `chrome_*` call focuses Chrome and activates the target tab so you can **watch the agent work** — invaluable for demos, debugging, and first-time confidence.
+By default, every `chrome_*` call runs in the **background** — Chrome won't pop up or steal focus. Switch to foreground when you want to **watch the agent work** (demos, debugging, first-time confidence).
 
 ```text
 /chrome background          # toggle for the whole session
-/chrome background on       # run in background
+/chrome background on       # run in background (default)
 /chrome background off      # bring Chrome forward so you can watch
 ```
 
-Per-call `background: true` wins over the session setting.
+Per-call `background: false` wins over the session setting (and `background: true` forces background).
 
 ### Diagnostics
 

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

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Pi Chrome Connector",
-  "version": "0.15.32",
+  "version": "0.15.34",
   "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

@@ -315,6 +315,38 @@ function cdpModifiersFor(mods) {
   return m;
 }
 
+// Resolve a single printable character to { code, keyCode, needShift } on a US layout.
+// Self-contained (maps defined inline) so it can be serialized into the page via
+// HELPER_FUNCS for the DOM-event fallback as well as used by the CDP path.
+// Using charCodeAt() for punctuation is wrong: e.g. "." is charCode 46 which collides
+// with VK_DELETE, "-" is 45 (VK_INSERT), so app keydown handlers misfire and drop input.
+function usKeyLayoutForChar(ch) {
+  const PUNCT = {
+    "`": { code: "Backquote", keyCode: 192 }, "~": { code: "Backquote", keyCode: 192, shift: true },
+    "-": { code: "Minus", keyCode: 189 }, "_": { code: "Minus", keyCode: 189, shift: true },
+    "=": { code: "Equal", keyCode: 187 }, "+": { code: "Equal", keyCode: 187, shift: true },
+    "[": { code: "BracketLeft", keyCode: 219 }, "{": { code: "BracketLeft", keyCode: 219, shift: true },
+    "]": { code: "BracketRight", keyCode: 221 }, "}": { code: "BracketRight", keyCode: 221, shift: true },
+    "\\": { code: "Backslash", keyCode: 220 }, "|": { code: "Backslash", keyCode: 220, shift: true },
+    ";": { code: "Semicolon", keyCode: 186 }, ":": { code: "Semicolon", keyCode: 186, shift: true },
+    "'": { code: "Quote", keyCode: 222 }, "\"": { code: "Quote", keyCode: 222, shift: true },
+    ",": { code: "Comma", keyCode: 188 }, "<": { code: "Comma", keyCode: 188, shift: true },
+    ".": { code: "Period", keyCode: 190 }, ">": { code: "Period", keyCode: 190, shift: true },
+    "/": { code: "Slash", keyCode: 191 }, "?": { code: "Slash", keyCode: 191, shift: true },
+    " ": { code: "Space", keyCode: 32 },
+  };
+  // Shifted digit symbols share the digit's physical code + keyCode.
+  const SHIFT_DIGIT = { ")": "0", "!": "1", "@": "2", "#": "3", "$": "4", "%": "5", "^": "6", "&": "7", "*": "8", "(": "9" };
+  if (/^[a-z]$/.test(ch)) return { code: `Key${ch.toUpperCase()}`, keyCode: ch.toUpperCase().charCodeAt(0), needShift: false };
+  if (/^[A-Z]$/.test(ch)) return { code: `Key${ch}`, keyCode: ch.charCodeAt(0), needShift: true };
+  if (/^[0-9]$/.test(ch)) return { code: `Digit${ch}`, keyCode: ch.charCodeAt(0), needShift: false };
+  if (SHIFT_DIGIT[ch]) { const d = SHIFT_DIGIT[ch]; return { code: `Digit${d}`, keyCode: d.charCodeAt(0), needShift: true }; }
+  const p = PUNCT[ch];
+  if (p) return { code: p.code, keyCode: p.keyCode, needShift: !!p.shift };
+  // Unknown char (e.g. unicode): keep text-driven insertion, avoid bogus keyCode collisions.
+  return { code: ch, keyCode: 0, needShift: false };
+}
+
 function cdpKeyInfo(key, shifted) {
   // Map common keys to CDP key event init fields. Returns { code, key, windowsVirtualKeyCode, text }.
   const SPECIAL = {
@@ -336,11 +368,8 @@ function cdpKeyInfo(key, shifted) {
   if (SPECIAL[key]) return { key, ...SPECIAL[key] };
   if (key.length === 1) {
     const ch = key;
-    let code, vk;
-    if (/^[a-zA-Z]$/.test(ch)) { code = `Key${ch.toUpperCase()}`; vk = ch.toUpperCase().charCodeAt(0); }
-    else if (/^[0-9]$/.test(ch)) { code = `Digit${ch}`; vk = ch.charCodeAt(0); }
-    else { code = ch; vk = ch.charCodeAt(0); }
-    return { key: ch, code, windowsVirtualKeyCode: vk, text: ch };
+    const layout = usKeyLayoutForChar(ch);
+    return { key: ch, code: layout.code, windowsVirtualKeyCode: layout.keyCode, text: ch };
   }
   return { key, code: key, windowsVirtualKeyCode: 0, text: "" };
 }
@@ -937,9 +966,27 @@ async function getTabByParams(params) {
   if ((tab.url || "").startsWith("chrome://") || (tab.url || "").startsWith("chrome-extension://")) {
     throw new Error(`Chrome blocks extension automation on protected URL: ${tab.url}`);
   }
+  // Tabs Pi interacts with (page.* actions) join this session's group so the user can see exactly
+  // which tabs Pi is driving. We only adopt *ungrouped* tabs — never hijack a tab the user (or
+  // another Pi session) already grouped, since groupTab would otherwise rename that group.
+  if (params.joinSessionGroup && params.sessionGroupTitle) {
+    await joinSessionGroup(tab, params.sessionGroupTitle);
+  }
   return tab;
 }
 
+// Add an ungrouped tab to the session's tab group (reusing it by title, else creating it).
+// No-op when the tab is already grouped or tabGroups is unavailable.
+async function joinSessionGroup(tab, title) {
+  if (!chrome.tabGroups || typeof tab.id !== "number") return;
+  if (typeof tab.groupId === "number" && tab.groupId >= 0) return;
+  try {
+    await groupTab(tab, title);
+  } catch {
+    // Grouping is best-effort; never block the actual page action on a grouping failure.
+  }
+}
+
 // 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.
@@ -961,6 +1008,7 @@ const HELPER_FUNCS = [
   dispatchPointerLikeEvent,
   humanMoveTo,
   humanClickPoint,
+  usKeyLayoutForChar,
   printableKeyCode,
   dispatchKeyEvent,
   typeCharacter,
@@ -1974,19 +2022,13 @@ function setNativeValue(element, value) {
 }
 
 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;
+  return ch.length === 1 ? usKeyLayoutForChar(ch).keyCode : 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 code = key.length === 1 ? usKeyLayoutForChar(key).code : (key === " " ? "Space" : key);
   const keyCode = key.length === 1 ? printableKeyCode(key) : (SPECIAL[key] ?? 0);
   const ev = new KeyboardEvent(type, {
     key,

package/extensions/chrome-profile-bridge/index.ts

@@ -549,10 +549,12 @@ export default function (pi: ExtensionAPI): void {
 	globalState[PI_CHROME_GLOBAL_KEY] = { version: PI_CHROME_VERSION, root: currentRoot, token: instanceToken };
 
 	const bridge = new ChromeProfileBridge(DEFAULT_HOST, DEFAULT_PORT);
-	let backgroundDefault = false;
+	let backgroundDefault = true;
 	let chromeAuthorizedUntil: number | "indefinite" | undefined;
 	let chromeToolsRegistered = false;
 	let authExpiryTimer: NodeJS.Timeout | undefined;
+	// Remembered so bridge sends can tag tabs with this session's group even when ctx isn't handy.
+	let sessionCtx: ExtensionContext | undefined;
 
 	const clearAuthExpiryTimer = (): void => {
 		if (!authExpiryTimer) return;
@@ -632,10 +634,18 @@ export default function (pi: ExtensionAPI): void {
 
 	const authorizedBridgeSend = (action: string, params: Record<string, unknown>, timeoutMs = DEFAULT_TIMEOUT_MS, signal?: AbortSignal): Promise<unknown> => {
 		requireChromeControlAuthorized();
-		return bridge.send(action, params, timeoutMs, signal);
+		// Any tab Pi *uses* (page.* interactions) should join this session's group, mirroring the
+		// auto-grouping that tab.new already does. Tagging the wire params lets getTabByParams pull
+		// the resolved (e.g. active) tab into the session group on the service-worker side. We skip
+		// tab.* actions: tab.new/group group explicitly, and activate/close/ungroup/list must not.
+		const shouldJoinGroup = action.startsWith("page.") && sessionCtx !== undefined && params.sessionGroupTitle === undefined;
+		const wireParams = shouldJoinGroup
+			? { ...params, sessionGroupTitle: sessionGroupTitle(sessionCtx as ExtensionContext), joinSessionGroup: true }
+			: params;
+		return bridge.send(action, wireParams, timeoutMs, signal);
 	};
 
-	// Translate the public `background` parameter (default false = visible/foreground) into the
+	// Translate the public `background` parameter (default on = silent/background) into the
 	// service worker's wire-level `foreground` flag, accepting legacy `foreground` as a fallback.
 	const withBackground = <T extends Record<string, unknown>>(params: T): T => {
 		const typed = params as { background?: boolean; foreground?: boolean };
@@ -650,6 +660,7 @@ export default function (pi: ExtensionAPI): void {
 	};
 
 	pi.on("session_start", async (_event, ctx) => {
+		sessionCtx = ctx;
 		await bridge.start();
 		updateChromeStatus(ctx);
 	});
@@ -682,7 +693,7 @@ Usage rules:
 3. \`includeSnapshot=true\` on click/type/fill/key to verify in one round trip.
 4. If \`chrome_evaluate\` returns null when you expected a value, the expression evaluated to null/undefined in the page; surface the value via \`JSON.stringify\` to confirm.
 5. \`chrome_navigate\` supports an optional \`initScript\` that runs at document_start in MAIN world for the next navigation (good for seeding localStorage or stubbing Date.now).
-6. By default chrome_* tools focus Chrome so the user can watch; pass \`background=true\` or run /chrome background on for session-wide background execution.
+6. By default chrome_* tools run in the background without focusing Chrome; pass \`background=false\` or run /chrome background off when the user wants to watch Chrome work.
 7. If you hit a native file-picker or privileged browser prompt gate, tell the user; generic clicks/typing/CSP gates are handled by Chrome input.
 8. Run /chrome doctor when in doubt about connectivity or capabilities.
 </chrome-profile-bridge>`;
@@ -953,8 +964,8 @@ Usage rules:
 				];
 			} else if (path[0] === "background" && path.length === 1) {
 				candidates = [
-					{ fullValue: "background on", label: "on", description: "Run in background. Chrome stays in the background. Your editor keeps focus." },
-					{ fullValue: "background off", label: "off", description: "Bring Chrome to the front so you can watch (default)." },
+					{ fullValue: "background on", label: "on", description: "Run in background. Chrome stays in the background. Your editor keeps focus. (default)" },
+					{ fullValue: "background off", label: "off", description: "Bring Chrome to the front so you can watch." },
 					{ fullValue: "background toggle", label: "toggle", description: "Flip whichever way it's currently set." },
 					{ fullValue: "background status", label: "status", description: "Show the current setting." },
 				];
@@ -1073,7 +1084,7 @@ Usage rules:
 		name: "chrome_snapshot",
 		label: "Chrome Snapshot",
 		description:
-			"Inspect a page in the user's existing Chrome profile: title, URL, visible body text, viewport, and clickable/focusable elements with stable uids plus CSS selectors. Brings Chrome to the foreground by default so the user can watch; pass background=true to inspect silently.",
+			"Inspect a page in the user's existing Chrome profile: title, URL, visible body text, viewport, and clickable/focusable elements with stable uids plus CSS selectors. Runs in the background by default; pass background=false to bring Chrome to the foreground so the user can watch.",
 		promptSnippet: "Inspect the current Chrome page and get CSS selectors for browser automation.",
 		parameters: Type.Object({
 			targetId: Type.Optional(Type.String()),
@@ -1084,7 +1095,7 @@ Usage rules:
 			roleFilter: Type.Optional(Type.String({ description: "Only return elements matching this ARIA role or tag name (case-insensitive). e.g. 'button', 'link', 'textbox'." })),
 			nearUid: Type.Optional(Type.String({ description: "Sort elements by proximity to this snapshot uid. Useful for finding controls near a known anchor." })),
 			background: Type.Optional(
-				Type.Boolean({ description: "If true, run silently in the background without focusing Chrome. Default false (Chrome focuses + tab activates so the user can watch)." }),
+				Type.Boolean({ description: "If true (the default), run silently in the background without focusing Chrome; pass false so Chrome focuses + the tab activates and the user can watch." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -1104,7 +1115,7 @@ Usage rules:
 		name: "chrome_navigate",
 		label: "Chrome Navigate",
 		description:
-			"Navigate an existing Chrome tab to a URL via the companion extension. By default focuses Chrome and activates the tab so the user can watch; pass background=true to navigate silently. Optionally waits for load completion.",
+			"Navigate an existing Chrome tab to a URL via the companion extension. Runs in the background by default; pass background=false to focus Chrome and activate the tab so the user can watch. Optionally waits for load completion.",
 		promptSnippet: "Navigate a Chrome tab in the user's existing profile.",
 		parameters: Type.Object({
 			url: Type.String(),
@@ -1115,7 +1126,7 @@ Usage rules:
 			timeoutMs: Type.Optional(Type.Number({ default: 15_000 })),
 			initScript: Type.Optional(Type.String({ description: "Optional JavaScript source to run in MAIN world at document_start of the next navigation. Useful for seeding localStorage, stubbing Date.now(), or defining navigator.webdriver=undefined. Requires the companion extension's webNavigation permission." })),
 			background: Type.Optional(
-				Type.Boolean({ description: "If true, navigate silently without focusing Chrome. Default false." }),
+				Type.Boolean({ description: "If true, navigate silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -1130,7 +1141,7 @@ Usage rules:
 		name: "chrome_evaluate",
 		label: "Chrome Evaluate",
 		description:
-			"Evaluate JavaScript in an existing Chrome tab through the companion extension. Runs in the page context and returns JSON-serializable values when possible. By default focuses Chrome and activates the tab; pass background=true to evaluate silently.",
+			"Evaluate JavaScript in an existing Chrome tab through the companion extension. Runs in the page context and returns JSON-serializable values when possible. Runs in the background by default; pass background=false to focus Chrome and activate the tab.",
 		promptSnippet: "Evaluate JavaScript in the active Chrome tab through the companion extension.",
 		parameters: Type.Object({
 			expression: Type.String(),
@@ -1139,7 +1150,7 @@ Usage rules:
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
 			background: Type.Optional(
-				Type.Boolean({ description: "If true, evaluate silently without focusing Chrome. Default false." }),
+				Type.Boolean({ description: "If true, evaluate silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -1172,7 +1183,7 @@ Usage rules:
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
 			background: Type.Optional(
-				Type.Boolean({ description: "If true, click silently without focusing Chrome. Default false." }),
+				Type.Boolean({ description: "If true, click silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -1204,7 +1215,7 @@ Usage rules:
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
 			background: Type.Optional(
-				Type.Boolean({ description: "If true, type silently without focusing Chrome. Default false." }),
+				Type.Boolean({ description: "If true, type silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -1236,7 +1247,7 @@ Usage rules:
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
 			background: Type.Optional(
-				Type.Boolean({ description: "If true, fill silently without focusing Chrome. Default false." }),
+				Type.Boolean({ description: "If true, fill silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -1255,7 +1266,7 @@ Usage rules:
 		name: "chrome_key",
 		label: "Chrome Key",
 		description:
-			"Send a keyboard key to an existing Chrome tab (Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right, or one character). By default focuses Chrome and activates the tab so the user can watch; pass background=true to send the key silently. Pass includeSnapshot=true to verify after the keypress.",
+			"Send a keyboard key to an existing Chrome tab (Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right, or one character). Runs in the background by default; pass background=false to focus Chrome and activate the tab so the user can watch. Pass includeSnapshot=true to verify after the keypress.",
 		promptSnippet: "Press keys in Chrome through the companion extension.",
 		parameters: Type.Object({
 			key: Type.String(),
@@ -1271,7 +1282,7 @@ Usage rules:
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
 			background: Type.Optional(
-				Type.Boolean({ description: "If true, send the key silently without focusing Chrome. Default false." }),
+				Type.Boolean({ description: "If true, send the key silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -1318,7 +1329,7 @@ Usage rules:
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
-			background: Type.Optional(Type.Boolean({ description: "If true, run silently without focusing Chrome. Default false." })),
+			background: Type.Optional(Type.Boolean({ description: "If true, run silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." })),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
 		}),
@@ -1340,7 +1351,7 @@ Usage rules:
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
-			background: Type.Optional(Type.Boolean({ description: "If true, run silently without focusing Chrome. Default false." })),
+			background: Type.Optional(Type.Boolean({ description: "If true, run silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." })),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
 		}),
@@ -1360,7 +1371,7 @@ Usage rules:
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
-			background: Type.Optional(Type.Boolean({ description: "If true, run silently without focusing Chrome. Default false." })),
+			background: Type.Optional(Type.Boolean({ description: "If true, run silently without focusing Chrome. Defaults to on (the session background setting); pass false to focus Chrome so the user can watch." })),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
 		}),
@@ -1374,7 +1385,7 @@ Usage rules:
 		name: "chrome_screenshot",
 		label: "Chrome Screenshot",
 		description:
-			"Capture a screenshot of an existing Chrome tab via the companion extension and save it to disk. Chrome's extension screenshot API requires the target tab to be the active tab in its window. By default Chrome is focused and the tab activates so the user can watch; pass background=true to capture silently (the tab is briefly activated within its window for the capture, then the previous active tab is restored).",
+			"Capture a screenshot of an existing Chrome tab via the companion extension and save it to disk. Chrome's extension screenshot API requires the target tab to be the active tab in its window. Runs in the background by default (the tab is briefly activated within its window for the capture, then the previous active tab is restored); pass background=false to focus Chrome so the user can watch.",
 		promptSnippet: "Capture Chrome screenshots and save them under .pi/chrome-screenshots by default.",
 		parameters: Type.Object({
 			path: Type.Optional(Type.String({ description: "Output path. Defaults to .pi/chrome-screenshots/<timestamp>.<format>." })),
@@ -1385,7 +1396,7 @@ Usage rules:
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
 			background: Type.Optional(
-				Type.Boolean({ description: "If true, capture silently without focusing the Chrome window (the target tab is briefly activated within its window for the capture, then restored). Default false." }),
+				Type.Boolean({ description: "If true (the default), capture silently without focusing the Chrome window (the target tab is briefly activated within its window for the capture, then restored); pass false to focus Chrome." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-chrome",
-	"version": "0.15.32",
+	"version": "0.15.34",
 	"scripts": {
 		"test": "node test-suite/unit/csp-eval.test.mjs",
 		"version": "node scripts/sync-manifest-version.js",

package/test-suite/unit/csp-eval.test.mjs

@@ -164,6 +164,27 @@ async function run() {
     "waitFor: missing selector times out",
   );
 
+  // ===== usKeyLayoutForChar / cdpKeyInfo: US-layout key codes =====
+  // Regression: punctuation must NOT use charCodeAt() (".":46 collides with VK_DELETE,
+  // "-":45 with VK_INSERT), which made apps drop the char on keydown.
+  const { usKeyLayoutForChar, cdpKeyInfo } = sandbox;
+  const period = usKeyLayoutForChar(".");
+  ok(period.code === "Period" && period.keyCode === 190 && !period.needShift, "keylayout: '.' -> Period/190 (not 46)");
+  const dash = usKeyLayoutForChar("-");
+  ok(dash.code === "Minus" && dash.keyCode === 189, "keylayout: '-' -> Minus/189 (not 45)");
+  const slash = usKeyLayoutForChar("/");
+  ok(slash.code === "Slash" && slash.keyCode === 191, "keylayout: '/' -> Slash/191");
+  const at = usKeyLayoutForChar("@");
+  ok(at.code === "Digit2" && at.keyCode === 50 && at.needShift, "keylayout: '@' -> Digit2/50 + shift");
+  const A = usKeyLayoutForChar("A");
+  ok(A.code === "KeyA" && A.keyCode === 65 && A.needShift, "keylayout: 'A' -> KeyA/65 + shift");
+  const a = usKeyLayoutForChar("a");
+  ok(a.code === "KeyA" && a.keyCode === 65 && !a.needShift, "keylayout: 'a' -> KeyA/65 no shift");
+  const dot = cdpKeyInfo(".");
+  ok(dot.code === "Period" && dot.windowsVirtualKeyCode === 190 && dot.text === ".", "cdpKeyInfo: '.' -> Period/190 with text");
+  const ent = cdpKeyInfo("Enter");
+  ok(ent.code === "Enter" && ent.windowsVirtualKeyCode === 13, "cdpKeyInfo: named key 'Enter' unaffected");
+
   console.log(`\n${passes} passed, ${failures} failed`);
   if (failures) process.exit(1);
 }