@arraypress/extension-kit 1.3.0 → 1.4.0

package/README.md

@@ -159,13 +159,25 @@ be public before the store listing goes live.
 ## Page start-up
 
 ```js
-const t = setUpPage(chrome, { title: 'optionsTitle', substitutions: [name] });
+const t = setUpPage(chrome, { title: 'optionsTitle' });
 ```
 
 Reports the page's colour scheme for the toolbar glyph (`watchColorScheme`; a failure is only
 logged), fills its `data-i18n` text (`localize`), sets its title from a message, and returns the
 page's `t`.
 
+The extension's name lives in one message, `extShortName`. A message that names the extension
+takes it as a placeholder whose content is `$1`, and every lookup without substitutions (`t(key)`,
+`data-i18n`, `data-i18n-*`, the title) fills it in:
+
+```json
+"optionsAbout": { "message": "About $NAME$", "placeholders": { "name": { "content": "$1" } } }
+```
+
+```html
+<h2 class="section-title" data-i18n="optionsAbout"></h2> <!-- About Upright -->
+```
+
 ## Sites
 
 ```js
@@ -175,11 +187,22 @@ onSite(siteHost(location.href), neverSites); // on a listed site or a subdomain
 hostPatterns('github.com');                  // ['*://github.com/*', '*://*.github.com/*'] (excludeMatches)
 originPattern('https://bit.ly/x');           // 'https://bit.ly/*' (permissions.request)
 siteLabel('https://example.com');            // 'example.com', as a list shows it
+withSite(['a.com', 'b.com'], 'a.com');       // ['b.com', 'a.com'], what a list keeps after Add (also withoutSite, withSiteReplaced)
 ```
 
 A site is http or https with a dot in its host (or `localhost`); text without a scheme is https;
 `localhost:8080` is a host and port. Pure, so a content script can load `sites/sites.js` alone.
 
+## Time limits
+
+```js
+const groups = await within(chrome.tabGroups.query({}), 2000, []); // a Chrome call that may never answer
+```
+
+`within(promise, ms, fallback)`: the value in time, or the fallback (late or failed); never
+rejects; its timer cleared once the work settles (the work itself isn't stopped). In the runtime
+half, so a service worker or page can use it; the test helpers use it too.
+
 ## Page components
 
 Chrome's own components, made in the page by script (no markup to copy), styled by `chrome-ui.css`.
@@ -247,25 +270,50 @@ restarts the wait: 10 seconds, as chrome://bookmarks's (`TOAST_MS`), or `duratio
 ### Site list
 
 ```js
-// A short list with an add row (chrome://settings), the markup in the page:
-// <ul class="list" id="sites"></ul> <p class="row text" id="no-sites">…</p>
-// <form class="row add" id="add-site"><input type="text" …><button type="submit">Add</button></form>
+// Memory Saver's way (chrome://settings/performance): an Add button and the dialog, ⋮ Edit/Remove.
+// <div class="row"><span class="label secondary">…</span><button id="add-site" type="button">Add</button></div>
+// <p class="row text" id="no-sites"><span class="label">No sites added</span></p> <ul class="list" id="sites"></ul>
 const sites = createSiteList({
-  list: byId('sites'), empty: byId('no-sites'), form: byId('add-site', HTMLFormElement),
-  parse: siteOrigin,
-  add: async (origin) => (await chrome.permissions.request({ origins: [originPattern(origin)] })) && save(origin),
-  remove: (origin) => unsave(origin),
-  words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+  list: byId('sites'), empty: byId('no-sites'), addButton: byId('add-site'),
+  parse: siteHost,
+  add: (site) => save({ sites: withSite(settings.sites, site) }),
+  remove: (site) => save({ sites: withoutSite(settings.sites, site) }),
+  replace: (site, edited) => save({ sites: withSiteReplaced(settings.sites, site, edited) }),
+  t, // the page's messages, under the standard keys below
 });
 sites.render(settings.sites);
 
-// Memory Saver's way (chrome://settings/performance): an Add button and the dialog, ⋮ Edit/Remove.
-createSiteList({ list, empty, addButton: byId('add-site'), parse: siteHost, add, remove, replace: (old, edited) => … });
+// A short list with an add row (chrome://settings): `form` instead of `addButton`.
+// <form class="row add" id="add-site"><input type="text" …><button type="submit">Add</button></form>
 ```
 
-`add` resolving to false keeps the typed text (access refused); `invalid(text)` hears what isn't
-a site in the add row; the dialog keeps its Add off with “Enter a site, like example.com” under
-the field. `words` translates `SITE_LIST_WORDS`.
+`withSite` adds a site at the end, once (added again, it moves there); `withoutSite` takes it out;
+`withSiteReplaced` edits it in place, merging it with a duplicate. A list that needs site access
+asks for it in `add`/`replace` (the dialog's click still counts as the person's) and gives it back
+in `remove`. `add` resolving to false keeps the add row's text (access refused); `invalid(text)`
+hears what isn't a site in the add row; the dialog keeps its Add off with “Enter a site, like
+example.com” under the field.
+
+The words: Chrome's English (`SITE_LIST_WORDS`) without `t`; with it, the page's messages under
+these keys (`SITE_LIST_MESSAGES`), so every extension's `_locales` names them alike. `words`
+overrides only those that differ.
+
+| Word | Key | English |
+|---|---|---|
+| `add` | `optionsAdd` | Add |
+| `addSite` | `optionsAddSite` | Add site |
+| `editSite` | `optionsEditSite` | Edit site |
+| `edit` | `optionsEdit` | Edit |
+| `remove` | `optionsRemove` | Remove |
+| `save` | `optionsSave` | Save |
+| `cancel` | `optionsCancel` | Cancel |
+| `site` | `optionsSiteLabel` | Site |
+| `invalid` | `optionsSiteInvalid` | Enter a site, like example.com |
+| `moreActions` | `optionsMoreActions` | More actions for `$SITE$` (content `$1`; the ⋮ button) |
+| `removeLabel` | `optionsRemoveLabel` | Remove `$SITE$` (content `$1`; the add row's Remove button) |
+
+A list with an Add button needs every key but `optionsRemoveLabel`; one with an add row needs
+`optionsRemove` and `optionsRemoveLabel`. A locale test can check them against `SITE_LIST_MESSAGES`.
 
 ## Build helpers (`@arraypress/extension-kit/build`)
 
@@ -300,7 +348,6 @@ except those listed, each with a reason:
 | `launchExtension(chromium, dir, options)` | Load an unpacked extension into a fresh profile; `{context, worker, extensionId, url(page), profile, close()}`. |
 | `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()}`. |
 | `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. |
-| `within(promise, ms, fallback)` | The value in time, or the fallback (late or failed); never rejects; its timer cleared. |
 | `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)`. |
 | `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.3.0",
+  "version": "1.4.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.",
   "type": "module",
   "main": "src/index.js",

package/src/build/vendor.js

@@ -28,7 +28,7 @@ const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const KIT = '@arraypress/extension-kit';
 
 /** What a vendored copy of the kit holds, relative to `src/`: everything an extension page or worker may load. */
-export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'settings', 'sites', 'styles', 'toolbar', 'ui']);
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'settings', 'sites', 'styles', 'time', 'toolbar', 'ui']);
 
 /** The kit's stylesheet, an absolute path in the installed package. */
 export const STYLESHEET = path.join(SOURCE, 'styles', 'chrome-ui.css');

package/src/dom/i18n.d.ts

@@ -4,6 +4,11 @@
  * `data-i18n-<attribute>="key"` (sets that attribute, e.g.
  * `data-i18n-placeholder`, `data-i18n-aria-label`).
  *
+ * The extension's name lives in one message, `extShortName`; a message that
+ * names the extension takes it as a placeholder whose content is `$1`
+ * (`"About $NAME$"`), and every lookup made without substitutions fills it
+ * in, in markup and script alike.
+ *
  * @module dom/i18n
  */
 export type I18nApi = {
@@ -19,18 +24,21 @@ export type I18nApi = {
  */
 /**
  * A message lookup that never comes back blank: a missing key shows as
- * itself, so a typo is visible on screen instead of an empty label.
+ * itself, so a typo is visible on screen instead of an empty label. Without
+ * substitutions, `$1` is the extension's name (`extShortName`).
  *
  * @param {Pick<I18nApi, 'getMessage'>} i18n - `chrome.i18n`.
  * @returns {(key: string, substitutions?: string | string[]) => string} Looks a key up.
  * @example
  * const t = translator(chrome.i18n);
  * t('optionsVersion', ['1.0.0']); // 'Version 1.0.0'
+ * t('optionsAbout');              // 'About Upright', from "About $NAME$"
  */
 export declare function translator(i18n: Pick<I18nApi, 'getMessage'>): (key: string, substitutions?: string | string[]) => string;
 /**
- * Fill every `data-i18n*` attribute under `root`, and, for a whole document,
- * set its `lang` to Chrome's UI language.
+ * Fill every `data-i18n*` attribute under `root` (a message that names the
+ * extension gets its name), and, for a whole document, set its `lang` to
+ * Chrome's UI language.
  *
  * @param {ParentNode} root - A document or an element.
  * @param {I18nApi} i18n - `chrome.i18n`.

package/src/dom/i18n.js

@@ -4,9 +4,17 @@
  * `data-i18n-<attribute>="key"` (sets that attribute, e.g.
  * `data-i18n-placeholder`, `data-i18n-aria-label`).
  *
+ * The extension's name lives in one message, `extShortName`; a message that
+ * names the extension takes it as a placeholder whose content is `$1`
+ * (`"About $NAME$"`), and every lookup made without substitutions fills it
+ * in, in markup and script alike.
+ *
  * @module dom/i18n
  */
 
+/** The message that holds the extension's name. */
+const NAME_MESSAGE = 'extShortName';
+
 /**
  * `chrome.i18n`, as far as pages need it.
  *
@@ -17,21 +25,26 @@
 
 /**
  * A message lookup that never comes back blank: a missing key shows as
- * itself, so a typo is visible on screen instead of an empty label.
+ * itself, so a typo is visible on screen instead of an empty label. Without
+ * substitutions, `$1` is the extension's name (`extShortName`).
  *
  * @param {Pick<I18nApi, 'getMessage'>} i18n - `chrome.i18n`.
  * @returns {(key: string, substitutions?: string | string[]) => string} Looks a key up.
  * @example
  * const t = translator(chrome.i18n);
  * t('optionsVersion', ['1.0.0']); // 'Version 1.0.0'
+ * t('optionsAbout');              // 'About Upright', from "About $NAME$"
  */
 export function translator(i18n) {
-  return (key, substitutions) => i18n.getMessage(key, substitutions) || key;
+  const name = i18n.getMessage(NAME_MESSAGE);
+  const named = name ? [name] : undefined;
+  return (key, substitutions = named) => i18n.getMessage(key, substitutions) || key;
 }
 
 /**
- * Fill every `data-i18n*` attribute under `root`, and, for a whole document,
- * set its `lang` to Chrome's UI language.
+ * Fill every `data-i18n*` attribute under `root` (a message that names the
+ * extension gets its name), and, for a whole document, set its `lang` to
+ * Chrome's UI language.
  *
  * @param {ParentNode} root - A document or an element.
  * @param {I18nApi} i18n - `chrome.i18n`.

package/src/dom/setup.d.ts

@@ -13,7 +13,7 @@ export type PageSetup = {
      */
     title?: string;
     /**
-     * The title's placeholders (the extension's name).
+     * The title's placeholders. Default: the extension's name (`translator`).
      */
     substitutions?: string | string[];
     /**
@@ -32,7 +32,7 @@ export type PageSetup = {
  *
  * @typedef {object} PageSetup
  * @property {string} [title] The title's message (“optionsTitle”). Default: the title is left as it is.
- * @property {string | string[]} [substitutions] The title's placeholders (the extension's name).
+ * @property {string | string[]} [substitutions] The title's placeholders. Default: the extension's name (`translator`).
  * @property {Document} [doc] The page. Default `document`.
  * @property {SchemeMedia} [media] The scheme to report. Default the page's `matchMedia(DARK_QUERY)`.
  */
@@ -45,7 +45,8 @@ export type PageSetup = {
  * @returns {(key: string, substitutions?: string | string[]) => string} The page's message lookup
  *   (`translator(chrome.i18n)`).
  * @example
- * const t = setUpPage(chrome, { title: 'optionsTitle', substitutions: [t('extShortName')] });
+ * const t = setUpPage(chrome, { title: 'optionsTitle' }); // "$NAME$ settings": 'Upright settings'
+ * t('optionsGetHelp');                                     // "Get help with $NAME$": 'Get help with Upright'
  * // The popup, whose title Chrome doesn't show:
  * const t = setUpPage(chrome);
  */

package/src/dom/setup.js

@@ -17,7 +17,7 @@ import { DARK_QUERY, watchColorScheme } from '../toolbar/scheme.js';
  *
  * @typedef {object} PageSetup
  * @property {string} [title] The title's message (“optionsTitle”). Default: the title is left as it is.
- * @property {string | string[]} [substitutions] The title's placeholders (the extension's name).
+ * @property {string | string[]} [substitutions] The title's placeholders. Default: the extension's name (`translator`).
  * @property {Document} [doc] The page. Default `document`.
  * @property {SchemeMedia} [media] The scheme to report. Default the page's `matchMedia(DARK_QUERY)`.
  */
@@ -31,7 +31,8 @@ import { DARK_QUERY, watchColorScheme } from '../toolbar/scheme.js';
  * @returns {(key: string, substitutions?: string | string[]) => string} The page's message lookup
  *   (`translator(chrome.i18n)`).
  * @example
- * const t = setUpPage(chrome, { title: 'optionsTitle', substitutions: [t('extShortName')] });
+ * const t = setUpPage(chrome, { title: 'optionsTitle' }); // "$NAME$ settings": 'Upright settings'
+ * t('optionsGetHelp');                                     // "Get help with $NAME$": 'Get help with Upright'
  * // The popup, whose title Chrome doesn't show:
  * const t = setUpPage(chrome);
  */

package/src/index.d.ts

@@ -20,12 +20,13 @@ export { setUpPage } from './dom/setup.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
-export { MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin } from './sites/sites.js';
+export { MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite, } from './sites/sites.js';
+export { within } from './time/time.js';
 export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
 export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
 export { OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen, } from './toolbar/theme.js';
 export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
-export { createSiteList } from './ui/site-list.js';
+export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
 export { askText, checkText } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
 export type ActionMenu = import('./ui/menu.js').ActionMenu;

package/src/index.js

@@ -21,14 +21,17 @@ export { setUpPage } from './dom/setup.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
-export { MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin } from './sites/sites.js';
+export {
+  MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite,
+} from './sites/sites.js';
+export { within } from './time/time.js';
 export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
 export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
 export {
   OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen,
 } from './toolbar/theme.js';
 export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
-export { createSiteList } from './ui/site-list.js';
+export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
 export { askText, checkText } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
 

package/src/sites/sites.d.ts

@@ -3,7 +3,8 @@
  * "https://www.Example.com/shop") and as pages report them (`location.href`):
  * the origin an extension asks Chrome for access to, the host a per-site
  * on/off list keeps, whether a page is on a listed site (subdomains
- * included), and the match patterns for both. Pure.
+ * included), the match patterns for both, and a list with a site added,
+ * taken out or edited. Pure.
  *
  * A site is a web host: http or https, with a dot in its name (or
  * `localhost`). Text without a scheme is read as https.
@@ -80,3 +81,34 @@ export declare function originPattern(url: string): string;
  * siteLabel('http://example.com');  // 'http://example.com'
  */
 export declare function siteLabel(site: string): string;
+/**
+ * A site list with `site` added: at the end, once (a site added again moves
+ * there).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to add.
+ * @returns {string[]} A new list.
+ * @example
+ * withSite(['a.com', 'b.com'], 'a.com'); // ['b.com', 'a.com']
+ */
+export declare function withSite(sites: readonly string[], site: string): string[];
+/**
+ * A site list without `site`.
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to take out.
+ * @returns {string[]} A new list.
+ */
+export declare function withoutSite(sites: readonly string[], site: string): string[];
+/**
+ * A site list with `site` edited to `edited`, in its place, once (an edit
+ * to a site already listed merges the two).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site as it was.
+ * @param {string} edited - What it was edited to.
+ * @returns {string[]} A new list.
+ * @example
+ * withSiteReplaced(['a.com', 'b.com'], 'a.com', 'b.com'); // ['b.com']
+ */
+export declare function withSiteReplaced(sites: readonly string[], site: string, edited: string): string[];

package/src/sites/sites.js

@@ -3,7 +3,8 @@
  * "https://www.Example.com/shop") and as pages report them (`location.href`):
  * the origin an extension asks Chrome for access to, the host a per-site
  * on/off list keeps, whether a page is on a listed site (subdomains
- * included), and the match patterns for both. Pure.
+ * included), the match patterns for both, and a list with a site added,
+ * taken out or edited. Pure.
  *
  * A site is a web host: http or https, with a dot in its name (or
  * `localhost`). Text without a scheme is read as https.
@@ -126,3 +127,43 @@ export function originPattern(url) {
 export function siteLabel(site) {
   return site.replace(/^https:\/\//, '');
 }
+
+/**
+ * A site list with `site` added: at the end, once (a site added again moves
+ * there).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to add.
+ * @returns {string[]} A new list.
+ * @example
+ * withSite(['a.com', 'b.com'], 'a.com'); // ['b.com', 'a.com']
+ */
+export function withSite(sites, site) {
+  return [...withoutSite(sites, site), site];
+}
+
+/**
+ * A site list without `site`.
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to take out.
+ * @returns {string[]} A new list.
+ */
+export function withoutSite(sites, site) {
+  return sites.filter((s) => s !== site);
+}
+
+/**
+ * A site list with `site` edited to `edited`, in its place, once (an edit
+ * to a site already listed merges the two).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site as it was.
+ * @param {string} edited - What it was edited to.
+ * @returns {string[]} A new list.
+ * @example
+ * withSiteReplaced(['a.com', 'b.com'], 'a.com', 'b.com'); // ['b.com']
+ */
+export function withSiteReplaced(sites, site, edited) {
+  return [...new Set(sites.map((s) => (s === site ? edited : s)))];
+}

package/src/testing/browser.js

@@ -8,7 +8,7 @@
  * @module testing/browser
  */
 
-import { within } from './time.js';
+import { within } from '../time/time.js';
 
 /** @import { Browser } from 'playwright' */
 

package/src/testing/e2e.js

@@ -12,7 +12,7 @@ import assert from 'node:assert/strict';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { deadline } from './time.js';
+import { deadline } from '../time/time.js';
 
 /** @import { BrowserContext, BrowserType, CDPSession, Page, Worker } from 'playwright' */
 

package/src/testing/index.d.ts

@@ -10,7 +10,6 @@ export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until, } from './e2e.js';
 export { eachLimited } from './pool.js';
-export { within } from './time.js';
 export { serve } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';

package/src/testing/index.js

@@ -13,7 +13,6 @@ export {
   CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until,
 } from './e2e.js';
 export { eachLimited } from './pool.js';
-export { within } from './time.js';
 export { serve } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';

package/src/{testing → time}/time.d.ts

@@ -1,8 +1,9 @@
 /**
- * Time limits for tests that drive a real browser, where a page that stops
- * responding would otherwise hold a run up forever.
+ * Time limits for work that may never finish: a Chrome call a service worker
+ * shouldn't wait on forever, or, in tests that drive a real browser, a page
+ * that stops responding. Runs anywhere (worker, page, Node).
  *
- * @module testing/time
+ * @module time/time
  */
 /**
  * Settle `promise` within `ms`, or settle the way `late` says. The timer is
@@ -19,9 +20,9 @@
 export declare function deadline<T>(promise: Promise<T>, ms: number, late: (resolve: (value: T) => void, reject: (error: Error) => void) => void): Promise<T>;
 /**
  * A promise's value within a time limit, or `fallback` when it's late or
- * fails: for a step a live run should give up on and go past (a renderer
- * that stopped responding, a close that never returns). The work itself
- * isn't stopped; the timer is cleared once it settles.
+ * fails: for a step to give up on and go past (a Chrome call that never
+ * answers, a renderer that stopped responding, a close that never returns).
+ * The work itself isn't stopped; the timer is cleared once it settles.
  *
  * @template T
  * @param {Promise<T>} promise - The work.

package/src/{testing → time}/time.js

@@ -1,8 +1,9 @@
 /**
- * Time limits for tests that drive a real browser, where a page that stops
- * responding would otherwise hold a run up forever.
+ * Time limits for work that may never finish: a Chrome call a service worker
+ * shouldn't wait on forever, or, in tests that drive a real browser, a page
+ * that stops responding. Runs anywhere (worker, page, Node).
  *
- * @module testing/time
+ * @module time/time
  */
 
 /**
@@ -28,9 +29,9 @@ export function deadline(promise, ms, late) {
 
 /**
  * A promise's value within a time limit, or `fallback` when it's late or
- * fails: for a step a live run should give up on and go past (a renderer
- * that stopped responding, a close that never returns). The work itself
- * isn't stopped; the timer is cleared once it settles.
+ * fails: for a step to give up on and go past (a Chrome call that never
+ * answers, a renderer that stopped responding, a close that never returns).
+ * The work itself isn't stopped; the timer is cleared once it settles.
  *
  * @template T
  * @param {Promise<T>} promise - The work.

package/src/ui/site-list.d.ts

@@ -90,6 +90,14 @@ export type SiteListWords = {
  */
 /** @type {Readonly<SiteListWords>} */
 export declare const SITE_LIST_WORDS: Readonly<SiteListWords>;
+/**
+ * The message key each word is read from when a page passes its `t`, so
+ * every extension's `_locales` names them alike. `removeLabel` and
+ * `moreActions` take the site as `$1` (`"More actions for $SITE$"`).
+ *
+ * @type {Readonly<Record<keyof SiteListWords, string>>}
+ */
+export declare const SITE_LIST_MESSAGES: Readonly<Record<keyof SiteListWords, string>>;
 export type SiteListOptions = {
     /**
      * The `<ul class="list">` to fill.
@@ -140,7 +148,13 @@ export type SiteListOptions = {
      */
     maxLength?: number;
     /**
-     * Translations of {@link SITE_LIST_WORDS}.
+     * The page's message lookup
+     * (`setUpPage`'s): the words are then its messages under {@link SITE_LIST_MESSAGES}. Without it,
+     * Chrome's English ({@link SITE_LIST_WORDS}).
+     */
+    t?: (key: string, substitutions?: string | string[]) => string;
+    /**
+     * Words that differ from those, by name.
      */
     words?: Partial<SiteListWords>;
 };
@@ -170,7 +184,10 @@ export type SiteList = {
  * @property {(text: string) => void} [invalid] The add row: called with what was typed when it isn't a site.
  * @property {(site: string) => string} [label] How a site reads. Default {@link siteLabel}.
  * @property {number} [maxLength] The dialog field's `maxlength`. Default {@link MAX_HOST_LENGTH}.
- * @property {Partial<SiteListWords>} [words] Translations of {@link SITE_LIST_WORDS}.
+ * @property {(key: string, substitutions?: string | string[]) => string} [t] The page's message lookup
+ *   (`setUpPage`'s): the words are then its messages under {@link SITE_LIST_MESSAGES}. Without it,
+ *   Chrome's English ({@link SITE_LIST_WORDS}).
+ * @property {Partial<SiteListWords>} [words] Words that differ from those, by name.
  */
 /**
  * A site list.
@@ -190,10 +207,10 @@ export type SiteList = {
  * const never = createSiteList({
  *   list: byId('never-sites'), form: byId('add-never', HTMLFormElement), empty: byId('no-sites'),
  *   parse: siteHost,
- *   add: (host) => save({ neverSites: [...settings.neverSites, host] }),
- *   remove: (host) => save({ neverSites: settings.neverSites.filter((h) => h !== host) }),
- *   words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+ *   add: (host) => save({ neverSites: withSite(settings.neverSites, host) }),
+ *   remove: (host) => save({ neverSites: withoutSite(settings.neverSites, host) }),
+ *   t, // its words from optionsAdd, optionsRemove, …
  * });
  * never.render(settings.neverSites);
  */
-export declare function createSiteList({ list, empty, form, addButton, parse, add, remove, replace, invalid, label, maxLength, words, }: SiteListOptions): SiteList;
+export declare function createSiteList({ list, empty, form, addButton, parse, add, remove, replace, invalid, label, maxLength, t, words, }: SiteListOptions): SiteList;

package/src/ui/site-list.js

@@ -63,6 +63,43 @@ export const SITE_LIST_WORDS = Object.freeze({
   moreActions: (/** @type {string} */ label) => `More actions for “${label}”`,
 });
 
+/**
+ * The message key each word is read from when a page passes its `t`, so
+ * every extension's `_locales` names them alike. `removeLabel` and
+ * `moreActions` take the site as `$1` (`"More actions for $SITE$"`).
+ *
+ * @type {Readonly<Record<keyof SiteListWords, string>>}
+ */
+export const SITE_LIST_MESSAGES = Object.freeze({
+  add: 'optionsAdd',
+  addSite: 'optionsAddSite',
+  editSite: 'optionsEditSite',
+  edit: 'optionsEdit',
+  remove: 'optionsRemove',
+  save: 'optionsSave',
+  cancel: 'optionsCancel',
+  site: 'optionsSiteLabel',
+  invalid: 'optionsSiteInvalid',
+  removeLabel: 'optionsRemoveLabel',
+  moreActions: 'optionsMoreActions',
+});
+
+/**
+ * The list's words from a page's messages, under {@link SITE_LIST_MESSAGES}.
+ *
+ * @param {(key: string, substitutions?: string | string[]) => string} t - The page's message lookup.
+ * @returns {SiteListWords} The words.
+ */
+function translatedWords(t) {
+  const m = SITE_LIST_MESSAGES;
+  return {
+    add: t(m.add), addSite: t(m.addSite), editSite: t(m.editSite), edit: t(m.edit), remove: t(m.remove),
+    save: t(m.save), cancel: t(m.cancel), site: t(m.site), invalid: t(m.invalid),
+    removeLabel: (label) => t(m.removeLabel, [label]),
+    moreActions: (label) => t(m.moreActions, [label]),
+  };
+}
+
 /**
  * What {@link createSiteList} takes: the list, one way to add to it, and
  * what adding, removing and editing do.
@@ -83,7 +120,10 @@ export const SITE_LIST_WORDS = Object.freeze({
  * @property {(text: string) => void} [invalid] The add row: called with what was typed when it isn't a site.
  * @property {(site: string) => string} [label] How a site reads. Default {@link siteLabel}.
  * @property {number} [maxLength] The dialog field's `maxlength`. Default {@link MAX_HOST_LENGTH}.
- * @property {Partial<SiteListWords>} [words] Translations of {@link SITE_LIST_WORDS}.
+ * @property {(key: string, substitutions?: string | string[]) => string} [t] The page's message lookup
+ *   (`setUpPage`'s): the words are then its messages under {@link SITE_LIST_MESSAGES}. Without it,
+ *   Chrome's English ({@link SITE_LIST_WORDS}).
+ * @property {Partial<SiteListWords>} [words] Words that differ from those, by name.
  */
 
 /**
@@ -105,17 +145,17 @@ export const SITE_LIST_WORDS = Object.freeze({
  * const never = createSiteList({
  *   list: byId('never-sites'), form: byId('add-never', HTMLFormElement), empty: byId('no-sites'),
  *   parse: siteHost,
- *   add: (host) => save({ neverSites: [...settings.neverSites, host] }),
- *   remove: (host) => save({ neverSites: settings.neverSites.filter((h) => h !== host) }),
- *   words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+ *   add: (host) => save({ neverSites: withSite(settings.neverSites, host) }),
+ *   remove: (host) => save({ neverSites: withoutSite(settings.neverSites, host) }),
+ *   t, // its words from optionsAdd, optionsRemove, …
  * });
  * never.render(settings.neverSites);
  */
 export function createSiteList({
-  list, empty, form, addButton, parse, add, remove, replace, invalid, label = siteLabel, maxLength = MAX_HOST_LENGTH, words,
+  list, empty, form, addButton, parse, add, remove, replace, invalid, label = siteLabel, maxLength = MAX_HOST_LENGTH, t, words,
 }) {
   const doc = list.ownerDocument;
-  const w = { ...SITE_LIST_WORDS, ...words };
+  const w = { ...(t ? translatedWords(t) : SITE_LIST_WORDS), ...words };
   const menu = addButton ? createMenu({ doc }) : null;
 
   /**