opendevbrowser 0.0.16 → 0.0.18

package/extension/dist/background.js

@@ -3,10 +3,21 @@ import { NativePortManager } from "./services/NativePortManager.js";
 import { DEFAULT_AUTO_CONNECT, DEFAULT_AUTO_PAIR, DEFAULT_DISCOVERY_PORT, DEFAULT_NATIVE_ENABLED, DEFAULT_PAIRING_ENABLED, DEFAULT_RELAY_PORT } from "./relay-settings.js";
 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();
+let canvasRuntime;
 const opsRuntime = new OpsRuntime({
     send: (message) => connection.sendOpsMessage(message),
-    cdp: connection.getCdpRouter()
+    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) => {
@@ -22,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;
@@ -29,12 +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" });
@@ -43,16 +63,9 @@ connection.onAnnotationCommand((command) => {
 connection.onOpsMessage((message) => {
     opsRuntime.handleMessage(message);
 });
-const RESTRICTED_PROTOCOLS = new Set([
-    "chrome:",
-    "chrome-extension:",
-    "chrome-search:",
-    "chrome-untrusted:",
-    "devtools:",
-    "chrome-devtools:",
-    "edge:",
-    "brave:"
-]);
+connection.onCanvasMessage((message) => {
+    canvasRuntime.handleMessage(message);
+});
 const updateBadge = (status) => {
     const isConnected = status === "connected";
     const dotColor = isConnected ? BADGE_CONNECTED_DOT_COLOR : BADGE_DISCONNECTED_DOT_COLOR;
@@ -139,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.";
@@ -149,13 +172,15 @@ 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":
             return "Annotation channel disconnected. Keep the extension open and retry.";
         case "ops_disconnected":
             return "Ops channel disconnected. Start a new session and retry.";
+        case "canvas_disconnected":
+            return "Canvas channel disconnected. Reopen the design canvas command and retry.";
         case "cdp_disconnected":
             return "No CDP clients connected. Start a session and retry.";
         case "relay_down":
@@ -243,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 {
@@ -303,6 +316,7 @@ const fetchRelayHealth = async (port) => {
         const cdpConnected = data.cdpConnected === true;
         const annotationConnected = data.annotationConnected === true;
         const opsConnected = data.opsConnected === true;
+        const canvasConnected = data.canvasConnected === true;
         const pairingRequired = data.pairingRequired === true;
         const ok = extensionConnected && handshake;
         return {
@@ -313,6 +327,7 @@ const fetchRelayHealth = async (port) => {
             cdpConnected,
             annotationConnected,
             opsConnected,
+            canvasConnected,
             pairingRequired
         };
     }
@@ -432,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) {
@@ -456,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");
     }
@@ -474,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) => {
@@ -516,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.
@@ -541,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;
@@ -554,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." };
     }
@@ -568,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) {
@@ -578,7 +831,7 @@ const probeAnnotationInjected = async () => {
     }
 };
 const toggleAnnotationUi = async () => {
-    const tab = await getActiveTab();
+    const tab = await getPreferredAnnotationTab();
     if (!tab || typeof tab.id !== "number") {
         return;
     }
@@ -587,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;
@@ -620,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,
@@ -632,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");
     }
 };
@@ -660,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,
@@ -675,19 +927,7 @@ const validatePayloadSize = (payload) => {
 const generateAnnotationRequestId = () => {
     return crypto.randomUUID();
 };
-const stripScreenshots = (payload) => {
-    const { screenshots, annotations, ...rest } = payload;
-    void screenshots;
-    return {
-        ...rest,
-        annotations: annotations.map((item) => {
-            const { screenshotId, ...restItem } = item;
-            void screenshotId;
-            return restItem;
-        })
-    };
-};
-const buildLastAnnotationMeta = (requestId, response, hasFullPayloadInMemory) => {
+const buildLastAnnotationMeta = (requestId, response, hasFullPayloadInMemory, extras = {}) => {
     const payload = response.payload;
     const annotationCount = payload ? payload.annotations.length : undefined;
     const screenshotCount = payload?.screenshots?.length ?? 0;
@@ -695,6 +935,9 @@ const buildLastAnnotationMeta = (requestId, response, hasFullPayloadInMemory) =>
         requestId,
         status: response.status,
         error: response.error,
+        receipt: extras.receipt ?? response.receipt,
+        source: extras.source,
+        label: extras.label,
         url: payload?.url,
         title: payload?.title,
         timestamp: payload?.timestamp,
@@ -712,6 +955,12 @@ const persistLastAnnotation = async (meta, payload) => {
         [LAST_ANNOTATION_PAYLOAD_KEY]: payload
     });
 };
+const persistAgentAnnotation = async (meta, payload) => {
+    await setStorage({
+        [LAST_AGENT_ANNOTATION_META_KEY]: meta,
+        [LAST_AGENT_ANNOTATION_PAYLOAD_KEY]: payload
+    });
+};
 const loadPersistedLastAnnotation = async () => {
     const data = await new Promise((resolve) => {
         chrome.storage.local.get([LAST_ANNOTATION_META_KEY, LAST_ANNOTATION_PAYLOAD_KEY], (items) => resolve(items));
@@ -722,6 +971,108 @@ const loadPersistedLastAnnotation = async () => {
     const payload = payloadRecord && typeof payloadRecord === "object" ? payloadRecord : null;
     return { meta, payload };
 };
+const loadPersistedAgentAnnotation = async () => {
+    const data = await new Promise((resolve) => {
+        chrome.storage.local.get([LAST_AGENT_ANNOTATION_META_KEY, LAST_AGENT_ANNOTATION_PAYLOAD_KEY], (items) => resolve(items));
+    });
+    const metaRecord = data[LAST_AGENT_ANNOTATION_META_KEY];
+    const payloadRecord = data[LAST_AGENT_ANNOTATION_PAYLOAD_KEY];
+    const meta = metaRecord && typeof metaRecord === "object" ? metaRecord : null;
+    const payload = payloadRecord && typeof payloadRecord === "object" ? payloadRecord : null;
+    return { meta, payload };
+};
+const isAnnotationPayload = (value) => {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const payload = value;
+    return typeof payload.url === "string"
+        && typeof payload.timestamp === "string"
+        && typeof payload.screenshotMode === "string"
+        && Array.isArray(payload.annotations);
+};
+const storeAgentAnnotationPayload = async (payload, source, label, receipt) => {
+    if (!validatePayloadSize(payload)) {
+        throw new Error("Annotation payload exceeded size limits.");
+    }
+    const response = {
+        version: 1,
+        requestId: receipt?.receiptId ?? crypto.randomUUID(),
+        status: "ok",
+        payload,
+        receipt
+    };
+    const meta = buildLastAnnotationMeta(response.requestId, response, true, {
+        source,
+        label: label?.trim().length ? label.trim() : formatDispatchSourceLabel(source),
+        receipt
+    });
+    lastAgentAnnotationFull = { meta, 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 {
+            version: 1,
+            requestId: crypto.randomUUID(),
+            status: "ok",
+            payload: lastAgentAnnotationFull.payload
+        };
+    }
+    if (lastAgentAnnotationFull) {
+        return {
+            version: 1,
+            requestId: crypto.randomUUID(),
+            status: "ok",
+            payload: stripAnnotationPayloadScreenshots(lastAgentAnnotationFull.payload)
+        };
+    }
+    const stored = await loadPersistedAgentAnnotation();
+    if (stored.payload) {
+        return {
+            version: 1,
+            requestId: crypto.randomUUID(),
+            status: "ok",
+            payload: stored.payload
+        };
+    }
+    return {
+        version: 1,
+        requestId: crypto.randomUUID(),
+        status: "error",
+        error: { code: "payload_unavailable", message: "No agent-dispatched annotation payload available." }
+    };
+};
 async function handleNativePortMessage(payload) {
     if (!payload || typeof payload !== "object") {
         return;
@@ -746,6 +1097,14 @@ const handleRelayAnnotationCommand = async (command, transport = "relay") => {
         await cancelAnnotationSession(payload.requestId, transport);
         return;
     }
+    if (payload.command === "fetch_stored") {
+        const stored = await loadAgentAnnotationPayload(payload.options?.includeScreenshots === true);
+        sendAnnotationResponse({
+            ...stored,
+            requestId: payload.requestId
+        }, transport);
+        return;
+    }
     try {
         await startAnnotationSession(payload, transport);
         sendAnnotationEvent({
@@ -805,7 +1164,7 @@ const handleAnnotationComplete = (requestId, payload) => {
     const meta = buildLastAnnotationMeta(requestId, response, true);
     lastAnnotationFull = { meta, payload };
     const storageMeta = { ...meta, hasFullPayloadInMemory: false };
-    const sanitizedPayload = stripScreenshots(payload);
+    const sanitizedPayload = stripAnnotationPayloadScreenshots(payload);
     persistLastAnnotation(storageMeta, sanitizedPayload).catch((error) => {
         logError("annotation.persist_sanitized_payload", error, { code: "annotation_persist_failed" });
     });
@@ -911,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;
@@ -976,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;
@@ -1031,6 +1392,9 @@ connection.onStatus((status) => {
             clearTimeout(session.timeoutId);
         }
         annotationSessions.clear();
+        if (autoConnectEnabled) {
+            scheduleRetry();
+        }
     }
 });
 updateBadge(getEffectiveStatus());
@@ -1066,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;
@@ -1077,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" });
@@ -1152,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);
@@ -1212,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" });
@@ -1237,9 +1639,9 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
             if (message.includeScreenshots) {
                 const response = {
                     type: "annotation:payloadResult",
-                    payload: null,
+                    payload: stored.payload,
                     meta: storedMeta,
-                    source: "none",
+                    source: stored.payload ? "storage" : "none",
                     warning: "Full payload not available; screenshots may have been dropped."
                 };
                 sendResponse(response);
@@ -1248,7 +1650,7 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
             if (lastAnnotationFull) {
                 const response = {
                     type: "annotation:payloadResult",
-                    payload: stripScreenshots(lastAnnotationFull.payload),
+                    payload: stripAnnotationPayloadScreenshots(lastAnnotationFull.payload),
                     meta: { ...lastAnnotationFull.meta, hasFullPayloadInMemory: true },
                     source: "memory"
                 };
@@ -1285,6 +1687,74 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
         });
         return true;
     }
+    if (message.type === "annotation:sendPayload") {
+        (async () => {
+            if (!isAnnotationPayload(message.payload)) {
+                const response = {
+                    type: "annotation:sendPayloadResult",
+                    ok: false,
+                    meta: null,
+                    receipt: null,
+                    error: { code: "invalid_request", message: "Invalid annotation payload." }
+                };
+                sendResponse(response);
+                return;
+            }
+            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 },
+                receipt
+            };
+            sendResponse(response);
+        })().catch((error) => {
+            const response = {
+                type: "annotation:sendPayloadResult",
+                ok: false,
+                meta: null,
+                receipt: null,
+                error: {
+                    code: "payload_too_large",
+                    message: error instanceof Error ? error.message : "Annotation dispatch failed."
+                }
+            };
+            sendResponse(response);
+        });
+        return true;
+    }
     if (message.type === "annotation:capture") {
         (async () => {
             const tab = sender.tab;
@@ -1319,3 +1789,8 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
     }
     return false;
 });
+chrome.runtime.onConnect.addListener((port) => {
+    if (port.name === "canvas-page") {
+        canvasRuntime.attachPort(port);
+    }
+});