@design.estate/wcctools 6.1.0 → 7.0.0

package/dist_ts/capture/classes.captureservice.js

@@ -0,0 +1,119 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureBrowser, captureBrowserClosedMessage } 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 {
+    bundleStatus;
+    browser;
+    origin = null;
+    constructor(bundleStatus, browserOptionsArg = {}) {
+        this.bundleStatus = bundleStatus;
+        this.browser = new WccCaptureBrowser(browserOptionsArg);
+    }
+    /** Registers the capture requests on a typed router. */
+    addTypedHandlers(typedrouterArg) {
+        typedrouterArg.addTypedHandler(new plugins.typedrequest.TypedHandler('captureScreenshot', async (requestArg, typedToolsArg) => {
+            return this.captureScreenshot(requestArg, typedToolsArg?.abortSignal);
+        }));
+        typedrouterArg.addTypedHandler(new plugins.typedrequest.TypedHandler('captureInteraction', async (requestArg, typedToolsArg) => {
+            return this.captureInteraction(requestArg, typedToolsArg?.abortSignal);
+        }));
+    }
+    /** How often the capture browser was launched. */
+    getBrowserLaunchCount() {
+        return this.browser.getLaunchCount();
+    }
+    /** The process id of the capture browser while it runs. */
+    getBrowserProcessId() {
+        return this.browser.getProcessId();
+    }
+    /** Takes captures of the dev server serving at `originArg` (scheme, host and port). */
+    open(originArg) {
+        this.origin = originArg;
+        this.browser.open();
+    }
+    /** Ends every capture and closes the browser. */
+    async close() {
+        this.origin = null;
+        await this.browser.close();
+    }
+    async captureScreenshot(requestArg, abortSignalArg) {
+        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 };
+        });
+    }
+    async captureInteraction(requestArg, abortSignalArg) {
+        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 = { 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.
+     */
+    async run(deadlineMsArg, clientSignalArg, captureArg) {
+        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. */
+    async waitForSettledBundles(abortSignalArg) {
+        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);
+        }
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5jYXB0dXJlc2VydmljZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3RzL2NhcHR1cmUvY2xhc3Nlcy5jYXB0dXJlc2VydmljZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsMkJBQTJCLEVBQWtDLE1BQU0sNkJBQTZCLENBQUM7QUFDN0gsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDbEQsT0FBTyxFQUFFLGFBQWEsRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ3BFLE9BQU8sRUFBRSxhQUFhLEVBQUUseUJBQXlCLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFbEcsd0VBQXdFO0FBQ3hFLE1BQU0sQ0FBQyxNQUFNLG9CQUFvQixHQUFHLE1BQU0sQ0FBQztBQUUzQyxrR0FBa0c7QUFDbEcsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQUcsTUFBTTtNQUN2QyxhQUFhLENBQUMsUUFBUSxHQUFHLGFBQWEsQ0FBQyxhQUFhO01BQ3BELGFBQWEsQ0FBQyxZQUFZLENBQUM7QUFFL0I7Ozs7OztHQU1HO0FBQ0gsTUFBTSxPQUFPLGlCQUFpQjtJQUtUO0lBSkYsT0FBTyxDQUFvQjtJQUNwQyxNQUFNLEdBQWtCLElBQUksQ0FBQztJQUVyQyxZQUNtQixZQUFrQyxFQUNuRCxvQkFBK0MsRUFBRTtRQURoQyxpQkFBWSxHQUFaLFlBQVksQ0FBc0I7UUFHbkQsSUFBSSxDQUFDLE9BQU8sR0FBRyxJQUFJLGlCQUFpQixDQUFDLGlCQUFpQixDQUFDLENBQUM7SUFDMUQsQ0FBQztJQUVELHdEQUF3RDtJQUNqRCxnQkFBZ0IsQ0FBQyxjQUFnRDtRQUN0RSxjQUFjLENBQUMsZUFBZSxDQUM1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

package/dist_ts/capture/classes.screencast.d.ts

@@ -0,0 +1,47 @@
+import * as plugins from '../plugins.js';
+type TPage = plugins.smartbrowser.puppeteer.Page;
+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 declare class WccScreencastRecorder {
+    private readonly page;
+    private readonly options;
+    private session;
+    private startedAt;
+    private readonly kept;
+    /** The newest frame that arrived too soon after the last kept one. */
+    private latest;
+    private stopped;
+    private ackFailure;
+    private readonly minFrameGapMs;
+    private readonly maxKeptFrames;
+    constructor(page: TPage, options: IWccScreencastOptions);
+    /** The time the recording started, as `Date.now()` read it. */
+    getStartedAt(): number;
+    start(): Promise<void>;
+    /** Stops the screencast, detaches from the page and answers the kept frames in time order. */
+    stop(): Promise<plugins.interfaces.IWccTimedFrame[]>;
+    private readonly onFrame;
+}
+/**
+ * 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 declare const selectFrames: <T extends {
+    timestampMs: number;
+}>(framesArg: T[], maxFramesArg: number) => T[];
+export {};

package/dist_ts/capture/classes.screencast.js

@@ -0,0 +1,127 @@
+import * as plugins from '../plugins.js';
+import { toWccImage } from './images.js';
+/**
+ * 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 {
+    page;
+    options;
+    session = null;
+    startedAt = 0;
+    kept = [];
+    /** The newest frame that arrived too soon after the last kept one. */
+    latest = null;
+    stopped = false;
+    ackFailure = null;
+    minFrameGapMs;
+    maxKeptFrames;
+    constructor(page, options) {
+        this.page = page;
+        this.options = options;
+        this.minFrameGapMs = 1000 / (options.maxFps ?? 10);
+        this.maxKeptFrames = options.maxKeptFrames ?? 200;
+    }
+    /** The time the recording started, as `Date.now()` read it. */
+    getStartedAt() {
+        return this.startedAt;
+    }
+    async start() {
+        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. */
+    async stop() {
+        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,
+        }));
+    }
+    onFrame = (eventArg) => {
+        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) => {
+            if (!this.stopped) {
+                this.ackFailure ??= error;
+            }
+        });
+        const paintedAt = eventArg.metadata.timestamp === undefined ? Date.now() : eventArg.metadata.timestamp * 1000;
+        const frame = {
+            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 = (framesArg, maxFramesArg) => {
+    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();
+    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]);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zY3JlZW5jYXN0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvY2FwdHVyZS9jbGFzc2VzLnNjcmVlbmNhc3QudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUM7QUFDekMsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQXVCekM7Ozs7R0FJRztBQUNILE1BQU0sT0FBTyxxQkFBcUI7SUFZYjtJQUNBO0lBWlgsT0FBTyxHQUF1QixJQUFJLENBQUM7SUFDbkMsU0FBUyxHQUFHLENBQUMsQ0FBQztJQUNMLElBQUksR0FBdUIsRUFBRSxDQUFDO0lBQy9DLHNFQUFzRTtJQUM5RCxNQUFNLEdBQTRCLElBQUksQ0FBQztJQUN2QyxPQUFPLEdBQUcsS0FBSyxDQUFDO0lBQ2hCLFVBQVUsR0FBWSxJQUFJLENBQUM7SUFDbEIsYUFBYSxDQUFTO0lBQ3RCLGFBQWEsQ0FBUztJQUV2QyxZQUNtQixJQUFXLEVBQ1gsT0FBOEI7UUFEOUIsU0FBSSxHQUFKLElBQUksQ0FBTztRQUNYLFlBQU8sR0FBUCxPQUFPLENBQXVCO1FBRS9DLElBQUksQ0FBQyxhQUFhLEdBQUcsSUFBSSxHQUFHLENBQUMsT0FBTyxDQUFDLE1BQU0sSUFBSSxFQUFFLENBQUMsQ0FBQztRQUNuRCxJQUFJLENBQUMsYUFBYSxHQUFHLE9BQU8sQ0FBQyxhQUFhLElBQUksR0FBRyxDQUFDO0lBQ3BELENBQUM7SUFFRCwrREFBK0Q7SUFDeEQsWUFBWTtRQUNqQixPQUFPLElBQUksQ0FBQyxTQUFTLENBQUM7SUFDeEIsQ0FBQztJQUVNLEtBQUssQ0FBQyxLQUFLO1FBQ2hCLE1BQU0sT0FBTyxHQUFHLE1BQU0sSUFBSSxDQUFDLElBQUksQ0FBQyxnQkFBZ0IsRUFBRSxDQUFDO1FBQ25ELElBQUksQ0FBQyxPQUFPLEdBQUcsT0FBTyxDQUFDO1FBQ3ZCLE9BQU8sQ0FBQyxFQUFFLENBQUMsc0JB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

package/dist_ts/capture/errors.d.ts

@@ -0,0 +1,14 @@
+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 declare class WccCaptureError extends plugins.typedrequest.TypedResponseError {
+    constructor(messageArg: string);
+}
+/** A capture request that is invalid as given; the CLI exits with 2. */
+export declare class WccCaptureRequestError extends WccCaptureError {
+    constructor(messageArg: string);
+}
+/** The message of any thrown value. */
+export declare const getErrorMessage: (errorArg: unknown) => string;

package/dist_ts/capture/errors.js

@@ -0,0 +1,23 @@
+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) {
+        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) {
+        super(messageArg);
+        this.name = 'WccCaptureRequestError';
+    }
+}
+/** The message of any thrown value. */
+export const getErrorMessage = (errorArg) => {
+    return errorArg instanceof Error ? errorArg.message : String(errorArg);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvY2FwdHVyZS9lcnJvcnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUM7QUFFekM7OztHQUdHO0FBQ0gsTUFBTSxPQUFPLGVBQWdCLFNBQVEsT0FBTyxDQUFDLFlBQVksQ0FBQyxrQkFBa0I7SUFDMUUsWUFBWSxVQUFrQjtRQUM1QixLQUFLLENBQUMsVUFBVSxDQUFDLENBQUM7UUFDbEIsSUFBSSxDQUFDLElBQUksR0FBRyxpQkFBaUIsQ0FBQztJQUNoQyxDQUFDO0NBQ0Y7QUFFRCx3RUFBd0U7QUFDeEUsTUFBTSxPQUFPLHNCQUF1QixTQUFRLGVBQWU7SUFDekQsWUFBWSxVQUFrQjtRQUM1QixLQUFLLENBQUMsVUFBVSxDQUFDLENBQUM7UUFDbEIsSUFBSSxDQUFDLElBQUksR0FBRyx3QkFBd0IsQ0FBQztJQUN2QyxDQUFDO0NBQ0Y7QUFFRCx1Q0FBdUM7QUFDdkMsTUFBTSxDQUFDLE1BQU0sZUFBZSxHQUFHLENBQUMsUUFBaUIsRUFBVSxFQUFFO0lBQzNELE9BQU8sUUFBUSxZQUFZLEtBQUssQ0FBQyxDQUFDLENBQUMsUUFBUSxDQUFDLE9BQU8sQ0FBQyxDQUFDLENBQUMsTUFBTSxDQUFDLFFBQVEsQ0FBQyxDQUFDO0FBQ3pFLENBQUMsQ0FBQyJ9

package/dist_ts/capture/images.d.ts

@@ -0,0 +1,3 @@
+import * as plugins from '../plugins.js';
+/** An encoded image with its pixel size read from its own header. */
+export declare const toWccImage: (bytesArg: Uint8Array, formatArg: "png" | "jpeg") => plugins.interfaces.IWccImage;

package/dist_ts/capture/images.js

@@ -0,0 +1,58 @@
+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) => {
+    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) => {
+    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, formatArg) => {
+    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'),
+    };
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW1hZ2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvY2FwdHVyZS9pbWFnZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUM7QUFDekMsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUU5QyxNQUFNLFlBQVksR0FBRyxDQUFDLElBQUksRUFBRSxJQUFJLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxJQUFJLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxJQUFJLENBQUMsQ0FBQztBQUV0RSxvREFBb0Q7QUFDcEQsTUFBTSxXQUFXLEdBQUcsQ0FBQyxRQUFvQixFQUE0QyxFQUFFO0lBQ3JGLElBQUksUUFBUSxDQUFDLE1BQU0sR0FBRyxFQUFFLElBQUksWUFBWSxDQUFDLElBQUksQ0FBQyxDQUFDLE9BQU8sRUFBRSxRQUFRLEVBQUUsRUFBRSxDQUFDLFFBQVEsQ0FBQyxRQUFRLENBQUMsS0FBSyxPQUFPLENBQUMsRUFBRSxDQUFDO1FBQ3JHLE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQztJQUNELE1BQU0sSUFBSSxHQUFHLElBQUksUUFBUSxDQUFDLFFBQVEsQ0FBQyxNQUFNLEVBQUUsUUFBUSxDQUFDLFVBQVUsRUFBRSxRQUFRLENBQUMsVUFBVSxDQUFDLENBQUM7SUFDckYsT0FBTyxFQUFFLEtBQUssRUFBRSxJQUFJLENBQUMsU0FBUyxDQUFDLEVBQUUsQ0FBQyxFQUFFLE1BQU0sRUFBRSxJQUFJLENBQUMsU0FBUyxDQUFDLEVBQUUsQ0FBQyxFQUFFLENBQUM7QUFDbkUsQ0FBQyxDQUFDO0FBRUYsdUVBQXVFO0FBQ3ZFLE1BQU0sWUFBWSxHQUFHLENBQUMsUUFBb0IsRUFBNEMsRUFBRTtJQUN0RixJQUFJLFFBQVEsQ0FBQyxNQUFNLEdBQUcsQ0FBQyxJQUFJLFFBQVEsQ0FBQyxDQUFDLENBQUMsS0FBSyxJQUFJLElBQUksUUFBUSxDQUFDLENB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

package/dist_ts/capture/index.d.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/dist_ts/capture/index.js

@@ -0,0 +1,5 @@
+export * from './classes.captureservice.js';
+export * from './classes.capturebrowser.js';
+export * from './errors.js';
+export { captureLimits, captureViewportWidths, resolveScreenshotRequest, resolveInteractionRequest } from './request.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9jYXB0dXJlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLGFBQWEsQ0FBQztBQUM1QixPQUFPLEVBQUUsYUFBYSxFQUFFLHFCQUFxQixFQUFFLHdCQUF3QixFQUFFLHlCQUF5QixFQUFFLE1BQU0sY0FBYyxDQUFDIn0=

package/dist_ts/capture/interaction.d.ts

@@ -0,0 +1,11 @@
+import * as plugins from '../plugins.js';
+import type { IWccRenderedPreview } from './previewpage.js';
+import { type IWccResolvedInteractionRequest } from './request.js';
+/**
+ * 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 declare const runInteraction: (previewArg: IWccRenderedPreview, requestArg: IWccResolvedInteractionRequest, abortSignalArg: AbortSignal) => Promise<Omit<plugins.interfaces.IWccInteractionResult, "selection" | "finalImage">>;

package/dist_ts/capture/interaction.js

@@ -0,0 +1,138 @@
+import * as plugins from '../plugins.js';
+import { getErrorMessage } from './errors.js';
+import { WccScreencastRecorder, selectFrames } from './classes.screencast.js';
+import { formatBlockedNavigation } from './navigationguard.js';
+import { captureLimits } from './request.js';
+/** A selector matched in the document and in every open shadow root below it. */
+const piercing = (selectorArg) => `pierce/${selectorArg}`;
+/** Resolves after `msArg`, or rejects with the signal's reason once it aborts; never leaves its timer behind. */
+const observe = (msArg, abortSignalArg) => {
+    return new Promise((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) => {
+    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, stepArg, abortSignalArg) => {
+    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);
+            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, requestArg, abortSignalArg) => {
+    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 = [];
+    let frames;
+    await recorder.start();
+    try {
+        const startedAt = recorder.getStartedAt();
+        for (const [index, step] of requestArg.steps.entries()) {
+            const startMs = Date.now() - startedAt;
+            let error = 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 };
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJhY3Rpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9jYXB0dXJlL2ludGVyYWN0aW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDO0FBQ3pDLE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxFQUFFLHFCQUFxQixFQUFFLFlBQVksRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzlFLE9BQU8sRUFBRSx1QkFBdUIsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBRS9ELE9BQU8sRUFBRSxhQUFhLEVBQXVDLE1BQU0sY0FBYyxDQUFDO0FBS2xGLGlGQUFpRjtBQUNqRixNQUFNLFFBQVEsR0FBRyxDQUFDLFdBQW1CLEVBQUUsRUFBRSxDQUFDLFVBQVUsV0FBVyxFQUFFLENBQUM7QUFFbEUsaUhBQWlIO0FBQ2pILE1BQU0sT0FBTyxHQUFHLENBQUMsS0FBYSxFQUFFLGNBQTJCLEVBQWlCLEVBQUU7SUFDNUUsT0FBTyxJQUFJLE9BQU8sQ0FBTyxDQUFDLE9BQU8sRUFBRSxNQUFNLEVBQUUsRUFBRTtRQUMzQyxJQUFJLGNBQWMsQ0FBQyxPQUFPLEVBQUUsQ0FBQztZQUMzQixNQUFNLENBQUMsY0FBYyxDQUFDLE1BQU0sQ0FBQyxDQUFDO1lBQzlCLE9BQU87UUFDVCxDQUFDO1FBQ0QsTUFBTSxPQUFPLEdBQUcsR0FBRyxFQUFFO1lBQ25CLFlBQVksQ0FBQyxLQUFLLENBQUMsQ0FBQztZQUNwQixNQUFNLENBQUMsY0FBYyxDQUFDLE1BQU0sQ0FBQyxDQUFDO1FBQ2hDLENBQUMsQ0FBQztRQUNGLE1BQU0sS0FBSyxHQUFHLFVBQVUsQ0FBQyxHQUFHLEVBQUU7WUFDNUIsY0FBYyxDQUFDLG1CQUFtQixDQUFDLE9BQU8sRUFBRSxPQUFPLENBQUMsQ0FBQztZQUNyRCxPQUFPLEVBQUUsQ0FBQztRQUNaLENBQUMsRUFBRSxLQUFLLENBQUMs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

package/dist_ts/capture/navigationguard.d.ts

@@ -0,0 +1,44 @@
+import * as plugins from '../plugins.js';
+type TPage = plugins.smartbrowser.puppeteer.Page;
+/** The message of a navigation the capture blocked. */
+export declare const formatBlockedNavigation: (urlArg: string) => string;
+/**
+ * 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 declare class WccNavigationGuard {
+    private readonly page;
+    /** Navigation requests aborted by the backstop since the last `takeBlockedNavigation()`. */
+    private abortedUrls;
+    private interceptionFailure;
+    private previewUrl;
+    private constructor();
+    /**
+     * 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.
+     */
+    static install(pageArg: TPage, previewUrlArg: string): Promise<WccNavigationGuard>;
+    /** Drops the history entries before the loaded preview (the blank page it opened as), so going back leaves nothing. */
+    forgetEarlierHistory(): Promise<void>;
+    /**
+     * 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.
+     */
+    takeBlockedNavigation(): Promise<string | null>;
+    /** Throws when the page tried to leave the preview while `whileArg` (e.g. "rendering"). */
+    assertStayed(whileArg: string): Promise<void>;
+    private decide;
+    /**
+     * 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;
+}
+export {};