opendevbrowser 0.0.17 → 0.0.19

package/extension/dist/background.js

@@ -5,16 +5,20 @@ import { logError } from "./logging.js";
 import { OpsRuntime } from "./ops/ops-runtime.js";
 import { CanvasRuntime } from "./canvas/canvas-runtime.js";
 import { formatDispatchSourceLabel, stripAnnotationPayloadScreenshots } from "./annotation-payload.js";
+import { getRestrictionMessage } from "./services/url-restrictions.js";
 const connection = new ConnectionManager();
-const canvasRuntime = new CanvasRuntime({
-    send: (message) => connection.sendCanvasMessage(message)
-});
+let canvasRuntime;
 const opsRuntime = new OpsRuntime({
     send: (message) => connection.sendOpsMessage(message),
     cdp: connection.getCdpRouter(),
     getCanvasPageState: (targetId) => canvasRuntime.getPageStateByTargetId(targetId),
     performCanvasPageAction: (targetId, action, selector) => canvasRuntime.performPageAction(targetId, action, selector)
 });
+canvasRuntime = new CanvasRuntime({
+    send: (message) => connection.sendCanvasMessage(message),
+    registerOpsCanvasTarget: (browserSessionId, targetId) => opsRuntime.registerCanvasTargetForSession(browserSessionId, targetId),
+    unregisterOpsCanvasTarget: (browserSessionId, targetId) => opsRuntime.unregisterCanvasTargetForSession(browserSessionId, targetId)
+});
 const nativePort = new NativePortManager({
     onMessage: (payload) => {
         handleNativePortMessage(payload).catch((error) => {
@@ -29,6 +33,7 @@ let autoConnectInFlight = false;
 let statusNoteOverride = null;
 let retryScheduled = false;
 let retryDelayMs = 5000;
+let autoConnectEnabled = DEFAULT_AUTO_CONNECT;
 let nativeEnabled = DEFAULT_NATIVE_ENABLED;
 const RETRY_ALARM_NAME = "opendevbrowser-auto-connect";
 const RETRY_MAX_MS = 60_000;
@@ -36,15 +41,20 @@ const ANNOTATION_CONTENT_SCRIPT = "dist/annotate-content.js";
 const ANNOTATION_CONTENT_STYLE = "dist/annotate-content.css";
 const ANNOTATION_MAX_PAYLOAD_BYTES = 10 * 1024 * 1024;
 const ANNOTATION_REQUEST_TIMEOUT_MS = 120_000;
+const ANNOTATION_RECEIVER_UNAVAILABLE_MESSAGE = "Annotation UI did not load in the page. Reload the tab and retry.";
 const LAST_ANNOTATION_META_KEY = "annotationLastMeta";
 const LAST_ANNOTATION_PAYLOAD_KEY = "annotationLastPayloadSansScreenshots";
 const LAST_AGENT_ANNOTATION_META_KEY = "annotationAgentMeta";
 const LAST_AGENT_ANNOTATION_PAYLOAD_KEY = "annotationAgentPayloadSansScreenshots";
+const LAST_ANNOTATABLE_TAB_ID_KEY = "annotationLastTabId";
+const POPUP_ANNOTATION_TARGET_TTL_MS = 10_000;
 const BADGE_CONNECTED_DOT_COLOR = "#16a34a";
 const BADGE_DISCONNECTED_DOT_COLOR = "#dc2626";
 const annotationSessions = new Map();
 let lastAnnotationFull = null;
 let lastAgentAnnotationFull = null;
+let lastAnnotatableTabId = null;
+let lastPopupAnnotationTarget = null;
 connection.onAnnotationCommand((command) => {
     handleRelayAnnotationCommand(command).catch((error) => {
         logError("annotation.relay_command", error, { code: "annotation_command_failed" });
@@ -56,16 +66,6 @@ connection.onOpsMessage((message) => {
 connection.onCanvasMessage((message) => {
     canvasRuntime.handleMessage(message);
 });
-const RESTRICTED_PROTOCOLS = new Set([
-    "chrome:",
-    "chrome-extension:",
-    "chrome-search:",
-    "chrome-untrusted:",
-    "devtools:",
-    "chrome-devtools:",
-    "edge:",
-    "brave:"
-]);
 const updateBadge = (status) => {
     const isConnected = status === "connected";
     const dotColor = isConnected ? BADGE_CONNECTED_DOT_COLOR : BADGE_DISCONNECTED_DOT_COLOR;
@@ -152,6 +152,16 @@ const setStorage = (items) => {
 const setStatusNoteOverride = (note) => {
     statusNoteOverride = note;
 };
+const loadStoredAnnotatableTabId = async () => {
+    const data = await new Promise((resolve) => {
+        chrome.storage.local.get([LAST_ANNOTATABLE_TAB_ID_KEY], (items) => resolve(items));
+    });
+    const value = data[LAST_ANNOTATABLE_TAB_ID_KEY];
+    return typeof value === "number" && Number.isInteger(value) ? value : null;
+};
+const persistAnnotatableTabId = async (tabId) => {
+    await setStorage({ [LAST_ANNOTATABLE_TAB_ID_KEY]: tabId });
+};
 const buildRelayHealthNote = (health) => {
     if (!health) {
         return "Relay unreachable. Start the daemon and retry.";
@@ -162,7 +172,7 @@ const buildRelayHealthNote = (health) => {
         case "pairing_required":
             return "Pairing required. Enable auto-pair or set the token.";
         case "handshake_incomplete":
-            return "Extension handshake pending. Keep the relay running and retry.";
+            return "Extension websocket is up but the daemon-extension handshake is incomplete. Open the popup and click Connect again to re-establish a clean handshake, then confirm `status --daemon` shows ext=on and handshake=on.";
         case "extension_disconnected":
             return "Extension not connected to relay. Click Connect.";
         case "annotation_disconnected":
@@ -258,23 +268,11 @@ const parseEpoch = (value) => {
     }
     return null;
 };
-const isWebStoreUrl = (url) => {
-    if (url.hostname === "chromewebstore.google.com") {
-        return true;
-    }
-    if (url.hostname === "chrome.google.com" && url.pathname.startsWith("/webstore")) {
-        return true;
-    }
-    return false;
-};
-const getRestrictionMessage = (url) => {
-    if (RESTRICTED_PROTOCOLS.has(url.protocol)) {
-        return "Active tab uses a restricted URL scheme. Open a normal http(s) page and retry.";
-    }
-    if (isWebStoreUrl(url)) {
-        return "Chrome Web Store tabs cannot be annotated. Open a normal tab and retry.";
-    }
-    return null;
+const getAnnotationRestrictionMessage = (url) => {
+    return getRestrictionMessage(url, {
+        restrictedSchemeMessage: "Active tab uses a restricted URL scheme. Open a normal http(s) page and retry.",
+        webStoreMessage: "Chrome Web Store tabs cannot be annotated. Open a normal tab and retry."
+    });
 };
 const fetchRelayConfig = async (port) => {
     try {
@@ -449,10 +447,166 @@ const waitForTabComplete = async (tabId, timeoutMs = 10000) => {
         chrome.tabs.onUpdated.addListener(listener);
     });
 };
+const waitForAnnotationTabReady = async (tabId) => {
+    const tab = await getTab(tabId);
+    if (!tab || tab.status === "complete") {
+        return;
+    }
+    try {
+        await waitForTabComplete(tabId);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "Tab load timeout") {
+            throw new Error("Active tab is still loading. Wait for it to finish and retry.");
+        }
+        throw error;
+    }
+};
 const getActiveTab = async () => {
     const tabs = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
     return tabs[0] ?? null;
 };
+const getTabRecency = (tab) => {
+    return typeof tab.lastAccessed === "number" ? tab.lastAccessed : -1;
+};
+const rememberAnnotatableTab = (tab) => {
+    if (!tab || typeof tab.id !== "number") {
+        return;
+    }
+    if (isRestrictedTab(tab) !== null) {
+        if (lastAnnotatableTabId === tab.id) {
+            lastAnnotatableTabId = null;
+            void persistAnnotatableTabId(null).catch((error) => {
+                logError("annotation.persist_tab", error, { code: "annotation_tab_persist_failed", extra: { tabId: null } });
+            });
+        }
+        return;
+    }
+    lastAnnotatableTabId = tab.id;
+    void persistAnnotatableTabId(tab.id).catch((error) => {
+        logError("annotation.persist_tab", error, { code: "annotation_tab_persist_failed", extra: { tabId: tab.id } });
+    });
+};
+const getRememberedAnnotatableTab = async (excludeTabId) => {
+    if (typeof lastAnnotatableTabId !== "number") {
+        lastAnnotatableTabId = await loadStoredAnnotatableTabId();
+    }
+    if (typeof lastAnnotatableTabId !== "number") {
+        return null;
+    }
+    if (typeof excludeTabId === "number" && lastAnnotatableTabId === excludeTabId) {
+        return null;
+    }
+    const tabId = lastAnnotatableTabId;
+    const tab = await getTab(tabId);
+    if (!tab || isRestrictedTab(tab) !== null) {
+        if (lastAnnotatableTabId === tabId) {
+            lastAnnotatableTabId = null;
+            void persistAnnotatableTabId(null).catch((error) => {
+                logError("annotation.persist_tab", error, { code: "annotation_tab_persist_failed", extra: { tabId: null } });
+            });
+        }
+        return null;
+    }
+    return tab;
+};
+const clearPopupAnnotationTarget = (tabId) => {
+    if (!lastPopupAnnotationTarget) {
+        return;
+    }
+    if (typeof tabId === "number" && lastPopupAnnotationTarget.tabId !== tabId) {
+        return;
+    }
+    lastPopupAnnotationTarget = null;
+};
+const rememberPopupAnnotationTarget = (tabId, bootId) => {
+    const previousBootId = lastPopupAnnotationTarget?.tabId === tabId
+        ? lastPopupAnnotationTarget.bootId
+        : null;
+    lastPopupAnnotationTarget = {
+        tabId,
+        bootId: typeof bootId === "string" ? bootId : previousBootId,
+        resolvedAt: Date.now()
+    };
+};
+const getCachedPopupAnnotationTab = async () => {
+    const cached = lastPopupAnnotationTarget;
+    if (!cached) {
+        return null;
+    }
+    if (Date.now() - cached.resolvedAt > POPUP_ANNOTATION_TARGET_TTL_MS) {
+        clearPopupAnnotationTarget(cached.tabId);
+        return null;
+    }
+    const tab = await getTab(cached.tabId);
+    if (!tab || isRestrictedTab(tab) !== null) {
+        clearPopupAnnotationTarget(cached.tabId);
+        return null;
+    }
+    return tab;
+};
+const getPopupAnnotationTab = async (tabIdHint) => {
+    const cached = await getCachedPopupAnnotationTab();
+    if (cached) {
+        rememberAnnotatableTab(cached);
+        return cached;
+    }
+    if (typeof tabIdHint === "number") {
+        const hinted = await getTab(tabIdHint);
+        if (hinted && isRestrictedTab(hinted) === null) {
+            rememberAnnotatableTab(hinted);
+            if (typeof hinted.id === "number") {
+                rememberPopupAnnotationTarget(hinted.id);
+            }
+            return hinted;
+        }
+    }
+    const preferred = await getPreferredAnnotationTab();
+    if (preferred && typeof preferred.id === "number") {
+        rememberPopupAnnotationTarget(preferred.id);
+    }
+    return preferred;
+};
+const getMostRecentAnnotatableTab = async (excludeTabId) => {
+    const tabs = await chrome.tabs.query({});
+    const candidates = tabs
+        .filter((tab) => {
+        if (typeof tab.id !== "number") {
+            return false;
+        }
+        if (typeof excludeTabId === "number" && tab.id === excludeTabId) {
+            return false;
+        }
+        return isRestrictedTab(tab) === null;
+    })
+        .sort((left, right) => {
+        const recencyDelta = getTabRecency(right) - getTabRecency(left);
+        if (recencyDelta !== 0) {
+            return recencyDelta;
+        }
+        const activeDelta = Number(Boolean(right.active)) - Number(Boolean(left.active));
+        if (activeDelta !== 0) {
+            return activeDelta;
+        }
+        return (right.id ?? 0) - (left.id ?? 0);
+    });
+    return candidates[0] ?? null;
+};
+const getPreferredAnnotationTab = async () => {
+    const active = await getActiveTab();
+    if (active && isRestrictedTab(active) === null) {
+        rememberAnnotatableTab(active);
+        return active;
+    }
+    const excludeTabId = active && typeof active.id === "number" ? active.id : undefined;
+    const remembered = await getRememberedAnnotatableTab(excludeTabId);
+    if (remembered) {
+        return remembered;
+    }
+    const fallback = await getMostRecentAnnotatableTab(excludeTabId);
+    rememberAnnotatableTab(fallback);
+    return fallback ?? active;
+};
 const resolveAnnotationTab = async (command) => {
     if (typeof command.tabId === "number") {
         if (command.url) {
@@ -473,7 +627,7 @@ const resolveAnnotationTab = async (command) => {
         }
         return created;
     }
-    const active = await getActiveTab();
+    const active = await getPreferredAnnotationTab();
     if (!active) {
         throw new Error("No active tab available");
     }
@@ -491,7 +645,7 @@ const isRestrictedTab = (tab) => {
         logError("annotation.parse_tab_url", error, { code: "tab_url_parse_failed" });
         return "Active tab URL is invalid.";
     }
-    return getRestrictionMessage(parsed);
+    return getAnnotationRestrictionMessage(parsed);
 };
 const injectAnnotationAssets = async (tabId) => {
     await new Promise((resolve, reject) => {
@@ -533,20 +687,56 @@ const isMissingAnnotationReceiverError = (error) => {
     }
     return error.message.includes("Receiving end does not exist");
 };
+const readAnnotationBridgeStatus = (response) => {
+    if (typeof response !== "object" || response === null) {
+        return null;
+    }
+    const candidate = response;
+    if (candidate.ok !== true || typeof candidate.bootId !== "string" || typeof candidate.active !== "boolean") {
+        return null;
+    }
+    return {
+        ok: true,
+        bootId: candidate.bootId,
+        active: candidate.active
+    };
+};
+const sendAnnotationMessageToTab = async (tabId, message) => {
+    try {
+        return await sendMessageToTab(tabId, message);
+    }
+    catch (error) {
+        if (!isMissingAnnotationReceiverError(error)) {
+            throw error;
+        }
+        await ensureAnnotationInjected(tabId);
+        try {
+            return await sendMessageToTab(tabId, message);
+        }
+        catch (retryError) {
+            if (isMissingAnnotationReceiverError(retryError)) {
+                throw new Error(ANNOTATION_RECEIVER_UNAVAILABLE_MESSAGE);
+            }
+            throw retryError;
+        }
+    }
+};
 const sleep = async (ms) => {
     await new Promise((resolve) => setTimeout(resolve, ms));
 };
 const pingAnnotation = async (tabId) => {
     const response = await sendMessageToTab(tabId, { type: "annotation:ping" });
-    const ok = typeof response === "object" && response !== null && response.ok === true;
-    if (!ok) {
+    const ready = readAnnotationBridgeStatus(response);
+    if (!ready) {
         throw new Error("Annotation ping failed");
     }
+    rememberPopupAnnotationTarget(tabId, ready.bootId);
+    return ready;
 };
 const ensureAnnotationInjected = async (tabId) => {
+    await waitForAnnotationTabReady(tabId);
     try {
-        await pingAnnotation(tabId);
-        return;
+        return await pingAnnotation(tabId);
     }
     catch (error) {
         // Initial ping can fail before content script injection; avoid noisy logs for missing receivers.
@@ -558,9 +748,9 @@ const ensureAnnotationInjected = async (tabId) => {
     let lastError = null;
     for (let attempt = 0; attempt <= backoff.length; attempt += 1) {
         try {
+            await waitForAnnotationTabReady(tabId);
             await injectAnnotationAssets(tabId);
-            await pingAnnotation(tabId);
-            return;
+            return await pingAnnotation(tabId);
         }
         catch (error) {
             lastError = error;
@@ -571,13 +761,55 @@ const ensureAnnotationInjected = async (tabId) => {
             }
         }
     }
+    if (isMissingAnnotationReceiverError(lastError)) {
+        throw new Error(ANNOTATION_RECEIVER_UNAVAILABLE_MESSAGE);
+    }
     if (lastError instanceof Error) {
         throw lastError;
     }
     throw new Error("Annotation injection failed");
 };
-const probeAnnotationInjected = async () => {
-    const active = await getActiveTab();
+const refreshAnnotationInjected = async (tabId) => {
+    await waitForAnnotationTabReady(tabId);
+    await injectAnnotationAssets(tabId);
+    return await pingAnnotation(tabId);
+};
+const startAnnotationUi = async (tabId, requestId, options, url) => {
+    let lastError = null;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const response = await sendAnnotationMessageToTab(tabId, {
+                type: "annotation:start",
+                requestId,
+                options: options ?? {},
+                url
+            });
+            const ready = readAnnotationBridgeStatus(response);
+            if (ready?.active) {
+                rememberPopupAnnotationTarget(tabId, ready.bootId);
+                return ready;
+            }
+            throw new Error("Annotation start acknowledgement missing active bridge.");
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === 0) {
+                await refreshAnnotationInjected(tabId);
+                continue;
+            }
+        }
+    }
+    if (isMissingAnnotationReceiverError(lastError)
+        || (lastError instanceof Error && lastError.message.includes("active bridge"))) {
+        throw new Error(ANNOTATION_RECEIVER_UNAVAILABLE_MESSAGE);
+    }
+    if (lastError instanceof Error) {
+        throw lastError;
+    }
+    throw new Error("Annotation start failed");
+};
+const probeAnnotationInjected = async (tabIdHint) => {
+    const active = await getPopupAnnotationTab(tabIdHint);
     if (!active || typeof active.id !== "number") {
         return { injected: false, detail: "No active tab available." };
     }
@@ -585,8 +817,12 @@ const probeAnnotationInjected = async () => {
     if (restricted) {
         return { injected: false, detail: restricted };
     }
+    if (active.status && active.status !== "complete") {
+        return { injected: false, detail: "Active tab is still loading." };
+    }
     try {
-        await pingAnnotation(active.id);
+        const ready = await pingAnnotation(active.id);
+        rememberPopupAnnotationTarget(active.id, ready.bootId);
         return { injected: true };
     }
     catch (error) {
@@ -595,7 +831,7 @@ const probeAnnotationInjected = async () => {
     }
 };
 const toggleAnnotationUi = async () => {
-    const tab = await getActiveTab();
+    const tab = await getPreferredAnnotationTab();
     if (!tab || typeof tab.id !== "number") {
         return;
     }
@@ -604,7 +840,7 @@ const toggleAnnotationUi = async () => {
         return;
     }
     await ensureAnnotationInjected(tab.id);
-    await sendMessageToTab(tab.id, { type: "annotation:toggle" });
+    await sendAnnotationMessageToTab(tab.id, { type: "annotation:toggle" });
 };
 const startAnnotationSession = async (command, transport) => {
     const requestId = command.requestId;
@@ -637,9 +873,11 @@ const startAnnotationSession = async (command, transport) => {
         }, transport);
         return;
     }
+    rememberAnnotatableTab(tab);
     let timeoutId = null;
     try {
-        await ensureAnnotationInjected(tab.id);
+        const initialBridge = await ensureAnnotationInjected(tab.id);
+        rememberPopupAnnotationTarget(tab.id, initialBridge.bootId);
         timeoutId = startAnnotationTimeout(requestId, transport);
         annotationSessions.set(requestId, {
             requestId,
@@ -649,18 +887,15 @@ const startAnnotationSession = async (command, transport) => {
             timeoutId,
             transport
         });
-        await sendMessageToTab(tab.id, {
-            type: "annotation:start",
-            requestId,
-            options: command.options ?? {},
-            url: command.url
-        });
+        const startedBridge = await startAnnotationUi(tab.id, requestId, command.options, command.url);
+        rememberPopupAnnotationTarget(tab.id, startedBridge.bootId);
     }
     catch (error) {
         if (timeoutId !== null) {
             clearTimeout(timeoutId);
         }
         annotationSessions.delete(requestId);
+        clearPopupAnnotationTarget(tab.id);
         throw error instanceof Error ? error : new Error("Annotation injection failed");
     }
 };
@@ -677,7 +912,7 @@ const cancelAnnotationSession = async (requestId, transport) => {
     }
     clearTimeout(session.timeoutId);
     annotationSessions.delete(requestId);
-    await sendMessageToTab(session.tabId, { type: "annotation:cancel", requestId });
+    await sendAnnotationMessageToTab(session.tabId, { type: "annotation:cancel", requestId });
     sendAnnotationResponse({
         version: 1,
         requestId,
@@ -700,6 +935,7 @@ const buildLastAnnotationMeta = (requestId, response, hasFullPayloadInMemory, ex
         requestId,
         status: response.status,
         error: response.error,
+        receipt: extras.receipt ?? response.receipt,
         source: extras.source,
         label: extras.label,
         url: payload?.url,
@@ -755,24 +991,55 @@ const isAnnotationPayload = (value) => {
         && typeof payload.screenshotMode === "string"
         && Array.isArray(payload.annotations);
 };
-const storeAgentAnnotationPayload = async (payload, source, label) => {
+const storeAgentAnnotationPayload = async (payload, source, label, receipt) => {
     if (!validatePayloadSize(payload)) {
         throw new Error("Annotation payload exceeded size limits.");
     }
     const response = {
         version: 1,
-        requestId: crypto.randomUUID(),
+        requestId: receipt?.receiptId ?? crypto.randomUUID(),
         status: "ok",
-        payload
+        payload,
+        receipt
     };
     const meta = buildLastAnnotationMeta(response.requestId, response, true, {
         source,
-        label: label?.trim().length ? label.trim() : formatDispatchSourceLabel(source)
+        label: label?.trim().length ? label.trim() : formatDispatchSourceLabel(source),
+        receipt
     });
     lastAgentAnnotationFull = { meta, payload };
-    await persistAgentAnnotation(meta, stripAnnotationPayloadScreenshots(payload));
+    await persistAgentAnnotation({ ...meta, hasFullPayloadInMemory: false }, stripAnnotationPayloadScreenshots(payload));
     return meta;
 };
+const buildStoredOnlyReceipt = (payload, source, label, reason) => {
+    const sanitizedPayload = stripAnnotationPayloadScreenshots(payload);
+    return {
+        receiptId: crypto.randomUUID(),
+        deliveryState: "stored_only",
+        storedFallback: true,
+        reason,
+        chatScopeKey: null,
+        createdAt: new Date().toISOString(),
+        itemCount: sanitizedPayload.annotations.length,
+        byteLength: new TextEncoder().encode(JSON.stringify(sanitizedPayload)).length,
+        source,
+        label: label?.trim().length ? label.trim() : formatDispatchSourceLabel(source)
+    };
+};
+const enqueueAgentPayload = async (payload, source, label) => {
+    const response = await connection.sendAnnotationCommand({
+        version: 1,
+        requestId: crypto.randomUUID(),
+        command: "store_agent_payload",
+        payload,
+        source,
+        label
+    });
+    if (response.status !== "ok" || !response.receipt) {
+        throw new Error(response.error?.code ?? response.error?.message ?? "relay_unavailable");
+    }
+    return response.receipt;
+};
 const loadAgentAnnotationPayload = async (includeScreenshots) => {
     if (includeScreenshots && lastAgentAnnotationFull) {
         return {
@@ -1003,6 +1270,7 @@ const attemptAutoConnect = async () => {
         });
     });
     const autoConnect = typeof data.autoConnect === "boolean" ? data.autoConnect : DEFAULT_AUTO_CONNECT;
+    autoConnectEnabled = autoConnect;
     if (!autoConnect || connection.getStatus() === "connected") {
         clearRetry();
         return;
@@ -1068,6 +1336,7 @@ const attemptAutoConnect = async () => {
                 if (config.instanceId && fetched.instanceId && config.instanceId !== fetched.instanceId) {
                     console.warn("[opendevbrowser] Relay instance mismatch during auto-pair. Retrying later.");
                     setStatusNoteOverride("Relay instance mismatch. Open the popup and click Connect.");
+                    scheduleRetry();
                     return;
                 }
                 const tokenEpoch = fetched.epoch ?? configEpoch;
@@ -1123,6 +1392,9 @@ connection.onStatus((status) => {
             clearTimeout(session.timeoutId);
         }
         annotationSessions.clear();
+        if (autoConnectEnabled) {
+            scheduleRetry();
+        }
     }
 });
 updateBadge(getEffectiveStatus());
@@ -1158,6 +1430,37 @@ if (chrome.commands?.onCommand) {
 autoConnect().catch((error) => {
     logError("auto_connect.startup", error, { code: "auto_connect_failed" });
 });
+void getActiveTab()
+    .then((tab) => {
+    rememberAnnotatableTab(tab);
+})
+    .catch((error) => {
+    logError("annotation.initial_tab", error, { code: "annotation_tab_resolution_failed" });
+});
+chrome.tabs.onActivated.addListener((activeInfo) => {
+    void getTab(activeInfo.tabId)
+        .then((tab) => {
+        rememberAnnotatableTab(tab);
+    })
+        .catch((error) => {
+        logError("annotation.tab_activated", error, { code: "annotation_tab_resolution_failed", extra: { tabId: activeInfo.tabId } });
+    });
+});
+chrome.tabs.onUpdated.addListener((tabId, _changeInfo, tab) => {
+    if (!tab.active && tabId !== lastAnnotatableTabId) {
+        return;
+    }
+    rememberAnnotatableTab(tab);
+});
+chrome.tabs.onRemoved.addListener((tabId) => {
+    if (lastAnnotatableTabId === tabId) {
+        lastAnnotatableTabId = null;
+        void persistAnnotatableTabId(null).catch((error) => {
+            logError("annotation.persist_tab", error, { code: "annotation_tab_persist_failed", extra: { tabId: null } });
+        });
+    }
+    clearPopupAnnotationTarget(tabId);
+});
 chrome.storage.onChanged.addListener((changes, area) => {
     if (area !== "local") {
         return;
@@ -1169,11 +1472,18 @@ chrome.storage.onChanged.addListener((changes, area) => {
         }
         updateBadge(getEffectiveStatus());
     }
+    if (changes.autoConnect) {
+        autoConnectEnabled =
+            typeof changes.autoConnect.newValue === "boolean" ? changes.autoConnect.newValue : DEFAULT_AUTO_CONNECT;
+    }
     if (changes.autoConnect?.newValue === true) {
         autoConnect().catch((error) => {
             logError("auto_connect.setting", error, { code: "auto_connect_failed" });
         });
     }
+    else if (changes.autoConnect?.newValue === false) {
+        clearRetry();
+    }
     if (changes.pairingToken) {
         autoConnect().catch((error) => {
             logError("auto_connect.pairing_token", error, { code: "auto_connect_failed" });
@@ -1244,7 +1554,7 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
                 ok: false
             };
             try {
-                const active = await getActiveTab();
+                const active = await getPopupAnnotationTab(message.tabId);
                 if (!active) {
                     response.error = { code: "invalid_request", message: "No active tab available." };
                     sendResponse(response);
@@ -1304,7 +1614,7 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
     }
     if (message.type === "annotation:probe") {
         (async () => {
-            const result = await probeAnnotationInjected();
+            const result = await probeAnnotationInjected(message.tabId);
             sendResponse({ type: "annotation:probeResult", ...result });
         })().catch((error) => {
             logError("annotation.probe", error, { code: "annotation_probe_failed" });
@@ -1384,16 +1694,50 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
                     type: "annotation:sendPayloadResult",
                     ok: false,
                     meta: null,
+                    receipt: null,
                     error: { code: "invalid_request", message: "Invalid annotation payload." }
                 };
                 sendResponse(response);
                 return;
             }
-            const meta = await storeAgentAnnotationPayload(message.payload, message.source ?? "popup_all", message.label);
+            const source = message.source ?? "popup_all";
+            let receipt;
+            try {
+                receipt = await enqueueAgentPayload(message.payload, source, message.label);
+            }
+            catch (error) {
+                const reason = error instanceof Error && error.message.trim().length > 0
+                    ? error.message.trim()
+                    : "relay_unavailable";
+                receipt = buildStoredOnlyReceipt(message.payload, source, message.label, reason);
+            }
+            let meta;
+            try {
+                meta = await storeAgentAnnotationPayload(message.payload, source, message.label, receipt);
+            }
+            catch (error) {
+                if (receipt.deliveryState !== "delivered") {
+                    throw error;
+                }
+                const response = {
+                    version: 1,
+                    requestId: receipt.receiptId,
+                    status: "ok",
+                    payload: message.payload,
+                    receipt
+                };
+                meta = buildLastAnnotationMeta(receipt.receiptId, response, true, {
+                    source,
+                    label: message.label?.trim().length ? message.label.trim() : formatDispatchSourceLabel(source),
+                    receipt
+                });
+                logError("annotation.store_agent_payload_optional", error, { code: "annotation_persist_failed" });
+            }
             const response = {
                 type: "annotation:sendPayloadResult",
                 ok: true,
-                meta: { ...meta, hasFullPayloadInMemory: true }
+                meta: { ...meta, hasFullPayloadInMemory: true },
+                receipt
             };
             sendResponse(response);
         })().catch((error) => {
@@ -1401,6 +1745,7 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
                 type: "annotation:sendPayloadResult",
                 ok: false,
                 meta: null,
+                receipt: null,
                 error: {
                     code: "payload_too_large",
                     message: error instanceof Error ? error.message : "Annotation dispatch failed."