NB - Native Browser Bridge

@@ -1,65 +0,0 @@-# DEV skill (source-only, dev-skills/) — architecture + the rich-hints rule--> Reader: **whoever edits this bridge.** NOT shipped to containers. Bridge SDK:-> https://wiki.adom.inc/adom/adom-desktop-bridges--## ⭐ THE loudest rule: the AI reads your verb OUTPUT, not this file-AD relays every field of a verb response verbatim to the calling AI. A verb that returns-`{success:true}` and nothing else makes the AI guess and retry-loop. EVERY `nbrowser_*` response MUST-carry a rich **`_hint`** (what just happened + the obvious next verb + the trap) plus `_next` /-`related` / `pitfalls`. This is the single highest-leverage thing in the whole bridge.--Mechanism in `server.js`: a single **`VERB_META`** table is the source of truth. It feeds BOTH-`nbrowser_describe` (per-verb hint/related/pitfalls) AND a `decorateHint(verb, r)` wrapper that stamps-top-level `_hint`/`related`/`_next` onto EVERY dispatch response. Add a verb → add its VERB_META entry-in the same commit, or it ships hint-less.--## The 3 components (know which one you're touching)-1. **The bridge** (`bridge/server.js`) — AD spawns it (`spawn.kind:"node"`), so **AD provisions Node**-   (v1.9.63 runtime contract; you never install Node for it). Binds `127.0.0.1:0` on-   `process.env.ADOM_BIND_HOST || '127.0.0.1'` (never `0.0.0.0` → no firewall prompt). Writes a-   discovery file `~/.adom/bridges/native-browser/host.json` + `node-path.txt`. Serves `/status`-   (health chip: led/summary/tooltip) + `/command` for AD, plus a loopback TCP listener the host dials.-2. **The native-messaging host** (`host/native-host.js` via `native-host.bat`) — **Chrome launches it**,-   NOT AD, so it does NOT inherit AD's managed-runtime PATH. It reuses AD's Node via-   `node-path.txt` (published by the bridge = `process.execPath`, backslash-normalized) and falls back-   to PATH `node`. This is the ONLY place system-Node dependence could bite a fresh machine — keep the-   `.bat`'s two-branch resolution intact.-3. **The MV3 extension** (`extension/`) — runs inside Chrome/Edge, no runtime. SW `connectNative` →-   host → bridge loopback. Deterministic ID (`manifest.json` pins `key`) so the host manifest's-   `allowed_origins` is known ahead of time.--Data path: container → relay → AD → bridge `/command` → loopback → host stdio → extension SW → CDP/native.--## Hard-won runtime gotchas (extension side)-- **`chrome.tabs.goBack`/`goForward` throw on tabs we drive.** On a tab navigated via-  `chrome.tabs.update({url})` with the debugger lazily attached, `chrome.tabs.goBack` throws *"Cannot-  find a next page in history"* even when `window.history.length` proves there IS a back entry. **Route-  back/forward through the PAGE's own history** instead: `chrome.scripting.executeScript({target:{tabId},-  func: () => history.back()})`. Reliable, and stays banner-free (no debugger attach). (Fixed in ext-  0.0.16; verified on ADOMBASELINE.)-- **UIA Invoke doesn't fire on Win32 common-dialog buttons / some Edge controls.** `desktop_ui_click`-  (UIA Invoke) returns `success:true` but the dialog's OK/Select-Folder/Reload button doesn't actuate.-  Fall back to a foreground `desktop_click {x,y}` (SendInput) at the control's screen rect. (See-  installing-the-extension for the picker + Reload cases.)--## Verb contract-Request `{command, args}`; response `{success, output(JSON string), error?, errorCode?}` + the hints.-`nbrowser_readiness` is READ-ONLY (never spawns/installs) — mirror `bridge_readiness`. Long ops: return-a job id + `statusVerb`, don't block. `nbrowser_describe` returns the full catalog.--## Test locally-`node -c bridge/server.js` (syntax). Run `server.js` standalone → it binds ephemeral + writes the-discovery file; `GET 127.0.0.1:<port>/status` → led/summary/tooltip. End-to-end: `nbrowser_readiness`-through AD (`--target <laptop>`), then open bg window → screenshot → close.--## The boundary with AD (don't file bridge bugs as AD bugs)-AD owns: spawn/reap, stable port, supervisor, cache install + auto-update, status classification, the-GUI card. YOU own: verbs + hints, `/status`, `nbrowser_describe`, the wiki page + triggers, the-manifest + zip, the skills pkg. A generic missing capability (new lifecycle verb, relay field) → file-against AD; a misbehaving `nbrowser_*` verb → fix here.--## Safety invariants (never regress — one wiped a user's other AI threads)-Only ever drive a window YOU opened; NEVER navigate/reload/close the user's existing window/tab (incl.-OS `desktop_navigate`). Background by default; foreground is the user's choice. `nbrowser_credentials`-read-only, never returns passwords; auto-login gated on `confirm:true`+`host:`. Honor the blocklist.