@forgebook/testing 0.1.8 → 0.2.0

package/dist/src/conformance.js

@@ -0,0 +1,146 @@
+/**
+ * The contract every framework adapter passes, as tests: what makes an adapter one, so React is not a special case.
+ *
+ * @remarks
+ * An adapter's package calls `describeAdapter` in its own tests with a small subject of its framework: a story that shows
+ * a greeting and counts its clicks, and throws for one name. The suite then says what the frame relies on (`renderer.ts`,
+ * `adapter.ts`): a story is drawn in its canvas inside its decorators, new args keep its state, it goes away, its errors
+ * reach the frame (those of the args shown only), and it can be drawn on a server, at once or in time. It runs in the adapter's own Vitest, with a simulated page.
+ * A framework that compiles a component apart for a page and for a server (Svelte) runs it twice, each run checking its
+ * half: in a simulated page, and in Node, where its modules are compiled for the server.
+ *
+ * @module
+ */
+import { isComponentDocs } from "forgebook/component-docs";
+import { afterEach, describe, expect, it } from "vitest";
+/** The name a subject's story throws for. */
+export const THROWING_NAME = "boom";
+/**
+ * How long the docs case may take, in milliseconds: it builds a TypeScript program from nothing, which takes seconds on a
+ * runner where the other packages' tests build theirs at the same time.
+ */
+const DOCS_TIMEOUT = 60_000;
+/** The canvases of the running test, emptied after it. */
+const canvases = [];
+/** A canvas in the page, as the frame gives a story one. */
+const canvas = () => {
+    const element = document.createElement("div");
+    document.body.append(element);
+    canvases.push(element);
+    return element;
+};
+/** Waits until a condition holds, for a framework that draws on its own schedule. */
+const settled = async (holds) => {
+    await expect.poll(holds, { timeout: 2000 }).toBe(true);
+};
+/**
+ * A server render as a promise: a framework may throw at once or reject, and the frame's tests treat both as a failure.
+ *
+ * @param renderer - the framework's renderer.
+ * @param story - the drawing.
+ */
+const asyncRender = async (renderer, story) => renderer.renderToString(story);
+/**
+ * The suite of an adapter.
+ *
+ * @param subject - the adapter's subject.
+ */
+export const describeAdapter = (subject) => {
+    const { name, renderer, drawing, decorator, codeOf, docsOf, half } = subject;
+    const inPage = half !== "server";
+    const onServer = half !== "page";
+    /** The story inside a decorator of the catalogue's and one of its own. */
+    const decorated = () => {
+        const plain = drawing("Ada");
+        return {
+            ...plain,
+            story: { ...plain.story, decorators: [decorator("story")] },
+            decorators: [decorator("catalogue")]
+        };
+    };
+    describe(`the ${name} adapter`, () => {
+        afterEach(() => {
+            for (const each of canvases.splice(0))
+                each.remove();
+        });
+        it.runIf(inPage)("draws a story in its canvas, and says when it is drawn", async () => {
+            const element = canvas();
+            const story = renderer.mount(element, drawing("Ada"), () => undefined);
+            await story.drawn;
+            expect(element.textContent).toContain("Hello Ada");
+            story.unmount();
+        });
+        it.runIf(inPage)("draws new args again, keeping the story's own state", async () => {
+            const element = canvas();
+            const story = renderer.mount(element, drawing("Ada"), () => undefined);
+            await story.drawn;
+            element.querySelector("button")?.click();
+            await settled(() => element.textContent?.includes("1") === true);
+            story.update(drawing("Grace"));
+            await settled(() => element.textContent?.includes("Hello Grace 1") === true);
+            story.unmount();
+        });
+        it.runIf(inPage)("draws a story inside its decorators, the catalogue's outside the story's", async () => {
+            const element = canvas();
+            const story = renderer.mount(element, decorated(), () => undefined);
+            await story.drawn;
+            const inner = element.querySelector('[data-decorator="catalogue"] [data-decorator="story"] button');
+            expect(inner?.textContent).toContain("Hello Ada");
+            story.unmount();
+        });
+        it.runIf(onServer)("draws a story inside its decorators on a server", async () => {
+            const html = await renderer.renderToString(decorated());
+            expect(html).toMatch(/data-decorator="catalogue"[\s\S]*data-decorator="story"[\s\S]*Ada/);
+        });
+        it.runIf(inPage)("takes a story away from its canvas", async () => {
+            const element = canvas();
+            const story = renderer.mount(element, drawing("Ada"), () => undefined);
+            await story.drawn;
+            story.unmount();
+            await settled(() => element.textContent === "");
+        });
+        it.runIf(inPage)("hands the frame an error thrown while drawing, and draws again when the args change", async () => {
+            const errors = [];
+            const element = canvas();
+            const story = renderer.mount(element, drawing(THROWING_NAME), (error) => errors.push(error));
+            await settled(() => errors.length > 0);
+            let isDrawn = false;
+            void story.drawn.then(() => {
+                isDrawn = true;
+            });
+            story.update(drawing("Ada"));
+            await settled(() => element.textContent?.includes("Hello Ada") === true);
+            // the frame waits for this before it runs the play function: a story drawn at last is drawn
+            await settled(() => isDrawn);
+            story.unmount();
+        });
+        it.runIf(inPage)("says nothing of a drawing the args replaced, even one still being drawn when they changed", async () => {
+            const errors = [];
+            const element = canvas();
+            const story = renderer.mount(element, drawing(THROWING_NAME), (error) => errors.push(error));
+            await settled(() => errors.length > 0);
+            // the frame draws the story again with the same args (the events, the language), then the args change back
+            // while that drawing is under way: its error, whenever it comes, is of args no longer shown
+            story.update(drawing(THROWING_NAME));
+            await Promise.resolve();
+            const before = errors.length;
+            story.update(drawing("Grace"));
+            await settled(() => element.textContent?.includes("Hello Grace") === true);
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            expect(errors.slice(before)).toEqual([]);
+            story.unmount();
+        });
+        it.runIf(onServer)("draws a story as HTML on a server, and fails with what the story throws", async () => {
+            expect(await renderer.renderToString(drawing("Ada"))).toContain("Ada");
+            await expect(asyncRender(renderer, drawing(THROWING_NAME))).rejects.toThrow();
+        });
+        it.runIf(inPage)("writes a story's args as the framework's code", () => {
+            const code = codeOf("Greeting", { name: "Ada" });
+            expect(code).toContain("Greeting");
+            expect(code).toContain("Ada");
+        });
+        it.runIf(inPage && docsOf !== undefined)("reads a component's docs in the catalogue's shape", () => {
+            expect(isComponentDocs(docsOf?.())).toBe(true);
+        }, DOCS_TIMEOUT);
+    });
+};

package/dist/src/deviceShot.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A story's picture framed in the device its view names, as `forgebook shot` asks for it with a model in the view
+ * (`--view iphone-16`): the story pictured at the device's viewport, then drawn in the device (`forgebook/device-picture`).
+ *
+ * @module
+ */
+import type { Page } from "@playwright/test";
+import { type NamedDevice } from "forgebook/device-picture";
+/**
+ * Pictures the story a page shows in the device, framed: the page must show it at the device's story area.
+ *
+ * @param page - the page, the story opened at its area's size (`deviceViewport`).
+ * @param device - the device.
+ * @param isEdgeToEdge - whether the story draws edge to edge.
+ * @param scheme - the story's scheme.
+ * @param file - where the picture goes.
+ */
+export declare const framedShot: (page: Page, device: NamedDevice, isEdgeToEdge: boolean, scheme: "light" | "dark", file: string) => Promise<void>;

package/dist/src/deviceShot.js

@@ -0,0 +1,29 @@
+import { framedPicture } from "forgebook/device-picture";
+/**
+ * Pictures the story a page shows in the device, framed: the page must show it at the device's story area.
+ *
+ * @param page - the page, the story opened at its area's size (`deviceViewport`).
+ * @param device - the device.
+ * @param isEdgeToEdge - whether the story draws edge to edge.
+ * @param scheme - the story's scheme.
+ * @param file - where the picture goes.
+ */
+export const framedShot = async (page, device, isEdgeToEdge, scheme, file) => {
+    const picture = await page.screenshot({ animations: "disabled" });
+    // the screen around a story inside the safe areas takes its page's colour, as the shell's frame does
+    const background = await page.evaluate(() => {
+        const colour = (element) => getComputedStyle(element).backgroundColor;
+        const body = colour(document.body);
+        return body === "rgba(0, 0, 0, 0)" ? colour(document.documentElement) : body;
+    });
+    const framed = framedPicture({
+        shown: device,
+        isEdgeToEdge,
+        picture: picture.toString("base64"),
+        scheme,
+        background
+    });
+    await page.setViewportSize({ width: framed.width, height: framed.height });
+    await page.setContent(framed.html);
+    await page.screenshot({ path: file, omitBackground: true, animations: "disabled" });
+};

package/dist/src/diffStories.d.ts

@@ -0,0 +1,77 @@
+import { type Page } from "@playwright/test";
+import type { StoryDiffReport, StoryDiffRequest } from "forgebook/story-check";
+/** How far a colour channel may move and stay the same, out of 255. */
+export declare const TOLERANCE = 2;
+/** What comparing two pictures says. */
+export type PictureDifference = {
+    /** Their sizes differ, so no pixel can be compared. */
+    readonly isSizeChanged: boolean;
+    /** The pixels that changed. */
+    readonly changedPixels: number;
+    /** Their share of the picture, 0 to 100. */
+    readonly percent: number;
+    /** The smallest box that holds them; none when nothing changed. */
+    readonly region: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | undefined;
+    /** The picture with what changed marked, a PNG as a data URL; none when nothing can be marked. */
+    readonly marked: string | undefined;
+};
+/** A picture's pixels, four bytes each: red, green, blue, alpha. */
+export type Pixels = {
+    /** Its width, in pixels. */
+    readonly width: number;
+    /** Its height, in pixels. */
+    readonly height: number;
+    /** Its bytes. */
+    readonly bytes: Uint8Array;
+};
+/**
+ * Compares two pictures' pixels.
+ *
+ * @param before - the stored picture.
+ * @param after - the new one.
+ * @param tolerance - how far a channel may move.
+ * @returns what changed, and the new picture's pixels with those marked.
+ */
+export declare const comparePixels: (before: Pixels, after: Pixels, tolerance?: number) => Omit<PictureDifference, "marked"> & {
+    readonly marks: Uint8Array;
+};
+/**
+ * Compares two pictures, with the browser reading and writing the PNGs.
+ *
+ * @param page - any page.
+ * @param baseline - the stored picture, as a data URL.
+ * @param current - the new one, as a data URL.
+ */
+export declare const comparePictures: (page: Page, baseline: string, current: string) => Promise<PictureDifference>;
+/**
+ * The baselines of a component with no story left: what would otherwise pass without a word when a story is removed.
+ *
+ * @param files - the baselines folder's PNG files.
+ * @param component - the component's id.
+ * @param stories - its stories' ids.
+ * @returns the files.
+ */
+export declare const removedBaselines: (files: readonly string[], component: string, stories: readonly string[]) => readonly string[];
+/**
+ * The stored baseline a picture compares with: the one with its name, else the one named by the story's former id
+ * (`StoryCheckStory.formerId`), so the baselines stored before the ids followed Storybook's still count.
+ *
+ * @param files - the baselines folder's files.
+ * @param name - the picture's name.
+ * @param formerName - the name the picture had under the story's former id; none when the id did not change.
+ * @returns the baseline's name; the picture's own when neither is stored (a new baseline).
+ */
+export declare const storedBaseline: (files: readonly string[], name: string, formerName: string | undefined) => string;
+/**
+ * Compares the stories a request names with their baselines.
+ *
+ * @param request - the stories, the views, the baselines' folder and where the pictures go.
+ * @returns one result per story and view, and one per baseline left by a removed story.
+ * @throws when the pictures would go in the baselines' folder, and overwrite what they prove.
+ */
+export declare const diffStories: (request: StoryDiffRequest) => Promise<StoryDiffReport>;

package/dist/src/diffStories.js

@@ -0,0 +1,251 @@
+/**
+ * Stories compared with their baselines, as `forgebook diff` asks: each picture taken again and read against the one
+ * `forgebook shot --update` stored.
+ *
+ * @remarks
+ * The pixels are compared in the browser the pictures come from, on a canvas: it is already there, and decoding PNG in
+ * Node would be a dependency for one comparison. A baseline only compares with pictures of the same rendering, so one
+ * taken on another system reads as changed or resized: take them where they are compared. A pixel counts as changed when a channel moves by more than `TOLERANCE`, which holds off rounding and no more; the answer
+ * gives the region and the percentage, and the decision about what matters stays with whoever reads it.
+ *
+ * @module
+ */
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { chromium } from "@playwright/test";
+import { shotName, shotStories } from "./shotStories.js";
+/** How far a colour channel may move and stay the same, out of 255. */
+export const TOLERANCE = 2;
+/** The colour that marks a changed pixel. */
+const MARK = [255, 0, 80, 255];
+/** How many bytes go to `String.fromCharCode` at once: a whole picture overflows the call's arguments. */
+const CHUNK = 0x8000;
+/** How many rows cross to the browser at once. */
+const BAND_ROWS = 2000;
+/** A PNG's bytes as a data URL. */
+const dataUrl = (file) => `data:image/png;base64,${readFileSync(file).toString("base64")}`;
+/** Whether a pixel moved by more than the tolerance in any channel. */
+const hasMoved = (first, second, index, tolerance) => {
+    for (let channel = 0; channel < 4; channel += 1) {
+        if (Math.abs((first[index + channel] ?? 0) - (second[index + channel] ?? 0)) > tolerance)
+            return true;
+    }
+    return false;
+};
+/**
+ * Compares two pictures' pixels.
+ *
+ * @param before - the stored picture.
+ * @param after - the new one.
+ * @param tolerance - how far a channel may move.
+ * @returns what changed, and the new picture's pixels with those marked.
+ */
+export const comparePixels = (before, after, tolerance = TOLERANCE) => {
+    const { width, height } = after;
+    const marks = Uint8Array.from(after.bytes);
+    if (before.width !== width || before.height !== height) {
+        return { isSizeChanged: true, changedPixels: 0, percent: 100, region: undefined, marks };
+    }
+    let changedPixels = 0;
+    let left = width;
+    let top = height;
+    let right = -1;
+    let bottom = -1;
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const index = (y * width + x) * 4;
+            if (hasMoved(before.bytes, after.bytes, index, tolerance)) {
+                changedPixels += 1;
+                left = Math.min(left, x);
+                top = Math.min(top, y);
+                right = Math.max(right, x);
+                bottom = Math.max(bottom, y);
+                marks.set(MARK, index);
+            }
+        }
+    }
+    const region = changedPixels === 0 ? undefined : { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+    return {
+        isSizeChanged: false,
+        changedPixels,
+        percent: (changedPixels / (width * height)) * 100,
+        region,
+        marks
+    };
+};
+/** A PNG's pixels, decoded by the browser and carried over in bands: one message cannot hold a tall picture. */
+const pixelsOf = async (page, source) => {
+    const { width, height } = await page.evaluate(async (url) => {
+        const bitmap = await createImageBitmap(await (await fetch(url)).blob());
+        const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+        canvas.getContext("2d", { willReadFrequently: true })?.drawImage(bitmap, 0, 0);
+        Object.assign(globalThis, { forgebookCanvas: canvas });
+        return { width: bitmap.width, height: bitmap.height };
+    }, source);
+    const bands = [];
+    for (let top = 0; top < height; top += BAND_ROWS) {
+        const rows = Math.min(BAND_ROWS, height - top);
+        const band = await page.evaluate(({ y, size, across, chunk }) => {
+            const canvas = Reflect.get(globalThis, "forgebookCanvas");
+            if (!(canvas instanceof OffscreenCanvas))
+                throw new Error("No picture to read");
+            const pixels = canvas.getContext("2d")?.getImageData(0, y, across, size).data;
+            if (pixels === undefined)
+                throw new Error("No canvas to compare on");
+            let text = "";
+            for (let start = 0; start < pixels.length; start += chunk) {
+                text += String.fromCharCode(...pixels.subarray(start, start + chunk));
+            }
+            return btoa(text);
+        }, { y: top, size: rows, across: width, chunk: CHUNK });
+        bands.push(Buffer.from(band, "base64"));
+    }
+    return { width, height, bytes: Buffer.concat(bands) };
+};
+/** Pixels as a PNG data URL, encoded by the browser, carried over in bands as they were read. */
+const pngOf = async (page, pixels) => {
+    const { width, height, bytes } = pixels;
+    await page.evaluate(({ across, down }) => {
+        Object.assign(globalThis, { forgebookCanvas: new OffscreenCanvas(across, down) });
+    }, { across: width, down: height });
+    for (let top = 0; top < height; top += BAND_ROWS) {
+        const rows = Math.min(BAND_ROWS, height - top);
+        const band = bytes.subarray(top * width * 4, (top + rows) * width * 4);
+        await page.evaluate(({ y, across, size, data }) => {
+            const canvas = Reflect.get(globalThis, "forgebookCanvas");
+            if (!(canvas instanceof OffscreenCanvas))
+                throw new Error("No picture to write");
+            const part = Uint8ClampedArray.from(atob(data), (letter) => letter.charCodeAt(0));
+            canvas.getContext("2d")?.putImageData(new ImageData(part, across, size), 0, y);
+        }, { y: top, across: width, size: rows, data: Buffer.from(band).toString("base64") });
+    }
+    return page.evaluate(async (chunk) => {
+        const canvas = Reflect.get(globalThis, "forgebookCanvas");
+        if (!(canvas instanceof OffscreenCanvas))
+            throw new Error("No picture to write");
+        const png = new Uint8Array(await (await canvas.convertToBlob({ type: "image/png" })).arrayBuffer());
+        let text = "";
+        for (let start = 0; start < png.length; start += chunk) {
+            text += String.fromCharCode(...png.subarray(start, start + chunk));
+        }
+        return `data:image/png;base64,${btoa(text)}`;
+    }, CHUNK);
+};
+/**
+ * Compares two pictures, with the browser reading and writing the PNGs.
+ *
+ * @param page - any page.
+ * @param baseline - the stored picture, as a data URL.
+ * @param current - the new one, as a data URL.
+ */
+export const comparePictures = async (page, baseline, current) => {
+    const after = await pixelsOf(page, current);
+    const { marks, ...difference } = comparePixels(await pixelsOf(page, baseline), after);
+    const marked = difference.changedPixels === 0 ? undefined : await pngOf(page, { ...after, bytes: marks });
+    return { ...difference, marked };
+};
+/**
+ * The baselines of a component with no story left: what would otherwise pass without a word when a story is removed.
+ *
+ * @param files - the baselines folder's PNG files.
+ * @param component - the component's id.
+ * @param stories - its stories' ids.
+ * @returns the files.
+ */
+export const removedBaselines = (files, component, stories) => {
+    const prefixOf = (id) => `${shotName({ story: { id }, name: "" }).replace(/default\.png$/, "")}`;
+    const owned = prefixOf(component);
+    const kept = stories.map(prefixOf);
+    return files.filter((file) => file.startsWith(owned) && !file.endsWith(".diff.png") && !kept.some((prefix) => file.startsWith(prefix)));
+};
+/**
+ * The stored baseline a picture compares with: the one with its name, else the one named by the story's former id
+ * (`StoryCheckStory.formerId`), so the baselines stored before the ids followed Storybook's still count.
+ *
+ * @param files - the baselines folder's files.
+ * @param name - the picture's name.
+ * @param formerName - the name the picture had under the story's former id; none when the id did not change.
+ * @returns the baseline's name; the picture's own when neither is stored (a new baseline).
+ */
+export const storedBaseline = (files, name, formerName) => !files.includes(name) && formerName !== undefined && files.includes(formerName) ? formerName : name;
+/** One picture's result. Read before anything is written: the pictures must not touch what they are compared with. */
+const diffOf = async (page, shot, folders) => {
+    const name = basename(shot.file);
+    const baseline = join(folders.baselines, folders.baselineName);
+    const current = join(folders.out, name);
+    copyFileSync(shot.file, current);
+    const base = { storyId: shot.storyId, view: shot.view, baseline, current };
+    if (shot.status !== undefined)
+        return { ...base, status: "broken", changedPixels: 0, percent: 100 };
+    if (!existsSync(baseline))
+        return { ...base, status: "new", changedPixels: 0, percent: 0 };
+    // most stories do not change, and equal files need no decoding
+    if (readFileSync(baseline).equals(readFileSync(shot.file))) {
+        return { ...base, status: "same", changedPixels: 0, percent: 0 };
+    }
+    const difference = await comparePictures(page, dataUrl(baseline), dataUrl(shot.file));
+    if (difference.isSizeChanged)
+        return { ...base, status: "resized", changedPixels: 0, percent: 100 };
+    if (difference.changedPixels === 0)
+        return { ...base, status: "same", changedPixels: 0, percent: 0 };
+    const diff = join(folders.out, name.replace(/\.png$/, ".diff.png"));
+    const [, data] = (difference.marked ?? "").split(",");
+    writeFileSync(diff, Buffer.from(data ?? "", "base64"));
+    return {
+        ...base,
+        status: "changed",
+        changedPixels: difference.changedPixels,
+        percent: difference.percent,
+        ...(difference.region === undefined ? {} : { region: difference.region }),
+        diff
+    };
+};
+/**
+ * Compares the stories a request names with their baselines.
+ *
+ * @param request - the stories, the views, the baselines' folder and where the pictures go.
+ * @returns one result per story and view, and one per baseline left by a removed story.
+ * @throws when the pictures would go in the baselines' folder, and overwrite what they prove.
+ */
+export const diffStories = async (request) => {
+    if (resolve(request.outDir) === resolve(request.baselines)) {
+        throw new Error("The pictures cannot go in the baselines' folder: give --out another one");
+    }
+    const taken = mkdtempSync(join(tmpdir(), "forgebook-diff-"));
+    mkdirSync(request.outDir, { recursive: true });
+    const browser = await chromium.launch();
+    try {
+        const { shots } = await shotStories({ ...request, outDir: taken });
+        const page = await browser.newPage();
+        const results = [];
+        const stored = existsSync(request.baselines) ? readdirSync(request.baselines) : [];
+        const formerIds = new Map(request.stories.map((story) => [story.id, story.formerId]));
+        for (const shot of shots) {
+            const formerId = formerIds.get(shot.storyId);
+            const formerName = formerId === undefined ? undefined : shotName({ story: { id: formerId }, name: shot.view });
+            const baselineName = storedBaseline(stored, basename(shot.file), formerName);
+            results.push(await diffOf(page, shot, { baselines: request.baselines, out: request.outDir, baselineName }));
+        }
+        // a story's baseline may still carry its former id (`storedBaseline`): it is kept, not removed
+        const stories = request.stories.flatMap((story) => story.formerId === undefined ? [story.id] : [story.id, story.formerId]);
+        const owners = [request.component, request.formerComponent].flatMap((owner) => owner === undefined ? [] : [owner]);
+        const removed = [...new Set(owners.flatMap((owner) => removedBaselines(stored, owner, stories)))];
+        for (const file of removed) {
+            results.push({
+                storyId: file.replace(/\.png$/, ""),
+                view: "",
+                status: "removed",
+                changedPixels: 0,
+                percent: 100,
+                baseline: join(request.baselines, file),
+                current: ""
+            });
+        }
+        return { schema: 1, results };
+    }
+    finally {
+        await browser.close();
+        rmSync(taken, { recursive: true, force: true });
+    }
+};

package/dist/src/overlays.d.ts

@@ -84,4 +84,3 @@ export declare const isOverlayChecked: (view: Partial<ViewState>) => boolean;
  * fixed element ends there.
  */
 export declare const findOverlaysPastFrame: (page: Page, sceneHeight?: number) => Promise<OverlayPastFrame[]>;
-//# sourceMappingURL=overlays.d.ts.map

package/dist/src/overlays.js

@@ -100,4 +100,3 @@ export const findOverlaysPastFrame = async (page, sceneHeight = 0) => {
     await page.evaluate(twoFrames);
     return overlaysPastFrame(layout, grown, WINDOW_GROWTH);
 };
-//# sourceMappingURL=overlays.js.map

package/dist/src/playwrightConfig.d.ts

@@ -35,4 +35,3 @@ export declare const storyTestConfig: (server: StoryTestServer) => PlaywrightTes
  * @param server - the package's folder and ports.
  */
 export declare const visualTestConfig: (server: StoryTestServer) => PlaywrightTestConfig;
-//# sourceMappingURL=playwrightConfig.d.ts.map

package/dist/src/playwrightConfig.js

@@ -31,9 +31,15 @@ export const frameServerCommand = (userAgent) => {
 };
 /** The workers to use. */
 const workersOf = ({ workers }) => workers !== undefined && workers > 0 ? workers : availableParallelism();
-/** The test instance of the frame page, started by Playwright and stopped after the run. */
+/**
+ * The test instance of the frame page, started by Playwright and stopped after the run.
+ *
+ * @remarks
+ * The command runs in a shell (`sh`, or `cmd.exe` on Windows), so the config's path is in double quotes, which both
+ * read: a folder with a space (`C:\Users\Ada Lovelace`) would split it into two arguments.
+ */
 const webServer = ({ dir, port, vite }) => ({
-    command: `${vite ?? frameServerCommand(process.env["npm_config_user_agent"])} --config ${dir}/vite.config.ts --host 127.0.0.1 --port ${port} --strictPort`,
+    command: `${vite ?? frameServerCommand(process.env["npm_config_user_agent"])} --config "${dir}/vite.config.ts" --host 127.0.0.1 --port ${port} --strictPort`,
     url: `http://127.0.0.1:${port}/frame.html`,
     reuseExistingServer: false
 });
@@ -76,4 +82,3 @@ export const visualTestConfig = (server) => {
         }
     };
 };
-//# sourceMappingURL=playwrightConfig.js.map

package/dist/src/semanticJudge.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A model's judgement of what axe cannot see, as `forgebook check --semantic` asks for it: whether a heading says what its
+ * section holds, an image's text says what it shows, a label says what its control does.
+ *
+ * @remarks
+ * Off unless asked, and it sends the story's accessibility tree and picture to the address the user configured, which may
+ * be a third party: no model is bundled and no key is stored. The endpoint speaks the OpenAI chat format, the one most
+ * providers and local servers share. What comes back is a judgement, not a fact, so it is reported apart from the
+ * problems, and it does not fail a check.
+ *
+ * @module
+ */
+import type { Page } from "@playwright/test";
+import type { SemanticModel, StoryJudgement } from "forgebook/story-check";
+/** What a story gives the model. */
+export type StorySight = {
+    /** Its accessibility tree, as text. */
+    readonly tree: string;
+    /** Its picture, a PNG as base64. */
+    readonly picture: string;
+};
+/**
+ * The request a model is sent.
+ *
+ * @param model - the model's name.
+ * @param sight - what the story gives it.
+ * @returns the body, in the OpenAI chat format.
+ */
+export declare const judgementRequest: (model: string, sight: StorySight) => unknown;
+/**
+ * The judgements in a model's answer.
+ *
+ * @param body - the answer's body.
+ * @returns the findings, or why the answer cannot be read: a model that answers nothing usable must not read as a pass.
+ */
+export declare const judgementsOf: (body: unknown) => readonly StoryJudgement[] | string;
+/**
+ * Asks a model about a story.
+ *
+ * @param model - the endpoint, the model's name and its key.
+ * @param sight - what the story gives it.
+ * @returns the findings, or why there are none to give.
+ */
+export declare const askModel: (model: SemanticModel, sight: StorySight) => Promise<readonly StoryJudgement[] | string>;
+/**
+ * What a page gives the model.
+ *
+ * @param page - a page with its story drawn.
+ */
+export declare const storySight: (page: Page) => Promise<StorySight>;