@arraypress/extension-kit 1.7.0 → 1.8.0

package/README.md

@@ -13,6 +13,8 @@ The pieces ArrayPress's Chrome extensions share, so each is written once:
 - **Chrome's page components**: the ⋮ action menu and its row button, the text dialog
   ("Rename folder", or several fields as "Add site search"), the toast with Undo and a settings card's site list, built on the
   stylesheet's classes; they work in a content script's shadow root too.
+- **Chrome's window around a capture**: the tab strip and toolbar, light or dark, as HTML for store
+  screenshots and as an SVG image an extension page draws on a canvas.
 - **Sites**: what people type into a per-site list, and whether a page is on one.
 - **Chrome's on-device model** (Gemini Nano, the Prompt API): availability, a download from the
   person's click with progress, one base session with a `clone()` per question, a time limit on
@@ -108,6 +110,8 @@ chrome.storage.onChanged.addListener((changes, area) => {
 const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
 saver.save({ menuStyle: 'full' });
 addEventListener('pagehide', () => saver.flush());
+// Changed in another tab or on another computer: shown, with this page's unwritten changes over it.
+saver.follow((settings) => show(settings), chrome.storage.onChanged);
 ```
 
 | Store member | What it does |
@@ -183,6 +187,25 @@ takes it as a placeholder whose content is `$1`, and every lookup without substi
 <h2 class="section-title" data-i18n="optionsAbout"></h2> <!-- About Upright -->
 ```
 
+## Chrome's window around a capture
+
+```js
+import { WINDOW_BARS, letterIcon, windowChromeSvg } from '../vendor/extension-kit/index.js';
+
+const svg = windowChromeSvg({ tabs: [{ title: 'Example', icon: letterIcon('E', '#1a73e8'), active: true }], url: 'example.com/a', theme: 'dark', w: 1280 });
+const bars = new Image();
+bars.src = `data:image/svg+xml,${encodeURIComponent(svg)}`;
+await bars.decode();
+context.drawImage(bars, 0, 0, 1280 * scale, (WINDOW_BARS.strip + WINDOW_BARS.toolbar) * scale); // the capture goes below
+```
+
+The same macOS window the store screenshots use (`storeFrame.windowChrome`, now `frame/window.js`
+in the runtime half): `windowChrome(options)` is its HTML, `windowChromeSvg(options)` that HTML in
+an SVG image `w` wide and `WINDOW_BARS.strip + WINDOW_BARS.toolbar` (88px) high, drawn sharp at any
+scale. Chrome draws an SVG image with HTML inside (`foreignObject`) without tainting the canvas
+(checked in Chromium, `tests/frame-chromium.test.js`). Images in it must be `data:` URLs
+(`letterIcon` makes one). `THEMES` holds the light and dark colours.
+
 ## Sites
 
 ```js
@@ -456,7 +479,7 @@ A list with an Add button needs every key but `optionsRemoveLabel`; one with an
 | `renderIcons`, `renderToolbarIcons({chromium, dir})` | See above. |
 | `buildTestCopy({from, to, hook, manifest})` | A test build: the extension, `hook` as its service worker (`e2e-hook.js`), the manifest changed. |
 | `testBuildDir(root, name)` | `.test-builds/<name>`, or under `$EXTENSION_TEST_BUILDS` (to test another build, or run two side by side). |
-| `storeFrame` | Store screenshots: `canvas`, `windowChrome`, `geometry`, `letterIcon`, `cursor`, `THEMES`, `W`×`H`. |
+| `storeFrame` | Store screenshots: `canvas`, `windowChrome` (and `windowChromeSvg`, from `frame/window.js`), `geometry`, `letterIcon`, `cursor`, `THEMES`, `W`×`H`. |
 | `placeholderWarning`, `repositoryReminder`, `printReleaseChecks` | See About links. |
 | `findDisallowedClones({runJscpd})` | Run jscpd and return clones `.jscpd-allowlist.json` doesn't cover (the `extension-kit duplication` command). |
 
@@ -480,6 +503,8 @@ except those listed, each with a reason:
 | `extensionProfile(chromium, dir, options)` | A profile to start the browser on more than once (a restart, a first start with a changed manifest): `{dir, launch(), remove()}`. |
 | `runChecks(runner, body, cleanUps)` | A script's checks: an error outside any check fails, the clean-ups always run (each within 30 s), then the tally. |
 | `messageLookup(extensionDir, locale)`, `readMessages(extensionDir, locale)` | `chrome.i18n.getMessage` over the real `_locales` (a locale over en, named placeholders filled), for unit tests. |
+| `heartbeat(page)` | A timer beating in a page: `stop()` gives the longest the main thread was held (ms), for performance checks. |
+| `playPermissionPrompt(answers)` | Chrome's permission prompt played in a page (`page.evaluate` or `addInitScript`): each request recorded on `window.asked` with whether a click was behind it, answered from `answers`. |
 | `checkRunner({timeout})` | Named checks that report and go on: `check(name, fn, {timeout})`, `fail(name)` for an error found outside a check, `finish()`. A check that runs past its limit (`CHECK_MS`, 60 s) fails, and the run goes on. |
 | `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)` (also in the main entry). |
 | `realisticBrowser(options)`, `chromeUserAgent(browser)` | Launch options and a user agent for a browser that doesn't say it's automated, for live checks. |
@@ -543,7 +568,7 @@ chrome://bookmarks in Chromium 156 / Chrome 157; the sources are listed at the t
 ## Development
 
 `npm test` runs ESLint, a strict TypeScript check of the JSDoc (`checkJs`), the tests (the menu,
-the dialog, the toast, the dialog site list, icon rendering and the Chrome readers in Playwright's
+the dialog, the toast, the dialog site list, the window frame, icon rendering and the Chrome readers in Playwright's
 Chromium, the rest in Node and jsdom), and the
 copied-code guard. The `.d.ts` files are generated from the JSDoc: `npm run types` writes them, and
 the type check fails while one is stale (it regenerates them into `.types/` and compares).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Shared pieces for Chrome extensions: Chrome's own page styles and components, a Chrome Sync settings store, the light/dark toolbar glyph, Chrome's on-device model, content-script helpers, About links, and build and test helpers.",
   "type": "module",
   "main": "src/index.js",

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

@@ -10,19 +10,27 @@
  * Playwright at `geometry(zoom).content`, then screenshot `canvas({caption, chrome:
  * windowChrome({tabs, url}), content})` at {@link W}×{@link H}.
  *
+ * The window itself is `frame/window.js`, in the runtime half, so an extension page can draw it
+ * around a capture too; it's re-exported here.
+ *
  * @module build/store-frame
  */
+export { THEMES, letterIcon, windowChrome, windowChromeSvg } from '../frame/window.js';
+export type Theme = import('../frame/window.js').Theme;
+export type Tab = import('../frame/window.js').Tab;
+/** @typedef {import('../frame/window.js').Theme} Theme */
+/** @typedef {import('../frame/window.js').Tab} Tab */
 /** The store screenshot's width. */
 export declare const W = 1280;
 /** The store screenshot's height. */
 export declare const H = 800;
 /** Where the window sits: its left edge, top edge, full width, and tab strip and toolbar heights. */
 export declare const WIN: {
+    strip: 42;
+    toolbar: 46;
     x: number;
     y: number;
     w: number;
-    strip: number;
-    toolbar: number;
 };
 export type Geometry = {
     /**
@@ -57,95 +65,6 @@ export type Geometry = {
  * @returns {Geometry} The window's unscaled width and the size to capture page content at.
  */
 export declare function geometry(zoom?: number): Geometry;
-/**
- * A letter favicon for made-up sites (no real brands).
- *
- * @param {string} letter - The letter.
- * @param {string} bg - Background colour.
- * @param {string} [fg] - Letter colour. Default white.
- * @returns {string} A data: URL of the SVG.
- */
-export declare const letterIcon: (letter: string, bg: string, fg?: string) => string;
-/** Chrome's light and dark window colours, and the canvas behind. */
-export declare const THEMES: {
-    light: {
-        bg: string;
-        caption: string;
-        sub: string;
-        frame: string;
-        tabText: string;
-        tabTextInactive: string;
-        tabSep: string;
-        activeTab: string;
-        toolbar: string;
-        toolbarIcon: string;
-        omnibox: string;
-        url: string;
-        urlDim: string;
-        contentLine: string;
-        shadow: string;
-    };
-    dark: {
-        bg: string;
-        caption: string;
-        sub: string;
-        frame: string;
-        tabText: string;
-        tabTextInactive: string;
-        tabSep: string;
-        activeTab: string;
-        toolbar: string;
-        toolbarIcon: string;
-        omnibox: string;
-        url: string;
-        urlDim: string;
-        contentLine: string;
-        shadow: string;
-    };
-};
-export type Theme = keyof typeof THEMES;
-export type Tab = {
-    /**
-     * Its title.
-     */
-    title: string;
-    /**
-     * Its favicon's URL.
-     */
-    icon: string;
-    /**
-     * The selected tab.
-     */
-    active?: boolean;
-    /**
-     * Playing sound.
-     */
-    audible?: boolean;
-    /**
-     * Muted.
-     */
-    muted?: boolean;
-};
-/**
- * The window's tab strip and toolbar, as HTML. Positions are window-relative.
- *
- * @param {object} options - What to draw.
- * @param {readonly Tab[]} options.tabs - The tabs, left to right.
- * @param {string} options.url - The address bar's text.
- * @param {string} [options.urlHost] - The start of `url` to show in full; the rest is dimmed.
- * @param {Theme} [options.theme] - Default light.
- * @param {number} [options.w] - The window's width. Default the full window.
- * @param {readonly string[]} [options.ext] - Toolbar extension icons' URLs.
- * @returns {string} The HTML, with its own styles.
- */
-export declare function windowChrome({ tabs, url, urlHost, theme, w, ext }: {
-    tabs: readonly Tab[];
-    url: string;
-    urlHost?: string;
-    theme?: Theme;
-    w?: number;
-    ext?: readonly string[];
-}): string;
 /**
  * The macOS arrow pointer.
  *

package/src/build/store-frame.js

@@ -10,16 +10,26 @@
  * Playwright at `geometry(zoom).content`, then screenshot `canvas({caption, chrome:
  * windowChrome({tabs, url}), content})` at {@link W}×{@link H}.
  *
+ * The window itself is `frame/window.js`, in the runtime half, so an extension page can draw it
+ * around a capture too; it's re-exported here.
+ *
  * @module build/store-frame
  */
 
+import { THEMES, WINDOW_BARS, WINDOW_W } from '../frame/window.js';
+
+export { THEMES, letterIcon, windowChrome, windowChromeSvg } from '../frame/window.js';
+
+/** @typedef {import('../frame/window.js').Theme} Theme */
+/** @typedef {import('../frame/window.js').Tab} Tab */
+
 /** The store screenshot's width. */
 export const W = 1280;
 /** The store screenshot's height. */
 export const H = 800;
 const CAPTION_H = 112;
 /** Where the window sits: its left edge, top edge, full width, and tab strip and toolbar heights. */
-export const WIN = { x: 64, y: CAPTION_H, w: 1152, strip: 42, toolbar: 46 };
+export const WIN = { x: 64, y: CAPTION_H, w: WINDOW_W, ...WINDOW_BARS };
 
 /**
  * How a shot's window is laid out.
@@ -42,164 +52,6 @@ export function geometry(zoom = 1) {
   return { zoom, w, content: { width: w, height: Math.round((H - WIN.y) / zoom) - WIN.strip - WIN.toolbar } };
 }
 
-/**
- * @param {unknown} s - Text.
- * @returns {string} It, escaped for HTML text and attributes.
- */
-const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-
-/** Material icon paths (24×24). */
-const P = {
-  back: 'M20 11H7.83l5.59-5.59L12 4l-8 8 8 8 1.41-1.41L7.83 13H20v-2z',
-  forward: 'M12 4l-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z',
-  reload: 'M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z',
-  close: 'M19 6.41L17.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',
-  add: 'M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z',
-  more: 'M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2zm0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z',
-  puzzle: 'M20.5 11H19V7c0-1.1-.9-2-2-2h-4V3.5C13 2.12 11.88 1 10.5 1S8 2.12 8 3.5V5H4c-1.1 0-1.99.9-1.99 2v3.8H3.5c1.49 0 2.7 1.21 2.7 2.7s-1.21 2.7-2.7 2.7H2V20c0 1.1.9 2 2 2h3.8v-1.5c0-1.49 1.21-2.7 2.7-2.7 1.49 0 2.7 1.21 2.7 2.7V22H17c1.1 0 2-.9 2-2v-4h1.5c1.38 0 2.5-1.12 2.5-2.5S21.88 11 20.5 11z',
-  star: 'M22 9.24l-7.19-.62L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21 12 17.27 18.18 21l-1.63-7.03L22 9.24zM12 15.4l-3.76 2.27 1-4.28-3.32-2.88 4.38-.38L12 6.1l1.71 4.04 4.38.38-3.32 2.88 1 4.28L12 15.4z',
-  tune: 'M3 17v2h6v-2H3zM3 5v2h10V5H3zm10 16v-2h8v-2h-8v-2h-2v6h2zM7 9v2H3v2h4v2h2V9H7zm14 4v-2H11v2h10zm-6-4h2V7h4V5h-4V3h-2v6z',
-  sound: 'M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02zM14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.85-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77z',
-  muted: 'M16.5 12c0-1.77-1.02-3.29-2.5-4.03v2.21l2.45 2.45c.03-.2.05-.41.05-.63zm2.5 0c0 .94-.2 1.82-.54 2.64l1.51 1.51C20.63 14.91 21 13.5 21 12c0-4.28-2.99-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71zM4.27 3L3 4.27 7.73 9H3v6h4l5 5v-6.73l4.25 4.25c-.67.52-1.42.93-2.25 1.18v2.06c1.38-.31 2.63-.95 3.69-1.81L19.73 21 21 19.73l-9-9L4.27 3zM12 4L9.91 6.09 12 8.18V4z',
-  person: 'M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z',
-};
-
-/**
- * A Material icon as inline SVG, in the text colour.
- *
- * @param {keyof typeof P} name - Which icon.
- * @param {number} [size] - Width and height in px. Default 20.
- * @returns {string} The SVG markup.
- */
-const icon = (name, size = 20) =>
-  `<svg viewBox="0 0 24 24" width="${size}" height="${size}"><path fill="currentColor" d="${P[name]}"/></svg>`;
-
-/**
- * A letter favicon for made-up sites (no real brands).
- *
- * @param {string} letter - The letter.
- * @param {string} bg - Background colour.
- * @param {string} [fg] - Letter colour. Default white.
- * @returns {string} A data: URL of the SVG.
- */
-export const letterIcon = (letter, bg, fg = '#fff') =>
-  `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><rect width="16" height="16" rx="4" fill="${bg}"/><text x="8" y="12" font-family="-apple-system,Helvetica,Arial" font-size="11" font-weight="700" text-anchor="middle" fill="${fg}">${letter}</text></svg>`)}`;
-
-/** Chrome's light and dark window colours, and the canvas behind. */
-export const THEMES = {
-  light: {
-    bg: '#eef2f8', caption: '#1f1f1f', sub: '#444746',
-    frame: '#dde3ea', tabText: '#1f1f1f', tabTextInactive: '#474747', tabSep: '#a8afb8', activeTab: '#ffffff',
-    toolbar: '#ffffff', toolbarIcon: '#474747', omnibox: '#e9eef6', url: '#1f1f1f', urlDim: '#5e5e5e',
-    contentLine: '#d3d7dc', shadow: '0 24px 60px rgba(31,45,70,.20), 0 0 0 .5px rgba(0,0,0,.18)',
-  },
-  dark: {
-    bg: '#1b1c1f', caption: '#e3e3e3', sub: '#c4c7c5',
-    frame: '#1f1f1f', tabText: '#e3e3e3', tabTextInactive: '#c7c7c7', tabSep: '#5f6368', activeTab: '#3c3c3c',
-    toolbar: '#3c3c3c', toolbarIcon: '#c7c7c7', omnibox: '#282828', url: '#e3e3e3', urlDim: '#a8a8a8',
-    contentLine: '#2a2a2a', shadow: '0 24px 60px rgba(0,0,0,.55), 0 0 0 .5px rgba(255,255,255,.14)',
-  },
-};
-
-/** @typedef {keyof typeof THEMES} Theme */
-
-/**
- * One tab in the drawn window.
- *
- * @typedef {object} Tab
- * @property {string} title Its title.
- * @property {string} icon Its favicon's URL.
- * @property {boolean} [active] The selected tab.
- * @property {boolean} [audible] Playing sound.
- * @property {boolean} [muted] Muted.
- */
-
-const TAB_H = 34;
-
-/**
- * Lay out tabs like Chrome: equal widths up to 240px, shrinking to fit.
- *
- * @param {readonly Tab[]} tabs - The tabs.
- * @param {number} w - The window's width.
- * @returns {{ x: number, width: number }[]} Each tab's window-relative x and width.
- */
-function tabLayout(tabs, w) {
-  const left = 84;
-  const right = 60;
-  const max = 240;
-  const avail = w - left - right - 36;
-  const width = Math.min(max, Math.floor(avail / tabs.length));
-  return tabs.map((_, i) => ({ x: left + i * width, width }));
-}
-
-/**
- * The window's tab strip and toolbar, as HTML. Positions are window-relative.
- *
- * @param {object} options - What to draw.
- * @param {readonly Tab[]} options.tabs - The tabs, left to right.
- * @param {string} options.url - The address bar's text.
- * @param {string} [options.urlHost] - The start of `url` to show in full; the rest is dimmed.
- * @param {Theme} [options.theme] - Default light.
- * @param {number} [options.w] - The window's width. Default the full window.
- * @param {readonly string[]} [options.ext] - Toolbar extension icons' URLs.
- * @returns {string} The HTML, with its own styles.
- */
-export function windowChrome({ tabs, url, urlHost, theme = 'light', w = WIN.w, ext = [] }) {
-  const t = THEMES[theme];
-  const layout = tabLayout(tabs, w);
-  const tabHtml = tabs.map((tab, i) => {
-    const { x, width } = layout[i];
-    const sepAfter = i < tabs.length - 1 && !tab.active && !tabs[i + 1].active;
-    const alert = tab.muted ? icon('muted', 16) : tab.audible ? icon('sound', 16) : '';
-    const showClose = tab.active || width >= 120;
-    return `<div class="tab${tab.active ? ' active' : ''}" style="left:${x}px;width:${width}px">
-      <img class="fav" src="${tab.icon}" width="16" height="16" alt="">
-      <span class="title">${esc(tab.title)}</span>
-      ${alert ? `<span class="alert">${alert}</span>` : ''}
-      ${showClose ? `<span class="x">${icon('close', 14)}</span>` : ''}
-    </div>${sepAfter ? `<span class="sep" style="left:${x + width - 1}px"></span>` : ''}`;
-  }).join('');
-  const last = layout[layout.length - 1];
-  const plusX = last.x + last.width + 4;
-  const extIcons = ext.map((src) => `<img src="${src}" width="16" height="16" alt="" style="margin:0 9px">`).join('');
-  return `
-  <div class="strip">
-    <span class="lights"><i style="background:#ff5f57"></i><i style="background:#febc2e"></i><i style="background:#28c840"></i></span>
-    ${tabHtml}
-    <span class="plus" style="left:${plusX}px">${icon('add', 18)}</span>
-  </div>
-  <div class="toolbar">
-    <span class="tb">${icon('back')}</span><span class="tb dim">${icon('forward')}</span><span class="tb">${icon('reload')}</span>
-    <div class="omni"><span class="site">${icon('tune', 16)}</span><span class="url">${urlHost ? `${esc(urlHost)}<span class="dim">${esc(url.slice(urlHost.length))}</span>` : esc(url)}</span><span class="star">${icon('star', 18)}</span></div>
-    ${extIcons}<span class="tb">${icon('puzzle')}</span>
-    <span class="avatar">${icon('person', 18)}</span><span class="tb">${icon('more')}</span>
-  </div>
-  <style>
-    .strip { position: relative; height: ${WIN.strip}px; background: ${t.frame}; }
-    .lights { position: absolute; left: 16px; top: 15px; display: flex; gap: 8px; }
-    .lights i { width: 12px; height: 12px; border-radius: 50%; display: block; box-shadow: inset 0 0 0 .5px rgba(0,0,0,.12); }
-    .tab { position: absolute; bottom: 0; height: ${TAB_H}px; display: flex; align-items: center; gap: 8px; padding: 0 10px 0 14px; box-sizing: border-box; color: ${t.tabTextInactive}; font: 12px/16px system-ui; }
-    .tab.active { background: ${t.activeTab}; color: ${t.tabText}; border-radius: 10px 10px 0 0; z-index: 1; }
-    .tab.active::before, .tab.active::after { content: ''; position: absolute; bottom: 0; width: 10px; height: 10px; }
-    .tab.active::before { left: -10px; background: radial-gradient(circle at 0 0, transparent 10px, ${t.activeTab} 10.5px); }
-    .tab.active::after { right: -10px; background: radial-gradient(circle at 100% 0, transparent 10px, ${t.activeTab} 10.5px); }
-    .tab .fav { flex: none; }
-    .tab .title { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; -webkit-mask-image: linear-gradient(90deg, #000 calc(100% - 18px), transparent); }
-    .tab .alert, .tab .x { flex: none; display: flex; color: ${t.toolbarIcon}; }
-    .sep { position: absolute; bottom: 9px; width: 1px; height: 18px; background: ${t.tabSep}; }
-    .plus { position: absolute; top: 11px; display: flex; color: ${t.toolbarIcon}; padding: 2px; }
-    .toolbar { height: ${WIN.toolbar}px; background: ${t.toolbar}; display: flex; align-items: center; gap: 4px; padding: 0 8px; box-sizing: border-box; border-bottom: 1px solid ${t.contentLine}; }
-    .tb { width: 34px; height: 34px; display: grid; place-items: center; color: ${t.toolbarIcon}; flex: none; }
-    .tb.dim { opacity: .45; }
-    .omni { flex: 1; min-width: 0; height: 34px; margin: 0 8px; border-radius: 17px; background: ${t.omnibox}; display: flex; align-items: center; gap: 10px; padding: 0 12px; color: ${t.url}; font: 14px system-ui; }
-    .omni .site { display: flex; color: ${t.toolbarIcon}; }
-    .omni .url { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-    .omni .dim { color: ${t.urlDim}; }
-    .omni .star { display: flex; color: ${t.toolbarIcon}; }
-    .avatar { flex: none; width: 26px; height: 26px; margin: 0 4px; border-radius: 50%; background: #7cacf8; color: #fff; display: grid; place-items: end center; overflow: hidden; }
-  </style>`;
-}
-
 /**
  * The macOS arrow pointer.
  *

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', 'ai', 'commands', 'content', 'dom', 'scripting', 'settings', 'sites', 'styles', 'time', 'toolbar', 'ui']);
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'ai', 'commands', 'content', 'dom', 'frame', 'scripting', '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/frame/window.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Chrome's window around a page: the macOS tab strip and toolbar (light or dark, the default
+ * theme), drawn as HTML. Shared by the store screenshots (`build/store-frame`, which lays it on a
+ * 1280×800 canvas in Playwright) and by extension pages, which draw it on a canvas around a
+ * capture through {@link windowChromeSvg} (an SVG image with the HTML inside, which Chrome draws
+ * without tainting the canvas). The markup is XML-clean so both can use it.
+ *
+ * Window metrics follow Chrome's 2023 refresh on macOS (tabs 34px high in a 42px strip, a 46px
+ * toolbar with a pill omnibox).
+ *
+ * @module frame/window
+ */
+/** The tab strip's and the toolbar's heights (px): the content starts below both. */
+export declare const WINDOW_BARS: Readonly<{
+    strip: 42;
+    toolbar: 46;
+}>;
+/** The window's default width (px): the store screenshot's. */
+export declare const WINDOW_W = 1152;
+/**
+ * A letter favicon for made-up sites (no real brands).
+ *
+ * @param {string} letter - The letter.
+ * @param {string} bg - Background colour.
+ * @param {string} [fg] - Letter colour. Default white.
+ * @returns {string} A data: URL of the SVG.
+ */
+export declare const letterIcon: (letter: string, bg: string, fg?: string) => string;
+/** Chrome's light and dark window colours, and the canvas behind. */
+export declare const THEMES: {
+    light: {
+        bg: string;
+        caption: string;
+        sub: string;
+        frame: string;
+        tabText: string;
+        tabTextInactive: string;
+        tabSep: string;
+        activeTab: string;
+        toolbar: string;
+        toolbarIcon: string;
+        omnibox: string;
+        url: string;
+        urlDim: string;
+        contentLine: string;
+        shadow: string;
+    };
+    dark: {
+        bg: string;
+        caption: string;
+        sub: string;
+        frame: string;
+        tabText: string;
+        tabTextInactive: string;
+        tabSep: string;
+        activeTab: string;
+        toolbar: string;
+        toolbarIcon: string;
+        omnibox: string;
+        url: string;
+        urlDim: string;
+        contentLine: string;
+        shadow: string;
+    };
+};
+export type Theme = keyof typeof THEMES;
+export type Tab = {
+    /**
+     * Its title.
+     */
+    title: string;
+    /**
+     * Its favicon's URL.
+     */
+    icon: string;
+    /**
+     * The selected tab.
+     */
+    active?: boolean;
+    /**
+     * Playing sound.
+     */
+    audible?: boolean;
+    /**
+     * Muted.
+     */
+    muted?: boolean;
+};
+/**
+ * The window's tab strip and toolbar, as HTML. Positions are window-relative.
+ *
+ * @param {object} options - What to draw.
+ * @param {readonly Tab[]} options.tabs - The tabs, left to right.
+ * @param {string} options.url - The address bar's text.
+ * @param {string} [options.urlHost] - The start of `url` to show in full; the rest is dimmed.
+ * @param {Theme} [options.theme] - Default light.
+ * @param {number} [options.w] - The window's width. Default {@link WINDOW_W}.
+ * @param {readonly string[]} [options.ext] - Toolbar extension icons' URLs.
+ * @returns {string} The HTML, with its own styles.
+ */
+export declare function windowChrome({ tabs, url, urlHost, theme, w, ext }: {
+    tabs: readonly Tab[];
+    url: string;
+    urlHost?: string;
+    theme?: Theme;
+    w?: number;
+    ext?: readonly string[];
+}): string;
+/**
+ * The window's tab strip and toolbar as a standalone SVG image, `w` wide and the bars' height
+ * high (scale it when drawing), for an extension page to draw on a canvas: `new Image()` with a
+ * `data:image/svg+xml` URL of it, then `drawImage`. Images in it (the tabs' icons, `ext`) must be
+ * `data:` URLs: an SVG image loads nothing else.
+ *
+ * @param {Parameters<typeof windowChrome>[0]} options - As {@link windowChrome}.
+ * @returns {string} The SVG markup.
+ * @example
+ * const svg = windowChromeSvg({ tabs: [{ title: 'Example', icon: letterIcon('E', '#1a73e8'), active: true }], url: 'example.com', w: 1280 });
+ */
+export declare function windowChromeSvg(options: Parameters<typeof windowChrome>[0]): string;

package/src/frame/window.js

@@ -0,0 +1,197 @@
+/**
+ * Chrome's window around a page: the macOS tab strip and toolbar (light or dark, the default
+ * theme), drawn as HTML. Shared by the store screenshots (`build/store-frame`, which lays it on a
+ * 1280×800 canvas in Playwright) and by extension pages, which draw it on a canvas around a
+ * capture through {@link windowChromeSvg} (an SVG image with the HTML inside, which Chrome draws
+ * without tainting the canvas). The markup is XML-clean so both can use it.
+ *
+ * Window metrics follow Chrome's 2023 refresh on macOS (tabs 34px high in a 42px strip, a 46px
+ * toolbar with a pill omnibox).
+ *
+ * @module frame/window
+ */
+
+/** The tab strip's and the toolbar's heights (px): the content starts below both. */
+export const WINDOW_BARS = Object.freeze({ strip: 42, toolbar: 46 });
+
+/** The window's default width (px): the store screenshot's. */
+export const WINDOW_W = 1152;
+
+/**
+ * @param {unknown} s - Text.
+ * @returns {string} It, escaped for HTML text and attributes.
+ */
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** Material icon paths (24×24). */
+const P = {
+  back: 'M20 11H7.83l5.59-5.59L12 4l-8 8 8 8 1.41-1.41L7.83 13H20v-2z',
+  forward: 'M12 4l-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z',
+  reload: 'M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z',
+  close: 'M19 6.41L17.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',
+  add: 'M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z',
+  more: 'M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2zm0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z',
+  puzzle: 'M20.5 11H19V7c0-1.1-.9-2-2-2h-4V3.5C13 2.12 11.88 1 10.5 1S8 2.12 8 3.5V5H4c-1.1 0-1.99.9-1.99 2v3.8H3.5c1.49 0 2.7 1.21 2.7 2.7s-1.21 2.7-2.7 2.7H2V20c0 1.1.9 2 2 2h3.8v-1.5c0-1.49 1.21-2.7 2.7-2.7 1.49 0 2.7 1.21 2.7 2.7V22H17c1.1 0 2-.9 2-2v-4h1.5c1.38 0 2.5-1.12 2.5-2.5S21.88 11 20.5 11z',
+  star: 'M22 9.24l-7.19-.62L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21 12 17.27 18.18 21l-1.63-7.03L22 9.24zM12 15.4l-3.76 2.27 1-4.28-3.32-2.88 4.38-.38L12 6.1l1.71 4.04 4.38.38-3.32 2.88 1 4.28L12 15.4z',
+  tune: 'M3 17v2h6v-2H3zM3 5v2h10V5H3zm10 16v-2h8v-2h-8v-2h-2v6h2zM7 9v2H3v2h4v2h2V9H7zm14 4v-2H11v2h10zm-6-4h2V7h4V5h-4V3h-2v6z',
+  sound: 'M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02zM14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.85-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77z',
+  muted: 'M16.5 12c0-1.77-1.02-3.29-2.5-4.03v2.21l2.45 2.45c.03-.2.05-.41.05-.63zm2.5 0c0 .94-.2 1.82-.54 2.64l1.51 1.51C20.63 14.91 21 13.5 21 12c0-4.28-2.99-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71zM4.27 3L3 4.27 7.73 9H3v6h4l5 5v-6.73l4.25 4.25c-.67.52-1.42.93-2.25 1.18v2.06c1.38-.31 2.63-.95 3.69-1.81L19.73 21 21 19.73l-9-9L4.27 3zM12 4L9.91 6.09 12 8.18V4z',
+  person: 'M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z',
+};
+
+/**
+ * A Material icon as inline SVG, in the text colour.
+ *
+ * @param {keyof typeof P} name - Which icon.
+ * @param {number} [size] - Width and height in px. Default 20.
+ * @returns {string} The SVG markup.
+ */
+const icon = (name, size = 20) =>
+  `<svg viewBox="0 0 24 24" width="${size}" height="${size}"><path fill="currentColor" d="${P[name]}"/></svg>`;
+
+/**
+ * A letter favicon for made-up sites (no real brands).
+ *
+ * @param {string} letter - The letter.
+ * @param {string} bg - Background colour.
+ * @param {string} [fg] - Letter colour. Default white.
+ * @returns {string} A data: URL of the SVG.
+ */
+export const letterIcon = (letter, bg, fg = '#fff') =>
+  `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><rect width="16" height="16" rx="4" fill="${bg}"/><text x="8" y="12" font-family="-apple-system,Helvetica,Arial" font-size="11" font-weight="700" text-anchor="middle" fill="${fg}">${letter}</text></svg>`)}`;
+
+/** Chrome's light and dark window colours, and the canvas behind. */
+export const THEMES = {
+  light: {
+    bg: '#eef2f8', caption: '#1f1f1f', sub: '#444746',
+    frame: '#dde3ea', tabText: '#1f1f1f', tabTextInactive: '#474747', tabSep: '#a8afb8', activeTab: '#ffffff',
+    toolbar: '#ffffff', toolbarIcon: '#474747', omnibox: '#e9eef6', url: '#1f1f1f', urlDim: '#5e5e5e',
+    contentLine: '#d3d7dc', shadow: '0 24px 60px rgba(31,45,70,.20), 0 0 0 .5px rgba(0,0,0,.18)',
+  },
+  dark: {
+    bg: '#1b1c1f', caption: '#e3e3e3', sub: '#c4c7c5',
+    frame: '#1f1f1f', tabText: '#e3e3e3', tabTextInactive: '#c7c7c7', tabSep: '#5f6368', activeTab: '#3c3c3c',
+    toolbar: '#3c3c3c', toolbarIcon: '#c7c7c7', omnibox: '#282828', url: '#e3e3e3', urlDim: '#a8a8a8',
+    contentLine: '#2a2a2a', shadow: '0 24px 60px rgba(0,0,0,.55), 0 0 0 .5px rgba(255,255,255,.14)',
+  },
+};
+
+/** @typedef {keyof typeof THEMES} Theme */
+
+/**
+ * One tab in the drawn window.
+ *
+ * @typedef {object} Tab
+ * @property {string} title Its title.
+ * @property {string} icon Its favicon's URL.
+ * @property {boolean} [active] The selected tab.
+ * @property {boolean} [audible] Playing sound.
+ * @property {boolean} [muted] Muted.
+ */
+
+const TAB_H = 34;
+
+/**
+ * Lay out tabs like Chrome: equal widths up to 240px, shrinking to fit.
+ *
+ * @param {readonly Tab[]} tabs - The tabs.
+ * @param {number} w - The window's width.
+ * @returns {{ x: number, width: number }[]} Each tab's window-relative x and width.
+ */
+function tabLayout(tabs, w) {
+  const left = 84;
+  const right = 60;
+  const max = 240;
+  const avail = w - left - right - 36;
+  const width = Math.min(max, Math.floor(avail / tabs.length));
+  return tabs.map((_, i) => ({ x: left + i * width, width }));
+}
+
+/**
+ * The window's tab strip and toolbar, as HTML. Positions are window-relative.
+ *
+ * @param {object} options - What to draw.
+ * @param {readonly Tab[]} options.tabs - The tabs, left to right.
+ * @param {string} options.url - The address bar's text.
+ * @param {string} [options.urlHost] - The start of `url` to show in full; the rest is dimmed.
+ * @param {Theme} [options.theme] - Default light.
+ * @param {number} [options.w] - The window's width. Default {@link WINDOW_W}.
+ * @param {readonly string[]} [options.ext] - Toolbar extension icons' URLs.
+ * @returns {string} The HTML, with its own styles.
+ */
+export function windowChrome({ tabs, url, urlHost, theme = 'light', w = WINDOW_W, ext = [] }) {
+  const t = THEMES[theme];
+  const layout = tabLayout(tabs, w);
+  const tabHtml = tabs.map((tab, i) => {
+    const { x, width } = layout[i];
+    const sepAfter = i < tabs.length - 1 && !tab.active && !tabs[i + 1].active;
+    const alert = tab.muted ? icon('muted', 16) : tab.audible ? icon('sound', 16) : '';
+    const showClose = tab.active || width >= 120;
+    return `<div class="tab${tab.active ? ' active' : ''}" style="left:${x}px;width:${width}px">
+      <img class="fav" src="${tab.icon}" width="16" height="16" alt=""/>
+      <span class="title">${esc(tab.title)}</span>
+      ${alert ? `<span class="alert">${alert}</span>` : ''}
+      ${showClose ? `<span class="x">${icon('close', 14)}</span>` : ''}
+    </div>${sepAfter ? `<span class="sep" style="left:${x + width - 1}px"></span>` : ''}`;
+  }).join('');
+  const last = layout[layout.length - 1];
+  const plusX = last.x + last.width + 4;
+  const extIcons = ext.map((src) => `<img src="${src}" width="16" height="16" alt="" style="margin:0 9px"/>`).join('');
+  return `
+  <div class="strip">
+    <span class="lights"><i style="background:#ff5f57"></i><i style="background:#febc2e"></i><i style="background:#28c840"></i></span>
+    ${tabHtml}
+    <span class="plus" style="left:${plusX}px">${icon('add', 18)}</span>
+  </div>
+  <div class="toolbar">
+    <span class="tb">${icon('back')}</span><span class="tb dim">${icon('forward')}</span><span class="tb">${icon('reload')}</span>
+    <div class="omni"><span class="site">${icon('tune', 16)}</span><span class="url">${urlHost ? `${esc(urlHost)}<span class="dim">${esc(url.slice(urlHost.length))}</span>` : esc(url)}</span><span class="star">${icon('star', 18)}</span></div>
+    ${extIcons}<span class="tb">${icon('puzzle')}</span>
+    <span class="avatar">${icon('person', 18)}</span><span class="tb">${icon('more')}</span>
+  </div>
+  <style>
+    .strip { position: relative; height: ${WINDOW_BARS.strip}px; background: ${t.frame}; }
+    .lights { position: absolute; left: 16px; top: 15px; display: flex; gap: 8px; }
+    .lights i { width: 12px; height: 12px; border-radius: 50%; display: block; box-shadow: inset 0 0 0 .5px rgba(0,0,0,.12); }
+    .tab { position: absolute; bottom: 0; height: ${TAB_H}px; display: flex; align-items: center; gap: 8px; padding: 0 10px 0 14px; box-sizing: border-box; color: ${t.tabTextInactive}; font: 12px/16px system-ui; }
+    .tab.active { background: ${t.activeTab}; color: ${t.tabText}; border-radius: 10px 10px 0 0; z-index: 1; }
+    .tab.active::before, .tab.active::after { content: ''; position: absolute; bottom: 0; width: 10px; height: 10px; }
+    .tab.active::before { left: -10px; background: radial-gradient(circle at 0 0, transparent 10px, ${t.activeTab} 10.5px); }
+    .tab.active::after { right: -10px; background: radial-gradient(circle at 100% 0, transparent 10px, ${t.activeTab} 10.5px); }
+    .tab .fav { flex: none; }
+    .tab .title { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; -webkit-mask-image: linear-gradient(90deg, #000 calc(100% - 18px), transparent); }
+    .tab .alert, .tab .x { flex: none; display: flex; color: ${t.toolbarIcon}; }
+    .sep { position: absolute; bottom: 9px; width: 1px; height: 18px; background: ${t.tabSep}; }
+    .plus { position: absolute; top: 11px; display: flex; color: ${t.toolbarIcon}; padding: 2px; }
+    .toolbar { height: ${WINDOW_BARS.toolbar}px; background: ${t.toolbar}; display: flex; align-items: center; gap: 4px; padding: 0 8px; box-sizing: border-box; border-bottom: 1px solid ${t.contentLine}; }
+    .tb { width: 34px; height: 34px; display: grid; place-items: center; color: ${t.toolbarIcon}; flex: none; }
+    .tb.dim { opacity: .45; }
+    .omni { flex: 1; min-width: 0; height: 34px; margin: 0 8px; border-radius: 17px; background: ${t.omnibox}; display: flex; align-items: center; gap: 10px; padding: 0 12px; color: ${t.url}; font: 14px system-ui; }
+    .omni .site { display: flex; color: ${t.toolbarIcon}; }
+    .omni .url { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .omni .dim { color: ${t.urlDim}; }
+    .omni .star { display: flex; color: ${t.toolbarIcon}; }
+    .avatar { flex: none; width: 26px; height: 26px; margin: 0 4px; border-radius: 50%; background: #7cacf8; color: #fff; display: grid; place-items: end center; overflow: hidden; }
+  </style>`;
+}
+
+
+/**
+ * The window's tab strip and toolbar as a standalone SVG image, `w` wide and the bars' height
+ * high (scale it when drawing), for an extension page to draw on a canvas: `new Image()` with a
+ * `data:image/svg+xml` URL of it, then `drawImage`. Images in it (the tabs' icons, `ext`) must be
+ * `data:` URLs: an SVG image loads nothing else.
+ *
+ * @param {Parameters<typeof windowChrome>[0]} options - As {@link windowChrome}.
+ * @returns {string} The SVG markup.
+ * @example
+ * const svg = windowChromeSvg({ tabs: [{ title: 'Example', icon: letterIcon('E', '#1a73e8'), active: true }], url: 'example.com', w: 1280 });
+ */
+export function windowChromeSvg(options) {
+  const w = options.w ?? WINDOW_W;
+  const h = WINDOW_BARS.strip + WINDOW_BARS.toolbar;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">`
+    + `<foreignObject x="0" y="0" width="${w}" height="${h}">`
+    + `<div xmlns="http://www.w3.org/1999/xhtml" style="width:${w}px;height:${h}px;margin:0;-webkit-font-smoothing:antialiased">${windowChrome({ ...options, w })}</div>`
+    + '</foreignObject></svg>';
+}

package/src/index.d.ts

@@ -2,7 +2,7 @@
  * The kit's browser half: what an extension's pages, offscreen document,
  * service worker and content scripts load, Chrome's page components (the ⋮
  * menu, the text dialog, the toast with Undo, a settings card's site list,
- * the built-in AI row), per-site lists' sites, Chrome's on-device model, and
+ * the built-in AI row), Chrome's window drawn around a capture, per-site lists' sites, Chrome's on-device model, and
  * a content script's slices and change watcher included. Every function takes the `chrome`
  * APIs it uses as arguments, so tests run the real logic against fakes.
  *
@@ -18,6 +18,7 @@ export { setShortcuts } from './commands/shortcuts.js';
 export { BLOCK_CHARS, SLICE_MS, blocksOf, inSlices } from './content/slices.js';
 export { MAX_WAIT_MS, SETTLE_MS, watchChanges } from './content/watch.js';
 export { focusedElement } from './dom/focus.js';
+export { THEMES, WINDOW_BARS, WINDOW_W, letterIcon, windowChrome, windowChromeSvg } from './frame/window.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
 export { setUpPage } from './dom/setup.js';
@@ -46,6 +47,8 @@ export type ModelSession = import('./ai/model.js').ModelSession;
 export type ModelStatus = import('./ai/model.js').ModelStatus;
 export type SliceOptions = import('./content/slices.js').SliceOptions;
 export type WatchHandlers = import('./content/watch.js').WatchHandlers;
+export type WindowTab = import('./frame/window.js').Tab;
+export type WindowTheme = import('./frame/window.js').Theme;
 export type ModelRow = import('./ui/model-row.js').ModelRow;
 export type ContentScript = import('./scripting/registration.js').ContentScript;
 export type ActionMenu = import('./ui/menu.js').ActionMenu;
@@ -70,6 +73,8 @@ export type Toast = import('./ui/toast.js').Toast;
  * @typedef {import('./ai/model.js').ModelStatus} ModelStatus
  * @typedef {import('./content/slices.js').SliceOptions} SliceOptions
  * @typedef {import('./content/watch.js').WatchHandlers} WatchHandlers
+ * @typedef {import('./frame/window.js').Tab} WindowTab
+ * @typedef {import('./frame/window.js').Theme} WindowTheme
  * @typedef {import('./ui/model-row.js').ModelRow} ModelRow
  * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
  * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu

package/src/index.js

@@ -2,7 +2,7 @@
  * The kit's browser half: what an extension's pages, offscreen document,
  * service worker and content scripts load, Chrome's page components (the ⋮
  * menu, the text dialog, the toast with Undo, a settings card's site list,
- * the built-in AI row), per-site lists' sites, Chrome's on-device model, and
+ * the built-in AI row), Chrome's window drawn around a capture, per-site lists' sites, Chrome's on-device model, and
  * a content script's slices and change watcher included. Every function takes the `chrome`
  * APIs it uses as arguments, so tests run the real logic against fakes.
  *
@@ -21,6 +21,7 @@ export { setShortcuts } from './commands/shortcuts.js';
 export { BLOCK_CHARS, SLICE_MS, blocksOf, inSlices } from './content/slices.js';
 export { MAX_WAIT_MS, SETTLE_MS, watchChanges } from './content/watch.js';
 export { focusedElement } from './dom/focus.js';
+export { THEMES, WINDOW_BARS, WINDOW_W, letterIcon, windowChrome, windowChromeSvg } from './frame/window.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
 export { setUpPage } from './dom/setup.js';
@@ -57,6 +58,8 @@ export { TOAST_MS, createToast } from './ui/toast.js';
  * @typedef {import('./ai/model.js').ModelStatus} ModelStatus
  * @typedef {import('./content/slices.js').SliceOptions} SliceOptions
  * @typedef {import('./content/watch.js').WatchHandlers} WatchHandlers
+ * @typedef {import('./frame/window.js').Tab} WindowTab
+ * @typedef {import('./frame/window.js').Theme} WindowTheme
  * @typedef {import('./ui/model-row.js').ModelRow} ModelRow
  * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
  * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu

package/src/settings/saver.d.ts

@@ -41,6 +41,14 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
      * Cancel the timers (tests, or a page being torn down).
      */
     stop: () => void;
+    /**
+     *   Hear the settings change elsewhere (another tab, another computer through sync):
+     *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+     *   `chrome.storage.onChanged`.
+     */
+    follow: (onChange: (settings: S) => void, events: {
+        addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void;
+    }) => void;
 };
 /** @import { SettingsStore } from './store.js' */
 /** @import { SyncedStorage } from './storage.js' */
@@ -59,6 +67,10 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
  * @property {() => Promise<unknown>} flush Write what's queued now (call it as the page is hidden);
  *   resolves once every write so far has finished.
  * @property {() => void} stop Cancel the timers (tests, or a page being torn down).
+ * @property {(onChange: (settings: S) => void, events: {addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void}) => void} follow
+ *   Hear the settings change elsewhere (another tab, another computer through sync):
+ *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+ *   `chrome.storage.onChanged`.
  */
 /**
  * Make a debounced saver over a settings store.
@@ -72,5 +84,6 @@ export type SettingsSaver<S extends Record<string, unknown>> = {
  * const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
  * toggle.addEventListener('change', () => saver.save({ compact: toggle.checked }));
  * addEventListener('pagehide', () => saver.flush());
+ * saver.follow((settings) => show(settings), chrome.storage.onChanged);
  */
 export declare function createSettingsSaver<S extends Record<string, unknown>>(store: SettingsStore<S>, storage: SyncedStorage, { delay, retryAfter, onSaved }?: SaverOptions<S>): SettingsSaver<S>;

package/src/settings/saver.js

@@ -27,6 +27,10 @@
  * @property {() => Promise<unknown>} flush Write what's queued now (call it as the page is hidden);
  *   resolves once every write so far has finished.
  * @property {() => void} stop Cancel the timers (tests, or a page being torn down).
+ * @property {(onChange: (settings: S) => void, events: {addListener(listener: (changes: Record<string, import('./storage.js').StorageChange>, area: string) => void): void}) => void} follow
+ *   Hear the settings change elsewhere (another tab, another computer through sync):
+ *   `onChange` gets them all, this page's changes not yet written laid over them. `events` is
+ *   `chrome.storage.onChanged`.
  */
 
 /**
@@ -41,6 +45,7 @@
  * const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
  * toggle.addEventListener('change', () => saver.save({ compact: toggle.checked }));
  * addEventListener('pagehide', () => saver.flush());
+ * saver.follow((settings) => show(settings), chrome.storage.onChanged);
  */
 export function createSettingsSaver(store, storage, { delay = 1000, retryAfter = 60_000, onSaved = () => {} } = {}) {
   /** @type {Partial<S>} */
@@ -90,6 +95,12 @@ export function createSettingsSaver(store, storage, { delay = 1000, retryAfter =
       timer = setTimeout(flush, delay);
     },
     flush,
+    follow(onChange, events) {
+      events.addListener(async (changes, area) => {
+        if (!store.changed(changes, area).length) return;
+        onChange(store.normalize({ ...(await store.load(storage)), ...pending }));
+      });
+    },
     stop() {
       clearTimeout(timer);
       clearTimeout(retryTimer);

package/src/testing/heartbeat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How long a page's main thread is held, for performance checks: a heartbeat in the page. From
+ * Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/heartbeat
+ */
+import type { Page } from 'playwright';
+/** @import { Page } from 'playwright' */
+/**
+ * Start a heartbeat in a page: a timer that fires again and again, costing nothing between
+ * beats; the longest gap between two is the longest the main thread was held (the Long Tasks
+ * API misses an extension's isolated world's work, and a `MessageChannel` heartbeat counts as
+ * task time itself). Gaps while the tab is hidden (another tab in front) don't count: Chrome
+ * throttles a hidden tab's timers.
+ *
+ * @param {Page} page - The page.
+ * @returns {Promise<() => Promise<number>>} Stops it and gives the longest gap (ms).
+ * @example
+ * const stop = await heartbeat(page);
+ * await doTheWork();
+ * const held = await stop(); // e.g. 17
+ */
+export declare function heartbeat(page: Page): Promise<() => Promise<number>>;

package/src/testing/heartbeat.js

@@ -0,0 +1,43 @@
+/**
+ * How long a page's main thread is held, for performance checks: a heartbeat in the page. From
+ * Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/heartbeat
+ */
+
+/** @import { Page } from 'playwright' */
+
+/**
+ * Start a heartbeat in a page: a timer that fires again and again, costing nothing between
+ * beats; the longest gap between two is the longest the main thread was held (the Long Tasks
+ * API misses an extension's isolated world's work, and a `MessageChannel` heartbeat counts as
+ * task time itself). Gaps while the tab is hidden (another tab in front) don't count: Chrome
+ * throttles a hidden tab's timers.
+ *
+ * @param {Page} page - The page.
+ * @returns {Promise<() => Promise<number>>} Stops it and gives the longest gap (ms).
+ * @example
+ * const stop = await heartbeat(page);
+ * await doTheWork();
+ * const held = await stop(); // e.g. 17
+ */
+export async function heartbeat(page) {
+  await page.evaluate(() => {
+    const beat = { longest: 0, running: true };
+    Object.assign(window, { extensionKitBeat: beat });
+    let last = performance.now();
+    const tick = () => {
+      const now = performance.now();
+      // A hidden tab's timers are throttled by Chrome: those gaps aren't the page being held.
+      if (!document.hidden) beat.longest = Math.max(beat.longest, now - last);
+      last = now;
+      if (beat.running) setTimeout(tick, 0);
+    };
+    setTimeout(tick, 0);
+  });
+  return () => page.evaluate(() => {
+    const beat = /** @type {{longest: number, running: boolean}} */ (/** @type {any} */ (window).extensionKitBeat);
+    beat.running = false;
+    return beat.longest;
+  });
+}

package/src/testing/index.d.ts

@@ -14,6 +14,8 @@ export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
 export { fakeLanguageModel } from './fake-model.js';
 export { messageLookup, readMessages } from './messages.js';
+export { heartbeat } from './heartbeat.js';
+export { playPermissionPrompt } from './prompt.js';
 export { serve, testCertificate } from './server.js';
 export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';

package/src/testing/index.js

@@ -17,6 +17,8 @@ export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
 export { fakeLanguageModel } from './fake-model.js';
 export { messageLookup, readMessages } from './messages.js';
+export { heartbeat } from './heartbeat.js';
+export { playPermissionPrompt } from './prompt.js';
 export { serve, testCertificate } from './server.js';
 export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';

package/src/testing/prompt.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Chrome's permission prompt, played in an extension page for an e2e test: Playwright can't
+ * click Chrome's own prompt. From Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/prompt
+ */
+/**
+ * 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.
+ *
+ * @param {boolean[]} answers - The answers, in order.
+ * @example
+ * await page.evaluate(playPermissionPrompt, [true]);
+ * await page.click('#download');
+ * const asked = await page.evaluate(() => window.asked); // [{ permissions: ['downloads'], origins: undefined, gesture: true }]
+ */
+export declare function playPermissionPrompt(answers: boolean[]): void;

package/src/testing/prompt.js

@@ -0,0 +1,29 @@
+/**
+ * Chrome's permission prompt, played in an extension page for an e2e test: Playwright can't
+ * click Chrome's own prompt. From Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/prompt
+ */
+
+/**
+ * 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.
+ *
+ * @param {boolean[]} answers - The answers, in order.
+ * @example
+ * await page.evaluate(playPermissionPrompt, [true]);
+ * await page.click('#download');
+ * const asked = await page.evaluate(() => window.asked); // [{ permissions: ['downloads'], origins: undefined, gesture: true }]
+ */
+export function playPermissionPrompt(answers) {
+  /** @type {{permissions?: string[], origins?: string[], gesture: boolean}[]} */
+  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 });
+    return answers.length > 1 ? answers.shift() : answers[0];
+  }));
+}