NB - Native Browser Bridge

@@ -1,47 +1,49 @@-# Adom Browser Extension--**Your AI's hands inside your real, signed-in browser.** The Adom Browser Extension (abe) works with-**both Chrome and Edge** - the browser you already use, with your cookies, SSO, saved logins, and-captcha trust intact. It is the native-browser counterpart to `pup` - the same command surface-(`nbrowser_*` mirrors `browser_*`), but every verb runs inside your *actual* browser, so your Adom AI-assistant can **build, drive, and test web software right alongside you**.--Cloud containers, Hydrogen Desktop, and the AD CLI reach it through the exact same-`relay → adom-desktop → bridge` path they already use for pup.--## Two layers of control--The system controls your native browser at two layers. You get value at layer 1 with nothing-installed in the browser; installing the extension unlocks layer 2.--**Layer 1: OS-level control, no extension required.** The bridge runs on your machine and knows your-browsers the way Windows does. Without the extension installed in any profile, your AI can already:--- **Map every identity**: every Chrome and Edge profile on the machine, with the email, the display-  label you see on the profile button ("John Personal", "adom.inc"), and whether the extension is-  installed there (`nbrowser_profiles`).-- **Open your real browser at a URL, in the right profile, in the background**-  (`nbrowser_open_os_window`): the window opens minimized with an orange flashing taskbar button, and-  you click it when you are ready. Your focus is never stolen. This is the OAuth workhorse: for flows-  like adom-google or Autodesk sign-in you are already authenticated in your own browser, so the AI-  opens the consent page in the correct profile and you just click Approve.+# Adom Native Browser++**Control of the browser you already use.** Adom Native Browser (**nb**) lets your AI work in your+real, signed-in Chrome or Edge, with your cookies, SSO, saved logins, and captcha trust intact. It+comes in two layers, and the first one works the moment Bridge is installed, with nothing added to+your browser at all.++## The two layers++**Layer 1, nb: open your real browser. Works on day one.**+No browser extension, no setup. Bridge already knows every Chrome and Edge profile on your machine,+so your AI can:++- **Open a URL in the right profile, in the background** (`nbrowser_open_os_window`). The window+  opens minimized with its taskbar button flashing orange, and you click it when you are ready. Your+  focus is never stolen. This is the OAuth workhorse: for adom-google, Autodesk, or any sign-in where+  you are *already* authenticated in your own browser, the AI puts the consent page in the correct+  profile and you just click Approve.+- **Know who is who** (`nbrowser_profiles`): every profile with its email and the display name you see+  on the browser's own profile button, so work and personal never get confused. - **Wake a sleeping profile with no window at all** (`nbrowser_wake_profile`), **inventory every-  browser window with ownership attribution** (`nbrowser_os_windows`), and **clean up windows through-  a deliberately hard two-step attestation gate** (`nbrowser_force_close`).+  browser window with ownership attribution** (`nbrowser_os_windows`), and **clean up windows** behind+  a deliberately hard two-step attestation gate (`nbrowser_force_close`).  At this layer the AI can open and manage windows but cannot see inside them: no reading, no clicking,-no screenshots. The user does the in-page work.--**Layer 2: deep control, extension installed.** With the extension in a profile, that profile becomes-fully drivable: navigate, read, click by visible text, type, upload files with no OS picker, run-JavaScript, screenshot and record in the background, wait on selectors and downloads, use saved-logins and TOTP behind strict gates. Layer 2 is also where the trust surface lives: every window is-registered with a purpose, the taskbar shows your profile picture with the Adom mark while the AI is-driving (and returns to native when it stops), spawned windows are tracked and reaped, and windows-you opened yourself are off limits, enforced in code.+no screenshots. You do the in-page work. That is enough for a surprising number of jobs, above all+finishing a sign-in.++**Layer 2, abe: let the AI actually drive. The upgrade.**+Install the Adom browser extension into a profile and that profile becomes fully drivable: navigate,+read the page, click by visible text, type with real `isTrusted` input, upload files with no OS+picker, run JavaScript, screenshot and record in the background, wait on selectors and downloads, use+saved logins and TOTP behind strict gates. This is the counterpart to `pup`, with the same command+surface (`nbrowser_*` mirrors `browser_*`), except every verb runs inside your *actual* logged-in+profile, so it sails through login walls and captchas that block pup's empty controlled Chromium.++Layer 2 is also where the trust surface lives. Every window an AI opens is registered with a stated+purpose. While an AI is driving, the taskbar button shows your own profile picture with the Adom mark+on it, and it returns to normal the moment driving stops. Windows *you* opened are off limits, and+that rule is enforced in code, not policy.  Every layer-1 response tells the AI honestly what it could not do and what layer 2 would add, so the-upgrade suggestion arrives at natural moments rather than as a wall.+upgrade suggestion arrives at a natural moment instead of as a wall.++Cloud containers, Hydrogen, and the `adom-desktop` CLI all reach this the same way they reach pup:+`relay -> Bridge -> bridge`.  ## Who we are, and why this extension needs broad browser capabilities @@ -66,32 +68,32 @@ banners.   ### Chip-fetcher - fill your CAD library while you keep designing-<video src="/blob/app/adom-browser-extension/demo/clips/use-case-1-chip-fetcher.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>+<video src="/blob/app/adom-native-browser/demo/clips/use-case-1-chip-fetcher.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video> Sourcing CAD for a BOM is tedious - symbol, footprint, 3D model, and datasheet for every part. Your AI drives the chip-fetcher dashboard in your browser, working down the parts list and pulling each one's full CAD bundle into your library, so the components are ready to drop into your design instead of you hunting them down one tab at a time.  ### Adom Symbol - schematic symbols, generated and previewed live-<video src="/blob/app/adom-browser-extension/demo/clips/use-case-2-adom-symbol.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>+<video src="/blob/app/adom-native-browser/demo/clips/use-case-2-adom-symbol.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video> You need a schematic symbol for a chip - pins grouped sensibly, the 3D package shown right on the symbol. Your AI drives Adom Symbol in the browser, generating the symbol from the datasheet pinout, arranging the pins by function, and embedding the 3D model - then previews it live so you can eyeball it before it lands in your library.  ### Web-based EDA & CAD - try a design change and see it routed-<video src="/blob/app/adom-browser-extension/demo/clips/use-case-3-web-eda.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>+<video src="/blob/app/adom-native-browser/demo/clips/use-case-3-web-eda.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video> Mid-design you want to try a change and see it routed. Your AI opens the EDA tool in the browser you're already signed into, **fills the schematic, re-runs the autorouter, and inspects the nets** - turning "try this and tell me what breaks" into something it just does, in the same session where your part libraries already live.  ### 3D board CAD - review the layout in the browser-<video src="/blob/app/adom-browser-extension/demo/clips/use-case-4-3d-board.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>+<video src="/blob/app/adom-native-browser/demo/clips/use-case-4-3d-board.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video> Before a board goes out, you want to look at the actual layout. Your AI opens the 3D board viewer in your browser, frames the camera, and x-rays the board to reveal the traces underneath - so reviewing a PCB is a conversation, not a context-switch into a separate desktop tool.  ### Adom Chipsmith - check a part fits its footprint before it ships-<video src="/blob/app/adom-browser-extension/demo/clips/use-case-5-chipsmith.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>+<video src="/blob/app/adom-native-browser/demo/clips/use-case-5-chipsmith.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video> Before a part goes onto a board, its 3D model and footprint have to actually line up. Your AI drives Adom Chipsmith in the browser to drop the chip onto its pads and check the fit visually - catching a mis-seated or wrong-variant model before it ever reaches the PCB.@@ -116,14 +118,14 @@ That's the whole reason for `debugger`, `cookies`, and `<all_urls>`: a developer against authenticated third-party APIs needs **full DevTools-grade access in their real session**. Take it away and this is just a worse screenshot tool. The table below maps every capability to a concrete request. -<img src="/blob/app/adom-browser-extension/screenshots/dev-debug-mouser-digikey.png" alt="The Adom AI assistant debugging an authenticated DigiKey API call inside the developer's own signed-in browser - eval in the page context, reading back the real authed JSON response" width="100%">+<img src="/blob/app/adom-native-browser/screenshots/dev-debug-mouser-digikey.png" alt="The Adom AI assistant debugging an authenticated DigiKey API call inside the developer's own signed-in browser - eval in the page context, reading back the real authed JSON response" width="100%">  | Permission | What the user-requested feature needs it for | |---|---| | `debugger` | Drive, inspect, screenshot, and **debug the live page** via the DevTools protocol - exactly what building and testing a web app requires. Attached only while a command runs, detached when idle. | | `host: <all_urls>` | A dev environment must work on **whatever app you're building or testing** - there's no fixed allow-list for "the whole web." Exercised only per command, never to crawl. | | `cookies` | Use your **existing signed-in dev tools and services** without forcing a re-login. Used to perform your task, never collected. |-| `nativeMessaging` | The core transport - connects the extension to **your local Adom Desktop** so your AI session can send commands and receive results. |+| `nativeMessaging` | The core transport - connects the extension to **your local Bridge** so your AI session can send commands and receive results. | | `tabs` · `scripting` · `webNavigation` | Open/switch/reload the tabs you operate, read the DOM and fill fields, and run each command at the right moment (e.g. "navigate, then screenshot"). | | `downloads` | Save files you ask to download - exports, CAD/3D assets, datasheets - into your own profile. | | `tabCapture` · `desktopCapture` | Record a walkthrough of **your own page** when you explicitly ask for one. |@@ -138,7 +140,7 @@ point it at, via the debugger/scripting APIs - never by loading external scripts - **It's visible when it's driving** - Chrome's *"started debugging this browser"* bar appears whenever a   debugger-using command runs; the extension lazy-attaches and idle-detaches after a few seconds, so the bar is   only up while it's actually working.-- **Idle by default** - it does nothing unless your Adom Desktop and an Adom session are connected, and you can+- **Idle by default** - it does nothing unless your Bridge and an Adom session are connected, and you can   remove it at any time to end all access.  ## What's new@@ -178,7 +180,7 @@ point it at, via the debugger/scripting APIs - never by loading external scripts  ## Fork & develop your own -Third parties are welcome to build their own version. The **[Fork &amp; develop guide →](https://wiki.adom.inc/adom/adom-browser-extension/files/docs/DEVELOPING.md)** walks through getting the source, loading it in **Chrome and Edge developer mode** (with screenshots), having **adom-desktop load it for you**, and the edit → reload dev loop.+Third parties are welcome to build their own version. The **[Fork &amp; develop guide →](https://wiki.adom.inc/adom/adom-native-browser/files/docs/DEVELOPING.md)** walks through getting the source, loading it in **Chrome and Edge developer mode** (with screenshots), having **adom-desktop load it for you**, and the edit → reload dev loop.  ## Sub-skills @@ -189,24 +191,24 @@ it connect" dead end:  | Stream | What it is | Where you see it | Current | |---|---|---|---|-| **Bridge runtime** | the local server Adom Desktop runs (`bridge.json` version) | the **Download** card | 0.1.50 |+| **Bridge runtime** | the local server Bridge runs (`bridge.json` version) | the **Download** card | 0.1.50 | | **Extension + host** | the MV3 extension + native host loaded into Chrome/Edge (`extension/manifest.json`) | `chrome://extensions` | 0.1.3 | | **Skills package** | the docs your AI reads (`pkg install`, root `package.json`) | the **Install** card | 0.4.x |  The bridge and the extension are BOTH `0.1.x` but are **different numbers** and update independently. The skew that matters for connectivity is **extension vs `bridge.json` `expectedExtensionVersion`** (the-extension the running bridge speaks to) — NOT the `0.4.x` skills-package number. If the native host keeps+extension the running bridge speaks to), NOT the `0.4.x` skills-package number. If the native host keeps exiting ("Native host has exited"), your extension/host is too old for the running bridge: re-sync the `extension/` + `host/` folders to the current build and reload. `nbrowser_readiness` (bridge 0.1.50+) reports this directly as `staleOnDisk`.  > **What `pkg install` gives you:** this package installs the bridge's SKILLS into your container so your-> AI knows how to drive your real signed-in Chrome and Edge; Adom Desktop loads the bridge runtime itself+> AI knows how to drive your real signed-in Chrome and Edge; Bridge loads the bridge runtime itself > from the release zip. The skills alone give you no bridge, and a bridge alone gives a calling AI no-> skills, so most setups want both. (Adom Desktop v1.9.142+ already ships this bridge as a default seed,+> skills, so most setups want both. (Bridge v1.9.142+ already ships this bridge as a default seed, > so extension-free control works on a fresh install with no steps at all.) -`adom-wiki pkg install adom/adom-browser-extension` installs this whole skill set - the core driving mechanics+`adom-wiki pkg install adom/adom-native-browser` installs this whole skill set - the core driving mechanics plus a growing list of **site recipes** that teach the AI how to drive specific websites. Each links to its full readme. @@ -214,31 +216,31 @@ to its full readme.  | Skill | What it covers | |---|---|-| [`adom-browser-extension`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/adom-browser-extension/SKILL.md) | **The main skill / router.** When to reach for the real browser (login/forms) vs pup, the `nbrowser_readiness` cold-start check, the offer-to-install hook, the three install surfaces (skills + bridge + extension), and the map to every sub-skill. |+| [`adom-native-browser`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/adom-native-browser/SKILL.md) | **The main skill / router.** When to reach for the real browser (login/forms) vs pup, the `nbrowser_readiness` cold-start check, the offer-to-install hook, the three install surfaces (skills + bridge + extension), and the map to every sub-skill. |  **Core mechanics**  | Skill | What it covers | |---|---|-| [`driving-the-extension`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-the-extension/SKILL.md) | The full `nbrowser_*` surface: the CDP-vs-native "debugging" bar, `isTrusted` input + xy-finding, multi-profile driving, the credential-library query + login automation, the taskbar status feature. |-| [`native-browser-safety`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/native-browser-safety/SKILL.md) | The cardinal safety rules: only drive windows YOU opened, background-by-default, the credential gating, and the blocklist. Read before driving. |-| [`installing-the-extension`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/installing-the-extension/SKILL.md) | How WE install the extension into the user's Chrome/Edge over adom-desktop's generic verbs (dev-mode Load-unpacked, one-click consent, verify-by-screenshot). |-| [`uninstalling-the-extension`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/uninstalling-the-extension/SKILL.md) | Clean removal - filter to the Adom card so Remove is unambiguous, the confirm-bubble beat, verify by screenshot + dropped profile key. |-| [`native-browser-recording`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/native-browser-recording/SKILL.md) | Full-framerate **background** recording of the user's real, logged-in Chrome - the occlusion-flag mode, the restart-into-background-recording flow, and the offer-to-revert-for-battery step (the unique capability). |-| [`driving-the-desktop`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-the-desktop/SKILL.md) | OS-level control via `desktop_*` when CDP can't reach (extension lifecycle, `chrome://` pages, native dialogs, popups) - including the ⛔ never-drive-a-PWA-window guard and the v20 saved-password ban. |-| [`driving-the-extension-demo`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-the-extension-demo/SKILL.md) | A runnable demo playbook - recipes + the recording gotchas (window-capture-vs-CDP white pages, the keep-awake guard). |-| [`cross-platform-dev`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/cross-platform-dev/SKILL.md) | The Windows-first → Kyle-ports-Mac dev flow for the bridge/host/extension. |+| [`driving-the-extension`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/driving-the-extension/SKILL.md) | The full `nbrowser_*` surface: the CDP-vs-native "debugging" bar, `isTrusted` input + xy-finding, multi-profile driving, the credential-library query + login automation, the taskbar status feature. |+| [`native-browser-safety`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/native-browser-safety/SKILL.md) | The cardinal safety rules: only drive windows YOU opened, background-by-default, the credential gating, and the blocklist. Read before driving. |+| [`installing-the-extension`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/installing-the-extension/SKILL.md) | How WE install the extension into the user's Chrome/Edge over adom-desktop's generic verbs (dev-mode Load-unpacked, one-click consent, verify-by-screenshot). |+| [`uninstalling-the-extension`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/uninstalling-the-extension/SKILL.md) | Clean removal - filter to the Adom card so Remove is unambiguous, the confirm-bubble beat, verify by screenshot + dropped profile key. |+| [`native-browser-recording`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/native-browser-recording/SKILL.md) | Full-framerate **background** recording of the user's real, logged-in Chrome - the occlusion-flag mode, the restart-into-background-recording flow, and the offer-to-revert-for-battery step (the unique capability). |+| [`driving-the-desktop`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/driving-the-desktop/SKILL.md) | OS-level control via `desktop_*` when CDP can't reach (extension lifecycle, `chrome://` pages, native dialogs, popups) - including the ⛔ never-drive-a-PWA-window guard and the v20 saved-password ban. |+| [`driving-the-extension-demo`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/driving-the-extension-demo/SKILL.md) | A runnable demo playbook - recipes + the recording gotchas (window-capture-vs-CDP white pages, the keep-awake guard). |+| [`cross-platform-dev`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/cross-platform-dev/SKILL.md) | The Windows-first → Kyle-ports-Mac dev flow for the bridge/host/extension. |  **Site recipes** - the extension also supports pluggable per-site playbooks that teach the AI a specific app's flow (selectors, multi-step forms, gotchas). The index and the contribution model live in-[`driving-sites`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-sites/SKILL.md).+[`driving-sites`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/driving-sites/SKILL.md).  ### Contributing a sub-skill  The recipe set is meant to **grow** - anyone can add one, and it stays part of *this* one repo (we don't spin up a separate wiki page per bundled skill): -1. Add `skills/driving-<site>/SKILL.md` - copy the template in [`driving-sites`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-sites/SKILL.md).+1. Add `skills/driving-<site>/SKILL.md` - copy the template in [`driving-sites`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/driving-sites/SKILL.md). 2. Register it in `install.sh`, `uninstall.sh`, `package.json` `files[]`, and the index in `driving-sites`. 3. Open a PR on this page. @@ -252,19 +254,19 @@ The Extension runs inside your own browser and acts only on the commands you - o working on your behalf - give it. The pages and screenshots it reads go to your own Adom session to carry out the task you asked for, and it works through your existing signed-in sessions so the tools you already use just work. Saved passwords stay with the browser; its own autofill enters them. Full policy:-**[Privacy Policy (Markdown) →](https://wiki.adom.inc/adom/adom-browser-extension/files/PRIVACY.md)** ·-**[HTML version →](https://wiki.adom.inc/adom/adom-browser-extension/files/privacy.html)**+**[Privacy Policy (Markdown) →](https://wiki.adom.inc/adom/adom-native-browser/files/PRIVACY.md)** ·+**[HTML version →](https://wiki.adom.inc/adom/adom-native-browser/files/privacy.html)**  ## How the install actually works (end to end)  New to this and wondering what happens the first time, from a cloud / Hydrogen container all the way-to your real browser doing something useful? The **[First-time install flow &rarr;](https://wiki.adom.inc/adom/adom-browser-extension/files/docs/INSTALL-FLOW.md)**+to your real browser doing something useful? The **[First-time install flow &rarr;](https://wiki.adom.inc/adom/adom-native-browser/files/docs/INSTALL-FLOW.md)** walks every step and endpoint: how the container reaches adom-desktop over the relay, who installs the bridge / host / extension (and who does NOT), how the bridge knows the extension connected, how skills propagate, and how third parties add sub-skills so the extension keeps getting better.  Removing it (or reinstalling to apply an updated build) is documented too:-**[Uninstall flow &rarr;](https://wiki.adom.inc/adom/adom-browser-extension/files/docs/UNINSTALL-FLOW.md)**+**[Uninstall flow &rarr;](https://wiki.adom.inc/adom/adom-native-browser/files/docs/UNINSTALL-FLOW.md)** - background-first, the search-filter guard so you never remove the wrong extension, and the one brief narrated foreground beat the confirm bubble forces. @@ -289,8 +291,8 @@ How the AI drives it (the flow, proven end-to-end on a fresh machine):    with no errors. 4. **Confirm + drive** - `nbrowser_readiness` flips to `ready`; the AI proceeds with your task. -The recipe, hardening, and every picker/OS-dialog trap live in the **[`installing-the-extension`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/installing-the-extension/SKILL.md)**-skill; the step-by-step first-time walk-through is the **[First-time install flow](https://wiki.adom.inc/adom/adom-browser-extension/files/docs/INSTALL-FLOW.md)**.+The recipe, hardening, and every picker/OS-dialog trap live in the **[`installing-the-extension`](https://wiki.adom.inc/adom/adom-native-browser/files/skills/installing-the-extension/SKILL.md)**+skill; the step-by-step first-time walk-through is the **[First-time install flow](https://wiki.adom.inc/adom/adom-native-browser/files/docs/INSTALL-FLOW.md)**. Cardinal rule throughout: **the AI does everything it can itself - it never makes you do a step it could do.**  ## Dependencies