← Commit history

Update 1 file(s)

John Lauer ·4918ef13ab ·3mo ago ·parent f13b4d8
1 file changed +23
dev-skills/developing-the-bridge/SKILL.md+23
@@ -296,3 +296,26 @@ profile's plain avatar and never linger. exercised, `announceForeground()` now paints a full-desktop `desktop_caption` with that reason for 3s (auto-dismiss) and logs `_foreground_announce`. A takeover the user cannot see explained is exactly what erodes trust in an agent that can touch their desktop.++## ⭐ Announce EVERY user-visible open, at the BOTTOM of the screen (John, 2026-07-22)+**The rule:** if a native-browser open is going to be visible to the user — because that is simply how+the browser behaves — **allow it**, do not fight it, but put up a **2-second desktop caption naming the+reason**. Fighting the browser produced worse bugs than the foregrounding ever did; being unannounced is+the actual failure. Three cases must announce (`announceVisibleOpen`):+1. an explicit foreground grant (`foreground:true` / `userRequestedForeground` + reason),+2. **a page the browser GROUPED into an existing window** — no new window exists to background, so it+   surfaces regardless (this is what made a Fusion sign-in page appear unannounced),+3. `open_tab` with `active:true` — the tab lands in front of the user inside an existing window.++**Position: `bottom`, never `top`.** The user's eye is already at the taskbar — that is where the overlay+badge and the orange flash appear — so a bottom caption sits beside the signals it explains instead of+competing with them from the far edge of the screen.++**The reason is never optional and never blank:** it falls back to the session's `purpose`, which+registration already makes mandatory. Worst case it reads "no reason given", which is itself a useful+signal that a calling thread is being sloppy. Every caption is logged (`_open_announce`) so you can audit+which thread announced what, and whether AD actually rendered it.++**Do NOT force-minimize what the browser intends to surface.** Background stays the default when a+genuinely new window IS created (verify `minimized:true`); when it cannot be honored, announce instead of+wrestling the window manager.