by adom

Your AI's hands in your real, signed-in browser. The Adom Browser Extension (abe) works with both Chrome and Edge: build, drive, and test web apps, and log past vendor walls, in the browser you already use - cookies, SSO, saved logins and captcha trust intact. The nbrowser_* bridge (pup's counterpart) runs in your actual logged-in profile.

Overview Files Skills Discover Packages Releases Dependencies Issues1 Breadcrumbs Pull Requests Activity

Download

name: cross-platform-dev description: How adom-browser-extension ships across Windows and macOS - Windows-first, Kyle ports to Mac. Read before adding platform-specific code.

Cross-platform dev flow (Windows-first → Kyle ports to Mac)

Adom's standard flow, applied to this repo: John builds and ships on Windows; Kyle ports to macOS as a fast-follow. John is a Windows user, Kyle is the Mac user. Design accordingly so Kyle's port is a thin layer, never a rewrite.

Shipping a bridge update so AD picks it up (build the manifest + zip, the .zip-blocked-use-.bin trap, the canonical URL, bridge_install vs refresh_bridges) is general bridge-author knowledge and lives on the bridges hub: the shipping-a-bridge skill at adom/adom-desktop-bridges. Read it before cutting a new bridge/ version.

The rule

Keep the bridge (bridge/server.js), the native host (host/native-host.js), and the extension (extension/) OS-agnostic - plain Node + standard MV3 APIs. Isolate everything Windows-specific to the install/registration layer only:

Concern	Windows (build first)	macOS (Kyle ports)
Native-messaging host manifest	`HKCU\Software\<vendor>\NativeMessagingHosts\inc.adom.native_browser`	`~/Library/Application Support/<Google/Chrome \| Microsoft Edge>/NativeMessagingHosts/inc.adom.native_browser.json`
Host launcher	`native-host.bat` → `node native-host.js`	`native-host.sh` → `node native-host.js` (chmod +x)
Bridge cache path	`%LOCALAPPDATA%\Adom Desktop\bridges-cache\native-browser\`	`~/Library/Application Support/Adom Desktop/bridges-cache/native-browser/`
Extension force-install	`HKLM\...\ExtensionInstallForcelist`	configuration profile / MDM `ExtensionInstallForcelist`
Discovery file	`os.homedir()/.adom/bridges/native-browser/host.json`	identical (uses `os.homedir()` - already cross-platform)

Implications

Never put process.platform === 'win32' branches in bridge/ or host/ core logic. If you need a platform path, derive it from os.homedir() (already cross-platform) - don't hardcode %...%.
The --silent-debugger-extension-api launch-flag wiring and registry writes are Windows-only by nature; keep them in install/ so Kyle swaps that folder, not the engine.
When you add a Windows install step, add a one-line "macOS equivalent" note next to it so the port is mechanical.

---
name: cross-platform-dev
description: How adom-browser-extension ships across Windows and macOS - Windows-first, Kyle ports to Mac. Read before adding platform-specific code.
---

# Cross-platform dev flow (Windows-first → Kyle ports to Mac)

Adom's standard flow, applied to this repo: **John builds and ships on Windows; Kyle ports to macOS
as a fast-follow.** John is a Windows user, Kyle is the Mac user. Design accordingly so Kyle's port is
a thin layer, never a rewrite.

> **Shipping a bridge update so AD picks it up** (build the manifest + zip, the `.zip`-blocked-use-`.bin`
> trap, the canonical URL, `bridge_install` vs `refresh_bridges`) is general bridge-author knowledge and
> lives on the bridges hub: the **`shipping-a-bridge`** skill at
> [adom/adom-desktop-bridges](https://wiki.adom.inc/adom/adom-desktop-bridges). Read it before cutting a
> new `bridge/` version.

## The rule

Keep the **bridge** (`bridge/server.js`), the **native host** (`host/native-host.js`), and the
**extension** (`extension/`) **OS-agnostic** - plain Node + standard MV3 APIs. Isolate everything
Windows-specific to the **install/registration layer** only:

| Concern | Windows (build first) | macOS (Kyle ports) |
|---|---|---|
| Native-messaging host manifest | `HKCU\Software\<vendor>\NativeMessagingHosts\inc.adom.native_browser` | `~/Library/Application Support/<Google/Chrome \| Microsoft Edge>/NativeMessagingHosts/inc.adom.native_browser.json` |
| Host launcher | `native-host.bat` → `node native-host.js` | `native-host.sh` → `node native-host.js` (chmod +x) |
| Bridge cache path | `%LOCALAPPDATA%\Adom Desktop\bridges-cache\native-browser\` | `~/Library/Application Support/Adom Desktop/bridges-cache/native-browser/` |
| Extension force-install | `HKLM\...\ExtensionInstallForcelist` | configuration profile / MDM `ExtensionInstallForcelist` |
| Discovery file | `os.homedir()/.adom/bridges/native-browser/host.json` | identical (uses `os.homedir()` - already cross-platform) |

## Implications

- Never put `process.platform === 'win32'` branches in `bridge/` or `host/` core logic. If you need a
  platform path, derive it from `os.homedir()` (already cross-platform) - don't hardcode `%...%`.
- The `--silent-debugger-extension-api` launch-flag wiring and registry writes are Windows-only by
  nature; keep them in `install/` so Kyle swaps that folder, not the engine.
- When you add a Windows install step, add a one-line "macOS equivalent" note next to it so the port
  is mechanical.