forgebook 0.3.3 → 0.4.0

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

@@ -0,0 +1,39 @@
+/**
+ * What a story's tags draw, as one chunk loaded the first time one of them is drawn (`tagView.tsx`): the tag filter and
+ * the statuses' badges, which share their reading of the catalogue's statuses.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { TreeComponent, TreeStory } from "../storyTree.ts";
+import { type TagFilterProps } from "./TagFilter.tsx";
+/** One place the tags draw in, and what it reads. */
+export type TagViewProps = ({
+    /** The sidebar's tag filter. */
+    readonly place: "filter";
+} & TagFilterProps) | {
+    /** A component's entry in the sidebar: its meta's statuses. */
+    readonly place: "entry";
+    /** The component. */
+    readonly component: TreeComponent;
+} | {
+    /** The top of a component's page: its meta's statuses, and `deprecated` when its TSDoc says so. */
+    readonly place: "page";
+    /** The component. */
+    readonly component: TreeComponent;
+    /** Loads its docs; none when the source has none for its file. */
+    readonly loadDocs: (() => Promise<unknown>) | undefined;
+} | {
+    /** A story's example on its component's page: the statuses it holds that its component's meta does not. */
+    readonly place: "story";
+    /** The story. */
+    readonly story: TreeStory;
+    /** Its component. */
+    readonly component: TreeComponent;
+};
+/**
+ * What the tags draw in a place.
+ *
+ * @param props - the place, and what it reads.
+ */
+export declare const TagView: (props: TagViewProps) => ReactNode;

package/dist/src/shell/TagViews.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ComponentBadges, StatusBadges } from "./StatusBadges.js";
+import { TagFilter } from "./TagFilter.js";
+/**
+ * What the tags draw in a place.
+ *
+ * @param props - the place, and what it reads.
+ */
+export const TagView = (props) => {
+    switch (props.place) {
+        case "filter":
+            return _jsx(TagFilter, { tree: props.tree, tags: props.tags, onTagsChange: props.onTagsChange });
+        case "entry":
+            return _jsx(StatusBadges, { tags: props.component.tags, className: "forgebook-status-badges" });
+        case "page":
+            return _jsx(ComponentBadges, { component: props.component, loadDocs: props.loadDocs });
+        case "story":
+            return (_jsx(StatusBadges, { tags: props.story.tags.filter((tag) => !props.component.tags.includes(tag)), className: "forgebook-status-badges forgebook-status-badges--story" }));
+    }
+};

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

@@ -13,6 +13,7 @@ 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";
+import type { ControlContext } from "./ToolbarControl.tsx";
 /** The toolbar's props. */
 export type ToolbarProps = {
     /** The view. */
@@ -35,6 +36,8 @@ export type ToolbarProps = {
     readonly isLogic?: boolean;
     /** The page's default device: the shown story's, or the catalogue's on a component's page; none by default. */
     readonly deviceDefault?: DeviceDefault;
+    /** Loads the catalogue's previews for a gallery; none when it gives none. */
+    readonly loadSwitchPreviews?: ControlContext["loadSwitchPreviews"];
 };
 /**
  * The button that shows the hidden sidebar, at the toolbar's start; the home's bar holds only it.
@@ -49,4 +52,4 @@ export declare const ShowSidebarButton: ({ onShowSidebar, showSidebarRef }: Pick
  *
  * @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, showSidebarRef, shownWidth, fixed, isLogic, deviceDefault }: ToolbarProps) => ReactNode;
+export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, isComponentPage, onShowSidebar, showSidebarRef, shownWidth, fixed, isLogic, deviceDefault, loadSwitchPreviews }: ToolbarProps) => ReactNode;

package/dist/src/shell/Toolbar.js

@@ -13,7 +13,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId, useRef } from "react";
 import { NO_DEVICE } from "../deviceView.js";
 import { NOT_FIXED, withFixed, withOwnFixed } from "../storyGlobals.js";
-import { switchWithRole } from "../switches.js";
+import { impliedSwitches, switchWithRole } from "../switches.js";
 import { hasViewChanges, isComparing } from "../viewState.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { Icon } from "./icons.js";
@@ -58,14 +58,15 @@ const compareChoices = (catalogue) => {
  * @param props - the view, its setter, and whether the page compares at all.
  */
 const CompareMenu = ({ view, onViewChange, isDisabled, fixed = NOT_FIXED }) => {
-    const { isOpen, isDrawn, setIsOpen, buttonRef, panelRef, panelId } = usePopover();
+    const { isOpen, isDrawn, setIsOpen, closeAfterChoice, buttonRef, panelRef, panelId } = usePopover();
     const catalogue = useCatalogue();
     const name = useId();
     return (_jsxs("div", { className: "forgebook-view-menu", children: [_jsxs("button", { ref: buttonRef, type: "button", className: "forgebook-button", title: STRINGS.compare, "aria-pressed": isComparing(view), "aria-expanded": isOpen, "aria-controls": panelId, disabled: isDisabled, onClick: (event) => setIsOpen(!isOpen, event), children: [_jsx(Icon, { name: "compare", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: STRINGS.compare }), _jsx(Icon, { name: "chevronDown", size: 12 })] }), isDrawn ? (_jsx("div", { ref: panelRef, id: panelId, className: "forgebook-popover forgebook-popover--end", role: "dialog", "aria-label": STRINGS.compare, children: _jsxs("fieldset", { className: "forgebook-choices", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: STRINGS.compare }), compareChoices(catalogue).map((choice) => (_jsxs("label", { className: "forgebook-choice", children: [_jsx("input", { type: "radio", name: name, 
-                                    // a switch the story fixes would draw the same story in every cell
-                                    disabled: choice.axes.some((axis) => fixed.switches[axis] !== undefined), checked: view.compare.join(",") === choice.axes.join(","), onChange: () => {
+                                    // a switch the story fixes, or another switch's value implies, would draw the same in every cell
+                                    disabled: choice.axes.some((axis) => fixed.switches[axis] !== undefined ||
+                                        impliedSwitches(view.switches, catalogue.switches).has(axis)), checked: view.compare.join(",") === choice.axes.join(","), onChange: () => {
                                         onViewChange({ ...view, compare: choice.axes });
-                                        setIsOpen(false);
+                                        closeAfterChoice();
                                     } }), choice.label] }, choice.axes.join(","))))] }) })) : null] }));
 };
 /**
@@ -79,13 +80,22 @@ export const ShowSidebarButton = ({ onShowSidebar, showSidebarRef }) => (_jsx("b
  *
  * @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, showSidebarRef, 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, loadSwitchPreviews }) => {
     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
     const view = withFixed(ownView, fixed);
     const onViewChange = (changed) => onOwnViewChange(withOwnFixed(changed, ownView, fixed));
-    const context = { view, onViewChange, isStoryPage, isComponentPage, fixed, shownWidth, deviceDefault };
+    const context = {
+        view,
+        onViewChange,
+        isStoryPage,
+        isComponentPage,
+        fixed,
+        shownWidth,
+        deviceDefault,
+        loadSwitchPreviews
+    };
     useControlKeys({ keys: layout.keys, view, onViewChange, fixed, isStoryPage, isComponentPage });
     const pinnedRef = useRef(null);
     // a page about logic puts away the pinned controls that only change looks: the View menu then counts them

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

@@ -15,6 +15,7 @@ import { type DeviceDefault } from "../deviceView.ts";
 import type { FixedView } from "../storyGlobals.ts";
 import type { ToolbarControl as Control } from "../toolbarLayout.ts";
 import { type ViewState } from "../viewState.ts";
+import type { SwitchPreviews } from "./SwitchGalleryPanel.tsx";
 /** Where a control is drawn: on the toolbar, or in a row of the View menu. */
 export type ControlForm = "bar" | "row";
 /** What every control reads and sets. */
@@ -33,6 +34,8 @@ export type ControlContext = {
     readonly shownWidth: number | undefined;
     /** The page's default device: the shown story's, or the catalogue's on a component's page. */
     readonly deviceDefault: DeviceDefault;
+    /** Loads the catalogue's previews for a gallery; none when it gives none. */
+    readonly loadSwitchPreviews: (() => Promise<SwitchPreviews>) | undefined;
 };
 /**
  * One control, drawn for where it sits.

package/dist/src/shell/ToolbarControl.js

@@ -14,15 +14,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from "react";
 import { AUDIENCE_IDS } from "../audiences.js";
 import { DEVICE_PARAMETER, shownDevice } from "../deviceView.js";
-import { switchControl } from "../switches.js";
+import { impliedSwitches, switchControl } from "../switches.js";
 import { isComparing, PLAIN_BACKDROP, SHEETS_CHOICES } from "../viewState.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { DeviceControl } from "./DeviceControl.js";
 import { Icon } from "./icons.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
 import { Segmented } from "./Segmented.js";
 import { STRINGS } from "./strings.js";
 import { switchValueIn, withSwitch } from "./switchView.js";
 import { WidthField } from "./WidthField.js";
+/** A switch's gallery, loaded with the first catalogue's switch that has one: most catalogues have none. */
+const SWITCH_GALLERY = lazyModule(() => import("./SwitchGallery.js").then((module) => module.SwitchGallery));
 /** The icon of each scheme a colour scheme switch's values draw in. */
 const SCHEME_ICONS = {
     light: "sun",
@@ -69,14 +72,28 @@ const FormChoice = ({ form, isList, ...choice }) => {
  *
  * @param props - the switch, its form, and what every control shares.
  */
-const SwitchControl = ({ each, form, view, onViewChange, isStoryPage, fixed }) => {
+const SwitchControl = ({ each, form, view, onViewChange, isStoryPage, fixed, loadSwitchPreviews }) => {
+    const { switches } = useCatalogue();
+    const implied = impliedSwitches(view.switches, switches).get(each.id);
     const isFixed = fixed.switches[each.id] !== undefined;
-    const isDisabled = (isStoryPage && view.compare.includes(each.id)) || isFixed;
-    const disabledNote = isFixed ? STRINGS.setByStory : undefined;
-    const value = switchValueIn(view, each);
+    const isDisabled = (isStoryPage && view.compare.includes(each.id)) || isFixed || implied !== undefined;
+    const storyNote = isFixed ? STRINGS.setByStory : undefined;
+    const disabledNote = implied === undefined ? storyNote : STRINGS.setBy.replace("{value}", implied.by.label);
+    const value = implied?.value ?? switchValueIn(view, each);
     const choose = (chosen) => onViewChange(withSwitch(view, each, chosen));
     const more = each.values.find((option) => option.isMore === true);
     const standard = each.values.find((option) => option.isMore !== true);
+    if (switchControl(each) === "gallery") {
+        return (_jsx(LazyView, { module: SWITCH_GALLERY, props: {
+                each,
+                isOnBar: form === "bar",
+                value,
+                onValueChange: choose,
+                isDisabled,
+                disabledNote,
+                loadPreviews: loadSwitchPreviews
+            }, loading: null, failed: (message) => (_jsx("p", { className: "forgebook-problems", role: "alert", children: message })) }));
+    }
     if (form === "bar" && each.role === "colorScheme") {
         return (_jsx(Segmented, { label: each.label, isDisabled: isDisabled, disabledNote: disabledNote, options: each.values.map((option) => ({
                 value: option.value,
@@ -85,7 +102,7 @@ const SwitchControl = ({ each, form, view, onViewChange, isStoryPage, fixed }) =
             })), value: value, onValueChange: choose }));
     }
     if (form === "bar" && each.role === "contrast" && more !== undefined && standard !== undefined) {
-        return (_jsxs("button", { type: "button", className: "forgebook-button", title: isFixed ? STRINGS.setByStory : each.label, "aria-pressed": value === more.value, disabled: isDisabled, onClick: () => choose(value === more.value ? standard.value : more.value), children: [_jsx(Icon, { name: "contrast", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: each.label })] }));
+        return (_jsxs("button", { type: "button", className: "forgebook-button", title: disabledNote ?? each.label, "aria-pressed": value === more.value, disabled: isDisabled, onClick: () => choose(value === more.value ? standard.value : more.value), children: [_jsx(Icon, { name: "contrast", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: each.label })] }));
     }
     return (_jsx(FormChoice, { form: form, isList: switchControl(each) === "list", label: each.label, options: each.values.map((option) => ({ value: option.value, label: option.label })), value: value, onValueChange: choose, isDisabled: isDisabled, disabledNote: disabledNote }));
 };

package/dist/src/shell/ViewMenuPanel.js

@@ -20,6 +20,7 @@ import { controlLabel } from "./controlLabel.js";
 import { Icon } from "./icons.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { NamedViews } from "./NamedViews.js";
+import { rememberPlay } from "./playMemory.js";
 /** How long the rows take to move out of a dragged row's way, in ms: the shell's `$duration-quick`. */
 const SHIFT_MS = 150;
 /** How they move: the shell's `$ease-out`, decelerating. */
@@ -195,5 +196,9 @@ export const ViewMenuPanel = ({ layout, ownView, movedIds, ids, drawControl, ...
         window.addEventListener("pointerup", drop);
         window.addEventListener("pointercancel", drop);
     };
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "forgebook-popover__body", children: [_jsx(NamedViews, { view: context.view, ownView: ownView, onViewChange: context.onViewChange }), _jsx("ol", { ref: listRef, className: "forgebook-arrange-list", "data-dragging": draggedId === undefined ? undefined : "", children: shown.map((each, index) => (_jsx(ControlRow, { each: each, index: index, count: shown.length, isDragged: each.control.id === draggedId, isMoved: movedIds.includes(each.control.id), isChanged: hasViewChanges(ownView, switches, [each.control.id], catalogue.audience), layout: layout, hintId: hintId, onGrab: grab, onAnnounce: setAnnounced, drawControl: drawControl }, each.control.id))) }), _jsx("span", { id: hintId, className: "forgebook-visually-hidden", children: LATER_STRINGS.moveControlHint }), _jsx("span", { className: "forgebook-visually-hidden", "aria-live": "polite", children: announced }), _jsx(HiddenControls, { hidden: hidden, layout: layout, drawControl: drawControl }), _jsxs("label", { className: "forgebook-wrap-choice", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": layout.isWrapped, className: "forgebook-switch", checked: layout.isWrapped, onChange: (event) => layout.setIsWrapped(event.currentTarget.checked) }), LATER_STRINGS.wrapToolbar] })] }), _jsxs("div", { className: "forgebook-popover__foot", children: [_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => context.onViewChange(withDefaults(context.view, switches, ids, catalogue.audience)), children: LATER_STRINGS.resetView }), _jsx("button", { type: "button", className: "forgebook-text-button", title: LATER_STRINGS.toolbarInBrowser, disabled: !layout.isArranged, onClick: layout.reset, children: LATER_STRINGS.resetToolbar }), _jsx("span", { className: "forgebook-popover__note", children: LATER_STRINGS.viewInAddress })] })] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "forgebook-popover__body", children: [_jsx(NamedViews, { view: context.view, ownView: ownView, onViewChange: context.onViewChange }), _jsx("ol", { ref: listRef, className: "forgebook-arrange-list", "data-dragging": draggedId === undefined ? undefined : "", children: shown.map((each, index) => (_jsx(ControlRow, { each: each, index: index, count: shown.length, isDragged: each.control.id === draggedId, isMoved: movedIds.includes(each.control.id), isChanged: hasViewChanges(ownView, switches, [each.control.id], catalogue.audience), layout: layout, hintId: hintId, onGrab: grab, onAnnounce: setAnnounced, drawControl: drawControl }, each.control.id))) }), _jsx("span", { id: hintId, className: "forgebook-visually-hidden", children: LATER_STRINGS.moveControlHint }), _jsx("span", { className: "forgebook-visually-hidden", "aria-live": "polite", children: announced }), _jsx(HiddenControls, { hidden: hidden, layout: layout, drawControl: drawControl }), _jsxs("label", { className: "forgebook-wrap-choice", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": layout.isWrapped, className: "forgebook-switch", checked: layout.isWrapped, onChange: (event) => layout.setIsWrapped(event.currentTarget.checked) }), LATER_STRINGS.wrapToolbar] }), _jsxs("label", { className: "forgebook-wrap-choice", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": context.view.play === "on", className: "forgebook-switch", checked: context.view.play === "on", onChange: (event) => {
+                                    const play = event.currentTarget.checked ? "on" : "off";
+                                    rememberPlay(catalogue, play);
+                                    context.onViewChange({ ...context.view, play });
+                                } }), LATER_STRINGS.playOnOpen] })] }), _jsxs("div", { className: "forgebook-popover__foot", children: [_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => context.onViewChange(withDefaults(context.view, switches, ids, catalogue.audience)), children: LATER_STRINGS.resetView }), _jsx("button", { type: "button", className: "forgebook-text-button", title: LATER_STRINGS.toolbarInBrowser, disabled: !layout.isArranged, onClick: layout.reset, children: LATER_STRINGS.resetToolbar }), _jsx("span", { className: "forgebook-popover__note", children: LATER_STRINGS.viewInAddress })] })] }));
 };

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

@@ -0,0 +1,22 @@
+/**
+ * What `checkedAddressArgs` needs for a story's structured values, loaded with the first story that has one: what reads a
+ * shape, the worst case of one, and the schemas of the custom controls it names. A catalogue of plain props never asks for
+ * this; one with no custom control never loads theirs.
+ *
+ * @module
+ */
+import type { ArgChecks } from "../addressArgs.ts";
+import { worstOfShape } from "../shapeValues.ts";
+import type { ArgControlLoaders } from "./customControls.ts";
+/** What the stage holds of it. */
+export type LoadedChecks = ArgChecks & {
+    /** A shape's worst value. */
+    readonly worstOfShape: typeof worstOfShape;
+};
+/**
+ * The checks for a story.
+ *
+ * @param names - the custom controls it names.
+ * @param loaders - the catalogue's custom controls.
+ */
+export declare const loadedChecks: (names: readonly string[], loaders: ArgControlLoaders) => Promise<LoadedChecks>;

package/dist/src/shell/argChecks.js

@@ -0,0 +1,20 @@
+import { isFileList, isValueOfShape, worstOfShape } from "../shapeValues.js";
+/**
+ * The checks for a story.
+ *
+ * @param names - the custom controls it names.
+ * @param loaders - the catalogue's custom controls.
+ */
+export const loadedChecks = async (names, loaders) => {
+    const checks = { isFileList, isValueOfShape, worstOfShape };
+    if (names.length === 0)
+        return checks;
+    try {
+        const { customChecksOf } = await import("./customControls.js");
+        return { ...checks, custom: await customChecksOf(names, loaders) };
+    }
+    catch {
+        // a page left open across a new build: a control that cannot load refuses its values, as one that fails does
+        return checks;
+    }
+};

package/dist/src/shell/asideStory.js

@@ -29,7 +29,8 @@ export const showAsideStory = (target, title, aside) => {
         frame.setAttribute("sandbox", sandbox);
     frame.setAttribute(FRAME_ASIDE_ATTRIBUTE, "");
     // a width set on the stage holds as far as the room allows
-    frame.style.cssText = "display:block;max-width:100%;height:100%;margin-inline:auto;border:0";
+    frame.style.cssText =
+        "display:block;max-width:100%;height:100%;margin-inline:auto;border:0;color-scheme:light";
     frame.style.width = aside.width === "fill" ? "100%" : `${aside.width}px`;
     if (aside.background !== undefined)
         target.style.backgroundColor = aside.background;
@@ -40,7 +41,11 @@ export const showAsideStory = (target, title, aside) => {
         const story = frame.contentWindow;
         if (!isFromFrames(event) || event.source !== story || story === null)
             return;
-        if (!isFrameMessage(event.data) || event.data.type !== "forgebook:ready")
+        if (!isFrameMessage(event.data))
+            return;
+        if (event.data.type === "forgebook:scheme")
+            frame.style.colorScheme = event.data.scheme;
+        if (event.data.type !== "forgebook:ready")
             return;
         isReady = true;
         if (args !== undefined)

package/dist/src/shell/audienceSections.css

@@ -8,11 +8,11 @@
     display: grid;
     align-content: start;
     gap: 0.5rem;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
   }
   .forgebook-guidance__list h3 {
     margin: 0;
-    font: 600 0.6875rem/1.3 var(--forgebook-font-sans);
+    font: var(--forgebook-text-label);
     color: var(--forgebook-text-tertiary);
   }
   .forgebook-guidance__list ul {
@@ -23,7 +23,7 @@
   }
   .forgebook-guidance__deprecated {
     margin: 0;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
   }
   .forgebook-about-pages {
     display: grid;
@@ -31,21 +31,21 @@
     margin: 0;
     padding: 0;
     list-style: none;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
   }
   .forgebook-about-pages li {
     display: grid;
     gap: 0.25rem;
   }
   .forgebook-about-pages__description {
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-token {
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    font: 400 0.71875rem/1.4 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono);
   }
   .forgebook-token__swatch {
     flex: none;
@@ -57,7 +57,7 @@
   .forgebook-tokens__others {
     display: grid;
     gap: 0.5rem;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-tokens__others > summary {
@@ -72,12 +72,12 @@
   }
   .forgebook-coverage__summary {
     margin: 0;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-coverage__progress {
     margin: 0;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-tertiary);
   }
   .forgebook-coverage__progress:empty {

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

@@ -25,4 +25,4 @@ export declare const useConfiguredCatalogue: ({ title, switches, languages, list
     readonly languages?: readonly StoryLanguage[];
     readonly lists?: CatalogueLists;
     readonly plugins?: readonly ShellPlugin[];
-}) => CatalogueSettings;
+}, readStored?: (key: string) => string | null) => CatalogueSettings;

package/dist/src/shell/catalogueContext.js

@@ -14,4 +14,9 @@ export const NO_PLUGINS = [];
  *
  * @param config - its name, its switches, its languages, its lists and its plugins (whose tabs it may turn off).
  */
-export const useConfiguredCatalogue = ({ title, switches, languages = NO_LANGUAGES, lists, plugins = NO_PLUGINS }) => useMemo(() => catalogueSettings(title, catalogueSwitches(switches, languages, lists?.controls), lists, plugins.flatMap((plugin) => plugin.tabs.map((tab) => tab.id))), [title, switches, languages, lists, plugins]);
+export const useConfiguredCatalogue = ({ title, switches, languages = NO_LANGUAGES, lists, plugins = NO_PLUGINS }, readStored) => useMemo(() => {
+    const settings = catalogueSettings(title, catalogueSwitches(switches, languages, lists?.controls), lists, plugins.flatMap((plugin) => plugin.tabs.map((tab) => tab.id)));
+    // a reader's choice stands in for the catalogue's default on their own pages; an address that names one comes first
+    const remembered = readStored?.(`${settings.id}:play`);
+    return remembered === "on" || remembered === "off" ? { ...settings, readerPlay: remembered } : settings;
+}, [title, switches, languages, lists, plugins, readStored]);

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

@@ -0,0 +1,27 @@
+/**
+ * A sentence's code spans, read as CommonMark reads them: a run of backticks opens a span that the next run of the same
+ * length closes, so a span holding a backtick is written with a longer run of them. Used by `CodeText.tsx`, and by
+ * what writes a sentence around a type that may hold backticks (a template literal type).
+ *
+ * @module
+ */
+/** One piece of a sentence: text, or code. */
+export type SentencePiece = {
+    /** The piece's text, a code span's without its backticks. */
+    readonly text: string;
+    /** Whether it is code. */
+    readonly isCode: boolean;
+};
+/**
+ * A sentence split into text and code spans. A run of backticks no run of the same length closes stays text.
+ *
+ * @param sentence - the sentence.
+ */
+export declare const sentencePieces: (sentence: string) => SentencePiece[];
+/**
+ * A text written as one code span, whatever backticks it holds: a run longer than any inside, with a space each side
+ * when the text starts or ends with a backtick.
+ *
+ * @param text - the code.
+ */
+export declare const codeSpan: (text: string) => string;

package/dist/src/shell/codeSpans.js

@@ -0,0 +1,76 @@
+/**
+ * A sentence's code spans, read as CommonMark reads them: a run of backticks opens a span that the next run of the same
+ * length closes, so a span holding a backtick is written with a longer run of them. Used by `CodeText.tsx`, and by
+ * what writes a sentence around a type that may hold backticks (a template literal type).
+ *
+ * @module
+ */
+/** A code span's text as CommonMark trims it: one space each side, when both are there and it is not only spaces. */
+const trimmedSpan = (text) => text.length >= 2 && text.startsWith(" ") && text.endsWith(" ") && text.trim() !== ""
+    ? text.slice(1, -1)
+    : text;
+/**
+ * A sentence split into text and code spans. A run of backticks no run of the same length closes stays text.
+ *
+ * @param sentence - the sentence.
+ */
+export const sentencePieces = (sentence) => {
+    const pieces = [];
+    let text = "";
+    let at = 0;
+    while (at < sentence.length) {
+        const open = sentence.indexOf("`", at);
+        if (open === -1)
+            break;
+        let length = 1;
+        while (sentence[open + length] === "`")
+            length += 1;
+        const close = closingRun(sentence, open + length, length);
+        if (close === -1) {
+            text += sentence.slice(at, open + length);
+            at = open + length;
+            continue;
+        }
+        text += sentence.slice(at, open);
+        if (text !== "")
+            pieces.push({ text, isCode: false });
+        text = "";
+        pieces.push({ text: trimmedSpan(sentence.slice(open + length, close)), isCode: true });
+        at = close + length;
+    }
+    text += sentence.slice(at);
+    if (text !== "")
+        pieces.push({ text, isCode: false });
+    return pieces;
+};
+/**
+ * Where the run of exactly `length` backticks that closes a span starts, or -1.
+ *
+ * @param sentence - the sentence.
+ * @param from - where the span's text starts.
+ * @param length - the opening run's length.
+ */
+const closingRun = (sentence, from, length) => {
+    let at = sentence.indexOf("`", from);
+    while (at !== -1) {
+        let run = 1;
+        while (sentence[at + run] === "`")
+            run += 1;
+        if (run === length)
+            return at;
+        at = sentence.indexOf("`", at + run);
+    }
+    return -1;
+};
+/**
+ * A text written as one code span, whatever backticks it holds: a run longer than any inside, with a space each side
+ * when the text starts or ends with a backtick.
+ *
+ * @param text - the code.
+ */
+export const codeSpan = (text) => {
+    const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+    const fence = "`".repeat(longest + 1);
+    const padding = text.startsWith("`") || text.endsWith("`") ? " " : "";
+    return `${fence}${padding}${text}${padding}${fence}`;
+};

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

@@ -6,7 +6,8 @@
  * Every value of a switch is drawn, its default too, so the frames show where the story starts; only the colour
  * scheme's system value is left out, since it draws as light or as dark, one of the others. A value that writes
  * nothing on the root (`isUnset`: the stories' own text, left to right, the mouse) is a value like the rest. In a pair, a cell's label leaves out the second switch's default (`Light`, `Light · More contrast`), so the familiar
- * value reads alone. Pure.
+ * value reads alone. A cell another switch's value contradicts is left out (a look drawn only for dark, at light): it
+ * would draw the same as the cell of the implied value, under a name that is not what it shows. Pure.
  *
  * @module
  */
@@ -31,5 +32,6 @@ export type CompareVariant = {
  *
  * @param axes - the compared axes.
  * @param catalogue - the catalogue's switches and text sizes.
+ * @param view - the stage's view, whose other switches may imply a compared one.
  */
-export declare const compareVariants: (axes: CompareAxes, catalogue: CompareCatalogue) => CompareVariant[];
+export declare const compareVariants: (axes: CompareAxes, catalogue: CompareCatalogue, view: ViewState) => CompareVariant[];

package/dist/src/shell/compareVariants.js

@@ -6,10 +6,12 @@
  * Every value of a switch is drawn, its default too, so the frames show where the story starts; only the colour
  * scheme's system value is left out, since it draws as light or as dark, one of the others. A value that writes
  * nothing on the root (`isUnset`: the stories' own text, left to right, the mouse) is a value like the rest. In a pair, a cell's label leaves out the second switch's default (`Light`, `Light · More contrast`), so the familiar
- * value reads alone. Pure.
+ * value reads alone. A cell another switch's value contradicts is left out (a look drawn only for dark, at light): it
+ * would draw the same as the cell of the implied value, under a name that is not what it shows. Pure.
  *
  * @module
  */
+import { shownSwitches } from "../switches.js";
 import { SHEETS_CHOICES } from "../viewState.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { STRINGS } from "./strings.js";
@@ -54,16 +56,22 @@ const axisVariants = (axis, catalogue) => {
  *
  * @param axes - the compared axes.
  * @param catalogue - the catalogue's switches and text sizes.
+ * @param view - the stage's view, whose other switches may imply a compared one.
  */
-export const compareVariants = (axes, catalogue) => {
+export const compareVariants = (axes, catalogue, view) => {
     const [first, second] = axes;
     if (first === undefined)
         return [];
     const firsts = axisVariants(first, catalogue);
-    if (second === undefined)
-        return firsts;
-    return axisVariants(second, catalogue).flatMap((outer) => firsts.map((inner) => ({
-        label: LATER_STRINGS.compareCell(outer.isDefault ? [inner.label] : [inner.label, outer.label]),
-        viewOf: (view) => outer.viewOf(inner.viewOf(view))
-    })));
+    const cells = second === undefined
+        ? firsts
+        : axisVariants(second, catalogue).flatMap((outer) => firsts.map((inner) => ({
+            label: LATER_STRINGS.compareCell(outer.isDefault ? [inner.label] : [inner.label, outer.label]),
+            viewOf: (stage) => outer.viewOf(inner.viewOf(stage))
+        })));
+    return cells.filter((cell) => {
+        const { switches } = cell.viewOf(view);
+        const shown = shownSwitches(switches, catalogue.switches);
+        return axes.every((axis) => shown[axis] === switches[axis]);
+    });
 };

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

@@ -0,0 +1,23 @@
+/**
+ * Whether this catalogue composes others (`refs`): a constant the plugin writes into the build (`define`), so a
+ * catalogue that composes none has every part of composition removed from its shell, and its first load carries none of
+ * it. And the composed catalogues themselves, set by `mountShell` behind that constant: a page holds one shell, so they
+ * are a fact of the page, as the frames' origin is, and a shell that composes none keeps not even their name.
+ *
+ * @remarks
+ * Read as a value that may be missing, so a shell bundled by something other than Forgebook's plugin (a test) runs with
+ * composition off rather than failing on a name nobody defined.
+ *
+ * @module
+ */
+import type { ShellRefs } from "./refParts.tsx";
+/** Whether this catalogue composes others. */
+export declare const HAS_REFS: boolean;
+/**
+ * Sets the composed catalogues, before the shell renders.
+ *
+ * @param refs - the composed catalogues, if the generated page gives any.
+ */
+export declare const setShellRefs: (refs: ShellRefs | undefined) => void;
+/** The composed catalogues; none until `mountShell` set them, or for a catalogue that composes none. */
+export declare const shellRefs: () => ShellRefs | undefined;

package/dist/src/shell/composition.js

@@ -0,0 +1,26 @@
+/**
+ * Whether this catalogue composes others (`refs`): a constant the plugin writes into the build (`define`), so a
+ * catalogue that composes none has every part of composition removed from its shell, and its first load carries none of
+ * it. And the composed catalogues themselves, set by `mountShell` behind that constant: a page holds one shell, so they
+ * are a fact of the page, as the frames' origin is, and a shell that composes none keeps not even their name.
+ *
+ * @remarks
+ * Read as a value that may be missing, so a shell bundled by something other than Forgebook's plugin (a test) runs with
+ * composition off rather than failing on a name nobody defined.
+ *
+ * @module
+ */
+/** Whether this catalogue composes others. */
+export const HAS_REFS = typeof __FORGEBOOK_REFS__ !== "undefined" && __FORGEBOOK_REFS__ === true;
+/** The composed catalogues, once `mountShell` set them. */
+let pageRefs;
+/**
+ * Sets the composed catalogues, before the shell renders.
+ *
+ * @param refs - the composed catalogues, if the generated page gives any.
+ */
+export const setShellRefs = (refs) => {
+    pageRefs = refs;
+};
+/** The composed catalogues; none until `mountShell` set them, or for a catalogue that composes none. */
+export const shellRefs = () => pageRefs;

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

@@ -4,7 +4,7 @@
  *
  * @remarks
  * Pure. A control its toolbar control leaves disabled is left as it is here too: a switch or a background the story
- * fixes (or a width), and a control the compare view draws side by side.
+ * fixes (or a width), a switch another switch's value implies, and a control the compare view draws side by side.
  *
  * @module
  */