@btraut/browser-bridge 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on "Keep a Changelog", and this project adheres to Semantic
 
 ## [Unreleased]
 
+## [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

package/README.md

@@ -234,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
 ```
 
@@ -249,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>`