@flrande/bak-extension 0.6.5 → 0.6.7

package/dist/.bak-e2e-build-stamp

@@ -1 +1 @@
-2026-03-13T06:30:44.568Z
+2026-03-13T07:58:24.806Z

package/dist/background.global.js

@@ -62,7 +62,7 @@
   // package.json
   var package_default = {
     name: "@flrande/bak-extension",
-    version: "0.6.5",
+    version: "0.6.7",
     type: "module",
     scripts: {
       build: "tsup src/background.ts src/content.ts src/popup.ts --format iife --out-dir dist --clean && node scripts/copy-assets.mjs",
@@ -573,13 +573,14 @@
         state.activeTabId = null;
         state.primaryTabId = null;
         window2 = createdWindow;
-        tabs = await this.waitForWindowTabs(createdWindow.id);
+        const initialTab = typeof createdWindow.initialTabId === "number" ? await this.waitForTrackedTab(createdWindow.initialTabId, createdWindow.id) : null;
+        tabs = initialTab ? [initialTab] : await this.waitForWindowTabs(createdWindow.id);
         state.tabIds = tabs.map((tab) => tab.id);
         if (state.primaryTabId === null) {
-          state.primaryTabId = tabs[0]?.id ?? null;
+          state.primaryTabId = initialTab?.id ?? tabs[0]?.id ?? null;
         }
         if (state.activeTabId === null) {
-          state.activeTabId = tabs.find((tab) => tab.active)?.id ?? tabs[0]?.id ?? null;
+          state.activeTabId = tabs.find((tab) => tab.active)?.id ?? initialTab?.id ?? tabs[0]?.id ?? null;
         }
         repairActions.push(created ? "created-window" : "recreated-window");
       }
@@ -1081,7 +1082,8 @@
         url: seedUrl || DEFAULT_SESSION_BINDING_URL,
         focused: false
       });
-      const recreatedTabs = await this.waitForWindowTabs(window2.id);
+      const initialTab = typeof window2.initialTabId === "number" ? await this.waitForTrackedTab(window2.initialTabId, window2.id) : null;
+      const recreatedTabs = initialTab ? [initialTab] : await this.waitForWindowTabs(window2.id);
       const firstTab = recreatedTabs[0] ?? null;
       const tabIdMap = /* @__PURE__ */ new Map();
       if (sourceTabs[0] && firstTab) {
@@ -1608,14 +1610,42 @@
     },
     async createWindow(options) {
       const previouslyFocusedWindow = options.focused === true ? null : (await chrome.windows.getAll()).find((window2) => window2.focused === true && typeof window2.id === "number") ?? null;
-      const previouslyFocusedTab = previouslyFocusedWindow?.id !== void 0 ? (await chrome.tabs.query({ windowId: previouslyFocusedWindow.id, active: true })).find((tab) => typeof tab.id === "number") ?? null : null;
-      const created = await chrome.windows.create({
-        url: options.url ?? "about:blank",
+      const previouslyFocusedTabs = previouslyFocusedWindow?.id !== void 0 ? await chrome.tabs.query({ windowId: previouslyFocusedWindow.id }) : [];
+      const previouslyFocusedTabIds = new Set(
+        previouslyFocusedTabs.flatMap((tab) => typeof tab.id === "number" ? [tab.id] : [])
+      );
+      const previouslyFocusedTab = previouslyFocusedTabs.find((tab) => tab.active === true && typeof tab.id === "number") ?? null;
+      const desiredUrl = options.url ?? "about:blank";
+      let created = await chrome.windows.create({
+        url: desiredUrl,
         focused: true
       });
       if (!created || typeof created.id !== "number") {
         throw new Error("Window missing id");
       }
+      const pickSeedTab = async (windowId) => {
+        const tabs = await chrome.tabs.query({ windowId });
+        const newlyCreatedTab = windowId === previouslyFocusedWindow?.id ? tabs.find((tab) => typeof tab.id === "number" && !previouslyFocusedTabIds.has(tab.id)) : null;
+        const normalizedDesiredUrl = normalizeComparableTabUrl(desiredUrl);
+        return newlyCreatedTab ?? tabs.find((tab) => {
+          const pendingUrl = "pendingUrl" in tab && typeof tab.pendingUrl === "string" ? tab.pendingUrl : "";
+          return normalizeComparableTabUrl(tab.url ?? pendingUrl) === normalizedDesiredUrl;
+        }) ?? tabs.find((tab) => tab.active === true && typeof tab.id === "number") ?? tabs.find((tab) => typeof tab.id === "number") ?? null;
+      };
+      let seedTab = await pickSeedTab(created.id);
+      const createdWindowTabs = await chrome.tabs.query({ windowId: created.id });
+      const createdWindowReusedFocusedWindow = previouslyFocusedWindow?.id === created.id;
+      const createdWindowLooksDirty = createdWindowTabs.length > 1;
+      if ((createdWindowReusedFocusedWindow || createdWindowLooksDirty) && typeof seedTab?.id === "number") {
+        created = await chrome.windows.create({
+          tabId: seedTab.id,
+          focused: true
+        });
+        if (!created || typeof created.id !== "number") {
+          throw new Error("Lifted window missing id");
+        }
+        seedTab = await pickSeedTab(created.id);
+      }
       if (options.focused !== true && previouslyFocusedWindow?.id && previouslyFocusedWindow.id !== created.id) {
         await chrome.windows.update(previouslyFocusedWindow.id, { focused: true });
         if (typeof previouslyFocusedTab?.id === "number") {
@@ -1625,7 +1655,8 @@
       const finalWindow = await chrome.windows.get(created.id);
       return {
         id: finalWindow.id,
-        focused: Boolean(finalWindow.focused)
+        focused: Boolean(finalWindow.focused),
+        initialTabId: seedTab?.id ?? null
       };
     },
     async updateWindow(windowId, options) {

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Browser Agent Kit",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "action": {
     "default_popup": "popup.html"
   },

package/dist/popup.global.js

@@ -2,10 +2,12 @@
 (() => {
   // src/popup.ts
   var statusEl = document.getElementById("status");
+  var statusNoteEl = document.getElementById("statusNote");
   var tokenInput = document.getElementById("token");
   var portInput = document.getElementById("port");
   var debugRichTextInput = document.getElementById("debugRichText");
   var saveBtn = document.getElementById("save");
+  var saveRowEl = document.getElementById("saveRow");
   var reconnectBtn = document.getElementById("reconnect");
   var disconnectBtn = document.getElementById("disconnect");
   var connectionStateEl = document.getElementById("connectionState");
@@ -18,9 +20,24 @@
   var sessionSummaryEl = document.getElementById("sessionSummary");
   var sessionListEl = document.getElementById("sessionList");
   var latestState = null;
-  function setStatus(text, bad = false) {
+  function setStatus(text, tone = "neutral") {
     statusEl.textContent = text;
-    statusEl.style.color = bad ? "#dc2626" : "#0f172a";
+    if (tone === "success") {
+      statusEl.style.color = "#166534";
+      return;
+    }
+    if (tone === "warning") {
+      statusEl.style.color = "#b45309";
+      return;
+    }
+    if (tone === "error") {
+      statusEl.style.color = "#dc2626";
+      return;
+    }
+    statusEl.style.color = "#0f172a";
+  }
+  function pluralize(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
   }
   function formatTimeAgo(at) {
     if (typeof at !== "number") {
@@ -41,7 +58,11 @@
     return `${deltaHours}h ago`;
   }
   function renderSessionBindings(state) {
-    sessionSummaryEl.textContent = `${state.count} sessions, ${state.attachedCount} attached, ${state.tabCount} tabs, ${state.detachedCount} detached`;
+    if (state.count === 0) {
+      sessionSummaryEl.textContent = "No remembered sessions";
+    } else {
+      sessionSummaryEl.textContent = `${pluralize(state.count, "session")}, ${pluralize(state.attachedCount, "attached binding")}, ${pluralize(state.tabCount, "tab")}, ${pluralize(state.detachedCount, "detached binding")}`;
+    }
     sessionListEl.replaceChildren();
     for (const item of state.items) {
       const li = document.createElement("li");
@@ -54,8 +75,25 @@
       sessionListEl.appendChild(li);
     }
   }
+  function describeConnectionState(connectionState) {
+    switch (connectionState) {
+      case "connected":
+        return "connected";
+      case "connecting":
+        return "waiting for runtime";
+      case "reconnecting":
+        return "retrying connection";
+      case "manual":
+        return "manually disconnected";
+      case "missing-token":
+        return "token required";
+      case "disconnected":
+      default:
+        return "disconnected";
+    }
+  }
   function renderConnectionDetails(state) {
-    connectionStateEl.textContent = state.connectionState;
+    connectionStateEl.textContent = describeConnectionState(state.connectionState);
     tokenStateEl.textContent = state.hasToken ? "configured" : "missing";
     connectionUrlEl.textContent = state.wsUrl;
     extensionVersionEl.textContent = state.extensionVersion;
@@ -81,38 +119,110 @@
       lastBindingUpdateEl.textContent = "none";
     }
   }
+  function parsePortValue() {
+    const port = Number.parseInt(portInput.value.trim(), 10);
+    return Number.isInteger(port) && port > 0 ? port : null;
+  }
+  function isFormDirty(state) {
+    if (!state) {
+      return tokenInput.value.trim().length > 0;
+    }
+    return tokenInput.value.trim().length > 0 || portInput.value.trim() !== String(state.port) || debugRichTextInput.checked !== Boolean(state.debugRichText);
+  }
+  function getConfigValidationMessage(state) {
+    if (!tokenInput.value.trim() && state?.hasToken !== true) {
+      return "Pair token is required";
+    }
+    if (parsePortValue() === null) {
+      return "Port is invalid";
+    }
+    return null;
+  }
+  function updateSaveState(state) {
+    const dirty = isFormDirty(state);
+    const validationError = getConfigValidationMessage(state);
+    saveRowEl.hidden = !dirty;
+    saveBtn.disabled = !dirty || validationError !== null;
+    saveBtn.textContent = state?.hasToken ? "Save settings" : "Save token";
+  }
+  function describeStatus(state) {
+    const combinedError = `${state.lastErrorContext ?? ""} ${state.lastError ?? ""}`.toLowerCase();
+    const runtimeOffline = combinedError.includes("cannot connect to bak cli");
+    if (state.connected) {
+      return {
+        text: "Connected to local bak runtime",
+        note: "Use the bak CLI to start browser work. This popup is mainly for status and configuration.",
+        tone: "success"
+      };
+    }
+    if (state.connectionState === "missing-token") {
+      return {
+        text: "Pair token is required",
+        note: "Paste a token once, then save it. Future reconnects happen automatically.",
+        tone: "error"
+      };
+    }
+    if (state.connectionState === "manual") {
+      return {
+        text: "Extension bridge is paused",
+        note: "Normal browser work starts from the bak CLI. Open Advanced only if you need to reconnect manually.",
+        tone: "warning"
+      };
+    }
+    if (runtimeOffline) {
+      return {
+        text: "Waiting for local bak runtime",
+        note: "Run any bak command, such as `bak doctor`, and the extension will reconnect automatically.",
+        tone: "warning"
+      };
+    }
+    if (state.connectionState === "reconnecting") {
+      return {
+        text: "Trying to reconnect",
+        note: "The extension is retrying in the background. You usually do not need to press anything here.",
+        tone: "warning"
+      };
+    }
+    if (state.lastError) {
+      return {
+        text: "Connection problem",
+        note: "Check the last error below. The extension keeps retrying automatically unless you disconnect it manually.",
+        tone: "error"
+      };
+    }
+    return {
+      text: "Not connected yet",
+      note: "Once the local bak runtime is available, the extension reconnects automatically.",
+      tone: "neutral"
+    };
+  }
   async function refreshState() {
     const state = await chrome.runtime.sendMessage({ type: "bak.getState" });
     if (state.ok) {
+      const shouldSyncForm = !isFormDirty(latestState);
       latestState = state;
-      portInput.value = String(state.port);
-      debugRichTextInput.checked = Boolean(state.debugRichText);
+      if (shouldSyncForm) {
+        portInput.value = String(state.port);
+        debugRichTextInput.checked = Boolean(state.debugRichText);
+        tokenInput.value = "";
+      }
       renderConnectionDetails(state);
       renderSessionBindings(state.sessionBindings);
-      if (state.connected) {
-        setStatus("Connected to bak CLI");
-      } else if (state.connectionState === "missing-token") {
-        setStatus("Pair token is required", true);
-      } else if (state.connectionState === "manual") {
-        setStatus("Disconnected manually");
-      } else if (state.connectionState === "reconnecting") {
-        setStatus("Reconnecting to bak CLI", true);
-      } else if (state.lastError) {
-        setStatus(`Disconnected: ${state.lastError}`, true);
-      } else {
-        setStatus("Disconnected");
-      }
+      updateSaveState(state);
+      const status = describeStatus(state);
+      setStatus(status.text, status.tone);
+      statusNoteEl.textContent = status.note;
     }
   }
   saveBtn.addEventListener("click", async () => {
     const token = tokenInput.value.trim();
-    const port = Number.parseInt(portInput.value.trim(), 10);
+    const port = parsePortValue();
     if (!token && latestState?.hasToken !== true) {
-      setStatus("Pair token is required", true);
+      setStatus("Pair token is required", "error");
       return;
     }
-    if (!Number.isInteger(port) || port <= 0) {
-      setStatus("Port is invalid", true);
+    if (port === null) {
+      setStatus("Port is invalid", "error");
       return;
     }
     await chrome.runtime.sendMessage({
@@ -132,6 +242,14 @@
     await chrome.runtime.sendMessage({ type: "bak.disconnect" });
     await refreshState();
   });
+  for (const element of [tokenInput, portInput, debugRichTextInput]) {
+    element.addEventListener("input", () => {
+      updateSaveState(latestState);
+    });
+    element.addEventListener("change", () => {
+      updateSaveState(latestState);
+    });
+  }
   void refreshState();
   var refreshInterval = window.setInterval(() => {
     void refreshState();

package/dist/popup.html

@@ -54,6 +54,9 @@
         gap: 8px;
         margin-top: 12px;
       }
+      .row[hidden] {
+        display: none;
+      }
       button {
         flex: 1;
         border: none;
@@ -62,6 +65,10 @@
         font-size: 12px;
         cursor: pointer;
       }
+      button:disabled {
+        opacity: 0.55;
+        cursor: default;
+      }
       #save {
         background: #0f172a;
         color: #fff;
@@ -79,6 +86,12 @@
         font-size: 12px;
         font-weight: 600;
       }
+      #statusNote {
+        margin-top: 4px;
+        font-size: 11px;
+        line-height: 1.45;
+        color: #475569;
+      }
       .panel {
         margin-top: 12px;
         padding: 10px;
@@ -120,6 +133,30 @@
         font-size: 11px;
         color: #334155;
       }
+      .hint.compact {
+        margin-top: 8px;
+      }
+      details.panel {
+        padding-bottom: 12px;
+      }
+      details.panel summary {
+        cursor: pointer;
+        font-size: 12px;
+        font-weight: 600;
+        list-style: none;
+      }
+      details.panel summary::-webkit-details-marker {
+        display: none;
+      }
+      details.panel summary::after {
+        content: "Show";
+        float: right;
+        font-size: 11px;
+        color: #64748b;
+      }
+      details.panel[open] summary::after {
+        content: "Hide";
+      }
     </style>
   </head>
   <body>
@@ -136,14 +173,11 @@
       <input id="debugRichText" type="checkbox" />
       <span class="toggle-text">Allow richer text capture for debugging (still redacted, off by default)</span>
     </label>
-    <div class="row">
-      <button id="save">Save & Connect</button>
-      <button id="reconnect">Reconnect</button>
-    </div>
-    <div class="row">
-      <button id="disconnect">Disconnect</button>
-    </div>
     <div id="status">Checking...</div>
+    <div id="statusNote">The extension reconnects automatically when the local bak runtime wakes up.</div>
+    <div class="row" id="saveRow" hidden>
+      <button id="save">Save settings</button>
+    </div>
     <div class="panel">
       <h2>Connection</h2>
       <dl class="meta-grid">
@@ -171,6 +205,14 @@
       </dl>
       <ul id="sessionList"></ul>
     </div>
+    <details class="panel" id="advancedPanel">
+      <summary>Advanced bridge controls</summary>
+      <div class="hint compact">These controls are only for debugging the extension bridge. Normal browser work should start from the bak CLI.</div>
+      <div class="row">
+        <button id="reconnect">Reconnect bridge</button>
+        <button id="disconnect">Disconnect bridge</button>
+      </div>
+    </details>
     <div class="hint">Extension only connects to ws://127.0.0.1</div>
     <script src="./popup.global.js"></script>
   </body>

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@flrande/bak-extension",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "type": "module",
   "dependencies": {
-    "@flrande/bak-protocol": "0.6.5"
+    "@flrande/bak-protocol": "0.6.7"
   },
   "devDependencies": {
     "@types/chrome": "^0.1.14",

package/public/popup.html

@@ -54,6 +54,9 @@
         gap: 8px;
         margin-top: 12px;
       }
+      .row[hidden] {
+        display: none;
+      }
       button {
         flex: 1;
         border: none;
@@ -62,6 +65,10 @@
         font-size: 12px;
         cursor: pointer;
       }
+      button:disabled {
+        opacity: 0.55;
+        cursor: default;
+      }
       #save {
         background: #0f172a;
         color: #fff;
@@ -79,6 +86,12 @@
         font-size: 12px;
         font-weight: 600;
       }
+      #statusNote {
+        margin-top: 4px;
+        font-size: 11px;
+        line-height: 1.45;
+        color: #475569;
+      }
       .panel {
         margin-top: 12px;
         padding: 10px;
@@ -120,6 +133,30 @@
         font-size: 11px;
         color: #334155;
       }
+      .hint.compact {
+        margin-top: 8px;
+      }
+      details.panel {
+        padding-bottom: 12px;
+      }
+      details.panel summary {
+        cursor: pointer;
+        font-size: 12px;
+        font-weight: 600;
+        list-style: none;
+      }
+      details.panel summary::-webkit-details-marker {
+        display: none;
+      }
+      details.panel summary::after {
+        content: "Show";
+        float: right;
+        font-size: 11px;
+        color: #64748b;
+      }
+      details.panel[open] summary::after {
+        content: "Hide";
+      }
     </style>
   </head>
   <body>
@@ -136,14 +173,11 @@
       <input id="debugRichText" type="checkbox" />
       <span class="toggle-text">Allow richer text capture for debugging (still redacted, off by default)</span>
     </label>
-    <div class="row">
-      <button id="save">Save & Connect</button>
-      <button id="reconnect">Reconnect</button>
-    </div>
-    <div class="row">
-      <button id="disconnect">Disconnect</button>
-    </div>
     <div id="status">Checking...</div>
+    <div id="statusNote">The extension reconnects automatically when the local bak runtime wakes up.</div>
+    <div class="row" id="saveRow" hidden>
+      <button id="save">Save settings</button>
+    </div>
     <div class="panel">
       <h2>Connection</h2>
       <dl class="meta-grid">
@@ -171,6 +205,14 @@
       </dl>
       <ul id="sessionList"></ul>
     </div>
+    <details class="panel" id="advancedPanel">
+      <summary>Advanced bridge controls</summary>
+      <div class="hint compact">These controls are only for debugging the extension bridge. Normal browser work should start from the bak CLI.</div>
+      <div class="row">
+        <button id="reconnect">Reconnect bridge</button>
+        <button id="disconnect">Disconnect bridge</button>
+      </div>
+    </details>
     <div class="hint">Extension only connects to ws://127.0.0.1</div>
     <script src="./popup.global.js"></script>
   </body>

package/src/background.ts

@@ -411,7 +411,7 @@ function emitSessionBindingUpdated(
   });
 }
 
-const sessionBindingBrowser: SessionBindingBrowser = {
+const sessionBindingBrowser: SessionBindingBrowser = {
   async getTab(tabId) {
     try {
       return toTabInfo(await chrome.tabs.get(tabId));
@@ -468,34 +468,71 @@ const sessionBindingBrowser: SessionBindingBrowser = {
       return null;
     }
   },
-  async createWindow(options) {
-    const previouslyFocusedWindow =
-      options.focused === true
-        ? null
-        : (await chrome.windows.getAll()).find((window) => window.focused === true && typeof window.id === 'number') ?? null;
-    const previouslyFocusedTab =
-      previouslyFocusedWindow?.id !== undefined
-        ? (await chrome.tabs.query({ windowId: previouslyFocusedWindow.id, active: true })).find((tab) => typeof tab.id === 'number') ?? null
-        : null;
-    const created = await chrome.windows.create({
-      url: options.url ?? 'about:blank',
-      focused: true
-    });
-    if (!created || typeof created.id !== 'number') {
-      throw new Error('Window missing id');
-    }
-    if (options.focused !== true && previouslyFocusedWindow?.id && previouslyFocusedWindow.id !== created.id) {
-      await chrome.windows.update(previouslyFocusedWindow.id, { focused: true });
-      if (typeof previouslyFocusedTab?.id === 'number') {
-        await chrome.tabs.update(previouslyFocusedTab.id, { active: true });
-      }
+  async createWindow(options) {
+    const previouslyFocusedWindow =
+      options.focused === true
+        ? null
+        : (await chrome.windows.getAll()).find((window) => window.focused === true && typeof window.id === 'number') ?? null;
+    const previouslyFocusedTabs =
+      previouslyFocusedWindow?.id !== undefined ? await chrome.tabs.query({ windowId: previouslyFocusedWindow.id }) : [];
+    const previouslyFocusedTabIds = new Set(
+      previouslyFocusedTabs.flatMap((tab) => (typeof tab.id === 'number' ? [tab.id] : []))
+    );
+    const previouslyFocusedTab =
+      previouslyFocusedTabs.find((tab) => tab.active === true && typeof tab.id === 'number') ?? null;
+    const desiredUrl = options.url ?? 'about:blank';
+    let created = await chrome.windows.create({
+      url: desiredUrl,
+      focused: true
+    });
+    if (!created || typeof created.id !== 'number') {
+      throw new Error('Window missing id');
+    }
+    const pickSeedTab = async (windowId: number): Promise<chrome.tabs.Tab | null> => {
+      const tabs = await chrome.tabs.query({ windowId });
+      const newlyCreatedTab =
+        windowId === previouslyFocusedWindow?.id
+          ? tabs.find((tab) => typeof tab.id === 'number' && !previouslyFocusedTabIds.has(tab.id))
+          : null;
+      const normalizedDesiredUrl = normalizeComparableTabUrl(desiredUrl);
+      return (
+        newlyCreatedTab ??
+        tabs.find((tab) => {
+          const pendingUrl = 'pendingUrl' in tab && typeof tab.pendingUrl === 'string' ? tab.pendingUrl : '';
+          return normalizeComparableTabUrl(tab.url ?? pendingUrl) === normalizedDesiredUrl;
+        }) ??
+        tabs.find((tab) => tab.active === true && typeof tab.id === 'number') ??
+        tabs.find((tab) => typeof tab.id === 'number') ??
+        null
+      );
+    };
+    let seedTab = await pickSeedTab(created.id);
+    const createdWindowTabs = await chrome.tabs.query({ windowId: created.id });
+    const createdWindowReusedFocusedWindow = previouslyFocusedWindow?.id === created.id;
+    const createdWindowLooksDirty = createdWindowTabs.length > 1;
+    if ((createdWindowReusedFocusedWindow || createdWindowLooksDirty) && typeof seedTab?.id === 'number') {
+      created = await chrome.windows.create({
+        tabId: seedTab.id,
+        focused: true
+      });
+      if (!created || typeof created.id !== 'number') {
+        throw new Error('Lifted window missing id');
+      }
+      seedTab = await pickSeedTab(created.id);
+    }
+    if (options.focused !== true && previouslyFocusedWindow?.id && previouslyFocusedWindow.id !== created.id) {
+      await chrome.windows.update(previouslyFocusedWindow.id, { focused: true });
+      if (typeof previouslyFocusedTab?.id === 'number') {
+        await chrome.tabs.update(previouslyFocusedTab.id, { active: true });
+      }
     }
     const finalWindow = await chrome.windows.get(created.id);
-    return {
-      id: finalWindow.id!,
-      focused: Boolean(finalWindow.focused)
-    };
-  },
+    return {
+      id: finalWindow.id!,
+      focused: Boolean(finalWindow.focused),
+      initialTabId: seedTab?.id ?? null
+    };
+  },
   async updateWindow(windowId, options) {
     const updated = await chrome.windows.update(windowId, {
       focused: options.focused

package/src/popup.ts

@@ -1,8 +1,10 @@
 const statusEl = document.getElementById('status') as HTMLDivElement;
+const statusNoteEl = document.getElementById('statusNote') as HTMLDivElement;
 const tokenInput = document.getElementById('token') as HTMLInputElement;
 const portInput = document.getElementById('port') as HTMLInputElement;
 const debugRichTextInput = document.getElementById('debugRichText') as HTMLInputElement;
 const saveBtn = document.getElementById('save') as HTMLButtonElement;
+const saveRowEl = document.getElementById('saveRow') as HTMLDivElement;
 const reconnectBtn = document.getElementById('reconnect') as HTMLButtonElement;
 const disconnectBtn = document.getElementById('disconnect') as HTMLButtonElement;
 const connectionStateEl = document.getElementById('connectionState') as HTMLDivElement;
@@ -50,9 +52,25 @@ interface PopupState {
 }
 let latestState: PopupState | null = null;
 
-function setStatus(text: string, bad = false): void {
+function setStatus(text: string, tone: 'neutral' | 'success' | 'warning' | 'error' = 'neutral'): void {
   statusEl.textContent = text;
-  statusEl.style.color = bad ? '#dc2626' : '#0f172a';
+  if (tone === 'success') {
+    statusEl.style.color = '#166534';
+    return;
+  }
+  if (tone === 'warning') {
+    statusEl.style.color = '#b45309';
+    return;
+  }
+  if (tone === 'error') {
+    statusEl.style.color = '#dc2626';
+    return;
+  }
+  statusEl.style.color = '#0f172a';
+}
+
+function pluralize(count: number, singular: string, plural = `${singular}s`): string {
+  return `${count} ${count === 1 ? singular : plural}`;
 }
 
 function formatTimeAgo(at: number | null): string {
@@ -75,7 +93,11 @@ function formatTimeAgo(at: number | null): string {
 }
 
 function renderSessionBindings(state: PopupState['sessionBindings']): void {
-  sessionSummaryEl.textContent = `${state.count} sessions, ${state.attachedCount} attached, ${state.tabCount} tabs, ${state.detachedCount} detached`;
+  if (state.count === 0) {
+    sessionSummaryEl.textContent = 'No remembered sessions';
+  } else {
+    sessionSummaryEl.textContent = `${pluralize(state.count, 'session')}, ${pluralize(state.attachedCount, 'attached binding')}, ${pluralize(state.tabCount, 'tab')}, ${pluralize(state.detachedCount, 'detached binding')}`;
+  }
   sessionListEl.replaceChildren();
   for (const item of state.items) {
     const li = document.createElement('li');
@@ -89,8 +111,26 @@ function renderSessionBindings(state: PopupState['sessionBindings']): void {
   }
 }
 
+function describeConnectionState(connectionState: PopupState['connectionState']): string {
+  switch (connectionState) {
+    case 'connected':
+      return 'connected';
+    case 'connecting':
+      return 'waiting for runtime';
+    case 'reconnecting':
+      return 'retrying connection';
+    case 'manual':
+      return 'manually disconnected';
+    case 'missing-token':
+      return 'token required';
+    case 'disconnected':
+    default:
+      return 'disconnected';
+  }
+}
+
 function renderConnectionDetails(state: PopupState): void {
-  connectionStateEl.textContent = state.connectionState;
+  connectionStateEl.textContent = describeConnectionState(state.connectionState);
   tokenStateEl.textContent = state.hasToken ? 'configured' : 'missing';
   connectionUrlEl.textContent = state.wsUrl;
   extensionVersionEl.textContent = state.extensionVersion;
@@ -120,42 +160,130 @@ function renderConnectionDetails(state: PopupState): void {
   }
 }
 
+function parsePortValue(): number | null {
+  const port = Number.parseInt(portInput.value.trim(), 10);
+  return Number.isInteger(port) && port > 0 ? port : null;
+}
+
+function isFormDirty(state: PopupState | null): boolean {
+  if (!state) {
+    return tokenInput.value.trim().length > 0;
+  }
+  return (
+    tokenInput.value.trim().length > 0 ||
+    portInput.value.trim() !== String(state.port) ||
+    debugRichTextInput.checked !== Boolean(state.debugRichText)
+  );
+}
+
+function getConfigValidationMessage(state: PopupState | null): string | null {
+  if (!tokenInput.value.trim() && state?.hasToken !== true) {
+    return 'Pair token is required';
+  }
+  if (parsePortValue() === null) {
+    return 'Port is invalid';
+  }
+  return null;
+}
+
+function updateSaveState(state: PopupState | null): void {
+  const dirty = isFormDirty(state);
+  const validationError = getConfigValidationMessage(state);
+  saveRowEl.hidden = !dirty;
+  saveBtn.disabled = !dirty || validationError !== null;
+  saveBtn.textContent = state?.hasToken ? 'Save settings' : 'Save token';
+}
+
+function describeStatus(state: PopupState): { text: string; note: string; tone: 'neutral' | 'success' | 'warning' | 'error' } {
+  const combinedError = `${state.lastErrorContext ?? ''} ${state.lastError ?? ''}`.toLowerCase();
+  const runtimeOffline = combinedError.includes('cannot connect to bak cli');
+
+  if (state.connected) {
+    return {
+      text: 'Connected to local bak runtime',
+      note: 'Use the bak CLI to start browser work. This popup is mainly for status and configuration.',
+      tone: 'success'
+    };
+  }
+
+  if (state.connectionState === 'missing-token') {
+    return {
+      text: 'Pair token is required',
+      note: 'Paste a token once, then save it. Future reconnects happen automatically.',
+      tone: 'error'
+    };
+  }
+
+  if (state.connectionState === 'manual') {
+    return {
+      text: 'Extension bridge is paused',
+      note: 'Normal browser work starts from the bak CLI. Open Advanced only if you need to reconnect manually.',
+      tone: 'warning'
+    };
+  }
+
+  if (runtimeOffline) {
+    return {
+      text: 'Waiting for local bak runtime',
+      note: 'Run any bak command, such as `bak doctor`, and the extension will reconnect automatically.',
+      tone: 'warning'
+    };
+  }
+
+  if (state.connectionState === 'reconnecting') {
+    return {
+      text: 'Trying to reconnect',
+      note: 'The extension is retrying in the background. You usually do not need to press anything here.',
+      tone: 'warning'
+    };
+  }
+
+  if (state.lastError) {
+    return {
+      text: 'Connection problem',
+      note: 'Check the last error below. The extension keeps retrying automatically unless you disconnect it manually.',
+      tone: 'error'
+    };
+  }
+
+  return {
+    text: 'Not connected yet',
+    note: 'Once the local bak runtime is available, the extension reconnects automatically.',
+    tone: 'neutral'
+  };
+}
+
 async function refreshState(): Promise<void> {
   const state = (await chrome.runtime.sendMessage({ type: 'bak.getState' })) as PopupState;
 
   if (state.ok) {
+    const shouldSyncForm = !isFormDirty(latestState);
     latestState = state;
-    portInput.value = String(state.port);
-    debugRichTextInput.checked = Boolean(state.debugRichText);
+    if (shouldSyncForm) {
+      portInput.value = String(state.port);
+      debugRichTextInput.checked = Boolean(state.debugRichText);
+      tokenInput.value = '';
+    }
     renderConnectionDetails(state);
     renderSessionBindings(state.sessionBindings);
-    if (state.connected) {
-      setStatus('Connected to bak CLI');
-    } else if (state.connectionState === 'missing-token') {
-      setStatus('Pair token is required', true);
-    } else if (state.connectionState === 'manual') {
-      setStatus('Disconnected manually');
-    } else if (state.connectionState === 'reconnecting') {
-      setStatus('Reconnecting to bak CLI', true);
-    } else if (state.lastError) {
-      setStatus(`Disconnected: ${state.lastError}`, true);
-    } else {
-      setStatus('Disconnected');
-    }
+    updateSaveState(state);
+    const status = describeStatus(state);
+    setStatus(status.text, status.tone);
+    statusNoteEl.textContent = status.note;
   }
 }
 
 saveBtn.addEventListener('click', async () => {
   const token = tokenInput.value.trim();
-  const port = Number.parseInt(portInput.value.trim(), 10);
+  const port = parsePortValue();
 
   if (!token && latestState?.hasToken !== true) {
-    setStatus('Pair token is required', true);
+    setStatus('Pair token is required', 'error');
     return;
   }
 
-  if (!Number.isInteger(port) || port <= 0) {
-    setStatus('Port is invalid', true);
+  if (port === null) {
+    setStatus('Port is invalid', 'error');
     return;
   }
 
@@ -180,6 +308,15 @@ disconnectBtn.addEventListener('click', async () => {
   await refreshState();
 });
 
+for (const element of [tokenInput, portInput, debugRichTextInput]) {
+  element.addEventListener('input', () => {
+    updateSaveState(latestState);
+  });
+  element.addEventListener('change', () => {
+    updateSaveState(latestState);
+  });
+}
+
 void refreshState();
 const refreshInterval = window.setInterval(() => {
   void refreshState();

package/src/session-binding.ts

@@ -16,10 +16,11 @@ export interface SessionBindingTab {
   groupId: number | null;
 }
 
-export interface SessionBindingWindow {
-  id: number;
-  focused: boolean;
-}
+export interface SessionBindingWindow {
+  id: number;
+  focused: boolean;
+  initialTabId?: number | null;
+}
 
 export interface SessionBindingGroup {
   id: number;
@@ -143,27 +144,31 @@ class SessionBindingManager {
         }
       }
     }
-    if (!window) {
-      const createdWindow = await this.browser.createWindow({
-        url: initialUrl,
-        focused: options.focus === true
-      });
+    if (!window) {
+      const createdWindow = await this.browser.createWindow({
+        url: initialUrl,
+        focused: options.focus === true
+      });
       state.windowId = createdWindow.id;
-      state.groupId = null;
-      state.tabIds = [];
-      state.activeTabId = null;
-      state.primaryTabId = null;
-      window = createdWindow;
-      tabs = await this.waitForWindowTabs(createdWindow.id);
-      state.tabIds = tabs.map((tab) => tab.id);
-      if (state.primaryTabId === null) {
-        state.primaryTabId = tabs[0]?.id ?? null;
-      }
-      if (state.activeTabId === null) {
-        state.activeTabId = tabs.find((tab) => tab.active)?.id ?? tabs[0]?.id ?? null;
-      }
-      repairActions.push(created ? 'created-window' : 'recreated-window');
-    }
+      state.groupId = null;
+      state.tabIds = [];
+      state.activeTabId = null;
+      state.primaryTabId = null;
+      window = createdWindow;
+      const initialTab =
+        typeof createdWindow.initialTabId === 'number'
+          ? await this.waitForTrackedTab(createdWindow.initialTabId, createdWindow.id)
+          : null;
+      tabs = initialTab ? [initialTab] : await this.waitForWindowTabs(createdWindow.id);
+      state.tabIds = tabs.map((tab) => tab.id);
+      if (state.primaryTabId === null) {
+        state.primaryTabId = initialTab?.id ?? tabs[0]?.id ?? null;
+      }
+      if (state.activeTabId === null) {
+        state.activeTabId = tabs.find((tab) => tab.active)?.id ?? initialTab?.id ?? tabs[0]?.id ?? null;
+      }
+      repairActions.push(created ? 'created-window' : 'recreated-window');
+    }
 
     tabs = tabs.length > 0 ? tabs : await this.readTrackedTabs(state.tabIds, state.windowId);
     const recoveredTabs = await this.recoverBindingTabs(state, tabs);
@@ -725,19 +730,21 @@ class SessionBindingManager {
     };
   }
 
-  private async moveBindingIntoDedicatedWindow(
-    state: SessionBindingRecord,
-    ownership: SessionBindingWindowOwnership,
-    initialUrl: string
-  ): Promise<{ window: SessionBindingWindow; tabs: SessionBindingTab[] }> {
+  private async moveBindingIntoDedicatedWindow(
+    state: SessionBindingRecord,
+    ownership: SessionBindingWindowOwnership,
+    initialUrl: string
+  ): Promise<{ window: SessionBindingWindow; tabs: SessionBindingTab[] }> {
     const sourceTabs = this.orderSessionBindingTabsForMigration(state, ownership.bindingTabs);
     const seedUrl = sourceTabs[0]?.url ?? initialUrl;
-    const window = await this.browser.createWindow({
-      url: seedUrl || DEFAULT_SESSION_BINDING_URL,
-      focused: false
-    });
-      const recreatedTabs = await this.waitForWindowTabs(window.id);
-    const firstTab = recreatedTabs[0] ?? null;
+    const window = await this.browser.createWindow({
+      url: seedUrl || DEFAULT_SESSION_BINDING_URL,
+      focused: false
+    });
+    const initialTab =
+      typeof window.initialTabId === 'number' ? await this.waitForTrackedTab(window.initialTabId, window.id) : null;
+    const recreatedTabs = initialTab ? [initialTab] : await this.waitForWindowTabs(window.id);
+    const firstTab = recreatedTabs[0] ?? null;
     const tabIdMap = new Map<number, number>();
     if (sourceTabs[0] && firstTab) {
       tabIdMap.set(sourceTabs[0].id, firstTab.id);