staffa 0.8.1 → 0.9.0

package/README.md

@@ -158,7 +158,9 @@ The first key that matches wins, and a segment a param refuses simply doesn't ma
 - A link to something that's already open goes back to it instead of opening it twice. The same path is never in the stack twice.
 - A link that isn't inside a panel (a nav item, or one in a dialog) has no panel to build on, so it replaces the stack as a whole: the page you asked for, with its ancestor pages opened beneath it (see [below](#ancestors)). Panels that the new stack also contains stay as they are, so clicking the nav item for the section you're already in won't reset it. Clicking a nav item and opening that same URL in a fresh tab therefore give you the same columns.
 
-From code, `S.panels.push(path)` opens a panel on top of the top one, `.replace(path)` opens one in place of the top one, and `.close(path?)` closes the top panel (or a named one). `S.panels.stack` is the list of open paths.
+From code, `S.panels.push(path)` opens a panel on top of the top one, `.replace(path)` opens one in place of the top one, `.open(path, beneath?)` opens a whole arrangement at once (the way a nav item does — see [below](#ancestors)), and `.close(path?)` closes the top panel (or a named one). `S.panels.stack` is the list of open paths.
+
+Navigating faster than the shell can settle is fine: closing travels through the browser's history, so it takes a moment to land, and anything asked for in the meantime waits for it rather than being dropped. Two quick Escapes (or back gestures) peel two panels, each aimed at the stack the one before it was heading for. A `requestClose` that says no clears what was queued behind it, so an Escape can't sail past the panel that just refused to close.
 
 **How much room a panel takes** is up to `$page.layout`. The content area is the page, at most 1280px wide, minus the nav sidebar:
 
@@ -210,6 +212,26 @@ Staffa itself contributes two things: the Escape key, which closes the top panel
 
 A URL that arrives without any of that (a shared link, a bookmark, a new tab) has nothing to restore, so Staffa builds the stack from the path: it walks the parent paths and opens each one you have a route for. With the routes above, `/projects/7/tasks/42` opens as three panels: the project list, project 7, and task 42. A parent path you have no route for is skipped, so if you don't want one screen appearing under another, just don't give it a route.
 
+That only works for URLs that spell their own context out. A flat one — `/thread/[id]`, where a push notification lands — has no parent path to walk, so it would open as a lone column with nothing beneath it and nothing for Escape to do. `ancestors` is where you say what belongs under it. It's keyed by the same path templates as `routes`, so each entry gets that key's params, matched and typed:
+
+```ts
+S.main({
+  routes: {
+    "/mailbox/[id]": drawMailbox,
+    "/thread/[id=integer]": drawThread,
+  },
+  ancestors: {
+    "/thread/[id=integer]": ({ id }) => [`/mailbox/${mailboxOf(id)}`],   // id is a number
+  },
+});
+```
+
+Return the paths shallowest first, or nothing to leave that path to the parent-path walk — which is also what a route you don't list gets, so you only name the ones whose URL doesn't say where they belong. It's asked for every navigation that has no panel to build on, so a nav item and a fresh tab still agree.
+
+It has to answer without drawing anything, which is why it lives here rather than on `$page`: the panels being replaced are asked their `requestClose` *before* the navigation is applied, and that is before any route handler could have run.
+
+From code, `S.panels.open(path, beneath?)` opens the same kind of arrangement, either asking `ancestors` for the stack or taking the one you hand it.
+
 Search params and the `#hash` belong to the top panel only. Anything a panel deeper in the stack needs in order to redraw itself has to live in its path.
 
 **A few more things.**
@@ -271,7 +293,7 @@ Components share naming conventions for options: `attrs` (outermost element), `c
 
 ### Layout & containers
 
-- **`S.main(opts)`**: app shell, a sticky header with `icon`, `title`, `subtitle`, `menu`; scrollable content area; footer. Set `maxWidth` to center the content. Give it a `nav` for a sidebar that collapses to a hamburger below 640 px — where the nav becomes a full page sliding in from the left, handing over to the chosen screen with a matching slide in from the right. Its `items` may be a reactive array; adding or removing one redraws just the sidebar, never the content beside it. Instead of a single `content` slot it can take a `routes` table — see [Panel-stack navigation](#panel-stack-navigation).
+- **`S.main(opts)`**: app shell, a sticky header with `icon`, `title`, `subtitle`, `menu`; scrollable content area; footer. Set `maxWidth` to center the content. Give it a `nav` for a sidebar that collapses to a hamburger below 640 px — where the nav becomes a full page sliding in from the left, handing over to the chosen screen with a matching slide in from the right. Its `items` may be a reactive array; adding or removing one redraws just the sidebar, never the content beside it. A navigation dismisses the collapsed nav by itself, links in your own custom rows included; `S.closeNav()` does it for the rows that *don't* navigate. Instead of a single `content` slot it can take a `routes` table — see [Panel-stack navigation](#panel-stack-navigation).
 - **`S.box(opts | content)`**: surface with optional `header`/`footer` and padded body. Pass a function for shorthand `{ content }`. `close: true` adds a ✕ that closes the panel the box is in (see [Panel-stack navigation](#panel-stack-navigation)); `close: fn` runs your own dismissal.
 - **`S.tabs(opts)`**: tablist with live panels and keyboard navigation. More tabs than fit make the strip scroll, with a ‹ / › button appearing at whichever end still has something to reach — so it's not just a swipe target. Selecting a tab any other way (the arrow keys, a `bind` written from elsewhere) scrolls it into view.
 - **`S.form(opts | content)`**: form aligning fields in a column or responsive grid, with an `actions` bar. Prevents the default page reload.
@@ -313,7 +335,8 @@ Options: `size`, `color` (defaults to `currentColor`), `strokeWidth`, `cap`, `jo
 
 ### Other
 
-- **`S.menuButton(opts)` / `S.addContextMenu(opts)` / `S.showFloatingMenu(opts)`**: dropdown menus from a button, right-click/long-press context menus, and the underlying floating menu primitive — with keyboard navigation.
+- **`S.menuButton(opts)` / `S.addContextMenu(opts)` / `S.showFloatingMenu(opts)`**: dropdown menus from a button, right-click/long-press context menus, and the underlying floating menu primitive — with keyboard navigation. A menu closes itself when the page navigates.
+- **`S.closeNav()`**: dismisses `S.main`'s navigation when it's showing as an overlay (the full page on a phone, the dropdown on a wider screen). For custom nav rows that act without navigating.
 - **`S.toast(opts)`**: transient notification at the bottom of the viewport.
 - **`S.addTooltip(el, opts)`**: tooltip on hover, attached to an existing element.
 
@@ -405,23 +428,8 @@ mkdir -p .claude/skills
 ln -s ../../node_modules/staffa/skill .claude/skills/staffa
 ```
 
-## Breaking changes
-
-- **0.7** — the surface model was reduced to two families: **neutral** (`.neutral`) and **accent** (`.primary`/`.danger`/`.success`/`.warning`/`.link`). Apps that only use the high-level `S.*` components need no changes. Code that uses surface classes or tokens directly must update:
-  - **Surface levels gone.** Replace `.base`/`.panel`/`.raised`/`.neutral`/`.nest` with the single `.neutral` class.
-  - **`.secondary` and `.gradient` gone.** Drop any `s-secondary` colour override; there's no `s-secondary` anymore. The default button is now `.primary`.
-  - **Tokens renamed.** `--s-fg`→`--s-text`, `--s-fg-muted`→`--s-muted`, `--s-border`→`--s-faint`. Removed: `--s-fg-faint`, `--s-border-strong`, `--s-ink`, `--s-on-accent`, `--s-page`/`--s-panel`/`--s-raised`, `--s-neutral`, `--s-tint`, `--s-glow`, `--s-shadow`, `--s-gradient-surface`. A custom surface now sets `--s-bg`/`--s-text` (was the `--s-a`/`--s-b` anchors).
-  - **Borders/shadows moved onto surfaces.** Components no longer draw their own border/shadow. If you relied on `S.box`/`S.dialog`/etc. elevation, it now comes from the surface; pass `.no-shadow` to drop it, or `.shadow`/`.extra-shadow` to add it on any surface.
-
-- **0.6**: None.
+## Changelog
 
-- **0.5**
-  - Surfaces (`.s-s`) now apply `border-radius` and — for `.tonal` and `.outlined` variants — `border` automatically. Custom surfaces or components that previously set these manually may see doubled or conflicting styles; remove the manual declarations.
-  - `border:0` is now applied to `.s-btn` by default (overriding the browser's 2px button border). Custom button-like components built on `.s-btn` that relied on the browser default border should add an explicit border.
+What changed in each release, and what to do about the breaking ones, is in [CHANGELOG.md](CHANGELOG.md).
 
-- **0.4**
-  - There is no default export anymore: replace `import S from "staffa"` with `import * as S from "staffa"`.
-  - `S.button` no longer has a `text` option: use `content` instead (it accepts a string or a draw function).
-  - The `Content` type is gone: use `Slot` instead. The `Styling` type alias is now exported as `Attributes`.
-  - `S.buttonChooser` uses `undefined` instead of `null` for "nothing selected" (in `bind` and with `allowDeselect`).
-  
+*Hint:* the recommended update strategy for a library this young is: don't. Pin it, and read the changelog before you move.

package/dist/components/main.d.ts

@@ -1,6 +1,6 @@
 import { type Slot, type Attributes } from "../core.js";
 import { type MenuOptions } from "./menu.js";
-import { type RouteHandler, type RouteTable, type Routes } from "./panels.js";
+import { type AncestorTable, type RouteHandler, type RouteTable, type Routes } from "./panels.js";
 /** Options for {@link main}. */
 export interface MainOptions<R = Routes> {
     /** Aberdeen attr/style string applied to the outermost shell element. */
@@ -80,6 +80,45 @@ export interface MainOptions<R = Routes> {
      * `$page.path`.
      */
     notFound?: RouteHandler<{}>;
+    /**
+     * What to open **beneath** a path that arrives cold — a shared link, a
+     * bookmark, a push notification, a nav item — with no stack of its own to
+     * restore. Keyed by path template exactly like {@link MainOptions.routes}, so
+     * each entry gets that key's params, matched and typed, rather than taking
+     * the path apart a second time.
+     *
+     * Without this, the stack is derived from the path: every prefix that has a
+     * route becomes a column, so `/projects/7/tasks/42` opens three deep. That
+     * only works for URLs that spell their own context out. A flat one —
+     * `/thread/[id]`, where a notification lands — has no prefix to walk, so it
+     * opens as a single column with nothing under it and nothing to close back
+     * to. This is where you say what that context is:
+     *
+     * ```ts
+     * S.main({
+     *   routes: {
+     *     "/mailbox/[id]": drawMailbox,
+     *     "/thread/[id=integer]": drawThread,
+     *   },
+     *   ancestors: {
+     *     "/thread/[id=integer]": ({ id }) => [`/mailbox/${mailboxOf(id)}`],  // id: number
+     *   },
+     * });
+     * ```
+     *
+     * Return the paths shallowest first; the path itself goes on top. Return
+     * nothing to leave a path to the prefix derivation, which is also what an
+     * unlisted one gets — so you only list the routes whose URL doesn't say where
+     * it belongs. Paths you have no route for are skipped, as they are there.
+     *
+     * This is asked for every origin-less navigation, so a nav item and a fresh
+     * tab still land on the same columns; a link *inside* a panel builds on that
+     * panel instead and never asks. It has to answer without drawing anything,
+     * since the panels being replaced are asked their {@link Page.requestClose}
+     * before the navigation is applied — before any handler could run. From code,
+     * {@link panels}.`open()` takes the same list directly.
+     */
+    ancestors?: AncestorTable<NoInfer<R>>;
     /**
      * Set `false` to show only the top panel, however wide the screen (the nav
      * sidebar still sits beside it). Everything else behaves the same: the URL,
@@ -173,3 +212,24 @@ export interface MainOptions<R = Routes> {
  * ```
  */
 export declare function main<R extends RouteTable<R>>(opts?: MainOptions<R>): void;
+/**
+ * Close the navigation, if it's showing as an overlay: the full page it becomes
+ * on a narrow shell, or the dropdown its button opens on a wider one. A sidebar
+ * isn't an overlay and has nothing to dismiss, so there it does nothing.
+ *
+ * A navigation closes the nav by itself, links in your own custom rows included,
+ * so this is for the items that *don't* navigate — one that opens a dialog, or
+ * flips a setting, and should still get the nav out of the way.
+ *
+ * @example
+ * ```ts
+ * S.main({
+ *   nav: { items: [
+ *     { label: "Inbox", href: "/inbox" },
+ *     () => S.button({ content: "New message", click: () => { S.closeNav(); compose(); } }),
+ *   ]},
+ *   routes: { ... },
+ * });
+ * ```
+ */
+export declare function closeNav(): void;

package/dist/components/main.js

@@ -1,4 +1,5 @@
 import A from "aberdeen";
+import { current as currentRoute } from "aberdeen/route";
 import { drawSlot, focusFirst, NARROW_PX } from "../core.js";
 import { drawMenu, showFloatingMenu, isFloatingMenuOpen, closeFloatingMenu, menuGlyph, closeGlyph } from "./menu.js";
 import { button } from "./button.js";
@@ -190,7 +191,13 @@ export function main(opts = {}) {
     // one rather than spread from `opts`: a spread reads every key, which on a
     // proxied options object subscribes this scope to all of them.
     const ctl = routes
-        ? new PanelController({ routes, notFound: opts.notFound, stacking: opts.stacking, title: opts.title })
+        ? new PanelController({
+            routes,
+            notFound: opts.notFound,
+            ancestors: opts.ancestors,
+            stacking: opts.stacking,
+            title: opts.title,
+        })
         : null;
     // Routed mode caps the shell to the ensemble width the layout engine publishes,
     // rather than to `maxWidth`.
@@ -342,6 +349,35 @@ export function main(opts = {}) {
         A.clean(() => document.removeEventListener("keydown", onKey));
     }
 }
+/**
+ * Dismisses whichever collapsed nav is showing, if either is: at most one shell
+ * has its nav up as an overlay at a time, so this needs nothing passed in. Set
+ * by the two things that open one (see {@link closeNav}).
+ */
+let openNav = null;
+/**
+ * Close the navigation, if it's showing as an overlay: the full page it becomes
+ * on a narrow shell, or the dropdown its button opens on a wider one. A sidebar
+ * isn't an overlay and has nothing to dismiss, so there it does nothing.
+ *
+ * A navigation closes the nav by itself, links in your own custom rows included,
+ * so this is for the items that *don't* navigate — one that opens a dialog, or
+ * flips a setting, and should still get the nav out of the way.
+ *
+ * @example
+ * ```ts
+ * S.main({
+ *   nav: { items: [
+ *     { label: "Inbox", href: "/inbox" },
+ *     () => S.button({ content: "New message", click: () => { S.closeNav(); compose(); } }),
+ *   ]},
+ *   routes: { ... },
+ * });
+ * ```
+ */
+export function closeNav() {
+    openNav?.();
+}
 /**
  * The hamburger in the top bar, shown whenever the sidebar isn't. What it opens
  * depends on how much room the shell has: a dropdown when there's plenty, and —
@@ -352,6 +388,11 @@ function drawNavTrigger(nav, $nav) {
     let myEl = null;
     A.clean(() => { if (myEl)
         closeFloatingMenu(myEl); });
+    // The dropdown form of the same overlay, for `closeNav()` (see `openNav`).
+    // The floating menu bows out on a navigation by itself, so this is only ever
+    // asked to dismiss one that isn't going anywhere.
+    const dismiss = () => { if (myEl)
+        closeFloatingMenu(myEl); };
     button({
         // The glyph doubles as the state: ☰ to open the page, ✕ to dismiss it. Its
         // own scope, so toggling doesn't rebuild (and re-focus) the button.
@@ -373,8 +414,10 @@ function drawNavTrigger(nav, $nav) {
             // the menu's own outside-click handler, so toggle it here.
             if (isFloatingMenuOpen(myEl))
                 closeFloatingMenu(myEl);
-            else
+            else {
+                openNav = dismiss;
                 showFloatingMenu({ items: nav.items, anchor: myEl, dropdownAttrs: nav.dropdownAttrs });
+            }
         },
     });
 }
@@ -388,7 +431,19 @@ function drawNavPage(nav, attrs, $nav) {
     // Whether this close is a *navigation* — the only kind that hands over to an
     // incoming screen. Dismissing the page just uncovers the content again.
     let navigated = false;
-    const pageEl = A("nav.s-nav-page.s-s.neutral aria-label=Navigation create=s-nav-page-off destroy=s-nav-page-off", attrs, () => drawMenu(nav.items, () => { navigated = true; $nav.open = false; }));
+    const dismiss = () => { navigated = true; $nav.open = false; };
+    const pageEl = A("nav.s-nav-page.s-s.neutral aria-label=Navigation create=s-nav-page-off destroy=s-nav-page-off", attrs, () => drawMenu(nav.items, dismiss));
+    // This is the shell's one nav overlay, so `closeNav()` knows where to aim.
+    openNav = dismiss;
+    A.clean(() => { if (openNav === dismiss)
+        openNav = null; });
+    // Whatever the page navigated to, it hands over to: the items do that
+    // themselves (`dismiss` above), but custom slot content — a link in a row the
+    // shell knows nothing about — doesn't, and neither does a navigation from
+    // anywhere else. Its own scope, so it can't redraw the page it closes.
+    const openedAt = A.peek(currentRoute, "path");
+    A(() => { if (currentRoute.path !== openedAt)
+        dismiss(); });
     const shell = pageEl.closest(".s-main");
     const behind = pageEl.parentElement?.querySelector(":scope > .s-body-inner");
     // Content mode's incoming half of the hand-off. In routed mode there is no

package/dist/components/menu.js

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { matchCurrent } from "aberdeen/route";
+import { matchCurrent, current as currentRoute } from "aberdeen/route";
 import { drawSlot, mountPortal, focusFirst } from "../core.js";
 import { mk } from "../icons-helpers.js";
 import { button } from "./button.js";
@@ -181,6 +181,13 @@ mountPortal(() => {
             closeFloating();
         }
     };
+    // A menu is a transient overlay: whatever navigation it started, it hands over
+    // to. Items do that themselves (`closeFloating` is `drawMenu`'s `onActivate`
+    // above), but custom slot content — a link in a row the menu knows nothing
+    // about — doesn't, and neither does a navigation from anywhere else.
+    const openedAt = A.peek(currentRoute, "path");
+    A(() => { if (currentRoute.path !== openedAt)
+        closeFloating(); });
     document.addEventListener("click", onClick, true);
     document.addEventListener("keydown", onKey, true);
     A.clean(() => {

package/dist/components/panels.d.ts

@@ -55,6 +55,21 @@ export type Routes = Record<string, RouteHandler>;
 export type RouteTable<R> = {
     [K in keyof R & string]: (page: Page<Prettify<PathParams<K>>>) => void;
 };
+/**
+ * What belongs beneath a path that arrives cold, worked out from the params of
+ * the path itself. Return the paths shallowest first, or nothing to leave this
+ * one to the parent-path derivation.
+ */
+export type AncestorsHandler<P = any> = (params: P, path: string) => readonly string[] | undefined | void;
+/**
+ * A table of {@link AncestorsHandler}s keyed by path template, the same way
+ * `routes` is — so each one's `params` are matched and typed from its own key
+ * rather than parsed out of the path a second time. The keys are checked
+ * against the route table, so a stale one is a type error.
+ */
+export type AncestorTable<R> = {
+    [K in keyof R & string]?: (params: Prettify<PathParams<K>>, path: string) => readonly string[] | undefined | void;
+};
 /**
  * What a route handler gets: the params from its route, plus everything the
  * shell needs to know about the panel it is drawing. It's an Aberdeen proxy, so
@@ -157,6 +172,8 @@ export interface Page<P = Record<string, string | number | string[]>> {
 export interface PanelStackOptions {
     routes: Routes;
     notFound?: RouteHandler<{}>;
+    /** What to open beneath a path that arrives cold. See {@link MainOptions.ancestors}. */
+    ancestors?: Record<string, AncestorsHandler | undefined>;
     /** Set `false` to show only the top panel, however much room there is. */
     stacking?: boolean;
     /** The shell's own title, used as the suffix of `document.title`. */
@@ -164,6 +181,8 @@ export interface PanelStackOptions {
 }
 export declare class PanelController {
     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;
@@ -186,18 +205,40 @@ export declare class PanelController {
     private lastBodyW;
     private layoutQueued;
     private timers;
+    /** The stack 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 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 is always the top panel, matched or not.
      */
     deriveStack(path: string): string[];
+    /**
+     * 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 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. */
@@ -251,6 +292,29 @@ export declare class PanelController {
      * coming at all (transitions off, or an element that never got placed).
      */
     private playExit;
+    /**
+     * The stack navigation works from: the one we're on the way to while a change
+     * is still settling, and the one on screen otherwise.
+     *
+     * Settling takes a moment more often than it looks: an async
+     * {@link Page.requestClose}, and every `route.back()`, which travels through
+     * the browser's history and lands on a `popstate`. Working from the committed
+     * stack in that window would make a second Escape ask for the panel the first
+     * one is already taking away — so two quick Escapes would peel one panel.
+     */
+    private intended;
+    /**
+     * Put a navigation to the router, or — while one is still settling — behind
+     * the one that is. Only the newest waits: each was worked out against
+     * {@link intended}, so the newest is the one that means what the user last
+     * asked for, and the one it displaces resolves `false`.
+     *
+     * A refusal empties the queue instead of running it. A veto is a "no, keep
+     * this open", and the Escape queued behind it was aimed a panel deeper — with
+     * the veto standing, running it would close the very panel that just said no.
+     */
+    private issue;
+    private start;
     /**
      * 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
@@ -266,8 +330,9 @@ export declare class PanelController {
     /** 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.
+     * Guarded close of whichever panel is open at `path`, top of the stack or not
+     * — what a page's own close affordances ({@link Page.close}, a box's ✕) come
+     * down to. `false` when that path isn't open.
      *
      * The top panel pops back to the snapshot beneath it. Any other panel is
      * *spliced* out: its guard runs, the columns above it keep their place and
@@ -277,20 +342,21 @@ export declare class PanelController {
      * why it goes through `route.go` here rather than through `navigate()`, whose
      * "link to the panel we're already on" check would see a no-op.
      */
-    closePanelAt(index: number): Promise<boolean>;
-    /** Guarded close of whichever panel `path` is open as. False when it isn't open. */
-    closeByPath(path: string): Promise<boolean>;
+    closePath(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 to `href`. `origin` is the path of the panel the link lives in, or
+     * `null` when it has none — a nav item, or a programmatic call, which builds
+     * the whole stack instead (see {@link deriveStack}). `replace` swaps the
+     * originating panel rather than stacking on top of it, and `beneath` says what
+     * the stack under the target is outright, for callers that know.
      */
-    navigate(href: string, originIndex: number, replace?: boolean): void;
+    navigate(href: string, origin: string | null, replace?: boolean, beneath?: readonly string[]): void;
     /** Programmatic push/replace, with the top panel as the implied origin. */
     pushPath(path: string, replace: boolean): void;
+    /** Programmatic open-as-a-whole-stack: `beneath` as given, or derived. */
+    openPath(path: string, beneath?: readonly string[]): void;
     /**
      * Link handling through `route.interceptLinks()`, whose handler hook hands us
      * the anchor so we can decide what the click *means*: the originating
@@ -368,6 +434,23 @@ export declare const panels: {
      * {@link Page.requestClose} first). The panels beneath it stay as they are.
      */
     replace(path: string): void;
+    /**
+     * Opens `path` as a whole arrangement rather than on top of what's there: the
+     * same thing a nav item or a fresh tab does. Without `beneath`, the stack under
+     * it is worked out the way a cold link's is (see `S.main()`'s `ancestors`);
+     * with it, the paths you give are opened underneath, shallowest first.
+     *
+     * That's the one for a screen whose URL doesn't say where it belongs — the
+     * thread a notification opens — and for seeding a stack from code in general.
+     * Panels the new arrangement also holds stay as they are, and any it drops are
+     * asked their {@link Page.requestClose} first.
+     *
+     * @example
+     * ```ts
+     * S.panels.open(`/thread/${id}`, [`/mailbox/${mailboxId}`]);
+     * ```
+     */
+    open(path: string, beneath?: readonly string[]): void;
     /**
      * 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