@arraypress/extension-kit 1.9.0 → 1.11.0

package/src/content/highlight.js

@@ -0,0 +1,117 @@
+/**
+ * “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, Esc, or the page being left) and
+ * `onClear` is told which, so a panel's pressed button can follow an Esc on
+ * the page. 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 (`onClear('asked')`).
+ */
+
+/**
+ * Why the boxes went: Esc on the page, another set shown in their place, `clear()` called, or
+ * the page left (`pagehide`: a page kept for Back would come back with stale boxes).
+ *
+ * @typedef {'escape' | 'replaced' | 'asked' | 'pagehide'} ClearReason
+ */
+
+/**
+ * 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 {(reason: ClearReason) => void} [options.onClear] - After the boxes go, and why (take an empty
+ *   overlay away; tell the panel when it's `'escape'` or `'pagehide'`, which it didn't ask for).
+ * @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;
+
+  /** Put a box on each rectangle in the window, reusing the boxes there are: nothing is made or removed while scrolling. */
+  const draw = () => {
+    pending = 0;
+    if (!shown) return;
+    const rects = 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));
+    const { boxes } = shown;
+    for (const box of boxes.splice(rects.length)) box.remove();
+    /** @type {HTMLElement[]} */
+    const added = [];
+    rects.forEach((rect, index) => {
+      let box = boxes[index];
+      if (!box) {
+        box = doc.createElement('div');
+        box.className = 'box';
+        boxes.push(box);
+        added.push(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` });
+    });
+    if (added.length) root().append(...added);
+  };
+  const update = () => {
+    if (!pending) pending = view.requestAnimationFrame(draw);
+  };
+  /** @param {KeyboardEvent} event */
+  const key = (event) => {
+    if (event.key === 'Escape') end('escape');
+  };
+  const left = () => end('pagehide');
+
+  /** @param {ClearReason} reason */
+  function end(reason) {
+    if (!shown) return;
+    view.removeEventListener('scroll', update, true);
+    view.removeEventListener('resize', update);
+    view.removeEventListener('keydown', key, true);
+    view.removeEventListener('pagehide', left);
+    if (pending) view.cancelAnimationFrame(pending);
+    pending = 0;
+    for (const box of shown.boxes) box.remove();
+    shown = null;
+    onClear(reason);
+  }
+
+  /** @type {Highlighter['show']} */
+  function show(elements, { reveal = false } = {}) {
+    end('replaced');
+    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);
+    view.addEventListener('pagehide', left);
+    draw();
+    return some.length;
+  }
+
+  return { show, clear: () => end('asked') };
+
+}

package/src/content/overlay.d.ts

@@ -19,6 +19,10 @@ export type PageOverlay = {
      * Take it off the page.
      */
     remove: () => void;
+    /**
+     * With `topLayer`: put it over whatever entered the top layer since.
+     */
+    raise: () => void;
 };
 /**
  * A page overlay.
@@ -27,21 +31,42 @@ export type 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.
+ * @property {() => void} raise With `topLayer`: put it over whatever entered the top layer since.
  */
 /**
  * Put an overlay on the page, replacing one of the same name a run before left.
- * The host's own styles are reset (`all: initial`) before `css`, so the page's
- * rules for unknown elements can't move or hide it; `css` styles `:host` and what's inside.
+ *
+ * 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).
+ *
+ * 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}} options - `name`: the host's element name, with a hyphen
- *   (never registered: a plain element); `css`: the overlay's styles.
+ * @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, { name: 'better-fonts-inspector', css: ':host { position: fixed; inset: 0; pointer-events: none; }' });
+ * 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 }: {
+export declare function pageOverlay(doc: Document, { name, css, hostStyle, topLayer }: {
     name: string;
     css: string;
+    hostStyle?: Record<string, string>;
+    topLayer?: boolean;
 }): PageOverlay;

package/src/content/overlay.js

@@ -14,29 +14,77 @@
  * @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.
  */
 
 /**
  * Put an overlay on the page, replacing one of the same name a run before left.
- * The host's own styles are reset (`all: initial`) before `css`, so the page's
- * rules for unknown elements can't move or hide it; `css` styles `:host` and what's inside.
+ *
+ * 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).
+ *
+ * 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}} options - `name`: the host's element name, with a hyphen
- *   (never registered: a plain element); `css`: the overlay's styles.
+ * @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, { name: 'better-fonts-inspector', css: ':host { position: fixed; inset: 0; pointer-events: none; }' });
+ * 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 }) {
+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/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

@@ -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/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>;

package/src/dom/copy.js

@@ -0,0 +1,84 @@
+/**
+ * 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
+ */
+
+/**
+ * What to put on the clipboard.
+ *
+ * @typedef {object} ClipboardFormats
+ * @property {string} text Plain text, for every app.
+ * @property {string} [html] HTML, for apps that paste formatted text.
+ */
+
+/**
+ * The copy command, with a copy listener that writes the formats: it runs first (capture, on the
+ * window) and stops the page's own listeners from changing what's copied.
+ *
+ * @param {Document} doc - The page.
+ * @param {ClipboardFormats} formats - What to copy.
+ * @returns {boolean} Whether the command ran and wrote them.
+ */
+function copyCommand(doc, { text, html }) {
+  const view = doc.defaultView;
+  if (!view) return false;
+  let wrote = false;
+  /** @param {ClipboardEvent} event */
+  const onCopy = (event) => {
+    if (!event.clipboardData) return;
+    event.clipboardData.setData('text/plain', text);
+    if (html !== undefined) event.clipboardData.setData('text/html', html);
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    wrote = true;
+  };
+  view.addEventListener('copy', onCopy, true);
+  try {
+    return doc.execCommand('copy') && wrote;
+  } catch {
+    return false;
+  } finally {
+    view.removeEventListener('copy', onCopy, true);
+  }
+}
+
+/**
+ * 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 async function copyFormats(doc, { text, html }) {
+  const view = doc.defaultView;
+  const clipboard = view?.navigator.clipboard;
+  if (view && clipboard) {
+    try {
+      if (html === undefined) await clipboard.writeText(text);
+      else {
+        await clipboard.write([new view.ClipboardItem({
+          'text/plain': new view.Blob([text], { type: 'text/plain' }),
+          'text/html': new view.Blob([html], { type: 'text/html' }),
+        })]);
+      }
+      return true;
+    } catch {
+      // No focus, or the page's permissions policy: the copy command below.
+    }
+  }
+  return copyCommand(doc, { text, html });
+}

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.
  *