forgebook 0.3.3 → 0.4.0

package/dist/src/frame/frame.css

@@ -5,6 +5,18 @@
     --forgebook-radius-control-small: 6px;
     --forgebook-radius-control: 7px;
     --forgebook-radius-card: 12px;
+    --forgebook-focus-edge: inset 0 0 0 1px var(--forgebook-accent);
+    --forgebook-focus-halo: color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    --forgebook-text-display: 700 1.375rem/1.2 var(--forgebook-font-sans);
+    --forgebook-text-card-title: 600 0.875rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-body: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    --forgebook-text-row-label: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    --forgebook-text-row-compact: 400 0.78125rem/1.4 var(--forgebook-font-sans);
+    --forgebook-text-control: 500 0.75rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-caption: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    --forgebook-text-label: 600 0.6875rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-mono: 400 0.71875rem/1.4 var(--forgebook-font-mono);
+    --forgebook-text-mono-small: 400 0.6875rem/1.6 var(--forgebook-font-mono);
     --forgebook-window: #f6f6f8;
     --forgebook-sidebar: #ebebef;
     --forgebook-surface: #fff;
@@ -19,6 +31,8 @@
     --forgebook-accent-text: #0059d2;
     --forgebook-on-accent: #fff;
     --forgebook-danger-text: #bc1f16;
+    --forgebook-caution-text: #935200;
+    --forgebook-positive-text: #077229;
     --forgebook-code-keyword: #7036c4;
     --forgebook-code-type: #0059d2;
     --forgebook-code-string: #077229;
@@ -59,7 +73,7 @@
   .forgebook-matrix__corner,
   .forgebook-matrix__name {
     padding: 0.5rem 0.75rem;
-    font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono-small);
     text-align: start;
     white-space: nowrap;
     opacity: 0.7;
@@ -68,9 +82,28 @@
     padding: 0.75rem;
     vertical-align: middle;
   }
+  .forgebook-frame-pending {
+    margin: 0;
+    padding: 0.5rem 0.75rem;
+    font: var(--forgebook-text-mono-small);
+    color: #fff;
+    background: #8a1c1c;
+  }
   .forgebook-frame-error {
+    --forgebook-focus-edge: inset 0 0 0 1px var(--forgebook-accent);
+    --forgebook-focus-halo: color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    --forgebook-text-display: 700 1.375rem/1.2 var(--forgebook-font-sans);
+    --forgebook-text-card-title: 600 0.875rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-body: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    --forgebook-text-row-label: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    --forgebook-text-row-compact: 400 0.78125rem/1.4 var(--forgebook-font-sans);
+    --forgebook-text-control: 500 0.75rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-caption: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    --forgebook-text-label: 600 0.6875rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-mono: 400 0.71875rem/1.4 var(--forgebook-font-mono);
+    --forgebook-text-mono-small: 400 0.6875rem/1.6 var(--forgebook-font-mono);
     margin: 1.5rem;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
     color: var(--forgebook-danger-text);
   }
   .forgebook-frame-error__message {
@@ -80,7 +113,7 @@
   .forgebook-frame-error__stack {
     margin: 0.75rem 0 0;
     overflow-x: auto;
-    font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono-small);
     color: var(--forgebook-text-secondary);
     white-space: pre;
   }

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

@@ -3,7 +3,22 @@
  *
  * @module
  */
-/** `ready` once the story rendered and its play function is over, `error` when it could not render. */
+/**
+ * `ready` once the story rendered, what it waits for came and its play function is over; `error` when it could not
+ * render; `pending` when the frame gave up waiting, or cannot tell, so what it shows was not seen in its final state: a
+ * check reads that as not verified, never as passed.
+ */
 export declare const STATUS_ATTRIBUTE = "data-forgebook-status";
+/** The root's attribute that says why the status is `pending`, in a sentence a person reads. */
+export declare const PENDING_REASON_ATTRIBUTE = "data-forgebook-pending-reason";
+/**
+ * The root's attribute set on a story that says it stays in a loading state (`parameters.suspense.expected`): the frame
+ * did not wait for it, and a check says so rather than let a preview turn the wait off unseen.
+ */
+export declare const NOT_AWAITED_ATTRIBUTE = "data-forgebook-not-awaited";
 /** The root's attribute set once the frame's code runs; the page's guard against code that fails earlier reads it. */
 export declare const FRAME_STARTED_ATTRIBUTE = "data-forgebook-started";
+/** The class of the text saying why a frame's story could not be drawn: what a check reports as the reason. */
+export declare const ERROR_MESSAGE_CLASS = "forgebook-frame-error__message";
+/** The class of a thrown error's stack under its message: the dev server's answer rewrites it in the lines as written. */
+export declare const ERROR_STACK_CLASS = "forgebook-frame-error__stack";

package/dist/src/frame/frameStatus.js

@@ -3,7 +3,22 @@
  *
  * @module
  */
-/** `ready` once the story rendered and its play function is over, `error` when it could not render. */
+/**
+ * `ready` once the story rendered, what it waits for came and its play function is over; `error` when it could not
+ * render; `pending` when the frame gave up waiting, or cannot tell, so what it shows was not seen in its final state: a
+ * check reads that as not verified, never as passed.
+ */
 export const STATUS_ATTRIBUTE = "data-forgebook-status";
+/** The root's attribute that says why the status is `pending`, in a sentence a person reads. */
+export const PENDING_REASON_ATTRIBUTE = "data-forgebook-pending-reason";
+/**
+ * The root's attribute set on a story that says it stays in a loading state (`parameters.suspense.expected`): the frame
+ * did not wait for it, and a check says so rather than let a preview turn the wait off unseen.
+ */
+export const NOT_AWAITED_ATTRIBUTE = "data-forgebook-not-awaited";
 /** The root's attribute set once the frame's code runs; the page's guard against code that fails earlier reads it. */
 export const FRAME_STARTED_ATTRIBUTE = "data-forgebook-started";
+/** The class of the text saying why a frame's story could not be drawn: what a check reports as the reason. */
+export const ERROR_MESSAGE_CLASS = "forgebook-frame-error__message";
+/** The class of a thrown error's stack under its message: the dev server's answer rewrites it in the lines as written. */
+export const ERROR_STACK_CLASS = "forgebook-frame-error__stack";

package/dist/src/frame/frameView.js

@@ -4,7 +4,7 @@
  *
  * @module
  */
-import { switchValueOf, switchWithRole } from "../switches.js";
+import { shownSwitches, switchValueOf, switchWithRole } from "../switches.js";
 import { schemeOf } from "../viewState.js";
 import { backdropSheet } from "./backdropPictures.js";
 /** The id of the style sheet that draws the backdrop. */
@@ -96,12 +96,13 @@ const applySwitch = (root, each, value) => {
  * @param catalogue - the catalogue's switches and backdrops.
  */
 export const applyView = (root, view, catalogue) => {
+    const shown = shownSwitches(view.switches, catalogue.switches);
     for (const each of catalogue.switches)
-        applySwitch(root, each, view.switches[each.id]);
+        applySwitch(root, each, shown[each.id]);
     // a language read right to left draws the story right to left; leaving it gives the root its own direction back,
     // unless a switch writes `dir` itself (the direction switch, applied above)
     const language = switchWithRole(catalogue.switches, "language");
-    const isRightToLeft = language !== undefined && switchValueOf(language, view.switches[language.id])?.isRightToLeft === true;
+    const isRightToLeft = language !== undefined && switchValueOf(language, shown[language.id])?.isRightToLeft === true;
     const isDirWritten = catalogue.switches.some((each) => each.apply.kind === "attribute" && each.apply.name === "dir");
     if (isRightToLeft)
         root.setAttribute("dir", "rtl");

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

@@ -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.
  *
@@ -19,6 +19,7 @@ import { type ViewSwitch } from "../switches.ts";
 import type { PlayToolsLoader } from "./playStory.ts";
 import { type FramePlugin } from "./pluginFrames.ts";
 import type { FrameRenderer } from "./renderer.ts";
+import type { ValueSheets } from "./valueSheets.ts";
 /** What an app passes to the frame. */
 export type FrameConfig = {
     /** The framework that draws the stories (`@forgebook/react` passes its own). */
@@ -36,6 +37,11 @@ export type FrameConfig = {
     readonly previews?: readonly unknown[];
     /** The switches of the toolbar and the View menu, as the shell's configuration gives them; the theme and contrast by default. */
     readonly switches?: readonly ViewSwitch[];
+    /**
+     * The address of each switch value's own style sheet, by `<switch id>=<value>`; none when no value has one. The
+     * generated frame gives addresses the configuration's check allowed; the page checks nothing itself.
+     */
+    readonly valueSheets?: ValueSheets;
     /** The catalogue's lists (its backgrounds, text sizes, grid step, accessibility rules…); the defaults when none. */
     readonly lists?: CatalogueLists;
     /** Loads the play tools, when the project installs Testing Library (the generated frame passes it then). */

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,31 @@
  */
 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 { 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,11 +51,60 @@ 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.
@@ -60,11 +112,13 @@ import.meta.hot?.on("vite:afterUpdate", () => {
  * @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")
@@ -73,29 +127,51 @@ const answerShell = (message, controls, storyId, rules, axeUrl, tellShell) => {
         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);
+};
+/**
+ * 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, for a story that uses them. */
-const playToolsOf = ({ playTools }) => playTools === undefined ? {} : { playTools };
+/** 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 +189,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 +214,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 +245,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 +259,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 +309,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,12 +321,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);
+                answerShell(message, controls, 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
@@ -262,7 +366,7 @@ 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,
@@ -270,14 +374,17 @@ export const mountFrame = async (container, config) => {
             decorators: [...preview.decorators, ...plugins.decorators],
             ...shown,
             resolveArgs: (args) => storyArgsOf(args, source.namedValues),
-            onControlsReady: (next) => {
+            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 +403,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")
@@ -370,6 +477,6 @@ export const mountFrame = async (container, config) => {
             window.location.reload();
             return;
         }
-        fail(message);
+        failedToLoad(message, fail);
     }
 };

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>>;