@arraypress/extension-kit 1.10.0 → 1.11.1

package/src/testing/package.d.ts

@@ -1,7 +1,7 @@
 /**
  * Helpers for an extension's packaging test: list the folder, list the real
  * zip of it, and find every path the extension names that doesn't resolve to
- * a file inside it (a broken import, a stylesheet link, a manifest entry).
+ * a file the zip holds (a broken import, a stylesheet link, a manifest entry).
  *
  * @module testing/package
  */
@@ -33,6 +33,10 @@ export type ManifestFiles = {
     options_ui?: {
         page?: string;
     };
+    /**
+     * The options page, the older way.
+     */
+    options_page?: string;
     /**
      * The popup and toolbar icon.
      */
@@ -56,6 +60,39 @@ export type ManifestFiles = {
     web_accessible_resources?: {
         resources: string[];
     }[];
+    /**
+     * Scripts and styles Chrome puts in pages.
+     */
+    content_scripts?: {
+        js?: string[];
+        css?: string[];
+    }[];
+    /**
+     * The locale whose `_locales/<locale>/messages.json` must be there.
+     */
+    default_locale?: string;
+    /**
+     * Rule files.
+     */
+    declarative_net_request?: {
+        rule_resources?: {
+            path: string;
+        }[];
+    };
+    /**
+     * Pages that replace Chrome's (the new tab page).
+     */
+    chrome_url_overrides?: Record<string, string>;
+    /**
+     * The DevTools page.
+     */
+    devtools_page?: string;
+    /**
+     * Sandboxed pages.
+     */
+    sandbox?: {
+        pages?: string[];
+    };
 };
 /**
  * The parts of a manifest that name files.
@@ -63,16 +100,25 @@ export type ManifestFiles = {
  * @typedef {object} ManifestFiles
  * @property {{service_worker?: string}} [background] The worker.
  * @property {{page?: string}} [options_ui] The options page.
+ * @property {string} [options_page] The options page, the older way.
  * @property {{default_popup?: string, default_icon?: string | Record<string, string>}} [action] The popup and toolbar icon.
  * @property {{default_path?: string}} [side_panel] The side panel.
  * @property {Record<string, string>} [icons] The extension's icons.
  * @property {{resources: string[]}[]} [web_accessible_resources] Files pages may load.
+ * @property {{js?: string[], css?: string[]}[]} [content_scripts] Scripts and styles Chrome puts in pages.
+ * @property {string} [default_locale] The locale whose `_locales/<locale>/messages.json` must be there.
+ * @property {{rule_resources?: {path: string}[]}} [declarative_net_request] Rule files.
+ * @property {Record<string, string>} [chrome_url_overrides] Pages that replace Chrome's (the new tab page).
+ * @property {string} [devtools_page] The DevTools page.
+ * @property {{pages?: string[]}} [sandbox] Sandboxed pages.
  */
 /**
  * The paths a manifest names, from the extension's root.
  *
  * @param {ManifestFiles} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
+ * @returns {string[]} Worker, pages, icons, side panel, content scripts and their styles, the default
+ *   locale's messages, rule files, overridden and DevTools pages, and web-accessible resources
+ *   (less patterns with `*`).
  */
 export declare function manifestReferences(manifest: ManifestFiles): string[];
 /**
@@ -84,11 +130,14 @@ export declare function manifestReferences(manifest: ManifestFiles): string[];
  */
 export declare function referencedPath(reference: string): string;
 /**
- * Every path the extension names that isn't a file inside it: relative
- * imports in its scripts, `chrome.runtime.getURL('…')` paths, `src`/`href`
- * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
- * or `?query` is ignored: `getURL('options.html#workspaces')` names
- * `options.html`.
+ * Every path the extension names that isn't a file it ships: relative imports in its scripts
+ * (`from`, `import()` and a bare `import './x.js'`), `chrome.runtime.getURL('…')` paths,
+ * `src`/`href` in its pages, `url(…)` and `@import` in its stylesheets, the manifest's entries
+ * ({@link manifestReferences}), and any `extra` paths. A file that's there but left out of the
+ * zip (`shipsFile`: an SVG under `icons/`, a declaration, a vendor stamp) is as missing as one
+ * that isn't: the store build won't have it. A `#fragment` or `?query` is ignored:
+ * `getURL('options.html#workspaces')` names `options.html`. A path starting `/` is from the
+ * extension's root. Files that don't ship aren't read.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).

package/src/testing/package.js

@@ -1,7 +1,7 @@
 /**
  * Helpers for an extension's packaging test: list the folder, list the real
  * zip of it, and find every path the extension names that doesn't resolve to
- * a file inside it (a broken import, a stylesheet link, a manifest entry).
+ * a file the zip holds (a broken import, a stylesheet link, a manifest entry).
  *
  * @module testing/package
  */
@@ -11,7 +11,7 @@ import { existsSync } from 'node:fs';
 import { mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { zipExtension } from '../build/zip.js';
+import { shipsFile, zipExtension } from '../build/zip.js';
 
 /**
  * Every file under `dir`.
@@ -49,27 +49,43 @@ export async function zipEntries(from, exclude) {
  * @typedef {object} ManifestFiles
  * @property {{service_worker?: string}} [background] The worker.
  * @property {{page?: string}} [options_ui] The options page.
+ * @property {string} [options_page] The options page, the older way.
  * @property {{default_popup?: string, default_icon?: string | Record<string, string>}} [action] The popup and toolbar icon.
  * @property {{default_path?: string}} [side_panel] The side panel.
  * @property {Record<string, string>} [icons] The extension's icons.
  * @property {{resources: string[]}[]} [web_accessible_resources] Files pages may load.
+ * @property {{js?: string[], css?: string[]}[]} [content_scripts] Scripts and styles Chrome puts in pages.
+ * @property {string} [default_locale] The locale whose `_locales/<locale>/messages.json` must be there.
+ * @property {{rule_resources?: {path: string}[]}} [declarative_net_request] Rule files.
+ * @property {Record<string, string>} [chrome_url_overrides] Pages that replace Chrome's (the new tab page).
+ * @property {string} [devtools_page] The DevTools page.
+ * @property {{pages?: string[]}} [sandbox] Sandboxed pages.
  */
 
 /**
  * The paths a manifest names, from the extension's root.
  *
  * @param {ManifestFiles} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
+ * @returns {string[]} Worker, pages, icons, side panel, content scripts and their styles, the default
+ *   locale's messages, rule files, overridden and DevTools pages, and web-accessible resources
+ *   (less patterns with `*`).
  */
 export function manifestReferences(manifest) {
   const icon = manifest.action?.default_icon;
   return [
     manifest.background?.service_worker,
     manifest.options_ui?.page,
+    manifest.options_page,
     manifest.action?.default_popup,
     manifest.side_panel?.default_path,
+    manifest.devtools_page,
     ...Object.values(manifest.icons ?? {}),
     ...(typeof icon === 'string' ? [icon] : Object.values(icon ?? {})),
+    ...(manifest.content_scripts ?? []).flatMap((entry) => [...(entry.js ?? []), ...(entry.css ?? [])]),
+    ...(manifest.default_locale ? [`_locales/${manifest.default_locale}/messages.json`] : []),
+    ...(manifest.declarative_net_request?.rule_resources ?? []).map((entry) => entry.path),
+    ...Object.values(manifest.chrome_url_overrides ?? {}),
+    ...(manifest.sandbox?.pages ?? []),
     ...(manifest.web_accessible_resources ?? []).flatMap((entry) => entry.resources),
   ].filter((ref) => typeof ref === 'string').filter((ref) => !ref.includes('*'));
 }
@@ -88,12 +104,27 @@ export function referencedPath(reference) {
 /** A reference with a scheme (`https:`, `data:`, `mailto:`) or protocol-relative: not a file of the extension. */
 const ELSEWHERE = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i;
 
+/** A module a script imports: `… from './x.js'`, `import('./x.js')`, or `import './x.js'` alone on its line; either quote. */
+const IMPORTS = [/(?:from|import\()\s*(['"])(\.{1,2}\/[^'"]+)\1/g, /^\s*import\s*(['"])(\.{1,2}\/[^'"]+)\1/gm];
+
+/** `getURL('…')`, either quote. */
+const GET_URL = /getURL\(\s*(['"])([^'"]+)\1\s*\)/g;
+
+/** A page's `src="…"` or `href="…"`, either quote. */
+const ATTRIBUTES = /\s(?:src|href)\s*=\s*(['"])([^'"]+)\1/g;
+
+/** A stylesheet's `url(…)` and `@import "…"`. */
+const STYLE_URLS = [/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, /@import\s+(['"])([^'"]+)\1/g];
+
 /**
- * Every path the extension names that isn't a file inside it: relative
- * imports in its scripts, `chrome.runtime.getURL('…')` paths, `src`/`href`
- * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
- * or `?query` is ignored: `getURL('options.html#workspaces')` names
- * `options.html`.
+ * Every path the extension names that isn't a file it ships: relative imports in its scripts
+ * (`from`, `import()` and a bare `import './x.js'`), `chrome.runtime.getURL('…')` paths,
+ * `src`/`href` in its pages, `url(…)` and `@import` in its stylesheets, the manifest's entries
+ * ({@link manifestReferences}), and any `extra` paths. A file that's there but left out of the
+ * zip (`shipsFile`: an SVG under `icons/`, a declaration, a vendor stamp) is as missing as one
+ * that isn't: the store build won't have it. A `#fragment` or `?query` is ignored:
+ * `getURL('options.html#workspaces')` names `options.html`. A path starting `/` is from the
+ * extension's root. Files that don't ship aren't read.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).
@@ -107,18 +138,26 @@ export async function missingReferences(dir, extra = []) {
   const check = (from, target) => {
     const name = referencedPath(target);
     if (!name || ELSEWHERE.test(target)) return;
-    const file = path.resolve(root, from, name);
-    if (!file.startsWith(root) || !existsSync(file)) missing.push(`${from || 'root'} → ${target}`);
+    const file = name.startsWith('/') ? path.join(root, name) : path.resolve(root, from, name);
+    const inside = path.relative(root, file).split(path.sep).join('/');
+    if (inside.startsWith('..') || !existsSync(file) || !shipsFile(inside)) missing.push(`${from || 'root'} → ${target}`);
+  };
+  /** @param {string} source @param {readonly RegExp[]} patterns @param {string} from */
+  const each = (source, patterns, from) => {
+    for (const pattern of patterns) for (const match of source.matchAll(pattern)) check(from, match[2]);
   };
-  for (const file of await filesUnder(root)) {
+  for (const file of (await filesUnder(root)).filter(shipsFile)) {
     const from = path.posix.dirname(file);
-    if (file.endsWith('.js')) {
-      const source = await readFile(path.join(root, file), 'utf8');
-      for (const [, spec] of source.matchAll(/(?:from|import\()\s*'(\.{1,2}\/[^']+)'/g)) check(from, spec);
-      for (const [, ref] of source.matchAll(/getURL\('([^']+)'\)/g)) check('', ref);
-    } else if (file.endsWith('.html')) {
-      const source = await readFile(path.join(root, file), 'utf8');
-      for (const [, ref] of source.matchAll(/(?:src|href)="([^"]+)"/g)) check(from, ref);
+    const kind = path.posix.extname(file);
+    if (kind !== '.js' && kind !== '.html' && kind !== '.css') continue;
+    const source = await readFile(path.join(root, file), 'utf8');
+    if (kind === '.js') {
+      each(source, IMPORTS, from);
+      each(source, [GET_URL], '');
+    } else if (kind === '.html') {
+      each(source, [ATTRIBUTES], from);
+    } else {
+      each(source, STYLE_URLS, from);
     }
   }
   const manifest = JSON.parse(await readFile(path.join(root, 'manifest.json'), 'utf8'));

package/src/testing/prompt.d.ts

@@ -8,8 +8,10 @@
  * Stand in for Chrome's permission prompt in a page: each `chrome.permissions.request` is
  * recorded on `window.asked` (what was asked, and whether a click was behind it,
  * `navigator.userActivation.isActive`) and answered from `answers` (the next one; the last is
- * kept), as a person clicking “Allow” or “Deny” would. Runs in the page: give it to
- * `page.evaluate` or `page.addInitScript`, so it takes no closures.
+ * kept), as a person clicking “Allow” or “Deny” would. A request with no click behind it is
+ * refused as Chrome refuses it (“This function must be called during a user gesture”) and takes
+ * no answer. Runs in the page: give it to `page.evaluate` or `page.addInitScript`, so it takes
+ * no closures.
  *
  * @param {boolean[]} answers - The answers, in order.
  * @example

package/src/testing/prompt.js

@@ -9,8 +9,10 @@
  * Stand in for Chrome's permission prompt in a page: each `chrome.permissions.request` is
  * recorded on `window.asked` (what was asked, and whether a click was behind it,
  * `navigator.userActivation.isActive`) and answered from `answers` (the next one; the last is
- * kept), as a person clicking “Allow” or “Deny” would. Runs in the page: give it to
- * `page.evaluate` or `page.addInitScript`, so it takes no closures.
+ * kept), as a person clicking “Allow” or “Deny” would. A request with no click behind it is
+ * refused as Chrome refuses it (“This function must be called during a user gesture”) and takes
+ * no answer. Runs in the page: give it to `page.evaluate` or `page.addInitScript`, so it takes
+ * no closures.
  *
  * @param {boolean[]} answers - The answers, in order.
  * @example
@@ -23,7 +25,9 @@ export function playPermissionPrompt(answers) {
   const asked = [];
   Object.assign(window, { asked });
   chrome.permissions.request = /** @type {typeof chrome.permissions.request} */ (/** @type {unknown} */ (async (/** @type {chrome.permissions.Permissions} */ permissions) => {
-    asked.push({ permissions: permissions.permissions, origins: permissions.origins, gesture: navigator.userActivation.isActive });
+    const gesture = navigator.userActivation.isActive;
+    asked.push({ permissions: permissions.permissions, origins: permissions.origins, gesture });
+    if (!gesture) throw new Error('This function must be called during a user gesture');
     return answers.length > 1 ? answers.shift() : answers[0];
   }));
 }

package/src/time/pool.d.ts

@@ -13,7 +13,8 @@
  *
  * @template T
  * @param {readonly T[]} items - The items.
- * @param {number} limit - At most this many at once.
+ * @param {number} limit - At most this many at once (at least one: a limit of 0 or less, or one
+ *   that isn't a number, runs them one at a time rather than not at all).
  * @param {(item: T, slot: number, index: number) => Promise<void>} work - Deals with one item;
  *   `slot` (0 to limit − 1) is the same for everything one slot does, for per-slot resources
  *   (a browser each).

package/src/time/pool.js

@@ -14,7 +14,8 @@
  *
  * @template T
  * @param {readonly T[]} items - The items.
- * @param {number} limit - At most this many at once.
+ * @param {number} limit - At most this many at once (at least one: a limit of 0 or less, or one
+ *   that isn't a number, runs them one at a time rather than not at all).
  * @param {(item: T, slot: number, index: number) => Promise<void>} work - Deals with one item;
  *   `slot` (0 to limit − 1) is the same for everything one slot does, for per-slot resources
  *   (a browser each).
@@ -24,7 +25,8 @@
  */
 export async function eachLimited(items, limit, work) {
   let next = 0;
-  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async (_, slot) => {
+  const slots = Math.max(1, Math.floor(limit) || 1);
+  await Promise.all(Array.from({ length: Math.min(slots, items.length) }, async (_, slot) => {
     while (next < items.length) {
       const index = next;
       next += 1;

package/src/toolbar/theme.d.ts

@@ -132,9 +132,12 @@ export type OffscreenApi = {
  *
  * @param {OffscreenApi} api - `chrome.offscreen` and `chrome.runtime`.
  * @param {string} [url] - The document, from the extension's root. Default {@link OFFSCREEN_PATH}.
+ * @param {string} [justification] - What the document is for, when it does more than watch the
+ *   scheme (it answers for Chrome's on-device model too, `serveModelOffscreen`): Chrome keeps it
+ *   with the document, so it has to be the whole truth.
  * @returns {Promise<boolean>} Whether it opened one (false: already open).
  */
-export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string): Promise<boolean>;
+export declare function watchFromOffscreen({ offscreen, runtime }: OffscreenApi, url?: string, justification?: string): Promise<boolean>;
 export type ToolbarWorkerApi = {
     /**
      * `chrome.storage`.
@@ -179,9 +182,14 @@ export type ToolbarWorkerApi = {
  * worker wakes.
  *
  * @param {ToolbarWorkerApi} api - `chrome`, or a fake.
+ * @param {{url?: string, justification?: string}} [document] - The offscreen document and what
+ *   it's for, when it isn't the kit's defaults ({@link watchFromOffscreen}).
  * @returns {ToolbarTheme} The theme, for tests.
  * @example
  * // background.js
  * startToolbarTheme(chrome);
  */
-export declare function startToolbarTheme(api: ToolbarWorkerApi): ToolbarTheme;
+export declare function startToolbarTheme(api: ToolbarWorkerApi, { url, justification }?: {
+    url?: string;
+    justification?: string;
+}): ToolbarTheme;

package/src/toolbar/theme.js

@@ -116,6 +116,9 @@ export function createToolbarTheme({ storage, action, extensionId }) {
 /** @type {Promise<boolean> | null} */
 let opening = null;
 
+/** Why the offscreen document is open, as Chrome is told. */
+const SCHEME_JUSTIFICATION = 'Reads whether Chrome is in light or dark mode, to show the matching toolbar icon.';
+
 /**
  * Open the offscreen document that watches the scheme (reason MATCH_MEDIA),
  * unless it's open. It stays open: it's one small page in the extension's own
@@ -125,16 +128,19 @@ let opening = null;
  *
  * @param {OffscreenApi} api - `chrome.offscreen` and `chrome.runtime`.
  * @param {string} [url] - The document, from the extension's root. Default {@link OFFSCREEN_PATH}.
+ * @param {string} [justification] - What the document is for, when it does more than watch the
+ *   scheme (it answers for Chrome's on-device model too, `serveModelOffscreen`): Chrome keeps it
+ *   with the document, so it has to be the whole truth.
  * @returns {Promise<boolean>} Whether it opened one (false: already open).
  */
-export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH) {
+export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH, justification = SCHEME_JUSTIFICATION) {
   opening ??= (async () => {
     const open = await runtime.getContexts({ contextTypes: ['OFFSCREEN_DOCUMENT'] });
     if (open.length) return false;
     await offscreen.createDocument({
       url,
       reasons: [offscreen.Reason.MATCH_MEDIA],
-      justification: 'Reads whether Chrome is in light or dark mode, to show the matching toolbar icon.',
+      justification,
     });
     return true;
   })().finally(() => { opening = null; });
@@ -159,15 +165,17 @@ export function watchFromOffscreen({ offscreen, runtime }, url = OFFSCREEN_PATH)
  * worker wakes.
  *
  * @param {ToolbarWorkerApi} api - `chrome`, or a fake.
+ * @param {{url?: string, justification?: string}} [document] - The offscreen document and what
+ *   it's for, when it isn't the kit's defaults ({@link watchFromOffscreen}).
  * @returns {ToolbarTheme} The theme, for tests.
  * @example
  * // background.js
  * startToolbarTheme(chrome);
  */
-export function startToolbarTheme(api) {
+export function startToolbarTheme(api, { url, justification } = {}) {
   const theme = createToolbarTheme({ storage: api.storage.local, action: api.action, extensionId: api.runtime.id });
   theme.restore();
-  watchFromOffscreen(api).catch((error) => console.error('Opening the colour scheme watcher:', error));
+  watchFromOffscreen(api, url, justification).catch((error) => console.error('Opening the colour scheme watcher:', error));
   api.runtime.onMessage.addListener((message, sender) => {
     theme.onMessage(message, sender);
     return false;

package/src/ui/menu.d.ts

@@ -99,8 +99,10 @@ export type Box = {
  *
  * @param {{width: number, height: number}} size - The menu's size.
  * @param {{width: number, height: number}} viewport - The window's (`innerWidth`, `innerHeight`).
- * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below'}} where - The anchor's
- *   box, or a point; `placement` says where it goes from an anchor (default `'over'`).
+ * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below', rtl?: boolean}} where - The
+ *   anchor's box, or a point; `placement` says where it goes from an anchor (default `'over'`); `rtl`
+ *   (a right-to-left page) lines its start up with the anchor's left edge and opens leftwards from a
+ *   point, as Chrome mirrors its own.
  * @returns {{left: number, top: number}} The menu's top-left, in px.
  * @example
  * menuPosition({width: 160, height: 120}, {width: 800, height: 600}, {anchor: button.getBoundingClientRect()});
@@ -112,11 +114,12 @@ export declare function menuPosition(size: {
 }, viewport: {
     width: number;
     height: number;
-}, { anchor, x, y, placement }: {
+}, { anchor, x, y, placement, rtl }: {
     anchor?: Box;
     x?: number;
     y?: number;
     placement?: 'over' | 'below';
+    rtl?: boolean;
 }): {
     left: number;
     top: number;
@@ -163,6 +166,11 @@ export type ActionMenu = {
      * Close it, if open, and return the focus.
      */
     close: () => void;
+    /**
+     * Take it off the page and stop listening to the window (a content
+     * script's overlay being removed).
+     */
+    destroy: () => void;
 };
 /**
  * What {@link createMenu} takes.
@@ -182,6 +190,8 @@ export type ActionMenu = {
  * @property {(entries: readonly MenuEntry[], where: MenuPlace) => void} open Fill it with `entries`
  *   and open it (closing it first if it's open).
  * @property {() => void} close Close it, if open, and return the focus.
+ * @property {() => void} destroy Take it off the page and stop listening to the window (a content
+ *   script's overlay being removed).
  */
 /**
  * Make a page's action menu: one `<dialog class="menu">` that any number of

package/src/ui/menu.js

@@ -14,7 +14,7 @@
  * @module ui/menu
  */
 
-import { focusedElement, rootDocument } from '../dom/focus.js';
+import { focusedElement, focusedIn, rootDocument } from '../dom/focus.js';
 
 /** The gap kept between a menu and the window's edges, in px. */
 export const MENU_EDGE = 8;
@@ -67,19 +67,21 @@ const BELOW_GAP = 4;
  *
  * @param {{width: number, height: number}} size - The menu's size.
  * @param {{width: number, height: number}} viewport - The window's (`innerWidth`, `innerHeight`).
- * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below'}} where - The anchor's
- *   box, or a point; `placement` says where it goes from an anchor (default `'over'`).
+ * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below', rtl?: boolean}} where - The
+ *   anchor's box, or a point; `placement` says where it goes from an anchor (default `'over'`); `rtl`
+ *   (a right-to-left page) lines its start up with the anchor's left edge and opens leftwards from a
+ *   point, as Chrome mirrors its own.
  * @returns {{left: number, top: number}} The menu's top-left, in px.
  * @example
  * menuPosition({width: 160, height: 120}, {width: 800, height: 600}, {anchor: button.getBoundingClientRect()});
  * // → {left: anchor.right - 160, top: anchor.top}
  */
-export function menuPosition(size, viewport, { anchor, x = 0, y = 0, placement = 'over' }) {
+export function menuPosition(size, viewport, { anchor, x = 0, y = 0, placement = 'over', rtl = false }) {
   const { width, height } = size;
   const left = (/** @type {number} */ start) => Math.max(MENU_EDGE, Math.min(start, viewport.width - width - MENU_EDGE));
   const room = (/** @type {number} */ top) => top + height <= viewport.height - MENU_EDGE;
-  if (!anchor) return { left: left(x), top: Math.max(MENU_EDGE, room(y) ? y : y - height) };
-  const start = left(anchor.right - width);
+  if (!anchor) return { left: left(rtl ? x - width : x), top: Math.max(MENU_EDGE, room(y) ? y : y - height) };
+  const start = left(rtl ? anchor.left : anchor.right - width);
   if (placement === 'below') {
     const below = anchor.bottom + BELOW_GAP;
     return { left: start, top: Math.max(MENU_EDGE, room(below) ? below : anchor.top - height - BELOW_GAP) };
@@ -99,6 +101,20 @@ export function isInside(box, x, y) {
   return x >= box.left && x <= box.right && y >= box.top && y <= box.bottom;
 }
 
+/**
+ * The box a menu opens from: the anchor's, or, when the anchor has none (it isn't drawn: a row's
+ * buttons shown only while the row is hovered or holds the focus), its nearest ancestor's that has.
+ *
+ * @param {Element} anchor - The button that opened the menu.
+ * @returns {DOMRect | undefined} The box; undefined when nothing up to the root is drawn.
+ */
+function anchorBox(anchor) {
+  for (let at = /** @type {Element | null} */ (anchor); at; at = at.parentElement) {
+    if (at.getClientRects().length) return at.getBoundingClientRect();
+  }
+  return undefined;
+}
+
 /**
  * What {@link createMenu} takes.
  *
@@ -118,6 +134,8 @@ export function isInside(box, x, y) {
  * @property {(entries: readonly MenuEntry[], where: MenuPlace) => void} open Fill it with `entries`
  *   and open it (closing it first if it's open).
  * @property {() => void} close Close it, if open, and return the focus.
+ * @property {() => void} destroy Take it off the page and stop listening to the window (a content
+ *   script's overlay being removed).
  */
 
 /**
@@ -168,21 +186,32 @@ export function createMenu({ id, placement = 'over', root, doc = rootDocument(ro
 
   menu.addEventListener('keydown', (event) => {
     const list = items();
-    const at = list.indexOf(/** @type {HTMLButtonElement} */ (focusedElement(doc)));
+    // Asked of the menu's own root: a closed shadow root's focused element can't be seen from the document.
+    const at = list.indexOf(/** @type {HTMLButtonElement} */ (focusedIn(menu)));
     /** @param {number} index */
     const go = (index) => {
-      event.preventDefault();
+      handled();
       list[(index + list.length) % list.length]?.focus();
     };
+    /** The key is the menu's: the page under a content script's menu doesn't act on it too (its own shortcuts). */
+    const handled = () => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
     if (event.key === 'ArrowDown') go(at + 1);
     else if (event.key === 'ArrowUp') go(at < 0 ? -1 : at - 1);
     else if (event.key === 'Home') go(0);
     else if (event.key === 'End') go(-1);
     else if (event.key === 'Escape' || event.key === 'Tab') {
-      event.preventDefault();
+      handled();
       close();
     }
   });
+  // Closed any other way (the browser's own close, another script): the button no longer says it's open.
+  menu.addEventListener('close', () => {
+    expanded?.setAttribute('aria-expanded', 'false');
+    expanded = null;
+  });
   // Esc the browser handles itself (when the keydown above didn't see it).
   menu.addEventListener('cancel', (event) => {
     event.preventDefault();
@@ -219,22 +248,30 @@ export function createMenu({ id, placement = 'over', root, doc = rootDocument(ro
       if (label) menu.setAttribute('aria-label', label);
       else menu.removeAttribute('aria-label');
 
-      const active = focusedElement(doc);
+      const active = focusedIn(menu) ?? focusedElement(doc);
       returnFocus = focusTo ?? anchor ?? (active instanceof view.HTMLElement ? active : null);
       if (anchor?.hasAttribute('aria-haspopup')) {
         anchor.setAttribute('aria-expanded', 'true');
         expanded = anchor;
       }
+      // Measured before the menu opens: it takes the focus, and a button shown only while its row
+      // holds the focus (`.sp-suffix`) has no box after that, so the menu would open in the corner.
+      const from = anchor && anchorBox(anchor);
       menu.showModal();
       const { width, height } = menu.getBoundingClientRect();
       const { left, top } = menuPosition({ width, height }, { width: view.innerWidth, height: view.innerHeight }, {
-        anchor: anchor?.getBoundingClientRect(), x, y, placement,
+        anchor: from, x, y, placement, rtl: view.getComputedStyle(menu).direction === 'rtl',
       });
       menu.style.left = `${left}px`;
       menu.style.top = `${top}px`;
       items()[0]?.focus();
     },
     close,
+    destroy() {
+      shut();
+      view.removeEventListener('blur', close);
+      menu.remove();
+    },
   };
 }
 

package/src/ui/model-row.js

@@ -94,7 +94,11 @@ export function createModelRow({ status, help, download, progress }, { options,
         progress.value = loaded;
         status.textContent = t(MODEL_MESSAGES.downloading, [String(Math.round(loaded * 100))]);
       },
-    }).then(async () => show(await state()), () => show('downloadable', t(MODEL_MESSAGES.downloadFailed)));
+    }).then(
+      // The state as the code that uses it sees it; if it can't be asked (the worker didn't answer), as this page does.
+      async (here) => show(await state().catch(() => here)),
+      () => show('downloadable', t(MODEL_MESSAGES.downloadFailed)),
+    );
   });
 
   return {

package/src/ui/site-list.js

@@ -27,6 +27,7 @@
  * @module ui/site-list
  */
 
+import { focusedIn } from '../dom/focus.js';
 import { createMenu, moreActionsButton } from './menu.js';
 import { askText } from './text-dialog.js';
 import { MAX_HOST_LENGTH, siteLabel } from '../sites/sites.js';
@@ -177,9 +178,11 @@ export function createSiteList({
   form?.addEventListener('submit', async (event) => {
     event.preventDefault();
     const input = /** @type {HTMLInputElement} */ (form.querySelector('input'));
-    const site = parse(input.value);
-    if (!site) invalid?.(input.value);
-    else if (await add(site) !== false) input.value = '';
+    const typed = input.value;
+    const site = parse(typed);
+    if (!site) invalid?.(typed);
+    // Cleared only if it's still what was added: adding can wait on Chrome (a permission prompt), and the next site may be typed meanwhile.
+    else if (await add(site) !== false && input.value === typed) input.value = '';
   });
   addButton?.addEventListener('click', async () => {
     const site = await ask(w.addSite, w.add);
@@ -219,6 +222,11 @@ export function createSiteList({
 
   return {
     render(sites) {
+      // The focus stays in the list across a redraw: on the same row's button (the one after a removed
+      // row, the last after the last), or on the way to add when no row is left. Without this, the
+      // row's button a dialog or menu gave the focus back to is replaced and the focus falls to the page.
+      const focused = focusedIn(list);
+      const at = focused && list.contains(focused) ? [...list.children].findIndex((row) => row.contains(focused)) : -1;
       list.replaceChildren(...sites.map((site) => {
         const row = doc.createElement('li');
         row.className = 'row';
@@ -229,6 +237,7 @@ export function createSiteList({
         return row;
       }));
       if (empty) empty.hidden = sites.length > 0;
+      if (at >= 0) (list.children[Math.min(at, sites.length - 1)]?.querySelector('button') ?? addButton ?? form?.querySelector('input'))?.focus();
     },
   };
 }

package/src/ui/text-dialog.d.ts

@@ -4,8 +4,9 @@
  * folder's name (`askText`); several, as chrome://settings/searchEngines asks
  * for a site search (`askFields`). The action button stays disabled while a
  * field is blank or isn't valid, with the reason under that field. Enter
- * means the action button, Esc and Cancel cancel, and the focus goes back to
- * what opened it. The page needs no markup: the dialog (`#text-dialog`) is
+ * means the action button, Esc and Cancel cancel (as does the dialog being
+ * closed any other way), and the focus goes back to what opened it. A reason
+ * is announced as it appears, and its field marked invalid. The page needs no markup: the dialog (`#text-dialog`) is
  * made the first time, its fields each time it's asked.
  *
  * @module ui/text-dialog