@arraypress/extension-kit 1.1.0 → 1.3.0

package/README.md

@@ -10,8 +10,13 @@ The pieces ArrayPress's Chrome extensions share, so each is written once:
   service worker shows the matching icon.
 - **About links**: README, Issues and PRIVACY.md in the extension's GitHub repository, plus
   package-time warnings for placeholder links.
-- **Build and test helpers** (Node): toolbar icon rendering, zipping for the Chrome Web Store, a
-  fake `chrome.storage`, Playwright helpers, packaging checks, and a copied-code guard.
+- **Chrome's page components**: the ⋮ action menu and its row button, the one-field dialog
+  ("Rename folder"), 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.
+- **Sites**: what people type into a per-site list, and whether a page is on one.
+- **Build and test helpers** (Node): icon rendering, vendoring npm packages (with a staleness
+  check), test builds, store screenshots, zipping for the Chrome Web Store, a fake
+  `chrome.storage`, Playwright helpers with time limits, packaging checks, and a copied-code guard.
 
 Zero dependencies. Every runtime function takes the `chrome` APIs it uses as arguments, so tests run
 the real logic against fakes.
@@ -50,6 +55,22 @@ import { startToolbarTheme } from '../vendor/extension-kit/index.js';
 The copy is made from the installed package every `npm install`, so it can't drift from the
 version in `package.json`. The zip helper leaves its `.d.ts` files out.
 
+Other libraries are copied the same way, by name (a path ending in `/` copies a folder's contents):
+
+```json
+{
+  "scripts": {
+    "postinstall": "extension-kit vendor extension/vendor/extension-kit && extension-kit vendor extension/vendor/clean-link @arraypress/clean-link src/",
+    "test": "extension-kit vendor-check && eslint . && …"
+  }
+}
+```
+
+`npm install some-package` doesn't run the extension's own `postinstall`, so a copy can go stale
+without a word. Each copy is stamped with its package's version (`vendored.json`, left out of the
+zip), and `extension-kit vendor-check` fails, naming the copy, until `npm run postinstall` remakes
+it. From a script: `vendorPackage(name, files, dest)`, `checkVendored(dir)`.
+
 ### An extension with a bundler
 
 Import `@arraypress/extension-kit` directly and copy the stylesheet into the build from
@@ -111,14 +132,17 @@ call `createToolbarTheme({storage, action, extensionId})` in the worker and pass
 the reports, which the content script sends with `reportColorScheme(media, stored,
 schemeSender(chrome.runtime))`.
 
-Render the glyphs from `icons/toolbar/glyph.svg` (and optional pixel-fitted `glyph-16.svg`):
+Render the glyphs from `icons/toolbar/glyph.svg` (and optional pixel-fitted `glyph-16.svg`), and
+the extension's own icon from `icons/icon.svg` to `icon-16.png` … `icon-128.png`, with the
+extension's Playwright:
 
-```js
-import { chromium } from 'playwright';
-import { renderToolbarIcons } from '@arraypress/extension-kit/build';
-await renderToolbarIcons({ chromium, dir: 'extension/icons/toolbar' });
+```json
+{ "scripts": { "icons": "extension-kit icons", "toolbar-icons": "extension-kit toolbar-icons" } }
 ```
 
+(`extension-kit toolbar-icons src/icons/toolbar` for another folder; from a script,
+`renderIcons` and `renderToolbarIcons({chromium, dir})`.)
+
 Colours are Chrome 157's toolbar icon colours, #474747 / #C7C7C7 (sources in the file).
 
 ## About links
@@ -132,6 +156,117 @@ At the end of `npm run package`, `printReleaseChecks(ABOUT_LINKS, REPOSITORY)` w
 link is a placeholder (`isPlaceholder`: example.com/.org/.net) and reminds you the repository must
 be public before the store listing goes live.
 
+## Page start-up
+
+```js
+const t = setUpPage(chrome, { title: 'optionsTitle', substitutions: [name] });
+```
+
+Reports the page's colour scheme for the toolbar glyph (`watchColorScheme`; a failure is only
+logged), fills its `data-i18n` text (`localize`), sets its title from a message, and returns the
+page's `t`.
+
+## Sites
+
+```js
+siteOrigin('example.com');                   // 'https://example.com', what Chrome grants access to
+siteHost(' https://www.GitHub.com/a ');      // 'github.com', what a per-site list keeps
+onSite(siteHost(location.href), neverSites); // on a listed site or a subdomain of one
+hostPatterns('github.com');                  // ['*://github.com/*', '*://*.github.com/*'] (excludeMatches)
+originPattern('https://bit.ly/x');           // 'https://bit.ly/*' (permissions.request)
+siteLabel('https://example.com');            // 'example.com', as a list shows it
+```
+
+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.
+
+## Page components
+
+Chrome's own components, made in the page by script (no markup to copy), styled by `chrome-ui.css`.
+Each takes `doc` (default `document`); the menu and the toast also take `root`, an element or a
+shadow root to go in (a content script's, so the page's styles never reach them), and follow the
+focus through shadow roots. The wording defaults to Chrome's English and takes a translation.
+
+### ⋮ menu (cr-action-menu)
+
+```js
+import { createMenu, moreActionsButton } from '../vendor/extension-kit/index.js';
+
+const menu = createMenu(); // one <dialog class="menu" role="menu"> for the page
+row.append(moreActionsButton(workspace.name, {
+  onClick: (anchor) => menu.open([
+    { label: 'Rename', run: () => rename(workspace) },
+    'separator',
+    { label: 'Delete', run: () => remove(workspace), disabled: locked },
+  ], { anchor }),
+}));
+// A right-click: menu.open(items, { x: event.clientX, y: event.clientY, focusTo: row });
+```
+
+It opens modally over its button, as Chrome's does (its top at the button's top, its end at the
+button's end), moved to stay 8px inside the window. A click outside, Esc, Tab or the window losing
+focus closes it; ↑/↓ (wrapping, past disabled items), Home and End move; focus goes back to the
+button (or `focusTo`); an item runs once the menu has closed. `createMenu({id, placement: 'below'})`
+opens it below the button instead. `menuPosition` and `isInside` are the pure geometry.
+
+`moreActionsButton(name, options)` is the 32px ⋮ icon button, labelled "More actions for “name”"
+(`label` for a translation), with `aria-haspopup="menu"`; its icon is the stylesheet's
+`.icon-more-vert` (`--icon-more-vert`, cr:more-vert), so the page needs no sprite. `className`,
+`tooltip` (a `title`) and `focusable: false` (out of the tab order, for a row that takes the focus)
+cover the rest.
+
+### One-field dialog (cr-dialog)
+
+```js
+const name = await askText({ title: 'Rename workspace', label: 'Name', value: workspace.name, maxLength: 200 });
+const site = await askText({
+  title: 'Add site', label: 'Site', action: 'Add',
+  validate: (text) => (siteFromInput(text) ? null : 'Enter a site, like example.com'),
+});
+```
+
+Resolves to the text, trimmed, or `null` when cancelled. The action button (default "Save") stays
+disabled while the text is blank or `validate` gives a reason, which shows under the field
+(`checkText` is that rule, pure). Enter presses the action button; Esc and Cancel cancel; the
+focus goes back to what had it, or to `returnTo` (an element, or a function asked at the end).
+One `#text-dialog` per page, made on first use.
+
+### Toast with Undo (cr-toast)
+
+```js
+const toast = createToast(); // at load, so screen readers know the live region
+toast.show(`Deleted “${workspace.name}”`, () => restore(workspace));
+toast.show('Copied'); // no Undo
+```
+
+`#toast` (`role="status"`), bottom left, a manual `popover` so it's in the top layer, over
+anything the page stacks (`:popover-open` while it shows). A new message replaces the last and
+restarts the wait: 10 seconds, as chrome://bookmarks's (`TOAST_MS`), or `duration` /
+`undoDuration`. Undo hides it and runs once. `undoLabel` translates the button.
+
+### Site list
+
+```js
+// A short list with an add row (chrome://settings), the markup in the page:
+// <ul class="list" id="sites"></ul> <p class="row text" id="no-sites">…</p>
+// <form class="row add" id="add-site"><input type="text" …><button type="submit">Add</button></form>
+const sites = createSiteList({
+  list: byId('sites'), empty: byId('no-sites'), form: byId('add-site', HTMLFormElement),
+  parse: siteOrigin,
+  add: async (origin) => (await chrome.permissions.request({ origins: [originPattern(origin)] })) && save(origin),
+  remove: (origin) => unsave(origin),
+  words: { remove: t('optionsRemove'), removeLabel: (site) => t('optionsRemoveLabel', [site]) },
+});
+sites.render(settings.sites);
+
+// Memory Saver's way (chrome://settings/performance): an Add button and the dialog, ⋮ Edit/Remove.
+createSiteList({ list, empty, addButton: byId('add-site'), parse: siteHost, add, remove, replace: (old, edited) => … });
+```
+
+`add` resolving to false keeps the typed text (access refused); `invalid(text)` hears what isn't
+a site in the add row; the dialog keeps its Add off with “Enter a site, like example.com” under
+the field. `words` translates `SITE_LIST_WORDS`.
+
 ## Build helpers (`@arraypress/extension-kit/build`)
 
 | Export | What it does |
@@ -139,7 +274,12 @@ be public before the store listing goes live.
 | `zipExtension(from, to, exclude?)` | Zip a folder for the Chrome Web Store, files only, less `ZIP_EXCLUDE` (icon SVG sources, `.d.ts`, `.DS_Store`). |
 | `shipsFile(file)` | Whether a file ships, by the same rules. |
 | `vendorKit(dest)` | Copy the browser half into an extension (the `extension-kit vendor` command). |
-| `renderToolbarIcons({chromium, dir})` | See above. |
+| `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. |
+| `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`. |
 | `placeholderWarning`, `repositoryReminder`, `printReleaseChecks` | See About links. |
 | `findDisallowedClones({runJscpd})` | Run jscpd and return clones `.jscpd-allowlist.json` doesn't cover (the `extension-kit duplication` command). |
 
@@ -159,12 +299,20 @@ except those listed, each with a reason:
 | `fakeChromeStorage({local, sync, session, now})` | In-memory `chrome.storage`: JSON copies, `onChanged` for real changes only, sync's 8,192-byte item quota and 120 writes a minute. `settled()` waits for listeners. |
 | `launchExtension(chromium, dir, options)` | Load an unpacked extension into a fresh profile; `{context, worker, extensionId, url(page), profile, close()}`. |
 | `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()}`. |
-| `checkRunner()` | Named checks that report and go on: `check(name, fn)`, `fail(name)` for an error found outside a check, `finish()`. |
+| `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. |
+| `within(promise, ms, fallback)` | The value in time, or the fallback (late or failed); never rejects; its timer cleared. |
+| `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)`. |
+| `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. |
 | `serve(routes, {port})` | Serve test pages on 127.0.0.1 from a table, a `Map` or a function of the path; `{origin, port, server, close()}`. |
 | `until(fn, what, timeout?)` | Poll until truthy. |
 | `offscreenEmulator(cdp)` | Emulate light/dark inside the offscreen document. |
 | `recordIconCalls(worker)` | Record `chrome.action.setIcon` calls Chrome accepted. |
-| `filesUnder`, `zipEntries`, `missingReferences`, `manifestReferences` | For a packaging test: the zip is the folder, and every path the extension names resolves. |
+| `installWarnings(worker, manifest)` | Chrome's own install warnings for a manifest (`chrome.management.getPermissionWarningsByManifest`, no permission needed), from a loaded extension's worker. |
+| `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. |
+| `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`). |
 
 ## Stylesheet classes
 
@@ -186,12 +334,14 @@ except those listed, each with a reason:
 | Toggle (cr-toggle) | `<input type="checkbox" class="switch" role="switch">` |
 | Select (md-select) | plain `<select>` |
 | Text field (cr-input) | plain `<input>`, `<textarea>`; `.field` > `label` + input for a labelled one |
+| Add row under a list | `<form class="row add">` with an `<input>` and a submit `<button>` (or `createSiteList`) |
 | Buttons (cr-button) | plain `<button>`; `.action` filled; `.link` as a link; `.icon-button` 32px round |
 | Settings menu | `.nav` > `ul.nav-list` > `a.nav-item[aria-current="page"]`, `.nav-separator` |
 | Manager layout | `.manager`/`.layout`, `.sidebar` with `.tree` > `.tree-item`, `.main` with `.list-card` |
-| Menu (cr-action-menu) | `<dialog class="menu">` of `button[role="menuitem"]`, `hr` |
-| Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` |
-| Toast (cr-toast) | `<div class="toast">text <button>Undo</button></div>` |
+| Menu (cr-action-menu) | `<dialog class="menu">` of `button[role="menuitem"]`, `hr` (or `createMenu`) |
+| ⋮ icon | `<span class="icon icon-more-vert" aria-hidden="true">` (or `moreActionsButton`) |
+| Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` (one field: `askText`) |
+| Toast (cr-toast) | `<div class="toast" popover="manual">text <button>Undo</button></div>` (or `createToast`); with `hidden` instead of `popover`, it shows over the page but not the top layer |
 | Drawer (cr-drawer) | `<dialog class="drawer">` with `.drawer-head` and a `.nav` |
 | Side panel page | `<body class="side-panel">`: the panel's colours, a column 100vh high |
 | Panel tabs (cr-tabs) | `<div class="tabs" role="tablist">` of `button.tab[role="tab"][aria-selected]` |
@@ -209,7 +359,9 @@ 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, and the
+`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
+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/bin/extension-kit.js

@@ -2,8 +2,16 @@
 /**
  * The kit's command line, run from an extension's npm scripts:
  *
- *   extension-kit vendor <dir>   copy the browser half into <dir> (npm install runs it)
- *   extension-kit duplication    fail on copied code jscpd finds, less .jscpd-allowlist.json
+ *   extension-kit vendor <dir>                      copy the kit's browser half into <dir> (postinstall)
+ *   extension-kit vendor <dir> <package> <path>...  copy files of an installed package into <dir>
+ *                                                   (a path ending in / copies its contents)
+ *   extension-kit vendor-check [dir]                fail when a copy in [dir] (default extension/vendor)
+ *                                                   no longer matches the installed package
+ *   extension-kit icons [dir]                       render [dir]/icon.svg (default extension/icons)
+ *   extension-kit toolbar-icons [dir]               render the toolbar glyph (default extension/icons/toolbar)
+ *   extension-kit duplication                       fail on copied code jscpd finds, less .jscpd-allowlist.json
+ *
+ * Playwright and jscpd are the extension's devDependencies, so they're resolved from there.
  *
  * @module bin/extension-kit
  */
@@ -11,16 +19,44 @@
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { findDisallowedClones } from '../src/build/duplication.js';
-import { vendorKit } from '../src/build/vendor.js';
+import { renderIcons, renderToolbarIcons } from '../src/build/toolbar-icons.js';
+import { checkVendored, vendorKit, vendorPackage } from '../src/build/vendor.js';
+
+const USAGE = `Usage:
+  extension-kit vendor <dir> [<package> <path>...]
+  extension-kit vendor-check [dir]
+  extension-kit icons [dir]
+  extension-kit toolbar-icons [dir]
+  extension-kit duplication`;
 
-const [command, arg] = process.argv.slice(2);
+const [command, ...args] = process.argv.slice(2);
+/** The extension's own `require`, for its devDependencies. */
+const extensionRequire = createRequire(path.join(process.cwd(), 'package.json'));
 
-if (command === 'vendor' && arg) {
-  await vendorKit(path.resolve(arg));
-  console.log(`extension-kit: copied into ${arg}`);
+if (command === 'vendor' && args.length === 1) {
+  await vendorKit(path.resolve(args[0]));
+  console.log(`extension-kit: copied into ${args[0]}`);
+} else if (command === 'vendor' && args.length >= 3) {
+  const [dir, name, ...files] = args;
+  await vendorPackage(name, files, path.resolve(dir));
+  console.log(`extension-kit: copied ${name} into ${dir}`);
+} else if (command === 'vendor-check' && args.length <= 1) {
+  const dir = args[0] ?? 'extension/vendor';
+  const stale = await checkVendored(dir);
+  for (const line of stale) console.error(line);
+  if (stale.length) {
+    console.error('\nThe vendored copies are out of date: run `npm run postinstall` (installing a package doesn\'t rerun it).');
+    process.exitCode = 1;
+  } else {
+    console.log(`${dir} matches the installed packages.`);
+  }
+} else if ((command === 'icons' || command === 'toolbar-icons') && args.length <= 1) {
+  const { chromium } = /** @type {typeof import('playwright')} */ (extensionRequire('playwright'));
+  const render = command === 'icons' ? renderIcons : renderToolbarIcons;
+  const dir = args[0] ?? (command === 'icons' ? 'extension/icons' : 'extension/icons/toolbar');
+  for (const file of await render({ chromium, dir })) console.log(`wrote ${file}`);
 } else if (command === 'duplication') {
-  // jscpd is the extension's devDependency, so resolve it from there.
-  const { runJscpd } = createRequire(path.join(process.cwd(), 'package.json'))('jscpd');
+  const { runJscpd } = extensionRequire('jscpd');
   const clones = await findDisallowedClones({ runJscpd });
   for (const clone of clones) console.error(`Copied code (${clone.lines} lines): ${clone.where}`);
   if (clones.length) {
@@ -30,6 +66,6 @@ if (command === 'vendor' && arg) {
     console.log('No copied code.');
   }
 } else {
-  console.error('Usage: extension-kit vendor <dir> | extension-kit duplication');
+  console.error(USAGE);
   process.exitCode = 2;
 }

package/package.json

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

package/src/build/index.d.ts

@@ -6,6 +6,8 @@
  */
 export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
 export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
-export { TOOLBAR_COLORS, TOOLBAR_ICON_COLORS, TOOLBAR_ICON_SIZES, renderToolbarIcons, toolbarIconFile } from './toolbar-icons.js';
-export { RUNTIME_ENTRIES, STYLESHEET, vendorKit } from './vendor.js';
+export * as storeFrame from './store-frame.js';
+export { HOOK_FILE, 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

@@ -7,6 +7,10 @@
 
 export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
 export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
-export { TOOLBAR_COLORS, TOOLBAR_ICON_COLORS, TOOLBAR_ICON_SIZES, renderToolbarIcons, toolbarIconFile } from './toolbar-icons.js';
-export { RUNTIME_ENTRIES, STYLESHEET, vendorKit } from './vendor.js';
+export * as storeFrame from './store-frame.js';
+export { HOOK_FILE, 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/store-frame.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Drawing kit for store screenshots: a 1280×800 canvas with a caption band and a Chrome window
+ * (macOS, light or dark, default theme). Everything here is presentation around real captures;
+ * nothing is a feature of the extension.
+ *
+ * Window metrics follow Chrome's 2023 refresh on macOS (tabs 34px high in a 42px strip, a 46px
+ * toolbar with a pill omnibox).
+ *
+ * Use it from an extension's `store/tools/make-screenshots.mjs`: capture the page content with
+ * Playwright at `geometry(zoom).content`, then screenshot `canvas({caption, chrome:
+ * windowChrome({tabs, url}), content})` at {@link W}×{@link H}.
+ *
+ * @module build/store-frame
+ */
+/** 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: {
+    x: number;
+    y: number;
+    w: number;
+    strip: number;
+    toolbar: number;
+};
+export type Geometry = {
+    /**
+     * The window's scale.
+     */
+    zoom: number;
+    /**
+     * The window's unscaled width.
+     */
+    w: number;
+    /**
+     * The size to capture page content at.
+     */
+    content: {
+        width: number;
+        height: number;
+    };
+};
+/**
+ * How a shot's window is laid out.
+ *
+ * @typedef {object} Geometry
+ * @property {number} zoom The window's scale.
+ * @property {number} w The window's unscaled width.
+ * @property {{ width: number, height: number }} content The size to capture page content at.
+ */
+/**
+ * A shot's window is drawn at `zoom` (scaled about its top-left corner) so text stays legible
+ * when the store shows screenshots small. Content is captured at 2× so the scaling stays sharp.
+ *
+ * @param {number} [zoom] - The window's scale. Default 1.
+ * @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.
+ *
+ * @param {number} x - Its tip, across the canvas.
+ * @param {number} y - Its tip, down the canvas.
+ * @returns {string} Absolutely positioned SVG.
+ */
+export declare const cursor: (x: number, y: number) => string;
+/**
+ * The full page: caption band, window, content and overlays.
+ *
+ * @param {object} options - What to draw.
+ * @param {string} options.caption - The headline above the window.
+ * @param {Theme} [options.theme] - Default light.
+ * @param {string} options.chrome - From windowChrome.
+ * @param {string} options.content - An <img> src (a capture at `geo.content` size) or raw HTML.
+ * @param {string} [options.overlays] - HTML drawn over the window.
+ * @param {Geometry} [options.geo] - Default geometry(1).
+ * @returns {string} A whole HTML document, W×H.
+ */
+export declare function canvas({ caption, theme, chrome, content, overlays, geo }: {
+    caption: string;
+    theme?: Theme;
+    chrome: string;
+    content: string;
+    overlays?: string;
+    geo?: Geometry;
+}): string;