@arraypress/extension-kit 1.7.0 → 1.9.0

package/src/scripting/call.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Calling one of an extension module's functions in a page: `executeScript`
+ * runs a small function in the page's isolated world that imports the module
+ * (by its extension address, so it must be listed in `web_accessible_resources`)
+ * and calls the export named, with arguments that survive structured cloning.
+ * The module, and anything it keeps, stays loaded in that world between calls,
+ * so a content script can hold a session (a picker, an inspector) across them.
+ *
+ * @module scripting/call
+ */
+export type CallScripting = Pick<typeof chrome.scripting, 'executeScript'>;
+export type FrameResult<T> = {
+    /**
+     * The frame (0 is the top one).
+     */
+    frameId: number;
+    /**
+     * The function's result, once its promise settled.
+     */
+    result: T;
+};
+/**
+ * The parts of `chrome.scripting` a call uses.
+ *
+ * @typedef {Pick<typeof chrome.scripting, 'executeScript'>} CallScripting
+ */
+/**
+ * What one frame's call gave back.
+ *
+ * @template T
+ * @typedef {object} FrameResult
+ * @property {number} frameId The frame (0 is the top one).
+ * @property {T} result The function's result, once its promise settled.
+ */
+/**
+ * The function `executeScript` runs in the page: alone, without closures.
+ *
+ * @param {string} module - The module's path in the extension, `content/main.js`.
+ * @param {string} name - The export to call.
+ * @param {unknown[]} args - Its arguments.
+ * @returns {Promise<unknown>} What it returns.
+ */
+export declare const importAndCall: (module: string, name: string, args: unknown[]) => Promise<unknown>;
+/**
+ * Call `name` from the extension module `module` in the target's frames.
+ *
+ * @template [T=unknown]
+ * @param {CallScripting} scripting - `chrome.scripting` (or a fake in tests).
+ * @param {chrome.scripting.InjectionTarget} target - The tab, and which frames (`allFrames`, `frameIds`).
+ * @param {string} module - The module's path in the extension (listed in `web_accessible_resources`).
+ * @param {string} name - The exported function.
+ * @param {unknown[]} [args] - Its arguments (structured-cloneable).
+ * @param {{immediately?: boolean}} [options] - `immediately` (default true): don't wait for the
+ *   page to be idle, which a page still loading ads or a player may not be for a long time.
+ * @returns {Promise<FrameResult<T>[]>} Each frame's result, frames Chrome couldn't run in left out;
+ *   rejects when it can run in none (a page Chrome keeps to itself, no access).
+ * @example
+ * const [{ result }] = await callInPage(chrome.scripting, { tabId }, 'content/main.js', 'scan', [options]);
+ * await callInPage(chrome.scripting, { tabId, allFrames: true }, 'content/main.js', 'highlight', [key]);
+ */
+export declare function callInPage<T = unknown>(scripting: CallScripting, target: chrome.scripting.InjectionTarget, module: string, name: string, args?: unknown[], { immediately }?: {
+    immediately?: boolean;
+}): Promise<FrameResult<T>[]>;

package/src/scripting/call.js

@@ -0,0 +1,57 @@
+/**
+ * Calling one of an extension module's functions in a page: `executeScript`
+ * runs a small function in the page's isolated world that imports the module
+ * (by its extension address, so it must be listed in `web_accessible_resources`)
+ * and calls the export named, with arguments that survive structured cloning.
+ * The module, and anything it keeps, stays loaded in that world between calls,
+ * so a content script can hold a session (a picker, an inspector) across them.
+ *
+ * @module scripting/call
+ */
+
+/**
+ * The parts of `chrome.scripting` a call uses.
+ *
+ * @typedef {Pick<typeof chrome.scripting, 'executeScript'>} CallScripting
+ */
+
+/**
+ * What one frame's call gave back.
+ *
+ * @template T
+ * @typedef {object} FrameResult
+ * @property {number} frameId The frame (0 is the top one).
+ * @property {T} result The function's result, once its promise settled.
+ */
+
+/**
+ * The function `executeScript` runs in the page: alone, without closures.
+ *
+ * @param {string} module - The module's path in the extension, `content/main.js`.
+ * @param {string} name - The export to call.
+ * @param {unknown[]} args - Its arguments.
+ * @returns {Promise<unknown>} What it returns.
+ */
+export const importAndCall = (module, name, args) => import(chrome.runtime.getURL(module)).then((loaded) => loaded[name](...args));
+
+/**
+ * Call `name` from the extension module `module` in the target's frames.
+ *
+ * @template [T=unknown]
+ * @param {CallScripting} scripting - `chrome.scripting` (or a fake in tests).
+ * @param {chrome.scripting.InjectionTarget} target - The tab, and which frames (`allFrames`, `frameIds`).
+ * @param {string} module - The module's path in the extension (listed in `web_accessible_resources`).
+ * @param {string} name - The exported function.
+ * @param {unknown[]} [args] - Its arguments (structured-cloneable).
+ * @param {{immediately?: boolean}} [options] - `immediately` (default true): don't wait for the
+ *   page to be idle, which a page still loading ads or a player may not be for a long time.
+ * @returns {Promise<FrameResult<T>[]>} Each frame's result, frames Chrome couldn't run in left out;
+ *   rejects when it can run in none (a page Chrome keeps to itself, no access).
+ * @example
+ * const [{ result }] = await callInPage(chrome.scripting, { tabId }, 'content/main.js', 'scan', [options]);
+ * await callInPage(chrome.scripting, { tabId, allFrames: true }, 'content/main.js', 'highlight', [key]);
+ */
+export async function callInPage(scripting, target, module, name, args = [], { immediately = true } = {}) {
+  const frames = await scripting.executeScript({ target, injectImmediately: immediately, func: importAndCall, args: [module, name, args] });
+  return frames.map((frame) => ({ frameId: frame.frameId, result: /** @type {T} */ (frame.result) }));
+}

package/src/settings/saver.d.ts

@@ -41,6 +41,14 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
      * Cancel the timers (tests, or a page being torn down).
      */
     stop: () => void;
+    /**
+     *   Hear the settings change elsewhere (another tab, another computer through sync):
+     *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+     *   `chrome.storage.onChanged`.
+     */
+    follow: (onChange: (settings: S) => void, events: {
+        addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void;
+    }) => void;
 };
 /** @import { SettingsStore } from './store.js' */
 /** @import { SyncedStorage } from './storage.js' */
@@ -59,6 +67,10 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
  * @property {() => Promise<unknown>} flush Write what's queued now (call it as the page is hidden);
  *   resolves once every write so far has finished.
  * @property {() => void} stop Cancel the timers (tests, or a page being torn down).
+ * @property {(onChange: (settings: S) => void, events: {addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void}) => void} follow
+ *   Hear the settings change elsewhere (another tab, another computer through sync):
+ *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+ *   `chrome.storage.onChanged`.
  */
 /**
  * Make a debounced saver over a settings store.
@@ -72,5 +84,6 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
  * const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
  * toggle.addEventListener('change', () => saver.save({ compact: toggle.checked }));
  * addEventListener('pagehide', () => saver.flush());
+ * saver.follow((settings) => show(settings), chrome.storage.onChanged);
  */
 export declare function createSettingsSaver<S extends Record<string, unknown>>(store: SettingsStore<S>, storage: SyncedStorage, { delay, retryAfter, onSaved }?: SaverOptions<S>): SettingsSaver<S>;

package/src/settings/saver.js

@@ -27,6 +27,10 @@
  * @property {() => Promise<unknown>} flush Write what's queued now (call it as the page is hidden);
  *   resolves once every write so far has finished.
  * @property {() => void} stop Cancel the timers (tests, or a page being torn down).
+ * @property {(onChange: (settings: S) => void, events: {addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void}) => void} follow
+ *   Hear the settings change elsewhere (another tab, another computer through sync):
+ *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+ *   `chrome.storage.onChanged`.
  */
 
 /**
@@ -41,6 +45,7 @@
  * const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
  * toggle.addEventListener('change', () => saver.save({ compact: toggle.checked }));
  * addEventListener('pagehide', () => saver.flush());
+ * saver.follow((settings) => show(settings), chrome.storage.onChanged);
  */
 export function createSettingsSaver(store, storage, { delay = 1000, retryAfter = 60_000, onSaved = () => {} } = {}) {
   /** @type {Partial<S>} */
@@ -90,6 +95,12 @@ export function createSettingsSaver(store, storage, { delay = 1000, retryAfter =
       timer = setTimeout(flush, delay);
     },
     flush,
+    follow(onChange, events) {
+      events.addListener(async (changes, area) => {
+        if (!store.changed(changes, area).length) return;
+        onChange(store.normalize({ ...(await store.load(storage)), ...pending }));
+      });
+    },
     stop() {
       clearTimeout(timer);
       clearTimeout(retryTimer);

package/src/testing/heartbeat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How long a page's main thread is held, for performance checks: a heartbeat in the page. From
+ * Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/heartbeat
+ */
+import type { Page } from 'playwright';
+/** @import { Page } from 'playwright' */
+/**
+ * Start a heartbeat in a page: a timer that fires again and again, costing nothing between
+ * beats; the longest gap between two is the longest the main thread was held (the Long Tasks
+ * API misses an extension's isolated world's work, and a `MessageChannel` heartbeat counts as
+ * task time itself). Gaps while the tab is hidden (another tab in front) don't count: Chrome
+ * throttles a hidden tab's timers.
+ *
+ * @param {Page} page - The page.
+ * @returns {Promise<() => Promise<number>>} Stops it and gives the longest gap (ms).
+ * @example
+ * const stop = await heartbeat(page);
+ * await doTheWork();
+ * const held = await stop(); // e.g. 17
+ */
+export declare function heartbeat(page: Page): Promise<() => Promise<number>>;

package/src/testing/heartbeat.js

@@ -0,0 +1,43 @@
+/**
+ * How long a page's main thread is held, for performance checks: a heartbeat in the page. From
+ * Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/heartbeat
+ */
+
+/** @import { Page } from 'playwright' */
+
+/**
+ * Start a heartbeat in a page: a timer that fires again and again, costing nothing between
+ * beats; the longest gap between two is the longest the main thread was held (the Long Tasks
+ * API misses an extension's isolated world's work, and a `MessageChannel` heartbeat counts as
+ * task time itself). Gaps while the tab is hidden (another tab in front) don't count: Chrome
+ * throttles a hidden tab's timers.
+ *
+ * @param {Page} page - The page.
+ * @returns {Promise<() => Promise<number>>} Stops it and gives the longest gap (ms).
+ * @example
+ * const stop = await heartbeat(page);
+ * await doTheWork();
+ * const held = await stop(); // e.g. 17
+ */
+export async function heartbeat(page) {
+  await page.evaluate(() => {
+    const beat = { longest: 0, running: true };
+    Object.assign(window, { extensionKitBeat: beat });
+    let last = performance.now();
+    const tick = () => {
+      const now = performance.now();
+      // A hidden tab's timers are throttled by Chrome: those gaps aren't the page being held.
+      if (!document.hidden) beat.longest = Math.max(beat.longest, now - last);
+      last = now;
+      if (beat.running) setTimeout(tick, 0);
+    };
+    setTimeout(tick, 0);
+  });
+  return () => page.evaluate(() => {
+    const beat = /** @type {{longest: number, running: boolean}} */ (/** @type {any} */ (window).extensionKitBeat);
+    beat.running = false;
+    return beat.longest;
+  });
+}

package/src/testing/index.d.ts

@@ -14,6 +14,8 @@ export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
 export { fakeLanguageModel } from './fake-model.js';
 export { messageLookup, readMessages } from './messages.js';
+export { heartbeat } from './heartbeat.js';
+export { playPermissionPrompt } from './prompt.js';
 export { serve, testCertificate } from './server.js';
 export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';

package/src/testing/index.js

@@ -17,6 +17,8 @@ export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
 export { fakeLanguageModel } from './fake-model.js';
 export { messageLookup, readMessages } from './messages.js';
+export { heartbeat } from './heartbeat.js';
+export { playPermissionPrompt } from './prompt.js';
 export { serve, testCertificate } from './server.js';
 export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';

package/src/testing/prompt.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Chrome's permission prompt, played in an extension page for an e2e test: Playwright can't
+ * click Chrome's own prompt. From Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/prompt
+ */
+/**
+ * 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.
+ *
+ * @param {boolean[]} answers - The answers, in order.
+ * @example
+ * await page.evaluate(playPermissionPrompt, [true]);
+ * await page.click('#download');
+ * const asked = await page.evaluate(() => window.asked); // [{ permissions: ['downloads'], origins: undefined, gesture: true }]
+ */
+export declare function playPermissionPrompt(answers: boolean[]): void;

package/src/testing/prompt.js

@@ -0,0 +1,29 @@
+/**
+ * Chrome's permission prompt, played in an extension page for an e2e test: Playwright can't
+ * click Chrome's own prompt. From Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/prompt
+ */
+
+/**
+ * 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.
+ *
+ * @param {boolean[]} answers - The answers, in order.
+ * @example
+ * await page.evaluate(playPermissionPrompt, [true]);
+ * await page.click('#download');
+ * const asked = await page.evaluate(() => window.asked); // [{ permissions: ['downloads'], origins: undefined, gesture: true }]
+ */
+export function playPermissionPrompt(answers) {
+  /** @type {{permissions?: string[], origins?: string[], gesture: boolean}[]} */
+  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 });
+    return answers.length > 1 ? answers.shift() : answers[0];
+  }));
+}