Pup - the AI's own browser

@@ -3,10 +3,9 @@ Drive a browser on the user's desktop from the cloud: open/close windows + tabs, navigate, screenshot, eval JS, record windows. pup is a **generic, non-profile browser** — every session is a **fresh, isolated Chrome/Edge process**, never the user's real signed-in browser. It drives the browser **already on the-machine** (installed Chrome, else Microsoft Edge). On **Windows** every PC ships Edge, so the common case-needs **no download**; on **macOS** neither is guaranteed (Edge isn't preinstalled, Safari isn't-CDP-drivable), so a Mac without Chrome takes the download path. **Chrome for Testing** is auto-fetched-only as a last resort when the box has no Chromium browser at all. Windows open in the **background by default** so pup never disrupts the user.+machine** (installed Chrome, else Microsoft Edge — every Windows PC ships Edge), so the common case needs+**no download**; **Chrome for Testing** is auto-fetched only as a last resort when the box has no+Chromium browser at all. Windows open in the **background by default** so pup never disrupts the user.  > To drive the user's **real, signed-in** Chrome/Edge (their cookies, SSO, saved logins), that's the > **Adom browser extension's `nbrowser_*` verbs** — a separate bridge, not pup.@@ -53,13 +52,6 @@ Full everyday usage (tabs, recording, window ownership, cold-start playbook) is  ## Window-type taskbar icons: read a pup window at a glance -> **Windows only.** This section and the taskbar/overlay/jump-list sections below describe **Windows-> taskbar** behaviour. macOS has no taskbar, no per-window tile, no overlay badges and no jump-> lists, so none of it applies there — a pup window on a Mac appears as an ordinary browser window-> and its identity comes from the launched bundle. The one signal that IS cross-platform is the-> **tab title** (solid dot = signed in, hollow dot = public). `browser_configure`'s-> `taskbarGrouping` / `agentActivity` are stored on macOS but inert; the verb says so in its reply.- ![The pup window-type icon family](docs/icons/family-v1.png)  Every pup window's **taskbar icon states what kind of thing it is showing**. All five share the same@@ -82,11 +74,9 @@ no gradients, no emoji):   window/tab counters instead. - The **tab title** carries the same login signal in text: a solid dot (`●   Logged in`) or hollow dot   (`○   Public`) leads the title of every Adom wiki tab.-- Under the hood **on Windows**, each window's identity (icon, name, Alt-Tab entry) rides a per-session+- Under the hood, each window's identity (icon, name, Alt-Tab entry) rides a per-session Windows   AppUserModelID that **carries the category**: the only way Win11 allows a taskbar tile to change-  live. Grouped mode instead keeps one stable, pinnable `Adom.Pup` identity. **On macOS there is no-  AUMID and no taskbar** — window identity is whatever the launched browser bundle provides, the-  category signal is carried by the tab title above, and `taskbarGrouping` is stored but inert.+  live. Grouped mode instead keeps one stable, pinnable `Adom.Pup` identity.  ### Using pup's icons in your own tool (HD browser picker, launchers, menus) @@ -169,7 +159,7 @@ pup can show any Adom wiki page from **two viewpoints**, and both the AI and the   thread on the machine. First use returns `wikiLoginNeeded:true`; the user signs in once, in that   window. -**Windows only** (macOS has no taskbar or jump list — reopen with `wikiView` instead). **The user can flip a wiki window themselves**: right-click its taskbar button: the jump list+**The user can flip a wiki window themselves**: right-click its taskbar button: the jump list carries **"Adom wiki: switch to logged-in view"** (or "...switch to public view"). Clicking it relaunches that same window under the other cookie jar, brings it to the front, and shows an on-screen caption while it works ("Switching to the logged-in view of the Adom wiki", then@@ -194,6 +184,25 @@ cloud, with no HUD and no need to bring the window forward.  *Above: a GIF preview of a real `browser_record` capture (≈8.6 s, the tab navigating the Adom wiki, recorded in the background on a VM). The native capture is the WebM linked below — this GIF is just an inline preview.* +### High-FPS windows: recording something the user is not looking at++pup windows are backgrounded by design, and Chrome throttles a window that is occluded — so+recording one normally yields a **1-2 fps** video. pup can disable Chrome's power-saving to keep a+window painting at full rate, but a window in that mode can never idle down (three of them once+drained a laptop overnight, wiki issue #14).++So it is **opt-in and leased**:++- **Default** is Chrome's own power behaviour. Normal windows throttle when occluded and cost+  nothing in the background. Right for driving, scraping and screenshots.+- **`browser_open_window {highFps:true}`** renders at full rate while occluded, for background+  recording. It holds a lease (default 20 min), and **an active recording holds that lease open+  indefinitely, so a take is never cut off**. On lapse the window is *downgraded* back to normal+  power by relaunching with its tabs intact, never closed.+- **`browser_highfps_extend {sessionId, minutes}`** negotiates more time up front.++**Full details, defaults, activity signals, and rules of thumb: [RECORDING.md](RECORDING.md).**+ ### Two recorders — pick by what you're capturing  | Verb pair | Captures | How it works under the hood |

@@ -1,8 +1,8 @@ {   "slug": "adom-desktop-puppeteer-bridge",-  "version": "1.9.74",+  "version": "1.9.93",   "type": "app",-  "description": "The pup SKILL PACK — the AI skills that teach a cloud/container AI how to drive the Adom Desktop Puppeteer (pup) bridge (browser_* verbs): the everyday `pup` skill plus focused sub-skills for windows/sessions/tabs, screenshots+recording, browsers+Chrome install, and driving the Adom wiki. Installs into ~/.claude/skills + ~/.codex/skills. DOCS ONLY — this is NOT the bridge runtime. The bridge itself (the Node program that drives the browser) runs on the DESKTOP: Adom Desktop bundles it and auto-installs/updates it, and it's published separately on the Releases tab as adom-bridge-puppeteer-v<ver>.zip. So the pkg version (skills, bumps often) and the Release version (runtime, bumps rarely) differ on purpose. TL;DR: pkg install = the skills for your AI; the bridge = the Release zip, which Adom Desktop manages for you.",+  "description": "The pup SKILL PACK \u2014 the AI skills that teach a cloud/container AI how to drive the Adom Desktop Puppeteer (pup) bridge (browser_* verbs): the everyday `pup` skill plus focused sub-skills for windows/sessions/tabs, screenshots+recording, browsers+Chrome install, and driving the Adom wiki. Installs into ~/.claude/skills + ~/.codex/skills. DOCS ONLY \u2014 this is NOT the bridge runtime. The bridge itself (the Node program that drives the browser) runs on the DESKTOP: Adom Desktop bundles it and auto-installs/updates it, and it's published separately on the Releases tab as adom-bridge-puppeteer-v<ver>.zip. So the pkg version (skills, bumps often) and the Release version (runtime, bumps rarely) differ on purpose. TL;DR: pkg install = the skills for your AI; the bridge = the Release zip, which Adom Desktop manages for you.",   "keywords": [     "pup",     "puppeteer",@@ -37,4 +37,4 @@   "dependencies": {     "adom/adom-desktop": "^1.9.63"   }-}\ No newline at end of file+}

@@ -4,7 +4,7 @@   "slug": "adom-desktop-puppeteer-bridge",   "title": "Adom Desktop - Puppeteer Bridge",   "brief": "The Adom Desktop Puppeteer (pup) bridge — drive a real headful browser on the user's desktop from the cloud: open/screenshot/eval/record. Cold-start drives the browser ALREADY on the machine (installed Chrome, else Microsoft Edge — every Windows PC ships with Edge) with a fresh isolated profile, so the common case needs NO download; Chrome for Testing is fetched only as a last resort. Two artifacts: the Releases zip is the bridge runtime (also bundled in Adom Desktop); the pkg installs the container-side Claude skills.",-  "version": "1.9.74",+  "version": "1.9.93",   "tags": [     "skills",     "pup",

@@ -71,12 +71,6 @@ hydrogen.adom.inc SSO once; the session then persists in the authed profile and (Container-identity auto-login — no interactive step — is still tracked in `adom/wiki` #89; when it lands, this becomes zero-touch.) -> **WINDOWS ONLY — do not offer this on macOS.** The jump-list task lives on a Windows taskbar-> button; macOS has neither, so there is nothing for the user to right-click. On a Mac just reopen-> the window yourself with `wikiView:"authed"` / `"public"` — same result, one verb, no user step.-> Telling a Mac user to right-click a taskbar button sends them looking for a control that does not-> exist, and they cannot tell that from having missed it.- **The user can flip the view themselves (v1.9.3).** Every wiki pup window carries a **taskbar right-click menu** task — "🔓 Switch to logged-in view" on a public window, "📖 Switch to public view" on an authed one. Clicking it relaunches THAT window under the other cookie jar and brings it

@@ -13,10 +13,8 @@ description: "How pup (Puppeteer bridge) picks and launches a browser, and every pup drives the browser **already on the machine** — it does NOT ship or require its own. On every open it builds a candidate list and **spawn-verifies** it: -1. **Chrome → Edge → cached Chrome for Testing** (a pinned default, if set, goes first). On **Windows**-   every PC ships Edge, so there's almost always a candidate with **no download**. On **macOS** neither-   is guaranteed — Edge is not preinstalled and Safari is not CDP-drivable — so a Mac without Chrome goes-   to the download path. Probe with `browser_readiness` rather than assuming a local browser exists.+1. **Chrome → Edge → cached Chrome for Testing** (a pinned default, if set, goes first). Every Windows PC+   ships Edge, so there's almost always a candidate with **no download**. 2. It **launches a fresh process** of that browser binary with an **isolated `--user-data-dir` + a CDP    `--remote-debugging-port`** — a clean empty profile driven over the DevTools Protocol, never the user's    signed-in profile, and a **real rendered window** (not headless).@@ -64,13 +62,7 @@ adom-desktop browser_use '{"browser":"chrome","install":true}'  - Downloads Google's official installer and installs Chrome, then pins it. **On a normal PC this is   silent** (user-scoped, no prompt).-- **macOS installs differently and never prompts for elevation.** pup downloads Google's `.dmg`, mounts it-  with `hdiutil`, `ditto`s `Google Chrome.app` to **`/Applications`**, and falls back to-  **`~/Applications`** if that isn't writable. There is no UAC, no admin prompt, and none of the-  approve-the-elevation flow below — so on a Mac, don't wait for or ask about a consent click. If the copy-  fails at both destinations the install genuinely failed; read the error rather than assuming a prompt is-  pending. The rest of this section (UAC, "click YES", re-notify) is **Windows-only**.-- **On a locked-down Windows box (a VM / managed device) it needs a Windows UAC.** pup escalates automatically and,+- **On a locked-down box (a VM / managed device) it needs a Windows UAC.** pup escalates automatically and,   on **AD ≥ 1.9.84**, fires a native "**click YES to finish installing Chrome**" notification **from the   bridge itself** — on the machine with the prompt **and** pinged to whatever device the user is attending   (cross-AD). If the prompt expires it re-notifies with a one-tap "Approve now". All autonomous — no AI turn

@@ -62,12 +62,8 @@ windows, no focus stolen) and stays fully drivable + screenshottable there — y - **Sizing/positioning does NOT foreground** — `browser_open_window {width,height,x,y}` places the window   at an exact size/spot **for clean screenshot framing** while it stays in the background. So you can frame   a shot without ever disturbing the user's main work.-- **`browser_alert_window`** — a non-intrusive "it's ready/done" nudge; prefer it over raising the window.-  Use it for an explicit end-of-task "it's ready". **On Windows** it flashes the taskbar button. **On-  macOS** there is no taskbar and no API to bounce another app's Dock tile, so the verb instead unhides-  the window at its z-position (visible, still NOT focused) and posts a native AD toast whose click-  focuses it; `{stop:true}` dismisses the toast. Same contract — a nudge that never steals focus — so-  call it identically on both platforms; just don't tell a Mac user to "look at the flashing icon".+- **`browser_alert_window`** flashes the taskbar (a non-intrusive "it's ready/done" nudge) — prefer it over+  raising the window. Use it for an explicit end-of-task "it's ready". - `browser_raise_os_window` / `browser_focus_window` bring a window forward — **GATED the same way:   REFUSED (`foreground_reason_required`) unless you pass `foregroundReason`.** Use only for an   explicit user show-me; `browser_lower_os_window` tucks it back after. **Raise steals focus and can@@ -102,10 +98,6 @@ adom-desktop browser_open_window '{"sessionId":"demo-web","owner":"demo","url":"  ## Taskbar look — split vs grouped (user preference, `browser_configure`) -> **WINDOWS ONLY.** macOS has no taskbar, so this preference has no visible effect there —-> `browser_configure` still stores it (and says so in its reply, with `taskbarSupported:false`), but-> nothing changes on screen. Don't offer it to a Mac user as a way to tidy their windows.- Each pup window wears the Adom Pup icon; how they arrange on the taskbar is the USER's choice:  - **`split` (default):** one taskbar button PER WINDOW, each badged with its own tab count