forgebook 0.3.3 → 0.4.1

package/dist/src/frame/mountFrame.js

@@ -5,7 +5,7 @@
  * @remarks
  * One document per story: the style sheets of the Styles setting, the switches on the root and anything the
  * story mounts on `body` stay in this document. The tests open the same address and wait for `data-forgebook-status`
- * on the root (`ready` or `error`), never for a delay. A Live story's clock runs from its start, or stays held there when
+ * on the root (`ready`, `error` or `pending`), never for a delay. A Live story's clock runs from its start, or stays held there when
  * the address says so (`clock=held`, what the tests open). The framework is the renderer the framework package
  * passes (`renderer.ts`); nothing here depends on one.
  *
@@ -13,28 +13,32 @@
  */
 import "./frame.css";
 import { storyTextOf } from "@forgebook/story-format/texts";
-import { actionNames, excludedControls, panelArgTypesOf } from "../argTypes.js";
+import { bundlerErrorLines } from "../bundlerErrors.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, previewValue } from "../messages.js";
-import { panelArgsOf, storyArgsOf } from "../namedValues.js";
+import { isMappedStackAnswer, LIVE_ERROR_EVENT, MAPPED_STACK_EVENT } from "../liveErrors.js";
 import { applySafeArea } from "../safeAreaParameter.js";
 import { sourceFiles } from "../sourceFiles.js";
+import { actionNames, excludedControls, panelArgTypesOf } from "../storyArgTypes.js";
 import { isClockHeldIn } from "../storyClock.js";
 import { fixedViewOf, NOT_FIXED, withFixed } from "../storyGlobals.js";
 import { shownTexts, storyTextKeysOf, withStoryTexts } from "../storyTexts.js";
 import { findStory, storyTree } from "../storyTree.js";
 import { catalogueSwitches } from "../switches.js";
 import { codeGlobalsOf, frameAddress, isSameLiveView, languageOf, liveView, parseView } from "../viewState.js";
+import { detailOf, previewValue } from "./callValues.js";
+import { followCanvasScheme } from "./canvasScheme.js";
 import { followTouch } from "./followTouch.js";
 import { storyFrameClock } from "./frameClock.js";
-import { FRAME_STARTED_ATTRIBUTE, STATUS_ATTRIBUTE } from "./frameStatus.js";
+import { ERROR_MESSAGE_CLASS, ERROR_STACK_CLASS, FRAME_STARTED_ATTRIBUTE, NOT_AWAITED_ATTRIBUTE, PENDING_REASON_ATTRIBUTE, STATUS_ATTRIBUTE } from "./frameStatus.js";
 import { applyView, loadSheets, viewSheets } from "./frameView.js";
+import { panelControls } from "./panelControls.js";
+import { panelArgsOf, storyArgsOf } from "./panelValues.js";
 import { startPluginFrames } from "./pluginFrames.js";
 import { shellChannel } from "./shellChannel.js";
+import { checkForShell } from "./shellCheck.js";
 import { spillOutline } from "./spillOutline.js";
 import { clearRetry, isStaleModuleError, markRetry, sessionStorageOf } from "./staleModule.js";
 import { mergedPreviews, readPreview, readStory, startingGlobals } from "./storyModule.js";
@@ -48,54 +52,125 @@ import { runStory } from "./storyRun.js";
 const tellDevServer = (report) => {
     import.meta.hot?.send(LIVE_ERROR_EVENT, report);
 };
-// 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
+// the browser writes a stack in the lines of the code Vite served, and the dev server answers with the lines as written
+import.meta.hot?.on(MAPPED_STACK_EVENT, (answer) => {
+    if (!isMappedStackAnswer(answer))
+        return;
+    for (const shown of document.querySelectorAll(`.${ERROR_STACK_CLASS}`))
+        if (shown.textContent === answer.sent)
+            shown.textContent = answer.stack;
+});
+// 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; a
+// story the frame gave up on keeps saying so until a new page waits for it again
 import.meta.hot?.on("vite:afterUpdate", () => {
-    if (document.documentElement.getAttribute(STATUS_ATTRIBUTE) === "error")
+    const status = document.documentElement.getAttribute(STATUS_ATTRIBUTE);
+    if (status === "error" || status === "pending")
         window.location.reload();
 });
+/**
+ * Why the dev server last failed to serve a module, and what to do when it says so: of a module it failed to serve, a
+ * browser says only that the import failed, and the reason reaches the page on the dev server's own channel.
+ */
+let servedError;
+let followServedError;
+import.meta.hot?.on("vite:error", ({ err }) => {
+    // the first since this page loaded: what its own import asked for, not what another frame's asked for later
+    servedError ??= bundlerErrorLines(err.message, err)[0];
+    followServedError?.();
+    followServedError = undefined;
+});
+/**
+ * What shows the sheets of a frame's values; none for a catalogue with none, which so loads no code for them.
+ *
+ * @param valueSheets - each value's sheet, when the catalogue has any.
+ * @param sheets - the frame's Styles setting.
+ * @param switches - the catalogue's switches.
+ * @param onFailed - told a sheet that did not load: the story is drawn without it.
+ */
+const valueSheetsShower = async (valueSheets, sheets, switches, onFailed) => {
+    if (valueSheets === undefined)
+        return undefined;
+    const { valueSheetUrls, valueSheetsIn } = await import("./valueSheets.js");
+    const show = valueSheetsIn(document, onFailed);
+    return (values) => show(valueSheetUrls(values, sheets, valueSheets, switches));
+};
+/**
+ * Fails a frame whose story did not load, with the dev server's reason when the import only says it failed, as soon as
+ * the reason arrives: it may come after the failed import.
+ *
+ * @param message - the error's message.
+ * @param fail - shows a reason in the frame.
+ */
+const failedToLoad = (message, fail) => {
+    if (isStaleModuleError(message))
+        followServedError = () => fail(servedError ?? message);
+    fail(isStaleModuleError(message) ? (servedError ?? message) : message);
+};
 /**
  * Does what a message of the shell asks of the rendered story; the view's live part is applied apart, before the story
- * loads.
+ * loads, and so are the panel's values (`panelControls.ts`).
  *
  * @param message - the message.
  * @param controls - the rendered story's controls.
  * @param storyId - the story's id, for the answers.
+ * @param pendingReason - why the story was not seen in its final state, if so: a check of what it shows now would pass
+ *   on a fallback, so it answers this instead.
  * @param rules - the catalogue's accessibility rules, for a check; none when it checks no accessibility.
  * @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, axeUrl, tellShell) => {
+const answerShell = (message, controls, storyId, pendingReason, rules, axeUrl, tellShell) => {
     if (message.type === "forgebook:replay")
         void controls.replay();
-    else if (message.type === "forgebook:args")
-        controls.setPanelArgs(message.args);
     else if (message.type === "forgebook:events")
         controls.setEvents(message.names);
     else if (message.type === "forgebook:matrix")
         controls.setMatrix(message.matrix ?? undefined);
-    else if (message.type === "forgebook:play-again")
-        controls.playAgain();
+    else if (message.type === "forgebook:play-step")
+        controls.stepPlay(message.command);
     else if (message.type === "forgebook:clock")
         controls.setClock(message.state);
     else if (message.type === "forgebook:clock-restart")
         controls.restartClock();
-    else if (message.type === "forgebook:check") {
-        // 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 checked = rules === undefined
-            ? Promise.reject(new Error("The catalogue checks no accessibility (a11y: false)"))
-            : 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)
-        }));
-    }
+    else if (message.type === "forgebook:check")
+        checkForShell(storyId, pendingReason, rules, axeUrl, tellShell);
 };
-/** The play tools a project installed, for a story that uses them. */
-const playToolsOf = ({ playTools }) => playTools === undefined ? {} : { playTools };
+/**
+ * Says on the page that the frame gave up on what the story loads: a person looking at the story, or at its picture,
+ * must not take the fallback for the story. Out of the story's own element, so the story is laid out as it was.
+ *
+ * @param reason - why.
+ */
+const showPending = (reason) => {
+    const notice = document.createElement("p");
+    notice.className = "forgebook-frame-pending";
+    notice.setAttribute("role", "status");
+    notice.textContent = `Not verified: ${reason}`;
+    document.body.prepend(notice);
+};
+/**
+ * Says how a story ended on the frame's root and on its page.
+ *
+ * @param outcome - how it ended; an error that came during the wait stands, and this leaves it there.
+ * @param storyId - the story's id, for the dev server.
+ * @param isNotAwaited - whether the story said not to wait for what it loads, which a check reports.
+ * @returns why it was not seen in its final state, if so.
+ */
+const showOutcome = (outcome, storyId, isNotAwaited) => {
+    if (outcome.status === "error")
+        return undefined;
+    if (isNotAwaited)
+        document.documentElement.setAttribute(NOT_AWAITED_ATTRIBUTE, "");
+    document.documentElement.setAttribute(STATUS_ATTRIBUTE, outcome.status);
+    if (outcome.status === "ready")
+        return undefined;
+    document.documentElement.setAttribute(PENDING_REASON_ATTRIBUTE, outcome.reason);
+    showPending(outcome.reason);
+    tellDevServer({ kind: "render", storyId, view: window.location.search, message: outcome.reason });
+    return outcome.reason;
+};
+/** The play tools a project installed, and whether the frame's address lets its story play when it opens. */
+const playOptions = ({ playTools }, playsOnOpen) => playTools === undefined ? { playsOnOpen } : { playTools, playsOnOpen };
 /**
  * Shows the story the address names in the given element.
  *
@@ -113,7 +188,9 @@ export const mountFrame = async (container, config) => {
     // 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);
+    // a frame runs its play unless its own address says otherwise, whatever the catalogue's readers start with: tests and
+    // tools open frames with no word, and a new address written below must not add one
+    const view = parseView(window.location.search, { ...catalogue, readerPlay: "on" });
     const shell = shellChannel(config.frames ?? SAME_ORIGIN, window);
     const tellShell = shell.tell;
     applyView(document.documentElement, view, catalogue);
@@ -136,17 +213,19 @@ export const mountFrame = async (container, config) => {
         tellShell({ type: "forgebook:size", storyId, height });
     };
     new ResizeObserver(reportSize).observe(document.body);
-    const reportError = (message) => {
+    const reportScheme = followCanvasScheme(document, window, storyId, tellShell);
+    const reportError = (message, stack) => {
         document.documentElement.setAttribute(STATUS_ATTRIBUTE, "error");
         tellShell({ type: "forgebook:error", storyId, message });
-        tellDevServer({ kind: "render", storyId, view: window.location.search, message });
+        const report = { kind: "render", storyId, view: window.location.search, message };
+        tellDevServer(stack === undefined ? report : { ...report, stack });
     };
     const fail = (message) => {
         const box = document.createElement("div");
         box.className = "forgebook-frame-error";
         box.setAttribute("role", "alert");
         const text = document.createElement("p");
-        text.className = "forgebook-frame-error__message";
+        text.className = ERROR_MESSAGE_CLASS;
         text.textContent = message;
         box.append(text);
         container.replaceChildren(box);
@@ -165,6 +244,11 @@ export const mountFrame = async (container, config) => {
             .then(({ applyTools }) => applyTools(document, latestTools, catalogue.gridStep))
             .catch((error) => reportError(error instanceof Error ? error.message : String(error)));
     };
+    // what shows the sheets of the values drawn, for a catalogue with any; set once the source's are placed
+    let showValueSheets;
+    // the view asked for while its sheets load: the next message is compared with it, or going back would stop short of
+    // overtaking it, and the sheets would then draw a view the reader already left
+    let askedView;
     shell.listen((message) => {
         if (message.type === "forgebook:tools")
             showTools(message.tools);
@@ -174,15 +258,29 @@ export const mountFrame = async (container, config) => {
             return;
         const shown = withFixed(message.view, fixed);
         // the same view again draws nothing: a story's state, and the time its draw takes, are not the shell's to spend
-        if (changeShown !== undefined &&
-            shownView !== undefined &&
-            isSameLiveView(withFixed(shownView, fixed), shown))
+        const latest = askedView ?? shownView;
+        if (changeShown !== undefined && latest !== undefined && isSameLiveView(withFixed(latest, fixed), shown))
             return;
-        applyView(document.documentElement, shown, catalogue);
-        changeShown?.(message.view);
-        shownView = changeShown === undefined ? undefined : message.view;
-        const address = frameAddress(window.location.pathname, storyId, { ...view, ...message.view }, switches);
-        window.history.replaceState(null, "", address);
+        askedView = message.view;
+        const showLive = () => {
+            applyView(document.documentElement, shown, catalogue);
+            changeShown?.(message.view);
+            shownView = changeShown === undefined ? undefined : message.view;
+            askedView = undefined;
+            const address = frameAddress(window.location.pathname, storyId, { ...view, ...message.view }, switches);
+            window.history.replaceState(null, "", address);
+        };
+        // the root changes with the sheet that draws it; a later view overtakes this one
+        if (showValueSheets === undefined)
+            showLive();
+        else {
+            showValueSheets(shown.switches)
+                .then((isLast) => {
+                if (isLast)
+                    showLive();
+            })
+                .catch((error) => reportError(error instanceof Error ? error.message : String(error)));
+        }
     });
     // 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
@@ -210,6 +308,8 @@ export const mountFrame = async (container, config) => {
         await source.setup?.();
         await preview.setup?.();
         await loadSheets(document, viewSheets(source.sheets, view));
+        showValueSheets = await valueSheetsShower(config.valueSheets, view.sheets, switches, reportError);
+        await showValueSheets?.(view.switches);
         // 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);
@@ -220,13 +320,15 @@ export const mountFrame = async (container, config) => {
         const plugins = startPluginFrames(config.plugins, storyId, tellShell);
         let story = first;
         fixed = fixedViewOf(story.globals, story.parameters, catalogue);
+        await showValueSheets?.(withFixed(view, fixed).switches);
         applyView(document.documentElement, withFixed(view, fixed), catalogue);
         let controls;
+        // why the story was not seen in its final state: a check of what it shows would pass on a fallback
+        let pendingReason;
         const clock = storyFrameClock(story.clockStart, isClockHeldIn(window.location.search));
-        shell.listen((message) => {
-            if (controls !== undefined)
-                answerShell(message, controls, storyId, catalogue.a11y, config.axeUrl, tellShell);
-        });
+        // the controls with a frame module, which turn the panel's values first; their docs name those given by type
+        const typed = panelControls(config.argControls, source, location.story.file, reportError);
+        shell.listen((message) => typed.take(message, { story, controls, tellReady }, (drawn) => answerShell(message, drawn, storyId, pendingReason, catalogue.a11y, config.axeUrl, tellShell)));
         // 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) => {
@@ -249,7 +351,7 @@ export const mountFrame = async (container, config) => {
                 storyId,
                 canReplay: story.replay !== undefined,
                 hasClock: story.clockStart !== undefined,
-                args,
+                args: typed.withOwn(args),
                 textKeys: storyTextKeysOf(story.args),
                 argTypes: panelArgTypesOf(story.argTypes, excludedControls(story.parameters["controls"])),
                 controls: story.controls,
@@ -262,22 +364,25 @@ export const mountFrame = async (container, config) => {
             container,
             story,
             identity: { id: storyId, name: location.story.name, title: location.component.title },
-            ...playToolsOf(config),
+            ...playOptions(config, view.play === "on"),
             pluginSetups: plugins.setups,
             renderer: config.renderer,
             clock,
             // the first of the list is the innermost
             decorators: [...preview.decorators, ...plugins.decorators],
             ...shown,
-            resolveArgs: (args) => storyArgsOf(args, source.namedValues),
-            onControlsReady: (next) => {
+            resolveArgs: (args) => typed.storyArgs(storyArgsOf(args, source.namedValues)),
+            onControlsReady: (next, outcome) => {
                 controls = next;
                 clearRetry(sessionStorageOf(window), window.location.href);
                 // the height first: the shell sizes the frame to the drawn story before anything reads it as ready, instead of
                 // waiting on the resize observer, which may report after the ready status
                 reportSize();
-                document.documentElement.setAttribute(STATUS_ATTRIBUTE, "ready");
-                tellReady();
+                reportScheme();
+                pendingReason = showOutcome(outcome, storyId, story.suspense.isExpected);
+                // the shell keeps an error it was told, and would read this as the story being fine again
+                if (outcome.status !== "error")
+                    tellReady();
                 changeShown = (live) => {
                     shownCount += 1;
                     const count = shownCount;
@@ -296,7 +401,7 @@ export const mountFrame = async (container, config) => {
                     });
                 };
             },
-            onError: reportError,
+            onError: (message, stack) => reportError(message, stack),
             onTrace: (trace) => {
                 tellShell({ type: "forgebook:play", storyId, trace });
                 if (trace.status === "failed")
@@ -314,7 +419,7 @@ export const mountFrame = async (container, config) => {
                 values: values.map(previewValue),
                 details: values.map(detailOf)
             }),
-            panelArgsOf: (values) => panelArgsOf(values, source.namedValues),
+            panelArgsOf: (values) => typed.panelArgs(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
@@ -370,6 +475,6 @@ export const mountFrame = async (container, config) => {
             window.location.reload();
             return;
         }
-        fail(message);
+        failedToLoad(message, fail);
     }
 };

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

@@ -0,0 +1,67 @@
+/**
+ * What a frame keeps of the custom controls with a frame module: the panel's latest values as their modules turned them,
+ * and the story's own values they named. The turning itself (`controlValues.ts`) loads when the shell first gives values.
+ *
+ * @remarks
+ * Turning values takes a load, so the shell's other messages wait for the values before them: a Replay or a matrix
+ * right after a change draws the changed values, as without any frame module.
+ *
+ * @module
+ */
+import type { StorySource } from "@forgebook/story-format/source";
+import type { PanelArgs, ShellMessage } from "../messages.ts";
+import type { ControlStory } from "./controlValues.ts";
+import type { StoryControls } from "./storyRun.ts";
+/** The custom controls' frame modules, by control: how to load each. */
+export type ControlFrameLoaders = Readonly<Record<string, () => Promise<unknown>>>;
+/** The story a message is for, as `take` reads it. */
+export type TakenStory<TControls> = {
+    /** The story as it is now. */
+    readonly story: Omit<ControlStory, "loadDocs">;
+    /** Its controls once drawn; none before, when nothing is answered. */
+    readonly controls: TControls | undefined;
+    /** Tells the shell the story's own values again. */
+    readonly tellReady: () => void;
+};
+/** A frame's custom controls with a frame module; with none, it hands the shell's messages on as they come. */
+export type PanelControls = {
+    /**
+     * Answers a message of the shell: the panel's values turned first, then given to the story; any other message after
+     * the values before it. A later change of values overtakes one still turning.
+     *
+     * @param message - the message.
+     * @param story - the story as it is now, and its controls once drawn; none before, when nothing is answered.
+     * @param answer - answers any other message.
+     */
+    readonly take: <TControls extends Pick<StoryControls, "setPanelArgs">>(message: ShellMessage, story: TakenStory<TControls>, answer: (controls: TControls) => void) => void;
+    /**
+     * The story's values with the turned ones over them; an arg whose control failed is left out, so the story keeps its
+     * own: its JSON is not what the story takes.
+     *
+     * @param resolved - the panel's values as the story would take them without the modules.
+     */
+    readonly storyArgs: (resolved: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
+    /**
+     * The story's own values for the panel, with those the modules named over them.
+     *
+     * @param own - the story's own values, as plain data gives them.
+     */
+    readonly withOwn: (own: PanelArgs) => PanelArgs;
+    /**
+     * The panel's values of a story that changed its own args: a value a module made is given back as the panel's JSON it
+     * came from, which plain data cannot hold, so the panel keeps the reader's choice.
+     *
+     * @param values - the story's values.
+     * @param shown - the same as plain data gives them.
+     */
+    readonly panelArgs: (values: Readonly<Record<string, unknown>>, shown: PanelArgs) => PanelArgs;
+};
+/**
+ * A frame's custom controls with a frame module.
+ *
+ * @param loaders - the frame modules, by control; none hands every message on as it comes.
+ * @param source - the story's source, whose docs name the controls given by type.
+ * @param file - the story's file, the key of its docs.
+ * @param report - says what went wrong.
+ */
+export declare const panelControls: (loaders: ControlFrameLoaders | undefined, source: StorySource, file: string, report: (message: string) => void) => PanelControls;

package/dist/src/frame/panelControls.js

@@ -0,0 +1,110 @@
+import { sourceFiles } from "../sourceFiles.js";
+import { panelArgTypesOf } from "../storyArgTypes.js";
+import { STATUS_ATTRIBUTE } from "./frameStatus.js";
+import { panelArgsOf } from "./panelValues.js";
+/**
+ * Whether a frame module may have something to do for the story, so its docs are worth loading: the panel gives a
+ * value (any prop may be one a control takes by type), the story's `argTypes` name a control with a frame module, or
+ * the story gives itself a value plain data cannot show (an icon a module could name). A story with none of these, most
+ * of a page's frames, loads neither the turning code nor its docs.
+ *
+ * @param args - the panel's values.
+ * @param story - the story.
+ * @param loaders - the frame modules, by control.
+ * @param source - the story's source, whose named values show some values plainly.
+ */
+const mayTurn = (args, story, loaders, source) => {
+    if (Object.keys(args).length > 0)
+        return true;
+    const named = Object.values(panelArgTypesOf(story.argTypes, [])).some((argType) => argType.customControl !== undefined && Object.hasOwn(loaders, argType.customControl));
+    const shown = panelArgsOf(story.args, source.namedValues);
+    // an event's handler is no value a control sets: a type's control never takes an event
+    return (named ||
+        Object.entries(story.args).some(([name, value]) => value !== undefined && !Object.hasOwn(shown, name) && !/^on[A-Z]/.test(name)));
+};
+/**
+ * A frame's custom controls with a frame module.
+ *
+ * @param loaders - the frame modules, by control; none hands every message on as it comes.
+ * @param source - the story's source, whose docs name the controls given by type.
+ * @param file - the story's file, the key of its docs.
+ * @param report - says what went wrong.
+ */
+export const panelControls = (loaders, source, file, report) => {
+    const loadDocs = sourceFiles(source).docs[file];
+    let made;
+    // the panel's values last given, as JSON: what the made values came from
+    let given = {};
+    let count = 0;
+    // the values still turning, which the other messages wait for
+    let turning = Promise.resolve();
+    const reportError = (error) => report(error instanceof Error ? error.message : String(error));
+    return {
+        take: (message, { story, controls, tellReady }, answer) => {
+            if (controls === undefined)
+                return;
+            if (message.type !== "forgebook:args") {
+                if (loaders === undefined)
+                    answer(controls);
+                else
+                    turning = turning.then(() => answer(controls));
+            }
+            else if (loaders === undefined)
+                controls.setPanelArgs(message.args);
+            else if (!mayTurn(message.args, story, loaders, source)) {
+                // nothing a module could turn or name: no module, and no docs, load for this story
+                const hadOwn = Object.keys(made?.own ?? {}).length > 0;
+                count += 1;
+                made = undefined;
+                turning = turning.then(() => {
+                    controls.setPanelArgs(message.args);
+                    if (hadOwn)
+                        tellReady();
+                });
+            }
+            else {
+                count += 1;
+                const asked = count;
+                turning = import("./controlValues.js")
+                    .then(({ controlValuesOf }) => controlValuesOf(message.args, loaders, { ...story, loadDocs }))
+                    .then((next) => {
+                    // values the reader changed again meanwhile are the next call's to draw
+                    if (asked !== count)
+                        return;
+                    const isOwnNew = JSON.stringify(next.own) !== JSON.stringify(made?.own ?? {});
+                    made = next;
+                    given = message.args;
+                    controls.setPanelArgs(message.args);
+                    for (const problem of next.problems)
+                        report(problem);
+                    // the panel shows the story's own value a module names, told once known; a story in error stays one
+                    const isError = document.documentElement.getAttribute(STATUS_ATTRIBUTE) === "error";
+                    if (isOwnNew && !isError)
+                        tellReady();
+                })
+                    .catch((error) => {
+                    reportError(error);
+                    // without the modules the story still takes the values plain data can give
+                    if (asked !== count)
+                        return;
+                    made = undefined;
+                    controls.setPanelArgs(message.args);
+                });
+            }
+        },
+        storyArgs: (resolved) => {
+            const dropped = made?.dropped ?? [];
+            return Object.fromEntries(Object.entries({ ...resolved, ...made?.values }).filter(([name]) => !dropped.includes(name)));
+        },
+        withOwn: (own) => ({ ...own, ...made?.own }),
+        panelArgs: (values, shown) => {
+            const kept = Object.entries(made?.values ?? {}).flatMap(([name, value]) => {
+                const json = given[name];
+                return json !== undefined && Object.hasOwn(values, name) && values[name] === value
+                    ? [[name, json]]
+                    : [];
+            });
+            return { ...shown, ...Object.fromEntries(kept) };
+        }
+    };
+};

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

@@ -0,0 +1,35 @@
+/**
+ * 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 { type NamedArg, type PanelArgs } from "../messages.ts";
+import { type NamedValues } from "../namedValues.ts";
+/**
+ * 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 declare const nameOf: (value: unknown, namedValues: NamedValues) => NamedArg | 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 declare const panelArgsOf: (args: Readonly<Record<string, unknown>>, namedValues?: NamedValues) => PanelArgs;
+/**
+ * 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 declare const storyArgsOf: (args: PanelArgs, namedValues?: NamedValues) => Readonly<Record<string, unknown>>;