← Commit history

Document the jump-list first-right-click blip: .plain AUMID churn created a listless button Explorer resolved first, plus orphaned CustomDestinations cleanup

John Lauer ·99a014b441 · ·parent 23a60c2
1 file changed +35
dev-skills/pup-bridge-debug/SKILL.md+35
@@ -368,3 +368,38 @@ Verifying a jump list is committed: read `%APPDATA%\Microsoft\Windows\Recent\Cus (binary). The task's DESCRIPTION and its `... adom-desktop-cli.exe <verb> "{}"` args are stored as plaintext UTF-16 and greppable; the TITLE is a PKEY_Title property-store blob, so a plain string search for the title MISSES it — search the description or the args instead.++## Symptom: pup jump list "blips out" on the first right-click, works on the second++Only pup's jump list did this; other apps' were fine. Root cause was AUMID CHURN from the+category-carrying appId design (`Adom.Pup.<sid>.<cat>.<gen>`):++- A freshly opened window sits on about:blank for a beat, so `pupCategory` was null and the stamp+  used `.plain`. That REGISTERED an `Adom.Pup.<sid>.plain.<gen>` AUMID — a full taskbar identity+  with NO jump list — and created a taskbar button under it. A moment later the URL resolved and the+  window was re-stamped under `.<category>`, creating ANOTHER button/association.+- Windows caches the button→AUMID→jumplist association per button. On the first right-click Explorer+  resolved the stale `.plain` association (no list) → the menu blipped shut. The second right-click+  re-resolved to the current `.category` AUMID (which has the list) → it showed.+- Every category flip also minted a new AUMID and orphaned the old one's jump-list file. Measured:+  **87 CustomDestinations files for 3 live windows.** (Orphans for dead AUMIDs don't break a live+  window's resolve — different hash — but they are junk and muddy diagnosis.)++Fix (v1.9.52):+- **Never stamp a transient `.plain`** while a real URL is still loading (`stampPupIdentity` returns+  a pending sentinel when `pupCategory` is null and a tab holds a non-blank http(s) URL; the retry+  loop + the `framenavigated` recheck re-stamp once the category is known). The button is now created+  ONCE, under its final category AUMID, with its jump list already attached → resolves on first click.+  A genuinely category-less window (never leaves about:blank) still gets `.plain` after ~6 attempts.+- **`brandPupWindow` no longer badges on a pending stamp** when identity IS supported (a false is+  "not yet", not "fall back to the legacy overlay badge").+- **`unregisterPupAumid` clears the AUMID's jump list (`tasks:[]`) before unregistering**, so a+  category flip / window close no longer orphans its CustomDestinations file. Both close paths+  (`browser_close`, `browser_close_window`) already unregister, so both now clear.+- Verify: after opening a window there must be exactly ONE `Adom.Pup.<sid>.*` key (no `.plain`) and+  the pup jump-list file count must equal the window count. `[jumplist] "<sid>" set N task(s) on+  <appId>` logs each commit for diagnosis.++To purge historical orphans on a machine, delete pup-task `*.customDestinations-ms` files (they carry+`browser_close` / `browser_wiki_set_view` in plaintext) older than a few minutes; live windows+re-commit theirs within seconds.