@arraypress/extension-kit 1.10.0 → 1.11.0

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);
     },

package/src/settings/storage.d.ts

@@ -74,14 +74,45 @@ export declare const MAX_SYNC_ITEM_BYTES = 8192;
  */
 export declare function pick<T extends Record<string, unknown>>(object: T, keys: readonly string[]): Partial<T>;
 /**
- * How many bytes sync counts for one item: the key plus the value's JSON,
- * UTF-8 encoded, as Chrome measures `QUOTA_BYTES_PER_ITEM`.
+ * How many bytes sync counts for one item, as Chrome measures
+ * `QUOTA_BYTES_PER_ITEM`: the key plus the value's JSON as Chrome's own
+ * writer spells it, UTF-8 encoded. That writer (`base::WriteJson`) escapes
+ * `<` as `\u003C` and U+2028 / U+2029 as `\u2028` / `\u2029`, six bytes each,
+ * so text full of `<` (an HTML template) weighs far more in sync than its
+ * `JSON.stringify` length says. Checked against Chromium's
+ * `settings_storage_quota_enforcer.cc` and `base/json/string_escape.cc`.
  *
  * @param {string} key - The item's key.
  * @param {unknown} value - The item's value.
  * @returns {number} Bytes.
+ * @example
+ * syncItemBytes('k', 'a<b'); // 11: k + "a\u003Cb"
  */
 export declare function syncItemBytes(key: string, value: unknown): number;
+/**
+ * Whether two stored values are the same, whatever order their objects' keys come in.
+ *
+ * @param {unknown} a - One value.
+ * @param {unknown} b - The other.
+ * @returns {boolean} True when they'd be stored alike.
+ * @example
+ * sameValue({ a: 1, b: [2] }, { b: [2], a: 1 }); // true
+ */
+export declare function sameValue(a: unknown, b: unknown): boolean;
+/**
+ * Run `work` while nothing else runs under the same name: in this page, the
+ * extension's other pages and its service worker alike (Web Locks, which an
+ * extension's contexts share), so a read-modify-write of one storage item
+ * can't interleave with another. `work` is told whether it had to wait.
+ *
+ * @template T
+ * @param {string} name - The lock's name.
+ * @param {(waited: boolean) => Promise<T>} work - What to do; `waited` is true when other work held the name first.
+ * @returns {Promise<T>} What `work` gives.
+ * @example
+ * await exclusive('unsyncedSettings', async () => storage.local.set({ held: { ...(await storage.local.get('held')).held, days } }));
+ */
+export declare function exclusive<T>(name: string, work: (waited: boolean) => Promise<T>): Promise<T>;
 /**
  * Whether an object has no own keys.
  *

package/src/settings/storage.js

@@ -53,16 +53,86 @@ export function pick(object, keys) {
   return /** @type {Partial<T>} */ (Object.fromEntries(keys.filter((key) => key in object).map((key) => [key, object[key]])));
 }
 
+/** What Chrome's JSON writer spells as six bytes where `JSON.stringify` writes fewer: `<` (one byte), U+2028 and U+2029 (three each). */
+const WIDER_IN_CHROME = /[<\u2028\u2029]/g;
+
 /**
- * How many bytes sync counts for one item: the key plus the value's JSON,
- * UTF-8 encoded, as Chrome measures `QUOTA_BYTES_PER_ITEM`.
+ * How many bytes sync counts for one item, as Chrome measures
+ * `QUOTA_BYTES_PER_ITEM`: the key plus the value's JSON as Chrome's own
+ * writer spells it, UTF-8 encoded. That writer (`base::WriteJson`) escapes
+ * `<` as `\u003C` and U+2028 / U+2029 as `\u2028` / `\u2029`, six bytes each,
+ * so text full of `<` (an HTML template) weighs far more in sync than its
+ * `JSON.stringify` length says. Checked against Chromium's
+ * `settings_storage_quota_enforcer.cc` and `base/json/string_escape.cc`.
  *
  * @param {string} key - The item's key.
  * @param {unknown} value - The item's value.
  * @returns {number} Bytes.
+ * @example
+ * syncItemBytes('k', 'a<b'); // 11: k + "a\u003Cb"
  */
 export function syncItemBytes(key, value) {
-  return new TextEncoder().encode(key + JSON.stringify(value)).length;
+  const json = String(JSON.stringify(value));
+  let wider = 0;
+  for (const [character] of json.matchAll(WIDER_IN_CHROME)) wider += character === '<' ? 5 : 3;
+  return new TextEncoder().encode(key + json).length + wider;
+}
+
+/**
+ * A value as text that reads the same however its objects' keys are ordered:
+ * Chrome hands a stored object back with its keys sorted.
+ *
+ * @param {unknown} value - Anything JSON can hold.
+ * @returns {string} Its JSON, object keys sorted.
+ */
+function canonical(value) {
+  return String(JSON.stringify(value, (_, inner) => (inner && typeof inner === 'object' && !Array.isArray(inner)
+    ? Object.fromEntries(Object.keys(inner).sort().map((key) => [key, inner[key]]))
+    : inner)));
+}
+
+/**
+ * Whether two stored values are the same, whatever order their objects' keys come in.
+ *
+ * @param {unknown} a - One value.
+ * @param {unknown} b - The other.
+ * @returns {boolean} True when they'd be stored alike.
+ * @example
+ * sameValue({ a: 1, b: [2] }, { b: [2], a: 1 }); // true
+ */
+export function sameValue(a, b) {
+  return canonical(a) === canonical(b);
+}
+
+/** Where there are no Web Locks (an old Node): each name's last piece of work, so the next waits for it. @type {Map<string, Promise<unknown>>} */
+const chains = new Map();
+
+/**
+ * Run `work` while nothing else runs under the same name: in this page, the
+ * extension's other pages and its service worker alike (Web Locks, which an
+ * extension's contexts share), so a read-modify-write of one storage item
+ * can't interleave with another. `work` is told whether it had to wait.
+ *
+ * @template T
+ * @param {string} name - The lock's name.
+ * @param {(waited: boolean) => Promise<T>} work - What to do; `waited` is true when other work held the name first.
+ * @returns {Promise<T>} What `work` gives.
+ * @example
+ * await exclusive('unsyncedSettings', async () => storage.local.set({ held: { ...(await storage.local.get('held')).held, days } }));
+ */
+export async function exclusive(name, work) {
+  const locks = /** @type {{navigator?: {locks?: LockManager}}} */ (globalThis).navigator?.locks;
+  if (locks) {
+    /** @type {{value: T} | null} */
+    const free = await locks.request(name, { ifAvailable: true }, async (lock) => (lock ? { value: await work(false) } : null));
+    return free ? free.value : locks.request(name, () => work(true));
+  }
+  const before = chains.get(name);
+  const run = (before ?? Promise.resolve()).then(() => work(before !== undefined));
+  const settled = run.catch(() => {});
+  chains.set(name, settled);
+  settled.then(() => { if (chains.get(name) === settled) chains.delete(name); });
+  return run;
 }
 
 /**

package/src/settings/store.d.ts

@@ -8,6 +8,15 @@
  * `chrome.storage.local` instead. Local also holds any write sync refused
  * (too many writes a minute, or an item over its size limit), kept under
  * `unsyncedKey`, read as if synced, and retried, so a change is never lost.
+ * Beside it (`<unsyncedKey>Was`) is what sync held for each when it was
+ * refused: once sync holds something else (the setting was changed since on
+ * another computer), the held change is the older one and is dropped, not
+ * read over the newer one or sent up over it.
+ *
+ * Holding a change is a read-modify-write of one local item, so it runs
+ * under a Web Lock the extension's pages and worker share: two refused
+ * writes at once keep both changes, and a retry can't put an older value
+ * back over a newer one.
  *
  * Each extension supplies its schema: the defaults and one normaliser that
  * coerces anything read from storage or a form into valid settings.
@@ -72,6 +81,11 @@ export type SettingsStore<S extends Record<string, unknown>> = {
      *   Try again to put earlier refusals into sync.
      */
     retryUnsynced: (storage: SyncedStorage) => Promise<boolean>;
+    /**
+     *   Whether trying again could help: something held is still the newest and small enough for sync
+     *   (an item over sync's size limit stays on this computer however often it's tried).
+     */
+    retryable: (storage: SyncedStorage) => Promise<boolean>;
     /**
      *   Save the settings `changes` names, normalised.
      */
@@ -116,6 +130,9 @@ export type SettingsStore<S extends Record<string, unknown>> = {
  *   everything reached sync.
  * @property {(storage: SyncedStorage) => Promise<boolean>} retryUnsynced
  *   Try again to put earlier refusals into sync.
+ * @property {(storage: SyncedStorage) => Promise<boolean>} retryable
+ *   Whether trying again could help: something held is still the newest and small enough for sync
+ *   (an item over sync's size limit stays on this computer however often it's tried).
  * @property {(storage: SyncedStorage, changes: Partial<S>) => Promise<{settings: S, synced: boolean}>} save
  *   Save the settings `changes` names, normalised.
  * @property {(changes: Record<string, StorageChange>, area: string) => (keyof S & string)[]} changed