staffa 0.14.0 → 0.16.0

package/README.md

@@ -8,29 +8,20 @@ import * as S from "staffa";
 
 const $user = A.proxy({ name: "", email: "" });
 
-S.main({
-  title: "Sign up",
-  maxWidth: "40rem",
-  content: () => {
-    S.form({
-      submit: () => S.dialog({
-        header: "Submitted",
-        content: () => A.dump($user)
-      }),
-      content: () => {
-        S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
-        S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
-      },
-      actions: () => S.button({ content: "Create account", type: "submit" }),
-    });
-  },
-});
+S.main({ title: "Sign up", maxWidth: "40rem", content: () => {
+  S.form({
+    submit: () => S.dialog({ header: "Submitted", content: () => A.dump($user) }),
+    content: () => {
+      S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
+      S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
+    },
+    actions: () => S.button({ content: "Create account", type: "submit" }),
+  });
+}});
 ```
 
 Staffa is made to look decent out of the box, but easily customizable at runtime.
 
-## Screenshot
-
 ![Screenshot](screenshot.png)
 
 ## Install
@@ -41,32 +32,25 @@ npm install staffa aberdeen
 
 Aberdeen is a peer dependency. Staffa is published as ESM with TypeScript types.
 
+**Every option of every component is documented in TSDoc**, on its `…Options` interface in `src/` — and, for AI agents, in the generated API reference that ships in `skill/`. This README only covers what those can't tell you.
+
 ## How it works
 
 ### Components are functions
 
-Every component takes a single typed options object and draws DOM via Aberdeen. No classes, no web components. The `S` object collects all component functions:
+Every component is a plain function taking a single typed options object and drawing DOM via Aberdeen. No classes, no web components. The `S` object collects them all. The options object may be an Aberdeen proxy, in which case mutating it updates the component in place:
 
 ```ts
-S.button({ content: "Save", disabled: false });
 S.box({ header: "Settings", content: () => { ... } });
-```
-
-### Options objects are typed and can be reactive
 
-All components get their options in a typed object. The object may be an Aberdeen proxy, if you want to update the component in-place.
-
-```ts
 const $btn = A.proxy({ content: "Save", disabled: false });
 S.button($btn);
-setTimeout(() => // Later..
-  $btn.disabled = true;  // button updates instantly
-}, 3000);
+setTimeout(() => { $btn.disabled = true; }, 3000);   // button updates instantly
 ```
 
 ### Rich text slots
 
-Anywhere a component takes content, a `label`, `header`, button `text`, dialog body, etc, you can pass either a string or a `() => void` draw function. Strings render as **rich text**: `*italic*`, `**bold**`, `` `code` ``, `[link](/path)`. All text is safely escaped.
+Anywhere a component takes content — a `label`, a `header`, a button's text, a dialog body — you can pass either a string or a `() => void` draw function. Strings render as **rich text**: `*italic*`, `**bold**`, `` `code` ``, `[link](/path)`. All text is safely escaped.
 
 ```ts
 S.button({ content: "Save **now**" });
@@ -75,12 +59,12 @@ S.box({ header: "See the [docs](/docs)", content: () => { ... } });
 
 ### Surfaces
 
-Staffa builds on **surfaces**: elements marked with `.s-s` that have their own background and derived text/border tokens. There are two families:
+Staffa builds on **surfaces**: elements marked `.s-s` that have their own background and derived text/border tokens. There are two families:
 
-- **Neutral surfaces** — `.neutral` (and the implicit page at `:root`). A calm neutral whose shade steps automatically with nesting depth (each level a step away from the page colour, up to a cap). Use them for cards, bars, popovers — anything that just holds content. No variants.
-- **Accent surfaces** — `.primary`, `.danger`, `.success`, `.warning`, `.link` (a bare `.s-s` defaults to primary). A bright fill with white ink, painted as a subtle single-colour gradient. They take a **variant**: `.filled` (default), `.tonal`, or `.outlined`. A surface nested *inside* an accent surface is always rendered filled, so it can't bleed into the vivid parent.
+- **Neutral surfaces** — `.neutral` (and the implicit page at `:root`). A calm neutral whose shade steps automatically with nesting depth, up to a cap. For cards, bars, popovers — anything that just holds content. No variants.
+- **Accent surfaces** — `.primary`, `.danger`, `.success`, `.warning`, `.link` (a bare `.s-s` defaults to primary). A bright fill with white ink, painted as a subtle single-colour gradient. They take a **variant**: `.filled` (default), `.tonal` or `.outlined`. A surface nested *inside* an accent surface is always rendered filled, so it can't bleed into the vivid parent.
 
-Components are built from these (`S.button` is a `.s-s.primary`, `S.box` a `.s-s.neutral`, etc.). Because component options include an optional `attrs` string, which has Aberdeen `A()` string semantics, you can easily override it:
+Components are built from these (`S.button` is a `.s-s.primary`, `S.box` a `.s-s.neutral`). Every component's `attrs` option is an Aberdeen `A()` string, so overriding is easy:
 
 ```ts
 S.button({ content: "Delete", attrs: ".danger" });
@@ -88,20 +72,20 @@ S.button({ content: "Cancel", attrs: ".neutral" });       // neutral button
 S.box({ attrs: ".primary", content: () => { ... } });
 ```
 
-Inside any surface (including `:root`), CSS variables are defined for the background and a set of safe foreground colors: `$s-bg`, `$s-text` (also applied as `color`), `$s-muted`, `$s-accent` (the surface's "pop" — the brand primary on neutral surfaces, the ink on accent surfaces), and `$s-faint`. By using these, components adapt to wherever they're nested.
+Inside any surface (including `:root`), CSS variables hold the background and a set of safe foreground colours: `$s-bg`, `$s-text` (also applied as `color`), `$s-muted`, `$s-accent` (the surface's "pop" — the brand primary on neutral surfaces, the ink on accent ones) and `$s-faint` (hairlines). Use these and components adapt to wherever they're nested.
 
-The colour tokens are mode-independent and settable: `$s-primary` (the one brand colour — it tints the neutrals and defines `.s-s.primary`), `$s-danger`, `$s-success`, `$s-warning`, and `$s-link` (the link colour, which is also the fill of the `.s-s.link` surface). Links render in `$s-link` on neutral surfaces and in the ink on accent surfaces.
+The colour tokens themselves are mode-independent and settable: `$s-primary` (the one brand colour — it tints the neutrals and defines `.s-s.primary`), `$s-danger`, `$s-success`, `$s-warning` and `$s-link` (also the fill of the `.s-s.link` surface). Links render in `$s-link` on neutral surfaces, in the ink on accent ones.
 
-**Borders & shadows.** Neutral surfaces carry a subtle hairline border on their own (so a card looks like a card without any component help). Any surface can be lifted with `.shadow` or `.extra-shadow`: on a neutral surface that's a neutral drop shadow, on an accent surface it's a self-coloured glow (a lit button is just a `.primary` surface with `.shadow`), and on `.tonal`/`.outlined` it's ignored. `.no-shadow` removes a component's built-in shadow:
+**Borders & shadows.** Neutral surfaces carry a subtle hairline border on their own, so a card looks like a card without any component help. Any surface can be lifted with `.shadow` or `.extra-shadow` — a neutral drop shadow on a neutral surface, a self-coloured glow on an accent one, ignored on `.tonal`/`.outlined`. `.no-shadow` removes a component's built-in shadow:
 
 ```ts
 S.box({ attrs: ".extra-shadow", content: () => { ... } });   // a more raised card
-S.button({ content: "Quiet", attrs: ".no-shadow" });          // drop the button glow
+S.button({ content: "Quiet", attrs: ".no-shadow" });         // drop the button glow
 ```
 
 ### Dark and light modes
 
-Dark/light mode is detected from OS preference by default. If you want to override this (based on user preferences), use:
+Dark/light mode follows the OS preference by default. Override it (and persist the choice) with:
 
 ```ts
 S.setDarkMode(true);       // force dark
@@ -109,13 +93,43 @@ S.setDarkMode(false);      // force light
 S.setDarkMode(undefined);  // follow OS
 ```
 
-*Hint:* A `buttonChooser` is probably the right component for a color scheme selector.
+`S.getDarkMode()` reads it back, reactively. A `buttonChooser` is probably the right component for a colour scheme selector.
 
-### Panel-stack navigation
+### CSS reset
+
+Staffa includes a lightweight CSS reset that makes bare semantic HTML look a bit better, but unsurprising without additional styling.
+
+### Theming
+
+Theming usually starts and ends with setting some CSS variables. Everything derives from the single brand colour `s-primary` (the neutral surface shades are tinted toward it too). Set them through CSS directly, or through Aberdeen:
+
+```ts
+A.cssVars["s-primary"] = "#fdda58";
+A.cssVars["s-danger"] = "#ee4422";
+A.cssVars["s-radius"] = "4px";
+```
+
+See `src/theme.ts` for the other variables in use.
+
+Beyond that, add CSS to override the default styling. To add your own accent surface, set its background (and, if needed, its ink) — the gradient and the rest of the tokens follow automatically:
+
+```ts
+A.insertGlobalCss({".s-s.my-surface": "--s-bg:#ef6b00 --s-text:#fff"});
+
+S.button({
+  content: "You'll want to click me",
+  attrs: ".my-surface",
+  click: () => S.alert("Good work!", {attrs: ".my-surface"})
+});
+```
+
+Custom surface class names may be anything other than the built-in modifiers (`.tonal`, `.outlined`, `.small`, `.large`). The `.tonal` and `.outlined` variants work on your surface for free.
+
+For styling that differs per mode, wrap the above in `A(() => { if (S.getDarkMode()) ... })`: `getDarkMode()` is reactive, so the scope re-runs when the mode changes.
 
-Give `S.main()` a `routes` table instead of a `content` slot, and it takes over navigation for you. Each route draws one screen of your app — Staffa calls those **panels** — and the shell shows as many of them at a time as comfortably fit, each in its own **column**.
+### Panel-stack navigation
 
-On a phone that means one panel at a time: a link opens a new panel on top of it, and closing that one brings the previous back, the way most mobile apps work. On a wider screen, panels that would have covered each other sit side by side instead. Pick a project from a list and it opens *beside* the list; pick another and it takes the first one's place. Your code doesn't know the difference.
+Give `S.main()` a `routes` table instead of a `content` slot and it takes over navigation. Each route draws one screen of your app — a **panel** — and the shell shows as many panels as comfortably fit, each in its own **column**: one at a time on a phone, several side by side on a wider screen. The open panels form a **stack**, whose last member is the **current** panel — the one the URL names, and the rightmost column. Your code doesn't know the difference.
 
 ```ts
 const shell = S.main({
@@ -134,76 +148,25 @@ function drawProject($panel: S.Panel<{ projectId: string }>) {
   $panel.title = `Project ${projectId}`;  // the shell puts it wherever it fits
   A(`a href=/projects/${projectId}/tasks/1 #Open the first task`);
 }
-
-// Etc..
-```
-
-Each handler gets a `$panel` object holding the params from its route, along with the things Staffa needs to know about the panel: what it's called, what it can do, how much room it wants, whether it's still loading. It's an Aberdeen proxy, so you can set those later (when your data arrives, say) and the shell keeps up.
-
-**Route keys.** A segment wrapped in brackets is a param:
-
-- `[name]` matches one segment, as a string.
-- `[name=integer]` matches one segment, as a number.
-- `[...name]` matches the rest of the path, as a string. It has to be the last thing in the key, and it needs at least one segment to match.
-
-The first key that matches wins, and a segment a param refuses simply doesn't match, so it falls through to a later route, or to `notFound`. TypeScript reads each key and types that handler's `$panel.params` from it, so `params.taskId` above really is a `number`.
-
-`integer` only accepts spellings that survive a round trip back to the same URL: `42` and `-7` and `0`, but not `007`, `1.5`, `0x10`, `-0` or anything past `Number.MAX_SAFE_INTEGER`. Otherwise `/tasks/42` and `/tasks/0042` would be two different paths for one record, and could sit open in two columns at once. For ids that aren't safe integers, such as snowflakes, use a plain `[id]` and keep them as strings.
-
-`[...name]` hands you the remaining path exactly as it appears in the URL, still percent-encoded. Decoding it for you would be lossy: an encoded slash inside a segment would come back looking just like a separator. When you want the pieces, `name.split("/").map(decodeURIComponent)` gives them to you. (Single-segment params have no such ambiguity, so those *are* decoded.)
-
-**Navigating is just links.** Write ordinary `<a href="/...">` links; Staffa handles the clicks (so don't also call Aberdeen's `interceptLinks()`).
-
-The open panels form a **stack**, and its last panel is the **current** one: the panel the URL names, and the rightmost column on screen. Whatever you navigate to lands there.
-
-- A link inside a panel opens its target on top of that panel, closing everything after it first. That's why clicking a second project replaces the open project instead of adding a third column.
-- A `data-panel` attribute on the link picks a different one of the three navigations, which differ only in how much of the link's own context the target keeps: `push` (the default just described) keeps the link's panel and builds on it; `replace` keeps everything under that panel but not the panel itself — what prev/next buttons want; and `open` keeps none of it, giving the target its own stack exactly as a nav item would — for a search hit or a mention, where the panel you clicked from is coincidence, not context.
-- A plain link to something that's already open goes back to it instead of opening it twice, closing whatever was stacked on top of it; a `replace` or `open` applies its usual shape instead, the open panel moving into place with its state intact. Either way 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 panel you asked for, with its ancestor panels 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.
-
-**The stack is an object, not a global.** In routed mode `S.main()` hands back the panel stack, and every panel gets the same object as `$panel.stack` — which is what a route handler uses, since it runs while the `S.main()` call is still going and can't see its return value yet.
-
-```ts
-shell.pushPanel(path);                 // on top of the current panel
-shell.replacePanel(path);              // in its place
-shell.openPanelStack(path, beneath?);  // a whole arrangement, the way a nav item does
-shell.closePanel(path?);               // the current panel, or a named one
-
-shell.panels;              // the open panels, oldest first — the Panel objects themselves
-shell.currentPanelIndex;   // which of them the URL is on
-shell.currentPanel;        // shorthand for panels[currentPanelIndex]
 ```
 
-Navigations settle asynchronously (closes travel through the browser's history), so each of the four methods returns a `Promise<boolean>`: `true` once it lands, `false` when it doesn't — an unsaved panel refused to close, a route guard said no, or another navigation superseded it. Ignore it unless you care.
-
-`panels` is a live view rather than a copy, so writing through it works — `shell.panels[0].pinned = true` is the only way to pin a panel from outside its own handler. All three are reactive on the stack's shape: read one in a scope and it re-runs when panels open, close or the cursor moves. Don't hold a `Panel` across a navigation; read it fresh.
-
-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.
-
-**The content area is the window**, minus the nav sidebar — or, when `S.main({ maxWidth })` says so, that much of it, centred. Either way it is the same width whatever is open, so the sidebar, the top bar and the footer never move.
-
-The shell divides that area into columns: the narrowest whole number of them that keeps each one at least **360px** wide, and no column ever wider than **540**. A 1080px content area is three columns of 360; a 1520px one is four of 380; below 720px there is a single column — of at most 540, centred. `$panel.maxWidth` counts in those columns:
-
-| `maxWidth` | How wide the panel gets | Good for |
-| --- | --- | --- |
-| `"small"` | One column — never above 540px. | lists, detail forms — anything that reads well at phone width |
-| `"medium"` (default) | Two columns — never above 1080px. | ordinary screens; the safe default |
-| `"large"` | Three columns — never above 1620px. | wide tables, dense forms |
-| `"none"` | The whole content area, unbounded. | boards, dashboards |
+Each handler gets a `$panel` proxy: the params from its route, plus what the shell needs to know about the panel — `title`, `actions`, `maxWidth`, `loading`, `pinned`, `unsaved`, `width`, `visible`, `close()`, `open()`, `stack`. Set them whenever you like — long after the handler ran, when your data arrives — and the shell keeps up. Each field is documented in the API reference.
 
-The ask is a promise in both directions: the shell never draws a panel wider than its column count × 540px, and every size is also capped at the content area — so a draw function has to look right from 360px up to its own ceiling, and nowhere past it. There is nothing below 360 to handle either: a narrower window is shown the 360px layout scaled down to fit (dialogs, menus and toasts scaling along), so 360 really is the floor.
+**Route keys.** `[name]` matches one segment as a string, `[name=integer]` one segment as a number, and a trailing `[...name]` the rest of the path as one raw (still percent-encoded) string. The first key that matches wins; a segment a param refuses falls through to a later route, or to `notFound`. TypeScript types each handler's `params` from its own key. `integer` accepts only spellings that survive a round trip back to the same URL, so one record can never have two paths — use a plain `[id]` for ids that aren't safe integers.
 
-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. As many columns as fit are shown, ending at the current panel; when they don't fill the content area they sit centred in it, so an arriving column nudges the others over to share the room.
+**Navigating is just links.** Write ordinary `<a href="/...">` links; the shell handles the clicks (so don't also call Aberdeen's `interceptLinks()`). The three navigations differ only in how much of the link's own context the target keeps:
 
-`S.main({ navWidth, maxWidth })` sets the sidebar's width and the cap. Leave `maxWidth` off and the app simply fills the window — worth capping (`"1600px"`, say) if you'd rather it didn't march across a 4K display.
+- **push** (the default) opens on top of the panel the link sits in, closing everything after it — which is why clicking a second project replaces the open project instead of adding a third column.
+- **replace** keeps everything under that panel but not the panel itself; what prev/next buttons want.
+- **open** keeps none of it, giving the target its own stack, as a nav item does; for a search hit or a mention, where the panel you clicked from is coincidence, not context.
 
-Columns tile the area they're given, separated by a hairline and no gutter — a column brings its own padding, so their contents stay comfortably apart regardless.
+`data-panel` on the link picks one; `linkNavigation` sets the default for links without it. A link outside any panel (a nav item, one in a dialog) has nothing to build on, so it replaces the stack as a whole, exactly as a cold link to that URL would — panels the new stack also contains staying as they are. A link to a path that's already open returns to it, closing what was stacked on top, rather than opening it twice; the same path is never in the stack twice.
 
-The panel is sized before your handler runs, and `$panel.width` is the resolved figure in pixels — so a chart, a virtualised list or a column count has the real width from the first frame, with nothing to measure. Set `maxWidth` at the top of your handler and you draw at the new width; set it later and the panel reflows without being redrawn, so nothing in it is rebuilt or loses its state.
+**The stack is an object, not a global.** `S.main()` hands back the `PanelStack` — `pushPanel`, `replacePanel`, `openPanelStack`, `closePanel`, and the live, reactive `panels` / `currentPanel` / `currentPanelIndex` — and every panel gets that same object as `$panel.stack`, which is what a route handler uses, since it runs while the `S.main()` call is still going. Every navigation settles asynchronously (closes travel through the browser's history), so each method returns a `Promise<boolean>`. Don't hold a `Panel` across a navigation; read it fresh. To navigate on behalf of one particular screen — a row's click handler — use that panel's own `$panel.open(href, how?)`, which does exactly what a link inside it does; `pushPanel` builds on the *current* panel instead.
 
-<a id="chrome"></a>
+**Columns and widths.** The content area is the window minus the nav sidebar, or `S.main({ maxWidth })` of it, centred — the same width whatever is open, so the sidebar, top bar and footer never move. It divides into the narrowest whole number of columns of at least **360px**, capped at **540px** each; `$panel.maxWidth` asks for one, two (the default), three of them or the lot. A column's width depends only on the window, never on what else is open, so opening or closing a panel never resizes another. Its ask is a ceiling, never a floor: aim your layout at 360px and let it degrade gracefully below that. `$panel.width` is the resolved figure in pixels, correct before your handler draws.
 
-**A panel declares its chrome; the shell places it.** A screen says what it is called and what it can do; everything else in its column — headings, cards, boxes — is the screen's own content, drawn like any other. Where the chrome ends up depends on how many columns are showing and how wide the shell is, so the shell decides:
+**A panel declares its chrome; the shell places it.** A screen says what it is called and what it can do; everything else in its column — headings, cards, boxes — is the screen's own content, drawn like any other.
 
 ```ts
 function drawTask($panel: S.Panel<{ taskId: number }>) {
@@ -213,33 +176,11 @@ function drawTask($panel: S.Panel<{ taskId: number }>) {
 }
 ```
 
-On a wide screen the title becomes the stack's last crumb and the Save button sits in a quiet strip at the top of the column. On a phone the crumb is still there and Save moves into the top bar, where the app menu was. Nothing in your code measures the viewport, and no screen is written twice.
+On a wide screen the title becomes the stack's last crumb and Save sits in a quiet strip at the top of the column; on a phone the crumb is still there and Save moves into the top bar, where the app menu was. Nothing in your code measures the viewport. Two deliberate rules: `actions` are the screen's *verbs* — Save, Delete, a menu — not a second way out, since going back is the crumbs' job at every width and there is no back button even on a phone (a link among the actions builds on this panel at both widths); and **`title` names the screen, it does not draw a heading** — a screen that wants its name in its own body writes it there, where it owns the typography. A column's body keeps a comfortable `$3` of padding; write `A("p:0")` for edge-to-edge rows, since the draw function's current element *is* the body.
 
-**The breadcrumbs are the navigation.** The top bar's second line writes the open panels out as breadcrumbs — `Projects / Trackle / Task 42` — with the panels currently on screen in bold. A crumb is an ordinary link to its panel, so clicking one goes back to that panel and closes what was stacked on top of it — and the browser's back button brings those columns back. The app's name and logo link to the app's home (the `home` option, `/` by default; `null` links neither), going back to it when it's already open and opening it when it isn't. A stack too long for the bar scrolls sideways, in an `S.scrollStrip` like the tab strip's.
+**The breadcrumbs are the navigation.** The top bar's second line writes the open panels out as breadcrumbs — `Projects / Trackle / Task 42`, the ones currently on screen in bold — leaving that line to the app's `subtitle` only while the stack has nothing to add. Each crumb is an ordinary link back to its panel, closing what was stacked on top; the app's name and logo link to `home` (`/` by default, `null` links neither). Right-clicking a crumb offers **Close** and **Pin**: a pinned panel (`$panel.pinned`) survives navigation elsewhere, riding along beneath the new panel or parking out of sight, but not an explicit close. Escape closes the current panel, or steps left when it can't, and at the stack's start jumps to the navigation.
 
-That line is the `subtitle`'s while the stack has nothing to add: one panel open, reachable from a nav item that is already highlighted in a visible sidebar. Otherwise the stack takes it, since it is then the only thing naming the screen.
-
-Right-click (or long-press) a crumb for **Close** — which takes just that panel out, wherever it sits in the stack — and **Pin**. A pinned panel — its crumb wears a pin — never closes as a side effect of navigation elsewhere: where a navigation would prune it, it rides along beneath the new panel instead (or parks out of sight, when the panel you went back to was already beneath it), one crumb click away. Pin the reference you keep coming back to, then navigate freely. An *explicit* close (Escape, `close()`, the crumb menu, `data-panel=replace`) still closes it, and it's yours from code as `$panel.pinned`. Because a crumb is a real link whose right-click the menu takes over, the menu also offers **Open in new tab** and **Copy link**.
-
-A crumb can also wear a **●**: the panel holds unsaved work, and nothing will close it (see `$panel.unsaved` below).
-
-| `$panel` | what it does |
-| --- | --- |
-| `title` | Names the screen: its breadcrumb, and `document.title` while it's the current panel. A panel that sets none borrows the first line of text in its own body — good enough for a crumb, but say it yourself. |
-| `actions` | The screen's buttons or menu. In the column's chrome while several columns fit; in the top bar (taking the app `menu`'s place) once the shell is narrow. A link among them builds on this panel at both widths. |
-
-Two deliberate rules there. `actions` are the screen's *verbs* — Save, Delete, Share, a menu — not a second way out: going back is the crumbs' job, at every width, and there is no back button even on a phone. And **`title` names the screen; it does not draw a heading** — a screen that wants its name in its own body writes it there, where it owns the typography.
-
-A column's body keeps a comfortable `$3` of padding; a screen that wants edge-to-edge rows just writes `A("p:0")`, since the draw function's current element *is* the body.
-
-**The rest of `$panel`:**
-
-- `params` and `path`: read-only.
-- `maxWidth`: as above, and live — set it whenever you like and the panel reflows.
-- `loading`: set it while you're fetching. A new panel waits a moment before sliding in, so it can arrive with real content instead of empty, and shows a loading indicator if the wait drags on.
-- `width` and `visible`: read-only and reactive. `width` is this column's width in pixels, for the rare content that genuinely differs by width. `visible` says whether this panel is on screen — not crowded out, not parked, not closing — which is the right question for per-panel floating UI like a FAB, since "am I the current panel?" answers wrongly when two columns are up.
-- `pinned`: the crumb menu's Pin, from code.
-- `unsaved`: set it while the panel holds work that must not be lost — a dirty form, an upload in flight. An unsaved panel **cannot be closed, by anything**: navigation and the back button park it instead (wearing a ● in its crumb), `close()` and the crumb menu's Close refuse, Escape steps left, and closing the browser tab runs into the browser's own are-you-sure. The tab title carries a leading `•` while *any* open panel is unsaved. Only the app clears the flag, which is its explicit "this is now discardable":
+**Unsaved work.** `$panel.unsaved` marks a panel holding work that must not be lost — a dirty form, an upload in flight. It then **cannot be closed, by anything**: navigation and the back button park it instead (its crumb wearing a ●), `close()` and the crumb menu's Close refuse, Escape steps left, and closing the browser tab runs into the browser's own are-you-sure. The tab title carries a leading `•` while *any* open panel is unsaved. Only the app clears the flag:
 
 ```ts
 A(() => { $panel.unsaved = $form.dirty || undefined; });   // the whole dirty check
@@ -252,27 +193,9 @@ S.button({ content: "Discard", attrs: ".neutral", click: () => {
 
 So a panel that can *be* unsaved needs its own way out — a Save or Discard among its `actions`. There is no "discard changes?" dialog anywhere: leaving is never blocked, the work just waits, parked, one crumb away.
 
-- `close()`: closes this panel, wherever it sits in the stack (refused while it's `unsaved`). Behind a Cancel button, or a Save that closes:
+**Cold URLs.** The URL holds the current panel; the rest of the stack — the panels before it, any parked after it, and which are pinned — rides in the browser's history entry, so back and forward step through whole arrangements of columns and a reload brings the same ones back. A URL arriving 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, so `/projects/7/tasks/42` opens as three columns. 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.
 
-```ts
-S.button({ content: "Cancel", attrs: ".neutral", click: () => $panel.close() });
-$panel.stack.closePanel();              // the current panel
-$panel.stack.closePanel("/projects/7"); // that panel, wherever it is
-```
-
-Closing the current panel hands the focus to the panel on its left. Closing one that *isn't* current takes just that one away: the columns around it stay where they are and keep their state, and the URL doesn't change, because the current panel didn't move. Either way it becomes a history entry, so the browser's back button brings the panel back.
-
-A closed panel is torn down at once: its `A.clean()` hooks run the moment it closes, so subscriptions, timers and requests stop there and then. Only its element hangs around, inert and frozen, for the length of the exit animation.
-
-Escape closes the current panel — or just steps left, when it holds unsaved work or panels sit parked beyond it — and at the stack's start it jumps to the navigation. The browser's back button replays whole arrangements, re-opening what a navigation closed.
-
-<a id="ancestors"></a>
-
-**The back button, and links from elsewhere.** The URL holds the current panel; the rest of the stack — the panels before it, any parked after it, and which are pinned — is stored beside it in the browser's history entry. So back and forward step through whole arrangements of columns, and a reload brings the same columns back.
-
-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 columns: 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:
+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 `ancestors` is where you say what belongs underneath. It's keyed by the same path templates as `routes`, so each entry gets that key's params, matched and typed:
 
 ```ts
 S.main({
@@ -286,107 +209,35 @@ S.main({
 });
 ```
 
-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 `$panel`: it's consulted while the navigation is still being worked out, before any route handler has run.
-
-From code, `openPanelStack(path, beneath?)` opens the same kind of arrangement, either asking `ancestors` for the panels beneath or taking the ones you hand it.
-
-Search params and the `#hash` belong to the current panel only. Anything another panel in the stack needs in order to redraw itself has to live in its path. (A panel you browse away from does get its search and hash back when a crumb makes it current again.)
+Return the paths shallowest first, or nothing to fall back to the parent-path walk — which is also what an unlisted route gets. It's asked for every navigation that has no panel to build on, so a nav item and a fresh tab agree, and it is consulted before any handler has run, so it must answer without drawing anything. From code, `openPanelStack(path, beneath?)` opens the same kind of arrangement.
 
 **A few more things.**
 
-- `columns: "single"` shows only the current panel, however wide the screen — one screen at a time at every size, each still at its asked width, centred. 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.
-
-### CSS reset
-
-Staffa includes a lightweight CSS reset that makes bare semantic HTML look a bit better but unsurprising without additional styling. 
-
-### Theming
-
-The first step in theming is just setting some CSS variables. Everything derives from a single brand colour, `s-primary` (the neutral surface shades are tinted toward it too), so often that's all you need. This can be done through CSS directly, or using Aberdeen:
-
-```ts
-A.cssVars["s-primary"] = "#fdda58";
-A.cssVars["s-danger"] = "#ee4422";
-A.cssVars["s-radius"] = "4px";
-```
-
-See `src/theme.ts` for what other CSS variables are being used.
-
-If you need further customization, just add some CSS to override the default styling. For instance, to add your own accent surface, set its background (and, if needed, its ink) — the subtle gradient and the rest of the tokens follow automatically:
-
-```ts
-A.insertGlobalCss({".s-s.my-surface": "--s-bg:#ef6b00 --s-text:#fff"});
-
-S.button({
-  content: "You'll want to click me",
-  attrs: ".my-surface",
-  click: () => S.alert("Good work!", {attrs: ".my-surface"})
-});
-```
-
-Custom surface class names may be anything (other than the built-in modifiers `.tonal`, `.outlined`, `.small`, `.large`). The `.tonal` and `.outlined` variants work on your surface for free.
-
-Note that when changing CSS like this, things *may* break if you upgrade Staffa. The recommended update strategy is therefore: don't!
-
-If you want to make changes that are dependent upon the current light/dark mode setting, rely on Aberdeen reactivity:
-
-```ts
-A(() => {
-  if (S.getDarkMode()) {
-    A.cssVars["s-primary"] = "#aa9944";
-    A.insertGlobalCss({".s-s.my-surface": "--s-bg:#444444 --s-text:#fff"});
-  } else {
-    A.cssVars["s-primary"] = "#fdda58";
-    A.insertGlobalCss({".s-s.my-surface": "--s-bg:#cccccc --s-text:#000"});
-  }
-});
-```
+- Search params and the `#hash` belong to the current panel only; anything another panel needs in order to redraw itself has to live in its path. (A panel you browse away from does get its search and hash back when a crumb makes it current again.)
+- A closed panel is torn down at once: its `A.clean()` hooks run the moment it closes, so subscriptions, timers and requests stop there and then.
+- `columns: "single"` shows only the current panel however wide the screen — only the display changes. It, `linkNavigation` and `maxWidth` are live: pass a proxied options object and a change is adopted in place, every panel keeping its state.
+- Only one routed `S.main()` can be mounted at a time; a second one throws, since the URL is global. Nothing else is.
+- Aberdeen's own `route.go()` works, but builds the whole stack from the path; prefer the stack's methods. A guard your app registered with `route.setGuard` keeps working — Staffa registers none of its own.
+- Deep links need your static server to serve the app for unknown paths (the usual SPA fallback; `-P` for `http-server`, as in the demo command below).
 
 ## Components
 
-Components share naming conventions for options: `attrs` (outermost element), `contentAttrs` (children-holding element), `inputAttrs` (form control element), and `<region>Attrs` (sub-regions like `headerAttrs`/`footerAttrs`). Form components consistently support `label`, `help`, `error`, `disabled`, `required`, `name` through the `drawField()` helper.
-
-### 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 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.
-- **`S.form(opts | content)`**: form aligning fields in a column or responsive grid, with an `actions` bar. Prevents the default page reload.
-
-### Form fields
-
-- **`S.textline(opts)`**: single-line input (`text`, `password`, `email`, `number`, `tel`, `url`, `search`, dates, ...).
-- **`S.textarea(opts)`**: multi-line input.
-- **`S.checkbox(opts)`**: labelled checkbox.
-- **`S.select(opts)`**: single-select dropdown backed by native `<select>` (styled control, OS dropdown).
-- **`S.autocomplete(opts)`**: type-ahead combobox with `multi` (chips), `allowCustom` (free text), `required`, and dynamic `options`.
-
-### Dialogs
+Every option of every component is documented in TSDoc on its `…Options` interface. Options share naming conventions: `attrs` (outermost element), `contentAttrs` (the children-holding element), `inputAttrs` (the form control) and `<region>Attrs` (`headerAttrs`, `footerAttrs`, …) — all Aberdeen attr/style strings, applied last so they can override. Form components consistently support `label`, `help`, `error`, `disabled`, `required` and `name`, and two-way binding through `bind: A.ref($obj, "key")`.
 
-- **`S.dialog(opts)`**: modal dialog with backdrop and fade transition. The `content` slot receives a `close()` function. Lifecycle is tied to the calling scope (disappears when cleaned up). Nesting stacks correctly.
-- **`S.alert(msg)` / `S.confirm(msg)` / `S.prompt(msg, initial?)`**: promise-returning shortcuts.
+- **Layout & containers**: `main` (the app shell: sticky header, optional nav sidebar that collapses to a hamburger on narrow screens, scrollable content area or [panel routes](#panel-stack-navigation), footer; `closeNav` dismisses the collapsed nav), `box`, `form`, `tabs`, `scrollStrip` (+ `revealInStrip`).
+- **Form fields**: `textline`, `textarea`, `checkbox`, `select`, `autocomplete`.
+- **Actions**: `button`, `iconButton`, `buttonGroup`, `buttonChooser`.
+- **Overlays & feedback**: `dialog` (+ `alert`, `confirm`, `prompt`), `menu`, `menuButton`, `showFloatingMenu`, `addContextMenu`, `toast`, `addTooltip`.
 
-### Actions
+`src/index.ts` is the authoritative list of exports.
 
-- **`S.button(opts | text)`**: button surface; restyle via `attrs` (e.g. `.danger`, `.outlined`), plus `size`, `disabled`, `icon`, `href` (renders `<a role=button>`). Defaults to filled `.primary`.
-- **`S.iconButton(opts)`**: a bare glyph in a square hit area — no fill, no border, ink that lifts on hover. For chrome that mustn't compete with what it sits beside: the app shell's ✕ and ☰ are made of it, and it's usually what a page's `actions` want.
-- **`S.buttonGroup(opts)`**: groups buttons, `attached` (segmented) or `spaced`.
-- **`S.buttonChooser(opts)`**: single-select segmented control bound to a value.
+### Keyboard shortcuts
 
+Menu items and buttons take a `key` option, and `S.bindKey(key, description, press)` binds a shortcut with no button to carry it, for as long as the calling scope lives. A key is spelled `"mod+k"` (⌘ on a Mac, Ctrl elsewhere), `"shift+f2"`, `"mod+shift+b"`, or a bare `"?"` — case doesn't matter, and no modifiers besides `mod` and `shift` are offered. Component shortcuts are announced to screen readers, and keystrokes a focused field or link owns are left to it. While a modal dialog is open only its own shortcuts fire, and binding a taken combination shadows the earlier binding until the new scope dies; `bindKey`'s docs describe the `"global"` and `"local"` modes that bend these rules. `?` pops an overview of exactly what a keypress could do right now, given where focus is — a cheat-sheet, not a modal: any keypress closes it and still lands, and Esc merely dismisses it; `S.setKeyHelp(false)` turns it off. Omit `press` to merely list a key your app handles by other means.
 
 ### Icons
 
-Staffa ships the full [Lucide icon set](https://lucide.dev/icons/) as named exports. Import only the ones you use, so a bundler tree-shakes the rest (the whole set is ~82 kB gzipped):
-
-Each icon is a draw function usable anywhere a slot is accepted (e.g. a button `icon`), or called directly. Customize per call, or globally via `setDefaults()`:
+Staffa ships the full [Lucide icon set](https://lucide.dev/icons/) as named exports from `staffa/icons`. Import only the ones you use, so a bundler tree-shakes the rest (the whole set is ~82 kB gzipped). Each icon is a draw function usable anywhere a slot is accepted, or called directly:
 
 ```ts
 import * as S from "staffa";
@@ -395,21 +246,11 @@ S.button({ content: "Save", icon: bell });
 sparkles({ size: "1.5em", color: "var(--s-primary)", strokeWidth: 1.5 });
 ```
 
-Options: `size`, `color` (defaults to `currentColor`), `strokeWidth`, `cap`, `join`, `attrs`.
-
-### 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. A menu closes itself when the page navigates.
-- **`S.menu(opts)`**: the same menu rows drawn in place — for a nav or settings column of your own. Items with nested `items` form a collapsible tree; `onLeafSelect` fires only when a leaf is picked, never for a branch unfolding.
-- **`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.
-
-Two-way binding uses Aberdeen proxies: pass `bind: A.ref($obj, "key")` to form fields.
+Options: `size`, `color` (defaults to `currentColor`), `strokeWidth`, `cap`, `join`, `attrs` — per call, or globally via `setDefaults()` from `staffa/icons`.
 
 ## Browser (no bundler)
 
-`staffa/all.js` is a pre-built ESM bundle. Use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap):
+`staffa/all.js` is a pre-built ESM bundle with all components, but not the icons. Use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap):
 
 ```html
 <script type="importmap">
@@ -429,40 +270,29 @@ Two-way binding uses Aberdeen proxies: pass `bind: A.ref($obj, "key")` to form f
 </script>
 ```
 
-It includes all components, but not the icons.
-
 ## Extending Staffa
 
-Staffa is designed for extension. A component is simply a plain function taking a typed options object and drawing Aberdeen DOM. This section explains the philosophy so extensions follow the same patterns.
+Staffa is designed for extension: a component is simply a plain function taking a typed options object and drawing Aberdeen DOM. These principles are how the built-in ones are written, and how yours should be too.
 
 ### Design principles
 
 1. **Components are functions**. They take one typed options object, emit Aberdeen DOM, and *usually* return nothing.
-
 2. **Reuse option types.** Define options by extending `ContentOptions` (for layout components) or `FieldOptions` (for form controls) from `src/core.ts` and `src/components/field.ts`. Don't reinvent fields like `attrs`, `label`, `help`, etc.
-
 3. **Reach for reactivity deliberately.** Pass option strings straight to `A` as positional args (the caller's scope). Only wrap a dedicated `A(() => ...)` scope where it matters: input elements (recreation loses focus), or large subtrees you don't want to redraw. Use `A.peek(() => ...)` when you need a value but must not subscribe.
-
-4. **Build on surfaces.** Mark elements `.s-s` and add `.neutral` or an accent role (`.primary`, `.danger`, …) plus an optional variant. Inside them, use the contextual CSS variables (`$s-text`, `$s-bg`, `$s-muted`, `$s-accent`, `$s-faint`, ...) so components adapt to wherever they're nested. Hard-coding colors in components shouldn't be needed, but if you must, make sure you set *both* foreground and background.
-
+4. **Build on surfaces.** Mark elements `.s-s` and add `.neutral` or an accent role (`.primary`, `.danger`, …) plus an optional variant. Inside them, use the contextual CSS variables (`$s-text`, `$s-bg`, `$s-muted`, `$s-accent`, `$s-faint`, ...) so components adapt to wherever they're nested. Hard-coding colours shouldn't be needed, but if you must, set *both* foreground and background.
 5. **No outer margins.** Components don't margin themselves; spacing is the parent's job. Content components set default `padding` on the content element; `contentAttrs` overrides it.
-
-6. **Make everything styleable.** Provide `attrs`, `contentAttrs`, `inputAttrs`, and `<region>Attrs` hooks so callers can customize. Apply `attrs` last so it can override component classes.
-
+6. **Make everything styleable.** Provide `attrs`, `contentAttrs`, `inputAttrs` and `<region>Attrs` hooks so callers can customize. Apply `attrs` last so it can override component classes.
 7. **Use semantic HTML and ARIA.** Prefer native elements (`<button>`, `<label>`, `<form>`, `<section>`) and native behaviour. Add ARIA only where semantics fall short (e.g. tabs, combobox).
-
-8. **Use CSS.** Use `A.insertGlobalCss({...})` at module top level to provide (nested) CSS styling for your component. Give your top-level element the `s-<component-name>` class. Avoid inventing further classes; lean on nesting (`&` for the element, bare key for descendants) and element/structural selectors.  
-
+8. **Use CSS.** Use `A.insertGlobalCss({...})` at module top level to provide (nested) CSS styling for your component. Give your top-level element the `s-<component-name>` class. Avoid inventing further classes; lean on nesting (`&` for the element, bare key for descendants) and element/structural selectors.
 9. **Reuse form controls.** Use `drawField()` and call `applyControlAttrs()`.
-
 10. **Function over form.** Provide enough contrast. Stick to UI conventions to help users; buttons have a rounded border, links are underlined, text input background is white, etc.
 
 ### Adding a component to Staffa
 
-The previous section is good advice for any project-specific custom, but should definitely be followed for any new components to be included in Staffa. In addition, you'd want to: 
+The principles above are good advice for any project-specific component, but must be followed for one to be included in Staffa. In addition:
 
 1. Create `src/components/<name>.ts`.
-2. Define `<Name>Options` extending `ContentOptions`, `FieldOptions`, or a plain interface. Add TSDoc on every option.
+2. Define `<Name>Options` extending `ContentOptions`, `FieldOptions`, or a plain interface. Add TSDoc on every option — that TSDoc *is* the API documentation.
 3. Add a TSDoc `@example` on the function.
 4. Register in `src/index.ts` (the `S` object + type re-export).
 5. Add it to the demo, cover it in the visual tests (`tests/*.spec.ts`), and run `npm run build` and `npm run typecheck`.
@@ -484,9 +314,7 @@ The visual tests (`tests/*.spec.ts`) need a build first (`npm run build`); they
 
 ## AI skill
 
-If you use Claude Code, GitHub Copilot or another AI agents that supports Skills, Staffa includes a `skill/` directory that provides specialized knowledge to the AI about how to use the library effectively.
-
-To use this, it is recommended to symlink the skill into your project's `.claude/skills` directory:
+For Claude Code, GitHub Copilot or any other agent that supports Skills, Staffa ships a `skill/` directory holding this README plus the generated API reference. Symlink it into your project:
 
 ```sh
 mkdir -p .claude/skills
@@ -497,4 +325,4 @@ ln -s ../../node_modules/staffa/skill .claude/skills/staffa
 
 What changed in each release, and what to do about the breaking ones, is in [CHANGELOG.md](CHANGELOG.md).
 
-*Hint:* the recommended update strategy for a library this young is: don't. Pin it, and read the changelog before you move.
+*Hint:* the recommended update strategy for a library this young is: don't. Pin it, and read the changelog before you move. This goes double if you've overridden Staffa's CSS.