@arraypress/extension-kit 1.10.0 → 1.11.0

package/src/ai/model.d.ts

@@ -9,7 +9,8 @@
  *   only downloads from a user gesture) and which reports progress;
  * - one base session, with the instructions and examples, is made once and
  *   kept; each question goes to a `clone()` of it, so answers don't leak into
- *   each other;
+ *   each other; a base session Chrome has let go since (it can't be cloned)
+ *   is made again;
  * - each answer has a time limit: an `AbortSignal` stops the answer once
  *   it's late, and the caller gets a reason instead of a hang;
  * - the first session after Chrome starts can take ~18 s while the model

package/src/ai/model.js

@@ -9,7 +9,8 @@
  *   only downloads from a user gesture) and which reports progress;
  * - one base session, with the instructions and examples, is made once and
  *   kept; each question goes to a `clone()` of it, so answers don't leak into
- *   each other;
+ *   each other; a base session Chrome has let go since (it can't be cloned)
+ *   is made again;
  * - each answer has a time limit: an `AbortSignal` stops the answer once
  *   it's late, and the caller gets a reason instead of a hang;
  * - the first session after Chrome starts can take ~18 s while the model
@@ -265,7 +266,14 @@ export function createModelSession({ model, options, initialPrompts = [] }) {
    * @returns {Promise<string>} The answer.
    */
   async function ask(api, prompt, signal, responseConstraint) {
-    const session = await (await baseSession(api)).clone({ signal });
+    const made = baseSession(api);
+    const kept = await made;
+    const session = await kept.clone({ signal }).catch(async (error) => {
+      if (signal.aborted) throw error;
+      // Chrome let the base session go (the model was updated, or its process ended): a new one, once.
+      if (base === made) base = null;
+      return (await baseSession(api)).clone({ signal });
+    });
     try {
       return await session.prompt(prompt, { signal, ...(responseConstraint && { responseConstraint }) });
     } finally {

package/src/build/vendor.d.ts

@@ -5,11 +5,13 @@
  * `extension/vendor/`; the copy is made from the installed package on
  * `npm install` (`postinstall`) and is never committed.
  *
- * Each copy is stamped with the package's name and version
- * ({@link VENDOR_STAMP}), so {@link checkVendored} can say when a copy no
- * longer matches what's installed: `npm install some-package` installs
- * without running the extension's own `postinstall`, and the copy goes stale
- * without a word.
+ * Each copy is stamped with the package's name and version, what was copied
+ * and a hash of it ({@link VENDOR_STAMP}), so {@link checkVendored} can say
+ * when a copy no longer matches what's installed: `npm install some-package`
+ * installs without running the extension's own `postinstall`, and the copy
+ * goes stale without a word; so does a copy edited by hand, or a package
+ * whose files changed under the same version (a library copied into
+ * `node_modules` to try it before it's published).
  *
  * An extension with a bundler imports the package instead and copies only
  * the stylesheet ({@link STYLESHEET}).
@@ -31,6 +33,14 @@ export type VendorStamp = {
      * Its version when copied.
      */
     version: string;
+    /**
+     * The paths copied, as {@link vendorPackage} took them (the kit's own copy has none).
+     */
+    files?: string[];
+    /**
+     * A hash of every file copied ({@link treeHash}); a copy from before 1.11 has none.
+     */
+    hash?: string;
 };
 /**
  * Where a vendored copy came from.
@@ -38,6 +48,8 @@ export type VendorStamp = {
  * @typedef {object} VendorStamp
  * @property {string} package The package's name.
  * @property {string} version Its version when copied.
+ * @property {string[]} [files] The paths copied, as {@link vendorPackage} took them (the kit's own copy has none).
+ * @property {string} [hash] A hash of every file copied ({@link treeHash}); a copy from before 1.11 has none.
  */
 /**
  * The folder of an installed package, found as Node finds it (the nearest
@@ -55,6 +67,8 @@ export declare function packageDir(name: string, from?: string): Promise<string>
  *
  * @param {string} dest - The folder to fill, e.g. `extension/vendor/extension-kit`. Removed first.
  * @returns {Promise<string[]>} The entries copied, relative to `dest`.
+ * @throws {Error} When `dest` holds an extension or a project (`manifest.json`, `package.json`, `.git`).
+ *
  * @example
  * await vendorKit('extension/vendor/extension-kit');
  * // extension/vendor/extension-kit/index.js, …/styles/chrome-ui.css, …, vendored.json
@@ -71,7 +85,9 @@ export declare function vendorKit(dest: string): Promise<string[]>;
  * @param {string} dest - The folder to fill, e.g. `extension/vendor/clean-link`. Removed first.
  * @param {{from?: string}} [options] - `from`: where to look for `node_modules` from. Default the current folder.
  * @returns {Promise<string[]>} The files and folders written, relative to `dest`.
- * @throws {Error} When the package isn't installed, or a path isn't in it.
+ * @throws {Error} When the package isn't installed, a path isn't in it, two paths would land in
+ *   the same place (`dist/index.js` and `rules/index.js`), or `dest` holds an extension or a project.
+ *
  * @example
  * await vendorPackage('@duckduckgo/autoconsent', ['dist/autoconsent.esm.js', 'rules/compact-rules.json', 'LICENSE'], 'extension/vendor/autoconsent');
  * // or, from postinstall: extension-kit vendor extension/vendor/clean-link @arraypress/clean-link src/
@@ -82,11 +98,16 @@ export declare function vendorPackage(name: string, files: readonly string[], de
 /**
  * Every vendored copy under `dir` (a folder with a {@link VENDOR_STAMP},
  * searched to any depth) that no longer matches the package installed now:
- * copied from another version, or from a package that's gone.
+ * copied from another version, from a package that's gone, edited since (a
+ * file a script wrote beside the copied ones afterwards doesn't count), or
+ * from files the installed package no longer has as they were. A folder with
+ * no vendored copy at all (a mistyped path, `postinstall` never run) is
+ * reported too.
  *
  * @param {string} dir - The vendor folder, e.g. `extension/vendor`.
  * @param {{from?: string}} [options] - `from`: where to look for `node_modules` from. Default the current folder.
- * @returns {Promise<string[]>} One line per stale copy; empty when all match (or there are none).
+ * @returns {Promise<string[]>} One line per stale copy; empty when all match.
+ *
  * @example
  * const stale = await checkVendored('extension/vendor');
  * // ['extension/vendor/extension-kit is @arraypress/extension-kit 1.2.0; 1.3.0 is installed']

package/src/build/vendor.js

@@ -5,11 +5,13 @@
  * `extension/vendor/`; the copy is made from the installed package on
  * `npm install` (`postinstall`) and is never committed.
  *
- * Each copy is stamped with the package's name and version
- * ({@link VENDOR_STAMP}), so {@link checkVendored} can say when a copy no
- * longer matches what's installed: `npm install some-package` installs
- * without running the extension's own `postinstall`, and the copy goes stale
- * without a word.
+ * Each copy is stamped with the package's name and version, what was copied
+ * and a hash of it ({@link VENDOR_STAMP}), so {@link checkVendored} can say
+ * when a copy no longer matches what's installed: `npm install some-package`
+ * installs without running the extension's own `postinstall`, and the copy
+ * goes stale without a word; so does a copy edited by hand, or a package
+ * whose files changed under the same version (a library copied into
+ * `node_modules` to try it before it's published).
  *
  * An extension with a bundler imports the package instead and copies only
  * the stylesheet ({@link STYLESHEET}).
@@ -17,7 +19,8 @@
  * @module build/vendor
  */
 
-import { access, cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { access, copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 
@@ -42,6 +45,8 @@ export const VENDOR_STAMP = 'vendored.json';
  * @typedef {object} VendorStamp
  * @property {string} package The package's name.
  * @property {string} version Its version when copied.
+ * @property {string[]} [files] The paths copied, as {@link vendorPackage} took them (the kit's own copy has none).
+ * @property {string} [hash] A hash of every file copied ({@link treeHash}); a copy from before 1.11 has none.
  */
 
 /**
@@ -73,14 +78,90 @@ async function versionOf(dir) {
 }
 
 /**
- * Write a folder's {@link VENDOR_STAMP}.
+ * Every file under a file or folder.
  *
- * @param {string} dest - The vendored folder.
- * @param {VendorStamp} source - Where the copy came from.
+ * @param {string} source - A file or a folder.
+ * @returns {Promise<string[]>} Paths from `source`, forward slashes ('' for a file itself).
+ */
+async function filesOf(source) {
+  if (!(await stat(source)).isDirectory()) return [''];
+  const entries = await readdir(source, { recursive: true, withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => path.relative(source, path.join(entry.parentPath, entry.name)).split(path.sep).join('/'));
+}
+
+/**
+ * What a copy holds: each file's place in the vendored folder and the file it comes from. A
+ * path lands under its own name (`dist/lib.esm.js` → `lib.esm.js`); a path ending in `/` has its
+ * contents copied instead (`src/` → `index.js`, …).
+ *
+ * @param {string} dir - The folder the paths are in (a package's, or the kit's `src/`).
+ * @param {readonly string[]} files - The paths.
+ * @returns {Promise<Map<string, string>>} Place in the copy (forward slashes) → source file.
+ * @throws {Error} When a path isn't there, or two files would land in the same place.
+ */
+async function copyPlan(dir, files) {
+  /** @type {Map<string, string>} */
+  const plan = new Map();
+  for (const file of files) {
+    const source = path.join(dir, file);
+    const under = file.endsWith('/') ? '' : path.basename(file);
+    for (const inner of await filesOf(source)) {
+      const place = [under, inner].filter(Boolean).join('/');
+      const taken = plan.get(place);
+      if (taken) throw new Error(`${path.relative(dir, taken)} and ${path.relative(dir, path.join(source, inner))} would both be copied to ${place}`);
+      plan.set(place, path.join(source, inner));
+    }
+  }
+  return plan;
+}
+
+/**
+ * A hash of a set of files: their places and contents, in order of place.
+ *
+ * @param {Iterable<[string, string]>} files - Place (forward slashes) → the file to read.
+ * @returns {Promise<string>} SHA-256, hex.
+ */
+async function treeHash(files) {
+  const hash = createHash('sha256');
+  for (const [place, file] of [...files].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    hash.update(`${place}\0`).update(await readFile(file)).update('\0');
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * Whether a folder is somewhere a copy mustn't go: it would be deleted first, and it holds an
+ * extension or a project (`manifest.json`, `package.json`, a `.git`) rather than an older copy.
+ *
+ * @param {string} dest - The folder to fill.
+ * @returns {Promise<void>}
+ * @throws {Error} When it does.
+ */
+async function refuseSource(dest) {
+  for (const sign of ['manifest.json', 'package.json', '.git']) {
+    if (await access(path.join(dest, sign)).then(() => true, () => false)) {
+      throw new Error(`${dest} holds a ${sign}: it isn't a vendor folder, and copying into it would delete it first`);
+    }
+  }
+}
+
+/**
+ * Replace `dest` with the files of a plan, stamped.
+ *
+ * @param {string} dest - The vendored folder. Removed first.
+ * @param {Map<string, string>} plan - From {@link copyPlan}.
+ * @param {Omit<VendorStamp, 'hash'>} source - Where the copy comes from.
  * @returns {Promise<void>}
  */
-async function stamp(dest, source) {
-  await writeFile(path.join(dest, VENDOR_STAMP), `${JSON.stringify(source, null, 2)}\n`);
+async function copyStamped(dest, plan, source) {
+  await refuseSource(dest);
+  await rm(dest, { recursive: true, force: true });
+  await mkdir(dest, { recursive: true });
+  for (const [place, file] of plan) {
+    await mkdir(path.dirname(path.join(dest, place)), { recursive: true });
+    await copyFile(file, path.join(dest, place));
+  }
+  await writeFile(path.join(dest, VENDOR_STAMP), `${JSON.stringify({ ...source, hash: await treeHash(plan) }, null, 2)}\n`);
 }
 
 /**
@@ -88,17 +169,14 @@ async function stamp(dest, source) {
  *
  * @param {string} dest - The folder to fill, e.g. `extension/vendor/extension-kit`. Removed first.
  * @returns {Promise<string[]>} The entries copied, relative to `dest`.
+ * @throws {Error} When `dest` holds an extension or a project (`manifest.json`, `package.json`, `.git`).
+ *
  * @example
  * await vendorKit('extension/vendor/extension-kit');
  * // extension/vendor/extension-kit/index.js, …/styles/chrome-ui.css, …, vendored.json
  */
 export async function vendorKit(dest) {
-  await rm(dest, { recursive: true, force: true });
-  await mkdir(dest, { recursive: true });
-  for (const entry of RUNTIME_ENTRIES) {
-    await cp(path.join(SOURCE, entry), path.join(dest, entry), { recursive: true });
-  }
-  await stamp(dest, { package: KIT, version: await versionOf(path.dirname(SOURCE)) });
+  await copyStamped(dest, await copyPlan(SOURCE, RUNTIME_ENTRIES), { package: KIT, version: await versionOf(path.dirname(SOURCE)) });
   return [...RUNTIME_ENTRIES];
 }
 
@@ -113,54 +191,72 @@ export async function vendorKit(dest) {
  * @param {string} dest - The folder to fill, e.g. `extension/vendor/clean-link`. Removed first.
  * @param {{from?: string}} [options] - `from`: where to look for `node_modules` from. Default the current folder.
  * @returns {Promise<string[]>} The files and folders written, relative to `dest`.
- * @throws {Error} When the package isn't installed, or a path isn't in it.
+ * @throws {Error} When the package isn't installed, a path isn't in it, two paths would land in
+ *   the same place (`dist/index.js` and `rules/index.js`), or `dest` holds an extension or a project.
+ *
  * @example
  * await vendorPackage('@duckduckgo/autoconsent', ['dist/autoconsent.esm.js', 'rules/compact-rules.json', 'LICENSE'], 'extension/vendor/autoconsent');
  * // or, from postinstall: extension-kit vendor extension/vendor/clean-link @arraypress/clean-link src/
  */
 export async function vendorPackage(name, files, dest, { from } = {}) {
   const dir = await packageDir(name, from);
-  await rm(dest, { recursive: true, force: true });
-  await mkdir(dest, { recursive: true });
-  /** @type {string[]} */
-  const written = [];
-  for (const file of files) {
-    const source = path.join(dir, file);
-    if (file.endsWith('/')) {
-      await cp(source, dest, { recursive: true });
-      written.push(...await readdir(source));
-    } else {
-      await cp(source, path.join(dest, path.basename(file)), { recursive: true });
-      written.push(path.basename(file));
-    }
+  const plan = await copyPlan(dir, files);
+  await copyStamped(dest, plan, { package: name, version: await versionOf(dir), files: [...files] });
+  return [...new Set([...plan.keys()].map((place) => place.split('/')[0]))];
+}
+
+/**
+ * Why a stamped copy no longer matches the package installed now, if it doesn't.
+ *
+ * @param {string} folder - The vendored folder.
+ * @param {VendorStamp} copied - Its stamp.
+ * @param {string | undefined} from - Where to look for `node_modules` from.
+ * @returns {Promise<string | null>} The line to print, or null when it matches.
+ */
+async function staleness(folder, copied, from) {
+  const dir = await packageDir(copied.package, from).catch(() => null);
+  if (dir === null) return `${folder} is ${copied.package} ${copied.version}, which isn't installed`;
+  const installed = await versionOf(dir);
+  if (installed !== copied.version) return `${folder} is ${copied.package} ${copied.version}; ${installed} is installed`;
+  if (!copied.hash) return null;
+  const plan = await (copied.files ? copyPlan(dir, copied.files) : copyPlan(path.join(dir, 'src'), RUNTIME_ENTRIES)).catch(() => null);
+  if (plan === null || await treeHash(plan) !== copied.hash) {
+    return `${folder} is ${copied.package} ${copied.version}, but the installed ${copied.version}'s files are different`;
   }
-  await stamp(dest, { package: name, version: await versionOf(dir) });
-  return written;
+  // The copied files as they are now; files a script wrote beside them afterwards aren't the package's.
+  const here = await treeHash([...plan.keys()].map((place) => [place, path.join(folder, place)])).catch(() => null);
+  if (here !== copied.hash) return `${folder} has changed since it was copied from ${copied.package} ${copied.version}`;
+  return null;
 }
 
 /**
  * Every vendored copy under `dir` (a folder with a {@link VENDOR_STAMP},
  * searched to any depth) that no longer matches the package installed now:
- * copied from another version, or from a package that's gone.
+ * copied from another version, from a package that's gone, edited since (a
+ * file a script wrote beside the copied ones afterwards doesn't count), or
+ * from files the installed package no longer has as they were. A folder with
+ * no vendored copy at all (a mistyped path, `postinstall` never run) is
+ * reported too.
  *
  * @param {string} dir - The vendor folder, e.g. `extension/vendor`.
  * @param {{from?: string}} [options] - `from`: where to look for `node_modules` from. Default the current folder.
- * @returns {Promise<string[]>} One line per stale copy; empty when all match (or there are none).
+ * @returns {Promise<string[]>} One line per stale copy; empty when all match.
+ *
  * @example
  * const stale = await checkVendored('extension/vendor');
  * // ['extension/vendor/extension-kit is @arraypress/extension-kit 1.2.0; 1.3.0 is installed']
  */
 export async function checkVendored(dir, { from } = {}) {
   const entries = await readdir(dir, { recursive: true }).catch(() => /** @type {string[]} */ ([]));
+  const stamps = entries.filter((file) => path.basename(file) === VENDOR_STAMP).sort();
+  if (!stamps.length) return [`${dir} has no vendored copies (no ${VENDOR_STAMP} in it)`];
   /** @type {string[]} */
   const stale = [];
-  for (const entry of entries.filter((file) => path.basename(file) === VENDOR_STAMP).sort()) {
-    const folder = path.join(dir, path.dirname(entry));
+  for (const entry of stamps) {
     /** @type {VendorStamp} */
     const copied = JSON.parse(await readFile(path.join(dir, entry), 'utf8'));
-    const installed = await packageDir(copied.package, from).then(versionOf, () => null);
-    if (installed === null) stale.push(`${folder} is ${copied.package} ${copied.version}, which isn't installed`);
-    else if (installed !== copied.version) stale.push(`${folder} is ${copied.package} ${copied.version}; ${installed} is installed`);
+    const line = await staleness(path.join(dir, path.dirname(entry)), copied, from);
+    if (line) stale.push(line);
   }
   return stale;
 }

package/src/content/highlight.d.ts

@@ -1,8 +1,9 @@
 /**
  * “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
+ * 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
@@ -21,10 +22,11 @@ export type Highlighter = {
         reveal?: boolean;
     }) => number;
     /**
-     * Take the boxes away.
+     * Take the boxes away (`onClear('asked')`).
      */
     clear: () => void;
 };
+export type ClearReason = 'escape' | 'replaced' | 'asked' | 'pagehide';
 /**
  * A page's highlight: one set of elements boxed at a time.
  *
@@ -32,7 +34,13 @@ export type 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.
+ * @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.
@@ -40,7 +48,8 @@ export type Highlighter = {
  * @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 {(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
@@ -49,6 +58,6 @@ export type Highlighter = {
  */
 export declare function createHighlighter(doc: Document, { root, onClear, max }: {
     root: () => ParentNode;
-    onClear?: () => void;
+    onClear?: (reason: ClearReason) => void;
     max?: number;
 }): Highlighter;

package/src/content/highlight.js

@@ -1,8 +1,9 @@
 /**
  * “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
+ * 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
@@ -21,7 +22,14 @@ export const HIGHLIGHT_CSS = '.box { position: fixed; box-sizing: border-box; bo
  * @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.
+ * @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
  */
 
 /**
@@ -30,7 +38,8 @@ export const HIGHLIGHT_CSS = '.box { position: fixed; box-sizing: border-box; bo
  * @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 {(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
@@ -43,40 +52,54 @@ export function createHighlighter(doc, { root, onClear = () => {}, max = MAX_BOX
   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;
-    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';
+    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` });
-      return box;
-    }));
-    root().append(...shown.boxes);
+    });
+    if (added.length) root().append(...added);
   };
   const update = () => {
     if (!pending) pending = view.requestAnimationFrame(draw);
   };
   /** @param {KeyboardEvent} event */
   const key = (event) => {
-    if (event.key === 'Escape') clear();
+    if (event.key === 'Escape') end('escape');
   };
+  const left = () => end('pagehide');
 
-  function clear() {
+  /** @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();
+    onClear(reason);
   }
 
   /** @type {Highlighter['show']} */
   function show(elements, { reveal = false } = {}) {
-    clear();
+    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' });
@@ -84,9 +107,11 @@ export function createHighlighter(doc, { root, onClear = () => {}, max = MAX_BOX
     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 };
+  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,6 +31,7 @@ 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.
@@ -37,10 +42,19 @@ export type PageOverlay = {
  * 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, {
@@ -50,8 +64,9 @@ export type PageOverlay = {
  * });
  * root.append(card);
  */
-export declare function pageOverlay(doc: Document, { name, css, hostStyle }: {
+export declare function pageOverlay(doc: Document, { name, css, hostStyle, topLayer }: {
     name: string;
     css: string;
     hostStyle?: Record<string, string>;
+    topLayer?: boolean;
 }): PageOverlay;