app
Pup - the AI's own browser
Public Made by Adomby adom
pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you: windows that never jump in front of your work, one shared profile that learns your logins, and every window labeled on the taskbar with its AI thread's name.
← Commit history
Dev skill: placement doctrine — CDP plain bounds only, z-order verified with revert-off-screen; CDP maximize and AD set_window_bounds documented as raising dead ends
1 file changed
+23−5
dev-skills/pup-bridge-dev/SKILL.md+23−5@@ -270,11 +270,16 @@ tiny Win32 call, no PS window-hunting, no timers, no loops.** Lives in `tryDetac invisible off-screen — the self-heal (reattach / open_tab / switch_tab / any status query) retries it. An un-bottomed window moved on-screen lands ON TOP of the user's work (the nxp.com pop, v1.8.59).- - **Geometry via CDP `Browser.setWindowBounds`** addressed by windowId — parking the WRONG- window is structurally impossible (the PS EnumWindows/pid-hunt version parked a phantom under- parallel opens and the window stayed invisible off-screen). Sequence: `normal` → move to- primary monitor → **`windowState:'maximized'`** (OS-true full size; never compute pixels from- `screen.availWidth` — the probe can fail mid-navigation and ships undersized windows).+ - **Geometry via CDP plain bounds ONLY** (`Browser.setWindowBounds {left,top,width,height}`,+ normal state), addressed by windowId — parking the WRONG window is structurally impossible.+ Size comes from the page's own `screen.availWidth/Height` WITH RETRIES (a single probe can+ fail mid-navigation; retry, don't fall back). NEVER `windowState:'maximized'` and NEVER AD+ `desktop_set_window_bounds` — BOTH RAISE the window (see dead ends).+ - **TRUST NOTHING — verify the Z-ORDER after placement** (v1.8.66): re-bottom after the move,+ then confirm via AD `desktop_list_windows` that pup's hwnd is NOT topmost and sits below at+ least one non-pup window. Unconfirmable after a retry → move the window BACK OFF-SCREEN and+ report `park-failed`. A window that might be covering the user never stays on-screen. This+ check is what caught ten versions of placement bugs the focus-based checks all missed. - **Self-verify POSITION** via CDP `getWindowBounds` (left/top > -5000), NOT focus — a focus-only verify passed while the window sat off-screen ("backgrounded" lie). - **The launch-gap contract:** a user who clicks the taskbar button within the ~2s before the@@ -372,6 +377,19 @@ must clear it first. — the #1 forbidden behavior. REMOVED in 1.8.60: the launch park bottoms unconditionally; a user who clicked during the ~2s gap clicks once more and it sticks. GetForegroundWindow remains valid AFTER startup (the late re-park paths), where a destroyed-foreground handoff can't target the window.+- **CDP `windowState:'maximized'` for background placement** → Chromium implements it as+ ShowWindow(SW_MAXIMIZE), which RAISES the window to the TOP of the z-order without stealing+ focus — so every focus-based check passes while pup windows sit stacked ON TOP of the user's+ work (latent 1.8.55→64; John caught five at z=0-4 under his editor). The "small-then-grow" and+ the nxp.com "pop" sightings were this raise. Full-size = CDP plain bounds sized from+ `screen.availWidth/Height`, never the maximize state.+- **AD `desktop_set_window_bounds` for background placement** → ALSO raises the window (even with+ `restore:false`), AND `desktop_list_monitors` reports LOGICAL px while set_window_bounds takes+ PHYSICAL px (windows came out on top and undersized, 1.8.65). If AD ever ships a documented+ no-raise bounds verb, re-evaluate; until then geometry is CDP-only.+- **Trusting ANY placement primitive without a z-order check** → three different placements raised+ the window and every one shipped because verification only checked focus and position. The+ z-verify + revert-off-screen (v1.8.66) is not optional. - **PS window-hunting (EnumWindows / `MainWindowHandle` / pid+CIM child walks) to find the window** → heavy (~1-2s process+compile per park = the whole "first 2 seconds" gap) AND mis-resolved under parallel opens (parked the wrong/phantom window; the real one stayed invisible off-screen while the