@arraypress/extension-kit 1.6.0 → 1.7.0

package/src/index.d.ts

@@ -1,8 +1,9 @@
 /**
- * The kit's browser half: what an extension's pages, offscreen document and
- * service worker load, Chrome's page components (the ⋮ menu, the one-field
- * dialog, the toast with Undo, a settings card's site list) and per-site
- * lists' sites included. Every function takes the `chrome`
+ * The kit's browser half: what an extension's pages, offscreen document,
+ * service worker and content scripts load, Chrome's page components (the ⋮
+ * menu, the text dialog, the toast with Undo, a settings card's site list,
+ * the built-in AI row), per-site lists' sites, Chrome's on-device model, and
+ * a content script's slices and change watcher included. 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
@@ -12,7 +13,10 @@
  * @module extension-kit
  */
 export { githubAboutLinks, isPlaceholder } from './about/links.js';
+export { MODEL_MESSAGES, chromeLanguageModel, createModelSession, describeModel, downloadModel, modelAvailability, } from './ai/model.js';
 export { setShortcuts } from './commands/shortcuts.js';
+export { BLOCK_CHARS, SLICE_MS, blocksOf, inSlices } from './content/slices.js';
+export { MAX_WAIT_MS, SETTLE_MS, watchChanges } from './content/watch.js';
 export { focusedElement } from './dom/focus.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
@@ -28,9 +32,21 @@ 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';
 export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
+export { createModelRow } from './ui/model-row.js';
 export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
 export { askFields, askText, checkText, fieldIds } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
+export type Availability = import('./ai/model.js').Availability;
+export type InitialPrompt = import('./ai/model.js').InitialPrompt;
+export type LanguageModelOptions = import('./ai/model.js').LanguageModelOptions;
+export type LanguageModelSession = import('./ai/model.js').LanguageModelSession;
+export type LanguageModelStatic = import('./ai/model.js').LanguageModelStatic;
+export type ModelAnswer = import('./ai/model.js').ModelAnswer;
+export type ModelSession = import('./ai/model.js').ModelSession;
+export type ModelStatus = import('./ai/model.js').ModelStatus;
+export type SliceOptions = import('./content/slices.js').SliceOptions;
+export type WatchHandlers = import('./content/watch.js').WatchHandlers;
+export type ModelRow = import('./ui/model-row.js').ModelRow;
 export type ContentScript = import('./scripting/registration.js').ContentScript;
 export type ActionMenu = import('./ui/menu.js').ActionMenu;
 export type MenuEntry = import('./ui/menu.js').MenuEntry;
@@ -44,6 +60,17 @@ export type Toast = import('./ui/toast.js').Toast;
 /**
  * The page helpers' types, for a page's JSDoc.
  *
+ * @typedef {import('./ai/model.js').Availability} Availability
+ * @typedef {import('./ai/model.js').InitialPrompt} InitialPrompt
+ * @typedef {import('./ai/model.js').LanguageModelOptions} LanguageModelOptions
+ * @typedef {import('./ai/model.js').LanguageModelSession} LanguageModelSession
+ * @typedef {import('./ai/model.js').LanguageModelStatic} LanguageModelStatic
+ * @typedef {import('./ai/model.js').ModelAnswer} ModelAnswer
+ * @typedef {import('./ai/model.js').ModelSession} ModelSession
+ * @typedef {import('./ai/model.js').ModelStatus} ModelStatus
+ * @typedef {import('./content/slices.js').SliceOptions} SliceOptions
+ * @typedef {import('./content/watch.js').WatchHandlers} WatchHandlers
+ * @typedef {import('./ui/model-row.js').ModelRow} ModelRow
  * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
  * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu
  * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry

package/src/index.js

@@ -1,8 +1,9 @@
 /**
- * The kit's browser half: what an extension's pages, offscreen document and
- * service worker load, Chrome's page components (the ⋮ menu, the one-field
- * dialog, the toast with Undo, a settings card's site list) and per-site
- * lists' sites included. Every function takes the `chrome`
+ * The kit's browser half: what an extension's pages, offscreen document,
+ * service worker and content scripts load, Chrome's page components (the ⋮
+ * menu, the text dialog, the toast with Undo, a settings card's site list,
+ * the built-in AI row), per-site lists' sites, Chrome's on-device model, and
+ * a content script's slices and change watcher included. 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
@@ -13,7 +14,12 @@
  */
 
 export { githubAboutLinks, isPlaceholder } from './about/links.js';
+export {
+  MODEL_MESSAGES, chromeLanguageModel, createModelSession, describeModel, downloadModel, modelAvailability,
+} from './ai/model.js';
 export { setShortcuts } from './commands/shortcuts.js';
+export { BLOCK_CHARS, SLICE_MS, blocksOf, inSlices } from './content/slices.js';
+export { MAX_WAIT_MS, SETTLE_MS, watchChanges } from './content/watch.js';
 export { focusedElement } from './dom/focus.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
@@ -33,6 +39,7 @@ export {
   OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen,
 } from './toolbar/theme.js';
 export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
+export { createModelRow } from './ui/model-row.js';
 export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
 export { askFields, askText, checkText, fieldIds } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
@@ -40,6 +47,17 @@ export { TOAST_MS, createToast } from './ui/toast.js';
 /**
  * The page helpers' types, for a page's JSDoc.
  *
+ * @typedef {import('./ai/model.js').Availability} Availability
+ * @typedef {import('./ai/model.js').InitialPrompt} InitialPrompt
+ * @typedef {import('./ai/model.js').LanguageModelOptions} LanguageModelOptions
+ * @typedef {import('./ai/model.js').LanguageModelSession} LanguageModelSession
+ * @typedef {import('./ai/model.js').LanguageModelStatic} LanguageModelStatic
+ * @typedef {import('./ai/model.js').ModelAnswer} ModelAnswer
+ * @typedef {import('./ai/model.js').ModelSession} ModelSession
+ * @typedef {import('./ai/model.js').ModelStatus} ModelStatus
+ * @typedef {import('./content/slices.js').SliceOptions} SliceOptions
+ * @typedef {import('./content/watch.js').WatchHandlers} WatchHandlers
+ * @typedef {import('./ui/model-row.js').ModelRow} ModelRow
  * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
  * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu
  * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry

package/src/styles/chrome-ui.css

@@ -139,6 +139,7 @@
     /* Icons for link rows (cr:open-in-new, cr:arrow-right / subpage arrow) and ⋮ buttons (cr:more-vert). */
     --icon-open-in-new: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M19 19H5V5h7V3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14c1.1 0 2-.9 2-2v-7h-2v7zM14 3v2h3.59l-9.83 9.83 1.41 1.41L19 6.41V10h2V3h-7z'/%3E%3C/svg%3E");
     --icon-arrow-right: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M10 6 8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z'/%3E%3C/svg%3E");
+    --icon-arrow-back: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M20 11H7.83l5.59-5.59L12 4l-8 8 8 8 1.41-1.41L7.83 13H20v-2z'/%3E%3C/svg%3E");
     --icon-more-vert: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2zm0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z'/%3E%3C/svg%3E");
 
     /* Sizes. */
@@ -300,6 +301,16 @@ button.link:hover { background: none; text-decoration: underline; }
 /* The ⋮ icon without a sprite: <span class="icon icon-more-vert" aria-hidden="true">. */
 .icon-more-vert { display: inline-block; background: currentColor; mask: var(--icon-more-vert) center / contain no-repeat; }
 
+/* The back arrow (cr:arrow-back), for a subpage's header. */
+.icon-arrow-back { display: inline-block; background: currentColor; mask: var(--icon-arrow-back) center / contain no-repeat; }
+.icon-arrow-back:dir(rtl) { transform: scaleX(-1); }
+
+/* settings-subpage's header, at the top of its card: the back button, then the subpage's title.
+   <div class="subpage-head"><button class="icon-button" aria-label="Back"><span class="icon icon-arrow-back"></span></button><h2>Cookies</h2></div> */
+.subpage-head { display: flex; align-items: center; gap: 8px; min-height: 56px; padding: 0 20px 0 8px; }
+.subpage-head h2 { margin: 0; font-size: 15px; font-weight: 400; color: var(--text); overflow-wrap: anywhere; }
+.subpage-head .icon-button { color: var(--icon-muted); }
+
 .sprite { position: absolute; width: 0; height: 0; overflow: hidden; }
 
 /* --------------------------------------------------------------- Fields */

package/src/testing/e2e.d.ts

@@ -193,6 +193,21 @@ export type CheckRunner = {
 export declare function checkRunner({ timeout: runnerTimeout }?: {
     timeout?: number;
 }): CheckRunner;
+/**
+ * Run a script's checks: an error outside any check is a failure, the
+ * clean-ups (closing browsers and servers) always run, in order, then the
+ * tally prints (and exits 1 on a failure). From the copies in Better Prices,
+ * Better Downloads, Better Saves and Clean Links (`test/e2e/helpers.mjs`).
+ *
+ * @param {CheckRunner} runner - From {@link checkRunner}.
+ * @param {() => Promise<void>} body - The checks.
+ * @param {readonly (() => Promise<unknown>)[]} cleanUps - Closing browsers and servers, in order.
+ * @returns {Promise<void>}
+ * @example
+ * const runner = checkRunner();
+ * await runChecks(runner, async () => { await runner.check('it hides', async () => { … }); }, [close, site.close]);
+ */
+export declare function runChecks(runner: CheckRunner, body: () => Promise<void>, cleanUps: readonly (() => Promise<unknown>)[]): Promise<void>;
 export type SchemePage = {
     /**
      * From the extension's root, e.g. `options/options.html`.

package/src/testing/e2e.js

@@ -12,7 +12,7 @@ import assert from 'node:assert/strict';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { deadline } from '../time/time.js';
+import { deadline, within } from '../time/time.js';
 
 /** @import { BrowserContext, BrowserType, CDPSession, Page, Worker } from 'playwright' */
 
@@ -245,6 +245,31 @@ export function checkRunner({ timeout: runnerTimeout = CHECK_MS } = {}) {
   };
 }
 
+/**
+ * Run a script's checks: an error outside any check is a failure, the
+ * clean-ups (closing browsers and servers) always run, in order, then the
+ * tally prints (and exits 1 on a failure). From the copies in Better Prices,
+ * Better Downloads, Better Saves and Clean Links (`test/e2e/helpers.mjs`).
+ *
+ * @param {CheckRunner} runner - From {@link checkRunner}.
+ * @param {() => Promise<void>} body - The checks.
+ * @param {readonly (() => Promise<unknown>)[]} cleanUps - Closing browsers and servers, in order.
+ * @returns {Promise<void>}
+ * @example
+ * const runner = checkRunner();
+ * await runChecks(runner, async () => { await runner.check('it hides', async () => { … }); }, [close, site.close]);
+ */
+export async function runChecks(runner, body, cleanUps) {
+  try {
+    await body();
+  } catch (error) {
+    runner.fail(`unexpected: ${error instanceof Error ? error.stack : error}`);
+  } finally {
+    for (const cleanUp of cleanUps) await within(Promise.resolve().then(cleanUp), 30_000, undefined);
+  }
+  runner.finish();
+}
+
 /**
  * A page of the extension that reports its colour scheme.
  *

package/src/testing/fake-model.d.ts

@@ -0,0 +1,87 @@
+/**
+ * A stand-in for Chrome's `LanguageModel` (the Prompt API), with its shape,
+ * for an extension's unit tests and its e2e build (whose hook puts it on the
+ * worker's or page's `globalThis`: Playwright's Chromium has no model). It
+ * acts out what a real Chrome does: a model still to download (with
+ * progress), one this computer can't run, a slow first session (the cold
+ * start), a slow answer, an answer cut short by its signal, and a failure.
+ * Moved here from Better Downloads' tests, so every extension that uses the
+ * model tests against the same one.
+ *
+ * Plain browser JavaScript with no Node imports, so a test build can copy it in.
+ *
+ * @module testing/fake-model
+ */
+import type { LanguageModelOptions, LanguageModelStatic, PromptOptions } from '../ai/model.js';
+export type FakeModelState = {
+    /**
+     * What `availability()` says.
+     */
+    availability: 'available' | 'downloadable' | 'downloading' | 'unavailable';
+    /**
+     * How long making a session takes (a cold start is ~18 s on a real Chrome).
+     */
+    createMs: number;
+    /**
+     * How long an answer takes.
+     */
+    answerMs: number;
+    /**
+     * The answer to a prompt.
+     */
+    answer: (prompt: string, options: PromptOptions) => string;
+    /**
+     * Whether answers fail (the model gave up).
+     */
+    failPrompt: boolean;
+    /**
+     * Whether a download fails part way.
+     */
+    failDownload: boolean;
+};
+export type FakeModelLog = {
+    /**
+     * Each `availability()`'s options.
+     */
+    availability: LanguageModelOptions[];
+    /**
+     * Each `create()`'s options.
+     */
+    created: LanguageModelOptions[];
+    /**
+     * Each prompt.
+     */
+    prompts: string[];
+    /**
+     * Each prompt's options (signal, responseConstraint).
+     */
+    promptOptions: PromptOptions[];
+    /**
+     * Sessions cloned.
+     */
+    cloned: number;
+    /**
+     * Prompts and creates stopped by their signal.
+     */
+    aborted: number;
+    /**
+     * Sessions let go.
+     */
+    destroyed: number;
+};
+export type FakeLanguageModel = LanguageModelStatic & {
+    state: FakeModelState;
+    log: FakeModelLog;
+    set: (patch: Partial<FakeModelState>) => void;
+};
+/**
+ * A fake Prompt API.
+ *
+ * @param {Partial<FakeModelState>} [initial] - How it starts (default: ready, instant, answers “Fake answer”).
+ * @returns {FakeLanguageModel} The API, its state and log.
+ * @example
+ * const model = fakeLanguageModel({ createMs: 18_000 }); // a cold start
+ * const sessions = createModelSession({ model: () => model, options });
+ * (await sessions.ask('Hi', { timeoutMs: 2500 })).reason; // 'late'
+ */
+export declare function fakeLanguageModel(initial?: Partial<FakeModelState>): FakeLanguageModel;

package/src/testing/fake-model.js

@@ -0,0 +1,142 @@
+/**
+ * A stand-in for Chrome's `LanguageModel` (the Prompt API), with its shape,
+ * for an extension's unit tests and its e2e build (whose hook puts it on the
+ * worker's or page's `globalThis`: Playwright's Chromium has no model). It
+ * acts out what a real Chrome does: a model still to download (with
+ * progress), one this computer can't run, a slow first session (the cold
+ * start), a slow answer, an answer cut short by its signal, and a failure.
+ * Moved here from Better Downloads' tests, so every extension that uses the
+ * model tests against the same one.
+ *
+ * Plain browser JavaScript with no Node imports, so a test build can copy it in.
+ *
+ * @module testing/fake-model
+ */
+
+/** @import { LanguageModelOptions, LanguageModelSession, LanguageModelStatic, PromptOptions } from '../ai/model.js' */
+
+/**
+ * How the fake behaves; change it at any time with `set`.
+ *
+ * @typedef {object} FakeModelState
+ * @property {'available' | 'downloadable' | 'downloading' | 'unavailable'} availability What `availability()` says.
+ * @property {number} createMs How long making a session takes (a cold start is ~18 s on a real Chrome).
+ * @property {number} answerMs How long an answer takes.
+ * @property {(prompt: string, options: PromptOptions) => string} answer The answer to a prompt.
+ * @property {boolean} failPrompt Whether answers fail (the model gave up).
+ * @property {boolean} failDownload Whether a download fails part way.
+ */
+
+/**
+ * What the fake was asked, for tests to look at.
+ *
+ * @typedef {object} FakeModelLog
+ * @property {LanguageModelOptions[]} availability Each `availability()`'s options.
+ * @property {LanguageModelOptions[]} created Each `create()`'s options.
+ * @property {string[]} prompts Each prompt.
+ * @property {PromptOptions[]} promptOptions Each prompt's options (signal, responseConstraint).
+ * @property {number} cloned Sessions cloned.
+ * @property {number} aborted Prompts and creates stopped by their signal.
+ * @property {number} destroyed Sessions let go.
+ */
+
+/**
+ * A fake Prompt API with its state, its log, and `set` to change the state.
+ *
+ * @typedef {LanguageModelStatic & {state: FakeModelState, log: FakeModelLog, set: (patch: Partial<FakeModelState>) => void}} FakeLanguageModel
+ */
+
+/**
+ * Wait, unless the signal stops it first.
+ *
+ * @param {number} ms - How long.
+ * @param {AbortSignal | undefined} signal - Stops it.
+ * @returns {Promise<void>} Resolves after `ms`; rejects with an AbortError when stopped.
+ */
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new DOMException('Aborted', 'AbortError'));
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+  });
+}
+
+/**
+ * A fake Prompt API.
+ *
+ * @param {Partial<FakeModelState>} [initial] - How it starts (default: ready, instant, answers “Fake answer”).
+ * @returns {FakeLanguageModel} The API, its state and log.
+ * @example
+ * const model = fakeLanguageModel({ createMs: 18_000 }); // a cold start
+ * const sessions = createModelSession({ model: () => model, options });
+ * (await sessions.ask('Hi', { timeoutMs: 2500 })).reason; // 'late'
+ */
+export function fakeLanguageModel(initial = {}) {
+  /** @type {FakeModelState} */
+  const state = {
+    availability: 'available', createMs: 0, answerMs: 0, answer: () => 'Fake answer', failPrompt: false, failDownload: false, ...initial,
+  };
+  /** @type {FakeModelLog} */
+  const log = { availability: [], created: [], prompts: [], promptOptions: [], cloned: 0, aborted: 0, destroyed: 0 };
+
+  /**
+   * A session.
+   *
+   * @returns {LanguageModelSession} It.
+   */
+  const session = () => ({
+    async prompt(prompt, options = {}) {
+      log.prompts.push(prompt);
+      log.promptOptions.push(options);
+      try {
+        await wait(state.answerMs, options.signal);
+      } catch (error) {
+        log.aborted++;
+        throw error;
+      }
+      if (state.failPrompt) throw new DOMException('The model failed', 'UnknownError');
+      return state.answer(prompt, options);
+    },
+    async clone() {
+      log.cloned++;
+      return session();
+    },
+    destroy() {
+      log.destroyed++;
+    },
+  });
+
+  return {
+    state,
+    log,
+    set: (patch) => Object.assign(state, patch),
+    async availability(options = {}) {
+      log.availability.push(options);
+      return state.availability;
+    },
+    async create(options = {}) {
+      log.created.push(options);
+      if (state.availability === 'unavailable') throw new DOMException('Not supported', 'NotSupportedError');
+      if (state.availability !== 'available') {
+        // A download, reported as Chrome reports it, then the model is here.
+        const monitor = new EventTarget();
+        options.monitor?.(monitor);
+        for (const loaded of [0, 0.5, 1]) {
+          if (state.failDownload && loaded === 1) throw new DOMException('Download failed', 'NetworkError');
+          monitor.dispatchEvent(Object.assign(new Event('downloadprogress'), { loaded }));
+        }
+        state.availability = 'available';
+      }
+      try {
+        await wait(state.createMs, options.signal);
+      } catch (error) {
+        log.aborted++;
+        throw error;
+      }
+      return session();
+    },
+  };
+}

package/src/testing/fake-storage.d.ts

@@ -49,6 +49,8 @@ export type FakeChromeStorage = {
      */
     settled: () => Promise<void>;
 };
+/** All of sync's items together may take this many bytes (`chrome.storage.sync.QUOTA_BYTES`). */
+export declare const SYNC_QUOTA_BYTES = 102400;
 /**
  * Make a fake `chrome.storage`.
  *

package/src/testing/fake-storage.js

@@ -49,6 +49,17 @@ export const SYNC_WRITES_PER_MINUTE = 120;
  */
 const viaJson = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
 
+/** All of sync's items together may take this many bytes (`chrome.storage.sync.QUOTA_BYTES`). */
+export const SYNC_QUOTA_BYTES = 102_400;
+
+/**
+ * The bytes an area's items take, as Chrome counts sync's: each key plus its value's JSON, in UTF-8.
+ *
+ * @param {Record<string, unknown>} items - The items.
+ * @returns {number} Bytes.
+ */
+const totalBytes = (items) => Object.entries(items).reduce((sum, [key, value]) => sum + new TextEncoder().encode(key + JSON.stringify(value)).length, 0);
+
 /**
  * Make a fake `chrome.storage`.
  *
@@ -72,10 +83,10 @@ export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = D
   /**
    * @param {string} name
    * @param {Record<string, unknown>} initialData
-   * @param {{quotaPerItem?: number, writesPerMinute?: number}} [limits]
+   * @param {{quotaPerItem?: number, quotaBytes?: number, writesPerMinute?: number}} [limits]
    * @returns {FakeArea}
    */
-  function area(name, initialData, { quotaPerItem, writesPerMinute } = {}) {
+  function area(name, initialData, { quotaPerItem, quotaBytes, writesPerMinute } = {}) {
     /** @type {Record<string, any>} */
     const data = viaJson(initialData);
     /** @type {number[]} */
@@ -108,6 +119,7 @@ export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = D
             throw new Error('Resource::kQuotaBytesPerItem quota exceeded');
           }
         }
+        if (quotaBytes && totalBytes({ ...data, ...items }) > quotaBytes) throw new Error('Resource::kQuotaBytes quota exceeded');
         take();
         /** @type {Record<string, StorageChange>} */
         const changes = {};
@@ -135,7 +147,7 @@ export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = D
 
   return {
     local: area('local', local),
-    sync: area('sync', sync, { quotaPerItem: MAX_SYNC_ITEM_BYTES, writesPerMinute: SYNC_WRITES_PER_MINUTE }),
+    sync: area('sync', sync, { quotaPerItem: MAX_SYNC_ITEM_BYTES, quotaBytes: SYNC_QUOTA_BYTES, writesPerMinute: SYNC_WRITES_PER_MINUTE }),
     session: area('session', session),
     onChanged: { addListener: (listener) => listeners.push(listener) },
     async settled() {

package/src/testing/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * The kit's test helpers: a fake `chrome.storage`, a fake on-device model, Playwright helpers for
  * end-to-end tests (time limits, a pool, a browser that passes for a
  * person's) and a server for their pages, Chrome's install warnings and
  * saved tab groups, and checks for a packaging test. Node only.
@@ -8,19 +8,24 @@
  */
 export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
-export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until, } from './e2e.js';
+export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, until, } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
 export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
+export { fakeLanguageModel } from './fake-model.js';
+export { messageLookup, readMessages } from './messages.js';
 export { serve, testCertificate } from './server.js';
-export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
 export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
 export type CheckRunner = import('./e2e.js').CheckRunner;
+export type FakeLanguageModel = import('./fake-model.js').FakeLanguageModel;
+export type FakeModelState = import('./fake-model.js').FakeModelState;
 export type ExtensionProfile = import('./e2e.js').ExtensionProfile;
 export type LaunchedExtension = import('./e2e.js').LaunchedExtension;
 export type LaunchOptions = import('./e2e.js').LaunchOptions;
+export type Messages = import('./messages.js').Messages;
 export type Exit = import('./live.js').Exit;
 export type LiveOptions = import('./live.js').LiveOptions;
 export type SavedTabGroup = import('./saved-groups.js').SavedTabGroup;
@@ -32,9 +37,12 @@ export type TestServer = import('./server.js').TestServer;
  * The helpers' types, for a test's JSDoc.
  *
  * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./fake-model.js').FakeLanguageModel} FakeLanguageModel
+ * @typedef {import('./fake-model.js').FakeModelState} FakeModelState
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./messages.js').Messages} Messages
  * @typedef {import('./live.js').Exit} Exit
  * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup

package/src/testing/index.js

@@ -1,5 +1,5 @@
 /**
- * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * The kit's test helpers: a fake `chrome.storage`, a fake on-device model, Playwright helpers for
  * end-to-end tests (time limits, a pool, a browser that passes for a
  * person's) and a server for their pages, Chrome's install warnings and
  * saved tab groups, and checks for a packaging test. Node only.
@@ -10,13 +10,15 @@
 export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 export {
-  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until,
+  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, until,
 } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
 export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
+export { fakeLanguageModel } from './fake-model.js';
+export { messageLookup, readMessages } from './messages.js';
 export { serve, testCertificate } from './server.js';
-export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
 export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
@@ -25,9 +27,12 @@ export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings
  * The helpers' types, for a test's JSDoc.
  *
  * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./fake-model.js').FakeLanguageModel} FakeLanguageModel
+ * @typedef {import('./fake-model.js').FakeModelState} FakeModelState
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./messages.js').Messages} Messages
  * @typedef {import('./live.js').Exit} Exit
  * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup

package/src/testing/messages.d.ts

@@ -0,0 +1,33 @@
+export type Messages = Record<string, {
+    message: string;
+    description?: string;
+    placeholders?: Record<string, {
+        content: string;
+    }>;
+}>;
+/**
+ * One locale's messages.json.
+ *
+ * @typedef {Record<string, {message: string, description?: string, placeholders?: Record<string, {content: string}>}>} Messages
+ */
+/**
+ * Read a locale's messages.
+ *
+ * @param {string} extensionDir - The extension's folder (with `_locales/`).
+ * @param {string} locale - "en" or "en_GB".
+ * @returns {Messages} Its messages.
+ * @example
+ * readMessages('extension', 'en_GB').optionsColour.message;
+ */
+export declare function readMessages(extensionDir: string, locale: string): Messages;
+/**
+ * `chrome.i18n.getMessage` over a locale's real messages ('' for a missing key, as Chrome gives).
+ *
+ * @param {string} extensionDir - The extension's folder.
+ * @param {string} [locale] - Default "en"; another locale is read over en.
+ * @returns {(key: string, substitutions?: string | string[]) => string} The lookup.
+ * @example
+ * const t = messageLookup('extension');
+ * t('optionsMoreActions', ['example.com']); // 'More actions for example.com'
+ */
+export declare function messageLookup(extensionDir: string, locale?: string): (key: string, substitutions?: string | string[]) => string;