forgebook 0.3.3 → 0.4.1

package/dist/src/frame/panelValues.js

@@ -0,0 +1,127 @@
+/**
+ * A story's values as they cross to the panel, and back: its own value found by name among the source's named values, and
+ * a name the panel sent turned back into the value for the story. Read in the frame.
+ *
+ * @remarks
+ * A component or a function cannot cross between the shell and a frame; its name can, and each side holds the same source.
+ * Pure.
+ *
+ * @module
+ */
+import { isArgList, isArgObject, isArgValue, isDateArg, isNamedArg, isUnsetArg } from "../messages.js";
+import { namedValueOf } from "../namedValues.js";
+/**
+ * The name of a value among the named ones, when it is one of them.
+ *
+ * @param value - a story's own arg.
+ * @param namedValues - the source's named values.
+ */
+export const nameOf = (value, namedValues) => {
+    for (const [of, values] of Object.entries(namedValues)) {
+        for (const [named, known] of Object.entries(values)) {
+            if (known === value)
+                return { of, named };
+        }
+    }
+    return undefined;
+};
+/** The most parts of one arg the panel is told of: a table's data is the story's, and costs every message it crosses. */
+const MOST_PARTS = 2000;
+/** The deepest an arg the panel is told of nests: a cycle ends here too. */
+const MOST_DEPTH = 12;
+/** A list as the panel can show it, or none when any item is not plain data. */
+const panelListOf = (list, walk, depth) => {
+    const items = list.map((item) => panelValueOf(item, walk, depth + 1));
+    return items.every((item) => item !== undefined) ? items.filter((item) => item !== undefined) : undefined;
+};
+/** A plain object as the panel can show it, or none when any field is not plain data. */
+const panelObjectOf = (value, walk, depth) => {
+    const fields = [];
+    for (const [name, each] of Object.entries(value)) {
+        if (each === undefined)
+            continue;
+        const shown = panelValueOf(each, walk, depth + 1);
+        if (shown === undefined)
+            return undefined;
+        fields.push([name, shown]);
+    }
+    return Object.fromEntries(fields);
+};
+/** Whether a value crosses as it is. */
+const isPlainLeaf = (value) => value === null || typeof value === "string" || typeof value === "boolean";
+/** A `Date` as the panel can show it: its moment, when it has one. */
+const dateValueOf = (date) => Number.isNaN(date.getTime()) ? undefined : { forgebookDate: date.toISOString() };
+/**
+ * A story's value as the panel can show it, or none when any part of it is not plain data.
+ *
+ * @param value - the value.
+ * @param walk - what the walk carries.
+ * @param depth - how deep it is.
+ */
+const panelValueOf = (value, walk, depth) => {
+    walk.parts -= 1;
+    if (walk.parts < 0 || depth > MOST_DEPTH)
+        return undefined;
+    if (isPlainLeaf(value))
+        return value;
+    if (typeof value === "number")
+        return depth === 0 || Number.isFinite(value) ? value : undefined;
+    const named = nameOf(value, walk.namedValues);
+    if (named !== undefined)
+        return named;
+    if (value instanceof Date)
+        return dateValueOf(value);
+    if (Array.isArray(value))
+        return panelListOf(value, walk, depth);
+    if (typeof value !== "object")
+        return undefined;
+    const prototype = Object.getPrototypeOf(value);
+    // a date, a map or a class's instance is not what a link can hold, nor what JSON gives back
+    return prototype === Object.prototype || prototype === null ? panelObjectOf(value, walk, depth) : undefined;
+};
+/**
+ * A story's own args as the panel can show them: plain data as it is, a named value by its name at any depth; an arg
+ * with anything else in it (an element, a function, a date) is left out whole.
+ *
+ * @param args - the story's args.
+ * @param namedValues - the source's named values; none by default.
+ */
+export const panelArgsOf = (args, namedValues = {}) => Object.fromEntries(Object.entries(args).flatMap(([name, value]) => {
+    const shown = panelValueOf(value, { namedValues, parts: MOST_PARTS }, 0);
+    // a name no value may hold (`constructor`) would have the shell refuse the frame's whole message
+    return shown === undefined || !isArgValue(shown) ? [] : [[name, shown]];
+}));
+/**
+ * A panel's value as the story takes it: each name turned back into its value, at any depth; a name the source no longer
+ * offers is none.
+ *
+ * @param value - the value.
+ * @param namedValues - the source's named values.
+ */
+const storyValueOf = (value, namedValues) => {
+    if (isNamedArg(value))
+        return namedValueOf(namedValues, value.of, value.named);
+    if (isDateArg(value))
+        return new Date(value.forgebookDate);
+    if (isArgList(value))
+        return value.map((item) => storyValueOf(item, namedValues)).filter((item) => item !== undefined);
+    if (!isArgObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).flatMap(([name, each]) => {
+        const known = storyValueOf(each, namedValues);
+        return known === undefined ? [] : [[name, known]];
+    }));
+};
+/**
+ * The panel's values as the story takes them: a name turned back into its value, a name the source no longer offers
+ * left out so the story keeps its own, and the panel's "no value" as `undefined` over the story's own.
+ *
+ * @param args - the panel's values.
+ * @param namedValues - the source's named values; none by default.
+ */
+export const storyArgsOf = (args, namedValues = {}) => Object.fromEntries(Object.entries(args).flatMap(([name, value]) => {
+    if (isUnsetArg(value))
+        return [[name, undefined]];
+    const known = storyValueOf(value, namedValues);
+    return known === undefined ? [] : [[name, known]];
+}));

package/dist/src/frame/playActions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A play's actions, one by one: what the play did through the `canvas` and the `userEvent` its context hands it, for
+ * the Interactions tab's log and its step debugger.
+ *
+ * @remarks
+ * The tools are wrapped, not the library: the story is what is shown, and what a play imports itself
+ * (`@testing-library/user-event`, `storybook/test`) is another object, so it runs unrecorded. A sync query must stay sync,
+ * so only what already returns a promise (a `findBy…`, a user's action, a `step`) can wait for "next"; a `getBy…` is only
+ * logged. A wrapped action behaves as the tool does, its result and its throw included.
+ *
+ * @module
+ */
+import type { PlayAction } from "../playTrace.ts";
+/** What the wrapped tools report to. */
+export type ActionRecorder = {
+    /** Waits until the play may go on past an action, by its text; at once unless the play is being stepped through. */
+    readonly gate: (label: string) => Promise<void>;
+    /** Adds an action to the log; its index. */
+    readonly begin: (label: string) => number;
+    /** Ends an action in the log. */
+    readonly end: (index: number, action: PlayAction) => void;
+};
+/**
+ * A tool whose functions log themselves.
+ *
+ * @param tool - the tool (`canvas`, `userEvent`); anything else stays as it is.
+ * @param name - its name in the log.
+ * @param recorder - what it reports to.
+ * @param isSync - whether a function of it returns at once: logged, never held.
+ */
+export declare const recordedTool: (tool: unknown, name: string, recorder: ActionRecorder, isSync: (member: string) => boolean) => unknown;
+/**
+ * Whether a query of Testing Library returns at once: all but `findBy…` and `findAllBy…`.
+ *
+ * @param member - the query's name.
+ */
+export declare const isSyncQuery: (member: string) => boolean;
+/** Whether a member of `userEvent` returns at once: none of them does, but for its `setup`. */
+export declare const isSyncEvent: () => boolean;

package/dist/src/frame/playActions.js

@@ -0,0 +1,98 @@
+import { previewValue } from "./callValues.js";
+/** Milliseconds since an instant, rounded. */
+const since = (start) => Math.round(performance.now() - start);
+/** The most characters of a call the log keeps. */
+const LABEL_LENGTH = 200;
+/** The most characters of an error the log keeps: a failed query's message holds the whole document. */
+const ERROR_LENGTH = 300;
+/** An error's message, cut to what a line of the log holds. */
+const messageOf = (error) => (error instanceof Error ? error.message : String(error)).slice(0, ERROR_LENGTH);
+/**
+ * An argument as the log shows it: an element by its tag and its name, the rest as the Events tab shows them.
+ *
+ * @param value - the argument.
+ */
+const argText = (value) => {
+    if (typeof Element !== "undefined" && value instanceof Element) {
+        const name = (value.getAttribute("aria-label") ?? value.textContent?.trim() ?? "").slice(0, 30);
+        return name === "" ? `<${value.localName}>` : `<${value.localName}> "${name}"`;
+    }
+    return value instanceof RegExp ? String(value) : previewValue(value);
+};
+/** The text of a call. */
+const callText = (name, args) => `${name}(${args.map(argText).join(", ")})`.slice(0, LABEL_LENGTH);
+/**
+ * A tool's async function, logged and held at the gate.
+ *
+ * @param label - the function's name in the log.
+ * @param run - calls the function.
+ * @param recorder - what it reports to.
+ */
+const heldCall = async (label, run, recorder) => {
+    await recorder.gate(label);
+    const index = recorder.begin(label);
+    const start = performance.now();
+    try {
+        const result = await run();
+        recorder.end(index, { label, status: "passed", ms: since(start) });
+        return result;
+    }
+    catch (error) {
+        recorder.end(index, { label, status: "failed", ms: since(start), error: messageOf(error) });
+        throw error;
+    }
+};
+/**
+ * A tool's sync function, logged.
+ *
+ * @param label - the function's name in the log.
+ * @param run - calls the function.
+ * @param recorder - what it reports to.
+ */
+const loggedCall = (label, run, recorder) => {
+    const index = recorder.begin(label);
+    try {
+        const result = run();
+        recorder.end(index, { label, status: "passed", ms: 0 });
+        return result;
+    }
+    catch (error) {
+        recorder.end(index, { label, status: "failed", ms: 0, error: messageOf(error) });
+        throw error;
+    }
+};
+/**
+ * A tool whose functions log themselves.
+ *
+ * @param tool - the tool (`canvas`, `userEvent`); anything else stays as it is.
+ * @param name - its name in the log.
+ * @param recorder - what it reports to.
+ * @param isSync - whether a function of it returns at once: logged, never held.
+ */
+export const recordedTool = (tool, name, recorder, isSync) => {
+    if (typeof tool !== "object" || tool === null)
+        return tool;
+    return new Proxy(tool, {
+        get: (target, key) => {
+            const member = Reflect.get(target, key);
+            if (typeof member !== "function" || typeof key !== "string")
+                return member;
+            return (...args) => {
+                const label = callText(`${name}.${key}`, args);
+                const run = () => Reflect.apply(member, target, args);
+                // `userEvent.setup()` hands back the instance the rest of the play uses
+                if (key === "setup")
+                    return recordedTool(run(), name, recorder, isSync);
+                return isSync(key) ? loggedCall(label, run, recorder) : heldCall(label, run, recorder);
+            };
+        }
+    });
+};
+/**
+ * Whether a query of Testing Library returns at once: all but `findBy…` and `findAllBy…`.
+ *
+ * @param member - the query's name.
+ */
+export const isSyncQuery = (member) => !member.startsWith("find");
+/** Whether a member of `userEvent` returns at once: none of them does, but for its `setup`. */
+export const isSyncEvent = () => false;

package/dist/src/frame/playStepper.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How a frame starts a play and holds it: the step debugger's hold waits before each action for "next", until
+ * "continue" lets the rest run.
+ *
+ * @remarks
+ * Most stories have no play, and every frame loads this module with `storyRun.ts`: the play's runner (`playStory.ts`)
+ * and the actions it records load with the first story that has a play, not with every frame.
+ *
+ * @module
+ */
+import type { PlayStepper, playStory } from "./playStory.ts";
+/** A hold the shell's commands release. */
+export type HeldStepper = PlayStepper & {
+    /** Lets the play do its next action. */
+    readonly next: () => void;
+    /** Lets the play run to its end. */
+    readonly release: () => void;
+};
+/** A new hold: the play stops before its first action. */
+export declare const heldStepper: () => HeldStepper;
+/**
+ * Plays a story, then calls `onPlayed`: at once when it has no play, without loading the runner.
+ *
+ * @param args - what `playStory` takes, in its order: the play, its context, `onPlayed`, `onTrace`, the tools and the
+ * stepper.
+ * @returns the play's promise, rejected when the play failed.
+ */
+export declare const runPlay: (...args: Parameters<typeof playStory>) => Promise<void>;

package/dist/src/frame/playStepper.js

@@ -0,0 +1,38 @@
+/** A new hold: the play stops before its first action. */
+export const heldStepper = () => {
+    let isHolding = true;
+    // a play may wait on several actions at once (`Promise.all`): "next" lets them all go
+    let waiting = [];
+    const next = () => {
+        for (const resume of waiting)
+            resume();
+        waiting = [];
+    };
+    return {
+        isHolding: () => isHolding,
+        wait: () => new Promise((resolve) => {
+            waiting = [...waiting, resolve];
+        }),
+        next,
+        release: () => {
+            isHolding = false;
+            next();
+        }
+    };
+};
+/**
+ * Plays a story, then calls `onPlayed`: at once when it has no play, without loading the runner.
+ *
+ * @param args - what `playStory` takes, in its order: the play, its context, `onPlayed`, `onTrace`, the tools and the
+ * stepper.
+ * @returns the play's promise, rejected when the play failed.
+ */
+export const runPlay = async (...args) => {
+    const [play, , onPlayed] = args;
+    if (play === undefined) {
+        onPlayed();
+        return;
+    }
+    const runner = await import("./playStory.js");
+    return runner.playStory(...args);
+};

package/dist/src/frame/playStory.d.ts

@@ -26,6 +26,13 @@ export type PlayTools = {
  * generated frame passes one when the project installs Testing Library.
  */
 export type PlayToolsLoader = () => Promise<PlayTools>;
+/** What holds a play before each action while it is stepped through. */
+export type PlayStepper = {
+    /** Whether the play still stops before an action; "continue" ends that. */
+    readonly isHolding: () => boolean;
+    /** Resolves when "next" or "continue" comes. */
+    readonly wait: () => Promise<void>;
+};
 /**
  * Plays a story, then calls `onPlayed`.
  *
@@ -34,6 +41,7 @@ export type PlayToolsLoader = () => Promise<PlayTools>;
  * @param onPlayed - called once the play is over, at once when there is none, whether it passed or failed.
  * @param onTrace - called with the trace after every change; never without a play.
  * @param tools - the play tools to hand the play (`canvas` bound to its canvas, `userEvent`); none without them.
+ * @param stepper - holds the play before each action, while it is stepped through; none lets it run.
  * @returns the play's promise, rejected when the play failed.
  */
-export declare const playStory: (play: LoadedStory["play"], context: Omit<StoryContext<LoadedArgs>, "step">, onPlayed: () => void, onTrace?: (trace: PlayTrace) => void, tools?: PlayTools | undefined) => Promise<void>;
+export declare const playStory: (play: LoadedStory["play"], context: Omit<StoryContext<LoadedArgs>, "step">, onPlayed: () => void, onTrace?: (trace: PlayTrace) => void, tools?: PlayTools | undefined, stepper?: PlayStepper | undefined) => Promise<void>;

package/dist/src/frame/playStory.js

@@ -1,7 +1,10 @@
+import { isSyncEvent, isSyncQuery, recordedTool } from "./playActions.js";
 /** A thrown value's message. */
 const messageOf = (error) => (error instanceof Error ? error.message : String(error));
 /** Milliseconds since an instant, rounded. */
 const since = (start) => Math.round(performance.now() - start);
+/** The most actions a trace holds: each message carries the whole list. */
+const MAX_ACTIONS = 200;
 /**
  * Plays a story, then calls `onPlayed`.
  *
@@ -10,23 +13,58 @@ const since = (start) => Math.round(performance.now() - start);
  * @param onPlayed - called once the play is over, at once when there is none, whether it passed or failed.
  * @param onTrace - called with the trace after every change; never without a play.
  * @param tools - the play tools to hand the play (`canvas` bound to its canvas, `userEvent`); none without them.
+ * @param stepper - holds the play before each action, while it is stepped through; none lets it run.
  * @returns the play's promise, rejected when the play failed.
  */
-export const playStory = async (play, context, onPlayed, onTrace = () => undefined, tools = undefined) => {
+export const playStory = async (play, context, onPlayed, onTrace = () => undefined, tools = undefined, stepper = undefined) => {
     if (play === undefined) {
         onPlayed();
         return;
     }
     let steps = [];
-    const report = (trace) => onTrace({ ...trace, steps });
+    let actions = [];
+    let openStep;
+    const report = (trace) => onTrace({ ...trace, steps, ...(actions.length === 0 ? {} : { actions }) });
+    const gate = async (label) => {
+        if (stepper?.isHolding() !== true)
+            return;
+        report({ status: "running", pausedAt: label });
+        await stepper.wait();
+        report({ status: "running" });
+    };
+    const recorder = {
+        gate,
+        begin: (label) => {
+            // a `waitFor` runs its query again until it passes: its failures are one line, not one each
+            const last = actions.at(-1);
+            if (last?.label === label && last.status === "failed")
+                return actions.length - 1;
+            // a play in a loop must not grow every message past what a person reads
+            if (actions.length >= MAX_ACTIONS)
+                return actions.length;
+            actions = [
+                ...actions,
+                { label, status: "running", ...(openStep === undefined ? {} : { step: openStep }) }
+            ];
+            report({ status: "running" });
+            return actions.length - 1;
+        },
+        end: (index, action) => {
+            actions = actions.map((current, at) => (at === index ? { ...current, ...action } : current));
+            report({ status: "running" });
+        }
+    };
     const setStep = (index, step) => {
         steps = steps.map((current, at) => (at === index ? step : current));
         report({ status: "running" });
     };
     const step = async (label, run) => {
+        await gate(label);
         const index = steps.length;
+        const outer = openStep;
         const start = performance.now();
         steps = [...steps, { label, status: "running" }];
+        openStep = index;
         report({ status: "running" });
         try {
             await run();
@@ -36,11 +74,19 @@ export const playStory = async (play, context, onPlayed, onTrace = () => undefin
             setStep(index, { label, status: "failed", ms: since(start), error: messageOf(error) });
             throw error;
         }
+        finally {
+            openStep = outer;
+        }
     };
     const start = performance.now();
     report({ status: "running" });
     try {
-        const toolsContext = tools === undefined ? {} : { canvas: tools.within(context.canvasElement), userEvent: tools.userEvent };
+        const toolsContext = tools === undefined
+            ? {}
+            : {
+                canvas: recordedTool(tools.within(context.canvasElement), "canvas", recorder, isSyncQuery),
+                userEvent: recordedTool(tools.userEvent, "userEvent", recorder, isSyncEvent)
+            };
         await play({ ...context, step, ...toolsContext });
         report({ status: "passed", ms: since(start) });
     }

package/dist/src/frame/renderer.d.ts

@@ -60,6 +60,17 @@ export type StoryDrawing = {
      */
     readonly changeArgs?: (change: ArgsChange) => void;
 };
+/**
+ * What a framework can say of what a drawn story still waits for: everything came, something is still loading (a
+ * `Suspense` boundary showing its fallback), or it cannot tell, which is never read as everything came.
+ */
+export type ContentState = {
+    readonly state: "settled";
+} | {
+    readonly state: "waiting" | "unknown";
+    /** What it waits for, or why it cannot tell, in a sentence a person reads. */
+    readonly reason: string;
+};
 /** What the frame keeps of a story drawn in a canvas. */
 export type MountedStory = {
     /**
@@ -67,6 +78,17 @@ export type MountedStory = {
      * story throws while it is first drawn (the error goes to `onError` instead).
      */
     readonly drawn: Promise<void>;
+    /**
+     * Waits until the story no longer shows a loading state of its framework (`Suspense`), for so long, in milliseconds.
+     * The frame calls it after `drawn` and after the play function, unless the story says it stays there
+     * (`parameters.suspense.expected`). A framework with no such state, or none it can read, leaves it out: its stories
+     * are ready once drawn.
+     *
+     * @param timeout - the most to wait, in milliseconds.
+     * @returns `settled`, `waiting` when the time ran out, or `unknown` when the framework cannot tell; a rejection reads as
+     *   `unknown`.
+     */
+    readonly settled?: (timeout: number) => Promise<ContentState>;
     /**
      * Draws the story again, keeping its state: other args, other switch values, another language; a story that threw
      * is tried again.
@@ -108,8 +130,19 @@ export type StoryRenderer = FrameRenderer & {
  *
  * @param component - the component's name, as its documentation names it.
  * @param args - the values of the moment, a named value by its name.
+ * @param written - the args the story file writes as code (a function, an element, a constant), each as written and
+ * written over its value; none or empty writes the values alone. A writer that cannot use them may ignore them.
+ */
+export type StoryCodeWriter = (component: string, args: PanelArgs, written?: Readonly<Record<string, string>>) => string;
+/**
+ * Waits for what a story waits for by looking at it: the first look is at once, so a story that waits for nothing pays
+ * for one look; the next ones start close together, since most waits are a state set in an effect, and spread out.
+ *
+ * @param read - looks at the story: what `MountedStory.settled` answers at this moment.
+ * @param timeout - the most to wait, in milliseconds.
+ * @returns the state once it is not `waiting`, or `waiting` once the time ran out.
  */
-export type StoryCodeWriter = (component: string, args: PanelArgs) => string;
+export declare const contentSettled: (read: () => ContentState, timeout: number) => Promise<ContentState>;
 /** The `step` a render and a decorator receive: outside a play there is no trace, so a step only runs its part. */
 export declare const untracedStep: StepFunction;
 /**

package/dist/src/frame/renderer.js

@@ -12,6 +12,30 @@
  * @module
  */
 import { storyTextOf } from "@forgebook/story-format/texts";
+/** The longest pause between two looks at what a story waits for, in milliseconds. */
+const LONGEST_LOOK = 50;
+/**
+ * Waits for what a story waits for by looking at it: the first look is at once, so a story that waits for nothing pays
+ * for one look; the next ones start close together, since most waits are a state set in an effect, and spread out.
+ *
+ * @param read - looks at the story: what `MountedStory.settled` answers at this moment.
+ * @param timeout - the most to wait, in milliseconds.
+ * @returns the state once it is not `waiting`, or `waiting` once the time ran out.
+ */
+export const contentSettled = (read, timeout) => new Promise((resolve) => {
+    const start = performance.now();
+    let pause = 1;
+    const look = () => {
+        const content = read();
+        if (content.state !== "waiting" || performance.now() - start >= timeout) {
+            resolve(content);
+            return;
+        }
+        setTimeout(look, pause);
+        pause = Math.min(pause * 2, LONGEST_LOOK);
+    };
+    look();
+});
 /** The `step` a render and a decorator receive: outside a play there is no trace, so a step only runs its part. */
 export const untracedStep = async (_label, run) => {
     await run();

package/dist/src/frame/shellChannel.d.ts

@@ -10,7 +10,7 @@
  * @module
  */
 import { type FramesPlacement, type PageLocation } from "../frameOrigins.ts";
-import { type FrameMessage, type ShellMessage } from "../messages.ts";
+import type { FrameMessage, ShellMessage } from "../messages.ts";
 /** A message's event, as the frame reads it. */
 export type ShellEvent = {
     /** The sender's origin. */

package/dist/src/frame/shellChannel.js

@@ -10,7 +10,7 @@
  * @module
  */
 import { pageOrigins } from "../frameOrigins.js";
-import { isShellMessage } from "../messages.js";
+import { isShellMessage } from "./shellMessageCheck.js";
 /**
  * The frame's channel with its shell.
  *

package/dist/src/frame/shellCheck.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A frame's answer to the shell's Check: the story's accessibility, or why it cannot be checked.
+ *
+ * @module
+ */
+import type { A11ySettings } from "../catalogue.ts";
+import type { ShellChannel } from "./shellChannel.ts";
+/**
+ * Checks the story's accessibility and tells the shell the result.
+ *
+ * @param storyId - the story's id, for the answers.
+ * @param pendingReason - why the story was not seen in its final state, if so: answered instead of a check.
+ * @param rules - the catalogue's accessibility rules; none when it checks no accessibility.
+ * @param axeUrl - the address of axe's script.
+ * @param tellShell - tells the shell the check's result.
+ */
+export declare const checkForShell: (storyId: string, pendingReason: string | undefined, rules: A11ySettings | undefined, axeUrl: string | undefined, tellShell: ShellChannel["tell"]) => void;

package/dist/src/frame/shellCheck.js

@@ -0,0 +1,25 @@
+/**
+ * Checks the story's accessibility and tells the shell the result.
+ *
+ * @param storyId - the story's id, for the answers.
+ * @param pendingReason - why the story was not seen in its final state, if so: answered instead of a check.
+ * @param rules - the catalogue's accessibility rules; none when it checks no accessibility.
+ * @param axeUrl - the address of axe's script.
+ * @param tellShell - tells the shell the check's result.
+ */
+export const checkForShell = (storyId, pendingReason, rules, axeUrl, tellShell) => {
+    // loaded on the first check: a frame that is never checked, or one of a catalogue that checks nothing, never
+    // fetches the code that loads axe
+    const refusal = pendingReason ??
+        (rules === undefined ? "The catalogue checks no accessibility (a11y: false)" : undefined);
+    const checked = refusal !== undefined || rules === undefined
+        ? Promise.reject(new Error(refusal))
+        : import("./checkStory.js").then((module) => module.checkStory(document, rules, axeUrl));
+    checked
+        .then((violations) => tellShell({ type: "forgebook:checked", storyId, violations }))
+        .catch((error) => tellShell({
+        type: "forgebook:check-error",
+        storyId,
+        message: error instanceof Error ? error.message : String(error)
+    }));
+};

package/dist/src/frame/shellMessageCheck.d.ts

@@ -0,0 +1,7 @@
+import { type ShellMessage } from "../messages.ts";
+/**
+ * Whether a received message is one the shell sends.
+ *
+ * @param value - the message's data.
+ */
+export declare const isShellMessage: (value: unknown) => value is ShellMessage;

package/dist/src/frame/shellMessageCheck.js

@@ -0,0 +1,53 @@
+/**
+ * The check a frame makes of what arrives from the shell: a page may receive messages from anything it embeds or is
+ * embedded in. Kept with the frame, so that the shell's page does not load what only the frame reads.
+ *
+ * @module
+ */
+import { isMatrix } from "../matrix.js";
+import { isPanelArgs } from "../messages.js";
+import { isClockRate } from "../storyClock.js";
+import { MEASURE_TOOLS } from "../viewState.js";
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a value is a list of strings. */
+const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+/** Whether a value is the view's live part. */
+const isLiveView = (value) => isRecord(value) &&
+    isRecord(value["switches"]) &&
+    Object.values(value["switches"]).every((switchValue) => typeof switchValue === "string") &&
+    typeof value["backdrop"] === "string" &&
+    typeof value["text"] === "number";
+/** Whether a value is a story clock's state. */
+const isClockState = (value) => isRecord(value) && typeof value["isRunning"] === "boolean" && isClockRate(value["rate"]);
+/**
+ * Whether a received message is one the shell sends.
+ *
+ * @param value - the message's data.
+ */
+export const isShellMessage = (value) => {
+    if (!isRecord(value))
+        return false;
+    if (value["type"] === "forgebook:replay" ||
+        value["type"] === "forgebook:check" ||
+        value["type"] === "forgebook:clock-restart") {
+        return true;
+    }
+    if (value["type"] === "forgebook:play-step")
+        return ["again", "start", "next", "continue"].includes(String(value["command"]));
+    if (value["type"] === "forgebook:args")
+        return isPanelArgs(value["args"]);
+    if (value["type"] === "forgebook:view")
+        return isLiveView(value["view"]);
+    if (value["type"] === "forgebook:clock")
+        return isClockState(value["state"]);
+    if (value["type"] === "forgebook:spills")
+        return typeof value["isOn"] === "boolean";
+    if (value["type"] === "forgebook:tools") {
+        const tools = value["tools"];
+        return Array.isArray(tools) && tools.every((tool) => MEASURE_TOOLS.some((known) => known === tool));
+    }
+    if (value["type"] === "forgebook:matrix")
+        return value["matrix"] === null || isMatrix(value["matrix"]);
+    return value["type"] === "forgebook:events" && isStringList(value["names"]);
+};