@arraypress/extension-kit 1.10.0 → 1.11.1

package/src/panel/show-on-page.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A side panel's “Show on page”: which of the panel's items (a font, a
+ * colour) is boxed on the page, kept true whatever ends it. A click on the
+ * item's button shows it, a second click takes it away, another item's
+ * replaces it; a rescan or the panel closing clears the page's boxes
+ * (`reset`); and when the page clears them itself (Esc there, or the page
+ * left: the highlighter's `onClear` reasons `'escape'` and `'pagehide'`,
+ * sent to the panel as a message) the panel's button is released without
+ * calling the page back (`cleared`).
+ *
+ * @module panel/show-on-page
+ */
+export type ShowOnPageSetup = {
+    /**
+     * Boxes these on
+     * the page (the panel's own call into the tab's frames), scrolling the first into view in
+     * `revealFrame`; null takes the boxes away.
+     */
+    show: (ids: string[] | null, revealFrame?: number) => Promise<unknown>;
+    /**
+     * Hears which item is shown now (press its
+     * button, release the others).
+     */
+    onChange: (shown: string | null) => void;
+};
+export type ShowOnPage = {
+    /**
+     * The item shown, or null.
+     */
+    shown: () => string | null;
+    /**
+     * Show the item
+     * `id` (the page's `ids`), or take it away if it's the one shown. Rejects when the page can't be
+     * reached, with nothing shown.
+     */
+    toggle: (id: string, ids: string[], revealFrame?: number) => Promise<void>;
+    /**
+     * A rescan started, or the panel is closing: take the page's boxes
+     * away if any are shown. The call to the page starts at once (a closing panel still gets it out)
+     * and a failure is ignored (the tab is gone).
+     */
+    reset: () => Promise<void>;
+    /**
+     * The page says its boxes went: nothing is shown, and the page isn't called.
+     */
+    cleared: () => void;
+};
+/**
+ * @typedef {object} ShowOnPageSetup
+ * @property {(ids: string[] | null, revealFrame?: number) => Promise<unknown>} show Boxes these on
+ *   the page (the panel's own call into the tab's frames), scrolling the first into view in
+ *   `revealFrame`; null takes the boxes away.
+ * @property {(shown: string | null) => void} onChange Hears which item is shown now (press its
+ *   button, release the others).
+ */
+/**
+ * @typedef {object} ShowOnPage
+ * @property {() => string | null} shown The item shown, or null.
+ * @property {(id: string, ids: string[], revealFrame?: number) => Promise<void>} toggle Show the item
+ *   `id` (the page's `ids`), or take it away if it's the one shown. Rejects when the page can't be
+ *   reached, with nothing shown.
+ * @property {() => Promise<void>} reset A rescan started, or the panel is closing: take the page's boxes
+ *   away if any are shown. The call to the page starts at once (a closing panel still gets it out)
+ *   and a failure is ignored (the tab is gone).
+ * @property {() => void} cleared The page says its boxes went: nothing is shown, and the page isn't called.
+ */
+/**
+ * A panel's “Show on page” state.
+ *
+ * @param {ShowOnPageSetup} setup - How to box items on the page, and who hears what's shown.
+ * @returns {ShowOnPage} The controller.
+ * @example
+ * const onPage = createShowOnPage({
+ *   show: (ids, frame) => callPage('highlight', [ids, frame]),
+ *   onChange: (shown) => { for (const button of buttons) button.setAttribute('aria-pressed', String(button.dataset.id === shown)); },
+ * });
+ * button.addEventListener('click', () => onPage.toggle(font.id, [font.id], font.frameId));
+ * chrome.runtime.onMessage.addListener((message) => { if (message.type === 'boxes-cleared') onPage.cleared(); });
+ * addEventListener('pagehide', () => onPage.reset());
+ * await onPage.reset(); // before a rescan
+ */
+export declare function createShowOnPage({ show, onChange }: ShowOnPageSetup): ShowOnPage;

package/src/panel/show-on-page.js

@@ -0,0 +1,83 @@
+/**
+ * A side panel's “Show on page”: which of the panel's items (a font, a
+ * colour) is boxed on the page, kept true whatever ends it. A click on the
+ * item's button shows it, a second click takes it away, another item's
+ * replaces it; a rescan or the panel closing clears the page's boxes
+ * (`reset`); and when the page clears them itself (Esc there, or the page
+ * left: the highlighter's `onClear` reasons `'escape'` and `'pagehide'`,
+ * sent to the panel as a message) the panel's button is released without
+ * calling the page back (`cleared`).
+ *
+ * @module panel/show-on-page
+ */
+
+/**
+ * @typedef {object} ShowOnPageSetup
+ * @property {(ids: string[] | null, revealFrame?: number) => Promise<unknown>} show Boxes these on
+ *   the page (the panel's own call into the tab's frames), scrolling the first into view in
+ *   `revealFrame`; null takes the boxes away.
+ * @property {(shown: string | null) => void} onChange Hears which item is shown now (press its
+ *   button, release the others).
+ */
+
+/**
+ * @typedef {object} ShowOnPage
+ * @property {() => string | null} shown The item shown, or null.
+ * @property {(id: string, ids: string[], revealFrame?: number) => Promise<void>} toggle Show the item
+ *   `id` (the page's `ids`), or take it away if it's the one shown. Rejects when the page can't be
+ *   reached, with nothing shown.
+ * @property {() => Promise<void>} reset A rescan started, or the panel is closing: take the page's boxes
+ *   away if any are shown. The call to the page starts at once (a closing panel still gets it out)
+ *   and a failure is ignored (the tab is gone).
+ * @property {() => void} cleared The page says its boxes went: nothing is shown, and the page isn't called.
+ */
+
+/**
+ * A panel's “Show on page” state.
+ *
+ * @param {ShowOnPageSetup} setup - How to box items on the page, and who hears what's shown.
+ * @returns {ShowOnPage} The controller.
+ * @example
+ * const onPage = createShowOnPage({
+ *   show: (ids, frame) => callPage('highlight', [ids, frame]),
+ *   onChange: (shown) => { for (const button of buttons) button.setAttribute('aria-pressed', String(button.dataset.id === shown)); },
+ * });
+ * button.addEventListener('click', () => onPage.toggle(font.id, [font.id], font.frameId));
+ * chrome.runtime.onMessage.addListener((message) => { if (message.type === 'boxes-cleared') onPage.cleared(); });
+ * addEventListener('pagehide', () => onPage.reset());
+ * await onPage.reset(); // before a rescan
+ */
+export function createShowOnPage({ show, onChange }) {
+  /** @type {string | null} */
+  let shown = null;
+  /** @param {string | null} id */
+  const set = (id) => {
+    if (shown === id) return;
+    shown = id;
+    onChange(id);
+  };
+
+  return {
+    shown: () => shown,
+    async toggle(id, ids, revealFrame) {
+      if (shown === id) {
+        set(null);
+        await show(null);
+        return;
+      }
+      set(id);
+      try {
+        await show(ids, revealFrame);
+      } catch (error) {
+        if (shown === id) set(null);
+        throw error;
+      }
+    },
+    async reset() {
+      if (shown === null) return;
+      set(null);
+      await show(null).catch(() => {});
+    },
+    cleared: () => set(null),
+  };
+}

package/src/scripting/call.d.ts

@@ -6,6 +6,13 @@
  * The module, and anything it keeps, stays loaded in that world between calls,
  * so a content script can hold a session (a picker, an inspector) across them.
  *
+ * `"use_dynamic_url": true` on those resources would keep a page from loading
+ * them to tell the extension is installed, and this import still works with
+ * it, but only for a module with no static imports: Chrome refuses a
+ * dynamic-URL module's own static import of a sibling module (checked in Chromium 156,
+ * tests/chrome-chromium.test.js). So it suits a single-file (bundled) page
+ * module, not one that imports its parts.
+ *
  * @module scripting/call
  */
 export type CallScripting = Pick<typeof chrome.scripting, 'executeScript'>;
@@ -15,9 +22,13 @@ export type FrameResult<T> = {
      */
     frameId: number;
     /**
-     * The function's result, once its promise settled.
+     * The function's result, once its promise settled (null when it failed).
      */
     result: T;
+    /**
+     * Why it failed there: the module didn't load, or the function threw.
+     */
+    error?: string;
 };
 /**
  * The parts of `chrome.scripting` a call uses.
@@ -30,15 +41,19 @@ export type FrameResult<T> = {
  * @template T
  * @typedef {object} FrameResult
  * @property {number} frameId The frame (0 is the top one).
- * @property {T} result The function's result, once its promise settled.
+ * @property {T} result The function's result, once its promise settled (null when it failed).
+ * @property {string} [error] Why it failed there: the module didn't load, or the function threw.
  */
+/** The key of what {@link importAndCall} answers with when the call failed: Chrome itself gives a bare null for a function that throws. */
+export declare const CALL_FAILED = "extension-kit:call-failed";
 /**
  * The function `executeScript` runs in the page: alone, without closures.
  *
  * @param {string} module - The module's path in the extension, `content/main.js`.
  * @param {string} name - The export to call.
  * @param {unknown[]} args - Its arguments.
- * @returns {Promise<unknown>} What it returns.
+ * @returns {Promise<unknown>} What it returns, or `{'extension-kit:call-failed': message}` when the
+ *   module didn't load or the function threw (`executeScript` would give null, and no reason).
  */
 export declare const importAndCall: (module: string, name: string, args: unknown[]) => Promise<unknown>;
 /**
@@ -49,15 +64,20 @@ export declare const importAndCall: (module: string, name: string, args: unknown
  * @param {chrome.scripting.InjectionTarget} target - The tab, and which frames (`allFrames`, `frameIds`).
  * @param {string} module - The module's path in the extension (listed in `web_accessible_resources`).
  * @param {string} name - The exported function.
- * @param {unknown[]} [args] - Its arguments (structured-cloneable).
- * @param {{immediately?: boolean}} [options] - `immediately` (default true): don't wait for the
- *   page to be idle, which a page still loading ads or a player may not be for a long time.
- * @returns {Promise<FrameResult<T>[]>} Each frame's result, frames Chrome couldn't run in left out;
- *   rejects when it can run in none (a page Chrome keeps to itself, no access).
+ * @param {unknown[]} [args] - Its arguments, and its result: JSON-serialisable (Chrome carries them
+ *   as JSON, so a Map, a Set or a Date doesn't survive).
+ * @param {{immediately?: boolean, timeoutMs?: number}} [options] - `immediately` (default true): don't
+ *   wait for the page to be idle, which a page still loading ads or a player may not be for a long
+ *   time. `timeoutMs`: the longest to wait for every frame (Chrome answers only once all have, so one
+ *   frame that never does keeps the rest waiting); default none.
+ * @returns {Promise<FrameResult<T>[]>} Each frame's result, frames Chrome couldn't run in left out; a
+ *   frame where the call failed has `result: null` and its `error`. Rejects when it can run in none
+ *   (a page Chrome keeps to itself, no access), and with a `TimeoutError` when `timeoutMs` passes.
  * @example
  * const [{ result }] = await callInPage(chrome.scripting, { tabId }, 'content/main.js', 'scan', [options]);
  * await callInPage(chrome.scripting, { tabId, allFrames: true }, 'content/main.js', 'highlight', [key]);
  */
-export declare function callInPage<T = unknown>(scripting: CallScripting, target: chrome.scripting.InjectionTarget, module: string, name: string, args?: unknown[], { immediately }?: {
+export declare function callInPage<T = unknown>(scripting: CallScripting, target: chrome.scripting.InjectionTarget, module: string, name: string, args?: unknown[], { immediately, timeoutMs }?: {
     immediately?: boolean;
+    timeoutMs?: number;
 }): Promise<FrameResult<T>[]>;

package/src/scripting/call.js

@@ -6,9 +6,18 @@
  * The module, and anything it keeps, stays loaded in that world between calls,
  * so a content script can hold a session (a picker, an inspector) across them.
  *
+ * `"use_dynamic_url": true` on those resources would keep a page from loading
+ * them to tell the extension is installed, and this import still works with
+ * it, but only for a module with no static imports: Chrome refuses a
+ * dynamic-URL module's own static import of a sibling module (checked in Chromium 156,
+ * tests/chrome-chromium.test.js). So it suits a single-file (bundled) page
+ * module, not one that imports its parts.
+ *
  * @module scripting/call
  */
 
+import { deadline } from '../time/time.js';
+
 /**
  * The parts of `chrome.scripting` a call uses.
  *
@@ -21,18 +30,24 @@
  * @template T
  * @typedef {object} FrameResult
  * @property {number} frameId The frame (0 is the top one).
- * @property {T} result The function's result, once its promise settled.
+ * @property {T} result The function's result, once its promise settled (null when it failed).
+ * @property {string} [error] Why it failed there: the module didn't load, or the function threw.
  */
 
+/** The key of what {@link importAndCall} answers with when the call failed: Chrome itself gives a bare null for a function that throws. */
+export const CALL_FAILED = 'extension-kit:call-failed';
+
 /**
  * The function `executeScript` runs in the page: alone, without closures.
  *
  * @param {string} module - The module's path in the extension, `content/main.js`.
  * @param {string} name - The export to call.
  * @param {unknown[]} args - Its arguments.
- * @returns {Promise<unknown>} What it returns.
+ * @returns {Promise<unknown>} What it returns, or `{'extension-kit:call-failed': message}` when the
+ *   module didn't load or the function threw (`executeScript` would give null, and no reason).
  */
-export const importAndCall = (module, name, args) => import(chrome.runtime.getURL(module)).then((loaded) => loaded[name](...args));
+export const importAndCall = (module, name, args) => import(chrome.runtime.getURL(module)).then((loaded) => loaded[name](...args))
+  .catch((error) => ({ 'extension-kit:call-failed': String(error?.message ?? error) }));
 
 /**
  * Call `name` from the extension module `module` in the target's frames.
@@ -42,16 +57,25 @@ export const importAndCall = (module, name, args) => import(chrome.runtime.getUR
  * @param {chrome.scripting.InjectionTarget} target - The tab, and which frames (`allFrames`, `frameIds`).
  * @param {string} module - The module's path in the extension (listed in `web_accessible_resources`).
  * @param {string} name - The exported function.
- * @param {unknown[]} [args] - Its arguments (structured-cloneable).
- * @param {{immediately?: boolean}} [options] - `immediately` (default true): don't wait for the
- *   page to be idle, which a page still loading ads or a player may not be for a long time.
- * @returns {Promise<FrameResult<T>[]>} Each frame's result, frames Chrome couldn't run in left out;
- *   rejects when it can run in none (a page Chrome keeps to itself, no access).
+ * @param {unknown[]} [args] - Its arguments, and its result: JSON-serialisable (Chrome carries them
+ *   as JSON, so a Map, a Set or a Date doesn't survive).
+ * @param {{immediately?: boolean, timeoutMs?: number}} [options] - `immediately` (default true): don't
+ *   wait for the page to be idle, which a page still loading ads or a player may not be for a long
+ *   time. `timeoutMs`: the longest to wait for every frame (Chrome answers only once all have, so one
+ *   frame that never does keeps the rest waiting); default none.
+ * @returns {Promise<FrameResult<T>[]>} Each frame's result, frames Chrome couldn't run in left out; a
+ *   frame where the call failed has `result: null` and its `error`. Rejects when it can run in none
+ *   (a page Chrome keeps to itself, no access), and with a `TimeoutError` when `timeoutMs` passes.
  * @example
  * const [{ result }] = await callInPage(chrome.scripting, { tabId }, 'content/main.js', 'scan', [options]);
  * await callInPage(chrome.scripting, { tabId, allFrames: true }, 'content/main.js', 'highlight', [key]);
  */
-export async function callInPage(scripting, target, module, name, args = [], { immediately = true } = {}) {
-  const frames = await scripting.executeScript({ target, injectImmediately: immediately, func: importAndCall, args: [module, name, args] });
-  return frames.map((frame) => ({ frameId: frame.frameId, result: /** @type {T} */ (frame.result) }));
+export async function callInPage(scripting, target, module, name, args = [], { immediately = true, timeoutMs } = {}) {
+  const running = scripting.executeScript({ target, injectImmediately: immediately, func: importAndCall, args: [module, name, args] });
+  const frames = await (timeoutMs === undefined ? running
+    : deadline(running, timeoutMs, (_, reject) => reject(new DOMException(`${module} ${name}: no answer in ${timeoutMs} ms`, 'TimeoutError'))));
+  return frames.map(({ frameId, result }) => {
+    const failed = result && typeof result === 'object' ? /** @type {Record<string, unknown>} */ (result)[CALL_FAILED] : undefined;
+    return typeof failed === 'string' ? { frameId, result: /** @type {T} */ (null), error: failed } : { frameId, result: /** @type {T} */ (result) };
+  });
 }

package/src/scripting/context-menus.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The right-click menu built whole, one build after another. A worker builds its menu on install
+ * and on browser start, and after a Chrome update both events come in the same run: two builds
+ * side by side clear the menu twice and then each creates every item, so Chrome reports
+ * "Cannot create item with duplicate id" for each on the extension's Errors page. Built through
+ * this, the second build starts once the first is done.
+ *
+ * @module scripting/context-menus
+ */
+export type MenuEdges = {
+    /**
+     * The menu.
+     */
+    contextMenus: Pick<typeof chrome.contextMenus, 'removeAll' | 'create'>;
+    /**
+     * Where Chrome leaves `create`'s error.
+     */
+    runtime: {
+        lastError?: {
+            message?: string;
+        };
+    };
+};
+/**
+ * The parts of `chrome` a menu build uses.
+ *
+ * @typedef {object} MenuEdges
+ * @property {Pick<typeof chrome.contextMenus, 'removeAll' | 'create'>} contextMenus The menu.
+ * @property {{lastError?: {message?: string}}} runtime Where Chrome leaves `create`'s error.
+ */
+/**
+ * A builder for an extension's right-click menu: each call takes every item away and creates the
+ * ones given, in order (a parent before its children), after any build still under way.
+ * `contextMenus.create` has no promise form; an item Chrome refuses is logged, not thrown, so one
+ * bad item can't stop the rest.
+ *
+ * @param {MenuEdges} edges - `chrome` (or fakes in tests).
+ * @returns {(items: readonly chrome.contextMenus.CreateProperties[]) => Promise<void>} Builds the
+ *   menu; settles once Chrome has made (or refused) the last item.
+ * @example
+ * const buildMenu = contextMenuBuilder(chrome);
+ * chrome.runtime.onInstalled.addListener(() => buildMenu(menuItems(t)));
+ * chrome.runtime.onStartup.addListener(() => buildMenu(menuItems(t)));
+ */
+export declare function contextMenuBuilder({ contextMenus, runtime }: MenuEdges): (items: readonly chrome.contextMenus.CreateProperties[]) => Promise<void>;

package/src/scripting/context-menus.js

@@ -0,0 +1,53 @@
+/**
+ * The right-click menu built whole, one build after another. A worker builds its menu on install
+ * and on browser start, and after a Chrome update both events come in the same run: two builds
+ * side by side clear the menu twice and then each creates every item, so Chrome reports
+ * "Cannot create item with duplicate id" for each on the extension's Errors page. Built through
+ * this, the second build starts once the first is done.
+ *
+ * @module scripting/context-menus
+ */
+
+/**
+ * The parts of `chrome` a menu build uses.
+ *
+ * @typedef {object} MenuEdges
+ * @property {Pick<typeof chrome.contextMenus, 'removeAll' | 'create'>} contextMenus The menu.
+ * @property {{lastError?: {message?: string}}} runtime Where Chrome leaves `create`'s error.
+ */
+
+/**
+ * A builder for an extension's right-click menu: each call takes every item away and creates the
+ * ones given, in order (a parent before its children), after any build still under way.
+ * `contextMenus.create` has no promise form; an item Chrome refuses is logged, not thrown, so one
+ * bad item can't stop the rest.
+ *
+ * @param {MenuEdges} edges - `chrome` (or fakes in tests).
+ * @returns {(items: readonly chrome.contextMenus.CreateProperties[]) => Promise<void>} Builds the
+ *   menu; settles once Chrome has made (or refused) the last item.
+ * @example
+ * const buildMenu = contextMenuBuilder(chrome);
+ * chrome.runtime.onInstalled.addListener(() => buildMenu(menuItems(t)));
+ * chrome.runtime.onStartup.addListener(() => buildMenu(menuItems(t)));
+ */
+export function contextMenuBuilder({ contextMenus, runtime }) {
+  /** The last build, so the next waits for it. */
+  let queue = Promise.resolve();
+  /** @param {readonly chrome.contextMenus.CreateProperties[]} items */
+  const build = async (items) => {
+    await contextMenus.removeAll();
+    for (const item of items) {
+      await new Promise((resolve) => {
+        contextMenus.create(item, () => {
+          if (runtime.lastError) console.error(`Creating the menu item “${item.id}”:`, runtime.lastError.message);
+          resolve(undefined);
+        });
+      });
+    }
+  };
+  return (items) => {
+    const run = queue.then(() => build(items), () => build(items));
+    queue = run.catch(() => {});
+    return run;
+  };
+}

package/src/scripting/registration.d.ts

@@ -25,7 +25,8 @@ export type Scripting = Pick<typeof chrome.scripting, 'getRegisteredContentScrip
  * @param {Scripting} scripting - `chrome.scripting` (or a fake in tests).
  * @param {string} id - The registered script's id.
  * @param {() => Promise<ContentScript | null>} want - What should be registered now (settings and
- *   grants read at the time).
+ *   grants read at the time). Give every property each time (`excludeMatches: []` for none): Chrome's
+ *   update keeps what a script leaves out, so a list that became empty and was dropped would stay.
  * @returns {() => Promise<void>} Makes the registration match; rejects if Chrome refuses.
  * @example
  * const sync = contentScriptSync(chrome.scripting, 'prices', async () => (await chrome.permissions.contains({ origins: ALL_SITES })

package/src/scripting/registration.js

@@ -24,7 +24,8 @@
  * @param {Scripting} scripting - `chrome.scripting` (or a fake in tests).
  * @param {string} id - The registered script's id.
  * @param {() => Promise<ContentScript | null>} want - What should be registered now (settings and
- *   grants read at the time).
+ *   grants read at the time). Give every property each time (`excludeMatches: []` for none): Chrome's
+ *   update keeps what a script leaves out, so a list that became empty and was dropped would stay.
  * @returns {() => Promise<void>} Makes the registration match; rejects if Chrome refuses.
  * @example
  * const sync = contentScriptSync(chrome.scripting, 'prices', async () => (await chrome.permissions.contains({ origins: ALL_SITES })

package/src/scripting/tab.d.ts

@@ -2,8 +2,9 @@
  * Reading a tab: one of the extension's page modules called in every frame
  * Chrome lets it run in, the frames' answers top first; or why it can't be
  * read: a page Chrome keeps to itself (its own pages, the Web Store, other
- * extensions'), or no access (the tab went to another site since the click
- * that gave activeTab).
+ * extensions'), no access (the tab went to another site since the click
+ * that gave activeTab), the module failed in every frame, or no answer in
+ * time.
  *
  * @module scripting/tab
  */
@@ -25,6 +26,11 @@ export type TabReading<T> = {
     state: 'browser';
 } | {
     state: 'no-access';
+} | {
+    state: 'failed';
+    error: string;
+} | {
+    state: 'timeout';
 };
 export type TabEdges = {
     /**
@@ -40,8 +46,10 @@ export type TabEdges = {
  * What reading a tab gave.
  *
  * @template T
- * @typedef {{state: 'read', frames: FrameResult<T>[]} | {state: 'browser'} | {state: 'no-access'}} TabReading
+ * @typedef {{state: 'read', frames: FrameResult<T>[]} | {state: 'browser'} | {state: 'no-access'} | {state: 'failed', error: string} | {state: 'timeout'}} TabReading
  *   `frames`: each frame that answered (not null), the top one first, then in Chrome's frame order.
+ *   `failed`: no frame answered and the call threw in at least one (`error`: the first one's reason),
+ *   which Chrome itself reports as a bare null; `timeout`: `timeoutMs` passed first.
  */
 /**
  * The Chrome APIs a reading uses (fakes in unit tests).
@@ -59,10 +67,14 @@ export type TabEdges = {
  * @param {string} module - The module (in `web_accessible_resources`).
  * @param {string} name - The export.
  * @param {unknown[]} [args] - Its arguments.
+ * @param {{timeoutMs?: number}} [options] - `timeoutMs`: the longest to wait (Chrome answers once every
+ *   frame has, so one that never does would keep a panel waiting for ever); default none.
  * @returns {Promise<TabReading<T>>} The frames' answers, or why there are none.
  * @example
  * const reading = await callInTab(chrome, tabId, 'content/main.js', 'scan');
  * if (reading.state === 'read') show(reading.frames);
- * else showMessage(reading.state); // 'browser' or 'no-access'
+ * else showMessage(reading.state); // 'browser', 'no-access', 'failed' or 'timeout'
  */
-export declare function callInTab<T = unknown>(edges: TabEdges, tabId: number, module: string, name: string, args?: unknown[]): Promise<TabReading<T>>;
+export declare function callInTab<T = unknown>(edges: TabEdges, tabId: number, module: string, name: string, args?: unknown[], { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<TabReading<T>>;

package/src/scripting/tab.js

@@ -2,8 +2,9 @@
  * Reading a tab: one of the extension's page modules called in every frame
  * Chrome lets it run in, the frames' answers top first; or why it can't be
  * read: a page Chrome keeps to itself (its own pages, the Web Store, other
- * extensions'), or no access (the tab went to another site since the click
- * that gave activeTab).
+ * extensions'), no access (the tab went to another site since the click
+ * that gave activeTab), the module failed in every frame, or no answer in
+ * time.
  *
  * @module scripting/tab
  */
@@ -33,8 +34,10 @@ export const isBrowserPage = (url) => BROWSER_PAGE.test(url);
  * What reading a tab gave.
  *
  * @template T
- * @typedef {{state: 'read', frames: FrameResult<T>[]} | {state: 'browser'} | {state: 'no-access'}} TabReading
+ * @typedef {{state: 'read', frames: FrameResult<T>[]} | {state: 'browser'} | {state: 'no-access'} | {state: 'failed', error: string} | {state: 'timeout'}} TabReading
  *   `frames`: each frame that answered (not null), the top one first, then in Chrome's frame order.
+ *   `failed`: no frame answered and the call threw in at least one (`error`: the first one's reason),
+ *   which Chrome itself reports as a bare null; `timeout`: `timeoutMs` passed first.
  */
 
 /**
@@ -54,13 +57,15 @@ export const isBrowserPage = (url) => BROWSER_PAGE.test(url);
  * @param {string} module - The module (in `web_accessible_resources`).
  * @param {string} name - The export.
  * @param {unknown[]} [args] - Its arguments.
+ * @param {{timeoutMs?: number}} [options] - `timeoutMs`: the longest to wait (Chrome answers once every
+ *   frame has, so one that never does would keep a panel waiting for ever); default none.
  * @returns {Promise<TabReading<T>>} The frames' answers, or why there are none.
  * @example
  * const reading = await callInTab(chrome, tabId, 'content/main.js', 'scan');
  * if (reading.state === 'read') show(reading.frames);
- * else showMessage(reading.state); // 'browser' or 'no-access'
+ * else showMessage(reading.state); // 'browser', 'no-access', 'failed' or 'timeout'
  */
-export async function callInTab(edges, tabId, module, name, args = []) {
+export async function callInTab(edges, tabId, module, name, args = [], { timeoutMs } = {}) {
   let url;
   try {
     url = (await edges.tabs.get(tabId)).url;
@@ -71,11 +76,14 @@ export async function callInTab(edges, tabId, module, name, args = []) {
   /** @type {FrameResult<T>[]} */
   let frames;
   try {
-    frames = await callInPage(edges.scripting, { tabId, allFrames: true }, module, name, args);
+    frames = await callInPage(edges.scripting, { tabId, allFrames: true }, module, name, args, { timeoutMs });
   } catch (error) {
+    if (/** @type {Error} */ (error)?.name === 'TimeoutError') return { state: 'timeout' };
     // Chrome's own page (said in its refusal), or no access: the tab went to another site since the click.
     return { state: BROWSER_REFUSAL.test(String(/** @type {Error} */ (error)?.message)) ? 'browser' : 'no-access' };
   }
   const read = frames.filter((frame) => frame.result !== null && frame.result !== undefined).sort((a, b) => a.frameId - b.frameId);
-  return read.length ? { state: 'read', frames: read } : { state: 'no-access' };
+  if (read.length) return { state: 'read', frames: read };
+  const failed = frames.toSorted((a, b) => a.frameId - b.frameId).find((frame) => frame.error !== undefined);
+  return failed ? { state: 'failed', error: /** @type {string} */ (failed.error) } : { state: 'no-access' };
 }

package/src/settings/saver.js

@@ -56,6 +56,7 @@ export function createSettingsSaver(store, storage, { delay = 1000, retryAfter =
   let retryTimer;
   /** @type {Promise<unknown>} */
   let writing = Promise.resolve();
+  let stopped = false;
 
   /**
    * Track a write so `flush()` can be awaited; a failure is logged, never thrown.
@@ -68,10 +69,18 @@ export function createSettingsSaver(store, storage, { delay = 1000, retryAfter =
     return writing;
   };
 
+  /** Try again later, if anything held could reach sync then. */
+  async function retryLater() {
+    clearTimeout(retryTimer);
+    retryTimer = undefined;
+    const worthIt = await store.retryable(storage);
+    if (stopped || !worthIt) return;
+    clearTimeout(retryTimer);
+    retryTimer = setTimeout(retry, retryAfter);
+  }
+
   function retry() {
-    track(store.retryUnsynced(storage).then((synced) => {
-      if (!synced) retryTimer = setTimeout(retry, retryAfter);
-    }));
+    track(store.retryUnsynced(storage).then((synced) => (synced ? undefined : retryLater())));
   }
 
   /** Writes start at once, not after earlier ones finish: Chrome applies them in order. */
@@ -80,10 +89,10 @@ export function createSettingsSaver(store, storage, { delay = 1000, retryAfter =
     const changes = pending;
     pending = {};
     if (!Object.keys(changes).length) return writing;
-    return track(store.save(storage, changes).then(({ settings, synced }) => {
-      clearTimeout(retryTimer);
-      if (!synced) retryTimer = setTimeout(retry, retryAfter);
+    return track(store.save(storage, changes).then(async ({ settings, synced }) => {
       onSaved(settings);
+      if (synced) clearTimeout(retryTimer);
+      else await retryLater();
     }));
   }
 
@@ -102,6 +111,7 @@ export function createSettingsSaver(store, storage, { delay = 1000, retryAfter =
       });
     },
     stop() {
+      stopped = true;
       clearTimeout(timer);
       clearTimeout(retryTimer);
     },