Pup - Puppeteer Bridge

Replace the blind-timer background park with one event-driven watchdog: wait for the window to exist, park once deactivate-first, re-park Chrome self-raises within 50ms, exit after 500ms of calm; afterwards nothing ever re-parks so a user taskbar click sticks; open response awaits the self-verified verdict.

Remove the GetLastInputInfo user-click heuristic, which false-fired whenever the user was typing anywhere and left fresh windows small and foreground; launch passes always park full-size, late re-parks use a simple pup-is-foreground check, centered-80 placement removed.

Revert minimize (it broke screenshots, visibilityState hidden hangs captureScreenshot); background is on-screen z-bottom with EnumWindows real-window handle, deactivate-then-park to avoid pop, and a short 1.2s re-park window so user clicks are not fought.

Background state is now MINIMIZE instead of on-screen z-bottom: minimizing hands focus back automatically and removes the re-park retry loop that fought user clicks, so a taskbar click restores the window and it stays; restore rect set on-screen; screenshots still work via disabled occlusion.

Resolve the real browser window via EnumWindows (largest visible Chrome_WidgetWin_1) instead of the flaky MainWindowHandle, which returned a hidden helper window on some boxes and left pup windows stuck off-screen so clicking their taskbar button showed nothing.

User-AI window balance: a deliberate user click now brings the pup window on-screen and shows it instead of activating it off-screen invisibly; browser_alert_window stop truly clears the Win11 flash tint via off-screen activation; programmatic per-window flash state added.

Respect a deliberate user raise: clicking a background pup window to watch a page load no longer forces it back to the background (open-time re-park now detects a real user click via GetLastInputInfo and latches off).

• v1.8.42: pup taskbar badge = the actual Adom favicon (was a hand-composited tile) (John Lauer)

• v1.8.41: pup taskbar badge is now the favicon-style tile — white Adom leaves on a teal rounded-rect (was bare white leaves) (John Lauer)

• v1.8.40: auto-badge pup windows with the white Adom leaves via AD-core desktop_taskbar (custom PNG overlay, AD >=1.9.106) — resolves the window by its (session: id) title, cross-process, on every open (John Lauer)

• v1.8.39: remove in-bridge ITaskbarList3 overlay (in-process-only, doesn't badge the browser's window) — taskbar badge is an AD-core desktop_taskbar capability; filing a pup-distinct-badge request to AD instead (John Lauer)

• v1.8.38: taskbar overlay badge — stamp the white Adom leaves on each pup window's taskbar button (ITaskbarList3::SetOverlayIcon) so pup windows are distinct from the user's real browser (John Lauer)
• Publish 1.8.38 (John Lauer)
• v1.8.37: cleanup nudge — browser_status/open _hint reminds the agent to close stale/piled-up pup windows (never auto-closes); skill: 'clean up after yourself' section (John Lauer)

• v1.8.36: snappy auto-flash — fire the taskbar flash the moment the window is backgrounded (after the local welcome page), not after the heavy URL's domcontentloaded (John Lauer)

• v1.8.35: browser_alert_window {stop:true} clears the taskbar highlight (FLASHW_STOP); fix alert_window to actually flash (was wrongly calling bringToFront) (John Lauer)

• Document the solved background-by-default/focus-steal playbook in the dev skill + CHANGELOG so it's never re-derived (off-screen launch, z-bottom park, AttachThreadInput focus handback, hidden PowerShell) plus the dead-ends (John Lauer)
• v1.8.34: AttachThreadInput focus hand-back — deterministically returns keyboard focus to the user's window after launch (no more keystroke steal); no minimize (no flicker) (John Lauer)

• v1.8.33: revert WS_EX_NOACTIVATE (broke taskbar-click); final = off-screen launch + on-screen-behind park (no pop, not covering, clickable, hidden PS) (John Lauer)

• v1.8.32: WS_EX_NOACTIVATE on background windows = deterministic no-focus-steal (never still-foreground); raise clears the style (John Lauer)

• v1.8.31: park background window ON-SCREEN sized-to-monitor at z-bottom (behind user windows, invisible, but clickable via taskbar); single background retry to avoid flicker (John Lauer)

• v1.8.30: run all window-mgmt PowerShell HIDDEN (execFileSync+windowsHide, no cmd shell) so pup never flashes a console; keep off-screen background shown for screenshots (John Lauer)
• v1.8.29: background = minimize-and-leave (off-screen already invisible), fully drops keyboard focus (John Lauer)
• v1.8.28: launch background windows OFF-SCREEN (never visually pops/covers user's work); raise repositions on-screen (John Lauer)
• v1.8.27: remove redundant pup-side localhost probe (AD core already reprimands localhost on failure); keep the real background-by-default fix + foreground-gate + finite flash (John Lauer)
• v1.8.26: real background-by-default (minimize->show-no-activate drops focus, self-verifying 'background' field); stop navigate/reload/switch_tab from raising bg windows (foreground-state gate); localhost reprimand (desktop-side port probe); finite flash (John Lauer)
• v1.8.25: fix foreground-restore threading (getOrLaunchBrowser now receives foreground; 1.8.24 threw 'foreground is not defined' on every open) (John Lauer)
• v1.8.24: fix background-by-default focus steal (capture user's foreground window before launch, restore it + push pup to back the instant the window appears via CDP-port owner resolution); finite 4-blink taskbar pulse instead of blink-forever (John Lauer)
• Remove internal identifiers from page.json (git-wiki)
• Publish 1.8.30 (John Lauer)
• Skills v1.8.30: teach auto-flash + updateNote/lastAgentUpdate signalling, keystroke-safe raise, open_tab tabId/tabCount, browser_render_html (UTF-8 HTML render) (John Lauer)
• v1.8.23: auto-flash on agent updates (debounced taskbar flash, {silent}/autoFlash:false), lastAgentUpdate/updateNote in list_tabs/list_windows, blur page focus before raise (keystroke-leak fix), open_tab returns tabId/tabCount, new browser_render_html verb (UTF-8-safe HTML render); doc steers alert-not-raise (John Lauer)
• Re-push page.json after pkg 1.8.29 (John Lauer)
• Publish 1.8.29 (John Lauer)
• skill: teach the new first-class page-driving verbs (browser_scroll / browser_set_viewport / browser_screenshot_element) + eval helpers, replacing the hand-rolled evals; pkg 1.8.29 (John Lauer)
• v1.8.22: screenshot_element below-fold clip fix + closest option (John Lauer)
• v1.8.21: browser_scroll + browser_set_viewport + browser_screenshot_element + shadow-DOM eval helpers + fullPage nested-scroll hint (John Lauer)
• Re-push page.json after pkg 1.8.28 (John Lauer)
• Publish 1.8.28 (John Lauer)
• README + pkg description: lead with a crisp 'Install (skills) vs Download (runtime)' explainer incl. why the two version numbers differ; refresh the stale pkg description to the current model. pkg 1.8.28 (John Lauer)
• Re-push page.json after pkg 1.8.27 (John Lauer)
• Publish 1.8.27 (John Lauer)
• Add pup-adom-wiki user skill (driving/verifying the wiki in pup + the logged-out reality) + README 'Extend pup' third-party breadcrumb section; skill map updated. pkg 1.8.27 (John Lauer)
• Re-push page.json after pkg 1.8.26 (John Lauer)
• Publish 1.8.26 (John Lauer)
• skills: add 'Driving & verifying tricky pages' — shadow-DOM piercing survey, scroll-the-element (not window) for nested scroll containers, count-in-DOM-then-confirm; + pointer from the main skill's key rules. From the adom-desktop download-card audit. pkg 1.8.26 (John Lauer)
• Re-push page.json after pkg 1.8.25 (John Lauer)
• Publish 1.8.25 (John Lauer)
• README: add a full Recording section — example GIF preview, the two recorders (CDP screencast VP9 vs MediaRecorder), and a WebM/MP4/GIF format comparison with real sizes, pros/cons, and verified ffmpeg convert commands (incl. the H.264 even-dimension gotcha); pkg 1.8.25 (John Lauer)
• Add example recording assets (native VP9 WebM + H.264 MP4 + GIF preview) for the README recording section (John Lauer)
• v1.8.20: lazy ffmpeg re-detection on record_start (install-then-record, no restart) (John Lauer)
• v1.8.19: fix browser_open_tab hang — tolerant title-suffix injector (prefix match) + drop the redundant per-tab observer that dueled it (John Lauer)
• v1.8.18: fix browser_open_tab CDP-pipe deadlock on Edge (opener() check before target.page() in popup-tracker) + newPage timeout guard (John Lauer)
• Re-push page.json after pkg 1.8.24 (John Lauer)
• Publish 1.8.24 (John Lauer)
• Re-push page.json after pkg 1.8.23 (John Lauer)
• Delete skills/pup-bridge-publish/SKILL.md (John Lauer)
• Delete skills/pup-bridge-dev/SKILL.md (John Lauer)
• SDK correction (maintainer-provided): pkg ships ONLY the pup user skill; dev/publish skills are source-only in dev-skills/ + publish-skills/ (not in files[], no user-invocable scoping); skillpack package.json declares dependencies:{adom/adom-desktop:^1.9.63} to pull the AD CLI + core skills; docs corrected (John Lauer)
• Publish 1.8.23 (John Lauer)
• Re-push page.json after pkg 1.8.22 (John Lauer)
• Delete publish-skills/pup-bridge-publish/SKILL.md (John Lauer)
• Delete dev-skills/pup-bridge-dev/SKILL.md (John Lauer)
• SDK re-audit: pup is open source, so ship dev/publish skills in skills// scoped user-invocable:false (dev-skills/*.md is dead per the Bridge SDK checklist); skillpack package.json dependencies emptied to {}; docs corrected (John Lauer)
• Publish 1.8.22 (John Lauer)
• maintainer docs: correct the skill-layout convention — dev/publish skills belong in dev-skills/ + publish-skills/ (auto-excluded from the pkg tarball), NOT skills/ (which ships them as user skills). Fixes the backwards 'skillpack way superseded source-only' framing that caused the 28KB tarball (John Lauer)
• Delete skills/pup-bridge-publish/SKILL.md (John Lauer)
• Delete skills/pup-bridge-dev/SKILL.md (John Lauer)
• Re-push page.json after pkg 1.8.21 (John Lauer)
• pkg leanness: move maintainer skills to dev-skills/ + publish-skills/ (auto-excluded from tarball); install.sh installs only the pup user skill; drop them from pkg files[] — user containers no longer get ~37KB of publish/dev recipes (tarball 28K->12K) (John Lauer)
• Publish 1.8.21 (John Lauer)
• Re-push page.json after pkg 1.8.20 (John Lauer)
• Publish 1.8.20 (John Lauer)
• docs: README rewritten for the generic non-profile-browser model (drop stale real-signed-in-browser + CfT-primary claims; background-by-default + ownership); CHANGELOG consolidated 1.6.0->1.8.17; pkg 1.8.20 (John Lauer)
• Re-push page.json after pkg 1.8.19 (John Lauer)
• Publish 1.8.19 (John Lauer)
• v1.8.17: hard background guarantee (sizing decoupled from foreground) + evaluateOnNewDocument title-suffix resilience; pkg 1.8.19 (John Lauer)
• Re-push page.json after pkg 1.8.18 publish (John Lauer)
• Publish 1.8.18 (John Lauer)
• v1.8.16: session ownership — refuse declared cross-thread window steals, reprimand anonymous grabs, expose owner in status; skill teaches owner + task-prefixed sessionIds; pkg 1.8.18 (John Lauer)
• Re-push page.json after pkg 1.8.17 publish (John Lauer)
• Publish 1.8.17 (John Lauer)
• Skills: document the AD 1.9.86 shell-approval flow — gate-hits auto-surface the in-window dialog, request_shell_approval re-summons it, retry the original verb, never shell_auto_approve; pkg 1.8.17 (John Lauer)
• Re-push page.json after pkg 1.8.16 publish (John Lauer)
• Publish 1.8.16 (John Lauer)
• dev skill: add the outbound bridge->AD notify recipe (direct-API, AD 1.9.84 full verb surface, bridge token, cross-AD target, notify-first ordering); pkg 1.8.16 (John Lauer)