@arraypress/extension-kit 1.10.0 → 1.11.1

package/src/ai/host.js

@@ -0,0 +1,225 @@
+/**
+ * Chrome's on-device model for a service worker, wherever Chrome puts the
+ * Prompt API. Chrome's documentation says `LanguageModel` isn't in workers
+ * (https://developer.chrome.com/docs/ai/prompt-api); Chrome 157 and Chromium
+ * 156 do have it in an extension's service worker (checked in both: an
+ * unpacked extension, `typeof LanguageModel` in the worker, an extension page
+ * and an offscreen document, `'function'` in all three). So neither is
+ * promised, and a worker that uses the model shouldn't depend on which holds:
+ * {@link createHostedModelSession} is a `ModelSession` that asks the worker's
+ * own `LanguageModel` when there is one, and otherwise the extension's
+ * offscreen document, which has a page's Prompt API and answers over
+ * `chrome.runtime` messages ({@link serveModelOffscreen}).
+ *
+ * The offscreen document is the one the worker already keeps for the toolbar
+ * glyph (an extension gets only one): its script calls both
+ * `watchSchemeOffscreen` and `serveModelOffscreen`. It's told the session's
+ * options and instructions with each request, so it needs none of the
+ * extension's own code.
+ *
+ * @module ai/host
+ */
+
+import { within } from '../time/time.js';
+import { chromeLanguageModel, createModelSession } from './model.js';
+
+/** @import { AskOptions, Availability, InitialPrompt, LanguageModelOptions, LanguageModelStatic, ModelAnswer, ModelSession } from './model.js' */
+
+/** The request's message type: `{type: MODEL_HOST, method, name, …}`. */
+export const MODEL_HOST = 'model-host';
+
+/** How long past an answer's time limit the worker waits for the offscreen document to say so itself (ms). */
+export const HOST_GRACE_MS = 1000;
+
+/** The model's states, to check an answer that came over a message. */
+const STATES = ['available', 'downloadable', 'downloading', 'unavailable', 'missing'];
+
+/** Why a question got no answer, to check the same. */
+const REASONS = ['unavailable', 'late', 'aborted', 'failed'];
+
+/**
+ * A request to the offscreen document.
+ *
+ * @typedef {object} HostRequest
+ * @property {typeof MODEL_HOST} type The message type.
+ * @property {'availability' | 'ask' | 'abort' | 'release'} method What's asked.
+ * @property {string} name The session's name (one base session each).
+ * @property {LanguageModelOptions} [options] What its sessions are made with.
+ * @property {InitialPrompt[]} [initialPrompts] Its instructions and examples.
+ * @property {string} [id] A question's id, for `abort`.
+ * @property {string} [prompt] The question.
+ * @property {number} [timeoutMs] Its time limit.
+ * @property {object} [responseConstraint] The answer's JSON Schema.
+ */
+
+/**
+ * The parts of `chrome.runtime` the worker's side uses.
+ *
+ * @typedef {{sendMessage(message: unknown): Promise<unknown>}} HostSender
+ */
+
+/**
+ * The parts of `chrome.runtime` the offscreen document's side uses.
+ *
+ * @typedef {object} HostRuntime
+ * @property {string} id This extension's id: requests from anyone else are ignored.
+ * @property {{addListener(listener: (message: unknown, sender: {id?: string, tab?: unknown}, respond: (answer: unknown) => void) => boolean): void}} onMessage
+ *   `chrome.runtime.onMessage`.
+ */
+
+/**
+ * @typedef {object} HostedSessionSetup
+ * @property {string} name The session's name, its own among the extension's sessions ('topics').
+ * @property {LanguageModelOptions} options What sessions are made (and availability asked) with.
+ * @property {InitialPrompt[]} [initialPrompts] The instructions and examples every question starts from.
+ * @property {HostSender} runtime `chrome.runtime`.
+ * @property {() => Promise<unknown>} open Makes sure the offscreen document is open
+ *   (`() => watchFromOffscreen(chrome)`); only called when the worker has no Prompt API.
+ * @property {() => LanguageModelStatic | undefined} [model] The worker's own Prompt API, read when used.
+ *   Default Chrome's.
+ */
+
+/**
+ * A model session for a service worker: the worker's own Prompt API when it
+ * has one, else the offscreen document's. The same `ModelSession` either way.
+ * An answer's JSON Schema crosses to the offscreen document as JSON, so it
+ * must be a plain object there (not a RegExp).
+ *
+ * @param {HostedSessionSetup} setup - The session, and how to reach the offscreen document.
+ * @returns {ModelSession} The session.
+ * @example
+ * // background.js
+ * const words = createHostedModelSession({
+ *   name: 'words', options: ENGLISH, initialPrompts: [{ role: 'system', content: 'You list words.' }],
+ *   runtime: chrome.runtime, open: () => watchFromOffscreen(chrome),
+ * });
+ * const { text } = await words.ask('Topic: football', { timeoutMs: 20_000 });
+ */
+export function createHostedModelSession({ name, options, initialPrompts = [], runtime, open, model = chromeLanguageModel }) {
+  const local = createModelSession({ model, options, initialPrompts });
+  let asked = 0;
+
+  /**
+   * Ask the offscreen document.
+   *
+   * @param {HostRequest['method']} method
+   * @param {Partial<HostRequest>} [more]
+   * @returns {Promise<unknown>} Its answer; rejects when there's no document to hear it.
+   */
+  const send = async (method, more = {}) => {
+    await open();
+    return runtime.sendMessage(/** @type {HostRequest} */ ({ type: MODEL_HOST, method, name, options, initialPrompts, ...more }));
+  };
+
+  return {
+    async availability() {
+      if (model()) return local.availability();
+      const state = await send('availability').catch(() => 'missing');
+      return STATES.includes(/** @type {string} */ (state)) ? /** @type {Availability} */ (state) : 'missing';
+    },
+
+    async ask(prompt, askOptions) {
+      if (model()) return local.ask(prompt, askOptions);
+      const { timeoutMs, signal, responseConstraint } = askOptions;
+      if (signal?.aborted) return { text: null, reason: 'aborted' };
+      const id = `${name}:${Date.now()}:${asked++}`;
+      const onAbort = () => { runtime.sendMessage({ type: MODEL_HOST, method: 'abort', name, id }).catch(() => {}); };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      try {
+        // The document keeps the time limit; the worker's own is for a document that never answers.
+        const answer = /** @type {Partial<ModelAnswer> | 'gone' | 'late' | undefined} */ (await within(
+          send('ask', { id, prompt, timeoutMs, ...(responseConstraint && { responseConstraint }) }).catch(() => 'gone'),
+          timeoutMs + HOST_GRACE_MS,
+          'late',
+        ));
+        if (answer === 'late') {
+          onAbort();
+          return { text: null, reason: signal?.aborted ? 'aborted' : 'late' };
+        }
+        if (answer && typeof answer === 'object') {
+          if (typeof answer.text === 'string' && answer.reason === 'answered') return { text: answer.text, reason: 'answered' };
+          if (REASONS.includes(/** @type {string} */ (answer.reason))) return { text: null, reason: /** @type {Exclude<ModelAnswer['reason'], 'answered'>} */ (answer.reason) };
+        }
+        return { text: null, reason: signal?.aborted ? 'aborted' : 'unavailable' };
+      } finally {
+        signal?.removeEventListener('abort', onAbort);
+      }
+    },
+
+    release() {
+      local.release();
+      if (!model()) runtime.sendMessage({ type: MODEL_HOST, method: 'release', name }).catch(() => {});
+    },
+  };
+}
+
+/**
+ * Answer the worker's model requests, in the offscreen document: one base
+ * session per name, made with the options and instructions the request
+ * carries (and again if they change). Requests from another extension, or
+ * from a content script (a web page's side), are ignored.
+ *
+ * @param {HostRuntime} runtime - `chrome.runtime`.
+ * @param {{model?: () => LanguageModelStatic | undefined}} [options] - The document's Prompt API. Default Chrome's.
+ * @returns {void}
+ * @example
+ * // offscreen/offscreen.js
+ * watchSchemeOffscreen(chrome.runtime);
+ * serveModelOffscreen(chrome.runtime);
+ */
+export function serveModelOffscreen(runtime, { model = chromeLanguageModel } = {}) {
+  /** Each name's session, and the setup it was made with. @type {Map<string, {setup: string, session: ModelSession}>} */
+  const sessions = new Map();
+  /** The questions being answered, to stop one. @type {Map<string, AbortController>} */
+  const asking = new Map();
+
+  /** @param {HostRequest} request @returns {ModelSession} */
+  const sessionFor = ({ name, options = {}, initialPrompts = [] }) => {
+    const setup = JSON.stringify([options, initialPrompts]);
+    const kept = sessions.get(name);
+    if (kept?.setup === setup) return kept.session;
+    kept?.session.release();
+    const session = createModelSession({ model, options, initialPrompts });
+    sessions.set(name, { setup, session });
+    return session;
+  };
+
+  /** @param {HostRequest} request @returns {Promise<unknown>} */
+  const answer = async (request) => {
+    switch (request.method) {
+      case 'availability':
+        return sessionFor(request).availability();
+      case 'ask': {
+        const stop = new AbortController();
+        const id = String(request.id);
+        asking.set(id, stop);
+        try {
+          return await sessionFor(request).ask(String(request.prompt ?? ''), /** @type {AskOptions} */ ({
+            timeoutMs: Number(request.timeoutMs) || 0,
+            signal: stop.signal,
+            ...(request.responseConstraint && { responseConstraint: request.responseConstraint }),
+          }));
+        } finally {
+          asking.delete(id);
+        }
+      }
+      case 'abort':
+        asking.get(String(request.id))?.abort();
+        return null;
+      case 'release':
+        sessions.get(request.name)?.session.release();
+        sessions.delete(request.name);
+        return null;
+      default:
+        return null;
+    }
+  };
+
+  runtime.onMessage.addListener((message, sender, respond) => {
+    const request = /** @type {HostRequest | null | undefined} */ (message);
+    if (request?.type !== MODEL_HOST || typeof request.name !== 'string') return false;
+    if (sender.id !== runtime.id || sender.tab) return false;
+    answer(request).then(respond, () => respond(null));
+    return true;
+  });
+}

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;