forgebook 0.3.1 → 0.3.2

package/README.md

@@ -9,7 +9,7 @@ per story, switches for theme, contrast, motion and language, and a props table
 > and every change is in the
 > [changelog](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/CHANGELOG.md).
 
-**Requirements:** Node 22.18 or later · Vite 8 (the catalogue is built on it; other bundlers are not supported) · React 19 through
+**Requirements:** Node 22.18 or later · Vite 8.3.4+ (the catalogue is built on it; other bundlers are not supported) · React 19 through
 [`@forgebook/react`](https://www.npmjs.com/package/@forgebook/react), Vue 3.5 through
 [`@forgebook/vue`](https://www.npmjs.com/package/@forgebook/vue) (a Nuxt project's through
 [`@forgebook/nuxt`](https://www.npmjs.com/package/@forgebook/nuxt)), Svelte 5 through
@@ -194,6 +194,15 @@ too, with a warning.
 
 It adds about a dozen packages to a React and Vite project.
 
+## On a narrow window
+
+Below 720 px the sidebar stops taking room from the page. It starts closed, opens from the toolbar's sidebar button and
+slides over the page, which keeps the whole width and cannot be reached while the sidebar is open. A tap outside it,
+Escape (once the search is empty and no menu is open), its own button or opening any page closes it, and the focus goes
+back to the button, unless a search's result has taken it to what it found. Opening it there changes
+nothing a wider window remembers: the sidebar a person showed or hid on a wide window is as they left it, width
+included. A reduced-motion preference shows and hides it at once.
+
 ## The toolbar
 
 The View menu holds every control: the catalogue's switches, and Forgebook's own (the background, the style sheets, the
@@ -498,8 +507,8 @@ The buttons read their colours from the page's theme.
 
 The field at the top of the sidebar searches the whole catalogue. The tree filters by name as you type, for browsing;
 beside it a list ranks everything the words find, each component or page with what matched inside it and why (a prop,
-an event, a heading, a sentence, a story), the words marked. `/` or ⌘K (Ctrl+K) comes to the field from anywhere, ↑ and ↓
-move, Enter opens at the exact heading or prop, ⌘Enter or a modified press opens a new tab, Escape empties the field.
+an event, a heading, a sentence, a story), the words marked. `/` or ⌘K (Ctrl+K) comes to the field from anywhere (with the sidebar hidden, ⌘K alone,
+which shows it), ↑ and ↓ move, Enter opens at the exact heading or prop, ⌘Enter or a modified press opens a new tab, Escape empties the field.
 
 A prop has an address of its own, so a link to one can be pasted anywhere: `?component=acme:inputs-select#prop.value`,
 and `#prop.Group.label` for a prop of a part named in `subcomponents`. A heading of a component's documentation file

package/dist/bin/forgebook/agents.md

@@ -115,7 +115,8 @@ in JSON with `--json`, and every answer about a story carries the links that ope
   and what its server code reads with `nextjs.cookies`, `headers` and `draftMode`. A link or a router call moves the
   story's route and is listed among its events; a `play` reads where it went with `storyRoute()`
   (`@forgebook/nextjs/route`). Async server components are drawn; what they reach on a server (a database, the file
-  system) is not there: fetch it and mock it with `parameters.msw`.
+  system) is not there: fetch it and mock it with `parameters.msw`. In the server tests a server component's `fetch` never
+  reaches the network, whatever its address: a fetch no handler answers fails the story, naming the address.
 
 - Say when a component is for and when it is not, in its TSDoc: `@useWhen`, `@avoidWhen`, `@alternatives`, `@deprecated`,
   `@replacedBy`. `forgebook story` returns them as `docs.guidance`: read them before using a component, and never use a

package/dist/src/shell/SearchPanel.js

@@ -18,10 +18,9 @@ import { searchables, searchCatalogue } from "../search.js";
 import { SEARCH_STRINGS } from "./searchStrings.js";
 import { shownTree } from "./treeSearch.js";
 import { useSearchIndex } from "./useSearchIndex.js";
+import { SIDE_BY_SIDE_WIDTH } from "./useSidebarLayout.js";
 /** How much a page shows: what a person reads before refining the words. */
 const LIMITS = { results: 24, hits: 3 };
-/** The narrowest window where the list opens beside the sidebar: a smaller one has it over the sidebar, under the field. */
-const BESIDE_WIDTH = 720;
 /** The room between the field and the list when the list opens under it, in CSS px. */
 const LIST_GAP = 6;
 /** The room the list leaves around it, in CSS px. */
@@ -35,7 +34,7 @@ const LIST_WIDTH = "38rem";
  * @param sidebarWidth - the sidebar's width, in CSS px.
  */
 const listPlace = (field, sidebarWidth) => {
-    if (window.innerWidth < BESIDE_WIDTH)
+    if (window.innerWidth < SIDE_BY_SIDE_WIDTH)
         return { top: field.bottom + LIST_GAP, insetInline: LIST_MARGIN };
     const start = sidebarWidth + LIST_MARGIN;
     return {

package/dist/src/shell/Shell.js

@@ -19,7 +19,7 @@ import { LogicMark } from "./LogicMark.js";
 import { lazyModule } from "./lazyModule.js";
 import { PluginHostsContext } from "./pluginHostsContext.js";
 import { Sidebar } from "./Sidebar.js";
-import { SidebarHandle } from "./SidebarHandle.js";
+import { SidebarEdge } from "./SidebarHandle.js";
 import { Stage } from "./Stage.js";
 import { StoryPicker } from "./StoryPicker.js";
 import { STRINGS } from "./strings.js";
@@ -28,6 +28,7 @@ import { useAppearance } from "./useAppearance.js";
 import { useRecentPages } from "./useRecentPages.js";
 import { useShownView } from "./useShownView.js";
 import { useSidebarLayout } from "./useSidebarLayout.js";
+import { useSidebarOverlay } from "./useSidebarOverlay.js";
 import { useStoryHeights } from "./useStoryHeights.js";
 import { useStoryIdsElement } from "./useStoryIdsElement.js";
 import { useStoryKeys } from "./useStoryKeys.js";
@@ -222,7 +223,7 @@ const fixedOfShown = (fixedViews, shown) => shown.kind === "story" ? (fixedViews
  *
  * @param props - whether the home is shown, and the toolbar's props.
  */
-const ShellBar = ({ isHome, ...toolbar }) => isHome ? (_jsx("div", { className: "forgebook-toolbar", children: toolbar.onShowSidebar === undefined ? null : (_jsx(ShowSidebarButton, { onShowSidebar: toolbar.onShowSidebar })) })) : (_jsx(Toolbar, { ...toolbar }));
+const ShellBar = ({ isHome, ...toolbar }) => isHome ? (_jsx("div", { className: "forgebook-toolbar", children: toolbar.onShowSidebar === undefined ? null : (_jsx(ShowSidebarButton, { onShowSidebar: toolbar.onShowSidebar, showSidebarRef: toolbar.showSidebarRef })) })) : (_jsx(Toolbar, { ...toolbar }));
 /**
  * What a component's page loads: its first file's docs and page, as Storybook's docs come from the first file of a
  * title, and the code of every file, for each example's Code card.
@@ -415,10 +416,16 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
     // the written home's module, loaded when the home is first opened
     const writtenHome = useMemo(() => (home === undefined ? undefined : lazyModule(home)), [home]);
     const idsByTitle = useMemo(() => componentIdsByTitle(tree), [tree]);
-    const { width: sidebarWidth, setWidth: setSidebarWidth, isOpen: isSidebarOpen, setIsOpen: setIsSidebarOpen } = useSidebarLayout();
-    const showSidebar = useCallback(() => setIsSidebarOpen(true), [setIsSidebarOpen]);
     const catalogue = useCatalogue();
     const { address, visit, pageAddress, openPage, openFound, openAnchor, replaceAddress } = useAddress(catalogue, addressTexts);
+    const { width: sidebarWidth, setWidth: setSidebarWidth, isOpen: isSidebarOpen, setIsOpen: setIsSidebarOpen, isOverlay: isSidebarOverlay } = useSidebarLayout(visit);
+    const showSidebar = useCallback(() => setIsSidebarOpen(true), [setIsSidebarOpen]);
+    const hideSidebar = useCallback(() => setIsSidebarOpen(false), [setIsSidebarOpen]);
+    const { isOver: isSidebarOver, sidebarRef, hideButtonRef, showButtonRef } = useSidebarOverlay({
+        isOverlay: isSidebarOverlay,
+        isOpen: isSidebarOpen,
+        onClose: hideSidebar
+    });
     // each page's last scroll position, kept across the component pages and the stage
     const scrollPositions = useRef(new Map());
     const scroll = { visit, positions: scrollPositions.current };
@@ -489,7 +496,9 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
         header,
         scroll
     };
-    return (_jsxs("div", { className: "catalogue", children: [_jsx(Sidebar, { width: sidebarWidth, isOpen: isSidebarOpen, onHide: () => setIsSidebarOpen(false), onShow: showSidebar, appearance: appearance, title: title, logo: logo, hasBranding: hasBranding !== false, tree: tree, sources: sources, searchHref: (target) => addressQuery(pageAddress(target), catalogue), onOpenResult: openFound, isHome: shown.kind === "home", homeHref: addressQuery(pageAddress(HOME), catalogue), onOpenHome: () => openPage(HOME), current: sidebarCurrent(location, shownStoryId), currentPageId: shownPageLocation?.page.id, pageHref: (id) => addressQuery(pageAddress({ kind: "page", id }), catalogue), onOpenPage: (id) => openPage({ kind: "page", id }), componentHref: (sourceId, componentTitle) => addressQuery(pageAddress(titledPage(idsByTitle, sourceId, componentTitle)), catalogue), onOpenComponent: (sourceId, componentTitle) => openPage(titledPage(idsByTitle, sourceId, componentTitle)) }), isSidebarOpen ? _jsx(SidebarHandle, { width: sidebarWidth, onWidthChange: setSidebarWidth }) : null, _jsxs("main", { className: "forgebook-main", children: [_jsx(ShellBar, { isHome: hasNoStories(shown), view: shownView, onViewChange: changeShownView, isStoryPage: shown.kind === "story", isComponentPage: shown.kind === "component", isLogic: isLogicPage(shown), onShowSidebar: isSidebarOpen ? undefined : () => setIsSidebarOpen(true), shownWidth: shown.kind === "story" ? shownWidth : undefined, fixed: fixedOfShown(fixedViews, shown), deviceDefault: deviceOfShown(catalogue.device, shown) }), shown.kind === "component" ? (_jsx(LazyPage, { module: COMPONENT_PAGE, header: header, pageProps: {
+    return (_jsxs("div", { className: "catalogue", children: [_jsx(Sidebar, { width: sidebarWidth, isOpen: isSidebarOpen, isOverlay: isSidebarOverlay, sidebarRef: sidebarRef, hideButtonRef: hideButtonRef, onHide: hideSidebar, onShow: showSidebar, appearance: appearance, title: title, logo: logo, hasBranding: hasBranding !== false, tree: tree, sources: sources, searchHref: (target) => addressQuery(pageAddress(target), catalogue), onOpenResult: openFound, isHome: shown.kind === "home", homeHref: addressQuery(pageAddress(HOME), catalogue), onOpenHome: () => openPage(HOME), current: sidebarCurrent(location, shownStoryId), currentPageId: shownPageLocation?.page.id, pageHref: (id) => addressQuery(pageAddress({ kind: "page", id }), catalogue), onOpenPage: (id) => openPage({ kind: "page", id }), componentHref: (sourceId, componentTitle) => addressQuery(pageAddress(titledPage(idsByTitle, sourceId, componentTitle)), catalogue), onOpenComponent: (sourceId, componentTitle) => openPage(titledPage(idsByTitle, sourceId, componentTitle)) }), _jsx(SidebarEdge, { isOverlay: isSidebarOverlay, isOpen: isSidebarOpen, width: sidebarWidth, onWidthChange: setSidebarWidth, onHide: hideSidebar }), _jsxs("main", { className: "forgebook-main", inert: isSidebarOver, children: [_jsx(ShellBar, { isHome: hasNoStories(shown), view: shownView, onViewChange: changeShownView, isStoryPage: shown.kind === "story", isComponentPage: shown.kind === "component", isLogic: isLogicPage(shown), 
+                        // under a sidebar lying over the page the button stays, so the bar's controls never move behind it
+                        onShowSidebar: isSidebarOpen && !isSidebarOver ? undefined : showSidebar, showSidebarRef: showButtonRef, shownWidth: shown.kind === "story" ? shownWidth : undefined, fixed: fixedOfShown(fixedViews, shown), deviceDefault: deviceOfShown(catalogue.device, shown) }), shown.kind === "component" ? (_jsx(LazyPage, { module: COMPONENT_PAGE, header: header, pageProps: {
                             component: shown.location.component,
                             anchor: shown.anchor,
                             view: address.view,

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

@@ -11,7 +11,7 @@
  * @module
  */
 import type { StorySource } from "@forgebook/story-format/source";
-import { type ReactNode } from "react";
+import { type ReactNode, type Ref } from "react";
 import type { SearchTarget } from "../search.ts";
 import type { StoryTree } from "../storyTree.ts";
 import { type SidebarPageLinks } from "./SidebarDocs.tsx";
@@ -54,6 +54,12 @@ export type SidebarProps = SidebarPageLinks & {
     readonly width: number;
     /** Whether it is shown: hidden, it slides out and stays mounted, so its search and open families come back with it. */
     readonly isOpen: boolean;
+    /** Whether it lies over the page and not beside it, on a narrow window. */
+    readonly isOverlay: boolean;
+    /** The sidebar's element. */
+    readonly sidebarRef: Ref<HTMLElement>;
+    /** Its button that hides it. */
+    readonly hideButtonRef: Ref<HTMLButtonElement>;
     /** Hides the sidebar. */
     readonly onHide: () => void;
     /** Shows it again. */
@@ -66,4 +72,4 @@ export type SidebarProps = SidebarPageLinks & {
  *
  * @param props - the tree, the shown component and how to open one.
  */
-export declare const Sidebar: ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, onHide, onShow, appearance, ...links }: SidebarProps) => ReactNode;
+export declare const Sidebar: ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, isOverlay, sidebarRef, hideButtonRef, onHide, onShow, appearance, ...links }: SidebarProps) => ReactNode;

package/dist/src/shell/Sidebar.js

@@ -50,7 +50,7 @@ const componentCount = (family) => family.groups.reduce((count, group) => count
  *
  * @param props - the tree, the shown component and how to open one.
  */
-export const Sidebar = ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, onHide, onShow, appearance, ...links }) => {
+export const Sidebar = ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, isOverlay, sidebarRef, hideButtonRef, onHide, onShow, appearance, ...links }) => {
     const [query, setQuery] = useState("");
     const [filterTree, setFilterTree] = useState();
     const showFiltered = useCallback((filter) => setFilterTree(() => filter), []);
@@ -86,12 +86,12 @@ export const Sidebar = ({ title, logo, hasBranding, tree, sources: storySources,
     // the filter comes with the search's list; a moment before it, or with no words, the tree shows whole
     const { sources, pages } = isSearching && filterTree !== undefined ? filterTree(tree, query) : wholeTree(tree);
     const hasMatches = pages.length > 0 || sources.some(({ families }) => families.length > 0);
-    return (_jsxs("aside", { className: "forgebook-sidebar", "data-open": isOpen ? "" : undefined, inert: !isOpen, style: { width, marginInlineStart: isOpen ? 0 : -width }, children: [_jsxs("div", { className: "forgebook-brand", children: [_jsxs("a", { className: "forgebook-brand__home", href: homeHref, "aria-current": isHome ? "page" : undefined, title: STRINGS.home, onClick: (event) => {
+    return (_jsxs("aside", { ref: sidebarRef, className: "forgebook-sidebar", "data-open": isOpen ? "" : undefined, "data-overlay": isOverlay ? "" : undefined, inert: !isOpen, style: { width, marginInlineStart: isOpen ? 0 : -width }, children: [_jsxs("div", { className: "forgebook-brand", children: [_jsxs("a", { className: "forgebook-brand__home", href: homeHref, "aria-current": isHome ? "page" : undefined, title: STRINGS.home, onClick: (event) => {
                             if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
                                 return;
                             event.preventDefault();
                             onOpenHome();
-                        }, children: [mark === undefined ? null : (_jsx("img", { className: "forgebook-brand__logo", src: mark, alt: "", width: 28, height: 28 })), _jsx("span", { className: "forgebook-brand__name", children: title })] }), _jsx("button", { type: "button", className: "forgebook-icon-button forgebook-brand__hide", title: STRINGS.hideSidebar, "aria-label": STRINGS.hideSidebar, onClick: onHide, children: _jsx(Icon, { name: "sidebar", size: 14 }) })] }), _jsx(SidebarSearch, { query: query, onQueryChange: setQuery, onFilterReady: showFiltered, tree: tree, sources: storySources, sidebarWidth: width, isSidebarOpen: isOpen, onShowSidebar: onShow, searchHref: searchHref, onOpenResult: onOpenResult }), _jsxs("nav", { ref: navRef, className: "forgebook-tree", "aria-label": STRINGS.componentsNav, children: [hasMatches ? null : _jsx("p", { className: "forgebook-tree__empty", children: STRINGS.noMatch }), _jsx(SidebarDocs, { sources: pages, currentPageId: currentPageId, isSearching: isSearching, foldChoices: foldChoices, onFoldChange: setFoldOpen, pageHref: pageHref, onOpenPage: onOpenPage }), sources.map(({ source, families }) => families.length === 0 ? null : (_jsxs("section", { className: "forgebook-tree__source", children: [_jsxs("h2", { className: "forgebook-tree__source-name", children: [source.logo === undefined ? null : (_jsx("img", { className: "forgebook-source-logo", src: source.logo, alt: "", width: 14, height: 14 })), source.name] }), families.map((family) => {
+                        }, children: [mark === undefined ? null : (_jsx("img", { className: "forgebook-brand__logo", src: mark, alt: "", width: 28, height: 28 })), _jsx("span", { className: "forgebook-brand__name", children: title })] }), _jsx("button", { ref: hideButtonRef, type: "button", className: "forgebook-icon-button forgebook-brand__hide", title: STRINGS.hideSidebar, "aria-label": STRINGS.hideSidebar, onClick: onHide, children: _jsx(Icon, { name: "sidebar", size: 14 }) })] }), _jsx(SidebarSearch, { query: query, onQueryChange: setQuery, onFilterReady: showFiltered, tree: tree, sources: storySources, sidebarWidth: width, isSidebarOpen: isOpen, onShowSidebar: onShow, searchHref: searchHref, onOpenResult: onOpenResult }), _jsxs("nav", { ref: navRef, className: "forgebook-tree", "aria-label": STRINGS.componentsNav, children: [hasMatches ? null : _jsx("p", { className: "forgebook-tree__empty", children: STRINGS.noMatch }), _jsx(SidebarDocs, { sources: pages, currentPageId: currentPageId, isSearching: isSearching, foldChoices: foldChoices, onFoldChange: setFoldOpen, pageHref: pageHref, onOpenPage: onOpenPage }), sources.map(({ source, families }) => families.length === 0 ? null : (_jsxs("section", { className: "forgebook-tree__source", children: [_jsxs("h2", { className: "forgebook-tree__source-name", children: [source.logo === undefined ? null : (_jsx("img", { className: "forgebook-source-logo", src: source.logo, alt: "", width: 14, height: 14 })), source.name] }), families.map((family) => {
                                 const key = familyKey(source, family);
                                 // a search opens every family it finds something in
                                 const isOpen = isSearching || (foldChoices.get(key) ?? isCurrentFamily(source, family));

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

@@ -1,5 +1,6 @@
 /**
- * The handle on the sidebar's right edge: dragged, or moved with the arrow keys, it sets the sidebar's width.
+ * The handle on the sidebar's right edge: dragged, or moved with the arrow keys, it sets the sidebar's width; on a narrow
+ * window, where the sidebar lies over the page at no chosen width, the shade on the page takes its place.
  *
  * @module
  */
@@ -26,3 +27,15 @@ export declare const SidebarHandle: ({ width, onWidthChange }: {
     readonly width: number;
     readonly onWidthChange: (width: number) => void;
 }) => ReactNode;
+/**
+ * What borders the sidebar: beside the page its handle, while shown; over it the shade on the page.
+ *
+ * @param props - where the sidebar lies, whether it is shown, its width and how to hide it.
+ */
+export declare const SidebarEdge: ({ isOverlay, isOpen, width, onWidthChange, onHide }: {
+    readonly isOverlay: boolean;
+    readonly isOpen: boolean;
+    readonly width: number;
+    readonly onWidthChange: (width: number) => void;
+    readonly onHide: () => void;
+}) => ReactNode;

package/dist/src/shell/SidebarHandle.js

@@ -43,3 +43,13 @@ export const SidebarHandle = ({ width, onWidthChange }) => {
     };
     return (_jsx("div", { className: "forgebook-sidebar-handle", role: "separator", "aria-orientation": "vertical", "aria-label": STRINGS.sidebarWidth, "aria-valuenow": width, "aria-valuemin": SIDEBAR_WIDTH.min, "aria-valuemax": SIDEBAR_WIDTH.max, tabIndex: 0, onPointerDown: startResize, onKeyDown: resizeWithKeys }));
 };
+/**
+ * What borders the sidebar: beside the page its handle, while shown; over it the shade on the page.
+ *
+ * @param props - where the sidebar lies, whether it is shown, its width and how to hide it.
+ */
+export const SidebarEdge = ({ isOverlay, isOpen, width, onWidthChange, onHide }) => {
+    if (!isOverlay)
+        return isOpen ? _jsx(SidebarHandle, { width: width, onWidthChange: onWidthChange }) : null;
+    return (_jsx("div", { className: "forgebook-sidebar-shade", "data-open": isOpen ? "" : undefined, "aria-hidden": "true", onClick: onHide }));
+};

package/dist/src/shell/SidebarSearch.js

@@ -68,13 +68,16 @@ export const SidebarSearch = ({ query, onQueryChange, onFilterReady, tree, sourc
                                 event.preventDefault();
                                 return;
                             }
-                            // Escape empties the search first, then leaves the field
+                            // Escape empties the search first, then leaves the field; emptying uses the key up, so a sidebar lying over
+                            // the page stays open for it (`useSidebarOverlay.ts`)
                             if (event.key !== "Escape")
                                 return;
-                            if (query === "")
+                            if (query === "") {
                                 event.currentTarget.blur();
-                            else
-                                onQueryChange("");
+                                return;
+                            }
+                            event.preventDefault();
+                            onQueryChange("");
                         }, placeholder: STRINGS.searchPlaceholder, "aria-label": STRINGS.searchLabel, onChange: (event) => {
                             onQueryChange(event.target.value);
                             setIsListOpen(true);

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

@@ -9,7 +9,7 @@
  *
  * @module
  */
-import { type ReactNode } from "react";
+import { type ReactNode, type Ref } from "react";
 import { type DeviceDefault } from "../deviceView.ts";
 import { type FixedView } from "../storyGlobals.ts";
 import { type ViewState } from "../viewState.ts";
@@ -23,8 +23,10 @@ export type ToolbarProps = {
     readonly isStoryPage?: boolean;
     /** Whether a component's page is shown: the audience changes nothing elsewhere. */
     readonly isComponentPage?: boolean;
-    /** Shows the hidden sidebar; none while it is shown. */
+    /** Shows the hidden sidebar; none while it is shown beside the page. */
     readonly onShowSidebar?: (() => void) | undefined;
+    /** The button that shows the sidebar, where the focus goes back when a sidebar over the page closes. */
+    readonly showSidebarRef?: Ref<HTMLButtonElement> | undefined;
     /** The width the shown story really has, in CSS px, for the width field; none on a component's page. */
     readonly shownWidth?: number | undefined;
     /** What the shown story fixes of the view: shown, and not changeable here; nothing by default. */
@@ -39,7 +41,7 @@ export type ToolbarProps = {
  *
  * @param props - what showing the sidebar does.
  */
-export declare const ShowSidebarButton: ({ onShowSidebar }: {
+export declare const ShowSidebarButton: ({ onShowSidebar, showSidebarRef }: Pick<ToolbarProps, "showSidebarRef"> & {
     readonly onShowSidebar: () => void;
 }) => ReactNode;
 /**
@@ -47,4 +49,4 @@ export declare const ShowSidebarButton: ({ onShowSidebar }: {
  *
  * @param props - the view, its setter, the page shown and the story's width.
  */
-export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, isComponentPage, onShowSidebar, shownWidth, fixed, isLogic, deviceDefault }: ToolbarProps) => ReactNode;
+export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, isComponentPage, onShowSidebar, showSidebarRef, shownWidth, fixed, isLogic, deviceDefault }: ToolbarProps) => ReactNode;

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

package/dist/src/storyMocks.js

@@ -0,0 +1,208 @@
+/**
+ * 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
+ */
+/** How many redirects a fetch follows, as browsers and Node's `fetch` do. */
+const MOST_REDIRECTS = 20;
+/**
+ * How many requests of a render wait at once. A handler that fetches the address it answers comes back to itself for
+ * ever, in promises alone, so no timer of the render's ever fires: only this stops it.
+ */
+const MOST_WAITING = 1000;
+/** The headers a redirect to another origin does not carry. */
+const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"];
+/** Whether a value is an object with named fields. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * 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 const mockHandlersOf = (parameters) => {
+    const msw = parameters["msw"];
+    const handlers = isRecord(msw) ? msw["handlers"] : undefined;
+    if (Array.isArray(handlers))
+        return handlers;
+    return isRecord(handlers) ? Object.values(handlers).flat() : [];
+};
+/** The addresses of this machine that are not a range: every interface's, which connecting to reaches this machine. */
+const OWN_ADDRESSES = new Set(["[::1]", "0.0.0.0", "[::]"]);
+/**
+ * Whether a host name is this machine's own, as `URL` writes it: `localhost` and its subdomains, with or without the
+ * final dot, `127.0.0.0/8`, the same range mapped into IPv6, and the addresses that reach every interface.
+ *
+ * @param hostname - the host name, from a `URL`.
+ */
+const isLoopback = (hostname) => {
+    const name = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+    return (name === "localhost" ||
+        name.endsWith(".localhost") ||
+        OWN_ADDRESSES.has(name) ||
+        /^127\.\d+\.\d+\.\d+$/.test(name) ||
+        /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(name));
+};
+/**
+ * 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 const isOnPageOrigin = (address, page) => {
+    if (address.origin === page.origin)
+        return true;
+    return (address.protocol === page.protocol &&
+        address.port === page.port &&
+        isLoopback(address.hostname) &&
+        isLoopback(page.hostname));
+};
+/**
+ * Makes a story's `{ once: true }` handlers answer again, as MSW's `restoreHandlers` does: each render on a server is a
+ * page of its own, as each frame is, while the handler objects outlive it in the test process.
+ *
+ * @param handlers - the story's handlers.
+ */
+const restoreHandlers = (handlers) => {
+    for (const handler of handlers)
+        if (isRecord(handler) && typeof handler["isUsed"] === "boolean")
+            Reflect.set(handler, "isUsed", false);
+};
+/**
+ * Whether a module is MSW's, as much as a server render uses.
+ *
+ * @param module - the module, as `import()` gave it.
+ */
+const isMswCore = (module) => typeof module === "object" &&
+    module !== null &&
+    "getResponse" in module &&
+    typeof module.getResponse === "function";
+/**
+ * Loads MSW, which only a story with handlers needs on a server.
+ *
+ * @param loadMsw - imports it.
+ * @throws when MSW is not installed, or is older than its `getResponse`.
+ */
+const mswCore = async (loadMsw) => {
+    let module;
+    try {
+        module = await loadMsw();
+    }
+    catch (error) {
+        throw new Error("Answering a fetch with the story's mocks on a server needs MSW: npm install --save-dev msw", { cause: error });
+    }
+    if (!isMswCore(module))
+        throw new Error("The installed MSW has no getResponse: MSW 2.11 or later is needed");
+    return module;
+};
+/**
+ * Whether a request asks to skip the mocks and reach the network: MSW's `bypass()` adds this to its `accept` header. A
+ * handler's `fetch(bypass(request))` would otherwise come back to the same handler for ever.
+ *
+ * @param request - the request.
+ */
+const isBypass = (request) => request.headers.get("accept")?.includes("msw/passthrough") === true;
+/**
+ * Whether an answer is MSW's `passthrough()`: MSW marks it with this status and header, which its own
+ * `isPassthroughResponse` reads (exported from MSW 3 only).
+ *
+ * @param answer - a handler's answer.
+ */
+const isPassthrough = (answer) => answer.status === 302 && answer.headers.get("x-msw-intention") === "passthrough";
+/**
+ * What the story's handlers answer: none when they do not, or when the one that does sends the request on to the
+ * network, which a server render never reaches.
+ *
+ * @param mocks - the story's mocks.
+ * @param request - the request.
+ */
+const mockAnswer = async (mocks, request) => {
+    if (mocks.handlers.length === 0 || isBypass(request))
+        return undefined;
+    const { getResponse } = await mswCore(mocks.loadMsw);
+    const address = new URL(request.url);
+    // an address on this machine, whichever name or port, is the app's own: `/api/users` answers it as in the app
+    const baseUrl = isLoopback(address.hostname) ? address.origin : mocks.origin;
+    const answer = await getResponse([...mocks.handlers], request, { baseUrl });
+    return answer === undefined || isPassthrough(answer) ? undefined : answer;
+};
+/**
+ * The request a mocked redirect leads to, as `fetch` follows it: the same method and body for a 307 or a 308, a GET
+ * for a 303 and for a POST's 301 or 302; none when the answer is no redirect or the request does not follow one.
+ *
+ * @param answer - a handler's answer.
+ * @param request - the request it answered, its body unread.
+ * @throws a `TypeError` for a redirect a request with `redirect: "error"` gets, as `fetch` does.
+ */
+const redirectOf = (answer, request) => {
+    const location = answer.headers.get("location");
+    if (![301, 302, 303, 307, 308].includes(answer.status) || location === null)
+        return undefined;
+    if (request.redirect === "manual")
+        return undefined;
+    if (request.redirect === "error")
+        throw new TypeError(`Redirected to ${location}, which the request refuses`);
+    const target = new URL(location, request.url);
+    const isGet = answer.status === 303 || (request.method === "POST" && answer.status !== 307 && answer.status !== 308);
+    const next = isGet
+        ? new Request(target, { method: request.method === "HEAD" ? "HEAD" : "GET", headers: request.headers })
+        : new Request(target, request);
+    // an adapter may send this one to the network: another origin never gets the first one's credentials, as with `fetch`
+    if (target.origin !== new URL(request.url).origin)
+        for (const name of CREDENTIAL_HEADERS)
+            next.headers.delete(name);
+    return next;
+};
+/**
+ * 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 const mockedFetch = (mocks) => {
+    restoreHandlers(mocks.handlers);
+    const send = async (request, redirects) => {
+        if (mocks.isMocked?.(new URL(request.url)) === false)
+            return globalThis.fetch(request);
+        // kept for a redirect that sends the request again, body included, after a handler read it
+        const kept = request.clone();
+        const answer = await mockAnswer(mocks, request);
+        if (answer === undefined)
+            throw mocks.onUnanswered(request);
+        // MSW's mocked network error: `fetch` rejects, as it does in the frame
+        if (answer.type === "error")
+            throw new TypeError("Failed to fetch", { cause: answer });
+        const next = redirectOf(answer, kept);
+        if (next === undefined)
+            return answer;
+        if (redirects >= MOST_REDIRECTS)
+            throw new TypeError(`Too many redirects, the last to ${next.url}`);
+        return send(next, redirects + 1);
+    };
+    let waiting = 0;
+    return async (request) => {
+        if (waiting >= MOST_WAITING)
+            throw new TypeError(`${request.method} ${request.url}: a handler keeps fetching what it answers`);
+        waiting += 1;
+        try {
+            return await send(request, 0);
+        }
+        finally {
+            waiting -= 1;
+        }
+    };
+};

package/dist/src/vite/docsExtractor.d.ts

@@ -83,6 +83,11 @@ export type DocsWorkerData = {
     /** Whether its answers are kept on disk, so it stamps what each was read from; a build's are not. */
     readonly keepsAnswers: boolean;
 };
+/** What the worker says of its own, unasked: that its modules, the framework's docs module's included, are loaded. */
+export type DocsWorkerLoaded = {
+    /** The message's kind. */
+    readonly kind: "loaded";
+};
 /** How an extractor reads. */
 export type DocsExtractorOptions = {
     /** Whether every story's docs will be read, as in a build; a dev server's reads by default. */
@@ -94,6 +99,8 @@ export type DocsExtractorOptions = {
      * never ends before the build does.
      */
     readonly idleMs?: number;
+    /** How long ending the worker waits for its modules to load, in milliseconds; `LOAD_WAIT_MS` by default. */
+    readonly loadWaitMs?: number;
 };
 /**
  * How long a dev server's worker stays with nothing to do, in milliseconds, before it ends. Its programs are the
@@ -114,4 +121,4 @@ export declare const NO_DOCS_EXTRACTOR: DocsExtractor;
  * @param options - how it reads, and where it keeps what it read.
  * @returns the extractor.
  */
-export declare const createDocsExtractor: (docsModule: string, { readsEverything, cacheFolder, idleMs }?: DocsExtractorOptions) => DocsExtractor;
+export declare const createDocsExtractor: (docsModule: string, { readsEverything, cacheFolder, idleMs, loadWaitMs }?: DocsExtractorOptions) => DocsExtractor;

package/dist/src/vite/docsExtractor.js

@@ -10,7 +10,7 @@
  * the disk keeps no docs at all (a first start, a build), one warm-up at a time and only while nothing waits. For the
  * same reason a dev server's worker left with nothing to do ends (`IDLE_MS`), so the memory a first start took does
  * not stay with the server until it stops. Requests are answered in order. The worker never keeps the process alive
- * (`unref`), and `close` ends it when the build or the server ends.
+ * (`unref`), and `close` ends it when the build or the server ends, once its modules are loaded (`endOnceLoaded`).
  *
  * @module
  */
@@ -40,6 +40,11 @@ const YOUNG_GENERATION_MB = 8;
  * looks keeps them, renewed after each edit rather than built again (seconds, in a large monorepo).
  */
 export const IDLE_MS = 5 * 60_000;
+/**
+ * How long ending a worker waits for its modules to load, in milliseconds: well past a slow machine's load of the
+ * compiler, and a limit so that a docs module whose loading never ends cannot keep a server from closing.
+ */
+const LOAD_WAIT_MS = 30_000;
 /**
  * The worker's young generation in a build, in MB: a build reads every story's docs in one go, and with the dev
  * server's small one it would spend much of that time collecting garbage.
@@ -75,6 +80,28 @@ export const NO_DOCS_EXTRACTOR = {
     listed: () => undefined,
     close: () => Promise.resolve()
 };
+/**
+ * Ends a worker once its modules are loaded.
+ *
+ * @remarks
+ * Node 24 aborts the whole process when a worker is terminated while it reads the exports of a CommonJS module it
+ * imports, and the compiler is one: a command answered before the warm-up's worker had loaded would die with nothing
+ * printed. Past the loading, terminating is safe and stops a program being built at once, which a request to the worker
+ * to end by itself would have to wait for.
+ *
+ * @param worker - the worker.
+ * @param loaded - settled once its modules are loaded, or it has ended.
+ * @param waitMs - how long to wait for that, in milliseconds.
+ */
+const endOnceLoaded = async (worker, loaded, waitMs) => {
+    let limit;
+    const overLimit = new Promise((resolve) => {
+        limit = setTimeout(resolve, waitMs);
+    });
+    await Promise.race([loaded, overLimit]);
+    clearTimeout(limit);
+    await worker.terminate();
+};
 /**
  * A docs extractor with its worker, started on its first request.
  *
@@ -82,7 +109,7 @@ export const NO_DOCS_EXTRACTOR = {
  * @param options - how it reads, and where it keeps what it read.
  * @returns the extractor.
  */
-export const createDocsExtractor = (docsModule, { readsEverything = false, cacheFolder, idleMs = IDLE_MS } = {}) => {
+export const createDocsExtractor = (docsModule, { readsEverything = false, cacheFolder, idleMs = IDLE_MS, loadWaitMs = LOAD_WAIT_MS } = {}) => {
     // the code that writes the answers: this package's and the framework's docs, whose edit or new version is a miss
     const code = cacheFolder === undefined ? undefined : codeStampOf(docsModule);
     const cacheOf = (kind, isValue) => cacheFolder === undefined || code === undefined
@@ -91,6 +118,8 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
     const docsCache = cacheOf("docs", isKeptDocs);
     const usageCache = cacheOf("usage", isKeptUsage);
     let worker;
+    // settled once the current worker's modules are loaded, or it has ended
+    let workerLoaded = Promise.resolve();
     let nextId = 0;
     // the changes the watcher reported: an answer read across one may have read a file before it changed, so it is not kept
     let changes = 0;
@@ -103,17 +132,23 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
     // the warm-ups not sent yet: one goes out only when nothing is pending, so a read never waits behind them all
     const warmUps = [];
     let idle;
+    // every ending under way: a second close must wait for the first's too, as a process may exit once it resolves
+    let ending = Promise.resolve();
+    // lets the current worker go, so the next request starts another, and ends it
+    const endWorker = async () => {
+        const running = worker;
+        worker = undefined;
+        if (running !== undefined)
+            ending = Promise.all([ending, endOnceLoaded(running, workerLoaded, loadWaitMs)]);
+        await ending;
+    };
     // ends the worker once nothing is asked of it for a while; a request in the meantime keeps it
     const stopWhenIdle = () => {
         clearTimeout(idle);
         // a build reads every story, and a quiet stretch in it would build every program again
         if (readsEverything || pending.size > 0 || warmUps.length > 0)
             return;
-        idle = setTimeout(() => {
-            const running = worker;
-            worker = undefined;
-            void running?.terminate();
-        }, idleMs);
+        idle = setTimeout(() => void endWorker(), idleMs);
         idle.unref();
     };
     const sendWarmUp = () => {
@@ -135,7 +170,16 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
             }
         });
         created.unref();
+        workerLoaded = new Promise((resolve) => {
+            created.on("message", (message) => {
+                if (message.kind === "loaded")
+                    resolve();
+            });
+            created.once("exit", () => resolve());
+        });
         created.on("message", (response) => {
+            if (response.kind === "loaded")
+                return;
             pending.get(response.id)?.(response);
             pending.delete(response.id);
             sendWarmUp();
@@ -229,10 +273,8 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
         },
         close: async () => {
             clearTimeout(idle);
-            const running = worker;
-            worker = undefined;
             warmUps.length = 0;
-            await running?.terminate();
+            await endWorker();
         }
     };
 };

package/dist/src/vite/docsWorker.js

@@ -17,7 +17,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * read builds one, and a changed source file (`{ kind: "changed" }`) renews them on their next read. A usage request
  * (`{ kind: "usage", id, files }`) is answered from the same programs (`usageGraph.ts`). A request is `{ id, storyFile }`, the answer `{ id, result }`, `extractStoryComponent`'s result as
  * it is (plain data), with the files it can change with (`docsDependencies.ts`), which the dev server keeps it on disk
- * with.
+ * with. Unasked, it says `{ kind: "loaded" }` once its modules are loaded.
  *
  * @module
  */
@@ -55,6 +55,11 @@ if (isWorkerData(workerData) && !workerData.readsEverything)
     readAskedFilesOnly();
 /** The framework's docs module, loaded once, before the first answer. */
 const docsModule = loadDocsModule();
+// the extractor waits for this before it ends the thread: `endOnceLoaded` says why
+void docsModule.then(() => {
+    const loaded = { kind: "loaded" };
+    parentPort?.postMessage(loaded);
+});
 /** The extractor's result, or why it threw: a throw would end the worker and every request waiting on it. */
 const extracted = async (storyFile) => {
     const module = await docsModule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgebook",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "See every component in every theme, contrast, language and width: CSF stories, one frame per story, and a props table from the components' types.",
   "keywords": [
     "react",
@@ -232,6 +232,10 @@
     "./code-literal": {
       "types": "./dist/src/codeLiteral.d.ts",
       "default": "./dist/src/codeLiteral.js"
+    },
+    "./story-mocks": {
+      "types": "./dist/src/storyMocks.d.ts",
+      "default": "./dist/src/storyMocks.js"
     }
   },
   "dependencies": {
@@ -240,7 +244,7 @@
     "lightningcss": "1.33.0",
     "marked": "18.1.0",
     "typescript-6": "npm:typescript@6.0.3",
-    "@forgebook/story-format": "0.2.2"
+    "@forgebook/story-format": "0.2.3"
   },
   "peerDependencies": {
     "@testing-library/dom": "^10.4.0",
@@ -248,7 +252,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "sass-embedded": "^1.80.0",
-    "vite": "^8.0.0"
+    "vite": "^8.3.4"
   },
   "devDependencies": {
     "@testing-library/dom": "10.4.2",