forgebook 0.1.8 → 0.2.0

package/dist/src/frame/mountFrame.js

@@ -15,10 +15,13 @@ import "./frame.css";
 import { storyTextOf } from "@forgebook/story-format/texts";
 import { actionNames, excludedControls, panelArgTypesOf } from "../argTypes.js";
 import { catalogueSettings } from "../catalogue.js";
+import { SAME_ORIGIN } from "../frameOrigins.js";
+import { PREVIEWS_EVENT, previewsRenewalOf, STORY_FILE_EVENT, successionOf } from "../hotModules.js";
 import { shownLanguage } from "../languages.js";
 import { LIVE_ERROR_EVENT } from "../liveErrors.js";
-import { detailOf, isShellMessage, previewValue } from "../messages.js";
+import { detailOf, previewValue } from "../messages.js";
 import { panelArgsOf, storyArgsOf } from "../namedValues.js";
+import { applySafeArea } from "../safeAreaParameter.js";
 import { sourceFiles } from "../sourceFiles.js";
 import { isClockHeldIn } from "../storyClock.js";
 import { fixedViewOf, NOT_FIXED, withFixed } from "../storyGlobals.js";
@@ -27,15 +30,16 @@ import { findStory, storyTree } from "../storyTree.js";
 import { catalogueSwitches } from "../switches.js";
 import { codeGlobalsOf, frameAddress, languageOf, parseView } from "../viewState.js";
 import { checkStory } from "./checkStory.js";
+import { followTouch } from "./followTouch.js";
 import { storyFrameClock } from "./frameClock.js";
-import { STATUS_ATTRIBUTE } from "./frameStatus.js";
+import { FRAME_STARTED_ATTRIBUTE, STATUS_ATTRIBUTE } from "./frameStatus.js";
 import { applyView, loadSheets, viewSheets } from "./frameView.js";
-import { applyTools } from "./measureTools.js";
+import { startPluginFrames } from "./pluginFrames.js";
+import { shellChannel } from "./shellChannel.js";
 import { spillOutline } from "./spillOutline.js";
 import { clearRetry, isStaleModuleError, markRetry, sessionStorageOf } from "./staleModule.js";
-import { mergedPreviews, readPreview, readStory } from "./storyModule.js";
+import { mergedPreviews, readPreview, readStory, startingGlobals } from "./storyModule.js";
 import { runStory } from "./storyRun.js";
-import { followTouch } from "./touchLayer.js";
 /**
  * Tells the dev server about an error, for an agent following them (`forgebook errors`); nothing in a build, which has
  * no connection to it.
@@ -45,11 +49,11 @@ import { followTouch } from "./touchLayer.js";
 const tellDevServer = (report) => {
     import.meta.hot?.send(LIVE_ERROR_EVENT, report);
 };
-/** Tells the shell, which is the parent page on the same origin. */
-const tellShell = (message) => {
-    if (window.parent !== window)
-        window.parent.postMessage(message, window.location.origin);
-};
+// a story that threw is gone from its frame, so a hot update has nothing to update: the fix shows only in a new page
+import.meta.hot?.on("vite:afterUpdate", () => {
+    if (document.documentElement.getAttribute(STATUS_ATTRIBUTE) === "error")
+        window.location.reload();
+});
 /**
  * Does what a message of the shell asks of the rendered story; the view's live part is applied apart, before the story
  * loads.
@@ -58,8 +62,10 @@ const tellShell = (message) => {
  * @param controls - the rendered story's controls.
  * @param storyId - the story's id, for the answers.
  * @param rules - the catalogue's accessibility rules, for a check.
+ * @param axeUrl - the address of axe's script, for a check.
+ * @param tellShell - tells the shell the check's result.
  */
-const answerShell = (message, controls, storyId, rules) => {
+const answerShell = (message, controls, storyId, rules, axeUrl, tellShell) => {
     if (message.type === "forgebook:replay")
         void controls.replay();
     else if (message.type === "forgebook:args")
@@ -75,7 +81,7 @@ const answerShell = (message, controls, storyId, rules) => {
     else if (message.type === "forgebook:clock-restart")
         controls.restartClock();
     else if (message.type === "forgebook:check") {
-        checkStory(document, rules)
+        checkStory(document, rules, axeUrl)
             .then((violations) => tellShell({ type: "forgebook:checked", storyId, violations }))
             .catch((error) => tellShell({
             type: "forgebook:check-error",
@@ -84,6 +90,8 @@ const answerShell = (message, controls, storyId, rules) => {
         }));
     }
 };
+/** The play tools a project installed, for a story that uses them. */
+const playToolsOf = ({ playTools }) => playTools === undefined ? {} : { playTools };
 /**
  * Shows the story the address names in the given element.
  *
@@ -91,17 +99,22 @@ const answerShell = (message, controls, storyId, rules) => {
  * @param config - the sources.
  */
 export const mountFrame = async (container, config) => {
+    // from here the frame shows its own errors: the page's guard against code that fails before it stands down
+    document.documentElement.setAttribute(FRAME_STARTED_ATTRIBUTE, "");
     const params = new URLSearchParams(window.location.search);
     const storyId = params.get("story") ?? "";
     const languages = config.languages ?? [];
     const switches = catalogueSwitches(config.switches, languages, config.lists?.controls);
     const catalogue = catalogueSettings("", switches, config.lists);
-    const preview = mergedPreviews((config.previews ?? []).map(readPreview));
+    // the previews' modules: an edit of one (or of what it imports) brings its successor
+    let previews = config.previews ?? [];
+    let preview = mergedPreviews(previews.map(readPreview));
     const view = parseView(window.location.search, catalogue);
+    const shell = shellChannel(config.frames ?? SAME_ORIGIN, window);
+    const tellShell = shell.tell;
     applyView(document.documentElement, view, catalogue);
-    // the Touch switch's simulation, on before the story's modules load, so a library that reads the device at once
-    // sees touch
-    followTouch(document);
+    // a story drawn edge to edge in a device is told its safe areas, which `env()` cannot give a frame
+    applySafeArea(document.documentElement, window.location.search);
     // what the story fixes of the view, once it is read: every view the frame applies has it over the shell's
     let fixed = NOT_FIXED;
     // set once the story runs: a view the shell sends then changes its language and its globals without a new mount
@@ -109,20 +122,6 @@ export const mountFrame = async (container, config) => {
     // the shell sends the live part of a changed view: applied on the root, and kept in the address so a reload (an
     // edit, a stale module) shows the same view
     const showSpills = spillOutline(document, ".forgebook-frame", (count) => tellShell({ type: "forgebook:spills", storyId, count }));
-    window.addEventListener("message", (event) => {
-        if (event.origin !== window.location.origin || !isShellMessage(event.data))
-            return;
-        if (event.data.type === "forgebook:tools")
-            applyTools(document, event.data.tools, catalogue.gridStep);
-        if (event.data.type === "forgebook:spills")
-            showSpills(event.data.isOn);
-        if (event.data.type !== "forgebook:view")
-            return;
-        applyView(document.documentElement, withFixed(event.data.view, fixed), catalogue);
-        changeShown?.(event.data.view);
-        const address = frameAddress(window.location.pathname, storyId, { ...view, ...event.data.view }, switches);
-        window.history.replaceState(null, "", address);
-    });
     // observed from the start, so the shell sizes the frame to an error as well as to a story
     const reportSize = () => {
         // the body's own height: the root's scroll height never drops below the frame's, so a story could not shrink
@@ -146,52 +145,115 @@ export const mountFrame = async (container, config) => {
         container.replaceChildren(box);
         reportError(message);
     };
+    // the measuring tools load when one is first turned on: the shell tells every frame, most often that none is; what
+    // the shell sent last is what shows once they are there
+    let measuring;
+    let latestTools = [];
+    const showTools = (tools) => {
+        latestTools = tools;
+        if (tools.length === 0 && measuring === undefined)
+            return;
+        measuring ??= import("./measureTools.js");
+        measuring
+            .then(({ applyTools }) => applyTools(document, latestTools, catalogue.gridStep))
+            .catch((error) => reportError(error instanceof Error ? error.message : String(error)));
+    };
+    shell.listen((message) => {
+        if (message.type === "forgebook:tools")
+            showTools(message.tools);
+        if (message.type === "forgebook:spills")
+            showSpills(message.isOn);
+        if (message.type !== "forgebook:view")
+            return;
+        applyView(document.documentElement, withFixed(message.view, fixed), catalogue);
+        changeShown?.(message.view);
+        const address = frameAddress(window.location.pathname, storyId, { ...view, ...message.view }, switches);
+        window.history.replaceState(null, "", address);
+    });
+    // until the story runs, or when it cannot, an edit of a file the frame loaded loads the page again: there is no story
+    // drawn to renew in place, and a story file that failed to load keeps no other way to show its fix
+    const reloadOnEdit = (event) => {
+        event.preventDefault();
+        window.location.reload();
+    };
+    let followStoryFile = reloadOnEdit;
+    let followPreviews = reloadOnEdit;
+    window.addEventListener(STORY_FILE_EVENT, (event) => followStoryFile(event));
+    window.addEventListener(PREVIEWS_EVENT, (event) => followPreviews(event));
     const location = findStory(storyTree(config.sources), storyId);
     const source = config.sources.find((candidate) => candidate.id === location?.source.id);
     const load = location === undefined || source === undefined
         ? undefined
-        : sourceFiles(source).stories[location.component.file];
+        : sourceFiles(source).stories[location.story.file];
     if (location === undefined || source === undefined || load === undefined) {
         fail(`No story "${storyId}"`);
         return;
     }
     try {
+        // the Touch switch's simulation, on before the story's modules load, so a library that reads the device at once
+        // sees touch
+        await followTouch(document, reportError);
         await source.setup?.();
         await preview.setup?.();
         await loadSheets(document, viewSheets(source.sheets, view));
-        const story = readStory(await load(), location.story.exportName, preview);
-        if (typeof story === "string") {
-            fail(story);
+        // the story file's exports: an edit of the file hands them on with its successor's
+        let shownFile = await load();
+        const first = readStory(shownFile, location.story.exportName, preview);
+        if (typeof first === "string") {
+            fail(first);
             return;
         }
+        const plugins = startPluginFrames(config.plugins, storyId, tellShell);
+        let story = first;
         fixed = fixedViewOf(story.globals, story.parameters, catalogue);
         applyView(document.documentElement, withFixed(view, fixed), catalogue);
         let controls;
         const clock = storyFrameClock(story.clockStart, isClockHeldIn(window.location.search));
-        window.addEventListener("message", (event) => {
-            if (event.origin !== window.location.origin || !isShellMessage(event.data))
-                return;
+        shell.listen((message) => {
             if (controls !== undefined)
-                answerShell(event.data, controls, storyId, catalogue.a11y);
+                answerShell(message, controls, storyId, catalogue.a11y, config.axeUrl, tellShell);
         });
-        // the language's texts, and the switches the story reads (the language's provider reads its id among them)
-        const shownFor = (live) => {
+        // the language's texts, and the switches the story reads (the language's provider reads its id among them); a
+        // language the source gives as a loader is loaded as it is shown
+        const shownFor = async (live) => {
             const switchesShown = { switches: { ...live.switches, ...fixed.switches } };
             return {
-                texts: shownTexts(source.texts, shownLanguage(languages, languageOf(switchesShown, switches))),
-                globals: codeGlobalsOf(switchesShown, switches)
+                texts: await shownTexts(source.texts, shownLanguage(languages, languageOf(switchesShown, switches))),
+                globals: { ...startingGlobals(preview, story), ...codeGlobalsOf(switchesShown, switches) }
             };
         };
-        const shown = shownFor(view);
+        const shown = await shownFor(view);
+        // the view the reader chose last: a language that loads slower than the next one chosen is never drawn
+        let shownCount = 0;
         const { texts } = shown;
+        // what the panel shows of the story; told again when an edit of its file changes it
+        const tellReady = () => {
+            // the panel shows a text an arg names as the story shows it, with its key beside it
+            const args = panelArgsOf(withStoryTexts(story.args, storyTextOf(texts)), source.namedValues);
+            tellShell({
+                type: "forgebook:ready",
+                storyId,
+                canReplay: story.replay !== undefined,
+                hasClock: story.clockStart !== undefined,
+                args,
+                textKeys: storyTextKeysOf(story.args),
+                argTypes: panelArgTypesOf(story.argTypes, excludedControls(story.parameters["controls"])),
+                controls: story.controls,
+                actions: actionNames(story.args, story.argTypes),
+                fixed,
+                parameters: Object.keys(story.parameters)
+            });
+        };
         const running = runStory({
             container,
             story,
             identity: { id: storyId, name: location.story.name, title: location.component.title },
-            ...(config.playTools === undefined ? {} : { playTools: config.playTools }),
+            ...playToolsOf(config),
+            pluginSetups: plugins.setups,
             renderer: config.renderer,
             clock,
-            decorators: preview.decorators,
+            // the first of the list is the innermost
+            decorators: [...preview.decorators, ...plugins.decorators],
             ...shown,
             resolveArgs: (args) => storyArgsOf(args, source.namedValues),
             onControlsReady: (next) => {
@@ -201,22 +263,21 @@ export const mountFrame = async (container, config) => {
                 // waiting on the resize observer, which may report after the ready status
                 reportSize();
                 document.documentElement.setAttribute(STATUS_ATTRIBUTE, "ready");
-                // the panel shows a text an arg names as the story shows it, with its key beside it
-                const args = panelArgsOf(withStoryTexts(story.args, storyTextOf(texts)), source.namedValues);
-                const textKeys = storyTextKeysOf(story.args);
-                tellShell({
-                    type: "forgebook:ready",
-                    storyId,
-                    canReplay: story.replay !== undefined,
-                    hasClock: story.clockStart !== undefined,
-                    args,
-                    textKeys,
-                    argTypes: panelArgTypesOf(story.argTypes, excludedControls(story.parameters["controls"])),
-                    controls: story.controls,
-                    actions: actionNames(story.args, story.argTypes),
-                    fixed
-                });
-                changeShown = (live) => running.setShown(shownFor(live));
+                tellReady();
+                changeShown = (live) => {
+                    shownCount += 1;
+                    const count = shownCount;
+                    shownFor(live)
+                        .then((next) => {
+                        if (count === shownCount)
+                            running.setShown(next);
+                    })
+                        .catch((error) => {
+                        // a language another choice replaced meanwhile is no longer the frame's concern
+                        if (count === shownCount)
+                            reportError(error instanceof Error ? error.message : String(error));
+                    });
+                };
             },
             onError: reportError,
             onTrace: (trace) => {
@@ -235,8 +296,47 @@ export const mountFrame = async (container, config) => {
                 name,
                 values: values.map(previewValue),
                 details: values.map(detailOf)
-            })
+            }),
+            panelArgsOf: (values) => panelArgsOf(values, source.namedValues),
+            onArgsChange: (args) => tellShell({ type: "forgebook:story-args", storyId, args })
         });
+        // an edit of the story file, or of a file it re-exports stories from, draws the story anew in place: the reader keeps
+        // what they did in it. A story the edit took away leaves nothing to draw in place: the page loads again
+        followStoryFile = (event) => {
+            const succession = successionOf(event);
+            if (succession === undefined || succession.previous !== shownFile)
+                return;
+            event.preventDefault();
+            shownFile = succession.next;
+            const next = readStory(succession.next, location.story.exportName, preview);
+            if (typeof next === "string") {
+                window.location.reload();
+                return;
+            }
+            story = next;
+            running.setStory(next);
+            if (controls !== undefined)
+                tellReady();
+        };
+        // an edit of a preview, or of a component it imports through a library's index, draws the story anew with the new
+        // previews; the set-ups they run already ran, and stay as they were
+        followPreviews = (event) => {
+            const renewal = previewsRenewalOf(event);
+            // the entry sends one module, or none, for each of its previews
+            if (renewal === undefined || renewal.next.length !== previews.length)
+                return;
+            previews = previews.map((module, index) => renewal.next[index] ?? module);
+            preview = mergedPreviews(previews.map(readPreview));
+            const next = readStory(shownFile, location.story.exportName, preview);
+            if (typeof next === "string") {
+                window.location.reload();
+                return;
+            }
+            story = next;
+            running.setStory(next, [...preview.decorators, ...plugins.decorators]);
+            if (controls !== undefined)
+                tellReady();
+        };
         // the shell opens another story by loading another page: the set-ups' cleanups run as this one goes (a page kept
         // for the back button keeps its story)
         window.addEventListener("pagehide", (event) => {
@@ -254,4 +354,3 @@ export const mountFrame = async (container, config) => {
         fail(message);
     }
 };
-//# sourceMappingURL=mountFrame.js.map

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

@@ -37,4 +37,3 @@ export type PlayToolsLoader = () => Promise<PlayTools>;
  * @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>;
-//# sourceMappingURL=playStory.d.ts.map

package/dist/src/frame/playStory.js

@@ -52,4 +52,3 @@ export const playStory = async (play, context, onPlayed, onTrace = () => undefin
         onPlayed();
     }
 };
-//# sourceMappingURL=playStory.js.map

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

@@ -0,0 +1,31 @@
+/**
+ * The plugins' frame modules in a story's frame: each made once with what reaches its tab, and what they run around the
+ * story, gathered.
+ *
+ * @module
+ */
+import type { FrameMessage } from "../messages.ts";
+import type { CreatePluginFrame } from "../plugin.ts";
+import type { LoadedBeforeEach, LoadedDecorator } from "./storyModule.ts";
+/** A plugin with a frame module, as the generated frame hands it over. */
+export type FramePlugin = {
+    /** The plugin's id. */
+    readonly id: string;
+    /** What its frame module exports as `frame`. */
+    readonly create: CreatePluginFrame;
+};
+/** What the plugins run around a story. */
+export type PluginFrames = {
+    /** Their decorators, in the order of `plugins`. */
+    readonly decorators: readonly LoadedDecorator[];
+    /** What they prepare before every mount, in the order of `plugins`. */
+    readonly setups: readonly LoadedBeforeEach[];
+};
+/**
+ * Makes the plugins' frame modules.
+ *
+ * @param plugins - the plugins with one; none when the catalogue lists none.
+ * @param storyId - the frame's story.
+ * @param tell - tells the shell.
+ */
+export declare const startPluginFrames: (plugins: readonly FramePlugin[] | undefined, storyId: string, tell: (message: FrameMessage) => void) => PluginFrames;

package/dist/src/frame/pluginFrames.js

@@ -0,0 +1,23 @@
+/**
+ * Makes the plugins' frame modules.
+ *
+ * @param plugins - the plugins with one; none when the catalogue lists none.
+ * @param storyId - the frame's story.
+ * @param tell - tells the shell.
+ */
+export const startPluginFrames = (plugins, storyId, tell) => {
+    const frames = (plugins ?? []).map((plugin) => plugin.create({
+        report: (value, options = {}) => tell({
+            type: "forgebook:plugin",
+            storyId,
+            plugin: plugin.id,
+            value,
+            hint: options.hint ?? null,
+            tab: options.tab ?? null
+        })
+    }));
+    return {
+        decorators: frames.flatMap((frame) => frame.decorators ?? []),
+        setups: frames.flatMap((frame) => (frame.prepare === undefined ? [] : [frame.prepare]))
+    };
+};

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

@@ -3,21 +3,31 @@
  * other args and takes it away, and how the shell writes a story drawn from its args as code.
  *
  * @remarks
- * The frame owns everything a framework does not need to know: the address and the view, the messages with the
- * shell, the style sheets, the play function, Replay, the matrix's layout, the story clock and the error shown in
- * place of a story. A framework package (`@forgebook/react`) implements this type and hands it to the frame; another
- * framework implements the same type. A story's decorators, providers and error capture are the framework's, since
- * they return or catch the framework's own output.
+ * The frame owns everything a framework does not need to know: the address and the view, the messages with the shell,
+ * the style sheets, the play function, Replay, the matrix's layout, the story clock and the error shown in place of a
+ * story. A framework package (`@forgebook/react`) implements `StoryRenderer` and hands the frame its drawing part
+ * (`FrameRenderer`); another framework implements the same types. A story's decorators, providers and error capture are
+ * the framework's, since they return or catch the framework's own output.
  *
  * @module
  */
 import type { StoryClock } from "@forgebook/story-format/clock";
 import type { StepFunction, StoryContext } from "@forgebook/story-format/csf";
-import type { StoryTextTable } from "@forgebook/story-format/texts";
+import { type StoryTextTable } from "@forgebook/story-format/texts";
 import type { PanelArgs } from "../messages.ts";
 import type { LoadedArgs, LoadedDecorator, LoadedStory } from "./storyModule.ts";
 /** Which story is drawn: its id, its name and its file's title, as its context gives them. */
 export type StoryIdentity = Pick<StoryContext<LoadedArgs>, "id" | "name" | "title">;
+/**
+ * A change a story makes to its own args while it is drawn (Storybook's `useArgs`): the names reset to the story's
+ * own values first, then the values set.
+ */
+export type ArgsChange = {
+    /** The names whose values go back to the story's own, or every name. */
+    readonly reset: readonly string[] | "all";
+    /** The values set, by name. */
+    readonly set: Readonly<Record<string, unknown>>;
+};
 /** One story to draw, as the frame hands it to the framework. */
 export type StoryDrawing = {
     /** Which story it is. */
@@ -39,6 +49,16 @@ export type StoryDrawing = {
     readonly globals: Readonly<Record<string, string>>;
     /** What the story's loaders returned: its `context.loaded`. */
     readonly loaded: Readonly<Record<string, unknown>>;
+    /**
+     * Lists a call among the story's events, beside its args' handlers: a call a framework's mock receives (a router's
+     * `push`), by name, with what it was called with. None outside a catalogue (a test's server render).
+     */
+    readonly onEvent?: (name: string, values: readonly unknown[]) => void;
+    /**
+     * Changes the story's args from its own code, as the panel would: the story is drawn again with them and the panel
+     * shows them. None where nothing takes them (a test's server render): a change there changes nothing.
+     */
+    readonly changeArgs?: (change: ArgsChange) => void;
 };
 /** What the frame keeps of a story drawn in a canvas. */
 export type MountedStory = {
@@ -55,22 +75,32 @@ export type MountedStory = {
     /** Takes the story away from its canvas. */
     readonly unmount: () => void;
 };
-/** A framework, as the frame uses it. */
-export type StoryRenderer = {
+/**
+ * A framework, as the frame uses it: it only draws. The frame takes this rather than a whole `StoryRenderer`, so a
+ * framework's frame page can leave its server renderer out: a static catalogue would ship it (some 200 kB for React's)
+ * and a first start would pre-bundle it, for a page that never runs it.
+ */
+export type FrameRenderer = {
     /**
      * Draws a story in a canvas the frame owns.
      *
      * @param canvas - the element the story is drawn in.
      * @param drawing - the story, its args, texts, clock and language.
-     * @param onError - called with the error when the story throws while it is drawn; the frame shows it instead.
+     * @param onError - called with the error when the story throws while it is drawn; the frame shows it instead, until
+     *   the next `update`. Only the latest drawing's error is reported: one of a drawing an `update` replaced while it was
+     *   under way would stand over the story drawn after it.
      */
     readonly mount: (canvas: HTMLElement, drawing: StoryDrawing, onError: (error: Error) => void) => MountedStory;
+};
+/** A framework, as the frame draws with it and the generated server tests render with it. */
+export type StoryRenderer = FrameRenderer & {
     /**
-     * The story drawn as HTML on the server, for the generated server tests; throws when the story throws.
+     * The story drawn as HTML on the server, for the generated server tests; throws, or rejects, when the story throws.
+     * A framework whose server render is asynchronous returns a promise (Vue's waits for what `setup` awaits).
      *
      * @param drawing - the story, its args, texts, clock and language.
      */
-    readonly renderToString: (drawing: StoryDrawing) => string;
+    readonly renderToString: (drawing: StoryDrawing) => Promise<string> | string;
 };
 /**
  * Writes a story drawn from its args as the framework's code, for the Code tab and Show code (`<Button tone="danger" />`
@@ -82,4 +112,12 @@ export type StoryRenderer = {
 export type StoryCodeWriter = (component: string, args: PanelArgs) => string;
 /** 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;
-//# sourceMappingURL=renderer.d.ts.map
+/**
+ * What a render and a decorator receive.
+ *
+ * @param drawing - the story's texts, clock and switches' values.
+ * @param args - the args they read: a framework may hand reactive ones.
+ * @param canvasOf - the element the story is drawn in, read only when a story asks for it: on the server there is
+ *   none, and a story that reads it there fails as it would in a page rendered on the server.
+ */
+export declare const storyContextOf: (drawing: StoryDrawing, args: LoadedArgs, canvasOf: () => HTMLElement) => StoryContext<LoadedArgs>;

package/dist/src/frame/renderer.js

@@ -3,16 +3,37 @@
  * other args and takes it away, and how the shell writes a story drawn from its args as code.
  *
  * @remarks
- * The frame owns everything a framework does not need to know: the address and the view, the messages with the
- * shell, the style sheets, the play function, Replay, the matrix's layout, the story clock and the error shown in
- * place of a story. A framework package (`@forgebook/react`) implements this type and hands it to the frame; another
- * framework implements the same type. A story's decorators, providers and error capture are the framework's, since
- * they return or catch the framework's own output.
+ * The frame owns everything a framework does not need to know: the address and the view, the messages with the shell,
+ * the style sheets, the play function, Replay, the matrix's layout, the story clock and the error shown in place of a
+ * story. A framework package (`@forgebook/react`) implements `StoryRenderer` and hands the frame its drawing part
+ * (`FrameRenderer`); another framework implements the same types. A story's decorators, providers and error capture are
+ * the framework's, since they return or catch the framework's own output.
  *
  * @module
  */
+import { storyTextOf } from "@forgebook/story-format/texts";
 /** 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();
 };
-//# sourceMappingURL=renderer.js.map
+/**
+ * What a render and a decorator receive.
+ *
+ * @param drawing - the story's texts, clock and switches' values.
+ * @param args - the args they read: a framework may hand reactive ones.
+ * @param canvasOf - the element the story is drawn in, read only when a story asks for it: on the server there is
+ *   none, and a story that reads it there fails as it would in a page rendered on the server.
+ */
+export const storyContextOf = (drawing, args, canvasOf) => ({
+    args,
+    step: untracedStep,
+    text: storyTextOf(drawing.texts),
+    clock: drawing.clock,
+    globals: drawing.globals,
+    loaded: drawing.loaded,
+    ...drawing.identity,
+    parameters: drawing.story.parameters,
+    get canvasElement() {
+        return canvasOf();
+    }
+});

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

@@ -21,4 +21,3 @@ export declare const endingAnimations: <TAnimation extends SettlingAnimation>(an
  * @param document - the frame's document.
  */
 export declare const animationsSettled: (document: Document) => Promise<void>;
-//# sourceMappingURL=settle.d.ts.map

package/dist/src/frame/settle.js

@@ -22,4 +22,3 @@ export const animationsSettled = async (document) => {
     await new Promise((resolve) => requestAnimationFrame(resolve));
     await Promise.allSettled(endingAnimations(document.getAnimations()).map((animation) => animation.finished));
 };
-//# sourceMappingURL=settle.js.map

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

@@ -0,0 +1,47 @@
+/**
+ * A frame's side of the messages with the shell: it tells only the catalogue's origin, and hears only its parent page
+ * on that origin.
+ *
+ * @remarks
+ * The frame works out the catalogue's origin from the placement and its own address, never from its address's query:
+ * a page that framed a story could otherwise name itself the catalogue and send the story values (a prop's `href`) no
+ * panel would set. A frame opened alone, with no parent, tells nobody.
+ *
+ * @module
+ */
+import { type FramesPlacement, type PageLocation } from "../frameOrigins.ts";
+import { type FrameMessage, type ShellMessage } from "../messages.ts";
+/** A message's event, as the frame reads it. */
+export type ShellEvent = {
+    /** The sender's origin. */
+    readonly origin: string;
+    /** The sender's window. */
+    readonly source: unknown;
+    /** The message. */
+    readonly data: unknown;
+};
+/** What the channel uses of the frame's window. */
+export type FrameWindow = {
+    /** The frame's address. */
+    readonly location: PageLocation;
+    /** The page that holds the frame; the frame itself when it is opened alone. */
+    readonly parent: {
+        readonly postMessage: (message: unknown, targetOrigin: string) => void;
+    };
+    /** Listens to the messages the frame receives. */
+    readonly addEventListener: (type: "message", listener: (event: ShellEvent) => void) => void;
+};
+/** How a frame talks with its shell. */
+export type ShellChannel = {
+    /** Tells the shell. */
+    readonly tell: (message: FrameMessage) => void;
+    /** Hears the shell: each message the parent page sends from the catalogue's origin. */
+    readonly listen: (onMessage: (message: ShellMessage) => void) => void;
+};
+/**
+ * The frame's channel with its shell.
+ *
+ * @param placement - where the frames run.
+ * @param frame - the frame's window.
+ */
+export declare const shellChannel: (placement: FramesPlacement, frame: FrameWindow) => ShellChannel;