From a76fbc3b9b82038ab44c04d6379cc2d45e5cecd8 Mon Sep 17 00:00:00 2001 From: Igor Soarez Date: Sat, 14 Nov 2026 09:15:15 +0000 Subject: tabs: one window for every agent; inactive tabs take input; background off by default Measured in Brave on 2026-11-14: an inactive tab takes trusted CDP clicks, key presses, text and mouse moves, and Page.captureScreenshot renders it live. Only mouseWheel hangs, waiting for a frame. The upstream guard that refused input to every hidden page was wrong for inactive tabs, and it is what made a window per session look necessary. - New sessions' tabs open inactive in the user's last focused window, in the session's tab group; a window is created only when none is open. - New groups start collapsed, unless their tab is the one showing, and expand when a tab in them is brought forward. Existing groups keep the user's setting. - Input is refused up front only in a minimized window (untested there). - chrome_scroll scrolls hidden pages by script instead of the wheel. - Focus emulation on attach, so blur-sensitive menus stay open. - Background mode is off by default. Calls still default to background; background:false or chrome_tab activate brings a tab forward. - Agent guidance, tool descriptions and docs say so. --- docs/ARCHITECTURE.md | 6 +++--- docs/FAQ.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c35cdd8..8d4c72b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -46,15 +46,15 @@ To point pi-chrome at an existing tab, pass `targetId`, `urlIncludes`, or `title ## Background mode -The existing background setting is a hard session policy, enabled by default. No separate lock/unlock command is needed. +The background setting is a hard session policy when on. In this fork it is off by default: every call still defaults to background, and an agent may pass `background:false` (or call `chrome_tab activate`) when it needs a tab showing. An inactive tab takes trusted CDP input and renders screenshots (measured 2026-11-14), so that is rarely needed. ```text /chrome background on # enforce no explicit window focus/tab activation -/chrome background off # allow foreground/watch mode +/chrome background off # default: agents may bring a tab forward when they ask ``` - 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. +- With background off, calls stay in the background unless they pass `background:false`; `chrome_tab activate` defaults to foreground. - 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. diff --git a/docs/FAQ.md b/docs/FAQ.md index bf46a51..cfa2cfa 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -36,7 +36,7 @@ Subagent sessions that run inside an authorized Pi process (for example with pi- ## Does pi-chrome navigate my current tab? -No. The first chrome_* action that has no explicit target opens a **dedicated automation window** that pi-chrome owns (falling back to a dedicated tab only if a separate window can't be created), and reuses it for the rest of the session. Your existing tabs and windows are never reused or overwritten. Pass `targetId`/`urlIncludes`/`titleIncludes` to deliberately act on a tab you already have open. +No. The first chrome_* action that has no explicit target opens a **dedicated automation tab** that pi-chrome owns, inactive, in your window and in the session's own (collapsed) tab group, and reuses it for the rest of the session. A window is created only when none is open. Your existing tabs and windows are never reused or overwritten. Pass `targetId`/`urlIncludes`/`titleIncludes` to deliberately act on a tab you already have open. The window survives `/reload` and Chrome service-worker restarts because ownership is tracked by id and mirrored to `chrome.storage.session`. It is closed when you run `/chrome revoke` and on real session end (not on `/reload`); cleanup only ever closes that session's own window/tab. -- cgit v1.2.3