@design.estate/wcctools 6.2.0 → 7.0.0

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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJldmlld3BhZ2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9jYXB0dXJlL3ByZXZpZXdwYWdlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDO0FBQ3pDLE9BQU8sRUFBRSxlQUFlLEVBQUUsc0JBQXNCLEVBQUUsZUFBZSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ3ZGLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDekMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDMUQsT0FBTyxFQUFFLGFBQWEsRUFBRSxnQkFBZ0IsRUFBd0QsTUFBTSxjQUFjLENBQUM7QUFLckgsMEVBQTBFO0FBQzFFLE1BQU0scUJBQXFCLEdBQUcsTUFBTSxDQUFDO0FBWXJDLE1BQU0sZ0JBQWdCLEdBQUcsQ0FBQyxTQUFtQixFQUFVLEVBQUU7SUFDdkQsT0FBTyxTQUFTLENBQUMsTUFBTSxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsMEJBQTBCLFNBQVMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7QUFDbkcsQ0FBQyxDQUFDO0FBRUY7Ozs7OztHQU1HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLEtBQUssRUFDaEMsVUFBMkIsRUFDM0IsU0FBaUIsRUFDakIsT0FBeUIsRUFDekIsVUFBaUQsRUFDbkIsRUFBRTtJQUNoQyxNQUFNLElBQUksR0FBRyxNQUFNLFVBQVUsQ0FBQyxPQUFPLEVBQUUsQ0FBQztJQUN4QyxNQUFNLFVBQVUsR0FBYSxFQUFFLENBQUM7SUFDaEMsSUFBSSxDQUFDLEVBQUUsQ0FBQyxXQUFXLEVBQUUsQ0FBQyxRQUFRLEVBQUUsRUFBRTtRQUNoQyxVQUFVLENBQUMsSUFBSSxDQUFDLGVBQWUsQ0FBQyxRQUFRLENBQUMsQ0FBQyxDQUFDO0lBQzdDLENBQUMsQ0FBQyxDQUFDO0lBQ0gsSUFBSSxDQUFDLEVBQUUsQ0FBQyxTQUFTLEVBQUUsQ0FBQyxVQUFVLEVBQUUsRUFBRTtRQUNoQyxJQUFJLFVBQVUsQ0FBQyxJQUFJLEVBQUUsS0FBSyxPQUFPLEVBQUUsQ0FBQztZQUNsQyxVQUFVLENBQUMsSUFBSSxDQUFDLFVBQVUsQ0FBQyxJQUFJLEVBQUUsQ0FBQyxDQUFDO1FBQ3JDLENBQUM7SUFDSCxDQUFDLENBQUMsQ0FBQztJQUNILE1BQU0sSUFBSSxDQUFDLFdBQVcsQ0FBQyxFQUFFLEtBQUssRUFBRSxPQUFPLENBQUMsS0FBSyxFQUFFLE1BQU0sRUFBRSxPQUFPLENBQUMsTUFBTSxFQUFFLGlCQUFpQixFQUFFLE9BQU8sQ0FBQyxLQUFLLEVBQUUsQ0FBQyxDQUFDO0lBQzNHLE1BQU0sSUFBSSxDQUFDLG9CQUFvQixDQUFDO1FBQzlCLEVBQUUsSUFBSSxFQUFFLHNCQUFzQixFQUFFLEtBQUssRUFBRSxPQUFPLENBQUMsS0FBSyxLQUFLLFFBQVEsQ0FBQyxDQUFDLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxNQUFNLEVBQUU7S0FDdkYsQ0FBQyxDQUFDO0lBRUgsTUFBTSxVQUFVLEdBQUcsR0FBRyxTQUFTLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxnQkFBZ0IsR0FBRyxPQUFPLENBQUMsTUFBTSxDQUFDLGtCQUFrQixDQUFDLEVBQUUsU0FBUyxFQUFFLElBQUksRUFBRSxLQUFLLEVBQUUsT0FBTyxDQUFDLEtBQUssRUFBRSxDQUFDLEVBQUUsQ0FBQztJQUNuSixNQUFNLGVBQWUsR0FBRyxNQUFNLGtCQUFrQixDQUFDLE9BQU8sQ0FBQyxJQUFJLEVBQUUsVUFBVSxDQUFDLENBQUM7SUFDM0UsTUFBTSxRQUFRLEdBQUcsTUFBTSxJQUFJLENBQUMsSUFBSSxDQUFDLFVBQVUsRUFBRSxFQUFFLFNBQVMsRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFLHFCQUFxQixFQUFFLENBQUMsQ0FBQztJQUNwRyxJQUFJLENBQUMsUUFBUSxFQUFFLEVBQUUsRUFBRSxFQUFFLENBQUM7UUFDcEIsTUFBTSxJQUFJLGVBQWUsQ0FBQywyQ0FBMkMsUUFBUSxFQUFFLE1BQU0sRUFBRSxJQUFJLFNBQVMsSUFBSSxnQkFBZ0IsQ0FBQyxVQUFVLENBQUMsRUFBRSxDQUFDLENBQUM7SUFDMUksQ0FBQztJQUNELE1BQU0sZUFBZSxDQUFDLG9CQUFvQixFQUFFLENBQUM7SUFDN0MsSUFBSSxDQUFDO1FBQ0gsTUFBTSxJQUFJLENBQUMsZUFBZSxDQUFDLEdBQUcsRUFBRSxDQUFDLE1BQU0sQ0FBQyxVQUFVLEtBQUssU0FBUyxFQUFFLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRSxPQUFPLEVBQUUscUJBQXFCLEVBQUUsQ0FBQyxDQUFDO0lBQ3hILENBQUM7SUFBQyxPQUFPLEtBQUssRUFBRSxDQUFDO1FBQ2YsTUFBTSxJQUFJLGVBQWUsQ0FDdkIsOENBQThDLHFCQUFxQixHQUFHLElBQUksT0FBTyxlQUFlLENBQUMsS0FBSyxDQUFDLEtBQUssZ0JBQWdCLENBQUMsVUFBVSxDQUFDLEVBQUUsQ0FDM0ksQ0FBQztJQUNKLENBQUM7SUFFRCxNQUFNLFFBQVEsR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxFQUFFLENBQUMsTUFBTSxDQUFDLFVBQVcsQ0FBQyxXQUFXLEVBQUUsQ0FBQyxDQUFDO0lBQzdFLE1BQU0sU0FBUyxHQUFHLGdCQUFnQixDQUFDLFFBQVEsRUFBRSxVQUFVLENBQUMsQ0FBQztJQUN6RCxNQUFNLE9BQU8sR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQyxZQUFZLEVBQUUsRUFBRSxDQUFDLE1BQU0sQ0FBQyxVQUFXLENBQUMsTUFBTSxDQUFDLFlBQVksQ0FBQyxFQUFFLFNBQVMsQ0FBQyxDQUFDO0lBQzFHLElBQUksT0FBTyxDQUFDLElBQUksS0FBSyxPQUFPLEVBQUUsQ0FBQztRQUM3QixNQUFNLElBQUksZUFBZSxDQUN2QixhQUFhLFNBQVMsQ0FBQyxXQUFXLElBQUksU0FBUyxDQUFDLFFBQVEsU0FBUyxTQUFTLENBQUMsU0FBUyxvQkFBb0IsT0FBTyxDQUFDLFVBQVUsQ0FBQyxLQUFLLEtBQUssT0FBTyxDQUFDLFVBQVUsQ0FBQyxNQUFNLEdBQUcsZ0JBQWdCLENBQUMsVUFBVSxDQUFDLEVBQUUsQ0FDaE0sQ0FBQztJQUNKLENBQUM7SUFDRCxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsS0FBSyxJQUFJLEVBQUU7UUFDN0IsTUFBTSxRQUFRLENBQUMsS0FBSyxDQUFDLEtBQUssQ0FBQztJQUM3QixDQUFDLENBQUMsQ0FBQztJQUNILE1BQU0sZUFBZSxDQUFDLFlBQVksQ0FBQyxXQUFXLENBQUMsQ0FBQztJQUNoRCxPQUFPLEVBQUUsSUFBSSxFQUFFLGVBQWUsRUFBRSxTQUFTLEVBQUUsSUFBSSxFQUFFLE9BQU8sQ0FBQyxJQUFJLEVBQUUsQ0FBQztBQUNsRSxDQUFDLENBQUM7QUFFRixnREFBZ0Q7QUFDaEQsTUFBTSxDQUFDLE1BQU0saUJBQWlCLEdBQUcsS0FBSyxFQUNwQyxVQUErQixFQUMvQixPQUF5QixFQUN6QixVQUFvQyxFQUNrRixFQUFFO0lBQ3hILE1BQU0sRUFBRSxJQUFJLEVBQUUsR0FBRyxVQUFVLENBQUM7SUFDNUIsTUFBTSxPQUFPLEdBQUcsVUFBVSxDQUFDLE9BQU8sSUFBSSxDQUFDLFVBQVUsQ0FBQyxJQUFJLEtBQUssTUFBTSxDQUFDLENBQUMsQ0FBQyxVQUFVLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDO0lBQzVGLE1BQU0sUUFBUSxHQUFHLEVBQUUsSUFBSSxFQUFFLFVBQVUsQ0FBQyxNQUFNLEVBQUUsR0FBRyxDQUFDLFVBQVUsQ0FBQyxPQUFPLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsT0FBTyxFQUFFLFVBQVUsQ0FBQyxPQUFPLEVBQUUsQ0FBQyxFQUFXLENBQUM7SUFFcEksSUFBSSxPQUFPLEtBQUssU0FBUyxFQUFFLENBQUM7UUFDMUIsSUFBSSxVQUFVLENBQUMsSUFBSSxLQUFLLE1BQU0sRUFBRSxDQUFDO1lBQy9CLE1BQU0sSUFBSSxzQkFBc0IsQ0FBQyxpRkFBaUYsQ0FBQyxDQUFDO1FBQ3RILENBQUM7UUFDRCxNQUFNLE1BQU0sR0FBRyxNQUFNLElBQUksQ0FBQyxjQUFjLENBQUMsR0FBRyxFQUFFLENBQUMsTUFBTSxDQUFDLFVBQVcsQ0FBQyxvQkFBb0IsRUFBRSxDQUFDLENBQUM7UUFDMUYsSUFBSSxDQUFDO1lBQ0gsTUFBTSxPQUFPLEdBQUcsTUFBTSxDQUFDLFNBQVMsRUFBRSxDQUFDO1lBQ25DLElBQUksQ0FBQyxPQUFPLEVBQUUsQ0FBQztnQkFDYixNQUFNLElBQUksZUFBZSxDQUN2Qix5QkFBeUIsVUFBVSxDQUFDLFNBQVMsQ0FBQyxRQUFRLGdFQUFnRSxDQUN2SCxDQUFDO1lBQ0osQ0FBQztZQUNELE1BQU0sS0FBSyxHQUFHLE1BQU0sT0FBTyxDQUFDLFVBQVUsQ0FBQyxRQUFRLENBQUMsQ0FBQztZQUNqRCxPQUFPLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRSxVQUFVLENBQUMsS0FBSyxFQUFFLFVBQVUsQ0FBQyxNQUFNLENBQUMsRUFBRSxTQUFTLEVBQUUsS0FBSyxFQUFFLENBQUM7UUFDcEYsQ0FBQztnQkFBUyxDQUFDO1lBQ1QsTUFBTSxNQUFNLENBQUMsT0FBTyxFQUFFLENBQUM7UUFDekIsQ0FBQztJQUNILENBQUM7SUFFRCxJQUFJLE9BQU8sS0FBSyxVQUFVLEVBQUUsQ0FBQztRQUMzQixNQUFNLEtBQUssR0FBRyxNQUFNLElBQUksQ0FBQyxVQUFVLENBQUMsUUFBUSxDQUFDLENBQUM7UUFDOUMsT0FBTyxFQUFFLE9BQU8sRUFBRSxLQUFLLEVBQUUsVUFBVSxDQUFDLEtBQUssRUFBRSxVQUFVLENBQUMsTUFBTSxDQUFDLEVBQUUsU0FBUyxFQUFFLEtBQUssRUFBRSxDQUFDO0lBQ3BGLENBQUM7SUFFRCxNQUFNLGNBQWMsR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxFQUFFLENBQUMsUUFBUSxDQUFDLGVBQWUsQ0FBQyxZQUFZLENBQUMsQ0FBQztJQUN4RixJQUFJLGNBQWMsR0FBRyxhQUFhLENBQUMsaUJBQWlCLEVBQUUsQ0FBQztRQUNyRCxNQUFNLEtBQUssR0FBRyxNQUFNLElBQUksQ0FBQyxVQUFVLENBQUM7WUFDbEMsR0FBRyxRQUFRO1lBQ1gsSUFBSSxFQUFFLEVBQUUsQ0FBQyxFQUFFLENBQUMsRUFBRSxDQUFDLEVBQUUsQ0FBQyxFQUFFLEtBQUssRUFBRSxPQUFPLENBQUMsS0FBSyxFQUFFLE1BQU0sRUFBRSxhQUFhLENBQUMsaUJBQWlCLEVBQUU7WUFDbkYscUJBQXFCLEVBQUUsSUFBSTtTQUM1QixDQUFDLENBQUM7UUFDSCxPQUFPLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRSxVQUFVLENBQUMsS0FBSyxFQUFFLFVBQVUsQ0FBQyxNQUFNLENBQUMsRUFBRSxTQUFTLEVBQUUsSUFBSSxFQUFFLENBQUM7SUFDbkYsQ0FBQztJQUNELE1BQU0sS0FBSyxHQUFHLE1BQU0sSUFBSSxDQUFDLFVBQVUsQ0FBQyxFQUFFLEdBQUcsUUFBUSxFQUFFLFFBQVEsRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDO0lBQ3JFLE9BQU8sRUFBRSxPQUFPLEVBQUUsS0FBSyxFQUFFLFVBQVUsQ0FBQyxLQUFLLEVBQUUsVUFBVSxDQUFDLE1BQU0sQ0FBQyxFQUFFLFNBQVMsRUFBRSxLQUFLLEVBQUUsQ0FBQztBQUNwRixDQUFDLENBQUMifQ==

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.devserver.d.ts

@@ -1,4 +1,6 @@
 import { WccDevApi } from './classes.devapi.js';
+import { WccHostPolicy } from './classes.hostpolicy.js';
+import { WccCaptureService } from './capture/index.js';
 export interface IWccDevServerOptions {
     /** Port to listen on; overrides the tswatch configuration. 0 picks a free port. */
     port?: number;
@@ -7,11 +9,22 @@ export interface IWccDevServerOptions {
      * tswatch bundles and watches in it (default: `process.cwd()` when the server is constructed).
      */
     cwd?: string;
+    /**
+     * The interface address to listen on (default `127.0.0.1`, this machine only). `0.0.0.0` or
+     * `::` listen on every interface; the machine's interface addresses are then allowed hosts.
+     */
+    host?: string;
+    /** Further hostnames or addresses the server answers, besides localhost and the listen address. */
+    allowedHosts?: readonly string[];
 }
 export interface IWccDevServerAddress {
     port: number;
     /** The shell's address. */
     url: string;
+    /** The interface address the server listens on. */
+    host: string;
+    /** The hostnames the server answers; requests for any other Host are refused. */
+    allowedHosts: string[];
 }
 /**
  * `wcctools dev`: bundles the catalog of a project with tswatch, as its `@git.zone/tswatch`
@@ -20,7 +33,12 @@ export interface IWccDevServerAddress {
  * - the shell on `/wcctools/` (`/` redirects there) and its routes `/wcctools-route/...`,
  * - the typed API on `/wcctools/typedrequest`, including the bundles' status,
  * - the catalog's preview document and bundle from the tswatch serve directory on every other
- *   path, with live reload that reloads only the preview document.
+ *   path, with live reload that reloads only the preview document,
+ * - captures of single demos in a headless browser (`capture`, also on the typed API).
+ *
+ * It listens on loopback unless told otherwise and admits requests as its `WccHostPolicy`
+ * describes: only the hosts it serves, and state-changing requests and WebSockets only from its
+ * own origin.
  *
  * The server owns no process lifecycle: while it runs, a process shutdown through smartexit's
  * `ProcessLifecycle` stops it. The entry point installs that lifecycle with
@@ -30,6 +48,10 @@ export declare class WccDevServer {
     private readonly options;
     /** The typed API on `/wcctools/typedrequest`; register further handlers before `start()`. */
     readonly api: WccDevApi;
+    /** Screenshots and interaction captures of the served catalog; available while the server runs. */
+    readonly capture: WccCaptureService;
+    /** Who may talk to the server: the hosts it answers and the origin of its requests. */
+    readonly hostPolicy: WccHostPolicy;
     /** The project directory everything resolves against. */
     readonly cwd: string;
     /** The project's tswatch configuration, or the `element` preset; read once, on construction. */
@@ -64,14 +86,8 @@ export declare class WccDevServer {
     private startServing;
     private getElementPreset;
     /**
-     * The shell: the prebuilt shell bundle and the typed API.
-     *
-     * Seam for side-effecting APIs (assistant, capture, standards fixes): before any handler with
-     * side effects is registered here, the server binds to localhost by default (another interface
-     * only on explicit request), validates the Host header against the addresses it serves instead
-     * of accepting any hostname, and admits typedsocket connections and typed requests only from the
-     * shell's own origin (a `websocketAdmission`/`requestAdmission`), keeping surface mode's strict
-     * authority validation. Until then every handler here is read-only.
+     * The shell: the prebuilt shell bundle and the typed API, whose requests (captures among them)
+     * are admitted only from the server's own origin.
      */
     private createShellSurface;
     /**