@design.estate/wcctools 6.2.0 → 7.0.0

package/ts/cli.screenshot.ts

@@ -0,0 +1,95 @@
+import * as plugins from './plugins.js';
+import { WccDevServer } from './classes.devserver.js';
+import { WccCaptureRequestError, captureViewportWidths, resolveScreenshotRequest } from './capture/index.js';
+
+/** Reads `<item>` or `<section>/<item>`. */
+const parseSubject = (argsArg: readonly string[], demoArg: number | undefined): plugins.interfaces.IWccCaptureSubject => {
+  if (argsArg.length !== 1 || argsArg[0].trim() === '') {
+    throw new WccCaptureRequestError('wcctools screenshot: name one catalog entry, as <item> or <section>/<item>.');
+  }
+  const [subject] = argsArg;
+  const slash = subject.indexOf('/');
+  const named: plugins.interfaces.IWccCaptureSubject = slash === -1
+    ? { itemName: subject }
+    : { sectionName: subject.slice(0, slash), itemName: subject.slice(slash + 1) };
+  return demoArg === undefined ? named : { ...named, demoIndex: demoArg };
+};
+
+/** Reads a named viewport or a width in pixels. */
+const parseViewport = (valueArg: string | undefined): plugins.interfaces.TWccCaptureViewport | undefined => {
+  if (valueArg === undefined) {
+    return undefined;
+  }
+  if (Object.hasOwn(captureViewportWidths, valueArg)) {
+    return valueArg as plugins.interfaces.TWccCaptureViewportPreset;
+  }
+  if (/^\d+$/.test(valueArg)) {
+    return Number(valueArg);
+  }
+  throw new WccCaptureRequestError(
+    `wcctools screenshot: --viewport must be one of ${Object.keys(captureViewportWidths).join(', ')} or a width in pixels.`,
+  );
+};
+
+/** The image format the output file's extension names. */
+const formatForFile = (fileArg: string): 'png' | 'jpeg' => {
+  const extension = plugins.path.extname(fileArg).toLowerCase();
+  if (extension === '.png') {
+    return 'png';
+  }
+  if (extension === '.jpg' || extension === '.jpeg') {
+    return 'jpeg';
+  }
+  throw new WccCaptureRequestError('wcctools screenshot: --out must name a .png, .jpg or .jpeg file.');
+};
+
+/**
+ * `wcctools screenshot`: bundles the catalog of the working directory, serves it on a free
+ * loopback port, screenshots one demo in a headless browser, writes the image and stops.
+ */
+export const registerScreenshotCommand = (out: plugins.smartconsole.SmartConsole): void => {
+  out.cli.command({
+    name: 'screenshot',
+    description: 'Screenshot one demo of the catalog in a headless browser: wcctools screenshot <item | section/item> --out <file.png>',
+    options: {
+      out: { type: 'string', required: true, description: 'The image file to write; .png, .jpg or .jpeg' },
+      demo: { type: 'number', description: 'The demo to render, counted from 0 as in the shell URL (default 0)' },
+      viewport: { type: 'string', description: `The width: ${Object.entries(captureViewportWidths).map(([nameArg, widthArg]) => `${nameArg} (${widthArg})`).join(', ')} or pixels (default desktop)` },
+      height: { type: 'number', description: 'The height of the preview window in pixels (default 800)' },
+      theme: { type: 'string', description: 'dark or bright (default dark)' },
+      framing: { type: 'string', description: 'element, viewport or fullpage (default element; fullpage for pages)' },
+      scale: { type: 'number', description: 'Device pixel ratio, 1 or 2 (default 1)' },
+      quality: { type: 'number', description: 'JPEG quality from 1 to 100 (default 80)' },
+    },
+  }, async ({ args, options }) => {
+    const format = formatForFile(options.out);
+    const request: plugins.interfaces.IWccScreenshotRequest = {
+      subject: parseSubject(args, options.demo),
+      viewport: parseViewport(options.viewport),
+      height: options.height,
+      theme: options.theme as plugins.interfaces.TWccTheme | undefined,
+      framing: options.framing as plugins.interfaces.TWccCaptureFraming | undefined,
+      scale: options.scale as 1 | 2 | undefined,
+      format,
+      quality: options.quality,
+    };
+    // Invalid options are refused before anything is bundled
+    resolveScreenshotRequest(request);
+    const outFile = plugins.path.resolve(options.out);
+    const devServer = new WccDevServer({ port: 0, cwd: process.cwd() });
+    // As for `wcctools dev`: SIGINT and SIGTERM stop the server and the capture browser once
+    plugins.smartexit.ProcessLifecycle.install({ shutdownTimeoutMs: devServer.getShutdownTimeoutMs() });
+    let result: plugins.interfaces.IWccScreenshotResult;
+    try {
+      await devServer.start();
+      result = await devServer.capture.captureScreenshot(request);
+    } finally {
+      await devServer.stop();
+    }
+    await plugins.fs.writeFile(outFile, Buffer.from(result.image.dataBase64, 'base64'));
+    const { selection, image } = result;
+    await out.log(
+      `wcctools screenshot: wrote ${outFile} (${selection.sectionName}/${selection.itemName} demo ${selection.demoIndex}, ${result.framing}, ${image.width}×${image.height}${result.truncated ? ', cut at the maximum height' : ''})`,
+    );
+  });
+};

package/ts/cli.ts

@@ -1,6 +1,9 @@
 import * as plugins from './plugins.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { WccDevServer } from './classes.devserver.js';
+import { WccHostPolicyError } from './classes.hostpolicy.js';
+import { WccCaptureRequestError } from './capture/index.js';
+import { registerScreenshotCommand } from './cli.screenshot.js';
 import { StandardConfigError, StandardUsageError, registerStandardCommands } from './standards/index.js';
 
 /**
@@ -21,16 +24,34 @@ export const registerCommands = (out: plugins.smartconsole.SmartConsole): void =
         type: 'number',
         description: 'Port to listen on (0 picks a free port); overrides the tswatch configuration',
       },
+      host: {
+        type: 'string',
+        description: 'Interface address to listen on (default 127.0.0.1, this machine only; 0.0.0.0 for every interface)',
+      },
+      allowedHost: {
+        type: 'strings',
+        description: 'A further hostname or address the server answers, besides localhost and the listen address (repeatable)',
+      },
     },
   }, async ({ options }) => {
-    const devServer = new WccDevServer({ port: options.port, cwd: process.cwd() });
+    const devServer = new WccDevServer({
+      port: options.port,
+      cwd: process.cwd(),
+      host: options.host,
+      allowedHosts: options.allowedHost,
+    });
     // The entry point owns process signals: SIGINT and SIGTERM run every registered cleanup, the
     // dev server's stop among them, once within tswatch's shutdown deadline, then exit.
     plugins.smartexit.ProcessLifecycle.install({ shutdownTimeoutMs: devServer.getShutdownTimeoutMs() });
     const address = await devServer.start();
     await out.log(`wcctools dev: ${address.url}`);
+    if (address.host !== '127.0.0.1' && address.host !== '::1' && address.host !== 'localhost') {
+      await out.log(`wcctools dev: listening on ${address.host}, answering the hosts ${address.allowedHosts.join(', ')}`);
+    }
   });
 
+  registerScreenshotCommand(out);
+
   registerStandardCommands(out);
 
   out.cli.default({}, async () => {
@@ -48,7 +69,9 @@ export const runCli = async () => {
     // Configuration and usage errors exit with 2, every other failure with 1.
     const usageError = error instanceof plugins.smartconsole.CliUsageError
       || error instanceof StandardConfigError
-      || error instanceof StandardUsageError;
+      || error instanceof StandardUsageError
+      || error instanceof WccCaptureRequestError
+      || error instanceof WccHostPolicyError;
     process.exitCode = usageError ? 2 : 1;
   } finally {
     await out.dispose();

package/ts/plugins.ts

@@ -2,10 +2,11 @@
 import * as childProcess from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as fsSync from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import * as url from 'node:url';
 
-export { childProcess, fs, fsSync, path, url };
+export { childProcess, fs, fsSync, os, path, url };
 
 // @api.global scope
 import * as typedrequest from '@api.global/typedrequest';
@@ -13,17 +14,23 @@ import * as typedserver from '@api.global/typedserver';
 
 export { typedrequest, typedserver };
 
+// @design.estate scope
+import * as deesDomtools from '@design.estate/dees-domtools';
+
+export { deesDomtools };
+
 // @git.zone scope
 import * as tswatch from '@git.zone/tswatch';
 
 export { tswatch };
 
 // @push.rocks scope
+import * as smartbrowser from '@push.rocks/smartbrowser/automation';
 import * as smartconfig from '@push.rocks/smartconfig';
 import * as smartconsole from '@push.rocks/smartconsole';
 import * as smartexit from '@push.rocks/smartexit';
 
-export { smartconfig, smartconsole, smartexit };
+export { smartbrowser, smartconfig, smartconsole, smartexit };
 
 // third party scope
 import typescript from 'typescript';

package/ts_interfaces/capture.ts

@@ -0,0 +1,144 @@
+import type { IWccSelection, TWccTheme } from './bridge.js';
+
+/**
+ * Captures of the catalog's demos: screenshots and interaction frames the `wcctools dev` server
+ * takes in a headless browser, and frames the shell samples from a recording.
+ */
+
+/** The named capture widths: the dees-domtools breakpoints. */
+export type TWccCaptureViewportPreset = 'phone' | 'phablet' | 'tablet' | 'desktop';
+
+/** A named capture width, or a width in CSS pixels. */
+export type TWccCaptureViewport = TWccCaptureViewportPreset | number;
+
+/**
+ * What a capture shows:
+ * - `element`: the rendered instance of the selected element (the first one its demo renders),
+ * - `viewport`: the visible preview at the capture's width and height,
+ * - `fullpage`: the whole preview document.
+ */
+export type TWccCaptureFraming = 'element' | 'viewport' | 'fullpage';
+
+export type TWccImageMimeType = 'image/png' | 'image/jpeg';
+
+/** An encoded image. */
+export interface IWccImage {
+  mimeType: TWccImageMimeType;
+  /** Width in device pixels. */
+  width: number;
+  /** Height in device pixels. */
+  height: number;
+  dataBase64: string;
+}
+
+/** A frame of a recording or of an observed interaction. */
+export interface IWccTimedFrame extends IWccImage {
+  /** Milliseconds since the start of the recording or observation. */
+  timestampMs: number;
+}
+
+/**
+ * The catalog entry a capture renders. `itemName` is an entry's name or its element's tag;
+ * without `sectionName` it must name exactly one entry across all sections.
+ */
+export interface IWccCaptureSubject {
+  sectionName?: string;
+  itemName: string;
+  /** 0-based demo index; default 0. */
+  demoIndex?: number;
+}
+
+/** How the headless preview is set up for a capture. */
+export interface IWccCaptureView {
+  /** Default `desktop`. */
+  viewport?: TWccCaptureViewport;
+  /** Height of the preview window in CSS pixels; default 800. */
+  height?: number;
+  /** Default `dark`. */
+  theme?: TWccTheme;
+  /** Device pixel ratio, 1 or 2; default 1. */
+  scale?: 1 | 2;
+}
+
+export interface IWccScreenshotRequest extends IWccCaptureView {
+  subject: IWccCaptureSubject;
+  /** Default `element` for element demos and `fullpage` for pages. */
+  framing?: TWccCaptureFraming;
+  /** Default `png`. */
+  format?: 'png' | 'jpeg';
+  /** JPEG quality from 1 to 100; default 80. */
+  quality?: number;
+}
+
+export interface IWccScreenshotResult {
+  /** The demo the subject resolved to. */
+  selection: IWccSelection;
+  framing: TWccCaptureFraming;
+  image: IWccImage;
+  /** True when a full-page capture was cut at the maximum height. */
+  truncated: boolean;
+}
+
+/**
+ * One step of a scripted interaction. A selector is a CSS selector matched in the preview
+ * document and in every open shadow root below it; the first match in document order is used,
+ * once it is visible and enabled.
+ */
+export type TWccInteractionStep =
+  | { action: 'click'; selector: string }
+  | { action: 'hover'; selector: string }
+  /** Replaces the value of an input, textarea, select or contenteditable element. */
+  | { action: 'fill'; selector: string; text: string }
+  /** Presses a key (`Enter`, `Tab`, `a`, …), on the matched element when a selector is given. */
+  | { action: 'press'; key: string; selector?: string }
+  /** Waits until a match is visible, or until none is (`hidden`). */
+  | { action: 'waitFor'; selector: string; state?: 'visible' | 'hidden' }
+  /** Observes for a fixed time, for example an animation. */
+  | { action: 'wait'; ms: number };
+
+export interface IWccInteractionRequest extends IWccCaptureView {
+  subject: IWccCaptureSubject;
+  steps: TWccInteractionStep[];
+  /** How long to keep observing after the last step, in milliseconds; default 500. */
+  observeMs?: number;
+  /** The most frames to return, spread over the observation; default 12. */
+  maxFrames?: number;
+  /** JPEG quality of the frames from 1 to 100; default 70. */
+  frameQuality?: number;
+  /** Also take a screenshot once the steps ran, framed as a screenshot request would be. */
+  finalScreenshot?: { framing?: TWccCaptureFraming; format?: 'png' | 'jpeg'; quality?: number };
+}
+
+export interface IWccInteractionStepResult {
+  index: number;
+  ok: boolean;
+  /** Why the step failed; the steps after a failed one do not run. */
+  error?: string;
+  /** Milliseconds since the start of the observation. */
+  startMs: number;
+  endMs: number;
+}
+
+export interface IWccInteractionResult {
+  selection: IWccSelection;
+  /** Viewport frames in time order, timestamped from the start of the observation. */
+  frames: IWccTimedFrame[];
+  steps: IWccInteractionStepResult[];
+  /** True when every step ran. */
+  completed: boolean;
+  finalImage?: IWccImage;
+}
+
+/** How frames are sampled from a recording. */
+export interface IWccFrameSamplingOptions {
+  /** Number of frames, spread evenly over the range; default 8, at most 32. */
+  count?: number;
+  /** Start of the range in seconds; default the start of the recording. */
+  startS?: number;
+  /** End of the range in seconds; default the end of the recording. */
+  endS?: number;
+  /** Frames wider than this are scaled down; default 960. */
+  maxWidth?: number;
+  /** JPEG quality from 0 to 1; default 0.8. */
+  quality?: number;
+}

package/ts_interfaces/index.ts

@@ -1,4 +1,5 @@
 export * from './catalog.js';
 export * from './bridge.js';
+export * from './capture.js';
 export * from './requests.js';
 export * from './standard.js';

package/ts_interfaces/requests.ts

@@ -1,4 +1,10 @@
 import * as plugins from './plugins.js';
+import type {
+  IWccInteractionRequest,
+  IWccInteractionResult,
+  IWccScreenshotRequest,
+  IWccScreenshotResult,
+} from './capture.js';
 
 /**
  * Typed requests the shell sends to the `wcctools dev` server on `/wcctools/typedrequest`.
@@ -63,3 +69,36 @@ export interface IReq_GetBundleStatus
   };
   response: IWccBundleStatusSnapshot;
 }
+
+/**
+ * Screenshots one demo in the dev server's headless browser. A capture waits while a catalog
+ * bundle builds, and is refused with a typed error when a bundle failed, when the subject does not
+ * resolve to a rendered demo, when the browser is busy with other captures, when the demo
+ * navigates away from the preview, or on its deadline of 30 seconds.
+ */
+export interface IReq_CaptureScreenshot
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_CaptureScreenshot
+  > {
+  method: 'captureScreenshot';
+  request: IWccScreenshotRequest;
+  response: IWccScreenshotResult;
+}
+
+/**
+ * Renders one demo in the dev server's headless browser, runs the scripted steps on it and
+ * returns the frames it observed meanwhile. A failed step ends the script and is reported in the
+ * result, as is a step that started a navigation away from the preview, which the browser blocked;
+ * refusals are those of `captureScreenshot`. Its deadline is 135 seconds, and `TypedRequest.fire()`
+ * gives up after 60 by default: fire it with a `timeoutMs` above the deadline.
+ */
+export interface IReq_CaptureInteraction
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_CaptureInteraction
+  > {
+  method: 'captureInteraction';
+  request: IWccInteractionRequest;
+  response: IWccInteractionResult;
+}

package/ts_shell/elements/wcc-recording-panel.ts

@@ -803,6 +803,18 @@ export class WccRecordingPanel extends DeesElement {
     this.recorderService.stopRecording();
   }
 
+  /**
+   * The finished recording shown for preview, with its trim range in seconds, or null while there
+   * is none. `sampleVideoFrames` (services/framesampler.service.ts) samples frames from it.
+   */
+  public getRecording(): { blob: Blob; trimStartS: number; trimEndS: number } | null {
+    const blob = this.recorderService.recordedBlob;
+    if (!blob || this.panelState !== 'preview') {
+      return null;
+    }
+    return { blob, trimStartS: this.trimStart, trimEndS: this.trimEnd };
+  }
+
   private handleRecordingComplete(blob: Blob): void {
     if (this.previewVideoUrl) {
       URL.revokeObjectURL(this.previewVideoUrl);

package/ts_shell/services/framesampler.service.ts

@@ -0,0 +1,112 @@
+import type * as plugins from '../plugins.js';
+
+type IWccTimedFrame = plugins.interfaces.IWccTimedFrame;
+type IWccFrameSamplingOptions = plugins.interfaces.IWccFrameSamplingOptions;
+
+/** The limits of a frame sampling. */
+export const frameSamplingLimits = {
+  defaultCount: 8,
+  maxCount: 32,
+  defaultMaxWidth: 960,
+  minMaxWidth: 64,
+  maxMaxWidth: 3840,
+  defaultQuality: 0.8,
+} as const;
+
+/** Thrown when a recording cannot be sampled as asked. */
+export class FrameSamplingError extends Error {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'FrameSamplingError';
+  }
+}
+
+const encodeBase64 = async (blobArg: Blob): Promise<string> => {
+  const bytes = new Uint8Array(await blobArg.arrayBuffer());
+  let binary = '';
+  // In chunks: String.fromCharCode takes a bounded number of arguments
+  for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+  }
+  return btoa(binary);
+};
+
+const encodeJpeg = (canvasArg: HTMLCanvasElement | OffscreenCanvas, qualityArg: number): Promise<Blob> => {
+  if (canvasArg instanceof OffscreenCanvas) {
+    return canvasArg.convertToBlob({ type: 'image/jpeg', quality: qualityArg });
+  }
+  return new Promise<Blob>((resolve, reject) => {
+    canvasArg.toBlob((blobArg) => {
+      if (blobArg) {
+        resolve(blobArg);
+      } else {
+        reject(new FrameSamplingError('wcctools: a recording frame could not be encoded as JPEG.'));
+      }
+    }, 'image/jpeg', qualityArg);
+  });
+};
+
+/**
+ * Samples timestamped JPEG frames from a recording (a WebM or MP4 blob, as the recorder produces):
+ * `count` frames at the middles of as many equal parts of the range, each the frame on screen at
+ * that time, scaled down to `maxWidth`. Frames that repeat one already sampled are left out.
+ */
+export const sampleVideoFrames = async (
+  recordingArg: Blob,
+  optionsArg: IWccFrameSamplingOptions = {},
+): Promise<IWccTimedFrame[]> => {
+  const count = optionsArg.count ?? frameSamplingLimits.defaultCount;
+  if (!Number.isInteger(count) || count < 1 || count > frameSamplingLimits.maxCount) {
+    throw new FrameSamplingError(`wcctools: the frame count must be a whole number from 1 to ${frameSamplingLimits.maxCount}.`);
+  }
+  const maxWidth = optionsArg.maxWidth ?? frameSamplingLimits.defaultMaxWidth;
+  if (!Number.isInteger(maxWidth) || maxWidth < frameSamplingLimits.minMaxWidth || maxWidth > frameSamplingLimits.maxMaxWidth) {
+    throw new FrameSamplingError(`wcctools: maxWidth must be a whole number from ${frameSamplingLimits.minMaxWidth} to ${frameSamplingLimits.maxMaxWidth}.`);
+  }
+  const quality = optionsArg.quality ?? frameSamplingLimits.defaultQuality;
+  if (!(quality > 0 && quality <= 1)) {
+    throw new FrameSamplingError('wcctools: the quality must be above 0 and at most 1.');
+  }
+
+  const { Input, BlobSource, CanvasSink, ALL_FORMATS } = await import('mediabunny');
+  const input = new Input({ source: new BlobSource(recordingArg), formats: ALL_FORMATS });
+  try {
+    const track = await input.getPrimaryVideoTrack();
+    if (!track) {
+      throw new FrameSamplingError('wcctools: the recording has no video track.');
+    }
+    if (!(await track.canDecode())) {
+      throw new FrameSamplingError(`wcctools: this browser cannot decode the recording's ${track.codec ?? 'unknown'} video.`);
+    }
+    const firstTimestamp = await track.getFirstTimestamp();
+    const duration = await track.computeDuration();
+    const startS = Math.max(optionsArg.startS ?? firstTimestamp, firstTimestamp);
+    const endS = Math.min(optionsArg.endS ?? duration, duration);
+    if (!(endS > startS)) {
+      throw new FrameSamplingError(`wcctools: the range ${startS}–${endS} s holds no frames of the ${duration} s recording.`);
+    }
+
+    const sink = new CanvasSink(track, track.displayWidth > maxWidth ? { width: maxWidth } : {});
+    const step = (endS - startS) / count;
+    const timestamps = Array.from({ length: count }, (_, indexArg) => startS + step * (indexArg + 0.5));
+    const frames: IWccTimedFrame[] = [];
+    let previousTimestamp: number | null = null;
+    for await (const wrapped of sink.canvasesAtTimestamps(timestamps)) {
+      if (!wrapped || wrapped.timestamp === previousTimestamp) {
+        continue;
+      }
+      previousTimestamp = wrapped.timestamp;
+      const jpeg = await encodeJpeg(wrapped.canvas, quality);
+      frames.push({
+        mimeType: 'image/jpeg',
+        width: wrapped.canvas.width,
+        height: wrapped.canvas.height,
+        dataBase64: await encodeBase64(jpeg),
+        timestampMs: Math.round(wrapped.timestamp * 1000),
+      });
+    }
+    return frames;
+  } finally {
+    input.dispose();
+  }
+};

package/ts_web/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.'
 }