staffa 0.7.4 → 0.8.1

package/src/components/box.ts

@@ -1,5 +1,6 @@
 import A from "aberdeen";
 import { type ContentOptions, type Slot, type Attributes, drawSlot } from "../core.js";
+import { closeContainingPanel } from "./panels.js";
 
 /** Options for {@link box}. */
 export interface BoxOptions extends ContentOptions {
@@ -7,6 +8,22 @@ export interface BoxOptions extends ContentOptions {
 	header?: Slot;
 	/** Footer content, drawn in a styled bar below the body. */
 	footer?: Slot;
+	/**
+	 * Draws a small ✕ button in the box's top-right corner: in the header row when
+	 * there is a {@link BoxOptions.header | header}, floating over the body when
+	 * there isn't.
+	 *
+	 * `true` closes the panel the box is drawn in, which is how a screen of a
+	 * routed `S.main()` gives the user a way back (the shell draws no back
+	 * arrows or ✕ of its own). Which panel that is gets worked out from the DOM
+	 * when it's clicked, so the box needs no `$page` handed to it and works from
+	 * any column, top of the stack or not. A box in a column further left closes
+	 * just that column and leaves the others alone. Outside a routed shell it
+	 * does nothing but warn.
+	 *
+	 * Pass a function to run that instead, for a dismissal of your own.
+	 */
+	close?: boolean | (() => void);
 	/** Aberdeen attr/style string applied to the body (content-holding) element. */
 	contentAttrs?: Attributes;
 	/** Aberdeen attr/style string applied to the header bar. */
@@ -26,11 +43,23 @@ export interface BoxOptions extends ContentOptions {
 // single divider.
 A.insertGlobalCss({
 	".s-box": {
-		"&": "display:flex flex-direction:column overflow:hidden r: $s-radius-lg;",
+		// position:relative so a headerless box can hang its ✕ in the corner.
+		"&": "display:flex flex-direction:column overflow:hidden r: $s-radius-lg; position:relative",
 		"&:not(:first-child)": "margin-top: $3",
 		"> header": "display:flex align-items:center gap:$2 padding: $2 $3; border:0 border-bottom: 1px solid $s-faint; r:0 font-weight:600",
 		"> footer": "display:flex align-items:center justify-content:flex-end gap:$2 padding: $2 $3; border:0 border-top: 1px solid $s-faint; r:0",
 		"> div": "p:$3 gap:$3",
+		// The ✕: quiet until you're near it, and drawn in the surface's own tokens
+		// so it works on whatever the box was recoloured to. `margin-left:auto`
+		// parks it at the far end of the header's flex row.
+		".s-box-close":
+			"flex-shrink:0 margin-left:auto display:flex align-items:center justify-content:center " +
+			"width:1.6rem height:1.6rem p:0 border:0 background:transparent cursor:pointer " +
+			"fg:$s-muted font-size:0.95rem line-height:1 r:$s-radius-sm " +
+			"transition: color 0.12s, background 0.12s;",
+		".s-box-close:hover": "fg:$s-text background: color-mix(in srgb, $s-text 8%, transparent);",
+		// Without a header there is no row to sit in, so it floats over the body.
+		"> .s-box-close": "position:absolute top:$2 right:$2 z-index:1",
 	},
 });
 
@@ -44,6 +73,9 @@ A.insertGlobalCss({
  *
  * Shortcut: pass a function to use it directly as the body content.
  *
+ * {@link BoxOptions.close | `close: true`} adds a ✕ that closes the panel the box
+ * is drawn in: the usual way back out of a screen in a routed `S.main()`.
+ *
  * @example
  * ```ts
  * const $user = A.proxy({name: "Kvothe"});
@@ -51,6 +83,7 @@ A.insertGlobalCss({
  *   S.textline({ label: "Name", bind: A.ref($user, "name") });
  * }});
  * S.box(() => A("p#Just some content"));   // shorthand
+ * S.box({ header: "Task 42", close: true, content: drawTask });  // ✕ closes this panel
  * ```
  */
 export function box(opts: BoxOptions | Slot = {}): void {
@@ -60,7 +93,14 @@ export function box(opts: BoxOptions | Slot = {}): void {
 		// Header and footer get their own scopes so toggling them doesn't recreate
 		// the body (which may hold focused inputs / lots of content).
 		A(() => {
-			if (o.header != null) A("header.s-s.neutral", o.headerAttrs, () => drawSlot(o.header));
+			if (o.header != null) {
+				A("header.s-s.neutral", o.headerAttrs, () => {
+					drawSlot(o.header);
+					if (o.close) drawCloseButton(o.close);
+				});
+			} else if (o.close) {
+				drawCloseButton(o.close);
+			}
 		});
 
 		A("div", o.contentAttrs, () => {
@@ -72,3 +112,18 @@ export function box(opts: BoxOptions | Slot = {}): void {
 		});
 	});
 }
+
+/**
+ * The box's ✕. With `close: true` the panel to close is resolved from the DOM at
+ * click time — so one box can close whichever column it happens to be drawn in,
+ * and a box outside a routed shell simply warns.
+ */
+function drawCloseButton(close: boolean | (() => void)): void {
+	A("button.s-box-close type=button aria-label=Close", () => {
+		A("click=", (e: Event) => {
+			if (typeof close === "function") close();
+			else void closeContainingPanel(e.currentTarget as HTMLElement);
+		});
+		A("span aria-hidden=true #✕");
+	});
+}

package/src/components/main.ts

@@ -1,10 +1,12 @@
 import A from "aberdeen";
-import { type Slot, type Attributes, drawSlot } from "../core.js";
-import { type MenuOptions, menuButton, drawMenu, isFloatingMenuOpen } from "./menu.js";
+import { type Slot, type Attributes, drawSlot, focusFirst, NARROW_PX } from "../core.js";
+import { type MenuOptions, drawMenu, showFloatingMenu, isFloatingMenuOpen, closeFloatingMenu, menuGlyph, closeGlyph } from "./menu.js";
+import { button } from "./button.js";
 import { isDialogOpen } from "./dialog.js";
+import { PanelController, type Page, type RouteHandler, type RouteTable, type Routes } from "./panels.js";
 
 /** Options for {@link main}. */
-export interface MainOptions {
+export interface MainOptions<R = Routes> {
 	/** Aberdeen attr/style string applied to the outermost shell element. */
 	attrs?: Attributes;
 	/** App/page title shown in the top bar. */
@@ -15,8 +17,80 @@ export interface MainOptions {
 	icon?: Slot;
 	/** Action area on the right of the top bar (buttons, menu, ...). */
 	menu?: Slot;
-	/** The scrollable page content. A string is rendered as rich text. */
+	/**
+	 * The scrollable page content. A string is rendered as rich text.
+	 * Mutually exclusive with {@link MainOptions.routes}.
+	 */
 	content?: Slot;
+	/**
+	 * Paths mapped to the functions that draw them, which hands navigation over
+	 * to the shell. Each route draws one screen of your app, called a panel, and
+	 * as many panels as fit are shown at a time: one at a time on a phone,
+	 * several side by side on a wider screen. Mutually exclusive with
+	 * {@link MainOptions.content}.
+	 *
+	 * A segment wrapped in brackets is a param: `[name]` matches one segment as
+	 * a string, `[name=integer]` matches one segment as a number, and a trailing
+	 * `[...name]` matches the rest of the path as one raw (still percent-encoded)
+	 * string, so it has to come last and needs at least one segment to match.
+	 * The first key that matches wins, a segment a param refuses falls through
+	 * to a later route (or to {@link MainOptions.notFound}), and each handler's
+	 * `$page.params` is typed from its own key.
+	 *
+	 * `integer` accepts only spellings that survive a round trip back to the
+	 * same URL, so `/tasks/0042` is not a second path for `/tasks/42`. Ids that
+	 * aren't safe integers, such as snowflakes, want a plain `[id]`.
+	 *
+	 * Navigating is just links: the shell handles the clicks itself, so do *not*
+	 * also call Aberdeen's `interceptLinks()`. A link opens its target on top of
+	 * the panel it sits in, closing anything that was above it first, unless it
+	 * carries `data-panel=replace`, which replaces its own panel instead. A link
+	 * to something already open goes back to it rather than opening it twice.
+	 * From code, use {@link panels} (`S.panels.push()` and friends): navigating
+	 * with `aberdeen/route`'s own `go()` works and still asks the panels'
+	 * {@link Page.requestClose}, but builds the whole stack from the path. A
+	 * navigation guard the app registered before mounting (an auth redirect,
+	 * say) keeps working: the shell asks it first, and puts it back when the
+	 * shell goes away.
+	 *
+	 * The shell draws no back arrows and no ✕ of its own: **every panel provides
+	 * its own way out**, with `S.box`'s `close` option for a ✕, or
+	 * {@link Page.close} behind a Cancel button. Escape and the browser's back
+	 * button are the shell's contribution.
+	 *
+	 * Only one routed shell can be mounted at a time (a second one throws),
+	 * which is what lets {@link panels} be a plain module-level object. Each
+	 * handler still gets its own `$page` rather than there being one global
+	 * "current page", since several panels are alive at once. It's that argument
+	 * that carries the per-route typing of `params`.
+	 *
+	 * @example
+	 * ```ts
+	 * S.main({
+	 *   title: "Trackle",
+	 *   nav: { items: [{ label: "Projects", href: "/projects" }] },
+	 *   routes: {
+	 *     "/projects": ($page) => { $page.title = "Projects"; drawProjects(); },
+	 *     "/projects/[id]": ($page) => drawProject($page.params.id),  // typed string
+	 *   },
+	 *   notFound: ($page) => S.box({ header: "Not found", content: $page.path }),
+	 * });
+	 * ```
+	 */
+	routes?: R;
+	/**
+	 * Draws the panel for a path none of the routes match. There are no params
+	 * to go with it, so `$page.params` is empty; the path itself is in
+	 * `$page.path`.
+	 */
+	notFound?: RouteHandler<{}>;
+	/**
+	 * Set `false` to show only the top panel, however wide the screen (the nav
+	 * sidebar still sits beside it). Everything else behaves the same: the URL,
+	 * the back button, `requestClose`, and the panels' own close buttons. This
+	 * only changes how many you see. Defaults to `true`.
+	 */
+	stacking?: boolean;
 	/** Footer content, pinned below the scroll area. */
 	footer?: Slot;
 	/**
@@ -26,6 +100,10 @@ export interface MainOptions {
 	 * sidebar) — cap to this width and centre horizontally. When unset, everything
 	 * fills the available width. Either way the content shares the page surface —
 	 * it is not boxed.
+	 *
+	 * Ignored when you pass {@link MainOptions.routes}: there the open panels
+	 * decide the width (see {@link Page.layout}), and the header and footer line
+	 * themselves up with them.
 	 */
 	maxWidth?: string;
 	/** Aberdeen attr/style string applied to the content area. */
@@ -35,18 +113,30 @@ export interface MainOptions {
 	/**
 	 * Navigation menu. When provided, renders a sidebar (in `"left"` / `"right"`
 	 * mode) or a button+dropdown (in `"button"` mode). The sidebar automatically
-	 * collapses to button mode when the shell is too narrow.
+	 * collapses to a button when the shell is too narrow — which there opens the
+	 * nav as a full page sliding in from the left, not as a dropdown.
+	 *
+	 * `items` may be a reactive array: the shell reads it inside the sidebar's own
+	 * scope, so an item arriving or leaving redraws the sidebar and nothing else.
+	 * The content beside it — in routed mode, the whole panel stack — is left
+	 * alone.
 	 */
 	nav?: MenuOptions;
 	/**
 	 * Where to render the nav. Defaults to `"left"`.
 	 * - `"left"` / `"right"`: sidebar next to the content area; collapses to a
-	 *   button+dropdown in the top bar when the shell width drops below 640 px.
-	 * - `"button"`: always a button+dropdown, never a sidebar.
+	 *   button in the top bar when the shell width drops below 640 px.
+	 * - `"button"`: always a button, never a sidebar.
+	 *
+	 * The button opens a dropdown on a wide shell, and — below 640 px — a
+	 * full-page nav that slides in from the left, handing over to the chosen
+	 * screen with a matching slide in from the right.
 	 */
 	navPosition?: "left" | "right" | "button";
 	/** Aberdeen attr/style string applied to the sidebar nav panel. */
 	navAttrs?: Attributes;
+	/** Aberdeen attr/style string applied to the narrow-screen full-page nav. */
+	navPageAttrs?: Attributes;
 }
 
 A.insertGlobalCss({
@@ -72,7 +162,9 @@ A.insertGlobalCss({
 		// Body always wraps <main> (with or without a sidebar) so max-width centering
 		// and scrollbar alignment work identically in both cases.
 		// .s-body centres .s-body-inner; .s-body-inner caps the content to maxWidth.
-		".s-body": "flex:1 overflow:hidden display:flex flex-direction:row min-height:0 justify-content:center",
+		// It's also the positioning + clipping context for the narrow-screen nav page,
+		// which slides in and out across its left edge.
+		".s-body": "flex:1 overflow:hidden display:flex flex-direction:row min-height:0 justify-content:center position:relative",
 		".s-body-inner": "flex:1 min-width:0 display:flex flex-direction:row min-height:0",
 		// Put the sidebar on the right (content fills the left) for right-hand navs.
 		"&.s-nav-right .s-body-inner": "flex-direction:row-reverse",
@@ -83,7 +175,14 @@ A.insertGlobalCss({
 		// can shrink to fit the bounded container (rather than letting wide content push
 		// the whole body — and any sidebar — past the viewport edge). overflow-x:hidden
 		// clips overlong content on the right; vertically it scrolls.
-		".s-body main": "flex:1 min-width:0 min-height:0 overflow-x:hidden overflow-y:auto display:flex flex-direction:column",
+		// The transition is dormant (nothing else moves <main>); it's there for the
+		// incoming half of the nav-page hand-off — see `slideContentIn`.
+		".s-body main":
+			"flex:1 min-width:0 min-height:0 overflow-x:hidden overflow-y:auto display:flex flex-direction:column " +
+			"transition: transform 0.3s ease;",
+		// A one-shot starting position: parked one screen to the right, with the
+		// transition off so it snaps there. Removing the class animates it home.
+		".s-body main.s-slide-in": "transform: translateX(100%); transition:none",
 		// The content area fills the scroll region with comfortable padding.
 		// It is deliberately NOT a boxed "sheet" — content brings its own boxes.
 		".s-body main > .s-content": "width:100% flex:1 p:$3",
@@ -94,18 +193,58 @@ A.insertGlobalCss({
 		// and the bar already comes from `.s-content`'s padding. Without a scrollbar
 		// there's no margin, so the content keeps its single $3 edge — not 2×$3.
 		".s-body main.s-scroll-y": "margin-right:$3",
+		// Routed mode takes its width from the panel stack instead of from
+		// `maxWidth`: the layout engine publishes the ensemble width (sidebar +
+		// separator + content area) as --s-shell-w — the standard 1280px page
+		// normally, the window's edges while a "large" panel is up — and the body
+		// row and the bars cap themselves to it. So the chrome lines up with the
+		// columns and the lot stays centred in the shell.
+		"&.s-routed > .s-body > .s-body-inner": "max-width: var(--s-shell-w, 100%);",
+		"&.s-routed > header > .s-bar": "max-width: var(--s-shell-w, 100%);",
+		"&.s-routed > footer > .s-bar": "max-width: var(--s-shell-w, 100%);",
+		// Changing the custom property animates the max-widths consuming it, with no
+		// JS in the loop: the chrome recentres in step with the panel whose arrival
+		// or departure moved it, over the same --s-panel-ms (see panels.ts). During
+		// a window resize (and the very first pass) the layout engine raises
+		// `.s-shell-snap` so the new width is adopted instantly instead of chasing
+		// the window through a transition.
+		"&.s-routed > .s-body > .s-body-inner, &.s-routed > header > .s-bar, &.s-routed > footer > .s-bar":
+			"transition: max-width var(--s-panel-ms) ease;",
+		"&.s-routed.s-shell-snap > .s-body > .s-body-inner, &.s-routed.s-shell-snap > header > .s-bar, &.s-routed.s-shell-snap > footer > .s-bar":
+			"transition:none",
 	},
 	// Sidebar nav panel. Items reuse the shared `.s-menu-item` /
 	// `.s-menu-sep` styles from menu.ts, so the sidebar and the floating
 	// dropdown stay visually identical.
-	// Borderless and transparent so the page's aurora shows through — an airy,
-	// floating sidebar whose only chrome is the active item's gradient pill.
+	// Borderless and transparent so the page's own surface shows through — an airy,
+	// floating sidebar whose only chrome is the active item's accent colouring.
 	".s-nav-panel": {
-		// Extra horizontal padding leaves room for the active pill's glow, which the
-		// vertical scroll (overflow-y:auto, which also clips overflow-x) would
-		// otherwise cut off at the panel edges.
+		// The generous horizontal padding is what keeps the rows clear of the content
+		// separator on one side and the shell edge on the other; the vertical scroll
+		// (overflow-y:auto, which also clips overflow-x) leaves no room to bleed past it.
 		"&": "display:flex flex-direction:column overflow-y:auto flex-shrink:0 max-width:228px padding:$3 gap:$1",
 	},
+	// The narrow-screen nav: a full "page" that slides in over the content from the
+	// left, rather than a dropdown — on a phone a nav is a screenful of UI, not a
+	// popup. Picking an item slides it back out while the chosen screen comes in
+	// from the right (see `slideContentIn`), so the two tile across the viewport
+	// and navigation reads as a lateral move between screens.
+	".s-nav-page": {
+		// It covers the body area only, so the top bar (whose trigger has become an
+		// ✕) and the footer stay put — the shell itself never blinks.
+		"&":
+			// z-index sits under the sticky header's 10: the two never overlap (the
+			// body starts below the bar), but the bar should still win if they ever do.
+			"position:absolute inset:0 z-index:5 display:flex flex-direction:column " +
+			"overflow-y:auto overscroll-behavior:contain border:0 r:0 padding:$2 gap:$1 " +
+			"transition: transform 0.3s ease;",
+		// Parked one screen to the left: the state the `create=`/`destroy=` hooks
+		// transition out of and back into.
+		"&.s-nav-page-off": "transform:translateX(-100%) pointer-events:none",
+		// Roomier rows than the dropdown's: this is the whole screen, and every row
+		// is a thumb target.
+		".s-menu-item": "padding: $2 $3; min-height:3rem font-size:1.05em gap:$3",
+	},
 	// In button-only mode (or always-button navPosition), hide the sidebar and
 	// show the trigger. In sidebar mode, show the panel and hide the trigger.
 	// CSS @container queries handle the responsive collapse automatically.
@@ -113,7 +252,7 @@ A.insertGlobalCss({
 	".s-main.s-nav-btn-only .s-nav-panel": "display:none",
 	".s-main.s-nav-btn-only .s-nav-trigger": "display:flex",
 	// Collapse sidebar → button when shell is narrow.
-	"@container (max-width: 640px)": {
+	[`@container (max-width: ${NARROW_PX}px)`]: {
 		".s-main.s-nav-left .s-nav-panel, .s-main.s-nav-right .s-nav-panel, .s-main .s-nav-sep": "display:none",
 		".s-main.s-nav-left .s-nav-trigger, .s-main.s-nav-right .s-nav-trigger": "display:flex",
 		// On phones a top-level content box becomes a full-bleed block: pull it out
@@ -131,6 +270,14 @@ A.insertGlobalCss({
  * footer. With {@link MainOptions.maxWidth} the content area is centred and its
  * width capped. Add a `nav` to get a responsive sidebar (auto-collapses to a
  * menu button below 640 px, or always a button with `navPosition: "button"`).
+ * Below 640 px that button opens the nav as a full page sliding in from the
+ * left; picking an item slides it away as the chosen screen enters from the
+ * right.
+ *
+ * Instead of a single `content` slot, pass {@link MainOptions.routes} and the
+ * shell takes over navigation: each route draws one screen, called a panel,
+ * and as many panels as fit are shown at a time, side by side on a wide screen
+ * and one at a time on a phone. See {@link MainOptions.routes} and {@link Page}.
  *
  * @example
  * ```ts
@@ -155,13 +302,50 @@ A.insertGlobalCss({
  * }
  * ```
  */
-export function main(opts: MainOptions = {}): void {
+// The self-referential constraint is what types each handler's `$page.params`
+// from its own route key. It deliberately has no default: giving `R` one makes
+// TypeScript fall back to it for contextual typing, and every `$page.params`
+// silently degrades to `any`. Callers that pass no `routes` are unaffected —
+// `MainOptions`'s own default kicks in there.
+export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
+	// Whether there is a nav to show is deliberately NOT worked out here: `items`
+	// may well be a reactive array, and reading it in the shell's own scope would
+	// subscribe *the whole shell* to it — an item arriving later would redraw the
+	// lot, and in routed mode that means tearing the panel stack down and building
+	// it again from the URL. So every use below reads `nav.items` inside its own
+	// scope, and only that scope redraws.
 	const nav = opts.nav;
 	const navPos = opts.navPosition ?? "left";
-	const hasNav = nav != null && nav.items.length > 0;
-	const navCls = hasNav ? (navPos === "button" ? ".s-nav-btn-only" : `.s-nav-${navPos}`) : "";
+	// Whether the narrow-screen full-page nav is showing. Per shell, so nested or
+	// sibling `main()`s can't fight over it.
+	const $nav = A.proxy({ open: false });
+
+	const routes = opts.routes as Routes | undefined;
+	if (routes != null && opts.content != null) {
+		throw new Error("Staffa: S.main() takes either `content` or `routes`, not both");
+	}
+	// The panel stack owns the routing, so it starts observing (and building its
+	// stack from) the URL before any of the shell is drawn — the top bar's back
+	// button already needs to know how deep we are. Its options are listed one by
+	// one rather than spread from `opts`: a spread reads every key, which on a
+	// proxied options object subscribes this scope to all of them.
+	const ctl = routes
+		? new PanelController({ routes, notFound: opts.notFound, stacking: opts.stacking, title: opts.title })
+		: null;
+	// Routed mode caps the shell to the ensemble width the layout engine publishes,
+	// rather than to `maxWidth`.
+	const capWidth = ctl ? null : opts.maxWidth;
+
+	const root = A(`div.s-main${ctl ? ".s-routed" : ""}`, opts.attrs, () => {
+		// Which nav mode the shell is in — sidebar or button — as a class on the
+		// shell, for the CSS below to hang the responsive collapse off. Its own
+		// scope (see `nav` above), so a nav appearing or emptying out only retags
+		// the shell rather than redrawing it.
+		A(() => {
+			if (nav == null || !nav.items.length) return;
+			A(navPos === "button" ? ".s-nav-btn-only" : `.s-nav-${navPos}`);
+		});
 
-	const root = A(`div.s-main${navCls}`, opts.attrs, () => {
 		// Top bar.
 		A(() => {
 			const hasBar =
@@ -169,29 +353,19 @@ export function main(opts: MainOptions = {}): void {
 				opts.subtitle != null ||
 				opts.icon != null ||
 				opts.menu != null ||
-				hasNav;
+				(nav != null && nav.items.length > 0);
 			if (!hasBar) return;
 			A("header.s-s.neutral", opts.topbarAttrs, () => {
 				A("div.s-bar", () => {
 					// Cap the bar's content to maxWidth and centre it within the full-width header.
 					A(() => {
-						if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
+						if (capWidth != null) A("max-width:", capWidth);
 					});
 					// Nav trigger button — visible when sidebar is hidden (button mode or narrow viewport).
 					A(() => {
-						if (!hasNav) return;
+						if (nav == null || !nav.items.length) return;
 						// .s-nav-trigger: CSS toggles display based on sidebar visibility.
-						A("div.s-nav-trigger", () => {
-							menuButton({
-								...nav,
-								button: {
-									icon: () => A("span aria-hidden=true #☰"),
-									ariaLabel: "Open navigation",
-									attrs: ".neutral .small",
-									...nav.button,
-								},
-							});
-						});
+						A("div.s-nav-trigger", () => drawNavTrigger(nav, $nav));
 					});
 
 					A(() => {
@@ -217,15 +391,22 @@ export function main(opts: MainOptions = {}): void {
 		A("div.s-body", () => {
 			A("div.s-body-inner", () => {
 				A(() => {
-					if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
+					if (capWidth != null) A("max-width:", capWidth);
 				});
-				if (hasNav && navPos !== "button") {
+				// The sidebar, in its own scope so a changing item list redraws just
+				// it — never the content area beside it (see `nav` above).
+				A(() => {
+					if (nav == null || !nav.items.length || navPos === "button") return;
 					A(`nav.s-nav-panel.s-nav-${navPos}`, opts.navAttrs, () => {
 						drawMenu(nav.items);
 					});
 					A("div.s-nav-sep aria-hidden=true");
-				}
-				drawMainContent(opts);
+				});
+				drawMainContent(opts, ctl);
+			});
+			// The narrow-screen nav page, laid over the body it slides across.
+			A(() => {
+				if (nav != null && nav.items.length && $nav.open) drawNavPage(nav, opts.navPageAttrs, $nav);
 			});
 		});
 
@@ -235,7 +416,7 @@ export function main(opts: MainOptions = {}): void {
 				A("footer", () => {
 					A("div.s-bar", () => {
 						A(() => {
-							if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
+							if (capWidth != null) A("max-width:", capWidth);
 						});
 						drawSlot(opts.footer);
 					});
@@ -244,16 +425,36 @@ export function main(opts: MainOptions = {}): void {
 		});
 	}) as HTMLElement;
 
-	// Escape jumps to the navigation: into the sidebar's current item when the
-	// sidebar is showing, or — when collapsed to (or always) a button — open the
-	// dropdown (which focuses its current item). Listens on `document` so it works
-	// wherever focus is, but bows out while another overlay (a dialog, or an
-	// already-open menu) is up — those handle Escape themselves.
-	if (hasNav) {
+	// Escape peels back a panel of UI, and finally jumps to the navigation: into
+	// the sidebar's current item when the sidebar is showing, or — when collapsed
+	// to (or always) a button — open the nav (dropdown or full page, whichever the
+	// shell width calls for), which focuses its current item. Listens on
+	// `document` so it works wherever focus is, but bows out while another overlay
+	// (a dialog, or an already-open menu) is up — those handle Escape themselves.
+	if (nav != null || ctl) {
 		const onKey = (e: KeyboardEvent) => {
 			if (e.key !== "Escape" || e.defaultPrevented) return;
 			// An open dialog or menu owns Escape itself — don't also jump to the nav.
 			if (isDialogOpen() || isFloatingMenuOpen()) return;
+			const trigger = root.querySelector<HTMLElement>(".s-nav-trigger button");
+			// So does the full-page nav: dismiss it and hand focus back to its trigger.
+			if ($nav.open) {
+				e.preventDefault();
+				$nav.open = false;
+				trigger?.focus();
+				return;
+			}
+			// Above the stack root, Escape closes the top panel — the same guarded
+			// close as a page's own ✕ or the browser's back button. It is, with
+			// browser back, the only way out the shell itself provides.
+			if (ctl && ctl.$state.paths.length > 1) {
+				e.preventDefault();
+				void ctl.closeTop();
+				return;
+			}
+			// Whether there is a nav at all is asked of the DOM, not of `nav.items`:
+			// a subscription here would be one on the shell's own scope again, and
+			// an empty nav simply has neither of the two elements below.
 			// `offsetParent` is null when the sidebar is hidden (display:none).
 			const panel = root.querySelector<HTMLElement>(".s-nav-panel");
 			if (panel?.offsetParent != null) {
@@ -263,7 +464,6 @@ export function main(opts: MainOptions = {}): void {
 				if (item) { e.preventDefault(); item.focus(); }
 				return;
 			}
-			const trigger = root.querySelector<HTMLElement>(".s-nav-trigger button");
 			if (trigger) { e.preventDefault(); trigger.click(); }
 		};
 		document.addEventListener("keydown", onKey);
@@ -271,7 +471,108 @@ export function main(opts: MainOptions = {}): void {
 	}
 }
 
-function drawMainContent(opts: MainOptions): void {
+/**
+ * The hamburger in the top bar, shown whenever the sidebar isn't. What it opens
+ * depends on how much room the shell has: a dropdown when there's plenty, and —
+ * below {@link NARROW_PX} — the full-page nav, which suits a phone far better
+ * than a popup. Either way a second click closes again.
+ */
+function drawNavTrigger(nav: MenuOptions, $nav: { open: boolean }): void {
+	let myEl: HTMLElement | null = null;
+	A.clean(() => { if (myEl) closeFloatingMenu(myEl); });
+
+	button({
+		// The glyph doubles as the state: ☰ to open the page, ✕ to dismiss it. Its
+		// own scope, so toggling doesn't rebuild (and re-focus) the button.
+		icon: () => A(() => ($nav.open ? closeGlyph : menuGlyph)({ size: "1.5em" })),
+		ariaLabel: "Open navigation",
+		// Quiet chrome, matching the `menu` slot's own buttons at the other end of the
+		// bar: the trigger is a way *in* to the app, not something to be sold on, and a
+		// filled brand button here shouts down the title it sits next to.
+		attrs: ".neutral .small",
+		...nav.button,
+		click: (e: Event) => {
+			myEl = e.currentTarget as HTMLElement;
+			const shell = myEl.closest<HTMLElement>(".s-main");
+			if (shell != null && shell.clientWidth <= NARROW_PX) { $nav.open = !$nav.open; return; }
+			// Wide shell: the classic dropdown. A click on the trigger never reaches
+			// the menu's own outside-click handler, so toggle it here.
+			if (isFloatingMenuOpen(myEl)) closeFloatingMenu(myEl);
+			else showFloatingMenu({ items: nav.items, anchor: myEl, dropdownAttrs: nav.dropdownAttrs });
+		},
+	});
+}
+
+/**
+ * The narrow-screen navigation: a full page sliding in over the content from the
+ * left. Picking an item slides it back out while the chosen screen enters from
+ * the right, so the two tile across the viewport and the whole thing reads as a
+ * lateral move rather than a popup blinking out.
+ */
+function drawNavPage(nav: MenuOptions, attrs: Attributes | undefined, $nav: { open: boolean }): void {
+	// Whether this close is a *navigation* — the only kind that hands over to an
+	// incoming screen. Dismissing the page just uncovers the content again.
+	let navigated = false;
+
+	const pageEl = A(
+		"nav.s-nav-page.s-s.neutral aria-label=Navigation create=s-nav-page-off destroy=s-nav-page-off",
+		attrs,
+		() => drawMenu(nav.items, () => { navigated = true; $nav.open = false; }),
+	) as HTMLElement;
+
+	const shell = pageEl.closest<HTMLElement>(".s-main");
+	const behind = pageEl.parentElement?.querySelector<HTMLElement>(":scope > .s-body-inner");
+	// Content mode's incoming half of the hand-off. In routed mode there is no
+	// <main> to slide: the chosen screen is a freshly pushed panel, which plays
+	// its own enter animation, so this correctly finds nothing.
+	const content = behind?.querySelector<HTMLElement>(":scope > main");
+
+	// The content is fully covered, but without this it stays tabbable and visible
+	// to screen readers underneath the page.
+	behind?.setAttribute("inert", "");
+
+	// Widening the shell past the collapse point brings the sidebar back, leaving
+	// this page covering the content for no reason — so bow out.
+	if (shell != null && typeof ResizeObserver !== "undefined") {
+		const ro = new ResizeObserver(() => { if (shell.clientWidth > NARROW_PX) $nav.open = false; });
+		ro.observe(shell);
+		A.clean(() => ro.disconnect());
+	}
+
+	A.clean(() => {
+		behind?.removeAttribute("inert");
+		if (!navigated) return;
+		// Same tick as the page's own destroy transition, so both halves of the
+		// hand-off move in lockstep.
+		if (content) slideContentIn(content);
+		shell?.querySelector<HTMLElement>(".s-nav-trigger button")?.focus();
+	});
+
+	// Land on the current page's entry (or the first one) once we're laid out.
+	requestAnimationFrame(() => {
+		if (document.body.contains(pageEl)) focusFirst(pageEl, ".s-menu-item[aria-current=page]");
+	});
+}
+
+/**
+ * Play the incoming half of the nav-page hand-off: park `el` one screen to the
+ * right, then let its CSS transition carry it home. Reading `offsetWidth` in
+ * between forces the browser to adopt the parked position as the "before" state,
+ * which is what makes the removal animate instead of doing nothing at all.
+ */
+function slideContentIn(el: HTMLElement): void {
+	el.classList.add("s-slide-in");
+	void el.offsetWidth;
+	el.classList.remove("s-slide-in");
+}
+
+function drawMainContent(opts: MainOptions<any>, ctl: PanelController | null): void {
+	// Routed mode replaces the single scrollable <main> with the panel viewport,
+	// which manages its own columns (and their scrolling) from JS.
+	if (ctl) {
+		ctl.drawStack();
+		return;
+	}
 	const mainEl = A("main", () => {
 		A("div.s-content", opts.contentAttrs, () => {
 			drawSlot(opts.content);