@btraut/browser-bridge 0.7.3 → 0.8.1

package/CHANGELOG.md

@@ -6,7 +6,31 @@ The format is based on "Keep a Changelog", and this project adheres to Semantic
 
 ## [Unreleased]
 
-_TBD_
+## [0.8.1] - 2026-02-14
+
+### Added
+
+- CLI: `browser-bridge dev info` now prints resolved runtime details (host/port + source, deterministic port, worktree id, metadata path, log dir, and metadata snapshot).
+- CLI: `browser-bridge dev activate` now resolves runtime, persists metadata for the current worktree, and opens extension options with activation query params.
+
+### Changed
+
+- Runtime metadata now supports persisted `extension_id` so extension targeting can survive across sessions/worktrees.
+- Extension options activation flow now applies `corePort` from activation query params via `chrome.storage.local` and then clears the query string to prevent repeated re-application on refresh.
+
+### Fixed
+
+- `drive.go_back` / `drive.go_forward` no longer hang when history navigation unloads the page before content-script messaging completes; history dispatch is deferred, background completion waits for deterministic top-level navigation signals, and tab messaging now has an explicit timeout guard.
+
+## [0.8.0] - 2026-02-14
+
+### Changed
+
+- `drive.click` now dispatches deferred clicks through CDP `Input.dispatchMouseEvent` in the extension background path, with locator point resolution coming from the content script.
+- `drive.hover` and `drive.drag` now run through CDP mouse movement/press/release events in the extension background path, with HTML snapshot capture handled as a separate internal content action.
+- `drive.key`, `drive.key_press`, and `drive.type` now route through CDP keyboard/text input commands in the extension background path, while content script target helpers only resolve/validate editable targets.
+- `drive.select` and `drive.fill_form` now run CDP-backed focus/typing primitives first, with explicit content-script fallback for control-specific operations that CDP does not map directly.
+- Added `docs/cdp-input-model.md` plus stronger assertions in `scripts/cli-full-tool-smoke.sh` to validate focus/value/drag side effects during CDP-input smoke runs.
 
 ## [0.7.3] - 2026-02-14
 

package/README.md

@@ -82,6 +82,14 @@ What makes it different:
 - **Recovery-first**: sessions have an explicit state machine with `session.recover()` and `diagnostics doctor`.
 - **Inspect beyond screenshots**: DOM snapshots (AX + HTML) and `inspect dom-diff` to detect page changes.
 
+## Input Semantics
+
+Drive input actions are CDP-first (Chrome DevTools Protocol `Input.*`) so click, hover, drag, key, and type behavior follows Chrome's native input pipeline instead of synthetic DOM event dispatch.
+
+High-level helpers (`drive.select`, `drive.fill_form`) still use explicit fallback branches for control-specific operations that CDP does not model directly (for example selecting by option value/text/index).
+
+See `docs/cdp-input-model.md` for details and smoke verification.
+
 ## 🆚 Feature Comparison
 
 | Category | Browser Bridge | Playwright MCP | agent-browser | mcp-chrome | Claude Code + Chrome |
@@ -226,12 +234,12 @@ Codex:
 codex mcp add browser-bridge -- browser-bridge mcp
 ```
 
-Optional custom host/port:
+Optional custom host/port (use `browser-bridge dev info` to get the current worktree port):
 
 ```bash
 codex mcp add browser-bridge \
   --env BROWSER_BRIDGE_CORE_HOST=127.0.0.1 \
-  --env BROWSER_BRIDGE_CORE_PORT=3210 \
+  --env BROWSER_BRIDGE_CORE_PORT=<port-from-dev-info> \
   -- browser-bridge mcp
 ```
 
@@ -241,17 +249,54 @@ Claude Code:
 claude mcp add --transport stdio browser-bridge -- browser-bridge mcp
 ```
 
-Optional custom host/port:
+Optional custom host/port (use `browser-bridge dev info` to get the current worktree port):
 
 ```bash
 claude mcp add --transport stdio browser-bridge \
   --env BROWSER_BRIDGE_CORE_HOST=127.0.0.1 \
-  --env BROWSER_BRIDGE_CORE_PORT=3210 \
+  --env BROWSER_BRIDGE_CORE_PORT=<port-from-dev-info> \
   -- browser-bridge mcp
 ```
 
 </details>
 
+## 🔁 Multi-Worktree Dev Loop
+
+Use this loop any time you switch worktrees.
+
+1. Resolve runtime for the current worktree:
+
+```bash
+browser-bridge dev info --json
+```
+
+Use the `port`, `worktreeId`, `metadataPath`, and `logDir` from output.
+
+2. Activate extension routing for this worktree (required for extension-driving tasks):
+
+```bash
+browser-bridge dev activate --extension-id <id>
+```
+
+After the first run, you can usually omit `--extension-id` because it is saved in `.context/browser-bridge/dev.json`.
+
+3. Run your CLI/MCP workflow in this worktree.
+
+## 🧯 Worktree Troubleshooting
+
+- Missing extension id: Run `browser-bridge dev activate --extension-id <id>`. Or set `BROWSER_BRIDGE_EXTENSION_ID=<id>`. You can copy the id from `chrome://extensions` (enable Developer mode to see ids).
+- Activation URL did not open in Chrome: Run `browser-bridge dev activate --json`, copy `result.activationUrl`, and open it directly in Chrome. `dev activate` uses the OS URL opener, so your default browser setting matters.
+- Logs and per-stream JSONL inspection: Logs are under `.context/logs/browser-bridge/`. Common streams: `cli.jsonl`, `core.jsonl`, `mcp-adapter.jsonl` (plus rotated files like `core.1.jsonl`).
+
+```bash
+ls -1 .context/logs/browser-bridge
+tail -n 80 .context/logs/browser-bridge/cli.jsonl
+tail -n 80 .context/logs/browser-bridge/core.jsonl
+tail -n 80 .context/logs/browser-bridge/mcp-adapter.jsonl
+```
+
+- Do not assume port `3210` across worktrees: Default port is deterministic per worktree and may differ. Always check `browser-bridge dev info` (or pass explicit `--port` / `BROWSER_BRIDGE_CORE_PORT`).
+
 ## 🩺 Diagnostics
 
 - CLI: `browser-bridge diagnostics doctor --session-id <id>`