@arraypress/extension-kit 1.9.0 → 1.11.0

package/src/testing/package.js

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

package/src/testing/pages.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Reaching a tested extension's pages from an e2e test: a Playwright page's
+ * tab id (as the extension's worker sees it), a page module called in a
+ * tab's frames as the extension calls it, and a page's whole tree through
+ * the DevTools protocol, closed shadow roots and frames included (where an
+ * extension's overlay lives). Tests only: an extension never needs CDP.
+ *
+ * @module testing/pages
+ */
+import type { CDPSession, Page, Worker } from 'playwright';
+/** @import { CDPSession, Page, Worker } from 'playwright' */
+/**
+ * The tab id of a page: the newest tab at its address (any tab for a `chrome:` page).
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @param {Page} page - The page.
+ * @returns {Promise<number>} Its tab's id.
+ * @example
+ * const tabId = await tabIdOf(worker, page);
+ */
+export declare function tabIdOf(worker: Worker, page: Page): Promise<number>;
+/**
+ * Call an export of the extension's page module in a tab's frames, as `callInPage` does from the
+ * worker.
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @param {number} tabId - The tab.
+ * @param {string} module - The module's path in the extension (`content/main.js`).
+ * @param {string} name - The export.
+ * @param {unknown[]} [args] - Its arguments.
+ * @returns {Promise<{frameId: number, result: any}[]>} Each frame's answer.
+ * @example
+ * const [{ result }] = await callTabModule(worker, tabId, 'content/main.js', 'scan');
+ */
+export declare function callTabModule(worker: Worker, tabId: number, module: string, name: string, args?: unknown[]): Promise<{
+    frameId: number;
+    result: any;
+}[]>;
+export type CdpNode = {
+    /**
+     * Its id in the session.
+     */
+    nodeId: number;
+    /**
+     * Its lasting id.
+     */
+    backendNodeId: number;
+    /**
+     * Its DOM node type.
+     */
+    nodeType: number;
+    /**
+     * Its name.
+     */
+    nodeName: string;
+    /**
+     * A text node's text.
+     */
+    nodeValue?: string;
+    /**
+     * Its attributes, name and value in turn.
+     */
+    attributes?: string[];
+    /**
+     * Its children.
+     */
+    children?: CdpNode[];
+    /**
+     * Its shadow roots, closed ones too.
+     */
+    shadowRoots?: CdpNode[];
+    /**
+     * A frame's document.
+     */
+    contentDocument?: CdpNode;
+};
+/**
+ * A node as the DevTools protocol's `DOM.getDocument` gives it (the parts read here).
+ *
+ * @typedef {object} CdpNode
+ * @property {number} nodeId Its id in the session.
+ * @property {number} backendNodeId Its lasting id.
+ * @property {number} nodeType Its DOM node type.
+ * @property {string} nodeName Its name.
+ * @property {string} [nodeValue] A text node's text.
+ * @property {string[]} [attributes] Its attributes, name and value in turn.
+ * @property {CdpNode[]} [children] Its children.
+ * @property {CdpNode[]} [shadowRoots] Its shadow roots, closed ones too.
+ * @property {CdpNode} [contentDocument] A frame's document.
+ */
+/**
+ * Every node of a page's tree in tree order, closed shadow roots and same-process frames included.
+ *
+ * @param {CDPSession} cdp - A session on the page.
+ * @returns {Promise<CdpNode[]>} The nodes; a node's shadow roots come before its children.
+ * @example
+ * const boxes = (await pierceNodes(cdp)).filter((node) => nodeAttribute(node, 'class') === 'box');
+ */
+export declare function pierceNodes(cdp: CDPSession): Promise<CdpNode[]>;
+/**
+ * A node's attribute.
+ *
+ * @param {CdpNode} node - The node.
+ * @param {string} name - The attribute.
+ * @returns {string} Its value, or ''.
+ */
+export declare function nodeAttribute(node: CdpNode, name: string): string;
+/**
+ * A node's text: a text node's own, an element's children's joined.
+ *
+ * @param {CdpNode} node - The node.
+ * @returns {string} Its text.
+ */
+export declare const nodeText: (node: CdpNode) => string;

package/src/testing/pages.js

@@ -0,0 +1,109 @@
+/**
+ * Reaching a tested extension's pages from an e2e test: a Playwright page's
+ * tab id (as the extension's worker sees it), a page module called in a
+ * tab's frames as the extension calls it, and a page's whole tree through
+ * the DevTools protocol, closed shadow roots and frames included (where an
+ * extension's overlay lives). Tests only: an extension never needs CDP.
+ *
+ * @module testing/pages
+ */
+
+/** @import { CDPSession, Page, Worker } from 'playwright' */
+
+/**
+ * The tab id of a page: the newest tab at its address (any tab for a `chrome:` page).
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @param {Page} page - The page.
+ * @returns {Promise<number>} Its tab's id.
+ * @example
+ * const tabId = await tabIdOf(worker, page);
+ */
+export async function tabIdOf(worker, page) {
+  return worker.evaluate(async (url) => {
+    const query = url.startsWith('chrome:') ? {} : { url: url.replace(/#.*$/, '') };
+    const ids = (await chrome.tabs.query(query)).map((tab) => tab.id ?? -1);
+    if (!ids.length) throw new Error(`No tab for ${url}`);
+    return Math.max(...ids);
+  }, page.url());
+}
+
+/**
+ * Call an export of the extension's page module in a tab's frames, as `callInPage` does from the
+ * worker.
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @param {number} tabId - The tab.
+ * @param {string} module - The module's path in the extension (`content/main.js`).
+ * @param {string} name - The export.
+ * @param {unknown[]} [args] - Its arguments.
+ * @returns {Promise<{frameId: number, result: any}[]>} Each frame's answer.
+ * @example
+ * const [{ result }] = await callTabModule(worker, tabId, 'content/main.js', 'scan');
+ */
+export function callTabModule(worker, tabId, module, name, args = []) {
+  return worker.evaluate(({ tabId, module, name, args }) => chrome.scripting.executeScript({
+    target: { tabId, allFrames: true },
+    injectImmediately: true,
+    // As the kit's importAndCall (a worker's evaluate takes no function from outside, and its CSP no eval).
+    func: (/** @type {string} */ module, /** @type {string} */ name, /** @type {unknown[]} */ args) => import(chrome.runtime.getURL(module)).then((loaded) => loaded[name](...args)),
+    args: [module, name, args],
+  }).then((frames) => frames.map(({ frameId, result }) => ({ frameId, result }))), { tabId, module, name, args });
+}
+
+/**
+ * A node as the DevTools protocol's `DOM.getDocument` gives it (the parts read here).
+ *
+ * @typedef {object} CdpNode
+ * @property {number} nodeId Its id in the session.
+ * @property {number} backendNodeId Its lasting id.
+ * @property {number} nodeType Its DOM node type.
+ * @property {string} nodeName Its name.
+ * @property {string} [nodeValue] A text node's text.
+ * @property {string[]} [attributes] Its attributes, name and value in turn.
+ * @property {CdpNode[]} [children] Its children.
+ * @property {CdpNode[]} [shadowRoots] Its shadow roots, closed ones too.
+ * @property {CdpNode} [contentDocument] A frame's document.
+ */
+
+/**
+ * Every node of a page's tree in tree order, closed shadow roots and same-process frames included.
+ *
+ * @param {CDPSession} cdp - A session on the page.
+ * @returns {Promise<CdpNode[]>} The nodes; a node's shadow roots come before its children.
+ * @example
+ * const boxes = (await pierceNodes(cdp)).filter((node) => nodeAttribute(node, 'class') === 'box');
+ */
+export async function pierceNodes(cdp) {
+  const { root } = /** @type {{root: CdpNode}} */ (await cdp.send('DOM.getDocument', { depth: -1, pierce: true }));
+  /** @type {CdpNode[]} */
+  const nodes = [];
+  /** @param {CdpNode} node */
+  const walk = (node) => {
+    nodes.push(node);
+    for (const child of [...(node.shadowRoots ?? []), ...(node.children ?? []), ...(node.contentDocument ? [node.contentDocument] : [])]) walk(child);
+  };
+  walk(root);
+  return nodes;
+}
+
+/**
+ * A node's attribute.
+ *
+ * @param {CdpNode} node - The node.
+ * @param {string} name - The attribute.
+ * @returns {string} Its value, or ''.
+ */
+export function nodeAttribute(node, name) {
+  const attributes = node.attributes ?? [];
+  const at = attributes.findIndex((value, index) => index % 2 === 0 && value === name);
+  return at >= 0 ? attributes[at + 1] : '';
+}
+
+/**
+ * A node's text: a text node's own, an element's children's joined.
+ *
+ * @param {CdpNode} node - The node.
+ * @returns {string} Its text.
+ */
+export const nodeText = (node) => (node.nodeType === 3 ? node.nodeValue ?? '' : (node.children ?? []).map(nodeText).join(''));

package/src/testing/prompt.d.ts

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

package/src/testing/prompt.js

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

package/src/time/pool.d.ts

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

package/src/time/pool.js

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

package/src/toolbar/theme.d.ts

@@ -132,9 +132,12 @@ export type OffscreenApi = {
  *
  * @param {OffscreenApi} api - `chrome.offscreen` and `chrome.runtime`.
  * @param {string} [url] - The document, from the extension's root. Default {@link OFFSCREEN_PATH}.
+ * @param {string} [justification] - What the document is for, when it does more than watch the
+ *   scheme (it answers for Chrome's on-device model too, `serveModelOffscreen`): Chrome keeps it
+ *   with the document, so it has to be the whole truth.
  * @returns {Promise<boolean>} Whether it opened one (false: already open).
  */
-export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string): Promise<boolean>;
+export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string, justification?: string): Promise<boolean>;
 export type ToolbarWorkerApi = {
     /**
      * `chrome.storage`.
@@ -179,9 +182,14 @@ export type ToolbarWorkerApi = {
  * worker wakes.
  *
  * @param {ToolbarWorkerApi} api - `chrome`, or a fake.
+ * @param {{url?: string, justification?: string}} [document] - The offscreen document and what
+ *   it's for, when it isn't the kit's defaults ({@link watchFromOffscreen}).
  * @returns {ToolbarTheme} The theme, for tests.
  * @example
  * // background.js
  * startToolbarTheme(chrome);
  */
-export declare function startToolbarTheme(api: ToolbarWorkerApi): ToolbarTheme;
+export declare function startToolbarTheme(api: ToolbarWorkerApi, { url, justification }?: {
+    url?: string;
+    justification?: string;
+}): ToolbarTheme;

package/src/toolbar/theme.js

@@ -116,6 +116,9 @@ export function createToolbarTheme({ storage, action, extensionId }) {
 /** @type {Promise<boolean> | null} */
 let opening = null;
 
+/** Why the offscreen document is open, as Chrome is told. */
+const SCHEME_JUSTIFICATION = 'Reads whether Chrome is in light or dark mode, to show the matching toolbar icon.';
+
 /**
  * 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
@@ -125,16 +128,19 @@ let opening = null;
  *
  * @param {OffscreenApi} api - `chrome.offscreen` and `chrome.runtime`.
  * @param {string} [url] - The document, from the extension's root. Default {@link OFFSCREEN_PATH}.
+ * @param {string} [justification] - What the document is for, when it does more than watch the
+ *   scheme (it answers for Chrome's on-device model too, `serveModelOffscreen`): Chrome keeps it
+ *   with the document, so it has to be the whole truth.
  * @returns {Promise<boolean>} Whether it opened one (false: already open).
  */
-export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH) {
+export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH, justification = SCHEME_JUSTIFICATION) {
   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.',
+      justification,
     });
     return true;
   })().finally(() => { opening = null; });
@@ -159,15 +165,17 @@ export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH)
  * worker wakes.
  *
  * @param {ToolbarWorkerApi} api - `chrome`, or a fake.
+ * @param {{url?: string, justification?: string}} [document] - The offscreen document and what
+ *   it's for, when it isn't the kit's defaults ({@link watchFromOffscreen}).
  * @returns {ToolbarTheme} The theme, for tests.
  * @example
  * // background.js
  * startToolbarTheme(chrome);
  */
-export function startToolbarTheme(api) {
+export function startToolbarTheme(api, { url, justification } = {}) {
   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));
+  watchFromOffscreen(api, url, justification).catch((error) => console.error('Opening the colour scheme watcher:', error));
   api.runtime.onMessage.addListener((message, sender) => {
     theme.onMessage(message, sender);
     return false;

package/src/ui/menu.d.ts

@@ -99,8 +99,10 @@ export type Box = {
  *
  * @param {{width: number, height: number}} size - The menu's size.
  * @param {{width: number, height: number}} viewport - The window's (`innerWidth`, `innerHeight`).
- * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below'}} where - The anchor's
- *   box, or a point; `placement` says where it goes from an anchor (default `'over'`).
+ * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below', rtl?: boolean}} where - The
+ *   anchor's box, or a point; `placement` says where it goes from an anchor (default `'over'`); `rtl`
+ *   (a right-to-left page) lines its start up with the anchor's left edge and opens leftwards from a
+ *   point, as Chrome mirrors its own.
  * @returns {{left: number, top: number}} The menu's top-left, in px.
  * @example
  * menuPosition({width: 160, height: 120}, {width: 800, height: 600}, {anchor: button.getBoundingClientRect()});
@@ -112,11 +114,12 @@ export declare function menuPosition(size: {
 }, viewport: {
     width: number;
     height: number;
-}, { anchor, x, y, placement }: {
+}, { anchor, x, y, placement, rtl }: {
     anchor?: Box;
     x?: number;
     y?: number;
     placement?: 'over' | 'below';
+    rtl?: boolean;
 }): {
     left: number;
     top: number;
@@ -163,6 +166,11 @@ export type ActionMenu = {
      * Close it, if open, and return the focus.
      */
     close: () => void;
+    /**
+     * Take it off the page and stop listening to the window (a content
+     * script's overlay being removed).
+     */
+    destroy: () => void;
 };
 /**
  * What {@link createMenu} takes.
@@ -182,6 +190,8 @@ export type ActionMenu = {
  * @property {(entries: readonly MenuEntry[], where: MenuPlace) => void} open Fill it with `entries`
  *   and open it (closing it first if it's open).
  * @property {() => void} close Close it, if open, and return the focus.
+ * @property {() => void} destroy Take it off the page and stop listening to the window (a content
+ *   script's overlay being removed).
  */
 /**
  * Make a page's action menu: one `<dialog class="menu">` that any number of