staffa 0.7.3 → 0.8.0

package/dist/components/layers.js

@@ -0,0 +1,888 @@
+import A from "aberdeen";
+import * as route from "aberdeen/route";
+import { NARROW_PX } from "../core.js";
+/** Leading slash, no trailing slash (except for the root itself) — as `route.current.path` is. */
+function normalizePath(path) {
+    let p = String(path).replace(/\/+$/, "");
+    if (!p.startsWith("/"))
+        p = `/${p}`;
+    return p;
+}
+function splitPath(path) {
+    const p = normalizePath(path);
+    return p === "/" ? [] : p.slice(1).split("/");
+}
+/** Turn a route key into segment tokens, throwing on malformed templates. */
+function compileRoute(key, draw) {
+    const parts = splitPath(key);
+    const segs = parts.map((part, i) => {
+        if (part.startsWith("*")) {
+            if (i !== parts.length - 1)
+                throw new Error(`Staffa: "*${part.slice(1)}" must be the last segment of route "${key}"`);
+            return { kind: "rest", name: part.slice(1) };
+        }
+        if (part.startsWith(":")) {
+            const m = /^:([A-Za-z_$][\w$]*)(?:\((num)\))?$/.exec(part);
+            if (!m)
+                throw new Error(`Staffa: malformed param "${part}" in route "${key}"`);
+            return { kind: "param", name: m[1], num: m[2] === "num" };
+        }
+        return { kind: "lit", value: part };
+    });
+    return { key, segs, draw };
+}
+/** Percent-decode a path segment, leaving it alone when it isn't valid encoding. */
+function decodeSeg(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function matchRoute(r, segments) {
+    const params = {};
+    for (let i = 0; i < r.segs.length; i++) {
+        const seg = r.segs[i];
+        if (seg.kind === "rest") {
+            // One-or-more remaining segments.
+            if (i >= segments.length)
+                return null;
+            params[seg.name] = segments.slice(i).map(decodeSeg);
+            return params;
+        }
+        if (i >= segments.length)
+            return null;
+        const value = segments[i];
+        if (seg.kind === "lit") {
+            if (value !== seg.value)
+                return null;
+        }
+        else if (seg.num) {
+            // A segment that isn't a finite number fails the match, so junk falls
+            // through to later routes (or notFound) instead of reaching a handler.
+            const n = Number(value);
+            if (value === "" || !Number.isFinite(n))
+                return null;
+            params[seg.name] = n;
+        }
+        else {
+            params[seg.name] = decodeSeg(value);
+        }
+    }
+    return r.segs.length === segments.length ? params : null;
+}
+// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * The one duration every bit of layer motion shares: the enter/exit fades, the
+ * `left` moves of columns shifting sideways, and the ensemble-width transition
+ * the chrome follows (see `--s-shell-w` in main.ts). Published as the
+ * `--s-layer-ms` custom property below, so CSS and JS can't drift apart.
+ */
+const LAYER_MS = 450;
+/** How long a freshly pushed `loading` layer holds its enter animation. */
+const LOADING_HOLD_MS = 300;
+/**
+ * The standard page width: sidebar plus content area, capped by the window.
+ * `"medium"` fills the content-area part of this exactly; only a `"large"`
+ * layer makes the shell grow past it.
+ */
+const SHELL_PX = 1280;
+/** The gap between two `"small"` layers sitting two-up. */
+const GUTTER_PX = 24;
+/** Don't pair smalls when half the content area would be narrower than this. */
+const PAIR_MIN_PX = 360;
+// ─── Module-level styling ────────────────────────────────────────────────────
+A.insertGlobalCss({
+    ":root": `--s-layer-ms:${LAYER_MS}ms`,
+    // The clipping viewport that the columns slide through. Layers are absolutely
+    // positioned inside it, with their width and x offset set from JS (see
+    // `layout()`), so they can animate between arrangements.
+    ".s-layers": "flex:1 min-width:0 min-height:0 position:relative overflow:hidden",
+    ".s-layer": {
+        // A layer 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.
+        // Every duration is `--s-layer-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*
+        // across the whole duration — an eased opacity spends its last stretch near
+        // zero, which looks like the layer 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 layer.
+        "&": "position:absolute top:0 bottom:0 left:0 display:flex flex-direction:column " +
+            "visibility:visible transition: left var(--s-layer-ms) ease, transform var(--s-layer-ms) ease-out, opacity var(--s-layer-ms) linear, visibility 0s;",
+        // The scroll container. Mirrors content mode's `main > .s-content`: same
+        // padding, and the same scrollbar inset (see `.s-scroll-y` in main.ts) so a
+        // single-column shell is pixel-identical to a non-routed one.
+        "> .s-content": "flex:1 min-height:0 overflow-y:auto overflow-x:hidden p:$3",
+        "> .s-content.s-scroll-y": "margin-right:$3",
+        // A vertical hairline centred in the gutter between two paired smalls,
+        // fading out at both ends — the same treatment as the sidebar's `.s-nav-sep`.
+        "&.s-layer-sep::before": `content:'' position:absolute left:-${GUTTER_PX / 2}px top:0.6rem bottom:0.6rem width:1px ` +
+            "background: linear-gradient(to bottom, transparent, $s-faint 18%, $s-faint 82%, transparent);",
+        // One vocabulary for every arrival and departure: a gradual fade over a short,
+        // slow drift — 8cqw (`cqw`: `.s-main` is the container). Layers appear and
+        // leave at the right edge; being crowded out at the left edge is its mirror.
+        //
+        // The start state of an enter, adopted with transitions off and then
+        // dropped, which is what makes the layer settle instead of jumping.
+        "&.s-layer-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.
+        "&.s-layer-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 —
+        // `visibility` takes it out of the rendering instead, but only once the fade
+        // has played: a transitioned `visibility` counts as *visible* for the whole
+        // duration and flips at the very end. Revealing it again uses the rule above
+        // (`visibility 0s`), so it comes back instantly.
+        "&.s-layer-hidden": "opacity:0 visibility:hidden transform: translateX(-8cqw); " +
+            "transition: left var(--s-layer-ms) ease, transform var(--s-layer-ms) ease-out, opacity var(--s-layer-ms) linear, visibility var(--s-layer-ms);",
+    },
+    // A window resize (and the very first pass) must track the window instantly,
+    // not rubber-band 450ms behind it: the layout engine raises this class on the
+    // shell for exactly those passes, applies the new geometry, and drops it
+    // after a forced reflow. Beats the standing transitions on specificity.
+    ".s-main.s-shell-snap .s-layer": "transition:none",
+    // On a narrow shell the single column is edge-to-edge, so there is no inset
+    // chrome for the scrollbar to line up with — cancel the `.s-scroll-y` margin
+    // (the twin of content mode's rule in main.ts).
+    [`@container (max-width: ${NARROW_PX}px)`]: {
+        ".s-layer > .s-content.s-scroll-y": "margin-right:0",
+    },
+    // A minimal "still fetching" hint, centred over the layer's content (which
+    // stays mounted underneath, so it can fill in reactively).
+    ".s-layer-loading": {
+        "&": "position:absolute inset:0 display:flex align-items:center justify-content:center gap:$1 pointer-events:none",
+        "i": "width:0.5rem height:0.5rem r:50% background:$s-muted opacity:0.45 animation: s-layer-pulse 1s ease-in-out infinite;",
+        "i:nth-child(2)": "animation-delay:0.15s",
+        "i:nth-child(3)": "animation-delay:0.3s",
+    },
+    "@keyframes s-layer-pulse": {
+        "0%, 100%": "opacity:0.25 transform:scale(0.8)",
+        "50%": "opacity:0.7 transform:scale(1)",
+    },
+});
+/** At most one routed shell per app — that's what `S.layers` is bound to. */
+let active = null;
+export class LayerController {
+    compiled;
+    opts;
+    /** The live stack, shallow-to-deep. Closing layers are no longer part of it. */
+    live = [];
+    byId = new Map();
+    nextId = 1;
+    /** Drives rendering: layer id → its `order` (used only as the sort key). */
+    $ids = A.proxy({});
+    /**
+     * The live stack's paths and its top layer, for reactive readers: the
+     * `document.title` watcher, `main()`'s Escape handling and `S.layers.stack`.
+     */
+    $state = A.proxy({ paths: [], topId: 0 });
+    containerEl;
+    /** The body width at the last layout; a change means a window resize → snap. */
+    lastBodyW = -1;
+    layoutQueued = false;
+    timers = new Set();
+    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));
+        // The router consults this guard before *any* route change is applied —
+        // ours, a link's, browser back/forward, even a direct route.go() by app
+        // code — so every layer the change would remove gets its requestClose
+        // asked, exactly once, and a veto leaves the URL and the stack untouched
+        // (the router holds the route steady while an async guard is pending,
+        // and knows the exact history depth to restore on a vetoed popstate).
+        route.setGuard((to) => this.checkChange(to));
+        // Commit the stack whenever the URL or its snapshot changes — the initial
+        // load, our own navigations, and browser back/forward. Anything that
+        // reaches this point has already passed the guard above.
+        A(() => {
+            const target = this.computeTarget();
+            A.peek(() => this.propose(target));
+        });
+        this.interceptLinks();
+        this.watchTitle();
+        A.clean(() => {
+            for (const t of this.timers)
+                clearTimeout(t);
+            this.timers.clear();
+            route.setGuard(null);
+            if (active === this)
+                active = null;
+        });
+    }
+    // ── Stack derivation ───────────────────────────────────────────────────
+    /** Resolve a path to its route handler + params, falling back to `notFound`. */
+    resolve(path) {
+        const segments = splitPath(path);
+        for (const r of this.compiled) {
+            const params = matchRoute(r, segments);
+            if (params)
+                return { draw: r.draw, params };
+        }
+        return { draw: this.opts.notFound ?? drawDefaultNotFound, params: {} };
+    }
+    matches(path) {
+        const segments = splitPath(path);
+        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 layer, matched or not.
+     */
+    deriveStack(path) {
+        const segments = splitPath(path);
+        const stack = [];
+        for (let i = 1; i < segments.length; i++) {
+            const prefix = "/" + segments.slice(0, i).join("/");
+            if (this.matches(prefix))
+                stack.push(prefix);
+        }
+        stack.push(normalizePath(path));
+        return stack;
+    }
+    /** The stack a route implies: its snapshot topped by its path, or — without a snapshot — derived. */
+    targetFor(path, snapshot) {
+        if (Array.isArray(snapshot))
+            return snapshot.map(String).concat(normalizePath(path));
+        return this.deriveStack(path);
+    }
+    /** The stack the current history entry asks for. Subscribes to path + snapshot. */
+    computeTarget() {
+        return this.targetFor(route.current.path, route.current.state.layers);
+    }
+    /**
+     * The route guard (see `route.setGuard` in the constructor): asked before any
+     * route change lands, wherever it came from. Runs the {@link Page.requestClose}
+     * guard of every layer the new route's stack would remove — a set defined by
+     * the target (the commit reconciles by path), so a derived stack that shares
+     * nothing with the live one still asks exactly the layers that are closing.
+     */
+    checkChange(to) {
+        const removed = this.removedBy(this.targetFor(to.path, to.state.layers));
+        return removed.length ? runGuards(removed) : true;
+    }
+    // ── Commit pipeline ────────────────────────────────────────────────────
+    paths() {
+        return this.live.map((e) => e.path);
+    }
+    /** The live layers a target stack drops — by path, so a splice removes only its own column. */
+    removedBy(target) {
+        return this.live.filter((entry) => !target.includes(entry.path));
+    }
+    /**
+     * Adopt a stack proposed by the URL. Close guards have already been run (and
+     * have passed) by the time a route change is visible here — `checkChange` is
+     * consulted by the router itself, before anything is applied.
+     */
+    propose(target) {
+        if (sameStack(this.paths(), target))
+            return;
+        this.commit(target, A.peek(route.current, "nav"));
+    }
+    /**
+     * Apply a target stack: unmount what's gone, mount what's new, animate the
+     * difference.
+     *
+     * Reconciliation is BY PATH (a stack can't hold the same path twice, so that's
+     * well-defined): a layer present in both stacks stays mounted *even if its
+     * index shifted*, which is what lets a layer be spliced out of the middle
+     * (§7) without disturbing the columns above it. A common-prefix diff would
+     * remount every one of them, throwing away exactly the scroll and form state
+     * rule 5 promises to keep.
+     */
+    commit(target, nav) {
+        const existing = new Map(this.live.map((entry) => [entry.path, entry]));
+        const next = [];
+        for (const path of target) {
+            const kept = existing.get(path);
+            if (kept) {
+                // Retained: it just takes its new place in the stack. Its `order` (the
+                // DOM sort key) deliberately stays put — see LayerEntry.order.
+                existing.delete(path);
+                next.push(kept);
+                continue;
+            }
+            const entry = this.createEntry(path, next.length);
+            // An initial load just appears, and so do layers *revealed* by a back —
+            // they belong underneath the ones sliding away. Everything else enters at
+            // the right edge, a replacement exactly like a push.
+            if (nav !== "load" && nav !== "back")
+                entry.enter = true;
+            next.push(entry);
+            this.byId.set(entry.id, entry);
+        }
+        // Whatever the target no longer holds leaves the same way: fading out over
+        // the right edge, which is also where its replacement (if any) comes in from.
+        for (const entry of existing.values())
+            this.beginClose(entry);
+        this.live = next;
+        A.merge(this.$state, { paths: this.paths(), topId: this.live.length ? this.live[this.live.length - 1].id : 0 });
+        for (const entry of this.live)
+            this.$ids[String(entry.id)] = entry.order;
+        this.scheduleLayout();
+    }
+    createEntry(path, order) {
+        const { draw, params } = this.resolve(path);
+        const entry = {
+            id: this.nextId++,
+            order,
+            path,
+            draw,
+            $ui: A.proxy({ holding: false }),
+            layout: "medium",
+            width: 0,
+        };
+        // `close` closes *this* layer, top of the stack or not. It resolves the
+        // layer's current depth at call time, so it keeps working after a splice has
+        // moved it — and quietly resolves false once the layer is gone.
+        entry.$page = A.proxy({
+            params,
+            path,
+            close: () => this.closeLayerAt(this.live.indexOf(entry)),
+        });
+        return entry;
+    }
+    /**
+     * Start a layer'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 layer 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).
+     */
+    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-layer-closing");
+            el.setAttribute("inert", "");
+            el.addEventListener("transitionend", (e) => {
+                if (e.target === el && e.propertyName === "opacity")
+                    drop();
+            });
+        }
+        const timer = setTimeout(() => {
+            this.timers.delete(timer);
+            drop();
+        }, LAYER_MS + 80);
+        this.timers.add(timer);
+    }
+    // ── Navigation ─────────────────────────────────────────────────────────
+    /**
+     * 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
+     * `S.layers.close()`. `route.back()` prefers the history entry where that
+     * layer was on top (with its scroll state intact); when there is no such entry
+     * it replaces the current one, carrying the snapshot passed as the fallback.
+     * Either way the route guard asks the closing layers first, and the returned
+     * promise reports its verdict.
+     */
+    goBackTo(target) {
+        return route.back({ path: target[target.length - 1] }, { state: { layers: target.slice(0, -1) } });
+    }
+    /** Close every layer above `index` (guarded). Resolves `false` when vetoed. */
+    closeDownTo(index) {
+        if (index < 0 || index >= this.live.length - 1)
+            return Promise.resolve(false);
+        return this.goBackTo(this.paths().slice(0, index + 1));
+    }
+    /** Guarded close of the top layer. */
+    closeTop() {
+        return this.closeDownTo(this.live.length - 2);
+    }
+    /**
+     * Guarded close of the layer at `index`, top of the stack or not — what a
+     * page's own close affordances ({@link Page.close}, a box's ✕) come down to.
+     *
+     * The top layer pops back to the snapshot beneath it. Any other layer is
+     * *spliced* out: its guard runs, the columns above it keep their place and
+     * state (the commit reconciles by path), and the URL doesn't change, since the
+     * top layer didn't. That still gets its own history entry, so the browser's
+     * back button restores the closed column like any other snapshot — which is
+     * why it goes through `route.go` here rather than through `navigate()`, whose
+     * "link to the layer we're already on" check would see a no-op.
+     */
+    closeLayerAt(index) {
+        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({
+            path: target[target.length - 1],
+            // The top layer keeps its search params and hash: it isn't going
+            // anywhere, and `go()` would otherwise default them away.
+            search: A.peek(() => ({ ...route.current.search })),
+            hash: A.peek(route.current, "hash"),
+            state: { layers: target.slice(0, -1) },
+        }));
+    }
+    /** Guarded close of whichever layer `path` is open as. False when it isn't open. */
+    closeByPath(path) {
+        const wanted = normalizePath(path);
+        return this.closeLayerAt(this.live.findIndex((entry) => entry.path === wanted));
+    }
+    /** Guarded close of the layer whose `.s-layer` element this is. */
+    closeLayerEl(el) {
+        return this.closeLayerAt(this.live.findIndex((entry) => entry.el === el));
+    }
+    /**
+     * Navigate to `href`. `originIndex` is the depth of the layer 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 layer rather than
+     * stacking on top of it.
+     */
+    navigate(href, originIndex, replace = false) {
+        let 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;
+        // A link to a layer 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) {
+            // The target is the layer we're already on. Going nowhere — but the link
+            // may still carry a different search or hash, which belong to the top
+            // layer: record that as a history entry, leaving the stack alone (the
+            // layer 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: { layers: this.paths().slice(0, -1) } });
+            return;
+        }
+        // Without an originating layer there is no stack to build on, so derive
+        // one — a nav click and a deep link to the same URL land identically.
+        // The route guard (checkChange) asks every layer this removes — a set
+        // defined by the target stack, wherever those layers 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: { layers: beneath } });
+    }
+    /** Programmatic push/replace, with the top layer as the implied origin. */
+    pushPath(path, replace) {
+        this.navigate(path, this.live.length - 1, replace);
+    }
+    // ── Link interception ──────────────────────────────────────────────────
+    /**
+     * Link handling through `route.interceptLinks()`, whose handler hook hands us
+     * the anchor so we can decide what the click *means*: the originating
+     * `.s-layer` (which decides what the click truncates), `data-layer=replace`,
+     * and return-to-an-open-layer semantics. The exclusion rules (targets,
+     * downloads, modified clicks, external URLs) live in Aberdeen; the close
+     * guards run in `checkChange` when our navigation reaches the router.
+     */
+    interceptLinks() {
+        route.interceptLinks((url, anchor) => {
+            const layer = anchor.closest(".s-layer");
+            const originIndex = layer ? this.live.findIndex((entry) => entry.el === layer) : -1;
+            this.navigate(url.href, originIndex, anchor.getAttribute("data-layer") === "replace");
+            return true;
+        });
+    }
+    // ── document.title ─────────────────────────────────────────────────────
+    /** `"<page title> · <app title>"`, kept in sync with the top layer. */
+    watchTitle() {
+        const original = document.title;
+        A(() => {
+            const entry = this.byId.get(this.$state.topId);
+            const pageTitle = entry?.$page.title;
+            const appTitle = typeof this.opts.title === "string" ? this.opts.title : undefined;
+            const title = pageTitle && appTitle ? `${pageTitle} · ${appTitle}` : pageTitle || appTitle;
+            if (title)
+                document.title = title;
+        });
+        A.clean(() => { document.title = original; });
+    }
+    // ── Rendering ──────────────────────────────────────────────────────────
+    /**
+     * Draw the layer viewport into the current element. Called by `main()`.
+     *
+     * There is deliberately no close chrome here — no back rail, no ←: pages
+     * provide their own way out (see {@link Page.close} and `S.box`'s `close`
+     * option). The shell contributes Escape and the browser's own back button.
+     */
+    drawStack() {
+        const container = A("div.s-layers role=main", () => {
+            A.onEach(this.$ids, (_order, id) => this.drawLayer(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
+            // resize that the columns happen to absorb, which still re-resolves widths.
+            ro.observe(container);
+            const body = container.parentElement?.parentElement;
+            if (body)
+                ro.observe(body);
+            A.clean(() => ro.disconnect());
+        }
+        A.clean(() => { if (this.containerEl === container)
+            this.containerEl = undefined; });
+        this.scheduleLayout();
+    }
+    drawLayer(id) {
+        const entry = this.byId.get(id);
+        if (!entry)
+            return;
+        const el = A("section.s-layer", () => {
+            const contentEl = A("div.s-content", () => {
+                entry.draw(entry.$page);
+                // After the content, so there is something to scroll when restoring.
+                route.persistScroll(entry.path);
+            });
+            watchVerticalOverflow(contentEl);
+            // The loading hint, in its own scope so flipping the flag doesn't
+            // redraw the layer's content. Held-back layers show nothing yet: they
+            // are still parked off screen, waiting to slide in with real content.
+            A(() => {
+                if (!entry.$page.loading || entry.$ui.holding)
+                    return;
+                A("div.s-layer-loading aria-hidden=true", () => { A("i"); A("i"); A("i"); });
+            });
+        });
+        // How much room the layer 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 layer 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.
+        entry.placed = false;
+        el.style.transition = "none";
+        A.clean(() => { if (entry.el === el)
+            entry.el = undefined; });
+        // A held-back layer that finishes loading gets to play its enter animation.
+        A(() => {
+            void entry.$page.loading;
+            this.scheduleLayout();
+        });
+        this.scheduleLayout();
+    }
+    // ── Layout engine ──────────────────────────────────────────────────────
+    scheduleLayout() {
+        if (this.layoutQueued)
+            return;
+        this.layoutQueued = true;
+        requestAnimationFrame(() => {
+            this.layoutQueued = false;
+            this.layout();
+        });
+    }
+    /**
+     * Size and position every layer, and publish the width of the whole ensemble
+     * (sidebar + separator + columns) for the shell to centre itself on.
+     *
+     * This is everything CSS can't work out for itself: which layers exist, which
+     * of them are visible, how wide each one is and where it sits. All the motion
+     * between two of these arrangements is CSS's job.
+     */
+    layout() {
+        const container = this.containerEl;
+        const inner = container?.parentElement;
+        const body = inner?.parentElement;
+        const shell = container?.closest(".s-main");
+        if (!container || !inner || !body || !shell)
+            return;
+        const n = this.live.length;
+        // A layer 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;
+        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;
+        if (snap) {
+            this.lastBodyW = 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 layer 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;
+        // The visible run: as many top-of-stack layers as the window fits, at the
+        // sizes the window gives them. The top layer always shows.
+        let first = n - 1;
+        let runSum = width(this.live[first]);
+        if (stacking) {
+            for (let i = n - 2; i >= 0; i--) {
+                const sum = runSum + GUTTER_PX + width(this.live[i]);
+                if (sum > fullRoom)
+                    break;
+                runSum = sum;
+                first = i;
+            }
+        }
+        // The content area holds the run, but is never smaller than the standard
+        // page (a lone small leaves its other half open — which is exactly where
+        // the next small lands, without anything on screen moving) and never
+        // 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));
+        for (let i = first; i < n; i++)
+            this.live[i].width = width(this.live[i]);
+        // Layers that have never been visible get their would-be width too, so a
+        // reveal doesn't start from nothing.
+        for (const entry of this.live) {
+            if (!entry.width)
+                entry.width = width(entry);
+        }
+        // The chrome above and below the body caps itself to the ensemble width,
+        // keeping everything centred and aligned however far the area stretches.
+        // The consumers transition their max-width (see main.ts), so the
+        // recentring plays along with the layer that caused it instead of
+        // snapping.
+        shell.style.setProperty("--s-shell-w", `${chrome + area}px`);
+        // Phase 1 — every layer's *start* state for this frame. Layers already on
+        // screen simply move (their standing transition animates it); freshly
+        // mounted ones still have transitions switched off, so what we set here is
+        // adopted instantly and becomes the "before" of their enter animation.
+        const fresh = [];
+        let x = 0;
+        for (let i = 0; i < n; i++) {
+            const entry = this.live[i];
+            const el = entry.el;
+            const shown = i >= first;
+            // Visible layers 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);
+            if (shown)
+                x += entry.width + GUTTER_PX;
+            el.classList.toggle("s-layer-sep", shown && i > first);
+            // Hidden layers fade out over the left edge and, once faded, stop being
+            // rendered at all — but they keep their DOM, and their scroll position.
+            el.classList.toggle("s-layer-hidden", !shown);
+            el.toggleAttribute("inert", !shown);
+            if (entry.placed)
+                continue;
+            fresh.push(entry);
+            // A layer that mounts while still fetching holds here for a moment, so
+            // it can enter with real content instead of an empty column.
+            if (!A.peek(entry.$page, "loading") || entry.holdDone)
+                entry.$ui.holding = false;
+            else if (!entry.$ui.holding) {
+                entry.$ui.holding = true;
+                this.holdEnter(entry);
+            }
+            // Already at its resting place; the enter animation is the offset (and
+            // the transparency) it starts from, one edge to the right.
+            if (entry.enter && shown)
+                el.classList.add("s-layer-enter");
+        }
+        // Phase 2 — force the browser to adopt those start states (and, on a snap
+        // pass, the transition-free geometry) as the ones to animate *from*.
+        // (Reading a layout property is what does it.)
+        if (fresh.length || snap)
+            void container.offsetWidth;
+        if (snap)
+            shell.classList.remove("s-shell-snap");
+        // Phase 3 — transitions back on, start state dropped, and off they go.
+        for (const entry of fresh) {
+            if (entry.$ui.holding)
+                continue;
+            entry.el.style.transition = "";
+            entry.el.classList.remove("s-layer-enter");
+            entry.enter = false;
+            entry.placed = true;
+        }
+    }
+    /** Let a `loading` layer's enter animation wait — but not indefinitely. */
+    holdEnter(entry) {
+        const timer = setTimeout(() => {
+            this.timers.delete(timer);
+            entry.holdDone = true;
+            if (entry.$ui.holding) {
+                entry.$ui.holding = false;
+                this.scheduleLayout();
+            }
+        }, LOADING_HOLD_MS);
+        this.timers.add(timer);
+    }
+}
+/** Put a layer at rest: `x` from the region's left edge, `width` pixels wide. */
+function place(el, x, width) {
+    el.style.left = `${x}px`;
+    el.style.width = `${width}px`;
+}
+// ─── Guards ──────────────────────────────────────────────────────────────────
+/**
+ * Ask every layer being removed, deepest first, whether it may go. Returns a
+ * plain boolean when no guard needs awaiting, so the common case stays
+ * synchronous (and screenshots stay deterministic).
+ */
+function runGuards(removed) {
+    const list = [...removed].reverse();
+    let i = 0;
+    const step = () => {
+        while (i < list.length) {
+            const guard = A.peek(list[i++].$page, "requestClose");
+            if (!guard)
+                continue;
+            let verdict;
+            try {
+                verdict = guard();
+            }
+            catch (e) {
+                console.error(e);
+                return false;
+            }
+            if (verdict === false)
+                return false;
+            if (verdict !== true)
+                return Promise.resolve(verdict).then((ok) => (ok === false ? false : step()));
+        }
+        return true;
+    };
+    return step();
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function sameStack(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+function drawDefaultNotFound($page) {
+    A("p fg:$s-muted", () => A("#", `No page at ${$page.path}`));
+}
+/**
+ * Toggle `.s-scroll-y` on `el` whenever a vertical scrollbar is eating into its
+ * width, so CSS can inset the bar from the layer's edge. Same trick (and the
+ * same reasoning) as content mode's `watchVerticalOverflow` in main.ts.
+ */
+function watchVerticalOverflow(el) {
+    if (typeof ResizeObserver === "undefined")
+        return;
+    const update = () => el.classList.toggle("s-scroll-y", el.offsetWidth > el.clientWidth);
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    if (el.firstElementChild)
+        ro.observe(el.firstElementChild);
+    update();
+    A.clean(() => ro.disconnect());
+}
+// ─── Public helpers ──────────────────────────────────────────────────────────
+/**
+ * Programmatic navigation for the routed `S.main()` shell — for acts that aren't
+ * link clicks, such as pushing the screen for a record you just created.
+ *
+ * The same rules as a link click apply: pushing a path that is already an open
+ * layer *returns* to it instead of duplicating it, and anything that would
+ * remove a layer asks its {@link Page.requestClose} guard first.
+ *
+ * @example
+ * ```ts
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   S.layers.push(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export const layers = {
+    /** Push `path` on top of the current top layer. */
+    push(path) {
+        requireActive().pushPath(path, false);
+    },
+    /** Replace the current top layer with `path`. */
+    replace(path) {
+        requireActive().pushPath(path, true);
+    },
+    /**
+     * Guarded close: of the top layer, or — given a `path` — of whichever layer is
+     * open at it, which is *spliced* out when it isn't on top (the columns above it
+     * stay exactly as they are). Resolves `false` when a guard vetoed, or when
+     * `path` isn't an open layer.
+     */
+    close(path) {
+        const ctl = requireActive();
+        return path == null ? ctl.closeTop() : ctl.closeByPath(path);
+    },
+    /** The current stack of paths, shallow-to-deep. Reactive: safe to read in a scope. */
+    get stack() {
+        return active ? active.$state.paths : [];
+    },
+};
+function requireActive() {
+    if (!active)
+        throw new Error("Staffa: S.layers needs a routed S.main() (one with `routes`) to be mounted");
+    return active;
+}
+/**
+ * Guarded close of the layer `el` sits in, resolved from the DOM — which is what
+ * lets a close affordance work without any page context, from any column,
+ * whether or not it is on top. Used by `S.box`'s `close: true`.
+ *
+ * Outside a routed shell (or outside any layer — a box in a dialog, say) there is
+ * nothing to close: it warns and resolves `false`.
+ */
+export function closeContainingLayer(el) {
+    const layerEl = el?.closest(".s-layer");
+    if (!active || !layerEl) {
+        console.warn("Staffa: `close: true` needs to be drawn inside a layer of a routed S.main()");
+        return Promise.resolve(false);
+    }
+    return active.closeLayerEl(layerEl);
+}