@arraypress/extension-kit 0.0.0-stage → 1.0.0

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/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>;

package/src/toolbar/scheme.js

@@ -0,0 +1,87 @@
+/**
+ * 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 const TOOLBAR_DARK_KEY = 'toolbarDark';
+
+/** The report's message type: `{type: TOOLBAR_SCHEME, dark: boolean}`. */
+export const TOOLBAR_SCHEME = 'toolbar-scheme';
+
+/** The media query that matches a dark colour scheme. */
+export const DARK_QUERY = '(prefers-color-scheme: dark)';
+
+/**
+ * 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 function reportColorScheme(media, known, send) {
+  let last = known;
+  const report = () => {
+    if (media.matches === last) return;
+    last = media.matches;
+    send(last);
+  };
+  report();
+  media.addEventListener('change', report);
+  return report;
+}
+
+/**
+ * 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 function schemeSender(runtime) {
+  return (dark) => runtime.sendMessage({ type: TOOLBAR_SCHEME, dark }).catch(() => {});
+}
+
+/**
+ * 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 async function watchColorScheme(api, media = matchMedia(DARK_QUERY)) {
+  const { [TOOLBAR_DARK_KEY]: stored } = await api.storage.local.get(TOOLBAR_DARK_KEY);
+  reportColorScheme(media, stored === true, schemeSender(api.runtime));
+}

package/src/toolbar/theme.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The worker side of the light/dark toolbar glyph, as Chrome's own toolbar
+ * icons do. The service worker can't see the scheme (no `matchMedia`), so
+ * documents report it (toolbar/scheme.js); this stores the last report per
+ * computer and shows the matching glyph. `setIcon` changes only the image: a
+ * badge still draws over it.
+ *
+ * An extension with nothing of its own on every page can keep an offscreen
+ * document open to hear a theme change (`watchFromOffscreen`,
+ * toolbar/offscreen.js).
+ *
+ * @module toolbar/theme
+ */
+/** Where the offscreen scheme watcher lives, from the extension's root. */
+export declare const OFFSCREEN_PATH = "offscreen/offscreen.html";
+/** Where the rendered glyphs live (build/toolbar-icons.js writes them). */
+export declare const TOOLBAR_ICON_DIR = "/icons/toolbar";
+export type ToolbarIconPaths = {
+    16: string;
+    32: string;
+    48: string;
+};
+export type ToolbarThemeApi = {
+    /**
+     *   `chrome.storage.local`.
+     */
+    storage: {
+        get(keys: string): Promise<Record<string, any>>;
+        set(items: Record<string, unknown>): Promise<void>;
+    };
+    /**
+     * `chrome.action`.
+     */
+    action: {
+        setIcon(details: {
+            path: ToolbarIconPaths;
+        }): Promise<void>;
+    };
+    /**
+     * `chrome.runtime.id`: reports from anyone else are ignored.
+     */
+    extensionId: string;
+};
+export type ToolbarTheme = {
+    /**
+     * Show the dark glyph again if that's what was
+     * seen last: after a restart or re-enable Chrome shows the manifest's light one.
+     */
+    restore: () => Promise<void>;
+    /**
+     * Handle a
+     * scheme report; returns whether it was one (handled or ignored), so a worker's
+     * message listener can stop there.
+     */
+    onMessage: (message: unknown, sender?: {
+        id?: string;
+    }) => boolean;
+    /**
+     * Resolves once every report so far is handled.
+     */
+    settled: () => Promise<void>;
+};
+/**
+ * @typedef {{16: string, 32: string, 48: string}} ToolbarIconPaths
+ */
+/**
+ * The worker APIs the toolbar theme uses: pieces of `chrome`, or fakes.
+ *
+ * @typedef {object} ToolbarThemeApi
+ * @property {{get(keys: string): Promise<Record<string, any>>, set(items: Record<string, unknown>): Promise<void>}} storage
+ *   `chrome.storage.local`.
+ * @property {{setIcon(details: {path: ToolbarIconPaths}): Promise<void>}} action `chrome.action`.
+ * @property {string} extensionId `chrome.runtime.id`: reports from anyone else are ignored.
+ */
+/**
+ * @typedef {object} ToolbarTheme
+ * @property {() => Promise<void>} restore Show the dark glyph again if that's what was
+ *   seen last: after a restart or re-enable Chrome shows the manifest's light one.
+ * @property {(message: unknown, sender?: {id?: string}) => boolean} onMessage Handle a
+ *   scheme report; returns whether it was one (handled or ignored), so a worker's
+ *   message listener can stop there.
+ * @property {() => Promise<void>} settled Resolves once every report so far is handled.
+ */
+/**
+ * The glyph for a scheme; the manifest's `default_icon` is the light one.
+ * Paths start with "/": Chrome resolves `setIcon` paths against the worker's
+ * own address, where a relative one fails to load.
+ *
+ * @param {boolean} dark - The dark scheme's glyph, else the light one's.
+ * @returns {ToolbarIconPaths} Paths by size, for `chrome.action.setIcon`.
+ * @example
+ * toolbarIcon(true); // { 16: '/icons/toolbar/dark-16.png', 32: …, 48: … }
+ */
+export declare function toolbarIcon(dark: boolean): ToolbarIconPaths;
+/**
+ * The worker's toolbar theme: one report at a time, so two quick ones can't
+ * store one scheme and show the other.
+ *
+ * @param {ToolbarThemeApi} api - Storage, the action and this extension's id.
+ * @returns {ToolbarTheme} The theme's handlers.
+ */
+export declare function createToolbarTheme({ storage, action, extensionId }: ToolbarThemeApi): ToolbarTheme;
+export type OffscreenApi = {
+    /**
+     *   `chrome.offscreen`.
+     */
+    offscreen: {
+        createDocument(details: {
+            url: string;
+            reasons: string[];
+            justification: string;
+        }): Promise<void>;
+        Reason: {
+            MATCH_MEDIA: string;
+        };
+    };
+    /**
+     * `chrome.runtime`.
+     */
+    runtime: {
+        getContexts(filter: {
+            contextTypes: 'OFFSCREEN_DOCUMENT'[];
+        }): Promise<unknown[]>;
+    };
+};
+/**
+ * Open the offscreen document that watches the scheme (reason MATCH_MEDIA),
+ * unless it's open. It stays open: it's one small page in the extension's own
+ * process, and the only way to hear a theme change while no page of ours is
+ * open. Chrome closes it when the browser quits, so call this each time the
+ * worker starts. Concurrent calls share one attempt.
+ *
+ * @param {OffscreenApi} api - `chrome.offscreen` and `chrome.runtime`.
+ * @param {string} [url] - The document, from the extension's root. Default {@link OFFSCREEN_PATH}.
+ * @returns {Promise<boolean>} Whether it opened one (false: already open).
+ */
+export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string): Promise<boolean>;
+export type ToolbarWorkerApi = {
+    /**
+     * `chrome.storage`.
+     */
+    storage: {
+        local: ToolbarThemeApi['storage'];
+    };
+    /**
+     * `chrome.action`.
+     */
+    action: ToolbarThemeApi['action'];
+    /**
+     * `chrome.offscreen`.
+     */
+    offscreen: OffscreenApi['offscreen'];
+    /**
+     *   `chrome.runtime`.
+     */
+    runtime: OffscreenApi['runtime'] & {
+        id: string;
+        onMessage: {
+            addListener(listener: (message: unknown, sender: {
+                id?: string;
+            }) => boolean): void;
+        };
+    };
+};
+/**
+ * Everything `startToolbarTheme` wires up: `chrome` itself will do.
+ *
+ * @typedef {object} ToolbarWorkerApi
+ * @property {{local: ToolbarThemeApi['storage']}} storage `chrome.storage`.
+ * @property {ToolbarThemeApi['action']} action `chrome.action`.
+ * @property {OffscreenApi['offscreen']} offscreen `chrome.offscreen`.
+ * @property {OffscreenApi['runtime'] & {id: string, onMessage: {addListener(listener: (message: unknown, sender: {id?: string}) => boolean): void}}} runtime
+ *   `chrome.runtime`.
+ */
+/**
+ * The whole worker side for an extension that watches from an offscreen
+ * document: restore the last glyph, open the watcher, and handle its reports.
+ * Call it at the worker's top level, so the listener attaches every time the
+ * worker wakes.
+ *
+ * @param {ToolbarWorkerApi} api - `chrome`, or a fake.
+ * @returns {ToolbarTheme} The theme, for tests.
+ * @example
+ * // background.js
+ * startToolbarTheme(chrome);
+ */
+export declare function startToolbarTheme(api: ToolbarWorkerApi): ToolbarTheme;