staffa 0.11.0 → 0.12.1

package/README.md

@@ -190,7 +190,7 @@ Navigating faster than the shell can settle is fine: closing travels through the
 
 Below the width two columns need, everything takes the whole content area whatever it asked for. Those numbers assume a nav sidebar of around 170px; without one, add that back. Nothing fits beside a `"full"` on a standard 1280px page, but on a wide enough window a `"half"` still can, and the page grows past 1280px to hold both.
 
-A column'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, and never reflows what someone was reading. A lone `"half"` leaves its other half empty, and that is exactly where the next one lands. When more columns fit than the standard 1280px page holds (three halves, say), the page itself grows, staying centred, to hold them.
+A column'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, and never reflows what someone was reading. A lone `"half"` leaves its other half empty, and that is exactly where the next one lands. When more columns fit than the standard 1280px page holds (three halves, say), the page itself grows, staying centred, to hold them — though the top bar and footer keep to the standard width, so the chrome holds still while the columns come and go.
 
 Columns tile that area, separated by a hairline and no gutter — a column brings its own padding, so their contents stay comfortably apart regardless.
 
@@ -293,6 +293,7 @@ Search params and the `#hash` belong to the current panel only. Anything another
 
 - `columns: "single"` shows only the current panel, however wide the screen — the phone experience at every size. Only the display changes: the URL, the back button, unsaved panels and the panels' own close buttons all behave the same.
 - `linkNavigation` sets what a link *without* a `data-panel` attribute does: `"push"` (the default), `"replace"`, or `"open"`. With `"open"` every click replaces the content as a whole — which, with flat routes, is the conventional sidebar-and-content app: one pane, swapped on every click, the crumb line simply naming it.
+- Both are live: pass a proxied options object (or make the field a getter) and a change is adopted in place, every open panel keeping its state.
 - Only one routed `S.main()` can be mounted at a time; a second one throws — the URL is global, so two of them would fight over it. Nothing else is global: the stack belongs to its shell, and each handler gets its own `$panel`, since several panels are alive at once.
 - Navigating with `aberdeen/route`'s own `go()` works — an unsaved panel survives it too — but, like a link from outside a panel, it builds the whole stack from the path. So prefer the stack's own methods. A navigation guard your app registered with `route.setGuard` (an auth redirect, say) keeps working untouched: Staffa registers none of its own.
 - Deep links need your static server to serve the app for unknown paths (the usual SPA fallback). For `http-server` that's `-P`, as in the demo command below.
@@ -349,7 +350,7 @@ Components share naming conventions for options: `attrs` (outermost element), `c
 
 ### Layout & containers
 
-- **`S.main(opts)`**: app shell, a sticky header with `logo`, `title`, `subtitle`, `menu` — plus, in routed mode, the breadcrumbs of the open panels; 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. An item with `items` of its own becomes a collapsible submenu: only the branch holding the current page stays unfolded, and clicking a branch selects its first leaf (expanding a branch doesn't dismiss the phone's full-page nav — only picking a leaf does). A sidebar taller than the window scrolls, and follows the highlighted item: navigating to a page whose item sits past the fold scrolls it back into view. 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.main(opts)`**: app shell, a sticky header with `logo`, `title`, `subtitle`, `menu` — plus, in routed mode, the breadcrumbs of the open panels; 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. An item with `items` of its own becomes a collapsible submenu: only the branch holding the current page stays unfolded, and clicking a branch selects its first leaf (expanding a branch doesn't dismiss the phone's full-page nav — only picking a leaf does). A page the menu holds nowhere leaves every fold as it was. An item can also `match` pages beyond its own `href` — a path prefix, or a `(path) => boolean` — claiming the detail screens that have no row of their own: it is then highlighted, and the branches above it stay unfolded, cold deep links included. A sidebar taller than the window scrolls, and follows the highlighted item: navigating to a page whose item sits past the fold scrolls it back into view. 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: fn` adds a ✕ that runs your dismissal — in the header row, or floating over the body when there is no header. (It is plain furniture: a routed screen gets its own way out from the shell, see [Panel-declared chrome](#chrome).)
 - **`S.tabs(opts)`**: tablist with live tab panels and keyboard navigation. More tabs than fit make the strip scroll (see `S.scrollStrip`); selecting a tab any other way (the arrow keys, a `bind` written from elsewhere) scrolls it into view.
 - **`S.scrollStrip(opts)`**: a horizontal row that scrolls once its content outgrows it, with a ‹ / › button appearing over whichever end still has something to reach — so it isn't just a swipe target. Its own scrollbar is hidden. `S.tabs` and the routed shell's breadcrumbs are built on it; reach for it for any row of chrome that can outgrow its space. `S.revealInStrip(el)` scrolls one of its children into view.

package/dist/components/main.d.ts

@@ -183,6 +183,10 @@ export interface MainOptions<R = Routes> {
      * — the phone experience at every size (the nav sidebar still sits beside
      * it). Only the display differs: the stack, the breadcrumbs, the URL,
      * Escape and the back button behave identically in both. Routed mode only.
+     *
+     * Live: pass a proxied options object (or make this field a getter) and a
+     * change is adopted in place — one layout pass, every panel keeping its
+     * state.
      */
     columns?: "auto" | "single";
     /**
@@ -193,6 +197,9 @@ export interface MainOptions<R = Routes> {
      * every click replaces the content as a whole — which, with flat routes,
      * is the conventional sidebar-and-content app: one pane, swapped on every
      * click, the crumb line simply naming it. Routed mode only.
+     *
+     * Live, like {@link MainOptions.columns}: change it and the next click
+     * uses the new default.
      */
     linkNavigation?: "push" | "replace" | "open";
     /** Footer content, pinned below the scroll area. */

package/dist/components/main.js

@@ -1,14 +1,14 @@
 import A from "aberdeen";
-import { current as currentRoute, matchCurrent } from "aberdeen/route";
+import { current as currentRoute } from "aberdeen/route";
 import { drawSlot, focusFirst, NARROW_PX } from "../core.js";
-import { drawMenu, isFloatingMenuOpen, consumeBranchNav } from "./menu.js";
+import { drawMenu, isFloatingMenuOpen, consumeBranchNav, anyCurrent } from "./menu.js";
 // The shell's own chrome glyphs, from the same Lucide set an app draws with —
 // so a nav trigger sits beside app icons as an equal. Named imports, so a
 // bundler keeps these two and tree-shakes the other ~1950 away.
 import { menu as menuIcon, x as closeIcon } from "../icons.js";
 import { iconButton } from "./button.js";
 import { isDialogOpen } from "./dialog.js";
-import { PanelStackController } from "./panels.js";
+import { PanelStackController, SHELL_PX } from "./panels.js";
 A.insertGlobalCss({
     ".s-main": {
         // container-type so @container queries below can respond to shell width.
@@ -26,8 +26,10 @@ A.insertGlobalCss({
         // The bar reads `[leading] [title] …spacer… [trailing]`. The spacer is the
         // trailing slot's own growth: it takes the free space and right-aligns
         // itself in it, which is what lets a search box live there. When the two
-        // compete, the title truncates first — but only down to a floor, past
-        // which the trailing slot shrinks instead: a wide search box must not
+        // compete, the titles give way first: the trailing slot's near-zero
+        // shrink factor keeps a row of actions at its natural width while the
+        // crumbs absorb the squeeze — but only down to the titles' floor, past
+        // which the trailing slot shrinks after all: a wide search box must not
         // starve the titles to nothing (the crumb strip's overlay buttons would
         // escape their zero-width strip, over the ☰ beside it).
         "> header > .s-bar, > footer > .s-bar": "display:flex align-items:center width:100% margin-inline:auto gap:$3 padding: $2 $3;",
@@ -48,13 +50,16 @@ A.insertGlobalCss({
         // which their classes then provide. (`filter:none` keeps the global
         // `a:hover` brighten off the gradient text.)
         "> header a.s-logo, > header a.s-title": "text-decoration:none filter:none cursor:pointer",
-        "> header .s-menu": "display:flex align-items:center justify-content:flex-end gap:$2 flex: 1 1 auto; min-width:0",
+        "> header .s-menu": "display:flex align-items:center justify-content:flex-end gap:$2 flex: 1 0.1 auto; min-width:0",
         // Body always wraps <main> (with or without a sidebar) so max-width centering
         // and scrollbar alignment work identically in both cases.
         // .s-body centres .s-body-inner; .s-body-inner caps the content to maxWidth.
         // It's also the positioning + clipping context for the narrow-screen nav panel,
-        // which slides in and out across its left edge.
-        ".s-body": "flex:1 overflow:hidden display:flex flex-direction:row min-height:0 justify-content:center position:relative",
+        // which slides in and out across its left edge. `overflow:clip` rather than
+        // `hidden` for the same reason as `.s-panels`: a hidden box can still be
+        // scrolled (find-in-page, an anchor, an extension), and a stray scroll here
+        // would shove the whole row — sidebar and columns — out of place for good.
+        ".s-body": "flex:1 overflow:clip display:flex flex-direction:row min-height:0 justify-content:center position:relative",
         ".s-body-inner": "flex:1 min-width:0 display:flex flex-direction:row min-height:0",
         // Put the sidebar on the right (content fills the left) for right-hand navs.
         "&.s-nav-right .s-body-inner": "flex-direction:row-reverse",
@@ -85,20 +90,24 @@ A.insertGlobalCss({
         // Routed mode takes its width from the stack instead of from
         // `maxWidth`: the layout engine publishes the ensemble width (sidebar +
         // separator + content area) as --s-shell-w — the standard 1280px page
-        // normally, the window's edges while a "screen" page is up — and the body
-        // row and the bars cap themselves to it. So the chrome lines up with the
-        // columns and the lot stays centred in the shell.
-        "&.s-routed > .s-body > .s-body-inner": "max-width: var(--s-shell-w, 100%);",
-        "&.s-routed > header > .s-bar": "max-width: var(--s-shell-w, 100%);",
-        "&.s-routed > footer > .s-bar": "max-width: var(--s-shell-w, 100%);",
-        // Changing the custom property animates the max-widths consuming it, with no
-        // JS in the loop: the chrome recentres in step with the panel whose arrival
-        // or departure moved it, over the same --s-panel-ms (see panels.ts). During
-        // a window resize (and the very first pass) the layout engine raises
-        // `.s-shell-snap` so the new width is adopted instantly instead of chasing
-        // the window through a transition.
-        "&.s-routed > .s-body > .s-body-inner, &.s-routed > header > .s-bar, &.s-routed > footer > .s-bar": "transition: max-width var(--s-panel-ms) ease;",
-        "&.s-routed.s-shell-snap > .s-body > .s-body-inner, &.s-routed.s-shell-snap > header > .s-bar, &.s-routed.s-shell-snap > footer > .s-bar": "transition:none",
+        // normally, wider while the columns outgrow it (a "screen" page, or
+        // extra columns fitting a wide window) — and the body row caps itself
+        // to it, staying centred around the columns. Changing the custom
+        // property animates the max-width consuming it, with no JS in the loop:
+        // the body recentres in step with the panel whose arrival or departure
+        // moved it, over the same --s-panel-ms (see panels.ts). During a window
+        // resize (and the very first pass) the layout engine raises
+        // `.s-shell-snap` so the new width is adopted instantly instead of
+        // chasing the window through a transition.
+        "&.s-routed > .s-body > .s-body-inner": "max-width: var(--s-shell-w, 100%); transition: max-width var(--s-panel-ms) ease;",
+        "&.s-routed.s-shell-snap > .s-body > .s-body-inner": "transition:none",
+        // The bars don't follow the ensemble past the standard page: a header
+        // stretching to the window's edges and back with every "screen" panel
+        // reads as the whole app flexing, so the chrome holds still and only
+        // the columns grow. (Below the standard width the ensemble is simply
+        // the window, which only a resize changes — so the bars never animate,
+        // and take no part in the transition above.)
+        [`&.s-routed > header > .s-bar, &.s-routed > footer > .s-bar`]: `max-width:${SHELL_PX}px`,
     },
     // Sidebar nav panel. Items reuse the shared `.s-menu-item` /
     // `.s-menu-sep` styles from menu.ts, so the sidebar and the floating
@@ -124,10 +133,12 @@ A.insertGlobalCss({
         // body starts below the bar), but the bar should still win if they ever do.
         "position:absolute inset:0 z-index:5 display:flex flex-direction:column " +
             "overflow-y:auto overscroll-behavior:contain border:0 r:0 padding:$2 gap:$1 " +
-            "transition: transform var(--s-panel-ms) ease;",
+            "transition: transform var(--s-panel-ms) ease, visibility var(--s-panel-ms);",
         // Parked one screen to the left: the state the `create=`/`destroy=` hooks
-        // transition out of and back into.
-        "&.s-nav-page-off": "transform:translateX(-100%) pointer-events:none",
+        // transition out of and back into. `visibility` flips at the slide's end
+        // (see `.s-menu-list` in menu.ts): the dismissed page lingers off screen
+        // until Aberdeen's removal timer, and mustn't stay reachable meanwhile.
+        "&.s-nav-page-off": "transform:translateX(-100%) pointer-events:none visibility:hidden",
         // Roomier rows than the dropdown's: this is the whole screen, and every row
         // is a thumb target.
         ".s-menu-item": "padding: $2 $3; min-height:3rem font-size:1.05em gap:$3",
@@ -184,12 +195,19 @@ export function main(opts = {}) {
             routes,
             notFound: opts.notFound,
             ancestors: opts.ancestors,
-            columns: opts.columns,
-            linkNavigation: opts.linkNavigation,
             title: opts.title,
             $shell,
         })
         : null;
+    if (ctl) {
+        // `columns` and `linkNavigation` are live: each is read in a scope of
+        // its own, so when the options object is a proxy (or the field a
+        // getter), a change re-runs just that scope — the columns relayout in
+        // place with every panel's state intact, and the next click picks up
+        // the new link default. Nothing else of the shell is touched.
+        A(() => ctl.setColumns(opts.columns));
+        A(() => ctl.setLinkNavigation(opts.linkNavigation));
+    }
     // Where the brand mark and the app's name link — or nowhere, when the app
     // said `home: null` (a title slot holding a control of its own, say).
     const homeHref = ctl && opts.home !== null ? opts.home ?? "/" : null;
@@ -443,24 +461,20 @@ function drawSecondLine(opts, ctl, nav, $shell) {
 }
 /**
  * Whether the stack would only be saying what the sidebar already says: a
- * single panel open, the sidebar on screen, and that panel being one of the nav's
- * own rows.
+ * single panel open, the sidebar on screen, and that panel being one of the
+ * nav's own rows — a leaf inside a submenu counts, since the sidebar shows it
+ * highlighted (inside its unfolded branch) all the same.
  *
- * The row test is {@link matchCurrent} — the very thing that marks a row
- * `aria-current=page` — so "the crumb is redundant" and "the sidebar has it
- * highlighted" can never come apart. It compares whole paths, so it is true
- * only for a nav item's own screen, never for one opened beneath it.
+ * The row test is the menu's own {@link anyCurrent} — the very thing that
+ * marks a row `aria-current=page` — so "the crumb is redundant" and "the
+ * sidebar has it highlighted" can never come apart.
  */
 function taglineFits(ctl, nav, $shell) {
     if ($shell.narrow || nav == null)
         return false;
     if (ctl.panels.length > 1)
         return false;
-    return nav.items.some((entry) => typeof entry !== "string" &&
-        typeof entry !== "function" &&
-        !("separator" in entry) &&
-        entry.href != null &&
-        matchCurrent(entry.href));
+    return anyCurrent(nav.items);
 }
 /**
  * Track whether the shell is narrow, for everything that has to agree about it.

package/dist/components/menu.d.ts

@@ -26,6 +26,17 @@ export interface MenuItem {
      * `attrs: "data-panel=push"` for a row that should stack instead.
      */
     href?: string;
+    /**
+     * Pages this item claims *beyond* its own `href`: a string claims that path
+     * and everything under it (`"/mail"` claims `/mail/…`, not `/mailbox`), a
+     * function is asked with the current path. While a claimed page is current,
+     * the item is highlighted and the branches above it stay unfolded — for the
+     * detail screens a menu has no row of their own: the `/thread/[id]` a
+     * notification lands on, an icon's page under the gallery's row. Claims
+     * work from the very first paint, so they also cover cold deep links,
+     * which no amount of fold-state keeping can.
+     */
+    match?: string | ((path: string) => boolean);
     /** `target` for the link (`_blank`, etc.). Only meaningful with `href`. */
     target?: string;
     /** Disables the item. */
@@ -137,6 +148,13 @@ export type ContextMenuOptions = Omit<FloatingMenuOptions, "anchor" | "at" | "cl
  *   not a selection, so it doesn't run this.
  */
 export declare function drawMenu(items: MenuEntry[], onLeafSelect?: () => void): void;
+/**
+ * Whether any item anywhere in `items` — branches, their leaves, `match`
+ * claims — is the current page. The one question both the fold logic and the
+ * shell's tagline rule (see `taglineFits` in main.ts) ask of a menu, exported
+ * so the two can never disagree with the highlighting.
+ */
+export declare function anyCurrent(items: MenuEntry[]): boolean;
 /**
  * Whether the navigation that just landed on `path` was a branch row expanding
  * (consuming the note it left). Internal — used by the floating menu below and

package/dist/components/menu.js

@@ -9,11 +9,16 @@ import { button } from "./button.js";
 A.insertGlobalCss({
     // Border comes from the `.s-s.neutral` surface; the panel only overrides the radius
     // (lg) and opts into elevation via `.shadow` (added on the element below).
+    // `visibility` rides the same transition as the fade (flipping only at its
+    // end, per CSS visibility interpolation): a dismissed menu lingers in the
+    // DOM for a while — Aberdeen's `destroy=` removes it on a timer, not at
+    // the transition's end — and without this it would spend that time
+    // invisible yet still hittable by tests and read by assistive tech.
     ".s-menu-list": "position:fixed z-index:350 min-width:10rem display:flex flex-direction:column p:$1 " +
         "r:$s-radius-lg " +
         "overflow-y:auto max-height:min(80vh,28rem) " +
-        "transition: opacity 0.15s, transform 0.15s;",
-    ".s-menu-list.hidden": "opacity:0 pointer-events:none transform:translateY(-6px)",
+        "transition: opacity 0.15s, transform 0.15s, visibility 0.15s;",
+    ".s-menu-list.hidden": "opacity:0 pointer-events:none transform:translateY(-6px) visibility:hidden",
     // One class for both the `<a>` (link) and `<button>` forms — they look
     // identical; the element only differs where link semantics matter (see below).
     // The scroll-margin keeps a revealed row (see the scrollIntoView in
@@ -158,7 +163,7 @@ function drawLeaf(entry, onLeafSelect) {
             A(() => {
                 const first = !drawn;
                 drawn = true;
-                if (!matchCurrent(entry.href))
+                if (!isCurrent(entry))
                     return;
                 A("aria-current=page");
                 // A list taller than its scrollport (a long sidebar nav, mostly)
@@ -187,6 +192,18 @@ function drawLeaf(entry, onLeafSelect) {
         drawSlot(entry.label);
     });
 }
+/**
+ * The last route-derived fold state of every linked branch, keyed by the
+ * branch's selection href. Module-level on purpose: the phone's full-page nav
+ * (and any dropdown) mounts a fresh menu every time it opens, and per-mount
+ * state would hand it three folded sections in the middle of the user's work.
+ * Bounded by the number of distinct branch hrefs an app ever shows.
+ */
+const foldMemory = new Map();
+function setFold(href, open) {
+    foldMemory.set(href, open);
+    return open;
+}
 /**
  * A branch: a native `<details>` folding a sub-list of entries in and out. The
  * children stay mounted whether folded or not — closing hides them, it doesn't
@@ -207,14 +224,19 @@ function drawBranch(entry, onLeafSelect, $menuHasCurrent) {
     // nowhere in the menu, nothing has an opinion, and the fold simply keeps
     // its last state — folding everything up would answer a question nobody
     // asked with a menu that forgot where the user was.
-    let last = false;
+    //
+    // "Last state" lives in `foldMemory`, not in this closure: menus remount —
+    // the phone's full-page nav exists only while it is open — and a remount
+    // must find the state where the previous mount left it. It is keyed on the
+    // branch's selection href, so the sidebar and the phone nav (two renderings
+    // of the same items) share one truth, however often either is rebuilt.
     const $open = href != null
         ? A.derive(() => {
             if (containsCurrent(entry))
-                return (last = true);
+                return setFold(href, true);
             if ($menuHasCurrent == null || $menuHasCurrent.value)
-                return (last = false);
-            return last;
+                return setFold(href, false);
+            return foldMemory.get(href) ?? false;
         })
         : null;
     A("details.s-menu-details", () => {
@@ -227,9 +249,10 @@ function drawBranch(entry, onLeafSelect, $menuHasCurrent) {
             if (entry.disabled)
                 A("aria-disabled=true");
             A(() => {
-                // Current only on its *own* page: when a descendant is current, that
+                // Current only on its *own* page (its `href`, or a `match` claim —
+                // pages with no row of their own): when a descendant is current, that
                 // row carries the highlight, and two highlights would read as two pages.
-                if (entry.href != null && matchCurrent(entry.href))
+                if (isCurrent(entry))
                     A("aria-current=page");
             });
             A("click=", (e) => {
@@ -266,14 +289,36 @@ function foldedAway(el) {
     }
     return false;
 }
-/** Whether any page linked anywhere in `items` is the current one. */
-function anyCurrent(items) {
+/**
+ * Whether any item anywhere in `items` — branches, their leaves, `match`
+ * claims — is the current page. The one question both the fold logic and the
+ * shell's tagline rule (see `taglineFits` in main.ts) ask of a menu, exported
+ * so the two can never disagree with the highlighting.
+ */
+export function anyCurrent(items) {
     return items.some((entry) => typeof entry !== "string" && typeof entry !== "function" && !("separator" in entry) && containsCurrent(entry));
 }
-/** Whether `entry`'s own page, or any page linked below it, is the current one. */
-function containsCurrent(entry) {
+/**
+ * Whether this item is the current page: its own `href` matches, or its
+ * `match` claims the current path. The single test behind `aria-current`,
+ * branch unfolding, and {@link anyCurrent} — one truth, three consumers.
+ */
+function isCurrent(entry) {
     if (entry.href != null && matchCurrent(entry.href))
         return true;
+    const m = entry.match;
+    if (m == null)
+        return false;
+    const path = currentRoute.path;
+    if (typeof m === "function")
+        return m(path);
+    const claim = m.replace(/\/+$/, "") || "/";
+    return path === claim || path.startsWith(claim === "/" ? "/" : claim + "/");
+}
+/** Whether `entry` is the current page itself, or holds it anywhere below. */
+function containsCurrent(entry) {
+    if (isCurrent(entry))
+        return true;
     for (const child of entry.items ?? []) {
         if (typeof child === "string" || typeof child === "function" || "separator" in child)
             continue;

package/dist/components/panels.d.ts

@@ -161,13 +161,19 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      *   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.
+     *   dashboards. While one is open the columns stretch to the screen edges
+     *   instead of stopping at the standard 1280px page; the top bar and
+     *   footer hold the standard width throughout.
      *
      * 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.
      *
+     * This is a *layout regime*, not a width guarantee: handle whatever width
+     * the bucket yields, and ask only for what your content can actually use —
+     * a screen that would cap its own content narrower than its ask is holding
+     * room that would have let another column fit beside it.
+     *
      * 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
@@ -243,7 +249,40 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      * ```
      */
     close(): Promise<boolean>;
+    /**
+     * Opens `href` exactly as a click on a link inside this panel does — the
+     * shell's own link handling runs through this very call, so the two can't
+     * drift apart. By default that is a push: the target opens on top of this
+     * panel, closing the panels after it first (pinned ones ride along
+     * beneath the new panel, unsaved ones park), and a path that is already
+     * open is returned to rather than opened twice. `how` plays the part of a
+     * link's `data-panel` attribute: `"replace"` puts the target in this
+     * panel's place, `"open"` leaves the panel behind and gives the target
+     * its own stack, and omitting it follows the shell's
+     * {@link MainOptions.linkNavigation}, like a link without the attribute.
+     *
+     * This is the one for navigation that can't be a link: a row's click
+     * handler, a keyboard shortcut acting on this screen. The stack's
+     * {@link PanelStack.pushPanel} builds on the *current* panel instead — a
+     * different panel exactly when the interaction happened in a column
+     * beside it, where it would pile the new panel on top of the open detail
+     * rather than pruning back to this one.
+     *
+     * @example
+     * ```ts
+     * A("div.row click=", () => void $panel.open(`/contacts/${id}`), ...);
+     * ```
+     */
+    open(href: string, how?: "push" | "replace" | "open"): Promise<boolean>;
 }
+/**
+ * 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. The top bar and footer keep to this
+ * width even then (see main.ts), so the chrome holds still while the
+ * columns stretch.
+ */
+export declare const SHELL_PX = 1280;
 /** Options the stack needs from its shell. */
 export interface PanelStackOptions {
     routes: Routes;
@@ -315,6 +354,11 @@ export interface PanelStack {
      * 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.
+     *
+     * Note that a link builds on the panel it is *drawn in*, which is the
+     * current panel only while no column beside it has the focus. Code
+     * navigating on behalf of a particular screen — a row's click handler —
+     * wants that panel's own {@link Panel.open} instead.
      */
     pushPanel(path: string): Promise<boolean>;
     /**
@@ -581,11 +625,22 @@ export declare class PanelStackController implements PanelStack {
      */
     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.
+     * Navigate to `href` — the one implementation behind a link click,
+     * {@link Panel.open} and the stack's own methods, so none of them can
+     * behave differently.
+     *
+     * `from` is the path of the panel the navigation starts from — the one
+     * the link lives in — or absent when it has none: a nav item, or a call
+     * that means the whole stack, which is then built instead (see
+     * {@link deriveStack}), or taken outright from `beneath`, for callers
+     * that know it.
+     *
+     * `how` is the link's `data-panel` attribute (or the caller's word for
+     * it): absent — like a link without the attribute — it is the shell's
+     * `linkNavigation` default, an unrecognised value is a push on top of
+     * `from`, `"replace"` swaps `from` out rather than stacking on it, and
+     * `"open"` drops `from` altogether so the target arrives with its own
+     * stack, the way a nav item's link does.
      *
      * Resolves the way every {@link PanelStack} method does: `true` once the
      * navigation lands, `false` when it doesn't (already there counts as
@@ -596,18 +651,15 @@ export declare class PanelStackController implements PanelStack {
     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), the `data-panel`
-     * attribute, and return-to-an-open-panel semantics. The exclusion rules
+     * the anchor so we can decide what the click *means*. 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`, `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. A link that doesn't say gets the
-     * shell's {@link PanelStackOptions.linkNavigation} (`push` by default);
-     * an unrecognised value is a `push`.
+     * A link inside a panel is that panel's {@link Panel.open}, the `data-panel`
+     * attribute as its `how` (see {@link navigate}, the shared implementation).
+     * A link that isn't inside any panel — a nav item, one in a dialog — has no
+     * panel to build on, so it replaces the stack as a whole, exactly as a cold
+     * link to the same URL would open it.
      */
     private interceptLinks;
     get currentPanel(): Panel | undefined;
@@ -617,6 +669,10 @@ export declare class PanelStackController implements PanelStack {
     replacePanel(path: string): Promise<boolean>;
     openPanelStack(path: string, beneath?: readonly string[]): Promise<boolean>;
     closePanel(path?: string): Promise<boolean>;
+    /** Adopt a changed `columns` setting: one layout pass, nothing redrawn. */
+    setColumns(columns: "auto" | "single" | undefined): void;
+    /** Adopt a changed `linkNavigation` default; the next click reads it. */
+    setLinkNavigation(mode: "push" | "replace" | "open" | undefined): void;
     /**
      * 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