@arraypress/extension-kit 1.5.0 → 1.6.0

package/README.md

@@ -193,6 +193,24 @@ withSite(['a.com', 'b.com'], 'a.com');       // ['b.com', 'a.com'], what a list
 A site is http or https with a dot in its host (or `localhost`); text without a scheme is https;
 `localhost:8080` is a host and port. Pure, so a content script can load `sites/sites.js` alone.
 
+## A content script on every site
+
+```js
+// The content script runs everywhere only while the optional all-sites grant is held, less the
+// "Never on" sites; one call brings the registration in line, whatever changed.
+const sync = contentScriptSync(chrome.scripting, 'prices', async () => {
+  const settings = await store.load(chrome.storage);
+  if (!settings.everySite || !(await chrome.permissions.contains({ origins: ALL_SITES }))) return null;
+  return { js: ['content/loader.js'], matches: ALL_SITES, excludeMatches: settings.neverSites.flatMap(hostPatterns), runAt: 'document_idle' };
+});
+chrome.permissions.onAdded.addListener(() => sync());
+chrome.permissions.onRemoved.addListener(() => sync()); // site access taken back on chrome://extensions
+```
+
+Registers, updates or unregisters the script `id` to match what `want()` gives at the time (null:
+none). Calls run one after another, so a quick run of changes can't register twice or end out of
+order; a refused change rejects that call only.
+
 ## Time limits
 
 ```js
@@ -203,6 +221,13 @@ const groups = await within(chrome.tabGroups.query({}), 2000, []); // a Chrome c
 rejects; its timer cleared once the work settles (the work itself isn't stopped). In the runtime
 half, so a service worker or page can use it; the test helpers use it too.
 
+```js
+await eachLimited(files, 4, async (file) => save(file)); // at most four at once
+```
+
+`eachLimited(items, limit, work)`: `work(item, slot, index)` on every item, at most `limit` at once;
+in the runtime half too (`/testing` exports it as well).
+
 ## Page components
 
 Chrome's own components, made in the page by script (no markup to copy), styled by `chrome-ui.css`.
@@ -366,19 +391,22 @@ except those listed, each with a reason:
 |---|---|
 | `fakeChromeStorage({local, sync, session, now})` | In-memory `chrome.storage`: JSON copies, `onChanged` for real changes only, sync's 8,192-byte item quota and 120 writes a minute. `settled()` waits for listeners. |
 | `launchExtension(chromium, dir, options)` | Load an unpacked extension into a fresh profile; `{context, worker, extensionId, url(page), profile, close()}`. |
+| `launchDownloading(chromium, dir, options)`, `filesIn(dir)` | An extension in a browser that downloads for real: `{…launchExtension's, downloads}`, the profile's own Downloads folder (Playwright otherwise saves downloads under made-up names no extension sees); the files under a folder, downloads still running left out. |
 | `extensionProfile(chromium, dir, options)` | A profile to start the browser on more than once (a restart, a first start with a changed manifest): `{dir, launch(), remove()}`. |
 | `checkRunner({timeout})` | Named checks that report and go on: `check(name, fn, {timeout})`, `fail(name)` for an error found outside a check, `finish()`. A check that runs past its limit (`CHECK_MS`, 60 s) fails, and the run goes on. |
-| `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)`. |
+| `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)` (also in the main entry). |
 | `realisticBrowser(options)`, `chromeUserAgent(browser)` | Launch options and a user agent for a browser that doesn't say it's automated, for live checks. |
 | `closeOnSignal(close)` | On Ctrl-C or a kill, close the run's browsers, then exit. |
 | `testBuildDir(root, name)` | As in `/build`, for the tests that load the build. |
-| `serve(routes, {port})` | Serve test pages on 127.0.0.1 from a table, a `Map` or a function of the path; `{origin, port, server, close()}`. |
+| `serve(routes, {port, tls})` | Serve test pages on 127.0.0.1 from a table, a `Map` or a function of the path; `{origin, port, server, close()}`. With `tls` (`testCertificate()`, a throwaway one from `openssl`), over HTTPS: for a site Chrome reaches only over HTTPS, mapped with `--host-resolver-rules`, Chromium started with `--ignore-certificate-errors`. |
 | `until(fn, what, timeout?)` | Poll until truthy. |
 | `offscreenEmulator(cdp)` | Emulate light/dark inside the offscreen document. |
 | `recordIconCalls(worker)` | Record `chrome.action.setIcon` calls Chrome accepted. |
 | `installWarnings(worker, manifest)` | Chrome's own install warnings for a manifest (`chrome.management.getPermissionWarningsByManifest`, no permission needed), from a loaded extension's worker. |
 | `warningsAddedBy(worker, manifest, names)` | `{warnings, without, added}`: the warnings with and without some permissions, and those only they bring (`withoutPermissions` is the pure part). |
 | `savedTabGroups(profile)` | Chrome's saved tab groups (`{title, pinned, urls}`) read from a closed profile's `Sync Data/LevelDB`: no extension API lists them. |
+| `parseLiveOptions(argv, env, {usage})`, `parseProxy(address)` | A live checker's command line (`--only`, `--category`, `--concurrency`, `--proxy` or `HTTPS_PROXY`, `--locale`, `--timezone`, `--out`, `--help`), and a proxy address for Playwright with its password hidden for the output. |
+| `exitPoint(request)` | Where the run's traffic leaves for the internet (`{ip, country, where, source}`), from a keyless lookup service through the context's proxy: sites decide what to show by it. |
 | `filesUnder`, `zipEntries`, `missingReferences`, `manifestReferences` | For a packaging test: the zip is the folder, and every path the extension names resolves (a `#fragment` or `?query` ignored: `referencedPath`). |
 
 ## Stylesheet classes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Shared pieces for Chrome extensions: Chrome's own page styles, a Chrome Sync settings store, the light/dark toolbar glyph, About links, and build and test helpers.",
   "type": "module",
   "main": "src/index.js",

package/src/build/vendor.js

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

package/src/index.d.ts

@@ -17,10 +17,12 @@ 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';
@@ -29,6 +31,7 @@ export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from
 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 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 +44,7 @@ export type Toast = import('./ui/toast.js').Toast;
 /**
  * The page helpers' types, for a page's JSDoc.
  *
+ * @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

@@ -18,12 +18,14 @@ 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';
@@ -38,6 +40,7 @@ export { TOAST_MS, createToast } from './ui/toast.js';
 /**
  * The page helpers' types, for a page's JSDoc.
  *
+ * @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/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/index.d.ts

@@ -9,8 +9,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, until, } from './e2e.js';
-export { eachLimited } from './pool.js';
-export { serve } from './server.js';
+export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { eachLimited } from '../time/pool.js';
+export { filesIn, launchDownloading } from './downloads.js';
+export { serve, testCertificate } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
@@ -19,6 +21,8 @@ export type CheckRunner = import('./e2e.js').CheckRunner;
 export type ExtensionProfile = import('./e2e.js').ExtensionProfile;
 export type LaunchedExtension = import('./e2e.js').LaunchedExtension;
 export type LaunchOptions = import('./e2e.js').LaunchOptions;
+export type Exit = import('./live.js').Exit;
+export type LiveOptions = import('./live.js').LiveOptions;
 export type SavedTabGroup = import('./saved-groups.js').SavedTabGroup;
 export type Manifest = import('./warnings.js').Manifest;
 export type Reply = import('./server.js').Reply;
@@ -31,6 +35,8 @@ export type TestServer = import('./server.js').TestServer;
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./live.js').Exit} Exit
+ * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/index.js

@@ -12,8 +12,10 @@ export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 export {
   CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until,
 } from './e2e.js';
-export { eachLimited } from './pool.js';
-export { serve } from './server.js';
+export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { eachLimited } from '../time/pool.js';
+export { filesIn, launchDownloading } from './downloads.js';
+export { serve, testCertificate } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
@@ -26,6 +28,8 @@ export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./live.js').Exit} Exit
+ * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/live.d.ts

@@ -0,0 +1,146 @@
+/**
+ * What a live checker (a run over real sites, never in CI) shares: its
+ * command line (which sites, how many at once, a proxy, how the browser
+ * looks) and where its traffic leaves for the internet, which decides what
+ * many sites show (cookie banners, prices, currency).
+ *
+ * @module testing/live
+ */
+import type { APIRequestContext } from 'playwright';
+export type Proxy = {
+    /**
+     * e.g. "http://uk.example.net:8080" or "socks5://127.0.0.1:1080".
+     */
+    server: string;
+    /**
+     * From the address, if it has one.
+     */
+    username?: string;
+    /**
+     * From the address, if it has one.
+     */
+    password?: string;
+};
+export type LiveOptions = {
+    /**
+     * Only sites whose address or name contains one of these (any case).
+     */
+    only: string[];
+    /**
+     * Only these categories (by id).
+     */
+    categories: string[];
+    /**
+     * Sites checked at once.
+     */
+    concurrency: number;
+    /**
+     * The proxy every request goes through.
+     */
+    proxy: Proxy | null;
+    /**
+     * The proxy's address without its password, for the output.
+     */
+    proxyLabel: string;
+    /**
+     * The browser's language (navigator.language, Accept-Language).
+     */
+    locale: string;
+    /**
+     * The browser's time zone.
+     */
+    timezone: string;
+    /**
+     * Where the report goes ('' for the checker's default).
+     */
+    out: string;
+    /**
+     * Show the usage and stop.
+     */
+    help: boolean;
+};
+/** @import { APIRequestContext } from 'playwright' */
+/**
+ * A proxy, as Playwright takes it.
+ *
+ * @typedef {object} Proxy
+ * @property {string} server e.g. "http://uk.example.net:8080" or "socks5://127.0.0.1:1080".
+ * @property {string} [username] From the address, if it has one.
+ * @property {string} [password] From the address, if it has one.
+ */
+/**
+ * A live checker's options.
+ *
+ * @typedef {object} LiveOptions
+ * @property {string[]} only Only sites whose address or name contains one of these (any case).
+ * @property {string[]} categories Only these categories (by id).
+ * @property {number} concurrency Sites checked at once.
+ * @property {Proxy | null} proxy The proxy every request goes through.
+ * @property {string} proxyLabel The proxy's address without its password, for the output.
+ * @property {string} locale The browser's language (navigator.language, Accept-Language).
+ * @property {string} timezone The browser's time zone.
+ * @property {string} out Where the report goes ('' for the checker's default).
+ * @property {boolean} help Show the usage and stop.
+ */
+/**
+ * Read a proxy address.
+ *
+ * @param {string} address - e.g. "http://user:pass@host:3128".
+ * @returns {{ proxy: Proxy, label: string }} For Playwright, and for the output (no password).
+ * @throws {Error} When it isn't an address.
+ * @example
+ * parseProxy('http://me:secret@uk.example:8080').label; // 'http://me:•••@uk.example:8080'
+ */
+export declare function parseProxy(address: string): {
+    proxy: Proxy;
+    label: string;
+};
+/**
+ * Read a live checker's command line: `--only <word>` (repeatable, or bare
+ * words), `--category <id>` (repeatable), `--concurrency <n>`, `--proxy <url>`
+ * (default `HTTPS_PROXY`), `--locale <tag>`, `--timezone <zone>`, `--out <dir>`,
+ * `--help`. A value may follow an `=` ("--only=amazon"); commas list several.
+ *
+ * @param {readonly string[]} argv - The arguments after the script.
+ * @param {Readonly<Record<string, string | undefined>>} env - The environment (HTTPS_PROXY, https_proxy).
+ * @param {{ usage: string, concurrency?: number, maxConcurrency?: number, locale?: string, timezone?: string }} defaults - The
+ *   usage text (shown with an unknown option), and the defaults: 3 at once (at most 8), en-GB, Europe/London.
+ * @returns {LiveOptions} The options.
+ * @throws {Error} On an unknown option or a bad value.
+ * @example
+ * parseLiveOptions(['--category', 'shops', 'amazon'], {}, { usage }).only; // ['amazon']
+ */
+export declare function parseLiveOptions(argv: readonly string[], env: Readonly<Record<string, string | undefined>>, { usage, concurrency, maxConcurrency, locale, timezone }: {
+    usage: string;
+    concurrency?: number;
+    maxConcurrency?: number;
+    locale?: string;
+    timezone?: string;
+}): LiveOptions;
+export type Exit = {
+    /**
+     * The public address.
+     */
+    ip: string;
+    /**
+     * Its ISO country code ("GB", "TH").
+     */
+    country: string;
+    /**
+     * Readable: city and organisation, where the service says.
+     */
+    where: string;
+    /**
+     * The service that answered.
+     */
+    source: string;
+};
+/**
+ * Where the browser's traffic leaves for the internet: its public IP's
+ * country, asked once through the same proxy the browser uses. Sites go by
+ * that address, not the browser's language or time zone.
+ *
+ * @param {APIRequestContext} request - A browser context's `request` (it uses the context's proxy).
+ * @returns {Promise<Exit | null>} null when no service answered.
+ */
+export declare function exitPoint(request: APIRequestContext): Promise<Exit | null>;

package/src/testing/live.js

@@ -0,0 +1,151 @@
+/**
+ * What a live checker (a run over real sites, never in CI) shares: its
+ * command line (which sites, how many at once, a proxy, how the browser
+ * looks) and where its traffic leaves for the internet, which decides what
+ * many sites show (cookie banners, prices, currency).
+ *
+ * @module testing/live
+ */
+
+/** @import { APIRequestContext } from 'playwright' */
+
+/**
+ * A proxy, as Playwright takes it.
+ *
+ * @typedef {object} Proxy
+ * @property {string} server e.g. "http://uk.example.net:8080" or "socks5://127.0.0.1:1080".
+ * @property {string} [username] From the address, if it has one.
+ * @property {string} [password] From the address, if it has one.
+ */
+
+/**
+ * A live checker's options.
+ *
+ * @typedef {object} LiveOptions
+ * @property {string[]} only Only sites whose address or name contains one of these (any case).
+ * @property {string[]} categories Only these categories (by id).
+ * @property {number} concurrency Sites checked at once.
+ * @property {Proxy | null} proxy The proxy every request goes through.
+ * @property {string} proxyLabel The proxy's address without its password, for the output.
+ * @property {string} locale The browser's language (navigator.language, Accept-Language).
+ * @property {string} timezone The browser's time zone.
+ * @property {string} out Where the report goes ('' for the checker's default).
+ * @property {boolean} help Show the usage and stop.
+ */
+
+/**
+ * Read a proxy address.
+ *
+ * @param {string} address - e.g. "http://user:pass@host:3128".
+ * @returns {{ proxy: Proxy, label: string }} For Playwright, and for the output (no password).
+ * @throws {Error} When it isn't an address.
+ * @example
+ * parseProxy('http://me:secret@uk.example:8080').label; // 'http://me:•••@uk.example:8080'
+ */
+export function parseProxy(address) {
+  const url = new URL(address.includes('://') ? address : `http://${address}`);
+  if (!url.hostname) throw new Error(`Not a proxy address: ${address}`);
+  const server = `${url.protocol}//${url.host}`;
+  const username = decodeURIComponent(url.username);
+  const password = decodeURIComponent(url.password);
+  return {
+    proxy: { server, ...(username && { username }), ...(password && { password }) },
+    label: `${url.protocol}//${username ? `${username}${password ? ':•••' : ''}@` : ''}${url.host}`,
+  };
+}
+
+/**
+ * Read a live checker's command line: `--only <word>` (repeatable, or bare
+ * words), `--category <id>` (repeatable), `--concurrency <n>`, `--proxy <url>`
+ * (default `HTTPS_PROXY`), `--locale <tag>`, `--timezone <zone>`, `--out <dir>`,
+ * `--help`. A value may follow an `=` ("--only=amazon"); commas list several.
+ *
+ * @param {readonly string[]} argv - The arguments after the script.
+ * @param {Readonly<Record<string, string | undefined>>} env - The environment (HTTPS_PROXY, https_proxy).
+ * @param {{ usage: string, concurrency?: number, maxConcurrency?: number, locale?: string, timezone?: string }} defaults - The
+ *   usage text (shown with an unknown option), and the defaults: 3 at once (at most 8), en-GB, Europe/London.
+ * @returns {LiveOptions} The options.
+ * @throws {Error} On an unknown option or a bad value.
+ * @example
+ * parseLiveOptions(['--category', 'shops', 'amazon'], {}, { usage }).only; // ['amazon']
+ */
+export function parseLiveOptions(argv, env, { usage, concurrency = 3, maxConcurrency = 8, locale = 'en-GB', timezone = 'Europe/London' }) {
+  /** @type {LiveOptions} */
+  const options = { only: [], categories: [], concurrency, proxy: null, proxyLabel: '', locale, timezone, out: '', help: false };
+  let proxy = env.HTTPS_PROXY || env.https_proxy || '';
+  for (let at = 0; at < argv.length; at += 1) {
+    const arg = argv[at];
+    const equals = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const flag = equals > 0 ? arg.slice(0, equals) : arg;
+    const inline = equals > 0 ? arg.slice(equals + 1) : undefined;
+    const value = () => {
+      const next = inline ?? argv[++at];
+      if (next === undefined || next === '') throw new Error(`${flag} needs a value`);
+      return next;
+    };
+    switch (flag) {
+      case '--only': options.only.push(...value().split(',')); break;
+      case '--category': options.categories.push(...value().split(',')); break;
+      case '--concurrency': {
+        const count = Number(value());
+        if (!Number.isInteger(count) || count < 1 || count > maxConcurrency) throw new Error(`--concurrency must be 1 to ${maxConcurrency}`);
+        options.concurrency = count;
+        break;
+      }
+      case '--proxy': proxy = value(); break;
+      case '--locale': options.locale = value(); break;
+      case '--timezone': options.timezone = value(); break;
+      case '--out': options.out = value(); break;
+      case '--help': case '-h': options.help = true; break;
+      default:
+        if (flag.startsWith('-')) throw new Error(`Unknown option ${flag}\n\n${usage}`);
+        options.only.push(flag);
+    }
+  }
+  if (proxy) ({ proxy: options.proxy, label: options.proxyLabel } = parseProxy(proxy));
+  return options;
+}
+
+/**
+ * The exit point.
+ *
+ * @typedef {object} Exit
+ * @property {string} ip The public address.
+ * @property {string} country Its ISO country code ("GB", "TH").
+ * @property {string} where Readable: city and organisation, where the service says.
+ * @property {string} source The service that answered.
+ */
+
+/**
+ * Lookup services that need no key, tried in order, each with how to read its answer.
+ *
+ * @type {readonly { url: string, read: (data: Record<string, unknown>) => { ip: unknown, country: unknown, where: unknown[] } }[]}
+ */
+const SERVICES = [
+  { url: 'https://ipinfo.io/json', read: (data) => ({ ip: data.ip, country: data.country, where: [data.city, data.org] }) },
+  { url: 'https://api.country.is/', read: (data) => ({ ip: data.ip, country: data.country, where: [] }) },
+  { url: 'https://ipapi.co/json/', read: (data) => ({ ip: data.ip, country: data.country_code, where: [data.city, data.org] }) },
+];
+
+/**
+ * Where the browser's traffic leaves for the internet: its public IP's
+ * country, asked once through the same proxy the browser uses. Sites go by
+ * that address, not the browser's language or time zone.
+ *
+ * @param {APIRequestContext} request - A browser context's `request` (it uses the context's proxy).
+ * @returns {Promise<Exit | null>} null when no service answered.
+ */
+export async function exitPoint(request) {
+  for (const { url, read } of SERVICES) {
+    try {
+      const response = await request.get(url, { timeout: 10000, headers: { accept: 'application/json' } });
+      if (!response.ok()) continue;
+      const { ip, country, where } = read(await response.json());
+      if (typeof country !== 'string' || !country) continue;
+      return { ip: String(ip ?? ''), country: country.toUpperCase(), where: where.filter((part) => typeof part === 'string' && part).join(', '), source: new URL(url).host };
+    } catch {
+      // The next service.
+    }
+  }
+  return null;
+}

package/src/testing/server.d.ts

@@ -1,7 +1,8 @@
 /**
  * A local web server for end-to-end test pages: a site for the content
  * script to run on, answering each path from a table (or a function), on
- * 127.0.0.1 so a test build's host permission can cover it.
+ * 127.0.0.1 so a test build's host permission can cover it; over HTTPS too,
+ * with a throwaway certificate.
  *
  * @module testing/server
  */
@@ -31,17 +32,36 @@ export type TestServer = {
      */
     close: () => Promise<void>;
 };
+/**
+ * A self-signed certificate for 127.0.0.1 and localhost, made by `openssl`, valid for a day: for
+ * {@link serve}'s `tls`, with Chromium started with `--ignore-certificate-errors` (a site whose
+ * name Chrome only reaches over HTTPS, as every HSTS-preloaded one, mapped to the test server with
+ * `--host-resolver-rules`).
+ *
+ * @returns {{key: string, cert: string}} The key and certificate, PEM.
+ * @example
+ * const site = await serve(routes, { tls: testCertificate() });
+ */
+export declare function testCertificate(): {
+    key: string;
+    cert: string;
+};
 /**
  * Serve `routes` on 127.0.0.1.
  *
  * @param {Routes} routes - Path → page, or a function of the path.
- * @param {{port?: number}} [options] - `port`: a fixed port (default: any free one).
+ * @param {{port?: number, tls?: {key: string, cert: string}}} [options] - `port`: a fixed port (default: any
+ *   free one); `tls`: serve HTTPS with this key and certificate ({@link testCertificate}).
  * @returns {Promise<TestServer>} The listening server.
  * @example
  * const site = await serve({'/': '<!doctype html><textarea></textarea>'});
  * await page.goto(`${site.origin}/`);
  * await site.close();
  */
-export declare function serve(routes: Routes, { port }?: {
+export declare function serve(routes: Routes, { port, tls }?: {
     port?: number;
+    tls?: {
+        key: string;
+        cert: string;
+    };
 }): Promise<TestServer>;

package/src/testing/server.js

@@ -1,12 +1,18 @@
 /**
  * A local web server for end-to-end test pages: a site for the content
  * script to run on, answering each path from a table (or a function), on
- * 127.0.0.1 so a test build's host permission can cover it.
+ * 127.0.0.1 so a test build's host permission can cover it; over HTTPS too,
+ * with a throwaway certificate.
  *
  * @module testing/server
  */
 
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { createServer } from 'node:http';
+import { createServer as createSecureServer } from 'node:https';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 
 /** @import { IncomingMessage, Server } from 'node:http' */
 
@@ -52,19 +58,42 @@ async function replyFor(routes, pathname, request) {
   return Object.hasOwn(table, pathname) ? table[pathname] : undefined;
 }
 
+/**
+ * A self-signed certificate for 127.0.0.1 and localhost, made by `openssl`, valid for a day: for
+ * {@link serve}'s `tls`, with Chromium started with `--ignore-certificate-errors` (a site whose
+ * name Chrome only reaches over HTTPS, as every HSTS-preloaded one, mapped to the test server with
+ * `--host-resolver-rules`).
+ *
+ * @returns {{key: string, cert: string}} The key and certificate, PEM.
+ * @example
+ * const site = await serve(routes, { tls: testCertificate() });
+ */
+export function testCertificate() {
+  const dir = mkdtempSync(path.join(tmpdir(), 'kit-tls-'));
+  try {
+    execFileSync('openssl', ['req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-days', '1', '-subj', '/CN=localhost',
+      '-keyout', path.join(dir, 'key.pem'), '-out', path.join(dir, 'cert.pem')], { stdio: 'ignore' });
+    return { key: readFileSync(path.join(dir, 'key.pem'), 'utf8'), cert: readFileSync(path.join(dir, 'cert.pem'), 'utf8') };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 /**
  * Serve `routes` on 127.0.0.1.
  *
  * @param {Routes} routes - Path → page, or a function of the path.
- * @param {{port?: number}} [options] - `port`: a fixed port (default: any free one).
+ * @param {{port?: number, tls?: {key: string, cert: string}}} [options] - `port`: a fixed port (default: any
+ *   free one); `tls`: serve HTTPS with this key and certificate ({@link testCertificate}).
  * @returns {Promise<TestServer>} The listening server.
  * @example
  * const site = await serve({'/': '<!doctype html><textarea></textarea>'});
  * await page.goto(`${site.origin}/`);
  * await site.close();
  */
-export async function serve(routes, { port = 0 } = {}) {
-  const server = createServer(async (request, response) => {
+export async function serve(routes, { port = 0, tls } = {}) {
+  /** @type {import('node:http').RequestListener} */
+  const handle = async (request, response) => {
     const { pathname } = new URL(request.url ?? '/', 'http://127.0.0.1');
     const reply = await replyFor(routes, pathname, request);
     if (reply === undefined) {
@@ -75,13 +104,14 @@ export async function serve(routes, { port = 0 } = {}) {
     const { body, type = HTML, status = 200, headers = {} } = typeof reply === 'string' || reply instanceof Uint8Array ? { body: reply } : reply;
     response.writeHead(status, { 'Content-Type': type, ...headers });
     response.end(body);
-  });
+  };
+  const server = tls ? createSecureServer(tls, handle) : createServer(handle);
   await new Promise((resolve) => server.listen(port, '127.0.0.1', () => resolve(undefined)));
   const address = /** @type {import('node:net').AddressInfo} */ (server.address());
   return {
     server,
     port: address.port,
-    origin: `http://127.0.0.1:${address.port}`,
+    origin: `${tls ? 'https' : 'http'}://127.0.0.1:${address.port}`,
     close() {
       server.closeAllConnections();
       return new Promise((resolve) => server.close(() => resolve()));

package/src/{testing → time}/pool.d.ts

@@ -1,8 +1,9 @@
 /**
- * Working through a list a few at a time: a live check of many sites, each
- * in one of a few browsers.
+ * Working through a list a few at a time: files fetched by an extension page,
+ * or a live check of many sites, each in one of a few browsers. Runs
+ * anywhere (worker, page, Node).
  *
- * @module testing/pool
+ * @module time/pool
  */
 /**
  * Run `work` on every item, at most `limit` at once, each slot taking the

package/src/{testing → time}/pool.js

@@ -1,8 +1,9 @@
 /**
- * Working through a list a few at a time: a live check of many sites, each
- * in one of a few browsers.
+ * Working through a list a few at a time: files fetched by an extension page,
+ * or a live check of many sites, each in one of a few browsers. Runs
+ * anywhere (worker, page, Node).
  *
- * @module testing/pool
+ * @module time/pool
  */
 
 /**