NB - Native Browser Bridge

@@ -215,7 +215,8 @@ const HELP = {   ],   bestPractices: [     'Before driving, nbrowser_status to confirm connected. After a dev_reload, expect a ~3-6s reconnect.',-    'For demos: nbrowser_caption (in-page subtitle/alert) OR AD desktop_caption (fullscreen; use position:bottom — top covers the URL bar + Chrome warning). Bring the window to front with AD desktop_bring_to_front {hwnd,state:maximize} (chrome.windows focus can\'t beat Windows foreground-lock).',+    'NEVER foreground the driven window to take a screenshot — nbrowser_screenshot (CDP) and AD desktop_screenshot_window (WGC) both capture a BACKGROUND/occluded window, and yanking the user\'s real browser forward disrupts their work. Only raise a window (AD desktop_bring_to_front) when the user EXPLICITLY asks to watch it live.',+    'For demos: nbrowser_caption (in-page subtitle/alert) OR AD desktop_caption (fullscreen; use position:bottom — top covers the URL bar + Chrome warning).',     'Mouse verbs: pass cursor:true to show the gliding Adom cursor, and intent:"Clicking the Pay button" so the cursor LABEL narrates the action (builds user trust).',     'Recording: method "wgc" (Windows, via adom-desktop 1.8.148+; no picker, no banner, background-capturable, mp4 on disk) is best; "getdisplaymedia" is cross-platform but FORCES a share picker; "tabcapture" = the friendly "Record this tab" toolbar button (no picker, records current tab).',   ],@@ -227,7 +228,7 @@ const HELP = {     'fetch_url/download': 'fetch_url uses the user\'s REAL cookies (authed). download via chrome.downloads.',     'errors/events': 'errors = console/page errors for a tab. events = window/tab closes incl. byUser.',     'record_start/stop/status/list': 'method: wgc|getdisplaymedia|tabcapture. record_start is non-blocking for getdisplaymedia (poll record_status). base64 return is for SHORT clips only.',-    'caption/focus': 'caption{style:subtitle|alert,position}. focus activates the tab (use AD desktop_bring_to_front to actually raise the window).',+    'caption/focus': 'caption{style:subtitle|alert,position}. focus activates the tab + flashes its taskbar button (does NOT raise the window — by design, never steals the user\'s focus). Capture in place; only desktop_bring_to_front when the user explicitly wants to watch live.',     'flash/flash_stop/flash_mode/taskbar': 'Paint glanceable status on the driven browser window\'s Windows TASKBAR button (hwnd captured at open_window; an "Adom is driving" badge goes on automatically). flash = orange "come look" cue (auto-clears on focus). flash_mode{quiet|chatty|off}: quiet(default)=flash on come-look moments (load/screenshot/error/done); chatty=every action (users who want to watch); off=no auto-flash. nbrowser_taskbar{progress:{state:"normal"|"paused"|"error"|"indeterminate"|"none",value?},overlay:{badge:"adom"|"none"}} = progress bar (green/YELLOW-for-gates/red/marquee) + overlay badge for long tasks. Use paused(yellow)+flash on captcha/2FA/login. Clears on close.',   }, };

@@ -97,14 +97,18 @@ function waitForLoad(tabId, timeoutMs = 30000) { // ---- windows / sessions ---------------------------------------------------- export async function openWindow(args = {}) {   await ensureLoaded();-  const win = await chrome.windows.create({ url: args.url, focused: true });+  // Open in the BACKGROUND by default — never steal the user's focus. The window is fully+  // drivable + capturable while occluded; pass focused:true ONLY when the user explicitly+  // asked to watch it live. (This is the whole point of native-browser driving: the user+  // keeps working in their foreground window while we operate one of their other windows.)+  const win = await chrome.windows.create({ url: args.url, focused: args.focused === true });   const sid = args.sessionId || newSessionId();   sessionWindows.set(sid, win.id);   await persist();   const tab = (win.tabs && win.tabs[0]) || {};   return {     ok: true, sessionId: sid, tabId: String(tab.id), windowId: win.id, url: tab.url || args.url,-    _hint: 'New window opened (but NOT raised above other apps — chrome.windows focus can\'t beat the Windows foreground-lock). To truly foreground it, call Adom Desktop desktop_bring_to_front {"titleContains":"<the page title>","state":"maximize"}. Remember to nbrowser_close_window {sessionId:"' + sid + '"} when done so you don\'t leave abandoned windows.',+    _hint: 'New window opened in the BACKGROUND — the user\'s focus is deliberately NOT stolen. Screenshot it where it sits with nbrowser_screenshot (CDP) or AD desktop_screenshot_window (WGC); both capture a background/occluded window, so NEVER foreground it just to grab a shot. Only raise it (AD desktop_bring_to_front) if the user EXPLICITLY asked to watch live. Remember to nbrowser_close_window {sessionId:"' + sid + '"} when done so you don\'t leave abandoned windows.',   }; } @@ -369,9 +373,9 @@ export async function caption(args = {}) {   return { ok: true, tabId: String(tabId), text: args.text, style: args.style || 'subtitle' }; } -// Activate the tab + best-effort window focus. NOTE: on Windows this does NOT actually raise the-// window (OS foreground-lock blocks a background app from stealing focus — you just get a taskbar-// flash). So we return the window title + the exact AD recipe to TRULY foreground it.+// Activate the tab + flash its taskbar button. NOTE: on Windows this does NOT raise the window+// above other apps (OS foreground-lock blocks a background app from stealing focus — you get a+// taskbar flash, by design, so the user's focus is never yanked). This is the desired behavior. export async function focus(args = {}) {   const tabId = await resolveTabId(args);   const tab = await chrome.tabs.get(tabId);@@ -380,7 +384,7 @@ export async function focus(args = {}) {   const t = (tab.title || '').slice(0, 40);   return {     ok: true, tabId: String(tabId), windowId: tab.windowId, title: tab.title,-    _hint: `Activated the tab, but chrome.windows focus CANNOT raise the window above other apps on Windows (OS foreground-lock). To TRULY bring it to the front, call Adom Desktop: desktop_bring_to_front {"titleContains":${JSON.stringify(t)},"state":"maximize"}. The extension cannot foreground a window itself.`,+    _hint: `Activated the tab + flashed its taskbar button. chrome.windows focus does NOT raise the window above other apps on Windows — by design, so the user's focus is never stolen. Capture it in place with nbrowser_screenshot or AD desktop_screenshot_window (both work on a background window). Only raise it (AD desktop_bring_to_front {"titleContains":${JSON.stringify(t)}}) if the user EXPLICITLY asked to watch it live.`,   }; } 

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

@@ -1,6 +1,6 @@ --- name: driving-the-extension-description: How to drive the Adom browser extension (nbrowser_* verbs) — control the user's REAL logged-in Chrome/Edge from the cloud. Covers the CDP-vs-native split (and the "debugging this browser" bar), the full verb surface, isTrusted input (click-by-text + xy-finding, type/press_key, hover, right-click), the gliding Adom cursor with intent narration, screenshots, the taskbar status feature (flash/progress/Adom-overlay), bringing the window to the foreground, captions, the chip-fetcher use case, and every pitfall learned building it.+description: How to drive the Adom browser extension (nbrowser_* verbs) — control the user's REAL logged-in Chrome/Edge from the cloud. Covers the CDP-vs-native split (and the "debugging this browser" bar), the full verb surface, isTrusted input (click-by-text + xy-finding, type/press_key, hover, right-click), the gliding Adom cursor with intent narration, screenshots, the taskbar status feature (flash/progress/Adom-overlay), background-safe capture (never stealing the user's focus), captions, the chip-fetcher use case, and every pitfall learned building it. ---  # Driving the Adom Browser Extension (`nbrowser_*`)@@ -126,6 +126,11 @@ adom-desktop -t AdomLapper nbrowser_screenshot '{"sessionId":"s1","toFile":true} Screenshots are large base64 — over the relay they can time out, so **prefer `toFile:true` + `pull_file`** (binary, chunked). `screenshot_full_res` is unresized; default resizes ≤1568 for the model. +> **🚫 NEVER foreground the window to take a screenshot.** `nbrowser_screenshot` (CDP) captures the+> page bitmap with **zero OS-window interaction**, and AD `desktop_screenshot_window` (WGC) captures a+> **background / occluded** window fine. The user is usually working *in* their real browser — yanking+> it forward to grab a shot disrupts them. See [Do NOT foreground the window](#do-not-foreground-the-window-to-look-at-it--capture-in-place).+ ## Taskbar status — flash, progress, the "Adom is driving" overlay badge Paint glanceable status on the **real browser window's Windows taskbar button** (the hwnd is captured at `open_window`; an **Adom overlay badge** goes on automatically while driving — a trust tell). Driven via@@ -141,13 +146,23 @@ Play it like a status light: indeterminate green while working → yellow + flas + one flash on done. **Respect the user's mode** (anxiety-driven users want `chatty`; trusting users want `quiet`). Never leave it strobing. -## Bringing the Chrome window to the FOREGROUND-`nbrowser_focus` activates the right *tab* but **can't reliably raise the window** (Windows-foreground-lock). To pop the *window* forward use AD's Win32 verb:+## Do NOT foreground the window to look at it — capture in place+**The user is usually working IN their real browser. Stealing its focus disrupts them — this has been+called out directly ("that's disrupting my work massively").** The whole point of native-browser driving+is that the user keeps working in *their* foreground window while Adom operates one of their *other*+windows in the background. So:++- **Screenshots NEVER need foregrounding** — `nbrowser_screenshot` (CDP) and AD `desktop_screenshot_window`+  (WGC) both capture a **background / occluded** window. Capture where it sits; never raise it for a shot.+- **`open_window` opens in the BACKGROUND** (focus is not stolen). Pass `focused:true` *only* when the+  user explicitly asked to watch it live.+- `nbrowser_focus` activates the right *tab* and flashes its taskbar button, but **by design does NOT+  raise the window** above other apps (Windows foreground-lock) — so it never yanks the user's focus.+  To say "come look" without forcing the window forward, use the taskbar **flash / overlay** above.+- **Only** raise a window when the user EXPLICITLY asks to see it live ("show me", "let me watch"): ```bash adom-desktop -t AdomLapper desktop_bring_to_front '{"titleContains":"<page title>","state":"restore"}'  # or {hwnd} ```-Pattern: `nbrowser_focus` (tab) → `desktop_bring_to_front` (window).  ## Captions (two systems) - **In-page** `nbrowser_caption {text, style, position}` — `style:"subtitle"` (calm white-on-dark, the