@arraypress/extension-kit 0.0.0-stage → 1.1.0

package/src/testing/fake-storage.js

@@ -0,0 +1,145 @@
+/**
+ * An in-memory `chrome.storage` for tests, behaving as Chrome does: values
+ * are stored as JSON, `onChanged` fires only for values that changed, and
+ * sync refuses an item over its 8,192-byte quota and more than 120 writes
+ * (set or remove) a minute. Tests then check outcomes (what's stored), not
+ * calls.
+ *
+ * @module testing/fake-storage
+ */
+
+import { MAX_SYNC_ITEM_BYTES } from '../settings/storage.js';
+
+/** @import { StorageChange } from '../settings/storage.js' */
+
+/** Chrome Sync's write limit: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_MINUTE`. */
+export const SYNC_WRITES_PER_MINUTE = 120;
+
+/**
+ * @typedef {(changes: Record<string, StorageChange>, area: string) => unknown} ChangeListener
+ */
+
+/**
+ * One fake storage area.
+ *
+ * @typedef {object} FakeArea
+ * @property {Record<string, any>} data What it holds, to inspect (and seed) in tests.
+ * @property {number} writes How many writes it has taken.
+ * @property {(keys?: string | string[] | null) => Promise<Record<string, any>>} get
+ * @property {(items: Record<string, unknown>) => Promise<void>} set
+ * @property {(keys: string | string[]) => Promise<void>} remove
+ */
+
+/**
+ * The fake `chrome.storage`.
+ *
+ * @typedef {object} FakeChromeStorage
+ * @property {FakeArea} local `chrome.storage.local`.
+ * @property {FakeArea} sync `chrome.storage.sync`, with Chrome's quotas.
+ * @property {FakeArea} session `chrome.storage.session`.
+ * @property {{addListener(listener: ChangeListener): void}} onChanged `chrome.storage.onChanged`.
+ * @property {() => Promise<void>} settled Waits for every listener, including the changes those listeners make.
+ */
+
+/**
+ * Copy a value the way storage does, through JSON.
+ *
+ * @param {unknown} value - Anything JSON-able, or undefined.
+ * @returns {any} The copy.
+ */
+const viaJson = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
+
+/**
+ * Make a fake `chrome.storage`.
+ *
+ * @param {object} [initial] - Starting contents and the clock.
+ * @param {Record<string, unknown>} [initial.local] - What local holds.
+ * @param {Record<string, unknown>} [initial.sync] - What sync holds.
+ * @param {Record<string, unknown>} [initial.session] - What session holds.
+ * @param {() => number} [initial.now] - The clock sync's write limit reads. Default `Date.now`.
+ * @returns {FakeChromeStorage} The fake.
+ * @example
+ * const storage = fakeChromeStorage({ sync: { days: 3 } });
+ * await store.save(storage, { days: 5 });
+ * assert.equal(storage.sync.data.days, 5);
+ */
+export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = Date.now } = {}) {
+  /** @type {ChangeListener[]} */
+  const listeners = [];
+  /** @type {unknown[]} */
+  const running = [];
+
+  /**
+   * @param {string} name
+   * @param {Record<string, unknown>} initialData
+   * @param {{quotaPerItem?: number, writesPerMinute?: number}} [limits]
+   * @returns {FakeArea}
+   */
+  function area(name, initialData, { quotaPerItem, writesPerMinute } = {}) {
+    /** @type {Record<string, any>} */
+    const data = viaJson(initialData);
+    /** @type {number[]} */
+    const recent = [];
+    /** @param {Record<string, StorageChange>} changes */
+    const fire = (changes) => {
+      if (!Object.keys(changes).length) return;
+      for (const listener of listeners) running.push(listener(viaJson(changes), name));
+    };
+    /** A write, counted against the per-minute limit; refused over it, as Chrome does. */
+    const take = () => {
+      if (writesPerMinute) {
+        while (recent.length && recent[0] <= now() - 60_000) recent.shift();
+        if (recent.length >= writesPerMinute) throw new Error('This request exceeds the MAX_WRITE_OPERATIONS_PER_MINUTE quota.');
+        recent.push(now());
+      }
+      fake.writes++;
+    };
+    /** @type {FakeArea} */
+    const fake = {
+      data,
+      writes: 0,
+      async get(keys) {
+        const wanted = keys == null ? Object.keys(data) : [keys].flat();
+        return Object.fromEntries(wanted.filter((key) => key in data).map((key) => [key, viaJson(data[key])]));
+      },
+      async set(items) {
+        for (const [key, value] of Object.entries(items)) {
+          if (quotaPerItem && key.length + JSON.stringify(value).length > quotaPerItem) {
+            throw new Error('Resource::kQuotaBytesPerItem quota exceeded');
+          }
+        }
+        take();
+        /** @type {Record<string, StorageChange>} */
+        const changes = {};
+        for (const [key, value] of Object.entries(items)) {
+          if (JSON.stringify(data[key]) === JSON.stringify(value)) continue;
+          changes[key] = { oldValue: data[key], newValue: viaJson(value) };
+          data[key] = viaJson(value);
+        }
+        fire(changes);
+      },
+      async remove(keys) {
+        take();
+        /** @type {Record<string, StorageChange>} */
+        const changes = {};
+        for (const key of [keys].flat()) {
+          if (!(key in data)) continue;
+          changes[key] = { oldValue: data[key] };
+          delete data[key];
+        }
+        fire(changes);
+      },
+    };
+    return fake;
+  }
+
+  return {
+    local: area('local', local),
+    sync: area('sync', sync, { quotaPerItem: MAX_SYNC_ITEM_BYTES, writesPerMinute: SYNC_WRITES_PER_MINUTE }),
+    session: area('session', session),
+    onChanged: { addListener: (listener) => listeners.push(listener) },
+    async settled() {
+      while (running.length) await Promise.all(running.splice(0));
+    },
+  };
+}

package/src/testing/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * end-to-end tests and a server for their pages, and checks for a packaging
+ * test. Node only.
+ *
+ * @module testing
+ */
+export { checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { serve } from './server.js';
+export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { filesUnder, manifestReferences, missingReferences, zipEntries } from './package.js';
+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 Reply = import('./server.js').Reply;
+export type Routes = import('./server.js').Routes;
+export type TestServer = import('./server.js').TestServer;
+/**
+ * The helpers' types, for a test's JSDoc.
+ *
+ * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
+ * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
+ * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./server.js').Reply} Reply
+ * @typedef {import('./server.js').Routes} Routes
+ * @typedef {import('./server.js').TestServer} TestServer
+ */

package/src/testing/index.js

@@ -0,0 +1,24 @@
+/**
+ * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * end-to-end tests and a server for their pages, and checks for a packaging
+ * test. Node only.
+ *
+ * @module testing
+ */
+
+export { checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { serve } from './server.js';
+export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { filesUnder, manifestReferences, missingReferences, zipEntries } from './package.js';
+
+/**
+ * The helpers' types, for a test's JSDoc.
+ *
+ * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
+ * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
+ * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./server.js').Reply} Reply
+ * @typedef {import('./server.js').Routes} Routes
+ * @typedef {import('./server.js').TestServer} TestServer
+ */

package/src/testing/package.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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).
+ *
+ * @module testing/package
+ */
+/**
+ * Every file under `dir`.
+ *
+ * @param {string} dir - The folder.
+ * @returns {Promise<string[]>} Paths relative to it, forward slashes, sorted.
+ */
+export declare function filesUnder(dir: string): Promise<string[]>;
+/**
+ * The entries of the real zip of `from` (build/zip.js), listed by `unzip`.
+ *
+ * @param {string} from - The extension folder.
+ * @param {readonly string[]} [exclude] - `zip -x` patterns, as `zipExtension` takes.
+ * @returns {Promise<string[]>} Entry names, sorted.
+ */
+export declare function zipEntries(from: string, exclude?: readonly string[]): Promise<string[]>;
+/**
+ * The paths a manifest names, from the extension's root.
+ *
+ * @param {Record<string, any>} manifest - The parsed `manifest.json`.
+ * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources.
+ */
+export declare function manifestReferences(manifest: Record<string, any>): 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.
+ *
+ * @param {string} dir - The extension folder.
+ * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).
+ * @returns {Promise<string[]>} "from → target" for each missing one; empty when all resolve.
+ */
+export declare function missingReferences(dir: string, extra?: readonly string[]): Promise<string[]>;

package/src/testing/package.js

@@ -0,0 +1,96 @@
+/**
+ * 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).
+ *
+ * @module testing/package
+ */
+
+import { execFileSync } from 'node:child_process';
+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';
+
+/**
+ * Every file under `dir`.
+ *
+ * @param {string} dir - The folder.
+ * @returns {Promise<string[]>} Paths relative to it, forward slashes, sorted.
+ */
+export async function filesUnder(dir) {
+  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  return entries.filter((entry) => entry.isFile())
+    .map((entry) => path.relative(dir, path.join(entry.parentPath, entry.name)).split(path.sep).join('/'))
+    .sort();
+}
+
+/**
+ * The entries of the real zip of `from` (build/zip.js), listed by `unzip`.
+ *
+ * @param {string} from - The extension folder.
+ * @param {readonly string[]} [exclude] - `zip -x` patterns, as `zipExtension` takes.
+ * @returns {Promise<string[]>} Entry names, sorted.
+ */
+export async function zipEntries(from, exclude) {
+  const tmp = await mkdtemp(path.join(tmpdir(), 'extension-zip-'));
+  try {
+    const zip = await zipExtension(from, path.join(tmp, 'out.zip'), exclude);
+    return execFileSync('unzip', ['-Z1', zip], { encoding: 'utf8' }).trim().split('\n').sort();
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The paths a manifest names, from the extension's root.
+ *
+ * @param {Record<string, any>} manifest - The parsed `manifest.json`.
+ * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources.
+ */
+export function manifestReferences(manifest) {
+  return [
+    manifest.background?.service_worker,
+    manifest.options_ui?.page,
+    manifest.action?.default_popup,
+    manifest.side_panel?.default_path,
+    ...Object.values(manifest.icons ?? {}),
+    ...Object.values(manifest.action?.default_icon ?? {}),
+    ...(manifest.web_accessible_resources ?? []).flatMap((/** @type {{resources: string[]}} */ entry) => entry.resources),
+  ].filter((ref) => typeof ref === 'string' && !ref.includes('*'));
+}
+
+/**
+ * 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.
+ *
+ * @param {string} dir - The extension folder.
+ * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).
+ * @returns {Promise<string[]>} "from → target" for each missing one; empty when all resolve.
+ */
+export async function missingReferences(dir, extra = []) {
+  const root = path.resolve(dir);
+  /** @type {string[]} */
+  const missing = [];
+  /** @param {string} from @param {string} target */
+  const check = (from, target) => {
+    const file = path.resolve(root, from, target);
+    if (!file.startsWith(root) || !existsSync(file)) missing.push(`${from || 'root'} → ${target}`);
+  };
+  for (const file of await filesUnder(root)) {
+    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 manifest = JSON.parse(await readFile(path.join(root, 'manifest.json'), 'utf8'));
+  for (const ref of [...manifestReferences(manifest), ...extra]) check('', ref);
+  return missing;
+}

package/src/testing/server.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ *
+ * @module testing/server
+ */
+import type { IncomingMessage, Server } from 'node:http';
+export type Reply = string | Uint8Array | {
+    body: string | Uint8Array;
+    type?: string;
+    status?: number;
+    headers?: Record<string, string>;
+};
+export type Routes = Readonly<Record<string, Reply>> | ReadonlyMap<string, Reply> | ((pathname: string, request: IncomingMessage) => Reply | undefined | Promise<Reply | undefined>);
+export type TestServer = {
+    /**
+     * Node's server.
+     */
+    server: Server;
+    /**
+     * The port it listens on.
+     */
+    port: number;
+    /**
+     * `http://127.0.0.1:<port>`.
+     */
+    origin: string;
+    /**
+     * Drop open connections and stop listening.
+     */
+    close: () => Promise<void>;
+};
+/**
+ * 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).
+ * @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 }?: {
+    port?: number;
+}): Promise<TestServer>;

package/src/testing/server.js

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ *
+ * @module testing/server
+ */
+
+import { createServer } from 'node:http';
+
+/** @import { IncomingMessage, Server } from 'node:http' */
+
+/**
+ * What a path answers: a body (sent as UTF-8 HTML), or a body with its own
+ * type, status and headers.
+ *
+ * @typedef {string | Uint8Array | {body: string | Uint8Array, type?: string, status?: number, headers?: Record<string, string>}} Reply
+ */
+
+/**
+ * The site: path (without the query) → reply, as an object or a `Map` (which
+ * a test may change as it goes), or a function of the path; no reply is a 404.
+ *
+ * @typedef {Readonly<Record<string, Reply>> | ReadonlyMap<string, Reply>
+ *   | ((pathname: string, request: IncomingMessage) => Reply | undefined | Promise<Reply | undefined>)} Routes
+ */
+
+/**
+ * A running test site.
+ *
+ * @typedef {object} TestServer
+ * @property {Server} server Node's server.
+ * @property {number} port The port it listens on.
+ * @property {string} origin `http://127.0.0.1:<port>`.
+ * @property {() => Promise<void>} close Drop open connections and stop listening.
+ */
+
+const HTML = 'text/html; charset=utf-8';
+
+/**
+ * The reply for a path.
+ *
+ * @param {Routes} routes - The site.
+ * @param {string} pathname - The request's path.
+ * @param {IncomingMessage} request - The request.
+ * @returns {Promise<Reply | undefined>} What to send; `undefined` for a 404.
+ */
+async function replyFor(routes, pathname, request) {
+  if (typeof routes === 'function') return routes(pathname, request);
+  if (routes instanceof Map) return routes.get(pathname);
+  const table = /** @type {Readonly<Record<string, Reply>>} */ (routes);
+  return Object.hasOwn(table, pathname) ? table[pathname] : undefined;
+}
+
+/**
+ * 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).
+ * @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) => {
+    const { pathname } = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const reply = await replyFor(routes, pathname, request);
+    if (reply === undefined) {
+      response.writeHead(404, { 'Content-Type': HTML });
+      response.end('');
+      return;
+    }
+    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);
+  });
+  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}`,
+    close() {
+      server.closeAllConnections();
+      return new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}

package/src/toolbar/offscreen.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The offscreen scheme watcher (toolbar/theme.js `watchFromOffscreen`): the
+ * one job of an offscreen document kept open to hear light/dark changes.
+ * Offscreen documents get `chrome.runtime` and nothing else, so it can't read
+ * what's stored: it reports once on opening (the worker drops a repeat), then
+ * on each change.
+ *
+ * @module toolbar/offscreen
+ */
+import type { MessageSender, SchemeMedia } from './scheme.js';
+/** @import { MessageSender, SchemeMedia } from './scheme.js' */
+/**
+ * How often the watcher looks, ms. An offscreen document never renders, and
+ * Chrome fires a media query's `change` event as part of rendering, so there
+ * it never comes (checked in Chromium 157: no animation frames either).
+ * `matches` itself stays current, so look every few seconds: one cached
+ * boolean read, and a message only when it differs.
+ */
+export declare const POLL_MS = 2000;
+/**
+ * Start watching. The offscreen document's script is just this call.
+ *
+ * @param {MessageSender} runtime - `chrome.runtime`.
+ * @param {SchemeMedia} [media] - Default `matchMedia(DARK_QUERY)`.
+ * @returns {ReturnType<typeof setInterval>} The poll, for `clearInterval` in tests.
+ * @example
+ * // offscreen/offscreen.js
+ * watchSchemeOffscreen(chrome.runtime);
+ */
+export declare function watchSchemeOffscreen(runtime: MessageSender, media?: SchemeMedia): ReturnType<typeof setInterval>;

package/src/toolbar/offscreen.js

@@ -0,0 +1,37 @@
+/**
+ * The offscreen scheme watcher (toolbar/theme.js `watchFromOffscreen`): the
+ * one job of an offscreen document kept open to hear light/dark changes.
+ * Offscreen documents get `chrome.runtime` and nothing else, so it can't read
+ * what's stored: it reports once on opening (the worker drops a repeat), then
+ * on each change.
+ *
+ * @module toolbar/offscreen
+ */
+
+import { DARK_QUERY, reportColorScheme, schemeSender } from './scheme.js';
+
+/** @import { MessageSender, SchemeMedia } from './scheme.js' */
+
+/**
+ * How often the watcher looks, ms. An offscreen document never renders, and
+ * Chrome fires a media query's `change` event as part of rendering, so there
+ * it never comes (checked in Chromium 157: no animation frames either).
+ * `matches` itself stays current, so look every few seconds: one cached
+ * boolean read, and a message only when it differs.
+ */
+export const POLL_MS = 2000;
+
+/**
+ * Start watching. The offscreen document's script is just this call.
+ *
+ * @param {MessageSender} runtime - `chrome.runtime`.
+ * @param {SchemeMedia} [media] - Default `matchMedia(DARK_QUERY)`.
+ * @returns {ReturnType<typeof setInterval>} The poll, for `clearInterval` in tests.
+ * @example
+ * // offscreen/offscreen.js
+ * watchSchemeOffscreen(chrome.runtime);
+ */
+export function watchSchemeOffscreen(runtime, media = matchMedia(DARK_QUERY)) {
+  const check = reportColorScheme(media, undefined, schemeSender(runtime));
+  return setInterval(check, POLL_MS);
+}

package/src/toolbar/scheme.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The page side of the light/dark toolbar glyph: documents tell the service
+ * worker whether they see a light or dark colour scheme, so it can swap the
+ * glyph (toolbar/theme.js). The worker has no `matchMedia`, so documents
+ * report: an extension's pages, its offscreen watcher, or a content script.
+ * Kept tiny, as a content script may carry it.
+ *
+ * @module toolbar/scheme
+ */
+/** `chrome.storage.local`: the scheme last reported. This computer's, never synced. */
+export declare const TOOLBAR_DARK_KEY = "toolbarDark";
+/** The report's message type: `{type: TOOLBAR_SCHEME, dark: boolean}`. */
+export declare const TOOLBAR_SCHEME = "toolbar-scheme";
+/** The media query that matches a dark colour scheme. */
+export declare const DARK_QUERY = "(prefers-color-scheme: dark)";
+export type MessageSender = {
+    sendMessage(message: unknown): Promise<unknown>;
+};
+export type SchemeApi = {
+    /**
+     * `chrome.runtime`.
+     */
+    runtime: MessageSender;
+    /**
+     * `chrome.storage`.
+     */
+    storage: {
+        local: {
+            get(keys: string): Promise<Record<string, any>>;
+        };
+    };
+};
+export type SchemeMedia = Pick<MediaQueryList, 'matches' | 'addEventListener'>;
+/**
+ * What a document reports through: `chrome.runtime`, or a fake.
+ *
+ * @typedef {{sendMessage(message: unknown): Promise<unknown>}} MessageSender
+ */
+/**
+ * What `watchColorScheme` needs: `chrome` itself will do.
+ *
+ * @typedef {object} SchemeApi
+ * @property {MessageSender} runtime `chrome.runtime`.
+ * @property {{local: {get(keys: string): Promise<Record<string, any>>}}} storage `chrome.storage`.
+ */
+/**
+ * The smallest `MediaQueryList`: `matchMedia(DARK_QUERY)`.
+ *
+ * @typedef {Pick<MediaQueryList, 'matches' | 'addEventListener'>} SchemeMedia
+ */
+/**
+ * Send `dark` now if it differs from `known` (what's stored), then on each
+ * change: a page load where nothing changed sends nothing.
+ *
+ * @param {SchemeMedia} media - `matchMedia(DARK_QUERY)`.
+ * @param {boolean | undefined} known - What the worker last stored;
+ *   undefined (unknown) sends once.
+ * @param {(dark: boolean) => void} send - Delivers a report.
+ * @returns {() => void} The check itself, for a document that has to poll
+ *   (an offscreen document never hears `change`).
+ */
+export declare function reportColorScheme(media: SchemeMedia, known: boolean | undefined, send: (dark: boolean) => void): () => void;
+/**
+ * A sender of scheme reports. The worker may be asleep or restarting: a lost
+ * report is retried by the next change or page, so failures are dropped.
+ *
+ * @param {MessageSender} runtime - `chrome.runtime`.
+ * @returns {(dark: boolean) => Promise<unknown>} Sends one report.
+ */
+export declare function schemeSender(runtime: MessageSender): (dark: boolean) => Promise<unknown>;
+/**
+ * For an extension page: read what's stored, then report now if it differs
+ * and on every change.
+ *
+ * @param {SchemeApi} api - `chrome`, or a fake with `runtime` and `storage.local`.
+ * @param {SchemeMedia} [media] - Default `matchMedia(DARK_QUERY)`.
+ * @returns {Promise<void>} Resolves once the first check has run.
+ * @example
+ * watchColorScheme(chrome).catch((error) => console.debug('Reporting the colour scheme:', error));
+ */
+export declare function watchColorScheme(api: SchemeApi, media?: SchemeMedia): Promise<void>;