@forgebook/testing 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ensiria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @forgebook/testing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tests from a package's [Forgebook](https://www.npmjs.com/package/forgebook) stories, so writing a story is writing its
+tests:
+
+- **in the browser** (Playwright), one test per story and variant (theme, contrast, style sheets, a narrow width): it
+  fails on an error in the page, an [axe](https://github.com/dequelabs/axe-core) violation of WCAG 2.2 A and AA, an
+  element that spills out of its parent, or an overlay left open past the story's frame;
+- **visual**, the same frames compared with reference screenshots, in the Playwright container so fonts and rendering
+  match everywhere;
+- **on the server** (Vitest), each story rendered to a string, so no component reads `window` or `document` while it
+  renders, and its controls checked against its args.
+
+**Requirements:** `forgebook` · Vite 8 · `@playwright/test` 1.64+ · Vitest 5 ·
+[MIT licence](https://github.com/Ensiria/forgebook/blob/develop/packages/testing/LICENSE)
+
+```sh
+npm install --save-dev @forgebook/testing @playwright/test vitest
+```
+
+| Import or command | What it is |
+|---|---|
+| `@forgebook/testing/browser` | The browser and visual tests of every story |
+| `@forgebook/testing/server` | The server-render tests of every story |
+| `@forgebook/testing/playwright`, `@forgebook/testing/vite` | The Playwright configurations and the Vite config of the test frame page |
+| `forgebook-heights` | Measures every story's height at a few widths, for the catalogue's loading boxes |
+| `forgebook-shot` | Opens one story of a running catalogue and reports it with a picture |
+
+Each module's TSDoc describes its setup; a step-by-step guide is still to be written. More:
+[Forgebook's README](https://github.com/Ensiria/forgebook/blob/develop/packages/forgebook/README.md).

package/dist/bin/forgebook-heights/forgebook-heights.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=forgebook-heights.d.mts.map

package/dist/bin/forgebook-heights/forgebook-heights.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgebook-heights.d.mts","sourceRoot":"","sources":["../../../bin/forgebook-heights/forgebook-heights.mts"],"names":[],"mappings":""}

package/dist/bin/forgebook-heights/forgebook-heights.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * The `forgebook-heights` command: opens every story of a catalogue in a browser and measures how tall its frame is
+ * at a few widths, for the shell to give a story's box that height while it loads.
+ *
+ * @remarks
+ * Usage: `forgebook-heights --help` (generated by `@ensiria/cli-kit`). It measures a running catalogue, or serves a
+ * built one with `--serve`, which loads far faster; the file it writes is generated, never committed.
+ *
+ * @module
+ */
+import { resolve } from "node:path";
+import { writeJson } from "@ensiria/cli-kit/files";
+import { plural } from "@ensiria/cli-kit/format";
+import { progress } from "@ensiria/cli-kit/progress";
+import { defineScript, ScriptError, usageError } from "@ensiria/cli-kit/script";
+import { HEIGHT_WIDTHS } from "forgebook/story-heights";
+import { heightsDocument, measureStories, openCatalogue, parseWidths } from "./measureHeights.js";
+/** The command, as the hints print it. */
+const COMMAND = "forgebook-heights";
+await defineScript({
+    name: "forgebook-heights",
+    command: COMMAND,
+    summary: "Measure every story's height at a few widths, for the catalogue's loading boxes.",
+    icon: "check",
+    json: true,
+    description: "Opens every story's frame (the address the catalogue's stage opens) in Chromium, waits until it is ready, and reads its height at each width, the way the frame reports it to the shell. Writes the heights as JSON for the catalogue's `heights` setting, which gives a story's box that height while it loads. The stories are measured in the default view; a story that fails or never answers is left out and reported.",
+    options: {
+        catalogue: {
+            type: "string",
+            default: "http://localhost:5310/",
+            valueName: "url",
+            env: "CATALOGUE_URL",
+            description: "The running catalogue's address, when --serve is not given."
+        },
+        serve: {
+            type: "string",
+            valueName: "dir",
+            description: "A built catalogue to serve for the run (its build folder): much faster than a dev server."
+        },
+        out: {
+            type: "string",
+            required: true,
+            valueName: "file",
+            description: "Where to write the heights (a .json)."
+        },
+        widths: {
+            type: "string",
+            default: HEIGHT_WIDTHS.join(","),
+            valueName: "px,px",
+            description: "The widths to measure at, separated by commas."
+        },
+        concurrency: {
+            type: "string",
+            default: "6",
+            valueName: "count",
+            description: "How many stories load at once."
+        },
+        timeout: {
+            type: "string",
+            default: "30000",
+            valueName: "ms",
+            description: "How long to wait for one story."
+        }
+    },
+    examples: [
+        {
+            command: `${COMMAND} --serve dist --out dist/story-heights.json`,
+            description: "Measure a built catalogue and write the heights beside it."
+        },
+        {
+            command: `${COMMAND} --out public/story-heights.json`,
+            description: "Measure the running development catalogue."
+        }
+    ],
+    run: async (context) => {
+        const { options, log } = context;
+        const widths = parseWidths(options.widths);
+        if (typeof widths === "string")
+            throw usageError(widths);
+        const concurrency = Number(options.concurrency);
+        const timeout = Number(options.timeout);
+        if (!Number.isInteger(concurrency) || concurrency < 1)
+            throw usageError("--concurrency needs a whole number");
+        if (!Number.isInteger(timeout) || timeout < 1)
+            throw usageError("--timeout needs a whole number of ms");
+        const out = resolve(options.out);
+        const catalogue = await openCatalogue(options.catalogue, options.serve === undefined ? undefined : resolve(options.serve));
+        try {
+            let bar;
+            const result = await measureStories({
+                address: catalogue.address,
+                widths,
+                concurrency,
+                timeout,
+                onStart: (stories) => {
+                    bar = progress({ label: "Measuring the stories", total: stories, unit: "stories" }, context);
+                },
+                onStory: () => bar?.tick()
+            }).catch((error) => {
+                bar?.fail();
+                throw new ScriptError(error instanceof Error ? error.message : String(error), {
+                    hint: `Is the catalogue running at ${catalogue.address}? Or build it and pass --serve`
+                });
+            });
+            bar?.done(`${plural(result.measured.size, "story", "stories")} measured`);
+            writeJson(out, heightsDocument(widths, result.measured));
+            for (const failure of result.failures)
+                log.warn(`${failure.story}: ${failure.reason}`);
+            log.success(`heights written to ${out}`);
+            return {
+                out,
+                widths,
+                stories: result.storyIds.length,
+                measured: result.measured.size,
+                failures: result.failures
+            };
+        }
+        finally {
+            await catalogue.close();
+        }
+    }
+}).run();
+//# sourceMappingURL=forgebook-heights.mjs.map

package/dist/bin/forgebook-heights/forgebook-heights.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgebook-heights.mjs","sourceRoot":"","sources":["../../../bin/forgebook-heights/forgebook-heights.mts"],"names":[],"mappings":"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"}

package/dist/bin/forgebook-heights/measureHeights.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The logic of `forgebook-heights`: the widths it is asked for, the document it writes, and the run in a browser that
+ * opens every story's frame and measures it at each width.
+ *
+ * @remarks
+ * The frame page is the one the catalogue's stage opens (D-56, D-69), and its height is read as the frame reports it to
+ * the shell (the body's own height), so a measured height is the one the stage would get. A story loads once at the
+ * first width and is then resized through the others: a reload per width would multiply the run by them. `--serve`
+ * serves a built catalogue with Vite's preview server, where a frame loads in one request per chunk instead of the
+ * development server's hundreds of modules. `parseWidths` and `heightsDocument` are pure.
+ *
+ * @module
+ */
+import { type Browser } from "@playwright/test";
+import type { StoryHeights } from "forgebook/story-heights";
+import type { HeightFailure } from "./measureHeights.types.ts";
+/**
+ * The widths a `--widths` text names: whole numbers of px within the stage's range, ascending, once each.
+ *
+ * @param text - the widths, separated by commas (`360,768,1440`).
+ * @returns the widths, or the message that says what is wrong.
+ */
+export declare const parseWidths: (text: string) => number[] | string;
+/**
+ * The document the shell reads: the stories measured, in the catalogue's order.
+ *
+ * @param widths - the widths measured at.
+ * @param measured - each measured story's heights, at `widths`.
+ */
+export declare const heightsDocument: (widths: readonly number[], measured: ReadonlyMap<string, readonly number[]>) => StoryHeights;
+/** A catalogue to measure: its address, and how to let it go when the run is over. */
+type Catalogue = {
+    /** The catalogue's address, ending with `/`. */
+    readonly address: string;
+    /** Stops what was started to serve it; nothing for a catalogue already running. */
+    readonly close: () => Promise<void>;
+};
+/**
+ * The catalogue to measure: one already running, or a built one served for the run.
+ *
+ * @param catalogue - the running catalogue's address, used when there is nothing to serve.
+ * @param serve - the folder of a built catalogue to serve; none to use the running one.
+ */
+export declare const openCatalogue: (catalogue: string, serve: string | undefined) => Promise<Catalogue>;
+/**
+ * The catalogue's story ids, as its shell writes them into the page.
+ *
+ * @param browser - the browser.
+ * @param address - the catalogue's address.
+ * @param timeout - how long to wait for the shell, in ms.
+ */
+export declare const catalogueStoryIds: (browser: Browser, address: string, timeout: number) => Promise<string[]>;
+/** What a measuring run is told. */
+export type MeasureRequest = {
+    /** The catalogue's address. */
+    readonly address: string;
+    /** The widths, ascending. */
+    readonly widths: readonly number[];
+    /** How many stories load at once. */
+    readonly concurrency: number;
+    /** How long to wait for a story, in ms. */
+    readonly timeout: number;
+    /** Told the number of stories before the first is measured. */
+    readonly onStart: (stories: number) => void;
+    /** Told after each story, measured or not. */
+    readonly onStory: (storyId: string) => void;
+};
+/** What a measuring run found. */
+export type MeasureResult = {
+    /** Every story's id, in the catalogue's order. */
+    readonly storyIds: readonly string[];
+    /** The measured stories' heights. */
+    readonly measured: ReadonlyMap<string, readonly number[]>;
+    /** The stories that could not be measured. */
+    readonly failures: readonly HeightFailure[];
+};
+/**
+ * Measures every story of a catalogue at each width.
+ *
+ * @param request - the catalogue, the widths, how many at once, and what to tell along the way.
+ */
+export declare const measureStories: (request: MeasureRequest) => Promise<MeasureResult>;
+export {};
+//# sourceMappingURL=measureHeights.d.ts.map

package/dist/bin/forgebook-heights/measureHeights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measureHeights.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-heights/measureHeights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,KAAK,OAAO,EAAuB,MAAM,kBAAkB,CAAC;AAErE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAK5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAQ/D;;;;;GAKG;AACH,eAAO,MAAM,WAAW,SAAU,MAAM,KAAG,MAAM,EAAE,GAAG,MAcrD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,WAClB,SAAS,MAAM,EAAE,YACf,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,KAC/C,YAAgF,CAAC;AAEpF,sFAAsF;AACtF,KAAK,SAAS,GAAG;IACf,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,cAAqB,MAAM,SAAS,MAAM,GAAG,SAAS,KAAG,OAAO,CAAC,SAAS,CAiBnG,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,YACnB,OAAO,WACP,MAAM,WACN,MAAM,KACd,OAAO,CAAC,MAAM,EAAE,CAWlB,CAAC;AAyDF,oCAAoC;AACpC,MAAM,MAAM,cAAc,GAAG;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7C,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,aAAa,GAAG;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAC1D,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,YAAmB,cAAc,KAAG,OAAO,CAAC,aAAa,CAmCnF,CAAC"}

package/dist/bin/forgebook-heights/measureHeights.js

@@ -0,0 +1,180 @@
+/**
+ * The logic of `forgebook-heights`: the widths it is asked for, the document it writes, and the run in a browser that
+ * opens every story's frame and measures it at each width.
+ *
+ * @remarks
+ * The frame page is the one the catalogue's stage opens (D-56, D-69), and its height is read as the frame reports it to
+ * the shell (the body's own height), so a measured height is the one the stage would get. A story loads once at the
+ * first width and is then resized through the others: a reload per width would multiply the run by them. `--serve`
+ * serves a built catalogue with Vite's preview server, where a frame loads in one request per chunk instead of the
+ * development server's hundreds of modules. `parseWidths` and `heightsDocument` are pure.
+ *
+ * @module
+ */
+import { chromium } from "@playwright/test";
+import { STATUS_ATTRIBUTE } from "forgebook/frame-status";
+import { STORY_IDS_ELEMENT } from "forgebook/story-ids-element";
+import { frameAddressOf } from "forgebook/view-state";
+import { preview } from "vite";
+/** The narrowest and widest widths a story is measured at, in CSS px: the stage's own range. */
+const WIDTH_RANGE = { min: 240, max: 2560 };
+/** The viewport's height while measuring: a story taller than it still reports its whole height. */
+const VIEWPORT_HEIGHT = 900;
+/**
+ * The widths a `--widths` text names: whole numbers of px within the stage's range, ascending, once each.
+ *
+ * @param text - the widths, separated by commas (`360,768,1440`).
+ * @returns the widths, or the message that says what is wrong.
+ */
+export const parseWidths = (text) => {
+    const parts = text
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part !== "");
+    if (parts.length === 0)
+        return "--widths needs at least one width";
+    const wrong = parts.find((part) => {
+        const width = Number(part);
+        return !Number.isInteger(width) || width < WIDTH_RANGE.min || width > WIDTH_RANGE.max;
+    });
+    if (wrong !== undefined) {
+        return `--widths takes whole numbers of px from ${WIDTH_RANGE.min} to ${WIDTH_RANGE.max}, not "${wrong}"`;
+    }
+    return [...new Set(parts.map(Number))].sort((left, right) => left - right);
+};
+/**
+ * The document the shell reads: the stories measured, in the catalogue's order.
+ *
+ * @param widths - the widths measured at.
+ * @param measured - each measured story's heights, at `widths`.
+ */
+export const heightsDocument = (widths, measured) => ({ widths: [...widths], heights: Object.fromEntries(measured) });
+/**
+ * The catalogue to measure: one already running, or a built one served for the run.
+ *
+ * @param catalogue - the running catalogue's address, used when there is nothing to serve.
+ * @param serve - the folder of a built catalogue to serve; none to use the running one.
+ */
+export const openCatalogue = async (catalogue, serve) => {
+    if (serve === undefined) {
+        return { address: catalogue.endsWith("/") ? catalogue : `${catalogue}/`, close: async () => undefined };
+    }
+    const server = await preview({
+        root: serve,
+        configFile: false,
+        logLevel: "silent",
+        build: { outDir: "." },
+        preview: { host: "127.0.0.1", port: 0, strictPort: false }
+    });
+    const [address] = server.resolvedUrls?.local ?? [];
+    if (address === undefined) {
+        await server.close();
+        throw new Error(`Vite's preview server did not say where it serves ${serve}`);
+    }
+    return { address, close: () => server.close() };
+};
+/**
+ * The catalogue's story ids, as its shell writes them into the page.
+ *
+ * @param browser - the browser.
+ * @param address - the catalogue's address.
+ * @param timeout - how long to wait for the shell, in ms.
+ */
+export const catalogueStoryIds = async (browser, address, timeout) => {
+    const page = await browser.newPage();
+    try {
+        await page.goto(address);
+        const element = page.locator(`#${STORY_IDS_ELEMENT}`);
+        await element.waitFor({ state: "attached", timeout });
+        const ids = JSON.parse((await element.textContent()) ?? "[]");
+        return Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : [];
+    }
+    finally {
+        await page.close();
+    }
+};
+/** The frame's height as it reports it to the shell: its body's own height, in whole px. */
+const frameHeight = async (page) => 
+// a text expression: the command runs on Node, where the page's own globals are not typed
+Number(await page.evaluate("Math.ceil(document.body.getBoundingClientRect().height)"));
+/** Waits until the page laid out what a resize changed: two animation frames. */
+const settled = async (page) => {
+    await page.evaluate("new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve(undefined))))");
+};
+/**
+ * One story's heights at each width, or why it could not be measured.
+ *
+ * @param page - a page to measure in.
+ * @param address - the catalogue's address.
+ * @param storyId - the story's id.
+ * @param widths - the widths, ascending.
+ * @param timeout - how long to wait for the story, in ms.
+ */
+const measureStory = async (page, address, storyId, widths, timeout) => {
+    const [first = WIDTH_RANGE.min] = widths;
+    await page.setViewportSize({ width: first, height: VIEWPORT_HEIGHT });
+    await page.goto(new URL(frameAddressOf("frame.html", storyId, ""), address).href);
+    const status = await page
+        .waitForFunction(`document.documentElement.getAttribute(${JSON.stringify(STATUS_ATTRIBUTE)})`, undefined, {
+        timeout
+    })
+        .then(async (handle) => String(await handle.jsonValue()))
+        .catch(() => "timeout");
+    if (status === "timeout")
+        return { story: storyId, reason: `no answer in ${timeout} ms` };
+    if (status !== "ready") {
+        const error = await page.locator(".forgebook-frame-error__message").first().textContent();
+        return { story: storyId, reason: error ?? "the story failed" };
+    }
+    const heights = [];
+    for (const width of widths) {
+        await page.setViewportSize({ width, height: VIEWPORT_HEIGHT });
+        await settled(page);
+        heights.push(await frameHeight(page));
+    }
+    return heights;
+};
+/**
+ * Measures every story of a catalogue at each width.
+ *
+ * @param request - the catalogue, the widths, how many at once, and what to tell along the way.
+ */
+export const measureStories = async (request) => {
+    const browser = await chromium.launch();
+    try {
+        const storyIds = await catalogueStoryIds(browser, request.address, request.timeout);
+        request.onStart(storyIds.length);
+        const measured = new Map();
+        const failures = [];
+        let next = 0;
+        // each worker takes the next story until none is left, so a slow story never holds the others
+        const worker = async () => {
+            const page = await browser.newPage();
+            try {
+                for (let index = next++; index < storyIds.length; index = next++) {
+                    const storyId = storyIds[index] ?? "";
+                    const result = await measureStory(page, request.address, storyId, request.widths, request.timeout);
+                    if ("reason" in result)
+                        failures.push(result);
+                    else
+                        measured.set(storyId, result);
+                    request.onStory(storyId);
+                }
+            }
+            finally {
+                await page.close();
+            }
+        };
+        await Promise.all(Array.from({ length: Math.max(1, request.concurrency) }, worker));
+        // the catalogue's order, not the order the workers finished in
+        const ordered = new Map(storyIds.flatMap((id) => {
+            const heights = measured.get(id);
+            return heights === undefined ? [] : [[id, heights]];
+        }));
+        return { storyIds, measured: ordered, failures };
+    }
+    finally {
+        await browser.close();
+    }
+};
+//# sourceMappingURL=measureHeights.js.map

package/dist/bin/forgebook-heights/measureHeights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measureHeights.js","sourceRoot":"","sources":["../../../bin/forgebook-heights/measureHeights.ts"],"names":[],"mappings":"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"}

package/dist/bin/forgebook-heights/measureHeights.types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `--json` document of `forgebook-heights`: how many stories were measured, which failed and why, and where the
+ * heights went.
+ *
+ * @module
+ */
+/** A story that could not be measured. */
+export type HeightFailure = {
+    /** The story's id. */
+    readonly story: string;
+    /** Why: its error, or that it did not answer in time. */
+    readonly reason: string;
+};
+/** What `forgebook-heights` reports. */
+export type HeightsReport = {
+    /** The file the heights were written to. */
+    readonly out: string;
+    /** The widths measured at, in CSS px. */
+    readonly widths: readonly number[];
+    /** How many stories the catalogue has. */
+    readonly stories: number;
+    /** How many were measured. */
+    readonly measured: number;
+    /** The ones that failed, left out of the file. */
+    readonly failures: readonly HeightFailure[];
+};
+//# sourceMappingURL=measureHeights.types.d.ts.map

package/dist/bin/forgebook-heights/measureHeights.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measureHeights.types.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-heights/measureHeights.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG;IAC1B,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wCAAwC;AACxC,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C,CAAC"}

package/dist/bin/forgebook-heights/measureHeights.types.js

@@ -0,0 +1,7 @@
+/**
+ * The `--json` document of `forgebook-heights`: how many stories were measured, which failed and why, and where the
+ * heights went.
+ *
+ * @module
+ */
+//# sourceMappingURL=measureHeights.types.js.map

package/dist/bin/forgebook-heights/measureHeights.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measureHeights.types.js","sourceRoot":"","sources":["../../../bin/forgebook-heights/measureHeights.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/bin/forgebook-shot/forgebook-shot.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=forgebook-shot.d.mts.map

package/dist/bin/forgebook-shot/forgebook-shot.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgebook-shot.d.mts","sourceRoot":"","sources":["../../../bin/forgebook-shot/forgebook-shot.mts"],"names":[],"mappings":""}

package/dist/bin/forgebook-shot/forgebook-shot.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * The `forgebook-shot` command: opens one story of a running catalogue in a browser, waits for it, and reports how it
+ * ended, its size, a picture and, when asked, the accessibility rules it breaks: what an agent needs to check a story
+ * it wrote without a person looking.
+ *
+ * @remarks
+ * Usage: `forgebook-shot --help` (generated by `@ensiria/cli-kit`). The catalogue must be running
+ * (`forgebook dev`).
+ *
+ * @module
+ */
+import { resolve } from "node:path";
+import { defineScript, ScriptError, usageError } from "@ensiria/cli-kit/script";
+import { takeShot } from "./storyShot.js";
+/** The command, as the hints print it. */
+const COMMAND = "forgebook-shot";
+await defineScript({
+    name: "forgebook-shot",
+    command: COMMAND,
+    summary: "Open one story of a running catalogue, wait for it, and report it with a picture.",
+    icon: "check",
+    json: true,
+    description: "Opens the story's frame (the address the catalogue's stage and the generated tests open) in Chromium with the given view, waits until it says ready or failed, and reports its size, the page's console errors, a full-page PNG when --out is given, and the axe violations of WCAG 2.2 A and AA with --a11y. A story that fails or never answers ends the command with an error.",
+    options: {
+        catalogue: {
+            type: "string",
+            default: "http://localhost:5310/",
+            valueName: "url",
+            env: "CATALOGUE_URL",
+            description: "The running catalogue's address."
+        },
+        story: {
+            type: "string",
+            required: true,
+            valueName: "id",
+            description: "The story's id, as the catalogue's address writes it (acme-ui:feedback-counter--plain)."
+        },
+        view: {
+            type: "string",
+            default: "",
+            valueName: "query",
+            description: "The view, as the catalogue's address writes it (theme=dark&contrast=more&lang=it)."
+        },
+        width: {
+            type: "string",
+            default: "1024",
+            valueName: "px",
+            description: "The width the story is drawn at."
+        },
+        out: { type: "string", valueName: "file", description: "Where to write the picture (a .png)." },
+        a11y: { type: "boolean", description: "Also check the story's accessibility (axe, WCAG 2.2 A and AA)." },
+        timeout: {
+            type: "string",
+            default: "30000",
+            valueName: "ms",
+            description: "How long to wait for the story."
+        }
+    },
+    examples: [
+        {
+            command: `${COMMAND} --story acme-ui:feedback-counter--plain --out counter.png`,
+            description: "A picture of a story, in the default view."
+        },
+        {
+            command: `${COMMAND} --story acme-ui:feedback-counter--plain --view theme=dark --a11y --json`,
+            description: "The dark theme, with its accessibility, as JSON."
+        }
+    ],
+    run: async ({ options, log }) => {
+        const width = Number(options.width);
+        const timeout = Number(options.timeout);
+        if (!Number.isInteger(width) || width < 1)
+            throw usageError("--width needs a whole number of px");
+        if (!Number.isInteger(timeout) || timeout < 1)
+            throw usageError("--timeout needs a whole number of ms");
+        const shot = await takeShot({
+            catalogue: options.catalogue,
+            story: options.story,
+            view: options.view,
+            width,
+            out: options.out === undefined ? undefined : resolve(options.out),
+            isA11y: options.a11y,
+            timeout
+        });
+        if (shot.status === "timeout") {
+            throw new ScriptError(`${shot.story} did not answer in ${timeout} ms`, {
+                hint: `Is the catalogue running at ${options.catalogue}? Open ${shot.address}`
+            });
+        }
+        for (const message of shot.consoleErrors)
+            log.warn(message);
+        if (shot.status === "error") {
+            throw new ScriptError(`${shot.story} failed: ${shot.error ?? "no message"}`, {
+                hint: `Open ${shot.address} to see it`
+            });
+        }
+        log.success(`${shot.story} is shown, ${shot.size.width} × ${shot.size.height} px`);
+        if (shot.screenshot !== undefined)
+            log.info(`picture: ${shot.screenshot}`);
+        if (shot.violations !== undefined) {
+            if (shot.violations.length === 0)
+                log.success("no accessibility rule broken");
+            for (const violation of shot.violations)
+                log.error(`${violation.id}: ${violation.help}`);
+        }
+        return shot;
+    }
+}).run();
+//# sourceMappingURL=forgebook-shot.mjs.map