forgebook 0.3.3 → 0.4.0

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

@@ -0,0 +1,50 @@
+/**
+ * How a story run waits for what its framework says the story loads, and how the story ended: what a play starts from and
+ * what the frame's status says.
+ *
+ * @remarks
+ * The frame only asks (`MountedStory.settled`); reading what is pending is the framework's. A framework with nothing to
+ * say costs nothing here, and its stories are ready once drawn.
+ *
+ * @module
+ */
+import type { ContentState, MountedStory } from "./renderer.ts";
+import type { LoadedStory } from "./storyModule.ts";
+/** How a story's first drawing ended: what the frame's status says. */
+export type StoryOutcome = 
+/** It is shown, with everything it waits for, and its play is over. */
+{
+    readonly status: "ready";
+}
+/** It threw meanwhile, and shows its error. */
+ | {
+    readonly status: "error";
+}
+/** The wait ended with something still loading, or the framework cannot tell: this says which. */
+ | {
+    readonly status: "pending";
+    readonly reason: string;
+};
+/**
+ * Waits for what a story loads, as it says it should be waited for.
+ *
+ * @param mounted - the story, drawn.
+ * @param story - its settings.
+ * @param timeout - the most to wait, in milliseconds; the story's bound by default.
+ */
+export declare const contentOf: (mounted: MountedStory, { suspense }: LoadedStory, timeout?: number) => Promise<ContentState>;
+/**
+ * Waits for a story's first drawing and for what it loads, which share one bound, as what a play starts from.
+ *
+ * @param mounted - the story.
+ * @param story - its settings.
+ */
+export declare const contentBeforePlay: (mounted: MountedStory, story: LoadedStory) => Promise<ContentState>;
+/**
+ * How a story ended, by what it waited for and whether it shows an error.
+ *
+ * @param content - the last look at what it loads.
+ * @param isFailed - whether it shows an error now.
+ * @param timeout - how long the frame waited, in milliseconds.
+ */
+export declare const outcomeOf: (content: ContentState, isFailed: boolean, timeout: number) => StoryOutcome;

package/dist/src/frame/storyContent.js

@@ -0,0 +1,73 @@
+/** What a story that waits for nothing has to say. */
+const SETTLED = { state: "settled" };
+/**
+ * Waits for what a story loads, as it says it should be waited for.
+ *
+ * @param mounted - the story, drawn.
+ * @param story - its settings.
+ * @param timeout - the most to wait, in milliseconds; the story's bound by default.
+ */
+export const contentOf = async (mounted, { suspense }, timeout = suspense.timeout) => {
+    if (suspense.isExpected || mounted.settled === undefined)
+        return SETTLED;
+    try {
+        return await mounted.settled(timeout);
+    }
+    catch (error) {
+        // an adapter that fails while it looks has not looked: never read as nothing pending, and a frame still answers
+        return { state: "unknown", reason: error instanceof Error ? error.message : String(error) };
+    }
+};
+/**
+ * Waits for a story's first drawing, within its bound, for a framework that has a wait to bound: a part that suspends
+ * with no boundary around it holds React's first commit, and that must end as a frame's answer, not as its silence. A
+ * framework with no wait keeps the frame waiting as long as it draws (a compiler loading on first use).
+ *
+ * @param mounted - the story.
+ * @param story - its settings.
+ * @returns what it still waits for, none once drawn.
+ */
+const drawnWithin = async (mounted, { suspense }) => {
+    if (suspense.isExpected || mounted.settled === undefined) {
+        await mounted.drawn;
+        return SETTLED;
+    }
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ state: "waiting", reason: "The story's first drawing still waits for what it loads" }), suspense.timeout);
+    });
+    const drawn = mounted.drawn.then(() => SETTLED);
+    return Promise.race([drawn, late]).finally(() => clearTimeout(timer));
+};
+/**
+ * Waits for a story's first drawing and for what it loads, which share one bound, as what a play starts from.
+ *
+ * @param mounted - the story.
+ * @param story - its settings.
+ */
+export const contentBeforePlay = async (mounted, story) => {
+    const start = performance.now();
+    const first = await drawnWithin(mounted, story);
+    if (first.state !== "settled")
+        return first;
+    return contentOf(mounted, story, Math.max(0, story.suspense.timeout - (performance.now() - start)));
+};
+/**
+ * How a story ended, by what it waited for and whether it shows an error.
+ *
+ * @param content - the last look at what it loads.
+ * @param isFailed - whether it shows an error now.
+ * @param timeout - how long the frame waited, in milliseconds.
+ */
+export const outcomeOf = (content, isFailed, timeout) => {
+    if (isFailed)
+        return { status: "error" };
+    if (content.state === "settled")
+        return { status: "ready" };
+    if (content.state === "unknown")
+        return { status: "pending", reason: content.reason };
+    return {
+        status: "pending",
+        reason: `${content.reason} after ${timeout} ms. A story meant to stay there sets parameters.suspense.expected; parameters.suspense.timeout waits longer`
+    };
+};

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

@@ -58,6 +58,15 @@ export type LoadedStory = {
     readonly layout: NonNullable<StoryParameters["layout"]>;
     /** A Live story's clock start, in ms since the Unix epoch (`parameters.clock`); none for a still. */
     readonly clockStart: number | undefined;
+    /** How the frame waits for a loading state (`parameters.suspense`). */
+    readonly suspense: StorySuspense;
+};
+/** How the frame waits for what a story loads before it says the story is ready. */
+export type StorySuspense = {
+    /** Whether the story is meant to stay in a loading state: the frame does not wait, and it is simply ready. */
+    readonly isExpected: boolean;
+    /** The most to wait, in milliseconds. */
+    readonly timeout: number;
 };
 /**
  * The meta and one story of a loaded module, merged.

package/dist/src/frame/storyModule.js

@@ -14,7 +14,12 @@
  *
  * @module
  */
-import { controlsOfParameter, mergedArgTypes } from "../argTypes.js";
+import { controlsOfParameter, mergedArgTypes } from "../storyArgTypes.js";
+/**
+ * How long a frame waits by default, in milliseconds: a lazy module on a dev server still preparing its dependencies
+ * takes seconds, and `forgebook check` stops listening to a silent frame at 30.
+ */
+const SUSPENSE_TIMEOUT = 10_000;
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
@@ -98,6 +103,18 @@ const ownOrMeta = (story, meta, name) => {
     const fromMeta = meta[name];
     return isFunction(fromMeta) ? fromMeta : undefined;
 };
+/**
+ * How the frame waits for a story, from its parameter; a timeout that is no time at all is the default's.
+ *
+ * @param setting - `parameters.suspense`.
+ */
+const suspenseOf = (setting) => {
+    const timeout = isRecord(setting) ? setting["timeout"] : undefined;
+    return {
+        isExpected: isRecord(setting) && setting["expected"] === true,
+        timeout: typeof timeout === "number" && timeout > 0 && Number.isFinite(timeout) ? timeout : SUSPENSE_TIMEOUT
+    };
+};
 /**
  * The meta and one story of a loaded module, merged.
  *
@@ -146,7 +163,8 @@ export const readStory = (module, exportName, preview = NO_PREVIEW) => {
             ...(isRecord(story["globals"]) ? story["globals"] : {})
         },
         layout: layout === "centered" || layout === "fullscreen" ? layout : "padded",
-        clockStart: clockStartOf(parameters["clock"])
+        clockStart: clockStartOf(parameters["clock"]),
+        suspense: suspenseOf(parameters["suspense"])
     };
 };
 /** The preview of a catalogue that has none. */

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

@@ -13,12 +13,14 @@
  */
 import { type StoryTextTable } from "@forgebook/story-format/texts";
 import type { Matrix } from "../matrix.ts";
-import type { PanelArgs } from "../messages.ts";
+import type { PlayStepCommand } from "../messages.ts";
+import { type PanelArgs } from "../messages.ts";
 import type { PlayTrace } from "../playTrace.ts";
 import type { ClockState } from "../storyClock.ts";
 import type { FrameClock } from "./frameClock.ts";
-import { type PlayToolsLoader } from "./playStory.ts";
+import type { PlayToolsLoader } from "./playStory.ts";
 import type { FrameRenderer, StoryDrawing, StoryIdentity } from "./renderer.ts";
+import { type StoryOutcome } from "./storyContent.ts";
 import type { LoadedBeforeEach, LoadedStory } from "./storyModule.ts";
 /** What the shell can do to a running story. */
 export type StoryControls = {
@@ -32,6 +34,8 @@ export type StoryControls = {
     readonly setMatrix: (matrix: Matrix | undefined) => void;
     /** Mounts the story again, so its play function runs again. */
     readonly playAgain: () => void;
+    /** Runs the play again on a fresh mount, or steps through it: from the start, to its next action, or on to its end. */
+    readonly stepPlay: (command: PlayStepCommand) => void;
     /** Sets whether the story clock runs, and how fast. */
     readonly setClock: (state: ClockState) => void;
     /**
@@ -50,6 +54,8 @@ export type StoryRunOptions = {
     readonly identity: StoryIdentity;
     /** Loads the play tools the project installed, for the first play; none without them. */
     readonly playTools?: PlayToolsLoader;
+    /** Whether a mount runs the play by itself: off (the address's `play=off`), only "run it" does. `true` by default. */
+    readonly playsOnOpen?: boolean;
     /** What the plugins prepare before every mount, ahead of the story's loaders. */
     readonly pluginSetups: readonly LoadedBeforeEach[];
     /** The framework that draws it. */
@@ -65,10 +71,10 @@ export type StoryRunOptions = {
     /** The panel's values as the story takes them (a named value turned back into the value). */
     readonly resolveArgs: (args: PanelArgs) => Readonly<Record<string, unknown>>;
     /**
-     * Called once with the controls, when the story is first drawn and its play function is over (the frame's ready
-     * status waits for it, so no check reads a half-played story).
+     * Called once with the controls and how the story ended, when the story is first drawn, what it loads came and its
+     * play function is over (the frame's status waits for it, so no check reads a half-played or half-loaded story).
      */
-    readonly onControlsReady: (controls: StoryControls) => void;
+    readonly onControlsReady: (controls: StoryControls, outcome: StoryOutcome) => void;
     /** Called on every call of a recorded event, with its arguments. */
     readonly onEvent: (name: string, values: readonly unknown[]) => void;
     /** What the panel can show of values: those it cannot (a function, an object) stay the frame's alone. */
@@ -78,8 +84,10 @@ export type StoryRunOptions = {
      * makes, so the panel shows them.
      */
     readonly onArgsChange: (args: PanelArgs) => void;
-    /** Called with the message when the story throws while it is drawn; the frame shows the error instead. */
-    readonly onError: (message: string) => void;
+    /**
+     * Called with the message and the stack when the story throws while it is drawn; the frame shows the error instead.
+     */
+    readonly onError: (message: string, stack: string | undefined) => void;
     /** Called with the play function's trace after every change. */
     readonly onTrace: (trace: PlayTrace) => void;
 };

package/dist/src/frame/storyRun.js

@@ -12,12 +12,15 @@
  * @module
  */
 import { storyTextOf } from "@forgebook/story-format/texts";
-import { actionNames, mappedArgs } from "../argTypes.js";
+import { UNSET_ARG } from "../messages.js";
+import { actionNames, mappedArgs } from "../storyArgTypes.js";
 import { withStoryTexts } from "../storyTexts.js";
+import { ERROR_MESSAGE_CLASS, ERROR_STACK_CLASS } from "./frameStatus.js";
 import { matrixLayout } from "./matrixLayout.js";
-import { playStory } from "./playStory.js";
+import { heldStepper, runPlay } from "./playStepper.js";
 import { animationsSettled } from "./settle.js";
 import { storyCanvas } from "./storyCanvas.js";
+import { contentBeforePlay, contentOf, outcomeOf } from "./storyContent.js";
 import { prepareStory } from "./storyHooks.js";
 /**
  * The error shown in place of a story that threw: its message and its stack.
@@ -30,12 +33,12 @@ const errorElement = (document, error) => {
     box.className = "forgebook-frame-error";
     box.setAttribute("role", "alert");
     const message = document.createElement("p");
-    message.className = "forgebook-frame-error__message";
+    message.className = ERROR_MESSAGE_CLASS;
     message.textContent = error.message;
     box.append(message);
     if (error.stack !== undefined) {
         const stack = document.createElement("pre");
-        stack.className = "forgebook-frame-error__stack";
+        stack.className = ERROR_STACK_CLASS;
         stack.textContent = error.stack;
         box.append(stack);
     }
@@ -105,6 +108,12 @@ export const runStory = (options) => {
     let shownError;
     let mountCount = 0;
     let hasPlayed = false;
+    // what the next mount does with the play: "run it" asks for one, whatever the switch says
+    let playsNext = options.playsOnOpen !== false;
+    // what the next mount is stepped with, and what the shell's commands reach: each belongs to one mount, so a Replay, a
+    // file's edit or a play gone stale neither pauses unasked nor takes a command meant for the one running
+    let nextStepper;
+    let stepper;
     let prepared = NOT_PREPARED;
     let preparing = Promise.resolve();
     // the story's actions are recorded whatever the shell names: a spy, an `argTypes` action
@@ -169,7 +178,12 @@ export const runStory = (options) => {
         };
         args = { ...story.args, ...ownValues, ...panelValues };
         redraw();
-        options.onArgsChange(options.panelArgsOf(panelValues));
+        // a value the story took away is the panel's "no value": the shell answers with these, over the story's own
+        const unset = Object.keys(panelValues).filter((name) => panelValues[name] === undefined);
+        options.onArgsChange({
+            ...Object.fromEntries(unset.map((name) => [name, UNSET_ARG])),
+            ...options.panelArgsOf(panelValues)
+        });
     };
     const clearError = () => {
         shownError?.remove();
@@ -185,7 +199,7 @@ export const runStory = (options) => {
                 child.hidden = true;
         shownError = errorElement(document, error);
         container.append(shownError);
-        options.onError(error.message);
+        options.onError(error.message, error.stack);
     };
     const unmountAll = () => {
         for (const { story: each } of mounted)
@@ -194,6 +208,18 @@ export const runStory = (options) => {
         clearError();
         container.replaceChildren();
     };
+    // run again or stepped through, a play asked for by name plays whatever the switch says
+    const stepPlay = (command) => {
+        if (command === "next")
+            stepper?.next();
+        else if (command === "continue")
+            stepper?.release();
+        else {
+            playsNext = true;
+            nextStepper = command === "start" ? heldStepper() : undefined;
+            mountStory();
+        }
+    };
     const controls = {
         replay: async () => {
             const mode = story.replay;
@@ -230,7 +256,8 @@ export const runStory = (options) => {
             matrix = next;
             mountStory();
         },
-        playAgain: () => mountStory(),
+        playAgain: () => stepPlay("again"),
+        stepPlay,
         setClock: clock.setState,
         restartClock: () => {
             clock.restart();
@@ -253,19 +280,32 @@ export const runStory = (options) => {
     };
     const mountAlone = () => {
         const count = mountCount;
+        stepper = nextStepper;
+        nextStepper = undefined;
         const canvas = storyCanvas(document, story);
         container.append(canvas);
         const alone = renderer.mount(canvas, drawing({}), showError);
         mounted = [{ story: alone, values: {} }];
-        void alone.drawn.then(async () => {
+        // a play drives the story, not its fallback; one that shows only the fallback has nothing for it to find
+        void contentBeforePlay(alone, story).then(async (loaded) => {
             // a later mount (Replay, the matrix) replaced this one before it was drawn: its play would drive a gone story
             if (count !== mountCount)
                 return;
-            const tools = await playTools();
+            const isStuck = loaded.state === "waiting" || shownError !== undefined;
+            const play = isStuck ? undefined : playOfMount();
+            const tools = play === undefined ? undefined : await playTools();
             if (count !== mountCount || tools instanceof Error)
                 return;
+            const finish = (content) => {
+                // a later mount took over meanwhile: it says how the story ended
+                if (hasPlayed || count !== mountCount)
+                    return;
+                hasPlayed = true;
+                const outcome = outcomeOf(content, shownError !== undefined, story.suspense.timeout);
+                options.onControlsReady(controls, outcome);
+            };
             // a failed play still ends the wait; its rejection reaches the page as an error the tests record
-            void playStory(story.play, {
+            void runPlay(play, {
                 ...options.identity,
                 args: shownArgs(),
                 canvasElement: canvas,
@@ -275,13 +315,22 @@ export const runStory = (options) => {
                 loaded: prepared.loaded,
                 parameters: story.parameters
             }, () => {
-                if (hasPlayed)
-                    return;
-                hasPlayed = true;
-                options.onControlsReady(controls);
-            }, options.onTrace, tools);
+                // what a play did may load something in turn (a tab it opened), which its checks must see too
+                if (play === undefined || loaded.state === "unknown")
+                    finish(loaded);
+                else
+                    void contentOf(alone, story).then(finish);
+            }, options.onTrace, tools, stepper);
         });
     };
+    // what this mount plays: none when the switch keeps the play from running, which the shell is told so it can offer it
+    const playOfMount = () => {
+        const isWanted = playsNext;
+        playsNext = options.playsOnOpen !== false;
+        if (!isWanted && story.play !== undefined)
+            options.onTrace({ status: "off", steps: [] });
+        return isWanted ? story.play : undefined;
+    };
     // the play tools the project installed, loaded for a story with a play; a failure to load them is shown as the
     // story's error
     const playTools = async () => {

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

@@ -0,0 +1,35 @@
+/**
+ * The style sheets of the switches' values (`sheet` on a value): the sheets of the values drawn, placed after the
+ * source's, the switches' in the order they are declared.
+ *
+ * @remarks
+ * Loaded only by a frame of a catalogue that has any (`mountFrame.ts`). A change keeps the old sheet in the document until
+ * the new one has loaded, and says when, so the frame moves the root's attributes at the same moment and the story is
+ * never drawn with neither. The reader's next choice overtakes one still loading: only the last one takes the old
+ * sheets away.
+ *
+ * @module
+ */
+import { type ViewSwitch } from "../switches.ts";
+import type { SheetsChoice } from "../viewState.ts";
+/** The address of each value's sheet, by `<switch id>=<value>`, as the generated frame gives them. */
+export type ValueSheets = Readonly<Record<string, string>>;
+/**
+ * The addresses a view's values draw with, in order; only Styles › Full has them, since Structure and Restyled leave
+ * out a theme's look.
+ *
+ * @param values - the switches' values, the story's fixed ones among them.
+ * @param sheets - the Styles setting.
+ * @param valueSheets - each value's sheet.
+ * @param switches - the catalogue's switches.
+ */
+export declare const valueSheetUrls: (values: Readonly<Record<string, string>>, sheets: SheetsChoice, valueSheets: ValueSheets, switches: readonly ViewSwitch[]) => string[];
+/**
+ * Shows the sheets of a frame's values, from now on after what the document's head holds.
+ *
+ * @param document - the frame's document: the source's sheets are already placed.
+ * @param onFailed - told a sheet that did not load, with what to say. The frame goes on without it, and choosing the value
+ * again tries again.
+ * @returns what shows a list of sheets, and answers once they have settled whether it is still the last one asked.
+ */
+export declare const valueSheetsIn: (document: Document, onFailed: (message: string) => void) => ((urls: readonly string[]) => Promise<boolean>);

package/dist/src/frame/valueSheets.js

@@ -0,0 +1,99 @@
+/**
+ * The style sheets of the switches' values (`sheet` on a value): the sheets of the values drawn, placed after the
+ * source's, the switches' in the order they are declared.
+ *
+ * @remarks
+ * Loaded only by a frame of a catalogue that has any (`mountFrame.ts`). A change keeps the old sheet in the document until
+ * the new one has loaded, and says when, so the frame moves the root's attributes at the same moment and the story is
+ * never drawn with neither. The reader's next choice overtakes one still loading: only the last one takes the old
+ * sheets away.
+ *
+ * @module
+ */
+import { shownSwitches } from "../switches.js";
+/**
+ * The addresses a view's values draw with, in order; only Styles › Full has them, since Structure and Restyled leave
+ * out a theme's look.
+ *
+ * @param values - the switches' values, the story's fixed ones among them.
+ * @param sheets - the Styles setting.
+ * @param valueSheets - each value's sheet.
+ * @param switches - the catalogue's switches.
+ */
+export const valueSheetUrls = (values, sheets, valueSheets, switches) => {
+    if (sheets !== "full")
+        return [];
+    const shown = shownSwitches(values, switches);
+    return switches.flatMap((each) => valueSheets[`${each.id}=${shown[each.id] ?? each.default}`] ?? []);
+};
+/**
+ * Puts sheets back in their order: an overtaken choice of two switches at once can leave a kept sheet on the wrong side of a
+ * new one. A sheet already in place is not touched, since moving a link loads it again.
+ *
+ * @param head - the document's head.
+ * @param end - what the sheets end before.
+ * @param links - the sheets, in order.
+ */
+const keepOrder = (head, end, links) => {
+    let next = end;
+    for (const link of links.toReversed()) {
+        if (link.nextSibling !== next)
+            head.insertBefore(link, next);
+        next = link;
+    }
+};
+/**
+ * Shows the sheets of a frame's values, from now on after what the document's head holds.
+ *
+ * @param document - the frame's document: the source's sheets are already placed.
+ * @param onFailed - told a sheet that did not load, with what to say. The frame goes on without it, and choosing the value
+ * again tries again.
+ * @returns what shows a list of sheets, and answers once they have settled whether it is still the last one asked.
+ */
+export const valueSheetsIn = (document, onFailed) => {
+    const { head } = document;
+    // what keeps the values' sheets together, whatever the frame adds to the head after them
+    const end = document.createComment(" the switches' values' sheets end here ");
+    head.append(end);
+    const placed = new Map();
+    let lastAsked = 0;
+    const place = (url, before) => {
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = url;
+        const isLoaded = new Promise((resolve) => {
+            link.addEventListener("load", () => resolve(true));
+            link.addEventListener("error", () => {
+                // forgotten, so that choosing the value again asks the server again
+                placed.delete(url);
+                link.remove();
+                onFailed(`The style sheet ${url} did not load`);
+                resolve(false);
+            });
+        });
+        head.insertBefore(link, before);
+        return { link, isLoaded };
+    };
+    return async (urls) => {
+        lastAsked += 1;
+        const asked = lastAsked;
+        let before = end;
+        // last to first, each new one before the next: a sheet kept where it is keeps the switches' order
+        for (const url of urls.toReversed()) {
+            const each = placed.get(url) ?? place(url, before);
+            placed.set(url, each);
+            before = each.link;
+        }
+        await Promise.all(urls.map((url) => placed.get(url)?.isLoaded));
+        if (asked !== lastAsked)
+            return false;
+        for (const [url, { link }] of placed) {
+            if (urls.includes(url))
+                continue;
+            link.remove();
+            placed.delete(url);
+        }
+        keepOrder(head, end, urls.flatMap((url) => placed.get(url)?.link ?? []));
+        return true;
+    };
+};

package/dist/src/hotModules.d.ts

@@ -22,6 +22,26 @@ export declare const RENEWED_MODULE_EVENT = "forgebook:module-renewed";
  * by their place in the list, in a `CustomEvent` whose detail is `PreviewsRenewal`.
  */
 export declare const PREVIEWS_EVENT = "forgebook:previews";
+/**
+ * The event an edit of a story file sends when it changes whether the file can be read, and an edit of any other of the
+ * project's scripts when it changes whether it parses: from the dev server to the group's module, which hands it on to
+ * the page in a `CustomEvent` whose detail is `StoryFileRead`, for the shell to name the file at once. The file stays in the list a page read: its frame keeps what it drew, and its fix draws in
+ * place.
+ */
+export declare const STORY_FILE_READ_EVENT = "forgebook:story-file-read";
+/** Whether an edited story file can be read now, or another script parses. */
+export type StoryFileRead = {
+    /** The file, absolute in Vite's form. */
+    readonly file: string;
+    /** Why it cannot, naming it with its line and column when they are known; none when it can. */
+    readonly problem?: string;
+};
+/**
+ * What an event says of an edited story file, when it is that event.
+ *
+ * @param event - the event.
+ */
+export declare const storyFileReadOf: (event: Event) => StoryFileRead | undefined;
 /** The previews an edit renewed: each one's new module, or `undefined` for one it did not change. */
 export type PreviewsRenewal = {
     /** The previews' modules, in the catalogue's order. */

package/dist/src/hotModules.js

@@ -22,6 +22,29 @@ export const RENEWED_MODULE_EVENT = "forgebook:module-renewed";
  * by their place in the list, in a `CustomEvent` whose detail is `PreviewsRenewal`.
  */
 export const PREVIEWS_EVENT = "forgebook:previews";
+/**
+ * The event an edit of a story file sends when it changes whether the file can be read, and an edit of any other of the
+ * project's scripts when it changes whether it parses: from the dev server to the group's module, which hands it on to
+ * the page in a `CustomEvent` whose detail is `StoryFileRead`, for the shell to name the file at once. The file stays in the list a page read: its frame keeps what it drew, and its fix draws in
+ * place.
+ */
+export const STORY_FILE_READ_EVENT = "forgebook:story-file-read";
+/**
+ * What an event says of an edited story file, when it is that event.
+ *
+ * @param event - the event.
+ */
+export const storyFileReadOf = (event) => {
+    if (!(event instanceof CustomEvent))
+        return undefined;
+    const detail = event.detail;
+    if (typeof detail !== "object" || detail === null || !("file" in detail))
+        return undefined;
+    if (typeof detail.file !== "string")
+        return undefined;
+    const problem = "problem" in detail && typeof detail.problem === "string" ? detail.problem : undefined;
+    return { file: detail.file, ...(problem === undefined ? {} : { problem }) };
+};
 /**
  * The previews an event carries, when it is the previews' event.
  *

package/dist/src/jsxCode.d.ts

@@ -1,22 +1,9 @@
-/**
- * The JSX of a story drawn from its args: the component with the values the story and the props panel set, as a
- * developer would write it, for the Code card. The code writer of every framework written in JSX (React, Preact,
- * Solid): each one's `./code` module hands it to the shell.
- *
- * @remarks
- * A text is an attribute in quotes (in braces when it holds a quote), a number or `null` in braces, `true` the bare
- * name, `false` in braces, a named value by its name (`icon={IconFolder}`), a list as an array literal
- * (`options={["weekly", "monthly"]}`); `children` goes between the tags. Only the values that cross from the frame are
- * known (texts, numbers, booleans, `null`, lists of texts and numbers, named values): a function or an element the
- * story passes is left out. Pure.
- *
- * @module
- */
 import type { StoryCodeWriter } from "./frame/renderer.ts";
 /**
  * A component's JSX with these args.
  *
  * @param component - the component's name (`IconTile`).
  * @param args - the values, in the order they are written.
+ * @param written - the args the story file writes as code, each as written; after the values in the order.
  */
 export declare const jsxCode: StoryCodeWriter;