@arraypress/extension-kit 1.9.0 → 1.10.0

package/src/dom/make.js

@@ -0,0 +1,71 @@
+/**
+ * Making a page's elements in a line: an element with its class and text, an
+ * icon from the page's SVG sprite, and Chrome's 24px icon button with its
+ * tooltip. For extension pages and content-script overlays alike (pass the
+ * document the element belongs to).
+ *
+ * @module dom/make
+ */
+
+/**
+ * An element with a class and text.
+ *
+ * @template {keyof HTMLElementTagNameMap} K
+ * @param {K} tag - Its tag.
+ * @param {string} [className] - Its class.
+ * @param {string} [text] - Its text.
+ * @param {Document} [doc] - Its document. Default `document`.
+ * @returns {HTMLElementTagNameMap[K]} It.
+ * @example
+ * make('span', 'meta', '12 colours');
+ */
+export function make(tag, className = '', text = '', doc = document) {
+  const element = doc.createElement(tag);
+  if (className) element.className = className;
+  if (text) element.textContent = text;
+  return element;
+}
+
+/**
+ * An icon from the page's SVG sprite (`<symbol id="i-copy">`), hidden from screen readers.
+ *
+ * @param {string} id - The symbol's id, without `#`.
+ * @param {string} [className] - More classes beside `icon`.
+ * @param {Document} [doc] - Its document. Default `document`.
+ * @returns {SVGSVGElement} The icon.
+ * @example
+ * button.append(spriteIcon('i-copy'));
+ */
+export function spriteIcon(id, className = '', doc = document) {
+  const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  svg.setAttribute('class', `icon ${className}`.trim());
+  svg.setAttribute('aria-hidden', 'true');
+  const use = doc.createElementNS('http://www.w3.org/2000/svg', 'use');
+  use.setAttribute('href', `#${id}`);
+  svg.append(use);
+  return svg;
+}
+
+/**
+ * Chrome's icon button (chrome-ui.css `.icon-button`): an icon, its label as tooltip and for
+ * screen readers.
+ *
+ * @param {object} options
+ * @param {string} options.icon - The sprite symbol's id.
+ * @param {string} options.label - What it does.
+ * @param {() => void} options.onClick - Doing it.
+ * @param {string} [options.className] - More classes.
+ * @param {Document} [options.doc] - Its document. Default `document`.
+ * @returns {HTMLButtonElement} The button.
+ * @example
+ * iconButton({ icon: 'i-copy', label: 'Copy', onClick: () => copy(hex) });
+ */
+export function iconButton({ icon, label, onClick, className = '', doc = document }) {
+  const button = make('button', `icon-button ${className}`.trim(), '', doc);
+  button.type = 'button';
+  button.title = label;
+  button.setAttribute('aria-label', label);
+  button.append(spriteIcon(icon, '', doc));
+  button.addEventListener('click', onClick);
+  return button;
+}

package/src/frame/window.d.ts

@@ -27,6 +27,13 @@ export declare const MAC_WINDOW: Readonly<{
 }>;
 /** The window's default width (px): the store screenshot's. */
 export declare const WINDOW_W = 1152;
+/**
+ * Text made safe for the drawn windows' HTML (and the store screenshots').
+ *
+ * @param {unknown} s - Text.
+ * @returns {string} It, escaped for HTML text and attributes.
+ */
+export declare const esc: (s: unknown) => string;
 /**
  * A letter favicon for made-up sites (no real brands).
  *

package/src/frame/window.js

@@ -26,10 +26,12 @@ export const MAC_WINDOW = Object.freeze({ titleBar: 32, radius: 16 });
 export const WINDOW_W = 1152;
 
 /**
+ * Text made safe for the drawn windows' HTML (and the store screenshots').
+ *
  * @param {unknown} s - Text.
  * @returns {string} It, escaped for HTML text and attributes.
  */
-const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 
 /** Material icon paths (24×24). */
 const P = {

package/src/index.d.ts

@@ -3,8 +3,9 @@
  * 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,
- * a content script's slices, change watcher and overlay, a module's function called in a page,
- * and a tab's side panel opened from a click. Every function takes the `chrome`
+ * 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
@@ -17,16 +18,22 @@ 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, 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 { iconButton, make, spriteIcon } from './dom/make.js';
 export { MAC_WINDOW, THEMES, WINDOW_BARS, WINDOW_W, letterIcon, macWindowSvg, windowChrome, windowChromeSvg } from './frame/window.js';
-export { localize, translator } from './dom/i18n.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';
@@ -40,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;
@@ -50,7 +58,9 @@ 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;
@@ -58,6 +68,8 @@ 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;
@@ -66,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.
@@ -79,7 +92,9 @@ 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
@@ -87,6 +102,8 @@ export type Toast = import('./ui/toast.js').Toast;
  * @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
@@ -95,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

@@ -3,8 +3,9 @@
  * 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,
- * a content script's slices, change watcher and overlay, a module's function called in a page,
- * and a tab's side panel opened from a click. Every function takes the `chrome`
+ * 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
@@ -20,16 +21,22 @@ export {
 } from './ai/model.js';
 export { setShortcuts } from './commands/shortcuts.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 { iconButton, make, spriteIcon } from './dom/make.js';
 export { MAC_WINDOW, THEMES, WINDOW_BARS, WINDOW_W, letterIcon, macWindowSvg, windowChrome, windowChromeSvg } from './frame/window.js';
-export { localize, translator } from './dom/i18n.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';
@@ -47,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';
 
 /**
@@ -61,7 +69,9 @@ 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
@@ -69,6 +79,8 @@ export { TOAST_MS, createToast } from './ui/toast.js';
  * @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
@@ -77,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/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

package/src/testing/live-run.d.ts

@@ -0,0 +1,130 @@
+/**
+ * A live checker's run: the command line read (`parseLiveOptions`), the
+ * sites chosen, where the traffic leaves for the internet printed, then each
+ * site visited in a browser with the extension loaded, a few at once (one
+ * browser a slot, launched on first use, passing for a person's), each within
+ * a time limit (a browser whose page ran out of time is replaced), Ctrl-C
+ * closing every browser. What a visit checks, and the report, are the
+ * checker's own.
+ *
+ * @module testing/live-run
+ */
+import { exitPoint } from './live.js';
+import type { BrowserType, Page } from 'playwright';
+import type { LaunchedExtension } from './e2e.js';
+import type { Exit } from './live.js';
+export type LiveSite = {
+    name: string;
+    url: string;
+    category: string;
+};
+export type LiveRun<S extends LiveSite, R> = {
+    /**
+     * The report's folder (made empty).
+     */
+    dir: string;
+    /**
+     * When it started (ISO).
+     */
+    started: string;
+    /**
+     * When it finished (ISO).
+     */
+    finished: string;
+    /**
+     * Where the traffic left.
+     */
+    exit: Exit | null;
+    /**
+     * How the browsers looked.
+     */
+    browser: {
+        locale: string;
+        timezone: string;
+        proxy: string;
+    };
+    /**
+     * Each site's visit, in the sites' order.
+     */
+    results: {
+        site: S;
+        visit: R;
+    }[];
+};
+/** @import { BrowserType, Page } from 'playwright' */
+/** @import { LaunchedExtension } from './e2e.js' */
+/** @import { Exit } from './live.js' */
+/**
+ * A site a checker visits.
+ *
+ * @typedef {{name: string, url: string, category: string}} LiveSite
+ */
+/**
+ * A finished run, for the checker's report.
+ *
+ * @template {LiveSite} S
+ * @template R
+ * @typedef {object} LiveRun
+ * @property {string} dir The report's folder (made empty).
+ * @property {string} started When it started (ISO).
+ * @property {string} finished When it finished (ISO).
+ * @property {Exit | null} exit Where the traffic left.
+ * @property {{locale: string, timezone: string, proxy: string}} browser How the browsers looked.
+ * @property {{site: S, visit: R}[]} results Each site's visit, in the sites' order.
+ */
+/**
+ * A live checker's usage text.
+ *
+ * @param {string[]} categories - The categories' ids.
+ * @param {number} concurrency - The default and most sites at once.
+ * @returns {string} The text.
+ */
+export declare const liveUsage: (categories: string[], concurrency: number) => string;
+/**
+ * Run a live check: read the command line, visit the chosen sites, give back every visit.
+ * Prints the usage and exits for `--help` (or an option it doesn't know), and exits when no
+ * site matches.
+ *
+ * @template {LiveSite} S
+ * @template R
+ * @param {object} run
+ * @param {BrowserType} run.chromium - Playwright's chromium.
+ * @param {string} run.build - The extension's live test build (every site granted).
+ * @param {string} run.prefix - The browsers' profile prefix.
+ * @param {string} run.root - The extension's repository (the report goes in `test/live/report`).
+ * @param {S[]} run.sites - Every site.
+ * @param {string[]} run.categories - The categories' ids, for the usage.
+ * @param {number} run.pageMs - The most a visit may take.
+ * @param {(browser: LaunchedExtension, page: Page, site: S) => Promise<R>} run.visit - Check one site, on a fresh page.
+ * @param {(site: S, error: string) => R} run.failed - A visit that couldn't finish (`'timed out'`).
+ * @param {(result: {site: S, visit: R}) => void} [run.onResult] - Each visit as it finishes (a line of output).
+ * @param {{argv?: string[], env?: Record<string, string | undefined>, concurrency?: number, findExit?: typeof exitPoint}} [run.command] - The
+ *   arguments and environment (default the process's), the most sites at once (default 4), and how the exit point
+ *   is found (default `exitPoint`, which asks a lookup service).
+ * @returns {Promise<LiveRun<S, R>>} The run.
+ * @example
+ * const run = await runLiveCheck({ chromium, build: BUILDS.live, prefix: 'better-colors-live-', root, sites: allSites(),
+ *   categories: CATEGORIES.map((c) => c.id), pageMs: 120_000, visit: (browser, page, site) => visit(browser, page, site.url),
+ *   failed: (site, error) => ({ url: site.url, error }), onResult: (result) => console.log(pageLine(result)) });
+ */
+export declare function runLiveCheck<S extends LiveSite, R>({ chromium, build, prefix, root, sites, categories, pageMs, visit, failed, onResult, command }: {
+    chromium: BrowserType;
+    build: string;
+    prefix: string;
+    root: string;
+    sites: S[];
+    categories: string[];
+    pageMs: number;
+    visit: (browser: LaunchedExtension, page: Page, site: S) => Promise<R>;
+    failed: (site: S, error: string) => R;
+    onResult?: (result: {
+        site: S;
+        visit: R;
+    }) => void;
+    command?: {
+        argv?: string[];
+        env?: Record<string, string | undefined>;
+        concurrency?: number;
+        findExit?: typeof exitPoint;
+    };
+}): Promise<LiveRun<S, R>>;