@design.estate/wcctools 6.1.0 → 7.0.0

package/dist_ts/capture/navigationguard.js

@@ -0,0 +1,129 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureError, getErrorMessage } from './errors.js';
+/** The message of a navigation the capture blocked. */
+export const formatBlockedNavigation = (urlArg) => {
+    return `navigation to ${urlArg} blocked: a capture stays on the rendered preview`;
+};
+/**
+ * Runs in the main frame before the preview's scripts, so its `navigate` listener is the first:
+ * cancels each navigation that would replace the document (a link, a form submission, a script
+ * assigning `location`, a reload, also to the same URL, to `about:blank` or a `blob:` URL) as it
+ * starts, and records its URL. Same-document navigations (`history.replaceState`, fragments) and
+ * downloads pass. Link clicks and scripts start their navigation while the step that caused it
+ * runs; form submissions in a task right after.
+ */
+const cancelLeavingNavigations = () => {
+    if (window !== window.top) {
+        return;
+    }
+    const cancelled = [];
+    window.wccCancelledNavigations = cancelled;
+    navigation.addEventListener('navigate', (eventArg) => {
+        if (eventArg.destination.sameDocument || eventArg.downloadRequest !== null || !eventArg.cancelable) {
+            return;
+        }
+        eventArg.preventDefault();
+        cancelled.push(eventArg.destination.url);
+    });
+};
+/**
+ * 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 class WccNavigationGuard {
+    page;
+    /** Navigation requests aborted by the backstop since the last `takeBlockedNavigation()`. */
+    abortedUrls = [];
+    interceptionFailure = null;
+    previewUrl;
+    constructor(page, previewUrlArg) {
+        this.page = page;
+        this.previewUrl = new URL(previewUrlArg).href;
+    }
+    /**
+     * 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 async install(pageArg, previewUrlArg) {
+        const guard = new WccNavigationGuard(pageArg, previewUrlArg);
+        pageArg.on('request', (requestArg) => guard.decide(requestArg));
+        await pageArg.setRequestInterception(true);
+        await pageArg.evaluateOnNewDocument(cancelLeavingNavigations);
+        return guard;
+    }
+    /** Drops the history entries before the loaded preview (the blank page it opened as), so going back leaves nothing. */
+    async forgetEarlierHistory() {
+        const session = await this.page.createCDPSession();
+        try {
+            await session.send('Page.resetNavigationHistory');
+        }
+        finally {
+            await session.detach();
+        }
+    }
+    /**
+     * 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.
+     */
+    async takeBlockedNavigation() {
+        const cancelledUrl = await this.page.evaluate(() => {
+            return new Promise((resolve) => {
+                requestAnimationFrame(() => {
+                    setTimeout(() => {
+                        const cancelled = window.wccCancelledNavigations ?? [];
+                        resolve(cancelled[0] ?? null);
+                        cancelled.length = 0;
+                    }, 0);
+                });
+            });
+        });
+        if (this.interceptionFailure !== null) {
+            throw new WccCaptureError(`wcctools: the capture failed to handle a request of the preview: ${getErrorMessage(this.interceptionFailure)}`);
+        }
+        const abortedUrl = this.abortedUrls[0] ?? null;
+        this.abortedUrls = [];
+        return cancelledUrl ?? abortedUrl;
+    }
+    /** Throws when the page tried to leave the preview while `whileArg` (e.g. "rendering"). */
+    async assertStayed(whileArg) {
+        const blockedUrl = await this.takeBlockedNavigation();
+        if (blockedUrl !== null) {
+            throw new WccCaptureError(`wcctools: the demo tried to navigate away while ${whileArg}; ${formatBlockedNavigation(blockedUrl)}.`);
+        }
+    }
+    decide(requestArg) {
+        if (requestArg.isInterceptResolutionHandled()) {
+            return;
+        }
+        if (!requestArg.isNavigationRequest() || requestArg.frame() !== this.page.mainFrame()) {
+            this.settle(requestArg.continue());
+            return;
+        }
+        if (this.previewUrl !== null && requestArg.url() === this.previewUrl) {
+            // The preview document's own load, once
+            this.previewUrl = null;
+            this.settle(requestArg.continue());
+            return;
+        }
+        this.abortedUrls.push(requestArg.url());
+        // `aborted` drops the navigation without committing an error page, so the preview stays
+        this.settle(requestArg.abort('aborted'));
+    }
+    /**
+     * 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.
+     */
+    settle(decisionArg) {
+        decisionArg.catch((errorArg) => {
+            this.interceptionFailure ??= errorArg;
+        });
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmF2aWdhdGlvbmd1YXJkLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvY2FwdHVyZS9uYXZpZ2F0aW9uZ3VhcmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUM7QUFDekMsT0FBTyxFQUFFLGVBQWUsRUFBRSxlQUFlLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFLL0QsdURBQXVEO0FBQ3ZELE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLENBQUMsTUFBYyxFQUFVLEVBQUU7SUFDaEUsT0FBTyxpQkFBaUIsTUFBTSxtREFBbUQsQ0FBQztBQUNwRixDQUFDLENBQUM7QUFRRjs7Ozs7OztHQU9HO0FBQ0gsTUFBTSx3QkFBd0IsR0FBRyxHQUFHLEVBQUU7SUFDcEMsSUFBSSxNQUFNLEtBQUssTUFBTSxDQUFDLEdBQUcsRUFBRSxDQUFDO1FBQzFCLE9BQU87SUFDVCxDQUFDO0lBQ0QsTUFBTSxTQUFTLEdBQWEsRUFBRSxDQUFDO0lBQzlCLE1BQStDLENBQUMsdUJBQXVCLEdBQUcsU0FBUyxDQUFDO0lBQ3JGLFVBQVUsQ0FBQyxnQkFBZ0IsQ0FBQyxVQUFVLEVBQUUsQ0FBQyxRQUFRLEVBQUUsRUFBRTtRQUNuRCxJQUFJLFFBQVEsQ0FBQyxXQUFXLENBQUMsWUFBWSxJQUFJLFFBQVEsQ0FBQyxlQUFlLEtBQUssSUFBSSxJQUFJLENBQUMsUUFBUSxDQUFDLFVBQVUsRUFBRSxDQUFDO1lBQ25HLE9BQU87UUFDVCxDQUFDO1FBQ0QsUUFBUSxDQUFDLGNBQWMsRUFBRSxDQUFDO1FBQzFCLFNBQVMsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLFdBQVcsQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUMzQyxDQUFDLENBQUMsQ0FBQztBQUNMLENBQUMsQ0FBQztBQUVGOzs7Ozs7Ozs7R0FTRztBQUNILE1BQU0sT0FBTyxrQkFBa0I7SUFPVjtJQU5uQiw0RkFBNEY7SUFDcEYsV0FBVyxHQUFh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

package/dist_ts/capture/previewpage.d.ts

@@ -0,0 +1,29 @@
+import * as plugins from '../plugins.js';
+import { WccNavigationGuard } from './navigationguard.js';
+import { type IWccResolvedImageOptions, type IWccResolvedView } from './request.js';
+type TBrowserContext = plugins.smartbrowser.puppeteer.BrowserContext;
+type TPage = plugins.smartbrowser.puppeteer.Page;
+/** A preview document in the capture browser that rendered one demo. */
+export interface IWccRenderedPreview {
+    page: TPage;
+    /** Keeps the page on the preview and knows the navigation it blocked. */
+    navigationGuard: WccNavigationGuard;
+    selection: plugins.interfaces.IWccSelection;
+    /** What the demo rendered: an element demo or a page. */
+    type: 'element' | 'page';
+}
+/**
+ * Opens the preview route of the dev server at `originArg` in the context, waits for the preview
+ * runtime to install its bridge (it does once it rendered the route), resolves the subject against
+ * the catalog manifest and renders it. Waits only on the preview's own signals: the bridge, the
+ * render's completed updates and the document's fonts. The page stays on the preview: every
+ * later navigation of its main frame is blocked, and one blocked while rendering fails the capture.
+ */
+export declare const renderPreview: (contextArg: TBrowserContext, originArg: string, viewArg: IWccResolvedView, subjectArg: plugins.interfaces.IWccCaptureSubject) => Promise<IWccRenderedPreview>;
+/** Screenshots a rendered preview as framed. */
+export declare const screenshotPreview: (previewArg: IWccRenderedPreview, viewArg: IWccResolvedView, optionsArg: IWccResolvedImageOptions) => Promise<{
+    framing: plugins.interfaces.TWccCaptureFraming;
+    image: plugins.interfaces.IWccImage;
+    truncated: boolean;
+}>;
+export {};

package/dist_ts/capture/previewpage.js

@@ -0,0 +1,96 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureError, WccCaptureRequestError, getErrorMessage } from './errors.js';
+import { toWccImage } from './images.js';
+import { WccNavigationGuard } from './navigationguard.js';
+import { captureLimits, resolveSelection } from './request.js';
+/** How long the preview document may take to load and render its demo. */
+const previewStartTimeoutMs = 20_000;
+const formatPageErrors = (errorsArg) => {
+    return errorsArg.length > 0 ? ` The preview reported: ${errorsArg.slice(0, 5).join(' | ')}` : '';
+};
+/**
+ * Opens the preview route of the dev server at `originArg` in the context, waits for the preview
+ * runtime to install its bridge (it does once it rendered the route), resolves the subject against
+ * the catalog manifest and renders it. Waits only on the preview's own signals: the bridge, the
+ * render's completed updates and the document's fonts. The page stays on the preview: every
+ * later navigation of its main frame is blocked, and one blocked while rendering fails the capture.
+ */
+export const renderPreview = async (contextArg, originArg, viewArg, subjectArg) => {
+    const page = await contextArg.newPage();
+    const pageErrors = [];
+    page.on('pageerror', (errorArg) => {
+        pageErrors.push(getErrorMessage(errorArg));
+    });
+    page.on('console', (messageArg) => {
+        if (messageArg.type() === 'error') {
+            pageErrors.push(messageArg.text());
+        }
+    });
+    await page.setViewport({ width: viewArg.width, height: viewArg.height, deviceScaleFactor: viewArg.scale });
+    await page.emulateMediaFeatures([
+        { name: 'prefers-color-scheme', value: viewArg.theme === 'bright' ? 'light' : 'dark' },
+    ]);
+    const previewUrl = `${originArg}${plugins.shared.previewRoutePath}${plugins.shared.formatPreviewQuery({ selection: null, theme: viewArg.theme })}`;
+    const navigationGuard = await WccNavigationGuard.install(page, previewUrl);
+    const response = await page.goto(previewUrl, { waitUntil: 'load', timeout: previewStartTimeoutMs });
+    if (!response?.ok()) {
+        throw new WccCaptureError(`wcctools: the preview document answered ${response?.status() ?? 'nothing'}.${formatPageErrors(pageErrors)}`);
+    }
+    await navigationGuard.forgetEarlierHistory();
+    try {
+        await page.waitForFunction(() => window.wccPreview !== undefined, { polling: 'raf', timeout: previewStartTimeoutMs });
+    }
+    catch (error) {
+        throw new WccCaptureError(`wcctools: the preview did not start within ${previewStartTimeoutMs / 1000} s (${getErrorMessage(error)}).${formatPageErrors(pageErrors)}`);
+    }
+    const manifest = await page.evaluate(() => window.wccPreview.getManifest());
+    const selection = resolveSelection(manifest, subjectArg);
+    const outcome = await page.evaluate((selectionArg) => window.wccPreview.render(selectionArg), selection);
+    if (outcome.kind === 'empty') {
+        throw new WccCaptureError(`wcctools: ${selection.sectionName}/${selection.itemName} demo ${selection.demoIndex} did not render: ${outcome.emptyState.title}. ${outcome.emptyState.detail}${formatPageErrors(pageErrors)}`);
+    }
+    await page.evaluate(async () => {
+        await document.fonts.ready;
+    });
+    await navigationGuard.assertStayed('rendering');
+    return { page, navigationGuard, selection, type: outcome.type };
+};
+/** Screenshots a rendered preview as framed. */
+export const screenshotPreview = async (previewArg, viewArg, optionsArg) => {
+    const { page } = previewArg;
+    const framing = optionsArg.framing ?? (previewArg.type === 'page' ? 'fullpage' : 'element');
+    const encoding = { type: optionsArg.format, ...(optionsArg.quality === undefined ? {} : { quality: optionsArg.quality }) };
+    if (framing === 'element') {
+        if (previewArg.type === 'page') {
+            throw new WccCaptureRequestError('wcctools: a page has no element to frame; use the viewport or fullpage framing.');
+        }
+        const handle = await page.evaluateHandle(() => window.wccPreview.findRenderedInstance());
+        try {
+            const element = handle.asElement();
+            if (!element) {
+                throw new WccCaptureError(`wcctools: the demo of ${previewArg.selection.itemName} renders no instance of its element; use the viewport framing.`);
+            }
+            const bytes = await element.screenshot(encoding);
+            return { framing, image: toWccImage(bytes, optionsArg.format), truncated: false };
+        }
+        finally {
+            await handle.dispose();
+        }
+    }
+    if (framing === 'viewport') {
+        const bytes = await page.screenshot(encoding);
+        return { framing, image: toWccImage(bytes, optionsArg.format), truncated: false };
+    }
+    const documentHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+    if (documentHeight > captureLimits.maxFullPageHeight) {
+        const bytes = await page.screenshot({
+            ...encoding,
+            clip: { x: 0, y: 0, width: viewArg.width, height: captureLimits.maxFullPageHeight },
+            captureBeyondViewport: true,
+        });
+        return { framing, image: toWccImage(bytes, optionsArg.format), truncated: true };
+    }
+    const bytes = await page.screenshot({ ...encoding, fullPage: true });
+    return { framing, image: toWccImage(bytes, optionsArg.format), truncated: false };
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJldmlld3BhZ2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9jYXB0dXJlL3ByZXZpZXdwYWdlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDO0FBQ3pDLE9BQU8sRUFBRSxlQUFlLEVBQUUsc0JBQXNCLEVBQUUsZUFBZSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ3ZGLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDekMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDMUQsT0FBTyxFQUFFLGFBQWEsRUFBRSxnQkFBZ0IsRUFBd0QsTUFBTSxjQUFjLENBQUM7QUFLckgsMEVBQTBFO0FBQzFFLE1BQU0scUJBQXFCLEdBQUcsTUFBTSxDQUFDO0FBWXJDLE1BQU0sZ0JBQWdCLEdBQUcsQ0FBQyxTQUFtQixFQUFVLEVBQUU7SUFDdkQsT0FBTyxTQUFTLENBQUMsTUFBTSxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsMEJBQTBCLFNBQVMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7QUFDbkcsQ0FBQyxDQUFDO0FBRUY7Ozs7OztHQU1HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLEtBQUssRUFDaEMsVUFBMkIsRUFDM0IsU0FBaUIsRUFDakIsT0FBeUIsRUFDekIsVUFBaUQsRUFDbkIsRUFBRTtJQUNoQyxNQUFNLElBQUksR0FBRyxNQUFNLFVBQVUsQ0FBQyxPQUFPLEVBQUUsQ0FBQztJQUN4QyxNQUFNLFVBQVUsR0FBYSxFQUFFLENBQUM7SUFDaEMsSUFBSSxDQUFDLEVBQUUsQ0FBQyxXQUFXLEVBQUUsQ0FBQyxRQUFRLEVBQUUsRUFBRTtRQUNoQyxVQUFVLENBQUMsSUFBSSxDQUFDLGVBQWUs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

package/dist_ts/capture/request.d.ts

@@ -0,0 +1,69 @@
+import * as plugins from '../plugins.js';
+type IWccCaptureSubject = plugins.interfaces.IWccCaptureSubject;
+type TWccCaptureFraming = plugins.interfaces.TWccCaptureFraming;
+type TWccInteractionStep = plugins.interfaces.TWccInteractionStep;
+/** The limits every capture request is held to. */
+export declare const captureLimits: {
+    readonly minWidth: 200;
+    readonly maxWidth: 3840;
+    readonly minHeight: 200;
+    readonly maxHeight: 4320;
+    readonly defaultHeight: 800;
+    /** Full-page captures are cut at this height in CSS pixels. */
+    readonly maxFullPageHeight: 10000;
+    readonly defaultJpegQuality: 80;
+    readonly maxSteps: 20;
+    readonly stepTimeoutMs: 5000;
+    readonly maxWaitMs: 3000;
+    readonly defaultObserveMs: 500;
+    readonly maxObserveMs: 5000;
+    readonly defaultMaxFrames: 12;
+    readonly maxMaxFrames: 40;
+    readonly defaultFrameQuality: 70;
+    readonly maxSelectorLength: 500;
+    readonly maxTextLength: 2000;
+    readonly maxKeyLength: 32;
+    readonly maxSubjectLength: 200;
+};
+/** The capture widths of the named viewports: the dees-domtools breakpoints. */
+export declare const captureViewportWidths: Readonly<Record<plugins.interfaces.TWccCaptureViewportPreset, number>>;
+/** The preview set-up of a capture, validated and with its defaults applied. */
+export interface IWccResolvedView {
+    width: number;
+    height: number;
+    theme: plugins.interfaces.TWccTheme;
+    scale: 1 | 2;
+}
+export interface IWccResolvedImageOptions {
+    /** Undefined: the default framing of what the demo rendered. */
+    framing?: TWccCaptureFraming;
+    format: 'png' | 'jpeg';
+    /** JPEG quality; undefined for PNG. */
+    quality?: number;
+}
+export interface IWccResolvedScreenshotRequest {
+    subject: IWccCaptureSubject;
+    view: IWccResolvedView;
+    image: IWccResolvedImageOptions;
+}
+export interface IWccResolvedInteractionRequest {
+    subject: IWccCaptureSubject;
+    view: IWccResolvedView;
+    steps: TWccInteractionStep[];
+    observeMs: number;
+    maxFrames: number;
+    frameQuality: number;
+    finalScreenshot: IWccResolvedImageOptions | null;
+}
+/** Reads a viewport: a named one, or a width in CSS pixels. */
+export declare const resolveViewportWidth: (viewportArg: unknown) => number;
+/** Validates a screenshot request and applies its defaults. */
+export declare const resolveScreenshotRequest: (requestArg: plugins.interfaces.IWccScreenshotRequest) => IWccResolvedScreenshotRequest;
+/** Validates an interaction request and applies its defaults. */
+export declare const resolveInteractionRequest: (requestArg: plugins.interfaces.IWccInteractionRequest) => IWccResolvedInteractionRequest;
+/**
+ * Resolves a subject to one demo of the catalog: an entry named by its name or its element's tag,
+ * in the named section or, without one, in exactly one section.
+ */
+export declare const resolveSelection: (manifestArg: plugins.interfaces.IWccCatalogManifest, subjectArg: IWccCaptureSubject) => plugins.interfaces.IWccSelection;
+export {};

package/dist_ts/capture/request.js

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

package/dist_ts/classes.bundlestatus.d.ts

@@ -0,0 +1,36 @@
+import * as plugins from './plugins.js';
+/** The longest time a status request waits for a change before it answers the unchanged status. */
+export declare const bundleStatusWaitLimitMs = 25000;
+/** What a status request answers while the board is closed: the server is not serving. */
+export declare const bundleStatusClosedMessage = "wcctools: the dev server is not serving the bundle status.";
+/**
+ * The status of the catalog bundles, as tswatch's bundle events report it, for the shell's
+ * `getBundleStatus` requests. Every event raises the revision and answers the requests waiting for
+ * a change. While closed (the server is not serving), requests are refused with a typed error, so
+ * a client backs off as it does for any failed request.
+ */
+export declare class WccBundleStatusBoard {
+    private readonly bundles;
+    private revision;
+    private isOpen;
+    /** Settles one waiting request: answers the current snapshot, or refuses; each removes itself. */
+    private readonly waiters;
+    /** Starts a run of the server: the bundles of an earlier run are forgotten. */
+    open(): void;
+    /** Ends the run: every waiting request is refused now, later ones at once. */
+    close(): void;
+    /** The number of requests waiting for a change. */
+    getWaiterCount(): number;
+    record(eventArg: plugins.tswatch.TBundleEvent): void;
+    getSnapshot(): plugins.interfaces.IWccBundleStatusSnapshot;
+    /**
+     * The snapshot once it differs from `afterRevisionArg`, or after the wait limit; at once without
+     * a revision or for a revision that is no longer current. Refused while closed. When
+     * `abortSignalArg` aborts (the client went away), the wait ends at once and releases its timer;
+     * it answers the current snapshot, which the transport drops.
+     */
+    waitForChange(afterRevisionArg: number | undefined, abortSignalArg?: AbortSignal): Promise<plugins.interfaces.IWccBundleStatusSnapshot>;
+    private changed;
+    private answerWaiters;
+    private createClosedError;
+}