@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/docs/list-detail-dialog.md

@@ -0,0 +1,100 @@
+# List-detail dialog
+
+`@kerfjs/ui/list-detail-dialog` is the modal form of a list-detail layout: a
+list column beside the selected item's detail, each running the dialog's full
+height. It is one of three dialog types:
+
+| Type                                                           | Use it for                                               |
+| -------------------------------------------------------------- | -------------------------------------------------------- |
+| `DialogSurface` ([surface-scaffold.md](surface-scaffold.md))   | One pane: a title, a body, and footer buttons.           |
+| `ListDetailDialog` (this page)                                 | Pick a record from a list and show its detail beside it. |
+| `WorkbenchDialog` ([workbench-dialog.md](workbench-dialog.md)) | An editing task with side panels.                        |
+
+```ts
+import {
+  ListDetailDialog,
+  openDialog,
+} from "@kerfjs/ui/list-detail-dialog";
+import { deviceClass } from "@kerfjs/ui/device-class";
+```
+
+In a browser bundler that honors the `browser` export condition, the import
+also loads the stylesheets of every component it renders (DialogSurface,
+SplitView, NavStack, Pane, and the toolbar components). Without that
+condition, import `@kerfjs/ui/list-detail-dialog.css`, which pulls in the same
+stylesheets, or `@kerfjs/ui/styles.css`.
+
+## Where things go
+
+- **The detail column owns the dialog's identity.** Its header toolbar carries
+  the primary title (an xl level-2 heading, with an optional `description`
+  line), the `actions` you pass, and the close control, last. Record actions go
+  in the detail `footer`, pinned below the scrolling detail.
+- **The list column is secondary.** Its header carries `list.title` at the
+  default toolbar size, so it reads as pane identity beside the primary title,
+  followed by your `list.toolbar` controls. An add control or count can go in
+  `list.footer`.
+- **The surface draws no header.** Both columns start at the dialog's top
+  edge, so the divider between them runs the dialog's full height.
+- **The description is yours to name.** The detail `description` describes the
+  selected record, not the dialog, so it is not the dialog's accessible
+  description. Pass `describedBy`, the id of app-owned summary copy, to render
+  `aria-describedby` on the dialog.
+
+Each column is a `Pane`: its header and footer stay pinned and its content
+scrolls on its own. Pass content that owns its geometry, usually a `List`.
+
+## Responsive by device class
+
+The component is declarative. The app derives `compact` from the device class
+and tracks its own selection and, on compact devices, whether the detail is
+pushed:
+
+```tsx
+const device = deviceClass();
+const selected = signal("atlas");
+const detailOpen = signal(false);
+
+<ListDetailDialog
+  id="projects"
+  label="Project Details"
+  compact={device.value.compact}
+  detailActive={detailOpen.value}
+  backLabel="Back to Projects"
+  list={{
+    title: "Recent Projects",
+    content: <List>{rows}</List>,
+  }}
+  detail={{
+    title: project.name,
+    content: <List>{details}</List>,
+    footer: actions,
+  }}
+/>;
+```
+
+- **Roomy** (`compact: false`): a modal of `size` `large` with a definite
+  height (default 560px, bounded by the viewport; pass `maxHeight` instead to
+  size it to its content). The list column is 280px, at most 40% of the
+  dialog, by default; set `list.width` like SplitView's `listWidth`.
+- **Compact** (`compact: true`): the dialog fills the screen and becomes a
+  `NavStack`. The list is the root view (titled `list.title`, with its toolbar
+  controls); `detailActive` pushes the detail (titled `detail.title`, with its
+  `actions`). Every view keeps the close control, and each view's `footer` is
+  pinned below it. The stack's back control dispatches `nav-back`; set
+  `detailActive` back to `false` in response. Wire `wireNavStack` above it for
+  the push and pop motion.
+
+Render one `ListDetailDialog` for both presentations, so crossing the compact
+breakpoint while it is open morphs it in place and it stays open.
+
+## Opening and closing
+
+It is a `DialogSurface` underneath: open it with `openDialog(element)` and close
+it with `closeDialog(element)`, the close control, Escape, an element with
+`data-dialog-close`, or (with `lightDismiss`) a press on the backdrop. Both
+functions are re-exported from this subpath. Give sibling dialogs distinct
+`rootAttributes['data-key']` values so a re-render morphs each into itself.
+
+See the [list-detail dialog recipe](recipes.md#list-detail-dialog) for a
+complete, production-backed example.

package/docs/manual-test-plan.md

@@ -0,0 +1,29 @@
+# Manual test plan
+
+Checks that automation cannot make truthfully. Run the catalog with
+`npm run dev:lan` and open the printed URL on the device (see
+[`ux-demo.md`](ux-demo.md)). Record the device, OS, and browser versions and the
+result on the tracking ticket.
+
+## DialogSurface bottom sheet: virtual keyboard and safe areas
+
+Route: `?component=surface-scaffold`, example "Resizable Bottom Sheet". Run on
+an iPhone (Safari) and an Android phone (Chrome).
+
+1. Open the sheet and focus the Message field. The keyboard pushes the sheet's
+   content above it, and the panel runs behind the keyboard with no gap.
+2. Rotate the phone, and pinch-zoom while the keyboard is open. The content
+   stays clear of the keyboard; while zoomed, the measured overlap is 0 and the
+   page relies on `dvh`.
+3. Dismiss the keyboard. The bottom padding returns to the home-indicator safe
+   area, and the sheet's square bottom edge meets the screen edge.
+4. Drag the grabber, with and without the keyboard open. The sheet resizes
+   between its minimum height and the screen less the top safe area.
+
+Playwright cannot raise a virtual keyboard; the overlap formula is unit-tested
+(`tests/unit/dialog-surface-controller.test.tsx`) and a simulated keyboard is covered
+in `tests/browser/dialog-bottom-sheet.spec.ts`.
+
+## Automated coverage summary
+
+Nothing has moved from this plan into automation yet.

package/docs/message-composer.md

@@ -0,0 +1,156 @@
+# MessageComposer
+
+`MessageComposer` (`@kerfjs/ui/message-composer`, CSS `@kerfjs/ui/message-composer.css`) is the chat
+or prompt composer: the place a person writes a message, assistant prompt, or
+reply and sends it with a trailing action. It replaces app-owned composer
+chrome, such as a `wa-textarea` and a button wrapped in application CSS that
+draws a frame, a focus border, and a shadow.
+
+## Contract
+
+```tsx
+<MessageComposer
+  id="assistant-message"
+  name="message"
+  label="Message"
+  placeholder="Ask about this build"
+  hint="Answers use the latest nightly build."
+  minRows={1}
+  maxRows={8}
+  trailing={
+    <Button tone="brand" action="send-message">
+      Send
+    </Button>
+  }
+/>
+```
+
+- **Frame.** The root is a raised surface (`--kui-color-surface-raised`) with
+  the standard 1px neutral border, the large radius (`--kui-radius-l`), and
+  `--kui-shadow-l`. While focus is anywhere within it, including on a trailing
+  action, the border turns `--kui-color-brand-border-loud`. The frame owns
+  8px padding, so a composer placed 8px from a container edge puts its text on
+  the same 17px column as a `List` of content items beside it.
+- **Field.** A native, borderless `<textarea>` named by `label`. It sizes to
+  its content with `field-sizing: content`, between `minRows` (default 1) and
+  `maxRows` (default 8) lines, and scrolls past the maximum. Both bounds are
+  positive integers, and `maxRows` is at least `minRows`; otherwise `MessageComposer`
+  throws a `RangeError`. In an engine without `field-sizing`, the field keeps
+  a fixed height of three lines, clamped to the bounds, and scrolls.
+- **Action row.** Below the field, a compact `Toolbar` (footer semantics,
+  named "<label> Actions") that the composer insets for you. Its leading zone
+  holds optional `leading` controls, such as an attach button or a model
+  `Select` in a `ToolbarControlGroup`, then the optional quiet `hint`; its
+  trailing zone holds `trailing`, normally one brand Send `Button`. Every
+  toolbar convention applies, from control groups to responsive relocation.
+  With an `id`, the hint is the field's accessible description
+  (`<id>-hint`).
+- **Value.** `value` seeds the field (a restored draft, or `''`). The app
+  reads the textarea in its send action, clears it, and re-renders.
+- **Disabled.** `disabled` disables the field; the app disables or marks busy
+  its own actions.
+- **Placement.** Pass it as a `DialogSurface`'s `footer`, or use `slot` to
+  assign it to a web component slot. `rootAttributes` takes safe `data-*`
+  identity.
+- **Enter to send.** `submitOnEnter` opts in to the keyboard contract below;
+  it marks the root `data-submit-on-enter="true"` (protected from
+  `rootAttributes`) and gives the field `aria-keyshortcuts="Enter"`.
+
+The app owns sending, any other keyboard shortcut, what a sent message looks
+like, and where the composer sits.
+
+## Enter to send
+
+Set `submitOnEnter` and call `wireMessageComposers` once over an ancestor of every
+such composer; it returns a disposer:
+
+```ts
+import { wireMessageComposers } from '@kerfjs/ui/wire-message-composers';
+
+const stopMessageComposers = wireMessageComposers(app);
+```
+
+In an opted-in composer's field:
+
+| Key                                          | Result                                                                                                    |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Enter, Cmd+Enter, Ctrl+Enter                 | Clicks the composer's **first trailing action**; the newline is suppressed.                               |
+| Shift+Enter, Alt+Enter                       | Inserts a newline, as in any textarea.                                                                    |
+| Enter committing an IME composition          | Left to the input method: `isComposing`, keyCode 229, or between `compositionstart` and `compositionend`. |
+| Enter on an empty or whitespace-only message | Nothing: no send and no newline.                                                                          |
+| Auto-repeating Enter (key held down)         | Nothing.                                                                                                  |
+
+The first trailing action is the first `button` (a `Button`), `wa-button`, or
+`[data-action]` element inside `actions`. Clicking it means the keyboard send
+runs the same delegated `data-action` handler as a pointer send, so the app
+writes one send handler that reads the field, clears it, and re-renders. The
+click does not move focus, so the person keeps typing. Nothing is sent while
+the field is `disabled`, or while that action has a `disabled` attribute or
+property, `aria-busy="true"` (a busy `Button`), a `loading` attribute (a busy
+`wa-button`), or `aria-disabled="true"`; the Enter is still suppressed, so a message waiting on
+a busy Send does not gain a newline.
+
+Leave `submitOnEnter` off for a long-form prompt where Enter should be a
+newline, and send with the action alone. A visible `hint` may also state the
+shortcut ("Enter to send, Shift+Enter for a new line") when the audience may
+not expect it; `aria-keyshortcuts` already announces it to assistive
+technology.
+
+## In a chat dialog
+
+A chat dialog floats the composer over its transcript. Use a `DialogSurface`
+with `bodyLayout="fill-last"` and `footerPresentation="floating"` (and
+`footerInset="none"`, since the composer draws its own frame), and slot the
+composer into the footer:
+
+```tsx
+<DialogSurface
+  id="assistant"
+  label="Assistant"
+  height={remify(560)}
+  bodyInset="none"
+  bodyLayout="fill-last"
+  footerPresentation="floating"
+  footerOffset={remify(8)}
+  footerInset="none"
+  footer={<MessageComposer submitOnEnter id="assistant-message" name="message" label="Message" placeholder="Ask about this build" trailing={send} />}
+>
+  <StateBanner title="Answers use the latest nightly build." tone="neutral" />
+  <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">{messages}</List>
+</DialogSurface>;
+```
+
+The floating footer is transparent, so the composer's own frame and shadow
+lift it over the transcript. The transcript's `scrollClearance="block-end"`
+lets messages scroll visibly beneath the composer while the last one still
+comes to rest above it, following the composer's measured height as it grows.
+Without the opt-in, the dialog body reserves that height below the transcript
+instead.
+
+## Do not
+
+- Wrap it in a framed `ContentItem`, card, or bordered container; it owns its
+  frame, padding, and shadow.
+- Style its field, frame, or action row from application CSS. A variation it
+  does not offer is a component gap.
+- Use it for an ordinary form field submitted with the rest of a form; use
+  a `multiline` `TextField`.
+
+## Verification
+
+`tests/unit/message-composer.test.tsx` covers serialization, the hint description,
+row bounds, and protected attributes; `tests/unit/wire-message-composers.test.tsx`
+covers the Enter-to-send matrix (modifiers, IME, empty, repeat, disabled
+field and actions, first action only, disposal). `tests/browser/message-composer.spec.ts` covers
+the focus-within border, growth up to `maxRows` and then scrolling, the action
+row geometry, and the send flow at wide and phone widths, and, in Chromium,
+Firefox, and WebKit, Enter, Shift+Enter, Cmd/Ctrl+Enter, empty messages, and
+IME composition (dispatched composition events and keyCode 229). In
+Chromium it also drives a real IME composition through the DevTools protocol
+(`Input.imeSetComposition`, then `Input.insertText` to commit). That test
+asserts the engine's own event order: an Enter keydown flagged `isComposing`
+while composing, the committing `Process` keydown with keyCode 229, then
+`compositionend`. None of those sends, the committed text lands in the field,
+and the next Enter sends it;
+`tests/browser/surface-scaffold.spec.ts` covers the composer in the floating
+footer of the chat dialog, including Enter to send.

package/docs/nav-stack.md

@@ -5,14 +5,19 @@ and out over one another while the top chrome settles. A **single-pane layout is
 a `NavStack` with one entry**. It is one of the opt-in app layouts (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
-Import the component and its companion stylesheet:
+Import the component and its wiring helper:
 
 ```ts
-import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
-import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
-import '@kerfjs/ui/nav-stack.css';
+import { NavStack, type NavStackView } from "@kerfjs/ui/nav-stack";
+import { wireNavStack } from "@kerfjs/ui/wire-nav-stack";
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads NavStack's stylesheet and those of the components it renders internally
+(`Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `Pane`, `List`, `LucideIcon`). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/nav-stack.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
 ## State lives in the app
 
 Like every `@kerfjs/ui` component, `NavStack` is declarative: the app owns the
@@ -20,28 +25,336 @@ stack as a `signal<NavStackView[]>`, `NavStack({ views })` renders it, and
 `wireNavStack` animates the transitions.
 
 ```tsx
-const views = signal<NavStackView[]>([{ key: 'inbox', title: 'Inbox', content: <InboxView /> }]);
+const views = signal<NavStackView[]>([
+  {
+    key: "inbox",
+    toolbar: { title: "Inbox" },
+    content: <InboxView />,
+    bottomToolbar: {
+      label: "Inbox status",
+      leading: <InboxStatus />,
+    },
+  },
+]);
 
 // render inside mount():
 <NavStack id="mail" label="Mail" views={views.value} />;
 
 // once, after first render:
-const dispose = wireNavStack(root, { onBack: () => { views.value = views.value.slice(0, -1); } });
+const dispose = wireNavStack(root, {
+  onBack: () => {
+    views.value = views.value.slice(0, -1);
+  },
+});
 
 // push / pop by editing the signal:
-views.value = [...views.value, { key: id, title: 'Message', content: <MessageView id={id} /> }];
+views.value = [
+  ...views.value,
+  { key: id, toolbar: { title: "Message" }, content: <MessageView id={id} /> },
+];
 ```
 
 `NavStack` renders every entry stacked, the last one active and the rest kept
-mounted (so their DOM state and focus survive) but hidden. Each entry carries a
-`key` (stable identity), `content`, an optional `title`, and optional per-view
-`toolbar` actions. The back control appears automatically once the stack has more
-than one entry; `wireNavStack`'s `onBack` is where the app pops its own signal.
+mounted (so their DOM state survives) but hidden. Each entry carries a
+`key` (stable identity), `content`, an optional `toolbar` object with `title`,
+`leading`, `center`, and `trailing` groups, and an optional structured
+`bottomToolbar`. The component-level structured
+`bottomToolbar` remains a persistent fallback for views that do not provide one.
+Each view can also provide `header`, `footer`, `headerList`, `footerList`, and
+`pane` configuration, as a `WorkbenchStaticPanel` does. With any of these,
+the view renders a `Pane`: its header and footer stay pinned around the view's
+scrolling content, and slide with that view during navigation. The header and
+footer list configuration forwards to their `List`s; `pane` forwards
+`contentElement`, `contentLabel`, `separators`, `safeAreaEdges`,
+`chromeDividers`, `appearance`, `deepInset`, `scrollClearance`, `headerPresentation`, `tabIndex`,
+and `outlined` to the Pane. Without those fields, the view
+keeps its simple direct scroll area. Use `pane: { appearance: "sunken" }` for a
+lowered scrolling work surface.
+The back control appears automatically once the stack has more than one entry;
+`wireNavStack`'s `onBack` is where the app pops its own signal.
+
+See [Lowered work surfaces](layout.md#lowered-work-surfaces) for nested Pane
+and layout content.
+
+## The top toolbar
+
+The top chrome is a real `Toolbar`, so it follows the same zone,
+group, and responsive rules as every other toolbar. Its leading zone holds the
+back control (a contained, bordered `ToolbarControlGroup`, shown once the stack has
+depth), then `toolbar.leading`. `toolbar.trailing` fills the trailing zone.
+Give each zone `ToolbarControlGroup`s or `ToolbarText`, as in any toolbar.
+
+Where `toolbar.title` goes depends on the back control:
+
+- **At the root** (no back control) the title is a filling `ToolbarText` at
+  the end of the leading zone, so it reads left-aligned.
+- **Once the stack has depth**, the title is the center zone's only child and
+  the toolbar is `centerAlign="balanced"`, like a platform navigation bar. The
+  title sits on the bar's midpoint while the sides leave room, moves away from
+  a wider side when they do not, and truncates with an ellipsis before it
+  reaches the back control or a trailing group. It keeps the root title's
+  full-strength text color at its smaller size. This overrides a configured
+  `centerAlign`, which applies to view-owned center content.
+- **A view that sets `toolbar.center`** owns the center zone, so its title
+  stays left-aligned in the leading zone at any depth.
+
+Configure the toolbar with `toolbarConfig` instead of styling it:
+
+```tsx
+<NavStack
+  id="mail"
+  label="Mail"
+  views={views.value}
+  backText={previousTitle}
+  toolbarConfig={{
+    headingLevel: 1,
+    titleSize: "xlarge",
+    dividerSides: "b",
+    responsive: "wrap",
+  }}
+/>
+```
+
+- Each view's `toolbar` can forward the `Toolbar` configuration (`dividerSides`,
+  `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and its `label`,
+  `titleSize`, and `headingLevel`. A view value overrides the corresponding
+  `toolbarConfig` default. Its `bottomToolbar` forwards the same `Toolbar`
+  configuration and has a required accessible `label`.
+- `toolbarConfig` supplies stack-wide defaults (`dividerSides`,
+  `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and adds
+  `label` (the toolbar's accessible name), `titleSize` (the title's
+  `ToolbarText` size; default `xlarge` at the root, where the title is the page
+  heading, and `large` once a back control shares the bar; a Workbench panel's
+  stack keeps `large` at every depth), and `headingLevel` (expose the title as
+  a heading; default a plain span). The defaults keep the stack's own chrome:
+  no divider, the standard Toolbar height (a 44px control band with 8px above and below), and the top and side safe-area edges
+  claimed.
+- `backIcon` replaces the default chevron-left icon. `backText` adds visible
+  text beside it (for example, the previous view's title); visible text names
+  the control, so `backLabel` applies only to the icon-only control.
+
+`panelToggle` supplies a persistent final group in the trailing zone of every
+view's top toolbar. `Workbench` uses it for a navigation panel's standard
+collapse toggle; the active view still owns the preceding toolbar groups.
+
+The catalog's **Configured Toolbar** example shows these together: a level-2
+heading title over a bottom divider, leading and center groups on the root
+view, a trailing group on the pushed view, and `backText` set to the previous
+view's title.
+
+Focus follows the controlled stack automatically. On push, `wireNavStack`
+remembers the focused descendant of the departing view and moves focus into the
+new top view. On pop it restores that exact descendant when it still exists. A
+new view prefers a descendant marked `data-nav-focus`, then its first enabled
+focusable descendant, and finally the view container itself. Use
+`data-nav-focus` for a heading or primary control when DOM order is not the best
+initial reading position; it may use `tabindex="-1"` for programmatic focus.
+When a remembered control was removed during the controlled rerender, the same
+fallback order applies. While focus rests on the view container itself (it
+had nothing focusable, such as an inert loading placeholder), a later
+re-render that morphs away the temporary `tabindex` keeps it there, and once
+content with a focus target arrives under the same key, focus moves to it;
+focus the person moved elsewhere is never reclaimed. Disposing the helper stops future transitions and
+cleans up any temporary fallback `tabindex` it added.
+
+## Separators and scroll dividers
+
+`separator="auto"` (the default) draws a line under the top chrome and above
+the optional bottom toolbar when the active view's Pane has
+`appearance="sunken"`, even if its content fits and no scroll wiring runs. The
+line follows the active view on push and pop. Set `separator="hidden"` to hide
+both stack-owned edges, including lines requested by `chromeDividers`. The
+existing 1px edges change color without moving the content. A view's own Pane
+header and footer separators remain controlled by that Pane.
+
+For a flat active view, the stack draws no permanent line. With
+`wireScrollDividers(appRoot)` installed (see
+[Layout › Scroll dividers](layout.md#scroll-dividers)), the top chrome shows a
+line along its bottom edge only while the active view's content is scrolled
+beneath it, and the bottom toolbar a line along its top edge only while more
+content lies below it — neither when the content fits. The line follows the
+active view across a push or pop. The chrome's line is overlaid on its bottom
+edge and the bottom toolbar's is its always-present 1px top border, colored
+only while shown, so neither ever moves the chrome or the content. When the view's only child is a `Pane`,
+the line keys on whichever actually scrolls — the view, or the Pane's content —
+and a Pane header or footer draws its own boundary instead. An explicit
+`toolbarConfig.dividerSides` still draws a permanent Toolbar edge.
+
+`chromeDividers` configures both lines for flat views, with the same values as a `Pane`'s:
+`scroll` (the default) follows the scroll state above and draws nothing until
+the wiring runs; `always` keeps both lines, with or without the wiring; `none`
+drops them even when the wiring reports scroll state. A sunken active Pane still
+shows the separator unless `separator="hidden"`. This option does not change the
+top Toolbar's own `dividerSides`.
+
+```tsx
+<NavStack id="settings" label="Settings" views={views.value} chromeDividers="always" />
+```
+
+## Background colors
+
+`background` paints the stack, its docked chrome and bottom toolbar, and every
+view in an app-chosen color from `@kerfjs/ui/css-values` instead of the
+surface. One view's own color goes in its `pane: { background }`, which paints
+over the stack's. Overlay chrome keeps the chrome material. The app keeps text
+at AA over the color; forced colors paint `Canvas`. See
+[Background colors](layout.md#background-colors).
+
+```tsx
+<NavStack id="music" label="Music" views={views.value} background={uiColor("surface-raised")} />
+```
+
+`tint={{ color, scheme }}` re-derives the stack's surface and text tokens from
+an app color instead, so its chrome, views, and content all take on the color
+with text kept at AA. See [Tinted surfaces](layout.md#tinted-surfaces).
+
+## Overlay chrome
+
+`chromePresentation="overlay"` lays the top chrome over the active view's top
+edge, like an iOS navigation bar, instead of docking it above the view
+(`"docked"`, the default). The chrome paints the shared chrome material,
+`--kui-chrome-material` behind `--kui-chrome-material-filter`, so content
+scrolls visibly, blurred, beneath it.
+
+```tsx
+<NavStack id="mail" label="Mail" views={views.value} chromePresentation="overlay" />
+```
+
+- **`wireNavStack` measures it.** The helper you already call for transitions
+  reads the live chrome's border-box height with a `ResizeObserver`, publishes
+  it on the stack root, and marks the root `data-chrome-overlay="measured"`.
+  Only then does the chrome leave its band. Unwired, or with `hideToolbar`, the
+  chrome stays docked, so it never covers content it has not measured. The
+  measurement follows the chrome as its title wraps, text grows, or a pushed
+  view changes its toolbar. A re-render that strips the measurement gets it
+  back before paint.
+- **Every view clears it automatically.** The measured height becomes the
+  viewport's block-start edge context (`--kui-edge-inset-block-start`), the
+  same context that carries safe areas. A plain view pads and scroll-pads by
+  it, a sole `Pane` adds it to its content's (or its header's) block-start
+  inset, and a nested layout hands it on. The first item rests just below the
+  chrome, and anything focused or scrolled into view stops clear of it. No
+  `scrollClearance` prop is involved, so a Pane that also opts into
+  `scrollClearance` does not clear the chrome twice.
+- **Safe area.** The chrome keeps claiming the top safe area: its toolbar pads
+  for it while the material paints through it. The measured height already
+  includes that padding, so views clear the chrome and the safe area exactly
+  once.
+- **Transitions.** Only the live chrome is measured, never a cross-fading
+  copy. An overlay bar (top chrome or bottom toolbar) cross-fades its
+  contents, never its material: the live bar keeps the material at full
+  opacity while its new contents fade in, and the copy fading out above it
+  carries only the old contents, so the sliding views never show through the
+  chrome mid push or pop. The incoming view settles at the incoming chrome's
+  clearance.
+- **Classic scrollbars.** Where the active view's scroller (the view, or a
+  sole header-less Pane's content) shows a classic, space-taking scrollbar,
+  `wireNavStack` measures it and the chrome ends where its track begins, so
+  the thumb and arrows stay visible and usable. An overlay scrollbar takes no
+  space and passes beneath the material like the content.
+- **Dividers.** With `wireScrollDividers`, the line under the chrome still
+  appears only while content is scrolled beneath it.
+- **Contrast.** The material keeps normal text at AA over any content. An
+  untoned `ToolbarText` in the chrome lifts itself: its title takes the normal
+  text color at every size and its `description` mixes the quiet color halfway
+  toward it, and a default-tone `ToolbarControlGroup` takes the normal text
+  color for its controls. Other quiet copy you place in the chrome has no such
+  lift, so keep it in the view (see
+  [Accessibility › Chrome material](accessibility.md#chrome-material)). The
+  material turns opaque under `prefers-reduced-transparency`,
+  `prefers-contrast: more`, or without `backdrop-filter`, and forced colors
+  paint `Canvas` with a `CanvasText` bottom edge.
+
+`SplitView`'s `compactStack.chromePresentation` and a Workbench navigation
+panel's `navStack.chromePresentation` forward the same option.
+`chromePresentation` governs only the top chrome; the bottom toolbar has its
+own option below.
+
+### Overlay bottom toolbar
+
+`bottomToolbarPresentation="overlay"` does the same for the bottom toolbar,
+like an iOS toolbar: it lies over the active view's bottom edge on the same
+chrome material instead of docking below the view (`"docked"`, the default).
+It is a separate prop, so either bar can be overlaid alone, and it mirrors
+`Pane.headerPresentation` and `DialogSurface.footerPresentation` in naming one
+edge.
+
+```tsx
+<NavStack
+  id="mail"
+  label="Mail"
+  views={views.value}
+  chromePresentation="overlay"
+  bottomToolbarPresentation="overlay"
+  bottomToolbar={{ label: 'Mail Actions', trailing: composeGroup }}
+/>
+```
+
+- **`wireNavStack` measures it.** It reads the live bottom toolbar's
+  border-box height (never a cross-fading copy's), publishes it on the stack
+  root, and marks the root `data-bottom-toolbar-overlay="measured"`. Only then
+  does the toolbar leave its band. Unwired, or while no bottom toolbar is
+  shown (a view without one and no stack-level fallback), it stays docked. The
+  measurement follows a view-owned toolbar as views push and pop, and a
+  re-render that strips it gets it back before paint.
+- **Every view clears it automatically.** The measured height becomes the
+  viewport's block-end edge context (`--kui-edge-inset-block-end`). A plain
+  view pads and scroll-pads by it, a sole `Pane` adds it to its content's
+  block-end inset (or its footer's, so the footer rests just above the
+  toolbar), and a nested layout hands it on. The last item rests just above
+  the toolbar, and anything focused or scrolled into view stops clear of it.
+- **Safe area.** The toolbar keeps claiming the bottom safe area (the home
+  indicator), and the measured height includes it, so views clear both exactly
+  once. Inside a `TabNavigator` scene the tab bar owns that edge, so the
+  stack's toolbar sits just above the tab bar and counts no safe area.
+- **Classic scrollbars and dividers.** The toolbar ends where a classic
+  scrollbar's track begins (a sole Pane with a footer ends its scroller above
+  the toolbar, so nothing needs leaving there). With `wireScrollDividers`, the
+  toolbar's top line still appears only while more content lies below.
+- **Contrast.** An untoned `ToolbarText` lifts itself as in the top chrome,
+  and a default-tone `ToolbarControlGroup` in either overlaid bar takes the
+  normal text color for its controls, so labels and icons keep AA over the
+  content beneath. The material has the same opaque fallbacks; in forced
+  colors the toolbar paints `Canvas` and its always-present 1px top border
+  becomes a `CanvasText` edge, which the measurement includes.
+
+`SplitView`'s `compactStack.bottomToolbarPresentation` and a Workbench
+navigation panel's `navStack.bottomToolbarPresentation` forward it too.
+
+### Clear chrome
+
+`chromePresentation="clear"` and `bottomToolbarPresentation="clear"` lay the
+bars over the active view like `overlay`, with the same measuring and edge
+insets, but fully transparent, for chrome over imagery. Keep their controls
+in glass control groups (`ToolbarControlGroup material="glass"`); the stack's
+own back control is one automatically under clear chrome. They stay
+clear while content scrolls beneath them; with `scrollEdge="material"` (or
+`"surface"`) a backing fades in gradually, opacity only, over
+`scrollEdgeDistance` pixels of scroll (default 60): behind the top chrome as
+the view's content scrolls beneath it, and behind the bottom toolbar until
+the content nears its end. Clear bars draw no scroll
+divider, turn opaque under reduced transparency or increased contrast, and
+paint `Canvas` in forced colors. See [Clear header](layout.md#clear-header).
+
+## Safe areas
+
+The stack paints through a device's unsafe areas. Its chrome pads for the top
+and side insets, its bottom toolbar for the bottom and side insets, and each
+view pads the remaining edges inside its scroller, so content scrolls under the
+unsafe area but can always be scrolled clear. A view whose only child is a
+`Pane` or layout lets that child own the insets. See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
 
 ## Transitions
 
 `wireNavStack(root, { onBack, duration? })` observes the rendered stack and
 animates each change: a pushed view slides in from the trailing edge; a popped
-view slides back off it over the revealed view. It returns a disposer. The
-animation honors `prefers-reduced-motion` (transitions collapse to instant) and
-`duration: 0` disables it. Applicable at every device size and inside dialogs.
+view slides back off it over the revealed view; and snapshots of the previous
+top and bottom chrome cross-fade into the active view's chrome. The preserved
+underlying view remains visible during a push, while remaining inaccessible.
+Starting transforms and opacity apply instantly before the transition begins.
+A new navigation settles the previous transition and cancels its pending frames
+and cleanup timers; disposal removes temporary copies and exiting views. Focus moves to
+the new top view independently of animation duration. It returns a disposer.
+The animation honors `prefers-reduced-motion` (transitions collapse to instant)
+and `duration: 0` disables it. Applicable at every device size and inside
+dialogs.