@arraypress/extension-kit 1.9.0 → 1.11.0

package/src/dom/i18n.d.ts

@@ -45,3 +45,20 @@ export declare function translator(i18n: Pick<I18nApi, 'getMessage'>): (key: str
  * @returns {void}
  */
 export declare function localize(root: ParentNode, i18n: I18nApi): void;
+/**
+ * A count in words, its number written as the person's language writes numbers: one message for
+ * one, another (with the number as `$1`) for any other count.
+ *
+ * @param {number} count - How many.
+ * @param {string} one - The message for one (`"1 colour"`).
+ * @param {string} many - The message for others (`"$COUNT$ colours"`, its placeholder `$1`).
+ * @param {{t: (key: string, substitutions?: string | string[]) => string, lang: string}} words - The
+ *   page's message lookup and the UI language.
+ * @returns {string} The words.
+ * @example
+ * counted(1200, 'panelColoursOne', 'panelColours', { t, lang: 'en-GB' }); // '1,200 colours'
+ */
+export declare const counted: (count: number, one: string, many: string, { t, lang }: {
+    t: (key: string, substitutions?: string | string[]) => string;
+    lang: string;
+}) => string;

package/src/dom/i18n.js

@@ -60,3 +60,18 @@ export function localize(root, i18n) {
   }
   if ('documentElement' in root) /** @type {Document} */ (root).documentElement.lang = i18n.getUILanguage();
 }
+
+/**
+ * A count in words, its number written as the person's language writes numbers: one message for
+ * one, another (with the number as `$1`) for any other count.
+ *
+ * @param {number} count - How many.
+ * @param {string} one - The message for one (`"1 colour"`).
+ * @param {string} many - The message for others (`"$COUNT$ colours"`, its placeholder `$1`).
+ * @param {{t: (key: string, substitutions?: string | string[]) => string, lang: string}} words - The
+ *   page's message lookup and the UI language.
+ * @returns {string} The words.
+ * @example
+ * counted(1200, 'panelColoursOne', 'panelColours', { t, lang: 'en-GB' }); // '1,200 colours'
+ */
+export const counted = (count, one, many, { t, lang }) => (count === 1 ? t(one) : t(many, [count.toLocaleString(lang)]));

package/src/dom/make.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 declare function make<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, text?: string, doc?: Document): HTMLElementTagNameMap[K];
+/**
+ * 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 declare function spriteIcon(id: string, className?: string, doc?: Document): SVGSVGElement;
+/**
+ * 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 declare function iconButton({ icon, label, onClick, className, doc }: {
+    icon: string;
+    label: string;
+    onClick: () => void;
+    className?: string;
+    doc?: Document;
+}): HTMLButtonElement;

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).
  *
@@ -104,7 +111,7 @@ export type Tab = {
      */
     title: string;
     /**
-     * Its favicon's URL.
+     * Its favicon's URL (escaped into the markup: an `&` in it is fine).
      */
     icon: string;
     /**

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 = {
@@ -66,7 +68,7 @@ const icon = (name, size = 20) =>
  * @returns {string} A data: URL of the SVG.
  */
 export const letterIcon = (letter, bg, fg = '#fff') =>
-  `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><rect width="16" height="16" rx="4" fill="${bg}"/><text x="8" y="12" font-family="-apple-system,Helvetica,Arial" font-size="11" font-weight="700" text-anchor="middle" fill="${fg}">${letter}</text></svg>`)}`;
+  `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><rect width="16" height="16" rx="4" fill="${esc(bg)}"/><text x="8" y="12" font-family="-apple-system,Helvetica,Arial" font-size="11" font-weight="700" text-anchor="middle" fill="${esc(fg)}">${esc(letter)}</text></svg>`)}`;
 
 /**
  * A window's shadow: soft and dropped below it, as macOS draws one (px; `blur` as CSS's and a
@@ -138,7 +140,7 @@ const trafficLights = ({ left, top, size, gap }) =>
  *
  * @typedef {object} Tab
  * @property {string} title Its title.
- * @property {string} icon Its favicon's URL.
+ * @property {string} icon Its favicon's URL (escaped into the markup: an `&` in it is fine).
  * @property {boolean} [active] The selected tab.
  * @property {boolean} [audible] Playing sound.
  * @property {boolean} [muted] Muted.
@@ -158,7 +160,7 @@ function tabLayout(tabs, w) {
   const right = 60;
   const max = 240;
   const avail = w - left - right - 36;
-  const width = Math.min(max, Math.floor(avail / tabs.length));
+  const width = Math.min(max, Math.floor(avail / Math.max(1, tabs.length)));
   return tabs.map((_, i) => ({ x: left + i * width, width }));
 }
 
@@ -183,15 +185,16 @@ export function windowChrome({ tabs, url, urlHost, theme = 'light', w = WINDOW_W
     const alert = tab.muted ? icon('muted', 16) : tab.audible ? icon('sound', 16) : '';
     const showClose = tab.active || width >= 120;
     return `<div class="tab${tab.active ? ' active' : ''}" style="left:${x}px;width:${width}px">
-      <img class="fav" src="${tab.icon}" width="16" height="16" alt=""/>
+      <img class="fav" src="${esc(tab.icon)}" width="16" height="16" alt=""/>
       <span class="title">${esc(tab.title)}</span>
       ${alert ? `<span class="alert">${alert}</span>` : ''}
       ${showClose ? `<span class="x">${icon('close', 14)}</span>` : ''}
     </div>${sepAfter ? `<span class="sep" style="left:${x + width - 1}px"></span>` : ''}`;
   }).join('');
-  const last = layout[layout.length - 1];
-  const plusX = last.x + last.width + 4;
-  const extIcons = ext.map((src) => `<img src="${src}" width="16" height="16" alt="" style="margin:0 9px"/>`).join('');
+  // After the last tab, or where the first would be in a window drawn without any.
+  const last = layout.at(-1);
+  const plusX = last ? last.x + last.width + 4 : 84;
+  const extIcons = ext.map((src) => `<img src="${esc(src)}" width="16" height="16" alt="" style="margin:0 9px"/>`).join('');
   return `
   <div class="strip">
     ${trafficLights({ left: 16, top: 15, size: 12, gap: 8 })}

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
@@ -15,20 +16,29 @@
  */
 export { githubAboutLinks, isPlaceholder } from './about/links.js';
 export { MODEL_MESSAGES, chromeLanguageModel, createModelSession, describeModel, downloadModel, modelAvailability, } from './ai/model.js';
+export { HOST_GRACE_MS, MODEL_HOST, createHostedModelSession, serveModelOffscreen } from './ai/host.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 { focusedElement } from './dom/focus.js';
+export { copyFormats } from './dom/copy.js';
+export { focusedElement, focusedIn } 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 { createShowOnPage } from './panel/show-on-page.js';
 export { openSidePanel, sidePanelPath } from './panel/side-panel.js';
-export { callInPage, importAndCall } from './scripting/call.js';
+export { CALL_FAILED, callInPage, importAndCall } from './scripting/call.js';
+export { contextMenuBuilder } from './scripting/context-menus.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 { MAX_SYNC_ITEM_BYTES, syncItemBytes } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
 export { MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite, } from './sites/sites.js';
 export { eachLimited } from './time/pool.js';
@@ -40,6 +50,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 +61,11 @@ 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 ClearReason = import('./content/highlight.js').ClearReason;
+export type ShowOnPage = import('./panel/show-on-page.js').ShowOnPage;
 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 +73,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 +83,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 +97,11 @@ 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/highlight.js').ClearReason} ClearReason
+ * @typedef {import('./panel/show-on-page.js').ShowOnPage} ShowOnPage
  * @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 +109,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 +119,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
@@ -18,20 +19,29 @@ export { githubAboutLinks, isPlaceholder } from './about/links.js';
 export {
   MODEL_MESSAGES, chromeLanguageModel, createModelSession, describeModel, downloadModel, modelAvailability,
 } from './ai/model.js';
+export { HOST_GRACE_MS, MODEL_HOST, createHostedModelSession, serveModelOffscreen } from './ai/host.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 { focusedElement } from './dom/focus.js';
+export { copyFormats } from './dom/copy.js';
+export { focusedElement, focusedIn } 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 { createShowOnPage } from './panel/show-on-page.js';
 export { openSidePanel, sidePanelPath } from './panel/side-panel.js';
-export { callInPage, importAndCall } from './scripting/call.js';
+export { CALL_FAILED, callInPage, importAndCall } from './scripting/call.js';
+export { contextMenuBuilder } from './scripting/context-menus.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 { MAX_SYNC_ITEM_BYTES, syncItemBytes } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
 export {
   MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite,
@@ -47,6 +57,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 +72,11 @@ 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/highlight.js').ClearReason} ClearReason
+ * @typedef {import('./panel/show-on-page.js').ShowOnPage} ShowOnPage
  * @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 +84,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 +94,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/show-on-page.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A side panel's “Show on page”: which of the panel's items (a font, a
+ * colour) is boxed on the page, kept true whatever ends it. A click on the
+ * item's button shows it, a second click takes it away, another item's
+ * replaces it; a rescan or the panel closing clears the page's boxes
+ * (`reset`); and when the page clears them itself (Esc there, or the page
+ * left: the highlighter's `onClear` reasons `'escape'` and `'pagehide'`,
+ * sent to the panel as a message) the panel's button is released without
+ * calling the page back (`cleared`).
+ *
+ * @module panel/show-on-page
+ */
+export type ShowOnPageSetup = {
+    /**
+     * Boxes these on
+     * the page (the panel's own call into the tab's frames), scrolling the first into view in
+     * `revealFrame`; null takes the boxes away.
+     */
+    show: (ids: string[] | null, revealFrame?: number) => Promise<unknown>;
+    /**
+     * Hears which item is shown now (press its
+     * button, release the others).
+     */
+    onChange: (shown: string | null) => void;
+};
+export type ShowOnPage = {
+    /**
+     * The item shown, or null.
+     */
+    shown: () => string | null;
+    /**
+     * Show the item
+     * `id` (the page's `ids`), or take it away if it's the one shown. Rejects when the page can't be
+     * reached, with nothing shown.
+     */
+    toggle: (id: string, ids: string[], revealFrame?: number) => Promise<void>;
+    /**
+     * A rescan started, or the panel is closing: take the page's boxes
+     * away if any are shown. The call to the page starts at once (a closing panel still gets it out)
+     * and a failure is ignored (the tab is gone).
+     */
+    reset: () => Promise<void>;
+    /**
+     * The page says its boxes went: nothing is shown, and the page isn't called.
+     */
+    cleared: () => void;
+};
+/**
+ * @typedef {object} ShowOnPageSetup
+ * @property {(ids: string[] | null, revealFrame?: number) => Promise<unknown>} show Boxes these on
+ *   the page (the panel's own call into the tab's frames), scrolling the first into view in
+ *   `revealFrame`; null takes the boxes away.
+ * @property {(shown: string | null) => void} onChange Hears which item is shown now (press its
+ *   button, release the others).
+ */
+/**
+ * @typedef {object} ShowOnPage
+ * @property {() => string | null} shown The item shown, or null.
+ * @property {(id: string, ids: string[], revealFrame?: number) => Promise<void>} toggle Show the item
+ *   `id` (the page's `ids`), or take it away if it's the one shown. Rejects when the page can't be
+ *   reached, with nothing shown.
+ * @property {() => Promise<void>} reset A rescan started, or the panel is closing: take the page's boxes
+ *   away if any are shown. The call to the page starts at once (a closing panel still gets it out)
+ *   and a failure is ignored (the tab is gone).
+ * @property {() => void} cleared The page says its boxes went: nothing is shown, and the page isn't called.
+ */
+/**
+ * A panel's “Show on page” state.
+ *
+ * @param {ShowOnPageSetup} setup - How to box items on the page, and who hears what's shown.
+ * @returns {ShowOnPage} The controller.
+ * @example
+ * const onPage = createShowOnPage({
+ *   show: (ids, frame) => callPage('highlight', [ids, frame]),
+ *   onChange: (shown) => { for (const button of buttons) button.setAttribute('aria-pressed', String(button.dataset.id === shown)); },
+ * });
+ * button.addEventListener('click', () => onPage.toggle(font.id, [font.id], font.frameId));
+ * chrome.runtime.onMessage.addListener((message) => { if (message.type === 'boxes-cleared') onPage.cleared(); });
+ * addEventListener('pagehide', () => onPage.reset());
+ * await onPage.reset(); // before a rescan
+ */
+export declare function createShowOnPage({ show, onChange }: ShowOnPageSetup): ShowOnPage;

package/src/panel/show-on-page.js

@@ -0,0 +1,83 @@
+/**
+ * A side panel's “Show on page”: which of the panel's items (a font, a
+ * colour) is boxed on the page, kept true whatever ends it. A click on the
+ * item's button shows it, a second click takes it away, another item's
+ * replaces it; a rescan or the panel closing clears the page's boxes
+ * (`reset`); and when the page clears them itself (Esc there, or the page
+ * left: the highlighter's `onClear` reasons `'escape'` and `'pagehide'`,
+ * sent to the panel as a message) the panel's button is released without
+ * calling the page back (`cleared`).
+ *
+ * @module panel/show-on-page
+ */
+
+/**
+ * @typedef {object} ShowOnPageSetup
+ * @property {(ids: string[] | null, revealFrame?: number) => Promise<unknown>} show Boxes these on
+ *   the page (the panel's own call into the tab's frames), scrolling the first into view in
+ *   `revealFrame`; null takes the boxes away.
+ * @property {(shown: string | null) => void} onChange Hears which item is shown now (press its
+ *   button, release the others).
+ */
+
+/**
+ * @typedef {object} ShowOnPage
+ * @property {() => string | null} shown The item shown, or null.
+ * @property {(id: string, ids: string[], revealFrame?: number) => Promise<void>} toggle Show the item
+ *   `id` (the page's `ids`), or take it away if it's the one shown. Rejects when the page can't be
+ *   reached, with nothing shown.
+ * @property {() => Promise<void>} reset A rescan started, or the panel is closing: take the page's boxes
+ *   away if any are shown. The call to the page starts at once (a closing panel still gets it out)
+ *   and a failure is ignored (the tab is gone).
+ * @property {() => void} cleared The page says its boxes went: nothing is shown, and the page isn't called.
+ */
+
+/**
+ * A panel's “Show on page” state.
+ *
+ * @param {ShowOnPageSetup} setup - How to box items on the page, and who hears what's shown.
+ * @returns {ShowOnPage} The controller.
+ * @example
+ * const onPage = createShowOnPage({
+ *   show: (ids, frame) => callPage('highlight', [ids, frame]),
+ *   onChange: (shown) => { for (const button of buttons) button.setAttribute('aria-pressed', String(button.dataset.id === shown)); },
+ * });
+ * button.addEventListener('click', () => onPage.toggle(font.id, [font.id], font.frameId));
+ * chrome.runtime.onMessage.addListener((message) => { if (message.type === 'boxes-cleared') onPage.cleared(); });
+ * addEventListener('pagehide', () => onPage.reset());
+ * await onPage.reset(); // before a rescan
+ */
+export function createShowOnPage({ show, onChange }) {
+  /** @type {string | null} */
+  let shown = null;
+  /** @param {string | null} id */
+  const set = (id) => {
+    if (shown === id) return;
+    shown = id;
+    onChange(id);
+  };
+
+  return {
+    shown: () => shown,
+    async toggle(id, ids, revealFrame) {
+      if (shown === id) {
+        set(null);
+        await show(null);
+        return;
+      }
+      set(id);
+      try {
+        await show(ids, revealFrame);
+      } catch (error) {
+        if (shown === id) set(null);
+        throw error;
+      }
+    },
+    async reset() {
+      if (shown === null) return;
+      set(null);
+      await show(null).catch(() => {});
+    },
+    cleared: () => set(null),
+  };
+}