---
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.