@arraypress/extension-kit 1.8.0 → 1.10.0

package/src/index.d.ts

@@ -2,8 +2,10 @@
  * The kit's browser half: what an extension's pages, offscreen document,
  * service worker and content scripts load, Chrome's page components (the ⋮
  * menu, the text dialog, the toast with Undo, a settings card's site list,
- * the built-in AI row), Chrome's window drawn around a capture, per-site lists' sites, Chrome's on-device model, and
- * a content script's slices and change watcher included. Every function takes the `chrome`
+ * the built-in AI row), Chrome's window drawn around a capture, per-site lists' sites, Chrome's on-device model,
+ * a content script's slices, change watcher, overlay and “Show on page” boxes, a module's
+ * function called in a page or every frame of a tab, a tab's side panel opened from a click,
+ * copying (plain text and HTML), and making elements and icon buttons in a line. Every function takes the `chrome`
  * APIs it uses as arguments, so tests run the real logic against fakes.
  *
  * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
@@ -15,14 +17,23 @@
 export { githubAboutLinks, isPlaceholder } from './about/links.js';
 export { MODEL_MESSAGES, chromeLanguageModel, createModelSession, describeModel, downloadModel, modelAvailability, } from './ai/model.js';
 export { setShortcuts } from './commands/shortcuts.js';
-export { BLOCK_CHARS, SLICE_MS, blocksOf, inSlices } from './content/slices.js';
+export { BLOCK_CHARS, SLICE_MS, blocksOf, eachInSlices, inSlices } from './content/slices.js';
+export { MAX_ELEMENTS, otherSiteFrames, renderedElements, shadowRootOf } from './content/elements.js';
+export { HIGHLIGHT_CSS, MAX_BOXES, createHighlighter } from './content/highlight.js';
+export { pageOverlay } from './content/overlay.js';
+export { PAGE_TOAST_MS, showPageToast } from './content/page-toast.js';
 export { MAX_WAIT_MS, SETTLE_MS, watchChanges } from './content/watch.js';
+export { copyFormats } from './dom/copy.js';
 export { focusedElement } from './dom/focus.js';
-export { THEMES, WINDOW_BARS, WINDOW_W, letterIcon, windowChrome, windowChromeSvg } from './frame/window.js';
-export { localize, translator } from './dom/i18n.js';
+export { iconButton, make, spriteIcon } from './dom/make.js';
+export { MAC_WINDOW, THEMES, WINDOW_BARS, WINDOW_W, letterIcon, macWindowSvg, windowChrome, windowChromeSvg } from './frame/window.js';
+export { counted, localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
 export { setUpPage } from './dom/setup.js';
+export { openSidePanel, sidePanelPath } from './panel/side-panel.js';
+export { callInPage, importAndCall } from './scripting/call.js';
 export { contentScriptSync } from './scripting/registration.js';
+export { callInTab, isBrowserPage } from './scripting/tab.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
@@ -36,6 +47,7 @@ export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from
 export { createModelRow } from './ui/model-row.js';
 export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
 export { askFields, askText, checkText, fieldIds } from './ui/text-dialog.js';
+export { noticeCard } from './ui/notice.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
 export type Availability = import('./ai/model.js').Availability;
 export type InitialPrompt = import('./ai/model.js').InitialPrompt;
@@ -46,11 +58,18 @@ export type ModelAnswer = import('./ai/model.js').ModelAnswer;
 export type ModelSession = import('./ai/model.js').ModelSession;
 export type ModelStatus = import('./ai/model.js').ModelStatus;
 export type SliceOptions = import('./content/slices.js').SliceOptions;
+export type Highlighter = import('./content/highlight.js').Highlighter;
+export type PageOverlay = import('./content/overlay.js').PageOverlay;
+export type ClipboardFormats = import('./dom/copy.js').ClipboardFormats;
 export type WatchHandlers = import('./content/watch.js').WatchHandlers;
 export type WindowTab = import('./frame/window.js').Tab;
 export type WindowTheme = import('./frame/window.js').Theme;
+export type WindowShadow = import('./frame/window.js').WindowShadow;
 export type ModelRow = import('./ui/model-row.js').ModelRow;
 export type ContentScript = import('./scripting/registration.js').ContentScript;
+export type FrameResult = import('./scripting/call.js').FrameResult<unknown>;
+export type TabReading = import('./scripting/tab.js').TabReading<unknown>;
+export type TabEdges = import('./scripting/tab.js').TabEdges;
 export type ActionMenu = import('./ui/menu.js').ActionMenu;
 export type MenuEntry = import('./ui/menu.js').MenuEntry;
 export type MenuItem = import('./ui/menu.js').MenuItem;
@@ -59,6 +78,7 @@ export type SiteList = import('./ui/site-list.js').SiteList;
 export type FieldRequest = import('./ui/text-dialog.js').FieldRequest;
 export type FieldsRequest = import('./ui/text-dialog.js').FieldsRequest;
 export type TextRequest = import('./ui/text-dialog.js').TextRequest;
+export type Notice = import('./ui/notice.js').Notice;
 export type Toast = import('./ui/toast.js').Toast;
 /**
  * The page helpers' types, for a page's JSDoc.
@@ -72,11 +92,18 @@ export type Toast = import('./ui/toast.js').Toast;
  * @typedef {import('./ai/model.js').ModelSession} ModelSession
  * @typedef {import('./ai/model.js').ModelStatus} ModelStatus
  * @typedef {import('./content/slices.js').SliceOptions} SliceOptions
+ * @typedef {import('./content/highlight.js').Highlighter} Highlighter
+ * @typedef {import('./content/overlay.js').PageOverlay} PageOverlay
+ * @typedef {import('./dom/copy.js').ClipboardFormats} ClipboardFormats
  * @typedef {import('./content/watch.js').WatchHandlers} WatchHandlers
  * @typedef {import('./frame/window.js').Tab} WindowTab
  * @typedef {import('./frame/window.js').Theme} WindowTheme
+ * @typedef {import('./frame/window.js').WindowShadow} WindowShadow
  * @typedef {import('./ui/model-row.js').ModelRow} ModelRow
  * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
+ * @typedef {import('./scripting/call.js').FrameResult<unknown>} FrameResult
+ * @typedef {import('./scripting/tab.js').TabReading<unknown>} TabReading
+ * @typedef {import('./scripting/tab.js').TabEdges} TabEdges
  * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu
  * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry
  * @typedef {import('./ui/menu.js').MenuItem} MenuItem
@@ -85,5 +112,6 @@ export type Toast = import('./ui/toast.js').Toast;
  * @typedef {import('./ui/text-dialog.js').FieldRequest} FieldRequest
  * @typedef {import('./ui/text-dialog.js').FieldsRequest} FieldsRequest
  * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
+ * @typedef {import('./ui/notice.js').Notice} Notice
  * @typedef {import('./ui/toast.js').Toast} Toast
  */

package/src/index.js

@@ -2,8 +2,10 @@
  * The kit's browser half: what an extension's pages, offscreen document,
  * service worker and content scripts load, Chrome's page components (the ⋮
  * menu, the text dialog, the toast with Undo, a settings card's site list,
- * the built-in AI row), Chrome's window drawn around a capture, per-site lists' sites, Chrome's on-device model, and
- * a content script's slices and change watcher included. Every function takes the `chrome`
+ * the built-in AI row), Chrome's window drawn around a capture, per-site lists' sites, Chrome's on-device model,
+ * a content script's slices, change watcher, overlay and “Show on page” boxes, a module's
+ * function called in a page or every frame of a tab, a tab's side panel opened from a click,
+ * copying (plain text and HTML), and making elements and icon buttons in a line. Every function takes the `chrome`
  * APIs it uses as arguments, so tests run the real logic against fakes.
  *
  * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
@@ -18,14 +20,23 @@ export {
   MODEL_MESSAGES, chromeLanguageModel, createModelSession, describeModel, downloadModel, modelAvailability,
 } from './ai/model.js';
 export { setShortcuts } from './commands/shortcuts.js';
-export { BLOCK_CHARS, SLICE_MS, blocksOf, inSlices } from './content/slices.js';
+export { BLOCK_CHARS, SLICE_MS, blocksOf, eachInSlices, inSlices } from './content/slices.js';
+export { MAX_ELEMENTS, otherSiteFrames, renderedElements, shadowRootOf } from './content/elements.js';
+export { HIGHLIGHT_CSS, MAX_BOXES, createHighlighter } from './content/highlight.js';
+export { pageOverlay } from './content/overlay.js';
+export { PAGE_TOAST_MS, showPageToast } from './content/page-toast.js';
 export { MAX_WAIT_MS, SETTLE_MS, watchChanges } from './content/watch.js';
+export { copyFormats } from './dom/copy.js';
 export { focusedElement } from './dom/focus.js';
-export { THEMES, WINDOW_BARS, WINDOW_W, letterIcon, windowChrome, windowChromeSvg } from './frame/window.js';
-export { localize, translator } from './dom/i18n.js';
+export { iconButton, make, spriteIcon } from './dom/make.js';
+export { MAC_WINDOW, THEMES, WINDOW_BARS, WINDOW_W, letterIcon, macWindowSvg, windowChrome, windowChromeSvg } from './frame/window.js';
+export { counted, localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
 export { setUpPage } from './dom/setup.js';
+export { openSidePanel, sidePanelPath } from './panel/side-panel.js';
+export { callInPage, importAndCall } from './scripting/call.js';
 export { contentScriptSync } from './scripting/registration.js';
+export { callInTab, isBrowserPage } from './scripting/tab.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
@@ -43,6 +54,7 @@ export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from
 export { createModelRow } from './ui/model-row.js';
 export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
 export { askFields, askText, checkText, fieldIds } from './ui/text-dialog.js';
+export { noticeCard } from './ui/notice.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
 
 /**
@@ -57,11 +69,18 @@ export { TOAST_MS, createToast } from './ui/toast.js';
  * @typedef {import('./ai/model.js').ModelSession} ModelSession
  * @typedef {import('./ai/model.js').ModelStatus} ModelStatus
  * @typedef {import('./content/slices.js').SliceOptions} SliceOptions
+ * @typedef {import('./content/highlight.js').Highlighter} Highlighter
+ * @typedef {import('./content/overlay.js').PageOverlay} PageOverlay
+ * @typedef {import('./dom/copy.js').ClipboardFormats} ClipboardFormats
  * @typedef {import('./content/watch.js').WatchHandlers} WatchHandlers
  * @typedef {import('./frame/window.js').Tab} WindowTab
  * @typedef {import('./frame/window.js').Theme} WindowTheme
+ * @typedef {import('./frame/window.js').WindowShadow} WindowShadow
  * @typedef {import('./ui/model-row.js').ModelRow} ModelRow
  * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
+ * @typedef {import('./scripting/call.js').FrameResult<unknown>} FrameResult
+ * @typedef {import('./scripting/tab.js').TabReading<unknown>} TabReading
+ * @typedef {import('./scripting/tab.js').TabEdges} TabEdges
  * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu
  * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry
  * @typedef {import('./ui/menu.js').MenuItem} MenuItem
@@ -70,5 +89,6 @@ export { TOAST_MS, createToast } from './ui/toast.js';
  * @typedef {import('./ui/text-dialog.js').FieldRequest} FieldRequest
  * @typedef {import('./ui/text-dialog.js').FieldsRequest} FieldsRequest
  * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
+ * @typedef {import('./ui/notice.js').Notice} Notice
  * @typedef {import('./ui/toast.js').Toast} Toast
  */

package/src/panel/side-panel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Opening Chrome's side panel for one tab, from a click: the panel is the
+ * tab's own (no `side_panel` in the manifest, no global panel), so it shows
+ * only beside the page it's about and goes when the person switches tabs, as
+ * Chrome does for a tab's panel. Chrome opens a panel only while the click
+ * still counts, so nothing is awaited before `open`.
+ *
+ * @module panel/side-panel
+ */
+export type SidePanelApi = Pick<typeof chrome.sidePanel, 'setOptions' | 'open'>;
+/**
+ * The parts of `chrome.sidePanel` opening one uses.
+ *
+ * @typedef {Pick<typeof chrome.sidePanel, 'setOptions' | 'open'>} SidePanelApi
+ */
+/**
+ * The panel page's address for a tab: `path?tab=<id>`, so the page knows its tab.
+ *
+ * @param {string} path - The panel page, `panel/panel.html`.
+ * @param {number} tabId - The tab.
+ * @returns {string} `panel/panel.html?tab=12`.
+ */
+export declare const sidePanelPath: (path: string, tabId: number) => string;
+/**
+ * Open the side panel beside a tab, from a click (the toolbar button's, a
+ * shortcut's, or a button on an extension page).
+ *
+ * @param {SidePanelApi} sidePanel - `chrome.sidePanel` (or a fake in tests).
+ * @param {number} tabId - The tab.
+ * @param {string} path - The panel page; it gets `?tab=<id>`.
+ * @returns {Promise<void>} Once it's open; rejects when Chrome refuses (no click behind it).
+ * @example
+ * chrome.action.onClicked.addListener((tab) => openSidePanel(chrome.sidePanel, tab.id, 'panel/panel.html'));
+ */
+export declare function openSidePanel(sidePanel: SidePanelApi, tabId: number, path: string): Promise<void>;

package/src/panel/side-panel.js

@@ -0,0 +1,41 @@
+/**
+ * Opening Chrome's side panel for one tab, from a click: the panel is the
+ * tab's own (no `side_panel` in the manifest, no global panel), so it shows
+ * only beside the page it's about and goes when the person switches tabs, as
+ * Chrome does for a tab's panel. Chrome opens a panel only while the click
+ * still counts, so nothing is awaited before `open`.
+ *
+ * @module panel/side-panel
+ */
+
+/**
+ * The parts of `chrome.sidePanel` opening one uses.
+ *
+ * @typedef {Pick<typeof chrome.sidePanel, 'setOptions' | 'open'>} SidePanelApi
+ */
+
+/**
+ * The panel page's address for a tab: `path?tab=<id>`, so the page knows its tab.
+ *
+ * @param {string} path - The panel page, `panel/panel.html`.
+ * @param {number} tabId - The tab.
+ * @returns {string} `panel/panel.html?tab=12`.
+ */
+export const sidePanelPath = (path, tabId) => `${path}?tab=${tabId}`;
+
+/**
+ * Open the side panel beside a tab, from a click (the toolbar button's, a
+ * shortcut's, or a button on an extension page).
+ *
+ * @param {SidePanelApi} sidePanel - `chrome.sidePanel` (or a fake in tests).
+ * @param {number} tabId - The tab.
+ * @param {string} path - The panel page; it gets `?tab=<id>`.
+ * @returns {Promise<void>} Once it's open; rejects when Chrome refuses (no click behind it).
+ * @example
+ * chrome.action.onClicked.addListener((tab) => openSidePanel(chrome.sidePanel, tab.id, 'panel/panel.html'));
+ */
+export function openSidePanel(sidePanel, tabId, path) {
+  // Not awaited: open() must be called while the click still counts.
+  sidePanel.setOptions({ tabId, path: sidePanelPath(path, tabId), enabled: true }).catch((error) => console.error('Setting the side panel up:', error));
+  return sidePanel.open({ tabId });
+}

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/scripting/tab.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Reading a tab: one of the extension's page modules called in every frame
+ * Chrome lets it run in, the frames' answers top first; or why it can't be
+ * read: a page Chrome keeps to itself (its own pages, the Web Store, other
+ * extensions'), or no access (the tab went to another site since the click
+ * that gave activeTab).
+ *
+ * @module scripting/tab
+ */
+import type { FrameResult } from './call.js';
+/**
+ * Whether Chrome keeps a page from extensions.
+ *
+ * @param {string} url - The page's address.
+ * @returns {boolean} It does.
+ * @example
+ * isBrowserPage('chrome://settings'); // true
+ * isBrowserPage('https://chromewebstore.google.com/detail/x'); // true
+ */
+export declare const isBrowserPage: (url: string) => boolean;
+export type TabReading<T> = {
+    state: 'read';
+    frames: FrameResult<T>[];
+} | {
+    state: 'browser';
+} | {
+    state: 'no-access';
+};
+export type TabEdges = {
+    /**
+     * `chrome.tabs`.
+     */
+    tabs: Pick<typeof chrome.tabs, 'get'>;
+    /**
+     * `chrome.scripting`.
+     */
+    scripting: Pick<typeof chrome.scripting, 'executeScript'>;
+};
+/**
+ * What reading a tab gave.
+ *
+ * @template T
+ * @typedef {{state: 'read', frames: FrameResult<T>[]} | {state: 'browser'} | {state: 'no-access'}} TabReading
+ *   `frames`: each frame that answered (not null), the top one first, then in Chrome's frame order.
+ */
+/**
+ * The Chrome APIs a reading uses (fakes in unit tests).
+ *
+ * @typedef {object} TabEdges
+ * @property {Pick<typeof chrome.tabs, 'get'>} tabs `chrome.tabs`.
+ * @property {Pick<typeof chrome.scripting, 'executeScript'>} scripting `chrome.scripting`.
+ */
+/**
+ * Call a page module's export in every frame of a tab, or say why it can't be.
+ *
+ * @template [T=unknown]
+ * @param {TabEdges} edges - Chrome's tabs and scripting.
+ * @param {number} tabId - The tab.
+ * @param {string} module - The module (in `web_accessible_resources`).
+ * @param {string} name - The export.
+ * @param {unknown[]} [args] - Its arguments.
+ * @returns {Promise<TabReading<T>>} The frames' answers, or why there are none.
+ * @example
+ * const reading = await callInTab(chrome, tabId, 'content/main.js', 'scan');
+ * if (reading.state === 'read') show(reading.frames);
+ * else showMessage(reading.state); // 'browser' or 'no-access'
+ */
+export declare function callInTab<T = unknown>(edges: TabEdges, tabId: number, module: string, name: string, args?: unknown[]): Promise<TabReading<T>>;

package/src/scripting/tab.js

@@ -0,0 +1,81 @@
+/**
+ * Reading a tab: one of the extension's page modules called in every frame
+ * Chrome lets it run in, the frames' answers top first; or why it can't be
+ * read: a page Chrome keeps to itself (its own pages, the Web Store, other
+ * extensions'), or no access (the tab went to another site since the click
+ * that gave activeTab).
+ *
+ * @module scripting/tab
+ */
+
+import { callInPage } from './call.js';
+
+/** @import { FrameResult } from './call.js' */
+
+/** Addresses Chrome keeps from every extension. */
+const BROWSER_PAGE = /^(?:chrome|chrome-extension|chrome-untrusted|devtools|edge|about|view-source):|^https:\/\/(?:chromewebstore\.google\.com|chrome\.google\.com\/webstore)\//;
+
+/** Chrome's refusals for its own pages, when the page's address isn't known (no access to the tab). */
+const BROWSER_REFUSAL = /Cannot access a (?:chrome|chrome-extension|chrome-untrusted|devtools|edge):\/\/ URL|extensions gallery cannot be scripted/i;
+
+/**
+ * Whether Chrome keeps a page from extensions.
+ *
+ * @param {string} url - The page's address.
+ * @returns {boolean} It does.
+ * @example
+ * isBrowserPage('chrome://settings'); // true
+ * isBrowserPage('https://chromewebstore.google.com/detail/x'); // true
+ */
+export const isBrowserPage = (url) => BROWSER_PAGE.test(url);
+
+/**
+ * What reading a tab gave.
+ *
+ * @template T
+ * @typedef {{state: 'read', frames: FrameResult<T>[]} | {state: 'browser'} | {state: 'no-access'}} TabReading
+ *   `frames`: each frame that answered (not null), the top one first, then in Chrome's frame order.
+ */
+
+/**
+ * The Chrome APIs a reading uses (fakes in unit tests).
+ *
+ * @typedef {object} TabEdges
+ * @property {Pick<typeof chrome.tabs, 'get'>} tabs `chrome.tabs`.
+ * @property {Pick<typeof chrome.scripting, 'executeScript'>} scripting `chrome.scripting`.
+ */
+
+/**
+ * Call a page module's export in every frame of a tab, or say why it can't be.
+ *
+ * @template [T=unknown]
+ * @param {TabEdges} edges - Chrome's tabs and scripting.
+ * @param {number} tabId - The tab.
+ * @param {string} module - The module (in `web_accessible_resources`).
+ * @param {string} name - The export.
+ * @param {unknown[]} [args] - Its arguments.
+ * @returns {Promise<TabReading<T>>} The frames' answers, or why there are none.
+ * @example
+ * const reading = await callInTab(chrome, tabId, 'content/main.js', 'scan');
+ * if (reading.state === 'read') show(reading.frames);
+ * else showMessage(reading.state); // 'browser' or 'no-access'
+ */
+export async function callInTab(edges, tabId, module, name, args = []) {
+  let url;
+  try {
+    url = (await edges.tabs.get(tabId)).url;
+  } catch {
+    return { state: 'no-access' };
+  }
+  if (url && isBrowserPage(url)) return { state: 'browser' };
+  /** @type {FrameResult<T>[]} */
+  let frames;
+  try {
+    frames = await callInPage(edges.scripting, { tabId, allFrames: true }, module, name, args);
+  } catch (error) {
+    // Chrome's own page (said in its refusal), or no access: the tab went to another site since the click.
+    return { state: BROWSER_REFUSAL.test(String(/** @type {Error} */ (error)?.message)) ? 'browser' : 'no-access' };
+  }
+  const read = frames.filter((frame) => frame.result !== null && frame.result !== undefined).sort((a, b) => a.frameId - b.frameId);
+  return read.length ? { state: 'read', frames: read } : { state: 'no-access' };
+}

package/src/styles/chrome-ui.css

@@ -1063,6 +1063,13 @@ label.row, .row[actionable] { cursor: pointer; }
 .sp-item:is(:hover, :focus-within) .sp-suffix,
 .sp-suffix.always { display: flex; }
 
+/* .sp-notice (ui/notice.js): a card saying what a list leaves out or can't do; a warning's icon in
+   the error colour, an information's in the secondary text colour. */
+.sp-notice .sp-heading > .icon { flex: none; width: 18px; height: 18px; color: var(--error); }
+.sp-notice.info .sp-heading > .icon { color: var(--text-secondary); }
+.sp-notice-text { margin: 0; padding: 2px 16px 8px; color: var(--text-secondary); font-size: 12px; line-height: 16px; }
+.sp-notice-actions { display: flex; justify-content: flex-end; padding: 0 16px 8px; }
+
 /* sp-empty-state: a centred heading and a line of help. */
 .sp-empty {
     display: flex;

package/src/testing/index.d.ts

@@ -10,12 +10,14 @@ export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, until, } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { liveUsage, runLiveCheck } from './live-run.js';
 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 { callTabModule, nodeAttribute, nodeText, pierceNodes, tabIdOf } from './pages.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';
@@ -28,8 +30,10 @@ export type ExtensionProfile = import('./e2e.js').ExtensionProfile;
 export type LaunchedExtension = import('./e2e.js').LaunchedExtension;
 export type LaunchOptions = import('./e2e.js').LaunchOptions;
 export type Messages = import('./messages.js').Messages;
+export type CdpNode = import('./pages.js').CdpNode;
 export type Exit = import('./live.js').Exit;
 export type LiveOptions = import('./live.js').LiveOptions;
+export type LiveSite = import('./live-run.js').LiveSite;
 export type SavedTabGroup = import('./saved-groups.js').SavedTabGroup;
 export type Manifest = import('./warnings.js').Manifest;
 export type Reply = import('./server.js').Reply;
@@ -45,8 +49,10 @@ export type TestServer = import('./server.js').TestServer;
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
  * @typedef {import('./messages.js').Messages} Messages
+ * @typedef {import('./pages.js').CdpNode} CdpNode
  * @typedef {import('./live.js').Exit} Exit
  * @typedef {import('./live.js').LiveOptions} LiveOptions
+ * @typedef {import('./live-run.js').LiveSite} LiveSite
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/index.js

@@ -13,12 +13,14 @@ export {
   CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, until,
 } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { liveUsage, runLiveCheck } from './live-run.js';
 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 { callTabModule, nodeAttribute, nodeText, pierceNodes, tabIdOf } from './pages.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';
@@ -35,8 +37,10 @@ export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
  * @typedef {import('./messages.js').Messages} Messages
+ * @typedef {import('./pages.js').CdpNode} CdpNode
  * @typedef {import('./live.js').Exit} Exit
  * @typedef {import('./live.js').LiveOptions} LiveOptions
+ * @typedef {import('./live-run.js').LiveSite} LiveSite
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply