@arraypress/extension-kit 1.6.0 → 1.7.0

package/src/ai/model.js

@@ -0,0 +1,312 @@
+/**
+ * Chrome's on-device model (Gemini Nano, through the Prompt API), the way
+ * every extension here uses it, following
+ * https://developer.chrome.com/docs/ai/prompt-api:
+ *
+ * - `availability()` is asked with the options `create()` gets, and only an
+ *   'available' model is used: nothing here downloads it, except
+ *   {@link downloadModel}, which a page calls from the person's click (Chrome
+ *   only downloads from a user gesture) and which reports progress;
+ * - one base session, with the instructions and examples, is made once and
+ *   kept; each question goes to a `clone()` of it, so answers don't leak into
+ *   each other;
+ * - each answer has a time limit: an `AbortSignal` stops the answer once
+ *   it's late, and the caller gets a reason instead of a hang;
+ * - the first session after Chrome starts can take ~18 s while the model
+ *   loads (a cold start, M3 Max). A question with a shorter limit gets
+ *   'late', and the session goes on loading for the next one. Nothing loads
+ *   it ahead of time: that would load the model on every start for work that
+ *   may never come.
+ *
+ * Nothing here touches `chrome.*` or the global itself: the Prompt API comes
+ * in as `model` (read when used, since Chrome may add it after start-up), so
+ * tests hand it the kit's fake (`fakeLanguageModel`, `/testing`) at exactly
+ * this edge. TypeScript's DOM library doesn't declare the Prompt API yet, so
+ * the parts used are typed here.
+ *
+ * @module ai/model
+ */
+
+import { within } from '../time/time.js';
+
+/**
+ * The model's answer to `availability()`: 'available', 'downloadable',
+ * 'downloading' or 'unavailable'; and, from {@link modelAvailability},
+ * 'missing' when this Chrome has no Prompt API.
+ *
+ * @typedef {'available' | 'downloadable' | 'downloading' | 'unavailable' | 'missing'} Availability
+ */
+
+/**
+ * @typedef {object} PromptOptions
+ * @property {AbortSignal} [signal] Stops the answer.
+ * @property {object} [responseConstraint] A JSON Schema (or RegExp) the answer must follow.
+ */
+
+/**
+ * @typedef {object} LanguageModelSession
+ * @property {(prompt: string, options?: PromptOptions) => Promise<string>} prompt The whole answer.
+ * @property {(options?: {signal?: AbortSignal}) => Promise<LanguageModelSession>} clone A copy with the same history.
+ * @property {() => void} destroy Let it go.
+ */
+
+/**
+ * @typedef {{role: 'system' | 'user' | 'assistant', content: string}} InitialPrompt
+ */
+
+/**
+ * @typedef {object} LanguageModelOptions
+ * @property {{type: string, languages: string[]}[]} [expectedInputs] What it's given.
+ * @property {{type: string, languages: string[]}[]} [expectedOutputs] What it answers in.
+ * @property {InitialPrompt[]} [initialPrompts] Its instructions and examples.
+ * @property {(monitor: EventTarget) => void} [monitor] Hears `downloadprogress` (`loaded`, 0–1) while the model downloads.
+ * @property {AbortSignal} [signal] Stops creating it.
+ */
+
+/**
+ * @typedef {object} LanguageModelStatic
+ * @property {(options?: LanguageModelOptions) => Promise<Availability>} availability Whether it can run here.
+ * @property {(options?: LanguageModelOptions) => Promise<LanguageModelSession>} create A session (downloads the model first, from a click).
+ */
+
+/**
+ * Chrome's `LanguageModel`, or undefined when this Chrome has none.
+ *
+ * @param {object} [scope] - Where to look. Default `globalThis` (a page, or the service worker).
+ * @returns {LanguageModelStatic | undefined} The Prompt API.
+ * @example
+ * const sessions = createModelSession({ model: chromeLanguageModel, options: ENGLISH });
+ */
+export function chromeLanguageModel(scope = globalThis) {
+  return /** @type {{LanguageModel?: LanguageModelStatic}} */ (scope).LanguageModel;
+}
+
+/**
+ * The model's state, never throwing: 'missing' without a Prompt API, and
+ * 'unavailable' when asking fails.
+ *
+ * @param {LanguageModelStatic | undefined} model - The Prompt API.
+ * @param {LanguageModelOptions} options - The options sessions are created with.
+ * @returns {Promise<Availability>} Its state.
+ * @example
+ * await modelAvailability(chromeLanguageModel(), ENGLISH); // 'available'
+ */
+export async function modelAvailability(model, options) {
+  if (!model) return 'missing';
+  try {
+    return await model.availability(options);
+  } catch {
+    return 'unavailable';
+  }
+}
+
+/**
+ * Download the model, from the person's click: `create()` with a monitor,
+ * the session let go once made. Call it first in the click's handler, with
+ * nothing awaited before it, or Chrome refuses (no user activation).
+ *
+ * @param {LanguageModelStatic | undefined} model - The Prompt API.
+ * @param {LanguageModelOptions} options - The options sessions are created with.
+ * @param {{onProgress?: (loaded: number) => void, signal?: AbortSignal}} [handlers] - `onProgress`: how much is
+ *   downloaded, 0–1, as Chrome reports it; `signal`: stops it.
+ * @returns {Promise<Availability>} The state afterwards ('available' once it's here).
+ * @throws {Error} When there's no Prompt API, or Chrome couldn't download it.
+ * @example
+ * button.addEventListener('click', () => {
+ *   downloadModel(chromeLanguageModel(), ENGLISH, { onProgress: (loaded) => { bar.value = loaded; } })
+ *     .then(show, () => show('downloadable', 'The download didn’t finish. Try again.'));
+ * });
+ */
+export async function downloadModel(model, options, { onProgress, signal } = {}) {
+  if (!model) throw new Error('This Chrome has no Prompt API');
+  const session = await model.create({
+    ...options,
+    ...(signal && { signal }),
+    monitor: (monitor) => monitor.addEventListener('downloadprogress', (event) => {
+      onProgress?.(Number(/** @type {ProgressEvent} */ (event).loaded) || 0);
+    }),
+  });
+  session.destroy();
+  return modelAvailability(model, options);
+}
+
+/**
+ * The settings page's words for a state: standard message keys (the
+ * extension's `_locales` names them alike), as `SITE_LIST_MESSAGES` does
+ * for a site list.
+ */
+export const MODEL_MESSAGES = Object.freeze({
+  /** “Chrome’s built-in AI”: the row's name. */
+  name: 'optionsModel',
+  /** “Checking…” before the state is known. */
+  checking: 'optionsModelChecking',
+  /** “Ready”. */
+  ready: 'optionsModelReady',
+  /** “Needs download”. */
+  needsDownload: 'optionsModelNeedsDownload',
+  /** “Chrome downloads its model once and shares it with every site and extension that uses it”. */
+  downloadHelp: 'optionsModelDownloadHelp',
+  /** “Download”: the button. */
+  download: 'optionsModelDownload',
+  /** “Downloading… $PERCENT$%” (content `$1`). */
+  downloading: 'optionsModelDownloading',
+  /** “The download didn’t finish. Try again.” */
+  downloadFailed: 'optionsModelDownloadFailed',
+  /** “Not supported on this computer”. */
+  unsupported: 'optionsModelUnsupported',
+  /** What a computer needs to run it. */
+  requirements: 'optionsModelRequirements',
+  /** “This Chrome doesn’t have it”. */
+  missing: 'optionsModelMissing',
+  /** What to do about that, and that the extension works without it. */
+  missingHelp: 'optionsModelMissingHelp',
+});
+
+/**
+ * The model's state, as a settings page shows it.
+ *
+ * @typedef {object} ModelStatus
+ * @property {'ready' | 'pending' | 'off'} state Ready to use, can be downloaded, or can't run here.
+ * @property {string} status The status's message key ({@link MODEL_MESSAGES}).
+ * @property {string} help The help's message key ('' for none).
+ * @property {boolean} canDownload Whether to offer Download.
+ */
+
+/**
+ * Describe an availability for a settings page. Pure.
+ *
+ * @param {string} availability - 'available', 'downloadable', 'downloading', 'unavailable' or 'missing'.
+ * @returns {ModelStatus} How to show it.
+ * @example
+ * describeModel('downloadable'); // { state: 'pending', status: 'optionsModelNeedsDownload', help: 'optionsModelDownloadHelp', canDownload: true }
+ */
+export function describeModel(availability) {
+  switch (availability) {
+    case 'available':
+      return { state: 'ready', status: MODEL_MESSAGES.ready, help: '', canDownload: false };
+    case 'downloadable':
+    case 'downloading':
+      return { state: 'pending', status: MODEL_MESSAGES.needsDownload, help: MODEL_MESSAGES.downloadHelp, canDownload: true };
+    case 'missing':
+      return { state: 'off', status: MODEL_MESSAGES.missing, help: MODEL_MESSAGES.missingHelp, canDownload: false };
+    default:
+      return { state: 'off', status: MODEL_MESSAGES.unsupported, help: MODEL_MESSAGES.requirements, canDownload: false };
+  }
+}
+
+/**
+ * What a question got: the answer, or why there's none: the model isn't
+ * on this computer ('unavailable'), the time ran out first ('late', a cold
+ * start among them), the caller's signal stopped it ('aborted'), or the model
+ * failed ('failed').
+ *
+ * @typedef {{text: string, reason: 'answered'} | {text: null, reason: 'unavailable' | 'late' | 'aborted' | 'failed'}} ModelAnswer
+ */
+
+/**
+ * @typedef {object} AskOptions
+ * @property {number} timeoutMs The most the answer may take, from the moment it's asked: the base
+ *   session (if it must be made) and the answer.
+ * @property {AbortSignal} [signal] Stops it sooner (the person cancelled).
+ * @property {object} [responseConstraint] A JSON Schema the answer must follow.
+ */
+
+/**
+ * @typedef {object} ModelSession
+ * @property {() => Promise<Availability>} availability The model's state, or 'missing'.
+ * @property {(prompt: string, options: AskOptions) => Promise<ModelAnswer>} ask Ask a copy of the base session.
+ * @property {() => void} release Let the base session go (the next question makes it again).
+ */
+
+/**
+ * A base session over a Prompt API, made when first needed and kept, each
+ * question asked of a `clone()` within its time limit.
+ *
+ * @param {{model: () => LanguageModelStatic | undefined, options: LanguageModelOptions, initialPrompts?: InitialPrompt[]}} setup -
+ *   `model`: the Prompt API, read when used; `options`: what sessions are made (and availability asked)
+ *   with; `initialPrompts`: the instructions and examples every question starts from.
+ * @returns {ModelSession} The session.
+ * @example
+ * const sessions = createModelSession({
+ *   model: chromeLanguageModel,
+ *   options: { expectedInputs: [{ type: 'text', languages: ['en'] }], expectedOutputs: [{ type: 'text', languages: ['en'] }] },
+ *   initialPrompts: [{ role: 'system', content: 'You name downloaded files.' }],
+ * });
+ * const { text } = await sessions.ask('Site: acme.com', { timeoutMs: 2500 }); // null when late
+ */
+export function createModelSession({ model, options, initialPrompts = [] }) {
+  /** @type {Promise<LanguageModelSession> | null} */
+  let base = null;
+
+  /**
+   * The base session, made once; a failed one isn't kept, so the next question tries again.
+   *
+   * @param {LanguageModelStatic} api - The Prompt API, ready.
+   * @returns {Promise<LanguageModelSession>} The session.
+   */
+  function baseSession(api) {
+    if (!base) {
+      const made = api.create({ ...options, ...(initialPrompts.length && { initialPrompts }) });
+      base = made;
+      made.catch(() => {
+        if (base === made) base = null;
+      });
+    }
+    return base;
+  }
+
+  /**
+   * Ask a copy of the base session; the copy is let go after.
+   *
+   * @param {LanguageModelStatic} api - The Prompt API, ready.
+   * @param {string} prompt - The question.
+   * @param {AbortSignal} signal - Stops it once it's late or the caller stops it.
+   * @param {object | undefined} responseConstraint - The answer's shape.
+   * @returns {Promise<string>} The answer.
+   */
+  async function ask(api, prompt, signal, responseConstraint) {
+    const session = await (await baseSession(api)).clone({ signal });
+    try {
+      return await session.prompt(prompt, { signal, ...(responseConstraint && { responseConstraint }) });
+    } finally {
+      session.destroy();
+    }
+  }
+
+  return {
+    availability: () => modelAvailability(model(), options),
+    async ask(prompt, { timeoutMs, signal, responseConstraint }) {
+      const started = Date.now();
+      if (signal?.aborted) return { text: null, reason: 'aborted' };
+      const api = model();
+      const state = await within(modelAvailability(api, options), timeoutMs, /** @type {Availability | 'late'} */ ('late'));
+      if (state === 'late') return { text: null, reason: 'late' };
+      if (state !== 'available' || !api) return { text: null, reason: 'unavailable' };
+      const stop = new AbortController();
+      const onAbort = () => stop.abort();
+      signal?.addEventListener('abort', onAbort, { once: true });
+      try {
+        // A string is the answer; false, it failed; null, it's late.
+        const outcome = await within(
+          ask(api, prompt, stop.signal, responseConstraint).catch(() => /** @type {false} */ (false)),
+          Math.max(0, timeoutMs - (Date.now() - started)),
+          /** @type {string | false | null} */ (null),
+        );
+        if (typeof outcome === 'string') return { text: outcome, reason: 'answered' };
+        if (signal?.aborted) return { text: null, reason: 'aborted' };
+        if (outcome === null) {
+          stop.abort();
+          return { text: null, reason: 'late' };
+        }
+        return { text: null, reason: 'failed' };
+      } finally {
+        signal?.removeEventListener('abort', onAbort);
+      }
+    },
+    release() {
+      const held = base;
+      base = null;
+      held?.then((session) => session.destroy(), () => {});
+    },
+  };
+}

package/src/build/vendor.js

@@ -28,7 +28,7 @@ const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const KIT = '@arraypress/extension-kit';
 
 /** What a vendored copy of the kit holds, relative to `src/`: everything an extension page or worker may load. */
-export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'scripting', 'settings', 'sites', 'styles', 'time', 'toolbar', 'ui']);
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'ai', 'commands', 'content', 'dom', 'scripting', 'settings', 'sites', 'styles', 'time', 'toolbar', 'ui']);
 
 /** The kit's stylesheet, an absolute path in the installed package. */
 export const STYLESHEET = path.join(SOURCE, 'styles', 'chrome-ui.css');

package/src/content/slices.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A content script's first look at a big page, in slices: the page is cut
+ * into blocks of at most `blockChars` characters of text (a long listing's
+ * cards, a long article's paragraphs), each handed whole to the caller's
+ * work, and the main thread is handed back to the page every `sliceMs`, so
+ * a 2,000-item page never freezes. From Better Prices (`content/slices.js`),
+ * shared with Topicless.
+ *
+ * @module content/slices
+ */
+/** The most text one block holds (characters), by default. */
+export declare const BLOCK_CHARS = 4000;
+/** How long one slice may run before the page gets the main thread back (ms), by default. Shorter slices cost more layout in all. */
+export declare const SLICE_MS = 40;
+/**
+ * The blocks of a part of the page: itself if small enough, else its
+ * children's blocks (its own text nodes as blocks of their own).
+ *
+ * @param {Node} root - The part.
+ * @param {number} [blockChars] - The most text a block holds. Default {@link BLOCK_CHARS}.
+ * @returns {Node[]} The blocks, in page order.
+ * @example
+ * blocksOf(document.body).length; // 1 for a short page, one per card for a long listing
+ */
+export declare function blocksOf(root: Node, blockChars?: number): Node[];
+export type SliceOptions = {
+    /**
+     * The most text a block holds. Default {@link BLOCK_CHARS}.
+     */
+    blockChars?: number;
+    /**
+     * How long a slice may run. Default {@link SLICE_MS}.
+     */
+    sliceMs?: number;
+    /**
+     * Hands the main thread back. Default: a macrotask.
+     */
+    pause?: () => Promise<void>;
+    /**
+     * The clock. Default `performance.now`.
+     */
+    now?: () => number;
+};
+/**
+ * @typedef {object} SliceOptions
+ * @property {number} [blockChars] The most text a block holds. Default {@link BLOCK_CHARS}.
+ * @property {number} [sliceMs] How long a slice may run. Default {@link SLICE_MS}.
+ * @property {() => Promise<void>} [pause] Hands the main thread back. Default: a macrotask.
+ * @property {() => number} [now] The clock. Default `performance.now`.
+ */
+/**
+ * Work through a part of the page in slices: `work(block)` on each block
+ * still in the page, the main thread handed back whenever a slice has run
+ * `sliceMs`.
+ *
+ * @param {Node} root - The part (the body).
+ * @param {(block: Node) => void} work - What to do with one block.
+ * @param {SliceOptions} [options] - Block size, slice length, how to pause.
+ * @returns {Promise<void>} Once every block is done.
+ * @example
+ * await inSlices(document.body, (block) => scanner.scan(block));
+ */
+export declare function inSlices(root: Node, work: (block: Node) => void, { blockChars, sliceMs, pause, now }?: SliceOptions): Promise<void>;

package/src/content/slices.js

@@ -0,0 +1,80 @@
+/**
+ * A content script's first look at a big page, in slices: the page is cut
+ * into blocks of at most `blockChars` characters of text (a long listing's
+ * cards, a long article's paragraphs), each handed whole to the caller's
+ * work, and the main thread is handed back to the page every `sliceMs`, so
+ * a 2,000-item page never freezes. From Better Prices (`content/slices.js`),
+ * shared with Topicless.
+ *
+ * @module content/slices
+ */
+
+/** The most text one block holds (characters), by default. */
+export const BLOCK_CHARS = 4000;
+
+/** How long one slice may run before the page gets the main thread back (ms), by default. Shorter slices cost more layout in all. */
+export const SLICE_MS = 40;
+
+/**
+ * The blocks of a part of the page: itself if small enough, else its
+ * children's blocks (its own text nodes as blocks of their own).
+ *
+ * @param {Node} root - The part.
+ * @param {number} [blockChars] - The most text a block holds. Default {@link BLOCK_CHARS}.
+ * @returns {Node[]} The blocks, in page order.
+ * @example
+ * blocksOf(document.body).length; // 1 for a short page, one per card for a long listing
+ */
+export function blocksOf(root, blockChars = BLOCK_CHARS) {
+  /** @type {Node[]} */
+  const blocks = [];
+  /** @param {Node} node */
+  const cut = (node) => {
+    if (node.nodeType !== 1 || (node.textContent ?? '').length <= blockChars || !node.firstChild) {
+      blocks.push(node);
+      return;
+    }
+    for (const child of node.childNodes) cut(child);
+  };
+  cut(root);
+  return blocks;
+}
+
+/**
+ * Hand the main thread back to the page: a macrotask later.
+ *
+ * @returns {Promise<void>}
+ */
+const nextTask = () => new Promise((resolve) => { setTimeout(resolve, 0); });
+
+/**
+ * @typedef {object} SliceOptions
+ * @property {number} [blockChars] The most text a block holds. Default {@link BLOCK_CHARS}.
+ * @property {number} [sliceMs] How long a slice may run. Default {@link SLICE_MS}.
+ * @property {() => Promise<void>} [pause] Hands the main thread back. Default: a macrotask.
+ * @property {() => number} [now] The clock. Default `performance.now`.
+ */
+
+/**
+ * Work through a part of the page in slices: `work(block)` on each block
+ * still in the page, the main thread handed back whenever a slice has run
+ * `sliceMs`.
+ *
+ * @param {Node} root - The part (the body).
+ * @param {(block: Node) => void} work - What to do with one block.
+ * @param {SliceOptions} [options] - Block size, slice length, how to pause.
+ * @returns {Promise<void>} Once every block is done.
+ * @example
+ * await inSlices(document.body, (block) => scanner.scan(block));
+ */
+export async function inSlices(root, work, { blockChars = BLOCK_CHARS, sliceMs = SLICE_MS, pause = nextTask, now = () => performance.now() } = {}) {
+  let started = now();
+  for (const block of blocksOf(root, blockChars)) {
+    if (!block.isConnected) continue;
+    work(block);
+    if (now() - started > sliceMs) {
+      await pause();
+      started = now();
+    }
+  }
+}

package/src/content/watch.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A content script keeping up with a page that changes (a single-page app,
+ * a list that loads more as you scroll): a MutationObserver that only
+ * collects what changed, and hands it over in one batch a little later,
+ * never touching the page itself. The extension's own elements are ignored
+ * (`ignore`), so what it adds never sets it off again. From Better Prices
+ * (`content/watch.js`), shared with Topicless.
+ *
+ * @module content/watch
+ */
+/** How long after a change the batch waits for more (ms), by default. */
+export declare const SETTLE_MS = 120;
+/** The longest a batch waits while a page keeps changing (ms), by default. */
+export declare const MAX_WAIT_MS = 600;
+export type WatchHandlers = {
+    /**
+     * The nodes added or changed since the last batch, each once,
+     * none inside another.
+     */
+    changed: (nodes: Node[]) => void;
+    /**
+     * A node that left (at once, so what the extension added for it
+     * can go with it).
+     */
+    removed?: (node: Node) => void;
+    /**
+     * Whether a node added or removed is the extension's own.
+     */
+    ignore?: (node: Node) => boolean;
+    /**
+     * How long a batch waits for more. Default {@link SETTLE_MS}.
+     */
+    settleMs?: number;
+    /**
+     * The longest a batch waits. Default {@link MAX_WAIT_MS}.
+     */
+    maxWaitMs?: number;
+    /**
+     * An element whose children changed is handed over again whole
+     * when it has at most this many element children (a split price's pieces; a list's new items
+     * are handed over themselves). Default 6; 0 never.
+     */
+    regroupChildren?: number;
+};
+/**
+ * @typedef {object} WatchHandlers
+ * @property {(nodes: Node[]) => void} changed The nodes added or changed since the last batch, each once,
+ *   none inside another.
+ * @property {(node: Node) => void} [removed] A node that left (at once, so what the extension added for it
+ *   can go with it).
+ * @property {(node: Node) => boolean} [ignore] Whether a node added or removed is the extension's own.
+ * @property {number} [settleMs] How long a batch waits for more. Default {@link SETTLE_MS}.
+ * @property {number} [maxWaitMs] The longest a batch waits. Default {@link MAX_WAIT_MS}.
+ * @property {number} [regroupChildren] An element whose children changed is handed over again whole
+ *   when it has at most this many element children (a split price's pieces; a list's new items
+ *   are handed over themselves). Default 6; 0 never.
+ */
+/**
+ * Watch `root` for changes.
+ *
+ * @param {Node} root - What to watch (the body, or the document element from `document_start`).
+ * @param {WatchHandlers} handlers - What to call, and how long to wait.
+ * @returns {() => void} Stops watching.
+ * @example
+ * const stop = watchChanges(document.body, {
+ *   changed: (nodes) => nodes.forEach((node) => scanner.scan(node)),
+ *   removed: (node) => scanner.forget(node),
+ *   ignore: (node) => node instanceof Element && node.localName === 'better-prices-note',
+ * });
+ */
+export declare function watchChanges(root: Node, { changed, removed, ignore, settleMs, maxWaitMs, regroupChildren, }: WatchHandlers): () => void;

package/src/content/watch.js

@@ -0,0 +1,95 @@
+/**
+ * A content script keeping up with a page that changes (a single-page app,
+ * a list that loads more as you scroll): a MutationObserver that only
+ * collects what changed, and hands it over in one batch a little later,
+ * never touching the page itself. The extension's own elements are ignored
+ * (`ignore`), so what it adds never sets it off again. From Better Prices
+ * (`content/watch.js`), shared with Topicless.
+ *
+ * @module content/watch
+ */
+
+/** How long after a change the batch waits for more (ms), by default. */
+export const SETTLE_MS = 120;
+
+/** The longest a batch waits while a page keeps changing (ms), by default. */
+export const MAX_WAIT_MS = 600;
+
+/**
+ * @typedef {object} WatchHandlers
+ * @property {(nodes: Node[]) => void} changed The nodes added or changed since the last batch, each once,
+ *   none inside another.
+ * @property {(node: Node) => void} [removed] A node that left (at once, so what the extension added for it
+ *   can go with it).
+ * @property {(node: Node) => boolean} [ignore] Whether a node added or removed is the extension's own.
+ * @property {number} [settleMs] How long a batch waits for more. Default {@link SETTLE_MS}.
+ * @property {number} [maxWaitMs] The longest a batch waits. Default {@link MAX_WAIT_MS}.
+ * @property {number} [regroupChildren] An element whose children changed is handed over again whole
+ *   when it has at most this many element children (a split price's pieces; a list's new items
+ *   are handed over themselves). Default 6; 0 never.
+ */
+
+/**
+ * Watch `root` for changes.
+ *
+ * @param {Node} root - What to watch (the body, or the document element from `document_start`).
+ * @param {WatchHandlers} handlers - What to call, and how long to wait.
+ * @returns {() => void} Stops watching.
+ * @example
+ * const stop = watchChanges(document.body, {
+ *   changed: (nodes) => nodes.forEach((node) => scanner.scan(node)),
+ *   removed: (node) => scanner.forget(node),
+ *   ignore: (node) => node instanceof Element && node.localName === 'better-prices-note',
+ * });
+ */
+export function watchChanges(root, {
+  changed, removed = () => {}, ignore = () => false, settleMs = SETTLE_MS, maxWaitMs = MAX_WAIT_MS, regroupChildren = 6,
+}) {
+  /** @type {Set<Node>} */
+  let pending = new Set();
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  let firstAt = 0;
+
+  const flush = () => {
+    timer = undefined;
+    firstAt = 0;
+    const nodes = [...pending].filter((node) => node.isConnected);
+    pending = new Set();
+    // Each subtree once: a node inside another changed node goes with it.
+    const tops = nodes.filter((node) => !nodes.some((other) => other !== node && other.contains(node)));
+    if (tops.length) changed(tops);
+  };
+
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      const target = mutation.target;
+      if (mutation.type === 'characterData') {
+        pending.add(target);
+        continue;
+      }
+      let ours = true;
+      for (const node of mutation.addedNodes) {
+        if (ignore(node)) continue;
+        ours = false;
+        pending.add(node);
+      }
+      for (const node of mutation.removedNodes) {
+        if (ignore(node)) continue;
+        ours = false;
+        removed(node);
+      }
+      if (!ours && target.nodeType === 1 && /** @type {Element} */ (target).childElementCount <= regroupChildren) pending.add(target);
+    }
+    if (!pending.size) return;
+    const now = Date.now();
+    firstAt ||= now;
+    clearTimeout(timer);
+    timer = setTimeout(flush, Math.max(0, Math.min(settleMs, firstAt + maxWaitMs - now)));
+  });
+  observer.observe(root, { childList: true, subtree: true, characterData: true });
+  return () => {
+    observer.disconnect();
+    clearTimeout(timer);
+  };
+}