staffa 0.8.1 → 0.10.0

package/dist/components/main.js

@@ -1,9 +1,14 @@
 import A from "aberdeen";
+import { current as currentRoute, matchCurrent } from "aberdeen/route";
 import { drawSlot, focusFirst, NARROW_PX } from "../core.js";
-import { drawMenu, showFloatingMenu, isFloatingMenuOpen, closeFloatingMenu, menuGlyph, closeGlyph } from "./menu.js";
-import { button } from "./button.js";
+import { drawMenu, isFloatingMenuOpen, consumeBranchNav } from "./menu.js";
+// The shell's own chrome glyphs, from the same Lucide set an app draws with —
+// so a nav trigger sits beside app icons as an equal. Named imports, so a
+// bundler keeps these two and tree-shakes the other ~1950 away.
+import { menu as menuIcon, x as closeIcon } from "../icons.js";
+import { iconButton } from "./button.js";
 import { isDialogOpen } from "./dialog.js";
-import { PanelController } from "./panels.js";
+import { PanelStackController } from "./panels.js";
 A.insertGlobalCss({
     ".s-main": {
         // container-type so @container queries below can respond to shell width.
@@ -18,16 +23,34 @@ A.insertGlobalCss({
         // radius down to just the bottom divider (it spans edge to edge).
         "> header": "border:0 border-bottom: 1px solid $s-faint; r:0 position:sticky top:0 z-index:10",
         "> footer": "border-top: 1px solid $s-faint; fg:$s-muted",
+        // The bar reads `[leading] [title] …spacer… [trailing]`. The spacer is the
+        // trailing slot's own growth: it takes the free space and right-aligns
+        // itself in it, which is what lets a search box live there. It doesn't
+        // shrink, and the title does — so the title is what truncates when the two
+        // compete, and the app's chrome stays usable.
         "> header > .s-bar, > footer > .s-bar": "display:flex align-items:center width:100% margin-inline:auto gap:$3 padding: $2 $3;",
-        "> header .s-header-icon": "display:flex align-items:center font-size:1.4em background: $s-gradient; -webkit-background-clip:text; background-clip:text; color:transparent;",
-        "> header .s-titles": "display:flex flex-direction:column min-width:0 flex:1",
+        "> header .s-logo, > header .s-nav-trigger": "display:flex align-items:center flex-shrink:0",
+        // The ☰ is a glyph in a 2rem hit area, so it carries ~6px of its own
+        // padding: pull it back by that, and the glyph — not its hit area — lines
+        // up with the bar's edge and with the stack below.
+        "> header .s-nav-trigger": "margin-left:-0.375rem",
+        "> header .s-logo": "font-size:1.4em background: $s-gradient; -webkit-background-clip:text; background-clip:text; color:transparent;",
+        "> header .s-titles": "display:flex flex-direction:column min-width:0 flex: 0 1 auto;",
+        // Same font-size and line-height as `.s-crumb`, because in routed mode the
+        // two take turns on this line (see `drawSecondLine`): a different height
+        // would jog the whole bar as they swap.
+        "> header .s-subtitle": "fg:$s-muted font-size:0.85em line-height:1.5 overflow:hidden text-overflow:ellipsis white-space:nowrap",
         "> header .s-title": "font-weight:800 font-size:1.1em line-height:1.2 overflow:hidden text-overflow:ellipsis white-space:nowrap letter-spacing:-0.01em background: $s-gradient; -webkit-background-clip:text; background-clip:text; color:transparent; width:fit-content max-width:100%",
-        "> header .s-subtitle": "fg:$s-muted font-size:0.85em overflow:hidden text-overflow:ellipsis white-space:nowrap",
-        "> header .s-menu": "display:flex align-items:center gap:$2",
+        // In routed mode the logo and the app's name are links to the app's home:
+        // strip the reset's link chrome down to the styling the div forms carry,
+        // which their classes then provide. (`filter:none` keeps the global
+        // `a:hover` brighten off the gradient text.)
+        "> header a.s-logo, > header a.s-title": "text-decoration:none filter:none cursor:pointer",
+        "> header .s-menu": "display:flex align-items:center justify-content:flex-end gap:$2 flex: 1 0 auto;",
         // 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.
-        // It's also the positioning + clipping context for the narrow-screen nav page,
+        // It's also the positioning + clipping context for the narrow-screen nav panel,
         // 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",
@@ -41,9 +64,9 @@ A.insertGlobalCss({
         // the whole body — and any sidebar — past the viewport edge). overflow-x:hidden
         // clips overlong content on the right; vertically it scrolls.
         // The transition is dormant (nothing else moves <main>); it's there for the
-        // incoming half of the nav-page hand-off — see `slideContentIn`.
+        // incoming half of the nav-panel 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;",
+            "transition: transform var(--s-panel-ms) 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",
@@ -57,10 +80,10 @@ 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
+        // Routed mode takes its width from the 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
+        // normally, the window's edges while a "screen" page 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%);",
@@ -78,7 +101,7 @@ A.insertGlobalCss({
     // 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 own surface shows through — an airy,
+    // Borderless and transparent so the panel's own surface shows through — an airy,
     // floating sidebar whose only chrome is the active item's accent colouring.
     ".s-nav-panel": {
         // The generous horizontal padding is what keeps the rows clear of the content
@@ -86,7 +109,7 @@ A.insertGlobalCss({
         // (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
+    // The narrow-screen nav: a full "panel" 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
@@ -99,7 +122,7 @@ A.insertGlobalCss({
         // 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;",
+            "transition: transform var(--s-panel-ms) 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",
@@ -107,16 +130,14 @@ A.insertGlobalCss({
         // 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.
-    ".s-main.s-nav-left .s-nav-trigger, .s-main.s-nav-right .s-nav-trigger": "display:none",
-    ".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.
+    // Collapse the sidebar when the shell is narrow. The ☰ that replaces it isn't
+    // hidden here but simply not drawn (see `main()`), because the same boolean
+    // also decides what the rest of the bar shows — one decision, in one place.
     [`@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",
+        ".s-main .s-nav-panel, .s-main .s-nav-sep": "display:none",
+        // A phone's bar holds two lines of chrome in a screen's width, so it buys
+        // the stack and the screen's actions room by spending less on air.
+        ".s-main > header > .s-bar": "gap:$1 padding: $1 $2;",
         // On phones a top-level content box becomes a full-bleed block: pull it out
         // to negate the content padding and drop the rounded corners.
         ".s-content > .s-box": "margin-inline: calc(-1 * $3); r:0 border-inline:0",
@@ -125,54 +146,11 @@ A.insertGlobalCss({
         ".s-main .s-body main.s-scroll-y": "margin-right:0",
     },
 });
-/**
- * An application shell that wires up the things almost every app needs: a sticky
- * top bar (icon, title, subtitle, action menu), a scrollable content area, and a
- * 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
- * S.main({
- *   icon: "✦",
- *   title: "Staffa Demo",
- *   maxWidth: "56rem",
- *   nav: {
- *     items: [
- *       { label: "Home", icon: () => A("#🏠"), href: "/" },
- *       { label: "Settings", href: "/settings" },
- *     ],
- *   },
- *   navPosition: "left",
- *   menu: () => S.button({ content: "New", attrs: ".small" }),
- *   content: drawPage,
- *   footer: "© 2026",
- * });
- *
- * function drawPage() {
- *   S.box({title: "Hello world", content: "Here's you app.."});
- * }
- * ```
- */
-// 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(opts = {}) {
     // 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
+    // lot, and in routed mode that means tearing the 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;
@@ -180,36 +158,59 @@ export function main(opts = {}) {
     // 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 });
+    // Whether the shell is narrow: its container is at or below NARROW_PX, the
+    // very threshold the `@container` queries above switch the sidebar on. One
+    // boolean, read by everything that has to agree about which regime we are in —
+    // the bar's layout, what the ☰ does, and where a panel's chrome goes — so they
+    // cannot drift apart. Its initial value is a guess from the viewport (a shell
+    // is rarely wider than that) which `watchNarrow` corrects before the first
+    // paint; guessing well just saves a redraw of anything keyed on it.
+    const $shell = A.proxy({
+        narrow: typeof document !== "undefined" && document.documentElement.clientWidth <= NARROW_PX,
+    });
     const routes = opts.routes;
     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
+    // The 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 })
+        ? new PanelStackController({
+            routes,
+            notFound: opts.notFound,
+            ancestors: opts.ancestors,
+            stacking: opts.stacking,
+            title: opts.title,
+            $shell,
+        })
         : 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.
+        // Which side the sidebar is on, as a class on the shell for the CSS above to
+        // hang 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}`);
+            A(`.s-nav-${navPos}`);
         });
-        // Top bar.
+        // Top bar: `[leading] [identity] …spacer… [trailing]`, where each slot's
+        // contents depend on how much room the shell has and — in routed mode — on
+        // what the current panel declared. Each is its own scope, so a resize across
+        // the threshold or a panel renaming itself moves the chrome without
+        // disturbing anything else. A routed shell always has a bar: it is where
+        // the breadcrumb stack lives, and where a panel's actions land once the
+        // shell is narrow.
         A(() => {
-            const hasBar = opts.title != null ||
+            const hasBar = ctl != null ||
+                opts.title != null ||
                 opts.subtitle != null ||
-                opts.icon != null ||
+                opts.logo != null ||
                 opts.menu != null ||
                 (nav != null && nav.items.length > 0);
             if (!hasBar)
@@ -221,30 +222,56 @@ export function main(opts = {}) {
                         if (capWidth != null)
                             A("max-width:", capWidth);
                     });
-                    // Nav trigger button — visible when sidebar is hidden (button mode or narrow viewport).
+                    // Leading: the ☰ once the nav has collapsed, the logo otherwise.
+                    // Deliberately no back button, at any width: going back is the
+                    // stack's job in both regimes (plus Escape and the browser's own
+                    // back). A « here would hand a narrow shell a way out that a wide
+                    // one hasn't got, and it would have to displace the ☰ to fit —
+                    // leaving a phone with no way to the app's navigation at all
+                    // until it had closed its way back to the stack's first panel.
                     A(() => {
-                        if (nav == null || !nav.items.length)
+                        if ($shell.narrow) {
+                            if (nav != null && nav.items.length) {
+                                A("div.s-nav-trigger", () => drawNavTrigger(nav, $nav));
+                                return;
+                            }
+                        }
+                        if (opts.logo == null)
                             return;
-                        // .s-nav-trigger: CSS toggles display based on sidebar visibility.
-                        A("div.s-nav-trigger", () => drawNavTrigger(nav, $nav));
-                    });
-                    A(() => {
-                        if (opts.icon != null)
-                            A("div.s-header-icon", () => drawSlot(opts.icon));
+                        // In routed mode the brand mark is a link to the app's home,
+                        // twinned with the app's name beside it — a real link, so it
+                        // has an address to hover, middle-click and copy, and a click
+                        // runs the shell's usual link rules.
+                        A(ctl ? "a.s-logo aria-label=Home" : "div.s-logo", () => {
+                            if (ctl)
+                                A("href=", opts.home ?? "/");
+                            drawSlot(opts.logo);
+                        });
                     });
+                    // The identity block: the brand on the first line — always; a
+                    // routed shell never renames itself, because the breadcrumb stack
+                    // on the line beneath already says where you are, in both regimes.
+                    // The name links to the app's home, the counterpart of the
+                    // crumbs it sits above.
                     A("div.s-titles", () => {
                         A(() => {
-                            if (opts.title != null)
-                                A("div.s-title", () => drawSlot(opts.title));
-                        });
-                        A(() => {
-                            if (opts.subtitle != null)
-                                A("div.s-subtitle", () => drawSlot(opts.subtitle));
+                            if (opts.title == null)
+                                return;
+                            A(ctl ? "a.s-title" : "div.s-title", () => {
+                                if (ctl)
+                                    A("href=", opts.home ?? "/");
+                                drawSlot(opts.title);
+                            });
                         });
+                        drawSecondLine(opts, ctl, nav, $shell);
                     });
+                    // Trailing: on a narrow shell the screen's own verbs win the space,
+                    // and a screen with none of its own leaves the app's chrome up.
                     A(() => {
-                        if (opts.menu)
-                            A("div.s-menu", () => drawSlot(opts.menu));
+                        const actions = $shell.narrow ? ctl?.currentPanel?.actions : undefined;
+                        const slot = actions ?? opts.menu;
+                        if (slot != null)
+                            A("div.s-menu", () => drawSlot(slot));
                     });
                 });
             });
@@ -260,7 +287,7 @@ export function main(opts = {}) {
                 // 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")
+                    if (nav == null || !nav.items.length)
                         return;
                     A(`nav.s-nav-panel.s-nav-${navPos}`, opts.navAttrs, () => {
                         drawMenu(nav.items);
@@ -269,10 +296,10 @@ export function main(opts = {}) {
                 });
                 drawMainContent(opts, ctl);
             });
-            // The narrow-screen nav page, laid over the body it slides across.
+            // The narrow-screen nav panel, laid over the body it slides across.
             A(() => {
                 if (nav != null && nav.items.length && $nav.open)
-                    drawNavPage(nav, opts.navPageAttrs, $nav);
+                    drawNavPage(nav, opts.navPageAttrs, $nav, $shell);
             });
         });
         // Footer — full-width background, content centred to maxWidth via .s-bar.
@@ -290,12 +317,13 @@ export function main(opts = {}) {
             }
         });
     });
+    watchNarrow(root, $shell);
     // 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.
+    // the sidebar's current item when the sidebar is showing, or — when it has
+    // collapsed to the ☰ — open the full-page nav, which focuses its current item.
+    // Listens on `document` so it works wherever focus is, but bows out while
+    // another overlay (a dialog, or an open menu) is up — those handle Escape
+    // themselves.
     if (nav != null || ctl) {
         const onKey = (e) => {
             if (e.key !== "Escape" || e.defaultPrevented)
@@ -311,22 +339,25 @@ export function main(opts = {}) {
                 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) {
+            // With a panel to the current one's left, Escape steps back along the
+            // stack: it closes the current panel when that panel is the stack's
+            // last, and just goes one panel left when panels are parked beyond it.
+            // A panel holding unsaved work isn't closed but parked, like a
+            // mid-stack one. There is no button for this — the crumbs are the
+            // pointing device's way back.
+            if (ctl && ctl.currentPanelIndex > 0) {
                 e.preventDefault();
-                void ctl.closeTop();
+                void ctl.back();
                 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(".s-nav-panel");
-            if (panel?.offsetParent != null) {
-                const item = panel.querySelector("[aria-current=page]") ??
-                    panel.querySelector(".s-menu-item:not([aria-disabled=true])");
+            const sidebar = root.querySelector(".s-nav-panel");
+            if (sidebar?.offsetParent != null) {
+                const item = sidebar.querySelector("[aria-current=page]") ??
+                    sidebar.querySelector(".s-menu-item:not([aria-disabled=true])");
                 if (item) {
                     e.preventDefault();
                     item.focus();
@@ -341,54 +372,151 @@ export function main(opts = {}) {
         document.addEventListener("keydown", onKey);
         A.clean(() => document.removeEventListener("keydown", onKey));
     }
+    // The stack is this shell's, not the app's: it is handed back rather than
+    // parked in a module-level global, so nothing can reach a shell it isn't in.
+    return ctl ?? undefined;
 }
 /**
- * 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.
+ * Dismisses the collapsed nav if it's showing: at most one shell has its nav up
+ * as an overlay at a time, so this needs nothing passed in. Set by the thing
+ * that opens one (see {@link closeNav}).
+ */
+let openNav = null;
+/**
+ * Close the navigation, if it's showing as an overlay — the full panel it becomes
+ * on a narrow shell. A sidebar isn't an overlay and has nothing to dismiss, so
+ * on a wider shell this does nothing.
+ *
+ * A navigation closes the nav by itself, links in your own custom rows included,
+ * so this is for the items that *don't* navigate — one that opens a dialog, or
+ * flips a setting, and should still get the nav out of the way.
+ *
+ * @example
+ * ```ts
+ * S.main({
+ *   nav: { items: [
+ *     { label: "Inbox", href: "/inbox" },
+ *     () => S.button({ content: "New message", click: () => { S.closeNav(); compose(); } }),
+ *   ]},
+ *   routes: { ... },
+ * });
+ * ```
+ */
+export function closeNav() {
+    openNav?.();
+}
+/**
+ * The line under the app's name: the breadcrumb stack, or the app's own
+ * {@link MainOptions.subtitle} in its place.
+ *
+ * A routed shell hands the line to the tagline only while the crumbs would be
+ * repeating what is already on screen — one panel open, that panel being a nav
+ * item's own screen, and the sidebar there to show it highlighted. That last
+ * condition is why a narrow shell always keeps the stack: the nav is behind the
+ * ☰ there, so nothing else names the screen. An app with no subtitle to show
+ * never asks any of this, and its crumbs simply mount once.
+ *
+ * One scope for the whole decision, so a navigation, a resize across the
+ * threshold or a nav item arriving swaps the line without disturbing the bar
+ * around it — and so that reading `nav.items` subscribes this line alone,
+ * never the shell entire (see `nav` in `main()`).
+ */
+function drawSecondLine(opts, ctl, nav, $shell) {
+    A(() => {
+        // Short-circuit first: with no subtitle, nothing below is read, so the
+        // crumbs keep the line for good and this scope never re-runs.
+        if (opts.subtitle != null && (ctl == null || taglineFits(ctl, nav, $shell))) {
+            A("div.s-subtitle", () => drawSlot(opts.subtitle));
+            return;
+        }
+        ctl?.drawCrumbs();
+    });
+}
+/**
+ * Whether the stack would only be saying what the sidebar already says: a
+ * single panel open, the sidebar on screen, and that panel being one of the nav's
+ * own rows.
+ *
+ * The row test is {@link matchCurrent} — the very thing that marks a row
+ * `aria-current=page` — so "the crumb is redundant" and "the sidebar has it
+ * highlighted" can never come apart. It compares whole paths, so it is true
+ * only for a nav item's own screen, never for one opened beneath it.
+ */
+function taglineFits(ctl, nav, $shell) {
+    if ($shell.narrow || nav == null)
+        return false;
+    if (ctl.panels.length > 1)
+        return false;
+    return nav.items.some((entry) => typeof entry !== "string" &&
+        typeof entry !== "function" &&
+        !("separator" in entry) &&
+        entry.href != null &&
+        matchCurrent(entry.href));
+}
+/**
+ * Track whether the shell is narrow, for everything that has to agree about it.
+ *
+ * The *content* box is what's measured, because that is what an `inline-size`
+ * `@container` query measures: reading `clientWidth` instead would count any
+ * padding a caller put on the shell, and the JS and the CSS would then disagree
+ * about the regime at exactly the widths where it matters.
+ */
+function watchNarrow(root, $shell) {
+    if (typeof ResizeObserver === "undefined")
+        return;
+    const ro = new ResizeObserver((entries) => {
+        const box = entries[0]?.contentBoxSize?.[0];
+        const width = box ? box.inlineSize : entries[0]?.contentRect.width;
+        if (width != null)
+            $shell.narrow = width <= NARROW_PX;
+    });
+    ro.observe(root);
+    A.clean(() => ro.disconnect());
+}
+/**
+ * The hamburger in the top bar, which is where the sidebar goes when the shell
+ * is too narrow to hold one. It opens the nav as a full panel — on a phone a nav
+ * is a screenful of UI, not a popup — and a second click closes it again.
+ *
+ * A bare glyph, like the ✕ on a panel: the trigger
+ * is a way *in* to the app, not something to be sold on, and a bordered box
+ * around it shouts down the title it sits beside.
  */
 function drawNavTrigger(nav, $nav) {
-    let myEl = null;
-    A.clean(() => { if (myEl)
-        closeFloatingMenu(myEl); });
-    button({
-        // The glyph doubles as the state: ☰ to open the page, ✕ to dismiss it. Its
+    iconButton({
+        // The glyph doubles as the state: ☰ to open the panel, ✕ 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) => {
-            myEl = e.currentTarget;
-            const shell = myEl.closest(".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 });
-        },
+        icon: nav.button?.icon ?? (() => A(() => ($nav.open ? closeIcon : menuIcon)())),
+        ariaLabel: nav.button?.ariaLabel ?? "Open navigation",
+        attrs: nav.button?.attrs,
+        click: () => { $nav.open = !$nav.open; },
     });
 }
 /**
- * The narrow-screen navigation: a full page sliding in over the content from the
+ * The narrow-screen navigation: a full panel 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, attrs, $nav) {
+function drawNavPage(nav, attrs, $nav, $shell) {
     // Whether this close is a *navigation* — the only kind that hands over to an
-    // incoming screen. Dismissing the page just uncovers the content again.
+    // incoming screen. Dismissing the panel 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; }));
+    const dismiss = () => { navigated = true; $nav.open = 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, dismiss));
+    // This is the shell's one nav overlay, so `closeNav()` knows where to aim.
+    openNav = dismiss;
+    A.clean(() => { if (openNav === dismiss)
+        openNav = null; });
+    // Whatever the panel navigated to, it hands over to: the items do that
+    // themselves (`dismiss` above), but custom slot content — a link in a row the
+    // shell knows nothing about — doesn't, and neither does a navigation from
+    // anywhere else. A branch row expanding is the exception: it navigates in
+    // order to unfold, and the nav should stay up while the user works down the
+    // tree. Its own scope, so it can't redraw the panel it closes.
+    const openedAt = A.peek(currentRoute, "path");
+    A(() => { if (currentRoute.path !== openedAt && !consumeBranchNav(currentRoute.path))
+        dismiss(); });
     const shell = pageEl.closest(".s-main");
     const behind = pageEl.parentElement?.querySelector(":scope > .s-body-inner");
     // Content mode's incoming half of the hand-off. In routed mode there is no
@@ -396,34 +524,32 @@ function drawNavPage(nav, attrs, $nav) {
     // its own enter animation, so this correctly finds nothing.
     const content = behind?.querySelector(":scope > main");
     // The content is fully covered, but without this it stays tabbable and visible
-    // to screen readers underneath the page.
+    // to screen readers underneath the panel.
     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());
-    }
+    // this panel covering the content for no reason — so bow out. Read from the
+    // shell's own flag rather than measured again here, so the panel and the ☰ that
+    // opened it never disagree about whether the shell is still narrow.
+    A(() => { if (!$shell.narrow)
+        $nav.open = false; });
     A.clean(() => {
         behind?.removeAttribute("inert");
         if (!navigated)
             return;
-        // Same tick as the page's own destroy transition, so both halves of the
+        // Same tick as the panel's own destroy transition, so both halves of the
         // hand-off move in lockstep.
         if (content)
             slideContentIn(content);
         shell?.querySelector(".s-nav-trigger button")?.focus();
     });
-    // Land on the current page's entry (or the first one) once we're laid out.
+    // Land on the current panel'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
+ * Play the incoming half of the nav-panel 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.
@@ -434,10 +560,10 @@ function slideContentIn(el) {
     el.classList.remove("s-slide-in");
 }
 function drawMainContent(opts, ctl) {
-    // Routed mode replaces the single scrollable <main> with the panel viewport,
+    // Routed mode replaces the single scrollable <main> with the column viewport,
     // which manages its own columns (and their scrolling) from JS.
     if (ctl) {
-        ctl.drawStack();
+        ctl.drawColumns();
         return;
     }
     const mainEl = A("main", () => {