@design.estate/wcctools 6.1.0 → 7.0.0

package/ts/capture/request.ts

@@ -0,0 +1,304 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureRequestError } from './errors.js';
+
+type IWccCaptureSubject = plugins.interfaces.IWccCaptureSubject;
+type TWccCaptureFraming = plugins.interfaces.TWccCaptureFraming;
+type TWccInteractionStep = plugins.interfaces.TWccInteractionStep;
+
+/** The limits every capture request is held to. */
+export const captureLimits = {
+  minWidth: 200,
+  maxWidth: 3840,
+  minHeight: 200,
+  maxHeight: 4320,
+  defaultHeight: 800,
+  /** Full-page captures are cut at this height in CSS pixels. */
+  maxFullPageHeight: 10_000,
+  defaultJpegQuality: 80,
+  maxSteps: 20,
+  stepTimeoutMs: 5_000,
+  maxWaitMs: 3_000,
+  defaultObserveMs: 500,
+  maxObserveMs: 5_000,
+  defaultMaxFrames: 12,
+  maxMaxFrames: 40,
+  defaultFrameQuality: 70,
+  maxSelectorLength: 500,
+  maxTextLength: 2_000,
+  maxKeyLength: 32,
+  maxSubjectLength: 200,
+} as const;
+
+/** The capture widths of the named viewports: the dees-domtools breakpoints. */
+export const captureViewportWidths: Readonly<Record<plugins.interfaces.TWccCaptureViewportPreset, number>> = {
+  phone: plugins.deesDomtools.breakpoints.phone,
+  phablet: plugins.deesDomtools.breakpoints.phablet,
+  tablet: plugins.deesDomtools.breakpoints.tablet,
+  desktop: plugins.deesDomtools.breakpoints.desktop,
+};
+
+const isViewportPreset = (valueArg: unknown): valueArg is plugins.interfaces.TWccCaptureViewportPreset => {
+  return typeof valueArg === 'string' && Object.hasOwn(captureViewportWidths, valueArg);
+};
+
+const framings: readonly TWccCaptureFraming[] = ['element', 'viewport', 'fullpage'];
+
+/** The preview set-up of a capture, validated and with its defaults applied. */
+export interface IWccResolvedView {
+  width: number;
+  height: number;
+  theme: plugins.interfaces.TWccTheme;
+  scale: 1 | 2;
+}
+
+export interface IWccResolvedImageOptions {
+  /** Undefined: the default framing of what the demo rendered. */
+  framing?: TWccCaptureFraming;
+  format: 'png' | 'jpeg';
+  /** JPEG quality; undefined for PNG. */
+  quality?: number;
+}
+
+export interface IWccResolvedScreenshotRequest {
+  subject: IWccCaptureSubject;
+  view: IWccResolvedView;
+  image: IWccResolvedImageOptions;
+}
+
+export interface IWccResolvedInteractionRequest {
+  subject: IWccCaptureSubject;
+  view: IWccResolvedView;
+  steps: TWccInteractionStep[];
+  observeMs: number;
+  maxFrames: number;
+  frameQuality: number;
+  finalScreenshot: IWccResolvedImageOptions | null;
+}
+
+const isInteger = (valueArg: unknown): valueArg is number => typeof valueArg === 'number' && Number.isInteger(valueArg);
+
+const requireIntegerIn = (valueArg: unknown, minArg: number, maxArg: number, nameArg: string): number => {
+  if (!isInteger(valueArg) || valueArg < minArg || valueArg > maxArg) {
+    throw new WccCaptureRequestError(`wcctools: ${nameArg} must be a whole number from ${minArg} to ${maxArg}.`);
+  }
+  return valueArg;
+};
+
+const requireText = (valueArg: unknown, maxLengthArg: number, nameArg: string, allowEmptyArg = false): string => {
+  if (typeof valueArg !== 'string' || (!allowEmptyArg && valueArg.trim() === '') || valueArg.length > maxLengthArg) {
+    throw new WccCaptureRequestError(`wcctools: ${nameArg} must be ${allowEmptyArg ? 'a' : 'a non-empty'} string of at most ${maxLengthArg} characters.`);
+  }
+  return valueArg;
+};
+
+const resolveSubject = (subjectArg: unknown): IWccCaptureSubject => {
+  if (typeof subjectArg !== 'object' || subjectArg === null) {
+    throw new WccCaptureRequestError('wcctools: a capture needs a subject: the catalog entry to render.');
+  }
+  const subject = subjectArg as Partial<IWccCaptureSubject>;
+  const resolved: IWccCaptureSubject = {
+    itemName: requireText(subject.itemName, captureLimits.maxSubjectLength, 'the subject\'s itemName'),
+    demoIndex: subject.demoIndex === undefined ? 0 : requireIntegerIn(subject.demoIndex, 0, 1_000, 'the demo index'),
+  };
+  if (subject.sectionName !== undefined) {
+    resolved.sectionName = requireText(subject.sectionName, captureLimits.maxSubjectLength, 'the subject\'s sectionName');
+  }
+  return resolved;
+};
+
+/** Reads a viewport: a named one, or a width in CSS pixels. */
+export const resolveViewportWidth = (viewportArg: unknown): number => {
+  if (viewportArg === undefined) {
+    return captureViewportWidths.desktop;
+  }
+  if (isViewportPreset(viewportArg)) {
+    return captureViewportWidths[viewportArg];
+  }
+  if (isInteger(viewportArg)) {
+    return requireIntegerIn(viewportArg, captureLimits.minWidth, captureLimits.maxWidth, 'the viewport width');
+  }
+  throw new WccCaptureRequestError(
+    `wcctools: the viewport must be one of ${Object.keys(captureViewportWidths).join(', ')} or a width from ${captureLimits.minWidth} to ${captureLimits.maxWidth}.`,
+  );
+};
+
+const resolveView = (requestArg: plugins.interfaces.IWccCaptureView): IWccResolvedView => {
+  const theme = requestArg.theme ?? 'dark';
+  if (theme !== 'dark' && theme !== 'bright') {
+    throw new WccCaptureRequestError('wcctools: the theme must be dark or bright.');
+  }
+  const scale = requestArg.scale ?? 1;
+  if (scale !== 1 && scale !== 2) {
+    throw new WccCaptureRequestError('wcctools: the scale must be 1 or 2.');
+  }
+  return {
+    width: resolveViewportWidth(requestArg.viewport),
+    height: requestArg.height === undefined
+      ? captureLimits.defaultHeight
+      : requireIntegerIn(requestArg.height, captureLimits.minHeight, captureLimits.maxHeight, 'the height'),
+    theme,
+    scale,
+  };
+};
+
+const resolveImageOptions = (
+  optionsArg: { framing?: unknown; format?: unknown; quality?: unknown },
+): IWccResolvedImageOptions => {
+  const framing = optionsArg.framing;
+  if (framing !== undefined && !framings.includes(framing as TWccCaptureFraming)) {
+    throw new WccCaptureRequestError(`wcctools: the framing must be one of ${framings.join(', ')}.`);
+  }
+  const format = optionsArg.format ?? 'png';
+  if (format !== 'png' && format !== 'jpeg') {
+    throw new WccCaptureRequestError('wcctools: the format must be png or jpeg.');
+  }
+  if (format === 'png' && optionsArg.quality !== undefined) {
+    throw new WccCaptureRequestError('wcctools: a quality applies to jpeg only.');
+  }
+  return {
+    framing: framing as TWccCaptureFraming | undefined,
+    format,
+    quality: format === 'jpeg'
+      ? (optionsArg.quality === undefined ? captureLimits.defaultJpegQuality : requireIntegerIn(optionsArg.quality, 1, 100, 'the quality'))
+      : undefined,
+  };
+};
+
+/** Validates a screenshot request and applies its defaults. */
+export const resolveScreenshotRequest = (requestArg: plugins.interfaces.IWccScreenshotRequest): IWccResolvedScreenshotRequest => {
+  if (typeof requestArg !== 'object' || requestArg === null) {
+    throw new WccCaptureRequestError('wcctools: the screenshot request is missing.');
+  }
+  return {
+    subject: resolveSubject(requestArg.subject),
+    view: resolveView(requestArg),
+    image: resolveImageOptions(requestArg),
+  };
+};
+
+const resolveStep = (stepArg: unknown, indexArg: number): TWccInteractionStep => {
+  const name = `step ${indexArg}`;
+  if (typeof stepArg !== 'object' || stepArg === null) {
+    throw new WccCaptureRequestError(`wcctools: ${name} must be an object with an action.`);
+  }
+  const step = stepArg as Record<string, unknown>;
+  const selector = (requiredArg: boolean) => {
+    if (!requiredArg && step.selector === undefined) {
+      return undefined;
+    }
+    return requireText(step.selector, captureLimits.maxSelectorLength, `the selector of ${name}`);
+  };
+  switch (step.action) {
+    case 'click':
+    case 'hover':
+      return { action: step.action, selector: selector(true) };
+    case 'fill':
+      return {
+        action: 'fill',
+        selector: selector(true),
+        text: requireText(step.text, captureLimits.maxTextLength, `the text of ${name}`, true),
+      };
+    case 'press': {
+      const pressStep: TWccInteractionStep = {
+        action: 'press',
+        key: requireText(step.key, captureLimits.maxKeyLength, `the key of ${name}`),
+      };
+      const pressSelector = selector(false);
+      return pressSelector === undefined ? pressStep : { ...pressStep, selector: pressSelector };
+    }
+    case 'waitFor': {
+      const state = step.state ?? 'visible';
+      if (state !== 'visible' && state !== 'hidden') {
+        throw new WccCaptureRequestError(`wcctools: the state of ${name} must be visible or hidden.`);
+      }
+      return { action: 'waitFor', selector: selector(true), state };
+    }
+    case 'wait':
+      return { action: 'wait', ms: requireIntegerIn(step.ms, 0, captureLimits.maxWaitMs, `the time of ${name}`) };
+    default:
+      throw new WccCaptureRequestError(`wcctools: the action of ${name} must be one of click, hover, fill, press, waitFor, wait.`);
+  }
+};
+
+/** Validates an interaction request and applies its defaults. */
+export const resolveInteractionRequest = (requestArg: plugins.interfaces.IWccInteractionRequest): IWccResolvedInteractionRequest => {
+  if (typeof requestArg !== 'object' || requestArg === null) {
+    throw new WccCaptureRequestError('wcctools: the interaction request is missing.');
+  }
+  if (!Array.isArray(requestArg.steps) || requestArg.steps.length > captureLimits.maxSteps) {
+    throw new WccCaptureRequestError(`wcctools: an interaction has a list of at most ${captureLimits.maxSteps} steps.`);
+  }
+  if (requestArg.finalScreenshot !== undefined && (typeof requestArg.finalScreenshot !== 'object' || requestArg.finalScreenshot === null)) {
+    throw new WccCaptureRequestError('wcctools: finalScreenshot must be an object.');
+  }
+  return {
+    subject: resolveSubject(requestArg.subject),
+    view: resolveView(requestArg),
+    steps: requestArg.steps.map((stepArg, indexArg) => resolveStep(stepArg, indexArg)),
+    observeMs: requestArg.observeMs === undefined
+      ? captureLimits.defaultObserveMs
+      : requireIntegerIn(requestArg.observeMs, 0, captureLimits.maxObserveMs, 'observeMs'),
+    maxFrames: requestArg.maxFrames === undefined
+      ? captureLimits.defaultMaxFrames
+      : requireIntegerIn(requestArg.maxFrames, 1, captureLimits.maxMaxFrames, 'maxFrames'),
+    frameQuality: requestArg.frameQuality === undefined
+      ? captureLimits.defaultFrameQuality
+      : requireIntegerIn(requestArg.frameQuality, 1, 100, 'frameQuality'),
+    finalScreenshot: requestArg.finalScreenshot ? resolveImageOptions(requestArg.finalScreenshot) : null,
+  };
+};
+
+const describeEntry = (sectionNameArg: string, entryNameArg: string) => `${sectionNameArg}/${entryNameArg}`;
+
+const listSome = (namesArg: string[]): string => {
+  const shown = namesArg.slice(0, 20).join(', ');
+  return namesArg.length > 20 ? `${shown}, … (${namesArg.length} in all)` : shown;
+};
+
+/**
+ * Resolves a subject to one demo of the catalog: an entry named by its name or its element's tag,
+ * in the named section or, without one, in exactly one section.
+ */
+export const resolveSelection = (
+  manifestArg: plugins.interfaces.IWccCatalogManifest,
+  subjectArg: IWccCaptureSubject,
+): plugins.interfaces.IWccSelection => {
+  const sections = subjectArg.sectionName === undefined
+    ? manifestArg.sections
+    : manifestArg.sections.filter((sectionArg) => sectionArg.name === subjectArg.sectionName);
+  if (sections.length === 0) {
+    throw new WccCaptureRequestError(
+      `wcctools: the catalog has no section "${subjectArg.sectionName}". Sections: ${listSome(manifestArg.sections.map((sectionArg) => sectionArg.name))}.`,
+    );
+  }
+  const wanted = subjectArg.itemName;
+  const matchesName = (entryArg: { name: string; tagName: string | null }) => {
+    return entryArg.name === wanted || (entryArg.tagName !== null && entryArg.tagName === wanted.toLowerCase());
+  };
+  const matches = sections.flatMap((sectionArg) => sectionArg.entries
+    .filter(matchesName)
+    .map((entryArg) => ({ section: sectionArg, entry: entryArg })));
+  if (matches.length === 0) {
+    const withoutDemo = sections.flatMap((sectionArg) => sectionArg.entriesWithoutDemo
+      .filter(matchesName)
+      .map((entryArg) => describeEntry(sectionArg.name, entryArg.name)));
+    if (withoutDemo.length > 0) {
+      throw new WccCaptureRequestError(`wcctools: ${listSome(withoutDemo)} has no demo to capture.`);
+    }
+    const known = sections.flatMap((sectionArg) => sectionArg.entries.map((entryArg) => describeEntry(sectionArg.name, entryArg.name)));
+    throw new WccCaptureRequestError(`wcctools: the catalog has no entry "${wanted}". Entries: ${listSome(known)}.`);
+  }
+  if (matches.length > 1) {
+    throw new WccCaptureRequestError(
+      `wcctools: "${wanted}" names ${matches.length} entries (${listSome(matches.map((matchArg) => describeEntry(matchArg.section.name, matchArg.entry.name)))}); name its section.`,
+    );
+  }
+  const [{ section, entry }] = matches;
+  const demoIndex = subjectArg.demoIndex ?? 0;
+  if (demoIndex >= entry.demoCount) {
+    throw new WccCaptureRequestError(
+      `wcctools: ${describeEntry(section.name, entry.name)} has ${entry.demoCount} demo${entry.demoCount === 1 ? '' : 's'}; demo ${demoIndex} does not exist (demos count from 0).`,
+    );
+  }
+  return { sectionName: section.name, itemName: entry.name, demoIndex };
+};

package/ts/classes.bundlestatus.ts

@@ -0,0 +1,123 @@
+import * as plugins from './plugins.js';
+
+/** The longest time a status request waits for a change before it answers the unchanged status. */
+export const bundleStatusWaitLimitMs = 25_000;
+
+/** What a status request answers while the board is closed: the server is not serving. */
+export const bundleStatusClosedMessage = 'wcctools: the dev server is not serving the bundle status.';
+
+/**
+ * The status of the catalog bundles, as tswatch's bundle events report it, for the shell's
+ * `getBundleStatus` requests. Every event raises the revision and answers the requests waiting for
+ * a change. While closed (the server is not serving), requests are refused with a typed error, so
+ * a client backs off as it does for any failed request.
+ */
+export class WccBundleStatusBoard {
+  private readonly bundles = new Map<string, plugins.interfaces.IWccBundleStatus>();
+  private revision = 0;
+  private isOpen = false;
+  /** Settles one waiting request: answers the current snapshot, or refuses; each removes itself. */
+  private readonly waiters = new Set<(refusalArg?: Error) => void>();
+
+  /** Starts a run of the server: the bundles of an earlier run are forgotten. */
+  public open() {
+    this.bundles.clear();
+    this.isOpen = true;
+    this.changed();
+  }
+
+  /** Ends the run: every waiting request is refused now, later ones at once. */
+  public close() {
+    this.isOpen = false;
+    const refusal = this.createClosedError();
+    for (const settle of [...this.waiters]) {
+      settle(refusal);
+    }
+  }
+
+  /** The number of requests waiting for a change. */
+  public getWaiterCount(): number {
+    return this.waiters.size;
+  }
+
+  public record(eventArg: plugins.tswatch.TBundleEvent) {
+    const previous = this.bundles.get(eventArg.name);
+    const status: plugins.interfaces.IWccBundleStatus = { name: eventArg.name, state: eventArg.type };
+    switch (eventArg.type) {
+      case 'started':
+        // The latest completed run stays reported while the next one runs
+        if (previous?.durationMs !== undefined) {
+          status.durationMs = previous.durationMs;
+        }
+        if (previous?.errorMessage !== undefined) {
+          status.errorMessage = previous.errorMessage;
+        }
+        break;
+      case 'finished':
+        status.durationMs = eventArg.durationMs;
+        break;
+      case 'failed':
+        status.durationMs = eventArg.durationMs;
+        status.errorMessage = eventArg.errorMessage;
+        break;
+    }
+    this.bundles.set(eventArg.name, status);
+    this.changed();
+  }
+
+  public getSnapshot(): plugins.interfaces.IWccBundleStatusSnapshot {
+    return {
+      revision: this.revision,
+      bundles: [...this.bundles.values()].map((statusArg) => ({ ...statusArg })),
+    };
+  }
+
+  /**
+   * The snapshot once it differs from `afterRevisionArg`, or after the wait limit; at once without
+   * a revision or for a revision that is no longer current. Refused while closed. When
+   * `abortSignalArg` aborts (the client went away), the wait ends at once and releases its timer;
+   * it answers the current snapshot, which the transport drops.
+   */
+  public waitForChange(
+    afterRevisionArg: number | undefined,
+    abortSignalArg?: AbortSignal,
+  ): Promise<plugins.interfaces.IWccBundleStatusSnapshot> {
+    if (!this.isOpen) {
+      return Promise.reject(this.createClosedError());
+    }
+    if (afterRevisionArg === undefined || afterRevisionArg !== this.revision || abortSignalArg?.aborted) {
+      return Promise.resolve(this.getSnapshot());
+    }
+    return new Promise((resolve, reject) => {
+      const settle = (refusalArg?: Error) => {
+        clearTimeout(waitLimit);
+        abortSignalArg?.removeEventListener('abort', onAbort);
+        this.waiters.delete(settle);
+        if (refusalArg) {
+          reject(refusalArg);
+        } else {
+          resolve(this.getSnapshot());
+        }
+      };
+      const onAbort = () => settle();
+      const waitLimit = setTimeout(() => settle(), bundleStatusWaitLimitMs);
+      abortSignalArg?.addEventListener('abort', onAbort, { once: true });
+      this.waiters.add(settle);
+    });
+  }
+
+  private changed() {
+    this.revision++;
+    this.answerWaiters();
+  }
+
+  private answerWaiters() {
+    for (const settle of [...this.waiters]) {
+      settle();
+    }
+  }
+
+  private createClosedError() {
+    return new plugins.typedrequest.TypedResponseError(bundleStatusClosedMessage);
+  }
+}

package/ts/classes.devapi.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import { WccBundleStatusBoard } from './classes.bundlestatus.js';
 
 /**
  * The typed API the shell reaches on `/wcctools/typedrequest`. Later features register their
@@ -6,6 +7,8 @@ import * as plugins from './plugins.js';
  */
 export class WccDevApi {
   public readonly typedrouter = new plugins.typedrequest.TypedRouter();
+  /** The catalog bundles' status, fed with tswatch's bundle events while the server runs. */
+  public readonly bundleStatus = new WccBundleStatusBoard();
   private serverInfo: plugins.interfaces.IWccDevServerInfo | null = null;
 
   constructor() {
@@ -17,6 +20,12 @@ export class WccDevApi {
         return { ...this.serverInfo };
       }),
     );
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.interfaces.IReq_GetBundleStatus>('getBundleStatus', async (requestArg, typedToolsArg) => {
+        // A client that goes away ends its wait, so no waiter or timer outlives the request
+        return this.bundleStatus.waitForChange(requestArg.afterRevision, typedToolsArg?.abortSignal);
+      }),
+    );
   }
 
   public setServerInfo(infoArg: plugins.interfaces.IWccDevServerInfo) {