NB - Native Browser Bridge

@@ -394,8 +394,78 @@ function flashHint() {   return `${FLASH_HINT}${flashMode}. Get the user's attention: nbrowser_flash {sessionId}. The USER may prefer more/less noise - nbrowser_flash_mode {mode:"quiet"|"chatty"|"off"} (quiet=come-look moments only [default]; chatty=every action, for users who want to watch; off=silent). On a human-in-the-loop gate (captcha/2FA/login), nbrowser_flash so they come help. Never leave it strobing - it auto-clears on focus, or nbrowser_flash_stop.`; } +// ============================================================================================+// VERB_META — ONE source of truth for per-verb hint/related/pitfalls. Feeds BOTH (a) nbrowser_describe+// (so AD's Verbs tab shows guidance + chaining + traps) AND (b) the rich `_hint` attached to EVERY+// verb response (decorateHint). The whole point: a calling AI should never have to guess or read docs,+// and should be STEERED away from the dangerous moves these powerful tools allow. ASCII only (no em-dashes).+// ⛔ SAFETY THREAD: this bridge drives the user's REAL, signed-in browser. The cardinal rule, repeated on+// every navigate/reload/close/window verb: only ever act on a window/tab YOU opened (nbrowser_open_window).+// Never touch one the user already has open - that can wipe their live work and other AI threads' tabs.+const OWN_ONLY = 'ONLY operate on a window/tab YOU opened via nbrowser_open_window. NEVER navigate/reload/close a window or tab the user already had open - the bridge drives their REAL browser, so you would destroy their live page, forms, sessions, or other AI threads.';+const VERB_META = {+  nbrowser_status: { hint: 'Connectivity check: connected profiles + active browser. Call this first if any verb errors "not connected".', related: ['nbrowser_profiles', 'nbrowser_ping', 'nbrowser_open_window'], pitfalls: ['a profile\'s extension SLEEPS when that profile has no open windows - it then shows disconnected; open a window to wake it'] },+  nbrowser_ping: { hint: 'Round-trip liveness through to the extension.', related: ['nbrowser_status'], pitfalls: [] },+  nbrowser_open_window: { hint: 'Open a NEW background window YOU own and get a sessionId; do ALL your work through that sessionId. This is how you get a surface to drive WITHOUT touching the user\'s own windows.', related: ['nbrowser_navigate', 'nbrowser_screenshot', 'nbrowser_close_window'], next: 'nbrowser_navigate', pitfalls: ['opens UNFOCUSED - do NOT pass focused:true unless the user asked to watch', 'this is the safe way to work: always drive a window you opened, never the user\'s existing ones'] },+  nbrowser_close_window: { hint: 'Close a window you opened. Clean up your own sessions when done.', related: ['nbrowser_list_windows'], pitfalls: ['⛔ only close a sessionId YOU opened - closing the user\'s window can wipe their live work and other AI threads'] },+  nbrowser_switch_window: { hint: 'Target a window for later verbs. Does NOT raise it.', related: ['nbrowser_list_windows'], pitfalls: ['does not foreground (by design); pass focused:true ONLY on explicit user request'] },+  nbrowser_list_windows: { hint: 'List live windows/sessions with bounds+state.', related: ['nbrowser_switch_window', 'nbrowser_rescan'], pitfalls: [] },+  nbrowser_window_state: { hint: 'Maximize/fullscreen/normal/minimize or move+resize.', related: ['nbrowser_fullscreen'], pitfalls: ['resizing a window the USER is in disrupts them; act on your own session windows'] },+  nbrowser_fullscreen: { hint: 'Fullscreen the window (hides tabs/URL bar) - great for clean recordings.', related: ['nbrowser_window_state'], pitfalls: ['F11-via-key does NOT work; use this verb'] },+  nbrowser_login_state: { hint: 'Is the profile signed in to a URL right now (via chrome.cookies)?', related: ['nbrowser_credentials'], pitfalls: [] },+  nbrowser_credentials: { hint: 'Read-only QUERY of the browser\'s own saved-login store (which vendors the user can auto-login to). Never returns passwords.', related: ['nbrowser_login_state', 'nbrowser_navigate'], pitfalls: ['if a vendor is not listed, the user has no saved login - ask them to save one once', 'never exposes the password; Chrome autofills it when you focus the field'] },+  nbrowser_profiles: { hint: 'List every BROWSER x PROFILE you can drive + which is active. Drive several in parallel with profile:"<key>".', related: ['nbrowser_use_profile', 'nbrowser_profile_block'], pitfalls: ['active is only the default when no profile is passed'] },+  nbrowser_use_profile: { hint: 'Set the default profile that verbs target.', related: ['nbrowser_profiles'], pitfalls: ['you can still override per-call with profile:"<email>"'] },+  nbrowser_profile_block: { hint: 'Blocklist a profile so it is NEVER driven (user safety whitelist; persists).', related: ['nbrowser_profile_unblock', 'nbrowser_profiles'], pitfalls: ['respect the blocklist - it is the user telling you hands-off'] },+  nbrowser_profile_unblock: { hint: 'Remove a profile from the blocklist.', related: ['nbrowser_profile_block'], pitfalls: [] },+  nbrowser_rescan: { hint: 'Reconcile the session map against live windows (drop closed).', related: ['nbrowser_list_windows'], pitfalls: [] },+  nbrowser_open_tab: { hint: 'Open a background tab in one of YOUR session windows.', related: ['nbrowser_close_tab', 'nbrowser_list_tabs'], pitfalls: ['opens active:false (background); open tabs in a window you created, not the user\'s'] },+  nbrowser_close_tab: { hint: 'Close a tab you opened.', related: ['nbrowser_list_tabs'], pitfalls: ['⛔ only close a tab YOU opened - closing the user\'s tab destroys their live page/session'] },+  nbrowser_switch_tab: { hint: 'Make a tab active within its window.', related: ['nbrowser_list_tabs'], pitfalls: [] },+  nbrowser_list_tabs: { hint: 'List tabs (tabId/url/title/active).', related: ['nbrowser_switch_tab'], pitfalls: [] },+  nbrowser_navigate: { hint: 'Navigate a tab to a URL. ' + OWN_ONLY, related: ['nbrowser_open_window', 'nbrowser_screenshot', 'nbrowser_wait'], next: 'nbrowser_screenshot', pitfalls: [OWN_ONLY, 'navigation can race - verify with nbrowser_screenshot before asserting success'] },+  nbrowser_reload: { hint: 'Reload a tab. ' + OWN_ONLY, related: ['nbrowser_navigate'], pitfalls: ['⛔ never reload a window the user is in - you lose their unsaved state; reload only your own session'] },+  nbrowser_back: { hint: 'History back on your own session tab.', related: ['nbrowser_forward'], pitfalls: ['only on a window you opened'] },+  nbrowser_forward: { hint: 'History forward on your own session tab.', related: ['nbrowser_back'], pitfalls: ['only on a window you opened'] },+  nbrowser_wait: { hint: 'Sleep server-side (let a page settle) before the next verb.', related: ['nbrowser_screenshot'], pitfalls: [] },+  nbrowser_screenshot: { hint: 'CDP screenshot - captures a BACKGROUND/occluded window WITHOUT foregrounding it. This is how you "see" a page; never pull a window forward to grab a shot.', related: ['nbrowser_eval', 'nbrowser_click'], pitfalls: ['resized <=1568 for the model; pass toFile:true to save full-res to a laptop file (pull_file it)'] },+  nbrowser_screenshot_full_res: { hint: 'Full-resolution / full-page screenshot via CDP.', related: ['nbrowser_screenshot'], pitfalls: ['large base64 can be slow over the relay - prefer toFile then pull_file'] },+  nbrowser_eval: { hint: 'Run JS in the page and get the result. Powerful - use read-only expressions to inspect state.', related: ['nbrowser_screenshot'], pitfalls: ['runs arbitrary JS on the user\'s LIVE session - never run destructive scripts'] },+  nbrowser_evaluate: { hint: 'Alias of nbrowser_eval.', related: ['nbrowser_eval'], pitfalls: ['runs arbitrary JS on the user\'s LIVE session - never run destructive scripts'] },+  nbrowser_input_dispatch: { hint: 'Low-level isTrusted CDP input (click/move/type/key).', related: ['nbrowser_click', 'nbrowser_type'], pitfalls: ['prefer nbrowser_click (smart selector) over raw xy'] },+  nbrowser_click: { hint: 'Click by visible text / selector / xy (isTrusted). Optional gliding cursor + intent label.', related: ['nbrowser_screenshot', 'nbrowser_type'], next: 'nbrowser_screenshot', pitfalls: ['attaches the debugger (yellow "debugging" bar; idle-detaches ~8s)', 'verify it landed with a screenshot - SPAs can swallow synthetic-looking events'] },+  nbrowser_type: { hint: 'Type into the focused field (isTrusted).', related: ['nbrowser_click', 'nbrowser_press_key'], pitfalls: ['click the field FIRST so it has focus'] },+  nbrowser_press_key: { hint: 'Press a key (Enter/Tab/etc.).', related: ['nbrowser_type'], pitfalls: [] },+  nbrowser_fetch_url: { hint: 'Authed fetch using the user\'s REAL cookies - perfect for logged-in JSON/APIs that pup cannot reach.', related: ['nbrowser_navigate'], pitfalls: ['results come from the user\'s live session - treat as sensitive'] },+  nbrowser_errors: { hint: 'Buffered page/console errors for a tab.', related: ['nbrowser_eval'], pitfalls: [] },+  nbrowser_close: { hint: 'Not an extension verb - close a specific window/tab instead.', related: ['nbrowser_close_window', 'nbrowser_close_tab'], pitfalls: ['there is no global detach-all; the debugger idle-detaches on its own'] },+  nbrowser_record_start: { hint: RECORD_WGC_HINT, related: ['nbrowser_record_stop', 'nbrowser_record_status'], next: 'nbrowser_record_status', pitfalls: ['⭐ prefer method:"wgc" (delegates to core desktop_record_window_start)', 'getdisplaymedia/tabcapture are REFUSED without fallbackConfirmed:true - a browser extension cannot silently screen-record'] },+  nbrowser_record_stop: { hint: 'Stop a recording and finalize the mp4 (pull it with pull_file).', related: ['nbrowser_record_status'], pitfalls: ['needs the recordingId from record_start, not a sessionId'] },+  nbrowser_record_status: { hint: 'Poll a recording.', related: ['nbrowser_record_start'], pitfalls: [] },+  nbrowser_record_list: { hint: 'List recent recordings.', related: ['nbrowser_record_status'], pitfalls: [] },+  nbrowser_flash: { hint: 'Flash the driven window\'s taskbar button - the "come look" cue (e.g. at a captcha/2FA/login human-gate).', related: ['nbrowser_flash_stop', 'nbrowser_flash_mode'], pitfalls: ['auto-clears on focus; nbrowser_flash_stop to clear early'] },+  nbrowser_flash_stop: { hint: 'Stop the taskbar flash.', related: ['nbrowser_flash'], pitfalls: [] },+  nbrowser_flash_mode: { hint: 'Set auto-flash verbosity (quiet/chatty/off).', related: ['nbrowser_flash'], pitfalls: [] },+  nbrowser_taskbar: { hint: 'Paint progress/overlay/flash on the window taskbar button (e.g. paused=yellow for a human gate).', related: ['nbrowser_flash'], pitfalls: ['clear everything at task end: {progress:{state:"none"},overlay:{badge:"none"},flash:"stop"}'] },+  nbrowser_describe: { hint: 'Returns per-verb schemas + hint/related/pitfalls for AD\'s Verbs tab.', related: ['nbrowser_help'], pitfalls: [] },+};+// Attach a rich `_hint` (+ related/_next) to EVERY response from VERB_META, so an AI calling cold is+// always told what it got, what to do next, and what to avoid - without ever reading docs first.+function decorateHint(verb, r) {+  if (!r || typeof r !== 'object') return r;+  const m = VERB_META[verb];+  if (!m) return r;+  if (r._hint == null && m.hint) r._hint = m.hint;          // never clobber a more-specific hint+  if (r.success !== false) {                                 // chaining aids only on success+    if (r.related == null && m.related && m.related.length) r.related = m.related;+    if (r._next == null && m.next) r._next = m.next;+  }+  return r;+}+ function dispatch(verb, args) {-  return new Promise((resolve) => {+  return new Promise((rawResolve) => {+    const resolve = (r) => rawResolve(decorateHint(verb, r));     if (verb === 'nbrowser_help') {       return resolve({ success: true, output: JSON.stringify({ ok: true, bridge: BRIDGE, version: VERSION, extConnected: anyConnected(), flashMode, ...HELP }) });     }@@ -405,8 +475,10 @@ function dispatch(verb, args) {     if (verb === 'nbrowser_describe') {       const S = 'optional sessionId of a window opened via nbrowser_open_window';       const P = 'optional profile key "chrome:<email>" / "edge:<email>" (default = active)';-      const d = (name, summary, input, output, timeoutSeconds, opts = {}) =>-        ({ name, summary, input, output, timeoutSeconds, statusVerb: opts.statusVerb || null, longRunning: !!opts.longRunning, example: opts.example || {} });+      const d = (name, summary, input, output, timeoutSeconds, opts = {}) => {+        const m = VERB_META[name] || {};+        return { name, summary, input, output, timeoutSeconds, statusVerb: opts.statusVerb || null, longRunning: !!opts.longRunning, example: opts.example || {}, hint: m.hint || summary, related: m.related || [], pitfalls: m.pitfalls || [] };+      };       const verbs = [         d('nbrowser_status', 'Is the extension connected? Reports ext id/version + active browser.', {}, { ok: 'bool', ext: 'str', version: 'str', engine: 'str', browser: '"chrome"|"edge"' }, 15),         d('nbrowser_ping', 'Round-trip liveness check through to the extension.', {}, { ok: 'bool', pong: 'bool' }, 15),