staffa 0.9.0 → 0.10.1

package/dist/components/pages.js

@@ -0,0 +1,1510 @@
+import A from "aberdeen";
+import * as route from "aberdeen/route";
+import { drawSlot } from "../core.js";
+import { circle as dotIcon, externalLink as newTabIcon, link as linkIcon, pin as pinIcon, pinOff as pinOffIcon, slash as sepIcon, x as closeIcon, } from "../icons.js";
+import { addContextMenu } from "./menu.js";
+import { scrollStrip, revealInStrip } from "./tabs.js";
+import { toast } from "./toast.js";
+/**
+ * The matchers a `[name=matcher]` segment can use. A matcher returns the param's
+ * value, or `undefined` to fail the match, in which case the path falls through
+ * to a later route (or to `notFound`) instead of reaching a handler.
+ *
+ * `integer` deliberately refuses anything that wouldn't survive a round trip
+ * back to the same URL: no leading zeroes ("007"), no "-0", no "1.5", "1e3" or
+ * "0x10", and nothing past `Number.MAX_SAFE_INTEGER` (where the number would no
+ * longer hold the id it came from). Two spellings of one id would otherwise be
+ * two different paths, so the same record could sit open in two columns at once.
+ * Use a plain `[id]` for ids that aren't safe integers, such as snowflakes.
+ */
+const MATCHERS = {
+    integer(segment) {
+        if (!/^(0|-?[1-9]\d*)$/.test(segment))
+            return undefined;
+        const n = Number(segment);
+        return Number.isSafeInteger(n) ? n : undefined;
+    },
+};
+/** 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 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. Used for
+ * both tables keyed by a path template: `routes` and `ancestors`.
+ */
+function compileKey(key) {
+    const parts = splitPath(key);
+    const segs = parts.map((part, i) => {
+        if (!part.startsWith("[") || !part.endsWith("]"))
+            return { kind: "lit", value: part };
+        const rest = /^\[\.\.\.([A-Za-z_$][\w$]*)\]$/.exec(part);
+        if (rest) {
+            if (i !== parts.length - 1)
+                throw new Error(`Staffa: "${part}" must be the last segment of route "${key}"`);
+            return { kind: "rest", name: rest[1] };
+        }
+        const param = /^\[([A-Za-z_$][\w$]*)(?:=([A-Za-z_$][\w$]*))?\]$/.exec(part);
+        if (!param)
+            throw new Error(`Staffa: malformed param "${part}" in route "${key}"`);
+        const [, name, matcher] = param;
+        if (matcher && !(matcher in MATCHERS)) {
+            throw new Error(`Staffa: unknown matcher "${matcher}" in route "${key}" (known: ${Object.keys(MATCHERS).join(", ")})`);
+        }
+        return { kind: "param", name, matcher };
+    });
+    return { key, segs };
+}
+/** 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, handed over exactly as they appear in
+            // the URL. Decoding first and joining would be lossy: an encoded slash
+            // inside a segment would come back indistinguishable from a separator.
+            if (i >= segments.length)
+                return null;
+            params[seg.name] = segments.slice(i).join("/");
+            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.matcher) {
+            // A segment the matcher rejects fails the match, so junk falls through
+            // to later routes (or notFound) instead of reaching a handler.
+            const matched = MATCHERS[seg.matcher](value);
+            if (matched === undefined)
+                return null;
+            params[seg.name] = matched;
+        }
+        else {
+            params[seg.name] = decodeSeg(value);
+        }
+    }
+    return r.segs.length === segments.length ? params : null;
+}
+// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * The one duration every bit of shell motion shares: the enter/exit fades, the
+ * `left` moves of columns shifting sideways, the ensemble-width transition the
+ * chrome follows (see `--s-shell-w` in main.ts), and the narrow-screen nav
+ * page's slide. Published as the `--s-page-ms` custom property below, so CSS
+ * and JS can't drift apart.
+ *
+ * Short enough to read as *the screen responded*, rather than as an animation
+ * being played at you: a page arriving is navigation, and navigation should
+ * feel instant even when it moves.
+ */
+const PAGE_MS = 250;
+/** How long a freshly pushed `loading` page holds its enter animation. */
+const LOADING_HOLD_MS = 300;
+/**
+ * The standard page width: sidebar plus content area, capped by the window.
+ * `"full"` fills the content-area part of this exactly; only a `"screen"`
+ * page makes the shell grow past it.
+ */
+const SHELL_PX = 1280;
+/** Don't pair smalls when half the content area would be narrower than this. */
+const PAIR_MIN_PX = 360;
+/**
+ * Pages are layered by their depth in the stack, two `z-index` steps per page:
+ * a page 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
+ * page 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-page-ms:${PAGE_MS}ms`,
+    // The clipping viewport that the columns slide through. Pages are absolutely
+    // positioned inside it, with their width and x offset set from JS (see
+    // `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.
+    // The region paints the page's sheen over its own box, and every page shows
+    // a slice of that same gradient (see `.s-page` below), so the columns and
+    // the ground beside them are one continuous surface.
+    ".s-pages": "flex:1 min-width:0 min-height:0 position:relative overflow:hidden isolation:isolate " +
+        "background: linear-gradient(170deg, color-mix(in oklab, $s-bg, white 9%), color-mix(in oklab, $s-bg, black 9%));",
+    ".s-page": {
+        // A page 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: 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-page-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 page vanishing rather than fading.
+        // No `overflow:hidden` here: the scroll container below clips the content
+        // itself.
+        // Layering is set from JS (`layout()` and `beginClose`) rather than left to
+        // DOM order: a closing page 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.
+        //
+        // Every page paints an opaque ground, because pages animate over one
+        // another — entering, leaving, being crowded out — and two transparent ones
+        // mean text sliding over text. It takes the page's own sheen, the one
+        // `.s-s, body` paints in theme.ts, resolved here against the inherited
+        // `--s-bg` (a page is not a surface, so it has to paint it itself).
+        //
+        // Painted per page, over the page's own box, which is as good as it
+        // needs to be: the sheen is a 9%-either-way wash over a whole column, so
+        // two columns' worth of it meeting at a hairline is not something the eye
+        // picks out. The region (`.s-pages` above) paints the same wash, so the
+        // ground beside a lone column matches it just as closely.
+        "&": "position:absolute top:0 bottom:0 left:0 display:flex flex-direction:column " +
+            "background: linear-gradient(170deg, color-mix(in oklab, $s-bg, white 9%), color-mix(in oklab, $s-bg, black 9%)); " +
+            "visibility:visible transition: left var(--s-page-ms) ease, transform var(--s-page-ms) ease-out, opacity var(--s-page-ms) linear, visibility 0s;",
+        // The hairline between two columns, fading out at both ends — the same
+        // treatment as the sidebar's `.s-nav-sep`. Columns tile the area with no
+        // gutter between them: each already brings its own `$3` of padding, which
+        // keeps two columns' *contents* comfortably apart, while a gutter on top
+        // of that only opened a strip of the page's own ground between two columns
+        // painting theirs. So this sits exactly on the boundary — and an
+        // edge-to-edge column (`A("p:0")`) really does reach the line bounding it.
+        "&.s-page-sep::before": "content:'' position:absolute left:0 top:0.6rem bottom:0.6rem width:1px z-index:1 " +
+            "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). Pages 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 page settle instead of jumping.
+        "&.s-page-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 leaves the DOM when the fade itself
+        // ends (see `playExit`), never part-way through it.
+        "&.s-page-closing": "opacity:0 pointer-events:none transform: translateX(8cqw);",
+        // Off screen but open: crowded out from under the visible run at the left
+        // edge (`hidden`), or right of the current page, parked past the right
+        // edge (`parked`) — the two are mirror images. Either 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-page-hidden, &.s-page-parked": "opacity:0 visibility:hidden " +
+            "transition: left var(--s-page-ms) ease, transform var(--s-page-ms) ease-out, opacity var(--s-page-ms) linear, visibility var(--s-page-ms);",
+        "&.s-page-hidden": "transform: translateX(-8cqw);",
+        "&.s-page-parked": "transform: translateX(8cqw);",
+    },
+    // The scroll container, with the column's own padding. A scrollbar here is
+    // left flush against the column's right edge — unlike content mode's, which
+    // insets one from the shell edge to line up with the bar above it. A column
+    // has something better to line up with: the hairline the next column starts
+    // at, or the edge of the content area. Both want the bar hard against them,
+    // and an inset would leave a strip of nothing between the two.
+    ".s-page > .s-content": "flex:1 min-height:0 overflow-y:auto overflow-x:hidden p:$3",
+    // A page's actions on a wide shell: a quiet strip at the column's top-right,
+    // above the scroll area (never sticky inside it). On a narrow shell the top
+    // bar carries them instead, and no strip is drawn at all.
+    ".s-page-actions": "display:flex align-items:center justify-content:flex-end gap:$1 flex-shrink:0 padding: $3 $3 0;",
+    // The breadcrumb trail the top bar shows: every open page, oldest first,
+    // the ones on screen right now in bold ink (see `drawCrumbs`). One row that
+    // scrolls sideways when the bar is tight — scrollbarless, with a fade at
+    // whichever edge has more trail behind it, so the cut-off reads as "keep
+    // going" rather than as the trail simply ending.
+    // The trail is a `.s-strip` (see tabs.ts), so the scrolling, the hidden
+    // scrollbar and the ‹ / › come with it; all that is left to say is the gap
+    // between a crumb and its chevron.
+    ".s-crumbs > .s-strip-row": "gap:$m1",
+    ".s-crumb": {
+        // Quiet ink for the trail, full ink and weight for the pages on screen:
+        // the weight change alone is ambiguous in a short crumb, the colour alone
+        // too subtle. No padding of its own — the first crumb has to start on the
+        // same pixel as the app's name above it, and the gap below spaces the row.
+        // `flex-shrink:0` because the crumbs are the strip's flex items and carry
+        // `overflow:hidden`, which resolves their automatic minimum size to zero:
+        // left to shrink they would ellipsise themselves down to stubs rather than
+        // overflow, and the trail would never scroll. One long title still caps at
+        // 14rem — that is this crumb's own business, not the row running out.
+        "&": "flex-shrink:0 font-size:0.85em line-height:1.5 fg:$s-muted text-decoration:none " +
+            "white-space:nowrap max-width:14rem overflow:hidden text-overflow:ellipsis " +
+            "transition: color 0.12s;",
+        "&.s-crumb-on": "font-weight:600 fg:$s-text",
+        // The same hover treatment as a menu item. The page you are on is a plain
+        // span rather than a link, so it needs no `:not()` guard here.
+        "a&:hover": "filter:none color: color-mix(in lab, $s-primary 33%, $s-text);",
+        // The pin of a pinned page, sitting inline just before its title. Filled:
+        // at crumb size the icon's hairline strokes alias into a wobble, while the
+        // body path filled solid reads as the classic pinned-tab pushpin.
+        "svg.s-crumb-pin": "vertical-align:-0.12em margin-right:0.3em opacity:0.8 fill:currentColor",
+        // The ● of a page holding unsaved work — the editors' dirty mark, filled
+        // solid for the same reason as the pin.
+        "svg.s-crumb-unsaved": "vertical-align:0.08em margin-right:0.3em fill:currentColor",
+    },
+    // A slash, not a chevron: the trail is a path, and a path's separator is what
+    // the URL itself uses. It also has to stay clearly *unlike* the ‹ / › the
+    // strip grows when the trail overflows (see `scrollStrip` in tabs.ts) — two
+    // near-identical chevrons, one meaningful and one a button, read as a bug.
+    "svg.s-crumb-sep": "flex-shrink:0 opacity:0.4",
+    // 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-page": "transition:none",
+    // A minimal "still fetching" hint, centred over the page's content (which
+    // stays mounted underneath, so it can fill in reactively).
+    ".s-page-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-page-pulse 1s ease-in-out infinite;",
+        "i:nth-child(2)": "animation-delay:0.15s",
+        "i:nth-child(3)": "animation-delay:0.3s",
+    },
+    "@keyframes s-page-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.pages` is bound to. */
+let active = null;
+export class PageController {
+    compiled;
+    /** The `ancestors` table, compiled like the routes it is keyed by. */
+    ancestors;
+    opts;
+    /** The live trail, oldest first. Closing pages are no longer part of it. */
+    live = [];
+    /** Index into `live` of the current page — the one the URL names. */
+    focus = 0;
+    byId = new Map();
+    nextId = 1;
+    /** Drives rendering: page id → its `order` (used only as the sort key). */
+    $ids = A.proxy({});
+    /**
+     * The live trail's paths and its current page, for reactive readers: the
+     * `document.title` watcher, `main()`'s Escape handling, the breadcrumbs,
+     * and `S.pages.stack`.
+     */
+    $state = A.proxy({ paths: [], focus: 0, currentId: 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 arrangement 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]) => ({ ...compileKey(key), draw }));
+        this.ancestors = Object.entries(opts.ancestors ?? {})
+            .filter((entry) => entry[1] != null)
+            .map(([key, fn]) => ({ ...compileKey(key), fn }));
+        // Commit the trail whenever the URL or its snapshot changes — the initial
+        // load, our own navigations, and browser back/forward. There is no route
+        // guard of the shell's own to pass first: closes are refused up front
+        // (`closePath` on an unsaved page) or repaired at the commit (`propose`
+        // keeps unsaved pages a navigation would drop), so a guard the app
+        // itself registered with `route.setGuard` — an auth redirect, say — is
+        // left exactly where it is and keeps working untouched.
+        A(() => {
+            const target = this.computeTarget();
+            A.peek(() => this.propose(target));
+        });
+        this.interceptLinks();
+        this.watchTitle();
+        this.guardTabClose();
+        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;
+            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 stack for origin-less navigation: a cold deep link, a nav item, a
+     * `route.go()` — anything arriving without a page to build on and without a
+     * snapshot to restore.
+     *
+     * The app's {@link PageStackOptions.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 always ends the derived stack, matched or not.
+     */
+    deriveTrail(path) {
+        const top = normalizePath(path);
+        const asked = this.askAncestors(top);
+        const beneath = asked ? asked.map(normalizePath) : this.prefixesOf(top);
+        const stack = [];
+        for (const ancestor of beneath) {
+            if (ancestor !== top && !stack.includes(ancestor) && this.matches(ancestor))
+                stack.push(ancestor);
+        }
+        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 pinned pages among `trail`, in order, minus `omit` — the ones a
+     * navigation must carry along rather than close. Pin flags live on the
+     * pages themselves, so a path without a live page can't be pinned.
+     */
+    pinnedIn(trail, omit) {
+        return trail.filter((path) => {
+            if (omit.includes(path))
+                return false;
+            const entry = this.live.find((e) => e.path === path);
+            return entry != null && A.peek(entry.$page, "pinned") === true;
+        });
+    }
+    /** Whether the page open at `path` (if any) holds unsaved work. Peeked. */
+    unsavedAt(path) {
+        const entry = this.live.find((e) => e.path === path);
+        return entry != null && A.peek(entry.$page, "unsaved") === true;
+    }
+    /**
+     * The arrangement a route implies: its snapshot around its path, or —
+     * without a snapshot — derived, with the new page current at the end and
+     * any pinned pages carried along beneath it.
+     */
+    targetFor(path, state) {
+        const before = Array.isArray(state?.pages) ? state.pages.map(String) : null;
+        if (before) {
+            const after = Array.isArray(state.parked) ? state.parked.map(String) : [];
+            return { trail: [...before, normalizePath(path), ...after], focus: before.length };
+        }
+        const base = this.deriveTrail(path).slice(0, -1);
+        const trail = [...base, ...this.pinnedIn(this.paths(), [...base, normalizePath(path)]), normalizePath(path)];
+        return { trail, focus: trail.length - 1 };
+    }
+    /** The arrangement the current history entry asks for. Subscribes to path + snapshot. */
+    computeTarget() {
+        return this.targetFor(route.current.path, route.current.state);
+    }
+    // ── Commit pipeline ────────────────────────────────────────────────────
+    paths() {
+        return this.live.map((e) => e.path);
+    }
+    /**
+     * Adopt an arrangement proposed by the URL — after repairing it: pages
+     * holding unsaved work are never torn down by a navigation, wherever it
+     * came from — a link, a nav item, even a browser back to an entry from
+     * before the page existed. Whatever the target drops, they stay, parked
+     * after the current page and wearing the ● that says why. (They are
+     * deliberately not written into history entries: the work they protect
+     * lives in the page's DOM, which a reload clears anyway.)
+     */
+    propose(target) {
+        const kept = this.live
+            .filter((e) => !target.trail.includes(e.path) && A.peek(e.$page, "unsaved"))
+            .map((e) => e.path);
+        if (kept.length)
+            target = { trail: [...target.trail, ...kept], focus: target.focus };
+        if (sameStack(this.paths(), target.trail) && target.focus === this.focus)
+            return;
+        this.commit(target, A.peek(route.current, "nav"));
+    }
+    /**
+     * Apply a target arrangement: unmount what's gone, mount what's new, animate
+     * the difference.
+     *
+     * Reconciliation is BY PATH (a trail can't hold the same path twice, so that's
+     * well-defined): a page present in both stacks stays mounted *even if its
+     * index shifted*, which is what lets a page 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) {
+        // The pages 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;
+        // Pin flags for pages this commit *creates* — a reload, or a cold
+        // restore. Live pages keep their own flag: a pin is the user's mark on
+        // the page, not part of where back/forward travel. Peeked, as `nav` is.
+        const pinned = A.peek(route.current.state, "pinned");
+        const seedPins = new Set(Array.isArray(pinned) ? pinned.map(String) : []);
+        const existing = new Map(this.live.map((entry) => [entry.path, entry]));
+        const next = [];
+        for (const path of target.trail) {
+            const kept = existing.get(path);
+            if (kept) {
+                // Retained: it just takes its new place in the trail. Its `order` (the
+                // DOM sort key) deliberately stays put — see PageEntry.order.
+                existing.delete(path);
+                next.push(kept);
+                continue;
+            }
+            const entry = this.createEntry(path, next.length, next.length <= target.focus, seedPins.has(path));
+            // An initial load just appears, and so do pages *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;
+        this.focus = Math.min(target.focus, this.live.length - 1);
+        A.merge(this.$state, {
+            paths: this.paths(),
+            focus: this.focus,
+            currentId: this.live.length ? this.live[this.focus].id : 0,
+        });
+        for (const entry of this.live)
+            this.$ids[String(entry.id)] = entry.order;
+        this.scheduleLayout();
+    }
+    createEntry(path, order, visible, pinned) {
+        const { draw, params } = this.resolve(path);
+        const entry = {
+            id: this.nextId++,
+            order,
+            path,
+            draw,
+            $ui: A.proxy({ holding: false }),
+            maxWidth: "full",
+            width: 0,
+        };
+        // `close` closes *this* page, current or not. It resolves the page's
+        // place in the trail at call time, so it keeps working after a splice has
+        // moved it — and quietly resolves false once the page is gone.
+        //
+        // `visible` starts at what the page's place implies: shown when it sits
+        // at or before the current page (a pushed page always does), hidden when
+        // it is restored already parked. `width` is filled in by the sizing scope
+        // in `drawPage` before the handler draws.
+        entry.$page = A.proxy({
+            params,
+            path,
+            width: 0,
+            visible,
+            pinned: pinned || undefined,
+            close: () => this.closePath(entry.path),
+        });
+        return entry;
+    }
+    /**
+     * Take a page out of the shell. The *scope* goes now: its cleaners run this
+     * tick, so whatever the page registered with `A.clean` — subscriptions,
+     * timers, an open portal — is torn down when the page closes, not when its
+     * animation is over. Only the element lingers, to play that animation, which
+     * is what the `destroy=` hook in `drawPage` is for: Aberdeen hands the
+     * element to {@link playExit} instead of removing it.
+     */
+    beginClose(entry) {
+        entry.closing = true;
+        // It is on its way out, so it is no longer "on screen" as far as anything
+        // hanging off `$page.visible` is concerned — even though its element lingers
+        // to play the fade.
+        entry.$page.visible = false;
+        // Frozen one layer below where it was, which is still above everything it
+        // was covering: it fades out over the page 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 page's send-off, run by Aberdeen once the page'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 page 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 page 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-page-closing");
+        el.setAttribute("inert", "");
+        const drop = () => {
+            clearTimeout(timer);
+            this.timers.delete(timer);
+            el.remove();
+        };
+        el.addEventListener("transitionend", (e) => {
+            if (e.target === el && e.propertyName === "opacity")
+                drop();
+        });
+        const timer = setTimeout(drop, PAGE_MS + 80);
+        this.timers.add(timer);
+    }
+    // ── Navigation ─────────────────────────────────────────────────────────
+    /**
+     * The arrangement 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: every `route.back()`
+     * travels through the browser's history and lands on a `popstate`, and an
+     * app-registered route guard may be async. Working from the committed
+     * arrangement in that window would make a second Escape aim at the page the
+     * first one is already taking away — so two quick Escapes would peel one page.
+     */
+    intended() {
+        return this.intent ?? { trail: this.paths(), focus: this.focus };
+    }
+    /** The history `state` describing `arr` — exactly what `targetFor` reads back. */
+    stateFor(arr) {
+        return {
+            pages: arr.trail.slice(0, arr.focus),
+            parked: arr.trail.slice(arr.focus + 1),
+            pinned: this.live.filter((e) => A.peek(e.$page, "pinned")).map((e) => e.path),
+        };
+    }
+    /**
+     * Stash the URL's search params and hash on the page they belong to — the
+     * current one — for when a crumb brings it back (see PageEntry.search).
+     * Called as a navigation is issued, just before the URL moves off it.
+     */
+    stashQuery() {
+        const entry = this.live.find((e) => e.path === A.peek(route.current, "path"));
+        if (!entry)
+            return;
+        entry.search = A.peek(() => ({ ...route.current.search }));
+        entry.hash = A.peek(route.current, "hash");
+    }
+    /**
+     * 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 navigation can still
+     * fail to land — an app-registered route guard vetoes it, or another one
+     * supersedes it — and what was queued behind it was worked out against the
+     * arrangement it would have produced.
+     */
+    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 pages 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;
+    }
+    /**
+     * Make the trail's `index`th page current: the URL and the visible run move
+     * to it, while the pages right of it stay open, parked past the right edge
+     * of the viewport. Nothing closes; it is a history entry, so the browser's
+     * back button returns the focus to where it was. What a click on a
+     * breadcrumb — any link to an open page — comes down to.
+     */
+    focusAt(index, search, hash) {
+        const arr = this.intended();
+        if (index < 0 || index >= arr.trail.length || index === arr.focus)
+            return;
+        const target = { trail: arr.trail, focus: index };
+        const path = arr.trail[index];
+        void this.issue(target, () => {
+            this.stashQuery();
+            // The page gets its own last search and hash back, unless the link
+            // that brought us here carries its own.
+            const entry = this.live.find((e) => e.path === path);
+            return route.go({ path, search: search ?? entry?.search, hash: hash ?? entry?.hash, state: this.stateFor(target) });
+        });
+    }
+    /**
+     * One step back along the trail — what Escape does. At the trail's
+     * end this closes the current page; mid-trail — with pages parked to the
+     * right — or when the page holds {@link Page.unsaved} work, the page stays
+     * open and the focus just moves to the page on its left, parking the one
+     * it leaves. Resolves `false` at the trail's start, where there is no left
+     * to go.
+     */
+    back() {
+        const arr = this.intended();
+        if (arr.focus === arr.trail.length - 1 && !this.unsavedAt(arr.trail[arr.focus]))
+            return this.closeCurrent();
+        if (arr.focus === 0)
+            return Promise.resolve(false);
+        this.focusAt(arr.focus - 1);
+        return Promise.resolve(true);
+    }
+    /** Close the current page (refused, like any close, while it is unsaved). */
+    closeCurrent() {
+        const arr = this.intended();
+        return this.closePath(arr.trail[arr.focus] ?? "");
+    }
+    /**
+     * Close whichever page is open at `path`, current or not — what
+     * {@link Page.close} and the crumb menu's Close come down to. `false` when
+     * that path isn't open, is the trail's only page, or holds
+     * {@link Page.unsaved} work — nothing may close an unsaved page; the app
+     * clears the flag first, which is its explicit "this is now discardable".
+     *
+     * Closing the current page at the trail's very end pops back through the
+     * browser's history to the entry beneath it, when it is there (restoring its
+     * scroll and search state); the arrangement is part of the match, so an
+     * entry where the closing page was merely parked won't do. Every other
+     * close is a *splice*: the columns around the closed one keep their place
+     * and state (the commit reconciles by path). That still gets its own
+     * history entry, so the browser's back button restores the closed column
+     * like any other arrangement — which is why it goes through `route.go` here
+     * rather than through `navigate()`, whose "link to an open page" check
+     * would turn it into a focus move.
+     */
+    closePath(path) {
+        const arr = this.intended();
+        const index = arr.trail.indexOf(normalizePath(path));
+        if (index < 0 || arr.trail.length < 2 || this.unsavedAt(arr.trail[index]))
+            return Promise.resolve(false);
+        const trail = arr.trail.filter((_, i) => i !== index);
+        // Closing the current page hands the focus to the page on its left (or,
+        // at the trail's start, to the one that was parked beside it); closing
+        // any other page moves the focus not at all.
+        const focus = index === arr.focus ? Math.max(0, index - 1) : arr.focus - (index < arr.focus ? 1 : 0);
+        const target = { trail, focus };
+        if (index === arr.focus && index === arr.trail.length - 1) {
+            return this.issue(target, () => route.back({ path: trail[focus], state: { pages: trail.slice(0, focus), parked: [] } }, { state: this.stateFor(target) }));
+        }
+        const current = trail[focus];
+        const moved = current !== arr.trail[arr.focus];
+        return this.issue(target, () => {
+            this.stashQuery();
+            // The current page keeps its search params and hash: it isn't going
+            // anywhere, and `go()` would otherwise default them away. When the
+            // close *did* move the focus, the newly current page gets its own back.
+            const entry = moved ? this.live.find((e) => e.path === current) : undefined;
+            return route.go({
+                path: current,
+                search: moved ? entry?.search : A.peek(() => ({ ...route.current.search })),
+                hash: moved ? entry?.hash : A.peek(route.current, "hash"),
+                state: this.stateFor(target),
+            });
+        });
+    }
+    /**
+     * Navigate to `href`. `origin` is the path of the page 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 deriveTrail}). `replace` swaps the
+     * originating page rather than stacking on top of it, and `beneath` says what
+     * the stack under the target is outright, for callers that know.
+     */
+    navigate(href, origin, replace = false, beneath) {
+        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;
+        const arr = this.intended();
+        // A link to a page that is already open is a return, not a navigation —
+        // a trail never holds the same path twice. Returning just moves the
+        // focus: the pages right of the target stay open, parked past the right
+        // edge, and nothing closes. That is the whole behaviour of a breadcrumb,
+        // which is exactly such a link.
+        const open = beneath ? -1 : arr.trail.indexOf(path);
+        if (open >= 0 && open !== arr.focus) {
+            this.focusAt(open, url.search ? search : undefined, hash || undefined);
+            return;
+        }
+        if (open >= 0) {
+            // The target is the page we're already on. Going nowhere — but the link
+            // may still carry a different search or hash, which belong to the
+            // current page: record that as a history entry, leaving the trail alone
+            // (the page reconciles by path, so it isn't even redrawn).
+            if (url.search === location.search && (url.hash || "") === (location.hash || ""))
+                return;
+            void this.issue(arr, () => route.go({ path, search, hash, state: this.stateFor(arr) }));
+            return;
+        }
+        // A new page: it opens at the trail's end and becomes current. The
+        // pages after the origin close — except pinned ones, which ride along,
+        // keeping their order, beneath the new page (and unsaved ones, which
+        // the commit itself keeps, parked — see `propose`). Without an
+        // originating page there is no trail to build on, so derive one — a
+        // nav click and a deep link to the same URL land identically (bar the
+        // pins, which a fresh tab doesn't have).
+        const originIndex = origin == null ? -1 : arr.trail.indexOf(origin);
+        const base = beneath
+            ? beneath.map(normalizePath).filter((p) => p !== path)
+            : originIndex < 0
+                ? this.deriveTrail(path).slice(0, -1)
+                : arr.trail.slice(0, replace ? originIndex : originIndex + 1);
+        // A replaced origin closes, pin or no pin: replacing is the page's own
+        // doing, not somewhere else navigating over it.
+        const under = [...base, ...this.pinnedIn(arr.trail, [...base, path, replace ? origin : null])];
+        const target = { trail: [...under, path], focus: under.length };
+        void this.issue(target, () => {
+            this.stashQuery();
+            return route.go({ path, search, hash, state: this.stateFor(target) });
+        });
+    }
+    /** Programmatic push/replace, with the current page as the implied origin. */
+    pushPath(path, replace) {
+        const arr = this.intended();
+        this.navigate(path, arr.trail[arr.focus] ?? null, replace);
+    }
+    /** Programmatic open-as-a-whole-trail: `beneath` as given, or derived. */
+    openPath(path, beneath) {
+        this.navigate(path, null, false, beneath);
+    }
+    // ── 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-page` (which decides what the click truncates), `data-page=replace`,
+     * and return-to-an-open-page 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 page = anchor.closest(".s-page");
+            const origin = page ? this.live.find((entry) => entry.el === page) : undefined;
+            this.navigate(url.href, origin?.path ?? null, anchor.getAttribute("data-page") === "replace");
+            return true;
+        });
+    }
+    // ── What the shell's top bar asks ──────────────────────────────────────
+    /**
+     * The current page's page, or `undefined` while there is none. Reactive on
+     * *which* page is current, so the bar follows every move along the trail;
+     * the fields it then reads (`title`, `actions`) are reactive in their own
+     * right, so a page that names itself when its data lands updates the bar in
+     * place.
+     */
+    currentPage() {
+        return this.byId.get(this.$state.currentId)?.$page;
+    }
+    /**
+     * The breadcrumb trail, drawn by `main()` into the top bar: every open
+     * page, oldest first, the ones on screen right now in bold, pinned ones
+     * wearing their pin. Every crumb but the current page's is a plain link to
+     * that page, and a link to an open page is a focus move (see `navigate`) —
+     * so clicking along the trail closes nothing, in either direction, and the
+     * pages right of the current one wait just past the viewport's edge.
+     * Right-click (or long-press) offers pinning, and closing just that one
+     * page — the close that splices it out of the middle when it isn't last.
+     */
+    drawCrumbs() {
+        // The very same row `S.tabs` puts its tab strip in: it scrolls when the
+        // trail outgrows the bar, and shows a ‹ / › over whichever end still has
+        // crumbs to reach — which a mouse can use, unlike a bare scroll area.
+        scrollStrip({
+            attrs: ".s-crumbs role=navigation aria-label=Breadcrumbs",
+            content: () => {
+                A(() => {
+                    const paths = this.$state.paths;
+                    const focus = this.$state.focus;
+                    let currentEl;
+                    for (let i = 0; i < paths.length; i++) {
+                        if (i)
+                            sepIcon({ size: "0.85em", attrs: ".s-crumb-sep" });
+                        const el = this.drawCrumb(paths[i], i, i === focus);
+                        if (i === focus)
+                            currentEl = el;
+                    }
+                    // Keep the page you are on in view once this pass has been laid out.
+                    requestAnimationFrame(() => { if (currentEl)
+                        revealInStrip(currentEl); });
+                });
+            },
+        });
+    }
+    drawCrumb(path, index, current) {
+        // Safe to close over: the crumb list is rebuilt whenever the trail (or
+        // its focus) changes, so this entry is `paths[index]`'s for the crumb's
+        // whole life.
+        const entry = this.live[index];
+        // A real link, for the page it names — so it has an address to hover, to
+        // middle-click, to copy. No click handling of its own: the shell's link
+        // handling already makes any link to an open page the focus move a crumb
+        // should be (see `navigate`). The page you are on is a span: nowhere to go.
+        return A(current ? "span.s-crumb aria-current=page" : "a.s-crumb", () => {
+            if (!current)
+                A("href=", path);
+            // Bold = on screen right now, so the trail also says which of its pages
+            // are the visible columns — not just which one is current.
+            A(() => { if (entry?.$page.visible)
+                A(".s-crumb-on"); });
+            // The ● of unsaved work — the mark that nothing can close this page —
+            // and the pin of a page that navigation elsewhere won't close.
+            A(() => { if (entry?.$page.unsaved)
+                dotIcon({ size: "0.45em", attrs: ".s-crumb-unsaved" }); });
+            A(() => { if (entry?.$page.pinned)
+                pinIcon({ size: "0.85em", attrs: ".s-crumb-pin" }); });
+            // `||`, not `??`: the root path's last segment is the empty string.
+            A(() => { A("#", entry?.$page.title ?? entry?.$ui.fallback ?? (path.split("/").pop() || path)); });
+            // Taking over right-click means taking the browser's link menu away, so
+            // the two entries anyone actually reaches for on a link come first,
+            // where that menu would have had them, and the shell's own verbs sit
+            // below the rule.
+            addContextMenu({ items: [
+                    {
+                        // A real new tab, so it arrives cold and builds its own stack
+                        // from the path — exactly what the same link middle-clicked does.
+                        label: "Open in new tab",
+                        icon: newTabIcon,
+                        click: () => { window.open(path, "_blank", "noopener"); },
+                    },
+                    {
+                        label: "Copy link",
+                        icon: linkIcon,
+                        click: () => void copyLink(path),
+                    },
+                    { separator: true },
+                    {
+                        label: () => { A(() => { A("#", entry?.$page.pinned ? "Unpin" : "Pin"); }); },
+                        icon: () => { A(() => { (entry?.$page.pinned ? pinOffIcon : pinIcon)(); }); },
+                        click: () => { if (entry)
+                            this.togglePin(entry); },
+                    },
+                    {
+                        label: "Close",
+                        icon: closeIcon,
+                        // Greyed out while the page holds unsaved work: nothing may
+                        // close it (`closePath` would refuse anyway). Read here, in the
+                        // crumb's own scope, so the flag flipping redraws the crumb —
+                        // the ● above and this menu entry stay one truth.
+                        disabled: entry?.$page.unsaved === true,
+                        click: () => void this.closePath(path),
+                    },
+                ] });
+        });
+    }
+    /**
+     * Flip a page's pin (see {@link Page.pinned}). The flag lives on the page;
+     * the current history entry's snapshot is rewritten too, so a reload keeps
+     * the pin — a same-page state tweak, which the router applies unguarded.
+     */
+    togglePin(entry) {
+        entry.$page.pinned = !A.peek(entry.$page, "pinned") || undefined;
+        route.current.state.pinned = this.live.filter((e) => A.peek(e.$page, "pinned")).map((e) => e.path);
+    }
+    // ── document.title ─────────────────────────────────────────────────────
+    /**
+     * `"<page title> · <app title>"`, kept in sync with the current page — and
+     * prefixed `"• "` while *any* open page holds unsaved work, the way editors
+     * mark a dirty document. Any page, not just the current one: the risk of
+     * losing the work is tab-wide, so the mark on the tab is too.
+     */
+    watchTitle() {
+        const original = document.title;
+        A(() => {
+            const entry = this.byId.get(this.$state.currentId);
+            const pageTitle = entry?.$page.title ?? entry?.$ui.fallback;
+            const appTitle = typeof this.opts.title === "string" ? this.opts.title : undefined;
+            // Reading `paths` re-runs this when the trail changes; each page's own
+            // `unsaved` (up to the first dirty one) does the rest.
+            void this.$state.paths;
+            const dirty = this.live.some((e) => e.$page.unsaved);
+            const title = pageTitle && appTitle ? `${pageTitle} · ${appTitle}` : pageTitle || appTitle;
+            if (title)
+                document.title = (dirty ? "• " : "") + title;
+        });
+        A.clean(() => { document.title = original; });
+    }
+    /**
+     * While any open page holds unsaved work, closing the tab — or navigating
+     * the whole browser away — runs into the browser's own are-you-sure. When
+     * the user stays, the unsaved page is brought back on screen if it wasn't,
+     * so what held the tab is in front of them rather than parked out of sight.
+     */
+    guardTabClose() {
+        if (typeof window === "undefined")
+            return;
+        let leaving = false;
+        const onHide = () => { leaving = true; };
+        const onBeforeUnload = (e) => {
+            // Being asked again means we weren't gone after all (a bfcache restore).
+            leaving = false;
+            const dirty = this.live.find((entry) => A.peek(entry.$page, "unsaved"));
+            if (!dirty)
+                return;
+            e.preventDefault();
+            e.returnValue = true; // Chrome/Edge < 119
+            // This task only ever amounts to anything if the user cancels: a
+            // confirmed leave unloads the document (`pagehide`) first.
+            const path = dirty.path;
+            setTimeout(() => {
+                if (leaving)
+                    return;
+                const entry = this.live.find((live) => live.path === path);
+                if (entry && !A.peek(entry.$page, "visible"))
+                    this.focusAt(this.intended().trail.indexOf(path));
+            }, 0);
+        };
+        window.addEventListener("beforeunload", onBeforeUnload);
+        window.addEventListener("pagehide", onHide);
+        A.clean(() => {
+            window.removeEventListener("beforeunload", onBeforeUnload);
+            window.removeEventListener("pagehide", onHide);
+        });
+    }
+    // ── Rendering ──────────────────────────────────────────────────────────
+    /**
+     * Draw the column viewport into the current element. Called by `main()`.
+     *
+     * A column is the page's own content, plus the one bit of chrome the shell
+     * places for it: its {@link Page.actions}, in a strip on wide shells and in
+     * the top bar on narrow ones (see {@link drawActions}).
+     */
+    drawColumns() {
+        const container = A("div.s-pages role=main", () => {
+            // Published before the first page draws, rather than from the return
+            // value below: a page 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.drawPage(Number(id)), (order, id) => [order, Number(id)]);
+        });
+        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();
+    }
+    drawPage(id) {
+        const entry = this.byId.get(id);
+        if (!entry)
+            return;
+        let el;
+        // How much room the page 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 page is
+        // created at the width the window gives it — the "full" width 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.maxWidth;
+            entry.maxWidth = asked === "half" || asked === "screen" ? asked : "full";
+            const width = this.roomFor(entry.maxWidth);
+            if (!width)
+                return;
+            entry.width = width;
+            // Published to the page too, so a handler can read the box it is about
+            // to draw into without measuring it.
+            if (A.peek(entry.$page, "width") !== width)
+                entry.$page.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 mind.
+            if (!el)
+                return;
+            el.style.width = `${width}px`;
+            this.scheduleLayout();
+        });
+        el = A(`section.s-page${entry.width ? ` w:${entry.width}px` : ""}`, "destroy=", (node) => this.playExit(entry, node), () => {
+            // The actions strip, in its own scope: chrome may redraw freely — when
+            // the page changes its actions, when the shell crosses the narrow
+            // threshold — but the body below never may.
+            A(() => this.drawActions(entry));
+            A("div.s-content", () => {
+                entry.draw(entry.$page);
+                // After the content, so there is something to scroll when restoring.
+                route.persistScroll(entry.path);
+                // A page that named itself is done; one that didn't lends its
+                // first line of text (the DOM is already built — Aberdeen draws
+                // synchronously) to the crumbs and document.title, so neither
+                // ever goes blank. Peeked: a rename must not redraw the page.
+                if (A.peek(entry.$page, "title") == null) {
+                    const text = firstText(A());
+                    if (text && A.peek(entry.$ui, "fallback") !== text)
+                        entry.$ui.fallback = text;
+                }
+            });
+            // The loading hint, in its own scope so flipping the flag doesn't
+            // redraw the page's content. Held-back pages 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-page-loading aria-hidden=true", () => { A("i"); A("i"); A("i"); });
+            });
+        });
+        entry.el = el;
+        // It has its width, but nothing animates from the arbitrary initial spot;
+        // `layout()` gives the page 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; });
+        // A held-back page that finishes loading gets to play its enter animation.
+        A(() => {
+            void entry.$page.loading;
+            this.scheduleLayout();
+        });
+        this.scheduleLayout();
+    }
+    /**
+     * The one bit of column chrome the shell draws: the page's actions, in a
+     * quiet strip above the scroll area — and only while the shell is wide, the
+     * top bar carrying them otherwise. Everything else in a column is the page's
+     * own content: a screen that wants a heading or a card draws them itself.
+     * Going back isn't here either — that is the breadcrumbs' job, in the bar.
+     */
+    drawActions(entry) {
+        if (this.opts.$shell.narrow || entry.$page.actions == null)
+            return;
+        A("div.s-page-actions", () => drawSlot(entry.$page.actions));
+    }
+    // ── Layout engine ──────────────────────────────────────────────────────
+    scheduleLayout() {
+        if (this.layoutQueued)
+            return;
+        this.layoutQueued = true;
+        requestAnimationFrame(() => {
+            this.layoutQueued = false;
+            this.layout();
+        });
+    }
+    /**
+     * Measure the shell, and with it the width the window gives a page of each
+     * layout. Measured on the *shell*, not on the column 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 page NEVER
+        // resizes because a neighbour came or went; only a window resize (the
+        // snap pass in `layout`) changes them:
+        // - "full" fills the standard content area exactly;
+        // - "half" is half of it whenever that half is still a usable column, and
+        //   the whole of it on narrower screens;
+        // - "screen" ignores the standard width and takes everything the window
+        //   has — which also means nothing ever fits beside it.
+        const full = Math.max(0, Math.min(SHELL_PX, total) - chrome);
+        const halved = full / 2;
+        return {
+            total,
+            chrome,
+            half: halved >= PAIR_MIN_PX ? halved : full,
+            full,
+            screen: Math.max(0, total - chrome),
+        };
+    }
+    /**
+     * The measurements this pass runs on. Taken once per layout pass and per
+     * commit, and shared with the pages 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 page asking for this is, right now; 0 while the shell can't be measured. */
+    roomFor(maxWidth) {
+        return this.geometry()?.[maxWidth] ?? 0;
+    }
+    /**
+     * Size and position every page, 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 pages 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 shell = container?.closest(".s-main");
+        if (!container || !shell)
+            return;
+        const n = this.live.length;
+        // A page 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;
+        // 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 !== geom.total;
+        if (snap) {
+            this.lastBodyW = geom.total;
+            shell.classList.add("s-shell-snap");
+        }
+        const width = (entry) => geom[entry.maxWidth];
+        // The visible run: as many columns as the window fits, at the sizes the
+        // window gives them, ending at the current page — which always shows.
+        // Pages beyond it are parked past the right edge (see phase 1).
+        const cur = Math.min(this.focus, n - 1);
+        let first = cur;
+        let runSum = width(this.live[cur]);
+        if (stacking) {
+            for (let i = cur - 1; i >= 0; i--) {
+                const sum = runSum + width(this.live[i]);
+                if (sum > geom.screen)
+                    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 "screen" up that's the window's edges.
+        const area = Math.min(geom.screen, Math.max(geom.full, runSum));
+        for (let i = first; i <= cur; i++)
+            this.live[i].width = width(this.live[i]);
+        // Pages 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 page that caused it instead of
+        // snapping.
+        shell.style.setProperty("--s-shell-w", `${geom.chrome + area}px`);
+        // Phase 1 — every page's *start* state for this frame. Pages 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 && i <= cur;
+            // Visible columns tile the content area, left to right. Pages crowded
+            // out from under the run rest at its left edge; pages beyond the
+            // current page park just past its right edge — both keep their last
+            // width. Deeper pages layer over shallower ones, each on the odd
+            // layer for its depth (see LAYER_STEP).
+            place(el, shown ? x : i > cur ? area : 0, entry.width, LAYER_STEP * i + 1);
+            // What `$page.visible` reports: on screen, as opposed to merely alive.
+            // Peeked, because this pass is not a reactive scope and must not become
+            // one — and written only on a change, so per-page UI hanging off it
+            // isn't rebuilt by every layout pass.
+            if (A.peek(entry.$page, "visible") !== shown)
+                entry.$page.visible = shown;
+            if (shown)
+                x += entry.width;
+            el.classList.toggle("s-page-sep", shown && i > first);
+            // Off-screen pages fade out over the edge they park at and, once
+            // faded, stop being rendered at all — but they keep their DOM, and
+            // their scroll position.
+            el.classList.toggle("s-page-hidden", i < first);
+            el.classList.toggle("s-page-parked", i > cur);
+            el.toggleAttribute("inert", !shown);
+            if (entry.placed)
+                continue;
+            fresh.push(entry);
+            // A page 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-page-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-page-enter");
+            entry.enter = false;
+            entry.placed = true;
+        }
+    }
+    /** Let a `loading` page'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 page 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);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function sameStack(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+/**
+ * The first non-empty text inside `el`, trimmed and capped at a name-like
+ * length — the stand-in title for a page that never set one.
+ */
+function firstText(el) {
+    const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+        const t = n.textContent.trim();
+        if (t)
+            return t.length > 48 ? `${t.slice(0, 47).trimEnd()}…` : t;
+    }
+}
+/**
+ * Put a page's address on the clipboard, as the absolute URL someone can paste
+ * anywhere — which is what the browser's own "Copy link" would have given them.
+ * Confirmed with a toast, since a silent copy leaves you wondering; `writeText`
+ * needs a secure context, so a failure says so rather than lying.
+ */
+async function copyLink(path) {
+    const url = new URL(path, location.href).href;
+    try {
+        await navigator.clipboard.writeText(url);
+        toast({ message: "Link copied." });
+    }
+    catch {
+        toast({ message: "Couldn't copy the link.", type: "danger" });
+    }
+}
+function drawDefaultNotFound($page) {
+    A("p fg:$s-muted", () => A("#", `No page at ${$page.path}`));
+}
+// ─── Public helpers ──────────────────────────────────────────────────────────
+/**
+ * Navigating the routed `S.main()` shell from code, for the times it isn't a
+ * link click, such as opening the screen for a record you just created.
+ *
+ * The same rules as a link click apply: pushing a path that is already open
+ * goes back to it — a focus move along the trail, closing nothing — rather
+ * than opening it twice, and a page holding {@link Page.unsaved} work is
+ * never closed, only parked.
+ *
+ * @example
+ * ```ts
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   S.pages.push(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export const pages = {
+    /**
+     * Opens `path` in a new page on top of the current one, closing the
+     * unpinned pages that were after it (pinned ones stay, sliding in beneath
+     * the new page).
+     */
+    push(path) {
+        requireActive().pushPath(path, false);
+    },
+    /**
+     * Opens `path` in place of the current page, which closes. The pages
+     * beneath it stay as they are.
+     */
+    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.
+     * Pages the new arrangement also holds stay as they are; ones it drops
+     * close, except pages with {@link Page.unsaved} work, which stay, parked.
+     *
+     * @example
+     * ```ts
+     * S.pages.open(`/thread/${id}`, [`/mailbox/${mailboxId}`]);
+     * ```
+     */
+    open(path, beneath) {
+        requireActive().openPath(path, beneath);
+    },
+    /**
+     * Closes the current page, or, given a `path`, whichever page is open at
+     * it. A page that isn't current is taken out on its own, leaving the
+     * columns around it exactly as they are.
+     *
+     * Resolves `false` if the page didn't close: it holds
+     * {@link Page.unsaved} work, `path` isn't open, or another navigation got
+     * there first.
+     */
+    close(path) {
+        const ctl = requireActive();
+        return path == null ? ctl.closeCurrent() : ctl.closePath(path);
+    },
+    /** The paths of the open pages, oldest first. Reactive: safe to read in a scope. */
+    get trail() {
+        return active ? active.$state.paths : [];
+    },
+    /**
+     * The path of the current page: the one the URL names, and the rightmost
+     * column on screen. The pages after it in {@link pages.trail} are the
+     * ones parked past the viewport's right edge. Reactive.
+     */
+    get current() {
+        return active ? active.$state.paths[active.$state.focus] : undefined;
+    },
+};
+function requireActive() {
+    if (!active)
+        throw new Error("Staffa: S.pages needs a routed S.main() (one with `routes`) to be mounted");
+    return active;
+}