@arraypress/extension-kit 1.9.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. |
 
@@ -245,16 +250,88 @@ for (const { frameId, result } of frames) show(frameId, result);
 // From the toolbar click: the tab's own side panel, panel/panel.html?tab=<id>, nothing awaited first.
 chrome.action.onClicked.addListener((tab) => openSidePanel(chrome.sidePanel, tab.id, 'panel/panel.html'));
 
-// In the content script: a layer the page's styles can't touch (a closed shadow root).
-const { root, remove } = pageOverlay(document, { name: 'my-inspector', css: ':host { position: fixed; inset: 0; pointer-events: none; }' });
+// 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), '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.
+const { root, remove } = pageOverlay(document, {
+  name: 'my-inspector',
+  hostStyle: { position: 'fixed', inset: '0', 'z-index': '2147483647', 'pointer-events': 'none' },
+  css: `${HIGHLIGHT_CSS} .card { position: absolute; }`,
+});
+
+// “Show on page”: boxes in DevTools' blue, kept on the elements as the page scrolls; Esc clears.
+// 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
 panel to `path?tab=<id>` (`sidePanelPath`) and opens it in the same moment: Chrome opens a panel
-only while the click counts. `pageOverlay` puts a host element of its own name (`all: initial`)
-on the root element, replacing one a run before left; `root` is its closed shadow root, `css` first.
+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), `{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). `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`, 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).
+row.append(make('span', 'meta', '12 colours'), iconButton({ icon: 'i-copy', label: t('copy'), onClick: () => copyFormats(document, { text: hex }) }));
+```
+
+`make(tag, className, text, doc)`, `spriteIcon(id, className, doc)` (a `<use>` of the page's
+sprite) and `iconButton({icon, label, onClick, className, doc})` (tooltip and label) take the
+document the element belongs to, so a content script's overlay uses them too.
+`copyFormats(doc, {text, html})` puts plain text and HTML on the clipboard at once (a titled link
+for rich editors, its plain text for the rest) and resolves to whether it did; a content script
+can call it from a menu click or a shortcut (Chrome lets the focused active tab write), and
+`showPageToast(doc, 'Link copied', {name})` confirms it with Chrome's own toast in the page.
+`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
 
@@ -296,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:
@@ -347,9 +452,18 @@ 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,
+in document order, into open and closed shadow roots (`shadowRootOf`, through
+`chrome.dom.openOrClosedShadowRoot`) and through `display: contents` wrappers; what's inside a
+`visibility: hidden` element is still read, nothing inside `display: none`; at most 20,000
+(`MAX_ELEMENTS`). `otherSiteFrames(doc)` gives the origins of frames from other sites, which a
+reading of the tab leaves out until the person allows those sites.
+
 ## Time limits
 
 ```js
@@ -394,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
@@ -513,9 +630,10 @@ A list with an Add button needs every key but `optionsRemoveLabel`; one with an
 | `vendorPackage(name, files, dest)`, `packageDir(name)` | Copy files of an installed package, stamped (`extension-kit vendor <dir> <package> <path>...`). |
 | `checkVendored(dir)` | The stale copies under `dir` (`extension-kit vendor-check`). |
 | `renderIcons`, `renderToolbarIcons({chromium, dir})` | See above. |
-| `buildTestCopy({from, to, hook, manifest})` | A test build: the extension, `hook` as its service worker (`e2e-hook.js`), the manifest changed. |
+| `buildTestCopy({from, to, hook, manifest, panelOpener})` | A test build: the extension, `hook` as its service worker (`e2e-hook.js`), the manifest changed; with `panelOpener` (`'panel/panel.html'`), `e2e/open-panel.html?tab=<id>` (`PANEL_OPENER`), whose button opens that side panel beside the tab as the toolbar click does (Playwright can't click the toolbar; its title turns `opened`). |
 | `testBuildDir(root, name)` | `.test-builds/<name>`, or under `$EXTENSION_TEST_BUILDS` (to test another build, or run two side by side). |
 | `storeFrame` | Store screenshots: `canvas`, `windowChrome` (and `windowChromeSvg`, from `frame/window.js`), `geometry`, `letterIcon`, `cursor`, `THEMES`, `W`×`H`. |
+| `storeShots({browser, dir, toolbarIcon})`, `storeShotHtml(shot)`, `contextMenuHtml(menu)`, `pngUrl(png)`, `PANEL_W`, `PANEL_HEADER_H` | The family's store screenshots in one style: a caption in sentence case over Chrome's light window with the extension pinned in the toolbar, real captures (taken at 2×) inside; what headless Chrome can't capture composed around the real extension UI: the popup page hung from the pressed toolbar button, the side panel page beside the page under a header with the extension's name, the right-click menu drawn as macOS draws Chrome's (the extension's real titles). `shoot(file, shot)` writes a 1280×800 PNG. |
 | `placeholderWarning`, `repositoryReminder`, `printReleaseChecks` | See About links. |
 | `findDisallowedClones({runJscpd})` | Run jscpd and return clones `.jscpd-allowlist.json` doesn't cover (the `extension-kit duplication` command). |
 
@@ -532,33 +650,42 @@ 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. |
 | `testBuildDir(root, name)` | As in `/build`, for the tests that load the build. |
+| `tabIdOf(worker, page)` | A Playwright page's tab id, as the extension's worker sees it. |
+| `callTabModule(worker, tabId, module, name, args)` | An export of the extension's page module called in a tab's frames, as `callInPage` does: `[{frameId, result}]`. |
+| `pierceNodes(cdp)`, `nodeAttribute(node, name)`, `nodeText(node)` | A page's whole tree through the DevTools protocol, closed shadow roots and frames included (where an extension's overlay is), and a node's attribute and text. |
 | `serve(routes, {port, tls})` | Serve test pages on 127.0.0.1 from a table, a `Map` or a function of the path; `{origin, port, server, close()}`. With `tls` (`testCertificate()`, a throwaway one from `openssl`), over HTTPS: for a site Chrome reaches only over HTTPS, mapped with `--host-resolver-rules`, Chromium started with `--ignore-certificate-errors`. |
 | `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. 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.9.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;