Pup - the AI's own browser

@@ -1,123 +0,0 @@-----name: pup-bridge-dev-user-invocable: false-description: "DEVELOPER skill for building, publishing, and maintaining the Adom Desktop Puppeteer (pup) bridge. NOT needed by general users — they want the `pup` skill. Read this when editing the bridge code, cutting a new version, publishing to the wiki, wiring the cold-start Chrome-for-Testing self-heal, or understanding the pkg-vs-release-vs-bundled artifact model. Trigger words: pup bridge dev, publish pup bridge, build puppeteer bridge, bridge_install pup, adom-desktop-puppeteer-bridge, cold-start self-heal, browser_readiness internals, pup release, pup manifest, ship pup bridge."------# pup-bridge-dev — building & shipping the Puppeteer bridge--The canonical source of truth for the pup bridge is **this wiki repo**-(`wiki.adom.inc/adom/adom-desktop-puppeteer-bridge`), extracted from `adom-desktop/plugins/puppeteer`-on 2026-06-29 to be cloud-owned like the kicad/fusion bridges. Read `CLAUDE.md` (ownership boundary)-and `PUBLISHING.md` (step-by-step recipe) in this repo alongside this skill.--## The THREE artifacts — know which is which (this is the #1 confusion)--A user installs TWO different things from this one page. They are not the same:--| Artifact | What it is | Who installs it | How |-|---|---|---|---|-| **pkg tarball** (Packages tab) | the **container-side Claude skills** (`SKILL.md` + `skills/*`) — docs that teach the cloud AI how to drive pup. **No bridge runtime.** | a cloud **container** | `adom-wiki pkg install adom/adom-desktop-puppeteer-bridge`, or auto via AD's `sync_skills` |-| **release zip** (Releases tab) | the **bridge RUNTIME** (`server.js`, `chrome.js`, `bridge.json`, node deps reconstructed on spawn) — the code that actually drives Chrome on the desktop | **Adom Desktop**, streamed into `bridges-cache\puppeteer` | `bridge_install {manifestUrl}` / `refresh_bridges` (via `updateManifestUrl`) |-| **bundled seed** (inside the AD installer) | a copy of the same runtime, shipped in the NSIS for first-run/offline | every AD install | ships with Adom Desktop; superseded by a newer cache copy (cache-over-bundled, numeric version) |--So: **the pkg is skills (container). The bridge is the zip (desktop) + the bundled seed.** Keep the-pkg description saying exactly that, or people think the tarball contains the bridge — it does not.--## How pup reaches a container — auto-discovery → auto-install → verbs--The full chain when a user on a fresh container says *"open my app in pup"*:--1. **Discovery.** The wiki's `discover` index (fed by this page's `discovery_triggers` — which now lead-   with `pup`, `open in pup`, `open my app in pup`, screenshot/record/tabs) matches the phrase. The-   container's regenerated `adom-wiki-discover` skill surfaces this page, so the AI proposes it.-2. **Auto-install the pkg.** The AI runs `adom-wiki skills install adom/adom-desktop-puppeteer-bridge`-   (a.k.a. `pkg install`). That extracts the tarball and runs `install.sh`, which drops `SKILL.md` +-   `skills/*` into **both `~/.claude/skills/` and `~/.codex/skills/`**. The `pup` skill is now loaded.-3. **The skill calls the bridge.** `pup`'s SKILL.md tells the AI to run `adom-desktop browser_*` verbs.-   AD routes `browser_*` to the puppeteer bridge.-4. **The bridge runtime.** It's already on the desktop: AD ships pup as a **bundled seed** (and supersedes-   it from this page's release zip via `updateManifestUrl` / `bridge_install`). On a truly fresh PC the-   cold-start self-heal (chrome.js) installs Chrome for Testing on first `browser_open_window`.--**Two install paths, keep BOTH healthy:**-- **Discovery path (above)** — works once `discovery_triggers` include the user phrases (done) + the-  discover index is regenerated. This is the "user said pup → AI installs the skill" path.-- **AD `sync_skills` path** — AD's daily `maybe_background_skill_sync` reads `bridge_list` → each bridge's-  `skillPkg` → `pkg install`s it into the container. For pup this requires AD to report-  `skillPkg = adom/adom-desktop-puppeteer-bridge` for the `puppeteer` bridge. **Today AD hardcodes it to-  `null`** (`AD_CORE_SKILL_BRIDGES = ["puppeteer"]` in `bridge_registry.rs`, from when pup's skill lived-  in the AD-core pkg). That must be removed now that the skill ships from this page — it's in the AD handoff.--## Repo layout--- `src/` — the runnable bridge (what the release zip contains, at zip-root). `server.js`, `chrome.js`,-  `credential_vault.js`, `bridge.json`, `BRIDGE_VERSION`, node `package.json`/`package-lock.json`, html/icons.-- `SKILL.md` (root) — the **user** skill (`name: pup`). Deployed to `~/.claude/skills/adom-desktop-puppeteer-bridge/`.-- `skills/pup-bridge-dev/` — THIS dev skill.-- `adom-bridge-puppeteer-manifest.json` (root) — the streaming manifest AD's `updateManifestUrl` points at.-- `package.json` (root) — the **adompkg descriptor** (slug/version/type/description) for `pkg publish`. NOT the node one.-- `install.sh` / `uninstall.sh` — deploy `SKILL.md` + `skills/*` into the container's `~/.claude/skills/`.-- `page.json`, `README.md`, `*.png` heroes — the wiki page presentation (the heroes are gitignored so the-  container pkg stays lean — they're already uploaded as page assets).--## Cold-start self-heal — the architecture (what 1.1.0 added, the reason this repo exists)--On a fresh PC (HD bundles AD; the installer pre-installs neither Node nor Chrome for Testing), the first-`browser_open_window` used to fail with a generic "Failed to launch Chrome after 3 attempts" + a dev-string. Now:--- **`src/chrome.js`** — `detectChrome()` (validates the ACTUAL exe, not "a dir exists"), `installChrome()`-  (programmatic via the bundled `@puppeteer/browsers`, pinned to the buildId puppeteer expects — never-  'stable', or launch() won't find it), an install-state singleton (dedup + progress), `ensureChromeReady()`-  (the gate — background install, returns immediately), `readiness()` (powers the verb + chip).-- **`browser_open_window` gate** (CfT path only; native-drive skips it): missing CfT → kick off a-  non-blocking install + return `{errorCode:"chrome_for_testing_installing", statusVerb:"browser_readiness",-  _hint:"poll then retry"}`. Install fail → `chrome_install_failed`/`chrome_download_failed` (no silent-  continue-to-doomed-launch).-- **`browser_readiness`** (poll) + **`browser_prewarm`** (install without opening a window).-- **`/status`** emits `led`/`summary`/`tooltip` truthfully (yellow installing, red failed, green ready).-- **Node** is handled by AD core BEFORE the bridge spawns (`node_not_found` → `desktop_install_node`) —-  not this bridge's job (the bridge is a node process; it can't run without node).-- **The one thing this bridge can't do:** pre-warm before first use (it isn't running until the first-  call). AD/HD must call `browser_prewarm` on embedded first-run — tracked in `HANDOFF-TO-ADOM-DESKTOP.md`.--## Publishing (the wiki has TWO storage layers — don't mix them)--Full recipe in `PUBLISHING.md`. The load-bearing rules:--1. **The bridge `.zip` → a RELEASE asset** (`adom-wiki release create` + `release upload`). NEVER-   `repo push` a `.zip` — it's gitignored and silently skipped; the manifest URL would 404.-2. **The manifest JSON + source → the git repo** (`adom-wiki repo push`). The manifest's `url` is the-   RELEASE download URL; its `sha256`/`size` MUST match the served asset (releases preserve your sha;-   re-download to confirm or `bridge_install` rejects it).-3. **The skills → a PKG** (`adom-wiki pkg publish`). The pkg description (root `package.json`) must say-   "container-side skills." `pkg pack` honors `.gitignore` for exclusion (no separate npmignore) — that's-   why the heroes are gitignored, to keep the tarball lean. Set per-version notes with `adom-wiki pkg notes`.-4. **Version display gotcha:** a RELEASE shows up in `adom-wiki pkg info` as a row with `type:null` (a-   wiki UI conflation). The real pkg rows have `type:"app"`. Use `release list` for true releases.-5. **`bridge.json` + `BRIDGE_VERSION` lockstep**, and keep the version **>** the AD bundled seed so-   cache-over-bundled wins.--## Testing a new version on a real desktop--```bash-adom-desktop targets    # multiple desktops → --target <name> is required-adom-desktop --target <name> bridge_install '{"manifestUrl":"https://wiki.adom.inc/api/v1/pages/adom-desktop-puppeteer-bridge/files/adom-bridge-puppeteer-manifest.json","force":true}'-adom-desktop --target <name> browser_readiness '{}'   # proves the new code is live-```--- **No Node on the box** → `browser_*` returns `node_not_found` before the bridge spawns (AD core; correct).-  That's a genuine cold-start demo of the FIRST link; it can't exercise `chrome.js` (no node to run it).-- **A box with Node but no Chrome for Testing** is the only place to see the full Chrome self-install live-  (`browser_open_window` → `chrome_for_testing_installing` → poll `browser_readiness` → opens). Most dev-  boxes already have CfT, so `readiness()` just returns `ready:true`.-- The streamed zip is **source-only**; AD runs `npm install` in the cache on first spawn (sharp/keytar-  ship prebuilds). The bundled seed already has node_modules. Don't put node_modules in the zip.--## Don't--- Don't edit `adom-desktop/plugins/puppeteer` as if it's live, and don't `release-bridge.sh puppeteer`-  from the adom-desktop repo — that clobbers this cloud-owned page.-- Don't ship the bridge runtime in the pkg tarball or the skills in the release zip. Two artifacts, two homes.-- Don't install 'stable' Chrome — pin to puppeteer's expected buildId (`chrome.js` does this).