@arraypress/extension-kit 1.6.0 → 1.7.0

package/README.md

@@ -14,6 +14,11 @@ The pieces ArrayPress's Chrome extensions share, so each is written once:
   ("Rename folder", or several fields as "Add site search"), the toast with Undo and a settings card's site list, built on the
   stylesheet's classes; they work in a content script's shadow root too.
 - **Sites**: what people type into a per-site list, and whether a page is on one.
+- **Chrome's on-device model** (Gemini Nano, the Prompt API): availability, a download from the
+  person's click with progress, one base session with a `clone()` per question, a time limit on
+  every answer, cold starts, and the settings page's “Chrome’s built-in AI” row.
+- **Content-script helpers**: a big page worked through in slices that never hold it long, and a
+  change watcher for single-page apps and endless lists.
 - **Build and test helpers** (Node): icon rendering, vendoring npm packages (with a staleness
   check), test builds, store screenshots, zipping for the Chrome Web Store, a fake
   `chrome.storage`, Playwright helpers with time limits, packaging checks, and a copied-code guard.
@@ -211,6 +216,81 @@ Registers, updates or unregisters the script `id` to match what `want()` gives a
 none). Calls run one after another, so a quick run of changes can't register twice or end out of
 order; a refused change rejects that call only.
 
+## Chrome's on-device model
+
+```js
+import { chromeLanguageModel, createModelSession } from '../vendor/extension-kit/index.js';
+
+const ENGLISH = { expectedInputs: [{ type: 'text', languages: ['en'] }], expectedOutputs: [{ type: 'text', languages: ['en'] }] };
+const model = createModelSession({
+  model: chromeLanguageModel,           // read when used: Chrome may add it after start-up
+  options: ENGLISH,                     // availability() is asked with what create() gets
+  initialPrompts: [{ role: 'system', content: 'You name downloaded files.' }, ...EXAMPLE],
+});
+const answer = await model.ask(prompt, { timeoutMs: 2500, signal, responseConstraint: schema });
+if (answer.text === null) useRules(answer.reason); // 'unavailable' | 'late' | 'aborted' | 'failed'
+```
+
+Following https://developer.chrome.com/docs/ai/prompt-api: only an `available` model is used (a
+question never downloads it); one base session is made when first needed and kept; each question
+goes to a `clone()` of it, let go after; the answer's `AbortSignal` fires at the time limit. The
+first session after Chrome starts can take ~18 s while the model loads: a question with a shorter
+limit comes back `'late'`, and the session goes on loading for the next one. Nothing loads it ahead
+of time (that would load the model on every start). `release()` lets the base session go.
+
+`modelAvailability(api, options)` never throws (`'missing'` without a Prompt API).
+`downloadModel(api, options, {onProgress})` is the only `create()` that may download: call it
+first in a click's handler, with nothing awaited before it. The settings row:
+
+```html
+<div class="row two-line">
+  <span class="label">
+    <span data-i18n="optionsModel">Chrome’s built-in AI</span>
+    <span class="secondary"><span id="model-status"></span> <span id="model-help" hidden></span></span>
+    <progress id="model-progress" max="1" value="0" hidden></progress>
+  </span>
+  <button id="model-download" type="button" data-i18n="optionsModelDownload" hidden>Download</button>
+</div>
+```
+
+```js
+const row = createModelRow(
+  { status: byId('model-status'), help: byId('model-help'), download: byId('model-download', HTMLButtonElement), progress: byId('model-progress', HTMLProgressElement) },
+  { options: ENGLISH, state: () => ask(MESSAGES.modelState), t, onShown: ({ state }) => { useAi.disabled = state === 'off'; } },
+);
+await row.refresh();
+```
+
+Its words are the page's messages under `MODEL_MESSAGES`' keys (`optionsModel`, `optionsModelReady`,
+`optionsModelNeedsDownload`, `optionsModelDownloadHelp`, `optionsModelDownload`,
+`optionsModelDownloading` with `$PERCENT$`, `optionsModelDownloadFailed`, `optionsModelUnsupported`,
+`optionsModelRequirements`, `optionsModelMissing`, `optionsModelMissingHelp`); `describeModel` maps
+a state to them. Tests use `fakeLanguageModel` (`/testing`), the Prompt API's shape: availability,
+download progress (or a failed download), a cold start, slow and failed answers, aborts, and a log
+of what it was asked.
+
+## Content scripts
+
+```js
+import { inSlices } from '../vendor/extension-kit/content/slices.js';
+import { watchChanges } from '../vendor/extension-kit/content/watch.js';
+
+await inSlices(document.body, (block) => scanner.scan(block)); // ≤4,000 characters a block, 40 ms slices
+const stop = watchChanges(document.body, {
+  changed: (nodes) => nodes.forEach((node) => scanner.scan(node)), // one batch, each subtree once
+  removed: (node) => scanner.forget(node),                         // at once
+  ignore: (node) => node instanceof Element && node.localName === 'my-note', // the extension's own
+  settleMs: 120, maxWaitMs: 600,
+});
+```
+
+`inSlices(root, work, {blockChars, sliceMs, pause})` cuts a page into blocks (`blocksOf`) and
+hands the main thread back whenever a slice has run its time, so a 2,000-item listing never
+freezes. `watchChanges` hands over what was added or changed a little after the page stops
+changing (at most `maxWaitMs` while it keeps on); an element with a few children (`regroupChildren`,
+default 6) whose children changed is handed over whole. Both are pure DOM, so a content script
+imports them directly (list them in `web_accessible_resources`).
+
 ## Time limits
 
 ```js
@@ -273,7 +353,11 @@ const site = await askText({
 });
 ```
 
-Resolves to the text, trimmed, or `null` when cancelled. The action button (default "Save") stays
+Resolves to the text, trimmed, or `null` when cancelled. A field can be `multiline` (a textarea,
+`rows` high: Enter starts a new line), carry a `hint` under it (or a function of its text, kept up
+as it's typed: “12 words”), and take a `value` that's still being worked out (a promise, say an
+on-device model's suggestion): the field waits, disabled, with `waiting` under it, then takes the
+text and the focus (unless the person has typed meanwhile); a failed one leaves it empty. The action button (default "Save") stays
 disabled while the text is blank or `validate` gives a reason, which shows under the field
 (`checkText` is that rule, pure). Enter presses the action button; Esc and Cancel cancel; the
 focus goes back to what had it, or to `returnTo` (an element, or a function asked at the end).
@@ -389,10 +473,13 @@ except those listed, each with a reason:
 
 | Export | What it does |
 |---|---|
-| `fakeChromeStorage({local, sync, session, now})` | In-memory `chrome.storage`: JSON copies, `onChanged` for real changes only, sync's 8,192-byte item quota and 120 writes a minute. `settled()` waits for listeners. |
+| `fakeLanguageModel(state)` | A fake Prompt API (`LanguageModel`): `availability`, `create` (download progress, a cold start, `failDownload`), sessions that `clone`, answer (`answerMs`, `answer(prompt)`, `failPrompt`) and stop on their signal; `log` of what it was asked, `set` to change it. Browser-safe, so a test build can put it on `globalThis`. |
+| `fakeChromeStorage({local, sync, session, now})` | In-memory `chrome.storage`: JSON copies, `onChanged` for real changes only, sync's 8,192-byte item quota, its 102,400 bytes in all (`SYNC_QUOTA_BYTES`) and 120 writes a minute. `settled()` waits for listeners. |
 | `launchExtension(chromium, dir, options)` | Load an unpacked extension into a fresh profile; `{context, worker, extensionId, url(page), profile, close()}`. |
 | `launchDownloading(chromium, dir, options)`, `filesIn(dir)` | An extension in a browser that downloads for real: `{…launchExtension's, downloads}`, the profile's own Downloads folder (Playwright otherwise saves downloads under made-up names no extension sees); the files under a folder, downloads still running left out. |
 | `extensionProfile(chromium, dir, options)` | A profile to start the browser on more than once (a restart, a first start with a changed manifest): `{dir, launch(), remove()}`. |
+| `runChecks(runner, body, cleanUps)` | A script's checks: an error outside any check fails, the clean-ups always run (each within 30 s), then the tally. |
+| `messageLookup(extensionDir, locale)`, `readMessages(extensionDir, locale)` | `chrome.i18n.getMessage` over the real `_locales` (a locale over en, named placeholders filled), for unit tests. |
 | `checkRunner({timeout})` | Named checks that report and go on: `check(name, fn, {timeout})`, `fail(name)` for an error found outside a check, `finish()`. A check that runs past its limit (`CHECK_MS`, 60 s) fails, and the run goes on. |
 | `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)` (also in the main entry). |
 | `realisticBrowser(options)`, `chromeUserAgent(browser)` | Launch options and a user agent for a browser that doesn't say it's automated, for live checks. |
@@ -435,6 +522,7 @@ except those listed, each with a reason:
 | Manager layout | `.manager`/`.layout`, `.sidebar` with `.tree` > `.tree-item`, `.main` with `.list-card` |
 | Menu (cr-action-menu) | `<dialog class="menu">` of `button[role="menuitem"]`, `hr` (or `createMenu`) |
 | ⋮ icon | `<span class="icon icon-more-vert" aria-hidden="true">` (or `moreActionsButton`) |
+| Subpage header (settings-subpage) | `<div class="subpage-head">` with a back `button.icon-button` holding `.icon.icon-arrow-back`, then `<h2>` |
 | Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` (`askText`, `askFields`) |
 | Toast (cr-toast) | `<div class="toast" popover="manual">text <button>Undo</button></div>` (or `createToast`); with `hidden` instead of `popover`, it shows over the page but not the top layer |
 | Drawer (cr-drawer) | `<dialog class="drawer">` with `.drawer-head` and a `.nav` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.6.0",
-  "description": "Shared pieces for Chrome extensions: Chrome's own page styles, a Chrome Sync settings store, the light/dark toolbar glyph, About links, and build and test helpers.",
+  "version": "1.7.0",
+  "description": "Shared pieces for Chrome extensions: Chrome's own page styles and components, a Chrome Sync settings store, the light/dark toolbar glyph, Chrome's on-device model, content-script helpers, About links, and build and test helpers.",
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/ai/model.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Chrome's on-device model (Gemini Nano, through the Prompt API), the way
+ * every extension here uses it, following
+ * https://developer.chrome.com/docs/ai/prompt-api:
+ *
+ * - `availability()` is asked with the options `create()` gets, and only an
+ *   'available' model is used: nothing here downloads it, except
+ *   {@link downloadModel}, which a page calls from the person's click (Chrome
+ *   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 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
+ *   loads (a cold start, M3 Max). A question with a shorter limit gets
+ *   'late', and the session goes on loading for the next one. Nothing loads
+ *   it ahead of time: that would load the model on every start for work that
+ *   may never come.
+ *
+ * Nothing here touches `chrome.*` or the global itself: the Prompt API comes
+ * in as `model` (read when used, since Chrome may add it after start-up), so
+ * tests hand it the kit's fake (`fakeLanguageModel`, `/testing`) at exactly
+ * this edge. TypeScript's DOM library doesn't declare the Prompt API yet, so
+ * the parts used are typed here.
+ *
+ * @module ai/model
+ */
+export type Availability = 'available' | 'downloadable' | 'downloading' | 'unavailable' | 'missing';
+export type PromptOptions = {
+    /**
+     * Stops the answer.
+     */
+    signal?: AbortSignal;
+    /**
+     * A JSON Schema (or RegExp) the answer must follow.
+     */
+    responseConstraint?: object;
+};
+export type LanguageModelSession = {
+    /**
+     * The whole answer.
+     */
+    prompt: (prompt: string, options?: PromptOptions) => Promise<string>;
+    /**
+     * A copy with the same history.
+     */
+    clone: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<LanguageModelSession>;
+    /**
+     * Let it go.
+     */
+    destroy: () => void;
+};
+export type InitialPrompt = {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+};
+export type LanguageModelOptions = {
+    /**
+     * What it's given.
+     */
+    expectedInputs?: {
+        type: string;
+        languages: string[];
+    }[];
+    /**
+     * What it answers in.
+     */
+    expectedOutputs?: {
+        type: string;
+        languages: string[];
+    }[];
+    /**
+     * Its instructions and examples.
+     */
+    initialPrompts?: InitialPrompt[];
+    /**
+     * Hears `downloadprogress` (`loaded`, 0–1) while the model downloads.
+     */
+    monitor?: (monitor: EventTarget) => void;
+    /**
+     * Stops creating it.
+     */
+    signal?: AbortSignal;
+};
+export type LanguageModelStatic = {
+    /**
+     * Whether it can run here.
+     */
+    availability: (options?: LanguageModelOptions) => Promise<Availability>;
+    /**
+     * A session (downloads the model first, from a click).
+     */
+    create: (options?: LanguageModelOptions) => Promise<LanguageModelSession>;
+};
+/**
+ * The model's answer to `availability()`: 'available', 'downloadable',
+ * 'downloading' or 'unavailable'; and, from {@link modelAvailability},
+ * 'missing' when this Chrome has no Prompt API.
+ *
+ * @typedef {'available' | 'downloadable' | 'downloading' | 'unavailable' | 'missing'} Availability
+ */
+/**
+ * @typedef {object} PromptOptions
+ * @property {AbortSignal} [signal] Stops the answer.
+ * @property {object} [responseConstraint] A JSON Schema (or RegExp) the answer must follow.
+ */
+/**
+ * @typedef {object} LanguageModelSession
+ * @property {(prompt: string, options?: PromptOptions) => Promise<string>} prompt The whole answer.
+ * @property {(options?: {signal?: AbortSignal}) => Promise<LanguageModelSession>} clone A copy with the same history.
+ * @property {() => void} destroy Let it go.
+ */
+/**
+ * @typedef {{role: 'system' | 'user' | 'assistant', content: string}} InitialPrompt
+ */
+/**
+ * @typedef {object} LanguageModelOptions
+ * @property {{type: string, languages: string[]}[]} [expectedInputs] What it's given.
+ * @property {{type: string, languages: string[]}[]} [expectedOutputs] What it answers in.
+ * @property {InitialPrompt[]} [initialPrompts] Its instructions and examples.
+ * @property {(monitor: EventTarget) => void} [monitor] Hears `downloadprogress` (`loaded`, 0–1) while the model downloads.
+ * @property {AbortSignal} [signal] Stops creating it.
+ */
+/**
+ * @typedef {object} LanguageModelStatic
+ * @property {(options?: LanguageModelOptions) => Promise<Availability>} availability Whether it can run here.
+ * @property {(options?: LanguageModelOptions) => Promise<LanguageModelSession>} create A session (downloads the model first, from a click).
+ */
+/**
+ * Chrome's `LanguageModel`, or undefined when this Chrome has none.
+ *
+ * @param {object} [scope] - Where to look. Default `globalThis` (a page, or the service worker).
+ * @returns {LanguageModelStatic | undefined} The Prompt API.
+ * @example
+ * const sessions = createModelSession({ model: chromeLanguageModel, options: ENGLISH });
+ */
+export declare function chromeLanguageModel(scope?: object): LanguageModelStatic | undefined;
+/**
+ * The model's state, never throwing: 'missing' without a Prompt API, and
+ * 'unavailable' when asking fails.
+ *
+ * @param {LanguageModelStatic | undefined} model - The Prompt API.
+ * @param {LanguageModelOptions} options - The options sessions are created with.
+ * @returns {Promise<Availability>} Its state.
+ * @example
+ * await modelAvailability(chromeLanguageModel(), ENGLISH); // 'available'
+ */
+export declare function modelAvailability(model: LanguageModelStatic | undefined, options: LanguageModelOptions): Promise<Availability>;
+/**
+ * Download the model, from the person's click: `create()` with a monitor,
+ * the session let go once made. Call it first in the click's handler, with
+ * nothing awaited before it, or Chrome refuses (no user activation).
+ *
+ * @param {LanguageModelStatic | undefined} model - The Prompt API.
+ * @param {LanguageModelOptions} options - The options sessions are created with.
+ * @param {{onProgress?: (loaded: number) => void, signal?: AbortSignal}} [handlers] - `onProgress`: how much is
+ *   downloaded, 0–1, as Chrome reports it; `signal`: stops it.
+ * @returns {Promise<Availability>} The state afterwards ('available' once it's here).
+ * @throws {Error} When there's no Prompt API, or Chrome couldn't download it.
+ * @example
+ * button.addEventListener('click', () => {
+ *   downloadModel(chromeLanguageModel(), ENGLISH, { onProgress: (loaded) => { bar.value = loaded; } })
+ *     .then(show, () => show('downloadable', 'The download didn’t finish. Try again.'));
+ * });
+ */
+export declare function downloadModel(model: LanguageModelStatic | undefined, options: LanguageModelOptions, { onProgress, signal }?: {
+    onProgress?: (loaded: number) => void;
+    signal?: AbortSignal;
+}): Promise<Availability>;
+/**
+ * The settings page's words for a state: standard message keys (the
+ * extension's `_locales` names them alike), as `SITE_LIST_MESSAGES` does
+ * for a site list.
+ */
+export declare const MODEL_MESSAGES: Readonly<{
+    /** “Chrome’s built-in AI”: the row's name. */
+    name: "optionsModel";
+    /** “Checking…” before the state is known. */
+    checking: "optionsModelChecking";
+    /** “Ready”. */
+    ready: "optionsModelReady";
+    /** “Needs download”. */
+    needsDownload: "optionsModelNeedsDownload";
+    /** “Chrome downloads its model once and shares it with every site and extension that uses it”. */
+    downloadHelp: "optionsModelDownloadHelp";
+    /** “Download”: the button. */
+    download: "optionsModelDownload";
+    /** “Downloading… $PERCENT$%” (content `$1`). */
+    downloading: "optionsModelDownloading";
+    /** “The download didn’t finish. Try again.” */
+    downloadFailed: "optionsModelDownloadFailed";
+    /** “Not supported on this computer”. */
+    unsupported: "optionsModelUnsupported";
+    /** What a computer needs to run it. */
+    requirements: "optionsModelRequirements";
+    /** “This Chrome doesn’t have it”. */
+    missing: "optionsModelMissing";
+    /** What to do about that, and that the extension works without it. */
+    missingHelp: "optionsModelMissingHelp";
+}>;
+export type ModelStatus = {
+    /**
+     * Ready to use, can be downloaded, or can't run here.
+     */
+    state: 'ready' | 'pending' | 'off';
+    /**
+     * The status's message key ({@link MODEL_MESSAGES}).
+     */
+    status: string;
+    /**
+     * The help's message key ('' for none).
+     */
+    help: string;
+    /**
+     * Whether to offer Download.
+     */
+    canDownload: boolean;
+};
+/**
+ * The model's state, as a settings page shows it.
+ *
+ * @typedef {object} ModelStatus
+ * @property {'ready' | 'pending' | 'off'} state Ready to use, can be downloaded, or can't run here.
+ * @property {string} status The status's message key ({@link MODEL_MESSAGES}).
+ * @property {string} help The help's message key ('' for none).
+ * @property {boolean} canDownload Whether to offer Download.
+ */
+/**
+ * Describe an availability for a settings page. Pure.
+ *
+ * @param {string} availability - 'available', 'downloadable', 'downloading', 'unavailable' or 'missing'.
+ * @returns {ModelStatus} How to show it.
+ * @example
+ * describeModel('downloadable'); // { state: 'pending', status: 'optionsModelNeedsDownload', help: 'optionsModelDownloadHelp', canDownload: true }
+ */
+export declare function describeModel(availability: string): ModelStatus;
+export type ModelAnswer = {
+    text: string;
+    reason: 'answered';
+} | {
+    text: null;
+    reason: 'unavailable' | 'late' | 'aborted' | 'failed';
+};
+export type AskOptions = {
+    /**
+     * The most the answer may take, from the moment it's asked: the base
+     * session (if it must be made) and the answer.
+     */
+    timeoutMs: number;
+    /**
+     * Stops it sooner (the person cancelled).
+     */
+    signal?: AbortSignal;
+    /**
+     * A JSON Schema the answer must follow.
+     */
+    responseConstraint?: object;
+};
+export type ModelSession = {
+    /**
+     * The model's state, or 'missing'.
+     */
+    availability: () => Promise<Availability>;
+    /**
+     * Ask a copy of the base session.
+     */
+    ask: (prompt: string, options: AskOptions) => Promise<ModelAnswer>;
+    /**
+     * Let the base session go (the next question makes it again).
+     */
+    release: () => void;
+};
+/**
+ * What a question got: the answer, or why there's none: the model isn't
+ * on this computer ('unavailable'), the time ran out first ('late', a cold
+ * start among them), the caller's signal stopped it ('aborted'), or the model
+ * failed ('failed').
+ *
+ * @typedef {{text: string, reason: 'answered'} | {text: null, reason: 'unavailable' | 'late' | 'aborted' | 'failed'}} ModelAnswer
+ */
+/**
+ * @typedef {object} AskOptions
+ * @property {number} timeoutMs The most the answer may take, from the moment it's asked: the base
+ *   session (if it must be made) and the answer.
+ * @property {AbortSignal} [signal] Stops it sooner (the person cancelled).
+ * @property {object} [responseConstraint] A JSON Schema the answer must follow.
+ */
+/**
+ * @typedef {object} ModelSession
+ * @property {() => Promise<Availability>} availability The model's state, or 'missing'.
+ * @property {(prompt: string, options: AskOptions) => Promise<ModelAnswer>} ask Ask a copy of the base session.
+ * @property {() => void} release Let the base session go (the next question makes it again).
+ */
+/**
+ * A base session over a Prompt API, made when first needed and kept, each
+ * question asked of a `clone()` within its time limit.
+ *
+ * @param {{model: () => LanguageModelStatic | undefined, options: LanguageModelOptions, initialPrompts?: InitialPrompt[]}} setup -
+ *   `model`: the Prompt API, read when used; `options`: what sessions are made (and availability asked)
+ *   with; `initialPrompts`: the instructions and examples every question starts from.
+ * @returns {ModelSession} The session.
+ * @example
+ * const sessions = createModelSession({
+ *   model: chromeLanguageModel,
+ *   options: { expectedInputs: [{ type: 'text', languages: ['en'] }], expectedOutputs: [{ type: 'text', languages: ['en'] }] },
+ *   initialPrompts: [{ role: 'system', content: 'You name downloaded files.' }],
+ * });
+ * const { text } = await sessions.ask('Site: acme.com', { timeoutMs: 2500 }); // null when late
+ */
+export declare function createModelSession({ model, options, initialPrompts }: {
+    model: () => LanguageModelStatic | undefined;
+    options: LanguageModelOptions;
+    initialPrompts?: InitialPrompt[];
+}): ModelSession;