← 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

John Lauer ·d68db2a8f2 · ·parent b9fbf94
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