@arraypress/extension-kit 1.8.0 → 1.10.0

package/src/content/elements.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A page's rendered elements, for a content script that reads them all: in
+ * document order, into open shadow roots and closed ones (where Chrome lets
+ * an extension see them, `chrome.dom.openOrClosedShadowRoot`), leaving out
+ * what Chrome doesn't render and what holds no page content (scripts,
+ * styles, templates, `<head>`).
+ *
+ * @module content/elements
+ */
+/** The most elements read (a very long page's first ones). */
+export declare const MAX_ELEMENTS = 20000;
+/**
+ * An element's shadow root, closed ones too where Chrome lets the extension see them.
+ *
+ * @param {Element} element - The element.
+ * @returns {ShadowRoot | null} Its shadow root.
+ * @example
+ * const root = shadowRootOf(host); // a closed root, from a content script
+ */
+export declare function shadowRootOf(element: Element): ShadowRoot | null;
+/**
+ * Every rendered element from the body down, in document order, a shadow root's elements before
+ * its host's children. An element Chrome doesn't draw (`visibility: hidden`) is left out, but
+ * what's inside it is still read (a child can be visible again), as is what's inside a
+ * `display: contents` element (a slot), which has no box of its own; nothing inside a
+ * `display: none` or `content-visibility: hidden` part is.
+ *
+ * @param {Document} doc - The page.
+ * @param {{skip?: (element: Element) => boolean, limit?: number}} [options] - `skip`: elements left
+ *   out with what's inside (the extension's overlay); `limit`: the most elements ({@link MAX_ELEMENTS}).
+ * @returns {Element[]} The elements.
+ * @example
+ * for (const element of renderedElements(document, { skip: isLayer })) read(element);
+ */
+export declare function renderedElements(doc: Document, { skip, limit }?: {
+    skip?: (element: Element) => boolean;
+    limit?: number;
+}): Element[];
+/**
+ * The origins of a page's frames that are another site's: their content isn't the page's to read,
+ * and an extension reads them only with that site's access (`chrome.permissions.request`, from a
+ * click). Frames inside shadow roots are found too.
+ *
+ * @param {Document} doc - The page.
+ * @param {Element[]} [elements] - Its elements, when already listed ({@link renderedElements}).
+ * @returns {string[]} Their origins (`https://ads.example.net`), each once.
+ * @example
+ * otherSiteFrames(document); // ['https://www.youtube.com']
+ */
+export declare function otherSiteFrames(doc: Document, elements?: Element[]): string[];

package/src/content/elements.js

@@ -0,0 +1,88 @@
+/**
+ * A page's rendered elements, for a content script that reads them all: in
+ * document order, into open shadow roots and closed ones (where Chrome lets
+ * an extension see them, `chrome.dom.openOrClosedShadowRoot`), leaving out
+ * what Chrome doesn't render and what holds no page content (scripts,
+ * styles, templates, `<head>`).
+ *
+ * @module content/elements
+ */
+
+/** Elements that are never drawn as the page's content, nor anything inside them. */
+const NEVER_RENDERED = new Set(['script', 'style', 'noscript', 'template', 'head', 'title', 'meta', 'link']);
+
+/** The most elements read (a very long page's first ones). */
+export const MAX_ELEMENTS = 20_000;
+
+/**
+ * An element's shadow root, closed ones too where Chrome lets the extension see them.
+ *
+ * @param {Element} element - The element.
+ * @returns {ShadowRoot | null} Its shadow root.
+ * @example
+ * const root = shadowRootOf(host); // a closed root, from a content script
+ */
+export function shadowRootOf(element) {
+  const dom = /** @type {{dom?: {openOrClosedShadowRoot?: (element: HTMLElement) => ShadowRoot | null}}} */ (globalThis.chrome ?? {}).dom;
+  return (dom?.openOrClosedShadowRoot && element instanceof HTMLElement ? dom.openOrClosedShadowRoot(element) : element.shadowRoot) ?? null;
+}
+
+/**
+ * Every rendered element from the body down, in document order, a shadow root's elements before
+ * its host's children. An element Chrome doesn't draw (`visibility: hidden`) is left out, but
+ * what's inside it is still read (a child can be visible again), as is what's inside a
+ * `display: contents` element (a slot), which has no box of its own; nothing inside a
+ * `display: none` or `content-visibility: hidden` part is.
+ *
+ * @param {Document} doc - The page.
+ * @param {{skip?: (element: Element) => boolean, limit?: number}} [options] - `skip`: elements left
+ *   out with what's inside (the extension's overlay); `limit`: the most elements ({@link MAX_ELEMENTS}).
+ * @returns {Element[]} The elements.
+ * @example
+ * for (const element of renderedElements(document, { skip: isLayer })) read(element);
+ */
+export function renderedElements(doc, { skip = () => false, limit = MAX_ELEMENTS } = {}) {
+  /** @type {Element[]} */
+  const found = [];
+  /** @param {Element} element */
+  const visit = (element) => {
+    if (found.length >= limit || NEVER_RENDERED.has(element.localName) || skip(element)) return;
+    if (element.checkVisibility()) {
+      if (element.checkVisibility({ visibilityProperty: true })) found.push(element);
+    } else if (element.ownerDocument.defaultView?.getComputedStyle(element).display !== 'contents') {
+      return;
+    }
+    const shadow = shadowRootOf(element);
+    if (shadow) for (const child of shadow.children) visit(child);
+    for (const child of element.children) visit(child);
+  };
+  if (doc.body) visit(doc.body);
+  return found;
+}
+
+/**
+ * The origins of a page's frames that are another site's: their content isn't the page's to read,
+ * and an extension reads them only with that site's access (`chrome.permissions.request`, from a
+ * click). Frames inside shadow roots are found too.
+ *
+ * @param {Document} doc - The page.
+ * @param {Element[]} [elements] - Its elements, when already listed ({@link renderedElements}).
+ * @returns {string[]} Their origins (`https://ads.example.net`), each once.
+ * @example
+ * otherSiteFrames(document); // ['https://www.youtube.com']
+ */
+export function otherSiteFrames(doc, elements = renderedElements(doc)) {
+  const own = doc.location?.origin;
+  /** @type {Set<string>} */
+  const sites = new Set();
+  for (const frame of elements) {
+    if (frame.localName !== 'iframe' && frame.localName !== 'frame') continue;
+    try {
+      const url = new URL(/** @type {HTMLIFrameElement} */ (frame).src);
+      if (/^https?:$/.test(url.protocol) && url.origin !== own) sites.add(url.origin);
+    } catch {
+      // No address (srcdoc, about:blank): the page's own.
+    }
+  }
+  return [...sites];
+}

package/src/content/highlight.d.ts

@@ -0,0 +1,54 @@
+/**
+ * “Show on page”: boxes in Chrome's blue (DevTools' highlight) around a set of
+ * elements, kept on them as the page scrolls or resizes, until cleared (the
+ * extension's button again, another set, or Esc). The first can be scrolled
+ * into view. The boxes go in the extension's own overlay (`pageOverlay`), so
+ * the page's styles can't touch them.
+ *
+ * @module content/highlight
+ */
+/** The most elements boxed at once. */
+export declare const MAX_BOXES = 500;
+/** The boxes' styles, for the overlay's stylesheet. @type {string} */
+export declare const HIGHLIGHT_CSS: string;
+export type Highlighter = {
+    /**
+     * Box elements (the
+     * ones still in the page, the first {@link MAX_BOXES}), clearing any boxed before; `reveal`
+     * scrolls the first into view. Returns how many are boxed.
+     */
+    show: (elements: Element[], options?: {
+        reveal?: boolean;
+    }) => number;
+    /**
+     * Take the boxes away.
+     */
+    clear: () => void;
+};
+/**
+ * A page's highlight: one set of elements boxed at a time.
+ *
+ * @typedef {object} Highlighter
+ * @property {(elements: Element[], options?: {reveal?: boolean}) => number} show Box elements (the
+ *   ones still in the page, the first {@link MAX_BOXES}), clearing any boxed before; `reveal`
+ *   scrolls the first into view. Returns how many are boxed.
+ * @property {() => void} clear Take the boxes away.
+ */
+/**
+ * A highlighter for a page.
+ *
+ * @param {Document} doc - The page.
+ * @param {object} options
+ * @param {() => ParentNode} options.root - Where boxes go: the overlay's shadow root, made when first needed.
+ * @param {() => void} [options.onClear] - After the boxes go (take an empty overlay away).
+ * @param {number} [options.max] - The most elements boxed. Default {@link MAX_BOXES}.
+ * @returns {Highlighter} It.
+ * @example
+ * const highlight = createHighlighter(document, { root: () => layer(document), onClear: tidyLayer });
+ * highlight.show(elements, { reveal: true });
+ */
+export declare function createHighlighter(doc: Document, { root, onClear, max }: {
+    root: () => ParentNode;
+    onClear?: () => void;
+    max?: number;
+}): Highlighter;

package/src/content/highlight.js

@@ -0,0 +1,92 @@
+/**
+ * “Show on page”: boxes in Chrome's blue (DevTools' highlight) around a set of
+ * elements, kept on them as the page scrolls or resizes, until cleared (the
+ * extension's button again, another set, or Esc). The first can be scrolled
+ * into view. The boxes go in the extension's own overlay (`pageOverlay`), so
+ * the page's styles can't touch them.
+ *
+ * @module content/highlight
+ */
+
+/** The most elements boxed at once. */
+export const MAX_BOXES = 500;
+
+/** The boxes' styles, for the overlay's stylesheet. @type {string} */
+export const HIGHLIGHT_CSS = '.box { position: fixed; box-sizing: border-box; border: 2px solid rgb(26 115 232); background: rgb(26 115 232 / 0.12); border-radius: 2px; pointer-events: none; }';
+
+/**
+ * A page's highlight: one set of elements boxed at a time.
+ *
+ * @typedef {object} Highlighter
+ * @property {(elements: Element[], options?: {reveal?: boolean}) => number} show Box elements (the
+ *   ones still in the page, the first {@link MAX_BOXES}), clearing any boxed before; `reveal`
+ *   scrolls the first into view. Returns how many are boxed.
+ * @property {() => void} clear Take the boxes away.
+ */
+
+/**
+ * A highlighter for a page.
+ *
+ * @param {Document} doc - The page.
+ * @param {object} options
+ * @param {() => ParentNode} options.root - Where boxes go: the overlay's shadow root, made when first needed.
+ * @param {() => void} [options.onClear] - After the boxes go (take an empty overlay away).
+ * @param {number} [options.max] - The most elements boxed. Default {@link MAX_BOXES}.
+ * @returns {Highlighter} It.
+ * @example
+ * const highlight = createHighlighter(document, { root: () => layer(document), onClear: tidyLayer });
+ * highlight.show(elements, { reveal: true });
+ */
+export function createHighlighter(doc, { root, onClear = () => {}, max = MAX_BOXES }) {
+  const view = /** @type {Window} */ (doc.defaultView);
+  /** @type {{elements: Element[], boxes: HTMLElement[]} | null} */
+  let shown = null;
+  let pending = 0;
+
+  const draw = () => {
+    pending = 0;
+    if (!shown) return;
+    for (const box of shown.boxes) box.remove();
+    shown.boxes = shown.elements.flatMap((element) => [...element.getClientRects()].filter((rect) => rect.width && rect.height
+      && rect.bottom > 0 && rect.top < view.innerHeight && rect.right > 0 && rect.left < view.innerWidth).map((rect) => {
+      const box = doc.createElement('div');
+      box.className = 'box';
+      Object.assign(box.style, { left: `${rect.left - 2}px`, top: `${rect.top - 2}px`, width: `${rect.width + 4}px`, height: `${rect.height + 4}px` });
+      return box;
+    }));
+    root().append(...shown.boxes);
+  };
+  const update = () => {
+    if (!pending) pending = view.requestAnimationFrame(draw);
+  };
+  /** @param {KeyboardEvent} event */
+  const key = (event) => {
+    if (event.key === 'Escape') clear();
+  };
+
+  function clear() {
+    if (!shown) return;
+    view.removeEventListener('scroll', update, true);
+    view.removeEventListener('resize', update);
+    view.removeEventListener('keydown', key, true);
+    for (const box of shown.boxes) box.remove();
+    shown = null;
+    onClear();
+  }
+
+  /** @type {Highlighter['show']} */
+  function show(elements, { reveal = false } = {}) {
+    clear();
+    const some = elements.filter((element) => element.isConnected).slice(0, max);
+    if (!some.length) return 0;
+    if (reveal) some[0].scrollIntoView({ block: 'center', inline: 'nearest' });
+    shown = { elements: some, boxes: [] };
+    view.addEventListener('scroll', update, { capture: true, passive: true });
+    view.addEventListener('resize', update, { passive: true });
+    view.addEventListener('keydown', key, true);
+    draw();
+    return some.length;
+  }
+
+  return { show, clear };
+}

package/src/content/overlay.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A content script's layer over the page: a host element of its own name on
+ * the page's root element, holding a closed shadow root with the script's
+ * styles, so the page's styles and scripts can't reach in and its styles
+ * can't reach out. Pickers, toasts, bars and inspectors draw in it.
+ *
+ * @module content/overlay
+ */
+export type PageOverlay = {
+    /**
+     * The host element, on the page's root element.
+     */
+    host: HTMLElement;
+    /**
+     * Its closed shadow root, the styles first: append to it.
+     */
+    root: ShadowRoot;
+    /**
+     * Take it off the page.
+     */
+    remove: () => void;
+};
+/**
+ * A page overlay.
+ *
+ * @typedef {object} PageOverlay
+ * @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.
+ */
+/**
+ * Put an overlay on the page, replacing one of the same name a run before left.
+ *
+ * The host's own styles are reset inline (`all: initial !important`), so the page's rules for
+ * unknown elements can't move or hide it. That reset also beats a plain `:host { … }` rule in
+ * `css` and an inline `host.style.x = …`: give the host's own styles as `hostStyle`, set inline
+ * with `!important` after the reset. `css` styles what's inside (and `:host` custom properties,
+ * which the reset doesn't touch).
+ *
+ * @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`.
+ * @returns {PageOverlay} The overlay.
+ * @example
+ * const { root, remove } = pageOverlay(document, {
+ *   name: 'better-fonts-inspector',
+ *   hostStyle: { position: 'fixed', inset: '0', 'z-index': '2147483647', 'pointer-events': 'none' },
+ *   css: '.card { position: absolute; }',
+ * });
+ * root.append(card);
+ */
+export declare function pageOverlay(doc: Document, { name, css, hostStyle }: {
+    name: string;
+    css: string;
+    hostStyle?: Record<string, string>;
+}): PageOverlay;

package/src/content/overlay.js

@@ -0,0 +1,52 @@
+/**
+ * A content script's layer over the page: a host element of its own name on
+ * the page's root element, holding a closed shadow root with the script's
+ * styles, so the page's styles and scripts can't reach in and its styles
+ * can't reach out. Pickers, toasts, bars and inspectors draw in it.
+ *
+ * @module content/overlay
+ */
+
+/**
+ * A page overlay.
+ *
+ * @typedef {object} PageOverlay
+ * @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.
+ */
+
+/**
+ * Put an overlay on the page, replacing one of the same name a run before left.
+ *
+ * The host's own styles are reset inline (`all: initial !important`), so the page's rules for
+ * unknown elements can't move or hide it. That reset also beats a plain `:host { … }` rule in
+ * `css` and an inline `host.style.x = …`: give the host's own styles as `hostStyle`, set inline
+ * with `!important` after the reset. `css` styles what's inside (and `:host` custom properties,
+ * which the reset doesn't touch).
+ *
+ * @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`.
+ * @returns {PageOverlay} The overlay.
+ * @example
+ * const { root, remove } = pageOverlay(document, {
+ *   name: 'better-fonts-inspector',
+ *   hostStyle: { position: 'fixed', inset: '0', 'z-index': '2147483647', 'pointer-events': 'none' },
+ *   css: '.card { position: absolute; }',
+ * });
+ * root.append(card);
+ */
+export function pageOverlay(doc, { name, css, hostStyle = {} }) {
+  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;
+  root.append(style);
+  doc.documentElement.append(host);
+  return { host, root, remove: () => host.remove() };
+}

package/src/content/page-toast.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Chrome's own confirmation in a web page: the dark pill with a check mark that Chrome shows at
+ * the bottom of the window for “Link copied”, for a content script that just did something the
+ * person asked for from a menu or a shortcut. In a closed shadow root (the kit's `pageOverlay`)
+ * the page can't style, as a popover in the top layer, over anything the page stacks; light on
+ * a dark system. One at a time: a new one replaces the last.
+ *
+ * @module content/page-toast
+ */
+/** How long it shows, in ms (as Chrome's “Link copied”). */
+export declare const PAGE_TOAST_MS = 4000;
+/**
+ * Show Chrome's confirmation toast in a page.
+ *
+ * @param {Document} doc - The page.
+ * @param {string} text - What it says (“Link copied”).
+ * @param {{name?: string, ms?: number}} [options] - `name`: the overlay's element name (the
+ *   extension's own, with a hyphen); `ms`: how long it shows. Defaults `extension-toast`, {@link PAGE_TOAST_MS}.
+ * @returns {() => void} Takes it away now.
+ * @example
+ * showPageToast(document, chrome.i18n.getMessage('copied'), { name: 'better-copy-toast' });
+ */
+export declare function showPageToast(doc: Document, text: string, { name, ms }?: {
+    name?: string;
+    ms?: number;
+}): () => void;

package/src/content/page-toast.js

@@ -0,0 +1,72 @@
+/**
+ * Chrome's own confirmation in a web page: the dark pill with a check mark that Chrome shows at
+ * the bottom of the window for “Link copied”, for a content script that just did something the
+ * person asked for from a menu or a shortcut. In a closed shadow root (the kit's `pageOverlay`)
+ * the page can't style, as a popover in the top layer, over anything the page stacks; light on
+ * a dark system. One at a time: a new one replaces the last.
+ *
+ * @module content/page-toast
+ */
+
+import { pageOverlay } from './overlay.js';
+
+/** How long it shows, in ms (as Chrome's “Link copied”). */
+export const PAGE_TOAST_MS = 4000;
+
+/** The toast's look: Chrome's cr-toast colours, its 48px pill, the check mark. */
+const CSS = `
+  .toast { position: fixed; inset: auto auto 24px 50%; margin: 0; transform: translateX(-50%); z-index: 2147483647;
+    display: flex; align-items: center; gap: 12px; min-height: 48px; max-width: calc(100vw - 48px);
+    box-sizing: border-box; padding: 0 20px 0 16px; border: 0; border-radius: 24px; overflow: hidden;
+    background: rgb(48 48 48); color: rgb(242 242 242); box-shadow: 0 2px 4px 0 rgb(0 0 0 / 0.28);
+    font: 13px/20px system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; letter-spacing: normal; text-align: start;
+    animation: in 150ms ease-out; }
+  .toast:not(:popover-open)[popover] { display: none; }
+  .text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  svg { width: 20px; height: 20px; fill: currentColor; flex: none; }
+  @media (prefers-color-scheme: dark) { .toast { background: rgb(227 227 227); color: rgb(31 31 31); } }
+  @keyframes in { from { opacity: 0; translate: 0 8px; } }
+  @media (prefers-reduced-motion: reduce) { .toast { animation: none; } }`;
+
+/** Chrome's check mark (Material “check”). */
+const CHECK = 'M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z';
+
+/**
+ * Show Chrome's confirmation toast in a page.
+ *
+ * @param {Document} doc - The page.
+ * @param {string} text - What it says (“Link copied”).
+ * @param {{name?: string, ms?: number}} [options] - `name`: the overlay's element name (the
+ *   extension's own, with a hyphen); `ms`: how long it shows. Defaults `extension-toast`, {@link PAGE_TOAST_MS}.
+ * @returns {() => void} Takes it away now.
+ * @example
+ * showPageToast(document, chrome.i18n.getMessage('copied'), { name: 'better-copy-toast' });
+ */
+export function showPageToast(doc, text, { name = 'extension-toast', ms = PAGE_TOAST_MS } = {}) {
+  const { root, remove } = pageOverlay(doc, { name, css: CSS });
+  const toast = doc.createElement('div');
+  toast.className = 'toast';
+  toast.setAttribute('role', 'status');
+  const NS = 'http://www.w3.org/2000/svg';
+  const svg = doc.createElementNS(NS, 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('aria-hidden', 'true');
+  const path = doc.createElementNS(NS, 'path');
+  path.setAttribute('d', CHECK);
+  svg.append(path);
+  const words = doc.createElement('span');
+  words.className = 'text';
+  words.textContent = text;
+  toast.append(svg, words);
+  root.append(toast);
+  // The top layer, over the page's own fixed bars and open dialogs, where popovers exist.
+  if (typeof toast.showPopover === 'function') {
+    toast.popover = 'manual';
+    toast.showPopover();
+  }
+  const timer = setTimeout(remove, ms);
+  return () => {
+    clearTimeout(timer);
+    remove();
+  };
+}

package/src/content/slices.d.ts

@@ -48,6 +48,21 @@ export type SliceOptions = {
  * @property {() => Promise<void>} [pause] Hands the main thread back. Default: a macrotask.
  * @property {() => number} [now] The clock. Default `performance.now`.
  */
+/**
+ * Work through any list in slices: `work(item, index)` on each, the main
+ * thread handed back whenever a slice has run `sliceMs`. For a content
+ * script's work that isn't cut by blocks of the page (each element's style
+ * read, each text measured).
+ *
+ * @template T
+ * @param {Iterable<T>} items - The items.
+ * @param {(item: T, index: number) => void} work - What to do with one.
+ * @param {Pick<SliceOptions, 'sliceMs' | 'pause' | 'now'>} [options] - Slice length, how to pause, the clock.
+ * @returns {Promise<void>} Once every item is done.
+ * @example
+ * await eachInSlices(elements, (element) => styles.push(getComputedStyle(element).fontFamily));
+ */
+export declare function eachInSlices<T>(items: Iterable<T>, work: (item: T, index: number) => void, { sliceMs, pause, now }?: Pick<SliceOptions, 'sliceMs' | 'pause' | 'now'>): Promise<void>;
 /**
  * Work through a part of the page in slices: `work(block)` on each block
  * still in the page, the main thread handed back whenever a slice has run
@@ -60,4 +75,4 @@ export type SliceOptions = {
  * @example
  * await inSlices(document.body, (block) => scanner.scan(block));
  */
-export declare function inSlices(root: Node, work: (block: Node) => void, { blockChars, sliceMs, pause, now }?: SliceOptions): Promise<void>;
+export declare function inSlices(root: Node, work: (block: Node) => void, { blockChars, ...options }?: SliceOptions): Promise<void>;

package/src/content/slices.js

@@ -55,6 +55,32 @@ const nextTask = () => new Promise((resolve) => { setTimeout(resolve, 0); });
  * @property {() => number} [now] The clock. Default `performance.now`.
  */
 
+/**
+ * Work through any list in slices: `work(item, index)` on each, the main
+ * thread handed back whenever a slice has run `sliceMs`. For a content
+ * script's work that isn't cut by blocks of the page (each element's style
+ * read, each text measured).
+ *
+ * @template T
+ * @param {Iterable<T>} items - The items.
+ * @param {(item: T, index: number) => void} work - What to do with one.
+ * @param {Pick<SliceOptions, 'sliceMs' | 'pause' | 'now'>} [options] - Slice length, how to pause, the clock.
+ * @returns {Promise<void>} Once every item is done.
+ * @example
+ * await eachInSlices(elements, (element) => styles.push(getComputedStyle(element).fontFamily));
+ */
+export async function eachInSlices(items, work, { sliceMs = SLICE_MS, pause = nextTask, now = () => performance.now() } = {}) {
+  let started = now();
+  let index = 0;
+  for (const item of items) {
+    work(item, index++);
+    if (now() - started > sliceMs) {
+      await pause();
+      started = now();
+    }
+  }
+}
+
 /**
  * Work through a part of the page in slices: `work(block)` on each block
  * still in the page, the main thread handed back whenever a slice has run
@@ -67,14 +93,7 @@ const nextTask = () => new Promise((resolve) => { setTimeout(resolve, 0); });
  * @example
  * await inSlices(document.body, (block) => scanner.scan(block));
  */
-export async function inSlices(root, work, { blockChars = BLOCK_CHARS, sliceMs = SLICE_MS, pause = nextTask, now = () => performance.now() } = {}) {
-  let started = now();
-  for (const block of blocksOf(root, blockChars)) {
-    if (!block.isConnected) continue;
-    work(block);
-    if (now() - started > sliceMs) {
-      await pause();
-      started = now();
-    }
-  }
+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);
 }

package/src/dom/copy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Copying in several formats at once: plain text, and HTML for apps that paste it rich (a link
+ * with its title in Google Docs, Slack or Notion), from a page, a popup or a content script.
+ * Says whether it worked, so a caller can offer another way when the page won't let it.
+ *
+ * Chrome lets the focused page write without a click (it grants clipboard-write to the active
+ * tab), so a content script can copy from a context-menu click or a keyboard shortcut; a page
+ * served over plain HTTP has no clipboard API, and one with `Permissions-Policy:
+ * clipboard-write=()` refuses it: there the copy command is tried, which needs a click in the page.
+ *
+ * @module dom/copy
+ */
+export type ClipboardFormats = {
+    /**
+     * Plain text, for every app.
+     */
+    text: string;
+    /**
+     * HTML, for apps that paste formatted text.
+     */
+    html?: string;
+};
+/**
+ * Put text, and HTML when given, on the clipboard: the clipboard API (one item holding both
+ * formats), else the copy command.
+ *
+ * @param {Document} doc - The page, popup or content script's document.
+ * @param {ClipboardFormats} formats - Plain text, and HTML for rich pasting.
+ * @returns {Promise<boolean>} Whether it's on the clipboard.
+ * @example
+ * const link = document.createElement('a');
+ * link.href = url;
+ * link.textContent = title;
+ * if (!(await copyFormats(document, { text: `${title} – ${url}`, html: link.outerHTML }))) offerCopyButton();
+ */
+export declare function copyFormats(doc: Document, { text, html }: ClipboardFormats): Promise<boolean>;