@arraypress/extension-kit 1.8.0 → 1.9.0

package/README.md

@@ -206,6 +206,19 @@ scale. Chrome draws an SVG image with HTML inside (`foreignObject`) without tain
 (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.
 
+A plain macOS window (1.9.0) draws the same way: `macWindowSvg({ title, theme, w })` is its title
+bar as macOS 26 and later draw it (measured from AppKit on macOS 27.2), `w` wide and
+`MAC_WINDOW.titleBar` (32px) high: 14px traffic lights (the same markup as Chrome's strip), the
+title after them, a hairline below. The canvas draws the rest: corners of `MAC_WINDOW.radius`
+(16px, `NSThemeFrame`'s) and the theme's shadow, `THEMES[theme].windowShadow`
+(`{ y, blur, color }` for a canvas's `shadowOffsetY`, `shadowBlur`, `shadowColor`; `THEMES[theme].shadow`
+is the same shadow as CSS, the store frame's).
+
+```js
+context.shadowColor = THEMES.light.windowShadow.color; // and its blur and y, at the scale
+context.roundRect(x, y, w * scale, (MAC_WINDOW.titleBar + contentHeight) * scale, MAC_WINDOW.radius * scale);
+```
+
 ## Sites
 
 ```js
@@ -221,6 +234,28 @@ withSite(['a.com', 'b.com'], 'a.com');       // ['b.com', 'a.com'], what a list
 A site is http or https with a dot in its host (or `localhost`); text without a scheme is https;
 `localhost:8080` is a host and port. Pure, so a content script can load `sites/sites.js` alone.
 
+## A page's side
+
+```js
+// In the worker or a page: call content/main.js's `scan` in the tab's frames (main.js and what it
+// imports listed in web_accessible_resources). The module stays loaded between calls.
+const frames = await callInPage(chrome.scripting, { tabId, allFrames: true }, 'content/main.js', 'scan', [options]);
+for (const { frameId, result } of frames) show(frameId, result);
+
+// From the toolbar click: the tab's own side panel, panel/panel.html?tab=<id>, nothing awaited first.
+chrome.action.onClicked.addListener((tab) => openSidePanel(chrome.sidePanel, tab.id, 'panel/panel.html'));
+
+// In the content script: a layer the page's styles can't touch (a closed shadow root).
+const { root, remove } = pageOverlay(document, { name: 'my-inspector', css: ':host { position: fixed; inset: 0; pointer-events: none; }' });
+```
+
+`callInPage(scripting, target, module, name, args, {immediately})` resolves to each frame's
+`{frameId, result}` (frames Chrome couldn't run in left out) and rejects when it can run in none;
+`immediately` (default true) doesn't wait for the page to be idle. `openSidePanel` sets the tab's
+panel to `path?tab=<id>` (`sidePanelPath`) and opens it in the same moment: Chrome opens a panel
+only while the click counts. `pageOverlay` puts a host element of its own name (`all: initial`)
+on the root element, replacing one a run before left; `root` is its closed shadow root, `css` first.
+
 ## A content script on every site
 
 ```js
@@ -309,7 +344,8 @@ const stop = watchChanges(document.body, {
 
 `inSlices(root, work, {blockChars, sliceMs, pause})` cuts a page into blocks (`blocksOf`) and
 hands the main thread back whenever a slice has run its time, so a 2,000-item listing never
-freezes. `watchChanges` hands over what was added or changed a little after the page stops
+freezes. `eachInSlices(items, work, {sliceMs, pause})` does the same for any list (each element's
+style read, each text measured): `work(item, index)`. `watchChanges` hands over what was added or changed a little after the page stops
 changing (at most `maxWaitMs` while it keeps on); an element with a few children (`regroupChildren`,
 default 6) whose children changed is handed over whole. Both are pure DOM, so a content script
 imports them directly (list them in `web_accessible_resources`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.8.0",
+  "version": "1.9.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/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', 'frame', 'scripting', 'settings', 'sites', 'styles', 'time', 'toolbar', 'ui']);
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'ai', 'commands', 'content', 'dom', 'frame', 'panel', '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/content/overlay.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A content script's layer over the page: a host element of its own name on
+ * the page's root element, holding a closed shadow root with the script's
+ * styles, so the page's styles and scripts can't reach in and its styles
+ * can't reach out. Pickers, toasts, bars and inspectors draw in it.
+ *
+ * @module content/overlay
+ */
+export type PageOverlay = {
+    /**
+     * The host element, on the page's root element.
+     */
+    host: HTMLElement;
+    /**
+     * Its closed shadow root, the styles first: append to it.
+     */
+    root: ShadowRoot;
+    /**
+     * Take it off the page.
+     */
+    remove: () => void;
+};
+/**
+ * A page overlay.
+ *
+ * @typedef {object} PageOverlay
+ * @property {HTMLElement} host The host element, on the page's root element.
+ * @property {ShadowRoot} root Its closed shadow root, the styles first: append to it.
+ * @property {() => void} remove Take it off the page.
+ */
+/**
+ * Put an overlay on the page, replacing one of the same name a run before left.
+ * The host's own styles are reset (`all: initial`) before `css`, so the page's
+ * rules for unknown elements can't move or hide it; `css` styles `:host` and what's inside.
+ *
+ * @param {Document} doc - The page.
+ * @param {{name: string, css: string}} options - `name`: the host's element name, with a hyphen
+ *   (never registered: a plain element); `css`: the overlay's styles.
+ * @returns {PageOverlay} The overlay.
+ * @example
+ * const { root, remove } = pageOverlay(document, { name: 'better-fonts-inspector', css: ':host { position: fixed; inset: 0; pointer-events: none; }' });
+ * root.append(card);
+ */
+export declare function pageOverlay(doc: Document, { name, css }: {
+    name: string;
+    css: string;
+}): PageOverlay;

package/src/content/overlay.js

@@ -0,0 +1,42 @@
+/**
+ * A content script's layer over the page: a host element of its own name on
+ * the page's root element, holding a closed shadow root with the script's
+ * styles, so the page's styles and scripts can't reach in and its styles
+ * can't reach out. Pickers, toasts, bars and inspectors draw in it.
+ *
+ * @module content/overlay
+ */
+
+/**
+ * A page overlay.
+ *
+ * @typedef {object} PageOverlay
+ * @property {HTMLElement} host The host element, on the page's root element.
+ * @property {ShadowRoot} root Its closed shadow root, the styles first: append to it.
+ * @property {() => void} remove Take it off the page.
+ */
+
+/**
+ * Put an overlay on the page, replacing one of the same name a run before left.
+ * The host's own styles are reset (`all: initial`) before `css`, so the page's
+ * rules for unknown elements can't move or hide it; `css` styles `:host` and what's inside.
+ *
+ * @param {Document} doc - The page.
+ * @param {{name: string, css: string}} options - `name`: the host's element name, with a hyphen
+ *   (never registered: a plain element); `css`: the overlay's styles.
+ * @returns {PageOverlay} The overlay.
+ * @example
+ * const { root, remove } = pageOverlay(document, { name: 'better-fonts-inspector', css: ':host { position: fixed; inset: 0; pointer-events: none; }' });
+ * root.append(card);
+ */
+export function pageOverlay(doc, { name, css }) {
+  for (const old of doc.querySelectorAll(name)) old.remove();
+  const host = doc.createElement(name);
+  host.style.setProperty('all', 'initial', 'important');
+  const root = host.attachShadow({ mode: 'closed' });
+  const style = doc.createElement('style');
+  style.textContent = css;
+  root.append(style);
+  doc.documentElement.append(host);
+  return { host, root, remove: () => host.remove() };
+}

package/src/content/slices.d.ts

@@ -48,6 +48,21 @@ export type SliceOptions = {
  * @property {() => Promise<void>} [pause] Hands the main thread back. Default: a macrotask.
  * @property {() => number} [now] The clock. Default `performance.now`.
  */
+/**
+ * Work through any list in slices: `work(item, index)` on each, the main
+ * thread handed back whenever a slice has run `sliceMs`. For a content
+ * script's work that isn't cut by blocks of the page (each element's style
+ * read, each text measured).
+ *
+ * @template T
+ * @param {Iterable<T>} items - The items.
+ * @param {(item: T, index: number) => void} work - What to do with one.
+ * @param {Pick<SliceOptions, 'sliceMs' | 'pause' | 'now'>} [options] - Slice length, how to pause, the clock.
+ * @returns {Promise<void>} Once every item is done.
+ * @example
+ * await eachInSlices(elements, (element) => styles.push(getComputedStyle(element).fontFamily));
+ */
+export declare function eachInSlices<T>(items: Iterable<T>, work: (item: T, index: number) => void, { sliceMs, pause, now }?: Pick<SliceOptions, 'sliceMs' | 'pause' | 'now'>): Promise<void>;
 /**
  * Work through a part of the page in slices: `work(block)` on each block
  * still in the page, the main thread handed back whenever a slice has run
@@ -60,4 +75,4 @@ export type SliceOptions = {
  * @example
  * await inSlices(document.body, (block) => scanner.scan(block));
  */
-export declare function inSlices(root: Node, work: (block: Node) => void, { blockChars, sliceMs, pause, now }?: SliceOptions): Promise<void>;
+export declare function inSlices(root: Node, work: (block: Node) => void, { blockChars, ...options }?: SliceOptions): Promise<void>;

package/src/content/slices.js

@@ -55,6 +55,32 @@ const nextTask = () => new Promise((resolve) => { setTimeout(resolve, 0); });
  * @property {() => number} [now] The clock. Default `performance.now`.
  */
 
+/**
+ * Work through any list in slices: `work(item, index)` on each, the main
+ * thread handed back whenever a slice has run `sliceMs`. For a content
+ * script's work that isn't cut by blocks of the page (each element's style
+ * read, each text measured).
+ *
+ * @template T
+ * @param {Iterable<T>} items - The items.
+ * @param {(item: T, index: number) => void} work - What to do with one.
+ * @param {Pick<SliceOptions, 'sliceMs' | 'pause' | 'now'>} [options] - Slice length, how to pause, the clock.
+ * @returns {Promise<void>} Once every item is done.
+ * @example
+ * await eachInSlices(elements, (element) => styles.push(getComputedStyle(element).fontFamily));
+ */
+export async function eachInSlices(items, work, { sliceMs = SLICE_MS, pause = nextTask, now = () => performance.now() } = {}) {
+  let started = now();
+  let index = 0;
+  for (const item of items) {
+    work(item, index++);
+    if (now() - started > sliceMs) {
+      await pause();
+      started = now();
+    }
+  }
+}
+
 /**
  * Work through a part of the page in slices: `work(block)` on each block
  * still in the page, the main thread handed back whenever a slice has run
@@ -67,14 +93,7 @@ const nextTask = () => new Promise((resolve) => { setTimeout(resolve, 0); });
  * @example
  * await inSlices(document.body, (block) => scanner.scan(block));
  */
-export async function inSlices(root, work, { blockChars = BLOCK_CHARS, sliceMs = SLICE_MS, pause = nextTask, now = () => performance.now() } = {}) {
-  let started = now();
-  for (const block of blocksOf(root, blockChars)) {
-    if (!block.isConnected) continue;
-    work(block);
-    if (now() - started > sliceMs) {
-      await pause();
-      started = now();
-    }
-  }
+export function inSlices(root, work, { blockChars = BLOCK_CHARS, ...options } = {}) {
+  // A block the work before took out of the page is skipped.
+  return eachInSlices(blocksOf(root, blockChars), (block) => { if (block.isConnected) work(block); }, options);
 }

package/src/frame/window.d.ts

@@ -1,12 +1,17 @@
 /**
- * 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.
+ * Windows around a page, drawn as HTML: Chrome's (the macOS tab strip and toolbar) and a plain
+ * macOS window's title bar, light or dark, sharing the traffic lights, the colours and the
+ * shadow. Chrome's is shared by the store screenshots (`build/store-frame`, which lays it on a
+ * 1280×800 canvas in Playwright) and by extension pages, which draw either on a canvas around a
+ * capture through {@link windowChromeSvg} or {@link macWindowSvg} (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).
+ * toolbar with a pill omnibox) and AppKit's titled window as macOS 26 and later draw it, measured
+ * on macOS 27.2 (`NSThemeFrame`'s `cornerRadius` 16, a 32pt title bar, the window buttons 14pt
+ * at 9, 32 and 55 from the left and 9 from the top, the title in the 13pt headline font at 85,
+ * after the buttons).
  *
  * @module frame/window
  */
@@ -15,6 +20,11 @@ export declare const WINDOW_BARS: Readonly<{
     strip: 42;
     toolbar: 46;
 }>;
+/** A plain macOS window (macOS 26 and later): its title bar's height and its corners' radius (px). */
+export declare const MAC_WINDOW: Readonly<{
+    titleBar: 32;
+    radius: 16;
+}>;
 /** The window's default width (px): the store screenshot's. */
 export declare const WINDOW_W = 1152;
 /**
@@ -26,7 +36,25 @@ export declare const WINDOW_W = 1152;
  * @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 type WindowShadow = {
+    /**
+     * How far down it falls.
+     */
+    y: number;
+    /**
+     * Its blur.
+     */
+    blur: number;
+    /**
+     * Its colour.
+     */
+    color: string;
+};
+/**
+ * Chrome's light and dark window colours, a macOS title bar's (`titleBar`, and `titleLine` below
+ * it, as AppKit draws them), the canvas behind, and the window's shadow (`windowShadow` for a
+ * canvas's `shadow*`, `shadow` for CSS).
+ */
 export declare const THEMES: {
     light: {
         bg: string;
@@ -43,6 +71,9 @@ export declare const THEMES: {
         url: string;
         urlDim: string;
         contentLine: string;
+        titleBar: string;
+        titleLine: string;
+        windowShadow: WindowShadow;
         shadow: string;
     };
     dark: {
@@ -60,6 +91,9 @@ export declare const THEMES: {
         url: string;
         urlDim: string;
         contentLine: string;
+        titleBar: string;
+        titleLine: string;
+        windowShadow: WindowShadow;
         shadow: string;
     };
 };
@@ -118,3 +152,31 @@ export declare function windowChrome({ tabs, url, urlHost, theme, w, ext }: {
  * 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;
+/**
+ * A plain macOS window's title bar, as HTML: the traffic lights at the left, the title after
+ * them (macOS 26 on), a hairline below.
+ *
+ * @param {object} options - What to draw.
+ * @param {string} options.title - The window's title.
+ * @param {Theme} [options.theme] - Default light.
+ * @param {number} [options.w] - The window's width. Default {@link WINDOW_W}.
+ * @returns {string} The HTML, with its own styles.
+ */
+declare function macTitleBar({ title, theme, w }: {
+    title: string;
+    theme?: Theme;
+    w?: number;
+}): string;
+/**
+ * A plain macOS window's title bar as a standalone SVG image, `w` wide and `MAC_WINDOW.titleBar`
+ * high (scale it when drawing), for an extension page to draw on a canvas as
+ * {@link windowChromeSvg}'s bars are drawn. The window's corners (`MAC_WINDOW.radius`) and its
+ * shadow (`THEMES[theme].windowShadow`) are the canvas's to draw.
+ *
+ * @param {Parameters<typeof macTitleBar>[0]} options - As {@link macTitleBar}.
+ * @returns {string} The SVG markup.
+ * @example
+ * const svg = macWindowSvg({ title: 'Example', theme: 'dark', w: 1280 });
+ */
+export declare function macWindowSvg(options: Parameters<typeof macTitleBar>[0]): string;
+export {};

package/src/frame/window.js

@@ -1,12 +1,17 @@
 /**
- * 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.
+ * Windows around a page, drawn as HTML: Chrome's (the macOS tab strip and toolbar) and a plain
+ * macOS window's title bar, light or dark, sharing the traffic lights, the colours and the
+ * shadow. Chrome's is shared by the store screenshots (`build/store-frame`, which lays it on a
+ * 1280×800 canvas in Playwright) and by extension pages, which draw either on a canvas around a
+ * capture through {@link windowChromeSvg} or {@link macWindowSvg} (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).
+ * toolbar with a pill omnibox) and AppKit's titled window as macOS 26 and later draw it, measured
+ * on macOS 27.2 (`NSThemeFrame`'s `cornerRadius` 16, a 32pt title bar, the window buttons 14pt
+ * at 9, 32 and 55 from the left and 9 from the top, the title in the 13pt headline font at 85,
+ * after the buttons).
  *
  * @module frame/window
  */
@@ -14,6 +19,9 @@
 /** 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 });
 
+/** A plain macOS window (macOS 26 and later): its title bar's height and its corners' radius (px). */
+export const MAC_WINDOW = Object.freeze({ titleBar: 32, radius: 16 });
+
 /** The window's default width (px): the store screenshot's. */
 export const WINDOW_W = 1152;
 
@@ -60,22 +68,69 @@ const icon = (name, size = 20) =>
 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. */
+/**
+ * A window's shadow: soft and dropped below it, as macOS draws one (px; `blur` as CSS's and a
+ * canvas's `shadowBlur`, twice the blur's standard deviation).
+ *
+ * @typedef {object} WindowShadow
+ * @property {number} y How far down it falls.
+ * @property {number} blur Its blur.
+ * @property {string} color Its colour.
+ */
+
+/** @type {{light: WindowShadow, dark: WindowShadow}} */
+const SHADOWS = {
+  light: { y: 24, blur: 60, color: 'rgba(31,45,70,.20)' },
+  dark: { y: 24, blur: 60, color: 'rgba(0,0,0,.55)' },
+};
+
+/**
+ * A window's shadow and its hairline rim as a CSS `box-shadow`.
+ *
+ * @param {WindowShadow} shadow - The shadow.
+ * @param {string} rim - The rim's colour.
+ * @returns {string} The `box-shadow` value.
+ */
+const boxShadow = (shadow, rim) => `0 ${shadow.y}px ${shadow.blur}px ${shadow.color}, 0 0 0 .5px ${rim}`;
+
+/**
+ * Chrome's light and dark window colours, a macOS title bar's (`titleBar`, and `titleLine` below
+ * it, as AppKit draws them), the canvas behind, and the window's shadow (`windowShadow` for a
+ * canvas's `shadow*`, `shadow` for CSS).
+ */
 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)',
+    contentLine: '#d3d7dc', titleBar: '#ffffff', titleLine: '#eaeaea',
+    windowShadow: SHADOWS.light, shadow: boxShadow(SHADOWS.light, '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)',
+    contentLine: '#2a2a2a', titleBar: '#282828', titleLine: '#3c3c3c',
+    windowShadow: SHADOWS.dark, shadow: boxShadow(SHADOWS.dark, 'rgba(255,255,255,.14)'),
   },
 };
 
+/** The traffic lights' colours: close, minimise, zoom. */
+const LIGHTS = ['#ff5f57', '#febc2e', '#28c840'];
+
+/** The traffic lights' styles: circles with a faint edge, their size and spacing set where they're placed. */
+const LIGHTS_CSS = `.lights { position: absolute; display: flex; }
+    .lights i { width: var(--light); height: var(--light); border-radius: 50%; display: block; box-shadow: inset 0 0 0 .5px rgba(0,0,0,.12); }`;
+
+/**
+ * macOS's traffic lights (styled by {@link LIGHTS_CSS}).
+ *
+ * @param {{left: number, top: number, size: number, gap: number}} place - The first one's left edge, their top edge, their size and the space between them (px).
+ * @returns {string} The HTML.
+ */
+const trafficLights = ({ left, top, size, gap }) =>
+  `<span class="lights" style="left:${left}px;top:${top}px;gap:${gap}px;--light:${size}px">${LIGHTS.map((color) => `<i style="background:${color}"></i>`).join('')}</span>`;
+
 /** @typedef {keyof typeof THEMES} Theme */
 
 /**
@@ -139,7 +194,7 @@ export function windowChrome({ tabs, url, urlHost, theme = 'light', w = WINDOW_W
   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>
+    ${trafficLights({ left: 16, top: 15, size: 12, gap: 8 })}
     ${tabHtml}
     <span class="plus" style="left:${plusX}px">${icon('add', 18)}</span>
   </div>
@@ -151,8 +206,7 @@ export function windowChrome({ tabs, url, urlHost, theme = 'light', w = WINDOW_W
   </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); }
+    ${LIGHTS_CSS}
     .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; }
@@ -189,9 +243,57 @@ export function windowChrome({ tabs, url, urlHost, theme = 'light', w = WINDOW_W
  */
 export function windowChromeSvg(options) {
   const w = options.w ?? WINDOW_W;
-  const h = WINDOW_BARS.strip + WINDOW_BARS.toolbar;
+  return svgImage(windowChrome({ ...options, w }), w, WINDOW_BARS.strip + WINDOW_BARS.toolbar);
+}
+
+/**
+ * A plain macOS window's title bar, as HTML: the traffic lights at the left, the title after
+ * them (macOS 26 on), a hairline below.
+ *
+ * @param {object} options - What to draw.
+ * @param {string} options.title - The window's title.
+ * @param {Theme} [options.theme] - Default light.
+ * @param {number} [options.w] - The window's width. Default {@link WINDOW_W}.
+ * @returns {string} The HTML, with its own styles.
+ */
+function macTitleBar({ title, theme = 'light', w = WINDOW_W }) {
+  const t = THEMES[theme];
+  return `
+  <div class="bar" style="width:${w}px">${trafficLights({ left: 9, top: 9, size: 14, gap: 9 })}<span class="title">${esc(title)}</span></div>
+  <style>
+    .bar { position: relative; height: ${MAC_WINDOW.titleBar}px; background: ${t.titleBar}; border-bottom: 1px solid ${t.titleLine}; box-sizing: border-box; }
+    ${LIGHTS_CSS}
+    .title { position: absolute; left: 85px; right: 16px; top: 0; color: ${t.tabText}; font: 600 13px/${MAC_WINDOW.titleBar - 1}px system-ui; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  </style>`;
+}
+
+/**
+ * A plain macOS window's title bar as a standalone SVG image, `w` wide and `MAC_WINDOW.titleBar`
+ * high (scale it when drawing), for an extension page to draw on a canvas as
+ * {@link windowChromeSvg}'s bars are drawn. The window's corners (`MAC_WINDOW.radius`) and its
+ * shadow (`THEMES[theme].windowShadow`) are the canvas's to draw.
+ *
+ * @param {Parameters<typeof macTitleBar>[0]} options - As {@link macTitleBar}.
+ * @returns {string} The SVG markup.
+ * @example
+ * const svg = macWindowSvg({ title: 'Example', theme: 'dark', w: 1280 });
+ */
+export function macWindowSvg(options) {
+  const w = options.w ?? WINDOW_W;
+  return svgImage(macTitleBar({ ...options, w }), w, MAC_WINDOW.titleBar);
+}
+
+/**
+ * HTML as a standalone SVG image, `w` × `h`.
+ *
+ * @param {string} html - The HTML (XML-clean).
+ * @param {number} w - Its width (px).
+ * @param {number} h - Its height.
+ * @returns {string} The SVG markup.
+ */
+function svgImage(html, w, h) {
   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>`
+    + `<div xmlns="http://www.w3.org/1999/xhtml" style="width:${w}px;height:${h}px;margin:0;-webkit-font-smoothing:antialiased">${html}</div>`
     + '</foreignObject></svg>';
 }

package/src/index.d.ts

@@ -2,8 +2,9 @@
  * 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), 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`
+ * the built-in AI row), Chrome's window drawn around a capture, per-site lists' sites, Chrome's on-device model,
+ * a content script's slices, change watcher and overlay, a module's function called in a page,
+ * and a tab's side panel opened from a click. Every function takes the `chrome`
  * APIs it uses as arguments, so tests run the real logic against fakes.
  *
  * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
@@ -15,13 +16,16 @@
 export { githubAboutLinks, isPlaceholder } from './about/links.js';
 export { MODEL_MESSAGES, chromeLanguageModel, createModelSession, describeModel, downloadModel, modelAvailability, } from './ai/model.js';
 export { setShortcuts } from './commands/shortcuts.js';
-export { BLOCK_CHARS, SLICE_MS, blocksOf, inSlices } from './content/slices.js';
+export { BLOCK_CHARS, SLICE_MS, blocksOf, eachInSlices, inSlices } from './content/slices.js';
+export { pageOverlay } from './content/overlay.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 { MAC_WINDOW, THEMES, WINDOW_BARS, WINDOW_W, letterIcon, macWindowSvg, 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';
+export { openSidePanel, sidePanelPath } from './panel/side-panel.js';
+export { callInPage, importAndCall } from './scripting/call.js';
 export { contentScriptSync } from './scripting/registration.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
@@ -46,11 +50,14 @@ export type ModelAnswer = import('./ai/model.js').ModelAnswer;
 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 PageOverlay = import('./content/overlay.js').PageOverlay;
 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 WindowShadow = import('./frame/window.js').WindowShadow;
 export type ModelRow = import('./ui/model-row.js').ModelRow;
 export type ContentScript = import('./scripting/registration.js').ContentScript;
+export type FrameResult = import('./scripting/call.js').FrameResult<unknown>;
 export type ActionMenu = import('./ui/menu.js').ActionMenu;
 export type MenuEntry = import('./ui/menu.js').MenuEntry;
 export type MenuItem = import('./ui/menu.js').MenuItem;
@@ -72,11 +79,14 @@ export type Toast = import('./ui/toast.js').Toast;
  * @typedef {import('./ai/model.js').ModelSession} ModelSession
  * @typedef {import('./ai/model.js').ModelStatus} ModelStatus
  * @typedef {import('./content/slices.js').SliceOptions} SliceOptions
+ * @typedef {import('./content/overlay.js').PageOverlay} PageOverlay
  * @typedef {import('./content/watch.js').WatchHandlers} WatchHandlers
  * @typedef {import('./frame/window.js').Tab} WindowTab
  * @typedef {import('./frame/window.js').Theme} WindowTheme
+ * @typedef {import('./frame/window.js').WindowShadow} WindowShadow
  * @typedef {import('./ui/model-row.js').ModelRow} ModelRow
  * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
+ * @typedef {import('./scripting/call.js').FrameResult<unknown>} FrameResult
  * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu
  * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry
  * @typedef {import('./ui/menu.js').MenuItem} MenuItem

package/src/index.js

@@ -2,8 +2,9 @@
  * 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), 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`
+ * the built-in AI row), Chrome's window drawn around a capture, per-site lists' sites, Chrome's on-device model,
+ * a content script's slices, change watcher and overlay, a module's function called in a page,
+ * and a tab's side panel opened from a click. Every function takes the `chrome`
  * APIs it uses as arguments, so tests run the real logic against fakes.
  *
  * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
@@ -18,13 +19,16 @@ export {
   MODEL_MESSAGES, chromeLanguageModel, createModelSession, describeModel, downloadModel, modelAvailability,
 } from './ai/model.js';
 export { setShortcuts } from './commands/shortcuts.js';
-export { BLOCK_CHARS, SLICE_MS, blocksOf, inSlices } from './content/slices.js';
+export { BLOCK_CHARS, SLICE_MS, blocksOf, eachInSlices, inSlices } from './content/slices.js';
+export { pageOverlay } from './content/overlay.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 { MAC_WINDOW, THEMES, WINDOW_BARS, WINDOW_W, letterIcon, macWindowSvg, 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';
+export { openSidePanel, sidePanelPath } from './panel/side-panel.js';
+export { callInPage, importAndCall } from './scripting/call.js';
 export { contentScriptSync } from './scripting/registration.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
@@ -57,11 +61,14 @@ export { TOAST_MS, createToast } from './ui/toast.js';
  * @typedef {import('./ai/model.js').ModelSession} ModelSession
  * @typedef {import('./ai/model.js').ModelStatus} ModelStatus
  * @typedef {import('./content/slices.js').SliceOptions} SliceOptions
+ * @typedef {import('./content/overlay.js').PageOverlay} PageOverlay
  * @typedef {import('./content/watch.js').WatchHandlers} WatchHandlers
  * @typedef {import('./frame/window.js').Tab} WindowTab
  * @typedef {import('./frame/window.js').Theme} WindowTheme
+ * @typedef {import('./frame/window.js').WindowShadow} WindowShadow
  * @typedef {import('./ui/model-row.js').ModelRow} ModelRow
  * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
+ * @typedef {import('./scripting/call.js').FrameResult<unknown>} FrameResult
  * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu
  * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry
  * @typedef {import('./ui/menu.js').MenuItem} MenuItem

package/src/panel/side-panel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Opening Chrome's side panel for one tab, from a click: the panel is the
+ * tab's own (no `side_panel` in the manifest, no global panel), so it shows
+ * only beside the page it's about and goes when the person switches tabs, as
+ * Chrome does for a tab's panel. Chrome opens a panel only while the click
+ * still counts, so nothing is awaited before `open`.
+ *
+ * @module panel/side-panel
+ */
+export type SidePanelApi = Pick<typeof chrome.sidePanel, 'setOptions' | 'open'>;
+/**
+ * The parts of `chrome.sidePanel` opening one uses.
+ *
+ * @typedef {Pick<typeof chrome.sidePanel, 'setOptions' | 'open'>} SidePanelApi
+ */
+/**
+ * The panel page's address for a tab: `path?tab=<id>`, so the page knows its tab.
+ *
+ * @param {string} path - The panel page, `panel/panel.html`.
+ * @param {number} tabId - The tab.
+ * @returns {string} `panel/panel.html?tab=12`.
+ */
+export declare const sidePanelPath: (path: string, tabId: number) => string;
+/**
+ * Open the side panel beside a tab, from a click (the toolbar button's, a
+ * shortcut's, or a button on an extension page).
+ *
+ * @param {SidePanelApi} sidePanel - `chrome.sidePanel` (or a fake in tests).
+ * @param {number} tabId - The tab.
+ * @param {string} path - The panel page; it gets `?tab=<id>`.
+ * @returns {Promise<void>} Once it's open; rejects when Chrome refuses (no click behind it).
+ * @example
+ * chrome.action.onClicked.addListener((tab) => openSidePanel(chrome.sidePanel, tab.id, 'panel/panel.html'));
+ */
+export declare function openSidePanel(sidePanel: SidePanelApi, tabId: number, path: string): Promise<void>;

package/src/panel/side-panel.js

@@ -0,0 +1,41 @@
+/**
+ * Opening Chrome's side panel for one tab, from a click: the panel is the
+ * tab's own (no `side_panel` in the manifest, no global panel), so it shows
+ * only beside the page it's about and goes when the person switches tabs, as
+ * Chrome does for a tab's panel. Chrome opens a panel only while the click
+ * still counts, so nothing is awaited before `open`.
+ *
+ * @module panel/side-panel
+ */
+
+/**
+ * The parts of `chrome.sidePanel` opening one uses.
+ *
+ * @typedef {Pick<typeof chrome.sidePanel, 'setOptions' | 'open'>} SidePanelApi
+ */
+
+/**
+ * The panel page's address for a tab: `path?tab=<id>`, so the page knows its tab.
+ *
+ * @param {string} path - The panel page, `panel/panel.html`.
+ * @param {number} tabId - The tab.
+ * @returns {string} `panel/panel.html?tab=12`.
+ */
+export const sidePanelPath = (path, tabId) => `${path}?tab=${tabId}`;
+
+/**
+ * Open the side panel beside a tab, from a click (the toolbar button's, a
+ * shortcut's, or a button on an extension page).
+ *
+ * @param {SidePanelApi} sidePanel - `chrome.sidePanel` (or a fake in tests).
+ * @param {number} tabId - The tab.
+ * @param {string} path - The panel page; it gets `?tab=<id>`.
+ * @returns {Promise<void>} Once it's open; rejects when Chrome refuses (no click behind it).
+ * @example
+ * chrome.action.onClicked.addListener((tab) => openSidePanel(chrome.sidePanel, tab.id, 'panel/panel.html'));
+ */
+export function openSidePanel(sidePanel, tabId, path) {
+  // Not awaited: open() must be called while the click still counts.
+  sidePanel.setOptions({ tabId, path: sidePanelPath(path, tabId), enabled: true }).catch((error) => console.error('Setting the side panel up:', error));
+  return sidePanel.open({ tabId });
+}

package/src/scripting/call.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Calling one of an extension module's functions in a page: `executeScript`
+ * runs a small function in the page's isolated world that imports the module
+ * (by its extension address, so it must be listed in `web_accessible_resources`)
+ * and calls the export named, with arguments that survive structured cloning.
+ * The module, and anything it keeps, stays loaded in that world between calls,
+ * so a content script can hold a session (a picker, an inspector) across them.
+ *
+ * @module scripting/call
+ */
+export type CallScripting = Pick<typeof chrome.scripting, 'executeScript'>;
+export type FrameResult<T> = {
+    /**
+     * The frame (0 is the top one).
+     */
+    frameId: number;
+    /**
+     * The function's result, once its promise settled.
+     */
+    result: T;
+};
+/**
+ * The parts of `chrome.scripting` a call uses.
+ *
+ * @typedef {Pick<typeof chrome.scripting, 'executeScript'>} CallScripting
+ */
+/**
+ * What one frame's call gave back.
+ *
+ * @template T
+ * @typedef {object} FrameResult
+ * @property {number} frameId The frame (0 is the top one).
+ * @property {T} result The function's result, once its promise settled.
+ */
+/**
+ * The function `executeScript` runs in the page: alone, without closures.
+ *
+ * @param {string} module - The module's path in the extension, `content/main.js`.
+ * @param {string} name - The export to call.
+ * @param {unknown[]} args - Its arguments.
+ * @returns {Promise<unknown>} What it returns.
+ */
+export declare const importAndCall: (module: string, name: string, args: unknown[]) => Promise<unknown>;
+/**
+ * Call `name` from the extension module `module` in the target's frames.
+ *
+ * @template [T=unknown]
+ * @param {CallScripting} scripting - `chrome.scripting` (or a fake in tests).
+ * @param {chrome.scripting.InjectionTarget} target - The tab, and which frames (`allFrames`, `frameIds`).
+ * @param {string} module - The module's path in the extension (listed in `web_accessible_resources`).
+ * @param {string} name - The exported function.
+ * @param {unknown[]} [args] - Its arguments (structured-cloneable).
+ * @param {{immediately?: boolean}} [options] - `immediately` (default true): don't wait for the
+ *   page to be idle, which a page still loading ads or a player may not be for a long time.
+ * @returns {Promise<FrameResult<T>[]>} Each frame's result, frames Chrome couldn't run in left out;
+ *   rejects when it can run in none (a page Chrome keeps to itself, no access).
+ * @example
+ * const [{ result }] = await callInPage(chrome.scripting, { tabId }, 'content/main.js', 'scan', [options]);
+ * await callInPage(chrome.scripting, { tabId, allFrames: true }, 'content/main.js', 'highlight', [key]);
+ */
+export declare function callInPage<T = unknown>(scripting: CallScripting, target: chrome.scripting.InjectionTarget, module: string, name: string, args?: unknown[], { immediately }?: {
+    immediately?: boolean;
+}): Promise<FrameResult<T>[]>;

package/src/scripting/call.js

@@ -0,0 +1,57 @@
+/**
+ * Calling one of an extension module's functions in a page: `executeScript`
+ * runs a small function in the page's isolated world that imports the module
+ * (by its extension address, so it must be listed in `web_accessible_resources`)
+ * and calls the export named, with arguments that survive structured cloning.
+ * The module, and anything it keeps, stays loaded in that world between calls,
+ * so a content script can hold a session (a picker, an inspector) across them.
+ *
+ * @module scripting/call
+ */
+
+/**
+ * The parts of `chrome.scripting` a call uses.
+ *
+ * @typedef {Pick<typeof chrome.scripting, 'executeScript'>} CallScripting
+ */
+
+/**
+ * What one frame's call gave back.
+ *
+ * @template T
+ * @typedef {object} FrameResult
+ * @property {number} frameId The frame (0 is the top one).
+ * @property {T} result The function's result, once its promise settled.
+ */
+
+/**
+ * The function `executeScript` runs in the page: alone, without closures.
+ *
+ * @param {string} module - The module's path in the extension, `content/main.js`.
+ * @param {string} name - The export to call.
+ * @param {unknown[]} args - Its arguments.
+ * @returns {Promise<unknown>} What it returns.
+ */
+export const importAndCall = (module, name, args) => import(chrome.runtime.getURL(module)).then((loaded) => loaded[name](...args));
+
+/**
+ * Call `name` from the extension module `module` in the target's frames.
+ *
+ * @template [T=unknown]
+ * @param {CallScripting} scripting - `chrome.scripting` (or a fake in tests).
+ * @param {chrome.scripting.InjectionTarget} target - The tab, and which frames (`allFrames`, `frameIds`).
+ * @param {string} module - The module's path in the extension (listed in `web_accessible_resources`).
+ * @param {string} name - The exported function.
+ * @param {unknown[]} [args] - Its arguments (structured-cloneable).
+ * @param {{immediately?: boolean}} [options] - `immediately` (default true): don't wait for the
+ *   page to be idle, which a page still loading ads or a player may not be for a long time.
+ * @returns {Promise<FrameResult<T>[]>} Each frame's result, frames Chrome couldn't run in left out;
+ *   rejects when it can run in none (a page Chrome keeps to itself, no access).
+ * @example
+ * const [{ result }] = await callInPage(chrome.scripting, { tabId }, 'content/main.js', 'scan', [options]);
+ * await callInPage(chrome.scripting, { tabId, allFrames: true }, 'content/main.js', 'highlight', [key]);
+ */
+export async function callInPage(scripting, target, module, name, args = [], { immediately = true } = {}) {
+  const frames = await scripting.executeScript({ target, injectImmediately: immediately, func: importAndCall, args: [module, name, args] });
+  return frames.map((frame) => ({ frameId: frame.frameId, result: /** @type {T} */ (frame.result) }));
+}