@design.estate/wcctools 6.2.0 → 7.0.0

package/readme.md

@@ -6,7 +6,8 @@
 
 `@design.estate/wcctools` provides a comprehensive development environment for web components, featuring:
 
-- 🖥️ **`wcctools dev`** — One command bundles your catalogue with live reload and serves it in the wcctools shell
+- 🖥️ **`wcctools dev`** — One command bundles your catalogue with live reload and serves it in the wcctools shell, on this machine only unless you expose it
+- 📸 **Headless Captures** — `wcctools screenshot` and the dev server's typed API screenshot any demo at any viewport and theme, and observe scripted interactions frame by frame
 - 🎨 **Interactive Component Catalogue** — Live preview with customizable sidebar sections
 - 🔧 **Real-time Property Editing** — Modify component props on the fly with auto-detected editors
 - 🌓 **Theme Switching** — Test light/dark modes instantly
@@ -30,6 +31,14 @@ pnpm add -D @design.estate/wcctools
 npm install @design.estate/wcctools --save-dev
 ```
 
+Captures run in a headless Chrome or Chromium found on the `PATH` (`google-chrome`, `chromium` or `chromium-browser`), driven by Puppeteer. pnpm asks whether Puppeteer's install script may run; without it, Puppeteer downloads no browser of its own and the one on the `PATH` is used:
+
+```yaml
+# pnpm-workspace.yaml
+allowBuilds:
+  puppeteer: false
+```
+
 ### Migrating from `@design.estate/dees-wcctools`
 
 `@design.estate/dees-wcctools` is now published as `@design.estate/wcctools`. Versions continue from 5.0.0 and the API is the same: swap the dependency and the import specifier.
@@ -56,6 +65,17 @@ A catalogue still on a 4.x or older release also follows the 5.0.0 changes: [`se
 
 Opened outside `wcctools dev` (for example from plain `tswatch`), the catalogue bundle shows a notice that names the command instead of the catalogue UI. `RecorderService`, `WccRecordButton` and `WccRecordingPanel` are no longer exported: recording lives in the shell.
 
+### Migrating to 7.0.0
+
+7.0.0 locks the dev server down, because its typed API now drives a headless browser:
+
+1. `wcctools dev` listens on `127.0.0.1` only. To open the catalogue from another machine, start it with `--host 0.0.0.0` (every interface; the machine's own addresses are then allowed) or `--host <address>`, and allow every further name you browse it under with `--allowed-host <name>`. Exposed this way, every machine that can reach the port can use the shell and the capture API: the `Host` and `Origin` checks below keep web pages in your browser from using the server, they do not authenticate other machines.
+2. Requests for a `Host` the server does not serve are refused with `403` and a message naming the `--allowed-host` to add.
+3. Typed requests and other state-changing requests, and WebSocket connections, are admitted only from the server's own origin; a request without an `Origin` header only from this machine.
+4. The preview no longer sends CORS headers: other origins cannot read the catalogue bundle.
+
+Nothing changes for a catalogue opened on `http://localhost:<port>/wcctools/`.
+
 ## Quick Start
 
 ### 1. Create Your Component
@@ -163,6 +183,7 @@ setupWccTools({
 ```bash
 pnpm exec wcctools dev            # port from the tswatch configuration, else 3002
 pnpm exec wcctools dev --port 0   # any free port
+pnpm exec wcctools dev --host 0.0.0.0 --allowed-host devbox.lan   # reachable from the network as devbox.lan
 ```
 
 It prints the shell's address, for example `wcctools dev: http://localhost:3002/wcctools/`. Saving a source file rebuilds the bundle and reloads only the preview frame; the shell keeps its state. When a bundle fails, the shell shows `bundle failed` with the bundler's message over the preview until the next run of that bundle finishes. `Ctrl+C` (or `SIGTERM`) stops the server and the watchers.
@@ -490,7 +511,7 @@ The preview document alone renders one demo from its own route, for tools that c
 
 ## API Reference
 
-### `wcctools dev [--port <port>]`
+### `wcctools dev [--port <port>] [--host <address>] [--allowed-host <name>…]`
 
 Bundles and watches the catalogue as the project's `@git.zone/tswatch` configuration describes (or tswatch's `element` preset) and serves on one port:
 
@@ -498,15 +519,83 @@ Bundles and watches the catalogue as the project's `@git.zone/tswatch` configura
 |------|--------|
 | `/` | Redirects to `/wcctools/` |
 | `/wcctools/`, `/wcctools-route/...` | The shell |
-| `/wcctools/typedrequest` | The shell's typed API: the server info (`getDevServerInfo`) and the bundle status (`getBundleStatus`) |
+| `/wcctools/typedrequest` | The typed API: the server info (`getDevServerInfo`), the bundle status (`getBundleStatus`) and [captures](#captures-on-the-typed-api) (`captureScreenshot`, `captureInteraction`) |
 | every other path | The catalogue's serve directory (default `dist_watch/`), with live reload for the preview document |
 
-`--port` overrides the configured port; `0` picks a free port.
+`--port` overrides the configured port; `0` picks a free port. `--host` sets the interface address to listen on (default `127.0.0.1`); `--allowed-host` (repeatable) adds a hostname or address the server answers.
+
+The shell follows the bundle status: per bundle the state of its latest run (`started`, `finished` or `failed`), the duration of the latest completed run and, while its latest completed run failed, the bundler's error message. A failed bundle is shown over the preview until a run of it finishes, which also reloads the preview.
 
-The shell follows the bundle status: per bundle the state of its latest run (`started`, `finished` or `failed`), the duration of the latest completed run and, while its latest completed run failed, the bundler's error message. A failed bundle is shown over the preview until a run of it finishes, which also reloads the preview. The typed API is read-only.
+#### Security model
+
+The dev server serves your source and drives a headless browser, so by default it answers only this machine (with `--host`, every machine that can reach the port; the checks below guard against web pages, not against other machines):
+
+- It listens on `127.0.0.1` unless `--host` says otherwise.
+- It answers only the hosts it serves: `localhost`, `127.0.0.1`, `::1`, the `--host` address (with `--host 0.0.0.0` or `::`, every address of the machine's interfaces) and each `--allowed-host`. Any other `Host` is refused with `403`, which defeats DNS rebinding.
+- Typed requests and every other request but `GET`, `HEAD` and `OPTIONS`, and WebSocket connections, must come from the server's own origin (`http://<allowed host>:<port>`). A request without an `Origin` header is admitted only from a loopback connection, as local tools send it. So other web pages you visit cannot drive the typed API, and since neither the shell nor the preview sends CORS headers, they cannot read the catalogue either. The same rule refuses the shell behind a TLS-terminating reverse proxy (see [Known Limitations](#known-limitations)).
 
 `wcctools dev` owns the process signals: on `SIGINT` or `SIGTERM` it stops the server and tswatch's bundling and watching once, within tswatch's shutdown deadline (the longest `stopGracePeriod` of the configured watcher commands plus a margin), and exits.
 
+### `wcctools screenshot <item | section/item> --out <file>`
+
+Bundles the catalogue of the working directory, serves it on a free loopback port, screenshots one demo in a headless browser, writes the image and stops.
+
+```bash
+wcctools screenshot my-button --out button.png                                   # desktop width, dark theme
+wcctools screenshot Elements/MyButton --demo 1 --viewport phone --theme bright --out button-phone.png
+wcctools screenshot Pages/Home --viewport tablet --out home.jpg                    # a page, in full
+wcctools screenshot my-card --viewport 720 --framing viewport --height 600 --scale 2 --out card@2x.png
+```
+
+| Option | Meaning |
+|--------|---------|
+| `<item>` | An entry's name or its element's tag; `section/item` when the name is in more than one section |
+| `--out` | The file to write; `.png`, `.jpg` or `.jpeg` sets the format |
+| `--demo` | The demo, counted from 0 as in the shell URL (default 0) |
+| `--viewport` | `phone` (400), `phablet` (600), `tablet` (1024), `desktop` (1600, the default) or a width from 200 to 3840 pixels; the widths are the dees-domtools breakpoints |
+| `--height` | Height of the preview window, which also sizes `100vh` (default 800) |
+| `--theme` | `dark` (default) or `bright` |
+| `--framing` | `element`: the rendered element, the default for element demos; `viewport`: the visible window; `fullpage`: the whole document, the default for pages (cut at 10000 pixels) |
+| `--scale` | Device pixel ratio, 1 (default) or 2 |
+| `--quality` | JPEG quality from 1 to 100 (default 80) |
+
+The capture waits for the preview's own signals, never for a fixed time: the preview bridge, the render's completed element updates and the document's fonts. It fails (exit code 1) when the bundle failed or the demo renders nothing; an entry that does not exist, or invalid options, exit with 2 and list what exists.
+
+### Captures on the typed API
+
+While `wcctools dev` runs, its typed API takes the same captures, in one shared headless browser that starts with the first capture, closes after a minute without one and always closes with the server. Two captures run at once and eight wait; more are refused as busy. Captures wait while a bundle builds and are refused while one failed. Every capture ends when its client goes away, and at its deadline, which counts from its request and includes waiting for a slot or a bundle: 30 seconds for a screenshot, 135 seconds for an interaction (20 steps of 5 seconds, 5 seconds of observation and 30 seconds of set-up). `TypedRequest.fire()` gives up after 60 seconds unless given a `timeoutMs`, so fire interactions with a `timeoutMs` above their deadline, as below.
+
+```typescript
+import { TypedRequest } from '@api.global/typedrequest';
+import type { IReq_CaptureScreenshot, IReq_CaptureInteraction } from '@design.estate/wcctools/interfaces';
+
+const endpoint = 'http://localhost:3002/wcctools/typedrequest';
+
+const shot = await new TypedRequest<IReq_CaptureScreenshot>(endpoint, 'captureScreenshot').fire({
+  subject: { itemName: 'my-button' },
+  viewport: 'phone',
+  theme: 'dark',
+});
+// shot.image: { mimeType: 'image/png', width, height, dataBase64 }
+
+const observed = await new TypedRequest<IReq_CaptureInteraction>(endpoint, 'captureInteraction').fire({
+  subject: { sectionName: 'Elements', itemName: 'MyInput' },
+  viewport: 'phone',
+  steps: [
+    { action: 'click', selector: 'input' },
+    { action: 'fill', selector: 'input', text: 'hello' },
+    { action: 'press', key: 'Enter' },
+    { action: 'waitFor', selector: '.error-message', state: 'hidden' },
+  ],
+  observeMs: 500,
+  maxFrames: 12,
+  finalScreenshot: { framing: 'element' },
+}, { timeoutMs: 140_000 }); // the interaction deadline is 135 s; fire() alone gives up after 60 s
+// observed.frames: viewport JPEGs with timestampMs; observed.steps: per step ok/error and its time
+```
+
+An interaction renders the demo, records the page's screencast while it runs the steps, keeps watching for `observeMs` after the last one (at most 5000) and returns at most `maxFrames` frames (at most 40) spread evenly over that time, the first and the last always among them. Steps are `click`, `hover`, `fill`, `press` (a key such as `Enter` or `Tab`, on a selector or the focused element), `waitFor` (`visible` or `hidden`) and `wait` (at most 3000 ms); there are at most 20. A selector is a CSS selector matched in the preview document and in every open shadow root below it, so `input` finds the input inside a component; the first match in document order is used once it is visible and enabled. Each step may take 5 seconds; a failing step ends the script and is reported with its error (`completed: false`), the frames up to then included. A capture stays on the preview route: a navigation that would replace the preview document (a link, a form submission, a script assigning `location`, a reload, also to the same URL, to `about:blank` or to a `blob:` URL) is cancelled as it starts, and the step that started it fails with `navigation to <url> blocked` and ends the script, so the final screenshot still shows the preview. A navigation started after the last step fails that step. The preview's history begins with the preview, so going back leaves nothing. A screenshot, or an interaction without steps, fails when its demo navigates away. Same-document navigations, such as fragment links and `history.pushState`, pass.
+
 Every `wcctools` command exits with code 2 on a usage error (an unknown command or option, a missing or invalid option value) and with 1 on any other failure.
 
 ### `wcctools check` and `wcctools fix`
@@ -577,7 +666,7 @@ The wrapper provides full DOM API access:
 
 ### `@design.estate/wcctools/interfaces`
 
-The contracts between the shell, the preview document and the dev server, for tools that drive a preview: the catalogue manifest (`IWccCatalogManifest`), the preview bridge the preview document installs as `window.wccPreview` (`IWccPreviewBridge`: render a demo, switch the theme, read and edit the rendered element's properties) and the dev server's typed requests, and the component standard's configuration and reports (`IStandardConfig`, `IStandardReport`, `IStandardFixResult`).
+The contracts between the shell, the preview document and the dev server, for tools that drive a preview: the catalogue manifest (`IWccCatalogManifest`), the preview bridge the preview document installs as `window.wccPreview` (`IWccPreviewBridge`: render a demo, switch the theme, read and edit the rendered element's properties) and the dev server's typed requests including the capture requests and their results (`IReq_CaptureScreenshot`, `IReq_CaptureInteraction`, `IWccImage`, `TWccInteractionStep`, …), and the component standard's configuration and reports (`IStandardConfig`, `IStandardReport`, `IStandardFixResult`).
 
 ```typescript
 import type { IWccPreviewBridge } from '@design.estate/wcctools/interfaces';
@@ -587,6 +676,15 @@ await bridge.render({ sectionName: 'Elements', itemName: 'MyButton', demoIndex:
 const properties = await bridge.getProperties();
 ```
 
+## Known Limitations
+
+- Captures need Chrome or Chromium on the `PATH`. In CI (`CI` set) or as root, the browser starts without its sandbox and prints a warning banner saying so.
+- Each start of the capture browser prints its launch arguments and executable on standard output (from `@push.rocks/smartbrowser`, which has no quiet option yet). The lines appear in the `wcctools dev` log on the first capture and in the output of `wcctools screenshot`, which therefore has no machine-readable output mode and writes images only to files.
+- A selector is matched within each document or shadow root on its own: `my-input input` does not reach into `my-input`'s shadow root, `input` does.
+- Captures wait for element updates and fonts, not for images or other resources a demo loads.
+- Captures cancel navigations through the Navigation API's `navigate` event before the demo's own listeners see it, so a demo that routes by calling `intercept()` on cross-document navigations does not route in a capture (its `intercept()` call throws). A `javascript:` URL navigates without that event; one that evaluates to a string replaces the preview document. A navigation Chrome does not let the page cancel (some history traversals; the preview's history holds only the preview, so there is none to traverse) is aborted at the network instead, may be reported on the step after the one that started it, and is not stopped when it loads nothing from the network.
+- The shell does not work through a TLS-terminating reverse proxy, even for a name given with `--allowed-host`: its typed requests and WebSocket connections then carry an `https:` origin (or the proxy's port), and the dev server admits only `http://<allowed host>:<port>` with its own port, so it refuses them; plain page loads still pass. Reach the dev server over plain HTTP on its own port, for example through an SSH tunnel.
+
 ## Project Structure
 
 ```

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/wcctools',
-  version: '6.2.0',
+  version: '7.0.0',
   description: 'A set of web component tools for creating element catalogues, enabling the structured development and documentation of custom elements and pages.'
 }

package/ts/capture/classes.capturebrowser.ts

@@ -0,0 +1,290 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureError, getErrorMessage } from './errors.js';
+
+type TBrowser = plugins.smartbrowser.puppeteer.Browser;
+type TBrowserContext = plugins.smartbrowser.puppeteer.BrowserContext;
+
+export interface IWccCaptureBrowserOptions {
+  /** Captures that run at once; default 2. */
+  maxConcurrent?: number;
+  /** Captures that wait for a slot; more are refused as busy. Default 8. */
+  maxQueued?: number;
+  /** The browser closes after this long without captures; default 60 s. */
+  idleCloseMs?: number;
+  /** How long closing the browser may take before its process is killed; default 5 s. */
+  closeTimeoutMs?: number;
+}
+
+interface IQueuedCapture {
+  grant: () => void;
+  refuse: (errorArg: Error) => void;
+}
+
+export const captureBrowserClosedMessage = 'wcctools: the dev server is not serving captures.';
+
+/**
+ * The headless browser of a dev server's captures: launched on the first capture, shared by the
+ * captures that follow and closed after a while without one, or when the server stops. Each
+ * capture runs in its own browser context, closed when it ends; a bounded number run at once and a
+ * bounded number wait for a slot. The browser leaves process signals to the application: the dev
+ * server's shutdown closes it.
+ */
+export class WccCaptureBrowser {
+  private readonly maxConcurrent: number;
+  private readonly maxQueued: number;
+  private readonly idleCloseMs: number;
+  private readonly closeTimeoutMs: number;
+  private isOpen = false;
+  private launching: Promise<TBrowser> | null = null;
+  private readonly closingBrowsers = new Set<Promise<void>>();
+  private readonly contexts = new Set<TBrowserContext>();
+  private readonly running = new Set<Promise<unknown>>();
+  private readonly queue: IQueuedCapture[] = [];
+  private activeCount = 0;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private launchCount = 0;
+
+  constructor(optionsArg: IWccCaptureBrowserOptions = {}) {
+    this.maxConcurrent = optionsArg.maxConcurrent ?? 2;
+    this.maxQueued = optionsArg.maxQueued ?? 8;
+    this.idleCloseMs = optionsArg.idleCloseMs ?? 60_000;
+    this.closeTimeoutMs = optionsArg.closeTimeoutMs ?? 5_000;
+  }
+
+  /** How often a browser was launched; one browser serves every capture while it runs. */
+  public getLaunchCount(): number {
+    return this.launchCount;
+  }
+
+  /** The process id of the running browser, or null while none runs. */
+  public async getProcessId(): Promise<number | null> {
+    const launching = this.launching;
+    if (!launching) {
+      return null;
+    }
+    const browser = await launching.catch(() => null);
+    return browser?.process()?.pid ?? null;
+  }
+
+  /** Takes captures from now on. */
+  public open() {
+    this.isOpen = true;
+  }
+
+  /**
+   * Refuses new captures and the waiting ones, ends the running ones by closing their contexts,
+   * closes the browser and resolves once all of it has settled.
+   */
+  public async close(): Promise<void> {
+    this.isOpen = false;
+    this.clearIdleTimer();
+    const refusal = new WccCaptureError(captureBrowserClosedMessage);
+    for (const queued of this.queue.splice(0)) {
+      queued.refuse(refusal);
+    }
+    await Promise.allSettled([...this.contexts].map((contextArg) => contextArg.close()));
+    await Promise.allSettled([...this.running]);
+    this.closeBrowser();
+    await Promise.allSettled([...this.closingBrowsers]);
+  }
+
+  /**
+   * Runs a capture in a browser context of its own, once a slot is free. The context closes when
+   * the capture ends, and at once when `abortSignalArg` aborts, which ends the capture with the
+   * signal's reason.
+   */
+  public async withContext<T>(
+    abortSignalArg: AbortSignal,
+    captureArg: (contextArg: TBrowserContext) => Promise<T>,
+  ): Promise<T> {
+    await this.acquireSlot(abortSignalArg);
+    const run = this.runInContext(abortSignalArg, captureArg);
+    this.running.add(run);
+    try {
+      return await run;
+    } finally {
+      this.running.delete(run);
+      this.releaseSlot();
+    }
+  }
+
+  private async runInContext<T>(
+    abortSignalArg: AbortSignal,
+    captureArg: (contextArg: TBrowserContext) => Promise<T>,
+  ): Promise<T> {
+    let context: TBrowserContext | null = null;
+    const closeContext = () => {
+      void context?.close().catch(() => {
+        // The context is gone already: its browser closed or disconnected
+      });
+    };
+    abortSignalArg.addEventListener('abort', closeContext, { once: true });
+    try {
+      const browser = await this.getBrowser();
+      abortSignalArg.throwIfAborted();
+      context = await browser.createBrowserContext();
+      this.contexts.add(context);
+      abortSignalArg.throwIfAborted();
+      if (!this.isOpen) {
+        // close() ran while the browser launched; it does not wait for this capture's context
+        throw new WccCaptureError(captureBrowserClosedMessage);
+      }
+      return await captureArg(context);
+    } catch (error) {
+      if (abortSignalArg.aborted) {
+        throw abortSignalArg.reason;
+      }
+      if (!this.isOpen) {
+        throw new WccCaptureError(captureBrowserClosedMessage);
+      }
+      throw error;
+    } finally {
+      abortSignalArg.removeEventListener('abort', closeContext);
+      if (context) {
+        this.contexts.delete(context);
+        if (context.browser().connected) {
+          await context.close().catch(() => {
+            // Closed meanwhile by an abort, or its browser disconnected
+          });
+        }
+      }
+    }
+  }
+
+  private acquireSlot(abortSignalArg: AbortSignal): Promise<void> {
+    if (!this.isOpen) {
+      return Promise.reject(new WccCaptureError(captureBrowserClosedMessage));
+    }
+    abortSignalArg.throwIfAborted();
+    this.clearIdleTimer();
+    if (this.activeCount < this.maxConcurrent) {
+      this.activeCount++;
+      return Promise.resolve();
+    }
+    if (this.queue.length >= this.maxQueued) {
+      return Promise.reject(new WccCaptureError(
+        `wcctools: the capture browser is busy (${this.maxConcurrent} captures running, ${this.queue.length} waiting); try again later.`,
+      ));
+    }
+    return new Promise<void>((resolve, reject) => {
+      const queued: IQueuedCapture = {
+        grant: () => {
+          abortSignalArg.removeEventListener('abort', onAbort);
+          resolve();
+        },
+        refuse: (errorArg) => {
+          abortSignalArg.removeEventListener('abort', onAbort);
+          reject(errorArg);
+        },
+      };
+      const onAbort = () => {
+        const index = this.queue.indexOf(queued);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+        }
+        queued.refuse(abortSignalArg.reason);
+      };
+      abortSignalArg.addEventListener('abort', onAbort, { once: true });
+      this.queue.push(queued);
+    });
+  }
+
+  private releaseSlot() {
+    const next = this.queue.shift();
+    if (next) {
+      // The slot passes to the next capture
+      next.grant();
+      return;
+    }
+    this.activeCount--;
+    if (this.activeCount === 0 && this.isOpen && this.launching) {
+      this.idleTimer = setTimeout(() => {
+        this.idleTimer = null;
+        if (this.activeCount === 0) {
+          this.closeBrowser();
+        }
+      }, this.idleCloseMs);
+      this.idleTimer.unref();
+    }
+  }
+
+  private clearIdleTimer() {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+  }
+
+  /** The running browser, launched when none runs; refused once close() ran, so it never outlives it. */
+  private getBrowser(): Promise<TBrowser> {
+    if (!this.isOpen) {
+      return Promise.reject(new WccCaptureError(captureBrowserClosedMessage));
+    }
+    this.launching ??= this.launch();
+    return this.launching;
+  }
+
+  private async launch(): Promise<TBrowser> {
+    this.launchCount++;
+    let browser: TBrowser;
+    try {
+      browser = await plugins.smartbrowser.getEnvAwareBrowserInstance({
+        launchOptions: {
+          // The application owns process signals: the dev server's shutdown closes the browser
+          handleSIGINT: false,
+          handleSIGTERM: false,
+          handleSIGHUP: false,
+        },
+      });
+    } catch (error) {
+      this.launching = null;
+      throw new WccCaptureError(
+        `wcctools: the capture browser failed to start: ${getErrorMessage(error)}. Captures need Chrome or Chromium: install google-chrome or chromium on the PATH.`,
+      );
+    }
+    const launching = this.launching;
+    browser.once('disconnected', () => {
+      // A crashed or closed browser is replaced by the next capture
+      if (this.launching === launching) {
+        this.launching = null;
+      }
+    });
+    return browser;
+  }
+
+  /** Closes the current browser, if one runs or launches; the next capture launches another. */
+  private closeBrowser() {
+    this.clearIdleTimer();
+    const launching = this.launching;
+    if (!launching) {
+      return;
+    }
+    this.launching = null;
+    const closing = launching
+      .then((browserArg) => this.closeWithin(browserArg), () => undefined)
+      .finally(() => {
+        this.closingBrowsers.delete(closing);
+      });
+    this.closingBrowsers.add(closing);
+  }
+
+  /** Closes a browser, and kills its process when closing takes longer than allowed. */
+  private async closeWithin(browserArg: TBrowser): Promise<void> {
+    if (!browserArg.connected) {
+      return;
+    }
+    let deadline: ReturnType<typeof setTimeout> | null = null;
+    const timedOut = new Promise<'timeout'>((resolve) => {
+      deadline = setTimeout(() => resolve('timeout'), this.closeTimeoutMs);
+    });
+    const closed = browserArg.close().then(() => 'closed' as const, () => 'failed' as const);
+    try {
+      const result = await Promise.race([closed, timedOut]);
+      if (result !== 'closed') {
+        browserArg.process()?.kill('SIGKILL');
+      }
+    } finally {
+      clearTimeout(deadline);
+    }
+  }
+}

package/ts/capture/classes.captureservice.ts

@@ -0,0 +1,152 @@
+import * as plugins from '../plugins.js';
+import type { WccBundleStatusBoard } from '../classes.bundlestatus.js';
+import { WccCaptureBrowser, captureBrowserClosedMessage, type IWccCaptureBrowserOptions } from './classes.capturebrowser.js';
+import { WccCaptureError } from './errors.js';
+import { runInteraction } from './interaction.js';
+import { renderPreview, screenshotPreview } from './previewpage.js';
+import { captureLimits, resolveInteractionRequest, resolveScreenshotRequest } from './request.js';
+
+/** The longest a screenshot may take, from its request to its image. */
+export const screenshotDeadlineMs = 30_000;
+
+/** The longest an interaction may take: its steps, its observation and the set-up around them. */
+export const interactionDeadlineMs = 30_000
+  + captureLimits.maxSteps * captureLimits.stepTimeoutMs
+  + captureLimits.maxObserveMs;
+
+/**
+ * The captures of a dev server: screenshots and observed interactions of single demos, taken in a
+ * headless browser on the server's preview route. A capture waits while a catalog bundle builds,
+ * and is refused when one failed, so it never shows a stale or broken bundle. Every capture has a
+ * deadline and ends when its client goes away. The service registers `captureScreenshot` and
+ * `captureInteraction` on the dev server's typed API.
+ */
+export class WccCaptureService {
+  private readonly browser: WccCaptureBrowser;
+  private origin: string | null = null;
+
+  constructor(
+    private readonly bundleStatus: WccBundleStatusBoard,
+    browserOptionsArg: IWccCaptureBrowserOptions = {},
+  ) {
+    this.browser = new WccCaptureBrowser(browserOptionsArg);
+  }
+
+  /** Registers the capture requests on a typed router. */
+  public addTypedHandlers(typedrouterArg: plugins.typedrequest.TypedRouter) {
+    typedrouterArg.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.interfaces.IReq_CaptureScreenshot>('captureScreenshot', async (requestArg, typedToolsArg) => {
+        return this.captureScreenshot(requestArg, typedToolsArg?.abortSignal);
+      }),
+    );
+    typedrouterArg.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.interfaces.IReq_CaptureInteraction>('captureInteraction', async (requestArg, typedToolsArg) => {
+        return this.captureInteraction(requestArg, typedToolsArg?.abortSignal);
+      }),
+    );
+  }
+
+  /** How often the capture browser was launched. */
+  public getBrowserLaunchCount(): number {
+    return this.browser.getLaunchCount();
+  }
+
+  /** The process id of the capture browser while it runs. */
+  public getBrowserProcessId(): Promise<number | null> {
+    return this.browser.getProcessId();
+  }
+
+  /** Takes captures of the dev server serving at `originArg` (scheme, host and port). */
+  public open(originArg: string) {
+    this.origin = originArg;
+    this.browser.open();
+  }
+
+  /** Ends every capture and closes the browser. */
+  public async close(): Promise<void> {
+    this.origin = null;
+    await this.browser.close();
+  }
+
+  public async captureScreenshot(
+    requestArg: plugins.interfaces.IWccScreenshotRequest,
+    abortSignalArg?: AbortSignal,
+  ): Promise<plugins.interfaces.IWccScreenshotResult> {
+    const request = resolveScreenshotRequest(requestArg);
+    return this.run(screenshotDeadlineMs, abortSignalArg, async (contextArg, originArg) => {
+      const preview = await renderPreview(contextArg, originArg, request.view, request.subject);
+      const shot = await screenshotPreview(preview, request.view, request.image);
+      await preview.navigationGuard.assertStayed('being captured');
+      return { selection: preview.selection, ...shot };
+    });
+  }
+
+  public async captureInteraction(
+    requestArg: plugins.interfaces.IWccInteractionRequest,
+    abortSignalArg?: AbortSignal,
+  ): Promise<plugins.interfaces.IWccInteractionResult> {
+    const request = resolveInteractionRequest(requestArg);
+    return this.run(interactionDeadlineMs, abortSignalArg, async (contextArg, originArg, signalArg) => {
+      const preview = await renderPreview(contextArg, originArg, request.view, request.subject);
+      const observed = await runInteraction(preview, request, signalArg);
+      const result: plugins.interfaces.IWccInteractionResult = { selection: preview.selection, ...observed };
+      if (request.finalScreenshot) {
+        result.finalImage = (await screenshotPreview(preview, request.view, request.finalScreenshot)).image;
+      }
+      return result;
+    });
+  }
+
+  /**
+   * Runs a capture within its deadline: waits for settled bundles, then runs it in a browser
+   * context of its own. The client's abort and the deadline both end it.
+   */
+  private async run<T>(
+    deadlineMsArg: number,
+    clientSignalArg: AbortSignal | undefined,
+    captureArg: (
+      contextArg: plugins.smartbrowser.puppeteer.BrowserContext,
+      originArg: string,
+      signalArg: AbortSignal,
+    ) => Promise<T>,
+  ): Promise<T> {
+    const origin = this.origin;
+    if (!origin) {
+      throw new WccCaptureError(captureBrowserClosedMessage);
+    }
+    const controller = new AbortController();
+    const deadline = setTimeout(() => {
+      controller.abort(new WccCaptureError(`wcctools: the capture did not finish within ${deadlineMsArg / 1000} s.`));
+    }, deadlineMsArg);
+    const onClientAbort = () => controller.abort(new WccCaptureError('wcctools: the client went away; the capture ended.'));
+    clientSignalArg?.addEventListener('abort', onClientAbort, { once: true });
+    if (clientSignalArg?.aborted) {
+      onClientAbort();
+    }
+    try {
+      await this.waitForSettledBundles(controller.signal);
+      return await this.browser.withContext(controller.signal, (contextArg) => captureArg(contextArg, origin, controller.signal));
+    } finally {
+      clearTimeout(deadline);
+      clientSignalArg?.removeEventListener('abort', onClientAbort);
+    }
+  }
+
+  /** Resolves once no bundle builds; refused while a bundle's latest run failed. */
+  private async waitForSettledBundles(abortSignalArg: AbortSignal): Promise<void> {
+    for (;;) {
+      abortSignalArg.throwIfAborted();
+      const snapshot = this.bundleStatus.getSnapshot();
+      const failed = snapshot.bundles.filter((bundleArg) => bundleArg.state === 'failed');
+      if (failed.length > 0) {
+        throw new WccCaptureError(
+          `wcctools: the catalog bundle failed, so there is nothing current to capture: ${failed.map((bundleArg) => `${bundleArg.name}: ${bundleArg.errorMessage ?? 'no message'}`).join('; ')}`,
+        );
+      }
+      if (!snapshot.bundles.some((bundleArg) => bundleArg.state === 'started')) {
+        return;
+      }
+      await this.bundleStatus.waitForChange(snapshot.revision, abortSignalArg);
+    }
+  }
+}