@design.estate/wcctools 6.1.0 → 7.0.0

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 };
+};