staffa 0.8.0 → 0.9.0

package/dist/components/panels.js

@@ -33,11 +33,12 @@ function splitPath(path) {
     return p === "/" ? [] : p.slice(1).split("/");
 }
 /**
- * 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, draw) {
+function compileKey(key) {
     const parts = splitPath(key);
     const segs = parts.map((part, i) => {
         if (!part.startsWith("[") || !part.endsWith("]"))
@@ -57,7 +58,7 @@ function compileRoute(key, draw) {
         }
         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. */
 function decodeSeg(value) {
@@ -122,21 +123,32 @@ 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 ────────────────────────────────────────────────────
 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*
@@ -144,6 +156,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;",
         // The scroll container. Mirrors content mode's `main > .s-content`: same
@@ -163,8 +179,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 —
@@ -203,6 +219,8 @@ A.insertGlobalCss({
 let active = null;
 export class PanelController {
     compiled;
+    /** The `ancestors` table, compiled like the routes it is keyed by. */
+    ancestors;
     opts;
     /** The live stack, shallow-to-deep. Closing panels are no longer part of it. */
     live = [];
@@ -216,17 +234,28 @@ export class PanelController {
      */
     $state = A.proxy({ paths: [], topId: 0 });
     containerEl;
+    /** The shell's measurements, shared by everything drawn since they were taken. */
+    geom;
     /** The body width at the last layout; a change means a window resize → snap. */
     lastBodyW = -1;
     layoutQueued = false;
     timers = new Set();
+    /** The stack the navigation in flight is heading for; see {@link intended}. */
+    intent = null;
+    /** The navigation the router hasn't settled yet, if any. */
+    settling = null;
+    /** The one navigation waiting behind it; see {@link issue}. */
+    queued = null;
     constructor(opts) {
         if (active) {
             throw new Error("Staffa: only one routed S.main() (one with `routes`) can be active at a time");
         }
         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[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 —
         // so every panel the change would remove gets its requestClose asked,
@@ -257,6 +286,10 @@ export class PanelController {
             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;
@@ -278,23 +311,54 @@ export class PanelController {
         return this.compiled.some((r) => matchRoute(r, segments) != null);
     }
     /**
-     * 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) {
-        const segments = splitPath(path);
+        const top = normalizePath(path);
+        const asked = this.askAncestors(top);
+        const beneath = asked ? asked.map(normalizePath) : this.prefixesOf(top);
         const stack = [];
-        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.
+     */
+    askAncestors(path) {
+        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. */
+    prefixesOf(path) {
+        const segments = splitPath(path);
+        const found = [];
+        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. */
     targetFor(path, snapshot) {
         if (Array.isArray(snapshot))
@@ -346,6 +410,9 @@ export class PanelController {
      * rule 5 promises to keep.
      */
     commit(target, nav) {
+        // 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 = [];
         for (const path of target) {
@@ -393,42 +460,113 @@ export class PanelController {
         entry.$page = A.proxy({
             params,
             path,
-            close: () => this.closePanelAt(this.live.indexOf(entry)),
+            close: () => this.closePath(entry.path),
         });
         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.
      */
     beginClose(entry) {
         entry.closing = true;
-        const el = entry.el;
-        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) => {
-                if (e.target === el && e.propertyName === "opacity")
-                    drop();
-            });
+        // 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).
+     */
+    playExit(entry, el) {
+        // 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;
         }
-        const timer = setTimeout(() => {
+        el.classList.add("s-panel-closing");
+        el.setAttribute("inert", "");
+        const drop = () => {
+            clearTimeout(timer);
             this.timers.delete(timer);
-            drop();
-        }, PANEL_MS + 80);
+            el.remove();
+        };
+        el.addEventListener("transitionend", (e) => {
+            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.
+     */
+    intended() {
+        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.
+     */
+    issue(target, run) {
+        this.intent = target;
+        if (this.settling) {
+            this.queued?.settle(false);
+            return new Promise((settle) => { this.queued = { run, settle }; });
+        }
+        return this.start(run);
+    }
+    start(run) {
+        const done = (ok) => {
+            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
@@ -439,21 +577,23 @@ export class PanelController {
      * promise reports its verdict.
      */
     goBackTo(target) {
-        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) {
-        if (index < 0 || index >= this.live.length - 1)
+        const paths = this.intended();
+        if (index < 0 || index >= paths.length - 1)
             return Promise.resolve(false);
-        return this.goBackTo(this.paths().slice(0, index + 1));
+        return this.goBackTo(paths.slice(0, index + 1));
     }
     /** Guarded close of the top panel. */
     closeTop() {
-        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
@@ -463,13 +603,15 @@ 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) {
-        if (index < 0 || index >= this.live.length)
+    closePath(path) {
+        const paths = this.intended();
+        const index = paths.indexOf(normalizePath(path));
+        if (index < 0)
             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({
+        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.
@@ -478,22 +620,19 @@ export class PanelController {
             state: { panels: target.slice(0, -1) },
         }));
     }
-    /** Guarded close of whichever panel `path` is open as. False when it isn't open. */
-    closeByPath(path) {
-        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) {
-        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, originIndex, replace = false) {
+    navigate(href, origin, replace = false, beneath) {
         let url;
         try {
             url = new URL(href, location.href);
@@ -504,21 +643,22 @@ export class PanelController {
         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) {
+        const open = paths.indexOf(path);
+        if (open >= 0 && open < paths.length - 1 && !beneath) {
             void this.closeDownTo(open);
             return;
         }
-        if (open >= 0) {
+        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;
         }
         // Without an originating panel there is no stack to build on, so derive
@@ -526,14 +666,22 @@ 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, replace) {
-        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, beneath) {
+        this.navigate(path, null, false, beneath);
     }
     // ── Link interception ──────────────────────────────────────────────────
     /**
@@ -547,8 +695,8 @@ export class PanelController {
     interceptLinks() {
         route.interceptLinks((url, anchor) => {
             const panel = anchor.closest(".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;
         });
     }
@@ -576,9 +724,13 @@ export class PanelController {
      */
     drawStack() {
         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();
             A.onEach(this.$ids, (_order, id) => this.drawPanel(Number(id)), (order, id) => [order, Number(id)]);
         });
-        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
@@ -597,7 +749,30 @@ export class PanelController {
         const entry = this.byId.get(id);
         if (!entry)
             return;
-        const el = A("section.s-panel", () => {
+        let el;
+        // 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();
+        });
+        el = A(`section.s-panel${entry.width ? ` w:${entry.width}px` : ""}`, "destroy=", (node) => 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.
@@ -613,17 +788,12 @@ export class PanelController {
                 A("div.s-panel-loading aria-hidden=true", () => { A("i"); A("i"); A("i"); });
             });
         });
-        // 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)
@@ -645,6 +815,65 @@ export class PanelController {
             this.layout();
         });
     }
+    /**
+     * 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.
+     */
+    measure() {
+        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.
+     */
+    geometry() {
+        return (this.geom ??= this.measure());
+    }
+    /** How wide a panel of this layout is, right now; 0 while the shell can't be measured. */
+    roomFor(layout) {
+        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.
@@ -655,10 +884,8 @@ export class PanelController {
      */
     layout() {
         const container = this.containerEl;
-        const inner = container?.parentElement;
-        const body = inner?.parentElement;
         const shell = container?.closest(".s-main");
-        if (!container || !inner || !body || !shell)
+        if (!container || !shell)
             return;
         const n = this.live.length;
         // A panel that hasn't drawn yet has no width to contribute, which would make
@@ -666,45 +893,22 @@ export class PanelController {
         // 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)
+        // 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;
         // A window resize (or the very first pass) must be adopted instantly —
         // 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) => entry.layout === "small" ? smallW : entry.layout === "large" ? fullRoom : stdRoom;
+        const width = (entry) => 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.
         let first = n - 1;
@@ -712,7 +916,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)
+                if (sum > geom.large)
                     break;
                 runSum = sum;
                 first = i;
@@ -724,7 +928,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
@@ -738,7 +942,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
         // mounted ones still have transitions switched off, so what we set here is
@@ -750,8 +954,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);
@@ -805,10 +1011,11 @@ export class PanelController {
         this.timers.add(timer);
     }
 }
-/** Put a panel at rest: `x` from the region's left edge, `width` pixels wide. */
-function place(el, x, width) {
+/** Put a panel at rest: `x` from the region's left edge, `width` pixels wide, on layer `z`. */
+function place(el, x, width, z) {
     el.style.left = `${x}px`;
     el.style.width = `${width}px`;
+    el.style.zIndex = String(z);
 }
 // ─── Guards ──────────────────────────────────────────────────────────────────
 /**
@@ -893,6 +1100,25 @@ export const panels = {
     replace(path) {
         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, beneath) {
+        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
@@ -903,7 +1129,7 @@ export const panels = {
      */
     close(path) {
         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() {