NB - Native Browser Bridge

@@ -38,6 +38,17 @@ desktop_screenshot_window {hwnd:<W>}     # WGC, BACKGROUND - works on the privil ``` Then look at the image: is Developer mode visibly ON? did the picker show the right path? is the Adom card in the list, **Enabled, with NO Errors button**? Do not assert success off control state alone.+**Tip (verified):** shooting the BROWSER hwnd returns a top-level `screenshots[]` array of its **owned+popups** too - so when the folder picker is open, `desktop_screenshot_window {hwnd:<browser>}` hands+back the page AND the picker (`screenshots[0]` = the `#32770` dialog) in **one call**; you don't need+the picker's hwnd to read it.++## ⭐ Narrate to the user with on-screen captions (hand-hold them)+This runs on the USER's screen and some steps are fragile or need them. Keep them oriented with+`desktop_caption {text:"..."}` - a large, always-on-top, click-through desktop banner - at each step:+what you're doing ("Adom: turning on Developer mode", "Adom: selecting the extension folder...") and+especially **what THEY must do** ("Click Select Folder to finish", "Paste the path with Ctrl+V"). Clear+it when done. Treat the install as a guided, narrated process, never a silent one.  ## The flow (background; never foreground the user's work) Open a fresh background window you own, get its `hwnd`, and drive **that** (never the user's tabs):@@ -50,33 +61,50 @@ desktop_screenshot_window {hwnd:<W>}                               # verify the ### Step A - ensure Developer mode is ON (verify it VISUALLY) The page's **Developer mode** is a toggle (top-right on Chrome, bottom-left on Edge). ```-desktop_find_control {hwnd:<W>, contains:"Developer mode"}         # fast hint: the toggle + claimed state+desktop_find_control {hwnd:<W>, contains:"Developer mode"}         # fast hint + best.rect of the toggle desktop_screenshot_window {hwnd:<W>}                               # GROUND TRUTH - read it: is the toggle ON?-# only if the SCREENSHOT shows it off:-desktop_ui_click {hwnd:<W>, contains:"Developer mode"}             # background Invoke-desktop_screenshot_window {hwnd:<W>}                               # confirm it flipped AND the Load unpacked / Pack / Update row appeared+```+⚠️ **Verified:** the "Developer mode" control is `invokable:false`, so `desktop_ui_click` will NOT flip+it. If the screenshot shows it OFF, click its **rect** with SendInput (foreground, brief):+```+desktop_click {x:<best.rect.centerX>, y:<best.rect.centerY>}      # toggle it (the label/toggle isn't UIA-invokable)+desktop_screenshot_window {hwnd:<W>}                              # confirm it flipped AND Load unpacked / Pack / Update appeared ``` Do not proceed until the screenshot shows Developer mode ON and the **Load unpacked** button visible. If the row didn't appear, the toggle didn't flip - re-read and retry, don't proceed blind. -### Step B - Load unpacked -> the native folder picker (THE fragile step we harden)-```-desktop_ui_click {hwnd:<W>, contains:"Load unpacked"}             # opens a Win32 folder picker (#32770; it DOES enumerate in desktop_list_windows + has an a11y tree)-```-Now select the `extension/` folder. This is the step that breaks most often, so be deliberate:-- **Preferred:** put the exact path into the picker's path/edit field and commit. `desktop_ui_set` on-  the picker edit can return *"operation was canceled by user"* on some builds - if it does, fall back-  to: focus the picker, `desktop_press_key` the path via clipboard paste (set clipboard, Ctrl+V), then-  Enter; or type into the "Folder:" combo and Enter.-- **Last resort (works because the picker remembers the last dir):** if the picker already opens inside-  the `extension/` folder, just `desktop_ui_click {hwnd:<picker>, role:"button", contains:"Select"}`.-- **Always verify the chosen path** with `desktop_screenshot_window {hwnd:<picker>}` BEFORE clicking-  Select - selecting the wrong folder loads a broken/old build silently.+### Step B - Load unpacked -> the native folder picker (VERIFIED method, 2026-06-27)+```+desktop_caption {text:"Adom: selecting the extension folder..."}  # narrate to the user+desktop_ui_click {hwnd:<W>, automationId:"loadUnpacked"}          # VERIFIED stable id + invokable; background -> opens the picker+```+The picker is a Win32 dialog (`#32770`, title "Select the extension directory."). ⚠️ **It opens in an+arbitrary last-used directory (observed: Downloads) - NEVER trust "it remembers the folder."** You MUST+set the path. Fill it by this ladder (most reliable first; all AD verbs, all observed live):++1. **Address bar - VERIFIED to work.** Focus the picker, then:+   ```+   desktop_press_key {hwnd:<picker>, keys:"ctrl+l"}              # focus the address bar+   desktop_type      {hwnd:<picker>, text:"<abs path to extension>"}+   desktop_press_key {hwnd:<picker>, keys:"enter"}              # navigates INTO the folder (breadcrumb + file list confirm it)+   desktop_ui_click  {hwnd:<picker>, automationId:"1"}          # the "Select Folder" button (id "1", invokable) -> commits+   ```+   SendInput-based, so the picker must be foreground - it is (modal). Keep it brief.+2. **Clipboard assist (put the USER in the loop for the one fragile step).** Copy the absolute path to+   the clipboard, `desktop_caption {text:"Paste this path (Ctrl+V) into the Folder box, then Select Folder"}`,+   and let them finish. Good when automation is uncertain or you want consent at the commit.+3. **UIA SetValue does NOT work here (verified).** The Folder combobox has **no ValuePattern** (`desktop_ui_set`+   returns "control found but has NO ValuePattern"). Do not rely on `ui_set` for the picker path.+4. **Coordinate click + type (last resort, most fragile).** `desktop_click` the Folder box by its rect,+   then `desktop_type`. Layout-dependent; only if 1 fails.++**ALWAYS screenshot and READ the path BEFORE committing.** `desktop_screenshot_window {hwnd:<W>}` (the+BROWSER hwnd) returns the picker in its `screenshots[]` array - confirm the breadcrumb/Folder shows+`...\extension` before clicking **Select Folder**; the wrong folder loads a broken/old build silently.+To back out without loading: `desktop_ui_click {hwnd:<picker>, automationId:"2"}` (Cancel). -> ⚠️ **This is the active iteration target.** The reliable, build-independent way to fill the picker-> path is exactly what we are hardening (a deterministic `install/load-unpacked` helper that sets the-> path and confirms, with retries + a screenshot check). Treat the path-fill as "verify, don't assume",-> and prefer the helper script once it lands.+> Next: a deterministic `install/load-unpacked` helper that runs ladder step 1 with retries + the+> screenshot path-check + captions baked in, so this is one call, not improvised steps.  ### Step C - verify it loaded clean AND connected (screenshot FIRST, three checks) 1. **Screenshot the extensions list and READ it** - this is the check that actually matters: