staffa 0.15.0 → 0.17.0

package/dist/components/panels.d.ts

@@ -3,31 +3,20 @@ 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*. The open panels
- * form a **stack**, whose last panel is the **current** one: the panel 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.
+ * Each route draws one screen, called a *panel*. The open panels form a
+ * **stack** whose last panel is the **current** one: the panel the URL names,
+ * and the rightmost column on screen. As many as fit are shown, ending there.
  *
- * Whatever a navigation lands on becomes the top of that stack, and the same
- * path is never in it twice. Opening a new panel closes everything after the
- * panel it came from; a plain link to a panel that is already open — a
- * breadcrumb, a nav item for the section you are in — returns to its own
- * place, closing whatever was stacked on top, while a `replace` or `open`
- * applies its usual shape, the open panel moving into it alive.
- * Two kinds of panel survive that: the ones the user pinned, which ride along,
- * and the ones holding unsaved work, which no navigation ever tears down.
- * Those wait parked out of sight past the rightmost column, which is the only
- * way a panel ever sits *after* the current one. Escape closes the current
- * panel — or just steps left, when it holds unsaved work or panels sit parked
- * beyond it.
+ * A navigation's target becomes the top of the stack, and the same path is
+ * never in it twice: opening a panel closes everything after the one it came
+ * from, while a plain link to an already-open panel returns to its place. Two
+ * kinds survive that — pinned panels, which ride along, and unsaved ones, which
+ * nothing tears down. Both wait parked past the rightmost column, the only way
+ * a panel ever sits *after* the current one.
  *
- * 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.
+ * Navigation runs through `aberdeen/route`: the URL holds the current panel and
+ * the rest of the arrangement is stored beside it in the history entry, so back
+ * and forward step through whole arrangements of columns.
  */
 /** Flattens an intersection into a single object type, so hovers read nicely. */
 type Prettify<T> = {
@@ -111,6 +100,10 @@ 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.
+     *
+     * Single-segment params are percent-decoded; `[...x]` is not, since decoding
+     * it would make an encoded slash indistinguishable from a separator. Split it
+     * yourself: `x.split("/").map(decodeURIComponent)`.
      */
     readonly params: P;
     /**
@@ -168,9 +161,9 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      * The widest this panel can usefully be — a ceiling the shell never
      * exceeds, so the draw function never has to look right past it. It is
      * counted in the shell's *columns*: the content area divides into the
-     * narrowest whole number of columns of at least 360px each (three columns
-     * of 360 in a 1080px area, four of 380 in 1520px), and a column is never
-     * wider than 540 — where the area holds just one, a small centres in it
+     * fewest whole number of columns of at most 540px each (two columns of 540
+     * in a 1080px area, three of ~507 in 1520px), and a column is never
+     * narrower than 360 — where the area holds just one, a small centres in it
      * rather than stretching. So an ask never exceeds its column count × 540:
      *
      * - `"small"` — one column, never above 540px: lists, detail forms.
@@ -306,10 +299,9 @@ export interface PanelStackOptions {
     /** 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.
+     * The shell's live narrow flag (see `main()`), deciding whether a panel's
+     * chrome sits in its own column or is promoted into the top bar. Shared
+     * rather than measured again, so the two can't disagree about the regime.
      */
     $shell: {
         narrow: boolean;
@@ -418,10 +410,9 @@ export interface PanelStack {
  */
 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.
+     * Kept out of Aberdeen's proxy wrapping: a class instance holding DOM nodes,
+     * timers and route handlers, riding inside every {@link Panel.stack}. Its
+     * reactivity comes from `$state` and the panels, which are proxies already.
      */
     readonly [OPAQUE] = true;
     private compiled;
@@ -429,35 +420,24 @@ export declare class PanelStackController implements PanelStack {
     private ancestors;
     private opts;
     /**
-     * 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.
+     * The live stack, oldest first (closing panels have left it), and which panel
+     * is current — the one reactive fact about the stack's *shape*. Each commit
+     * publishes the next shape by assigning a fresh `live` array; the entries are
+     * opaque, so a panel renaming itself doesn't redraw the stack.
+     *
+     * The invariant that makes this safe to touch from anywhere: **queries
+     * subscribe, commands peek**. Every navigation entry point (`navigate`,
+     * `closePath`, `back`, …) wraps itself in `A.peek`, so an app calling one
+     * from a reactive scope can't subscribe that scope to the stack it is
+     * changing; `propose` and `commit` inherit that and read 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.
+     * The open panels again, keyed by path — the shape the DOM consumes.
+     * `drawColumns`' `onEach` mounts by key, so splicing a panel out of the
+     * middle touches exactly one key and the retained columns keep their scroll
+     * positions and half-typed forms. (Iterating `live` would key by array index,
+     * which a splice renumbers, redrawing every panel after it.)
      */
     private $open;
     /** Feeds {@link PanelEntry.order}: one shared counter, so keys never tie. */
@@ -483,24 +463,18 @@ export declare class PanelStackController implements PanelStack {
     private matches;
     /**
      * 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.
+     * `route.go()` — anything with no panel to build on and no snapshot to
+     * restore. {@link PanelStackOptions.ancestors} gets first say; failing that,
+     * every prefix of the path is probed against the route table. A path with no
+     * route is skipped rather than opened as a "not found" column, so not routing
+     * a screen keeps it from appearing under another. The path itself always ends
+     * the derived stack, matched or not.
      */
     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.
+     * Ask the `ancestors` table what belongs beneath `path`. The first matching
+     * key answers, with its own matched params; `undefined` means "no opinion",
+     * leaving the path to the prefix derivation as an unlisted one would be.
      */
     private askAncestors;
     /** Every prefix of `path` that has a route, shallowest first. */
@@ -514,70 +488,57 @@ export declare class PanelStackController implements PanelStack {
     /** Whether the panel open at `path` (if any) holds unsaved work. */
     private unsavedAt;
     /**
-     * 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 arrangement a route implies: its snapshot around its path, or — without
+     * one — derived, the new panel current at the end with pinned panels beneath.
      *
-     * 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.
+     * The snapshot reads subscribe (they are the URL's). The derivation is peeked:
+     * it reads the live stack for its pins, which the route observer rewrites, so
+     * subscribing would re-run that observer once per commit.
      */
     private targetFor;
     /** The arrangement the current history entry asks for. Subscribes to path + snapshot. */
     private computeTarget;
     private paths;
     /**
-     * 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.)
+     * Adopt an arrangement proposed by the URL, after repairing it: a panel holding
+     * unsaved work is never torn down by any navigation — including a back to an
+     * entry from before it existed — so whatever the target drops, it stays, parked
+     * after the current panel. Parked panels are deliberately kept out of history
+     * entries: the work they protect lives in DOM a reload clears anyway.
      */
     private propose;
     /**
      * 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
-     * index shifted*, which is what lets a panel be spliced out of the middle
-     * (§7) without disturbing the columns above it. A common-prefix diff would
-     * remount every one of them, throwing away exactly the scroll and form state
-     * rule 5 promises to keep.
+     * Reconciliation is BY PATH, not by index: a panel in both stacks stays mounted
+     * even if its index shifted, which is what lets one be spliced out of the middle
+     * without disturbing the columns above it. A common-prefix diff would remount
+     * them all, throwing away their scroll and form state.
      */
     private commit;
     private createEntry;
     /**
-     * Take a panel out of the shell. The *scope* goes now: its cleaners run this
-     * tick, so whatever the panel registered with `A.clean` — subscriptions,
-     * timers, an open portal — is torn down when the panel closes, not when its
-     * animation is over. Only the element lingers, to play that animation, which
-     * is what the `destroy=` hook in `drawPanel` is for: Aberdeen hands the
-     * element to {@link playExit} instead of removing it.
+     * Take a panel out of the shell. The *scope* goes now — its `A.clean` hooks run
+     * this tick, so subscriptions, timers and portals stop at the close rather than
+     * at the end of the animation. Only the element lingers to play that animation,
+     * which is what `drawPanel`'s `destroy=` hook hands to {@link playExit}.
      */
     private beginClose;
     /**
-     * A closed panel's send-off, run by Aberdeen once the panel's scope is gone (so
-     * the content it shows is frozen, which is exactly what a departing column
-     * should be): it fades where it stands, inert, and leaves the DOM when the fade
-     * itself ends. Removing it on a fixed timer instead would race the transition —
-     * pull the element a frame early and the panel appears to fade half-way and
-     * then vanish. The timeout is just a fallback for when no `transitionend` is
-     * coming at all (transitions off, or an element that never got placed).
+     * A closed panel's send-off, run by Aberdeen once its scope is gone: it fades
+     * where it stands, inert, and leaves the DOM on `transitionend`. A fixed timer
+     * would race the transition and pull the element a frame early, making the
+     * panel appear to fade half-way and vanish; the timeout is only a fallback for
+     * when no `transitionend` is coming (transitions off, element never placed).
      */
     private playExit;
     /**
      * 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.
+     * change is still settling, the one on screen otherwise. That window is common
+     * (every `route.back()` waits for a `popstate`), and working from the committed
+     * arrangement inside it would aim a second Escape at the panel the first is
+     * already taking away — two quick Escapes would peel one panel.
      */
     private intended;
     /** The history `state` describing `arr` — exactly what `targetFor` reads back. */
@@ -585,96 +546,67 @@ export declare class PanelStackController implements PanelStack {
     /** 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.
+     * Put a navigation to the router, or — while one is still settling — behind the
+     * one that is. Only the newest waits; the one it displaces resolves `false`.
+     * A refusal empties the queue rather than running it, since what was queued
+     * was worked out against the arrangement the refused one would have produced.
      */
     private issue;
     private start;
     /**
      * Make the stack's `index`th panel current without closing anything, leaving
-     * the panels right of it parked out of sight.
-     *
-     * Only ever a step around a panel that refuses to close — nothing else is
-     * left sitting after the current one — so this is Escape's way past an
-     * unsaved panel, and the way back to one. It is a history entry, so the
-     * browser's back button returns the focus to where it was.
+     * the panels right of it parked out of sight — Escape's way past an unsaved
+     * panel, and back to one. A history entry, so back returns the focus.
      */
     private focusAt;
     /**
-     * One step back along the stack — what Escape does (`main()` calls this;
-     * it is not {@link PanelStack} API). Normally that closes the current panel,
-     * which is the stack's end. When it holds {@link Panel.unsaved} work — or
-     * panels sit parked beyond it — it stays open instead, and the focus
-     * simply moves to the panel on its left.
-     * Resolves `false` at the stack's start, where there is no left to go.
+     * One step back along the stack — what Escape does (`main()` calls this; it is
+     * not {@link PanelStack} API). Normally that closes the current panel; when it
+     * holds {@link Panel.unsaved} work, or panels sit parked beyond it, the focus
+     * moves left instead. Resolves `false` at the stack's start.
      */
     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.
+     * Close all come down to. `false` when that path isn't open, is the stack's
+     * only panel, or holds {@link Panel.unsaved} work.
+     *
+     * Closing the current panel at the stack's end pops back through history to
+     * the entry beneath it (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*, which still earns
+     * its own history entry — hence `route.go` here rather than `navigate()`,
+     * whose "link to an open panel" check would turn it into a focus move.
      */
     private closePath;
     /**
      * 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), picking how much of `from`'s context the target keeps: a push (the
-     * default, and what unrecognised values fall back to) keeps `from` and
-     * builds on it, `"replace"` keeps only what is beneath `from`, and
-     * `"open"` keeps nothing — the target arrives with its own stack, the way
-     * a nav item's link does. Absent, it is the shell's `linkNavigation`
-     * default, like a link without the attribute. A target that is already
-     * open is returned to by a push, and *moved* — alive, state intact — by
-     * the other two: the stack never holds a path twice.
-     *
-     * Resolves the way every {@link PanelStack} method does: `true` once the
-     * navigation lands, `false` when it doesn't (already there counts as
-     * landed).
+     * {@link Panel.open} and the stack's own methods, so none can drift.
+     *
+     * `from` is the panel the navigation starts from, absent when it has none (a
+     * nav item), in which case the stack is derived or taken from `beneath`.
+     *
+     * `how` is the link's `data-panel` attribute, picking how much of `from`'s
+     * context the target keeps: a push (the default, and the fallback for
+     * unrecognised values) builds on `from`, `"replace"` keeps only what is
+     * beneath it, `"open"` keeps nothing. A target that is already open is
+     * returned to by a push and *moved* — alive — by the other two, since the
+     * stack never holds a path twice.
+     *
+     * Resolves `true` once the navigation lands (already being there counts).
      */
     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 exclusion rules
-     * (targets, downloads, modified clicks, external URLs) live in Aberdeen; the
-     * close guards run in `checkChange` when our navigation reaches the router.
+     * Link handling through `route.interceptLinks()`, whose hook hands us the
+     * anchor so we can decide what the click means. The exclusion rules (targets,
+     * downloads, modified clicks, external URLs) live in Aberdeen.
      *
-     * 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.
+     * A link inside a panel is that panel's {@link Panel.open}, with `data-panel`
+     * as its `how`. A link outside every panel — a nav item, one in a dialog —
+     * has nothing to build on, so it replaces the stack as a cold link would.
      */
     private interceptLinks;
     get currentPanel(): Panel | undefined;
@@ -689,101 +621,81 @@ export declare class PanelStackController implements PanelStack {
     /** 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
-     * wearing their pin. Every crumb but the current panel's is a plain link to
-     * that panel, and a link to an open panel returns to it (see `navigate`) —
-     * so clicking a crumb goes back to that panel and closes what was stacked on
-     * top of it, pinned and unsaved panels excepted. 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.
+     * The breadcrumb stack, drawn by `main()` into the top bar: every open panel,
+     * oldest first, the ones on screen in bold. Every crumb but the current one is
+     * a plain link, and a link to an open panel returns to it (see `navigate`),
+     * closing what was stacked on top. Right-click offers pinning and closing.
      */
     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.
+     * Flip a panel's pin (see {@link Panel.pinned}). The current history entry's
+     * snapshot is rewritten too, so a reload keeps the pin.
      */
     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.
+     * `"<panel title> · <app title>"`, kept in sync with the current panel, and
+     * prefixed `"• "` while *any* open panel holds unsaved work — not just the
+     * current one, since the risk of losing it is tab-wide.
      */
     private watchTitle;
     /**
-     * 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, with
-     * the unsaved panel brought on screen as the question is raised, so what is
-     * holding the tab is in front of the user rather than parked out of sight.
+     * While any open panel holds unsaved work, closing the tab runs into the
+     * browser's own are-you-sure, with that panel brought on screen as the
+     * question is raised rather than left parked out of sight.
      */
     private guardTabClose;
     /**
      * Draw the column viewport into the current element. Called by `main()`.
      *
-     * 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}).
+     * A column is the panel's own content plus the one bit of chrome the shell
+     * places for it: its {@link Panel.actions} (see {@link drawActions}).
      */
     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.
+     * top bar carrying them otherwise. Everything else is the panel's own content.
      */
     private drawActions;
     scheduleLayout(): void;
     /**
-     * Run the pending layout pass now, rather than on the frame it is waiting
-     * for. For the callers that have to *read* what only the pass knows —
-     * `$panel.visible`, `$panel.width` — at a moment when waiting isn't an
-     * option. Does nothing when no pass is owed.
+     * Run the pending layout pass now instead of on the frame it waits for, for
+     * callers that must read what only the pass knows (`$panel.visible`,
+     * `$panel.width`) and can't wait. Does nothing when no pass is owed.
      */
     private flushLayout;
     /**
      * Measure the content area, and with it the width a panel of each size gets.
+     * The column region *is* that area (CSS's doing), so there is nothing to add
+     * up here that could drift from the bars above and below. Widths stay
+     * fractional: a rounded column edge would drift a pixel away from that chrome.
      *
-     * The column region *is* the content area: it takes whatever the shell has
-     * left beside the sidebar, capped by the shell's own `maxWidth` — all of it
-     * CSS's doing, so there is nothing to add up here and nothing that could
-     * drift from the width the bars above and below line up with. Fractional
-     * widths throughout: a rounded column edge would drift a pixel away from that
-     * chrome.
-     *
-     * The area divides into the narrowest whole number of columns that keeps each
-     * at least {@link SMALL_MIN_PX} wide — the `"small"` unit every other size is
-     * a multiple of, capped at the area itself. So 1080px is three columns of 360
-     * and 1520px four of 380. An area too narrow for two is a single column,
-     * itself capped at {@link SMALL_MAX_PX}: a small centres there instead of
-     * stretching toward 720, so its ceiling holds, while the larger sizes still
-     * take the whole area. A width is thus a pure function of the window: a panel
-     * NEVER resizes because a neighbour came or went, and only a window resize
-     * (the snap pass in `layout`) changes one.
-     *
-     * `undefined` while the shell has no width to speak of (it isn't in a document
-     * yet, or it's `display:none`); the next pass tries again.
+     * The area divides into the fewest whole number of columns of at most
+     * {@link SMALL_MAX_PX} — so 1080px is two of 540, 1520px three of ~507 —
+     * keeping columns as wide as the cap allows rather than as narrow as
+     * {@link SMALL_MIN_PX} permits. Only below 720px can that division dip under
+     * the minimum; there a single column, capped at 540, centres in the area
+     * instead. A width is therefore a pure function of the window: a panel NEVER
+     * resizes because a neighbour came or went.
+     *
+     * `undefined` while the shell has no width yet (not in a document, or
+     * `display:none`); the next pass tries again.
      */
     private measure;
     /**
-     * The measurements this pass runs on. Taken once per layout pass and per
-     * commit, and shared with the panels drawn in between — they all size
-     * themselves against the same shell, and a `getBoundingClientRect()` each
-     * would be a forced reflow each, in the middle of building their DOM.
+     * The measurements this pass runs on, taken once per pass and per commit and
+     * shared with the panels drawn in between: they must all size against the
+     * same shell, and a `getBoundingClientRect()` each is a forced reflow each.
      */
     private geometry;
     /** 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.
-     *
-     * This is everything CSS can't work out for itself: which panels exist, which
-     * of them are visible, how wide each one is and where it sits. All the motion
-     * between two of these arrangements is CSS's job.
+     * Size and position every panel — everything CSS can't work out for itself:
+     * which panels exist, which are visible, how wide each is and where it sits.
+     * The motion between two such arrangements is CSS's job.
      */
     private layout;
     /** Let a `loading` panel's enter animation wait — but not indefinitely. */