# OpenDevBrowser Extension

Chrome extension runtime for OpenDevBrowser relay mode.

## Purpose

Connects Chrome tabs to the local OpenDevBrowser relay so sessions can run against logged-in browser contexts.

## Key behavior

- Connects to local relay (`/extension`) and participates in `/ops`, `/canvas`, `/cdp` (legacy), and `/annotation` workflows.
- Uses flat CDP sessions (Chrome 125+) with `sessionId`-based routing.
- Supports auto-connect, auto-pair, and optional native-host fallback. Relay takeover suppression is temporary: if no replacement extension client remains connected, auto-connect retries the stored relay.
- Tracks a primary tab for handshake/status while keeping multi-target routing intact.
- Supports browser replay capture for extension-backed sessions through the existing screenshot lane used by OpenDevBrowser screencasts.
- Uses canonical toolbar/store icons from `assets/extension-icons` synced into `extension/icons` at build time.
- Shows a small badge dot for status (`green` connected, `red` disconnected).
- Desktop observation remains the public read-only daemon/core-owned plane and does not use the extension relay.
- Generated help points users to the exact lookup labels `screencast / browser replay`, `desktop observation`, and `computer use / browser-scoped computer use`; the extension participates in replay-backed browser sessions, not the public read-only desktop plane.

## Build

Run from repo root:

```bash
npm run extension:sync
npm run extension:build
node scripts/chrome-store-compliance-check.mjs
npm run extension:pack
```

## Load unpacked

1. Build extension assets.
2. Open `chrome://extensions`.
3. Enable Developer mode.
4. Load unpacked from:
   - `~/.config/opencode/opendevbrowser/extension`, or
   - repo `extension/` for local development, or
   - pre-release local package install path: `<WORKDIR>/node_modules/opendevbrowser/extension`.

The extracted install copy created by `npx opendevbrowser --full` includes `manifest.json`, `popup.html`, `canvas.html`, `dist/`, and `icons/`.

## Source map

- `extension/src/background.ts` — relay + command routing coordinator
- `extension/src/popup.tsx` — settings UI
- `extension/canvas.html` — extension-hosted design-canvas editor shell
- `extension/src/canvas-page.ts` — design-canvas page bootstrap
- `extension/src/canvas/*` — design-canvas runtime state, sync, and rendering helpers
- `extension/src/services/*` — connection manager, relay client, CDP router/session mapping
- `extension/src/ops/*` — high-level ops runtime
- `extension/src/annotate-content.ts` — in-page annotation UI

## Runtime prerequisites

- Chrome 125+
- Local daemon/relay running (`npx opendevbrowser serve`)
- Matching relay port/token settings

See [`../docs/EXTENSION.md`](../docs/EXTENSION.md) for full operational and troubleshooting details.
