forgebook 0.3.1 → 0.3.3

package/dist/src/shell/Toolbar.js

@@ -73,13 +73,13 @@ const CompareMenu = ({ view, onViewChange, isDisabled, fixed = NOT_FIXED }) => {
  *
  * @param props - what showing the sidebar does.
  */
-export const ShowSidebarButton = ({ onShowSidebar }) => (_jsx("button", { type: "button", className: "forgebook-icon-button", title: STRINGS.showSidebar, "aria-label": STRINGS.showSidebar, onClick: onShowSidebar, children: _jsx(Icon, { name: "sidebar", size: 14 }) }));
+export const ShowSidebarButton = ({ onShowSidebar, showSidebarRef }) => (_jsx("button", { ref: showSidebarRef, type: "button", className: "forgebook-icon-button", title: STRINGS.showSidebar, "aria-label": STRINGS.showSidebar, onClick: onShowSidebar, children: _jsx(Icon, { name: "sidebar", size: 14 }) }));
 /**
  * The toolbar.
  *
  * @param props - the view, its setter, the page shown and the story's width.
  */
-export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage = true, isComponentPage = false, onShowSidebar, shownWidth, fixed = NOT_FIXED, isLogic = false, deviceDefault = NO_DEVICE }) => {
+export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage = true, isComponentPage = false, onShowSidebar, showSidebarRef, shownWidth, fixed = NOT_FIXED, isLogic = false, deviceDefault = NO_DEVICE }) => {
     const layout = useToolbarLayout();
     const catalogue = useCatalogue();
     // the story's fixed values are shown, and a change of anything else keeps the user's own in the address
@@ -96,5 +96,5 @@ export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryP
     const moved = useToolbarOverflow(pinnedRef, pinned.map((each) => each.control.id));
     // a bar that wraps has room for every pinned control
     const onBar = layout.isWrapped ? pinned : pinned.filter((each) => !moved.includes(each.control.id));
-    return (_jsxs("div", { className: layout.isWrapped ? "forgebook-toolbar forgebook-toolbar--wrap" : "forgebook-toolbar", children: [onShowSidebar === undefined ? null : _jsx(ShowSidebarButton, { onShowSidebar: onShowSidebar }), _jsx(ViewMenu, { layout: layout, ownView: ownView, movedIds: [...(layout.isWrapped ? [] : moved), ...putAway], ...context }), onBar.length === 0 ? null : _jsx("span", { className: "forgebook-toolbar__divider" }), _jsx("div", { ref: pinnedRef, className: "forgebook-toolbar__pinned-list", children: onBar.map((each) => (_jsx(PinnedControl, { control: each.control, isHidden: each.isHidden, isChanged: hasViewChanges(ownView, catalogue.switches, [each.control.id], catalogue.audience), layout: layout, ...context }, each.control.id))) }), _jsxs("button", { type: "button", className: "forgebook-button", title: STRINGS.panel, "aria-pressed": view.isPanelOpen, disabled: !isStoryPage, onClick: () => onViewChange({ ...view, isPanelOpen: !view.isPanelOpen }), children: [_jsx(Icon, { name: "panel", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: STRINGS.panel })] }), isLogic ? null : (_jsx(CompareMenu, { view: view, onViewChange: onViewChange, isDisabled: !isStoryPage, fixed: fixed }))] }));
+    return (_jsxs("div", { className: layout.isWrapped ? "forgebook-toolbar forgebook-toolbar--wrap" : "forgebook-toolbar", children: [onShowSidebar === undefined ? null : (_jsx(ShowSidebarButton, { onShowSidebar: onShowSidebar, showSidebarRef: showSidebarRef })), _jsx(ViewMenu, { layout: layout, ownView: ownView, movedIds: [...(layout.isWrapped ? [] : moved), ...putAway], ...context }), onBar.length === 0 ? null : _jsx("span", { className: "forgebook-toolbar__divider" }), _jsx("div", { ref: pinnedRef, className: "forgebook-toolbar__pinned-list", children: onBar.map((each) => (_jsx(PinnedControl, { control: each.control, isHidden: each.isHidden, isChanged: hasViewChanges(ownView, catalogue.switches, [each.control.id], catalogue.audience), layout: layout, ...context }, each.control.id))) }), _jsxs("button", { type: "button", className: "forgebook-button", title: STRINGS.panel, "aria-pressed": view.isPanelOpen, disabled: !isStoryPage, onClick: () => onViewChange({ ...view, isPanelOpen: !view.isPanelOpen }), children: [_jsx(Icon, { name: "panel", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: STRINGS.panel })] }), isLogic ? null : (_jsx(CompareMenu, { view: view, onViewChange: onViewChange, isDisabled: !isStoryPage, fixed: fixed }))] }));
 };

package/dist/src/shell/asideStory.d.ts

@@ -7,7 +7,7 @@
  *
  * @module
  */
-import { type PanelArgs } from "../messages.ts";
+import { type AcceptedArgs } from "../addressArgs.ts";
 import type { PluginStoryFrame } from "../plugin.ts";
 import type { LiveView, StageWidth } from "../viewState.ts";
 /** How the story is drawn again. */
@@ -18,11 +18,24 @@ export type AsideStory = {
     readonly width: StageWidth;
     /** The colour its page has in the view; none without one. */
     readonly background: string | undefined;
-    /** The values set in the panel, sent once it is ready. */
-    readonly args: PanelArgs;
+    /**
+     * The values the story accepted of the panel's, sent once it is ready; `undefined` while the check waits for the
+     * story's docs, when the frame draws the story's own and `AsideFrame.settle` gives them.
+     */
+    readonly args: AcceptedArgs | undefined;
     /** The view's live part, sent once it is ready; none when the address already says it all (the compare view). */
     readonly view: LiveView | undefined;
 };
+/** A story's second frame, as the shell holds it. */
+export type AsideFrame = PluginStoryFrame & {
+    /**
+     * Gives a frame drawn before the check ended the values it accepted; a frame that has them keeps them, since it shows
+     * the panel's values of the moment it was asked for.
+     *
+     * @param args - the accepted values.
+     */
+    readonly settle: (args: AcceptedArgs) => void;
+};
 /**
  * Draws a story's second frame in an element.
  *
@@ -31,4 +44,4 @@ export type AsideStory = {
  * @param aside - how the story is drawn.
  * @returns what takes it away.
  */
-export declare const showAsideStory: (target: HTMLElement, title: string, aside: AsideStory) => PluginStoryFrame;
+export declare const showAsideStory: (target: HTMLElement, title: string, aside: AsideStory) => AsideFrame;

package/dist/src/shell/asideStory.js

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { checkedArgsMessage } from "../addressArgs.js";
 import { isFrameMessage } from "../messages.js";
 import { framesOrigin, isFromFrames, storyFrameAttributes } from "./framesOrigin.js";
 import { FRAME_ASIDE_ATTRIBUTE } from "./useFrameMessages.js";
@@ -32,14 +33,18 @@ export const showAsideStory = (target, title, aside) => {
     frame.style.width = aside.width === "fill" ? "100%" : `${aside.width}px`;
     if (aside.background !== undefined)
         target.style.backgroundColor = aside.background;
+    let args = aside.args;
+    let isReady = false;
+    const send = (message) => frame.contentWindow?.postMessage(message, framesOrigin());
     const answer = (event) => {
         const story = frame.contentWindow;
         if (!isFromFrames(event) || event.source !== story || story === null)
             return;
         if (!isFrameMessage(event.data) || event.data.type !== "forgebook:ready")
             return;
-        const send = (message) => story.postMessage(message, framesOrigin());
-        send({ type: "forgebook:args", args: aside.args });
+        isReady = true;
+        if (args !== undefined)
+            send(checkedArgsMessage(args));
         if (aside.view !== undefined)
             send({ type: "forgebook:view", view: aside.view });
     };
@@ -50,6 +55,13 @@ export const showAsideStory = (target, title, aside) => {
         remove: () => {
             window.removeEventListener("message", answer);
             frame.remove();
+        },
+        settle: (accepted) => {
+            if (args !== undefined)
+                return;
+            args = accepted;
+            if (isReady)
+                send(checkedArgsMessage(accepted));
         }
     };
 };

package/dist/src/shell/shell.css

@@ -136,6 +136,31 @@
     border-inline-end: 1px solid var(--forgebook-separator);
     transition: margin-inline-start 320ms cubic-bezier(0.32, 0.72, 0, 1);
   }
+  .forgebook-sidebar[data-overlay] {
+    position: fixed;
+    inset-block: 0;
+    inset-inline-start: 0;
+    z-index: 22;
+    height: auto;
+    max-width: calc(100vw - 2rem);
+    transition: margin-inline-start 320ms cubic-bezier(0.32, 0.72, 0, 1), box-shadow 320ms cubic-bezier(0.32, 0.72, 0, 1);
+  }
+  .forgebook-sidebar[data-overlay][data-open] {
+    box-shadow: 0 0 0 1px var(--forgebook-edge), 0 18px 48px var(--forgebook-shadow-deep), 0 4px 12px var(--forgebook-shadow-lift);
+  }
+  .forgebook-sidebar-shade {
+    position: fixed;
+    inset: 0;
+    z-index: 21;
+    background: var(--forgebook-shade);
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity 320ms cubic-bezier(0.32, 0.72, 0, 1), visibility 320ms;
+  }
+  .forgebook-sidebar-shade[data-open] {
+    opacity: 1;
+    visibility: visible;
+  }
   .forgebook-appearance {
     position: relative;
     flex: none;
@@ -2476,7 +2501,9 @@
     .forgebook-stage-tools {
       animation-name: forgebook-appear;
     }
-    .forgebook-sidebar {
+    .forgebook-sidebar,
+    .forgebook-sidebar[data-overlay],
+    .forgebook-sidebar-shade {
       transition: none;
     }
     .forgebook-example__toggle svg,

package/dist/src/shell/useAddressArgs.d.ts

@@ -1,4 +1,16 @@
-import { type ArgDeclaration, type DroppedArg } from "../addressArgs.ts";
+/**
+ * The props panel's values an address names, as a page hands them to the story's frames: only those the story declares,
+ * with a value of the declared type, once the story's frame and its component's docs say what that is.
+ *
+ * @remarks
+ * The address is written by whoever shares the link, so its values are checked here, in the core, before any frame
+ * receives them, whatever framework draws the story (`addressArgs.ts`). Until the story's frame is ready and its docs
+ * are read (or known to be missing), no value is sent: the frame draws the story's own args meanwhile.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+import { type AcceptedArgs, type ArgDeclaration, type DroppedArg } from "../addressArgs.ts";
 import type { ComponentDocs } from "../componentDocs.ts";
 import { type PanelArgs } from "../messages.ts";
 import type { NamedValues } from "../namedValues.ts";
@@ -29,11 +41,15 @@ export type AddressArgsInput = {
     readonly controls: ReadyDeclaration["controls"];
     /** The source's named values; none when it has none. */
     readonly namedValues: NamedValues | undefined;
+    /** The element that holds the story's frames, which hear each change of the checked values. */
+    readonly frames: RefObject<HTMLElement | null>;
 };
 /** The address's values once checked, and how to check them for a frame that has just reported ready. */
 export type AddressArgs = {
     /** The values the story receives; none before its declaration is known. */
     readonly accepted: PanelArgs;
+    /** The same values for a frame that waits for the check; `undefined` until the declaration is known. */
+    readonly checked: AcceptedArgs | undefined;
     /** The values left out, with the reason. */
     readonly dropped: readonly DroppedArg[];
     /**
@@ -45,7 +61,7 @@ export type AddressArgs = {
      * The values to send a frame that has just reported ready, from its own message, since the state that holds it
      * updates after; none while the docs load.
      */
-    readonly acceptedFor: (ready: ReadyDeclaration) => PanelArgs | undefined;
+    readonly acceptedFor: (ready: ReadyDeclaration) => AcceptedArgs | undefined;
 };
 /**
  * The address's values, checked against what the story declares.

package/dist/src/shell/useAddressArgs.js

@@ -1,6 +1,6 @@
 /**
- * The props panel's values an address names, as the stage hands them to the story's frames: only those the story
- * declares, with a value of the declared type, once the story's frame and its component's docs say what that is.
+ * The props panel's values an address names, as a page hands them to the story's frames: only those the story declares,
+ * with a value of the declared type, once the story's frame and its component's docs say what that is.
  *
  * @remarks
  * The address is written by whoever shares the link, so its values are checked here, in the core, before any frame
@@ -9,9 +9,10 @@
  *
  * @module
  */
-import { useMemo } from "react";
-import { checkedAddressArgs } from "../addressArgs.js";
+import { useEffect, useMemo, useRef } from "react";
+import { checkedAddressArgs, checkedArgsMessage } from "../addressArgs.js";
 import { panelArgsParam } from "../messages.js";
+import { tellFrames } from "./FrameView.js";
 /**
  * What a story declares, once both its frame and its docs answered.
  *
@@ -43,20 +44,31 @@ const NO_NAMED_VALUES = {};
  * @param input - the address's values and what the stage knows of the story.
  */
 export const useAddressArgs = (input) => {
-    const { panelArgs, docs, storyArgs, argTypes, controls } = input;
+    const { panelArgs, docs, storyArgs, argTypes, controls, frames } = input;
     const namedValues = input.namedValues ?? NO_NAMED_VALUES;
     const checked = useMemo(() => {
         const ready = storyArgs === undefined ? undefined : { args: storyArgs, argTypes, controls };
         const declaration = declarationOf(docs, ready, namedValues);
         return declaration === undefined ? undefined : checkedAddressArgs(panelArgs, declaration);
     }, [panelArgs, docs, storyArgs, argTypes, controls, namedValues]);
+    const acceptedParam = checked === undefined ? undefined : panelArgsParam(checked.accepted);
+    // the values reach the frames from the address, so going back in the history sets them too; compared as text, so a
+    // frame is told again only when they change
+    const sealedRef = useRef(checked?.sealed);
+    sealedRef.current = checked?.sealed;
+    useEffect(() => {
+        if (acceptedParam === undefined || sealedRef.current === undefined)
+            return;
+        tellFrames(frames.current, checkedArgsMessage(sealedRef.current));
+    }, [acceptedParam, frames]);
     return {
         accepted: checked?.accepted ?? NO_ARGS,
+        checked: checked?.sealed,
         dropped: checked?.dropped ?? NOTHING_DROPPED,
-        acceptedParam: checked === undefined ? undefined : panelArgsParam(checked.accepted),
+        acceptedParam,
         acceptedFor: (message) => {
             const declaration = declarationOf(docs, message, namedValues);
-            return declaration === undefined ? undefined : checkedAddressArgs(panelArgs, declaration).accepted;
+            return declaration === undefined ? undefined : checkedAddressArgs(panelArgs, declaration).sealed;
         }
     };
 };

package/dist/src/shell/useSidebarLayout.d.ts

@@ -1,3 +1,5 @@
+/** The narrowest window with room for the sidebar beside the page and for the search's list beside it, in CSS px. */
+export declare const SIDE_BY_SIDE_WIDTH = 720;
 /** The sidebar's layout and its setters. */
 export type SidebarLayout = {
     /** Its width, in CSS px. */
@@ -6,8 +8,16 @@ export type SidebarLayout = {
     readonly setWidth: (width: number) => void;
     /** Whether it is shown. */
     readonly isOpen: boolean;
-    /** Shows or hides it. */
+    /** Shows or hides it: kept for the next visit on a wide window, only for this visit of the page on a narrow one. */
     readonly setIsOpen: (isOpen: boolean) => void;
+    /** Whether the window is narrow, so that the sidebar, when shown, lies over the page and not beside it. */
+    readonly isOverlay: boolean;
 };
-/** The sidebar's layout. */
-export declare const useSidebarLayout: () => SidebarLayout;
+/**
+ * The sidebar's layout.
+ *
+ * @param visit - the page's visit, new whenever a page is opened or the history moves, the shown page opened again
+ *   included: whatever changes the page under a sidebar lying over it closes the sidebar, in the same render, so that
+ *   the new page is never drawn out of reach.
+ */
+export declare const useSidebarLayout: (visit: object) => SidebarLayout;

package/dist/src/shell/useSidebarLayout.js

@@ -1,18 +1,56 @@
 /**
- * The sidebar's width and whether it is shown: this browser's convenience, kept for the next visit, not the address's.
+ * The sidebar's width and whether it is shown: on a wide window, this browser's convenience, kept for the next visit, not
+ * the address's; on a narrow one, a moment's look over the page, which leaves what was kept alone.
+ *
+ * @remarks
+ * Beside the page, a sidebar on a phone's window leaves the page about 110 px. There it slides over the page instead
+ * (`useSidebarOverlay.ts`), starts closed, and belongs to the visit it was opened on. A choice kept from a wide window
+ * would otherwise cover the page at every load, and opening it on a phone would change what the wide window shows next.
  *
  * @module
  */
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
 import { boundedSidebarWidth, SIDEBAR_WIDTH } from "./SidebarHandle.js";
 import { useStored } from "./useStored.js";
+/** The narrowest window with room for the sidebar beside the page and for the search's list beside it, in CSS px. */
+export const SIDE_BY_SIDE_WIDTH = 720;
+/** The media query of a window too narrow for the sidebar beside the page. */
+const NARROW_WINDOW = `(max-width: ${SIDE_BY_SIDE_WIDTH - 1}px)`;
 /** The width a stored text holds, or the default. */
 const storedWidth = (stored) => {
     const width = Number(stored);
     return stored === null || !Number.isFinite(width) ? SIDEBAR_WIDTH.initial : boundedSidebarWidth(width);
 };
-/** The sidebar's layout. */
-export const useSidebarLayout = () => {
+/** Listens to the window crossing the narrow width. */
+const subscribeToNarrow = (onChange) => {
+    const query = window.matchMedia(NARROW_WINDOW);
+    query.addEventListener("change", onChange);
+    return () => query.removeEventListener("change", onChange);
+};
+/** Whether the window is narrow now. */
+const isNarrowNow = () => window.matchMedia(NARROW_WINDOW).matches;
+/**
+ * The sidebar's layout.
+ *
+ * @param visit - the page's visit, new whenever a page is opened or the history moves, the shown page opened again
+ *   included: whatever changes the page under a sidebar lying over it closes the sidebar, in the same render, so that
+ *   the new page is never drawn out of reach.
+ */
+export const useSidebarLayout = (visit) => {
     const [width, setWidth] = useStored("sidebar-width", storedWidth, String);
-    const [isOpen, setIsOpen] = useStored("sidebar", (stored) => stored !== "hidden", (shown) => (shown ? "shown" : "hidden"));
-    return { width, setWidth, isOpen, setIsOpen };
+    const [isKeptOpen, setIsKeptOpen] = useStored("sidebar", (stored) => stored !== "hidden", (shown) => (shown ? "shown" : "hidden"));
+    const isOverlay = useSyncExternalStore(subscribeToNarrow, isNarrowNow, () => false);
+    const [overlayVisit, setOverlayVisit] = useState(undefined);
+    // it does not come back open when the window turns narrow again
+    useEffect(() => {
+        if (!isOverlay)
+            setOverlayVisit(undefined);
+    }, [isOverlay]);
+    const setIsOpen = useCallback((isOpen) => {
+        if (isOverlay)
+            setOverlayVisit(isOpen ? visit : undefined);
+        else
+            setIsKeptOpen(isOpen);
+    }, [isOverlay, visit, setIsKeptOpen]);
+    return { width, setWidth, isOpen: isOverlay ? overlayVisit === visit : isKeptOpen, setIsOpen, isOverlay };
 };

package/dist/src/shell/useSidebarOverlay.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What a sidebar lying over the page does beyond its look: Escape closes it, the focus moves into it as it opens and back
+ * to the button that shows it as it closes. The page behind is made inert by the shell, and a tap on the shade closes it.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+/** What the shell reads, and wires to the sidebar and its buttons. */
+export type SidebarOverlay = {
+    /** Whether the sidebar lies over the page now: shown, on a narrow window. */
+    readonly isOver: boolean;
+    /** The sidebar. */
+    readonly sidebarRef: RefObject<HTMLElement | null>;
+    /** The sidebar's button that hides it: where the focus goes as it opens. */
+    readonly hideButtonRef: RefObject<HTMLButtonElement | null>;
+    /** The toolbar's button that shows it: where the focus goes back as it closes. */
+    readonly showButtonRef: RefObject<HTMLButtonElement | null>;
+};
+/** What the wiring needs to know of the sidebar. */
+export type SidebarOverlayState = {
+    /** Whether the window is narrow, so that a shown sidebar lies over the page. */
+    readonly isOverlay: boolean;
+    /** Whether it is shown. */
+    readonly isOpen: boolean;
+    /** Closes it. */
+    readonly onClose: () => void;
+};
+/**
+ * Wires a sidebar lying over the page; nothing on a wide window, where the sidebar sits beside it.
+ *
+ * @param state - the sidebar's state.
+ * @returns whether it lies over the page, and the references to give the sidebar and its buttons.
+ */
+export declare const useSidebarOverlay: ({ isOverlay, isOpen, onClose }: SidebarOverlayState) => SidebarOverlay;

package/dist/src/shell/useSidebarOverlay.js

@@ -0,0 +1,51 @@
+/**
+ * What a sidebar lying over the page does beyond its look: Escape closes it, the focus moves into it as it opens and back
+ * to the button that shows it as it closes. The page behind is made inert by the shell, and a tap on the shade closes it.
+ *
+ * @module
+ */
+import { useEffect, useRef } from "react";
+/**
+ * Wires a sidebar lying over the page; nothing on a wide window, where the sidebar sits beside it.
+ *
+ * @param state - the sidebar's state.
+ * @returns whether it lies over the page, and the references to give the sidebar and its buttons.
+ */
+export const useSidebarOverlay = ({ isOverlay, isOpen, onClose }) => {
+    const sidebarRef = useRef(null);
+    const hideButtonRef = useRef(null);
+    const showButtonRef = useRef(null);
+    const isOver = isOverlay && isOpen;
+    useEffect(() => {
+        if (!isOver)
+            return;
+        const closeOnEscape = (event) => {
+            // a key an input method is composing with, or one the search used to empty itself, is not for the sidebar; neither
+            // is one that closes a menu open in the sidebar, which handles it itself
+            if (event.key !== "Escape" || event.isComposing || event.defaultPrevented)
+                return;
+            const openMenu = sidebarRef.current?.querySelector(".forgebook-popover");
+            if (openMenu === null || openMenu === undefined)
+                onClose();
+        };
+        document.addEventListener("keydown", closeOnEscape);
+        return () => document.removeEventListener("keydown", closeOnEscape);
+    }, [isOver, onClose]);
+    const wasOver = useRef(false);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: also looked at when the window crosses the width, and never when a wide window's sidebar is hidden, which leaves the focus alone
+    useEffect(() => {
+        const focused = document.activeElement;
+        const isFocusInSidebar = sidebarRef.current?.contains(focused) === true;
+        // the platform's search key has already put the focus on the search field
+        if (isOver && !isFocusInSidebar)
+            hideButtonRef.current?.focus({ preventScroll: true });
+        // the sidebar went away with the focus in it, closed or by the window crossing the width; one still shown keeps the
+        // focus, and a search's result that has already taken it to what it found keeps it too
+        const isFocusLost = isFocusInSidebar || (wasOver.current && (focused === document.body || focused === null));
+        if (!isOver && sidebarRef.current?.inert === true && isFocusLost) {
+            showButtonRef.current?.focus({ preventScroll: true });
+        }
+        wasOver.current = isOver;
+    }, [isOver, isOverlay]);
+    return { isOver, sidebarRef, hideButtonRef, showButtonRef };
+};

package/dist/src/storyMocks.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A story's mock handlers (`parameters.msw.handlers`) read from its parameters, and run on a server in place of the
+ * network. Exported as `forgebook/story-mocks`, for `@forgebook/plugin-msw` and the adapters that render on a server.
+ *
+ * @remarks
+ * A server render (the generated server tests) has no service worker, and whatever answers on the test machine must
+ * not decide what a page draws. So the handlers the frame's worker serves are run here through MSW's `getResponse`, a
+ * plain call with no interception, so concurrent renders never see each other's handlers. A request no handler answers,
+ * one a handler answers with `passthrough()`, or one made with `bypass()`, fails with the error the adapter writes, which
+ * knows what its stories can give instead. A handler's `HttpResponse.error()` rejects the fetch and its redirect is
+ * followed, as in the frame.
+ *
+ * Imports nothing, MSW included: `msw` is an optional peer of each adapter that uses this, so it is resolved from that
+ * package and passed in. A strict package manager would not find it from here.
+ *
+ * @module
+ */
+/** What a story's mocks need to answer requests on a server. */
+export type ServerMocks = {
+    /** The story's handlers (`mockHandlersOf`). */
+    readonly handlers: readonly unknown[];
+    /** The origin of the story's page, which a handler's path (`/api/users`) is read from, as the frame reads it. */
+    readonly origin: string;
+    /** Imports `msw`, from the adapter that declares it as a peer; called only when there are handlers to run. */
+    readonly loadMsw: () => Promise<unknown>;
+    /** The error a request fails with when no handler answers it; the adapter also keeps it, to fail the render. */
+    readonly onUnanswered: (request: Request) => Error;
+    /** Whether the mocks answer an address, or the network does; every address by default. */
+    readonly isMocked?: (address: URL) => boolean;
+};
+/**
+ * The handlers a story's parameters declare, flat: a list, or a record of lists as MSW's Storybook addon writes them.
+ *
+ * @param parameters - the story's parameters.
+ * @returns the handlers; none when the story has no mocks.
+ */
+export declare const mockHandlersOf: (parameters: Readonly<Record<string, unknown>>) => readonly unknown[];
+/**
+ * Whether an address reaches the same server as a page: its origin, or another name of this machine on the same scheme
+ * and port (`127.0.0.1` or `[::1]` beside a `localhost` page), which a real machine answers the same.
+ *
+ * @param address - the address.
+ * @param page - the page's address.
+ */
+export declare const isOnPageOrigin: (address: URL, page: URL) => boolean;
+/**
+ * A `fetch` of one render, its requests answered by the story's mocks. Make one per render: its `{ once: true }` handlers
+ * answer again from here.
+ *
+ * @param mocks - the story's mocks.
+ * @returns what sends a request; an address the mocks do not take goes to the global `fetch`.
+ */
+export declare const mockedFetch: (mocks: ServerMocks) => ((request: Request) => Promise<Response>);