@arraypress/extension-kit 1.5.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,23 +13,41 @@
  * @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';
 export { setUpPage } from './dom/setup.js';
+export { contentScriptSync } from './scripting/registration.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
 export { MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite, } from './sites/sites.js';
+export { eachLimited } from './time/pool.js';
 export { within } from './time/time.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';
 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;
 export type MenuItem = import('./ui/menu.js').MenuItem;
@@ -41,6 +60,18 @@ 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
  * @typedef {import('./ui/menu.js').MenuItem} MenuItem

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,17 +14,24 @@
  */
 
 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';
 export { setUpPage } from './dom/setup.js';
+export { contentScriptSync } from './scripting/registration.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
 export {
   MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite,
 } from './sites/sites.js';
+export { eachLimited } from './time/pool.js';
 export { within } from './time/time.js';
 export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
 export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
@@ -31,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';
@@ -38,6 +47,18 @@ 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
  * @typedef {import('./ui/menu.js').MenuItem} MenuItem

package/src/scripting/registration.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One registered content script kept in step with what may run: registered,
+ * updated or unregistered to match, each change after the last, so a quick
+ * run of setting and permission changes can't register and unregister out
+ * of order. For an extension whose content script runs on every site only
+ * while an optional all-sites grant is held, less a "Never on" list.
+ *
+ * @module scripting/registration
+ */
+export type ContentScript = Omit<chrome.scripting.RegisteredContentScript, 'id' | 'js'> & {
+    js: string[];
+};
+export type Scripting = Pick<typeof chrome.scripting, 'getRegisteredContentScripts' | 'registerContentScripts' | 'updateContentScripts' | 'unregisterContentScripts'>;
+/** @typedef {Omit<chrome.scripting.RegisteredContentScript, 'id' | 'js'> & {js: string[]}} ContentScript The script, but its id: its `js`, `matches` and the rest. */
+/**
+ * The parts of `chrome.scripting` a registration uses.
+ *
+ * @typedef {Pick<typeof chrome.scripting, 'getRegisteredContentScripts' | 'registerContentScripts' | 'updateContentScripts' | 'unregisterContentScripts'>} Scripting
+ */
+/**
+ * Keep the content script `id` registered as `want()` says: the script, or
+ * null for none. Each call asks `want()` afresh once the change before it is
+ * done, so the last call always wins.
+ *
+ * @param {Scripting} scripting - `chrome.scripting` (or a fake in tests).
+ * @param {string} id - The registered script's id.
+ * @param {() => Promise<ContentScript | null>} want - What should be registered now (settings and
+ *   grants read at the time).
+ * @returns {() => Promise<void>} Makes the registration match; rejects if Chrome refuses.
+ * @example
+ * const sync = contentScriptSync(chrome.scripting, 'prices', async () => (await chrome.permissions.contains({ origins: ALL_SITES })
+ *   ? { js: ['content/loader.js'], matches: ALL_SITES, excludeMatches: neverSites.flatMap(hostPatterns), runAt: 'document_idle' }
+ *   : null));
+ * chrome.permissions.onAdded.addListener(() => sync());
+ */
+export declare function contentScriptSync(scripting: Scripting, id: string, want: () => Promise<ContentScript | null>): () => Promise<void>;

package/src/scripting/registration.js

@@ -0,0 +1,54 @@
+/**
+ * One registered content script kept in step with what may run: registered,
+ * updated or unregistered to match, each change after the last, so a quick
+ * run of setting and permission changes can't register and unregister out
+ * of order. For an extension whose content script runs on every site only
+ * while an optional all-sites grant is held, less a "Never on" list.
+ *
+ * @module scripting/registration
+ */
+
+/** @typedef {Omit<chrome.scripting.RegisteredContentScript, 'id' | 'js'> & {js: string[]}} ContentScript The script, but its id: its `js`, `matches` and the rest. */
+
+/**
+ * The parts of `chrome.scripting` a registration uses.
+ *
+ * @typedef {Pick<typeof chrome.scripting, 'getRegisteredContentScripts' | 'registerContentScripts' | 'updateContentScripts' | 'unregisterContentScripts'>} Scripting
+ */
+
+/**
+ * Keep the content script `id` registered as `want()` says: the script, or
+ * null for none. Each call asks `want()` afresh once the change before it is
+ * done, so the last call always wins.
+ *
+ * @param {Scripting} scripting - `chrome.scripting` (or a fake in tests).
+ * @param {string} id - The registered script's id.
+ * @param {() => Promise<ContentScript | null>} want - What should be registered now (settings and
+ *   grants read at the time).
+ * @returns {() => Promise<void>} Makes the registration match; rejects if Chrome refuses.
+ * @example
+ * const sync = contentScriptSync(chrome.scripting, 'prices', async () => (await chrome.permissions.contains({ origins: ALL_SITES })
+ *   ? { js: ['content/loader.js'], matches: ALL_SITES, excludeMatches: neverSites.flatMap(hostPatterns), runAt: 'document_idle' }
+ *   : null));
+ * chrome.permissions.onAdded.addListener(() => sync());
+ */
+export function contentScriptSync(scripting, id, want) {
+  /** The last change, so the next waits for it. */
+  let queue = Promise.resolve();
+  const apply = async () => {
+    const script = await want();
+    const registered = (await scripting.getRegisteredContentScripts({ ids: [id] })).length > 0;
+    if (!script) {
+      if (registered) await scripting.unregisterContentScripts({ ids: [id] });
+      return;
+    }
+    const full = { ...script, id };
+    if (registered) await scripting.updateContentScripts([full]);
+    else await scripting.registerContentScripts([full]);
+  };
+  return () => {
+    const run = queue.then(apply, apply);
+    queue = run.catch(() => {});
+    return run;
+  };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * A browser that downloads for real, for an extension that names, files or
+ * makes downloads. Playwright normally takes downloads over (CDP's
+ * `Browser.setDownloadBehavior` set to `allowAndName`), saving them under
+ * made-up names where no extension sees them: `downloads.onDeterminingFilename`
+ * never fires, and `chrome.downloads.download`'s names are lost. So the
+ * profile gets its own Downloads folder (Chrome's `download.default_directory`
+ * preference, written before the first start) and the behaviour goes back to
+ * Chrome's default: files land on disk as on a person's computer.
+ *
+ * @module testing/downloads
+ */
+import type { BrowserType } from 'playwright';
+import type { LaunchOptions, LaunchedExtension } from './e2e.js';
+/** @import { BrowserType } from 'playwright' */
+/** @import { LaunchOptions, LaunchedExtension } from './e2e.js' */
+/**
+ * Every file under a folder, as paths from it (Chrome's `.crdownload` files
+ * of downloads still running left out), sorted.
+ *
+ * @param {string} dir - The folder.
+ * @returns {Promise<string[]>} The files.
+ * @example
+ * await filesIn(downloads); // ['Trips/Lake.jpg', 'Trips/Lake 2.jpg']
+ */
+export declare function filesIn(dir: string): Promise<string[]>;
+/**
+ * Load the unpacked extension at `dir` into a fresh profile whose downloads
+ * go to a folder of their own, really.
+ *
+ * @param {BrowserType} chromium - Playwright's `chromium`.
+ * @param {string} dir - The unpacked extension.
+ * @param {LaunchOptions} [options] - As `launchExtension`'s.
+ * @returns {Promise<LaunchedExtension & {downloads: string}>} The running extension, and its
+ *   Downloads folder; `close()` deletes both.
+ * @example
+ * const { context, downloads, close } = await launchDownloading(chromium, 'extension');
+ */
+export declare function launchDownloading(chromium: BrowserType, dir: string, options?: LaunchOptions): Promise<LaunchedExtension & {
+    downloads: string;
+}>;

package/src/testing/downloads.js

@@ -0,0 +1,70 @@
+/**
+ * A browser that downloads for real, for an extension that names, files or
+ * makes downloads. Playwright normally takes downloads over (CDP's
+ * `Browser.setDownloadBehavior` set to `allowAndName`), saving them under
+ * made-up names where no extension sees them: `downloads.onDeterminingFilename`
+ * never fires, and `chrome.downloads.download`'s names are lost. So the
+ * profile gets its own Downloads folder (Chrome's `download.default_directory`
+ * preference, written before the first start) and the behaviour goes back to
+ * Chrome's default: files land on disk as on a person's computer.
+ *
+ * @module testing/downloads
+ */
+
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { extensionProfile } from './e2e.js';
+
+/** @import { BrowserType } from 'playwright' */
+/** @import { LaunchOptions, LaunchedExtension } from './e2e.js' */
+
+/**
+ * Every file under a folder, as paths from it (Chrome's `.crdownload` files
+ * of downloads still running left out), sorted.
+ *
+ * @param {string} dir - The folder.
+ * @returns {Promise<string[]>} The files.
+ * @example
+ * await filesIn(downloads); // ['Trips/Lake.jpg', 'Trips/Lake 2.jpg']
+ */
+export async function filesIn(dir) {
+  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && !entry.name.endsWith('.crdownload'))
+    .map((entry) => path.relative(dir, path.join(entry.parentPath, entry.name))).sort();
+}
+
+/**
+ * Load the unpacked extension at `dir` into a fresh profile whose downloads
+ * go to a folder of their own, really.
+ *
+ * @param {BrowserType} chromium - Playwright's `chromium`.
+ * @param {string} dir - The unpacked extension.
+ * @param {LaunchOptions} [options] - As `launchExtension`'s.
+ * @returns {Promise<LaunchedExtension & {downloads: string}>} The running extension, and its
+ *   Downloads folder; `close()` deletes both.
+ * @example
+ * const { context, downloads, close } = await launchDownloading(chromium, 'extension');
+ */
+export async function launchDownloading(chromium, dir, options = {}) {
+  const profile = await extensionProfile(chromium, dir, options);
+  const downloads = path.join(path.dirname(profile.dir), 'Downloads');
+  await mkdir(path.join(profile.dir, 'Default'), { recursive: true });
+  await mkdir(downloads, { recursive: true });
+  await writeFile(path.join(profile.dir, 'Default', 'Preferences'), JSON.stringify({
+    download: { default_directory: downloads, prompt_for_download: false, directory_upgrade: true },
+  }));
+  const launched = await profile.launch();
+  const page = await launched.context.newPage();
+  const cdp = await launched.context.newCDPSession(page);
+  await cdp.send('Browser.setDownloadBehavior', { behavior: 'default' });
+  await cdp.detach();
+  await page.close();
+  return {
+    ...launched,
+    downloads,
+    async close() {
+      await launched.close();
+      await profile.remove();
+    },
+  };
+}

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;