@arraypress/extension-kit 1.10.0 → 1.11.0

package/src/testing/index.d.ts

@@ -8,9 +8,9 @@
  */
 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, runChecks, until, } from './e2e.js';
+export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, stopWorker, until, } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
-export { liveUsage, runLiveCheck } from './live-run.js';
+export { REPORT_MARKER, liveUsage, reportFolder, runLiveCheck } from './live-run.js';
 export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
 export { fakeLanguageModel } from './fake-model.js';
@@ -19,7 +19,7 @@ export { heartbeat } from './heartbeat.js';
 export { playPermissionPrompt } from './prompt.js';
 export { callTabModule, nodeAttribute, nodeText, pierceNodes, tabIdOf } from './pages.js';
 export { serve, testCertificate } from './server.js';
-export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { LOCAL_QUOTA_BYTES, SYNC_MAX_ITEMS, SYNC_QUOTA_BYTES, SYNC_WRITES_PER_HOUR, 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';

package/src/testing/index.js

@@ -10,10 +10,10 @@
 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, runChecks, until,
+  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, stopWorker, until,
 } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
-export { liveUsage, runLiveCheck } from './live-run.js';
+export { REPORT_MARKER, liveUsage, reportFolder, runLiveCheck } from './live-run.js';
 export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
 export { fakeLanguageModel } from './fake-model.js';
@@ -22,7 +22,9 @@ export { heartbeat } from './heartbeat.js';
 export { playPermissionPrompt } from './prompt.js';
 export { callTabModule, nodeAttribute, nodeText, pierceNodes, tabIdOf } from './pages.js';
 export { serve, testCertificate } from './server.js';
-export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export {
+  LOCAL_QUOTA_BYTES, SYNC_MAX_ITEMS, SYNC_QUOTA_BYTES, SYNC_WRITES_PER_HOUR, 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';

package/src/testing/live-run.d.ts

@@ -80,10 +80,31 @@ export type LiveRun<S extends LiveSite, R> = {
  * @returns {string} The text.
  */
 export declare const liveUsage: (categories: string[], concurrency: number) => string;
+/** The file that marks a folder as a live report the kit made, so the next run may replace it. */
+export declare const REPORT_MARKER = ".live-report";
+/**
+ * The folder a run's report goes in, made empty. Only a folder the kit made is ever emptied:
+ * the checker's own (`own`), or one carrying {@link REPORT_MARKER} from an earlier run. A new
+ * or empty folder is taken (and marked); a folder with anything else in it is refused, so
+ * `--out .` or `--out ~/Desktop` can't delete what's there.
+ *
+ * @param {string} dir - The folder.
+ * @param {{own?: boolean}} [options] - `own`: the checker's default folder, replaced without asking.
+ * @returns {Promise<string>} `dir`, empty but for the marker.
+ * @throws {Error} When the folder holds files and isn't a report folder.
+ *
+ * @example
+ * await reportFolder('/tmp/report'); // made, or emptied if an earlier run made it
+ */
+export declare function reportFolder(dir: string, { own }?: {
+    own?: boolean;
+}): Promise<string>;
 /**
  * Run a live check: read the command line, visit the chosen sites, give back every visit.
  * Prints the usage and exits for `--help` (or an option it doesn't know), and exits when no
- * site matches.
+ * site matches or `--out` names a folder with other files in it ({@link reportFolder}). A visit
+ * that throws, runs out of time or loses its browser is `failed` with why, and the run goes on
+ * (the slot gets a new browser).
  *
  * @template {LiveSite} S
  * @template R
@@ -96,7 +117,7 @@ export declare const liveUsage: (categories: string[], concurrency: number) => s
  * @param {string[]} run.categories - The categories' ids, for the usage.
  * @param {number} run.pageMs - The most a visit may take.
  * @param {(browser: LaunchedExtension, page: Page, site: S) => Promise<R>} run.visit - Check one site, on a fresh page.
- * @param {(site: S, error: string) => R} run.failed - A visit that couldn't finish (`'timed out'`).
+ * @param {(site: S, error: string) => R} run.failed - A visit that couldn't finish: `'timed out'`, or the error's message.
  * @param {(result: {site: S, visit: R}) => void} [run.onResult] - Each visit as it finishes (a line of output).
  * @param {{argv?: string[], env?: Record<string, string | undefined>, concurrency?: number, findExit?: typeof exitPoint}} [run.command] - The
  *   arguments and environment (default the process's), the most sites at once (default 4), and how the exit point

package/src/testing/live-run.js

@@ -10,9 +10,9 @@
  * @module testing/live-run
  */
 
-import { mkdir, rm } from 'node:fs/promises';
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { within } from '../time/time.js';
+import { deadline, within } from '../time/time.js';
 import { eachLimited } from '../time/pool.js';
 import { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 import { launchExtension } from './e2e.js';
@@ -60,10 +60,43 @@ export const liveUsage = (categories, concurrency) => `Usage: npm run live -- [o
   --out <dir>          write the report there (default test/live/report)
   --help`;
 
+/** The file that marks a folder as a live report the kit made, so the next run may replace it. */
+export const REPORT_MARKER = '.live-report';
+
+/**
+ * The folder a run's report goes in, made empty. Only a folder the kit made is ever emptied:
+ * the checker's own (`own`), or one carrying {@link REPORT_MARKER} from an earlier run. A new
+ * or empty folder is taken (and marked); a folder with anything else in it is refused, so
+ * `--out .` or `--out ~/Desktop` can't delete what's there.
+ *
+ * @param {string} dir - The folder.
+ * @param {{own?: boolean}} [options] - `own`: the checker's default folder, replaced without asking.
+ * @returns {Promise<string>} `dir`, empty but for the marker.
+ * @throws {Error} When the folder holds files and isn't a report folder.
+ *
+ * @example
+ * await reportFolder('/tmp/report'); // made, or emptied if an earlier run made it
+ */
+export async function reportFolder(dir, { own = false } = {}) {
+  const entries = await readdir(dir).catch(() => /** @type {string[]} */ ([]));
+  if (entries.length && !own && !entries.includes(REPORT_MARKER)) {
+    throw new Error(`${dir} has files in it and isn't a report folder: choose a new or empty folder for --out`);
+  }
+  if (entries.length) await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, REPORT_MARKER), 'A live check\'s report: the next run replaces this folder.\n');
+  return dir;
+}
+
+/** Stands for a visit that ran out of time. */
+const LATE = Symbol('late');
+
 /**
  * Run a live check: read the command line, visit the chosen sites, give back every visit.
  * Prints the usage and exits for `--help` (or an option it doesn't know), and exits when no
- * site matches.
+ * site matches or `--out` names a folder with other files in it ({@link reportFolder}). A visit
+ * that throws, runs out of time or loses its browser is `failed` with why, and the run goes on
+ * (the slot gets a new browser).
  *
  * @template {LiveSite} S
  * @template R
@@ -76,7 +109,7 @@ export const liveUsage = (categories, concurrency) => `Usage: npm run live -- [o
  * @param {string[]} run.categories - The categories' ids, for the usage.
  * @param {number} run.pageMs - The most a visit may take.
  * @param {(browser: LaunchedExtension, page: Page, site: S) => Promise<R>} run.visit - Check one site, on a fresh page.
- * @param {(site: S, error: string) => R} run.failed - A visit that couldn't finish (`'timed out'`).
+ * @param {(site: S, error: string) => R} run.failed - A visit that couldn't finish: `'timed out'`, or the error's message.
  * @param {(result: {site: S, visit: R}) => void} [run.onResult] - Each visit as it finishes (a line of output).
  * @param {{argv?: string[], env?: Record<string, string | undefined>, concurrency?: number, findExit?: typeof exitPoint}} [run.command] - The
  *   arguments and environment (default the process's), the most sites at once (default 4), and how the exit point
@@ -109,9 +142,14 @@ export async function runLiveCheck({ chromium, build, prefix, root, sites, categ
     console.error('No pages match.');
     process.exit(2);
   }
-  const dir = options.out ? path.resolve(options.out) : path.join(root, 'test', 'live', 'report');
-  await rm(dir, { recursive: true, force: true });
-  await mkdir(dir, { recursive: true });
+  /** @type {string} */
+  let dir;
+  try {
+    dir = await reportFolder(options.out ? path.resolve(options.out) : path.join(root, 'test', 'live', 'report'), { own: !options.out });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(2);
+  }
 
   const browserOptions = realisticBrowser(options.proxy ? { proxy: options.proxy } : {});
   const plain = await chromium.launch({ channel: 'chromium', ...browserOptions });
@@ -133,19 +171,27 @@ export async function runLiveCheck({ chromium, build, prefix, root, sites, categ
     /** @type {{site: S, visit: R}[]} */
     const results = [];
     await eachLimited(chosen, options.concurrency, async (site, slot, index) => {
-      browsers[slot] ??= await launchExtension(chromium, build, { prefix: `${prefix}${slot}-`, ...launchOptions });
-      const launched = /** @type {LaunchedExtension} */ (browsers[slot]);
-      await within(launched.context.clearCookies(), 10_000, undefined);
-      const page = await launched.context.newPage();
-      const result = await within(visit(launched, page, site), pageMs, undefined);
-      const timedOut = result === undefined;
-      await within(page.close(), 15_000, undefined);
-      if (timedOut) {
-        // A page that ran out of time may have left its browser stuck: the slot gets a new one.
-        await within(launched.close(), 15_000, undefined);
+      /** @type {R} */
+      let outcome;
+      try {
+        browsers[slot] ??= await launchExtension(chromium, build, { prefix: `${prefix}${slot}-`, ...launchOptions });
+        const launched = /** @type {LaunchedExtension} */ (browsers[slot]);
+        await within(launched.context.clearCookies(), 10_000, undefined);
+        const page = await launched.context.newPage();
+        try {
+          const result = await deadline(/** @type {Promise<R | typeof LATE>} */ (visit(launched, page, site)), pageMs, (resolve) => resolve(LATE));
+          if (result === LATE) throw new Error('timed out');
+          outcome = result;
+        } finally {
+          await within(page.close(), 15_000, undefined);
+        }
+      } catch (error) {
+        // A visit that failed may have left its browser stuck, or lost it: the slot gets a new one.
+        await within(Promise.resolve(browsers[slot]?.close()), 15_000, undefined);
         browsers[slot] = null;
+        outcome = failed(site, error instanceof Error ? error.message : String(error));
       }
-      results[index] = { site, visit: timedOut ? failed(site, 'timed out') : /** @type {R} */ (result) };
+      results[index] = { site, visit: outcome };
       onResult(results[index]);
     });
     return {

package/src/testing/messages.d.ts

@@ -21,13 +21,17 @@ export type Messages = Record<string, {
  */
 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).
+ * `chrome.i18n.getMessage` over a locale's real messages, as Chrome reads them (checked against
+ * Chromium): names found whatever their case, named placeholders and `$1`–`$9` filled, `$$` a
+ * dollar sign, '' for a missing key, `undefined` for more than nine substitutions.
  *
  * @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.
+ * @returns {(key: string, substitutions?: string | number | (string | number)[]) => string} The lookup.
+ * @throws {Error} When a message names a placeholder it doesn't define (Chrome refuses to load the extension).
+ *
  * @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;
+export declare function messageLookup(extensionDir: string, locale?: string): (key: string, substitutions?: string | number | (string | number)[]) => string;

package/src/testing/messages.js

@@ -2,7 +2,8 @@
  * Chrome's message lookup for an extension's unit tests: its real `_locales`
  * files, a locale's messages over `en`'s, named placeholders ("$SITE$" →
  * `{site: {content: '$1'}}`) filled from substitutions as
- * `chrome.i18n.getMessage` fills them. Node only. From the copies in Better
+ * `chrome.i18n.getMessage` fills them, and refused as Chrome refuses them (a
+ * placeholder that isn't defined). Node only. From the copies in Better
  * Prices, Better Downloads, Better Saves and Clean Links (`test/helpers/i18n.js`).
  *
  * @module testing/messages
@@ -29,23 +30,63 @@ export function readMessages(extensionDir, locale) {
   return JSON.parse(readFileSync(path.join(extensionDir, '_locales', locale, 'messages.json'), 'utf8'));
 }
 
+/** A named placeholder in a message, as Chrome reads one: `$SITE$` (letters, digits, `_`, `@`). */
+const PLACEHOLDER = /\$([A-Za-z0-9_@]+)\$/g;
+
+/**
+ * A message with its named placeholders put in, as Chrome does when it loads an extension.
+ *
+ * @param {string} key - The message's name, for the error.
+ * @param {Messages[string]} entry - The message.
+ * @returns {string} The message, `$1`-style substitutions still to fill.
+ * @throws {Error} When it names a placeholder it doesn't define: Chrome refuses to load such an extension.
+ */
+function withPlaceholders(key, entry) {
+  const contents = new Map(Object.entries(entry.placeholders ?? {}).map(([name, { content }]) => [name.toLowerCase(), content]));
+  return entry.message.replace(PLACEHOLDER, (_, name) => {
+    const content = contents.get(name.toLowerCase());
+    if (content === undefined) throw new Error(`Message “${key}” uses $${name}$ but has no such placeholder: Chrome wouldn't load the extension`);
+    return content;
+  });
+}
+
 /**
- * `chrome.i18n.getMessage` over a locale's real messages ('' for a missing key, as Chrome gives).
+ * Fill a message's substitutions as Chrome does: `$1`–`$9` from the list ('' past its end), `$$`
+ * a dollar sign; a `$` before anything else is dropped with what follows it.
+ *
+ * @param {string} message - The message, named placeholders already put in.
+ * @param {readonly string[]} subs - The substitutions.
+ * @returns {string} The text.
+ */
+function substituted(message, subs) {
+  return message.replace(/\$(\$+|[\s\S])?/g, (_, next) => {
+    if (next === undefined) return '';
+    if (next.startsWith('$')) return next;
+    return /[1-9]/.test(next) ? String(subs[Number(next) - 1] ?? '') : '';
+  });
+}
+
+/**
+ * `chrome.i18n.getMessage` over a locale's real messages, as Chrome reads them (checked against
+ * Chromium): names found whatever their case, named placeholders and `$1`–`$9` filled, `$$` a
+ * dollar sign, '' for a missing key, `undefined` for more than nine substitutions.
  *
  * @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.
+ * @returns {(key: string, substitutions?: string | number | (string | number)[]) => string} The lookup.
+ * @throws {Error} When a message names a placeholder it doesn't define (Chrome refuses to load the extension).
+ *
  * @example
  * const t = messageLookup('extension');
  * t('optionsMoreActions', ['example.com']); // 'More actions for example.com'
  */
 export function messageLookup(extensionDir, locale = 'en') {
-  const messages = { ...readMessages(extensionDir, 'en'), ...(locale === 'en' ? {} : readMessages(extensionDir, locale)) };
+  const read = { ...readMessages(extensionDir, 'en'), ...(locale === 'en' ? {} : readMessages(extensionDir, locale)) };
+  const messages = new Map(Object.entries(read).map(([key, entry]) => [key.toLowerCase(), withPlaceholders(key, entry)]));
   return (key, substitutions = []) => {
-    const entry = messages[key];
-    if (!entry) return '';
-    const subs = [substitutions].flat();
-    return entry.message.replace(/\$([A-Za-z_]+)\$/g, (_, name) => (entry.placeholders?.[name.toLowerCase()]?.content ?? '')
-      .replace(/\$(\d)/g, (/** @type {string} */ __, /** @type {string} */ n) => subs[Number(n) - 1] ?? ''));
+    const subs = [substitutions].flat().map(String);
+    if (subs.length > 9) return /** @type {string} */ (/** @type {unknown} */ (undefined));
+    const message = messages.get(key.toLowerCase());
+    return message === undefined ? '' : substituted(message, subs);
   };
 }

package/src/testing/package.d.ts

@@ -1,7 +1,7 @@
 /**
  * Helpers for an extension's packaging test: list the folder, list the real
  * zip of it, and find every path the extension names that doesn't resolve to
- * a file inside it (a broken import, a stylesheet link, a manifest entry).
+ * a file the zip holds (a broken import, a stylesheet link, a manifest entry).
  *
  * @module testing/package
  */
@@ -33,6 +33,10 @@ export type ManifestFiles = {
     options_ui?: {
         page?: string;
     };
+    /**
+     * The options page, the older way.
+     */
+    options_page?: string;
     /**
      * The popup and toolbar icon.
      */
@@ -56,6 +60,39 @@ export type ManifestFiles = {
     web_accessible_resources?: {
         resources: string[];
     }[];
+    /**
+     * Scripts and styles Chrome puts in pages.
+     */
+    content_scripts?: {
+        js?: string[];
+        css?: string[];
+    }[];
+    /**
+     * The locale whose `_locales/<locale>/messages.json` must be there.
+     */
+    default_locale?: string;
+    /**
+     * Rule files.
+     */
+    declarative_net_request?: {
+        rule_resources?: {
+            path: string;
+        }[];
+    };
+    /**
+     * Pages that replace Chrome's (the new tab page).
+     */
+    chrome_url_overrides?: Record<string, string>;
+    /**
+     * The DevTools page.
+     */
+    devtools_page?: string;
+    /**
+     * Sandboxed pages.
+     */
+    sandbox?: {
+        pages?: string[];
+    };
 };
 /**
  * The parts of a manifest that name files.
@@ -63,16 +100,25 @@ export type ManifestFiles = {
  * @typedef {object} ManifestFiles
  * @property {{service_worker?: string}} [background] The worker.
  * @property {{page?: string}} [options_ui] The options page.
+ * @property {string} [options_page] The options page, the older way.
  * @property {{default_popup?: string, default_icon?: string | Record<string, string>}} [action] The popup and toolbar icon.
  * @property {{default_path?: string}} [side_panel] The side panel.
  * @property {Record<string, string>} [icons] The extension's icons.
  * @property {{resources: string[]}[]} [web_accessible_resources] Files pages may load.
+ * @property {{js?: string[], css?: string[]}[]} [content_scripts] Scripts and styles Chrome puts in pages.
+ * @property {string} [default_locale] The locale whose `_locales/<locale>/messages.json` must be there.
+ * @property {{rule_resources?: {path: string}[]}} [declarative_net_request] Rule files.
+ * @property {Record<string, string>} [chrome_url_overrides] Pages that replace Chrome's (the new tab page).
+ * @property {string} [devtools_page] The DevTools page.
+ * @property {{pages?: string[]}} [sandbox] Sandboxed pages.
  */
 /**
  * The paths a manifest names, from the extension's root.
  *
  * @param {ManifestFiles} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
+ * @returns {string[]} Worker, pages, icons, side panel, content scripts and their styles, the default
+ *   locale's messages, rule files, overridden and DevTools pages, and web-accessible resources
+ *   (less patterns with `*`).
  */
 export declare function manifestReferences(manifest: ManifestFiles): string[];
 /**
@@ -84,11 +130,14 @@ export declare function manifestReferences(manifest: ManifestFiles): string[];
  */
 export declare function referencedPath(reference: string): string;
 /**
- * Every path the extension names that isn't a file inside it: relative
- * imports in its scripts, `chrome.runtime.getURL('…')` paths, `src`/`href`
- * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
- * or `?query` is ignored: `getURL('options.html#workspaces')` names
- * `options.html`.
+ * Every path the extension names that isn't a file it ships: relative imports in its scripts
+ * (`from`, `import()` and a bare `import './x.js'`), `chrome.runtime.getURL('…')` paths,
+ * `src`/`href` in its pages, `url(…)` and `@import` in its stylesheets, the manifest's entries
+ * ({@link manifestReferences}), and any `extra` paths. A file that's there but left out of the
+ * zip (`shipsFile`: an SVG under `icons/`, a declaration, a vendor stamp) is as missing as one
+ * that isn't: the store build won't have it. A `#fragment` or `?query` is ignored:
+ * `getURL('options.html#workspaces')` names `options.html`. A path starting `/` is from the
+ * extension's root. Files that don't ship aren't read.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).

package/src/testing/package.js

@@ -1,7 +1,7 @@
 /**
  * Helpers for an extension's packaging test: list the folder, list the real
  * zip of it, and find every path the extension names that doesn't resolve to
- * a file inside it (a broken import, a stylesheet link, a manifest entry).
+ * a file the zip holds (a broken import, a stylesheet link, a manifest entry).
  *
  * @module testing/package
  */
@@ -11,7 +11,7 @@ import { existsSync } from 'node:fs';
 import { mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { zipExtension } from '../build/zip.js';
+import { shipsFile, zipExtension } from '../build/zip.js';
 
 /**
  * Every file under `dir`.
@@ -49,27 +49,43 @@ export async function zipEntries(from, exclude) {
  * @typedef {object} ManifestFiles
  * @property {{service_worker?: string}} [background] The worker.
  * @property {{page?: string}} [options_ui] The options page.
+ * @property {string} [options_page] The options page, the older way.
  * @property {{default_popup?: string, default_icon?: string | Record<string, string>}} [action] The popup and toolbar icon.
  * @property {{default_path?: string}} [side_panel] The side panel.
  * @property {Record<string, string>} [icons] The extension's icons.
  * @property {{resources: string[]}[]} [web_accessible_resources] Files pages may load.
+ * @property {{js?: string[], css?: string[]}[]} [content_scripts] Scripts and styles Chrome puts in pages.
+ * @property {string} [default_locale] The locale whose `_locales/<locale>/messages.json` must be there.
+ * @property {{rule_resources?: {path: string}[]}} [declarative_net_request] Rule files.
+ * @property {Record<string, string>} [chrome_url_overrides] Pages that replace Chrome's (the new tab page).
+ * @property {string} [devtools_page] The DevTools page.
+ * @property {{pages?: string[]}} [sandbox] Sandboxed pages.
  */
 
 /**
  * The paths a manifest names, from the extension's root.
  *
  * @param {ManifestFiles} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
+ * @returns {string[]} Worker, pages, icons, side panel, content scripts and their styles, the default
+ *   locale's messages, rule files, overridden and DevTools pages, and web-accessible resources
+ *   (less patterns with `*`).
  */
 export function manifestReferences(manifest) {
   const icon = manifest.action?.default_icon;
   return [
     manifest.background?.service_worker,
     manifest.options_ui?.page,
+    manifest.options_page,
     manifest.action?.default_popup,
     manifest.side_panel?.default_path,
+    manifest.devtools_page,
     ...Object.values(manifest.icons ?? {}),
     ...(typeof icon === 'string' ? [icon] : Object.values(icon ?? {})),
+    ...(manifest.content_scripts ?? []).flatMap((entry) => [...(entry.js ?? []), ...(entry.css ?? [])]),
+    ...(manifest.default_locale ? [`_locales/${manifest.default_locale}/messages.json`] : []),
+    ...(manifest.declarative_net_request?.rule_resources ?? []).map((entry) => entry.path),
+    ...Object.values(manifest.chrome_url_overrides ?? {}),
+    ...(manifest.sandbox?.pages ?? []),
     ...(manifest.web_accessible_resources ?? []).flatMap((entry) => entry.resources),
   ].filter((ref) => typeof ref === 'string').filter((ref) => !ref.includes('*'));
 }
@@ -88,12 +104,27 @@ export function referencedPath(reference) {
 /** A reference with a scheme (`https:`, `data:`, `mailto:`) or protocol-relative: not a file of the extension. */
 const ELSEWHERE = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i;
 
+/** A module a script imports: `… from './x.js'`, `import('./x.js')`, or `import './x.js'` alone on its line; either quote. */
+const IMPORTS = [/(?:from|import\()\s*(['"])(\.{1,2}\/[^'"]+)\1/g, /^\s*import\s*(['"])(\.{1,2}\/[^'"]+)\1/gm];
+
+/** `getURL('…')`, either quote. */
+const GET_URL = /getURL\(\s*(['"])([^'"]+)\1\s*\)/g;
+
+/** A page's `src="…"` or `href="…"`, either quote. */
+const ATTRIBUTES = /\s(?:src|href)\s*=\s*(['"])([^'"]+)\1/g;
+
+/** A stylesheet's `url(…)` and `@import "…"`. */
+const STYLE_URLS = [/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, /@import\s+(['"])([^'"]+)\1/g];
+
 /**
- * Every path the extension names that isn't a file inside it: relative
- * imports in its scripts, `chrome.runtime.getURL('…')` paths, `src`/`href`
- * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
- * or `?query` is ignored: `getURL('options.html#workspaces')` names
- * `options.html`.
+ * Every path the extension names that isn't a file it ships: relative imports in its scripts
+ * (`from`, `import()` and a bare `import './x.js'`), `chrome.runtime.getURL('…')` paths,
+ * `src`/`href` in its pages, `url(…)` and `@import` in its stylesheets, the manifest's entries
+ * ({@link manifestReferences}), and any `extra` paths. A file that's there but left out of the
+ * zip (`shipsFile`: an SVG under `icons/`, a declaration, a vendor stamp) is as missing as one
+ * that isn't: the store build won't have it. A `#fragment` or `?query` is ignored:
+ * `getURL('options.html#workspaces')` names `options.html`. A path starting `/` is from the
+ * extension's root. Files that don't ship aren't read.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).
@@ -107,18 +138,26 @@ export async function missingReferences(dir, extra = []) {
   const check = (from, target) => {
     const name = referencedPath(target);
     if (!name || ELSEWHERE.test(target)) return;
-    const file = path.resolve(root, from, name);
-    if (!file.startsWith(root) || !existsSync(file)) missing.push(`${from || 'root'} → ${target}`);
+    const file = name.startsWith('/') ? path.join(root, name) : path.resolve(root, from, name);
+    const inside = path.relative(root, file).split(path.sep).join('/');
+    if (inside.startsWith('..') || !existsSync(file) || !shipsFile(inside)) missing.push(`${from || 'root'} → ${target}`);
+  };
+  /** @param {string} source @param {readonly RegExp[]} patterns @param {string} from */
+  const each = (source, patterns, from) => {
+    for (const pattern of patterns) for (const match of source.matchAll(pattern)) check(from, match[2]);
   };
-  for (const file of await filesUnder(root)) {
+  for (const file of (await filesUnder(root)).filter(shipsFile)) {
     const from = path.posix.dirname(file);
-    if (file.endsWith('.js')) {
-      const source = await readFile(path.join(root, file), 'utf8');
-      for (const [, spec] of source.matchAll(/(?:from|import\()\s*'(\.{1,2}\/[^']+)'/g)) check(from, spec);
-      for (const [, ref] of source.matchAll(/getURL\('([^']+)'\)/g)) check('', ref);
-    } else if (file.endsWith('.html')) {
-      const source = await readFile(path.join(root, file), 'utf8');
-      for (const [, ref] of source.matchAll(/(?:src|href)="([^"]+)"/g)) check(from, ref);
+    const kind = path.posix.extname(file);
+    if (kind !== '.js' && kind !== '.html' && kind !== '.css') continue;
+    const source = await readFile(path.join(root, file), 'utf8');
+    if (kind === '.js') {
+      each(source, IMPORTS, from);
+      each(source, [GET_URL], '');
+    } else if (kind === '.html') {
+      each(source, [ATTRIBUTES], from);
+    } else {
+      each(source, STYLE_URLS, from);
     }
   }
   const manifest = JSON.parse(await readFile(path.join(root, 'manifest.json'), 'utf8'));

package/src/testing/prompt.d.ts

@@ -8,8 +8,10 @@
  * Stand in for Chrome's permission prompt in a page: each `chrome.permissions.request` is
  * recorded on `window.asked` (what was asked, and whether a click was behind it,
  * `navigator.userActivation.isActive`) and answered from `answers` (the next one; the last is
- * kept), as a person clicking “Allow” or “Deny” would. Runs in the page: give it to
- * `page.evaluate` or `page.addInitScript`, so it takes no closures.
+ * kept), as a person clicking “Allow” or “Deny” would. A request with no click behind it is
+ * refused as Chrome refuses it (“This function must be called during a user gesture”) and takes
+ * no answer. Runs in the page: give it to `page.evaluate` or `page.addInitScript`, so it takes
+ * no closures.
  *
  * @param {boolean[]} answers - The answers, in order.
  * @example

package/src/testing/prompt.js

@@ -9,8 +9,10 @@
  * Stand in for Chrome's permission prompt in a page: each `chrome.permissions.request` is
  * recorded on `window.asked` (what was asked, and whether a click was behind it,
  * `navigator.userActivation.isActive`) and answered from `answers` (the next one; the last is
- * kept), as a person clicking “Allow” or “Deny” would. Runs in the page: give it to
- * `page.evaluate` or `page.addInitScript`, so it takes no closures.
+ * kept), as a person clicking “Allow” or “Deny” would. A request with no click behind it is
+ * refused as Chrome refuses it (“This function must be called during a user gesture”) and takes
+ * no answer. Runs in the page: give it to `page.evaluate` or `page.addInitScript`, so it takes
+ * no closures.
  *
  * @param {boolean[]} answers - The answers, in order.
  * @example
@@ -23,7 +25,9 @@ export function playPermissionPrompt(answers) {
   const asked = [];
   Object.assign(window, { asked });
   chrome.permissions.request = /** @type {typeof chrome.permissions.request} */ (/** @type {unknown} */ (async (/** @type {chrome.permissions.Permissions} */ permissions) => {
-    asked.push({ permissions: permissions.permissions, origins: permissions.origins, gesture: navigator.userActivation.isActive });
+    const gesture = navigator.userActivation.isActive;
+    asked.push({ permissions: permissions.permissions, origins: permissions.origins, gesture });
+    if (!gesture) throw new Error('This function must be called during a user gesture');
     return answers.length > 1 ? answers.shift() : answers[0];
   }));
 }

package/src/time/pool.d.ts

@@ -13,7 +13,8 @@
  *
  * @template T
  * @param {readonly T[]} items - The items.
- * @param {number} limit - At most this many at once.
+ * @param {number} limit - At most this many at once (at least one: a limit of 0 or less, or one
+ *   that isn't a number, runs them one at a time rather than not at all).
  * @param {(item: T, slot: number, index: number) => Promise<void>} work - Deals with one item;
  *   `slot` (0 to limit − 1) is the same for everything one slot does, for per-slot resources
  *   (a browser each).

package/src/time/pool.js

@@ -14,7 +14,8 @@
  *
  * @template T
  * @param {readonly T[]} items - The items.
- * @param {number} limit - At most this many at once.
+ * @param {number} limit - At most this many at once (at least one: a limit of 0 or less, or one
+ *   that isn't a number, runs them one at a time rather than not at all).
  * @param {(item: T, slot: number, index: number) => Promise<void>} work - Deals with one item;
  *   `slot` (0 to limit − 1) is the same for everything one slot does, for per-slot resources
  *   (a browser each).
@@ -24,7 +25,8 @@
  */
 export async function eachLimited(items, limit, work) {
   let next = 0;
-  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async (_, slot) => {
+  const slots = Math.max(1, Math.floor(limit) || 1);
+  await Promise.all(Array.from({ length: Math.min(slots, items.length) }, async (_, slot) => {
     while (next < items.length) {
       const index = next;
       next += 1;