@arraypress/extension-kit 1.9.0 → 1.10.0

package/README.md

@@ -245,16 +245,54 @@ 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; }' });
+// In the panel: every frame of the tab, or why it can't be read.
+const reading = await callInTab(chrome, tabId, 'content/main.js', 'scan');
+if (reading.state === 'read') show(reading.frames); // top frame first
+else showMessage(reading.state);                   // 'browser' (Chrome's own page) or 'no-access'
+
+// In the content script: a layer the page's styles can't touch (a closed shadow root). The host's
+// own styles go in hostStyle: its inline `all: initial !important` reset beats a `:host` rule.
+const { root, remove } = pageOverlay(document, {
+  name: 'my-inspector',
+  hostStyle: { position: 'fixed', inset: '0', 'z-index': '2147483647', 'pointer-events': 'none' },
+  css: `${HIGHLIGHT_CSS} .card { position: absolute; }`,
+});
+
+// “Show on page”: boxes in DevTools' blue, kept on the elements as the page scrolls; Esc clears.
+const highlight = createHighlighter(document, { root: () => root });
+highlight.show(elements, { reveal: true });
 ```
 
 `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.
+only while the click counts. `callInTab(edges, tabId, module, name, args)` calls it in every frame
+and gives `{state: 'read', frames}` (frames that answered, top first), or `{state: 'browser'}` for
+a page Chrome keeps to itself (`isBrowserPage(url)`: its own pages, the Web Store) or
+`{state: 'no-access'}` (the tab went to another site since the click). `pageOverlay` puts a host
+element of its own name on the root element, replacing one a run before left; `root` is its closed
+shadow root, `css` first. The host is reset inline (`all: initial !important`) so the page can't
+move or hide it; that also beats a `:host { … }` rule and `host.style.x = …`, so the host's own
+styles go in `hostStyle` (set `!important` after the reset). `createHighlighter(doc, {root, onClear,
+max})` boxes up to 500 elements (`MAX_BOXES`) in the overlay (`HIGHLIGHT_CSS` styles them), only
+those in the window, following the page as it scrolls; `show` replaces the set, `clear` or Esc
+ends it.
+
+```js
+// A page's elements in a line, and copying from a click (the copy command where the API can't).
+row.append(make('span', 'meta', '12 colours'), iconButton({ icon: 'i-copy', label: t('copy'), onClick: () => copyFormats(document, { text: hex }) }));
+```
+
+`make(tag, className, text, doc)`, `spriteIcon(id, className, doc)` (a `<use>` of the page's
+sprite) and `iconButton({icon, label, onClick, className, doc})` (tooltip and label) take the
+document the element belongs to, so a content script's overlay uses them too.
+`copyFormats(doc, {text, html})` puts plain text and HTML on the clipboard at once (a titled link
+for rich editors, its plain text for the rest) and resolves to whether it did; a content script
+can call it from a menu click or a shortcut (Chrome lets the focused active tab write), and
+`showPageToast(doc, 'Link copied', {name})` confirms it with Chrome's own toast in the page.
+`noticeCard({icon, tone, title, text, buttons, actions})` is a side panel's notice (`.sp-notice`:
+frames from other sites to allow); `counted(count, one, many, {t, lang})` a count in words.
 
 ## A content script on every site
 
@@ -350,6 +388,13 @@ changing (at most `maxWaitMs` while it keeps on); an element with a few children
 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`).
 
+`renderedElements(doc, {skip, limit})` (`content/elements.js`) lists every element Chrome draws,
+in document order, into open and closed shadow roots (`shadowRootOf`, through
+`chrome.dom.openOrClosedShadowRoot`) and through `display: contents` wrappers; what's inside a
+`visibility: hidden` element is still read, nothing inside `display: none`; at most 20,000
+(`MAX_ELEMENTS`). `otherSiteFrames(doc)` gives the origins of frames from other sites, which a
+reading of the tab leaves out until the person allows those sites.
+
 ## Time limits
 
 ```js
@@ -513,9 +558,10 @@ A list with an Add button needs every key but `optionsRemoveLabel`; one with an
 | `vendorPackage(name, files, dest)`, `packageDir(name)` | Copy files of an installed package, stamped (`extension-kit vendor <dir> <package> <path>...`). |
 | `checkVendored(dir)` | The stale copies under `dir` (`extension-kit vendor-check`). |
 | `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. |
+| `buildTestCopy({from, to, hook, manifest, panelOpener})` | A test build: the extension, `hook` as its service worker (`e2e-hook.js`), the manifest changed; with `panelOpener` (`'panel/panel.html'`), `e2e/open-panel.html?tab=<id>` (`PANEL_OPENER`), whose button opens that side panel beside the tab as the toolbar click does (Playwright can't click the toolbar; its title turns `opened`). |
 | `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` (and `windowChromeSvg`, from `frame/window.js`), `geometry`, `letterIcon`, `cursor`, `THEMES`, `W`×`H`. |
+| `storeShots({browser, dir, toolbarIcon})`, `storeShotHtml(shot)`, `contextMenuHtml(menu)`, `pngUrl(png)`, `PANEL_W`, `PANEL_HEADER_H` | The family's store screenshots in one style: a caption in sentence case over Chrome's light window with the extension pinned in the toolbar, real captures (taken at 2×) inside; what headless Chrome can't capture composed around the real extension UI: the popup page hung from the pressed toolbar button, the side panel page beside the page under a header with the extension's name, the right-click menu drawn as macOS draws Chrome's (the extension's real titles). `shoot(file, shot)` writes a 1280×800 PNG. |
 | `placeholderWarning`, `repositoryReminder`, `printReleaseChecks` | See About links. |
 | `findDisallowedClones({runJscpd})` | Run jscpd and return clones `.jscpd-allowlist.json` doesn't cover (the `extension-kit duplication` command). |
 
@@ -546,6 +592,9 @@ except those listed, each with a reason:
 | `realisticBrowser(options)`, `chromeUserAgent(browser)` | Launch options and a user agent for a browser that doesn't say it's automated, for live checks. |
 | `closeOnSignal(close)` | On Ctrl-C or a kill, close the run's browsers, then exit. |
 | `testBuildDir(root, name)` | As in `/build`, for the tests that load the build. |
+| `tabIdOf(worker, page)` | A Playwright page's tab id, as the extension's worker sees it. |
+| `callTabModule(worker, tabId, module, name, args)` | An export of the extension's page module called in a tab's frames, as `callInPage` does: `[{frameId, result}]`. |
+| `pierceNodes(cdp)`, `nodeAttribute(node, name)`, `nodeText(node)` | A page's whole tree through the DevTools protocol, closed shadow roots and frames included (where an extension's overlay is), and a node's attribute and text. |
 | `serve(routes, {port, tls})` | Serve test pages on 127.0.0.1 from a table, a `Map` or a function of the path; `{origin, port, server, close()}`. With `tls` (`testCertificate()`, a throwaway one from `openssl`), over HTTPS: for a site Chrome reaches only over HTTPS, mapped with `--host-resolver-rules`, Chromium started with `--ignore-certificate-errors`. |
 | `until(fn, what, timeout?)` | Poll until truthy. |
 | `offscreenEmulator(cdp)` | Emulate light/dark inside the offscreen document. |
@@ -554,6 +603,7 @@ except those listed, each with a reason:
 | `warningsAddedBy(worker, manifest, names)` | `{warnings, without, added}`: the warnings with and without some permissions, and those only they bring (`withoutPermissions` is the pure part). |
 | `savedTabGroups(profile)` | Chrome's saved tab groups (`{title, pinned, urls}`) read from a closed profile's `Sync Data/LevelDB`: no extension API lists them. |
 | `parseLiveOptions(argv, env, {usage})`, `parseProxy(address)` | A live checker's command line (`--only`, `--category`, `--concurrency`, `--proxy` or `HTTPS_PROXY`, `--locale`, `--timezone`, `--out`, `--help`), and a proxy address for Playwright with its password hidden for the output. |
+| `runLiveCheck({chromium, build, prefix, root, sites, categories, pageMs, visit, failed, onResult})`, `liveUsage(categories, n)` | A live checker's whole run: its command line (`parseLiveOptions`, usage from the categories), the sites chosen, the exit point printed, each site visited on a fresh page in a browser with the extension (one a slot, at most 4, passing for a person's), within `pageMs` (a browser whose page ran out of time replaced), Ctrl-C closing them all; `{dir, started, finished, exit, browser, results}` for the checker's report. |
 | `exitPoint(request)` | Where the run's traffic leaves for the internet (`{ip, country, where, source}`), from a keyless lookup service through the context's proxy: sites decide what to show by it. |
 | `filesUnder`, `zipEntries`, `missingReferences`, `manifestReferences` | For a packaging test: the zip is the folder, and every path the extension names resolves (a `#fragment` or `?query` ignored: `referencedPath`). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.9.0",
+  "version": "1.10.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/index.d.ts

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

package/src/build/index.js

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

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

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

package/src/build/store-shots.js

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

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

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

package/src/build/test-build.js

@@ -11,7 +11,7 @@
  * @module build/test-build
  */
 
-import { cp, readFile, rm, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 /** The environment variable that moves the test builds' folder (absolute, or relative to the extension's root). */
@@ -53,8 +53,42 @@ export function testBuildDir(root, name = 'e2e', env = process.env) {
  *   imports the real worker and exposes what a test can't reach headlessly (a menu click, the
  *   toolbar button).
  * @property {(manifest: TestManifest) => void} [manifest] Changes the copy's manifest in place.
+ * @property {string} [panelOpener] A side panel page (`panel/panel.html`): adds {@link PANEL_OPENER}
+ *   (`?tab=<id>`), whose button opens that panel beside the tab the way the toolbar click does
+ *   (the kit's `openSidePanel`, during a real click), which Playwright can't click. Its title turns
+ *   `opened` (or `error: …`). The kit must be vendored at `vendor/extension-kit/`.
  */
 
+/** The page {@link TestBuild}'s `panelOpener` adds, from the build's root. */
+export const PANEL_OPENER = 'e2e/open-panel.html';
+
+/**
+ * The opener page's markup (its script a file beside it: extension pages run no inline script).
+ *
+ * @returns {string} The HTML.
+ */
+const openerHtml = () => `<!doctype html>
+<meta charset="utf-8">
+<title>Open the side panel</title>
+<!-- Test builds only: a button that does what the toolbar click does, which Playwright can't click. -->
+<button id="open" type="button">Open the side panel</button>
+<script type="module" src="open-panel.js"></script>
+`;
+
+/**
+ * The opener page's script.
+ *
+ * @param {string} panel - The panel page.
+ * @returns {string} The module.
+ */
+const openerScript = (panel) => `import { openSidePanel } from '../vendor/extension-kit/panel/side-panel.js';
+
+const tabId = Number(new URLSearchParams(location.search).get('tab'));
+document.getElementById('open').addEventListener('click', () => {
+  openSidePanel(chrome.sidePanel, tabId, ${JSON.stringify(panel)}).then(() => { document.title = 'opened'; }, (error) => { document.title = \`error: \${error.message}\`; });
+});
+`;
+
 /**
  * Copy an extension folder into a test build, with its own hook and manifest.
  *
@@ -66,7 +100,7 @@ export function testBuildDir(root, name = 'e2e', env = process.env) {
  *   manifest: (manifest) => { manifest.host_permissions = ['http://127.0.0.1/*']; },
  * });
  */
-export async function buildTestCopy({ from, to, hook, manifest: change }) {
+export async function buildTestCopy({ from, to, hook, manifest: change, panelOpener }) {
   await rm(to, { recursive: true, force: true });
   await cp(from, to, { recursive: true });
   const file = path.join(to, 'manifest.json');
@@ -78,5 +112,10 @@ export async function buildTestCopy({ from, to, hook, manifest: change }) {
   }
   change?.(manifest);
   await writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`);
+  if (panelOpener) {
+    await mkdir(path.join(to, path.dirname(PANEL_OPENER)), { recursive: true });
+    await writeFile(path.join(to, PANEL_OPENER), openerHtml());
+    await writeFile(path.join(to, PANEL_OPENER.replace(/\.html$/, '.js')), openerScript(panelOpener));
+  }
   return to;
 }

package/src/content/elements.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A page's rendered elements, for a content script that reads them all: in
+ * document order, into open shadow roots and closed ones (where Chrome lets
+ * an extension see them, `chrome.dom.openOrClosedShadowRoot`), leaving out
+ * what Chrome doesn't render and what holds no page content (scripts,
+ * styles, templates, `<head>`).
+ *
+ * @module content/elements
+ */
+/** The most elements read (a very long page's first ones). */
+export declare const MAX_ELEMENTS = 20000;
+/**
+ * An element's shadow root, closed ones too where Chrome lets the extension see them.
+ *
+ * @param {Element} element - The element.
+ * @returns {ShadowRoot | null} Its shadow root.
+ * @example
+ * const root = shadowRootOf(host); // a closed root, from a content script
+ */
+export declare function shadowRootOf(element: Element): ShadowRoot | null;
+/**
+ * Every rendered element from the body down, in document order, a shadow root's elements before
+ * its host's children. An element Chrome doesn't draw (`visibility: hidden`) is left out, but
+ * what's inside it is still read (a child can be visible again), as is what's inside a
+ * `display: contents` element (a slot), which has no box of its own; nothing inside a
+ * `display: none` or `content-visibility: hidden` part is.
+ *
+ * @param {Document} doc - The page.
+ * @param {{skip?: (element: Element) => boolean, limit?: number}} [options] - `skip`: elements left
+ *   out with what's inside (the extension's overlay); `limit`: the most elements ({@link MAX_ELEMENTS}).
+ * @returns {Element[]} The elements.
+ * @example
+ * for (const element of renderedElements(document, { skip: isLayer })) read(element);
+ */
+export declare function renderedElements(doc: Document, { skip, limit }?: {
+    skip?: (element: Element) => boolean;
+    limit?: number;
+}): Element[];
+/**
+ * The origins of a page's frames that are another site's: their content isn't the page's to read,
+ * and an extension reads them only with that site's access (`chrome.permissions.request`, from a
+ * click). Frames inside shadow roots are found too.
+ *
+ * @param {Document} doc - The page.
+ * @param {Element[]} [elements] - Its elements, when already listed ({@link renderedElements}).
+ * @returns {string[]} Their origins (`https://ads.example.net`), each once.
+ * @example
+ * otherSiteFrames(document); // ['https://www.youtube.com']
+ */
+export declare function otherSiteFrames(doc: Document, elements?: Element[]): string[];