@design.estate/wcctools 6.2.0 → 7.0.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 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.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLG1KQUFtSjtDQUNqSyxDQUFBIn0=

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

@@ -0,0 +1,65 @@
+import * as plugins from '../plugins.js';
+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;
+}
+export declare 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 declare class WccCaptureBrowser {
+    private readonly maxConcurrent;
+    private readonly maxQueued;
+    private readonly idleCloseMs;
+    private readonly closeTimeoutMs;
+    private isOpen;
+    private launching;
+    private readonly closingBrowsers;
+    private readonly contexts;
+    private readonly running;
+    private readonly queue;
+    private activeCount;
+    private idleTimer;
+    private launchCount;
+    constructor(optionsArg?: IWccCaptureBrowserOptions);
+    /** How often a browser was launched; one browser serves every capture while it runs. */
+    getLaunchCount(): number;
+    /** The process id of the running browser, or null while none runs. */
+    getProcessId(): Promise<number | null>;
+    /** Takes captures from now on. */
+    open(): void;
+    /**
+     * 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.
+     */
+    close(): Promise<void>;
+    /**
+     * 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.
+     */
+    withContext<T>(abortSignalArg: AbortSignal, captureArg: (contextArg: TBrowserContext) => Promise<T>): Promise<T>;
+    private runInContext;
+    private acquireSlot;
+    private releaseSlot;
+    private clearIdleTimer;
+    /** The running browser, launched when none runs; refused once close() ran, so it never outlives it. */
+    private getBrowser;
+    private launch;
+    /** Closes the current browser, if one runs or launches; the next capture launches another. */
+    private closeBrowser;
+    /** Closes a browser, and kills its process when closing takes longer than allowed. */
+    private closeWithin;
+}
+export {};

package/dist_ts/capture/classes.capturebrowser.js

@@ -0,0 +1,251 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureError, getErrorMessage } from './errors.js';
+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 {
+    maxConcurrent;
+    maxQueued;
+    idleCloseMs;
+    closeTimeoutMs;
+    isOpen = false;
+    launching = null;
+    closingBrowsers = new Set();
+    contexts = new Set();
+    running = new Set();
+    queue = [];
+    activeCount = 0;
+    idleTimer = null;
+    launchCount = 0;
+    constructor(optionsArg = {}) {
+        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. */
+    getLaunchCount() {
+        return this.launchCount;
+    }
+    /** The process id of the running browser, or null while none runs. */
+    async getProcessId() {
+        const launching = this.launching;
+        if (!launching) {
+            return null;
+        }
+        const browser = await launching.catch(() => null);
+        return browser?.process()?.pid ?? null;
+    }
+    /** Takes captures from now on. */
+    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.
+     */
+    async close() {
+        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.
+     */
+    async withContext(abortSignalArg, captureArg) {
+        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();
+        }
+    }
+    async runInContext(abortSignalArg, captureArg) {
+        let context = 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
+                    });
+                }
+            }
+        }
+    }
+    acquireSlot(abortSignalArg) {
+        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((resolve, reject) => {
+            const queued = {
+                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);
+        });
+    }
+    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();
+        }
+    }
+    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. */
+    getBrowser() {
+        if (!this.isOpen) {
+            return Promise.reject(new WccCaptureError(captureBrowserClosedMessage));
+        }
+        this.launching ??= this.launch();
+        return this.launching;
+    }
+    async launch() {
+        this.launchCount++;
+        let browser;
+        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. */
+    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. */
+    async closeWithin(browserArg) {
+        if (!browserArg.connected) {
+            return;
+        }
+        let deadline = null;
+        const timedOut = new Promise((resolve) => {
+            deadline = setTimeout(() => resolve('timeout'), this.closeTimeoutMs);
+        });
+        const closed = browserArg.close().then(() => 'closed', () => 'failed');
+        try {
+            const result = await Promise.race([closed, timedOut]);
+            if (result !== 'closed') {
+                browserArg.process()?.kill('SIGKILL');
+            }
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5jYXB0dXJlYnJvd3Nlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3RzL2NhcHR1cmUvY2xhc3Nlcy5jYXB0dXJlYnJvd3Nlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUN6QyxPQUFPLEVBQUUsZUFBZSxFQUFFLGVBQWUsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQXFCL0QsTUFBTSxDQUFDLE1BQU0sMkJBQTJCLEdBQUcsbURBQW1ELENBQUM7QUFFL0Y7Ozs7OztHQU1HO0FBQ0gsTUFBTSxPQUFPLGlCQUFpQjtJQUNYLGFBQWEsQ0FBUztJQUN0QixTQUFTLENBQVM7SUFDbEIsV0FBVyxDQUFTO0lBQ3BCLGNBQWMsQ0FBUztJQUNoQyxNQUFNLEdBQUcsS0FBSyxDQUFDO0lBQ2YsU0FBUyxHQUE2QixJQUFJLENBQUM7SUFDbEMsZUFBZSxHQUFHLElBQUksR0FBRyxFQUFpQixDQUFDO0lBQzNDLFFBQVEsR0FBRyxJQUFJLEdBQUcsRUFBbUIsQ0FBQztJQUN0QyxPQUFPLEdBQUcsSUFBSSxHQUFHLEVBQW9CLENBQUM7SUFDdEMsS0FBSyxHQUFxQixFQUFFLENBQUM7SUFDdEMsV0FBVyxHQUFHLENBQUMsQ0FBQztJQUNoQixTQUFTLEdBQXlDLElBQUksQ0FBQztJQUN2RCxXQUFXLEdBQUcsQ0FBQyxDQUFDO0lBRXhCLFlBQVksYUFBd0MsRUFBRTtRQUNwRCxJQUFJLENBQUMsYUFBYSxHQUFHLFVBQVUsQ0FBQyxhQUFhLElBQUksQ0FBQyxDQUFDO1FBQ25ELElBQUksQ0FBQyxTQUFTLEdBQUcsVUFBVSxDQUFDLFNBQVMsSUFBSSxDQUFDLENBQUM7UUFDM0MsSUFBSSxDQUFDLFdBQVcsR0FBRyxVQUFVLENBQUMsV0FBVyxJQUFJLE1BQU0sQ0FBQztRQUNwRCxJQUFJLENBQUMsY0FBYyxHQUFHLFVBQVUsQ0FBQyxjQUFjLElBQUksS0FBSyxDQUFDO0lBQzNE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

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

@@ -0,0 +1,39 @@
+import * as plugins from '../plugins.js';
+import type { WccBundleStatusBoard } from '../classes.bundlestatus.js';
+import { type IWccCaptureBrowserOptions } from './classes.capturebrowser.js';
+/** The longest a screenshot may take, from its request to its image. */
+export declare const screenshotDeadlineMs = 30000;
+/** The longest an interaction may take: its steps, its observation and the set-up around them. */
+export declare const interactionDeadlineMs: number;
+/**
+ * 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 declare class WccCaptureService {
+    private readonly bundleStatus;
+    private readonly browser;
+    private origin;
+    constructor(bundleStatus: WccBundleStatusBoard, browserOptionsArg?: IWccCaptureBrowserOptions);
+    /** Registers the capture requests on a typed router. */
+    addTypedHandlers(typedrouterArg: plugins.typedrequest.TypedRouter): void;
+    /** How often the capture browser was launched. */
+    getBrowserLaunchCount(): number;
+    /** The process id of the capture browser while it runs. */
+    getBrowserProcessId(): Promise<number | null>;
+    /** Takes captures of the dev server serving at `originArg` (scheme, host and port). */
+    open(originArg: string): void;
+    /** Ends every capture and closes the browser. */
+    close(): Promise<void>;
+    captureScreenshot(requestArg: plugins.interfaces.IWccScreenshotRequest, abortSignalArg?: AbortSignal): Promise<plugins.interfaces.IWccScreenshotResult>;
+    captureInteraction(requestArg: plugins.interfaces.IWccInteractionRequest, abortSignalArg?: AbortSignal): Promise<plugins.interfaces.IWccInteractionResult>;
+    /**
+     * 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 run;
+    /** Resolves once no bundle builds; refused while a bundle's latest run failed. */
+    private waitForSettledBundles;
+}

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