@arraypress/extension-kit 1.9.0 → 1.11.0

package/src/ai/host.js

@@ -0,0 +1,225 @@
+/**
+ * Chrome's on-device model for a service worker, wherever Chrome puts the
+ * Prompt API. Chrome's documentation says `LanguageModel` isn't in workers
+ * (https://developer.chrome.com/docs/ai/prompt-api); Chrome 157 and Chromium
+ * 156 do have it in an extension's service worker (checked in both: an
+ * unpacked extension, `typeof LanguageModel` in the worker, an extension page
+ * and an offscreen document, `'function'` in all three). So neither is
+ * promised, and a worker that uses the model shouldn't depend on which holds:
+ * {@link createHostedModelSession} is a `ModelSession` that asks the worker's
+ * own `LanguageModel` when there is one, and otherwise the extension's
+ * offscreen document, which has a page's Prompt API and answers over
+ * `chrome.runtime` messages ({@link serveModelOffscreen}).
+ *
+ * The offscreen document is the one the worker already keeps for the toolbar
+ * glyph (an extension gets only one): its script calls both
+ * `watchSchemeOffscreen` and `serveModelOffscreen`. It's told the session's
+ * options and instructions with each request, so it needs none of the
+ * extension's own code.
+ *
+ * @module ai/host
+ */
+
+import { within } from '../time/time.js';
+import { chromeLanguageModel, createModelSession } from './model.js';
+
+/** @import { AskOptions, Availability, InitialPrompt, LanguageModelOptions, LanguageModelStatic, ModelAnswer, ModelSession } from './model.js' */
+
+/** The request's message type: `{type: MODEL_HOST, method, name, …}`. */
+export const MODEL_HOST = 'model-host';
+
+/** How long past an answer's time limit the worker waits for the offscreen document to say so itself (ms). */
+export const HOST_GRACE_MS = 1000;
+
+/** The model's states, to check an answer that came over a message. */
+const STATES = ['available', 'downloadable', 'downloading', 'unavailable', 'missing'];
+
+/** Why a question got no answer, to check the same. */
+const REASONS = ['unavailable', 'late', 'aborted', 'failed'];
+
+/**
+ * A request to the offscreen document.
+ *
+ * @typedef {object} HostRequest
+ * @property {typeof MODEL_HOST} type The message type.
+ * @property {'availability' | 'ask' | 'abort' | 'release'} method What's asked.
+ * @property {string} name The session's name (one base session each).
+ * @property {LanguageModelOptions} [options] What its sessions are made with.
+ * @property {InitialPrompt[]} [initialPrompts] Its instructions and examples.
+ * @property {string} [id] A question's id, for `abort`.
+ * @property {string} [prompt] The question.
+ * @property {number} [timeoutMs] Its time limit.
+ * @property {object} [responseConstraint] The answer's JSON Schema.
+ */
+
+/**
+ * The parts of `chrome.runtime` the worker's side uses.
+ *
+ * @typedef {{sendMessage(message: unknown): Promise<unknown>}} HostSender
+ */
+
+/**
+ * The parts of `chrome.runtime` the offscreen document's side uses.
+ *
+ * @typedef {object} HostRuntime
+ * @property {string} id This extension's id: requests from anyone else are ignored.
+ * @property {{addListener(listener: (message: unknown, sender: {id?: string, tab?: unknown}, respond: (answer: unknown) => void) => boolean): void}} onMessage
+ *   `chrome.runtime.onMessage`.
+ */
+
+/**
+ * @typedef {object} HostedSessionSetup
+ * @property {string} name The session's name, its own among the extension's sessions ('topics').
+ * @property {LanguageModelOptions} options What sessions are made (and availability asked) with.
+ * @property {InitialPrompt[]} [initialPrompts] The instructions and examples every question starts from.
+ * @property {HostSender} runtime `chrome.runtime`.
+ * @property {() => Promise<unknown>} open Makes sure the offscreen document is open
+ *   (`() => watchFromOffscreen(chrome)`); only called when the worker has no Prompt API.
+ * @property {() => LanguageModelStatic | undefined} [model] The worker's own Prompt API, read when used.
+ *   Default Chrome's.
+ */
+
+/**
+ * A model session for a service worker: the worker's own Prompt API when it
+ * has one, else the offscreen document's. The same `ModelSession` either way.
+ * An answer's JSON Schema crosses to the offscreen document as JSON, so it
+ * must be a plain object there (not a RegExp).
+ *
+ * @param {HostedSessionSetup} setup - The session, and how to reach the offscreen document.
+ * @returns {ModelSession} The session.
+ * @example
+ * // background.js
+ * const words = createHostedModelSession({
+ *   name: 'words', options: ENGLISH, initialPrompts: [{ role: 'system', content: 'You list words.' }],
+ *   runtime: chrome.runtime, open: () => watchFromOffscreen(chrome),
+ * });
+ * const { text } = await words.ask('Topic: football', { timeoutMs: 20_000 });
+ */
+export function createHostedModelSession({ name, options, initialPrompts = [], runtime, open, model = chromeLanguageModel }) {
+  const local = createModelSession({ model, options, initialPrompts });
+  let asked = 0;
+
+  /**
+   * Ask the offscreen document.
+   *
+   * @param {HostRequest['method']} method
+   * @param {Partial<HostRequest>} [more]
+   * @returns {Promise<unknown>} Its answer; rejects when there's no document to hear it.
+   */
+  const send = async (method, more = {}) => {
+    await open();
+    return runtime.sendMessage(/** @type {HostRequest} */ ({ type: MODEL_HOST, method, name, options, initialPrompts, ...more }));
+  };
+
+  return {
+    async availability() {
+      if (model()) return local.availability();
+      const state = await send('availability').catch(() => 'missing');
+      return STATES.includes(/** @type {string} */ (state)) ? /** @type {Availability} */ (state) : 'missing';
+    },
+
+    async ask(prompt, askOptions) {
+      if (model()) return local.ask(prompt, askOptions);
+      const { timeoutMs, signal, responseConstraint } = askOptions;
+      if (signal?.aborted) return { text: null, reason: 'aborted' };
+      const id = `${name}:${Date.now()}:${asked++}`;
+      const onAbort = () => { runtime.sendMessage({ type: MODEL_HOST, method: 'abort', name, id }).catch(() => {}); };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      try {
+        // The document keeps the time limit; the worker's own is for a document that never answers.
+        const answer = /** @type {Partial<ModelAnswer> | 'gone' | 'late' | undefined} */ (await within(
+          send('ask', { id, prompt, timeoutMs, ...(responseConstraint && { responseConstraint }) }).catch(() => 'gone'),
+          timeoutMs + HOST_GRACE_MS,
+          'late',
+        ));
+        if (answer === 'late') {
+          onAbort();
+          return { text: null, reason: signal?.aborted ? 'aborted' : 'late' };
+        }
+        if (answer && typeof answer === 'object') {
+          if (typeof answer.text === 'string' && answer.reason === 'answered') return { text: answer.text, reason: 'answered' };
+          if (REASONS.includes(/** @type {string} */ (answer.reason))) return { text: null, reason: /** @type {Exclude<ModelAnswer['reason'], 'answered'>} */ (answer.reason) };
+        }
+        return { text: null, reason: signal?.aborted ? 'aborted' : 'unavailable' };
+      } finally {
+        signal?.removeEventListener('abort', onAbort);
+      }
+    },
+
+    release() {
+      local.release();
+      if (!model()) runtime.sendMessage({ type: MODEL_HOST, method: 'release', name }).catch(() => {});
+    },
+  };
+}
+
+/**
+ * Answer the worker's model requests, in the offscreen document: one base
+ * session per name, made with the options and instructions the request
+ * carries (and again if they change). Requests from another extension, or
+ * from a content script (a web page's side), are ignored.
+ *
+ * @param {HostRuntime} runtime - `chrome.runtime`.
+ * @param {{model?: () => LanguageModelStatic | undefined}} [options] - The document's Prompt API. Default Chrome's.
+ * @returns {void}
+ * @example
+ * // offscreen/offscreen.js
+ * watchSchemeOffscreen(chrome.runtime);
+ * serveModelOffscreen(chrome.runtime);
+ */
+export function serveModelOffscreen(runtime, { model = chromeLanguageModel } = {}) {
+  /** Each name's session, and the setup it was made with. @type {Map<string, {setup: string, session: ModelSession}>} */
+  const sessions = new Map();
+  /** The questions being answered, to stop one. @type {Map<string, AbortController>} */
+  const asking = new Map();
+
+  /** @param {HostRequest} request @returns {ModelSession} */
+  const sessionFor = ({ name, options = {}, initialPrompts = [] }) => {
+    const setup = JSON.stringify([options, initialPrompts]);
+    const kept = sessions.get(name);
+    if (kept?.setup === setup) return kept.session;
+    kept?.session.release();
+    const session = createModelSession({ model, options, initialPrompts });
+    sessions.set(name, { setup, session });
+    return session;
+  };
+
+  /** @param {HostRequest} request @returns {Promise<unknown>} */
+  const answer = async (request) => {
+    switch (request.method) {
+      case 'availability':
+        return sessionFor(request).availability();
+      case 'ask': {
+        const stop = new AbortController();
+        const id = String(request.id);
+        asking.set(id, stop);
+        try {
+          return await sessionFor(request).ask(String(request.prompt ?? ''), /** @type {AskOptions} */ ({
+            timeoutMs: Number(request.timeoutMs) || 0,
+            signal: stop.signal,
+            ...(request.responseConstraint && { responseConstraint: request.responseConstraint }),
+          }));
+        } finally {
+          asking.delete(id);
+        }
+      }
+      case 'abort':
+        asking.get(String(request.id))?.abort();
+        return null;
+      case 'release':
+        sessions.get(request.name)?.session.release();
+        sessions.delete(request.name);
+        return null;
+      default:
+        return null;
+    }
+  };
+
+  runtime.onMessage.addListener((message, sender, respond) => {
+    const request = /** @type {HostRequest | null | undefined} */ (message);
+    if (request?.type !== MODEL_HOST || typeof request.name !== 'string') return false;
+    if (sender.id !== runtime.id || sender.tab) return false;
+    answer(request).then(respond, () => respond(null));
+    return true;
+  });
+}

package/src/ai/model.d.ts

@@ -9,7 +9,8 @@
  *   only downloads from a user gesture) and which reports progress;
  * - one base session, with the instructions and examples, is made once and
  *   kept; each question goes to a `clone()` of it, so answers don't leak into
- *   each other;
+ *   each other; a base session Chrome has let go since (it can't be cloned)
+ *   is made again;
  * - each answer has a time limit: an `AbortSignal` stops the answer once
  *   it's late, and the caller gets a reason instead of a hang;
  * - the first session after Chrome starts can take ~18 s while the model

package/src/ai/model.js

@@ -9,7 +9,8 @@
  *   only downloads from a user gesture) and which reports progress;
  * - one base session, with the instructions and examples, is made once and
  *   kept; each question goes to a `clone()` of it, so answers don't leak into
- *   each other;
+ *   each other; a base session Chrome has let go since (it can't be cloned)
+ *   is made again;
  * - each answer has a time limit: an `AbortSignal` stops the answer once
  *   it's late, and the caller gets a reason instead of a hang;
  * - the first session after Chrome starts can take ~18 s while the model
@@ -265,7 +266,14 @@ export function createModelSession({ model, options, initialPrompts = [] }) {
    * @returns {Promise<string>} The answer.
    */
   async function ask(api, prompt, signal, responseConstraint) {
-    const session = await (await baseSession(api)).clone({ signal });
+    const made = baseSession(api);
+    const kept = await made;
+    const session = await kept.clone({ signal }).catch(async (error) => {
+      if (signal.aborted) throw error;
+      // Chrome let the base session go (the model was updated, or its process ended): a new one, once.
+      if (base === made) base = null;
+      return (await baseSession(api)).clone({ signal });
+    });
     try {
       return await session.prompt(prompt, { signal, ...(responseConstraint && { responseConstraint }) });
     } finally {

package/src/build/index.d.ts

@@ -7,7 +7,8 @@
 export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
 export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
 export * as storeFrame from './store-frame.js';
-export { HOOK_FILE, TEST_BUILDS_ENV, buildTestCopy, testBuildDir } from './test-build.js';
+export { PANEL_HEADER_H, PANEL_W, contextMenuHtml, pngUrl, storeShotHtml, storeShots } from './store-shots.js';
+export { HOOK_FILE, PANEL_OPENER, TEST_BUILDS_ENV, buildTestCopy, testBuildDir } from './test-build.js';
 export { ICON_SIZES, TOOLBAR_COLORS, TOOLBAR_ICON_COLORS, TOOLBAR_ICON_SIZES, renderIcons, renderToolbarIcons, toolbarIconFile, } from './toolbar-icons.js';
 export { RUNTIME_ENTRIES, STYLESHEET, VENDOR_STAMP, checkVendored, packageDir, vendorKit, vendorPackage } from './vendor.js';
 export { ZIP_EXCLUDE, shipsFile, zipExtension } from './zip.js';

package/src/build/index.js

@@ -8,7 +8,8 @@
 export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
 export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
 export * as storeFrame from './store-frame.js';
-export { HOOK_FILE, TEST_BUILDS_ENV, buildTestCopy, testBuildDir } from './test-build.js';
+export { PANEL_HEADER_H, PANEL_W, contextMenuHtml, pngUrl, storeShotHtml, storeShots } from './store-shots.js';
+export { HOOK_FILE, PANEL_OPENER, TEST_BUILDS_ENV, buildTestCopy, testBuildDir } from './test-build.js';
 export {
   ICON_SIZES, TOOLBAR_COLORS, TOOLBAR_ICON_COLORS, TOOLBAR_ICON_SIZES, renderIcons, renderToolbarIcons, toolbarIconFile,
 } from './toolbar-icons.js';

package/src/build/store-shots.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Store screenshots for the whole family, in one style: a caption band in sentence case over
+ * Chrome's window (light theme) with the extension pinned in the toolbar, real captures inside.
+ * What headless Chrome can't capture is composed around the real extension UI, as Chrome draws
+ * it: the toolbar popup hanging from the extension's button (the popup page captured on its own),
+ * the side panel beside the page (the panel page captured on its own) and the right-click menu
+ * (drawn, with the extension's real menu titles).
+ *
+ * {@link storeShotHtml} lays one out (pure); {@link storeShots} renders them in a Playwright
+ * page at 2× and writes 1280×800 PNGs. Captures are taken at 2× too
+ * (`deviceScaleFactor: 2`) and shown at their CSS size, so text stays sharp.
+ *
+ * @module build/store-shots
+ */
+import type { Tab, Theme } from '../frame/window.js';
+import type { Geometry } from './store-frame.js';
+/** @import { Tab, Theme } from '../frame/window.js' */
+/** @import { Geometry } from './store-frame.js' */
+/** The side panel's width, as Chrome opens it (px). */
+export declare const PANEL_W = 360;
+/** The side panel's header: the extension's icon and name, and Chrome's close button (px). Capture a panel page `PANEL_HEADER_H` shorter than the content. */
+export declare const PANEL_HEADER_H = 40;
+export type MenuItem = {
+    /**
+     * Its words (none: a separator).
+     */
+    label?: string;
+    /**
+     * A 16px icon's URL (the extension's, beside its own item).
+     */
+    icon?: string;
+    /**
+     * It opens a submenu (an arrow).
+     */
+    submenu?: boolean;
+    /**
+     * The pointer is over it.
+     */
+    highlighted?: boolean;
+    /**
+     * Greyed out.
+     */
+    disabled?: boolean;
+};
+/**
+ * One row of the right-click menu.
+ *
+ * @typedef {object} MenuItem
+ * @property {string} [label] Its words (none: a separator).
+ * @property {string} [icon] A 16px icon's URL (the extension's, beside its own item).
+ * @property {boolean} [submenu] It opens a submenu (an arrow).
+ * @property {boolean} [highlighted] The pointer is over it.
+ * @property {boolean} [disabled] Greyed out.
+ */
+/**
+ * The right-click menu as macOS draws Chrome's (a native menu): rounded, translucent, 13px rows,
+ * the row under the pointer in the accent colour; a submenu beside its highlighted row. Its class
+ * names start `ctx` (the window's own styles have `.sep`, `.tab`…).
+ *
+ * @param {object} menu - What to draw.
+ * @param {number} menu.x - Its left edge, in the window's content area (px).
+ * @param {number} menu.y - Its top edge, in the content area.
+ * @param {readonly MenuItem[]} menu.items - Its rows.
+ * @param {readonly MenuItem[]} [menu.submenu] - The highlighted row's submenu.
+ * @returns {string} The HTML, positioned in the content area.
+ */
+export declare function contextMenuHtml({ x, y, items, submenu }: {
+    x: number;
+    y: number;
+    items: readonly MenuItem[];
+    submenu?: readonly MenuItem[];
+}): string;
+export type Shot = {
+    /**
+     * The caption, sentence case, a few words.
+     */
+    caption: string;
+    /**
+     * The window's tabs.
+     */
+    tabs: readonly Tab[];
+    /**
+     * The address bar's text.
+     */
+    url: string;
+    /**
+     * The start of `url` shown in full; the rest dimmed.
+     */
+    urlHost?: string;
+    /**
+     * The page's capture (a data: URL), at the content's size (less the side panel's when there's one).
+     */
+    page: string;
+    /**
+     * The popup's capture and its size: hung from the extension's toolbar button.
+     */
+    popup?: {
+        image: string;
+        width: number;
+        height: number;
+    };
+    /**
+     * The side panel's capture (`PANEL_W` wide, the content's height less `PANEL_HEADER_H`), the extension's name and icon for its header.
+     */
+    panel?: {
+        image: string;
+        title: string;
+        icon: string;
+    };
+    /**
+     * A right-click menu over the page.
+     */
+    menu?: Parameters<typeof contextMenuHtml>[0];
+    /**
+     * The mouse pointer, in the content area.
+     */
+    pointer?: {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * One store screenshot.
+ *
+ * @typedef {object} Shot
+ * @property {string} caption The caption, sentence case, a few words.
+ * @property {readonly Tab[]} tabs The window's tabs.
+ * @property {string} url The address bar's text.
+ * @property {string} [urlHost] The start of `url` shown in full; the rest dimmed.
+ * @property {string} page The page's capture (a data: URL), at the content's size (less the side panel's when there's one).
+ * @property {{image: string, width: number, height: number}} [popup] The popup's capture and its size: hung from the extension's toolbar button.
+ * @property {{image: string, title: string, icon: string}} [panel] The side panel's capture (`PANEL_W` wide, the content's height less `PANEL_HEADER_H`), the extension's name and icon for its header.
+ * @property {Parameters<typeof contextMenuHtml>[0]} [menu] A right-click menu over the page.
+ * @property {{x: number, y: number}} [pointer] The mouse pointer, in the content area.
+ */
+/**
+ * The HTML of one store screenshot: the caption, Chrome's window with the extension's toolbar
+ * button, and the captures; a popup hangs from the button (shown pressed), a side panel sits at
+ * the window's right, a menu over the page.
+ *
+ * @param {Shot & {toolbarIcon: string, theme?: Theme, geo?: Geometry}} shot - What to draw; the extension's toolbar icon (a data: URL).
+ * @returns {string} A whole HTML document, {@link W}×{@link H}.
+ */
+export declare function storeShotHtml({ caption, tabs, url, urlHost, page, popup, panel, menu, pointer, toolbarIcon, theme, geo }: Shot & {
+    toolbarIcon: string;
+    theme?: Theme;
+    geo?: Geometry;
+}): string;
+/**
+ * A data: URL of a PNG.
+ *
+ * @param {Uint8Array} png - The PNG's bytes.
+ * @returns {string} The URL.
+ */
+export declare const pngUrl: (png: Uint8Array) => string;
+/**
+ * A store-screenshot writer: lays each shot out with {@link storeShotHtml} in a page of the
+ * given browser at 2×, waits for its images, and saves it as a {@link W}×{@link H} PNG.
+ *
+ * @param {object} options - Where and how.
+ * @param {import('playwright').Browser | import('playwright').BrowserContext} options.browser - A browser (or a context) to draw in.
+ * @param {string} options.dir - The folder to write to (made if missing).
+ * @param {string} options.toolbarIcon - The extension's toolbar icon, a data: URL.
+ * @returns {{geo: Geometry, shoot: (file: string, shot: Shot) => Promise<string>}} The window's geometry
+ *   (capture pages at `geo.content`), and `shoot`, which writes one and returns its path.
+ * @example
+ * const { geo, shoot } = storeShots({ browser, dir: 'store/screenshots', toolbarIcon });
+ * await shoot('1-menu.png', { caption: 'Copy any page as Markdown', tabs, url, page: pngUrl(await page.screenshot()) });
+ */
+export declare function storeShots({ browser, dir, toolbarIcon }: {
+    browser: import('playwright').Browser | import('playwright').BrowserContext;
+    dir: string;
+    toolbarIcon: string;
+}): {
+    geo: Geometry;
+    shoot: (file: string, shot: Shot) => Promise<string>;
+};

package/src/build/store-shots.js

@@ -0,0 +1,173 @@
+/**
+ * Store screenshots for the whole family, in one style: a caption band in sentence case over
+ * Chrome's window (light theme) with the extension pinned in the toolbar, real captures inside.
+ * What headless Chrome can't capture is composed around the real extension UI, as Chrome draws
+ * it: the toolbar popup hanging from the extension's button (the popup page captured on its own),
+ * the side panel beside the page (the panel page captured on its own) and the right-click menu
+ * (drawn, with the extension's real menu titles).
+ *
+ * {@link storeShotHtml} lays one out (pure); {@link storeShots} renders them in a Playwright
+ * page at 2× and writes 1280×800 PNGs. Captures are taken at 2× too
+ * (`deviceScaleFactor: 2`) and shown at their CSS size, so text stays sharp.
+ *
+ * @module build/store-shots
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { esc } from '../frame/window.js';
+import { H, W, WIN, canvas, cursor, geometry, windowChrome } from './store-frame.js';
+
+/** @import { Tab, Theme } from '../frame/window.js' */
+/** @import { Geometry } from './store-frame.js' */
+
+/** The side panel's width, as Chrome opens it (px). */
+export const PANEL_W = 360;
+
+/** The side panel's header: the extension's icon and name, and Chrome's close button (px). Capture a panel page `PANEL_HEADER_H` shorter than the content. */
+export const PANEL_HEADER_H = 40;
+
+/**
+ * One row of the right-click menu.
+ *
+ * @typedef {object} MenuItem
+ * @property {string} [label] Its words (none: a separator).
+ * @property {string} [icon] A 16px icon's URL (the extension's, beside its own item).
+ * @property {boolean} [submenu] It opens a submenu (an arrow).
+ * @property {boolean} [highlighted] The pointer is over it.
+ * @property {boolean} [disabled] Greyed out.
+ */
+
+/**
+ * The right-click menu as macOS draws Chrome's (a native menu): rounded, translucent, 13px rows,
+ * the row under the pointer in the accent colour; a submenu beside its highlighted row. Its class
+ * names start `ctx` (the window's own styles have `.sep`, `.tab`…).
+ *
+ * @param {object} menu - What to draw.
+ * @param {number} menu.x - Its left edge, in the window's content area (px).
+ * @param {number} menu.y - Its top edge, in the content area.
+ * @param {readonly MenuItem[]} menu.items - Its rows.
+ * @param {readonly MenuItem[]} [menu.submenu] - The highlighted row's submenu.
+ * @returns {string} The HTML, positioned in the content area.
+ */
+export function contextMenuHtml({ x, y, items, submenu }) {
+  /** @param {readonly MenuItem[]} rows @returns {string} */
+  const list = (rows) => rows.map((row) => (row.label === undefined
+    ? '<div class="ctx-sep"></div>'
+    : `<div class="ctx-row${row.highlighted ? ' on' : ''}${row.disabled ? ' off' : ''}"><span class="ctx-ic">${row.icon ? `<img src="${row.icon}" width="16" height="16" alt="">` : ''}</span><span class="ctx-label">${esc(row.label)}</span>${row.submenu ? '<span class="ctx-arrow">›</span>' : ''}</div>`)).join('');
+  const at = items.findIndex((row) => row.highlighted && row.submenu);
+  const top = (/** @type {number} */ index) => 5 + items.slice(0, index).reduce((sum, row) => sum + (row.label === undefined ? 11 : 22), 0);
+  return `<div class="ctx" style="left:${x}px;top:${y}px">${list(items)}</div>`
+    + (submenu && at >= 0 ? `<div class="ctx" style="left:${x + 236}px;top:${y + top(at) - 5}px">${list(submenu)}</div>` : '')
+    + `<style>
+      .ctx { position: absolute; z-index: 10; width: 240px; box-sizing: border-box; padding: 5px; border-radius: 10px; background: rgba(246,246,246,.96);
+        box-shadow: 0 0 0 .5px rgba(0,0,0,.22), 0 10px 30px rgba(0,0,0,.22); font: 13px/22px system-ui; color: #1d1d1f; }
+      .ctx-row { display: flex; align-items: center; height: 22px; padding: 0 8px 0 4px; border-radius: 5px; white-space: nowrap; }
+      .ctx-row.on { background: #0a82ff; color: #fff; }
+      .ctx-row.off { color: #b0b0b0; }
+      .ctx-ic { width: 22px; flex: none; display: flex; }
+      .ctx-label { flex: 1; overflow: hidden; text-overflow: ellipsis; }
+      .ctx-arrow { flex: none; font-size: 15px; opacity: .7; }
+      .ctx-sep { height: 1px; margin: 5px 8px; background: rgba(0,0,0,.11); }
+    </style>`;
+}
+
+/**
+ * One store screenshot.
+ *
+ * @typedef {object} Shot
+ * @property {string} caption The caption, sentence case, a few words.
+ * @property {readonly Tab[]} tabs The window's tabs.
+ * @property {string} url The address bar's text.
+ * @property {string} [urlHost] The start of `url` shown in full; the rest dimmed.
+ * @property {string} page The page's capture (a data: URL), at the content's size (less the side panel's when there's one).
+ * @property {{image: string, width: number, height: number}} [popup] The popup's capture and its size: hung from the extension's toolbar button.
+ * @property {{image: string, title: string, icon: string}} [panel] The side panel's capture (`PANEL_W` wide, the content's height less `PANEL_HEADER_H`), the extension's name and icon for its header.
+ * @property {Parameters<typeof contextMenuHtml>[0]} [menu] A right-click menu over the page.
+ * @property {{x: number, y: number}} [pointer] The mouse pointer, in the content area.
+ */
+
+/**
+ * The HTML of one store screenshot: the caption, Chrome's window with the extension's toolbar
+ * button, and the captures; a popup hangs from the button (shown pressed), a side panel sits at
+ * the window's right, a menu over the page.
+ *
+ * @param {Shot & {toolbarIcon: string, theme?: Theme, geo?: Geometry}} shot - What to draw; the extension's toolbar icon (a data: URL).
+ * @returns {string} A whole HTML document, {@link W}×{@link H}.
+ */
+export function storeShotHtml({ caption, tabs, url, urlHost, page, popup, panel, menu, pointer, toolbarIcon, theme = 'light', geo = geometry(1) }) {
+  const { width: cw, height: ch } = geo.content;
+  const pageW = panel ? cw - PANEL_W : cw;
+  const content = `<div style="position:relative;display:flex;width:${cw}px;height:${ch}px">
+    <img src="${page}" width="${pageW}" height="${ch}" alt="" style="display:block;flex:none">
+    ${panel ? `<div class="panel"><div class="panel-head"><img src="${panel.icon}" width="16" height="16" alt=""><span>${esc(panel.title)}</span><svg viewBox="0 0 24 24" width="18" height="18"><path fill="#474747" d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg></div>
+      <img src="${panel.image}" width="${PANEL_W}" height="${ch - PANEL_HEADER_H}" alt="" style="display:block"></div>` : ''}
+    ${menu ? contextMenuHtml(menu) : ''}
+    ${pointer ? cursor(pointer.x, pointer.y) : ''}
+  </div>
+  <style>
+    .panel { flex: none; width: ${PANEL_W}px; height: ${ch}px; background: #fff; border-left: 1px solid #d3d7dc; box-sizing: content-box; }
+    .panel-head { height: ${PANEL_HEADER_H}px; display: flex; align-items: center; gap: 10px; padding: 0 12px 0 14px; font: 500 13px system-ui; color: #1f1f1f; }
+    .panel-head span { flex: 1; }
+  </style>`;
+  const overlays = popup ? `<div class="popup" style="width:${popup.width}px;height:${popup.height}px"><img src="${popup.image}" width="${popup.width}" height="${popup.height}" alt=""></div>
+  <style>
+    .popup { position: absolute; z-index: 30; border-radius: 10px; overflow: hidden; background: #fff; box-shadow: 0 0 0 .5px rgba(0,0,0,.2), 0 4px 12px rgba(0,0,0,.14), 0 12px 32px rgba(0,0,0,.16); }
+    .popup img { display: block; }
+    .toolbar > img.pressed { border-radius: 50%; background: #e3e3e3; box-shadow: 0 0 0 9px #e3e3e3; }
+  </style>
+  <script>
+    // Hang the popup from the extension's button, as Chrome does: its right edge near the button's, just under the toolbar.
+    const button = document.querySelector('.toolbar > img');
+    button.classList.add('pressed');
+    const box = button.getBoundingClientRect();
+    const popupBox = document.querySelector('.popup');
+    popupBox.style.left = (box.right + 14 - ${popup.width}) + 'px';
+    popupBox.style.top = (${WIN.y + WIN.strip + WIN.toolbar} - 2) + 'px';
+  </script>` : '';
+  return canvas({ caption: esc(caption), theme, chrome: windowChrome({ tabs, url, urlHost, theme, w: geo.w, ext: [toolbarIcon] }), content, overlays, geo });
+}
+
+/**
+ * A data: URL of a PNG.
+ *
+ * @param {Uint8Array} png - The PNG's bytes.
+ * @returns {string} The URL.
+ */
+export const pngUrl = (png) => `data:image/png;base64,${Buffer.from(png).toString('base64')}`;
+
+/**
+ * A store-screenshot writer: lays each shot out with {@link storeShotHtml} in a page of the
+ * given browser at 2×, waits for its images, and saves it as a {@link W}×{@link H} PNG.
+ *
+ * @param {object} options - Where and how.
+ * @param {import('playwright').Browser | import('playwright').BrowserContext} options.browser - A browser (or a context) to draw in.
+ * @param {string} options.dir - The folder to write to (made if missing).
+ * @param {string} options.toolbarIcon - The extension's toolbar icon, a data: URL.
+ * @returns {{geo: Geometry, shoot: (file: string, shot: Shot) => Promise<string>}} The window's geometry
+ *   (capture pages at `geo.content`), and `shoot`, which writes one and returns its path.
+ * @example
+ * const { geo, shoot } = storeShots({ browser, dir: 'store/screenshots', toolbarIcon });
+ * await shoot('1-menu.png', { caption: 'Copy any page as Markdown', tabs, url, page: pngUrl(await page.screenshot()) });
+ */
+export function storeShots({ browser, dir, toolbarIcon }) {
+  const geo = geometry(1);
+  return {
+    geo,
+    shoot: async (file, shot) => {
+      const context = 'newContext' in browser ? await browser.newContext({ viewport: { width: W, height: H }, deviceScaleFactor: 2 }) : null;
+      const page = context ? await context.newPage() : await /** @type {import('playwright').BrowserContext} */ (browser).newPage();
+      try {
+        await page.setViewportSize({ width: W, height: H });
+        await page.setContent(storeShotHtml({ ...shot, toolbarIcon, geo }), { waitUntil: 'load' });
+        await page.evaluate(() => Promise.all([...document.images].map((img) => img.decode().catch(() => undefined))));
+        await mkdir(dir, { recursive: true });
+        const out = path.join(dir, file);
+        await writeFile(out, await page.screenshot({ type: 'png', scale: 'css', clip: { x: 0, y: 0, width: W, height: H } }));
+        return out;
+      } finally {
+        await (context ?? page).close();
+      }
+    },
+  };
+}

package/src/build/test-build.d.ts

@@ -54,6 +54,12 @@ export type TestBuild = {
      * Changes the copy's manifest in place.
      */
     manifest?: (manifest: TestManifest) => void;
+    /**
+     * A side panel page (`panel/panel.html`): adds {@link PANEL_OPENER}(`?tab=<id>`), whose button opens that panel beside the tab the way the toolbar click does
+     * (the kit's `openSidePanel`, during a real click), which Playwright can't click. Its title turns
+     * `opened` (or `error: …`). The kit must be vendored at `vendor/extension-kit/`.
+     */
+    panelOpener?: string;
 };
 /**
  * A Chrome extension manifest, as far as a test build changes it.
@@ -70,7 +76,13 @@ export type TestBuild = {
  *   imports the real worker and exposes what a test can't reach headlessly (a menu click, the
  *   toolbar button).
  * @property {(manifest: TestManifest) => void} [manifest] Changes the copy's manifest in place.
+ * @property {string} [panelOpener] A side panel page (`panel/panel.html`): adds {@link PANEL_OPENER}
+ *   (`?tab=<id>`), whose button opens that panel beside the tab the way the toolbar click does
+ *   (the kit's `openSidePanel`, during a real click), which Playwright can't click. Its title turns
+ *   `opened` (or `error: …`). The kit must be vendored at `vendor/extension-kit/`.
  */
+/** The page {@link TestBuild}'s `panelOpener` adds, from the build's root. */
+export declare const PANEL_OPENER = "e2e/open-panel.html";
 /**
  * Copy an extension folder into a test build, with its own hook and manifest.
  *
@@ -82,4 +94,4 @@ export type TestBuild = {
  *   manifest: (manifest) => { manifest.host_permissions = ['http://127.0.0.1/*']; },
  * });
  */
-export declare function buildTestCopy({ from, to, hook, manifest: change }: TestBuild): Promise<string>;
+export declare function buildTestCopy({ from, to, hook, manifest: change, panelOpener }: TestBuild): Promise<string>;