NB - Native Browser Bridge

@@ -74,6 +74,11 @@ username field and killed Chrome's password dropdown). As of v0.1.0 a bare `user is **not enough**: without a `foregroundReason` the window stays background. To genuinely foreground (some auth pages need it): **first** `adom-bridge notify_user` to warn the user, **then** pass `userRequestedForeground:true` + `foregroundReason:"<why>"`, do the one thing, and return to background.+⚠️ **On macOS this is not enforced in code yet (nb-bridge#52).** Chrome is not activated, so keyboard+focus stays with the user, but the window is drawn over their work and there is no auto-revert. On a Mac,+open small and call `nbrowser_window_state {state:"minimized"}` right after opening; the window stays fully+drivable while minimized.+ The verbs are built for this: `nbrowser_open_window` opens **unfocused**, `open_tab` opens `active:false`, `switch_window` does **not** raise - leave those defaults alone. Capture without foregrounding: **`nbrowser_screenshot` (CDP) and `desktop_screenshot_window` (WGC) both capture a

@@ -104,8 +104,8 @@ opens and navigations, drive `chrome://` pages only when the user is not mid-tas surface a window. (Observed live: a `desktop_navigate` to `chrome://extensions` left the window at `z:0` even though no `bring_to_front` was called and the window was opened `focused:false`.) -**The bridge now ENFORCES all of this in code (ext >= 0.0.22) - you cannot shove a window in front of-the user even by accident.** `open_window`/`open_tab` open in the background regardless of a stray+**On WINDOWS the bridge ENFORCES all of this in code (ext >= 0.0.22) - you cannot shove a window in front+of the user even by accident.** `open_window`/`open_tab` open in the background regardless of a stray `focused:true`/`active:true` (those legacy flags are IGNORED); `switch_window`/`focus` never raise; and after every open/navigate/switch/state change the bridge checks the z-order - if a driven window landed topmost, it is **auto-sent back to the background** (focus returned to the user's previous window, or the@@ -113,6 +113,13 @@ window minimized if the user was in another app) and the response carries a `_wa `focusAutoReverted:true`. Each auto-correction is logged as a `focus_violation` event (`nbrowser_events`) so the user can see when a thread tried to steal focus. +⚠️ **macOS: the enforcement below does NOT run yet (nb-bridge#52, 2026-10-14).** The window is not+activated, so the user's app keeps keyboard focus, but the new window is still DRAWN OVER their work, and+the z-order check and auto-revert are Windows-only. Until that ships, a careful caller on a Mac opens+small and immediately calls `nbrowser_window_state {state:"minimized"}` - a minimized window stays fully+drivable (eval, wait_for, navigate and screenshots all work) - and re-activates the user's previous app if+it changed. Do not tell a Mac user their windows open out of sight.+ **Foregrounding takes real work now (v0.1.0+), because it STEALS the user's keyboard focus.** Users automating the browser almost always have 5 other things in the foreground; a raised window captures their keystrokes (real incident: it typed a user's chat message into a username field and dismissed