Pup - the AI's own browser

@@ -0,0 +1,88 @@+---+name: pup-render-test+description: "DEV skill (source-only) - how to RALPH-TEST whether a BACKGROUND (occluded) pup window actually PAINTED its content, vs sitting BLANK. The trap: a normal screenshot (CDP Page.captureScreenshot, or PrintWindow PW_RENDERFULLCONTENT) FORCES a fresh render, so it shows content even when the live window is blank - it masks the exact bug you are testing for. The ground-truth signal is the Windows DWM taskbar THUMBNAIL (what you see hovering a taskbar icon): DWM generates it from the window's last COMPOSITED surface without forcing a render, so a blank thumbnail means the window never painted. Read this before claiming a background window renders, before touching the occlusion/focus-emulation/park code, or when a user reports 'pup windows are blank'. Trigger words: blank pup window, window not rendering, background window blank, did it paint, taskbar thumbnail, DWM thumbnail, requestAnimationFrame not firing, visibilityState hidden, occluded window blank, setFocusEmulationEnabled, one rAF, render test, ralph render, prove it rendered."+---++# Ralph-testing background-window rendering (blank vs painted)++John's method, made automatable: **hover a pup window's taskbar icon; Windows shows a thumbnail+preview. Blank preview = the window never rendered. Content in the preview = it rendered.** That+thumbnail is the ground truth, and this skill captures it programmatically so you can prove it in a+test instead of by eye.++## Why a normal screenshot LIES here (the trap)++The whole failure mode is: a window born off-screen and parked occluded reports+`visibilityState: 'hidden'`, `requestAnimationFrame` is paused, and the compositor never produces a+frame - so the window is **blank** even though its DOM is fully loaded. But the usual ways to look+at a window all **force a render**, which hides exactly that:++- **CDP `Page.captureScreenshot`** (what `pup_screenshot` uses) forces the renderer to produce a+  frame for the capture. Always shows content. Useless for this test.+- **`PrintWindow` with `PW_RENDERFULLCONTENT`** (flag 2, what most window-grab tools use for Chrome)+  also forces a full render. Same problem.++So "I screenshotted it and saw the page" does NOT prove the live window rendered. It proves the+capture forced a render.++## The ground truth: the DWM thumbnail++The DWM taskbar thumbnail is composited by the Desktop Window Manager from the window's **last+already-composited surface** - it does NOT ask the window to render. If the window never painted,+the thumbnail is empty. `tools/ralph-render-test.ps1` reproduces this:++1. Create a tiny top-left host form.+2. `DwmRegisterThumbnail(host, sourceWindow)` + `DwmUpdateThumbnailProperties` to draw the source's+   thumbnail into the host.+3. `Graphics.CopyFromScreen` the host region (captures what DWM actually drew).+4. Count distinct sampled colors: **`>= 12` = RENDERED**, fewer = **BLANK**. A magenta-bleed result+   (the host's own backcolor showing through) = **THUMBNAIL_EMPTY** (no composited surface at all).++Measured baseline (2026-08-22): DigiKey 14, TI 13 (rendered); a blank/empty window ~9.++## How to run it++```bash+# 1. resolve the pup windows' hwnds by their property tags (see dev-skills/pup-no-wiggle):+#    enumerate Chrome_WidgetWin_1 windows, GetProp each for "AdomPupSid=<sid>".+# 2. run the render test on those hwnds (on the desktop, via ab shell_execute or directly):+powershell -NoProfile -ExecutionPolicy Bypass -File tools/ralph-render-test.ps1 -Hwnds "5380294,2824624,12061336"+# -> 2824624 -> RENDERED(distinct=14)+#    12061336 -> RENDERED(distinct=13)+#    5380294  -> BLANK(distinct=9)+```++The test briefly flashes a small 280x200 host window at the top-left corner (~0.5s per window) - that+is the thumbnail host, expected. It never touches or foregrounds the window under test.++## ALWAYS pair with a DOM check, or you will misread it++A BLANK thumbnail has TWO very different causes; disambiguate with `pup_eval`+`document.body.innerText.length`:++| thumbnail | DOM bodyLen | meaning |+|---|---|---|+| RENDERED | any | window painted - the render path is healthy |+| BLANK | **> 0** | **RENDER BUG**: content exists but never painted - this is what the fix addresses |+| BLANK | **0** | empty page (bot-wall / 403 / 404 / still loading) - NOT a render bug; see `pup-bot-walls` |++The Mouser case on 2026-08-22 was exactly the second row: `BLANK` thumbnail but `bodyLen == 0`+because Mouser served a 403 bot-wall - a blank *page*, not a blank *paint*. Do not "fix" rendering+for that; it is a sourcing/bot-wall problem.++## The fix this verifies (so nobody regresses it)++`createPageInNewWindow` pulses `Emulation.setFocusEmulationEnabled` ON for two animation frames at+birth, then OFF (v2.0.280 -> made a one-shot in 2.0.281). This is John's "one rAF to get a rendering+to occur": the occluded window composites a single frame (Chrome retains the last frame for an+occluded window, so it stays painted), then returns to throttled/idle. Do **NOT** leave focus+emulation ON, and do **NOT** reach for the highFps anti-throttle LAUNCH flags to solve blankness -+both keep the page rendering continuously and reintroduce the issue-#14 battery drain. The whole+point is: paint once, then idle. Re-run this render test after any change to the birth/park/occlusion+path and confirm a freshly-opened background vendor page still scores RENDERED.++## Known limitation / TODO++- The birth pulse fixes NEW windows. A window brought back by crash/sleep RECOVERY does not go+  through `createPageInNewWindow`, so it can still come back blank - apply the same one-shot pulse on+  the recovery/re-attach path, then verify with this test.