@arraypress/extension-kit 1.6.0 → 1.8.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), Chrome's window drawn around a capture, 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,8 +13,12 @@
  * @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 { THEMES, WINDOW_BARS, WINDOW_W, letterIcon, windowChrome, windowChromeSvg } from './frame/window.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
 export { setUpPage } from './dom/setup.js';
@@ -28,9 +33,23 @@ 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 WindowTab = import('./frame/window.js').Tab;
+export type WindowTheme = import('./frame/window.js').Theme;
+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 +63,19 @@ 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('./frame/window.js').Tab} WindowTab
+ * @typedef {import('./frame/window.js').Theme} WindowTheme
+ * @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), Chrome's window drawn around a capture, 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,8 +14,14 @@
  */
 
 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 { THEMES, WINDOW_BARS, WINDOW_W, letterIcon, windowChrome, windowChromeSvg } from './frame/window.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
 export { setUpPage } from './dom/setup.js';
@@ -33,6 +40,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 +48,19 @@ 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('./frame/window.js').Tab} WindowTab
+ * @typedef {import('./frame/window.js').Theme} WindowTheme
+ * @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/settings/saver.d.ts

@@ -41,6 +41,14 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
      * Cancel the timers (tests, or a page being torn down).
      */
     stop: () => void;
+    /**
+     *   Hear the settings change elsewhere (another tab, another computer through sync):
+     *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+     *   `chrome.storage.onChanged`.
+     */
+    follow: (onChange: (settings: S) => void, events: {
+        addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void;
+    }) => void;
 };
 /** @import { SettingsStore } from './store.js' */
 /** @import { SyncedStorage } from './storage.js' */
@@ -59,6 +67,10 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
  * @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).
+ * @property {(onChange: (settings: S) => void, events: {addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void}) => void} follow
+ *   Hear the settings change elsewhere (another tab, another computer through sync):
+ *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+ *   `chrome.storage.onChanged`.
  */
 /**
  * Make a debounced saver over a settings store.
@@ -72,5 +84,6 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
  * const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
  * toggle.addEventListener('change', () => saver.save({ compact: toggle.checked }));
  * addEventListener('pagehide', () => saver.flush());
+ * saver.follow((settings) => show(settings), chrome.storage.onChanged);
  */
 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

@@ -27,6 +27,10 @@
  * @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).
+ * @property {(onChange: (settings: S) => void, events: {addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void}) => void} follow
+ *   Hear the settings change elsewhere (another tab, another computer through sync):
+ *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+ *   `chrome.storage.onChanged`.
  */
 
 /**
@@ -41,6 +45,7 @@
  * const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
  * toggle.addEventListener('change', () => saver.save({ compact: toggle.checked }));
  * addEventListener('pagehide', () => saver.flush());
+ * saver.follow((settings) => show(settings), chrome.storage.onChanged);
  */
 export function createSettingsSaver(store, storage, { delay = 1000, retryAfter = 60_000, onSaved = () => {} } = {}) {
   /** @type {Partial<S>} */
@@ -90,6 +95,12 @@ export function createSettingsSaver(store, storage, { delay = 1000, retryAfter =
       timer = setTimeout(flush, delay);
     },
     flush,
+    follow(onChange, events) {
+      events.addListener(async (changes, area) => {
+        if (!store.changed(changes, area).length) return;
+        onChange(store.normalize({ ...(await store.load(storage)), ...pending }));
+      });
+    },
     stop() {
       clearTimeout(timer);
       clearTimeout(retryTimer);

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/heartbeat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How long a page's main thread is held, for performance checks: a heartbeat in the page. From
+ * Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/heartbeat
+ */
+import type { Page } from 'playwright';
+/** @import { Page } from 'playwright' */
+/**
+ * Start a heartbeat in a page: a timer that fires again and again, costing nothing between
+ * beats; the longest gap between two is the longest the main thread was held (the Long Tasks
+ * API misses an extension's isolated world's work, and a `MessageChannel` heartbeat counts as
+ * task time itself). Gaps while the tab is hidden (another tab in front) don't count: Chrome
+ * throttles a hidden tab's timers.
+ *
+ * @param {Page} page - The page.
+ * @returns {Promise<() => Promise<number>>} Stops it and gives the longest gap (ms).
+ * @example
+ * const stop = await heartbeat(page);
+ * await doTheWork();
+ * const held = await stop(); // e.g. 17
+ */
+export declare function heartbeat(page: Page): Promise<() => Promise<number>>;

package/src/testing/heartbeat.js

@@ -0,0 +1,43 @@
+/**
+ * How long a page's main thread is held, for performance checks: a heartbeat in the page. From
+ * Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/heartbeat
+ */
+
+/** @import { Page } from 'playwright' */
+
+/**
+ * Start a heartbeat in a page: a timer that fires again and again, costing nothing between
+ * beats; the longest gap between two is the longest the main thread was held (the Long Tasks
+ * API misses an extension's isolated world's work, and a `MessageChannel` heartbeat counts as
+ * task time itself). Gaps while the tab is hidden (another tab in front) don't count: Chrome
+ * throttles a hidden tab's timers.
+ *
+ * @param {Page} page - The page.
+ * @returns {Promise<() => Promise<number>>} Stops it and gives the longest gap (ms).
+ * @example
+ * const stop = await heartbeat(page);
+ * await doTheWork();
+ * const held = await stop(); // e.g. 17
+ */
+export async function heartbeat(page) {
+  await page.evaluate(() => {
+    const beat = { longest: 0, running: true };
+    Object.assign(window, { extensionKitBeat: beat });
+    let last = performance.now();
+    const tick = () => {
+      const now = performance.now();
+      // A hidden tab's timers are throttled by Chrome: those gaps aren't the page being held.
+      if (!document.hidden) beat.longest = Math.max(beat.longest, now - last);
+      last = now;
+      if (beat.running) setTimeout(tick, 0);
+    };
+    setTimeout(tick, 0);
+  });
+  return () => page.evaluate(() => {
+    const beat = /** @type {{longest: number, running: boolean}} */ (/** @type {any} */ (window).extensionKitBeat);
+    beat.running = false;
+    return beat.longest;
+  });
+}