# browser67 architecture

```text
Codex / MCP client
  -> src/mcp/browser/server.mjs
  -> src/tmwd-runtime/index.mjs
  -> src/tmwd-hub.mjs
     -> src/tmwd-hub/{config,sessions,relay,ws-server,link-server,shutdown}.mjs
  -> extension/background.js
     -> extension/browser67/window-focus-runtime.js
        -> dedicated Agent window / bounded focus lease
  -> Chrome/Edge tab

Codex / MCP client
  -> src/mcp/js-reverse/server.mjs
  -> src/tmwd-runtime/index.mjs
  -> src/tmwd-hub.mjs
     -> src/tmwd-hub/{config,sessions,relay,ws-server,link-server,shutdown}.mjs
  -> extension/background.js
  -> Chrome/Edge tab
  -> window.__TMWD_JS_REVERSE__ runtime hooks
```

Fallback paths:

```text
remote_cdp mode -> src/cdp-runtime/index.mjs -> http://127.0.0.1:9222
native fallback -> src/native/input.mjs -> macOS/Windows/Linux OS input backend
```

## Key design decisions

1. Keep browser67's real user-browser path as the default for profile-sensitive
   work; the current transport/protocol is TMWD.
2. Keep remote CDP explicit and visible.
3. Keep extension source vendored and reproducible.
4. Keep runtime artifacts under the active browser67 home, canonically
   `~/.browser67` with legacy `~/.tmwd-browser-mcp` compatibility.
5. Keep deterministic contracts separate from live browser gates.
6. Keep GenericAgent provenance explicit in `UPSTREAM.lock.json`.
7. Keep JS reverse MCP capabilities browser67-backed and hook-first;
   debugger/callframe workflows must stay explicit instead of silently
   pretending support.
8. Keep JS reverse docs and mounted skill content synchronized by script.
9. Keep the hub optionally managed by user-level launchd, not a hidden global service.
10. Keep routine managed work background-first in a dedicated, non-focused
    window within the selected Browser Profile. This isolates tab presentation,
    not profile data: approved cookies and sessions remain those of the same
    Profile.
11. Treat foreground focus as a bounded capability. Ordinary bridge work does
    not acquire it; native/CAPTCHA work may acquire one managed-tab focus lease.
    Restore is conditional on unchanged user focus, a still-live original
    target, an unchanged foreground target, and no service-worker recovery.

## Maintenance boundaries

- `extension/` is source-controlled and mirrors GenericAgent's extension except
  install-local `config.js`.
- `~/.browser67/browser/tmwd_cdp_bridge/` is the canonical Chrome/Edge
  unpacked extension install target. Legacy installs under
  `~/.tmwd-browser-mcp/browser/tmwd_cdp_bridge/` remain supported during
  migration.
- `~/.browser67/runtime/` is runtime state and logs. Run directories live
  under `runtime/runs` and are governed by `npm run runtime:cleanup:dry-run`
  / `npm run runtime:cleanup -- --write` so screenshot evidence stays outside
  the repo without growing indefinitely.
- `runtime/js-reverse/` is ignored local evidence, reports, and rebuild bundles
  produced by `src/mcp/js-reverse/server.mjs`.
- `~/Library/LaunchAgents/com.browser67.tmwd-hub.plist` is optional user-level
  autostart state created by `npm run launchd:install`.
- `src/tmwd-hub.mjs` and `src/tmwd-hub-control.mjs` are thin executable
  entrypoints. Hub state, session TTL, WS relay, link HTTP commands, shutdown,
  endpoint parsing, probing, and state-file IO live in sibling module folders.