Pup - the AI's own browser

@@ -1,5 +1,43 @@ # Changelog — Adom Desktop Puppeteer Bridge +## 1.9.74 — 2026-07-23 — macOS parity: the whole OS-presentation layer, mac-native++Until now pup on macOS ran "headless-in-spirit": every CDP verb worked, but the OS layer+(background-by-default, lower/raise, alert) silently no-op'd (`applied:false`) because it was all+Win32/PowerShell. Verified live on a Mac (AD 1.9.167, feat/macos-parity):++1. BACKGROUND-BY-DEFAULT, THE MAC WAY. AppKit clamps windows onto a visible screen, so the+   Windows off-screen-launch trick can't work. Instead the detached launch now runs on darwin+   too (`--no-startup-window` + spawn detached), and the bridge HIDES the browser process+   (the Cmd+H state, via System Events) BEFORE its first window is created — windows born+   into a hidden app are born invisible. The park then sizes the window full-screen via CDP+   (while hidden, so a later raise looks right) and re-asserts the hide. Cross-origin+   navigation cannot unhide it. Screenshots/eval/recording all work on the hidden window+   (--disable-backgrounding-occluded-windows). One session = one process, so hide is+   per-session; shared-profile window groups hide together (documented DEGRADED vs per-hwnd).+2. LOWER / RAISE. browser_lower_os_window = hide (applied:true, verified via System Events);+   browser_raise_os_window / focus (foregroundReason gate unchanged) = unhide + activate by+   pid. The wiki-toggle raise path (osRaiseSessionWindow) gained the same branch.+3. ALERT. macOS has no taskbar flash and no API to bounce another app's Dock tile. The mac+   nudge: un-hide the window at its z-position (visible, NOT focused) + an AD native toast+   whose click focuses the window (notify_user focus:{titleContains}); {stop:true} dismisses+   the toast (notify_dismiss).+4. CHROME INSTALL. browser_use {browser:'chrome',install:true} now works on mac: official+   universal dmg → hdiutil attach → ditto to /Applications (falls to ~/Applications when not+   writable). No UAC machinery needed. ~/Applications is also probed by detection now.+5. PROCESS SCANS. The POSIX ps-scan filters were case-sensitive on 'chrome' — mac system+   Chrome ("…/MacOS/Google Chrome") never matched, so rescan/recovery missed it. Now /chrome|+   msedge|Microsoft Edge/i.+6. RECORDING. ffmpeg detection probes Homebrew/MacPorts paths (/opt/homebrew/bin,+   /usr/local/bin, /opt/local/bin — AD spawns bridges outside a login shell, so PATH lacks+   them), and the not-found hint says `brew install ffmpeg` on mac instead of winget. Verified:+   tab-record of a HIDDEN window produces a playable webm.+7. CfT PREWARM on branded-browser fallback now kicks on darwin too.++Windows behavior is unchanged: every new branch is `process.platform === 'darwin'`-gated, and+the AUMID/jump-list/overlay/tooltip identity stack stays Windows-only by design (no Dock+equivalent; the window title's "(session: <id>)" suffix is the mac identity).+ ## 1.9.43 — 2026-07-20 — Why some icons had overlays and others did not, plus stacked session titles  John: "why do you sometimes have overlays on your icons and sometimes not?" It was never a rule, it

@@ -29,7 +29,8 @@ does NOT attach to the user's running browser and does NOT run headless. It:    below.) 3. **Renders a REAL window, but keeps it in the BACKGROUND.** It is *not* headless — a real GPU-composited    window, so `browser_screenshot` / recording are true-to-life and canvas/WebGL/media render correctly.-   But pup immediately z-orders it to the **bottom** (Win32 `SetWindowPos` with `SWP_NOACTIVATE`), so it+   But pup immediately z-orders it to the **bottom** (Windows: Win32 `SetWindowPos` with+   `SWP_NOACTIVATE`; macOS: the browser process is **hidden**, the Cmd+H state — same contract), so it    renders **without stealing focus and without covering the user's active window**. You drive and    screenshot it fully while it stays hidden. `foreground:true` is the ONLY thing that shows it. 4. **Spawn-verifies + falls through.** The pick order is **Chrome → Edge → cached Chrome for Testing**; pup@@ -81,6 +82,22 @@ adom-desktop browser_screenshot  '{"sessionId":"mytask-web"}' - **On a fresh PC it's usually a non-event** — pup drives the installed Chrome/Edge with no download. The   rare "no browser at all" / Node-provisioning / disk cases are all in `pup-browsers-and-chrome`. +## macOS differences (v1.9.74+) — same verbs, mac-native mechanics++Every `browser_*` verb works on macOS; only the OS-presentation layer differs:++- **Background = hidden app.** A background open launches the session's browser process hidden+  (the Cmd+H state) — truly invisible, still fully drivable/screenshottable/recordable.+  `browser_lower_os_window` re-hides; `browser_raise_os_window` (with `foregroundReason`)+  unhides + activates. One session = one browser process, so a shared-profile window group+  hides/shows together.+- **`browser_alert_window` = un-hide (not focused) + a native toast** whose click focuses the+  window — macOS has no taskbar to flash. `{stop:true}` dismisses the toast.+- **No taskbar identity on mac** — the per-window icons/badges/jump-lists below are+  Windows-only; on mac the window title's `(session: <id>)` suffix is the identity.+- **Recording** needs ffmpeg (`brew install ffmpeg` — the error hint says so; re-detects+  without a restart).+ ## Taskbar preference — the USER can ask for "combined mode"  pup windows each get their own taskbar button by default ("split": one button per window, badged

@@ -1,10 +1,10 @@ {   "manifest_version": 1,   "name": "puppeteer",-  "version": "1.9.73",-  "url": "https://wiki.adom.inc/download/adom/adom-desktop-puppeteer-bridge/1.9.73/adom-bridge-puppeteer-v1.9.73.zip",-  "sha256": "599c867cc6738caf228089e64f3b32359d6325629674feef39c95db85e80cd20",-  "size": 308819,+  "version": "1.9.74",+  "url": "https://wiki.adom.inc/download/adom/adom-desktop-puppeteer-bridge/1.9.74/adom-bridge-puppeteer-v1.9.74.zip",+  "sha256": "0f434106907515788dbf180ee81e8151e2f316234241ad107205d3bdd9ede1c1",+  "size": 267309,   "verbPrefixes": [     "browser_",     "desktop_recorder_",@@ -12,5 +12,5 @@   ],   "healthEndpoint": "/status",   "statusVerb": "browser_readiness",-  "released_at": "2026-07-20T15:30:00Z"+  "released_at": "2026-07-23T16:55:27Z" }\ No newline at end of file

@@ -1 +1 @@-1.9.73+1.9.74\ No newline at end of file

@@ -2,8 +2,8 @@   "manifest_version": 1,   "name": "puppeteer",   "displayName": "Puppeteer (Chrome for Testing + Native)",-  "version": "1.9.73",-  "description": "Drives a browser ALREADY on the machine \u2014 installed Chrome, else Microsoft Edge (every Windows PC ships with Edge) \u2014 launched with a FRESH isolated profile, so the common case has NO ~150 MB Chrome-for-Testing download and it never touches the user's real tabs/logins. Binds its local server to LOOPBACK (127.0.0.1) only, so no Windows Firewall 'allow Node through the firewall' prompt ever pops. Chrome for Testing is fetched only as a LAST RESORT if the machine has no Chromium browser at all. SPAWN-VERIFIED fallback: pup tries each detected browser (Chrome \u2192 Edge \u2192 CfT) and actually launches it, falling through to the next if one won't start (and handling browsers like Edge that relaunch onto another PID), so a corrupt/partial install never hard-fails an open. The browser that launches is cached as the default (persisted across restarts) so it isn't re-probed each time. On spawn the bridge SELF-WARMS: detects browsers + disk, and only if the box has no Chrome/Edge and no cached CfT does it background-fetch CfT so the first open is instant. browser_use pins a specific browser (chrome | edge | cft | auto); {browser:'chrome',install:true} downloads & installs REAL Google Chrome (user-scoped, no admin) on an Edge-only box. browser_readiness (READ-ONLY) reports which browser will be used + the full candidate list + the default + free disk. Every failure returns a specific errorCode + _hint (chrome_install_no_disk, chrome_download_network, chrome_install_permission, chrome_stable_not_detected, \u2026). Launches with FULL browser permissions by default for full debug (strictPermissions:true opts out). Headful automation: open/close windows+tabs, navigate, screenshot, eval JS, record. pup is a GENERIC, non-profile browser only \u2014 every session is a fresh isolated Chrome/Edge process, never the user's real signed-in browser; profile defaults to sessionId. To drive the user's REAL Chrome/Edge (their profile, cookies, SSO), use the Adom browser EXTENSION's nbrowser_* verbs \u2014 a separate bridge, not pup's job.",+  "version": "1.9.74",+  "description": "Drives a browser ALREADY on the machine — installed Chrome, else Microsoft Edge (every Windows PC ships with Edge) — launched with a FRESH isolated profile, so the common case has NO ~150 MB Chrome-for-Testing download and it never touches the user's real tabs/logins. Binds its local server to LOOPBACK (127.0.0.1) only, so no Windows Firewall 'allow Node through the firewall' prompt ever pops. Chrome for Testing is fetched only as a LAST RESORT if the machine has no Chromium browser at all. SPAWN-VERIFIED fallback: pup tries each detected browser (Chrome → Edge → CfT) and actually launches it, falling through to the next if one won't start (and handling browsers like Edge that relaunch onto another PID), so a corrupt/partial install never hard-fails an open. The browser that launches is cached as the default (persisted across restarts) so it isn't re-probed each time. On spawn the bridge SELF-WARMS: detects browsers + disk, and only if the box has no Chrome/Edge and no cached CfT does it background-fetch CfT so the first open is instant. browser_use pins a specific browser (chrome | edge | cft | auto); {browser:'chrome',install:true} downloads & installs REAL Google Chrome (user-scoped, no admin) on an Edge-only box. browser_readiness (READ-ONLY) reports which browser will be used + the full candidate list + the default + free disk. Every failure returns a specific errorCode + _hint (chrome_install_no_disk, chrome_download_network, chrome_install_permission, chrome_stable_not_detected, …). Launches with FULL browser permissions by default for full debug (strictPermissions:true opts out). Headful automation: open/close windows+tabs, navigate, screenshot, eval JS, record. pup is a GENERIC, non-profile browser only — every session is a fresh isolated Chrome/Edge process, never the user's real signed-in browser; profile defaults to sessionId. To drive the user's REAL Chrome/Edge (their profile, cookies, SSO), use the Adom browser EXTENSION's nbrowser_* verbs — a separate bridge, not pup's job. macOS (v1.9.74+): full parity with mac-native mechanics — background-by-default is the app-level hide (windows stay drivable/screenshottable while hidden), raise/lower map to unhide+activate/hide, browser_alert_window posts a native toast whose click focuses the window, browser_use {browser:'chrome',install:true} installs Chrome from the official dmg, and taskbar identity/badging remains Windows-only.",   "homepage": "https://wiki.adom.inc/adom/adom-desktop",   "author": "Adom Inc.",   "license": "MIT",@@ -74,13 +74,13 @@   "updateManifestUrl": "https://wiki.adom.inc/api/v1/pages/adom-desktop-puppeteer-bridge/files/adom-bridge-puppeteer-manifest.json",   "dependencies": {     "node": ">=20",-    "browser": "Chromium-family \u2014 installed Chrome or Edge (every Windows box ships Edge); if neither exists, Chrome for Testing is auto-fetched as a last resort. No hard Chrome requirement."+    "browser": "Chromium-family — installed Chrome or Edge (every Windows box ships Edge); if neither exists, Chrome for Testing is auto-fetched as a last resort. No hard Chrome requirement."   },   "runtime": {     "kind": "node",     "version": ">=20",     "preferred": "22",-    "_note": "AD-managed shared-runtime declaration (see PROPOSAL-shared-runtimes.md). Bridges DECLARE their runtime; AD provisions a portable interpreter from its shared adom-runtimes cache and spawns by absolute path \u2014 no UAC, no PATH reliance. Additive: older AD ignores this and uses `dependencies` / bare `node` on PATH."+    "_note": "AD-managed shared-runtime declaration (see PROPOSAL-shared-runtimes.md). Bridges DECLARE their runtime; AD provisions a portable interpreter from its shared adom-runtimes cache and spawns by absolute path — no UAC, no PATH reliance. Additive: older AD ignores this and uses `dependencies` / bare `node` on PATH."   },   "category": "Browser Automation",   "tags": [@@ -96,11 +96,11 @@     },     "macos": {       "supported": false,-      "reason": "macOS port pending \u2014 puppeteer-core is cross-platform but the bridge's spawn config uses Windows-only killImageName 'node.exe' and Chrome for Testing path resolution hasn't been tested."+      "reason": "macOS port pending — puppeteer-core is cross-platform but the bridge's spawn config uses Windows-only killImageName 'node.exe' and Chrome for Testing path resolution hasn't been tested."     },     "linux": {       "supported": false,-      "reason": "Linux port pending \u2014 same killImageName + Chrome resolution issues as macOS."+      "reason": "Linux port pending — same killImageName + Chrome resolution issues as macOS."     }   },   "prewarm": {

@@ -129,7 +129,9 @@ function listSystemBrowsers() {   const posix = [     ['chrome', '/usr/bin/google-chrome'], ['chrome', '/usr/bin/chromium'], ['chrome', '/usr/bin/chromium-browser'],     ['chrome', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'],+    ['chrome', path.join(os.homedir(), 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome')],     ['edge',   '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],+    ['edge',   path.join(os.homedir(), 'Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge')],   ];   const out = [];   const seen = new Set();@@ -247,7 +249,9 @@ function setDefaultBrowser({ browser, executablePath, install, elevate } = {}) {       installChromeStable({ elevate }); // background; browser_use polling + readiness track it       return {         ok: true, installing: true, installingChrome: true,-        _hint: "Installing Google Chrome in the background. On a normal PC this is silent with NO prompt. On a locked-down box (a VM, managed device) it needs a Windows approval — the bridge will pop a native notification asking the user to click YES on the UAC, and if it expires it re-notifies with a one-tap 'Approve now'. Poll browser_readiness: chromeStablePhase goes installing → awaiting_uac (waiting on the user's click) → ready. pup drives Edge meanwhile, so nothing is blocked.",+        _hint: process.platform === 'darwin'+          ? "Installing Google Chrome in the background (official dmg → Applications; silent, no prompt). Poll browser_readiness: chromeStablePhase goes installing → ready. pup keeps driving its current browser meanwhile, so nothing is blocked."+          : "Installing Google Chrome in the background. On a normal PC this is silent with NO prompt. On a locked-down box (a VM, managed device) it needs a Windows approval — the bridge will pop a native notification asking the user to click YES on the UAC, and if it expires it re-notifies with a one-tap 'Approve now'. Poll browser_readiness: chromeStablePhase goes installing → awaiting_uac (waiting on the user's click) → ready. pup drives Edge meanwhile, so nothing is blocked.",         ...pickSummary(),       };     }@@ -718,9 +722,50 @@ function installChromeStable(opts = {}) {     try {       const pre = listSystemBrowsers().find(x => x.kind === 'chrome');       if (pre) { chromeStableState.phase = 'ready'; chromeStableState.finishedAt = Date.now(); return { ok: true, executablePath: pre.executablePath, alreadyInstalled: true }; }+      // ── macOS ── official universal dmg → mount → copy the .app. User-scoped first+      // (~/Applications needs no rights); /Applications when writable (admin users — the+      // normal Mac case). No UAC/elevation dance exists or is needed here.+      if (process.platform === 'darwin') {+        const dmg = path.join(os.tmpdir(), `chrome_installer_${process.pid}.dmg`);+        console.log(`[chrome] downloading Google Chrome dmg → ${dmg}`);+        await _download('https://dl.google.com/chrome/mac/universal/stable/GGRO/googlechrome.dmg', dmg);+        const { execFileSync } = require('child_process');+        let mountPoint = null;+        try {+          const out = execFileSync('/usr/bin/hdiutil', ['attach', '-nobrowse', '-readonly', '-plist', dmg], { encoding: 'utf8', timeout: 60_000 });+          const m = out.match(/<key>mount-point<\/key>\s*<string>([^<]+)<\/string>/);+          mountPoint = m ? m[1] : null;+          if (!mountPoint) throw new Error('could not resolve the dmg mount point');+          const srcApp = path.join(mountPoint, 'Google Chrome.app');+          if (!fs.existsSync(srcApp)) throw new Error(`no Google Chrome.app inside the dmg at ${mountPoint}`);+          const dests = ['/Applications', path.join(os.homedir(), 'Applications')];+          let installedTo = null, lastErr = null;+          for (const destDir of dests) {+            try {+              fs.mkdirSync(destDir, { recursive: true });+              execFileSync('/usr/bin/ditto', [srcApp, path.join(destDir, 'Google Chrome.app')], { timeout: 120_000 });+              installedTo = path.join(destDir, 'Google Chrome.app');+              break;+            } catch (e) { lastErr = e; }+          }+          if (!installedTo) throw lastErr || new Error('copy failed');+          console.log(`[chrome] Google Chrome installed at ${installedTo}`);+        } finally {+          if (mountPoint) { try { execFileSync('/usr/bin/hdiutil', ['detach', mountPoint, '-quiet'], { timeout: 30_000 }); } catch {} }+          try { fs.unlinkSync(dmg); } catch {}+        }+        const found = listSystemBrowsers().find(x => x.kind === 'chrome');+        if (!found) {+          chromeStableState.phase = 'failed'; chromeStableState.errorCode = 'chrome_stable_not_detected';+          chromeStableState.error = 'Copied Google Chrome.app but it did not detect afterward — check /Applications and ~/Applications.';+          return { ok: false, errorCode: chromeStableState.errorCode, error: chromeStableState.error };+        }+        chromeStableState.phase = 'ready'; chromeStableState.finishedAt = Date.now();+        return { ok: true, executablePath: found.executablePath };+      }       if (process.platform !== 'win32') {         chromeStableState.phase = 'failed'; chromeStableState.errorCode = 'chrome_stable_unsupported_os';-        chromeStableState.error = 'Auto-installing Google Chrome is only wired up for Windows.';+        chromeStableState.error = 'Auto-installing Google Chrome is only wired up for Windows and macOS.';         return { ok: false, errorCode: chromeStableState.errorCode, error: chromeStableState.error };       }       const freeMb = diskFreeMb();