← Commit history
README.md+93−93@@ -1,7 +1,7 @@ # Adom Browser Extension (Chrome + Edge) **Your AI's hands inside your real, signed-in Chrome or Edge.** The native-browser counterpart to-`pup` — the same command surface (`nbrowser_*` mirrors `browser_*`), but every verb runs inside your+`pup` - the same command surface (`nbrowser_*` mirrors `browser_*`), but every verb runs inside your *actual* browser, so your Adom AI assistant can **build, drive, and test web software right alongside you**, in the browser you already work in. @@ -10,120 +10,120 @@ Cloud containers, Hydrogen Desktop, and the AD CLI reach it through the exact sa ## Who we are, and why this extension needs broad browser capabilities -**Adom Industries is an AI electronics-prototyping company** — a full, AI-native development environment for+**Adom Industries is an AI electronics-prototyping company** - a full, AI-native development environment for the entire electronics industry, where developers everywhere build *on top of us*. Our ecosystem and our users are continuously writing and running code: **web-based oscilloscopes, web-based EDA & CAD software, and-applications that drive and control real circuit boards** — all in the browser, all day, every day.+applications that drive and control real circuit boards** - all in the browser, all day, every day. -Because Adom is a complete **"vibe coding"** development environment — an AI assistant and a developer-building software together in real time — the Extension operates the browser the **same way a human developer+Because Adom is a complete **"vibe coding"** development environment - an AI assistant and a developer+building software together in real time - the Extension operates the browser the **same way a human developer does**: open and navigate pages, read and screenshot, fill forms, click, inspect the DOM, run and debug JavaScript, and manage tabs, windows, downloads, and the developer's own signed-in sessions. It is the **same-category of capability as the Claude browser extension** — the AI agent's hands inside your own browser,+category of capability as the Claude browser extension** - the AI agent's hands inside your own browser, acting only on the commands you give it. ## What it does for you -Five real apps from the Adom ecosystem — each shown in a short **demo video**, the AI driving the live app+Five real apps from the Adom ecosystem - each shown in a short **demo video**, the AI driving the live app **in a real, logged-in Chrome window through this extension**, and how it helps you get the work done. Every-clip below was recorded on a genuine browser session — there are no developer-mode warnings and no debugger+clip below was recorded on a genuine browser session - there are no developer-mode warnings and no debugger banners. > **Note (temporary):** each section has a real `<video>` player *and* a placeholder image. This wiki's README-> sanitizer currently strips `<video>` tags, so only the **placeholder frame** shows for now — click any frame to+> sanitizer currently strips `<video>` tags, so only the **placeholder frame** shows for now - click any frame to > watch that clip. Once the wiki allows `<video>` (a one-line sanitizer change), the players render inline and the > placeholders can be removed. -### Chip-fetcher — fill your CAD library while you keep designing+### Chip-fetcher - fill your CAD library while you keep designing <video src="/blob/app/adom-browser-extension/demo/clips/use-case-1-chip-fetcher.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>-<a href="/blob/app/adom-browser-extension/demo/clips/use-case-1-chip-fetcher.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-1-chip-fetcher.png" alt="chip-fetcher demo video — placeholder, click to watch" width="100%"></a>-Sourcing CAD for a BOM is tedious — symbol, footprint, 3D model, and datasheet for every part. Your AI drives+<a href="/blob/app/adom-browser-extension/demo/clips/use-case-1-chip-fetcher.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-1-chip-fetcher.png" alt="chip-fetcher demo video - placeholder, click to watch" width="100%"></a>+Sourcing CAD for a BOM is tedious - symbol, footprint, 3D model, and datasheet for every part. Your AI drives the chip-fetcher dashboard in your browser, working down the parts list and pulling each one's full CAD bundle into your library, so the components are ready to drop into your design instead of you hunting them down one tab at a time. -### Adom Symbol — schematic symbols, generated and previewed live+### Adom Symbol - schematic symbols, generated and previewed live <video src="/blob/app/adom-browser-extension/demo/clips/use-case-2-adom-symbol.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>-<a href="/blob/app/adom-browser-extension/demo/clips/use-case-2-adom-symbol.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-2-adom-symbol.png" alt="Adom Symbol demo video — placeholder, click to watch" width="100%"></a>-You need a schematic symbol for a chip — pins grouped sensibly, the 3D package shown right on the symbol. Your+<a href="/blob/app/adom-browser-extension/demo/clips/use-case-2-adom-symbol.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-2-adom-symbol.png" alt="Adom Symbol demo video - placeholder, click to watch" width="100%"></a>+You need a schematic symbol for a chip - pins grouped sensibly, the 3D package shown right on the symbol. Your AI drives Adom Symbol in the browser, generating the symbol from the datasheet pinout, arranging the pins by-function, and embedding the 3D model — then previews it live so you can eyeball it before it lands in your library.+function, and embedding the 3D model - then previews it live so you can eyeball it before it lands in your library. -### Web-based EDA & CAD — try a design change and see it routed+### Web-based EDA & CAD - try a design change and see it routed <video src="/blob/app/adom-browser-extension/demo/clips/use-case-3-web-eda.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>-<a href="/blob/app/adom-browser-extension/demo/clips/use-case-3-web-eda.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-3-web-eda.png" alt="Web EDA demo video — placeholder, click to watch" width="100%"></a>+<a href="/blob/app/adom-browser-extension/demo/clips/use-case-3-web-eda.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-3-web-eda.png" alt="Web EDA demo video - placeholder, click to watch" width="100%"></a> Mid-design you want to try a change and see it routed. Your AI opens the EDA tool in the browser you're already-signed into, **fills the schematic, re-runs the autorouter, and inspects the nets** — turning "try this and+signed into, **fills the schematic, re-runs the autorouter, and inspects the nets** - turning "try this and tell me what breaks" into something it just does, in the same session where your part libraries already live. -### 3D board CAD — review the layout in the browser+### 3D board CAD - review the layout in the browser <video src="/blob/app/adom-browser-extension/demo/clips/use-case-4-3d-board.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>-<a href="/blob/app/adom-browser-extension/demo/clips/use-case-4-3d-board.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-4-3d-board.png" alt="3D board demo video — placeholder, click to watch" width="100%"></a>+<a href="/blob/app/adom-browser-extension/demo/clips/use-case-4-3d-board.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-4-3d-board.png" alt="3D board demo video - placeholder, click to watch" width="100%"></a> Before a board goes out, you want to look at the actual layout. Your AI opens the 3D board viewer in your-browser, frames the camera, and x-rays the board to reveal the traces underneath — so reviewing a PCB is a+browser, frames the camera, and x-rays the board to reveal the traces underneath - so reviewing a PCB is a conversation, not a context-switch into a separate desktop tool. -### Adom Chipsmith — check a part fits its footprint before it ships+### Adom Chipsmith - check a part fits its footprint before it ships <video src="/blob/app/adom-browser-extension/demo/clips/use-case-5-chipsmith.mp4" controls muted playsinline width="100%" style="border-radius:10px;border:1px solid #30363d;max-width:760px"></video>-<a href="/blob/app/adom-browser-extension/demo/clips/use-case-5-chipsmith.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-5-chipsmith.png" alt="Chipsmith demo video — placeholder, click to watch" width="100%"></a>+<a href="/blob/app/adom-browser-extension/demo/clips/use-case-5-chipsmith.mp4"><img src="/blob/app/adom-browser-extension/demo/clips/poster-5-chipsmith.png" alt="Chipsmith demo video - placeholder, click to watch" width="100%"></a> Before a part goes onto a board, its 3D model and footprint have to actually line up. Your AI drives Adom-Chipsmith in the browser to drop the chip onto its pads and check the fit visually — catching a mis-seated or+Chipsmith in the browser to drop the chip onto its pads and check the fit visually - catching a mis-seated or wrong-variant model before it ever reaches the PCB. ## Every permission, justified A development environment has to operate the browser the way a developer does. Each permission maps to a-concrete action you ask for — to deliver the features above, never to collect data.+concrete action you ask for - to deliver the features above, never to collect data. -### A real example — debugging an authenticated Mouser / DigiKey app+### A real example - debugging an authenticated Mouser / DigiKey app -You're building an app that pulls live pricing and stock from the **Mouser** and **DigiKey** APIs — calls+You're building an app that pulls live pricing and stock from the **Mouser** and **DigiKey** APIs - calls that only succeed from your **signed-in** session. A response comes back empty, so you ask your Adom assistant to debug it, and it does exactly what you'd do in DevTools, in your own logged-in tab: - **`eval`s** `await fetch('/api/digikey/search?mpn=ADS1262IPWR').then(r => r.json())` right in your app's page context and reads back the **real authenticated** response;-- inspects the **console + network** for the failing call — the `401`, the malformed auth header;-- patches the code, re-runs the call, and confirms the parts resolve — without you leaving your seat.+- inspects the **console + network** for the failing call - the `401`, the malformed auth header;+- patches the code, re-runs the call, and confirms the parts resolve - without you leaving your seat. That's the whole reason for `debugger`, `cookies`, and `<all_urls>`: a developer debugging their own web app against authenticated third-party APIs needs **full DevTools-grade access in their real session**. Take it away and this is just a worse screenshot tool. The table below maps every capability to a concrete request. -<img src="/blob/app/adom-browser-extension/screenshots/dev-debug-mouser-digikey.png" alt="The Adom AI assistant debugging an authenticated DigiKey API call inside the developer's own signed-in browser — eval in the page context, reading back the real authed JSON response" width="100%">+<img src="/blob/app/adom-browser-extension/screenshots/dev-debug-mouser-digikey.png" alt="The Adom AI assistant debugging an authenticated DigiKey API call inside the developer's own signed-in browser - eval in the page context, reading back the real authed JSON response" width="100%"> | Permission | What the user-requested feature needs it for | |---|---|-| `debugger` | Drive, inspect, screenshot, and **debug the live page** via the DevTools protocol — exactly what building and testing a web app requires. Attached only while a command runs, detached when idle. |-| `host: <all_urls>` | A dev environment must work on **whatever app you're building or testing** — there's no fixed allow-list for "the whole web." Exercised only per command, never to crawl. |+| `debugger` | Drive, inspect, screenshot, and **debug the live page** via the DevTools protocol - exactly what building and testing a web app requires. Attached only while a command runs, detached when idle. |+| `host: <all_urls>` | A dev environment must work on **whatever app you're building or testing** - there's no fixed allow-list for "the whole web." Exercised only per command, never to crawl. | | `cookies` | Use your **existing signed-in dev tools and services** without forcing a re-login. Used to perform your task, never collected. |-| `nativeMessaging` | The core transport — connects the extension to **your local Adom Desktop** so your AI session can send commands and receive results. |+| `nativeMessaging` | The core transport - connects the extension to **your local Adom Desktop** so your AI session can send commands and receive results. | | `tabs` · `scripting` · `webNavigation` | Open/switch/reload the tabs you operate, read the DOM and fill fields, and run each command at the right moment (e.g. "navigate, then screenshot"). |-| `downloads` | Save files you ask to download — exports, CAD/3D assets, datasheets — into your own profile. |+| `downloads` | Save files you ask to download - exports, CAD/3D assets, datasheets - into your own profile. | | `tabCapture` · `desktopCapture` | Record a walkthrough of **your own page** when you explicitly ask for one. |-| `storage` · `alarms` | Remember your session-to-window map and keep the connection alive — minimal local state only. |+| `storage` · `alarms` | Remember your session-to-window map and keep the connection alive - minimal local state only. | **No remotely-hosted code.** All logic ships in the package; it evaluates JavaScript only on the page you-point it at, via the debugger/scripting APIs — never by loading external scripts.+point it at, via the debugger/scripting APIs - never by loading external scripts. ## You're always in control -- **It acts only on your command** — every action is initiated by you, or by your Adom session working on your behalf.-- **It's visible when it's driving** — Chrome's *"started debugging this browser"* bar appears whenever a+- **It acts only on your command** - every action is initiated by you, or by your Adom session working on your behalf.+- **It's visible when it's driving** - Chrome's *"started debugging this browser"* bar appears whenever a debugger-using command runs; the extension lazy-attaches and idle-detaches after a few seconds, so the bar is only up while it's actually working.-- **Idle by default** — it does nothing unless your Adom Desktop and an Adom session are connected, and you can+- **Idle by default** - it does nothing unless your Adom Desktop and an Adom session are connected, and you can remove it at any time to end all access. ## What's new -- **Drive ALL your browser profiles** (your work + personal Chrome/Edge profiles, …), not just one — `nbrowser_profiles`+- **Drive ALL your browser profiles** (your work + personal Chrome/Edge profiles, …), not just one - `nbrowser_profiles` / `nbrowser_use_profile` switch instantly, with a persistent **security blocklist** to exclude any.-- **Know which of your tools you're signed into** — `nbrowser_credentials` is a *read-only* query over the+- **Know which of your tools you're signed into** - `nbrowser_credentials` is a *read-only* query over the browser's own saved-login store (**Chrome + Edge**); it never stores or exposes passwords.-- **Sign into your tools hands-free** — focus the field → the browser autofills → submit, so the services+- **Sign into your tools hands-free** - focus the field → the browser autofills → submit, so the services and dev tools you already use just work in your real, signed-in session.-- **Window control** — `nbrowser_fullscreen` / `window_state` (fullscreen / maximize / move / tile),+- **Window control** - `nbrowser_fullscreen` / `window_state` (fullscreen / maximize / move / tile), `login_state`, and a robust hover that reveals tooltips on non-interactive elements. ## Fork & develop your own@@ -132,7 +132,7 @@ Third parties are welcome to build their own version. The **[Fork & develop ## Sub-skills -`adompkg install adom-browser-extension` installs this whole skill set — the core driving mechanics+`adompkg install adom-browser-extension` installs this whole skill set - the core driving mechanics plus a growing list of **site recipes** that teach the AI how to drive specific websites. Each links to its full readme. @@ -141,32 +141,32 @@ to its full readme. | Skill | What it covers | |---|---| | [`driving-the-extension`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-the-extension/SKILL.md) | The full `nbrowser_*` surface: the CDP-vs-native "debugging" bar, `isTrusted` input + xy-finding, multi-profile driving, the credential-library query + login automation, the taskbar status feature. |-| [`native-browser-recording`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/native-browser-recording/SKILL.md) | Full-framerate **background** recording of the user's real, logged-in Chrome — the occlusion-flag mode, the restart-into-background-recording flow, and the offer-to-revert-for-battery step (the unique capability). |-| [`driving-the-desktop`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-the-desktop/SKILL.md) | OS-level control via `desktop_*` when CDP can't reach (extension lifecycle, `chrome://` pages, native dialogs, popups) — including the ⛔ never-drive-a-PWA-window guard and the v20 saved-password ban. |-| [`driving-the-extension-demo`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-the-extension-demo/SKILL.md) | A runnable demo playbook — recipes + the recording gotchas (window-capture-vs-CDP white pages, the keep-awake guard). |+| [`native-browser-recording`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/native-browser-recording/SKILL.md) | Full-framerate **background** recording of the user's real, logged-in Chrome - the occlusion-flag mode, the restart-into-background-recording flow, and the offer-to-revert-for-battery step (the unique capability). |+| [`driving-the-desktop`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-the-desktop/SKILL.md) | OS-level control via `desktop_*` when CDP can't reach (extension lifecycle, `chrome://` pages, native dialogs, popups) - including the ⛔ never-drive-a-PWA-window guard and the v20 saved-password ban. |+| [`driving-the-extension-demo`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-the-extension-demo/SKILL.md) | A runnable demo playbook - recipes + the recording gotchas (window-capture-vs-CDP white pages, the keep-awake guard). | | [`cross-platform-dev`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/cross-platform-dev/SKILL.md) | The Windows-first → Kyle-ports-Mac dev flow for the bridge/host/extension. | -**Site recipes** — the extension also supports pluggable per-site playbooks that teach the AI a specific+**Site recipes** - the extension also supports pluggable per-site playbooks that teach the AI a specific app's flow (selectors, multi-step forms, gotchas). The index and the contribution model live in [`driving-sites`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-sites/SKILL.md). ### Contributing a sub-skill -The recipe set is meant to **grow** — anyone can add one, and it stays part of *this* one repo (we don't+The recipe set is meant to **grow** - anyone can add one, and it stays part of *this* one repo (we don't spin up a separate wiki page per bundled skill): -1. Add `skills/driving-<site>/SKILL.md` — copy the template in [`driving-sites`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-sites/SKILL.md).+1. Add `skills/driving-<site>/SKILL.md` - copy the template in [`driving-sites`](https://wiki.adom.inc/adom/adom-browser-extension/files/skills/driving-sites/SKILL.md). 2. Register it in `install.sh`, `uninstall.sh`, `package.json` `files[]`, and the index in `driving-sites`. 3. Open a PR on this page. Prefer to own + version it yourself? Publish your recipe as your **own** wiki page and **breadcrumb it**-back to this page instead (the wiki Family pattern — see `driving-sites`). Either way it's discoverable+back to this page instead (the wiki Family pattern - see `driving-sites`). Either way it's discoverable from here. ## Privacy -The Extension runs inside your own browser and acts only on the commands you — or your Adom AI session,-working on your behalf — give it. The pages and screenshots it reads go to your own Adom session to carry+The Extension runs inside your own browser and acts only on the commands you - or your Adom AI session,+working on your behalf - give it. The pages and screenshots it reads go to your own Adom session to carry out the task you asked for, and it works through your existing signed-in sessions so the tools you already use just work. Saved passwords stay with the browser; its own autofill enters them. Full policy: **[Privacy Policy (Markdown) →](https://wiki.adom.inc/adom/adom-browser-extension/files/PRIVACY.md)** ·@@ -203,12 +203,12 @@ AD ──HTTP /command (ephemeral, discovery file)──► bridge/server.js └─ chrome.tabs/downloads/cookies → native-API verbs ``` -- **bridge/** — AD-spawned Node server. Binds `127.0.0.1:0` (ephemeral, PORTS.md-compliant), writes a+- **bridge/** - AD-spawned Node server. Binds `127.0.0.1:0` (ephemeral, PORTS.md-compliant), writes a discovery file, exposes `/status` + `/command` to AD, and a raw-TCP loopback the host dials.-- **host/** — tiny native-messaging host. Chrome/Edge launch it on+- **host/** - tiny native-messaging host. Chrome/Edge launch it on `connectNative('inc.adom.native_browser')`; it reads the bridge's discovery file and pumps stdio ↔ the bridge loopback. The extension never touches a TCP port.-- **extension/** — the MV3 extension (one codebase, Chrome + Edge). SW stays alive via the host's+- **extension/** - the MV3 extension (one codebase, Chrome + Edge). SW stays alive via the host's ~20s keepalive ping (no offscreen document needed). ## Repo layout@@ -220,29 +220,29 @@ AD ──HTTP /command (ephemeral, discovery file)──► bridge/server.js | `host/` | native-messaging host (`native-host.js`, `.bat`, manifest template) | | `install/` | bridges-cache copy + HKCU host registration + force-install policy | | `skills/` | repo-local skills (incl. the Windows-first → Kyle-ports-Mac dev flow) |-| `wiki/` | `page.json` — this repo's own Adom Wiki page metadata |+| `wiki/` | `page.json` - this repo's own Adom Wiki page metadata | ## What you can do (live) Driving the user's real browser, verified end-to-end: -- **Navigate & manage** windows/tabs — `open_window`, `navigate`, `switch_tab`, … (native `chrome.*`,+- **Navigate & manage** windows/tabs - `open_window`, `navigate`, `switch_tab`, … (native `chrome.*`, **no debugger bar**).-- **`isTrusted` input** that React/SPAs accept — `click`, `double_click`, `right_click`, `hover`,+- **`isTrusted` input** that React/SPAs accept - `click`, `double_click`, `right_click`, `hover`, `type`, `press_key` (via `chrome.debugger`/CDP). **Click by visible text** and the smart finder reads- the element's `getBoundingClientRect` to compute its xy — DOM-truth, not pixel-guessing.-- **The gliding Adom cursor** — `cursor:true` + `intent:"Clicking the Pay button"` shows a teal arrow ++ the element's `getBoundingClientRect` to compute its xy - DOM-truth, not pixel-guessing.+- **The gliding Adom cursor** - `cursor:true` + `intent:"Clicking the Pay button"` shows a teal arrow + pulsing ring that glides to the target while **narrating its intention** (trust-building, mimics HD).-- **Screenshots** — `screenshot {toFile:true}` → pull the PNG (avoids relay base64 timeouts).-- **Authed `fetch_url`** — uses the user's REAL cookies, so it grabs files behind a login.-- **Taskbar status** — `flash`/`taskbar` paint a "come look" flash, a progress bar+- **Screenshots** - `screenshot {toFile:true}` → pull the PNG (avoids relay base64 timeouts).+- **Authed `fetch_url`** - uses the user's REAL cookies, so it grabs files behind a login.+- **Taskbar status** - `flash`/`taskbar` paint a "come look" flash, a progress bar (green/yellow-for-human-gates/red), and an **"Adom is driving" overlay badge** on the real browser's taskbar button (modes: `quiet`/`chatty`/`off`). See [`TASKBAR-FEATURE.md`](TASKBAR-FEATURE.md).-- **Recording** — `record_start {method:"wgc"}` (Windows, via adom-desktop — no picker, background) or+- **Recording** - `record_start {method:"wgc"}` (Windows, via adom-desktop - no picker, background) or `getdisplaymedia` (cross-platform). **The `chrome.debugger` "started debugging this browser" bar** appears only while a CDP verb (input /-screenshot / eval) is active — the bridge lazy-attaches and idle-detaches after ~8s. Native verbs never+screenshot / eval) is active - the bridge lazy-attaches and idle-detaches after ~8s. Native verbs never show it. Full breakdown + the verb-by-verb table: [`skills/driving-the-extension/SKILL.md`](skills/driving-the-extension/SKILL.md). ### Try the handshake locally (dev)@@ -256,7 +256,7 @@ node bridge/server.js # 2. Load extension/ unpacked in Chrome AND Edge (chrome://extensions → Developer mode → Load unpacked) # note the assigned extension ID. -# 3. Register the native host (Windows, per-user, no UAC) — see install/ for the scripted version:+# 3. Register the native host (Windows, per-user, no UAC) - see install/ for the scripted version: # host-manifest.json "path" -> absolute path to host/native-host.bat # host-manifest.json "allowed_origins" -> ["chrome-extension://<ext-id>/"] # HKCU\Software\Google\Chrome\NativeMessagingHosts\inc.adom.native_browser -> manifest path@@ -266,50 +266,50 @@ node bridge/server.js # adom-desktop nbrowser_status -> {ok:true, ext:"adom-browser-extension", browser:"chrome"|"edge"} ``` -## Recording — full-framerate, in the background (the doctrine)+## Recording - full-framerate, in the background (the doctrine) -> **Why this matters — and why we keep relearning it.** Demos must look **amazing**, which means-> **full-resolution, high-framerate (20–60 fps)** capture. That single requirement drives every choice+> **Why this matters - and why we keep relearning it.** Demos must look **amazing**, which means+> **full-resolution, high-framerate (20-60 fps)** capture. That single requirement drives every choice > here. **The enemy is *paint-throttling*, not the codec:** Chrome correctly stops painting occluded / > background / static windows (battery), and capture is event-driven, so a throttled page silently drops to > ~5 fps ("frozen" / sped-up video). Every technique below keeps frames flowing. *(Pup's `browser_record_start`-> CDP screencast is a perfectly good 20–30 fps engine when the page paints — the full cross-surface reference,+> CDP screencast is a perfectly good 20-30 fps engine when the page paints - the full cross-surface reference, > incl. Hydrogen and the foreground-rebump trick, is in the demo-recording skill's `recording-mechanics.md`.)* **Background recording needs TWO things, both required:**-1. **A high-fps engine** — `wgc` (60 fps, Windows, picker-free) or `getdisplaymedia` (the WebRTC/Meet- pipeline, 30–60 fps, cross-platform).-2. **A browser that keeps *painting* the occluded window at full rate** — which requires the background+1. **A high-fps engine** - `wgc` (60 fps, Windows, picker-free) or `getdisplaymedia` (the WebRTC/Meet+ pipeline, 30-60 fps, cross-platform).+2. **A browser that keeps *painting* the occluded window at full rate** - which requires the background launch flags `--disable-features=CalculateNativeWinOcclusion --disable-backgrounding-occluded-windows --disable-renderer-backgrounding --disable-background-timer-throttling`. **Without them Chrome stops- painting an occluded window — which is its *correct, battery-saving default* — and the engine captures+ painting an occluded window - which is its *correct, battery-saving default* - and the engine captures blank/frozen frames.** Those flags are an **exception we want only for the recorded window, only while recording**, then put back. ### The two scenarios-- **Scenario 1 — recording that does NOT need the user's login → use `pup`.** Pup is a browser *we*+- **Scenario 1 - recording that does NOT need the user's login → use `pup`.** Pup is a browser *we* launch, already running with the background flags, so it captures full-framerate in the background out of the box; the user's real Chrome is untouched and they keep working. **Preferred whenever the app doesn't need the user's real session.**-- **Scenario 2 — recording that NEEDS the user's login → native Chrome (this extension).** Only the+- **Scenario 2 - recording that NEEDS the user's login → native Chrome (this extension).** Only the user's real Chrome has their cookies/logins. To record it at full framerate in the background: 1. Check whether native Chrome already runs with the flags. 2. If not → **ASK + WARN the user we must fully restart their Chrome.** Then **fully kill the entire- `chrome.exe` process tree** — native Chrome spawns many helper/background processes (GPU, utility,+ `chrome.exe` process tree** - native Chrome spawns many helper/background processes (GPU, utility, crashpad, the background-mode launcher), so closing the window is NOT enough; the flags don't apply- until *every* `chrome.exe` is gone — wait for full shutdown, and **relaunch with their real profile**+ until *every* `chrome.exe` is gone - wait for full shutdown, and **relaunch with their real profile** (logins survive in the profile dir; tabs return via session-restore) **plus the flags**. 3. Record the native window at full framerate **in the background** (`wgc`, or `getdisplaymedia` + `--auto-select-desktop-capture-source`) while they keep working.- 4. **Later, OFFER TO REVERT:** *"Chrome is in full-background recording mode, which uses more battery —+ 4. **Later, OFFER TO REVERT:** *"Chrome is in full-background recording mode, which uses more battery - want us to put you back to normal?"* → if yes, fully restart Chrome again **without** the flags. Best of all worlds: real session **and** amazing recordings **and** normal battery the rest of the time. The hard requirement under both transitions is a **robust full-restart of native Chrome** (kill the whole-process tree, confirm it's down, relaunch with profile + flags — and again to revert).+process tree, confirm it's down, relaunch with profile + flags - and again to revert). **⛔ Never, no matter how tempting:** foreground the window to "fix" a blank recording (defeats the whole-point — the user must keep working) · leave the background flags on globally/permanently (drains laptop+point - the user must keep working) · leave the background flags on globally/permanently (drains laptop battery) · use CDP screencast for demo video (low framerate, ugly). ### The two engines@@ -321,30 +321,30 @@ The browser can be recorded with **either** of two engines. Pick with `method`; |---|---|---| | **Platforms** | ✅ macOS, Ubuntu, Windows (cross-platform) | ⛔ Windows only (needs adom-desktop 1.8.148+) | | **Engine** | Same WebRTC pipeline Google Meet uses | OS-level Windows Graphics Capture → mp4 |-| **FPS** | High (30–60) | High (up to 60) |-| **Picker** | ❌ Chrome forces a one-time "choose what to share" picker per recording — no silent variant exists in any browser | ✅ None — agent picks the window by handle |+| **FPS** | High (30-60) | High (up to 60) |+| **Picker** | ❌ Chrome forces a one-time "choose what to share" picker per recording - no silent variant exists in any browser | ✅ None - agent picks the window by handle | | **Background** | ✅ keeps capturing the chosen surface even when occluded… | ✅ true background | | **Display wake-lock** | ⚠️ holds the display awake while sharing (can't blank the screen) | ✅ none | | **Output** | WebM (base64 returned) | mp4 (file path) |-| **Where it runs** | the extension (offscreen `MediaRecorder`) | the **bridge → adom-desktop** (`desktop_record_window_*`, standalone — never HD) |+| **Where it runs** | the extension (offscreen `MediaRecorder`) | the **bridge → adom-desktop** (`desktop_record_window_*`, standalone - never HD) | -**Rule of thumb:** on Windows (adom-desktop 1.8.148+), use **`wgc`** — it's picker-free and truly background,+**Rule of thumb:** on Windows (adom-desktop 1.8.148+), use **`wgc`** - it's picker-free and truly background, ideal for "record while the user does something else." Everywhere else (Mac/Ubuntu, or older AD), use **`getdisplaymedia`** and accept the one-time share picker. The verbs expose both so the caller/AI can choose and we can compare them head-to-head. -### The share picker — and how to skip it (agent-driven, zero clicks)+### The share picker - and how to skip it (agent-driven, zero clicks) -`getDisplayMedia`/`desktopCapture` shows a **forced "choose what to share" picker** — Chrome security+`getDisplayMedia`/`desktopCapture` shows a **forced "choose what to share" picker** - Chrome security forbids an extension from selecting the source programmatically (anti-spyware). There is **no API bypass**. To record **without a human click**, use one of: -1. **`wgc` (Windows + HD)** — the agent records a window *by handle*; no picker exists. ✅ best on Win.-2. **`getdisplaymedia` + Chrome launch flag `--auto-select-desktop-capture-source="<window title>"`** —+1. **`wgc` (Windows + HD)** - the agent records a window *by handle*; no picker exists. ✅ best on Win.+2. **`getdisplaymedia` + Chrome launch flag `--auto-select-desktop-capture-source="<window title>"`** - when *we* launch Chrome (e.g. HD launches it), the picker **auto-selects** the matching window and is skipped. ✅ **cross-platform** (Mac/Ubuntu/Windows) → this is the Mac/Ubuntu answer. -On an **already-running, un-managed Chrome** (not launched by us, no HD) the pick is unavoidable —+On an **already-running, un-managed Chrome** (not launched by us, no HD) the pick is unavoidable - that's the manual/ad-hoc fallback only. > Status: `getdisplaymedia` (with picker) implemented in-extension; non-blocking (`record_start`@@ -355,5 +355,5 @@ that's the manual/ad-hoc fallback only. ## Distribution Three channels (see the plan): self-hosted `.crx` + force-install policy (primary, managed machines),-Chrome Web Store + Edge Add-ons (official public — $5 once on Chrome, free on Edge), load-unpacked+Chrome Web Store + Edge Add-ons (official public - $5 once on Chrome, free on Edge), load-unpacked (dev). Verbs stay `nbrowser_*` regardless of store display name ("Adom for Chrome & Edge").