@design.estate/wcctools 6.1.0 → 7.0.0

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

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';