@design.estate/wcctools 6.2.0 → 7.0.0

package/ts/capture/classes.screencast.ts

@@ -0,0 +1,152 @@
+import * as plugins from '../plugins.js';
+import { toWccImage } from './images.js';
+
+type TPage = plugins.smartbrowser.puppeteer.Page;
+type TCDPSession = plugins.smartbrowser.puppeteer.CDPSession;
+
+interface IScreencastFrame {
+  /** Milliseconds since the recorder started. */
+  timestampMs: number;
+  dataBase64: string;
+}
+
+export interface IWccScreencastOptions {
+  /** JPEG quality from 1 to 100. */
+  quality: number;
+  /** Frames are scaled down to fit these device pixels. */
+  maxWidth: number;
+  maxHeight: number;
+  /** At most this many frames per second are kept; default 10. */
+  maxFps?: number;
+  /** The most frames kept over a whole recording; older ones are thinned out. Default 200. */
+  maxKeptFrames?: number;
+}
+
+/**
+ * Records a page's screencast (Chrome DevTools Protocol `Page.startScreencast`): JPEG frames the
+ * browser sends whenever the page paints, kept at a bounded rate and count. The page's last
+ * painted frame is always kept.
+ */
+export class WccScreencastRecorder {
+  private session: TCDPSession | null = null;
+  private startedAt = 0;
+  private readonly kept: IScreencastFrame[] = [];
+  /** The newest frame that arrived too soon after the last kept one. */
+  private latest: IScreencastFrame | null = null;
+  private stopped = false;
+  private ackFailure: unknown = null;
+  private readonly minFrameGapMs: number;
+  private readonly maxKeptFrames: number;
+
+  constructor(
+    private readonly page: TPage,
+    private readonly options: IWccScreencastOptions,
+  ) {
+    this.minFrameGapMs = 1000 / (options.maxFps ?? 10);
+    this.maxKeptFrames = options.maxKeptFrames ?? 200;
+  }
+
+  /** The time the recording started, as `Date.now()` read it. */
+  public getStartedAt(): number {
+    return this.startedAt;
+  }
+
+  public async start(): Promise<void> {
+    const session = await this.page.createCDPSession();
+    this.session = session;
+    session.on('Page.screencastFrame', this.onFrame);
+    this.startedAt = Date.now();
+    await session.send('Page.startScreencast', {
+      format: 'jpeg',
+      quality: this.options.quality,
+      maxWidth: this.options.maxWidth,
+      maxHeight: this.options.maxHeight,
+      everyNthFrame: 1,
+    });
+  }
+
+  /** Stops the screencast, detaches from the page and answers the kept frames in time order. */
+  public async stop(): Promise<plugins.interfaces.IWccTimedFrame[]> {
+    const session = this.session;
+    this.session = null;
+    if (session && !this.stopped) {
+      this.stopped = true;
+      session.off('Page.screencastFrame', this.onFrame);
+      if (!session.detached) {
+        try {
+          await session.send('Page.stopScreencast');
+        } finally {
+          await session.detach();
+        }
+      }
+    }
+    if (this.ackFailure) {
+      throw this.ackFailure;
+    }
+    if (this.latest && this.latest.timestampMs > (this.kept.at(-1)?.timestampMs ?? -1)) {
+      this.kept.push(this.latest);
+      this.latest = null;
+    }
+    return this.kept.map((frameArg) => ({
+      ...toWccImage(Buffer.from(frameArg.dataBase64, 'base64'), 'jpeg'),
+      timestampMs: frameArg.timestampMs,
+    }));
+  }
+
+  private readonly onFrame = (eventArg: { data: string; sessionId: number; metadata: { timestamp?: number } }) => {
+    const session = this.session;
+    if (!session) {
+      return;
+    }
+    // Chrome sends the next frame only once this one is acknowledged
+    session.send('Page.screencastFrameAck', { sessionId: eventArg.sessionId }).catch((error: unknown) => {
+      if (!this.stopped) {
+        this.ackFailure ??= error;
+      }
+    });
+    const paintedAt = eventArg.metadata.timestamp === undefined ? Date.now() : eventArg.metadata.timestamp * 1000;
+    const frame: IScreencastFrame = {
+      timestampMs: Math.max(0, Math.round(paintedAt - this.startedAt)),
+      dataBase64: eventArg.data,
+    };
+    const lastKept = this.kept.at(-1);
+    if (lastKept && frame.timestampMs - lastKept.timestampMs < this.minFrameGapMs) {
+      this.latest = frame;
+      return;
+    }
+    this.latest = null;
+    this.kept.push(frame);
+    if (this.kept.length > this.maxKeptFrames) {
+      // Thin out evenly: drop every other frame, keeping the first
+      for (let index = this.kept.length - 1; index > 0; index -= 2) {
+        this.kept.splice(index, 1);
+      }
+    }
+  };
+}
+
+/**
+ * Picks at most `maxFramesArg` frames spread evenly over the time the frames cover: for each of
+ * that many points in time, the frame on screen at that point. The first and the last frame are
+ * always among them.
+ */
+export const selectFrames = <T extends { timestampMs: number }>(framesArg: T[], maxFramesArg: number): T[] => {
+  if (framesArg.length <= maxFramesArg) {
+    return [...framesArg];
+  }
+  if (maxFramesArg === 1) {
+    return [framesArg[framesArg.length - 1]];
+  }
+  const first = framesArg[0].timestampMs;
+  const span = framesArg[framesArg.length - 1].timestampMs - first;
+  const picked = new Set<number>();
+  let frameIndex = 0;
+  for (let point = 0; point < maxFramesArg; point++) {
+    const time = point === maxFramesArg - 1 ? Number.POSITIVE_INFINITY : first + (span * point) / (maxFramesArg - 1);
+    while (frameIndex + 1 < framesArg.length && framesArg[frameIndex + 1].timestampMs <= time) {
+      frameIndex++;
+    }
+    picked.add(frameIndex);
+  }
+  return [...picked].sort((a, b) => a - b).map((indexArg) => framesArg[indexArg]);
+};

package/ts/capture/errors.ts

@@ -0,0 +1,25 @@
+import * as plugins from '../plugins.js';
+
+/**
+ * A capture that failed: the typed API answers it as a typed error with this message, the CLI
+ * prints it and exits with 1.
+ */
+export class WccCaptureError extends plugins.typedrequest.TypedResponseError {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'WccCaptureError';
+  }
+}
+
+/** A capture request that is invalid as given; the CLI exits with 2. */
+export class WccCaptureRequestError extends WccCaptureError {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'WccCaptureRequestError';
+  }
+}
+
+/** The message of any thrown value. */
+export const getErrorMessage = (errorArg: unknown): string => {
+  return errorArg instanceof Error ? errorArg.message : String(errorArg);
+};

package/ts/capture/images.ts

@@ -0,0 +1,61 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureError } from './errors.js';
+
+const pngSignature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/** The pixel size of a PNG, from its IHDR chunk. */
+const readPngSize = (bytesArg: Uint8Array): { width: number; height: number } | null => {
+  if (bytesArg.length < 24 || pngSignature.some((byteArg, indexArg) => bytesArg[indexArg] !== byteArg)) {
+    return null;
+  }
+  const view = new DataView(bytesArg.buffer, bytesArg.byteOffset, bytesArg.byteLength);
+  return { width: view.getUint32(16), height: view.getUint32(20) };
+};
+
+/** The pixel size of a JPEG, from its first start-of-frame segment. */
+const readJpegSize = (bytesArg: Uint8Array): { width: number; height: number } | null => {
+  if (bytesArg.length < 4 || bytesArg[0] !== 0xff || bytesArg[1] !== 0xd8) {
+    return null;
+  }
+  const view = new DataView(bytesArg.buffer, bytesArg.byteOffset, bytesArg.byteLength);
+  let offset = 2;
+  while (offset + 4 <= bytesArg.length) {
+    if (bytesArg[offset] !== 0xff) {
+      return null;
+    }
+    const marker = bytesArg[offset + 1];
+    // Markers without a length: fill bytes, TEM and RSTn
+    if (marker === 0xff) {
+      offset += 1;
+      continue;
+    }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+      offset += 2;
+      continue;
+    }
+    const length = view.getUint16(offset + 2);
+    const isStartOfFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+    if (isStartOfFrame) {
+      if (offset + 9 > bytesArg.length) {
+        return null;
+      }
+      return { width: view.getUint16(offset + 7), height: view.getUint16(offset + 5) };
+    }
+    offset += 2 + length;
+  }
+  return null;
+};
+
+/** An encoded image with its pixel size read from its own header. */
+export const toWccImage = (bytesArg: Uint8Array, formatArg: 'png' | 'jpeg'): plugins.interfaces.IWccImage => {
+  const size = formatArg === 'png' ? readPngSize(bytesArg) : readJpegSize(bytesArg);
+  if (!size) {
+    throw new WccCaptureError(`wcctools: the browser returned no valid ${formatArg.toUpperCase()} image.`);
+  }
+  return {
+    mimeType: formatArg === 'png' ? 'image/png' : 'image/jpeg',
+    width: size.width,
+    height: size.height,
+    dataBase64: Buffer.from(bytesArg.buffer, bytesArg.byteOffset, bytesArg.byteLength).toString('base64'),
+  };
+};

package/ts/capture/index.ts

@@ -0,0 +1,4 @@
+export * from './classes.captureservice.js';
+export * from './classes.capturebrowser.js';
+export * from './errors.js';
+export { captureLimits, captureViewportWidths, resolveScreenshotRequest, resolveInteractionRequest } from './request.js';

package/ts/capture/interaction.ts

@@ -0,0 +1,146 @@
+import * as plugins from '../plugins.js';
+import { getErrorMessage } from './errors.js';
+import { WccScreencastRecorder, selectFrames } from './classes.screencast.js';
+import { formatBlockedNavigation } from './navigationguard.js';
+import type { IWccRenderedPreview } from './previewpage.js';
+import { captureLimits, type IWccResolvedInteractionRequest } from './request.js';
+
+type TPage = plugins.smartbrowser.puppeteer.Page;
+type TWccInteractionStep = plugins.interfaces.TWccInteractionStep;
+
+/** A selector matched in the document and in every open shadow root below it. */
+const piercing = (selectorArg: string) => `pierce/${selectorArg}`;
+
+/** Resolves after `msArg`, or rejects with the signal's reason once it aborts; never leaves its timer behind. */
+const observe = (msArg: number, abortSignalArg: AbortSignal): Promise<void> => {
+  return new Promise<void>((resolve, reject) => {
+    if (abortSignalArg.aborted) {
+      reject(abortSignalArg.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortSignalArg.reason);
+    };
+    const timer = setTimeout(() => {
+      abortSignalArg.removeEventListener('abort', onAbort);
+      resolve();
+    }, msArg);
+    abortSignalArg.addEventListener('abort', onAbort, { once: true });
+  });
+};
+
+/** A step as its error messages name it: its action and its selector or key. */
+const describeStep = (stepArg: TWccInteractionStep): string => {
+  switch (stepArg.action) {
+    case 'press':
+      return stepArg.selector === undefined ? `press "${stepArg.key}"` : `press "${stepArg.key}" on "${stepArg.selector}"`;
+    case 'wait':
+      return `wait ${stepArg.ms} ms`;
+    default:
+      return `${stepArg.action} "${stepArg.selector}"`;
+  }
+};
+
+const runStep = async (pageArg: TPage, stepArg: TWccInteractionStep, abortSignalArg: AbortSignal): Promise<void> => {
+  const timeout = captureLimits.stepTimeoutMs;
+  switch (stepArg.action) {
+    case 'click':
+      await pageArg.locator(piercing(stepArg.selector)).setTimeout(timeout).click({ signal: abortSignalArg });
+      return;
+    case 'hover':
+      await pageArg.locator(piercing(stepArg.selector)).setTimeout(timeout).hover({ signal: abortSignalArg });
+      return;
+    case 'fill':
+      await pageArg.locator(piercing(stepArg.selector)).setTimeout(timeout).fill(stepArg.text, { signal: abortSignalArg });
+      return;
+    case 'press': {
+      if (stepArg.selector !== undefined) {
+        const handle = await pageArg.locator(piercing(stepArg.selector)).setTimeout(timeout).waitHandle({ signal: abortSignalArg });
+        try {
+          await handle.focus();
+        } finally {
+          await handle.dispose();
+        }
+      }
+      // Puppeteer refuses keys it does not know with an error naming the key
+      await pageArg.keyboard.press(stepArg.key as plugins.smartbrowser.puppeteer.KeyInput);
+      return;
+    }
+    case 'waitFor': {
+      const handle = await pageArg.waitForSelector(piercing(stepArg.selector), {
+        timeout,
+        signal: abortSignalArg,
+        ...(stepArg.state === 'hidden' ? { hidden: true } : { visible: true }),
+      });
+      await handle?.dispose();
+      return;
+    }
+    case 'wait':
+      await observe(stepArg.ms, abortSignalArg);
+      return;
+  }
+};
+
+/**
+ * Runs the steps on a rendered preview while recording its screencast, observes for a while after
+ * the last one and answers the steps' results and a bounded selection of the frames. A failed step
+ * ends the script; an abort ends it with the signal's reason. The page stays on the preview: a step
+ * that starts a navigation fails with the blocked navigation and ends the script; a navigation
+ * blocked during the observation fails the last step.
+ */
+export const runInteraction = async (
+  previewArg: IWccRenderedPreview,
+  requestArg: IWccResolvedInteractionRequest,
+  abortSignalArg: AbortSignal,
+): Promise<Omit<plugins.interfaces.IWccInteractionResult, 'selection' | 'finalImage'>> => {
+  const { page, navigationGuard } = previewArg;
+  const recorder = new WccScreencastRecorder(page, {
+    quality: requestArg.frameQuality,
+    maxWidth: requestArg.view.width * requestArg.view.scale,
+    maxHeight: requestArg.view.height * requestArg.view.scale,
+  });
+  const steps: plugins.interfaces.IWccInteractionStepResult[] = [];
+  let frames: plugins.interfaces.IWccTimedFrame[];
+  await recorder.start();
+  try {
+    const startedAt = recorder.getStartedAt();
+    for (const [index, step] of requestArg.steps.entries()) {
+      const startMs = Date.now() - startedAt;
+      let error: string | null = null;
+      try {
+        await runStep(page, step, abortSignalArg);
+      } catch (stepError) {
+        abortSignalArg.throwIfAborted();
+        error = getErrorMessage(stepError);
+      }
+      const blockedUrl = await navigationGuard.takeBlockedNavigation();
+      if (blockedUrl !== null) {
+        error = formatBlockedNavigation(blockedUrl);
+      }
+      const endMs = Date.now() - startedAt;
+      if (error === null) {
+        steps.push({ index, ok: true, startMs, endMs });
+        continue;
+      }
+      steps.push({ index, ok: false, error: `${describeStep(step)}: ${error}`, startMs, endMs });
+      break;
+    }
+    await observe(requestArg.observeMs, abortSignalArg);
+    const lastStep = steps.at(-1);
+    if (lastStep === undefined) {
+      await navigationGuard.assertStayed('being observed');
+    } else if (lastStep.ok) {
+      const blockedUrl = await navigationGuard.takeBlockedNavigation();
+      if (blockedUrl !== null) {
+        // Started after the last step ended: by that step, or by the demo on its own
+        lastStep.ok = false;
+        lastStep.error = `${describeStep(requestArg.steps[lastStep.index])}: ${formatBlockedNavigation(blockedUrl)}`;
+      }
+    }
+  } finally {
+    frames = await recorder.stop();
+  }
+  const completed = steps.length === requestArg.steps.length && steps.every((stepArg) => stepArg.ok);
+  return { frames: selectFrames(frames, requestArg.maxFrames), steps, completed };
+};

package/ts/capture/navigationguard.ts

@@ -0,0 +1,147 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureError, getErrorMessage } from './errors.js';
+
+type TPage = plugins.smartbrowser.puppeteer.Page;
+type THTTPRequest = plugins.smartbrowser.puppeteer.HTTPRequest;
+
+/** The message of a navigation the capture blocked. */
+export const formatBlockedNavigation = (urlArg: string): string => {
+  return `navigation to ${urlArg} blocked: a capture stays on the rendered preview`;
+};
+
+/** The preview window as the navigation guard's page script extends it. */
+interface IWccNavigationGuardWindow {
+  /** The URLs of the navigations the page script cancelled and nobody has read yet. */
+  wccCancelledNavigations?: string[];
+}
+
+/**
+ * Runs in the main frame before the preview's scripts, so its `navigate` listener is the first:
+ * cancels each navigation that would replace the document (a link, a form submission, a script
+ * assigning `location`, a reload, also to the same URL, to `about:blank` or a `blob:` URL) as it
+ * starts, and records its URL. Same-document navigations (`history.replaceState`, fragments) and
+ * downloads pass. Link clicks and scripts start their navigation while the step that caused it
+ * runs; form submissions in a task right after.
+ */
+const cancelLeavingNavigations = () => {
+  if (window !== window.top) {
+    return;
+  }
+  const cancelled: string[] = [];
+  (window as unknown as IWccNavigationGuardWindow).wccCancelledNavigations = cancelled;
+  navigation.addEventListener('navigate', (eventArg) => {
+    if (eventArg.destination.sameDocument || eventArg.downloadRequest !== null || !eventArg.cancelable) {
+      return;
+    }
+    eventArg.preventDefault();
+    cancelled.push(eventArg.destination.url);
+  });
+};
+
+/**
+ * Keeps a capture page on the preview. Its main frame loads the preview document once; after that,
+ * the page script above cancels every navigation that would replace the document before it starts.
+ * Request interception backs it up: a main-frame navigation request the page could not cancel is
+ * aborted before it leaves. The preview's history holds the preview alone, so there is no earlier
+ * document to go back to. Subframes and all other requests are left alone.
+ *
+ * `takeBlockedNavigation()` answers the navigation blocked since its last call, so each step of an
+ * interaction learns about the navigation it started.
+ */
+export class WccNavigationGuard {
+  /** Navigation requests aborted by the backstop since the last `takeBlockedNavigation()`. */
+  private abortedUrls: string[] = [];
+  private interceptionFailure: unknown = null;
+  private previewUrl: string | null;
+
+  private constructor(
+    private readonly page: TPage,
+    previewUrlArg: string,
+  ) {
+    this.previewUrl = new URL(previewUrlArg).href;
+  }
+
+  /**
+   * Installs the page script and intercepts the page's requests; the page's first main-frame
+   * navigation may load `previewUrlArg` only. Install before loading the preview.
+   */
+  public static async install(pageArg: TPage, previewUrlArg: string): Promise<WccNavigationGuard> {
+    const guard = new WccNavigationGuard(pageArg, previewUrlArg);
+    pageArg.on('request', (requestArg) => guard.decide(requestArg));
+    await pageArg.setRequestInterception(true);
+    await pageArg.evaluateOnNewDocument(cancelLeavingNavigations);
+    return guard;
+  }
+
+  /** Drops the history entries before the loaded preview (the blank page it opened as), so going back leaves nothing. */
+  public async forgetEarlierHistory(): Promise<void> {
+    const session = await this.page.createCDPSession();
+    try {
+      await session.send('Page.resetNavigationHistory');
+    } finally {
+      await session.detach();
+    }
+  }
+
+  /**
+   * Lets the page run the tasks queued so far (an animation frame, then a task), then answers the
+   * URL of the first navigation blocked since the last call, by the page script or the backstop,
+   * or null when none was.
+   */
+  public async takeBlockedNavigation(): Promise<string | null> {
+    const cancelledUrl = await this.page.evaluate(() => {
+      return new Promise<string | null>((resolve) => {
+        requestAnimationFrame(() => {
+          setTimeout(() => {
+            const cancelled = (window as unknown as IWccNavigationGuardWindow).wccCancelledNavigations ?? [];
+            resolve(cancelled[0] ?? null);
+            cancelled.length = 0;
+          }, 0);
+        });
+      });
+    });
+    if (this.interceptionFailure !== null) {
+      throw new WccCaptureError(`wcctools: the capture failed to handle a request of the preview: ${getErrorMessage(this.interceptionFailure)}`);
+    }
+    const abortedUrl = this.abortedUrls[0] ?? null;
+    this.abortedUrls = [];
+    return cancelledUrl ?? abortedUrl;
+  }
+
+  /** Throws when the page tried to leave the preview while `whileArg` (e.g. "rendering"). */
+  public async assertStayed(whileArg: string): Promise<void> {
+    const blockedUrl = await this.takeBlockedNavigation();
+    if (blockedUrl !== null) {
+      throw new WccCaptureError(`wcctools: the demo tried to navigate away while ${whileArg}; ${formatBlockedNavigation(blockedUrl)}.`);
+    }
+  }
+
+  private decide(requestArg: THTTPRequest) {
+    if (requestArg.isInterceptResolutionHandled()) {
+      return;
+    }
+    if (!requestArg.isNavigationRequest() || requestArg.frame() !== this.page.mainFrame()) {
+      this.settle(requestArg.continue());
+      return;
+    }
+    if (this.previewUrl !== null && requestArg.url() === this.previewUrl) {
+      // The preview document's own load, once
+      this.previewUrl = null;
+      this.settle(requestArg.continue());
+      return;
+    }
+    this.abortedUrls.push(requestArg.url());
+    // `aborted` drops the navigation without committing an error page, so the preview stays
+    this.settle(requestArg.abort('aborted'));
+  }
+
+  /**
+   * Keeps the first failure of an interception decision. Puppeteer itself tolerates a request
+   * that ended or a page that closed meanwhile; what reaches here fails the capture.
+   */
+  private settle(decisionArg: Promise<void>) {
+    decisionArg.catch((errorArg: unknown) => {
+      this.interceptionFailure ??= errorArg;
+    });
+  }
+}

package/ts/capture/previewpage.ts

@@ -0,0 +1,130 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureError, WccCaptureRequestError, getErrorMessage } from './errors.js';
+import { toWccImage } from './images.js';
+import { WccNavigationGuard } from './navigationguard.js';
+import { captureLimits, resolveSelection, type IWccResolvedImageOptions, type IWccResolvedView } from './request.js';
+
+type TBrowserContext = plugins.smartbrowser.puppeteer.BrowserContext;
+type TPage = plugins.smartbrowser.puppeteer.Page;
+
+/** How long the preview document may take to load and render its demo. */
+const previewStartTimeoutMs = 20_000;
+
+/** A preview document in the capture browser that rendered one demo. */
+export interface IWccRenderedPreview {
+  page: TPage;
+  /** Keeps the page on the preview and knows the navigation it blocked. */
+  navigationGuard: WccNavigationGuard;
+  selection: plugins.interfaces.IWccSelection;
+  /** What the demo rendered: an element demo or a page. */
+  type: 'element' | 'page';
+}
+
+const formatPageErrors = (errorsArg: string[]): string => {
+  return errorsArg.length > 0 ? ` The preview reported: ${errorsArg.slice(0, 5).join(' | ')}` : '';
+};
+
+/**
+ * Opens the preview route of the dev server at `originArg` in the context, waits for the preview
+ * runtime to install its bridge (it does once it rendered the route), resolves the subject against
+ * the catalog manifest and renders it. Waits only on the preview's own signals: the bridge, the
+ * render's completed updates and the document's fonts. The page stays on the preview: every
+ * later navigation of its main frame is blocked, and one blocked while rendering fails the capture.
+ */
+export const renderPreview = async (
+  contextArg: TBrowserContext,
+  originArg: string,
+  viewArg: IWccResolvedView,
+  subjectArg: plugins.interfaces.IWccCaptureSubject,
+): Promise<IWccRenderedPreview> => {
+  const page = await contextArg.newPage();
+  const pageErrors: string[] = [];
+  page.on('pageerror', (errorArg) => {
+    pageErrors.push(getErrorMessage(errorArg));
+  });
+  page.on('console', (messageArg) => {
+    if (messageArg.type() === 'error') {
+      pageErrors.push(messageArg.text());
+    }
+  });
+  await page.setViewport({ width: viewArg.width, height: viewArg.height, deviceScaleFactor: viewArg.scale });
+  await page.emulateMediaFeatures([
+    { name: 'prefers-color-scheme', value: viewArg.theme === 'bright' ? 'light' : 'dark' },
+  ]);
+
+  const previewUrl = `${originArg}${plugins.shared.previewRoutePath}${plugins.shared.formatPreviewQuery({ selection: null, theme: viewArg.theme })}`;
+  const navigationGuard = await WccNavigationGuard.install(page, previewUrl);
+  const response = await page.goto(previewUrl, { waitUntil: 'load', timeout: previewStartTimeoutMs });
+  if (!response?.ok()) {
+    throw new WccCaptureError(`wcctools: the preview document answered ${response?.status() ?? 'nothing'}.${formatPageErrors(pageErrors)}`);
+  }
+  await navigationGuard.forgetEarlierHistory();
+  try {
+    await page.waitForFunction(() => window.wccPreview !== undefined, { polling: 'raf', timeout: previewStartTimeoutMs });
+  } catch (error) {
+    throw new WccCaptureError(
+      `wcctools: the preview did not start within ${previewStartTimeoutMs / 1000} s (${getErrorMessage(error)}).${formatPageErrors(pageErrors)}`,
+    );
+  }
+
+  const manifest = await page.evaluate(() => window.wccPreview!.getManifest());
+  const selection = resolveSelection(manifest, subjectArg);
+  const outcome = await page.evaluate((selectionArg) => window.wccPreview!.render(selectionArg), selection);
+  if (outcome.kind === 'empty') {
+    throw new WccCaptureError(
+      `wcctools: ${selection.sectionName}/${selection.itemName} demo ${selection.demoIndex} did not render: ${outcome.emptyState.title}. ${outcome.emptyState.detail}${formatPageErrors(pageErrors)}`,
+    );
+  }
+  await page.evaluate(async () => {
+    await document.fonts.ready;
+  });
+  await navigationGuard.assertStayed('rendering');
+  return { page, navigationGuard, selection, type: outcome.type };
+};
+
+/** Screenshots a rendered preview as framed. */
+export const screenshotPreview = async (
+  previewArg: IWccRenderedPreview,
+  viewArg: IWccResolvedView,
+  optionsArg: IWccResolvedImageOptions,
+): Promise<{ framing: plugins.interfaces.TWccCaptureFraming; image: plugins.interfaces.IWccImage; truncated: boolean }> => {
+  const { page } = previewArg;
+  const framing = optionsArg.framing ?? (previewArg.type === 'page' ? 'fullpage' : 'element');
+  const encoding = { type: optionsArg.format, ...(optionsArg.quality === undefined ? {} : { quality: optionsArg.quality }) } as const;
+
+  if (framing === 'element') {
+    if (previewArg.type === 'page') {
+      throw new WccCaptureRequestError('wcctools: a page has no element to frame; use the viewport or fullpage framing.');
+    }
+    const handle = await page.evaluateHandle(() => window.wccPreview!.findRenderedInstance());
+    try {
+      const element = handle.asElement();
+      if (!element) {
+        throw new WccCaptureError(
+          `wcctools: the demo of ${previewArg.selection.itemName} renders no instance of its element; use the viewport framing.`,
+        );
+      }
+      const bytes = await element.screenshot(encoding);
+      return { framing, image: toWccImage(bytes, optionsArg.format), truncated: false };
+    } finally {
+      await handle.dispose();
+    }
+  }
+
+  if (framing === 'viewport') {
+    const bytes = await page.screenshot(encoding);
+    return { framing, image: toWccImage(bytes, optionsArg.format), truncated: false };
+  }
+
+  const documentHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+  if (documentHeight > captureLimits.maxFullPageHeight) {
+    const bytes = await page.screenshot({
+      ...encoding,
+      clip: { x: 0, y: 0, width: viewArg.width, height: captureLimits.maxFullPageHeight },
+      captureBeyondViewport: true,
+    });
+    return { framing, image: toWccImage(bytes, optionsArg.format), truncated: true };
+  }
+  const bytes = await page.screenshot({ ...encoding, fullPage: true });
+  return { framing, image: toWccImage(bytes, optionsArg.format), truncated: false };
+};