@arraypress/extension-kit 1.10.0 → 1.11.0

package/README.md

@@ -74,9 +74,12 @@ Other libraries are copied the same way, by name (a path ending in `/` copies a
 ```
 
 `npm install some-package` doesn't run the extension's own `postinstall`, so a copy can go stale
-without a word. Each copy is stamped with its package's version (`vendored.json`, left out of the
-zip), and `extension-kit vendor-check` fails, naming the copy, until `npm run postinstall` remakes
-it. From a script: `vendorPackage(name, files, dest)`, `checkVendored(dir)`.
+without a word. Each copy is stamped with its package's version, what was copied and a hash of it
+(`vendored.json`, left out of the zip), and `extension-kit vendor-check` fails, naming the copy,
+until `npm run postinstall` remakes it: a copy of another version, one edited by hand, one whose
+package's files changed under the same version (a library copied into `node_modules` to try it
+before it's published), or a vendor folder with no copies in it at all. A copy is never made into
+a folder that holds a `manifest.json`, a `package.json` or a `.git` (the folder is emptied first). From a script: `vendorPackage(name, files, dest)`, `checkVendored(dir)`.
 
 ### An extension with a bundler
 
@@ -116,10 +119,12 @@ saver.follow((settings) => show(settings), chrome.storage.onChanged);
 
 | Store member | What it does |
 |---|---|
-| `load(storage)` | Every setting: sync, then held refusals, then local, normalised. |
+| `load(storage)` | Every setting: sync, then held refusals (the ones still newer than what sync holds), then local, normalised. |
 | `save(storage, changes)` | Writes only the settings named, so another computer's change to a different one survives. Resolves to `{settings, synced}`. |
-| `writeSynced(storage, values)` | One sync write; what sync refuses (rate limit, an item over 8,192 bytes) is kept in local under `unsyncedKey` and retried with the next write. |
+| `writeSynced(storage, values)` | One sync write; what sync refuses (rate limit, an item over 8,192 bytes) is kept in local under `unsyncedKey` and retried with the next write. Items refused together are tried one at a time, and a held change is dropped once another computer has changed that setting since. Holding runs under a Web Lock, so two writers at once lose nothing. |
 | `retryUnsynced(storage)` | Try the held refusals again. |
+| `retryable(storage)` | Whether trying again could help (something held is still the newest and fits one sync item). |
+| `syncItemBytes(key, value)` (an export) | What Chrome Sync counts for one item: the key plus the value as Chrome's JSON writer spells it (`<` is six bytes). |
 | `changed(changes, area)` | The settings a `chrome.storage.onChanged` event touches. |
 | `normalize(raw)`, `defaults`, `localKeys`, `syncedKeys`, `unsyncedKey` | The schema. |
 
@@ -248,7 +253,7 @@ chrome.action.onClicked.addListener((tab) => openSidePanel(chrome.sidePanel, tab
 // In the panel: every frame of the tab, or why it can't be read.
 const reading = await callInTab(chrome, tabId, 'content/main.js', 'scan');
 if (reading.state === 'read') show(reading.frames); // top frame first
-else showMessage(reading.state);                   // 'browser' (Chrome's own page) or 'no-access'
+else showMessage(reading.state);                   // 'browser' (Chrome's own page), 'no-access', 'failed' or 'timeout'
 
 // In the content script: a layer the page's styles can't touch (a closed shadow root). The host's
 // own styles go in hostStyle: its inline `all: initial !important` reset beats a `:host` rule.
@@ -259,10 +264,28 @@ const { root, remove } = pageOverlay(document, {
 });
 
 // “Show on page”: boxes in DevTools' blue, kept on the elements as the page scrolls; Esc clears.
-const highlight = createHighlighter(document, { root: () => root });
+// onClear says why they went, so the panel hears of the ones it didn't ask for.
+const highlight = createHighlighter(document, {
+  root: () => root,
+  onClear: (reason) => { if (reason === 'escape' || reason === 'pagehide') chrome.runtime.sendMessage({ type: 'boxes-cleared' }); },
+});
 highlight.show(elements, { reveal: true });
+
+// In the panel: which item is shown, whatever ends it.
+const onPage = createShowOnPage({ show: (ids, frame) => callPage('highlight', [ids, frame]), onChange: press });
+button.addEventListener('click', () => onPage.toggle(font.id, [font.id], font.frameId));
+chrome.runtime.onMessage.addListener((message) => { if (message.type === 'boxes-cleared') onPage.cleared(); });
+addEventListener('pagehide', () => onPage.reset()); // and `await onPage.reset()` before a rescan
 ```
 
+A page can load a web-accessible module by the extension's address, and so tell the extension
+is installed. `"use_dynamic_url": true` stops that (the page's `import()` and `fetch()` are
+refused) and `callInPage`'s own import still works, but **only for a module with no static
+imports**: Chrome refuses a dynamic-URL module's `import … from './part.js'` (checked in Chromium
+156, `tests/chrome-chromium.test.js`). The family's page modules import their parts and the kit
+statically and have no bundler, so they are listed without it; a single-file page module (a
+bundled one) can use it.
+
 `callInPage(scripting, target, module, name, args, {immediately})` resolves to each frame's
 `{frameId, result}` (frames Chrome couldn't run in left out) and rejects when it can run in none;
 `immediately` (default true) doesn't wait for the page to be idle. `openSidePanel` sets the tab's
@@ -270,14 +293,20 @@ panel to `path?tab=<id>` (`sidePanelPath`) and opens it in the same moment: Chro
 only while the click counts. `callInTab(edges, tabId, module, name, args)` calls it in every frame
 and gives `{state: 'read', frames}` (frames that answered, top first), or `{state: 'browser'}` for
 a page Chrome keeps to itself (`isBrowserPage(url)`: its own pages, the Web Store) or
-`{state: 'no-access'}` (the tab went to another site since the click). `pageOverlay` puts a host
+`{state: 'no-access'}` (the tab went to another site since the click), `{state: 'failed', error}`
+(the page module didn't load or threw in every frame; Chrome alone reports that as null) or, with
+`{timeoutMs}`, `{state: 'timeout'}` (Chrome answers only once every frame has). `pageOverlay` puts a host
 element of its own name on the root element, replacing one a run before left; `root` is its closed
 shadow root, `css` first. The host is reset inline (`all: initial !important`) so the page can't
 move or hide it; that also beats a `:host { … }` rule and `host.style.x = …`, so the host's own
-styles go in `hostStyle` (set `!important` after the reset). `createHighlighter(doc, {root, onClear,
+styles go in `hostStyle` (set `!important` after the reset). `topLayer: true` makes the host a
+manual popover, drawn over the page's modal dialogs and fullscreen element and put back on top
+(`raise()`) when the page opens one after it; a modal dialog still makes it inert, so it shows but
+can't be clicked while the dialog is open. `createHighlighter(doc, {root, onClear,
 max})` boxes up to 500 elements (`MAX_BOXES`) in the overlay (`HIGHLIGHT_CSS` styles them), only
-those in the window, following the page as it scrolls; `show` replaces the set, `clear` or Esc
-ends it.
+those in the window, following the page as it scrolls; `show` replaces the set, `clear`, Esc or
+leaving the page ends it, and `onClear(reason)` hears which (`'replaced'`, `'asked'`, `'escape'`,
+`'pagehide'`). `createShowOnPage({show, onChange})` is the panel's side: `toggle`, `reset`, `cleared`.
 
 ```js
 // A page's elements in a line, and copying from a click (the copy command where the API can't).
@@ -294,6 +323,16 @@ can call it from a menu click or a shortcut (Chrome lets the focused active tab
 `noticeCard({icon, tone, title, text, buttons, actions})` is a side panel's notice (`.sp-notice`:
 frames from other sites to allow); `counted(count, one, many, {t, lang})` a count in words.
 
+## The right-click menu
+
+```js
+// Built on install and on browser start; after a Chrome update both come in one run, and two
+// builds side by side would create every item twice. Through the builder, one waits for the other.
+const buildMenu = contextMenuBuilder(chrome);
+chrome.runtime.onInstalled.addListener(() => buildMenu(menuItems(t)));
+chrome.runtime.onStartup.addListener(() => buildMenu(menuItems(t)));
+```
+
 ## A content script on every site
 
 ```js
@@ -334,6 +373,34 @@ first session after Chrome starts can take ~18 s while the model loads: a questi
 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.
 
+A base session Chrome has let go since (the model was updated, its process ended) is made again
+when its `clone()` fails.
+
+**In a service worker.** Chrome's documentation says the Prompt API isn't in workers; Chrome 157
+and Chromium 156 do have `LanguageModel` in an extension's service worker (checked in both, with
+an unpacked extension: `'function'` in the worker, an extension page and an offscreen document).
+Since neither is promised, a worker uses `createHostedModelSession`: the same `ModelSession`,
+asking the worker's own `LanguageModel` when there is one and otherwise the extension's offscreen
+document, over `chrome.runtime` messages.
+
+```js
+// background.js
+const words = createHostedModelSession({
+  name: 'words', options: ENGLISH, initialPrompts: [{ role: 'system', content: 'You list words.' }],
+  runtime: chrome.runtime,
+  open: () => watchFromOffscreen(chrome, undefined, 'Reads light or dark mode for the toolbar icon, and runs Chrome’s on-device model.'),
+});
+
+// offscreen/offscreen.js: the one offscreen document an extension gets does both jobs.
+watchSchemeOffscreen(chrome.runtime);
+serveModelOffscreen(chrome.runtime);
+```
+
+The document is told each session's options and instructions with the request, keeps one base
+session per `name`, keeps the time limit, and stops an answer when the caller's signal aborts. It
+ignores requests from content scripts and other extensions. The schema for an answer crosses as
+JSON (an object, not a RegExp).
+
 `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:
@@ -385,7 +452,9 @@ hands the main thread back whenever a slice has run its time, so a 2,000-item li
 freezes. `eachInSlices(items, work, {sliceMs, pause})` does the same for any list (each element's
 style read, each text measured): `work(item, index)`. `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
+default 6) whose children changed is handed over whole; what changes inside the extension's own
+elements (`ignore`, asked of a change's target and its ancestors) sets nothing off. `inSlices` cuts
+the page as the work goes and leaves out scripts, styles and templates. Both are pure DOM, so a content script
 imports them directly (list them in `web_accessible_resources`).
 
 `renderedElements(doc, {skip, limit})` (`content/elements.js`) lists every element Chrome draws,
@@ -439,7 +508,10 @@ It opens modally over its button, as Chrome's does (its top at the button's top,
 button's end), moved to stay 8px inside the window. A click outside, Esc, Tab or the window losing
 focus closes it; ↑/↓ (wrapping, past disabled items), Home and End move; focus goes back to the
 button (or `focusTo`); an item runs once the menu has closed. `createMenu({id, placement: 'below'})`
-opens it below the button instead. `menuPosition` and `isInside` are the pure geometry.
+opens it below the button instead. `menuPosition` and `isInside` are the pure geometry. In a
+content script, give it the overlay's shadow root (`createMenu({root})`, a closed one too): the
+keys it handles don't reach the page's own shortcuts, and `destroy()` takes it off the page with
+its window listener. On a right-to-left page it lines up with its button's other edge.
 
 `moreActionsButton(name, options)` is the 32px ⋮ icon button, labelled "More actions for “name”"
 (`label` for a translation), with `aria-haspopup="menu"`; its icon is the stylesheet's
@@ -578,16 +650,16 @@ except those listed, each with a reason:
 
 | Export | What it does |
 |---|---|
-| `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. |
+| `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, a destroyed session that answers nothing more, a download refused without a click (`userActivation`); `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`, each point checked against Chromium: values as Chrome stores them (`undefined`, functions and `NaN` dropped, a `Date` is `{}`), `get` with a key, keys, defaults or nothing, `clear`, `getBytesInUse`, `onChanged` (the area's own too, `removeListener`) for real changes only, whatever order an object's keys come in. Sync's quotas with Chrome's own errors: 8,192 bytes an item counted as Chrome counts them (`syncItemBytes`), 102,400 bytes (`SYNC_QUOTA_BYTES`) and 512 items (`SYNC_MAX_ITEMS`) in all, 120 calls a minute and 1,800 an hour (`SYNC_WRITES_PER_MINUTE`, `SYNC_WRITES_PER_HOUR`) of each of `set`, `remove` and `clear`; local and session hold 10 MB (`LOCAL_QUOTA_BYTES`). `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. |
+| `messageLookup(extensionDir, locale)`, `readMessages(extensionDir, locale)` | `chrome.i18n.getMessage` over the real `_locales`, as Chromium answers: a locale over en, names in any case, named placeholders and `$1`–`$9` filled, `$$` a dollar sign; a message naming a placeholder it doesn't define throws (Chrome won't load that extension). For unit tests. |
 | `heartbeat(page)` | A timer beating in a page: `stop()` gives the longest the main thread was held (ms), for performance checks. |
-| `playPermissionPrompt(answers)` | Chrome's permission prompt played in a page (`page.evaluate` or `addInitScript`): each request recorded on `window.asked` with whether a click was behind it, answered from `answers`. |
-| `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. |
+| `playPermissionPrompt(answers)` | Chrome's permission prompt played in a page (`page.evaluate` or `addInitScript`): each request recorded on `window.asked` with whether a click was behind it, answered from `answers`; one with no click behind it is refused, as Chrome refuses it. |
+| `checkRunner({timeout})` | Named checks that report and go on: `check(name, fn, {timeout})`, `fail(name)` for an error found outside a check, `finish()` (exits 1 on a failure, or when no check ran at all). 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. |
 | `closeOnSignal(close)` | On Ctrl-C or a kill, close the run's browsers, then exit. |
@@ -599,16 +671,21 @@ except those listed, each with a reason:
 | `until(fn, what, timeout?)` | Poll until truthy. |
 | `offscreenEmulator(cdp)` | Emulate light/dark inside the offscreen document. |
 | `recordIconCalls(worker)` | Record `chrome.action.setIcon` calls Chrome accepted. |
+| `stopWorker(launched, {start})` | Stop the service worker as Chrome does when it's idle (memory gone, storage kept) and start it again, or leave it for the next event: for checks that state survives a restart. Playwright's debugger otherwise keeps the worker alive for the whole run. |
 | `installWarnings(worker, manifest)` | Chrome's own install warnings for a manifest (`chrome.management.getPermissionWarningsByManifest`, no permission needed), from a loaded extension's worker. |
 | `warningsAddedBy(worker, manifest, names)` | `{warnings, without, added}`: the warnings with and without some permissions, and those only they bring (`withoutPermissions` is the pure part). |
 | `savedTabGroups(profile)` | Chrome's saved tab groups (`{title, pinned, urls}`) read from a closed profile's `Sync Data/LevelDB`: no extension API lists them. |
 | `parseLiveOptions(argv, env, {usage})`, `parseProxy(address)` | A live checker's command line (`--only`, `--category`, `--concurrency`, `--proxy` or `HTTPS_PROXY`, `--locale`, `--timezone`, `--out`, `--help`), and a proxy address for Playwright with its password hidden for the output. |
-| `runLiveCheck({chromium, build, prefix, root, sites, categories, pageMs, visit, failed, onResult})`, `liveUsage(categories, n)` | A live checker's whole run: its command line (`parseLiveOptions`, usage from the categories), the sites chosen, the exit point printed, each site visited on a fresh page in a browser with the extension (one a slot, at most 4, passing for a person's), within `pageMs` (a browser whose page ran out of time replaced), Ctrl-C closing them all; `{dir, started, finished, exit, browser, results}` for the checker's report. |
+| `runLiveCheck({chromium, build, prefix, root, sites, categories, pageMs, visit, failed, onResult})`, `liveUsage(categories, n)` | A live checker's whole run: its command line (`parseLiveOptions`, usage from the categories), the sites chosen, the exit point printed, each site visited on a fresh page in a browser with the extension (one a slot, at most 4, passing for a person's), within `pageMs` (a browser whose page ran out of time replaced), Ctrl-C closing them all; `{dir, started, finished, exit, browser, results}` for the checker's report. A visit that throws, runs out of time or loses its browser is `failed(site, why)` and the run goes on with a new browser. The report folder is emptied only if the kit made it (`reportFolder`, `REPORT_MARKER`): `--out` on a folder with other files in it is refused. |
 | `exitPoint(request)` | Where the run's traffic leaves for the internet (`{ip, country, where, source}`), from a keyless lookup service through the context's proxy: sites decide what to show by it. |
-| `filesUnder`, `zipEntries`, `missingReferences`, `manifestReferences` | For a packaging test: the zip is the folder, and every path the extension names resolves (a `#fragment` or `?query` ignored: `referencedPath`). |
+| `filesUnder`, `zipEntries`, `missingReferences`, `manifestReferences` | For a packaging test: the zip is the folder, and every path the extension names is a file the zip holds (one left out of the zip is as missing as one that isn't there): imports (`from`, `import()`, a bare `import './x.js'`), `getURL`, `src`/`href`, a stylesheet's `url()` and `@import`, and the manifest's worker, pages, icons, content scripts, default locale's messages, rule files and web-accessible resources. A `#fragment` or `?query` is ignored (`referencedPath`). |
 
 ## Stylesheet classes
 
+The stylesheet uses logical properties (and mirrors the few things that need it: a select's arrow,
+the switch's knob, the link-row arrow, the drawer), so a page with `dir="rtl"` reads as Chrome's
+own pages do in a right-to-left language.
+
 | Piece | Markup |
 |---|---|
 | Page column (680px, 96%) | `<main class="page">` |

package/bin/extension-kit.js

@@ -6,7 +6,8 @@
  *   extension-kit vendor <dir> <package> <path>...  copy files of an installed package into <dir>
  *                                                   (a path ending in / copies its contents)
  *   extension-kit vendor-check [dir]                fail when a copy in [dir] (default extension/vendor)
- *                                                   no longer matches the installed package
+ *                                                   no longer matches the installed package (another
+ *                                                   version, other files, edited since), or there's none
  *   extension-kit icons [dir]                       render [dir]/icon.svg (default extension/icons)
  *   extension-kit toolbar-icons [dir]               render the toolbar glyph (default extension/icons/toolbar)
  *   extension-kit duplication                       fail on copied code jscpd finds, less .jscpd-allowlist.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.10.0",
+  "version": "1.11.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",

package/src/ai/host.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 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 type { InitialPrompt, LanguageModelOptions, LanguageModelStatic, ModelSession } 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 declare 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 declare const HOST_GRACE_MS = 1000;
+export type HostRequest = {
+    /**
+     * The message type.
+     */
+    type: typeof MODEL_HOST;
+    /**
+     * What's asked.
+     */
+    method: 'availability' | 'ask' | 'abort' | 'release';
+    /**
+     * The session's name (one base session each).
+     */
+    name: string;
+    /**
+     * What its sessions are made with.
+     */
+    options?: LanguageModelOptions;
+    /**
+     * Its instructions and examples.
+     */
+    initialPrompts?: InitialPrompt[];
+    /**
+     * A question's id, for `abort`.
+     */
+    id?: string;
+    /**
+     * The question.
+     */
+    prompt?: string;
+    /**
+     * Its time limit.
+     */
+    timeoutMs?: number;
+    /**
+     * The answer's JSON Schema.
+     */
+    responseConstraint?: object;
+};
+export type HostSender = {
+    sendMessage(message: unknown): Promise<unknown>;
+};
+export type HostRuntime = {
+    /**
+     * This extension's id: requests from anyone else are ignored.
+     */
+    id: string;
+    /**
+     *   `chrome.runtime.onMessage`.
+     */
+    onMessage: {
+        addListener(listener: (message: unknown, sender: {
+            id?: string;
+            tab?: unknown;
+        }, respond: (answer: unknown) => void) => boolean): void;
+    };
+};
+export type HostedSessionSetup = {
+    /**
+     * The session's name, its own among the extension's sessions ('topics').
+     */
+    name: string;
+    /**
+     * What sessions are made (and availability asked) with.
+     */
+    options: LanguageModelOptions;
+    /**
+     * The instructions and examples every question starts from.
+     */
+    initialPrompts?: InitialPrompt[];
+    /**
+     * `chrome.runtime`.
+     */
+    runtime: HostSender;
+    /**
+     * Makes sure the offscreen document is open
+     * (`() => watchFromOffscreen(chrome)`); only called when the worker has no Prompt API.
+     */
+    open: () => Promise<unknown>;
+    /**
+     * The worker's own Prompt API, read when used.
+     * Default Chrome's.
+     */
+    model?: () => LanguageModelStatic | undefined;
+};
+/**
+ * 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 declare function createHostedModelSession({ name, options, initialPrompts, runtime, open, model }: HostedSessionSetup): ModelSession;
+/**
+ * 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 declare function serveModelOffscreen(runtime: HostRuntime, { model }?: {
+    model?: () => LanguageModelStatic | undefined;
+}): void;

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;
+  });
+}