@arraypress/extension-kit 0.0.0-stage → 1.1.0

package/src/dom/i18n.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Localising extension pages from `_locales/<lang>/messages.json`. Markup
+ * opts in with `data-i18n="key"` (sets the text) or
+ * `data-i18n-<attribute>="key"` (sets that attribute, e.g.
+ * `data-i18n-placeholder`, `data-i18n-aria-label`).
+ *
+ * @module dom/i18n
+ */
+export type I18nApi = {
+    getMessage: (key: string, substitutions?: string | string[]) => string;
+    getUILanguage: () => string;
+};
+/**
+ * `chrome.i18n`, as far as pages need it.
+ *
+ * @typedef {object} I18nApi
+ * @property {(key: string, substitutions?: string | string[]) => string} getMessage
+ * @property {() => string} getUILanguage
+ */
+/**
+ * A message lookup that never comes back blank: a missing key shows as
+ * itself, so a typo is visible on screen instead of an empty label.
+ *
+ * @param {Pick<I18nApi, 'getMessage'>} i18n - `chrome.i18n`.
+ * @returns {(key: string, substitutions?: string | string[]) => string} Looks a key up.
+ * @example
+ * const t = translator(chrome.i18n);
+ * t('optionsVersion', ['1.0.0']); // 'Version 1.0.0'
+ */
+export declare function translator(i18n: Pick<I18nApi, 'getMessage'>): (key: string, substitutions?: string | string[]) => string;
+/**
+ * Fill every `data-i18n*` attribute under `root`, and, for a whole document,
+ * set its `lang` to Chrome's UI language.
+ *
+ * @param {ParentNode} root - A document or an element.
+ * @param {I18nApi} i18n - `chrome.i18n`.
+ * @returns {void}
+ */
+export declare function localize(root: ParentNode, i18n: I18nApi): void;

package/src/dom/i18n.js

@@ -0,0 +1,49 @@
+/**
+ * Localising extension pages from `_locales/<lang>/messages.json`. Markup
+ * opts in with `data-i18n="key"` (sets the text) or
+ * `data-i18n-<attribute>="key"` (sets that attribute, e.g.
+ * `data-i18n-placeholder`, `data-i18n-aria-label`).
+ *
+ * @module dom/i18n
+ */
+
+/**
+ * `chrome.i18n`, as far as pages need it.
+ *
+ * @typedef {object} I18nApi
+ * @property {(key: string, substitutions?: string | string[]) => string} getMessage
+ * @property {() => string} getUILanguage
+ */
+
+/**
+ * A message lookup that never comes back blank: a missing key shows as
+ * itself, so a typo is visible on screen instead of an empty label.
+ *
+ * @param {Pick<I18nApi, 'getMessage'>} i18n - `chrome.i18n`.
+ * @returns {(key: string, substitutions?: string | string[]) => string} Looks a key up.
+ * @example
+ * const t = translator(chrome.i18n);
+ * t('optionsVersion', ['1.0.0']); // 'Version 1.0.0'
+ */
+export function translator(i18n) {
+  return (key, substitutions) => i18n.getMessage(key, substitutions) || key;
+}
+
+/**
+ * Fill every `data-i18n*` attribute under `root`, and, for a whole document,
+ * set its `lang` to Chrome's UI language.
+ *
+ * @param {ParentNode} root - A document or an element.
+ * @param {I18nApi} i18n - `chrome.i18n`.
+ * @returns {void}
+ */
+export function localize(root, i18n) {
+  const t = translator(i18n);
+  for (const element of root.querySelectorAll('*')) {
+    for (const { name, value } of [...element.attributes]) {
+      if (name === 'data-i18n') element.textContent = t(value);
+      else if (name.startsWith('data-i18n-')) element.setAttribute(name.slice('data-i18n-'.length), t(value));
+    }
+  }
+  if ('documentElement' in root) /** @type {Document} */ (root).documentElement.lang = i18n.getUILanguage();
+}

package/src/dom/page.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Small DOM helpers for extension pages built on chrome-ui.css: finding an
+ * element with its real type, the markup of a value row, the About card's
+ * links, and the "Saved" indicator. Browser only.
+ *
+ * @module dom/page
+ */
+import type { AboutLinks } from '../about/links.js';
+/** @import { AboutLinks } from '../about/links.js' */
+/**
+ * The element with `id`, checked to be a `Type`, so the page's code gets the
+ * real type (an `HTMLInputElement` has `.checked`) and fails loudly when the
+ * markup and the script disagree.
+ *
+ * @template {typeof HTMLElement} C
+ * @param {string} id - The element's id.
+ * @param {C} [Type] - Its class. Default `HTMLElement`.
+ * @param {ParentNode & {getElementById(id: string): HTMLElement | null}} [root] - Where to look. Default `document`.
+ * @returns {InstanceType<C>} The element.
+ * @throws {Error} When there is no such element, or it isn't a `Type`.
+ * @example
+ * const days = byId('inactiveDays', HTMLInputElement);
+ * days.valueAsNumber; // typed
+ */
+export declare function byId<C extends typeof HTMLElement>(id: string, Type?: C, root?: ParentNode & {
+    getElementById(id: string): HTMLElement | null;
+}): InstanceType<C>;
+/**
+ * A row with a label and a value at its end, as chrome://settings shows a
+ * keyboard shortcut: `.row` > `.label` + `.row-value`.
+ *
+ * @param {string} label - The row's text.
+ * @param {string} value - What sits at its end.
+ * @param {Document} [doc] - Where to make it. Default `document`.
+ * @returns {HTMLDivElement} The row.
+ */
+export declare function valueRow(label: string, value: string, doc?: Document): HTMLDivElement;
+/**
+ * Point the About card's link rows (`#help`, `#report-issue`,
+ * `#privacy-policy`, all `<a>`) at their addresses.
+ *
+ * @param {AboutLinks} links - From `githubAboutLinks`.
+ * @param {Document} [doc] - The page. Default `document`.
+ * @returns {void}
+ * @throws {Error} When a link row is missing.
+ */
+export declare function setAboutLinks(links: AboutLinks, doc?: Document): void;
+/**
+ * The "Saved" indicator: a `.save-status` element that shows a text, then
+ * fades out after `ms`. A new flash restarts the wait.
+ *
+ * @param {HTMLElement} element - The `.save-status` element.
+ * @param {number} ms - How long it stays.
+ * @returns {(text: string) => void} Shows `text`.
+ * @example
+ * const flash = statusFlasher(byId('status'), 1500);
+ * flash('Saved');
+ */
+export declare function statusFlasher(element: HTMLElement, ms: number): (text: string) => void;

package/src/dom/page.js

@@ -0,0 +1,93 @@
+/**
+ * Small DOM helpers for extension pages built on chrome-ui.css: finding an
+ * element with its real type, the markup of a value row, the About card's
+ * links, and the "Saved" indicator. Browser only.
+ *
+ * @module dom/page
+ */
+
+/** @import { AboutLinks } from '../about/links.js' */
+
+/**
+ * The element with `id`, checked to be a `Type`, so the page's code gets the
+ * real type (an `HTMLInputElement` has `.checked`) and fails loudly when the
+ * markup and the script disagree.
+ *
+ * @template {typeof HTMLElement} C
+ * @param {string} id - The element's id.
+ * @param {C} [Type] - Its class. Default `HTMLElement`.
+ * @param {ParentNode & {getElementById(id: string): HTMLElement | null}} [root] - Where to look. Default `document`.
+ * @returns {InstanceType<C>} The element.
+ * @throws {Error} When there is no such element, or it isn't a `Type`.
+ * @example
+ * const days = byId('inactiveDays', HTMLInputElement);
+ * days.valueAsNumber; // typed
+ */
+export function byId(id, Type = /** @type {C} */ (HTMLElement), root = document) {
+  /** @type {Element | null} */
+  const element = root.getElementById(id);
+  if (!element) throw new Error(`#${id} is missing`);
+  if (!(element instanceof Type)) throw new Error(`#${id} is a ${element.constructor.name}, not a ${Type.name}`);
+  return /** @type {InstanceType<C>} */ (element);
+}
+
+/**
+ * A row with a label and a value at its end, as chrome://settings shows a
+ * keyboard shortcut: `.row` > `.label` + `.row-value`.
+ *
+ * @param {string} label - The row's text.
+ * @param {string} value - What sits at its end.
+ * @param {Document} [doc] - Where to make it. Default `document`.
+ * @returns {HTMLDivElement} The row.
+ */
+export function valueRow(label, value, doc = document) {
+  const row = doc.createElement('div');
+  row.className = 'row';
+  const text = doc.createElement('span');
+  text.className = 'label';
+  text.textContent = label;
+  const end = doc.createElement('span');
+  end.className = 'row-value';
+  end.textContent = value;
+  row.append(text, end);
+  return row;
+}
+
+/**
+ * Point the About card's link rows (`#help`, `#report-issue`,
+ * `#privacy-policy`, all `<a>`) at their addresses.
+ *
+ * @param {AboutLinks} links - From `githubAboutLinks`.
+ * @param {Document} [doc] - The page. Default `document`.
+ * @returns {void}
+ * @throws {Error} When a link row is missing.
+ */
+export function setAboutLinks(links, doc = document) {
+  // The page's own class, so this works in any window (and in jsdom).
+  const { HTMLAnchorElement: Anchor } = /** @type {Window & typeof globalThis} */ (doc.defaultView);
+  byId('help', Anchor, doc).href = links.help;
+  byId('report-issue', Anchor, doc).href = links.reportIssue;
+  byId('privacy-policy', Anchor, doc).href = links.privacyPolicy;
+}
+
+/**
+ * The "Saved" indicator: a `.save-status` element that shows a text, then
+ * fades out after `ms`. A new flash restarts the wait.
+ *
+ * @param {HTMLElement} element - The `.save-status` element.
+ * @param {number} ms - How long it stays.
+ * @returns {(text: string) => void} Shows `text`.
+ * @example
+ * const flash = statusFlasher(byId('status'), 1500);
+ * flash('Saved');
+ */
+export function statusFlasher(element, ms) {
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  return (text) => {
+    element.textContent = text;
+    element.classList.add('show');
+    clearTimeout(timer);
+    timer = setTimeout(() => element.classList.remove('show'), ms);
+  };
+}

package/src/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The kit's browser half: what an extension's pages, offscreen document and
+ * service worker load. Every function takes the `chrome` APIs it uses as
+ * arguments, so tests run the real logic against fakes.
+ *
+ * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
+ * in `@arraypress/extension-kit/testing`, and the stylesheet is
+ * `@arraypress/extension-kit/chrome-ui.css`.
+ *
+ * @module extension-kit
+ */
+export { githubAboutLinks, isPlaceholder } from './about/links.js';
+export { setShortcuts } from './commands/shortcuts.js';
+export { localize, translator } from './dom/i18n.js';
+export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
+export { createSettingsSaver } from './settings/saver.js';
+export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
+export { createSettingsStore } from './settings/store.js';
+export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
+export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
+export { OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen, } from './toolbar/theme.js';

package/src/index.js

@@ -0,0 +1,24 @@
+/**
+ * The kit's browser half: what an extension's pages, offscreen document and
+ * service worker load. Every function takes the `chrome` APIs it uses as
+ * arguments, so tests run the real logic against fakes.
+ *
+ * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
+ * in `@arraypress/extension-kit/testing`, and the stylesheet is
+ * `@arraypress/extension-kit/chrome-ui.css`.
+ *
+ * @module extension-kit
+ */
+
+export { githubAboutLinks, isPlaceholder } from './about/links.js';
+export { setShortcuts } from './commands/shortcuts.js';
+export { localize, translator } from './dom/i18n.js';
+export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
+export { createSettingsSaver } from './settings/saver.js';
+export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
+export { createSettingsStore } from './settings/store.js';
+export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
+export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
+export {
+  OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen,
+} from './toolbar/theme.js';

package/src/settings/saver.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Debounced saving for an options page. Chrome Sync allows 120 writes a
+ * minute, and a person flicking switches can beat that, so changes apply at
+ * once on the page but reach storage only once the clicks stop: a burst of
+ * toggles is one sync write. If sync refuses anyway, the store keeps the
+ * change on this computer and the saver tries again later.
+ *
+ * @module settings/saver
+ */
+import type { SettingsStore } from './store.js';
+import type { SyncedStorage } from './storage.js';
+export type SaverOptions<S extends Record<string, unknown>> = {
+    /**
+     * Quiet time before a write, ms. Default 1000.
+     */
+    delay?: number;
+    /**
+     * Wait before retrying what sync refused, ms. Default 60,000.
+     */
+    retryAfter?: number;
+    /**
+     * Called with every setting after each write.
+     */
+    onSaved?: (settings: S) => void;
+};
+export type SettingsSaver<S extends Record<string, unknown>> = {
+    /**
+     * A copy of the changes not yet written, to lay over what storage holds.
+     */
+    pending: Partial<S>;
+    /**
+     * Queue `changes`; the write starts once `delay` passes quietly.
+     */
+    save: (changes: Partial<S>) => void;
+    /**
+     * Write what's queued now (call it as the page is hidden);
+     * resolves once every write so far has finished.
+     */
+    flush: () => Promise<unknown>;
+    /**
+     * Cancel the timers (tests, or a page being torn down).
+     */
+    stop: () => void;
+};
+/** @import { SettingsStore } from './store.js' */
+/** @import { SyncedStorage } from './storage.js' */
+/**
+ * @template {Record<string, unknown>} S
+ * @typedef {object} SaverOptions
+ * @property {number} [delay] Quiet time before a write, ms. Default 1000.
+ * @property {number} [retryAfter] Wait before retrying what sync refused, ms. Default 60,000.
+ * @property {(settings: S) => void} [onSaved] Called with every setting after each write.
+ */
+/**
+ * @template {Record<string, unknown>} S
+ * @typedef {object} SettingsSaver
+ * @property {Partial<S>} pending A copy of the changes not yet written, to lay over what storage holds.
+ * @property {(changes: Partial<S>) => void} save Queue `changes`; the write starts once `delay` passes quietly.
+ * @property {() => Promise<unknown>} flush Write what's queued now (call it as the page is hidden);
+ *   resolves once every write so far has finished.
+ * @property {() => void} stop Cancel the timers (tests, or a page being torn down).
+ */
+/**
+ * Make a debounced saver over a settings store.
+ *
+ * @template {Record<string, unknown>} S
+ * @param {SettingsStore<S>} store - The extension's settings store.
+ * @param {SyncedStorage} storage - `chrome.storage`, or a fake.
+ * @param {SaverOptions<S>} [options] - Timing and the saved callback.
+ * @returns {SettingsSaver<S>} The saver.
+ * @example
+ * const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
+ * toggle.addEventListener('change', () => saver.save({ compact: toggle.checked }));
+ * addEventListener('pagehide', () => saver.flush());
+ */
+export declare function createSettingsSaver<S extends Record<string, unknown>>(store: SettingsStore<S>, storage: SyncedStorage, { delay, retryAfter, onSaved }?: SaverOptions<S>): SettingsSaver<S>;

package/src/settings/saver.js

@@ -0,0 +1,98 @@
+/**
+ * Debounced saving for an options page. Chrome Sync allows 120 writes a
+ * minute, and a person flicking switches can beat that, so changes apply at
+ * once on the page but reach storage only once the clicks stop: a burst of
+ * toggles is one sync write. If sync refuses anyway, the store keeps the
+ * change on this computer and the saver tries again later.
+ *
+ * @module settings/saver
+ */
+
+/** @import { SettingsStore } from './store.js' */
+/** @import { SyncedStorage } from './storage.js' */
+
+/**
+ * @template {Record<string, unknown>} S
+ * @typedef {object} SaverOptions
+ * @property {number} [delay] Quiet time before a write, ms. Default 1000.
+ * @property {number} [retryAfter] Wait before retrying what sync refused, ms. Default 60,000.
+ * @property {(settings: S) => void} [onSaved] Called with every setting after each write.
+ */
+
+/**
+ * @template {Record<string, unknown>} S
+ * @typedef {object} SettingsSaver
+ * @property {Partial<S>} pending A copy of the changes not yet written, to lay over what storage holds.
+ * @property {(changes: Partial<S>) => void} save Queue `changes`; the write starts once `delay` passes quietly.
+ * @property {() => Promise<unknown>} flush Write what's queued now (call it as the page is hidden);
+ *   resolves once every write so far has finished.
+ * @property {() => void} stop Cancel the timers (tests, or a page being torn down).
+ */
+
+/**
+ * Make a debounced saver over a settings store.
+ *
+ * @template {Record<string, unknown>} S
+ * @param {SettingsStore<S>} store - The extension's settings store.
+ * @param {SyncedStorage} storage - `chrome.storage`, or a fake.
+ * @param {SaverOptions<S>} [options] - Timing and the saved callback.
+ * @returns {SettingsSaver<S>} The saver.
+ * @example
+ * const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
+ * toggle.addEventListener('change', () => saver.save({ compact: toggle.checked }));
+ * addEventListener('pagehide', () => saver.flush());
+ */
+export function createSettingsSaver(store, storage, { delay = 1000, retryAfter = 60_000, onSaved = () => {} } = {}) {
+  /** @type {Partial<S>} */
+  let pending = {};
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let retryTimer;
+  /** @type {Promise<unknown>} */
+  let writing = Promise.resolve();
+
+  /**
+   * Track a write so `flush()` can be awaited; a failure is logged, never thrown.
+   *
+   * @param {Promise<void>} promise
+   * @returns {Promise<unknown>}
+   */
+  const track = (promise) => {
+    writing = Promise.all([writing, promise.catch((error) => console.error('Saving settings:', error))]);
+    return writing;
+  };
+
+  function retry() {
+    track(store.retryUnsynced(storage).then((synced) => {
+      if (!synced) retryTimer = setTimeout(retry, retryAfter);
+    }));
+  }
+
+  /** Writes start at once, not after earlier ones finish: Chrome applies them in order. */
+  function flush() {
+    clearTimeout(timer);
+    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);
+      onSaved(settings);
+    }));
+  }
+
+  return {
+    get pending() { return { ...pending }; },
+    save(changes) {
+      pending = { ...pending, ...changes };
+      clearTimeout(timer);
+      timer = setTimeout(flush, delay);
+    },
+    flush,
+    stop() {
+      clearTimeout(timer);
+      clearTimeout(retryTimer);
+    },
+  };
+}

package/src/settings/storage.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The slice of `chrome.storage` the settings store uses, as types, plus the
+ * small helpers every part of the store shares.
+ *
+ * The store never touches the `chrome` global: callers pass `chrome.storage`
+ * (or a fake in tests), so the logic runs and is tested unchanged in Node.
+ *
+ * @module settings/storage
+ */
+export type StorageArea = {
+    /**
+     *   Read `keys` (all when null); missing keys are absent from the result.
+     */
+    get: (keys?: string | string[] | null) => Promise<Record<string, any>>;
+    /**
+     * Write `items`.
+     */
+    set: (items: Record<string, unknown>) => Promise<void>;
+    /**
+     * Remove `keys`.
+     */
+    remove: (keys: string | string[]) => Promise<void>;
+};
+export type SyncedStorage = {
+    /**
+     * `chrome.storage.sync`: follows the user's Chrome Sync.
+     */
+    sync: StorageArea;
+    /**
+     * `chrome.storage.local`: this computer only.
+     */
+    local: StorageArea;
+};
+export type StorageChange = {
+    oldValue?: unknown;
+    newValue?: unknown;
+};
+/**
+ * One `chrome.storage` area (`chrome.storage.sync`, `.local`, …), promise form.
+ *
+ * @typedef {object} StorageArea
+ * @property {(keys?: string | string[] | null) => Promise<Record<string, any>>} get
+ *   Read `keys` (all when null); missing keys are absent from the result.
+ * @property {(items: Record<string, unknown>) => Promise<void>} set Write `items`.
+ * @property {(keys: string | string[]) => Promise<void>} remove Remove `keys`.
+ */
+/**
+ * `chrome.storage`, as far as settings need it: the synced area and this
+ * computer's own.
+ *
+ * @typedef {object} SyncedStorage
+ * @property {StorageArea} sync `chrome.storage.sync`: follows the user's Chrome Sync.
+ * @property {StorageArea} local `chrome.storage.local`: this computer only.
+ */
+/**
+ * One entry of a `chrome.storage.onChanged` event.
+ *
+ * @typedef {{oldValue?: unknown, newValue?: unknown}} StorageChange
+ */
+/**
+ * Chrome refuses a sync item over 8,192 bytes (key plus JSON value):
+ * `chrome.storage.sync.QUOTA_BYTES_PER_ITEM`.
+ */
+export declare const MAX_SYNC_ITEM_BYTES = 8192;
+/**
+ * The entries of `object` whose keys are in `keys`, in `keys`' order.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} object - Where to pick from.
+ * @param {readonly string[]} keys - Which keys to keep; absent ones are skipped.
+ * @returns {Partial<T>} A new object.
+ * @example
+ * pick({ a: 1, b: 2 }, ['b', 'c']); // { b: 2 }
+ */
+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`.
+ *
+ * @param {string} key - The item's key.
+ * @param {unknown} value - The item's value.
+ * @returns {number} Bytes.
+ */
+export declare function syncItemBytes(key: string, value: unknown): number;
+/**
+ * Whether an object has no own keys.
+ *
+ * @param {object} object - The object to look at.
+ * @returns {boolean} True for `{}`.
+ */
+export declare function isEmpty(object: object): boolean;

package/src/settings/storage.js

@@ -0,0 +1,76 @@
+/**
+ * The slice of `chrome.storage` the settings store uses, as types, plus the
+ * small helpers every part of the store shares.
+ *
+ * The store never touches the `chrome` global: callers pass `chrome.storage`
+ * (or a fake in tests), so the logic runs and is tested unchanged in Node.
+ *
+ * @module settings/storage
+ */
+
+/**
+ * One `chrome.storage` area (`chrome.storage.sync`, `.local`, …), promise form.
+ *
+ * @typedef {object} StorageArea
+ * @property {(keys?: string | string[] | null) => Promise<Record<string, any>>} get
+ *   Read `keys` (all when null); missing keys are absent from the result.
+ * @property {(items: Record<string, unknown>) => Promise<void>} set Write `items`.
+ * @property {(keys: string | string[]) => Promise<void>} remove Remove `keys`.
+ */
+
+/**
+ * `chrome.storage`, as far as settings need it: the synced area and this
+ * computer's own.
+ *
+ * @typedef {object} SyncedStorage
+ * @property {StorageArea} sync `chrome.storage.sync`: follows the user's Chrome Sync.
+ * @property {StorageArea} local `chrome.storage.local`: this computer only.
+ */
+
+/**
+ * One entry of a `chrome.storage.onChanged` event.
+ *
+ * @typedef {{oldValue?: unknown, newValue?: unknown}} StorageChange
+ */
+
+/**
+ * Chrome refuses a sync item over 8,192 bytes (key plus JSON value):
+ * `chrome.storage.sync.QUOTA_BYTES_PER_ITEM`.
+ */
+export const MAX_SYNC_ITEM_BYTES = 8192;
+
+/**
+ * The entries of `object` whose keys are in `keys`, in `keys`' order.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} object - Where to pick from.
+ * @param {readonly string[]} keys - Which keys to keep; absent ones are skipped.
+ * @returns {Partial<T>} A new object.
+ * @example
+ * pick({ a: 1, b: 2 }, ['b', 'c']); // { b: 2 }
+ */
+export function pick(object, keys) {
+  return /** @type {Partial<T>} */ (Object.fromEntries(keys.filter((key) => key in object).map((key) => [key, object[key]])));
+}
+
+/**
+ * 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`.
+ *
+ * @param {string} key - The item's key.
+ * @param {unknown} value - The item's value.
+ * @returns {number} Bytes.
+ */
+export function syncItemBytes(key, value) {
+  return new TextEncoder().encode(key + JSON.stringify(value)).length;
+}
+
+/**
+ * Whether an object has no own keys.
+ *
+ * @param {object} object - The object to look at.
+ * @returns {boolean} True for `{}`.
+ */
+export function isEmpty(object) {
+  return Object.keys(object).length === 0;
+}