staffa 0.8.1 → 0.10.0

package/dist/components/panels.d.ts

@@ -1,16 +1,29 @@
+import { OPAQUE } from "aberdeen";
+import { type Slot } from "../core.js";
 /**
  * Routed, multi-column panel navigation for {@link main}.
  *
- * Each route draws one screen of the app, called a panel, and as many panels as
- * fit are shown at a time. On a phone that is one, so a link opens a new panel
- * on top and closing it brings the previous one back. On a wider screen the
- * panels that would have covered each other sit side by side instead, oldest on
- * the left. The app's own code is the same either way.
+ * Each route draws one screen of the app, called a *panel*. The open panels
+ * form a **stack**, and one of them is the **current** panel: the one the URL
+ * names, and the rightmost column on screen. As many panels as fit are shown,
+ * ending at the current one — on a phone that is one at a time, on a wider
+ * screen the panels that would have covered each other sit side by side
+ * instead. The app's own code is the same either way.
  *
- * Navigation runs through `aberdeen/route`: the URL holds the top panel, and
- * the ones beneath it are stored beside it in the history entry. So back and
- * forward step through whole arrangements of columns, and a reload (or a shared
- * link) brings the same columns back.
+ * Going to a panel that is already open — a breadcrumb, or any link to it —
+ * just moves the current-panel cursor along the stack: panels right of it stay
+ * open, parked past the right edge of the viewport, and nothing closes.
+ * Opening a *new* panel is what prunes: everything after the panel it came
+ * from closes, except panels the user pinned — which ride along beneath the
+ * new panel — and panels holding unsaved work, which no navigation ever tears
+ * down. Escape steps one panel left, closing the panel it leaves only when
+ * that panel is the stack's discardable end.
+ *
+ * Navigation runs through `aberdeen/route`: the URL holds the current panel,
+ * and the rest of the arrangement — the panels before it, the ones parked
+ * after it, and which are pinned — is stored beside it in the history entry.
+ * So back and forward step through whole arrangements of columns, and a reload
+ * (or a shared link) brings the same columns back.
  */
 /** Flattens an intersection into a single object type, so hovers read nicely. */
 type Prettify<T> = {
@@ -39,21 +52,36 @@ export type SegParams<S extends string> = S extends `[...${infer Name}]` ? {
  * `{ id: string; taskId: number }`.
  */
 export type PathParams<P extends string> = P extends `${infer Head}/${infer Rest}` ? SegParams<Head> & PathParams<Rest> : SegParams<P>;
-/** A panel draw function: it receives the panel's {@link Page} and draws into the current scope. */
-export type RouteHandler<P = any> = (page: Page<P>) => void;
+/** A panel draw function: it receives the panel's {@link Panel} and draws into the current scope. */
+export type RouteHandler<P = any> = (panel: Panel<P>) => void;
 /**
  * A route table: path templates mapped to panel draw functions. Used as the
  * loose (non-inferred) type; `S.main()` infers a more precise type from the
- * literal you pass, so each handler's `$page.params` is typed per its key.
+ * literal you pass, so each handler's `$panel.params` is typed per its key.
  */
 export type Routes = Record<string, RouteHandler>;
 /**
  * The shape `S.main()`'s `routes` option is checked against: every key types its
  * own handler's `params`. Used as a self-referential generic constraint, which
- * is what makes `$page.params` infer from the route key.
+ * is what makes `$panel.params` infer from the route key.
  */
 export type RouteTable<R> = {
-    [K in keyof R & string]: (page: Page<Prettify<PathParams<K>>>) => void;
+    [K in keyof R & string]: (panel: Panel<Prettify<PathParams<K>>>) => void;
+};
+/**
+ * What belongs beneath a path that arrives cold, worked out from the params of
+ * the path itself. Return the paths shallowest first, or nothing to leave this
+ * one to the parent-path derivation.
+ */
+export type AncestorsHandler<P = any> = (params: P, path: string) => readonly string[] | undefined | void;
+/**
+ * A table of {@link AncestorsHandler}s keyed by path template, the same way
+ * `routes` is — so each one's `params` are matched and typed from its own key
+ * rather than parsed out of the path a second time. The keys are checked
+ * against the route table, so a stale one is a type error.
+ */
+export type AncestorTable<R> = {
+    [K in keyof R & string]?: (params: Prettify<PathParams<K>>, path: string) => readonly string[] | undefined | void;
 };
 /**
  * What a route handler gets: the params from its route, plus everything the
@@ -61,124 +89,323 @@ export type RouteTable<R> = {
  * you can set things later, such as a `title` that arrives with your data or
  * `loading` going back to `false`, and the shell keeps up.
  *
- * Search params and the `#hash` belong to the top panel only. A panel with
- * another one on top of it keeps just its path, so anything a panel needs in
- * order to redraw itself has to live in that path.
+ * Search params and the `#hash` belong to the current panel only. Any other
+ * panel keeps just its path, so anything a panel needs in order to redraw
+ * itself has to live in that path. (A panel browsed away from does get its
+ * search and hash back when a crumb makes it current again.)
  */
-export interface Page<P = Record<string, string | number | string[]>> {
+export interface Panel<P = Record<string, string | number | string[]>> {
     /**
      * The params matched from this panel's path, typed per its route key:
      * `[x]` is a `string`, `[x=integer]` a `number`, `[...x]` a `string`.
      * Read-only.
      */
     readonly params: P;
+    /**
+     * The stack this panel is in — the very object `S.main()` hands back. It is
+     * here as well because a route handler runs *while* that call is still
+     * going, so its return value isn't available to it yet; this always is.
+     */
+    readonly stack: PanelStack;
     /** This panel's path, e.g. `"/projects/7"`. Read-only. */
     readonly path: string;
-    /** Shown in `document.title` while this panel is top-most. */
+    /**
+     * Names this screen, in the top bar's breadcrumb stack and in
+     * `document.title` while the panel is current. A panel that doesn't set one
+     * borrows the first line of text in its own body, so the stack never shows a
+     * blank — but a borrowed paragraph makes a poor name, so say it yourself.
+     *
+     * It does **not** conjure a heading: naming a screen and heading its content
+     * are different jobs, and a screen that wants its name in its own body
+     * writes it there, where it owns the typography.
+     */
     title?: string;
     /**
-     * How much room this panel takes. The content area is the page, at most
-     * 1280px wide, minus the nav sidebar; the widths below assume a sidebar of
-     * around 170px, so without one add that back.
+     * This screen's own actions: a couple of buttons, a menu. The shell draws
+     * them — never the panel — and *where* depends on facts only the shell has:
+     * a quiet strip at the top of this panel's column while several columns are
+     * up, and the top bar (where they take the app's own `menu` slot) once the
+     * shell is narrow and this panel is the screen.
+     *
+     * They are drawn in exactly one of those places at a time, so crossing the
+     * threshold redraws them; anything stateful inside (the focus in a search
+     * box) is lost. Buttons and menus are fine.
+     */
+    actions?: Slot;
+    /**
+     * How wide this panel's column actually is, in pixels — what
+     * {@link Panel.maxWidth} asked for, resolved against the window. Reactive and
+     * read-only, and correct *before* your handler draws, so content that sizes
+     * itself can read it instead of measuring.
      *
-     * - `"small"` is 360 to 540px once two panels fit side by side, which is
-     *   what makes it right for lists, detail forms, and anything else that
-     *   reads well at phone width. Below that it takes the whole content area
-     *   (so up to ~730px), like a medium does. A lone small leaves its other
-     *   half empty, and that is exactly where the next small lands, without
-     *   anything on screen moving.
-     * - `"medium"` (the default) takes the whole content area: up to ~1100px,
-     *   and the screen width on a phone. The safe default for ordinary screens.
-     *   Nothing fits beside a medium on a standard 1280px page, though on a wide
-     *   enough window a small still can.
-     * - `"large"` takes the whole window, with no upper limit (~1750px on a
-     *   1920px screen): for boards, wide tables and dense dashboards. While it's
-     *   open the whole shell (top bar, content and footer) stretches to the
-     *   screen edges rather than stopping at 1280px.
+     * You rarely need it: the shell places the chrome for you. It's for content
+     * that genuinely differs by width, such as a table that becomes a list.
+     */
+    readonly width: number;
+    /**
+     * Whether this panel is on screen right now: not crowded out from under the
+     * visible run, not parked past its right end, and not on its way out.
+     * Reactive and read-only.
      *
-     * When more columns fit than the standard page holds (three smalls, or a
-     * medium and a small) the page itself grows, staying centred, to hold them.
+     * The one to hang per-panel floating UI on (a FAB, a "3 selected" bar), for
+     * which "am I the current panel?" is the wrong question — two columns can be
+     * visible at once, and both of them are really there.
+     */
+    readonly visible: boolean;
+    /**
+     * The widest this panel can usefully be. Every panel must work at 360–540px,
+     * because that is what it gets when two columns fit; this says how much
+     * *more* it can take.
      *
-     * A panel's width depends only on the size of the window, never on what else
-     * is open, so opening or closing a panel never resizes the ones already on
-     * screen.
+     * - `"half"` — nothing more. Half the content area (360–540px), so a second
+     *   column fits beside it. For lists and detail forms.
+     * - `"full"` (the default) — the whole content area, up to ~1100px.
+     * - `"screen"` — the whole window, unbounded: boards, wide tables, dense
+     *   dashboards. While one is open the shell itself stretches to the screen
+     *   edges instead of stopping at the standard 1280px page.
      *
-     * The panel is sized from this **before** your handler runs, so anything that
-     * measures its own box has a real one from the first frame. What it is sized
-     * at is whatever this says at that moment, which for a brand-new panel is the
-     * default: a handler that *assigns* `layout` is drawn at the medium width and
-     * reflowed immediately after — in time for the frame, but not for a
-     * measurement taken in the same breath.
+     * Below the width two columns need, everything takes the content area
+     * whatever it asked for. Widths depend only on the window, never on what
+     * else is open, so opening or closing a panel never resizes another.
      *
-     * Assigning it later works just as well. When your data arrives and you find
-     * you want the wide one, the panel reflows to its new width without being
-     * redrawn — so nothing in it is rebuilt or loses its state — and the columns
-     * beside it move over.
+     * Set it at the top of your handler and the panel is already that wide when
+     * you draw (see {@link Panel.width}); set it later — when your data tells you
+     * — and the panel reflows without being redrawn, keeping its state, while
+     * the columns beside it move over.
      */
-    layout?: "small" | "medium" | "large";
+    maxWidth?: "half" | "full" | "screen";
     /**
      * Set this while you're fetching what the panel needs, and back to `false`
      * when you're done. A new panel waits a moment before sliding in, so it can
      * arrive with real content instead of empty; if the wait drags on it slides
      * in anyway and shows a loading indicator until the flag clears. It only
-     * affects the animation; the stack, the URL and `requestClose` never wait
-     * for it.
+     * affects the animation; the stack and the URL never wait for it.
      */
     loading?: boolean;
     /**
-     * Your chance to say no. Everything that would close this panel waits for
-     * it: Escape, the panel's own ✕ or Cancel button ({@link Page.close}, or a
-     * box with `close: true`), the browser's back button, a link that would
-     * close it, and {@link panels}.`close()`. Return `false` to keep the panel
-     * open, usually after a dirty check and a {@link confirm}.
+     * Keeps this panel from being closed by navigation happening *elsewhere*.
+     * Opening a new panel normally closes everything after the panel it came
+     * from; a pinned panel survives that, staying in the stack — parked past the
+     * right edge of the viewport — slotted in beneath the new panel, one crumb
+     * click away. The user toggles it from the crumb's context menu
+     * (right-click or long-press), which is also where the pin shows; setting
+     * it from code does the same thing.
+     *
+     * A pin never blocks an *explicit* close: Escape at the stack's end,
+     * {@link Panel.close}, the crumb menu's Close and `data-panel=replace` all
+     * still close the panel.
+     */
+    pinned?: boolean;
+    /**
+     * Set this while the panel holds work that must not be lost — a dirty form,
+     * an upload in flight. An unsaved panel cannot be closed, by anything:
+     * navigation that would prune it parks it instead, past the viewport's
+     * right edge, wearing a ● in its crumb — even the browser's back button
+     * only parks it. {@link Panel.close} and the crumb menu's Close refuse,
+     * Escape on it steps left along the stack rather than closing, and closing
+     * the browser tab runs into the browser's own are-you-sure (after which the
+     * shell brings the unsaved panel back on screen).
+     *
+     * Only the app clears it; the user has no toggle. A Save or Discard button
+     * clears it and then closes:
+     *
+     * ```ts
+     * A(() => { $panel.unsaved = $form.dirty || undefined; });
+     * S.button({ content: "Discard", attrs: ".neutral", click: () => {
+     *   $panel.unsaved = false;   // explicitly — see below
+     *   void $panel.close();
+     * }});
+     * ```
+     *
+     * The explicit `unsaved = false` before `close()` matters when the flag is
+     * kept by a reactive scope, as above: resetting the form marks that scope
+     * dirty, but it reruns *after* the running handler — after `close()` has
+     * already been refused.
      */
-    requestClose?: () => boolean | Promise<boolean>;
+    unsaved?: boolean;
     /**
-     * Closes **this** panel, wherever it sits in the stack. The top panel goes
-     * back to whatever was underneath it; any other panel is taken out on its
-     * own, leaving the columns to its right where they are, with their state,
-     * and the URL alone, since the top panel didn't move. Either way it
-     * becomes a history entry, so the browser's back button brings it back.
+     * Closes **this** panel, wherever it sits in the stack. Closing the current
+     * panel hands the focus to the panel on its left; closing any other panel
+     * takes just it away, leaving the columns around it where they are, with
+     * their state. Either way it becomes a history entry, so the browser's
+     * back button brings the panel back.
      *
-     * Resolves `false` if the panel didn't close: {@link Page.requestClose} said
-     * no, it was the only panel on the stack (so there's nothing to go back to),
-     * or another navigation got there first. The shell draws no back arrows or
-     * ✕ of its own, so this (or `S.box`'s `close` option) is how a panel gives
-     * the user a way out.
+     * Resolves `false` if the panel didn't close: it holds
+     * {@link Panel.unsaved} work, it was the only panel on the stack (so
+     * there's nothing to show instead), or another navigation got there first.
+     * The shell's breadcrumbs already travel back, so reach for this when a
+     * screen wants a more explicit way out: a Cancel button, or a Save that
+     * closes.
      *
      * @example
      * ```ts
-     * S.button({ content: "Cancel", attrs: ".neutral", click: () => void $page.close() });
+     * S.button({ content: "Cancel", attrs: ".neutral", click: () => void $panel.close() });
      * ```
      */
     close(): Promise<boolean>;
 }
-/** Options the panel stack needs from its shell. */
+/** Options the stack needs from its shell. */
 export interface PanelStackOptions {
     routes: Routes;
     notFound?: RouteHandler<{}>;
-    /** Set `false` to show only the top panel, however much room there is. */
+    /** What to open beneath a path that arrives cold. See {@link MainOptions.ancestors}. */
+    ancestors?: Record<string, AncestorsHandler | undefined>;
+    /** Set `false` to show only the current panel, however much room there is. */
     stacking?: boolean;
     /** The shell's own title, used as the suffix of `document.title`. */
     title?: unknown;
+    /**
+     * The shell's live narrow flag (see `main()`), which decides where a panel's
+     * chrome goes: in its own column, or promoted into the top bar. Shared rather
+     * than measured again here, so the bar and the columns can't disagree about
+     * which regime they are in.
+     */
+    $shell: {
+        narrow: boolean;
+    };
 }
-export declare class PanelController {
+/**
+ * The panel stack behind a routed `S.main()`, and what that call hands back:
+ * the open {@link Panel}s, which of them is current, and the four ways to
+ * change that. Everything on it is scoped to its own shell.
+ *
+ * Every navigation settles asynchronously (closes travel through the
+ * browser's history), so the methods resolve once it has: `true` when it
+ * landed, `false` when it didn't — an unsaved panel refused to close, an
+ * app-registered route guard said no, or another navigation superseded it.
+ * Ignore the promise unless you care.
+ *
+ * @example
+ * ```ts
+ * const shell = S.main({ title: "Trackle", routes: { ... } });
+ *
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   shell.pushPanel(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export interface PanelStack {
+    /**
+     * The open panels, oldest first — the stack itself, as live objects rather
+     * than a copy of it. Writing through one is how you pin a panel, or rename
+     * it, from outside its own handler. Reactive on the stack's shape; don't
+     * hold a {@link Panel} across a navigation, since a closed one is dropped
+     * here while its element plays out its exit.
+     */
+    readonly panels: readonly Panel[];
+    /** Index into {@link PanelStack.panels} of the current panel. Reactive. */
+    readonly currentPanelIndex: number;
+    /**
+     * The current panel — shorthand for `panels[currentPanelIndex]`, and
+     * `undefined` only while the stack is still empty. Reactive on *which*
+     * panel is current; the fields you then read (`title`, `actions`, …) are
+     * reactive in their own right.
+     */
+    readonly currentPanel: Panel | undefined;
+    /**
+     * Opens `path` in a new panel on top of the current one, closing the
+     * unpinned panels that were after it (pinned ones stay, sliding in beneath
+     * the new panel).
+     *
+     * The same rules as a link click apply: pushing a path that is already open
+     * goes back to it — a focus move along the stack, closing nothing — rather
+     * than opening it twice, and a panel holding {@link Panel.unsaved} work is
+     * never closed, only parked. That's what a plain link does, and what
+     * `data-panel=push` says outright.
+     */
+    pushPanel(path: string): Promise<boolean>;
+    /**
+     * Opens `path` in place of the current panel, which closes. The panels
+     * beneath it stay as they are. That's what a `data-panel=replace` link does.
+     */
+    replacePanel(path: string): Promise<boolean>;
+    /**
+     * Opens `path` as a whole stack 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 {@link MainOptions.ancestors});
+     * with it, the paths you give are opened underneath, shallowest first.
+     *
+     * That's the one for a screen whose URL doesn't say where it belongs — the
+     * thread a notification opens — and for seeding a stack from code in general.
+     * Panels the new stack also holds stay as they are; ones it drops close,
+     * except panels with {@link Panel.unsaved} work, which stay, parked.
+     *
+     * A `data-panel=open` link does the same thing (without a `beneath`): it
+     * leaves the panel it sits in behind rather than stacking on it, which is
+     * what a link to somewhere else in the app wants — a search hit, a mention.
+     *
+     * @example
+     * ```ts
+     * shell.openPanelStack(`/thread/${id}`, [`/mailbox/${mailboxId}`]);
+     * ```
+     */
+    openPanelStack(path: string, beneath?: readonly string[]): Promise<boolean>;
+    /**
+     * Closes the current panel, or, given a `path`, whichever panel is open at
+     * it. Closing the current panel hands the focus to the panel on its left;
+     * closing any other panel takes just it away, leaving the columns around it
+     * exactly as they are, with their state. Either way it becomes a history
+     * entry, so the browser's back button brings the panel back.
+     *
+     * Resolves `false` if the panel didn't close: it holds {@link Panel.unsaved}
+     * work, `path` isn't open, it was the stack's only panel, or another
+     * navigation got there first.
+     */
+    closePanel(path?: string): Promise<boolean>;
+}
+/**
+ * The controller behind a routed shell. It implements {@link PanelStack} —
+ * the app-facing face, and the only part of it that is Staffa API — and on
+ * top of that draws the columns and the breadcrumbs for `main()`, which
+ * constructs it.
+ */
+export declare class PanelStackController implements PanelStack {
+    /**
+     * Kept out of Aberdeen's proxy wrapping: this is a class instance holding
+     * DOM nodes, timers and route handlers, and it rides inside every
+     * {@link Panel.stack}. Its reactivity doesn't need the wrapper — it comes
+     * from `$state` and the panels, which are proxies in their own right.
+     */
+    readonly [OPAQUE] = true;
     private compiled;
+    /** The `ancestors` table, compiled like the routes it is keyed by. */
+    private ancestors;
     private opts;
-    /** The live stack, shallow-to-deep. Closing panels are no longer part of it. */
-    private live;
-    private byId;
-    private nextId;
-    /** Drives rendering: panel id → its `order` (used only as the sort key). */
-    $ids: Record<string, number>;
-    /**
-     * The live stack's paths and its top panel, for reactive readers: the
-     * `document.title` watcher, `main()`'s Escape handling and `S.panels.stack`.
-     */
-    $state: {
-        paths: string[];
-        topId: number;
-    };
+    /**
+     * The live stack, oldest first (closing panels are no longer part of it),
+     * and which of its panels is current — the one reactive fact about the
+     * stack's *shape*. The getters, the crumbs and `document.title` subscribe
+     * to it simply by reading it; each commit publishes the next shape by
+     * assigning a fresh `live` array. The entries themselves are opaque (see
+     * {@link PanelEntry}), so the array carries their comings, goings and
+     * order — nothing deeper; a panel's own facts stay separately reactive on
+     * its `$panel`, which is what lets a panel rename itself without the
+     * stack redrawing.
+     *
+     * One rule makes this safe to touch from anywhere: **queries subscribe,
+     * commands peek**. The getters below are the queries. Every navigation
+     * entry point (`navigate`, `closePath`, `back`, …) wraps itself in
+     * `A.peek`, so an app calling one from inside a reactive scope (a
+     * redirect in a route handler, say) can't subscribe that scope to the
+     * very stack it is changing — and everything those commands call through
+     * to, `propose` and `commit` included, inherits the same guarantee and
+     * reads the stack plainly.
+     */
+    private $state;
+    /**
+     * The open panels again, keyed by path — the shape as the DOM consumes it.
+     * `drawColumns`' `onEach` mounts and unmounts panels by key, so a panel
+     * spliced out of the middle of the stack touches exactly one key, and the
+     * DOM of the retained columns — scroll positions, half-typed forms — is
+     * left alone. (Iterating `live` itself would key panels by array index,
+     * and a splice renumbers every index after it, redrawing them all.) A
+     * key's value is its entry, by reference, and is never reassigned, so a
+     * panel only ever redraws wholesale when its path closes.
+     */
+    private $open;
+    /** Feeds {@link PanelEntry.order}: one shared counter, so keys never tie. */
+    private nextOrder;
     private containerEl?;
     /** The shell's measurements, shared by everything drawn since they were taken. */
     private geom?;
@@ -186,42 +413,77 @@ export declare class PanelController {
     private lastBodyW;
     private layoutQueued;
     private timers;
+    /** The arrangement the navigation in flight is heading for; see {@link intended}. */
+    private intent;
+    /** The navigation the router hasn't settled yet, if any. */
+    private settling;
+    /** The route last seen by the observer, for stashing a left panel's query. */
+    private lastSeen;
+    /** The one navigation waiting behind it; see {@link issue}. */
+    private queued;
     constructor(opts: PanelStackOptions);
     /** Resolve a path to its route handler + params, falling back to `notFound`. */
     private resolve;
     private matches;
     /**
-     * The one derivation rule for origin-less navigation (§2.8): probe every
-     * prefix of the path against the route table; the matching prefixes become
-     * the stack. Prefixes without a route are simply skipped, so an app that
-     * doesn't want one screen stacked under another just doesn't route that
-     * prefix. The path itself is always the top panel, matched or not.
+     * The stack for origin-less navigation: a cold deep link, a nav item, a
+     * `route.go()` — anything arriving without a panel to build on and without a
+     * snapshot to restore.
+     *
+     * The app's {@link PanelStackOptions.ancestors} gets first say, since only it
+     * can know what belongs under a path that doesn't spell its own context out
+     * (a `/thread/[id]` reached from a notification). Failing that — or when it
+     * has no opinion — every prefix of the path is probed against the route table
+     * and the matching ones become the stack. Either way, a path with no route is
+     * skipped rather than opened as a "not found" column, so an app that doesn't
+     * want one screen stacked under another simply doesn't route it. The path
+     * itself always ends the derived stack, matched or not.
      */
-    deriveStack(path: string): string[];
-    /** The stack a route implies: its snapshot topped by its path, or — without a snapshot — derived. */
-    private targetFor;
-    /** The stack the current history entry asks for. Subscribes to path + snapshot. */
-    private computeTarget;
+    private deriveStack;
+    /**
+     * Ask the `ancestors` table what belongs beneath `path`. The first key that
+     * matches answers — with its own matched params, so it never has to take the
+     * path apart itself — and `undefined` from it means "no opinion", leaving the
+     * path to the prefix derivation just as an unlisted one is.
+     */
+    private askAncestors;
+    /** Every prefix of `path` that has a route, shallowest first. */
+    private prefixesOf;
+    /**
+     * The pinned panels among `stack`, in order, minus `omit` — the ones a
+     * navigation must carry along rather than close. Pin flags live on the
+     * panels themselves, so a path without a live panel can't be pinned.
+     */
+    private pinnedIn;
+    /** Whether the panel open at `path` (if any) holds unsaved work. */
+    private unsavedAt;
     /**
-     * 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 panel 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 panels that are closing.
+     * The arrangement a route implies: its snapshot around its path, or —
+     * without a snapshot — derived, with the new panel current at the end and
+     * any pinned panels carried along beneath it.
+     *
+     * The snapshot reads subscribe — they are the URL's, exactly what the
+     * route observer is for. The derivation is peeked instead: it reads the
+     * live stack for its pins, which is the very thing that observer rewrites,
+     * and subscribing to it would re-run the observer once per commit.
      */
-    private checkChange;
+    private targetFor;
+    /** The arrangement the current history entry asks for. Subscribes to path + snapshot. */
+    private computeTarget;
     private paths;
-    /** The live panels a target stack drops — by path, so a splice removes only its own column. */
-    private removedBy;
     /**
-     * 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.
+     * Adopt an arrangement proposed by the URL — after repairing it: panels
+     * 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 panel existed. Whatever the target drops, they stay, parked
+     * after the current panel 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.)
      */
     private propose;
     /**
-     * Apply a target stack: unmount what's gone, mount what's new, animate the
-     * difference.
+     * Apply a target arrangement: 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 panel present in both stacks stays mounted *even if its
@@ -252,69 +514,158 @@ export declare class PanelController {
      */
     private playExit;
     /**
-     * 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.panels.close()`. `route.back()` prefers the history entry where that
-     * panel 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 panels first, and the returned
-     * promise reports its verdict.
-     */
-    private goBackTo;
-    /** Close every panel above `index` (guarded). Resolves `false` when vetoed. */
-    closeDownTo(index: number): Promise<boolean>;
-    /** Guarded close of the top panel. */
-    closeTop(): Promise<boolean>;
-    /**
-     * Guarded close of the panel at `index`, top of the stack or not — what a
-     * page's own close affordances ({@link Page.close}, a box's ✕) come down to.
+     * 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 panel the
+     * first one is already taking away — so two quick Escapes would peel one panel.
+     */
+    private intended;
+    /** The history `state` describing `arr` — exactly what `targetFor` reads back. */
+    private stateFor;
+    /** The paths of the pinned panels — the pin list history entries persist. */
+    private pinnedPaths;
+    /**
+     * 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.
+     */
+    private issue;
+    private start;
+    /**
+     * Make the stack's `index`th panel current: the URL and the visible run move
+     * to it, while the panels 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 panel — comes down to.
+     */
+    private focusAt;
+    /**
+     * One step back along the stack — what Escape does (`main()` calls this;
+     * it is not {@link PanelStack} API). At the stack's end this closes the
+     * current panel; mid-stack — with panels parked to the right — or when the
+     * panel holds {@link Panel.unsaved} work, the panel stays open and the
+     * focus just moves to the panel on its left, parking the one it leaves.
+     * Resolves `false` at the stack's start, where there is no left to go.
+     */
+    back(): Promise<boolean>;
+    /**
+     * Close whichever panel is open at `path`, current or not — what
+     * {@link Panel.close}, {@link PanelStack.closePanel} and the crumb menu's
+     * Close come down to. `false` when that path isn't open, is the stack's
+     * only panel, or holds {@link Panel.unsaved} work — nothing may close an
+     * unsaved panel; the app clears the flag first, which is its explicit
+     * "this is now discardable".
+     *
+     * Closing the current panel at the stack'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 panel 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 panel" check
+     * would turn it into a focus move.
+     */
+    private closePath;
+    /**
+     * Navigate to `href`. `origin` is the path of the panel the link lives in, or
+     * `null` when it has none — a nav item, or a programmatic call, which builds
+     * the whole stack instead (see {@link deriveStack}). `replace` swaps the
+     * originating panel rather than stacking on top of it, and `beneath` says what
+     * the stack under the target is outright, for callers that know.
      *
-     * The top panel pops back to the snapshot beneath it. Any other panel is
-     * *spliced* out: its guard runs, the columns above it keep their place and
-     * state (the commit reconciles by path), and the URL doesn't change, since the
-     * top panel 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 panel we're already on" check would see a no-op.
-     */
-    closePanelAt(index: number): Promise<boolean>;
-    /** Guarded close of whichever panel `path` is open as. False when it isn't open. */
-    closeByPath(path: string): Promise<boolean>;
-    /** Guarded close of the panel whose `.s-panel` element this is. */
-    closePanelEl(el: HTMLElement): Promise<boolean>;
-    /**
-     * Navigate to `href`. `originIndex` is the depth of the panel the link lives
-     * in (−1 when it has none — a nav item or a programmatic call, which derives
-     * the whole stack instead). `replace` swaps the originating panel rather than
-     * stacking on top of it.
-     */
-    navigate(href: string, originIndex: number, replace?: boolean): void;
-    /** Programmatic push/replace, with the top panel as the implied origin. */
-    pushPath(path: string, replace: boolean): void;
+     * Resolves the way every {@link PanelStack} method does: `true` once the
+     * navigation lands, `false` when it doesn't (already there counts as
+     * landed).
+     */
+    private navigate;
+    /** Programmatic push/replace, with the current panel as the implied origin. */
+    private pushPath;
     /**
      * Link handling through `route.interceptLinks()`, whose handler hook hands us
      * the anchor so we can decide what the click *means*: the originating
-     * `.s-panel` (which decides what the click truncates), `data-panel=replace`,
-     * and return-to-an-open-panel 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.
+     * `.s-panel` (which decides what the click truncates), the `data-panel`
+     * attribute, and return-to-an-open-panel 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.
+     *
+     * `data-panel` names which of the three {@link PanelStack} navigations the
+     * click is: `push` (the default), `replace`, or `open`, which drops the
+     * originating panel so the target arrives with its own stack beneath it,
+     * exactly as a nav item's link does. An unrecognised value is a `push`.
      */
     private interceptLinks;
-    /** `"<page title> · <app title>"`, kept in sync with the top panel. */
+    get currentPanel(): Panel | undefined;
+    get panels(): readonly Panel[];
+    get currentPanelIndex(): number;
+    pushPanel(path: string): Promise<boolean>;
+    replacePanel(path: string): Promise<boolean>;
+    openPanelStack(path: string, beneath?: readonly string[]): Promise<boolean>;
+    closePanel(path?: string): Promise<boolean>;
+    /**
+     * The breadcrumb stack, drawn by `main()` into the top bar: every open
+     * panel, oldest first, the ones on screen right now in bold, pinned ones
+     * wearing their pin. Every crumb but the current panel's is a plain link to
+     * that panel, and a link to an open panel is a focus move (see `navigate`) —
+     * so clicking along the stack closes nothing, in either direction, and the
+     * panels right of the current one wait just past the viewport's edge.
+     * Right-click (or long-press) offers pinning, and closing just that one
+     * panel — the close that splices it out of the middle when it isn't last.
+     */
+    drawCrumbs(): void;
+    private drawCrumb;
+    /**
+     * Flip a panel's pin (see {@link Panel.pinned}). The flag lives on the panel;
+     * the current history entry's snapshot is rewritten too, so a reload keeps
+     * the pin — a same-panel state tweak, which the router applies unguarded.
+     */
+    private togglePin;
+    /**
+     * `"<panel title> · <app title>"`, kept in sync with the current panel — and
+     * prefixed `"• "` while *any* open panel holds unsaved work, the way editors
+     * mark a dirty document. Any panel, not just the current one: the risk of
+     * losing the work is tab-wide, so the mark on the tab is too.
+     */
     private watchTitle;
     /**
-     * Draw the panel viewport into the current element. Called by `main()`.
+     * While any open panel 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 panel 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.
+     */
+    private guardTabClose;
+    /**
+     * Draw the column 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.
+     * A column is the panel's own content, plus the one bit of chrome the shell
+     * places for it: its {@link Panel.actions}, in a strip on wide shells and in
+     * the top bar on narrow ones (see {@link drawActions}).
      */
-    drawStack(): void;
+    drawColumns(): void;
     private drawPanel;
+    /**
+     * The one bit of column chrome the shell draws: the panel'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 panel'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.
+     */
+    private drawActions;
     scheduleLayout(): void;
     /**
      * Measure the shell, and with it the width the window gives a panel of each
-     * layout. Measured on the *shell*, not on the panel region: the region's width
+     * 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.
@@ -330,7 +681,7 @@ export declare class PanelController {
      * would be a forced reflow each, in the middle of building their DOM.
      */
     private geometry;
-    /** How wide a panel of this layout is, right now; 0 while the shell can't be measured. */
+    /** How wide a panel asking for this is, right now; 0 while the shell can't be measured. */
     private roomFor;
     /**
      * Size and position every panel, and publish the width of the whole ensemble
@@ -344,49 +695,4 @@ export declare class PanelController {
     /** Let a `loading` panel's enter animation wait — but not indefinitely. */
     private holdEnter;
 }
-/**
- * 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 rather than opening it twice, and anything that would close a
- * panel asks its {@link Page.requestClose} first.
- *
- * @example
- * ```ts
- * S.button({ content: "New task", click: async () => {
- *   const task = await createTask();
- *   S.panels.push(`/tasks/${task.id}`);
- * }});
- * ```
- */
-export declare const panels: {
-    /** Opens `path` in a new panel on top of the top one. */
-    push(path: string): void;
-    /**
-     * Opens `path` in place of the top panel, which closes (asking its
-     * {@link Page.requestClose} first). The panels beneath it stay as they are.
-     */
-    replace(path: string): void;
-    /**
-     * Closes the top panel, or, given a `path`, whichever panel is open at it,
-     * asking {@link Page.requestClose} first. A panel that isn't on top is taken
-     * out on its own, leaving the columns to its right exactly as they are.
-     *
-     * Resolves `false` if the panel didn't close: `requestClose` said no, `path`
-     * isn't open, or another navigation got there first.
-     */
-    close(path?: string): Promise<boolean>;
-    /** The paths of the open panels, oldest first. Reactive: safe to read in a scope. */
-    readonly stack: readonly string[];
-};
-/**
- * Closes the panel `el` sits in, working out which one that is from the DOM.
- * That is what lets a close button work without being handed a `$page`, from
- * any column, whether or not it is on top. Used by `S.box`'s `close: true`.
- *
- * Outside a routed shell (or outside any panel, such as a box in a dialog) there is
- * nothing to close: it warns and resolves `false`.
- */
-export declare function closeContainingPanel(el: Element | null | undefined): Promise<boolean>;
 export {};