Merge pull request #208 from esokullu/codex/background-tab-runs

Make local browser runs background-safe

Author: esokullu

README.md

@@ -212,10 +212,11 @@ they diverge.
 Chrome DevTools Protocol via `chrome.debugger`, so the Firefox build has no
 shadow-DOM piercing, no real trusted mouse events (some React/Vue handlers won't
 fire), no closed-shadow-root traversal, no `resolveSelector` retry budget, no
-SPA-navigation-aware retry, and no CDP screenshots (it falls back to
-`tabs.captureVisibleTab`, active tabs only). Site adapters, vision detection,
-loop detection, the auto-screenshot loop, and the Compact prompt/tool set *are*
-mirrored to Firefox. Some single-page apps may also fail to trigger
+SPA-navigation-aware retry, and no CDP screenshots. It uses `tabs.captureTab`
+for viewport screenshots, including inactive run tabs, but still cannot provide
+Chrome's pixel-perfect or full-page CDP capture. Site adapters, vision
+detection, loop detection, the auto-screenshot loop, and the Compact prompt/tool
+set *are* mirrored to Firefox. Some single-page apps may also fail to trigger
 content-script re-injection after client-side navigation.
 
 ## Contributing

docs/architecture.md

@@ -719,7 +719,7 @@ Firefox uses `browser.storage.session`.
 |---|---|---|
 | Background | Service worker (ephemeral) | Background page (persistent) |
 | Events | CDP-trusted (`isTrusted=true`) | Synthetic (`isTrusted=false`) |
-| Screenshots | CDP `Page.captureScreenshot` | `browser.tabs.captureVisibleTab()` |
+| Screenshots | CDP `Page.captureScreenshot` with run-scoped focus emulation for background tabs | `browser.tabs.captureTab()` for direct inactive-tab capture |
 | Conversation/UI persistence | `chrome.storage.session` | `browser.storage.session` |
 | Offscreen document | Yes (fetch proxy + recorder) | Not available |
 | Trace recorder | IndexedDB (opt-in) | IndexedDB (opt-in) — same `trace/recorder.js` |

docs/fr/architecture.md

@@ -402,7 +402,7 @@ rouvert reconstruise correctement le Markdown en cours. Chrome utilise
 |---|---|---|
 | Arrière-plan | Service worker (éphémère) | Page d'arrière-plan (persistante) |
 | Événements | CDP de confiance (`isTrusted=true`) | Synthétiques (`isTrusted=false`) |
-| Captures d'écran | CDP `Page.captureScreenshot` | `browser.tabs.captureVisibleTab()` |
+| Captures d'écran | CDP `Page.captureScreenshot` avec émulation de focus limitée à l'exécution en arrière-plan | `browser.tabs.captureTab()` pour capturer directement un onglet inactif |
 | Persistance conversation/interface | `chrome.storage.session` | `browser.storage.session` |
 | Document hors-écran | Oui (proxy fetch + enregistreur) | Non disponible |
 | Enregistreur de trace | IndexedDB (optionnel) | IndexedDB (optionnel) — même `trace/recorder.js` |

docs/fr/slash-commands.md

@@ -31,6 +31,7 @@ d'une espace ouvre l'autocomplétion de ses options disponibles.
 | `/workflow --export <id>` | Télécharger un fichier JSON portable `webbrain-workflow/1` assaini |
 | `/workflow --import --file` | Importer un fichier de workflow portable comme nouveau workflow local |
 | `/allow-api` | **Dérogation de mutation API par conversation.** Voir [plus bas](#allow-api). |
+| `/foreground [invite]` | Exécuter une tâche locale au premier plan pour assurer la compatibilité visuelle |
 | `/dangerously-skip-permissions` | **Contournement global des demandes d'autorisation.** Désactive `Ask before consequential actions` sans ouvrir les Paramètres. WebBrain agira sans demandes par site jusqu'à ce que vous réactiviez le réglage. |
 | `/compact` | Force le compactage du contexte pour la conversation actuelle |
 | `/verbose` | Bascule l'affichage verbeux/compact des outils |
@@ -64,6 +65,22 @@ quitter la page initiale ne la ramène pas vers l'URL surveillée, et l'onglet
 auxiliaire est fermé à la fin du watch. Les échecs d'interrogation transitoires
 sont tolérés ; trois échecs consécutifs arrêtent le watch.
 
+## `/foreground`
+
+Les exécutions locales ordinaires restent liées à leur onglet d'origine et
+fonctionnent sans activer cet onglet ni donner le focus à sa fenêtre. Chrome
+effectue les captures via CDP avec une émulation du focus limitée à l'exécution ;
+Firefox capture directement l'onglet cible avec `tabs.captureTab`. Si Chrome
+renvoie plusieurs fois une image vide en arrière-plan, WebBrain l'écarte et
+continue à partir du DOM et des données d'accessibilité.
+
+Utilisez `/foreground <invite>` comme solution de compatibilité pour une seule
+exécution lorsqu'un site ne restitue pas correctement son état visuel en
+arrière-plan. Cette commande rétablit l'activation de l'onglet et le focus de la
+fenêtre pour cette exécution uniquement. Elle n'est pas persistante, et les
+exécutions Cloud gérées conservent leur comportement actuel au premier plan car
+leur navigateur est dédié à la tâche.
+
 ## `/allow-api`
 
 `/allow-api` lève la restriction UI-d'abord pour la conversation en cours, afin
@@ -92,10 +109,11 @@ zone visible juste avant et après l'exécution (Chrome et Firefox). Par exemple
 `checkout-before.png` et `checkout-after.png` ; sans `--save-as`, WebBrain
 utilise des noms horodatés.
 
-Si l'exécution ouvre un autre onglet, WebBrain réactive l'onglet d'origine avant
-d'enregistrer la capture « après ». Si l'enregistrement ou la capture initiale ne
-peut pas être démarré et sauvegardé, l'exécution n'est pas envoyée. Les
-`/record` et `/screenshot` autonomes conservent leur comportement existant.
+Pour ce suffixe de diagnostic, Chrome peut réactiver l'onglet d'origine avant
+d'enregistrer la capture « après ». Firefox capture directement cet onglet sans
+l'activer. Si l'enregistrement ou la capture initiale ne peut pas être démarré
+et sauvegardé, l'exécution n'est pas envoyée. Les `/record` et `/screenshot`
+autonomes conservent leur comportement existant.
 
 ## Exports, instantanés et workflows
 

docs/slash-commands.md

@@ -31,6 +31,7 @@ for its available flags.
 | `/workflow --export <id>` | Download a sanitized portable `webbrain-workflow/1` JSON file |
 | `/workflow --import --file` | Import a portable workflow file as a new local saved workflow |
 | `/allow-api` | **Per-conversation API mutation override.** See [below](#allow-api). |
+| `/foreground [prompt]` | Run one local task in the foreground for visual compatibility |
 | `/dangerously-skip-permissions` | **Global permission-prompt bypass.** Turns off `Ask before consequential actions` without opening Settings. WebBrain will act without per-site prompts until you re-enable the setting. |
 | `/compact` | Force context compaction for the current conversation |
 | `/verbose` | Toggle verbose/compact tool display |
@@ -63,6 +64,20 @@ navigate it back to the watched URL, and the helper tab is closed when the watch
 ends. Transient poll failures are tolerated; three consecutive failures stop the
 watch.
 
+## `/foreground`
+
+Regular local runs stay pinned to their original tab and operate without
+activating that tab or focusing its window. Chrome captures through CDP with
+focus emulation scoped to the run; Firefox captures the target tab directly
+with `tabs.captureTab`. If Chrome repeatedly returns a blank background frame,
+WebBrain discards it and continues from DOM and accessibility data.
+
+Use `/foreground <prompt>` as a one-run compatibility escape hatch for a site
+whose visual state does not render correctly in the background. It restores tab
+activation and window focus for that run. The setting is not persistent, and
+managed cloud runs retain their existing foreground behavior because their
+browser is dedicated to the task.
+
 ## `/allow-api`
 
 `/allow-api` lifts the UI-first restriction for the current conversation so the
@@ -89,10 +104,11 @@ immediately before and after the run (Chrome and Firefox). For example,
 `checkout-before.png` and `checkout-after.png`; without `--save-as`, WebBrain
 uses timestamped filenames.
 
-If the run opens another tab, WebBrain reactivates the originating run tab
-before saving the after screenshot. If the recording or initial screenshot
-cannot be started and saved, the run is not sent. Standalone `/record` and
-`/screenshot` keep their existing behavior.
+For the Chrome diagnostic suffix, WebBrain may reactivate the originating run
+tab before saving the after screenshot. Firefox captures that tab directly
+without activating it. If the recording or initial screenshot cannot be
+started and saved, the run is not sent. Standalone `/record` and `/screenshot`
+keep their existing behavior.
 
 ## Exports, snapshots, and workflows
 

docs/zh-CN/architecture.md

@@ -278,7 +278,7 @@ while (steps < maxSteps) {
 |---|---|---|
 | 后台 | Service Worker（临时） | 后台页面（持久化） |
 | 事件 | CDP 受信任（`isTrusted=true`） | 合成事件（`isTrusted=false`） |
-| 截图 | CDP `Page.captureScreenshot` | `browser.tabs.captureVisibleTab()` |
+| 截图 | CDP `Page.captureScreenshot`，后台运行时使用仅限该次运行的焦点模拟 | `browser.tabs.captureTab()`，可直接捕获非活动标签页 |
 | 对话/UI 持久化 | `chrome.storage.session` | `browser.storage.session` |
 | 离屏文档 | 有（fetch 代理 + 录制器） | 不可用 |
 | 轨迹记录器 | IndexedDB（可选） | IndexedDB（可选）— 相同的 `trace/recorder.js` |

docs/zh-CN/slash-commands.md

@@ -29,6 +29,7 @@ WebBrain 接受作为输入框某行开头的斜杠命令。在面板内输入 `
 | `/workflow --export <id>` | 下载经过清洗的可移植 `webbrain-workflow/1` JSON 文件 |
 | `/workflow --import --file` | 将可移植工作流文件导入为新的本地工作流 |
 | `/allow-api` | **按对话的 API 变更覆盖。** 参见[下文](#allow-api)。 |
+| `/foreground [提示词]` | 为视觉兼容性在前台运行一次本地任务 |
 | `/dangerously-skip-permissions` | **全局权限提示绕过。** 无需打开设置即可关闭「操作前询问」。在你重新启用该设置之前，WebBrain 将不再按站点弹出提示。 |
 | `/compact` | 强制压缩当前对话上下文 |
 | `/verbose` | 切换详细/压缩工具显示 |
@@ -55,6 +56,17 @@ WebBrain 接受作为输入框某行开头的斜杠命令。在面板内输入 `
 轮询在专用的非活动标签页中进行，因此离开发起页面不会把它导航回被监视的 URL；watch
 结束时会关闭该辅助标签页。短暂的轮询失败可以容忍；连续三次失败会停止 watch。
 
+## `/foreground`
+
+常规本地运行会固定在最初的标签页上执行，不会激活该标签页或聚焦其窗口。Chrome 通过
+CDP 截图，并仅在该次运行期间模拟焦点；Firefox 使用 `tabs.captureTab` 直接捕获目标
+标签页。如果 Chrome 多次返回空白的后台画面，WebBrain 会丢弃该画面，继续使用 DOM
+和无障碍数据。
+
+若某个网站无法在后台正确渲染视觉状态，可使用 `/foreground <提示词>` 作为仅对本次
+运行生效的兼容模式。它会为该次运行恢复标签页激活和窗口聚焦，不会成为持久设置。
+托管 Cloud 运行仍保留现有前台行为，因为其浏览器专用于该任务。
+
 ## `/allow-api`
 
 `/allow-api` 会为当前对话解除 UI 优先限制，使智能体在 UI 失败时可通过 `fetch_url`
@@ -77,9 +89,9 @@ WebBrain 接受作为输入框某行开头的斜杠命令。在面板内输入 `
 `测试结账流程 /screenshot --save-as checkout.png` 会保存 `checkout-before.png` 和
 `checkout-after.png`；若不带 `--save-as`，WebBrain 使用带时间戳的文件名。
 
-如果运行打开了另一个标签页，WebBrain 会在保存「之后」截图前重新激活发起运行的标签页。
-如果录制或初始截图无法启动并保存，该运行不会被发送。独立的 `/record` 与
-`/screenshot` 保持原有行为。
+对于这个诊断后缀，Chrome 可能会在保存「之后」截图前重新激活发起运行的标签页；
+Firefox 会直接捕获该标签页而不激活它。如果录制或初始截图无法启动并保存，该运行不会
+被发送。独立的 `/record` 与 `/screenshot` 保持原有行为。
 
 ## 导出、快照与工作流