staffa 0.10.1 → 0.12.0

package/src/components/main.ts

@@ -1,7 +1,7 @@
 import A from "aberdeen";
-import { current as currentRoute, matchCurrent } from "aberdeen/route";
+import { current as currentRoute } from "aberdeen/route";
 import { type Slot, type Attributes, drawSlot, focusFirst, NARROW_PX } from "../core.js";
-import { type MenuOptions, type MenuEntry, drawMenu, isFloatingMenuOpen, consumeBranchNav } from "./menu.js";
+import { type MenuOptions, drawMenu, isFloatingMenuOpen, consumeBranchNav, anyCurrent } 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.
@@ -50,9 +50,11 @@ export interface MainOptions<R = Routes> {
 	 * when your home screen lives elsewhere. It's an ordinary link, so the
 	 * usual rules apply: a home that is already open in the stack — its first
 	 * panel, usually — is returned to, closing nothing, and one that isn't is
-	 * opened the way a nav item would be. Routed mode only.
+	 * opened the way a nav item would be. Pass `null` to link neither — for a
+	 * `title` or `logo` slot holding interactive content of its own, which
+	 * can't sit inside a link. Routed mode only.
 	 */
-	home?: string;
+	home?: string | null;
 	/**
 	 * The app's own chrome, at the trailing end of the top bar: an account
 	 * button, a global search box, a settings menu. It may grow into the bar's
@@ -187,12 +189,31 @@ export interface MainOptions<R = Routes> {
 	// `$panel` would quietly degrade to `any` (see the note on `main` below).
 	ancestors?: AncestorTable<NoInfer<R>>;
 	/**
-	 * Set `false` to show only the current panel, however wide the screen (the
-	 * nav sidebar still sits beside it). Everything else behaves the same: the
-	 * URL, the back button, unsaved panels, and the panels' own close buttons.
-	 * This only changes how many you see. Defaults to `true`.
+	 * How many panels are *shown* at a time. `"auto"` (the default) shows as
+	 * many columns, side by side, as comfortably fit, ending at the current
+	 * panel; `"single"` shows only the current panel, however wide the screen
+	 * — the phone experience at every size (the nav sidebar still sits beside
+	 * it). Only the display differs: the stack, the breadcrumbs, the URL,
+	 * Escape and the back button behave identically in both. Routed mode only.
+	 *
+	 * Live: pass a proxied options object (or make this field a getter) and a
+	 * change is adopted in place — one layout pass, every panel keeping its
+	 * state.
+	 */
+	columns?: "auto" | "single";
+	/**
+	 * What a link *without* a `data-panel` attribute does — the per-link
+	 * attribute always wins. `"push"` (the default) opens the target on top of
+	 * the panel the link sits in; `"replace"` opens it in that panel's place;
+	 * `"open"` gives it its own stack, the way a nav item does. With `"open"`
+	 * every click replaces the content as a whole — which, with flat routes,
+	 * is the conventional sidebar-and-content app: one pane, swapped on every
+	 * click, the crumb line simply naming it. Routed mode only.
+	 *
+	 * Live, like {@link MainOptions.columns}: change it and the next click
+	 * uses the new default.
 	 */
-	stacking?: boolean;
+	linkNavigation?: "push" | "replace" | "open";
 	/** Footer content, pinned below the scroll area. */
 	footer?: Slot;
 	/**
@@ -256,9 +277,11 @@ A.insertGlobalCss({
 		"> 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.
+		// itself in it, which is what lets a search box live there. When the two
+		// compete, the title truncates first — but only down to a floor, past
+		// which the trailing slot shrinks instead: a wide search box must not
+		// starve the titles to nothing (the crumb strip's overlay buttons would
+		// escape their zero-width strip, over the ☰ beside it).
 		"> header > .s-bar, > footer > .s-bar": "display:flex align-items:center width:100% margin-inline:auto gap:$3 padding: $2 $3;",
 		"> 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
@@ -266,7 +289,7 @@ A.insertGlobalCss({
 		// 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;",
+		"> header .s-titles": "display:flex flex-direction:column min-width:5rem 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.
@@ -277,7 +300,7 @@ A.insertGlobalCss({
 		// 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;",
+		"> header .s-menu": "display:flex align-items:center justify-content:flex-end gap:$2 flex: 1 1 auto; min-width:0",
 		// 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.
@@ -356,10 +379,12 @@ 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 var(--s-panel-ms) ease;",
+			"transition: transform var(--s-panel-ms) ease, visibility var(--s-panel-ms);",
 		// 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",
+		// transition out of and back into. `visibility` flips at the slide's end
+		// (see `.s-menu-list` in menu.ts): the dismissed page lingers off screen
+		// until Aberdeen's removal timer, and mustn't stay reachable meanwhile.
+		"&.s-nav-page-off": "transform:translateX(-100%) pointer-events:none visibility:hidden",
 		// 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",
@@ -467,11 +492,22 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): PanelS
 			routes,
 			notFound: opts.notFound,
 			ancestors: opts.ancestors,
-			stacking: opts.stacking,
 			title: opts.title,
 			$shell,
 		})
 		: null;
+	if (ctl) {
+		// `columns` and `linkNavigation` are live: each is read in a scope of
+		// its own, so when the options object is a proxy (or the field a
+		// getter), a change re-runs just that scope — the columns relayout in
+		// place with every panel's state intact, and the next click picks up
+		// the new link default. Nothing else of the shell is touched.
+		A(() => ctl.setColumns(opts.columns));
+		A(() => ctl.setLinkNavigation(opts.linkNavigation));
+	}
+	// Where the brand mark and the app's name link — or nowhere, when the app
+	// said `home: null` (a title slot holding a control of its own, say).
+	const homeHref = ctl && opts.home !== null ? opts.home ?? "/" : null;
 	// Routed mode caps the shell to the ensemble width the layout engine publishes,
 	// rather than to `maxWidth`.
 	const capWidth = ctl ? null : opts.maxWidth;
@@ -527,8 +563,8 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): PanelS
 						// 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 ?? "/");
+						A(homeHref != null ? "a.s-logo aria-label=Home" : "div.s-logo", () => {
+							if (homeHref != null) A("href=", homeHref);
 							drawSlot(opts.logo);
 						});
 					});
@@ -541,8 +577,8 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): PanelS
 					A("div.s-titles", () => {
 						A(() => {
 							if (opts.title == null) return;
-							A(ctl ? "a.s-title" : "div.s-title", () => {
-								if (ctl) A("href=", opts.home ?? "/");
+							A(homeHref != null ? "a.s-title" : "div.s-title", () => {
+								if (homeHref != null) A("href=", homeHref);
 								drawSlot(opts.title);
 							});
 						});
@@ -551,10 +587,13 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): PanelS
 
 					// 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.
+					// Promoted actions are marked as the current panel's own chrome
+					// (`.s-panel-origin`), so a link among them still builds on that
+					// panel — see `interceptLinks` in panels.ts.
 					A(() => {
 						const actions = $shell.narrow ? ctl?.currentPanel?.actions : undefined;
 						const slot = actions ?? opts.menu;
-						if (slot != null) A("div.s-menu", () => drawSlot(slot));
+						if (slot != null) A(`div.s-menu${actions != null ? ".s-panel-origin" : ""}`, () => drawSlot(slot));
 					});
 				});
 			});
@@ -720,23 +759,18 @@ function drawSecondLine(
 
 /**
  * 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.
+ * single panel open, the sidebar on screen, and that panel being one of the
+ * nav's own rows — a leaf inside a submenu counts, since the sidebar shows it
+ * highlighted (inside its unfolded branch) all the same.
  *
- * 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.
+ * The row test is the menu's own {@link anyCurrent} — 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.
  */
 function taglineFits(ctl: PanelStackController, nav: MenuOptions | undefined, $shell: { narrow: boolean }): boolean {
 	if ($shell.narrow || nav == null) return false;
 	if (ctl.panels.length > 1) return false;
-	return nav.items.some((entry: MenuEntry) =>
-		typeof entry !== "string" &&
-		typeof entry !== "function" &&
-		!("separator" in entry) &&
-		entry.href != null &&
-		matchCurrent(entry.href));
+	return anyCurrent(nav.items);
 }
 
 /**

package/src/components/menu.ts

@@ -30,6 +30,17 @@ export interface MenuItem {
 	 * `attrs: "data-panel=push"` for a row that should stack instead.
 	 */
 	href?: string;
+	/**
+	 * Pages this item claims *beyond* its own `href`: a string claims that path
+	 * and everything under it (`"/mail"` claims `/mail/…`, not `/mailbox`), a
+	 * function is asked with the current path. While a claimed page is current,
+	 * the item is highlighted and the branches above it stay unfolded — for the
+	 * detail screens a menu has no row of their own: the `/thread/[id]` a
+	 * notification lands on, an icon's page under the gallery's row. Claims
+	 * work from the very first paint, so they also cover cold deep links,
+	 * which no amount of fold-state keeping can.
+	 */
+	match?: string | ((path: string) => boolean);
 	/** `target` for the link (`_blank`, etc.). Only meaningful with `href`. */
 	target?: string;
 	/** Disables the item. */
@@ -38,11 +49,13 @@ export interface MenuItem {
 	attrs?: Attributes;
 	/**
 	 * Child entries, which turn the item into a collapsible **branch** of a
-	 * tree. Only the branch holding the current page is expanded; navigate away
-	 * and it folds back up. Clicking a branch *selects* rather than toggles: it
-	 * follows the item's own `href`, or failing that the first linked leaf
-	 * below it — which is what expands it. A branch with no link anywhere below
-	 * it falls back to plain open/close toggling.
+	 * tree. Only the branch holding the current page is expanded; navigate to
+	 * another page in the menu and it folds back up. (Navigating to a page the
+	 * menu doesn't hold *anywhere* leaves every fold as it was: there is no
+	 * better answer to fold up to.) Clicking a branch *selects* rather than
+	 * toggles: it follows the item's own `href`, or failing that the first
+	 * linked leaf below it — which is what expands it. A branch with no link
+	 * anywhere below it falls back to plain open/close toggling.
 	 *
 	 * Expanding is not selecting: a branch click never counts as picking an
 	 * item (see `onLeafSelect` on {@link menu}), so on a phone the nav stays up
@@ -131,12 +144,17 @@ export type ContextMenuOptions = Omit<FloatingMenuOptions, "anchor" | "at" | "cl
 A.insertGlobalCss({
 	// Border comes from the `.s-s.neutral` surface; the panel only overrides the radius
 	// (lg) and opts into elevation via `.shadow` (added on the element below).
+	// `visibility` rides the same transition as the fade (flipping only at its
+	// end, per CSS visibility interpolation): a dismissed menu lingers in the
+	// DOM for a while — Aberdeen's `destroy=` removes it on a timer, not at
+	// the transition's end — and without this it would spend that time
+	// invisible yet still hittable by tests and read by assistive tech.
 	".s-menu-list":
 		"position:fixed z-index:350 min-width:10rem display:flex flex-direction:column p:$1 " +
 		"r:$s-radius-lg " +
 		"overflow-y:auto max-height:min(80vh,28rem) " +
-		"transition: opacity 0.15s, transform 0.15s;",
-	".s-menu-list.hidden": "opacity:0 pointer-events:none transform:translateY(-6px)",
+		"transition: opacity 0.15s, transform 0.15s, visibility 0.15s;",
+	".s-menu-list.hidden": "opacity:0 pointer-events:none transform:translateY(-6px) visibility:hidden",
 	// One class for both the `<a>` (link) and `<button>` forms — they look
 	// identical; the element only differs where link semantics matter (see below).
 	// The scroll-margin keeps a revealed row (see the scrollIntoView in
@@ -243,14 +261,20 @@ export function drawMenu(items: MenuEntry[], onLeafSelect?: () => void): void {
 		els[next].focus();
 	});
 
-	drawEntries(items, onLeafSelect);
+	// Whether the current page is in this menu *at all*, shared by every branch
+	// below: a navigation to a page the menu doesn't hold must leave the folds
+	// alone (see `drawBranch`), and that is a fact about the whole menu, which
+	// no branch can tell on its own. Derived, so the branches re-run only when
+	// the answer flips — not on every navigation between two held pages.
+	const $menuHasCurrent = A.derive(() => anyCurrent(items));
+	drawEntries(items, onLeafSelect, $menuHasCurrent);
 }
 
-function drawEntries(items: MenuEntry[], onLeafSelect?: () => void): void {
+function drawEntries(items: MenuEntry[], onLeafSelect?: () => void, $menuHasCurrent?: { value: boolean }): void {
 	for (const entry of items) {
 		if (typeof entry === "string" || typeof entry === "function") { drawSlot(entry); continue; }
 		if ("separator" in entry) { A("hr.s-menu-sep"); continue; }
-		if (entry.items) drawBranch(entry, onLeafSelect);
+		if (entry.items) drawBranch(entry, onLeafSelect, $menuHasCurrent);
 		else drawLeaf(entry, onLeafSelect);
 	}
 }
@@ -274,7 +298,7 @@ function drawLeaf(entry: MenuItem, onLeafSelect?: () => void): void {
 			A(() => {
 				const first = !drawn;
 				drawn = true;
-				if (!matchCurrent(entry.href!)) return;
+				if (!isCurrent(entry)) return;
 				A("aria-current=page");
 				// A list taller than its scrollport (a long sidebar nav, mostly)
 				// highlights nothing when the current row is scrolled out of it,
@@ -299,6 +323,20 @@ function drawLeaf(entry: MenuItem, onLeafSelect?: () => void): void {
 	});
 }
 
+/**
+ * The last route-derived fold state of every linked branch, keyed by the
+ * branch's selection href. Module-level on purpose: the phone's full-page nav
+ * (and any dropdown) mounts a fresh menu every time it opens, and per-mount
+ * state would hand it three folded sections in the middle of the user's work.
+ * Bounded by the number of distinct branch hrefs an app ever shows.
+ */
+const foldMemory = new Map<string, boolean>();
+
+function setFold(href: string, open: boolean): boolean {
+	foldMemory.set(href, open);
+	return open;
+}
+
 /**
  * A branch: a native `<details>` folding a sub-list of entries in and out. The
  * children stay mounted whether folded or not — closing hides them, it doesn't
@@ -311,12 +349,27 @@ function drawLeaf(entry: MenuItem, onLeafSelect?: () => void): void {
  * linked branch is open exactly while it holds the current page. Only a branch
  * with no link anywhere below it keeps the native open/close toggle.
  */
-function drawBranch(entry: MenuItem, onLeafSelect?: () => void): void {
+function drawBranch(entry: MenuItem, onLeafSelect?: () => void, $menuHasCurrent?: { value: boolean }): void {
 	const href = entry.href ?? firstLeafHref(entry.items!);
 	// The route-derived fold state, as a derived boolean so the attribute scope
 	// below re-runs only when the answer flips — not on every navigation that
-	// merely moves *between* pages inside the branch.
-	const $open = href != null ? A.derive(() => containsCurrent(entry)) : null;
+	// merely moves *between* pages inside the branch. When the current page is
+	// nowhere in the menu, nothing has an opinion, and the fold simply keeps
+	// its last state — folding everything up would answer a question nobody
+	// asked with a menu that forgot where the user was.
+	//
+	// "Last state" lives in `foldMemory`, not in this closure: menus remount —
+	// the phone's full-page nav exists only while it is open — and a remount
+	// must find the state where the previous mount left it. It is keyed on the
+	// branch's selection href, so the sidebar and the phone nav (two renderings
+	// of the same items) share one truth, however often either is rebuilt.
+	const $open = href != null
+		? A.derive(() => {
+			if (containsCurrent(entry)) return setFold(href, true);
+			if ($menuHasCurrent == null || $menuHasCurrent.value) return setFold(href, false);
+			return foldMemory.get(href) ?? false;
+		})
+		: null;
 
 	A("details.s-menu-details", () => {
 		// For a no-link branch this scope has no subscriptions and never re-runs,
@@ -326,9 +379,10 @@ function drawBranch(entry: MenuItem, onLeafSelect?: () => void): void {
 		A("summary.s-menu-item.s-menu-branch", entry.attrs, () => {
 			if (entry.disabled) A("aria-disabled=true");
 			A(() => {
-				// Current only on its *own* page: when a descendant is current, that
+				// Current only on its *own* page (its `href`, or a `match` claim —
+				// pages with no row of their own): when a descendant is current, that
 				// row carries the highlight, and two highlights would read as two pages.
-				if (entry.href != null && matchCurrent(entry.href)) A("aria-current=page");
+				if (isCurrent(entry)) A("aria-current=page");
 			});
 			A("click=", (e: Event) => {
 				if (entry.disabled) { e.preventDefault(); return; }
@@ -346,7 +400,7 @@ function drawBranch(entry: MenuItem, onLeafSelect?: () => void): void {
 			A("span.s-menu-chevron aria-hidden=true", () => chevronRight());
 		});
 
-		A("div.s-menu-sub", () => drawEntries(entry.items!, onLeafSelect));
+		A("div.s-menu-sub", () => drawEntries(entry.items!, onLeafSelect, $menuHasCurrent));
 	});
 }
 
@@ -366,9 +420,35 @@ function foldedAway(el: HTMLElement): boolean {
 	return false;
 }
 
-/** Whether `entry`'s own page, or any page linked below it, is the current one. */
-function containsCurrent(entry: MenuItem): boolean {
+/**
+ * Whether any item anywhere in `items` — branches, their leaves, `match`
+ * claims — is the current page. The one question both the fold logic and the
+ * shell's tagline rule (see `taglineFits` in main.ts) ask of a menu, exported
+ * so the two can never disagree with the highlighting.
+ */
+export function anyCurrent(items: MenuEntry[]): boolean {
+	return items.some((entry) =>
+		typeof entry !== "string" && typeof entry !== "function" && !("separator" in entry) && containsCurrent(entry));
+}
+
+/**
+ * Whether this item is the current page: its own `href` matches, or its
+ * `match` claims the current path. The single test behind `aria-current`,
+ * branch unfolding, and {@link anyCurrent} — one truth, three consumers.
+ */
+function isCurrent(entry: MenuItem): boolean {
 	if (entry.href != null && matchCurrent(entry.href)) return true;
+	const m = entry.match;
+	if (m == null) return false;
+	const path = currentRoute.path;
+	if (typeof m === "function") return m(path);
+	const claim = m.replace(/\/+$/, "") || "/";
+	return path === claim || path.startsWith(claim === "/" ? "/" : claim + "/");
+}
+
+/** Whether `entry` is the current page itself, or holds it anywhere below. */
+function containsCurrent(entry: MenuItem): boolean {
+	if (isCurrent(entry)) return true;
 	for (const child of entry.items ?? []) {
 		if (typeof child === "string" || typeof child === "function" || "separator" in child) continue;
 		if (containsCurrent(child)) return true;

package/src/components/panels.ts

@@ -668,8 +668,10 @@ export interface PanelStackOptions {
 	notFound?: RouteHandler<{}>;
 	/** What to open beneath a path that arrives cold. See {@link MainOptions.ancestors}. */
 	ancestors?: Record<string, AncestorsHandler | undefined>;
-	/** Set `false` to show only the current panel, however much room there is. */
-	stacking?: boolean;
+	/** How many panels are shown at a time. See {@link MainOptions.columns}. */
+	columns?: "auto" | "single";
+	/** What a bare link does. See {@link MainOptions.linkNavigation}. */
+	linkNavigation?: "push" | "replace" | "open";
 	/** The shell's own title, used as the suffix of `document.title`. */
 	title?: unknown;
 	/**
@@ -1443,16 +1445,29 @@ export class PanelStackController implements PanelStack {
 	 * close guards run in `checkChange` when our navigation reaches the router.
 	 *
 	 * `data-panel` names which of the three {@link PanelStack} navigations the
-	 * click is: `push` (the default), `replace`, or `open`, which drops the
+	 * click is: `push`, `replace`, or `open`, which drops the
 	 * originating panel so the target arrives with its own stack beneath it,
-	 * exactly as a nav item's link does. An unrecognised value is a `push`.
+	 * exactly as a nav item's link does. A link that doesn't say gets the
+	 * shell's {@link PanelStackOptions.linkNavigation} (`push` by default);
+	 * an unrecognised value is a `push`.
 	 */
 	private interceptLinks(): void {
 		route.interceptLinks((url, anchor) => {
-			const mode = anchor.getAttribute("data-panel");
-			const panel = mode === "open" ? null : anchor.closest<HTMLElement>(".s-panel");
-			const origin = panel ? this.$state.live.find((entry) => entry.el === panel) : undefined;
-			void this.navigate(url.href, origin?.path ?? null, mode === "replace");
+			const mode = anchor.getAttribute("data-panel") ?? this.opts.linkNavigation;
+			let origin: string | null = null;
+			if (mode !== "open") {
+				const panel = anchor.closest<HTMLElement>(".s-panel");
+				if (panel) {
+					origin = this.$state.live.find((entry) => entry.el === panel)?.path ?? null;
+				} else if (anchor.closest(".s-panel-origin")) {
+					// The current panel's actions, promoted into the top bar on a
+					// narrow shell (see main.ts), sit outside every `.s-panel` — but
+					// they are still the current panel's own chrome, so a link among
+					// them builds on that panel, exactly as it does at full width.
+					origin = this.$state.live[this.$state.focus]?.path ?? null;
+				}
+			}
+			void this.navigate(url.href, origin, mode === "replace");
 			return true;
 		});
 	}
@@ -1494,6 +1509,25 @@ export class PanelStackController implements PanelStack {
 		});
 	}
 
+	// ── Live settings ──────────────────────────────────────────────────────
+	// `main()` keeps these fed from small reactive scopes of their own, so an
+	// app that reads them off a proxy (or through a getter) can change them at
+	// runtime and the shell adapts in place — nothing is redrawn, no panel
+	// loses its state. Not {@link PanelStack} API: the app talks to `main()`'s
+	// options; these are how `main()` talks to the stack.
+
+	/** Adopt a changed `columns` setting: one layout pass, nothing redrawn. */
+	setColumns(columns: "auto" | "single" | undefined): void {
+		if (this.opts.columns === columns) return;
+		this.opts.columns = columns;
+		this.scheduleLayout();
+	}
+
+	/** Adopt a changed `linkNavigation` default; the next click reads it. */
+	setLinkNavigation(mode: "push" | "replace" | "open" | undefined): void {
+		this.opts.linkNavigation = mode;
+	}
+
 	/**
 	 * The breadcrumb stack, drawn by `main()` into the top bar: every open
 	 * panel, oldest first, the ones on screen right now in bold, pinned ones
@@ -1883,7 +1917,7 @@ export class PanelStackController implements PanelStack {
 		const geom = this.geometry();
 		if (!geom) return;
 
-		const stacking = this.opts.stacking !== false;
+		const stacking = this.opts.columns !== "single";
 
 		// A window resize (or the very first pass) must be adopted instantly —
 		// geometry tracking the window through a 450ms transition reads as lag,