@arraypress/extension-kit 0.0.0-stage → 1.1.0

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;

package/src/toolbar/theme.js

@@ -0,0 +1,176 @@
+/**
+ * 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
+ */
+
+import { TOOLBAR_DARK_KEY, TOOLBAR_SCHEME } from './scheme.js';
+
+/** Where the offscreen scheme watcher lives, from the extension's root. */
+export const OFFSCREEN_PATH = 'offscreen/offscreen.html';
+
+/** Where the rendered glyphs live (build/toolbar-icons.js writes them). */
+export const TOOLBAR_ICON_DIR = '/icons/toolbar';
+
+/**
+ * @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 function toolbarIcon(dark) {
+  const scheme = dark ? 'dark' : 'light';
+  return {
+    16: `${TOOLBAR_ICON_DIR}/${scheme}-16.png`,
+    32: `${TOOLBAR_ICON_DIR}/${scheme}-32.png`,
+    48: `${TOOLBAR_ICON_DIR}/${scheme}-48.png`,
+  };
+}
+
+/**
+ * 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 function createToolbarTheme({ storage, action, extensionId }) {
+  /** @type {Promise<void>} */
+  let queue = Promise.resolve();
+  /** @param {boolean} dark */
+  const show = (dark) => action.setIcon({ path: toolbarIcon(dark) });
+
+  return {
+    restore() {
+      queue = queue.then(async () => {
+        const { [TOOLBAR_DARK_KEY]: dark } = await storage.get(TOOLBAR_DARK_KEY);
+        if (dark === true) await show(true);
+      }).catch((error) => console.error('Restoring the toolbar icon:', error));
+      return queue;
+    },
+
+    onMessage(message, sender) {
+      const report = /** @type {{type?: unknown, dark?: unknown} | null | undefined} */ (message);
+      if (report?.type !== TOOLBAR_SCHEME) return false;
+      const { dark } = report;
+      if (sender?.id !== extensionId || typeof dark !== 'boolean') return true;
+      queue = queue.then(async () => {
+        const { [TOOLBAR_DARK_KEY]: was = false } = await storage.get(TOOLBAR_DARK_KEY);
+        if (was === dark) return;
+        // Shown first: if Chrome refuses the icon, nothing is stored, and the next report tries again.
+        await show(dark);
+        await storage.set({ [TOOLBAR_DARK_KEY]: dark });
+      }).catch((error) => console.error('Changing the toolbar icon:', error));
+      return true;
+    },
+
+    settled: () => queue,
+  };
+}
+
+/**
+ * What opening the offscreen watcher needs: pieces of `chrome`, or fakes.
+ *
+ * @typedef {object} OffscreenApi
+ * @property {{createDocument(details: {url: string, reasons: string[], justification: string}): Promise<void>, Reason: {MATCH_MEDIA: string}}} offscreen
+ *   `chrome.offscreen`.
+ * @property {{getContexts(filter: {contextTypes: 'OFFSCREEN_DOCUMENT'[]}): Promise<unknown[]>}} runtime `chrome.runtime`.
+ */
+
+/** @type {Promise<boolean> | null} */
+let opening = null;
+
+/**
+ * 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 function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH) {
+  opening ??= (async () => {
+    const open = await runtime.getContexts({ contextTypes: ['OFFSCREEN_DOCUMENT'] });
+    if (open.length) return false;
+    await offscreen.createDocument({
+      url,
+      reasons: [offscreen.Reason.MATCH_MEDIA],
+      justification: 'Reads whether Chrome is in light or dark mode, to show the matching toolbar icon.',
+    });
+    return true;
+  })().finally(() => { opening = null; });
+  return opening;
+}
+
+/**
+ * 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 function startToolbarTheme(api) {
+  const theme = createToolbarTheme({ storage: api.storage.local, action: api.action, extensionId: api.runtime.id });
+  theme.restore();
+  watchFromOffscreen(api).catch((error) => console.error('Opening the colour scheme watcher:', error));
+  api.runtime.onMessage.addListener((message, sender) => {
+    theme.onMessage(message, sender);
+    return false;
+  });
+  return theme;
+}