@arraypress/extension-kit 1.11.1 → 1.12.0

package/src/net/requests.d.ts

@@ -0,0 +1,130 @@
+/**
+ * One request from a service worker that follows nothing, with what `fetch`
+ * hides of a redirect read through webRequest: for anything that must see
+ * each hop before it's made (a link's redirects shown one by one, a page
+ * fetched on a schedule that must never be sent on into the person's own
+ * network).
+ *
+ * What MV3 allows, checked in Chromium 156 (Clean Links' `test/e2e/where.mjs`,
+ * Better Alerts' `test/e2e/background.mjs`):
+ * - `fetch(url, {redirect: 'manual'})` in the worker answers a redirect with an
+ *   `opaqueredirect` response: status 0, no headers, so no `Location`, even
+ *   with host access. `redirect: 'follow'` hides the hops, and the request to
+ *   the next site is made before anyone can look at where it goes.
+ * - webRequest does see the worker's own requests (tab -1, initiator the
+ *   extension) when it has host access to them: `onHeadersReceived` gives the
+ *   status line and every header, `Location` included, even for a manual
+ *   redirect. So each hop is one manual fetch, and its redirect is read there.
+ * - `webRequest` adds no install warning, and must be a required permission:
+ *   a listener added after Chrome grants an optional webRequest at run time
+ *   gets no events until the worker restarts. It sees nothing without host
+ *   access, which can stay optional.
+ *
+ * Requests carry no cookies (`credentials: 'omit'`), no referrer, and skip the cache.
+ *
+ * @module net/requests
+ */
+/** How long to wait for webRequest's headers after the response is in (they come first). */
+export declare const HEADERS_WAIT_MS = 2000;
+/** The filter for the worker's own requests: outside any tab, as `fetch` makes them. */
+export declare const OWN_REQUESTS: chrome.webRequest.RequestFilter;
+export type SeenRequest = {
+    statusCode: number;
+    responseHeaders?: {
+        name: string;
+        value?: string;
+    }[];
+} | {
+    error: string;
+};
+export type OwnRequestEvents = {
+    /**
+     *   Response headers.
+     */
+    onHeadersReceived: {
+        addListener(listener: (details: any) => void, filter: chrome.webRequest.RequestFilter, extra?: string[]): void;
+        removeListener(listener: (details: any) => void): void;
+    };
+    /**
+     *   Failed requests.
+     */
+    onErrorOccurred: {
+        addListener(listener: (details: any) => void, filter: chrome.webRequest.RequestFilter): void;
+        removeListener(listener: (details: any) => void): void;
+    };
+};
+export type OwnAnswer = {
+    /**
+     * The HTTP status; a redirect's own (301…), read through webRequest; 0
+     * when nothing could be read.
+     */
+    status: number;
+    /**
+     * The response's headers, by lower-case
+     * name; a redirect's `location` among them.
+     */
+    headers: {
+        get(name: string): string | null;
+    };
+    /**
+     * The response, to read a body from; null for a redirect.
+     */
+    response: Response | null;
+    /**
+     * It redirected to something that isn't a web address, and where
+     * can't be read (Chrome refuses such a redirect, `net::ERR_UNSAFE_REDIRECT`, before its headers show).
+     */
+    leavesWeb: boolean;
+};
+export type OwnRequestOptions = {
+    /**
+     * `'GET'` (the default) or `'HEAD'`.
+     */
+    method?: string;
+    /**
+     * Request headers (`If-None-Match`…).
+     */
+    headers?: Record<string, string>;
+    /**
+     * Stops it.
+     */
+    signal?: AbortSignal;
+};
+export type OwnRequests = {
+    /**
+     * Start listening to webRequest for as long as requests are
+     * being made; the function it returns stops. Not at the worker's top level: the filter can't
+     * name the extension, only “outside any tab”, which is also every website's own service worker,
+     * and with access to many sites each of their requests would wake this worker to be thrown away.
+     * Work that makes requests keeps the worker awake by itself, so nothing is missed.
+     */
+    listen: () => () => void;
+    /**
+     * One request,
+     * following nothing. Rejects as `fetch` does (the network, an abort).
+     */
+    request: (url: string, options?: OwnRequestOptions) => Promise<OwnAnswer>;
+};
+/**
+ * The worker's own requests, one at a time and following nothing, a redirect's
+ * status and `Location` read through webRequest.
+ *
+ * @param {object} edges - Chrome's side.
+ * @param {OwnRequestEvents} edges.webRequest - `chrome.webRequest`.
+ * @param {string} edges.extensionId - `chrome.runtime.id`: only this extension's requests are read.
+ * @param {typeof fetch} [edges.fetch] - `fetch`. Default the global one.
+ * @param {number} [edges.headersWaitMs] - Default {@link HEADERS_WAIT_MS}.
+ * @returns {OwnRequests} `listen` and `request`.
+ * @example
+ * const own = ownRequests({ webRequest: chrome.webRequest, extensionId: chrome.runtime.id });
+ * const stop = own.listen();
+ * const { status, headers } = await own.request('https://bit.ly/abc', { method: 'HEAD' });
+ * // 301, headers.get('location') === 'https://example.com/'
+ * stop();
+ */
+export declare function ownRequests({ webRequest, extensionId, fetch: ask, headersWaitMs }: {
+    webRequest: OwnRequestEvents;
+    extensionId: string;
+    fetch?: typeof fetch;
+    headersWaitMs?: number;
+}): OwnRequests;

package/src/net/requests.js

@@ -0,0 +1,199 @@
+/**
+ * One request from a service worker that follows nothing, with what `fetch`
+ * hides of a redirect read through webRequest: for anything that must see
+ * each hop before it's made (a link's redirects shown one by one, a page
+ * fetched on a schedule that must never be sent on into the person's own
+ * network).
+ *
+ * What MV3 allows, checked in Chromium 156 (Clean Links' `test/e2e/where.mjs`,
+ * Better Alerts' `test/e2e/background.mjs`):
+ * - `fetch(url, {redirect: 'manual'})` in the worker answers a redirect with an
+ *   `opaqueredirect` response: status 0, no headers, so no `Location`, even
+ *   with host access. `redirect: 'follow'` hides the hops, and the request to
+ *   the next site is made before anyone can look at where it goes.
+ * - webRequest does see the worker's own requests (tab -1, initiator the
+ *   extension) when it has host access to them: `onHeadersReceived` gives the
+ *   status line and every header, `Location` included, even for a manual
+ *   redirect. So each hop is one manual fetch, and its redirect is read there.
+ * - `webRequest` adds no install warning, and must be a required permission:
+ *   a listener added after Chrome grants an optional webRequest at run time
+ *   gets no events until the worker restarts. It sees nothing without host
+ *   access, which can stay optional.
+ *
+ * Requests carry no cookies (`credentials: 'omit'`), no referrer, and skip the cache.
+ *
+ * @module net/requests
+ */
+
+/** How long to wait for webRequest's headers after the response is in (they come first). */
+export const HEADERS_WAIT_MS = 2000;
+
+/** The filter for the worker's own requests: outside any tab, as `fetch` makes them. */
+export const OWN_REQUESTS = /** @type {chrome.webRequest.RequestFilter} */ (Object.freeze({ urls: ['<all_urls>'], tabId: -1, types: ['xmlhttprequest'] }));
+
+/**
+ * What webRequest reports of one of the worker's requests: its response's status and headers, or
+ * the error that ended it.
+ *
+ * @typedef {{statusCode: number, responseHeaders?: {name: string, value?: string}[]} | {error: string}} SeenRequest
+ */
+
+/**
+ * The parts of `chrome.webRequest` used (fakes in tests).
+ *
+ * @typedef {object} OwnRequestEvents
+ * @property {{addListener(listener: (details: any) => void, filter: chrome.webRequest.RequestFilter, extra?: string[]): void, removeListener(listener: (details: any) => void): void}} onHeadersReceived
+ *   Response headers.
+ * @property {{addListener(listener: (details: any) => void, filter: chrome.webRequest.RequestFilter): void, removeListener(listener: (details: any) => void): void}} onErrorOccurred
+ *   Failed requests.
+ */
+
+/**
+ * One answer.
+ *
+ * @typedef {object} OwnAnswer
+ * @property {number} status The HTTP status; a redirect's own (301…), read through webRequest; 0
+ *   when nothing could be read.
+ * @property {{get(name: string): string | null}} headers The response's headers, by lower-case
+ *   name; a redirect's `location` among them.
+ * @property {Response | null} response The response, to read a body from; null for a redirect.
+ * @property {boolean} leavesWeb It redirected to something that isn't a web address, and where
+ *   can't be read (Chrome refuses such a redirect, `net::ERR_UNSAFE_REDIRECT`, before its headers show).
+ */
+
+/**
+ * What a request may set.
+ *
+ * @typedef {object} OwnRequestOptions
+ * @property {string} [method] `'GET'` (the default) or `'HEAD'`.
+ * @property {Record<string, string>} [headers] Request headers (`If-None-Match`…).
+ * @property {AbortSignal} [signal] Stops it.
+ */
+
+/**
+ * The worker's own requests.
+ *
+ * @typedef {object} OwnRequests
+ * @property {() => () => void} listen Start listening to webRequest for as long as requests are
+ *   being made; the function it returns stops. Not at the worker's top level: the filter can't
+ *   name the extension, only “outside any tab”, which is also every website's own service worker,
+ *   and with access to many sites each of their requests would wake this worker to be thrown away.
+ *   Work that makes requests keeps the worker awake by itself, so nothing is missed.
+ * @property {(url: string, options?: OwnRequestOptions) => Promise<OwnAnswer>} request One request,
+ *   following nothing. Rejects as `fetch` does (the network, an abort).
+ */
+
+/**
+ * The key a request is matched by: method and URL without its fragment (webRequest never sees one).
+ *
+ * @param {string} method - 'HEAD' or 'GET'.
+ * @param {string} url - The address.
+ * @returns {string} The key.
+ */
+const requestKey = (method, url) => `${method} ${new URL(url).href.replace(/#.*$/, '')}`;
+
+/**
+ * One header from webRequest's list (names are case-insensitive).
+ *
+ * @param {SeenRequest | undefined} seen - What webRequest saw.
+ * @param {string} name - The header's name.
+ * @returns {string | null} Its value.
+ */
+const seenHeader = (seen, name) => (seen && 'responseHeaders' in seen ? seen.responseHeaders : [])
+  ?.find((header) => header.name.toLowerCase() === name.toLowerCase())?.value ?? null;
+
+/**
+ * A wait that gives nothing.
+ *
+ * @param {number} ms - How long.
+ * @returns {Promise<undefined>} Resolves after it.
+ */
+const pause = (ms) => new Promise((resolve) => { setTimeout(() => resolve(undefined), ms); });
+
+/**
+ * The worker's own requests, one at a time and following nothing, a redirect's
+ * status and `Location` read through webRequest.
+ *
+ * @param {object} edges - Chrome's side.
+ * @param {OwnRequestEvents} edges.webRequest - `chrome.webRequest`.
+ * @param {string} edges.extensionId - `chrome.runtime.id`: only this extension's requests are read.
+ * @param {typeof fetch} [edges.fetch] - `fetch`. Default the global one.
+ * @param {number} [edges.headersWaitMs] - Default {@link HEADERS_WAIT_MS}.
+ * @returns {OwnRequests} `listen` and `request`.
+ * @example
+ * const own = ownRequests({ webRequest: chrome.webRequest, extensionId: chrome.runtime.id });
+ * const stop = own.listen();
+ * const { status, headers } = await own.request('https://bit.ly/abc', { method: 'HEAD' });
+ * // 301, headers.get('location') === 'https://example.com/'
+ * stop();
+ */
+export function ownRequests({ webRequest, extensionId, fetch: ask = fetch, headersWaitMs = HEADERS_WAIT_MS }) {
+  /** Requests waiting for webRequest's report, by {@link requestKey}. @type {Map<string, (seen: SeenRequest) => void>} */
+  const waiting = new Map();
+  let listeners = 0;
+
+  /**
+   * Whether a report is of this extension's own request.
+   *
+   * @param {{tabId: number, initiator?: string}} details - What Chrome reports.
+   * @returns {boolean} It is.
+   */
+  const own = (details) => details.tabId === -1 && details.initiator === `chrome-extension://${extensionId}`;
+  /** @param {{tabId: number, initiator?: string, method: string, url: string, statusCode: number, responseHeaders?: {name: string, value?: string}[]}} details */
+  const onHeaders = (details) => {
+    if (own(details)) waiting.get(requestKey(details.method, details.url))?.(details);
+  };
+  /** @param {{tabId: number, initiator?: string, method: string, url: string, error: string}} details */
+  const onError = (details) => {
+    if (own(details)) waiting.get(requestKey(details.method, details.url))?.({ error: details.error });
+  };
+
+  return {
+    listen() {
+      if (listeners++ === 0) {
+        webRequest.onHeadersReceived.addListener(onHeaders, OWN_REQUESTS, ['responseHeaders']);
+        webRequest.onErrorOccurred.addListener(onError, OWN_REQUESTS);
+      }
+      let stopped = false;
+      return () => {
+        if (stopped) return;
+        stopped = true;
+        if (--listeners > 0) return;
+        webRequest.onHeadersReceived.removeListener(onHeaders);
+        webRequest.onErrorOccurred.removeListener(onError);
+      };
+    },
+
+    async request(url, { method = 'GET', headers = {}, signal } = {}) {
+      const key = requestKey(method, url);
+      /** @type {Promise<SeenRequest | undefined>} */
+      const seen = new Promise((resolve) => {
+        waiting.set(key, resolve);
+        signal?.addEventListener('abort', () => resolve(undefined), { once: true });
+      });
+      try {
+        /** @type {Response} */
+        let response;
+        try {
+          response = await ask(url, { method, headers, redirect: 'manual', credentials: 'omit', cache: 'no-store', referrerPolicy: 'no-referrer', signal });
+        } catch (error) {
+          // Chrome fails even a manual fetch whose redirect leaves the web (Location: mailto:…),
+          // reporting only the error: that redirect is still an answer, though where it goes can't be read.
+          const details = await Promise.race([seen, pause(200)]);
+          if (signal?.aborted || !details || !('error' in details) || details.error !== 'net::ERR_UNSAFE_REDIRECT') throw error;
+          return { status: 0, headers: { get: () => null }, response: null, leavesWeb: true };
+        }
+        if (response.type !== 'opaqueredirect') return { status: response.status, headers: response.headers, response, leavesWeb: false };
+        const details = await Promise.race([seen, pause(headersWaitMs)]);
+        return {
+          status: details && 'statusCode' in details ? details.statusCode : 0,
+          headers: { get: (name) => seenHeader(details, name) },
+          response: null,
+          leavesWeb: false,
+        };
+      } finally {
+        waiting.delete(key);
+      }
+    },
+  };
+}

package/src/sites/sites.d.ts

@@ -4,7 +4,8 @@
  * the origin an extension asks Chrome for access to, the host a per-site
  * on/off list keeps, whether a page is on a listed site (subdomains
  * included), the match patterns for both, and a list with a site added,
- * taken out or edited. Pure.
+ * taken out or edited; and whether an address is a web page's, and whether
+ * it is on this computer or its own network rather than the internet. Pure.
  *
  * A site is a web host: http or https, with a dot in its name (or
  * `localhost`). Text without a scheme is read as https. Only a real host
@@ -117,3 +118,33 @@ export declare function withoutSite(sites: readonly string[], site: string): str
  * withSiteReplaced(['a.com', 'b.com'], 'a.com', 'b.com'); // ['b.com']
  */
 export declare function withSiteReplaced(sites: readonly string[], site: string, edited: string): string[];
+/**
+ * Whether an address is a web page (http or https), the only kind an
+ * extension can ask Chrome for access to, or fetch.
+ *
+ * @param {string} url - Any address, valid or not.
+ * @returns {boolean} True for http(s).
+ * @example
+ * isWebUrl('https://example.com/'); // true
+ * isWebUrl('mailto:a@example.com'); // false
+ */
+export declare function isWebUrl(url: string): boolean;
+/**
+ * Whether a host is this computer or on its own network rather than the internet: `localhost`
+ * and names under it, `.local`, `.lan`, `.internal` and `.home.arpa` names, a name without a dot, and the addresses
+ * kept for loopback, private networks and link-local use (IPv4 0/8, 10/8, 100.64/10, 127/8,
+ * 169.254/16, 172.16/12, 192.168/16; IPv6 `::`, `::1`, `fc00::/7`, `fe80::/10`, and IPv4 ones
+ * written as IPv6). Told from the address alone: a public name that resolves to a private
+ * address can't be seen from here.
+ *
+ * For anything that follows a link on a person's behalf (a redirect check, a link checker): a hop
+ * from a site on the internet to a local address is where to stop, since a request there can
+ * change something on a router, a printer or a development server.
+ *
+ * @param {string} url - A web address (`new URL` writes "0x7f.1" and "2130706433" as 127.0.0.1).
+ * @returns {boolean} True for a local address; false for the internet, or what isn't an address.
+ * @example
+ * isLocalUrl('http://192.168.1.1/admin'); // true
+ * isLocalUrl('https://example.com/'); // false
+ */
+export declare function isLocalUrl(url: string): boolean;

package/src/sites/sites.js

@@ -4,7 +4,8 @@
  * the origin an extension asks Chrome for access to, the host a per-site
  * on/off list keeps, whether a page is on a listed site (subdomains
  * included), the match patterns for both, and a list with a site added,
- * taken out or edited. Pure.
+ * taken out or edited; and whether an address is a web page's, and whether
+ * it is on this computer or its own network rather than the internet. Pure.
  *
  * A site is a web host: http or https, with a dot in its name (or
  * `localhost`). Text without a scheme is read as https. Only a real host
@@ -184,3 +185,65 @@ export function withoutSite(sites, site) {
 export function withSiteReplaced(sites, site, edited) {
   return [...new Set(sites.map((s) => (s === site ? edited : s)))];
 }
+
+/**
+ * Whether an address is a web page (http or https), the only kind an
+ * extension can ask Chrome for access to, or fetch.
+ *
+ * @param {string} url - Any address, valid or not.
+ * @returns {boolean} True for http(s).
+ * @example
+ * isWebUrl('https://example.com/'); // true
+ * isWebUrl('mailto:a@example.com'); // false
+ */
+export function isWebUrl(url) {
+  try {
+    return ['http:', 'https:'].includes(new URL(url).protocol);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether a host is this computer or on its own network rather than the internet: `localhost`
+ * and names under it, `.local`, `.lan`, `.internal` and `.home.arpa` names, a name without a dot, and the addresses
+ * kept for loopback, private networks and link-local use (IPv4 0/8, 10/8, 100.64/10, 127/8,
+ * 169.254/16, 172.16/12, 192.168/16; IPv6 `::`, `::1`, `fc00::/7`, `fe80::/10`, and IPv4 ones
+ * written as IPv6). Told from the address alone: a public name that resolves to a private
+ * address can't be seen from here.
+ *
+ * For anything that follows a link on a person's behalf (a redirect check, a link checker): a hop
+ * from a site on the internet to a local address is where to stop, since a request there can
+ * change something on a router, a printer or a development server.
+ *
+ * @param {string} url - A web address (`new URL` writes "0x7f.1" and "2130706433" as 127.0.0.1).
+ * @returns {boolean} True for a local address; false for the internet, or what isn't an address.
+ * @example
+ * isLocalUrl('http://192.168.1.1/admin'); // true
+ * isLocalUrl('https://example.com/'); // false
+ */
+export function isLocalUrl(url) {
+  let host;
+  try {
+    host = new URL(url).hostname.toLowerCase().replace(/\.$/, '');
+  } catch {
+    return false;
+  }
+  if (!host) return false;
+  if (host.startsWith('[')) {
+    const address = host.slice(1, -1);
+    const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(address);
+    if (mapped) {
+      const [high, low] = [parseInt(mapped[1], 16), parseInt(mapped[2], 16)];
+      return isLocalUrl(`http://${high >> 8}.${high & 255}.${low >> 8}.${low & 255}/`);
+    }
+    return address === '::' || address === '::1' || /^f[cd][0-9a-f]{2}:/.test(address) || /^fe[89ab][0-9a-f]:/.test(address);
+  }
+  const ipv4 = /^(\d+)\.(\d+)\.\d+\.\d+$/.exec(host);
+  if (ipv4) {
+    const [a, b] = [Number(ipv4[1]), Number(ipv4[2])];
+    return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254)
+      || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+  }
+  return host === 'localhost' || !host.includes('.') || /\.(?:localhost|local|internal|lan|home\.arpa)$/.test(host);
+}

package/src/toolbar/theme.d.ts

@@ -135,9 +135,11 @@ export type OffscreenApi = {
  * @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.
+ * @param {readonly string[]} [reasons] - Chrome's reasons for whatever else the document does
+ *   (`'DOM_PARSER'` for one that also reads fetched HTML), after MATCH_MEDIA. Default none.
  * @returns {Promise<boolean>} Whether it opened one (false: already open).
  */
-export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string, justification?: string): Promise<boolean>;
+export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string, justification?: string, reasons?: readonly string[]): Promise<boolean>;
 export type ToolbarWorkerApi = {
     /**
      * `chrome.storage`.
@@ -182,14 +184,16 @@ 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}).
+ * @param {{url?: string, justification?: string, reasons?: readonly string[]}} [document] - The offscreen
+ *   document, what it's for and Chrome's reasons for what else it does, when they aren't the kit's
+ *   defaults ({@link watchFromOffscreen}).
  * @returns {ToolbarTheme} The theme, for tests.
  * @example
  * // background.js
  * startToolbarTheme(chrome);
  */
-export declare function startToolbarTheme(api: ToolbarWorkerApi, { url, justification }?: {
+export declare function startToolbarTheme(api: ToolbarWorkerApi, { url, justification, reasons }?: {
     url?: string;
     justification?: string;
+    reasons?: readonly string[];
 }): ToolbarTheme;

package/src/toolbar/theme.js

@@ -131,15 +131,17 @@ const SCHEME_JUSTIFICATION = 'Reads whether Chrome is in light or dark mode, to
  * @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.
+ * @param {readonly string[]} [reasons] - Chrome's reasons for whatever else the document does
+ *   (`'DOM_PARSER'` for one that also reads fetched HTML), after MATCH_MEDIA. Default none.
  * @returns {Promise<boolean>} Whether it opened one (false: already open).
  */
-export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH, justification = SCHEME_JUSTIFICATION) {
+export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH, justification = SCHEME_JUSTIFICATION, reasons = []) {
   opening ??= (async () => {
     const open = await runtime.getContexts({ contextTypes: ['OFFSCREEN_DOCUMENT'] });
     if (open.length) return false;
     await offscreen.createDocument({
       url,
-      reasons: [offscreen.Reason.MATCH_MEDIA],
+      reasons: [offscreen.Reason.MATCH_MEDIA, ...reasons],
       justification,
     });
     return true;
@@ -165,17 +167,18 @@ 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}).
+ * @param {{url?: string, justification?: string, reasons?: readonly string[]}} [document] - The offscreen
+ *   document, what it's for and Chrome's reasons for what else it does, when they aren't the kit's
+ *   defaults ({@link watchFromOffscreen}).
  * @returns {ToolbarTheme} The theme, for tests.
  * @example
  * // background.js
  * startToolbarTheme(chrome);
  */
-export function startToolbarTheme(api, { url, justification } = {}) {
+export function startToolbarTheme(api, { url, justification, reasons } = {}) {
   const theme = createToolbarTheme({ storage: api.storage.local, action: api.action, extensionId: api.runtime.id });
   theme.restore();
-  watchFromOffscreen(api, url, justification).catch((error) => console.error('Opening the colour scheme watcher:', error));
+  watchFromOffscreen(api, url, justification, reasons).catch((error) => console.error('Opening the colour scheme watcher:', error));
   api.runtime.onMessage.addListener((message, sender) => {
     theme.onMessage(message, sender);
     return false;