# Taskbar status feature — design (flash + progress + overlay + self-teaching hints)

Goal: when the AI drives the user's real browser, paint glanceable status onto that window's Windows
taskbar button — so the user has an "ongoing task list" cue (pup-style) without watching the screen.
Designed with John, 2026-06-20.

## What renders on the BROWSER (Chrome/Edge) taskbar button
Only these work cross-window (ITaskbarList3 + FlashWindowEx take any hwnd):
- **Flash** (`FlashWindowEx`, FLASHW_TRAY|FLASHW_TIMERNOFG) — orange "come look" until the user focuses
  the window. Self-clears on focus; bridge also stops it on close/shutdown.
- **Progress bar** (`SetProgressState`/`SetProgressValue`) — determinate 0–100% or indeterminate
  marquee, color-coded: green=running, **yellow=paused (human-in-the-loop: captcha/2FA/login)**, red=error.
- **Overlay badge icon** (`SetOverlayIcon`) — small corner glyph. **DEFAULT = the Adom logo whenever a
  session is driving the window ("Adom is driving your browser")**. AI / 3rd-party bridge can override
  with a custom icon; `"none"` clears.

(Thumbnail-toolbar buttons, jump lists, iconic/live-preview only work on the owner's OWN window, so
they'd be AD's button — "AI cockpit", phase 2. A DWM live thumbnail of the browser inside AD is the
juicy phase-2 item.)

## Flash modes (set by USER or AI)
- `quiet` (default) — flash only on "come look" moments: navigate-complete, screenshot taken, error,
  task done. Plus progress/overlay stay live.
- `chatty` — flash on every activity verb (click/type/navigate/eval/screenshot). For anxiety-driven
  users who want to watch everything.
- `off` — no auto-flash; explicit `nbrowser_flash` still works.

## Bridge verb surface (bridge owns the logic; AD owns the OS primitive)
- `nbrowser_flash {sessionId?}` / `nbrowser_flash_stop {sessionId?}`
- `nbrowser_flash_mode {mode:"quiet"|"chatty"|"off"}`
- `nbrowser_taskbar {sessionId?, progress?:{state,value?}, overlay?:{badge,tooltip?}}`
- **hwnd captured at control-start**: on `nbrowser_open_window` the bridge resolves the OS hwnd (via
  AD GetForegroundWindow / desktop_list_windows — the just-opened window is focused) and caches
  `sessionId → hwnd`. All taskbar ops target the cached hwnd → never the wrong window.
- On control-start the bridge sets overlay=Adom by default.

## Self-teaching hints (a fresh AI thread must DISCOVER this — it isn't obvious)
- `nbrowser_open_window` reply: full hint — capability exists, current flashMode, the verbs, when to
  use (done/error/gate), that the USER can prefer chatty/quiet/off, "never leave it strobing".
- First activity per session: one-line reminder.
- `nbrowser_help`: complete reference + best-practice playbook.
- `nbrowser_flash_mode` echoes the new mode + that the user can change it anytime.
- Teach WHY/WHEN (courtesy to the user, tied to their preference), not just HOW.

## Dependency: AD `desktop_taskbar` verb (prompt sent to AD thread)
`desktop_taskbar { hwnd, flash?, progress?:{state,value?}, overlay?:{badge:"adom"(default)|"<named>"|"none", icon?:"<path|base64>", tooltip?} } -> {ok}`
- Lightweight persistent COM (ITaskbarList3 init once), no per-call process spawn.
- Ships the Adom overlay icon; accepts custom icons for 3rd-party bridges.
- Flash is the only channel doable via run_script fallback before this lands; progress/overlay need it.

## Build order
1. AD confirms `desktop_taskbar` shape (+ a foreground-hwnd helper if needed).
2. Bridge: hwnd capture on open_window + the 4 verbs + modes + auto-flash hook + Adom-overlay default
   + the rich hints. Extension: report active-window title if needed for hwnd resolution of adopted windows.
3. Test: open window → correct hwnd flashes; progress green/yellow/red; Adom badge shows while driving.