forgebook 0.3.3 → 0.4.1

package/dist/src/shell/RefStoryPage.js

@@ -0,0 +1,123 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A story of a composed catalogue (`refs`), shown read-only: its own catalogue's embed page in a frame, on that
+ * catalogue's origin, with this catalogue's switches. Loaded the first time one is opened.
+ *
+ * @remarks
+ * The embed page is the composed catalogue's own, so the story runs with its own preview, theme and frames, and this
+ * page runs none of its code: what crosses one way is the address (the story and the switches, which the embed reads as
+ * any address), the other way a height (`EmbedSizeMessage`), heard only from that frame's window and origin. A change of
+ * the toolbar's switches gives the frame a new address. Off this catalogue's origin the frame is sandboxed as a story's
+ * frame is, which keeps it from navigating this tab.
+ *
+ * @module
+ */
+import "./refStory.css";
+import { useEffect, useRef, useState } from "react";
+import { refEmbedAddress, refStoryAddress } from "../catalogueRefs.js";
+import { EMBED_SIZE_TYPE } from "../embed.js";
+import { STAGE_HEIGHT_RANGE } from "../viewState.js";
+import { FRAME_SANDBOX, framesOrigin } from "./framesOrigin.js";
+import { Icon } from "./icons.js";
+import { REF_STRINGS } from "./refStrings.js";
+import { useRefIndex } from "./useRefIndex.js";
+/** The frame's height before the embed reports its own, in CSS px. */
+const WAITING_HEIGHT = 240;
+/**
+ * The browser features another site's page may use: what shows a story (full screen, a video, a copy button), and none
+ * that asks the reader (the camera, the microphone, the position, the clipboard's reading). A permission the reader
+ * gave this catalogue would otherwise be that site's too, without a question.
+ */
+const REF_PERMISSIONS = [
+    "fullscreen",
+    "picture-in-picture",
+    "autoplay",
+    "encrypted-media",
+    "clipboard-write"
+].join("; ");
+/** The story's component title and name, as the index gives them; none until it is read, or when it lists neither. */
+const namesOf = (index, storyId) => {
+    for (const component of index?.components ?? []) {
+        const story = component.stories.find((each) => each.id === storyId);
+        if (story !== undefined)
+            return { component: component.title.split("/").join(" › "), story: story.name };
+    }
+    return undefined;
+};
+/**
+ * Whether a message is a height from the embed page: its type and a number, nothing else is read.
+ *
+ * @param data - the message.
+ */
+const heightOf = (data) => {
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const type = Reflect.get(data, "type");
+    const height = Reflect.get(data, "height");
+    // never taller than a stage: the embed scrolls a taller story inside its frame, and a page could say any number
+    return type === EMBED_SIZE_TYPE && typeof height === "number" && Number.isFinite(height) && height > 0
+        ? Math.min(Math.ceil(height), STAGE_HEIGHT_RANGE.max)
+        : undefined;
+};
+/**
+ * The embed page's frame, as tall as the story it reports.
+ *
+ * @param props - the composed catalogue, the frame's address and its accessible name.
+ */
+const RefFrame = ({ composed, address, title }) => {
+    const frameRef = useRef(null);
+    const [height, setHeight] = useState(undefined);
+    const origin = new URL(composed.url).origin;
+    useEffect(() => {
+        const onMessage = (event) => {
+            if (event.origin !== origin || event.source !== frameRef.current?.contentWindow)
+                return;
+            const reported = heightOf(event.data);
+            if (reported !== undefined)
+                setHeight(reported);
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, [origin]);
+    return (_jsx("iframe", { ref: frameRef, className: "forgebook-ref-story__frame", src: address, title: title, allow: REF_PERMISSIONS, 
+        // on this catalogue's own origin a sandbox could be lifted by what runs in it; elsewhere it keeps this tab
+        sandbox: origin === window.location.origin ? undefined : FRAME_SANDBOX, style: { height: height ?? WAITING_HEIGHT } }));
+};
+/**
+ * Whether a composed catalogue is served on the origin this catalogue's stories run on, where it is not this page.
+ *
+ * @param composed - the composed catalogue.
+ */
+const isOnFramesOrigin = (composed) => {
+    const origin = new URL(composed.url).origin;
+    return origin === framesOrigin() && origin !== window.location.origin;
+};
+/**
+ * Why a story of a composed catalogue is not shown, or none: the shell names only a catalogue it composes, and one on
+ * this catalogue's stories' origin would be framed as one of them and share their storage.
+ *
+ * @param composed - the composed catalogue the address names, if the configuration has it.
+ * @param refId - the id the address names.
+ */
+const refusalOf = (composed, refId) => {
+    if (composed === undefined)
+        return REF_STRINGS.unknownRef(refId);
+    return isOnFramesOrigin(composed) ? REF_STRINGS.onFramesOrigin(composed.title) : undefined;
+};
+/**
+ * A story of a composed catalogue, read-only.
+ *
+ * @param props - the composed catalogues, the one and the story the address names, and the switches.
+ */
+export const RefStoryPage = ({ refs, refId, storyId, switches }) => {
+    const composed = refs.find((each) => each.id === refId);
+    const state = useRefIndex(composed, true);
+    const refusal = refusalOf(composed, refId);
+    if (composed === undefined || refusal !== undefined)
+        return (_jsx("div", { className: "forgebook-workspace", role: "alert", children: _jsx("h1", { className: "forgebook-empty", children: refusal }) }));
+    const names = namesOf(state.status === "ready" ? state.index : undefined, storyId);
+    const storyName = names?.story ?? storyId;
+    return (_jsxs("div", { className: "forgebook-workspace forgebook-ref-story", children: [_jsxs("header", { className: "forgebook-header", children: [_jsx("p", { className: "forgebook-header__path", children: [composed.title, names?.component].filter((part) => part !== undefined).join(" · ") }), _jsxs("div", { className: "forgebook-header__row", children: [_jsx("h1", { className: "forgebook-header__title", children: storyName }), _jsxs("a", { className: "forgebook-button", href: refStoryAddress(composed, storyId), target: "_blank", rel: "noopener noreferrer", children: [_jsx(Icon, { name: "external", size: 12 }), REF_STRINGS.openThere(composed.title)] })] }), _jsx("p", { className: "forgebook-ref-story__note", children: REF_STRINGS.readOnly })] }), _jsx("div", { className: "forgebook-ref-story__stage", children: _jsx(RefFrame
+                // a new story is a new frame: its height starts over with it
+                , { composed: composed, address: refEmbedAddress(composed, storyId, switches), title: REF_STRINGS.storyTitle(storyName, composed.title) }, storyId) })] }));
+};

package/dist/src/shell/SearchPanel.js

@@ -112,24 +112,30 @@ const ResultNote = ({ result, listed }) => {
     return (_jsxs("p", { className: "forgebook-result__note", children: [more > 0 ? _jsx("span", { children: SEARCH_STRINGS.more(more) }) : null, result.missed.length > 0 ? _jsx("span", { children: SEARCH_STRINGS.missing(result.missed.join(", ")) }) : null] }));
 };
 /** The answer's rows, for the keys and the list. */
-const useResultRows = (answer) => {
+const useResultRows = (answer, hrefOf) => {
     const baseId = useId();
     return useMemo(() => answer.results.map((result, place) => ({
         result,
-        own: { id: `${baseId}-${place}`, target: result.target },
+        own: { id: `${baseId}-${place}`, key: hrefOf(result.target), target: result.target },
         hits: result.hits.map((hit, hitPlace) => ({
             hit,
-            row: { id: `${baseId}-${place}-${hitPlace}`, target: hit.target }
+            row: {
+                id: `${baseId}-${place}-${hitPlace}`,
+                key: `${hrefOf(result.target)} ${hitPlace}`,
+                target: hit.target
+            }
         }))
-    })), [answer, baseId]);
+    })), [answer, baseId, hrefOf]);
 };
 /** The highlighted row: moved by the keys and the pointer, kept in view, named to the field. */
-const useActiveRow = ({ rows, isShown, hrefOf, onOpen, onActiveChange, keysRef }) => {
-    const [place, setPlace] = useState(0);
-    // new words, or an index that arrived, change what each place holds: Enter must not open what the reader never saw
-    // biome-ignore lint/correctness/useExhaustiveDependencies: the rows are what resets it
-    useEffect(() => setPlace(0), [rows]);
-    const active = rows[Math.min(place, rows.length - 1)];
+const useActiveRow = ({ rows, isShown, words, isBehind, hrefOf, onOpen, onActiveChange, keysRef }) => {
+    // what a person chose is a row, not a place: an index that arrives moves the rows, and Enter must open the one chosen.
+    // Until they choose, and for new words, it is the first
+    const [chosen, setChosen] = useState();
+    const chosenPlace = chosen?.words === words ? rows.findIndex((row) => row.key === chosen.key) : -1;
+    const place = Math.max(chosenPlace, 0);
+    const active = rows[place];
+    const setActive = (row) => setChosen({ words, key: row.key });
     const activeId = isShown ? active?.id : undefined;
     useEffect(() => onActiveChange(activeId), [activeId, onActiveChange]);
     const listRef = useRef(null);
@@ -138,23 +144,42 @@ const useActiveRow = ({ rows, isShown, hrefOf, onOpen, onActiveChange, keysRef }
             return;
         listRef.current?.querySelector(`[id="${CSS.escape(activeId)}"]`)?.scrollIntoView({ block: "nearest" });
     }, [activeId]);
+    const act = ({ key, hasModifier }) => {
+        if (activeId === undefined || active === undefined)
+            return false;
+        const step = KEY_STEPS[key];
+        const next = step === undefined ? undefined : rows[(place + step + rows.length) % rows.length];
+        if (next !== undefined)
+            setActive(next);
+        else if (key !== "Enter")
+            return false;
+        else if (hasModifier)
+            window.open(hrefOf(active.target), "_blank", "noopener");
+        else
+            onOpen(active.target);
+        return true;
+    };
+    // a key pressed while the list is behind the words is meant for the list of those words, and waits for it
+    const waitingKeys = useRef([]);
+    useEffect(() => {
+        if (isBehind)
+            return;
+        const next = waitingKeys.current.shift();
+        // one at a time: the next key acts on the row this one moved to, which the next render gives
+        if (next !== undefined && !act(next))
+            waitingKeys.current = [];
+    });
     useImperativeHandle(keysRef, () => ({
         press: (key, hasModifier) => {
-            if (activeId === undefined || active === undefined)
-                return false;
-            const step = KEY_STEPS[key];
-            if (step !== undefined)
-                setPlace((row) => (row + step + rows.length) % rows.length);
-            else if (key !== "Enter")
-                return false;
-            else if (hasModifier)
-                window.open(hrefOf(active.target), "_blank", "noopener");
-            else
-                onOpen(active.target);
-            return true;
+            const isListKey = key === "Enter" || KEY_STEPS[key] !== undefined;
+            if (isListKey && (isBehind || waitingKeys.current.length > 0)) {
+                waitingKeys.current.push({ key, hasModifier });
+                return true;
+            }
+            return act({ key, hasModifier });
         }
     }));
-    return { active, setActive: (row) => setPlace(rows.indexOf(row)), listRef };
+    return { active, setActive, listRef };
 };
 /** The answer's state, in a line: how many results, what is still coming, what could not be read. */
 const PanelStatus = ({ total, query, isLoading, hasFailed }) => (_jsxs("p", { className: "forgebook-search-panel__status", role: "status", children: [total === 0 && !isLoading ? _jsx("span", { children: SEARCH_STRINGS.nothing(query.trim()) }) : null, total > 0 ? _jsx("span", { children: SEARCH_STRINGS.count(total) }) : null, isLoading ? _jsx("span", { children: SEARCH_STRINGS.reading }) : null, hasFailed ? _jsx("span", { children: SEARCH_STRINGS.unreadable }) : null] }));
@@ -175,7 +200,7 @@ export const SearchPanel = ({ tree, sources, query, isOpen, field, sidebarWidth,
     // the field never waits for a long list
     const words = useDeferredValue(query);
     const answer = useMemo(() => searchCatalogue(all, words, LIMITS), [all, words]);
-    const results = useResultRows(answer);
+    const results = useResultRows(answer, hrefOf);
     const rows = useMemo(() => results.flatMap(({ own, hits }) => [own, ...hits.map(({ row }) => row)]), [results]);
     const isShown = isOpen && hasQuery;
     const panelRef = useRef(null);
@@ -188,6 +213,8 @@ export const SearchPanel = ({ tree, sources, query, isOpen, field, sidebarWidth,
     const { active, setActive, listRef } = useActiveRow({
         rows,
         isShown,
+        words,
+        isBehind: words !== query,
         hrefOf,
         onOpen,
         onActiveChange,

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

@@ -10,8 +10,11 @@ import { type AddressTexts } from "../addressTexts.ts";
 import type { CatalogueLists } from "../catalogue.ts";
 import type { ViewSwitch } from "../switches.ts";
 import type { WrittenHomeProps } from "./AuthoredHome.tsx";
+import type { ArgControlLoaders } from "./customControls.ts";
 import { type LoadPluginHosts } from "./pluginHostsContext.ts";
 import type { ShellPlugin } from "./pluginTabs.tsx";
+import type { ShellRefs } from "./refParts.tsx";
+import { type ToolbarProps } from "./Toolbar.tsx";
 /** What an app passes to the shell. */
 export type ShellConfig = {
     /** The catalogue's name, in the page title and the sidebar. */
@@ -30,6 +33,8 @@ export type ShellConfig = {
     readonly heights?: string;
     /** The sources, in the order the sidebar lists them. */
     readonly sources: readonly StorySource[];
+    /** The catalogue's own story patterns, for a home with no story to say where it looks; none by default. */
+    readonly storyGlobs?: readonly string[];
     /**
      * The frame page's address: relative to the shell's (`frame.html`) when the frames share its origin, on the frames'
      * origin otherwise (`mountShell` makes it).
@@ -55,6 +60,13 @@ export type ShellConfig = {
     readonly home?: () => Promise<ComponentType<WrittenHomeProps>>;
     /** Loads the catalogue's design tokens, on first use; none when it has none. */
     readonly loadTokens?: () => Promise<unknown>;
+    /**
+     * Loads the previews of the catalogue's galleries, when one first opens; none when it gives none. The generated page
+     * gives what the configuration's check allowed; the page checks nothing itself.
+     */
+    readonly loadSwitchPreviews?: ToolbarProps["loadSwitchPreviews"];
+    /** Loads each custom control `argControls` registers, by name; none when it registers none. */
+    readonly argControls?: ArgControlLoaders;
     /** The plugins with views (the generated page passes them); none by default. */
     readonly plugins?: readonly ShellPlugin[];
     /**
@@ -67,6 +79,12 @@ export type ShellConfig = {
      * texts that are not plain words from a story that may write them into markup. `any` by default.
      */
     readonly addressTexts?: AddressTexts;
+    /**
+     * Other catalogues, built and deployed, listed after this one's stories and shown read-only (`catalogueRefs.ts`), and
+     * the code that draws them (`forgebook/shell/refs`): the generated page gives them only for a catalogue that has some,
+     * so the others' first load carries none of it. None by default.
+     */
+    readonly refs?: ShellRefs;
 };
 /**
  * The catalogue's page: its settings computed once from the configuration (its switches, its languages' switch, its

package/dist/src/shell/Shell.js

@@ -1,17 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { addressArgsFor } from "../addressTexts.js";
+import { readArgsParam, readStorybookLink } from "../addressArgsParam.js";
+import { addressArgsRead } from "../addressTexts.js";
 import { deviceDefaultOf, pageDeviceDefault } from "../deviceView.js";
-import { panelArgsParam, parsePanelArgsParam } from "../messages.js";
+import { panelArgsParam } from "../messages.js";
 import { anchorOf } from "../pageAddress.js";
 import { findPage } from "../pageTree.js";
 import { sourceFiles } from "../sourceFiles.js";
 import { storyBackground } from "../storyBackground.js";
 import { NOT_FIXED } from "../storyGlobals.js";
 import { knownHeight } from "../storyHeights.js";
-import { componentId, findComponent, findComponentByTitle, findStory, isLogicComponent, sidebarStoryIds, storyTree } from "../storyTree.js";
+import { componentId, findComponent, findComponentByTitle, findStory, isLogicComponent, sidebarStoryIds, storyOfAddress, storyTree } from "../storyTree.js";
 import { parseView, viewParams } from "../viewState.js";
 import { CatalogueContext, NO_PLUGINS, useCatalogue, useConfiguredCatalogue } from "./catalogueContext.js";
+import { HAS_REFS, shellRefs } from "./composition.js";
 import { filesCodeLoader } from "./filesCode.js";
 import { Icon } from "./icons.js";
 import { LazyPage } from "./LazyPage.js";
@@ -19,16 +21,20 @@ import { LogicMark } from "./LogicMark.js";
 import { lazyModule } from "./lazyModule.js";
 import { PluginHostsContext } from "./pluginHostsContext.js";
 import { Sidebar } from "./Sidebar.js";
-import { SidebarEdge } from "./SidebarHandle.js";
+import { SidebarShade } from "./SidebarHandle.js";
 import { Stage } from "./Stage.js";
 import { StoryPicker } from "./StoryPicker.js";
 import { STRINGS } from "./strings.js";
 import { ShowSidebarButton, Toolbar } from "./Toolbar.js";
 import { useAppearance } from "./useAppearance.js";
+import { useEditedProblems } from "./useEditedProblems.js";
+import { useListedTree } from "./useListedTree.js";
 import { useRecentPages } from "./useRecentPages.js";
+import { useShortcutHelp } from "./useShortcutHelp.js";
 import { useShownView } from "./useShownView.js";
 import { useSidebarLayout } from "./useSidebarLayout.js";
 import { useSidebarOverlay } from "./useSidebarOverlay.js";
+import { readStored } from "./useStored.js";
 import { useStoryHeights } from "./useStoryHeights.js";
 import { useStoryIdsElement } from "./useStoryIdsElement.js";
 import { useStoryKeys } from "./useStoryKeys.js";
@@ -37,6 +43,15 @@ import { useSystemDark } from "./useSystemDark.js";
 const DOC_PAGE = lazyModule(() => import("./DocPage.js").then((module) => module.DocPage));
 /** The home, loaded when it is opened. */
 const HOME_PAGE = lazyModule(() => import("./HomePage.js").then((module) => module.HomePage));
+/** The address's parameter that names a composed catalogue; its story is in `story`, as a story of this one's is. */
+const REF_PARAMETER = "ref";
+/**
+ * A part of the composed catalogues, once its module is there; nothing for a catalogue that composes none, or on a page
+ * that shows none of their stories.
+ *
+ * @param props - the module, if any, and the part's props; none when there is nothing to draw.
+ */
+const RefSlot = ({ refs, part }) => refs === undefined || part === undefined ? null : (_jsx(LazyPage, { module: refsModuleOf(refs), header: null, pageProps: part }));
 /** A component's page, loaded when one is opened. */
 const COMPONENT_PAGE = lazyModule(() => import("./ComponentPage.js").then((module) => module.ComponentPage));
 /**
@@ -51,6 +66,8 @@ const HOME = { kind: "home" };
 const pageKey = (page) => {
     if (page.kind === "home")
         return page.kind;
+    if (HAS_REFS && page.kind === "ref")
+        return `ref:${page.ref}/${page.id}`;
     // a heading is a place of its own in the history: Back from it returns to where the reader was
     return page.kind === "story" ? `story:${page.id}` : `${page.kind}:${page.id}#${page.anchor ?? ""}`;
 };
@@ -85,16 +102,20 @@ const drawnWidth = (width, fill) => (width === "fill" ? fill : width);
  */
 const stageHeight = (heights, storyId, width, shownWidth) => knownHeight(heights, storyId, drawnWidth(width, shownWidth ?? FILL_WIDTH));
 /**
- * The page an address's query and fragment name: a story wins, then a component, then a docs page; none is the home.
+ * The page an address's query and fragment name: a composed catalogue's story wins, then a story, a component, a docs
+ * page; none is the home.
  *
  * @param search - the address's query.
  * @param hash - its fragment.
  */
 const pageOf = (search, hash) => {
     const params = new URLSearchParams(search);
-    const story = params.get("story");
+    const story = storyOfAddress(params);
     const component = params.get("component");
     const page = params.get("page");
+    const ref = HAS_REFS ? params.get(REF_PARAMETER) : null;
+    if (ref !== null && story !== null)
+        return { kind: "ref", ref, id: story };
     if (story !== null)
         return { kind: "story", id: story };
     const anchor = anchorOf(hash.replace(/^#/, ""));
@@ -112,32 +133,50 @@ const pageOf = (search, hash) => {
  */
 const readAddress = (catalogue, addressTexts) => {
     const params = new URLSearchParams(window.location.search);
+    const param = params.get("args");
     return {
         page: pageOf(window.location.search, window.location.hash),
         view: parseView(window.location.search, catalogue),
-        panelArgs: addressArgsFor(parsePanelArgsParam(params.get("args")), addressTexts),
-        matrix: (params.get("matrix") ?? "").split(",").filter((name) => name !== "")
+        ...addressArgsRead(readArgsParam(param), param, addressTexts),
+        matrix: (params.get("matrix") ?? "").split(",").filter((name) => name !== ""),
+        tags: params.getAll("tag").filter((tag) => tag !== "" && tag !== "!")
     };
 };
+/**
+ * Writes a composed catalogue's story into an address's parameters; nothing for another page.
+ *
+ * @param params - the parameters.
+ * @param page - the page.
+ */
+const writeRefPage = (params, page) => {
+    if (page.kind !== "ref")
+        return;
+    params.set(REF_PARAMETER, page.ref);
+    params.set("story", page.id);
+};
 /**
  * The query of an address.
  *
  * @param address - the page, the view, the panel's values and the matrix's axes.
  * @param catalogue - the catalogue's switches and default audience, for the view's values.
  */
-const addressQuery = ({ page, view, panelArgs, matrix }, catalogue) => {
-    const params = viewParams(view, catalogue.switches, catalogue.audience);
+const addressQuery = ({ page, view, panelArgs, link, matrix, tags }, catalogue) => {
+    const params = viewParams(view, catalogue.switches, catalogue.audience, catalogue.play);
+    if (HAS_REFS)
+        writeRefPage(params, page);
     if (page.kind === "story")
         params.set("story", page.id);
     if (page.kind === "component")
         params.set("component", page.id);
     if (page.kind === "page")
         params.set("page", page.id);
-    const args = page.kind === "story" ? panelArgsParam(panelArgs) : "";
+    const args = page.kind === "story" ? (link?.param ?? panelArgsParam(panelArgs)) : "";
     if (args !== "")
         params.set("args", args);
     if (page.kind === "story" && matrix.length > 0)
         params.set("matrix", matrix.join(","));
+    for (const tag of tags)
+        params.append("tag", tag);
     const query = params.toString();
     // the fragment is part of what is written back on every change of the view, or a change would lose the heading
     const fragment = (page.kind === "page" || page.kind === "component") && page.anchor !== undefined
@@ -145,7 +184,27 @@ const addressQuery = ({ page, view, panelArgs, matrix }, catalogue) => {
         : "";
     return `${query === "" ? window.location.pathname : `?${query}`}${fragment}`;
 };
-/** What the address's page shows: a story or a component that is not there (renamed, removed) says so, never another. */
+/**
+ * What the address's page shows in a catalogue that composes others: a composed catalogue's story, or what `shownPage`
+ * said. A `ref` that names no composed catalogue is another site's mark (`?ref=newsletter`): the story is this
+ * catalogue's.
+ *
+ * @param tree - the tree.
+ * @param page - the address's page.
+ * @param refs - the composed catalogues, if any.
+ * @param shown - what `shownPage` said of it.
+ */
+const shownRef = (tree, page, refs, shown) => {
+    if (page.kind !== "ref")
+        return shown;
+    return refs?.catalogues.some((each) => each.id === page.ref)
+        ? { kind: "ref", place: { refId: page.ref, storyId: page.id } }
+        : shownPage(tree, { kind: "story", id: page.id });
+};
+/**
+ * What the address's page shows: a story or a component that is not there (renamed, removed) says so, never another. A
+ * composed catalogue's story is `shownRef`'s.
+ */
 const shownPage = (tree, page) => {
     if (page.kind === "story") {
         const location = findStory(tree, page.id);
@@ -188,6 +247,37 @@ const isLogicPage = (shown) => {
 };
 /** The shown component's place, a story's too; none on any other page. */
 const componentLocationOf = (shown) => shown.kind === "story" || shown.kind === "component" ? shown.location : undefined;
+/** The shown story of a composed catalogue; none on any other page. */
+const refPlaceOf = (shown) => shown.kind === "ref" ? shown.place : undefined;
+/** The page of a composed catalogue's story. */
+const refPageOf = ({ refId, storyId }) => ({ kind: "ref", ref: refId, id: storyId });
+/** The composed catalogues' code, once a part of it was first drawn: a page holds one shell, with one configuration. */
+let refsModule;
+/** The composed catalogues' code, loaded when a part of it is first drawn. */
+const refsModuleOf = (refs) => {
+    refsModule ??= lazyModule(refs.load);
+    return refsModule;
+};
+/**
+ * What the composed catalogues add to the shown page: their sidebar sections, and a story's page when one is shown;
+ * nothing for a catalogue that composes none.
+ *
+ * @param refs - the composed catalogues, if any.
+ * @param current - the shown story of one of them, if any.
+ * @param links - how a story of theirs is linked and opened.
+ * @param switches - this catalogue's switches, with the view's values.
+ */
+const refSlotsOf = (refs, current, links, switches) => {
+    if (refs === undefined)
+        return { sidebar: {}, page: null };
+    const page = current === undefined ? undefined : { place: "page", refs: refs.catalogues, ...current, switches };
+    return {
+        sidebar: {
+            composed: _jsx(RefSlot, { refs: refs, part: { place: "sidebar", refs: refs.catalogues, current, ...links } })
+        },
+        page: _jsx(RefSlot, { refs: refs, part: page })
+    };
+};
 /** The shown docs page's place; none on any other page. */
 const pageLocationOf = (shown) => shown.kind === "page" ? shown.location : undefined;
 /** Whether nothing shown follows the view's switches: the home, or a docs page without a story. */
@@ -324,7 +414,7 @@ const RelatedLinks = ({ related, hrefOf, onOpen }) => related.length === 0 ? nul
  * @param props - the problems, the shown component's place, the message when a named page is missing, the picker
  * of the component's stories, and the related components.
  */
-const ShellHeader = ({ problems, location, page, message, picker, related, isLogic }) => (_jsxs(_Fragment, { children: [problems.length > 0 ? (_jsxs("div", { className: "forgebook-problems", role: "alert", children: [_jsx("strong", { children: STRINGS.indexProblems }), _jsx("ul", { children: problems.map((problem) => (_jsx("li", { children: problem }, problem))) })] })) : null, message === undefined ? null : (_jsx("p", { className: "forgebook-empty", role: "alert", children: message })), location === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsxs("p", { className: "forgebook-header__path", children: [[location.source.name, location.family.name, location.group.name]
+const ShellHeader = ({ problems, location, page, message, picker, related, isLogic }) => (_jsxs(_Fragment, { children: [problems.length > 0 ? (_jsxs("div", { className: "forgebook-problems", role: "alert", children: [_jsx("strong", { children: STRINGS.indexProblems }), _jsx("ul", { children: problems.map((problem) => (_jsx("li", { children: problem }, problem))) })] })) : null, message === undefined ? null : (_jsx("div", { role: "alert", children: _jsx("h1", { className: "forgebook-empty", children: message }) })), location === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsxs("p", { className: "forgebook-header__path", children: [[location.source.name, location.family.name, location.group.name]
                             .filter((part) => part !== undefined)
                             .join(" · "), location.component.alsoIn.length === 0 ? null : (_jsxs("span", { className: "forgebook-header__also-in", children: [" · ", STRINGS.alsoIn(location.component.alsoIn.map((place) => place.split("/").join(" › ")).join(", "))] }))] }), _jsxs("div", { className: "forgebook-header__row", children: [_jsx("h1", { className: "forgebook-header__title", children: location.component.name }), isLogic ? _jsx(LogicMark, {}) : null, picker, location.component.design === undefined ? null : (_jsxs("a", { className: "forgebook-button", href: location.component.design.url, target: "_blank", rel: "noopener noreferrer", children: [_jsx(Icon, { name: "external", size: 14 }), STRINGS.openInFigma] }))] }), related] })), page === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsx("p", { className: "forgebook-header__path", children: [page.source.name, page.page.group].filter((part) => part !== undefined).join(" · ") }), _jsx("div", { className: "forgebook-header__row", children: _jsx("h1", { className: "forgebook-header__title", children: page.page.name }) })] }))] }));
 /** A story's page. */
@@ -357,12 +447,23 @@ const useAddress = (catalogue, addressTexts) => {
         window.addEventListener("popstate", onBack);
         return () => window.removeEventListener("popstate", onBack);
     }, [catalogue, addressTexts]);
+    // a link in Storybook's form has its reader loaded for it; a value changed meanwhile, or another page, has the last word
+    const waitingParam = address.link?.isWaiting === true ? address.link.param : undefined;
+    useEffect(() => {
+        if (waitingParam === undefined)
+            return;
+        void readStorybookLink(waitingParam, ({ readStorybookArgs }, param) => readStorybookArgs(param)).then((read) => setAddress((current) => current.link?.isWaiting === true && current.link.param === waitingParam
+            ? { ...current, ...addressArgsRead(read, waitingParam, addressTexts) }
+            : current));
+    }, [waitingParam, addressTexts]);
     // a height set with the foot handle belongs to the story it was set on: another page starts at its own
     const pageAddress = (page) => ({
         page,
         view: { ...address.view, height: "auto" },
         panelArgs: {},
-        matrix: []
+        link: undefined,
+        matrix: [],
+        tags: address.tags
     });
     const open = (page, movesFocus) => {
         const next = pageAddress(page);
@@ -411,8 +512,9 @@ const useOwnPageId = (address, ownPage, replaceAddress) => {
  *
  * @param props - the configuration.
  */
-const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addressTexts = "any", plugins = NO_PLUGINS, loadTokens, home }) => {
+const ShellPage = ({ title, logo, hasBranding, heights, sources, storyGlobs, frameUrl, addressTexts = "any", plugins = NO_PLUGINS, loadTokens, loadSwitchPreviews, argControls, home }) => {
     const tree = useMemo(() => storyTree(sources), [sources]);
+    const problems = useEditedProblems(tree.problems);
     // 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]);
@@ -440,7 +542,18 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
     const isSystemDark = useSystemDark();
     const appearance = useAppearance(address.view, catalogue.switches);
     useStoryIdsElement(useMemo(() => sidebarStoryIds(tree, catalogue.storyGroups.map((group) => group.id)), [tree, catalogue.storyGroups]));
-    const shown = shownPage(tree, address.page);
+    const { help, showHelp } = useShortcutHelp();
+    let shown = shownPage(tree, address.page);
+    // what composition adds to the page; the build removes this whole block from a catalogue that composes none
+    let refSlots;
+    if (HAS_REFS) {
+        const refs = shellRefs();
+        shown = shownRef(tree, address.page, refs, shown);
+        refSlots = refSlotsOf(refs, refPlaceOf(shown), {
+            refStoryHref: (place) => addressQuery(pageAddress(refPageOf(place)), catalogue),
+            onOpenRefStory: (place) => openPage(refPageOf(place))
+        }, address.view.switches);
+    }
     const location = componentLocationOf(shown);
     const ownPage = recentPageOf(shown);
     const recent = useRecentPages(ownPage);
@@ -463,16 +576,21 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
         catalogueDevice: catalogue.device,
         onAddressViewChange: changeView
     });
-    useStoryKeys(tree, shownStoryId, shown.kind === "component" ? shown.location.component.stories[0]?.id : undefined, (id) => openPage({ kind: "story", id }));
+    const listedTree = useListedTree(tree, address.tags);
+    useStoryKeys(listedTree, shownStoryId, shown.kind === "component" ? shown.location.component.stories[0]?.id : undefined, (id) => openPage({ kind: "story", id }));
     const source = sources.find((candidate) => candidate.id === location?.source.id);
     const files = source === undefined ? undefined : sourceFiles(source);
     const storyHrefOf = (story) => addressQuery(pageAddress(storyPage(story)), catalogue);
     const columnHeightOf = (storyId) => knownHeight(storyHeights, storyId, drawnWidth(address.view.width, PAGE_COLUMN_WIDTH));
-    const header = (_jsx(ShellHeader, { problems: tree.problems, location: location, page: shownPageLocation, isLogic: isLogicPage(shown), message: shown.kind === "missing" ? shown.message : undefined, picker: location === undefined ? null : (_jsx(StoryPicker, { component: location.component, currentStoryId: shownStoryId, onOpenComponent: () => openPage(componentPage(location.component)), onOpenStory: (story) => openPage(storyPage(story)) })), related: _jsx(RelatedLinks, { related: relatedComponents(tree, location), hrefOf: (page) => addressQuery(pageAddress(page), catalogue), onOpen: openPage }) }));
+    // the component's page puts its width's button in the header (`PageWidth.tsx`); until then, and on a story's page,
+    // an empty place of the button's size keeps the picker where it stays
+    const headerWith = (tools) => (_jsx(ShellHeader, { problems: problems, location: location, page: shownPageLocation, isLogic: isLogicPage(shown), message: shown.kind === "missing" ? shown.message : undefined, picker: location === undefined ? null : (_jsx(StoryPicker, { component: location.component, currentStoryId: shownStoryId, onOpenComponent: () => openPage(componentPage(location.component)), onOpenStory: (story) => openPage(storyPage(story)), children: tools })), related: _jsx(RelatedLinks, { related: relatedComponents(tree, location), hrefOf: (page) => addressQuery(pageAddress(page), catalogue), onOpen: openPage }) }));
+    const header = headerWith(_jsx("span", { className: "forgebook-page-width" }));
     const homeProps = {
         title,
         tree,
         sources,
+        storyGlobs,
         recent,
         hrefOf: (page) => addressQuery(pageAddress(page), catalogue),
         onOpen: (page) => openPage(page),
@@ -496,9 +614,9 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
         header,
         scroll
     };
-    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), 
+    return (_jsxs("div", { className: "catalogue", children: [_jsx(Sidebar, { width: sidebarWidth, onWidthChange: setSidebarWidth, isOpen: isSidebarOpen, isOverlay: isSidebarOverlay, sidebarRef: sidebarRef, hideButtonRef: hideButtonRef, onHide: hideSidebar, onShow: showSidebar, appearance: appearance, onShowKeys: showHelp, title: title, logo: logo, hasBranding: hasBranding !== false, tree: listedTree, wholeTree: tree, tags: address.tags, onTagsChange: (tags) => replaceAddress({ ...address, tags }), 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 }), ...refSlots?.sidebar, componentHref: (sourceId, componentTitle) => addressQuery(pageAddress(titledPage(idsByTitle, sourceId, componentTitle)), catalogue), onOpenComponent: (sourceId, componentTitle) => openPage(titledPage(idsByTitle, sourceId, componentTitle)) }), help, _jsx(SidebarShade, { isOverlay: isSidebarOverlay, isOpen: isSidebarOpen, 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: {
+                        onShowSidebar: isSidebarOpen && !isSidebarOver ? undefined : showSidebar, showSidebarRef: showButtonRef, shownWidth: shown.kind === "story" ? shownWidth : undefined, fixed: fixedOfShown(fixedViews, shown), deviceDefault: deviceOfShown(catalogue.device, shown), loadSwitchPreviews: loadSwitchPreviews }), shown.kind === "component" ? (_jsx(LazyPage, { module: COMPONENT_PAGE, header: header, pageProps: {
                             component: shown.location.component,
                             anchor: shown.anchor,
                             view: address.view,
@@ -510,7 +628,7 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
                             ...componentLoaders(files, shown.location.component),
                             background: storyBackground(shown.location.source.background, address.view, catalogue, isSystemDark),
                             heightOf: columnHeightOf,
-                            header,
+                            headerWith,
                             scroll,
                             usedIn: usedInLinks(source, catalogue.hasUsedIn, tree, {
                                 hrefOf: (page) => addressQuery(pageAddress(page), catalogue),
@@ -528,7 +646,7 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
                             anchor: shown.anchor,
                             onOpenPage: (id) => openPage({ kind: "page", id }),
                             onOpenAnchor: openAnchor
-                        } }, shown.location.page.id)) : null, shown.kind === "story" ? (_jsx(Stage, { component: shown.location.component, story: shown.location.story, view: shownView, onViewChange: changeShownView, onFixedChange: (storyId, fixed) => setFixedViews((current) => new Map(current).set(storyId, fixed)), panelArgs: address.panelArgs, onPanelArgsChange: (panelArgs) => replaceAddress({ ...address, panelArgs }), matrixAxes: address.matrix, onMatrixAxesChange: (matrix) => replaceAddress({ ...address, matrix }), frameUrl: frameUrl, plugins: plugins, ...storyLoaders(files, shown.location.story), namedValues: source?.namedValues, header: header, onShownWidthChange: setShownWidth, scroll: scroll, backgroundOf: (view) => storyBackground(shown.location.source.background, view, catalogue, isSystemDark), measuredHeight: stageHeight(storyHeights, shown.location.story.id, address.view.width, shownWidth) })) : null, shown.kind === "missing" ? header : null] })] }));
+                        } }, shown.location.page.id)) : null, shown.kind === "story" ? (_jsx(Stage, { loadTokens: loadTokens, argControls: argControls, component: shown.location.component, story: shown.location.story, view: shownView, onViewChange: changeShownView, onFixedChange: (storyId, fixed) => setFixedViews((current) => new Map(current).set(storyId, fixed)), panelArgs: address.panelArgs, addressLink: address.link, onPanelArgsChange: (panelArgs) => replaceAddress({ ...address, panelArgs, link: undefined }), matrixAxes: address.matrix, onMatrixAxesChange: (matrix) => replaceAddress({ ...address, matrix }), frameUrl: frameUrl, plugins: plugins, ...storyLoaders(files, shown.location.story), namedValues: source?.namedValues, header: header, onShownWidthChange: setShownWidth, scroll: scroll, backgroundOf: (view) => storyBackground(shown.location.source.background, view, catalogue, isSystemDark), measuredHeight: stageHeight(storyHeights, shown.location.story.id, address.view.width, shownWidth) })) : null, refSlots?.page, shown.kind === "missing" ? header : null] })] }));
 };
 /**
  * The catalogue's page: its settings computed once from the configuration (its switches, its languages' switch, its
@@ -536,4 +654,4 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
  *
  * @param props - the configuration.
  */
-export const Shell = (props) => (_jsx(CatalogueContext.Provider, { value: useConfiguredCatalogue(props), children: _jsx(PluginHostsContext.Provider, { value: props.pluginHosts, children: _jsx(ShellPage, { ...props }) }) }));
+export const Shell = (props) => (_jsx(CatalogueContext.Provider, { value: useConfiguredCatalogue(props, readStored), children: _jsx(PluginHostsContext.Provider, { value: props.pluginHosts, children: _jsx(ShellPage, { ...props }) }) }));