@btraut/browser-bridge 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -6,12 +6,28 @@ The format is based on "Keep a Changelog", and this project adheres to Semantic
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-02-16
+
+### Changed
+
+- Runtime routing now defaults to single-instance mode on `127.0.0.1:3210`; deterministic per-worktree ports are used only in explicit isolated mode.
+- Core startup now probes fallback ports only in isolated mode and preserves existing runtime metadata fields (including `extension_id`) when persisting host/port updates.
+- `browser-bridge dev activate` is now explicitly an isolated-worktree workflow command and persists `isolated_mode: true` in runtime metadata.
+
+### Fixed
+
+- Eliminated normal-workflow extension disconnects caused by hidden default port drift between Core/CLI and extension routing.
+
 ## [0.10.0] - 2026-02-15
 
 ### Added
 
 - CLI: support `-v` as a short alias for `--version`, with the value resolved from the installed package metadata.
 
+### Fixed
+
+- README: switch the header image to an absolute GitHub URL so it renders correctly on npm package pages.
+
 ## [0.9.0] - 2026-02-15
 
 ### Fixed

package/README.md

@@ -1,4 +1,4 @@
-<img src="docs/assets/readme-header.png" alt="Browser Bridge header graphic" width="720" />
+<img src="https://raw.githubusercontent.com/btraut/browser-bridge/main/docs/assets/readme-header.png" alt="Browser Bridge header graphic" width="720" />
 
 [![npm version](https://img.shields.io/npm/v/@btraut/browser-bridge.svg)](https://www.npmjs.com/package/@btraut/browser-bridge) [![npm downloads](https://img.shields.io/npm/dm/@btraut/browser-bridge.svg)](https://www.npmjs.com/package/@btraut/browser-bridge) [![CI](https://github.com/btraut/browser-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/btraut/browser-bridge/actions/workflows/ci.yml) [![License](https://img.shields.io/github/license/btraut/browser-bridge.svg)](LICENSE)
 
@@ -260,9 +260,23 @@ claude mcp add --transport stdio browser-bridge \
 
 </details>
 
-## 🔁 Multi-Worktree Dev Loop
+## ✅ Default Runtime (Normal Usage)
 
-Use this loop any time you switch worktrees.
+For normal usage, Browser Bridge is zero-setup:
+
+- Core and CLI default to `127.0.0.1:3210`.
+- The extension also defaults to `3210`.
+- You do not need `dev activate` unless you intentionally opt into isolated worktree routing.
+
+Optional status check:
+
+```bash
+browser-bridge dev info --json
+```
+
+## 🔁 Isolated Multi-Worktree Dev Loop (Advanced)
+
+Use this loop when you intentionally run multiple worktree instances in parallel.
 
 1. Resolve runtime for the current worktree:
 
@@ -272,7 +286,7 @@ 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):
+2. Activate isolated extension routing for this worktree:
 
 ```bash
 browser-bridge dev activate --extension-id <id>
@@ -295,7 +309,7 @@ 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`).
+- Default mode port is `3210`. In isolated mode, port is worktree-specific. Use `browser-bridge dev info` if you are unsure (or pass explicit `--port` / `BROWSER_BRIDGE_CORE_PORT`).
 
 ## 🩺 Diagnostics
 

package/dist/api.js

@@ -103,6 +103,8 @@ var ENV_CORE_HOST = "BROWSER_BRIDGE_CORE_HOST";
 var ENV_VISION_HOST = "BROWSER_VISION_CORE_HOST";
 var ENV_CORE_PORT = "BROWSER_BRIDGE_CORE_PORT";
 var ENV_VISION_PORT = "BROWSER_VISION_CORE_PORT";
+var ENV_ISOLATED_MODE = "BROWSER_BRIDGE_ISOLATED_MODE";
+var ENV_VISION_ISOLATED_MODE = "BROWSER_VISION_ISOLATED_MODE";
 var RUNTIME_METADATA_RELATIVE_PATH = ".context/browser-bridge/dev.json";
 var DEFAULT_LOG_DIRECTORY_RELATIVE_PATH = ".context/logs/browser-bridge";
 var resolveCwd = (cwd) => (0, import_node_path.resolve)(cwd ?? process.cwd());
@@ -119,6 +121,22 @@ var normalizeHost = (value) => {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 };
+var parseBoolean = (value) => {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
+    return true;
+  }
+  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
+    return false;
+  }
+  return void 0;
+};
 var parsePort = (value, label, invalidPolicy) => {
   if (value === void 0 || value === null) {
     return void 0;
@@ -202,6 +220,13 @@ var resolveEnvPortRaw = (env) => {
   }
   return env[ENV_VISION_PORT];
 };
+var resolveEnvIsolatedMode = (env) => {
+  const bridge = parseBoolean(env[ENV_ISOLATED_MODE]);
+  if (bridge !== void 0) {
+    return bridge;
+  }
+  return parseBoolean(env[ENV_VISION_ISOLATED_MODE]);
+};
 var sanitizeMetadata = (raw) => {
   if (!raw || typeof raw !== "object") {
     return null;
@@ -212,8 +237,9 @@ var sanitizeMetadata = (raw) => {
   const gitRoot = normalizeHost(candidate.git_root);
   const worktreeId = normalizeHost(candidate.worktree_id);
   const extensionId = normalizeHost(candidate.extension_id);
+  const isolatedMode = parseBoolean(candidate.isolated_mode);
   const updatedAt = normalizeHost(candidate.updated_at);
-  if (!host && port === void 0 && !gitRoot && !worktreeId && !extensionId && !updatedAt) {
+  if (!host && port === void 0 && !gitRoot && !worktreeId && !extensionId && isolatedMode === void 0 && !updatedAt) {
     return null;
   }
   return {
@@ -222,6 +248,7 @@ var sanitizeMetadata = (raw) => {
     git_root: gitRoot,
     worktree_id: worktreeId,
     extension_id: extensionId,
+    isolated_mode: isolatedMode,
     updated_at: updatedAt
   };
 };
@@ -367,6 +394,11 @@ var resolveCoreRuntime = (options = {}) => {
     options.strictEnvPort ? "throw" : "ignore"
   );
   const metadataPort = parsePort(metadata?.port, "port", "ignore");
+  const optionIsolatedMode = options.isolatedMode;
+  const envIsolatedMode = resolveEnvIsolatedMode(env);
+  const metadataIsolatedMode = metadata?.isolated_mode;
+  const isolatedMode = optionIsolatedMode ?? envIsolatedMode ?? metadataIsolatedMode ?? false;
+  const isolatedModeSource = optionIsolatedMode !== void 0 ? "option" : envIsolatedMode !== void 0 ? "env" : metadataIsolatedMode !== void 0 ? "metadata" : "default";
   let port;
   let portSource;
   if (optionPort !== void 0) {
@@ -375,12 +407,15 @@ var resolveCoreRuntime = (options = {}) => {
   } else if (envPort !== void 0) {
     port = envPort;
     portSource = "env";
-  } else if (metadataPort !== void 0) {
+  } else if (metadataPort !== void 0 && isolatedMode) {
     port = metadataPort;
     portSource = "metadata";
-  } else {
+  } else if (isolatedMode) {
     port = deterministicPort;
     portSource = "deterministic";
+  } else {
+    port = LEGACY_DEFAULT_PORT;
+    portSource = "default";
   }
   return {
     host,
@@ -391,7 +426,9 @@ var resolveCoreRuntime = (options = {}) => {
     metadata,
     gitRoot,
     worktreeId: resolveWorktreeId({ cwd: resolvedCwd, gitRoot }),
-    deterministicPort
+    deterministicPort,
+    isolatedMode,
+    isolatedModeSource
   };
 };
 
@@ -5086,6 +5123,26 @@ var createCoreServer = (options = {}) => {
   };
 };
 var CORE_PORT_PROBE_ATTEMPTS = 20;
+var buildRuntimeMetadataForPersist = (runtime, resolvedPort) => ({
+  ...runtime.metadata ?? {},
+  host: runtime.host,
+  port: resolvedPort,
+  git_root: runtime.gitRoot ?? runtime.metadata?.git_root,
+  worktree_id: runtime.worktreeId ?? runtime.metadata?.worktree_id,
+  updated_at: (/* @__PURE__ */ new Date()).toISOString()
+});
+var resolveProbePortsForRuntime = (runtime) => {
+  if (!runtime.isolatedMode) {
+    return [runtime.port];
+  }
+  if (runtime.portSource === "metadata" || runtime.portSource === "deterministic") {
+    return createBoundedPortProbeSequence(
+      runtime.port,
+      CORE_PORT_PROBE_ATTEMPTS
+    );
+  }
+  return [runtime.port];
+};
 var resolveSessionTtlMs = () => {
   const env = process.env.BROWSER_BRIDGE_SESSION_TTL_MS || process.env.BROWSER_VISION_SESSION_TTL_MS;
   if (env) {
@@ -5175,7 +5232,7 @@ var startCoreServer = async (options = {}) => {
     registry: options.registry,
     logger
   });
-  const probePorts = runtime.portSource === "metadata" || runtime.portSource === "deterministic" ? createBoundedPortProbeSequence(runtime.port, CORE_PORT_PROBE_ATTEMPTS) : [runtime.port];
+  const probePorts = resolveProbePortsForRuntime(runtime);
   let lastAddressInUseError;
   for (const candidatePort of probePorts) {
     const listenStart = process.hrtime.bigint();
@@ -5198,13 +5255,7 @@ var startCoreServer = async (options = {}) => {
       });
       try {
         writeRuntimeMetadata(
-          {
-            host: runtime.host,
-            port: resolvedPort,
-            git_root: runtime.gitRoot ?? void 0,
-            worktree_id: runtime.worktreeId ?? void 0,
-            updated_at: (/* @__PURE__ */ new Date()).toISOString()
-          },
+          buildRuntimeMetadataForPersist(runtime, resolvedPort),
           { metadataPath: runtime.metadataPath }
         );
         logger.info("core.runtime_metadata.persisted", {