staffa 0.8.0 → 0.9.0

package/src/components/panels.ts

@@ -63,6 +63,23 @@ export type Routes = Record<string, RouteHandler>;
  */
 export type RouteTable<R> = { [K in keyof R & string]: (page: Page<Prettify<PathParams<K>>>) => void };
 
+/**
+ * What belongs beneath a path that arrives cold, worked out from the params of
+ * the path itself. Return the paths shallowest first, or nothing to leave this
+ * one to the parent-path derivation.
+ */
+export type AncestorsHandler<P = any> = (params: P, path: string) => readonly string[] | undefined | void;
+
+/**
+ * A table of {@link AncestorsHandler}s keyed by path template, the same way
+ * `routes` is — so each one's `params` are matched and typed from its own key
+ * rather than parsed out of the path a second time. The keys are checked
+ * against the route table, so a stale one is a type error.
+ */
+export type AncestorTable<R> = {
+	[K in keyof R & string]?: (params: Prettify<PathParams<K>>, path: string) => readonly string[] | undefined | void;
+};
+
 // ─── The Page object ─────────────────────────────────────────────────────────
 
 /**
@@ -111,8 +128,19 @@ export interface Page<P = Record<string, string | number | string[]>> {
 	 *
 	 * A panel's width depends only on the size of the window, never on what else
 	 * is open, so opening or closing a panel never resizes the ones already on
-	 * screen. This is read **once**, right after your handler runs, so set it
-	 * there; later changes are ignored.
+	 * screen.
+	 *
+	 * The panel is sized from this **before** your handler runs, so anything that
+	 * measures its own box has a real one from the first frame. What it is sized
+	 * at is whatever this says at that moment, which for a brand-new panel is the
+	 * default: a handler that *assigns* `layout` is drawn at the medium width and
+	 * reflowed immediately after — in time for the frame, but not for a
+	 * measurement taken in the same breath.
+	 *
+	 * Assigning it later works just as well. When your data arrives and you find
+	 * you want the wide one, the panel reflows to its new width without being
+	 * redrawn — so nothing in it is rebuilt or loses its state — and the columns
+	 * beside it move over.
 	 */
 	layout?: "small" | "medium" | "large";
 	/**
@@ -199,11 +227,12 @@ function splitPath(path: string): string[] {
 }
 
 /**
- * Turn a route key into segment tokens, throwing on malformed templates. A
+ * Turn a path template into segment tokens, throwing on malformed ones. A
  * segment is a param only when it is *entirely* a bracket group, so a literal
- * segment that merely contains brackets (`/v[1]beta`) stays literal.
+ * segment that merely contains brackets (`/v[1]beta`) stays literal. Used for
+ * both tables keyed by a path template: `routes` and `ancestors`.
  */
-function compileRoute(key: string, draw: RouteHandler): CompiledRoute {
+function compileKey(key: string): { key: string; segs: Seg[] } {
 	const parts = splitPath(key);
 	const segs = parts.map((part, i): Seg => {
 		if (!part.startsWith("[") || !part.endsWith("]")) return { kind: "lit", value: part };
@@ -221,7 +250,7 @@ function compileRoute(key: string, draw: RouteHandler): CompiledRoute {
 		}
 		return { kind: "param", name, matcher };
 	});
-	return { key, segs, draw };
+	return { key, segs };
 }
 
 /** Percent-decode a path segment, leaving it alone when it isn't valid encoding. */
@@ -229,7 +258,7 @@ function decodeSeg(value: string): string {
 	try { return decodeURIComponent(value); } catch { return value; }
 }
 
-function matchRoute(r: CompiledRoute, segments: string[]): Record<string, any> | null {
+function matchRoute(r: { segs: Seg[] }, segments: string[]): Record<string, any> | null {
 	const params: Record<string, any> = {};
 	for (let i = 0; i < r.segs.length; i++) {
 		const seg = r.segs[i];
@@ -279,6 +308,14 @@ const SHELL_PX = 1280;
 const GUTTER_PX = 24;
 /** Don't pair smalls when half the content area would be narrower than this. */
 const PAIR_MIN_PX = 360;
+/**
+ * Panels are layered by their depth in the stack, two `z-index` steps per panel:
+ * a panel sits on the odd layer for its depth, and a *closing* one drops to the
+ * even layer just below, where it is frozen for the length of its fade. So a
+ * panel that replaces another comes in over it, while one that closes fades out
+ * over whatever it was covering — which is the way round both should read.
+ */
+const LAYER_STEP = 2;
 
 // ─── Module-level styling ────────────────────────────────────────────────────
 
@@ -286,16 +323,19 @@ A.insertGlobalCss({
 	":root": `--s-panel-ms:${PANEL_MS}ms`,
 	// The clipping viewport that the columns slide through. Panels are absolutely
 	// positioned inside it, with their width and x offset set from JS (see
-	// `layout()`), so they can animate between arrangements.
-	".s-panels": "flex:1 min-width:0 min-height:0 position:relative overflow:hidden",
+	// `layout()`), so they can animate between arrangements. `isolation` keeps the
+	// layers they stack themselves in (see LAYER_STEP) to themselves: the region
+	// as a whole still sits under the shell's own chrome — the sticky top bar, and
+	// the nav page that slides across the body — however deep the stack gets.
+	".s-panels": "flex:1 min-width:0 min-height:0 position:relative overflow:hidden isolation:isolate",
 	".s-panel": {
 		// A panel rests at a plain `left` offset and carries no transform: a
 		// transformed element is composited, which costs it subpixel text
 		// antialiasing. `transform` is used only to play the enter/exit slides,
-		// where the compositing is what makes them cheap. There is deliberately
-		// no `width` transition: widths depend only on the window, change only in
-		// `.s-shell-snap` passes, and a column's content never reflows while the
-		// arrangement moves.
+		// where the compositing is what makes them cheap. There is deliberately no
+		// `width` transition: a width changes only when the window resizes or when
+		// the page itself asks for another layout, and animating one would reflow
+		// the column's content on every frame of it.
 		// Every duration is `--s-panel-ms`, so a column's move, its neighbour's fade
 		// and the chrome recentering around them all run as one motion. The drift
 		// eases out (it should read as a slow settle) while the fade runs *linear*
@@ -303,6 +343,10 @@ A.insertGlobalCss({
 		// zero, which looks like the panel vanishing rather than fading.
 		// No `overflow:hidden` here: the scroll container below clips the content
 		// itself, and the pair hairline sits in the gutter *outside* the panel.
+		// Layering is set from JS (`layout()` and `beginClose`) rather than left to
+		// DOM order: a closing panel is no longer part of the reactive list, so
+		// where its element sits among the live ones is Aberdeen's business, not a
+		// thing to depend on. `LAYER_*` says what the numbers mean.
 		"&":
 			"position:absolute top:0 bottom:0 left:0 display:flex flex-direction:column " +
 			"visibility:visible transition: left var(--s-panel-ms) ease, transform var(--s-panel-ms) ease-out, opacity var(--s-panel-ms) linear, visibility 0s;",
@@ -324,8 +368,8 @@ A.insertGlobalCss({
 		// dropped, which is what makes the panel settle instead of jumping.
 		"&.s-panel-enter": "opacity:0 transition:none transform: translateX(8cqw);",
 		// On its way out: fading where it stands, drifting the same short distance,
-		// and out of reach while it does. It is removed from the DOM when the fade
-		// itself ends (see `beginClose`), never part-way through it.
+		// and out of reach while it does. It leaves the DOM when the fade itself
+		// ends (see `playExit`), never part-way through it.
 		"&.s-panel-closing": "opacity:0 pointer-events:none transform: translateX(8cqw);",
 		// Crowded out from under the visible run. It keeps its DOM (and thus its
 		// scroll position and half-typed forms), so `display:none` is out —
@@ -390,22 +434,43 @@ interface PanelEntry {
 	placed?: boolean;
 	/** Whether its `loading` hold has already expired, so it can't hold again. */
 	holdDone?: boolean;
-	/** What the panel asked for, read once — right after its handler ran. */
+	/** What the panel asks for, kept in step with its `$page.layout`. */
 	layout: "small" | "medium" | "large";
 	/**
-	 * The width it was last laid out at. Visible panels get a fresh value every
-	 * pass (widths are a pure function of the content area and small-pairing);
-	 * hidden and closing panels keep this, so nothing invisible ever reflows.
+	 * The width it was last laid out at. Set before the panel's content is first
+	 * drawn, so that content has a real box to measure itself against. Visible
+	 * panels get a fresh value every pass (widths are a pure function of the
+	 * content area and small-pairing); hidden and closing panels keep this, so
+	 * nothing invisible ever reflows.
 	 */
 	width: number;
 }
 
+/**
+ * What the shell measures out to, and with it the width every panel size gets.
+ * A pure function of the window, so it is the same for every panel in a pass.
+ */
+interface Geometry {
+	/** The body row: everything the columns and the sidebar share. */
+	total: number;
+	/** What sits beside the columns — the sidebar and its hairline, if shown. */
+	chrome: number;
+	/** Half the standard content area, or all of it when a half would be too narrow. */
+	small: number;
+	/** The standard content area: the 1280px page minus the chrome. */
+	medium: number;
+	/** Everything the window has beside the chrome, with no upper limit. */
+	large: number;
+}
+
 // ─── Controller ──────────────────────────────────────────────────────────────
 
 /** Options the panel stack needs from its shell. */
 export interface PanelStackOptions {
 	routes: Routes;
 	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 top panel, however much room there is. */
 	stacking?: boolean;
 	/** The shell's own title, used as the suffix of `document.title`. */
@@ -417,6 +482,8 @@ let active: PanelController | null = null;
 
 export class PanelController {
 	private compiled: CompiledRoute[];
+	/** The `ancestors` table, compiled like the routes it is keyed by. */
+	private ancestors: { key: string; segs: Seg[]; fn: AncestorsHandler }[];
 	private opts: PanelStackOptions;
 	/** The live stack, shallow-to-deep. Closing panels are no longer part of it. */
 	private live: PanelEntry[] = [];
@@ -430,10 +497,18 @@ export class PanelController {
 	 */
 	$state = A.proxy({ paths: [] as string[], topId: 0 });
 	private containerEl?: HTMLElement;
+	/** The shell's measurements, shared by everything drawn since they were taken. */
+	private geom?: Geometry;
 	/** The body width at the last layout; a change means a window resize → snap. */
 	private lastBodyW = -1;
 	private layoutQueued = false;
 	private timers = new Set<ReturnType<typeof setTimeout>>();
+	/** The stack the navigation in flight is heading for; see {@link intended}. */
+	private intent: string[] | null = null;
+	/** The navigation the router hasn't settled yet, if any. */
+	private settling: Promise<boolean> | null = null;
+	/** The one navigation waiting behind it; see {@link issue}. */
+	private queued: { run: () => boolean | Promise<boolean>; settle: (ok: boolean) => void } | null = null;
 
 	constructor(opts: PanelStackOptions) {
 		if (active) {
@@ -441,7 +516,10 @@ export class PanelController {
 		}
 		active = this;
 		this.opts = opts;
-		this.compiled = Object.entries(opts.routes).map(([key, draw]) => compileRoute(key, draw));
+		this.compiled = Object.entries(opts.routes).map(([key, draw]) => ({ ...compileKey(key), draw }));
+		this.ancestors = Object.entries(opts.ancestors ?? {})
+			.filter((entry): entry is [string, AncestorsHandler] => entry[1] != null)
+			.map(([key, fn]) => ({ ...compileKey(key), fn }));
 
 		// The router consults this guard before any navigation is applied — ours,
 		// a link's, browser back/forward, even a direct route.go() by app code —
@@ -473,6 +551,10 @@ export class PanelController {
 		A.clean(() => {
 			for (const t of this.timers) clearTimeout(t);
 			this.timers.clear();
+			// Nothing is going to navigate a shell that isn't there: whatever was
+			// waiting its turn is answered rather than left hanging.
+			this.queued?.settle(false);
+			this.queued = null;
 			route.setGuard(appGuard);
 			if (active === this) active = null;
 		});
@@ -496,23 +578,54 @@ export class PanelController {
 	}
 
 	/**
-	 * The one derivation rule for origin-less navigation (§2.8): probe every
-	 * prefix of the path against the route table; the matching prefixes become
-	 * the stack. Prefixes without a route are simply skipped, so an app that
-	 * doesn't want one screen stacked under another just doesn't route that
-	 * prefix. The path itself is always the top panel, matched or not.
+	 * The stack for origin-less navigation: a cold deep link, a nav item, a
+	 * `route.go()` — anything arriving without a panel to build on and without a
+	 * snapshot to restore.
+	 *
+	 * The app's {@link PanelStackOptions.ancestors} gets first say, since only it
+	 * can know what belongs under a path that doesn't spell its own context out
+	 * (a `/thread/[id]` reached from a notification). Failing that — or when it
+	 * has no opinion — every prefix of the path is probed against the route table
+	 * and the matching ones become the stack. Either way, a path with no route is
+	 * skipped rather than opened as a "not found" column, so an app that doesn't
+	 * want one screen stacked under another simply doesn't route it. The path
+	 * itself is always the top panel, matched or not.
 	 */
 	deriveStack(path: string): string[] {
-		const segments = splitPath(path);
+		const top = normalizePath(path);
+		const asked = this.askAncestors(top);
+		const beneath = asked ? asked.map(normalizePath) : this.prefixesOf(top);
 		const stack: string[] = [];
-		for (let i = 1; i < segments.length; i++) {
-			const prefix = "/" + segments.slice(0, i).join("/");
-			if (this.matches(prefix)) stack.push(prefix);
+		for (const ancestor of beneath) {
+			if (ancestor !== top && !stack.includes(ancestor) && this.matches(ancestor)) stack.push(ancestor);
 		}
-		stack.push(normalizePath(path));
+		stack.push(top);
 		return stack;
 	}
 
+	/**
+	 * Ask the `ancestors` table what belongs beneath `path`. The first key that
+	 * matches answers — with its own matched params, so it never has to take the
+	 * path apart itself — and `undefined` from it means "no opinion", leaving the
+	 * path to the prefix derivation just as an unlisted one is.
+	 */
+	private askAncestors(path: string): readonly string[] | undefined {
+		const segments = splitPath(path);
+		for (const entry of this.ancestors) {
+			const params = matchRoute(entry, segments);
+			if (params) return entry.fn(params, path) ?? undefined;
+		}
+		return undefined;
+	}
+
+	/** Every prefix of `path` that has a route, shallowest first. */
+	private prefixesOf(path: string): string[] {
+		const segments = splitPath(path);
+		const found: string[] = [];
+		for (let i = 1; i < segments.length; i++) found.push("/" + segments.slice(0, i).join("/"));
+		return found;
+	}
+
 	/** The stack a route implies: its snapshot topped by its path, or — without a snapshot — derived. */
 	private targetFor(path: string, snapshot: unknown): string[] {
 		if (Array.isArray(snapshot)) return snapshot.map(String).concat(normalizePath(path));
@@ -569,6 +682,9 @@ export class PanelController {
 	 * rule 5 promises to keep.
 	 */
 	private commit(target: string[], nav: string): void {
+		// The panels this commit mounts size themselves as they draw, so make them
+		// measure the shell as it is now rather than trusting the last pass's numbers.
+		this.geom = undefined;
 		const existing = new Map(this.live.map((entry) => [entry.path, entry]));
 		const next: PanelEntry[] = [];
 		for (const path of target) {
@@ -615,43 +731,111 @@ export class PanelController {
 		entry.$page = A.proxy({
 			params,
 			path,
-			close: () => this.closePanelAt(this.live.indexOf(entry)),
+			close: () => this.closePath(entry.path),
 		}) as Page<any>;
 		return entry;
 	}
 
 	/**
-	 * Start a panel's exit: it lingers in the DOM, inert and fading, and is dropped
-	 * only when the fade itself ends. Removing it on a fixed timer instead would
-	 * race the transition — pull the element a frame early and the panel appears to
-	 * fade half-way and then vanish. The timeout is just a fallback for when no
-	 * `transitionend` is coming at all (transitions off, or an element that never
-	 * got placed).
+	 * Take a panel out of the shell. The *scope* goes now: its cleaners run this
+	 * tick, so whatever the panel registered with `A.clean` — subscriptions,
+	 * timers, an open portal — is torn down when the panel closes, not when its
+	 * animation is over. Only the element lingers, to play that animation, which
+	 * is what the `destroy=` hook in `drawPanel` is for: Aberdeen hands the
+	 * element to {@link playExit} instead of removing it.
 	 */
 	private beginClose(entry: PanelEntry): void {
 		entry.closing = true;
-		const el = entry.el;
+		// Frozen one layer below where it was, which is still above everything it
+		// was covering: it fades out over the panel it uncovers, and under the one
+		// that takes its place (see LAYER_STEP). Set here, while the element is
+		// still ours — a moment later the scope, and with it `entry.el`, is gone.
+		if (entry.el) entry.el.style.zIndex = String(LAYER_STEP * this.live.indexOf(entry));
+		this.byId.delete(entry.id);
+		delete this.$ids[String(entry.id)];
+	}
+
+	/**
+	 * A closed panel's send-off, run by Aberdeen once the panel's scope is gone (so
+	 * the content it shows is frozen, which is exactly what a departing column
+	 * should be): it fades where it stands, inert, and leaves the DOM when the fade
+	 * itself ends. Removing it on a fixed timer instead would race the transition —
+	 * pull the element a frame early and the panel appears to fade half-way and
+	 * then vanish. The timeout is just a fallback for when no `transitionend` is
+	 * coming at all (transitions off, or an element that never got placed).
+	 */
+	private playExit(entry: PanelEntry, el: HTMLElement): void {
+		// Only a close is worth animating. A panel being *redrawn* (a reactive
+		// dependency in its handler) replaces its element through here too, and that
+		// one simply goes, so the new one isn't drawn over a ghost of the old.
+		if (!entry.closing) { el.remove(); return; }
+		el.classList.add("s-panel-closing");
+		el.setAttribute("inert", "");
 		const drop = () => {
-			if (!this.byId.has(entry.id)) return;
-			this.byId.delete(entry.id);
-			delete this.$ids[String(entry.id)];
-		};
-		if (el) {
-			el.classList.add("s-panel-closing");
-			el.setAttribute("inert", "");
-			el.addEventListener("transitionend", (e: TransitionEvent) => {
-				if (e.target === el && e.propertyName === "opacity") drop();
-			});
-		}
-		const timer = setTimeout(() => {
+			clearTimeout(timer);
 			this.timers.delete(timer);
-			drop();
-		}, PANEL_MS + 80);
+			el.remove();
+		};
+		el.addEventListener("transitionend", (e: TransitionEvent) => {
+			if (e.target === el && e.propertyName === "opacity") drop();
+		});
+		const timer = setTimeout(drop, PANEL_MS + 80);
 		this.timers.add(timer);
 	}
 
 	// ── Navigation ─────────────────────────────────────────────────────────
 
+	/**
+	 * The stack navigation works from: the one we're on the way to while a change
+	 * is still settling, and the one on screen otherwise.
+	 *
+	 * Settling takes a moment more often than it looks: an async
+	 * {@link Page.requestClose}, and every `route.back()`, which travels through
+	 * the browser's history and lands on a `popstate`. Working from the committed
+	 * stack in that window would make a second Escape ask for the panel the first
+	 * one is already taking away — so two quick Escapes would peel one panel.
+	 */
+	private intended(): string[] {
+		return this.intent ?? this.paths();
+	}
+
+	/**
+	 * Put a navigation to the router, or — while one is still settling — behind
+	 * the one that is. Only the newest waits: each was worked out against
+	 * {@link intended}, so the newest is the one that means what the user last
+	 * asked for, and the one it displaces resolves `false`.
+	 *
+	 * A refusal empties the queue instead of running it. A veto is a "no, keep
+	 * this open", and the Escape queued behind it was aimed a panel deeper — with
+	 * the veto standing, running it would close the very panel that just said no.
+	 */
+	private issue(target: string[], run: () => boolean | Promise<boolean>): Promise<boolean> {
+		this.intent = target;
+		if (this.settling) {
+			this.queued?.settle(false);
+			return new Promise<boolean>((settle) => { this.queued = { run, settle }; });
+		}
+		return this.start(run);
+	}
+
+	private start(run: () => boolean | Promise<boolean>): Promise<boolean> {
+		const done = (ok: boolean): boolean => {
+			this.settling = null;
+			const next = this.queued;
+			this.queued = null;
+			// The router applies a change (and runs Aberdeen's queue, so our own
+			// commit has happened) before it settles us, which is what lets the next
+			// one go straight out: it asks the guards of the panels it removes from
+			// the stack as it stands now, not the one it was queued against.
+			if (ok && next) this.start(next.run).then(next.settle, () => next.settle(false));
+			else { this.intent = null; next?.settle(false); }
+			return ok;
+		};
+		const settling = Promise.resolve(run()).then(done, (e) => { console.error(e); return done(false); });
+		this.settling = settling;
+		return settling;
+	}
+
 	/**
 	 * Navigate back to a stack that is a truncation of the current one — the shared
 	 * implementation of Escape, a page closing itself, return-links and
@@ -662,23 +846,26 @@ export class PanelController {
 	 * promise reports its verdict.
 	 */
 	private goBackTo(target: string[]): Promise<boolean> {
-		return route.back({ path: target[target.length - 1] }, { state: { panels: target.slice(0, -1) } });
+		return this.issue(target, () =>
+			route.back({ path: target[target.length - 1] }, { state: { panels: target.slice(0, -1) } }));
 	}
 
 	/** Close every panel above `index` (guarded). Resolves `false` when vetoed. */
 	closeDownTo(index: number): Promise<boolean> {
-		if (index < 0 || index >= this.live.length - 1) return Promise.resolve(false);
-		return this.goBackTo(this.paths().slice(0, index + 1));
+		const paths = this.intended();
+		if (index < 0 || index >= paths.length - 1) return Promise.resolve(false);
+		return this.goBackTo(paths.slice(0, index + 1));
 	}
 
 	/** Guarded close of the top panel. */
 	closeTop(): Promise<boolean> {
-		return this.closeDownTo(this.live.length - 2);
+		return this.closeDownTo(this.intended().length - 2);
 	}
 
 	/**
-	 * Guarded close of the panel at `index`, top of the stack or not — what a
-	 * page's own close affordances ({@link Page.close}, a box's ✕) come down to.
+	 * Guarded close of whichever panel is open at `path`, top of the stack or not
+	 * — what a page's own close affordances ({@link Page.close}, a box's ✕) come
+	 * down to. `false` when that path isn't open.
 	 *
 	 * The top panel pops back to the snapshot beneath it. Any other panel is
 	 * *spliced* out: its guard runs, the columns above it keep their place and
@@ -688,11 +875,13 @@ export class PanelController {
 	 * why it goes through `route.go` here rather than through `navigate()`, whose
 	 * "link to the panel we're already on" check would see a no-op.
 	 */
-	closePanelAt(index: number): Promise<boolean> {
-		if (index < 0 || index >= this.live.length) return Promise.resolve(false);
-		if (index === this.live.length - 1) return this.closeTop();
-		const target = this.paths().filter((_, i) => i !== index);
-		return Promise.resolve(route.go({
+	closePath(path: string): Promise<boolean> {
+		const paths = this.intended();
+		const index = paths.indexOf(normalizePath(path));
+		if (index < 0) return Promise.resolve(false);
+		if (index === paths.length - 1) return this.closeDownTo(index - 1);
+		const target = paths.filter((_, i) => i !== index);
+		return this.issue(target, () => route.go({
 			path: target[target.length - 1],
 			// The top panel keeps its search params and hash: it isn't going
 			// anywhere, and `go()` would otherwise default them away.
@@ -702,41 +891,38 @@ export class PanelController {
 		}));
 	}
 
-	/** Guarded close of whichever panel `path` is open as. False when it isn't open. */
-	closeByPath(path: string): Promise<boolean> {
-		const wanted = normalizePath(path);
-		return this.closePanelAt(this.live.findIndex((entry) => entry.path === wanted));
-	}
-
 	/** Guarded close of the panel whose `.s-panel` element this is. */
 	closePanelEl(el: HTMLElement): Promise<boolean> {
-		return this.closePanelAt(this.live.findIndex((entry) => entry.el === el));
+		const entry = this.live.find((e) => e.el === el);
+		return entry ? this.closePath(entry.path) : Promise.resolve(false);
 	}
 
 	/**
-	 * Navigate to `href`. `originIndex` is the depth of the panel the link lives
-	 * in (−1 when it has none — a nav item or a programmatic call, which derives
-	 * the whole stack instead). `replace` swaps the originating panel rather than
-	 * stacking on top of it.
+	 * Navigate to `href`. `origin` is the path of the panel the link lives in, or
+	 * `null` when it has none — a nav item, or a programmatic call, which builds
+	 * the whole stack instead (see {@link deriveStack}). `replace` swaps the
+	 * originating panel rather than stacking on top of it, and `beneath` says what
+	 * the stack under the target is outright, for callers that know.
 	 */
-	navigate(href: string, originIndex: number, replace = false): void {
+	navigate(href: string, origin: string | null, replace = false, beneath?: readonly string[]): void {
 		let url: URL;
 		try { url = new URL(href, location.href); } catch { return; }
 		const path = normalizePath(url.pathname);
 		const search = Object.fromEntries(new URLSearchParams(url.search));
 		const hash = url.hash;
+		const paths = this.intended();
 
 		// A link to a panel that is already open is a return, not a navigation —
 		// so a stack can never hold the same path twice.
-		const open = this.live.findIndex((e) => e.path === path);
-		if (open >= 0 && open < this.live.length - 1) { void this.closeDownTo(open); return; }
-		if (open >= 0) {
+		const open = paths.indexOf(path);
+		if (open >= 0 && open < paths.length - 1 && !beneath) { void this.closeDownTo(open); return; }
+		if (open >= 0 && !beneath) {
 			// The target is the panel we're already on. Going nowhere — but the link
 			// may still carry a different search or hash, which belong to the top
 			// panel: record that as a history entry, leaving the stack alone (the
 			// panel reconciles by path, so it isn't even redrawn).
 			if (url.search === location.search && (url.hash || "") === (location.hash || "")) return;
-			route.go({ path, search, hash, state: { panels: this.paths().slice(0, -1) } });
+			void this.issue(paths, () => route.go({ path, search, hash, state: { panels: paths.slice(0, -1) } }));
 			return;
 		}
 
@@ -745,15 +931,24 @@ export class PanelController {
 		// The route guard (checkChange) asks every panel this removes — a set
 		// defined by the target stack, wherever those panels happen to sit —
 		// before the change is applied; a veto leaves everything untouched.
-		const beneath = originIndex < 0
-			? this.deriveStack(path).slice(0, -1)
-			: this.paths().slice(0, replace ? originIndex : originIndex + 1);
-		route.go({ path, search, hash, state: { panels: beneath } });
+		const originIndex = origin == null ? -1 : paths.indexOf(origin);
+		const under = beneath
+			? beneath.map(normalizePath).filter((p) => p !== path)
+			: originIndex < 0
+				? this.deriveStack(path).slice(0, -1)
+				: paths.slice(0, replace ? originIndex : originIndex + 1);
+		void this.issue([...under, path], () => route.go({ path, search, hash, state: { panels: under } }));
 	}
 
 	/** Programmatic push/replace, with the top panel as the implied origin. */
 	pushPath(path: string, replace: boolean): void {
-		this.navigate(path, this.live.length - 1, replace);
+		const paths = this.intended();
+		this.navigate(path, paths[paths.length - 1] ?? null, replace);
+	}
+
+	/** Programmatic open-as-a-whole-stack: `beneath` as given, or derived. */
+	openPath(path: string, beneath?: readonly string[]): void {
+		this.navigate(path, null, false, beneath);
 	}
 
 	// ── Link interception ──────────────────────────────────────────────────
@@ -769,8 +964,8 @@ export class PanelController {
 	private interceptLinks(): void {
 		route.interceptLinks((url, anchor) => {
 			const panel = anchor.closest<HTMLElement>(".s-panel");
-			const originIndex = panel ? this.live.findIndex((entry) => entry.el === panel) : -1;
-			this.navigate(url.href, originIndex, anchor.getAttribute("data-panel") === "replace");
+			const origin = panel ? this.live.find((entry) => entry.el === panel) : undefined;
+			this.navigate(url.href, origin?.path ?? null, anchor.getAttribute("data-panel") === "replace");
 			return true;
 		});
 	}
@@ -801,6 +996,11 @@ export class PanelController {
 	 */
 	drawStack(): void {
 		const container = A("div.s-panels role=main", () => {
+			// Published before the first panel draws, rather than from the return
+			// value below: a panel sizes itself from the shell's measurements (see
+			// `measure`), and the first ones do that while this very call is still
+			// running. `A()` without arguments is "the element we're in".
+			this.containerEl = A() as HTMLElement;
 			A.onEach(
 				this.$ids,
 				(_order, id) => this.drawPanel(Number(id)),
@@ -808,7 +1008,6 @@ export class PanelController {
 			);
 		}) as HTMLElement;
 
-		this.containerEl = container;
 		if (typeof ResizeObserver !== "undefined") {
 			const ro = new ResizeObserver(() => this.layout());
 			// The region *and* the body it sits in: the region alone misses a shell
@@ -825,8 +1024,30 @@ export class PanelController {
 	private drawPanel(id: number): void {
 		const entry = this.byId.get(id);
 		if (!entry) return;
+		let el: HTMLElement | undefined;
+
+		// How much room the panel wants, resolved *before* its content is drawn: an
+		// element that arrives without a width has no box for its content to measure
+		// itself against until the next frame's layout pass, which is a frame too
+		// late for anything that sizes itself from its container. So the panel is
+		// created at the width the window gives its layout — "medium" until the page
+		// says otherwise. Reactively, too: a page that changes its mind later (when
+		// its data arrives, say) reflows in place rather than being redrawn, and the
+		// columns beside it slide over to make room.
+		A(() => {
+			const asked = entry.$page.layout;
+			entry.layout = asked === "small" || asked === "large" ? asked : "medium";
+			const width = this.roomFor(entry.layout);
+			if (!width) return;
+			entry.width = width;
+			// The first run has no element to put it on yet — it's created with this
+			// width, just below. Later runs are the page changing its layout.
+			if (!el) return;
+			el.style.width = `${width}px`;
+			this.scheduleLayout();
+		});
 
-		const el = A("section.s-panel", () => {
+		el = A(`section.s-panel${entry.width ? ` w:${entry.width}px` : ""}`, "destroy=", (node: HTMLElement) => this.playExit(entry, node), () => {
 			const contentEl = A("div.s-content", () => {
 				entry.draw(entry.$page);
 				// After the content, so there is something to scroll when restoring.
@@ -843,18 +1064,12 @@ export class PanelController {
 			});
 		}) as HTMLElement;
 
-		// How much room the panel wants, settled right after its handler's
-		// synchronous run — deliberately once: a column that changed its mind
-		// later would reflow itself and shove its neighbours around.
-		const asked = A.peek(entry.$page, "layout");
-		entry.layout = asked === "small" || asked === "large" ? asked : "medium";
-
 		entry.el = el;
-		// Nothing animates from the arbitrary initial position; `layout()` gives
-		// the panel its real geometry (and turns transitions back on) in the
-		// upcoming frame, before anything is painted. A redraw (a reactive
-		// dependency inside the handler) lands here too, with a brand-new element
-		// that has to be placed again before it may animate.
+		// It has its width, but nothing animates from the arbitrary initial spot;
+		// `layout()` gives the panel its place in the run (and turns transitions
+		// back on) in the upcoming frame, before anything is painted. A redraw (a
+		// reactive dependency inside the handler) lands here too, with a brand-new
+		// element that has to be placed again before it may animate.
 		entry.placed = false;
 		el.style.transition = "none";
 		A.clean(() => { if (entry.el === el) entry.el = undefined; });
@@ -879,6 +1094,67 @@ export class PanelController {
 		});
 	}
 
+	/**
+	 * Measure the shell, and with it the width the window gives a panel of each
+	 * layout. Measured on the *shell*, not on the panel region: the region's width
+	 * is the layout engine's own output, so reading it back would nail the layout
+	 * to whatever it happened to be a frame ago. Fractional widths throughout — a
+	 * rounded column edge would drift a pixel away from the chrome above it.
+	 *
+	 * `undefined` while the shell has no width to speak of (it isn't in a document
+	 * yet, or it's `display:none`); the next pass tries again.
+	 */
+	private measure(): Geometry | undefined {
+		const container = this.containerEl;
+		const inner = container?.parentElement;
+		const body = inner?.parentElement;
+		if (!container || !inner || !body) return undefined;
+		const total = body.getBoundingClientRect().width;
+		if (!total) return undefined;
+
+		// Everything that sits beside the columns: the sidebar and its hairline,
+		// either of which may be display:none on a narrow shell.
+		let chrome = 0;
+		for (const child of inner.children) {
+			if (child !== container) chrome += child.getBoundingClientRect().width;
+		}
+
+		// The standard page is SHELL_PX wide, capped by the window; what it leaves
+		// beside the sidebar is the *standard* content area. Widths are a pure
+		// function of the window — never of what else is open — so a panel NEVER
+		// resizes because a neighbour came or went; only a window resize (the
+		// snap pass in `layout`) changes them:
+		// - "medium" fills the standard content area exactly;
+		// - "small" is half of it (minus the gutter) whenever that half is still
+		//   a usable column, and the whole of it on narrower screens;
+		// - "large" ignores the standard width and takes everything the window
+		//   has — which also means nothing ever fits beside it.
+		const medium = Math.max(0, Math.min(SHELL_PX, total) - chrome);
+		const half = (medium - GUTTER_PX) / 2;
+		return {
+			total,
+			chrome,
+			small: half >= PAIR_MIN_PX ? half : medium,
+			medium,
+			large: Math.max(0, total - chrome),
+		};
+	}
+
+	/**
+	 * The measurements this pass runs on. Taken once per layout pass and per
+	 * commit, and shared with the panels drawn in between — they all size
+	 * themselves against the same shell, and a `getBoundingClientRect()` each
+	 * would be a forced reflow each, in the middle of building their DOM.
+	 */
+	private geometry(): Geometry | undefined {
+		return (this.geom ??= this.measure());
+	}
+
+	/** How wide a panel of this layout is, right now; 0 while the shell can't be measured. */
+	private roomFor(layout: PanelEntry["layout"]): number {
+		return this.geometry()?.[layout] ?? 0;
+	}
+
 	/**
 	 * Size and position every panel, and publish the width of the whole ensemble
 	 * (sidebar + separator + columns) for the shell to centre itself on.
@@ -889,22 +1165,18 @@ export class PanelController {
 	 */
 	private layout(): void {
 		const container = this.containerEl;
-		const inner = container?.parentElement;
-		const body = inner?.parentElement;
 		const shell = container?.closest<HTMLElement>(".s-main");
-		if (!container || !inner || !body || !shell) return;
+		if (!container || !shell) return;
 		const n = this.live.length;
 		// A panel that hasn't drawn yet has no width to contribute, which would make
 		// this pass's arithmetic (and any enter animation it triggers) meaningless.
 		// Every mount schedules another pass, so simply wait for it.
 		if (!n || this.live.some((entry) => !entry.el)) return;
 
-		// Measured on the *shell*, not on the region: the region's width is this
-		// function's own output, so reading it back would nail the layout to
-		// whatever it happened to be a frame ago. Fractional widths throughout — a
-		// rounded column edge would drift a pixel away from the chrome above it.
-		const total = body.getBoundingClientRect().width;
-		if (!total) return;
+		// This pass measures afresh — it is the one thing that runs after a resize.
+		this.geom = undefined;
+		const geom = this.geometry();
+		if (!geom) return;
 
 		const stacking = this.opts.stacking !== false;
 
@@ -912,35 +1184,13 @@ export class PanelController {
 		// geometry tracking the window through a 450ms transition reads as lag,
 		// and a shell animating itself into place on load reads as a glitch.
 		// `.s-shell-snap` suppresses every standing transition for this one pass.
-		const snap = this.lastBodyW !== total;
+		const snap = this.lastBodyW !== geom.total;
 		if (snap) {
-			this.lastBodyW = total;
+			this.lastBodyW = geom.total;
 			shell.classList.add("s-shell-snap");
 		}
 
-		// Everything that sits beside the columns: the sidebar and its hairline,
-		// either of which may be display:none on a narrow shell.
-		let chrome = 0;
-		for (const child of inner.children) {
-			if (child !== container) chrome += child.getBoundingClientRect().width;
-		}
-
-		// The standard page is SHELL_PX wide, capped by the window; what it leaves
-		// beside the sidebar is the *standard* content area. Widths are a pure
-		// function of the window — never of what else is open — so a panel NEVER
-		// resizes because a neighbour came or went; only a window resize (the
-		// snap pass above) changes them:
-		// - "medium" fills the standard content area exactly;
-		// - "small" is half of it (minus the gutter) whenever that half is still
-		//   a usable column, and the whole of it on narrower screens;
-		// - "large" ignores the standard width and takes everything the window
-		//   has — which also means nothing ever fits beside it.
-		const stdRoom = Math.max(0, Math.min(SHELL_PX, total) - chrome);
-		const fullRoom = Math.max(0, total - chrome);
-		const halfW = (stdRoom - GUTTER_PX) / 2;
-		const smallW = halfW >= PAIR_MIN_PX ? halfW : stdRoom;
-		const width = (entry: PanelEntry) =>
-			entry.layout === "small" ? smallW : entry.layout === "large" ? fullRoom : stdRoom;
+		const width = (entry: PanelEntry) => geom[entry.layout];
 
 		// The visible run: as many top-of-stack panels as the window fits, at the
 		// sizes the window gives them. The top panel always shows.
@@ -949,7 +1199,7 @@ export class PanelController {
 		if (stacking) {
 			for (let i = n - 2; i >= 0; i--) {
 				const sum = runSum + GUTTER_PX + width(this.live[i]);
-				if (sum > fullRoom) break;
+				if (sum > geom.large) break;
 				runSum = sum;
 				first = i;
 			}
@@ -961,7 +1211,7 @@ export class PanelController {
 		// wider than the window. So the page is the familiar 1280px until extra
 		// columns genuinely fit, and stretches — centred — to hold the ones that
 		// do; with a "large" up that's the window's edges.
-		const area = Math.min(fullRoom, Math.max(stdRoom, runSum));
+		const area = Math.min(geom.large, Math.max(geom.medium, runSum));
 
 		for (let i = first; i < n; i++) this.live[i].width = width(this.live[i]);
 		// Panels that have never been visible get their would-be width too, so a
@@ -975,7 +1225,7 @@ export class PanelController {
 		// The consumers transition their max-width (see main.ts), so the
 		// recentring plays along with the panel that caused it instead of
 		// snapping.
-		shell.style.setProperty("--s-shell-w", `${chrome + area}px`);
+		shell.style.setProperty("--s-shell-w", `${geom.chrome + area}px`);
 
 		// Phase 1 — every panel's *start* state for this frame. Panels already on
 		// screen simply move (their standing transition animates it); freshly
@@ -988,8 +1238,10 @@ export class PanelController {
 			const el = entry.el!;
 			const shown = i >= first;
 			// Visible panels are left-aligned in the content area, a gutter apart;
-			// hidden ones park at its left edge, keeping their last width.
-			place(el, shown ? x : 0, entry.width);
+			// hidden ones park at its left edge, keeping their last width. Deeper
+			// panels layer over shallower ones, each on the odd layer for its depth
+			// (see LAYER_STEP).
+			place(el, shown ? x : 0, entry.width, LAYER_STEP * i + 1);
 			if (shown) x += entry.width + GUTTER_PX;
 			el.classList.toggle("s-panel-sep", shown && i > first);
 			// Hidden panels fade out over the left edge and, once faded, stop being
@@ -1036,10 +1288,11 @@ export class PanelController {
 	}
 }
 
-/** Put a panel at rest: `x` from the region's left edge, `width` pixels wide. */
-function place(el: HTMLElement, x: number, width: number): void {
+/** Put a panel at rest: `x` from the region's left edge, `width` pixels wide, on layer `z`. */
+function place(el: HTMLElement, x: number, width: number, z: number): void {
 	el.style.left = `${x}px`;
 	el.style.width = `${width}px`;
+	el.style.zIndex = String(z);
 }
 
 // ─── Guards ──────────────────────────────────────────────────────────────────
@@ -1126,6 +1379,25 @@ export const panels = {
 	replace(path: string): void {
 		requireActive().pushPath(path, true);
 	},
+	/**
+	 * Opens `path` as a whole arrangement rather than on top of what's there: the
+	 * same thing a nav item or a fresh tab does. Without `beneath`, the stack under
+	 * it is worked out the way a cold link's is (see `S.main()`'s `ancestors`);
+	 * with it, the paths you give are opened underneath, shallowest first.
+	 *
+	 * That's the one for a screen whose URL doesn't say where it belongs — the
+	 * thread a notification opens — and for seeding a stack from code in general.
+	 * Panels the new arrangement also holds stay as they are, and any it drops are
+	 * asked their {@link Page.requestClose} first.
+	 *
+	 * @example
+	 * ```ts
+	 * S.panels.open(`/thread/${id}`, [`/mailbox/${mailboxId}`]);
+	 * ```
+	 */
+	open(path: string, beneath?: readonly string[]): void {
+		requireActive().openPath(path, beneath);
+	},
 	/**
 	 * Closes the top panel, or, given a `path`, whichever panel is open at it,
 	 * asking {@link Page.requestClose} first. A panel that isn't on top is taken
@@ -1136,7 +1408,7 @@ export const panels = {
 	 */
 	close(path?: string): Promise<boolean> {
 		const ctl = requireActive();
-		return path == null ? ctl.closeTop() : ctl.closeByPath(path);
+		return path == null ? ctl.closeTop() : ctl.closePath(path);
 	},
 	/** The paths of the open panels, oldest first. Reactive: safe to read in a scope. */
 	get stack(): readonly string[] {