@arraypress/extension-kit 1.9.0 → 1.11.0

package/src/build/test-build.js

@@ -11,7 +11,7 @@
  * @module build/test-build
  */
 
-import { cp, readFile, rm, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 /** The environment variable that moves the test builds' folder (absolute, or relative to the extension's root). */
@@ -53,8 +53,42 @@ export function testBuildDir(root, name = 'e2e', env = process.env) {
  *   imports the real worker and exposes what a test can't reach headlessly (a menu click, the
  *   toolbar button).
  * @property {(manifest: TestManifest) => void} [manifest] Changes the copy's manifest in place.
+ * @property {string} [panelOpener] A side panel page (`panel/panel.html`): adds {@link PANEL_OPENER}
+ *   (`?tab=<id>`), whose button opens that panel beside the tab the way the toolbar click does
+ *   (the kit's `openSidePanel`, during a real click), which Playwright can't click. Its title turns
+ *   `opened` (or `error: …`). The kit must be vendored at `vendor/extension-kit/`.
  */
 
+/** The page {@link TestBuild}'s `panelOpener` adds, from the build's root. */
+export const PANEL_OPENER = 'e2e/open-panel.html';
+
+/**
+ * The opener page's markup (its script a file beside it: extension pages run no inline script).
+ *
+ * @returns {string} The HTML.
+ */
+const openerHtml = () => `<!doctype html>
+<meta charset="utf-8">
+<title>Open the side panel</title>
+<!-- Test builds only: a button that does what the toolbar click does, which Playwright can't click. -->
+<button id="open" type="button">Open the side panel</button>
+<script type="module" src="open-panel.js"></script>
+`;
+
+/**
+ * The opener page's script.
+ *
+ * @param {string} panel - The panel page.
+ * @returns {string} The module.
+ */
+const openerScript = (panel) => `import { openSidePanel } from '../vendor/extension-kit/panel/side-panel.js';
+
+const tabId = Number(new URLSearchParams(location.search).get('tab'));
+document.getElementById('open').addEventListener('click', () => {
+  openSidePanel(chrome.sidePanel, tabId, ${JSON.stringify(panel)}).then(() => { document.title = 'opened'; }, (error) => { document.title = \`error: \${error.message}\`; });
+});
+`;
+
 /**
  * Copy an extension folder into a test build, with its own hook and manifest.
  *
@@ -66,7 +100,7 @@ export function testBuildDir(root, name = 'e2e', env = process.env) {
  *   manifest: (manifest) => { manifest.host_permissions = ['http://127.0.0.1/*']; },
  * });
  */
-export async function buildTestCopy({ from, to, hook, manifest: change }) {
+export async function buildTestCopy({ from, to, hook, manifest: change, panelOpener }) {
   await rm(to, { recursive: true, force: true });
   await cp(from, to, { recursive: true });
   const file = path.join(to, 'manifest.json');
@@ -78,5 +112,10 @@ export async function buildTestCopy({ from, to, hook, manifest: change }) {
   }
   change?.(manifest);
   await writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`);
+  if (panelOpener) {
+    await mkdir(path.join(to, path.dirname(PANEL_OPENER)), { recursive: true });
+    await writeFile(path.join(to, PANEL_OPENER), openerHtml());
+    await writeFile(path.join(to, PANEL_OPENER.replace(/\.html$/, '.js')), openerScript(panelOpener));
+  }
   return to;
 }

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/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,63 @@
+/**
+ * “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 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 (`onClear('asked')`).
+     */
+    clear: () => void;
+};
+export type ClearReason = 'escape' | 'replaced' | 'asked' | 'pagehide';
+/**
+ * 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 declare function createHighlighter(doc: Document, { root, onClear, max }: {
+    root: () => ParentNode;
+    onClear?: (reason: ClearReason) => void;
+    max?: number;
+}): Highlighter;