tabctl 0.6.0-rc.7 → 0.6.0-rc.8

package/README.md

@@ -170,7 +170,7 @@ tabctl query 'query { inspectTabs(tabIds: [456], signals: ["page-meta"]) { entri
 tabctl query 'query { inspectTabs(windowId: 123, selectors: [{ name: "prices", selector: ".price", attr: "text", all: true }, { name: "buy_now_visible", selector: "button.buy-now", attr: "visible" }, { name: "buy_now_style", selector: "button.buy-now", attr: "styles", styleProps: ["color", "background-color"] }, { name: "review_count", selector: ".review", attr: "count" }, { name: "email_value", selector: "input[type=email]", attr: "value" }]) { entries { tabId url signals { name valueJson } } } }'
 
 # Read tab content as Markdown (Kreuzberg preprocessing by default)
-tabctl query 'query { readTabs(windowId: 123, extract: true, maxChars: 30000) { entries { tabId title url markdown chars truncated extracted status emptyReason diagnostics { sourceHtmlChars sourceTextChars documentReadyState truncatedHtml } error } } }'
+tabctl query 'query { readTabs(windowId: 123, extract: true, maxChars: 30000) { entries { tabId title url markdown chars truncated extracted cached status emptyReason diagnostics { source sourceHtmlChars sourceTextChars documentReadyState truncatedHtml cachedAt cacheAgeMs } error } } }'
 
 # Generate reports
 tabctl query '{ reportTabs(windowId: 123) { entries { tabId title url description } } }'
@@ -427,7 +427,8 @@ Notes:
 - Browser reads and mutations now go through GraphQL via `tabctl query`.
 - Reports include short descriptions from page metadata and a fallback snippet.
 - `inspectTabs` supports `page-meta` plus selector reads with `all`, `text`, `textMode`, `styleProps`, and attrs such as `html`, `value`, `count`, `box`, `styles`, `visible`, `enabled`, and `checked`.
-- `readTabs` converts main-frame page HTML to Markdown with Kreuzberg `html-to-markdown`; per-tab `status`, `emptyReason`, `diagnostics`, and `error` distinguish empty pages, unsupported URLs, injection failures, conversion failures, and timeouts.
+- `readTabs` converts main-frame page HTML to Markdown with Kreuzberg `html-to-markdown`; per-tab `status`, `emptyReason`, `diagnostics`, and `error` distinguish empty pages, unsupported URLs, injection failures, conversion failures, timeouts, and cached fallbacks (`status: CACHED`, `cached: true`, `diagnostics.source: "cache"`).
+- Cached fallbacks use a bounded profile-local open-tab HTML cache refreshed after successful reads, active tab switches, and quiescent active pages; diagnostics include cache age and match mode when cached content is used.
 - `captureScreenshots` returns tile metadata and image data from GraphQL.
 - `undoAction` accepts either an explicit `txid` or `latest: true`.
 - `tabctl history --json` returns a top-level JSON array.

package/dist/extension/background.js

@@ -341,7 +341,8 @@
     extractPageHtml: () => extractPageHtml,
     extractPageMarkdown: () => extractPageMarkdown,
     extractPageMeta: () => extractPageMeta,
-    extractSelectorSignal: () => extractSelectorSignal
+    extractSelectorSignal: () => extractSelectorSignal,
+    probePageQuiescence: () => probePageQuiescence
   });
   function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -485,6 +486,114 @@
       error: null
     };
   }
+  async function probePageQuiescence(tabId, timeoutMs, sampleWindowMs) {
+    const result = await executeWithTimeoutDetailed(tabId, timeoutMs, async (rawWindowMs) => {
+      const startedAt = Date.now();
+      const windowMs = Math.max(50, Math.min(Number(rawWindowMs) || 350, 1500));
+      const htmlCap = 25e4;
+      const sample = () => {
+        const root = document.documentElement;
+        const bodyText = document.body?.innerText || root?.textContent || "";
+        const html = root?.outerHTML || "";
+        const resources = typeof performance !== "undefined" && typeof performance.getEntriesByType === "function" ? performance.getEntriesByType("resource").length : null;
+        return {
+          textChars: bodyText.length,
+          htmlChars: Math.min(html.length, htmlCap),
+          domElements: document.getElementsByTagName("*").length,
+          resourceCount: resources
+        };
+      };
+      const waitForIdleWindow = () => new Promise((resolve) => {
+        const win = window;
+        const done = () => setTimeout(resolve, windowMs);
+        if (typeof win.requestIdleCallback === "function") {
+          let resolved = false;
+          const finish = () => {
+            if (resolved) {
+              return;
+            }
+            resolved = true;
+            done();
+          };
+          const fallback = setTimeout(finish, windowMs + 100);
+          win.requestIdleCallback(() => {
+            clearTimeout(fallback);
+            finish();
+          }, { timeout: windowMs });
+          return;
+        }
+        setTimeout(resolve, windowMs);
+      });
+      try {
+        const readyState = document.readyState;
+        if (readyState !== "interactive" && readyState !== "complete") {
+          return {
+            quiet: false,
+            reason: "not-ready",
+            documentReadyState: readyState,
+            before: null,
+            after: null,
+            elapsedMs: Date.now() - startedAt,
+            error: null
+          };
+        }
+        const before = sample();
+        await waitForIdleWindow();
+        const after = sample();
+        const stable = before.textChars === after.textChars && before.htmlChars === after.htmlChars && before.domElements === after.domElements && before.resourceCount === after.resourceCount;
+        return {
+          quiet: stable,
+          reason: stable ? "stable" : "changed",
+          documentReadyState: document.readyState,
+          before,
+          after,
+          elapsedMs: Date.now() - startedAt,
+          error: null
+        };
+      } catch (err) {
+        return {
+          quiet: false,
+          reason: "probe-error",
+          documentReadyState: typeof document !== "undefined" ? document.readyState : null,
+          before: null,
+          after: null,
+          elapsedMs: Date.now() - startedAt,
+          error: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }, [sampleWindowMs]);
+    if (result.kind === "timeout") {
+      return {
+        quiet: false,
+        reason: "timed-out",
+        documentReadyState: null,
+        before: null,
+        after: null,
+        elapsedMs: timeoutMs,
+        error: `Timed out after ${timeoutMs}ms`
+      };
+    }
+    if (result.kind === "error") {
+      return {
+        quiet: false,
+        reason: "injection-error",
+        documentReadyState: null,
+        before: null,
+        after: null,
+        elapsedMs: 0,
+        error: result.message
+      };
+    }
+    return result.value ?? {
+      quiet: false,
+      reason: "no-result",
+      documentReadyState: null,
+      before: null,
+      after: null,
+      elapsedMs: 0,
+      error: "Content script returned no quiescence probe payload"
+    };
+  }
   async function extractSelectorSignal(tabId, specs, timeoutMs, selectorValueMaxLength) {
     if (!specs.length) {
       return null;
@@ -674,6 +783,18 @@
   var RECONNECT_ALARM = "tabctl-reconnect";
   var KEEPALIVE_INTERVAL_MINUTES = 1;
   var BROWSER_STATE_SYNC_DEBOUNCE_MS = 750;
+  var ACTIVE_PAGE_CACHE_DEBOUNCE_MS = 1e3;
+  var ACTIVE_PAGE_CACHE_TIMEOUT_MS = 5e3;
+  var MAX_PAGE_HTML_CHARS = 15e5;
+  var ACTIVE_PAGE_CACHE_MAX_HTML_CHARS = MAX_PAGE_HTML_CHARS;
+  var ACTIVE_PAGE_CACHE_QUIESCENT_DELAY_MS = 6e3;
+  var ACTIVE_PAGE_CACHE_QUIESCENT_RETRY_MS = 1e3;
+  var ACTIVE_PAGE_CACHE_QUIESCENT_TIMEOUT_MS = 2500;
+  var ACTIVE_PAGE_CACHE_QUIESCENT_SAMPLE_MS = 350;
+  var ACTIVE_PAGE_CACHE_QUIESCENT_COOLDOWN_MS = 3e4;
+  var ACTIVE_PAGE_CACHE_STATUS_TIMEOUT_MS = 3e4;
+  var CACHE_AVAILABLE_BADGE_TEXT = "C";
+  var CACHE_AVAILABLE_BADGE_COLOR = "#2da44e";
   var RECONNECT_INITIAL_DELAY_MS = 250;
   var RECONNECT_MAX_DELAY_MS = 3e4;
   var RECONNECT_ALARM_MIN_DELAY_MS = 3e4;
@@ -701,6 +822,18 @@
     incognitoTabIds: /* @__PURE__ */ new Set(),
     incognitoGroupIds: /* @__PURE__ */ new Set()
   };
+  var activePageCache = {
+    nextId: 1,
+    timer: null,
+    pending: null,
+    quiescentTimer: null,
+    quiescentPending: null,
+    inFlightKeys: /* @__PURE__ */ new Set(),
+    lastCapturedKey: null,
+    lastQuiescentCapturedKey: null,
+    lastQuiescentCapturedAt: 0,
+    statusRequests: /* @__PURE__ */ new Map()
+  };
   function log(...args) {
     console.log("[tabctl]", ...args);
   }
@@ -781,6 +914,9 @@
       state.port = port;
       resetReconnectBackoffAfterStablePort(port);
       port.onMessage.addListener((message) => {
+        if (handlePageCacheStatusMessage(message)) {
+          return;
+        }
         void handleNativeMessage(port, message);
       });
       port.onDisconnect.addListener(() => {
@@ -793,11 +929,13 @@
         if (state.port === port) {
           state.port = null;
         }
+        activePageCache.statusRequests.clear();
         clearReconnectStableTimer();
         scheduleReconnect("disconnect");
       });
       log("Native host connected");
       queueBrowserStateSync("startup");
+      void refreshActivePageCacheIndicator("connectNative");
     } catch (error) {
       log("Native host connection failed", error);
       scheduleReconnect("connect-failed");
@@ -808,6 +946,360 @@
     browserState.nextId += 1;
     return `browser-state-${Date.now()}-${id}`;
   }
+  function nextActivePageCacheId() {
+    const id = activePageCache.nextId;
+    activePageCache.nextId += 1;
+    return `page-cache-capture-${Date.now()}-${id}`;
+  }
+  function nextActivePageCacheStatusId() {
+    const id = activePageCache.nextId;
+    activePageCache.nextId += 1;
+    return `page-cache-status-${Date.now()}-${id}`;
+  }
+  function trackPageCacheStatusRequest(id, tabId, url) {
+    activePageCache.statusRequests.set(id, { tabId, url });
+    setTimeout(() => {
+      activePageCache.statusRequests.delete(id);
+    }, ACTIVE_PAGE_CACHE_STATUS_TIMEOUT_MS);
+  }
+  function isScriptableUrl(url) {
+    const lower = url.toLowerCase();
+    return lower.startsWith("http://") || lower.startsWith("https://");
+  }
+  function activePageCacheKey(tab, url) {
+    return `${tab.id}:${url}`;
+  }
+  function activePageCacheUrl(tab) {
+    return tab.url || tab.pendingUrl || "";
+  }
+  async function tabUrlMatches(tabId, expectedUrl) {
+    try {
+      return activePageCacheUrl(await chrome.tabs.get(tabId)) === expectedUrl;
+    } catch {
+      return false;
+    }
+  }
+  async function clearCacheAvailableIndicator(tabId) {
+    try {
+      await chrome.action?.setBadgeText?.({ tabId, text: "" });
+      await chrome.action?.setTitle?.({ tabId, title: "Tab Control" });
+    } catch (error) {
+      log("clear cache indicator failed", { tabId, error });
+    }
+  }
+  async function setCacheAvailableIndicator(tabId, expectedUrl) {
+    try {
+      const tab = await chrome.tabs.get(tabId);
+      if (!isEligibleActivePageCacheTab(tab) || activePageCacheUrl(tab) !== expectedUrl) {
+        await clearCacheAvailableIndicator(tabId);
+        return;
+      }
+      await chrome.action?.setBadgeBackgroundColor?.({ tabId, color: CACHE_AVAILABLE_BADGE_COLOR });
+      await chrome.action?.setBadgeText?.({ tabId, text: CACHE_AVAILABLE_BADGE_TEXT });
+      await chrome.action?.setTitle?.({ tabId, title: "Tab Control - page cache available" });
+    } catch (error) {
+      log("set cache indicator failed", { tabId, error });
+    }
+  }
+  async function applyPageCacheStatus(tabId, expectedUrl, available) {
+    try {
+      const tab = await chrome.tabs.get(tabId);
+      if (activePageCacheUrl(tab) !== expectedUrl) {
+        return;
+      }
+      if (!isEligibleActivePageCacheTab(tab) || !available) {
+        await clearCacheAvailableIndicator(tabId);
+        return;
+      }
+      await setCacheAvailableIndicator(tabId, expectedUrl);
+    } catch {
+      await clearCacheAvailableIndicator(tabId);
+    }
+  }
+  function handlePageCacheStatusMessage(message) {
+    if (!message || typeof message !== "object" || message.action) {
+      return false;
+    }
+    const requestId = typeof message.id === "string" ? message.id : "";
+    const pending = activePageCache.statusRequests.get(requestId);
+    if (!pending) {
+      return false;
+    }
+    activePageCache.statusRequests.delete(requestId);
+    const data = message.data && typeof message.data === "object" ? message.data : {};
+    const tabId = typeof data.tabId === "number" ? data.tabId : pending.tabId;
+    const url = typeof data.url === "string" ? data.url : pending.url;
+    const available = message.ok === true && data.available === true && tabId === pending.tabId && url === pending.url;
+    void applyPageCacheStatus(pending.tabId, pending.url, available);
+    return true;
+  }
+  function requestPageCacheStatus(tab, reason) {
+    const url = activePageCacheUrl(tab);
+    if (typeof tab.id !== "number" || !isEligibleActivePageCacheTab(tab)) {
+      if (typeof tab.id === "number") {
+        void clearCacheAvailableIndicator(tab.id);
+      }
+      return;
+    }
+    const port = state.port;
+    if (!port) {
+      connectNative();
+      void clearCacheAvailableIndicator(tab.id);
+      return;
+    }
+    const id = nextActivePageCacheStatusId();
+    trackPageCacheStatusRequest(id, tab.id, url);
+    port.postMessage({
+      id,
+      action: "page-cache-status",
+      ok: true,
+      data: {
+        reason,
+        requestedAt: Date.now(),
+        tab: {
+          tabId: tab.id,
+          url,
+          incognito: tab.incognito || false,
+          discarded: tab.discarded || false,
+          status: tab.status || null
+        }
+      }
+    });
+  }
+  async function requestPageCacheStatusForTab(tabId, reason) {
+    try {
+      requestPageCacheStatus(await chrome.tabs.get(tabId), reason);
+    } catch {
+      await clearCacheAvailableIndicator(tabId);
+    }
+  }
+  async function refreshActivePageCacheIndicator(reason) {
+    try {
+      const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+      if (tab) {
+        requestPageCacheStatus(tab, reason);
+      }
+    } catch (error) {
+      log("active page cache indicator refresh failed", { reason, error });
+    }
+  }
+  function urlMismatchPageHtmlResponse(expectedUrl) {
+    return {
+      status: "URL_MISMATCH",
+      html: "",
+      sourceHtmlChars: 0,
+      sourceTextChars: 0,
+      documentReadyState: null,
+      truncatedHtml: false,
+      error: `Tab URL changed before page HTML extraction completed: expected ${expectedUrl}`
+    };
+  }
+  function isEligibleActivePageCacheTab(tab) {
+    const url = activePageCacheUrl(tab);
+    return typeof tab.id === "number" && Boolean(url) && tab.incognito !== true && !browserState.incognitoTabIds.has(tab.id) && (typeof tab.windowId !== "number" || !browserState.incognitoWindowIds.has(tab.windowId)) && tab.discarded !== true && tab.status !== "loading" && isScriptableUrl(url);
+  }
+  function clearPendingActivePageCacheCapture() {
+    if (activePageCache.timer) {
+      clearTimeout(activePageCache.timer);
+      activePageCache.timer = null;
+    }
+    activePageCache.pending = null;
+  }
+  function clearPendingQuiescentActivePageCacheCapture() {
+    if (activePageCache.quiescentTimer) {
+      clearTimeout(activePageCache.quiescentTimer);
+      activePageCache.quiescentTimer = null;
+    }
+    activePageCache.quiescentPending = null;
+  }
+  function isQuiescentCaptureCoolingDown(key) {
+    return activePageCache.lastQuiescentCapturedKey === key && Date.now() - activePageCache.lastQuiescentCapturedAt < ACTIVE_PAGE_CACHE_QUIESCENT_COOLDOWN_MS;
+  }
+  function scheduleQuiescentActivePageCacheCapture(tab, reason, key) {
+    if (isQuiescentCaptureCoolingDown(key)) {
+      return;
+    }
+    clearPendingQuiescentActivePageCacheCapture();
+    activePageCache.quiescentPending = {
+      tabId: tab.id,
+      key,
+      reason: `${reason}:quiescent`,
+      attempts: 0
+    };
+    activePageCache.quiescentTimer = setTimeout(() => {
+      activePageCache.quiescentTimer = null;
+      const pending = activePageCache.quiescentPending;
+      activePageCache.quiescentPending = null;
+      if (pending) {
+        void captureQuiescentActivePageCache(pending);
+      }
+    }, ACTIVE_PAGE_CACHE_QUIESCENT_DELAY_MS);
+  }
+  function scheduleActivePageCacheCapture(tab, reason) {
+    if (!isEligibleActivePageCacheTab(tab)) {
+      if (typeof tab.id === "number") {
+        void clearCacheAvailableIndicator(tab.id);
+      }
+      clearPendingActivePageCacheCapture();
+      clearPendingQuiescentActivePageCacheCapture();
+      return;
+    }
+    requestPageCacheStatus(tab, reason);
+    const url = activePageCacheUrl(tab);
+    const key = activePageCacheKey(tab, url);
+    scheduleQuiescentActivePageCacheCapture(tab, reason, key);
+    if (activePageCache.inFlightKeys.has(key) || activePageCache.lastCapturedKey === key) {
+      return;
+    }
+    clearPendingActivePageCacheCapture();
+    activePageCache.pending = { tab, reason, key };
+    activePageCache.timer = setTimeout(() => {
+      activePageCache.timer = null;
+      const pending = activePageCache.pending;
+      activePageCache.pending = null;
+      if (pending) {
+        void captureActivePageCache(pending.tab, pending.reason, pending.key);
+      }
+    }, ACTIVE_PAGE_CACHE_DEBOUNCE_MS);
+  }
+  async function scheduleActivePageCacheCaptureForTab(tabId, reason) {
+    try {
+      scheduleActivePageCacheCapture(await chrome.tabs.get(tabId), reason);
+    } catch (error) {
+      log("active page cache tab lookup failed", { tabId, reason, error });
+      await clearCacheAvailableIndicator(tabId);
+    }
+  }
+  async function scheduleActivePageCacheCaptureForWindow(windowId, reason) {
+    if (windowId === chrome.windows.WINDOW_ID_NONE) {
+      return;
+    }
+    try {
+      const [tab] = await chrome.tabs.query({ active: true, windowId });
+      if (tab) {
+        scheduleActivePageCacheCapture(tab, reason);
+      }
+    } catch (error) {
+      log("active page cache window lookup failed", { windowId, reason, error });
+    }
+  }
+  async function currentActivePageCacheTab(tabId, key) {
+    try {
+      const tab = await chrome.tabs.get(tabId);
+      const url = activePageCacheUrl(tab);
+      if (!tab.active || !isEligibleActivePageCacheTab(tab) || activePageCacheKey(tab, url) !== key) {
+        return null;
+      }
+      return tab;
+    } catch {
+      return null;
+    }
+  }
+  async function rescheduleQuiescentActivePageCacheCapture(pending) {
+    if (pending.attempts >= 2 || isQuiescentCaptureCoolingDown(pending.key)) {
+      return;
+    }
+    activePageCache.quiescentPending = { ...pending, attempts: pending.attempts + 1 };
+    activePageCache.quiescentTimer = setTimeout(() => {
+      activePageCache.quiescentTimer = null;
+      const retry = activePageCache.quiescentPending;
+      activePageCache.quiescentPending = null;
+      if (retry) {
+        void captureQuiescentActivePageCache(retry);
+      }
+    }, ACTIVE_PAGE_CACHE_QUIESCENT_RETRY_MS);
+  }
+  async function captureQuiescentActivePageCache(pending) {
+    if (isQuiescentCaptureCoolingDown(pending.key)) {
+      return;
+    }
+    if (activePageCache.inFlightKeys.has(pending.key)) {
+      await rescheduleQuiescentActivePageCacheCapture(pending);
+      return;
+    }
+    const tab = await currentActivePageCacheTab(pending.tabId, pending.key);
+    if (!tab) {
+      return;
+    }
+    const probe = await content.probePageQuiescence(
+      tab.id,
+      ACTIVE_PAGE_CACHE_QUIESCENT_TIMEOUT_MS,
+      ACTIVE_PAGE_CACHE_QUIESCENT_SAMPLE_MS
+    );
+    if (!probe.quiet) {
+      await rescheduleQuiescentActivePageCacheCapture(pending);
+      return;
+    }
+    const captured = await captureActivePageCache(tab, pending.reason, pending.key);
+    if (captured) {
+      activePageCache.lastQuiescentCapturedKey = pending.key;
+      activePageCache.lastQuiescentCapturedAt = Date.now();
+    }
+  }
+  async function captureActivePageCache(tab, reason, key) {
+    if (!state.port) {
+      connectNative();
+      return false;
+    }
+    if (!isEligibleActivePageCacheTab(tab) || activePageCache.inFlightKeys.has(key)) {
+      return false;
+    }
+    activePageCache.inFlightKeys.add(key);
+    try {
+      const captureTab = await currentActivePageCacheTab(tab.id, key);
+      if (!captureTab) {
+        return false;
+      }
+      const extraction = await content.extractPageHtml(captureTab.id, ACTIVE_PAGE_CACHE_TIMEOUT_MS, ACTIVE_PAGE_CACHE_MAX_HTML_CHARS);
+      if (extraction.status !== "READ" || typeof extraction.html !== "string" || extraction.html.length === 0) {
+        void requestPageCacheStatusForTab(captureTab.id, `${reason}:capture-failed`);
+        return false;
+      }
+      const verifiedTab = await currentActivePageCacheTab(captureTab.id, key);
+      if (!verifiedTab) {
+        return false;
+      }
+      const port = state.port;
+      if (!port) {
+        return false;
+      }
+      const id = nextActivePageCacheId();
+      trackPageCacheStatusRequest(id, verifiedTab.id, activePageCacheUrl(verifiedTab));
+      port.postMessage({
+        id,
+        action: "page-cache-capture",
+        ok: true,
+        data: {
+          reason,
+          capturedAt: Date.now(),
+          tab: {
+            tabId: verifiedTab.id,
+            windowId: verifiedTab.windowId,
+            index: verifiedTab.index,
+            url: activePageCacheUrl(verifiedTab),
+            title: verifiedTab.title,
+            groupId: verifiedTab.groupId,
+            favIconUrl: verifiedTab.favIconUrl || null,
+            status: verifiedTab.status || null,
+            pinned: verifiedTab.pinned || false,
+            active: verifiedTab.active || false,
+            incognito: verifiedTab.incognito || false,
+            discarded: verifiedTab.discarded || false,
+            lastAccessedAt: verifiedTab.lastAccessed || null
+          },
+          extraction
+        }
+      });
+      activePageCache.lastCapturedKey = key;
+      return true;
+    } catch (error) {
+      log("active page cache capture failed", { tabId: tab.id, reason, error });
+      void requestPageCacheStatusForTab(tab.id, `${reason}:capture-error`);
+      return false;
+    } finally {
+      activePageCache.inFlightKeys.delete(key);
+    }
+  }
   function normalizeEventPayload(kind, payload) {
     const event = {
       kind,
@@ -924,6 +1416,12 @@
         incognito: tab.incognito,
         changeInfo
       });
+      if ("url" in changeInfo || "status" in changeInfo || "discarded" in changeInfo) {
+        void clearCacheAvailableIndicator(tabId);
+      }
+      if (tab.active && ("url" in changeInfo || "status" in changeInfo || "discarded" in changeInfo)) {
+        scheduleActivePageCacheCapture(tab, "tabs.onUpdated");
+      }
     });
     chrome.tabs?.onMoved?.addListener((tabId, moveInfo) => {
       enqueueBrowserStateEvent("tabs.onMoved", {
@@ -953,12 +1451,19 @@
         windowId: removeInfo.windowId,
         isWindowClosing: removeInfo.isWindowClosing
       });
+      activePageCache.statusRequests.forEach((pending, requestId) => {
+        if (pending.tabId === tabId) {
+          activePageCache.statusRequests.delete(requestId);
+        }
+      });
+      void clearCacheAvailableIndicator(tabId);
     });
     chrome.tabs?.onActivated?.addListener((activeInfo) => {
       enqueueBrowserStateEvent("tabs.onActivated", {
         tabId: activeInfo.tabId,
         windowId: activeInfo.windowId
       });
+      void scheduleActivePageCacheCaptureForTab(activeInfo.tabId, "tabs.onActivated");
     });
     chrome.tabGroups?.onCreated?.addListener((group) => {
       enqueueBrowserStateEvent("tabGroups.onCreated", {
@@ -1009,6 +1514,7 @@
     });
     chrome.windows?.onFocusChanged?.addListener((windowId) => {
       enqueueBrowserStateEvent("windows.onFocusChanged", { windowId });
+      void scheduleActivePageCacheCaptureForWindow(windowId, "windows.onFocusChanged");
     });
   }
   connectNative();
@@ -1141,9 +1647,17 @@
       }
       case "p:page-html": {
         const targetTabId = requireFiniteId(params.tabId, "tabId");
-        const maxHtmlChars = typeof params.maxHtmlChars === "number" ? Math.max(1, Math.min(params.maxHtmlChars, 65e4)) : 5e5;
+        const expectedUrl = typeof params.expectedUrl === "string" ? params.expectedUrl : "";
+        const maxHtmlChars = typeof params.maxHtmlChars === "number" ? Math.max(1, Math.min(params.maxHtmlChars, MAX_PAGE_HTML_CHARS)) : 5e5;
         const timeoutMs = typeof params.timeoutMs === "number" ? Math.max(1, params.timeoutMs) : 15e3;
-        return await content.extractPageHtml(targetTabId, timeoutMs, maxHtmlChars);
+        if (expectedUrl && !await tabUrlMatches(targetTabId, expectedUrl)) {
+          return urlMismatchPageHtmlResponse(expectedUrl);
+        }
+        const result = await content.extractPageHtml(targetTabId, timeoutMs, maxHtmlChars);
+        if (expectedUrl && !await tabUrlMatches(targetTabId, expectedUrl)) {
+          return urlMismatchPageHtmlResponse(expectedUrl);
+        }
+        return result;
       }
       default:
         throw new Error(`Unknown action: ${action}`);

package/dist/extension/lib/content.js

@@ -7,6 +7,7 @@ exports.executeWithTimeoutDetailed = executeWithTimeoutDetailed;
 exports.extractPageMeta = extractPageMeta;
 exports.extractPageMarkdown = extractPageMarkdown;
 exports.extractPageHtml = extractPageHtml;
+exports.probePageQuiescence = probePageQuiescence;
 exports.extractSelectorSignal = extractSelectorSignal;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -153,6 +154,120 @@ async function extractPageHtml(tabId, timeoutMs, maxHtmlChars) {
         error: null,
     };
 }
+async function probePageQuiescence(tabId, timeoutMs, sampleWindowMs) {
+    const result = await executeWithTimeoutDetailed(tabId, timeoutMs, async (rawWindowMs) => {
+        const startedAt = Date.now();
+        const windowMs = Math.max(50, Math.min(Number(rawWindowMs) || 350, 1_500));
+        const htmlCap = 250_000;
+        const sample = () => {
+            const root = document.documentElement;
+            const bodyText = document.body?.innerText || root?.textContent || "";
+            const html = root?.outerHTML || "";
+            const resources = typeof performance !== "undefined" && typeof performance.getEntriesByType === "function"
+                ? performance.getEntriesByType("resource").length
+                : null;
+            return {
+                textChars: bodyText.length,
+                htmlChars: Math.min(html.length, htmlCap),
+                domElements: document.getElementsByTagName("*").length,
+                resourceCount: resources,
+            };
+        };
+        const waitForIdleWindow = () => new Promise((resolve) => {
+            const win = window;
+            const done = () => setTimeout(resolve, windowMs);
+            if (typeof win.requestIdleCallback === "function") {
+                let resolved = false;
+                const finish = () => {
+                    if (resolved) {
+                        return;
+                    }
+                    resolved = true;
+                    done();
+                };
+                const fallback = setTimeout(finish, windowMs + 100);
+                win.requestIdleCallback(() => {
+                    clearTimeout(fallback);
+                    finish();
+                }, { timeout: windowMs });
+                return;
+            }
+            setTimeout(resolve, windowMs);
+        });
+        try {
+            const readyState = document.readyState;
+            if (readyState !== "interactive" && readyState !== "complete") {
+                return {
+                    quiet: false,
+                    reason: "not-ready",
+                    documentReadyState: readyState,
+                    before: null,
+                    after: null,
+                    elapsedMs: Date.now() - startedAt,
+                    error: null,
+                };
+            }
+            const before = sample();
+            await waitForIdleWindow();
+            const after = sample();
+            const stable = before.textChars === after.textChars
+                && before.htmlChars === after.htmlChars
+                && before.domElements === after.domElements
+                && before.resourceCount === after.resourceCount;
+            return {
+                quiet: stable,
+                reason: stable ? "stable" : "changed",
+                documentReadyState: document.readyState,
+                before,
+                after,
+                elapsedMs: Date.now() - startedAt,
+                error: null,
+            };
+        }
+        catch (err) {
+            return {
+                quiet: false,
+                reason: "probe-error",
+                documentReadyState: typeof document !== "undefined" ? document.readyState : null,
+                before: null,
+                after: null,
+                elapsedMs: Date.now() - startedAt,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }, [sampleWindowMs]);
+    if (result.kind === "timeout") {
+        return {
+            quiet: false,
+            reason: "timed-out",
+            documentReadyState: null,
+            before: null,
+            after: null,
+            elapsedMs: timeoutMs,
+            error: `Timed out after ${timeoutMs}ms`,
+        };
+    }
+    if (result.kind === "error") {
+        return {
+            quiet: false,
+            reason: "injection-error",
+            documentReadyState: null,
+            before: null,
+            after: null,
+            elapsedMs: 0,
+            error: result.message,
+        };
+    }
+    return result.value ?? {
+        quiet: false,
+        reason: "no-result",
+        documentReadyState: null,
+        before: null,
+        after: null,
+        elapsedMs: 0,
+        error: "Content script returned no quiescence probe payload",
+    };
+}
 async function extractSelectorSignal(tabId, specs, timeoutMs, selectorValueMaxLength) {
     if (!specs.length) {
         return null;

package/dist/extension/manifest.json

@@ -19,5 +19,8 @@
   "background": {
     "service_worker": "background.js"
   },
-  "version_name": "0.6.0-rc.7"
+  "action": {
+    "default_title": "Tab Control"
+  },
+  "version_name": "0.6.0-rc.8"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tabctl",
-  "version": "0.6.0-rc.7",
+  "version": "0.6.0-rc.8",
   "description": "CLI tool to manage and analyze browser tabs",
   "license": "MIT",
   "repository": {
@@ -53,7 +53,7 @@
     "typescript": "^5.4.5"
   },
   "optionalDependencies": {
-    "tabctl-win32-x64": "0.6.0-rc.7"
+    "tabctl-win32-x64": "0.6.0-rc.8"
   },
   "dependencies": {
     "normalize-url": "^8.1.1"