shelving 1.244.1 → 1.246.0

package/extract/PackageExtractor.d.ts

@@ -32,6 +32,7 @@ export interface PackageExtractorOptions {
  * - Static export keys (e.g. `"./api"`, `"./firestore/client"`) become one module each.
  * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file or subdirectory.
  * - Each export's *target* extension (e.g. the `.js` in `"./util/*.js"`) is mapped to source extensions via `extensions`, so built `.js` paths resolve to their `.ts` sources.
+ * - Each module's `title` is prefixed with the package `name` (e.g. `ui` → `shelving/ui`) so listings read as package subpaths.
  * - The `"."` root export is skipped — its content is the root tree element itself.
  * - Throws if a static export key has no matching source element in the tree.
  *

package/extract/PackageExtractor.js

@@ -16,6 +16,7 @@ const DEFAULT_EXTENSIONS = {
  * - Static export keys (e.g. `"./api"`, `"./firestore/client"`) become one module each.
  * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file or subdirectory.
  * - Each export's *target* extension (e.g. the `.js` in `"./util/*.js"`) is mapped to source extensions via `extensions`, so built `.js` paths resolve to their `.ts` sources.
+ * - Each module's `title` is prefixed with the package `name` (e.g. `ui` → `shelving/ui`) so listings read as package subpaths.
  * - The `"."` root export is skipped — its content is the root tree element itself.
  * - Throws if a static export key has no matching source element in the tree.
  *
@@ -56,7 +57,9 @@ export class PackageExtractor extends Extractor {
     async extract(packageJson) {
         const pkgPath = requirePath(packageJson, this._base, this.extract);
         const pkg = (await Bun.file(pkgPath).json());
-        const exports = pkg.exports ?? {};
+        const tree = this._tree;
+        // Read the package name alongside its exports — the name prefixes each module title (e.g. `ui` → `shelving/ui`).
+        const { name, exports = {} } = pkg;
         const modules = [];
         for (const [key, value] of Object.entries(exports)) {
             if (key === ".")
@@ -76,18 +79,21 @@ export class PackageExtractor extends Extractor {
                 modules.push(this._module.extract({ name: subpath, source }));
             }
         }
-        const tree = this._tree;
+        // Prefix the package name onto each module's title so listings read `shelving/ui` rather than a bare `ui`, making modules glanceable as package subpaths.
+        const children = name
+            ? modules.map(module => ({ ...module, props: { ...module.props, title: `${name}/${module.props.title ?? module.props.name}` } }))
+            : modules;
         // Canonical URL `path`s aren't stamped here — they're derived from tree structure when the tree is flattened (`flattenTree()`) in the UI layer.
         return {
             type: "tree-element",
-            key: pkg.name ?? tree.key,
+            key: name ?? tree.key,
             props: {
                 source: tree.props.source,
-                name: pkg.name ?? tree.props.name,
-                title: pkg.name ?? tree.props.title,
+                name: name ?? tree.props.name,
+                title: name ?? tree.props.title,
                 description: pkg.description ?? tree.props.description,
                 content: tree.props.content,
-                children: modules,
+                children,
             },
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.244.1",
+	"version": "1.246.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/README.md

@@ -11,7 +11,7 @@ The `ui` module exists so an app never hand-rolls the same form field, card, or
 A few conventions run through every component:
 
 - **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button strong>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in *one place* — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style` or raw `className`.
-- **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like [`Card`](/ui/Card), [`Section`](/ui/Section), [`Button`](/ui/Button), and [`Tag`](/ui/Tag) rather than shipping their own styling.
+- **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like [`<Card>`](/ui/Card), [`<Section>`](/ui/Section), [`<Button>`](/ui/Button), and [`<Tag>`](/ui/Tag) rather than shipping their own styling.
 - **Sentence case.** Titles, headings, and button labels capitalise only the first word.
 - **Theme with CSS.** An app-wide custom look is a CSS file, not a wall of props. Write a `theme.css` that overrides the base design-token variables (and, where needed, per-component hooks) at `:root`, and import it after the library styles. The recommended workflow is to spend time tuning those variables to match your design — see [Theming](#theming) below.
 
@@ -19,15 +19,15 @@ A few conventions run through every component:
 
 The styling system lives in `style/` and has four moving parts: design tokens, the tint scale, cascade layers, and the styling props. Components compose them in a predictable shape; consumers theme by overriding CSS custom properties at `:root`.
 
-**Design tokens.** Every design-token constant is defined at `:root`, split across the themed token modules in `style/` — each module owns one domain, documents the variables it defines, and is the page a theme author overrides. `style/layers.css` is the cascade-layer anchor; every `*.module.css` `@import`s it plus the specific token modules it references, so the tokens and the layer order reach every component regardless of bundle order. The domains are: colours ([`getColorClass`](/ui/getColorClass)), font sizes ([`getSizeClass`](/ui/getSizeClass)), font weights ([`getWeightClass`](/ui/getWeightClass)), font faces ([`getFontClass`](/ui/getFontClass)), spacing ([`getSpaceClass`](/ui/getSpaceClass)), widths ([`getWidthClass`](/ui/getWidthClass)), radii ([`getRadiusClass`](/ui/getRadiusClass)), strokes ([`getStrokeClass`](/ui/getStrokeClass)), shadows ([`getShadowClass`](/ui/getShadowClass)), and durations ([`getDurationClass`](/ui/getDurationClass)). Each also defines the semantic aliases a theme usually targets (`--color-primary`, `--color-link`, `--space-paragraph`, …). Components read tokens via `var(--token)`.
+**Design tokens.** Every design-token constant is defined at `:root`, split across the themed token modules in `style/` — each module owns one domain, documents the variables it defines, and is the page a theme author overrides. `style/layers.css` is the cascade-layer anchor; every `*.module.css` `@import`s it plus the specific token modules it references, so the tokens and the layer order reach every component regardless of bundle order. The domains are: colours ([`getColorClass()`](/ui/getColorClass)), font sizes ([`getSizeClass()`](/ui/getSizeClass)), font weights ([`getWeightClass()`](/ui/getWeightClass)), font faces ([`getFontClass()`](/ui/getFontClass)), spacing ([`getSpaceClass()`](/ui/getSpaceClass)), widths ([`getWidthClass()`](/ui/getWidthClass)), radii ([`getRadiusClass()`](/ui/getRadiusClass)), strokes ([`getStrokeClass()`](/ui/getStrokeClass)), shadows ([`getShadowClass()`](/ui/getShadowClass)), and durations ([`getDurationClass()`](/ui/getDurationClass)). Each also defines the semantic aliases a theme usually targets (`--color-primary`, `--color-link`, `--space-paragraph`, …). Components read tokens via `var(--token)`.
 
-**The tint scale.** All colour flows from one anchor variable, `--tint-50`, from which a 21-step ladder is computed and *recomputed* under [`TINT_CLASS`](/ui/TINT_CLASS) — the heart of how `color=` and `status=` retint a whole subtree. The ladder, the recompute trick, the painting conventions, and the theming guide all live on the [`TINT_CLASS`](/ui/TINT_CLASS) page.
+**The tint scale.** All colour flows from one anchor variable, `--tint-50`, from which a 21-step ladder is computed and *recomputed* under [`TINT_CLASS`](/ui/TINT_CLASS) — the heart of how `color=` and `status=` retint a whole subtree. The ladder, the recompute trick, the painting conventions, and the theming guide all live on the `TINT_CLASS` page.
 
 **Cascade layers.** Styles are ordered by `@layer`, lowest to highest priority: `defaults` (`:root` tokens, the tint ladder, body baseline) → `components` (the bulk of the CSS: `.card`, `.button`, …) → `variants` (cross-cutting opt-in modifiers, which always beat components) → `overrides` (top-priority structural fixes like `:first-child` / `:last-child` margin collapses). Unlayered rules beat all layered rules, so a theme should set tokens at `:root` or wrap its rules in `@layer`.
 
-**Styling props.** The cross-cutting visual options are props, each backed by a helper in `style/` that maps the prop to a class. Colour and status move the tint anchor — [`getColorClass`](/ui/getColorClass) and [`getStatusClass`](/ui/getStatusClass); font size, weight, and family come from [`getSizeClass`](/ui/getSizeClass), [`getWeightClass`](/ui/getWeightClass), and [`getFontClass`](/ui/getFontClass), which [`getTypographyClass`](/ui/getTypographyClass) combines with text alignment and tint; spacing, padding, and gap from [`getSpaceClass`](/ui/getSpaceClass), [`getPaddingClass`](/ui/getPaddingClass), and [`getGapClass`](/ui/getGapClass); width constraints from [`getWidthClass`](/ui/getWidthClass); flex layout from [`getFlexClass`](/ui/getFlexClass); and opt-in scrolling from [`getScrollClass`](/ui/getScrollClass). Each helper's page lists its exact prop values and what they set. A component opts into the props it wants by extending the matching `*Props` interfaces and composing the `getXxxClass(props)` calls.
+**Styling props.** The cross-cutting visual options are props, each backed by a helper in `style/` that maps the prop to a class. Colour and status move the tint anchor — `getColorClass()` and [`getStatusClass()`](/ui/getStatusClass); font size, weight, and family come from `getSizeClass()`, `getWeightClass()`, and `getFontClass()`, which [`getTypographyClass()`](/ui/getTypographyClass) combines with text alignment and tint; spacing, padding, and gap from `getSpaceClass()`, [`getPaddingClass()`](/ui/getPaddingClass), and [`getGapClass()`](/ui/getGapClass); width constraints from `getWidthClass()`; flex layout from [`getFlexClass()`](/ui/getFlexClass); and opt-in scrolling from [`getScrollClass()`](/ui/getScrollClass). Each helper's page lists its exact prop values and what they set. A component opts into the props it wants by extending the matching `*Props` interfaces and composing the `getXxxClass(props)` calls.
 
-Each painting component also exposes its own theme hooks — a single tint hook (`--card-tint`) to recolour the whole component, plus per-property hooks (`--card-background`, `--card-radius`, …) for surgical overrides. Those are documented in each component's own **Styling** section (see [`Card`](/ui/Card) for the precedent).
+Each painting component also exposes its own theme hooks — a single tint hook (`--card-tint`) to recolour the whole component, plus per-property hooks (`--card-background`, `--card-radius`, …) for surgical overrides. Those are documented in each component's own **Styling** section (see [`<Card>`](/ui/Card) for the precedent).
 
 ## Theming
 
@@ -45,10 +45,10 @@ The recommended way to give an app its own look is a **theme stylesheet**, not s
 
 Each base token lives in a themed module that documents the variables it defines and which ones a theme usually overrides. Work from broadest (a palette colour or scale root) to narrowest (a single semantic alias):
 
-- [weight](/ui/getWeightClass) · [size](/ui/getSizeClass) · [font](/ui/getFontClass) — typography (`--weight-*`, `--size-*`, `--font-*`, `--case-label`).
-- [color](/ui/getColorClass) — palette, semantic, and brand colours (`--color-*`).
-- [space](/ui/getSpaceClass) · [width](/ui/getWidthClass) — layout spacing and widths (`--space-*`, `--width-*`).
-- [radius](/ui/getRadiusClass) · [stroke](/ui/getStrokeClass) · [shadow](/ui/getShadowClass) · [duration](/ui/getDurationClass) — surface tokens (`--radius-*`, `--stroke-*`, `--shadow-*`, `--duration-*`).
+- [`weight`](/ui/getWeightClass) · [`size`](/ui/getSizeClass) · [`font`](/ui/getFontClass) — typography (`--weight-*`, `--size-*`, `--font-*`, `--case-label`).
+- [`color`](/ui/getColorClass) — palette, semantic, and brand colours (`--color-*`).
+- [`space`](/ui/getSpaceClass) · [`width`](/ui/getWidthClass) — layout spacing and widths (`--space-*`, `--width-*`).
+- [`radius`](/ui/getRadiusClass) · [`stroke`](/ui/getStrokeClass) · [`shadow`](/ui/getShadowClass) · [`duration`](/ui/getDurationClass) — surface tokens (`--radius-*`, `--stroke-*`, `--shadow-*`, `--duration-*`).
 
 The **tint ladder** is the one exception that doesn't follow the override-a-variable pattern: its 21 steps are *recomputed* from a single anchor inside every tinted scope, so you move the anchor rather than overriding individual steps. See [`TINT_CLASS`](/ui/TINT_CLASS) for the full theming guide, and each component's **Styling** section for its per-component hooks.
 
@@ -56,19 +56,19 @@ The **tint ladder** is the one exception that doesn't follow the override-a-vari
 
 The components below are listed in the index following this page; this is the short version of where to start reading.
 
-**Content.** Block-level structure starts with [`Card`](/ui/Card), [`Section`](/ui/Section), and the [`Heading`](/ui/Heading) / [`Title`](/ui/Title) family, with [`Table`](/ui/Table), [`List`](/ui/List), and [`Figure`](/ui/Figure) for specific shapes; wrap longform copy in [`Prose`](/ui/Prose). Inline pieces — [`Link`](/ui/Link), [`Code`](/ui/Code), [`Strong`](/ui/Strong), [`Mark`](/ui/Mark) — live inside that block content. To render a Markdown string as components, use [`Markup`](/ui/Markup).
+**Content.** Block-level structure starts with [`<Card>`](/ui/Card), [`<Section>`](/ui/Section), and the [`<Heading>`](/ui/Heading) / [`<Title>`](/ui/Title) family, with [`<Table>`](/ui/Table), [`<List>`](/ui/List), and [`<Figure>`](/ui/Figure) for specific shapes; wrap longform copy in [`<Prose>`](/ui/Prose). Inline pieces — [`<Link>`](/ui/Link), [`<Code>`](/ui/Code), [`<Strong>`](/ui/Strong), [`<Mark>`](/ui/Mark) — live inside that block content. To render a Markdown string as components, use [`<Markup>`](/ui/Markup).
 
-**Structure.** Mount a client app with [`App`](/ui/App), or render a full server document with [`HTML`](/ui/HTML) and [`Page`](/ui/Page). Arrange the screen with [`CenteredLayout`](/ui/CenteredLayout) or [`SidebarLayout`](/ui/SidebarLayout), and drive URLs with [`Navigation`](/ui/Navigation) and [`Router`](/ui/Router).
+**Structure.** Mount a client app with [`<App>`](/ui/App), or render a full server document with [`<HTML>`](/ui/HTML) and [`<Page>`](/ui/Page). Arrange the screen with [`<CenteredLayout>`](/ui/CenteredLayout) or [`<SidebarLayout>`](/ui/SidebarLayout), and drive URLs with [`<Navigation>`](/ui/Navigation) and [`<Router>`](/ui/Router).
 
-**Interaction.** Forms start at [`Form`](/ui/Form), which wires [`Field`](/ui/Field) and the typed inputs to a [`FormStore`](/ui/FormStore); [`Button`](/ui/Button) is the standalone action. Overlays are [`Dialog`](/ui/Dialog) and [`Modal`](/ui/Modal); navigation menus are [`Menu`](/ui/Menu) and [`MenuItem`](/ui/MenuItem); transient feedback is [`Notice`](/ui/Notice) (and the global [`Notices`](/ui/Notices) list); animate enter/leave with [`Transition`](/ui/Transition).
+**Interaction.** Forms start at [`<Form>`](/ui/Form), which wires [`<Field>`](/ui/Field) and the typed inputs to a [`FormStore`](/ui/FormStore); [`<Button>`](/ui/Button) is the standalone action. Overlays are [`<Dialog>`](/ui/Dialog) and [`<Modal>`](/ui/Modal); navigation menus are [`<Menu>`](/ui/Menu) and [`<MenuItem>`](/ui/MenuItem); transient feedback is [`<Notice>`](/ui/Notice) (and the global [`<Notices>`](/ui/Notices) list); animate enter/leave with [`<Transition>`](/ui/Transition).
 
-**Documentation site.** Hand an extracted tree to [`TreeApp`](/ui/TreeApp) and you get a complete site — sidebar, routing, and a rendered page per element — using the renderers in `docs/`.
+**Documentation site.** Hand an extracted tree to [`<TreeApp>`](/ui/TreeApp) and you get a complete site — sidebar, routing, and a rendered page per element — using the renderers in `docs/`.
 
 ## See also
 
-- [extract](/extract) — builds the tree that the documentation components render
-- [markup](/markup) — Markdown rendering used by [`Markup`](/ui/Markup) and [`Prose`](/ui/Prose)
-- [store](/store) — reactive state behind [`FormStore`](/ui/FormStore), `NavigationStore`, and notices
-- [react](/react) — store and provider hooks used alongside these components
+- [`extract`](/extract) — builds the tree that the documentation components render
+- [`markup`](/markup) — Markdown rendering used by [`<Markup>`](/ui/Markup) and [`<Prose>`](/ui/Prose)
+- [`store`](/store) — reactive state behind [`FormStore`](/ui/FormStore), [`NavigationStore`](/ui/NavigationStore), and notices
+- [`react`](/react) — store and provider hooks used alongside these components
 
 > Building or extending a component? The contributor walkthrough (file layout, the tint-anchor + per-property-hook pattern, `:first-child` / `:last-child` overrides, and the checklist) lives in the **React Components** section of `AGENTS.md`.

package/ui/layout/CenteredLayout.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { requireMetaURL } from "../misc/MetaContext.js";
+import { RouteCache } from "../router/RouteCache.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import CENTERED_LAYOUT_CSS from "./CenteredLayout.module.css";
 import { LAYOUT_CLASS } from "./Layout.js";
@@ -15,6 +15,7 @@ import { LAYOUT_CLASS } from "./Layout.js";
  * @see https://dhoulb.github.io/shelving/ui/layout/CenteredLayout/CenteredLayout
  */
 export function CenteredLayout({ children, fullWidth = false }) {
-    const { path } = requireMetaURL();
-    return (_jsx("main", { className: getClass(getModuleClass(CENTERED_LAYOUT_CSS, "main"), LAYOUT_CLASS), children: _jsx("div", { className: getModuleClass(CENTERED_LAYOUT_CSS, "mainInner"), style: fullWidth ? { maxWidth: "none" } : undefined, children: children }) }, path));
+    // Wrap the scrolling `<main>` in `<RouteCache>` so recently-visited pages stay mounted but hidden,
+    // keeping their scroll position and state intact across back/forward navigation.
+    return (_jsx(RouteCache, { children: _jsx("main", { className: getClass(getModuleClass(CENTERED_LAYOUT_CSS, "main"), LAYOUT_CLASS), children: _jsx("div", { className: getModuleClass(CENTERED_LAYOUT_CSS, "mainInner"), style: fullWidth ? { maxWidth: "none" } : undefined, children: children }) }) }));
 }

package/ui/layout/CenteredLayout.tsx

@@ -1,5 +1,5 @@
 import type { ReactElement } from "react";
-import { requireMetaURL } from "../misc/MetaContext.js";
+import { RouteCache } from "../router/RouteCache.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import CENTERED_LAYOUT_CSS from "./CenteredLayout.module.css";
@@ -26,12 +26,15 @@ export interface CenteredLayoutProps extends OptionalChildProps {
  * @see https://dhoulb.github.io/shelving/ui/layout/CenteredLayout/CenteredLayout
  */
 export function CenteredLayout({ children, fullWidth = false }: CenteredLayoutProps): ReactElement {
-	const { path } = requireMetaURL();
+	// Wrap the scrolling `<main>` in `<RouteCache>` so recently-visited pages stay mounted but hidden,
+	// keeping their scroll position and state intact across back/forward navigation.
 	return (
-		<main key={path} className={getClass(getModuleClass(CENTERED_LAYOUT_CSS, "main"), LAYOUT_CLASS)}>
-			<div className={getModuleClass(CENTERED_LAYOUT_CSS, "mainInner")} style={fullWidth ? { maxWidth: "none" } : undefined}>
-				{children}
-			</div>
-		</main>
+		<RouteCache>
+			<main className={getClass(getModuleClass(CENTERED_LAYOUT_CSS, "main"), LAYOUT_CLASS)}>
+				<div className={getModuleClass(CENTERED_LAYOUT_CSS, "mainInner")} style={fullWidth ? { maxWidth: "none" } : undefined}>
+					{children}
+				</div>
+			</main>
+		</RouteCache>
 	);
 }

package/ui/layout/SidebarLayout.d.ts

@@ -17,6 +17,7 @@ export interface SidebarLayoutProps extends OptionalChildProps {
  * - On narrow viewports the sidebar becomes an off-canvas drawer toggled by a single menu button that switches between a burger and a close icon.
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
+ * - The scrollable content column is kept alive across navigation via `<RouteCache>`, so returning to a recently-visited page restores its scroll position and state; the sidebar stays mounted throughout.
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  *
  * @kind component

package/ui/layout/SidebarLayout.js

@@ -3,6 +3,7 @@ import { Bars3Icon, XMarkIcon } from "@heroicons/react/24/solid";
 import { useEffect, useState } from "react";
 import { Button } from "../form/Button.js";
 import { requireMetaURL } from "../misc/MetaContext.js";
+import { RouteCache } from "../router/RouteCache.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import { LAYOUT_CLASS } from "./Layout.js";
 import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
@@ -12,6 +13,7 @@ import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
  * - On narrow viewports the sidebar becomes an off-canvas drawer toggled by a single menu button that switches between a burger and a close icon.
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
+ * - The scrollable content column is kept alive across navigation via `<RouteCache>`, so returning to a recently-visited page restores its scroll position and state; the sidebar stays mounted throughout.
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  *
  * @kind component
@@ -31,7 +33,11 @@ export function SidebarLayout({ sidebar, children, right = false }) {
             setOpen(false);
     }, [path]);
     const sidebarEl = (_jsx("nav", { className: getClass(getModuleClass(SIDEBAR_LAYOUT_CSS, "sidebar"), open && getModuleClass(SIDEBAR_LAYOUT_CSS, "open")), children: sidebar }, "sidebar"));
-    const contentEl = (_jsxs("div", { className: getClass(LAYOUT_CLASS, getModuleClass(SIDEBAR_LAYOUT_CSS, "content")), children: [_jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "toggle"), children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), _jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "contentInner"), children: children })] }, path));
+    // Wrap the scrolling content column in `<RouteCache>` so recently-visited pages stay mounted but hidden
+    // — keeping the scroll position of this `.content` container (and all page state) intact across
+    // back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither
+    // duplicated nor remounted as the URL changes.
+    const contentEl = (_jsx(RouteCache, { children: _jsxs("div", { className: getClass(LAYOUT_CLASS, getModuleClass(SIDEBAR_LAYOUT_CSS, "content")), children: [_jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "toggle"), children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), _jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "contentInner"), children: children })] }) }, "content"));
     const overlayEl = open && (_jsx("button", { type: "button", className: getModuleClass(SIDEBAR_LAYOUT_CSS, "overlay"), "aria-label": "Close menu", onClick: () => setOpen(false) }, "overlay"));
     return (_jsx("main", { className: getClass(getModuleClass(SIDEBAR_LAYOUT_CSS, "main"), LAYOUT_CLASS), children: right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl] }));
 }

package/ui/layout/SidebarLayout.tsx

@@ -2,6 +2,7 @@ import { Bars3Icon, XMarkIcon } from "@heroicons/react/24/solid";
 import { type ReactElement, type ReactNode, useEffect, useState } from "react";
 import { Button } from "../form/Button.js";
 import { requireMetaURL } from "../misc/MetaContext.js";
+import { RouteCache } from "../router/RouteCache.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import { LAYOUT_CLASS } from "./Layout.js";
@@ -25,6 +26,7 @@ export interface SidebarLayoutProps extends OptionalChildProps {
  * - On narrow viewports the sidebar becomes an off-canvas drawer toggled by a single menu button that switches between a burger and a close icon.
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
+ * - The scrollable content column is kept alive across navigation via `<RouteCache>`, so returning to a recently-visited page restores its scroll position and state; the sidebar stays mounted throughout.
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  *
  * @kind component
@@ -52,15 +54,21 @@ export function SidebarLayout({ sidebar, children, right = false }: SidebarLayou
 			{sidebar}
 		</nav>
 	);
+	// Wrap the scrolling content column in `<RouteCache>` so recently-visited pages stay mounted but hidden
+	// — keeping the scroll position of this `.content` container (and all page state) intact across
+	// back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither
+	// duplicated nor remounted as the URL changes.
 	const contentEl = (
-		<div key={path} className={getClass(LAYOUT_CLASS, getModuleClass(SIDEBAR_LAYOUT_CSS, "content"))}>
-			<div className={getModuleClass(SIDEBAR_LAYOUT_CSS, "toggle")}>
-				<Button title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
-					{open ? <XMarkIcon /> : <Bars3Icon />}
-				</Button>
+		<RouteCache key="content">
+			<div className={getClass(LAYOUT_CLASS, getModuleClass(SIDEBAR_LAYOUT_CSS, "content"))}>
+				<div className={getModuleClass(SIDEBAR_LAYOUT_CSS, "toggle")}>
+					<Button title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
+						{open ? <XMarkIcon /> : <Bars3Icon />}
+					</Button>
+				</div>
+				<div className={getModuleClass(SIDEBAR_LAYOUT_CSS, "contentInner")}>{children}</div>
 			</div>
-			<div className={getModuleClass(SIDEBAR_LAYOUT_CSS, "contentInner")}>{children}</div>
-		</div>
+		</RouteCache>
 	);
 	const overlayEl = open && (
 		<button

package/ui/router/RouteCache.d.ts

@@ -0,0 +1,42 @@
+import { type ReactNode } from "react";
+/**
+ * Props for `<RouteCache>` — the `maxCached` size and the content `children` to keep alive per URL.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/router/RouteCache/RouteCacheProps
+ */
+export interface RouteCacheProps {
+    /**
+     * Number of recently-visited URLs to keep mounted (but hidden) so the entire state of their subtree —
+     * scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs,
+     * focus — is restored intact when navigating back or forward to them.
+     * - Defaults to `10`. Once the limit is reached the least-recently-visited entry is unmounted.
+     * - Set to `0` (or less) to disable caching and unmount the subtree as you leave each URL.
+     */
+    readonly maxCached?: number | undefined;
+    /** The content to render for the current URL and keep alive (hidden) for recently-visited URLs. */
+    readonly children: ReactNode;
+}
+/**
+ * Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
+ *
+ * - Reads the live URL from the surrounding `<Meta>` context and keeps up to `maxCached` recently-visited
+ *   pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
+ *   entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
+ * - Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
+ * - Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
+ *   different page per path and a hidden page never re-renders for someone else's URL.
+ * - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
+ *   subscriptions/observers/timers pause and resume cleanly as it is hidden and shown.
+ * - Because it wraps the scroll container itself (rather than sitting below it inside the router), the
+ *   scroll position of every cached page is preserved — surrounding chrome (sidebar, drawer state) stays
+ *   outside the cache, so it is neither duplicated nor remounted on navigation.
+ * - When `maxCached <= 0` the page is rendered directly with no caching (it unmounts as you leave it).
+ *
+ * @kind component
+ * @param maxCached Number of recently-visited URLs to keep alive (defaults to `10`; `0` disables caching).
+ * @param children The content region to render and cache (typically a layout's scrollable column).
+ * @returns The visible current page plus any cached pages kept alive but hidden.
+ * @example <SidebarLayout sidebar={<Menu />}><RouteCache><Router … /></RouteCache></SidebarLayout>
+ * @see https://dhoulb.github.io/shelving/ui/router/RouteCache/RouteCache
+ */
+export declare function RouteCache({ maxCached, children }: RouteCacheProps): ReactNode;

package/ui/router/RouteCache.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Activity, useRef } from "react";
+import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
+/**
+ * Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
+ *
+ * - Reads the live URL from the surrounding `<Meta>` context and keeps up to `maxCached` recently-visited
+ *   pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
+ *   entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
+ * - Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
+ * - Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
+ *   different page per path and a hidden page never re-renders for someone else's URL.
+ * - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
+ *   subscriptions/observers/timers pause and resume cleanly as it is hidden and shown.
+ * - Because it wraps the scroll container itself (rather than sitting below it inside the router), the
+ *   scroll position of every cached page is preserved — surrounding chrome (sidebar, drawer state) stays
+ *   outside the cache, so it is neither duplicated nor remounted on navigation.
+ * - When `maxCached <= 0` the page is rendered directly with no caching (it unmounts as you leave it).
+ *
+ * @kind component
+ * @param maxCached Number of recently-visited URLs to keep alive (defaults to `10`; `0` disables caching).
+ * @param children The content region to render and cache (typically a layout's scrollable column).
+ * @returns The visible current page plus any cached pages kept alive but hidden.
+ * @example <SidebarLayout sidebar={<Menu />}><RouteCache><Router … /></RouteCache></SidebarLayout>
+ * @see https://dhoulb.github.io/shelving/ui/router/RouteCache/RouteCache
+ */
+export function RouteCache({ maxCached = 10, children }) {
+    // Read the live URL from context; each navigation re-renders this with the new path.
+    const meta = requireMetaURL();
+    const mapRef = useRef(undefined);
+    const usedRef = useRef(0);
+    // Snapshot the children under the live URL (frozen) so each kept-alive copy keeps rendering for the URL
+    // it was captured at — the same `children` element resolves a different page per path.
+    const node = _jsx(MetaContext, { value: meta, children: children });
+    // Caching disabled — render the page directly so it unmounts as soon as you leave it.
+    if (maxCached <= 0)
+        return node;
+    // Insert or refresh the current page, then evict the least-recently-used pages beyond the limit.
+    const { path } = meta;
+    const map = (mapRef.current ??= new Map());
+    const used = ++usedRef.current;
+    const entry = map.get(path);
+    if (entry) {
+        entry.node = node;
+        entry.used = used;
+    }
+    else {
+        map.set(path, { node, used });
+    }
+    while (map.size > maxCached)
+        map.delete(_findLeastRecentlyUsed(map));
+    // Render every cached page; only the current `path` is visible, the rest are kept alive but hidden.
+    return Array.from(map, ([key, cached]) => (_jsx(Activity, { mode: key === path ? "visible" : "hidden", children: cached.node }, key)));
+}
+/** Find the key of the least-recently-used (lowest `used` tick) entry in the cache map. */
+function _findLeastRecentlyUsed(map) {
+    let lruKey;
+    let lruUsed = Number.POSITIVE_INFINITY;
+    for (const [key, entry] of map) {
+        if (entry.used < lruUsed) {
+            lruUsed = entry.used;
+            lruKey = key;
+        }
+    }
+    return lruKey;
+}

package/ui/router/RouteCache.md

@@ -0,0 +1,31 @@
+# RouteCache
+
+A keep-alive page cache. Drop it into a layout around its scrolling content region: it reads the current URL from the surrounding [`<Meta>`](/ui/MetaContext) context and keeps a handful of recently-visited pages mounted but *hidden* (using React's [`<Activity>`](https://react.dev/reference/react/Activity)), so navigating back or forward to a page restores its entire DOM and component state — scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs, focus — instead of remounting it fresh at the top.
+
+Shelving's [`SidebarLayout`](/ui/SidebarLayout) and [`CenteredLayout`](/ui/CenteredLayout) already wrap their scrollable content column in one for you, so pages rendered inside them keep their state across navigation automatically. Reach for it by hand only when building a custom layout.
+
+**Things to know:**
+
+- Pages are kept in a least-recently-used map keyed by `path`. Once `maxCached` pages are retained the least-recently-visited one is unmounted (and loses its state). A never-seen or evicted page mounts fresh at the top.
+- Pass `maxCached={0}` (or less) to disable caching entirely — the page renders directly and unmounts as soon as you leave it.
+- `<Activity mode="hidden">` preserves a hidden page's *state* while unmounting its *effects*, so subscriptions, observers (e.g. infinite-scroll), and timers pause and resume cleanly as the page is hidden and shown.
+- Each snapshot is frozen under its own `<Meta>` context, so the same single `children` element resolves a different page per path and a hidden page never re-renders for someone else's URL.
+- For per-page **scroll** to be preserved the cache has to wrap the scroll container itself — which is why it lives in the layout (around the scrollable column) rather than below it inside the router. Surrounding chrome (sidebar, drawer state) stays outside the cache, so it is neither duplicated nor remounted on navigation.
+
+## Usage
+
+```tsx
+import { RouteCache } from "shelving/ui";
+
+<SidebarLayout sidebar={<Menu/>}>
+  <RouteCache>
+    <Router routes={routes}/>
+  </RouteCache>
+</SidebarLayout>
+```
+
+## See also
+
+- [`SidebarLayout`](/ui/SidebarLayout) / [`CenteredLayout`](/ui/CenteredLayout) — wrap their scrollable content column in a `<RouteCache>` for you
+- [`Router`](/ui/Router) — matches a URL to a route; render it inside a `<RouteCache>` to keep pages alive
+- [`Navigation`](/ui/Navigation) — drives the URL changes that move between cached pages

package/ui/router/RouteCache.tsx

@@ -0,0 +1,97 @@
+import { Activity, type ReactNode, useRef } from "react";
+import type { AbsolutePath } from "../../util/path.js";
+import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
+
+/** A cached page: the rendered node plus a monotonic `used` tick for least-recently-used eviction. */
+interface CacheEntry {
+	node: ReactNode;
+	used: number;
+}
+
+/**
+ * Props for `<RouteCache>` — the `maxCached` size and the content `children` to keep alive per URL.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/router/RouteCache/RouteCacheProps
+ */
+export interface RouteCacheProps {
+	/**
+	 * Number of recently-visited URLs to keep mounted (but hidden) so the entire state of their subtree —
+	 * scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs,
+	 * focus — is restored intact when navigating back or forward to them.
+	 * - Defaults to `10`. Once the limit is reached the least-recently-visited entry is unmounted.
+	 * - Set to `0` (or less) to disable caching and unmount the subtree as you leave each URL.
+	 */
+	readonly maxCached?: number | undefined;
+	/** The content to render for the current URL and keep alive (hidden) for recently-visited URLs. */
+	readonly children: ReactNode;
+}
+
+/**
+ * Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
+ *
+ * - Reads the live URL from the surrounding `<Meta>` context and keeps up to `maxCached` recently-visited
+ *   pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
+ *   entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
+ * - Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
+ * - Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
+ *   different page per path and a hidden page never re-renders for someone else's URL.
+ * - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
+ *   subscriptions/observers/timers pause and resume cleanly as it is hidden and shown.
+ * - Because it wraps the scroll container itself (rather than sitting below it inside the router), the
+ *   scroll position of every cached page is preserved — surrounding chrome (sidebar, drawer state) stays
+ *   outside the cache, so it is neither duplicated nor remounted on navigation.
+ * - When `maxCached <= 0` the page is rendered directly with no caching (it unmounts as you leave it).
+ *
+ * @kind component
+ * @param maxCached Number of recently-visited URLs to keep alive (defaults to `10`; `0` disables caching).
+ * @param children The content region to render and cache (typically a layout's scrollable column).
+ * @returns The visible current page plus any cached pages kept alive but hidden.
+ * @example <SidebarLayout sidebar={<Menu />}><RouteCache><Router … /></RouteCache></SidebarLayout>
+ * @see https://dhoulb.github.io/shelving/ui/router/RouteCache/RouteCache
+ */
+export function RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode {
+	// Read the live URL from context; each navigation re-renders this with the new path.
+	const meta = requireMetaURL();
+	const mapRef = useRef<Map<AbsolutePath, CacheEntry>>(undefined);
+	const usedRef = useRef(0);
+
+	// Snapshot the children under the live URL (frozen) so each kept-alive copy keeps rendering for the URL
+	// it was captured at — the same `children` element resolves a different page per path.
+	const node = <MetaContext value={meta}>{children}</MetaContext>;
+
+	// Caching disabled — render the page directly so it unmounts as soon as you leave it.
+	if (maxCached <= 0) return node;
+
+	// Insert or refresh the current page, then evict the least-recently-used pages beyond the limit.
+	const { path } = meta;
+	const map = (mapRef.current ??= new Map());
+	const used = ++usedRef.current;
+	const entry = map.get(path);
+	if (entry) {
+		entry.node = node;
+		entry.used = used;
+	} else {
+		map.set(path, { node, used });
+	}
+	while (map.size > maxCached) map.delete(_findLeastRecentlyUsed(map));
+
+	// Render every cached page; only the current `path` is visible, the rest are kept alive but hidden.
+	return Array.from(map, ([key, cached]) => (
+		<Activity key={key} mode={key === path ? "visible" : "hidden"}>
+			{cached.node}
+		</Activity>
+	));
+}
+
+/** Find the key of the least-recently-used (lowest `used` tick) entry in the cache map. */
+function _findLeastRecentlyUsed(map: Map<AbsolutePath, CacheEntry>): AbsolutePath {
+	let lruKey!: AbsolutePath;
+	let lruUsed = Number.POSITIVE_INFINITY;
+	for (const [key, entry] of map) {
+		if (entry.used < lruUsed) {
+			lruUsed = entry.used;
+			lruKey = key;
+		}
+	}
+	return lruKey;
+}

package/ui/router/Router.md

@@ -8,6 +8,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
 - `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
 - With a `base` set, the path used for matching is the URL after `matchURLPrefix` strips the base prefix; URLs outside the base render as `null`.
 - Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
+- `cache` (default `10`) keeps recently-visited pages mounted but hidden so back/forward navigation restores their state — see [Keeping page state](#keeping-page-state).
 
 ## Usage
 
@@ -119,6 +120,30 @@ const SIDEBARRED_ROUTES = {
 }}/>
 ```
 
+### Keeping page state
+
+By default `<Router>` unmounts a page when you navigate away and mounts a fresh one when you return — so scroll position, open/closed toggles, in-progress searches, form inputs, and focus are all lost, and you land back at the top.
+
+The `cache` prop keeps recently-visited pages mounted but hidden (using React's [`<Activity>`](https://react.dev/reference/react/Activity)), so navigating back or forward to a page restores its entire DOM and component state untouched — no per-feature scroll-capturing or state serialisation required.
+
+```tsx
+// Keep the last 10 visited pages alive (the default).
+<Router routes={ROUTES}/>
+
+// Keep more pages, at the cost of more retained DOM/memory.
+<Router routes={ROUTES} cache={25}/>
+
+// Opt out — unmount each page as you leave it (original behaviour).
+<Router routes={ROUTES} cache={0}/>
+```
+
+**Things to know:**
+
+- Pages are keyed by their matched `path`; once `cache` pages are retained the least-recently-visited one is unmounted (and so loses its state). Visiting a never-seen or evicted page mounts it fresh at the top.
+- Each cached page is wrapped in its own frozen `<Meta>` context, so hidden pages never re-render for the current URL.
+- `<Activity mode="hidden">` unmounts a hidden page's _effects_ while preserving its state, so subscriptions, observers (e.g. infinite-scroll), and timers pause politely and resume when the page is shown again.
+- For per-page scroll to be preserved, each page must own its scroll container (the scrollable element must live _inside_ the route, not in a shared layout wrapper that all routes render into).
+
 ### SSR / static rendering
 
 `<Router>` re-renders when context changes and needs no client. For static rendering set `url` and `root` on the outer wrapper and skip `<Navigation>`:

package/ui/router/Router.test.tsx

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { MetaContext } from "../misc/MetaContext.js";
+import { createMeta } from "../util/meta.js";
+import { Router } from "./Router.js";
+
+const ROUTES = {
+	"/": () => <main>Home</main>,
+	"/about": () => <main>About</main>,
+} as const;
+
+function render(url: string) {
+	return renderToStaticMarkup(
+		<MetaContext value={createMeta({ root: "http://x.com/", url })}>
+			<Router routes={ROUTES} />
+		</MetaContext>,
+	);
+}
+
+describe("Router", () => {
+	test("renders the matched route", () => {
+		expect(render("./about")).toContain("About");
+	});
+
+	test("throws when no route matches and no fallback is given", () => {
+		expect(() => render("./missing")).toThrow();
+	});
+});

package/ui/router/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./Navigation.js";
 export * from "./NavigationContext.js";
 export * from "./NavigationStore.js";
+export * from "./RouteCache.js";
 export * from "./Router.js";
 export * from "./Routes.js";

package/ui/router/index.js

@@ -1,5 +1,6 @@
 export * from "./Navigation.js";
 export * from "./NavigationContext.js";
 export * from "./NavigationStore.js";
+export * from "./RouteCache.js";
 export * from "./Router.js";
 export * from "./Routes.js";

package/ui/router/index.ts

@@ -1,5 +1,6 @@
 export * from "./Navigation.js";
 export * from "./NavigationContext.js";
 export * from "./NavigationStore.js";
+export * from "./RouteCache.js";
 export * from "./Router.js";
 export * from "./Routes.js";