@arraypress/extension-kit 1.10.0 → 1.11.0

package/src/content/overlay.js

@@ -14,6 +14,7 @@
  * @property {HTMLElement} host The host element, on the page's root element.
  * @property {ShadowRoot} root Its closed shadow root, the styles first: append to it.
  * @property {() => void} remove Take it off the page.
+ * @property {() => void} raise With `topLayer`: put it over whatever entered the top layer since.
  */
 
 /**
@@ -25,10 +26,19 @@
  * with `!important` after the reset. `css` styles what's inside (and `:host` custom properties,
  * which the reset doesn't touch).
  *
+ * With `topLayer` the host is a manual popover, shown: it draws in the top layer, over the page's
+ * modal dialogs, popovers and fullscreen element, which no `z-index` reaches. The top layer
+ * paints in the order things entered it, so the overlay goes back on top (`raise`) whenever the
+ * page opens a dialog or a popover or goes fullscreen after it. What a modal dialog makes inert
+ * stays inert, the overlay with it: it shows over the dialog, but can't be clicked while the
+ * dialog is open. The popover's own backdrop is taken away (first in the overlay's styles), so a
+ * page's `::backdrop` rule can't tint the window through it.
+ *
  * @param {Document} doc - The page.
- * @param {{name: string, css: string, hostStyle?: Record<string, string>}} options - `name`: the
- *   host's element name, with a hyphen (never registered: a plain element); `css`: the overlay's
- *   styles; `hostStyle`: the host's own styles by CSS property name (`'z-index'`), each `!important`.
+ * @param {{name: string, css: string, hostStyle?: Record<string, string>, topLayer?: boolean}} options -
+ *   `name`: the host's element name, with a hyphen (never registered: a plain element); `css`: the
+ *   overlay's styles; `hostStyle`: the host's own styles by CSS property name (`'z-index'`), each
+ *   `!important`; `topLayer`: draw over the page's dialogs and fullscreen element. Default false.
  * @returns {PageOverlay} The overlay.
  * @example
  * const { root, remove } = pageOverlay(document, {
@@ -38,15 +48,43 @@
  * });
  * root.append(card);
  */
-export function pageOverlay(doc, { name, css, hostStyle = {} }) {
+export function pageOverlay(doc, { name, css, hostStyle = {}, topLayer = false }) {
   for (const old of doc.querySelectorAll(name)) old.remove();
   const host = doc.createElement(name);
   host.style.setProperty('all', 'initial', 'important');
   for (const [property, value] of Object.entries(hostStyle)) host.style.setProperty(property, value, 'important');
   const root = host.attachShadow({ mode: 'closed' });
   const style = doc.createElement('style');
-  style.textContent = css;
+  // A shown popover has a backdrop over the whole window, which a page's bare `::backdrop { … }` rule would tint.
+  style.textContent = topLayer ? `:host::backdrop { display: none !important; }\n${css}` : css;
   root.append(style);
   doc.documentElement.append(host);
-  return { host, root, remove: () => host.remove() };
+  if (!topLayer || typeof host.showPopover !== 'function') return { host, root, remove: () => host.remove(), raise: () => {} };
+
+  host.popover = 'manual';
+  const raise = () => {
+    if (!host.isConnected) return;
+    host.hidePopover();
+    host.showPopover();
+  };
+  /** Something of the page's entered the top layer: a dialog or popover opened, or the page went fullscreen. */
+  const entered = (/** @type {Event} */ event) => {
+    if (event.target === host) return;
+    if (event.type === 'toggle' && /** @type {ToggleEvent} */ (event).newState !== 'open') return;
+    raise();
+  };
+  const view = doc.defaultView;
+  view?.addEventListener('toggle', entered, true);
+  view?.addEventListener('fullscreenchange', entered, true);
+  host.showPopover();
+  return {
+    host,
+    root,
+    raise,
+    remove() {
+      view?.removeEventListener('toggle', entered, true);
+      view?.removeEventListener('fullscreenchange', entered, true);
+      host.remove();
+    },
+  };
 }

package/src/content/slices.d.ts

@@ -14,7 +14,9 @@ export declare const BLOCK_CHARS = 4000;
 export declare const SLICE_MS = 40;
 /**
  * The blocks of a part of the page: itself if small enough, else its
- * children's blocks (its own text nodes as blocks of their own).
+ * children's blocks (its own text nodes as blocks of their own). Scripts,
+ * styles and templates inside a part that's cut are left out: their text
+ * isn't the page's.
  *
  * @param {Node} root - The part.
  * @param {number} [blockChars] - The most text a block holds. Default {@link BLOCK_CHARS}.

package/src/content/slices.js

@@ -15,9 +15,35 @@ export const BLOCK_CHARS = 4000;
 /** How long one slice may run before the page gets the main thread back (ms), by default. Shorter slices cost more layout in all. */
 export const SLICE_MS = 40;
 
+/** Elements whose text is never the page's content: not cut into, nor handed over as blocks. */
+const NOT_CONTENT = new Set(['script', 'style', 'noscript', 'template']);
+
+/**
+ * The blocks of a part of the page, one at a time as they're asked for: the cutting (each
+ * level's text measured) is spread over the slices with the work, not done whole before the
+ * first. A level's children are listed when it's reached, so what the work adds beside a block
+ * isn't handed back to it.
+ *
+ * @param {Node} node - The part.
+ * @param {number} blockChars - The most text a block holds.
+ * @returns {Generator<Node, void, void>} The blocks, in page order.
+ */
+function* cut(node, blockChars) {
+  if (node.nodeType !== 1 || (node.textContent ?? '').length <= blockChars || !node.firstChild) {
+    yield node;
+    return;
+  }
+  for (const child of [...node.childNodes]) {
+    if (child.nodeType === 1 && NOT_CONTENT.has(/** @type {Element} */ (child).localName)) continue;
+    yield* cut(child, blockChars);
+  }
+}
+
 /**
  * The blocks of a part of the page: itself if small enough, else its
- * children's blocks (its own text nodes as blocks of their own).
+ * children's blocks (its own text nodes as blocks of their own). Scripts,
+ * styles and templates inside a part that's cut are left out: their text
+ * isn't the page's.
  *
  * @param {Node} root - The part.
  * @param {number} [blockChars] - The most text a block holds. Default {@link BLOCK_CHARS}.
@@ -26,18 +52,7 @@ export const SLICE_MS = 40;
  * blocksOf(document.body).length; // 1 for a short page, one per card for a long listing
  */
 export function blocksOf(root, blockChars = BLOCK_CHARS) {
-  /** @type {Node[]} */
-  const blocks = [];
-  /** @param {Node} node */
-  const cut = (node) => {
-    if (node.nodeType !== 1 || (node.textContent ?? '').length <= blockChars || !node.firstChild) {
-      blocks.push(node);
-      return;
-    }
-    for (const child of node.childNodes) cut(child);
-  };
-  cut(root);
-  return blocks;
+  return [...cut(root, blockChars)];
 }
 
 /**
@@ -95,5 +110,5 @@ export async function eachInSlices(items, work, { sliceMs = SLICE_MS, pause = ne
  */
 export function inSlices(root, work, { blockChars = BLOCK_CHARS, ...options } = {}) {
   // A block the work before took out of the page is skipped.
-  return eachInSlices(blocksOf(root, blockChars), (block) => { if (block.isConnected) work(block); }, options);
+  return eachInSlices(cut(root, blockChars), (block) => { if (block.isConnected) work(block); }, options);
 }

package/src/content/watch.d.ts

@@ -24,7 +24,8 @@ export type WatchHandlers = {
      */
     removed?: (node: Node) => void;
     /**
-     * Whether a node added or removed is the extension's own.
+     * Whether a node is the extension's own: one added or removed, and
+     * anything that changes inside one (its text set again), is left out.
      */
     ignore?: (node: Node) => boolean;
     /**
@@ -48,7 +49,8 @@ export type WatchHandlers = {
  *   none inside another.
  * @property {(node: Node) => void} [removed] A node that left (at once, so what the extension added for it
  *   can go with it).
- * @property {(node: Node) => boolean} [ignore] Whether a node added or removed is the extension's own.
+ * @property {(node: Node) => boolean} [ignore] Whether a node is the extension's own: one added or removed, and
+ *   anything that changes inside one (its text set again), is left out.
  * @property {number} [settleMs] How long a batch waits for more. Default {@link SETTLE_MS}.
  * @property {number} [maxWaitMs] The longest a batch waits. Default {@link MAX_WAIT_MS}.
  * @property {number} [regroupChildren] An element whose children changed is handed over again whole

package/src/content/watch.js

@@ -21,7 +21,8 @@ export const MAX_WAIT_MS = 600;
  *   none inside another.
  * @property {(node: Node) => void} [removed] A node that left (at once, so what the extension added for it
  *   can go with it).
- * @property {(node: Node) => boolean} [ignore] Whether a node added or removed is the extension's own.
+ * @property {(node: Node) => boolean} [ignore] Whether a node is the extension's own: one added or removed, and
+ *   anything that changes inside one (its text set again), is left out.
  * @property {number} [settleMs] How long a batch waits for more. Default {@link SETTLE_MS}.
  * @property {number} [maxWaitMs] The longest a batch waits. Default {@link MAX_WAIT_MS}.
  * @property {number} [regroupChildren] An element whose children changed is handed over again whole
@@ -56,14 +57,27 @@ export function watchChanges(root, {
     firstAt = 0;
     const nodes = [...pending].filter((node) => node.isConnected);
     pending = new Set();
-    // Each subtree once: a node inside another changed node goes with it.
-    const tops = nodes.filter((node) => !nodes.some((other) => other !== node && other.contains(node)));
+    // Each subtree once: a node inside another changed node goes with it. Found by walking up from
+    // each (its depth), not by asking every pair: a feed adding thousands at once would stall the page.
+    const batch = new Set(nodes);
+    const tops = nodes.filter((node) => {
+      for (let above = node.parentNode; above; above = above.parentNode) if (batch.has(above)) return false;
+      return true;
+    });
     if (tops.length) changed(tops);
   };
 
+  /** Whether a node is the extension's own, or inside one that is. @param {Node | null} node */
+  const within = (node) => {
+    for (let at = node; at; at = at.parentNode) if (ignore(at)) return true;
+    return false;
+  };
+
   const observer = new MutationObserver((mutations) => {
     for (const mutation of mutations) {
       const target = mutation.target;
+      // What happens inside the extension's own elements (its note's text set again) isn't the page changing.
+      if (within(target)) continue;
       if (mutation.type === 'characterData') {
         pending.add(target);
         continue;

package/src/dom/focus.d.ts

@@ -19,6 +19,17 @@
  * focusedElement();       // → the button
  */
 export declare function focusedElement(root?: Document | ShadowRoot): Element | null;
+/**
+ * The focused element as seen from where `node` is: its shadow root's (a
+ * closed one too, which the document's `activeElement` stops at) or its
+ * document's, followed into open shadow roots below.
+ *
+ * @param {Node} node - A node in the page or in a shadow root.
+ * @returns {Element | null} The focused element, or null when nothing there has it.
+ * @example
+ * focusedIn(menu); // the menu's focused item, in a content script's closed shadow root too
+ */
+export declare function focusedIn(node: Node): Element | null;
 /**
  * The document a component is made in: `root`'s, or the page's.
  *

package/src/dom/focus.js

@@ -25,6 +25,21 @@ export function focusedElement(root = document) {
   return active;
 }
 
+/**
+ * The focused element as seen from where `node` is: its shadow root's (a
+ * closed one too, which the document's `activeElement` stops at) or its
+ * document's, followed into open shadow roots below.
+ *
+ * @param {Node} node - A node in the page or in a shadow root.
+ * @returns {Element | null} The focused element, or null when nothing there has it.
+ * @example
+ * focusedIn(menu); // the menu's focused item, in a content script's closed shadow root too
+ */
+export function focusedIn(node) {
+  const root = /** @type {Document | ShadowRoot} */ (node.getRootNode());
+  return 'activeElement' in root ? focusedElement(root) : null;
+}
+
 /**
  * The document a component is made in: `root`'s, or the page's.
  *

package/src/frame/window.d.ts

@@ -111,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

@@ -68,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
@@ -140,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.
@@ -160,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 }));
 }
 
@@ -185,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

@@ -16,6 +16,7 @@
  */
 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';
@@ -24,18 +25,20 @@ 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 { 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 { 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';
@@ -59,6 +62,8 @@ 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;
@@ -93,6 +98,8 @@ export type Toast = import('./ui/toast.js').Toast;
  * @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

package/src/index.js

@@ -19,6 +19,7 @@ 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';
@@ -27,18 +28,20 @@ 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 { 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 { 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,
@@ -70,6 +73,8 @@ export { TOAST_MS, createToast } from './ui/toast.js';
  * @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

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),
+  };
+}