@forgebook/testing 0.1.9 → 0.2.0

package/README.md

@@ -107,6 +107,9 @@ import { storyTestViteConfig } from "@forgebook/testing/vite";
 export default storyTestViteConfig(import.meta.dirname, react());
 ```
 
+The config holds the framework's own Vite plugins (React's, or Solid's that compiles the stories' JSX), as the catalogue
+does: don't add them again.
+
 Then `npx playwright install chromium` once, and `playwright test -c test/stories/playwright.config.ts` starts the
 frame page and runs one test per story and variant (light, dark, both with more contrast, a narrow width, and the
 structure view), starting Vite through the package manager that runs them (`vite` in `testServer.ts` names
@@ -166,3 +169,25 @@ translation catalogue), its HTML checked.
 | `forgebook-shot` | Opens one story of a running catalogue and reports it with a picture |
 
 More: [Forgebook's README](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/README.md).
+
+## Writing a framework adapter
+
+A framework is an adapter package: a renderer, a code writer and a docs reader. `@forgebook/testing/conformance` is what
+every adapter passes, in its own Vitest with a simulated page, so a framework is done when this is green:
+
+```ts
+import { describeAdapter } from "@forgebook/testing/conformance";
+
+describeAdapter({ name: "Solid", renderer, drawing, decorator, codeOf, docsOf });
+```
+
+`drawing(name)` gives a story with a button showing `Hello <name> <clicks>`, its clicks in its own state, which throws
+for `THROWING_NAME`. `decorator(label)` draws a story inside a `section` with that `data-decorator`. A renderer's
+`renderToString` may return a promise. The frame takes only the drawing half, a `FrameRenderer` of `forgebook/renderer`:
+a framework's frame page imports a module without the server render, so the server renderer stays out of a static
+catalogue and of a first start's pre-bundle (`reactFrameRenderer` in `@forgebook/react`). A framework whose page and
+server builds differ runs the suite twice, with `half: "page"` in a simulated page and `half: "server"` in Node: Svelte
+compiles a component apart for each, and Solid's `solid-js/web` is its browser build or its server build, never both.
+`test/conformance.test.tsx` in `@forgebook/react` and `@forgebook/preact`, `test/conformance.test.ts` in
+`@forgebook/vue`, `@forgebook/web-components`, `@forgebook/html` and `@forgebook/angular`, and the two `conformance`
+tests of `@forgebook/svelte` and of `@forgebook/solid` are complete examples.

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

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

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

@@ -121,4 +121,3 @@ await defineScript({
         }
     }
 }).run();
-//# sourceMappingURL=forgebook-heights.mjs.map

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

@@ -81,4 +81,3 @@ export type MeasureResult = {
  */
 export declare const measureStories: (request: MeasureRequest) => Promise<MeasureResult>;
 export {};
-//# sourceMappingURL=measureHeights.d.ts.map

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

@@ -12,6 +12,7 @@
  * @module
  */
 import { chromium } from "@playwright/test";
+import { codeLiteral } from "forgebook/code-literal";
 import { STATUS_ATTRIBUTE } from "forgebook/frame-status";
 import { STORY_IDS_ELEMENT } from "forgebook/story-ids-element";
 import { frameAddressOf } from "forgebook/view-state";
@@ -115,7 +116,7 @@ const measureStory = async (page, address, storyId, widths, timeout) => {
     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, {
+        .waitForFunction(`document.documentElement.getAttribute(${codeLiteral(STATUS_ATTRIBUTE)})`, undefined, {
         timeout
     })
         .then(async (handle) => String(await handle.jsonValue()))
@@ -177,4 +178,3 @@ export const measureStories = async (request) => {
         await browser.close();
     }
 };
-//# sourceMappingURL=measureHeights.js.map

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

@@ -24,4 +24,3 @@ export type HeightsReport = {
     /** 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.js

@@ -4,4 +4,3 @@
  *
  * @module
  */
-//# sourceMappingURL=measureHeights.types.js.map

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

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

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

@@ -107,4 +107,3 @@ await defineScript({
         return shot;
     }
 }).run();
-//# sourceMappingURL=forgebook-shot.mjs.map

package/dist/bin/forgebook-shot/storyShot.d.ts

@@ -31,4 +31,3 @@ export declare const shotAddress: (catalogue: string, story: string, view: strin
  * @returns the report; a frame that never answers is `timeout`, not an exception.
  */
 export declare const takeShot: (request: ShotRequest) => Promise<StoryShot>;
-//# sourceMappingURL=storyShot.d.ts.map

package/dist/bin/forgebook-shot/storyShot.js

@@ -11,6 +11,7 @@
 import { AxeBuilder } from "@axe-core/playwright";
 import { chromium } from "@playwright/test";
 import { DEFAULT_A11Y_TAGS } from "forgebook/catalogue";
+import { codeLiteral } from "forgebook/code-literal";
 import { STATUS_ATTRIBUTE } from "forgebook/frame-status";
 import { frameAddressOf } from "forgebook/view-state";
 /**
@@ -44,7 +45,7 @@ export const takeShot = async (request) => {
         await page.goto(address);
         // a text expression: the command runs on Node, where the page's own globals are not typed
         const status = await page
-            .waitForFunction(`document.documentElement.getAttribute(${JSON.stringify(STATUS_ATTRIBUTE)})`, undefined, {
+            .waitForFunction(`document.documentElement.getAttribute(${codeLiteral(STATUS_ATTRIBUTE)})`, undefined, {
             timeout: request.timeout
         })
             .then(async (handle) => ((await handle.jsonValue()) === "ready" ? "ready" : "error"))
@@ -80,4 +81,3 @@ export const takeShot = async (request) => {
         await browser.close();
     }
 };
-//# sourceMappingURL=storyShot.js.map

package/dist/bin/forgebook-shot/storyShot.types.d.ts

@@ -29,4 +29,3 @@ export type StoryShot = {
     /** The accessibility rules the story breaks, when asked (`--a11y`). */
     readonly violations?: readonly Violation[];
 };
-//# sourceMappingURL=storyShot.types.d.ts.map

package/dist/bin/forgebook-shot/storyShot.types.js

@@ -1 +0,0 @@
-//# sourceMappingURL=storyShot.types.js.map

package/dist/src/browserTests.d.ts

@@ -1,21 +1,3 @@
-/**
- * One Playwright test per story and variant, on the catalogue's frame pages: the address the catalogue shows is the
- * address the tests open.
- *
- * @remarks
- * Each test opens the frame for a story in a variant (the theme, the contrast, the style sheets), waits for the
- * frame to say the story is shown (`data-forgebook-status`), its story clock held at its start, and fails on an error in the console or the page, or on
- * an axe violation of WCAG 2.2 A and AA, on an element that spills out of its parent (`forgebook/spills`: what overlaps a
- * neighbour when the story is narrower than it was drawn for), on an overlay its play leaves open past the frame the
- * catalogue would give it (`overlays.ts`: the story then declares `parameters.height`), or on the source's own
- * `check`. The variants include a
- * narrow frame, as wide as the catalogue's stage beside the props panel. With `screenshot` it compares the frame with its reference image instead,
- * for the visual tests, which run in the Playwright container so fonts and rendering are the same everywhere.
- * A story about logic (`parameters.logic`) is tested once, in the default view, without the layout checks, and never
- * pictured (`storyTestPlan.ts`).
- *
- * @module
- */
 import { type Page } from "@playwright/test";
 import { type CatalogueLists } from "forgebook/catalogue";
 import { type ViewSwitch } from "forgebook/switches";
@@ -70,4 +52,3 @@ export type StoryBrowserTestsOptions = StoryFilesOptions & {
  * the source's own.
  */
 export declare const storyBrowserTests: (options: StoryBrowserTestsOptions) => void;
-//# sourceMappingURL=browserTests.d.ts.map

package/dist/src/browserTests.js

@@ -16,11 +16,12 @@
  *
  * @module
  */
+import { existsSync } from "node:fs";
 import { expect, test } from "@playwright/test";
 import { catalogueSettings } from "forgebook/catalogue";
 import { STATUS_ATTRIBUTE } from "forgebook/frame-status";
 import { heldClockAddress } from "forgebook/story-clock";
-import { storyTree, testedStoryLocations } from "forgebook/story-tree";
+import { formerStoryId, storyTree, testedStoryLocations } from "forgebook/story-tree";
 import { DEFAULT_SWITCHES, switchWithRole } from "forgebook/switches";
 import { defaultView, frameAddress } from "forgebook/view-state";
 import { isOverlayChecked } from "./overlays.js";
@@ -81,6 +82,21 @@ const expectChecksPass = async (page, planned, a11y, check) => {
     await check?.(page);
     expect(messages(await overlayProblems(page, isOverlayChecked(planned.variant.view), planned.story.height))).toEqual([]);
 };
+/**
+ * A story's screenshot name in a variant: by its id, or by the id an earlier rule gave it while only a screenshot of
+ * that name is stored, so the screenshots taken before the ids followed Storybook's keep comparing.
+ *
+ * @param id - the story's id.
+ * @param formerId - the id the former rule gave it.
+ * @param variant - the variant's name.
+ */
+const screenshotName = (id, formerId, variant) => {
+    const named = (storyId) => `${storyId.replace(":", "--")}--${variant}.png`;
+    const isStored = (name) => existsSync(test.info().snapshotPath(name, { kind: "screenshot" }));
+    return named(formerId) !== named(id) && !isStored(named(id)) && isStored(named(formerId))
+        ? named(formerId)
+        : named(id);
+};
 /**
  * Declares the tests, one `describe` per component and one test per story and variant.
  *
@@ -92,7 +108,8 @@ export const storyBrowserTests = (options) => {
     const variants = options.variants ?? storyVariants(switches);
     const catalogue = catalogueSettings("", switches, options.lists);
     const defaults = defaultView(catalogue);
-    const tree = storyTree([indexedSource(options)]);
+    const source = indexedSource(options);
+    const tree = storyTree([source]);
     const groups = Map.groupBy(testedStoryLocations(tree), (location) => location.component.title);
     for (const [title, locations] of groups) {
         const planned = plannedStoryTests(locations.map((location) => location.story), variants, screenshot);
@@ -116,7 +133,8 @@ export const storyBrowserTests = (options) => {
                     await page.goto(heldClockAddress(frameAddress(frameUrl, story.id, view, switches)));
                     await expect(page.locator("html")).toHaveAttribute(STATUS_ATTRIBUTE, "ready");
                     if (screenshot) {
-                        await expect(page).toHaveScreenshot(`${story.id.replace(":", "--")}--${variant.name}.png`, {
+                        const name = screenshotName(story.id, formerStoryId(source.id, title, story.exportName), variant.name);
+                        await expect(page).toHaveScreenshot(name, {
                             fullPage: true,
                             animations: "disabled"
                         });
@@ -129,4 +147,3 @@ export const storyBrowserTests = (options) => {
         });
     }
 };
-//# sourceMappingURL=browserTests.js.map

package/dist/src/checkPage.d.ts

@@ -0,0 +1,16 @@
+import { type CatalogueLists } from "forgebook/catalogue";
+import type { StoryCheckReport } from "forgebook/story-check";
+/** What a page check is asked. */
+export type PageCheckRequest = {
+    /** The pages' addresses. */
+    readonly addresses: readonly string[];
+    /** The catalogue's lists: its accessibility rules. */
+    readonly lists: CatalogueLists;
+};
+/**
+ * Checks pages, on one browser.
+ *
+ * @param request - the addresses and the catalogue's settings.
+ * @returns one result per page, in the request's order.
+ */
+export declare const checkPages: ({ addresses, lists }: PageCheckRequest) => Promise<StoryCheckReport>;

package/dist/src/checkPage.js

@@ -0,0 +1,68 @@
+/**
+ * A real page of an application checked as a story is: accessibility, what spills, and its errors.
+ *
+ * @remarks
+ * An agent verifies the screen it built, not only the stories behind it, so `forgebook check-page` opens any address.
+ * Loaded from the project only when it runs, like `checkStories.ts`. No frame says this page is ready, so it counts as
+ * ready when the network goes quiet, or after `QUIET_MS` for a page that keeps a connection open, which is checked as it
+ * stands then. The report has a story check's shape, the address standing for the story's id.
+ *
+ * @module
+ */
+import { chromium } from "@playwright/test";
+import { catalogueSettings } from "forgebook/catalogue";
+import { axeProblems, errorProblems, focusProblems, spillProblems, watchedErrors } from "./storyCheck.js";
+/** How long a page gets for its network to go quiet, in milliseconds. */
+const QUIET_MS = 10_000;
+/** One page, checked. */
+const checkedPage = async (address, open, a11y) => {
+    const page = await open();
+    const errors = watchedErrors(page);
+    const result = (problems) => ({
+        storyId: address,
+        view: "",
+        frame: address,
+        problems
+    });
+    try {
+        const response = await page.goto(address);
+        await page.waitForLoadState("networkidle", { timeout: QUIET_MS }).catch(() => undefined);
+        if (response !== null && !response.ok()) {
+            return result([{ kind: "frame", message: `It answered ${response.status()}` }]);
+        }
+        return result([
+            ...(await axeProblems(page, a11y)),
+            ...(await spillProblems(page, "body")),
+            ...(await focusProblems(page)),
+            ...errorProblems(errors)
+        ]);
+    }
+    catch (error) {
+        return result([{ kind: "frame", message: error instanceof Error ? error.message : String(error) }]);
+    }
+    finally {
+        await page.close();
+    }
+};
+/**
+ * Checks pages, on one browser.
+ *
+ * @param request - the addresses and the catalogue's settings.
+ * @returns one result per page, in the request's order.
+ */
+export const checkPages = async ({ addresses, lists }) => {
+    const { a11y } = catalogueSettings("", [], lists);
+    const browser = await chromium.launch();
+    try {
+        // from a context of its own: axe opens pages of its own, which a bare `browser.newPage()` cannot share
+        const context = await browser.newContext();
+        const results = [];
+        for (const address of addresses) {
+            results.push(await checkedPage(address, () => context.newPage(), a11y));
+        }
+        return { schema: 1, results };
+    }
+    finally {
+        await browser.close();
+    }
+};

package/dist/src/checkStories.d.ts

@@ -6,4 +6,3 @@ import type { StoryCheckReport, StoryCheckRequest } from "forgebook/story-check"
  * @returns one result per story and view, in the request's order.
  */
 export declare const checkStories: (request: StoryCheckRequest) => Promise<StoryCheckReport>;
-//# sourceMappingURL=checkStories.d.ts.map

package/dist/src/checkStories.js

@@ -1,6 +1,7 @@
 import { catalogueSettings } from "forgebook/catalogue";
 import { isOverlayChecked } from "./overlays.js";
-import { axeProblems, errorProblems, overlayProblems, spillProblems, watchedErrors } from "./storyCheck.js";
+import { askModel, storySight } from "./semanticJudge.js";
+import { axeProblems, errorProblems, focusProblems, overlayProblems, spillProblems, watchedErrors } from "./storyCheck.js";
 import { eachStoryPage, openedStory, READY_MS } from "./storyPages.js";
 import { hasLookChecks } from "./storyTestPlan.js";
 /**
@@ -10,7 +11,7 @@ import { hasLookChecks } from "./storyTestPlan.js";
  * @param storyPage - the story and the view.
  * @param a11y - the catalogue's accessibility settings.
  */
-const checkedPage = async (page, storyPage, a11y) => {
+const checkedPage = async (page, storyPage, a11y, semantic) => {
     const errors = watchedErrors(page);
     const status = await openedStory(page, storyPage);
     const result = (problems) => ({
@@ -34,7 +35,11 @@ const checkedPage = async (page, storyPage, a11y) => {
             ...(await overlayProblems(page, isOverlayChecked(storyPage.view), storyPage.story.height))
         ]
         : [];
-    return result([...(await axeProblems(page, a11y)), ...lookProblems, ...errorProblems(errors)]);
+    const axe = await axeProblems(page, a11y);
+    const checked = result([...axe, ...lookProblems, ...(await focusProblems(page)), ...errorProblems(errors)]);
+    return semantic === undefined
+        ? checked
+        : { ...checked, judgements: await askModel(semantic, await storySight(page)) };
 };
 /**
  * Checks the stories a request names, in its views, on one browser.
@@ -44,7 +49,6 @@ const checkedPage = async (page, storyPage, a11y) => {
  */
 export const checkStories = async (request) => {
     const { a11y } = catalogueSettings("", request.switches, request.lists);
-    const results = await eachStoryPage(request, (page, storyPage) => checkedPage(page, storyPage, a11y));
+    const results = await eachStoryPage(request, (page, storyPage) => checkedPage(page, storyPage, a11y, request.semantic));
     return { schema: 1, results };
 };
-//# sourceMappingURL=checkStories.js.map

package/dist/src/conformance.d.ts

@@ -0,0 +1,46 @@
+import type { StoryCodeWriter, StoryDrawing, StoryRenderer } from "forgebook/renderer";
+import type { LoadedDecorator } from "forgebook/story-module";
+/** A half of the suite: what a story does in a page, or on a server. */
+export type AdapterHalf = "page" | "server";
+/** The name a subject's story throws for. */
+export declare const THROWING_NAME = "boom";
+/** What an adapter hands the suite. */
+export type AdapterSubject = {
+    /** The framework's name, in the tests' titles. */
+    readonly name: string;
+    /** Its renderer. */
+    readonly renderer: StoryRenderer;
+    /**
+     * A drawing of a story with a button that shows `Hello <name> <clicks>`, counting its clicks in its own state, and that
+     * throws while drawn when the name is `THROWING_NAME`.
+     *
+     * @param name - the name, as the story's args carry it.
+     */
+    readonly drawing: (name: string) => StoryDrawing;
+    /**
+     * A decorator that draws the story inside a `section` with this `data-decorator` value, written as the framework
+     * writes one.
+     *
+     * @param label - the value.
+     */
+    readonly decorator: (label: string) => LoadedDecorator;
+    /** The code writer the shell uses. */
+    readonly codeOf: StoryCodeWriter;
+    /**
+     * The framework's docs of a story file's component, as `extractStoryComponent` reads them. None skips the check, for an
+     * adapter with no documented types yet.
+     */
+    readonly docsOf?: () => unknown;
+    /**
+     * The half of the suite this run checks, for a framework whose components are compiled apart for a page and for a
+     * server: its package runs the suite once in a simulated page (`page`, with the code writer and the docs) and once in
+     * Node (`server`). Both halves when none.
+     */
+    readonly half?: AdapterHalf;
+};
+/**
+ * The suite of an adapter.
+ *
+ * @param subject - the adapter's subject.
+ */
+export declare const describeAdapter: (subject: AdapterSubject) => void;

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" });
+};