@kerfjs/ui 5.0.0-beta.98 → 5.0.0-beta.99

package/docs/layout.md

@@ -185,6 +185,62 @@ Firefox, scroll-state container queries only in Chromium, and neither lets
 the pinned chrome — a sibling of the scroller — read the scroller's state on
 its own. One wiring keeps the behavior identical in every engine.
 
+### Overlay header
+
+`headerPresentation="overlay"` lays a Pane's header over the top of its
+scrolling content instead of giving it its own row, the way platform
+navigation bars let content scroll visibly beneath a translucent bar:
+
+```tsx
+<Pane
+  label="Inbox"
+  headerPresentation="overlay"
+  header={<Toolbar label="Inbox" leading={<ToolbarText text="Inbox" size="xlarge" />} />}
+>
+  {messages}
+</Pane>
+```
+
+The header paints the shared chrome material, `--kui-chrome-material` (the
+surface at 80% opacity) behind `--kui-chrome-material-filter` (a blur and
+saturation backdrop filter), so content passing beneath it reads as softened
+color, not as competing text. The material becomes the opaque surface under
+`prefers-reduced-transparency: reduce` or `prefers-contrast: more`, and where
+the browser lacks `backdrop-filter`. In forced colors the header paints
+`Canvas` with a `CanvasText` bottom edge.
+
+`wireScrollDividers` measures each overlay header (its border-box height,
+safe-area padding included) with a `ResizeObserver` and publishes it on the
+Pane as the `--kui-scroll-clearance-block-start` context (see
+[Scroll clearance](#scroll-clearance)). The Pane's content clears it
+automatically, with no `scrollClearance` prop. At rest the first item sits just
+below the header. Mid-scroll, content passes beneath it, and anything focused
+or scrolled into view still comes to rest clear of it. The clearance follows
+the header as its title wraps or its text grows. The header draws its scroll
+divider as a docked header does, once content is scrolled beneath it. The
+wiring also marks the Pane `data-header-overlay="measured"`, and only then
+does the header move over the content. Until the wiring runs, the header stays
+docked in its own row, so it can never cover content it has not measured. A
+re-render that drops the measurement gets it back before paint.
+
+The overlay needs pinned chrome. With `chromePlacement="auto"`, the header
+stays docked. `PaneConfig` carries `headerPresentation`, so a Workbench
+`mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's
+`pane` can lay its header over its content the same way. Overlay-header text
+must stay at AA over whatever passes beneath: an untoned `ToolbarText` there
+takes the normal text color for its title and lifts its `description` toward
+it, and other quiet secondary copy belongs in the content (see
+[Accessibility › Chrome material](accessibility.md#chrome-material)).
+
+An overlay scrollbar (macOS by default) passes beneath the header like the
+content. A classic, space-taking scrollbar (Windows and Linux, or macOS with
+"always show scrollbars") stays uncovered: the wiring also measures the
+content's vertical scrollbar (`offsetWidth` beyond `clientWidth`) and publishes
+its inline size on the Pane as `--kui-pane-scrollbar-inline-size`, and the
+header ends where the scrollbar's track begins, so its thumb and arrow buttons
+remain visible and usable. The measurement follows the scrollbar as content
+starts or stops overflowing.
+
 A pane is safe-area aware. Its background and separators paint through a
 device's unsafe areas while its header, content, and footer pad for each side
 the pane still reaches; the content's block insets are scroll padding, so its
@@ -313,19 +369,24 @@ component's context stays allowed (see `KUI-L019`).
 
 ## Public roles and tokens
 
-| Need                                     | Class                        | Token / default                                                    |
-| ---------------------------------------- | ---------------------------- | ------------------------------------------------------------------ |
-| Unpadded header/content/footer structure | `Pane`, `.kui-pane`          | —                                                                  |
-| Scrolling pane content                   | `.kui-pane__content`         | —                                                                  |
-| Optional logical-edge separators         | `Pane.separators`            | `--kui-pane-separator-width: 1px`                                  |
-| Safe-area sides a pane may pad           | `Pane.safeAreaEdges`         | `--kui-safe-area-*: env(safe-area-inset-*)`, routed by each layout |
-| Major vertical rhythm                    | `.kui-content`               | `--kui-layout-content-gap: 24px`                                   |
-| Self-contained child geometry            | `ContentItem`                | 8px margin + 1px border + 8px padding                              |
-| Pill child                               | `ContentItem shape="pill"`   | `--kui-layout-pill-radius: 22px`                                   |
-| Visibly framed child                     | `ContentItem frame="framed"` | neutral 1px border, same geometry                                  |
-| Related controls                         | `.kui-control-cluster`       | `--kui-layout-control-gap: 8px`                                    |
-| Inline metadata                          | `.kui-inline-metadata`       | `--kui-layout-metadata-gap: 4px`                                   |
-| Explicit scroll owner outside a pane     | `.kui-scroll-owner`          | `overflow: auto`                                                   |
+| Need                                     | Class                                | Token / default                                                    |
+| ---------------------------------------- | ------------------------------------ | ------------------------------------------------------------------ |
+| Unpadded header/content/footer structure | `Pane`, `.kui-pane`                  | —                                                                  |
+| Scrolling pane content                   | `.kui-pane__content`                 | —                                                                  |
+| Optional logical-edge separators         | `Pane.separators`                    | `--kui-pane-separator-width: 1px`                                  |
+| Safe-area sides a pane may pad           | `Pane.safeAreaEdges`                 | `--kui-safe-area-*: env(safe-area-inset-*)`, routed by each layout |
+| Header laid over scrolling content       | `Pane.headerPresentation`            | `--kui-chrome-material`, `--kui-chrome-material-filter`            |
+| Dialog title bar laid over its body      | `DialogSurface.headerPresentation`   | `--kui-chrome-material-raised`, `--kui-chrome-material-filter`     |
+| Stack top bar laid over the active view  | `NavStack.chromePresentation`        | `--kui-chrome-material`, `--kui-chrome-material-filter`            |
+| Stack bottom toolbar laid over the view  | `NavStack.bottomToolbarPresentation` | `--kui-chrome-material`, `--kui-chrome-material-filter`            |
+| Tab bar laid over the active scene       | `TabNavigator.barPresentation`       | `--kui-chrome-material`, `--kui-chrome-material-filter`            |
+| Major vertical rhythm                    | `.kui-content`                       | `--kui-layout-content-gap: 24px`                                   |
+| Self-contained child geometry            | `ContentItem`                        | 8px margin + 1px border + 8px padding                              |
+| Pill child                               | `ContentItem shape="pill"`           | `--kui-layout-pill-radius: 22px`                                   |
+| Visibly framed child                     | `ContentItem frame="framed"`         | neutral 1px border, same geometry                                  |
+| Related controls                         | `.kui-control-cluster`               | `--kui-layout-control-gap: 8px`                                    |
+| Inline metadata                          | `.kui-inline-metadata`               | `--kui-layout-metadata-gap: 4px`                                   |
+| Explicit scroll owner outside a pane     | `.kui-scroll-owner`                  | `overflow: auto`                                                   |
 
 The component layer applies the same contract to `Toolbar`, `ListHeader`,
 `ListItem`, `Toolbar`, `StateBanner`, `ValueTable`,
@@ -409,7 +470,7 @@ import { FieldLabel } from "@kerfjs/ui/text";
 
 <div role="group" aria-labelledby="needed-by-label">
   <ListInsetControl sides="trl">
-    <FieldLabel id="needed-by-label">Needed by</FieldLabel>
+    <FieldLabel id="needed-by-label">Needed By</FieldLabel>
   </ListInsetControl>
   <ContentItem>October 16, 2026</ContentItem>
 </div>;
@@ -646,6 +707,78 @@ When it has focus it draws the theme focus ring inset by the ring width and
 rounded with `--kui-radius-m`, so a rounded or `overflow: hidden` parent
 never clips it. Do not style `.kui-list` focus yourself.
 
+### Scroll clearance
+
+Chrome that lies over a scroll owner's block edge (a `DialogSurface` floating
+footer over a transcript, or translucent chrome over a scrolling region)
+publishes how far it covers that edge through an inherited context:
+`--kui-scroll-clearance-block-start` and `--kui-scroll-clearance-block-end`.
+A scroll owner opts in per edge with `scrollClearance` (`"block-start"`,
+`"block-end"`, or `"both"`) on a `scrollable` `List` or a `Pane`. It adds the
+published clearance to its own block padding and `scroll-padding`, so content
+scrolls visibly beneath the chrome while the first and last items (and any
+item focused or scrolled into view) still come to rest clear of it. Without
+the prop the context is ignored. `PaneConfig` carries `scrollClearance` too,
+so a composed Pane opts in the same way: a Workbench `mainPane` or panel
+`pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane` (for
+example a NavStack view inside a dialog with a floating composer).
+
+Opt in only the one scroller that reaches the covered edge; a nested scroller
+must not opt in again. `DialogSurface` publishes block-end for its floating
+footer and block-start for its floating header (see
+`docs/surface-scaffold.md`), and clears the context in every dialog body. A `Pane` with `headerPresentation="overlay"` publishes block-start for
+its own header, once `wireScrollDividers` has measured it, and its content
+clears it without the prop (see [Overlay header](#overlay-header)). When an application overlays its own chrome on a region (for example a
+translucent toolbar laid over the top of a scrolling list), it publishes the
+chrome's block size on that region's container, the one place where an app
+sets this context:
+
+```tsx
+<section style="position:relative;display:grid;--kui-scroll-clearance-block-start:48px">
+  <List scrollable scrollClearance="block-start">{rows}</List>
+  {translucentToolbar}
+</section>;
+```
+
+### Framed result pickers
+
+For a bounded, framed list of `ListItem` rows (search results, duplicate
+candidates, a recent-items picker), configure the List instead of wrapping it
+in an app-owned scroller:
+
+```tsx
+<List scrollable frame gap="2xs" minHeight={rem(4.25)} maxHeight={rem(14)}>
+  {candidates.map((candidate) => (
+    <ListItem action="pick-duplicate" itemId={candidate.id} label={candidate.title} description={candidate.detail} multiline />
+  ))}
+</List>;
+```
+
+`frame` draws a 1px `--kui-color-neutral-border-normal` border with the
+`--kui-radius-m` control radius and a 4px inset on every side (replacing
+`inset`, `textInsets`, and `controlInsets`). That inset is exactly a row's
+focus-ring reach, so the first and last rows' rings stay inside the clip at
+the scroll extremes. Every `scrollable` List, framed or not, carries block
+scroll padding of that reach plus 2px of slack (6px; nothing moves at rest),
+so a middle row focused or scrolled into view also stops with its ring inside
+the clip, even where Chromium's focus scroll stops a pixel short of the padded
+target. An unframed scrollable List has no inset, so its first and last rows
+still meet the clip at the scroll extremes; use `frame` when those rows must
+show a whole ring.
+How far `focus()` scrolls a partly visible row is up to the engine: Chromium
+brings it to the nearest edge, Firefox leaves it until about half of it is
+hidden and then centers it, and WebKit leaves a partly visible row where it
+is. Call `wireListFocusScroll(root)` from `@kerfjs/ui/wire-list-focus-scroll`
+once at the app root (keep its disposer) to make keyboard focus consistent:
+when a `:focus-visible` element inside a `scrollable` List has a ring that
+crosses the clip, it calls `scrollIntoView({ block: 'nearest' })`, which
+honors the List's scroll padding in every engine. It leaves pointer focus
+alone, so a click never scrolls its row from under the pointer, and it is a
+no-op where Chromium has already scrolled. `maxHeight` and `minHeight` take typed
+`CssLength`s from `@kerfjs/ui/css-values` and bound the List directly, with no
+flex-column ancestor; pair `maxHeight` with `scrollable`. A frame of settings
+rows with dividers between them is a `FramedList`, not a framed List.
+
 For long reading content, such as a reader view, pass `inset="document"`: 24px
 block and 32px inline on all four sides, narrowing to 16px inline below 576px.
 It replaces any `textInsets`/`controlInsets` on that List.

package/docs/nav-stack.md

@@ -66,7 +66,8 @@ 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`, and `appearance` to the Pane. Without those fields, the view
+`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;
@@ -136,7 +137,7 @@ Configure the toolbar with `toolbarConfig` instead of styling it:
 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
+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.
@@ -186,6 +187,115 @@ top Toolbar's own `dividerSides`.
 <NavStack id="settings" label="Settings" views={views.value} chromeDividers="always" />
 ```
 
+## 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. The copy keeps painting over the top edge with the same material while
+  it fades, and 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.
+
 ## Safe areas
 
 The stack paints through a device's unsafe areas. Its chrome pads for the top

package/docs/recipes.md

@@ -26,7 +26,7 @@ The adapter is delivered as reference source, not a new package runtime export.
 `delegate()` remains a valid alternative when an application needs selector-
 specific dispatch; either way, wire once at a stable root and retain disposal.
 
-## Desktop application shell
+## Desktop Application Shell
 
 [Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx)
 
@@ -52,7 +52,7 @@ whole width). The app owns each rail's collapsed and size signals — which
 routing, persistence, and data. Adapt only public `--kui-layout-*` and
 component variables.
 
-## Navigation sidebar
+## Navigation Sidebar
 
 [Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
 
@@ -65,7 +65,7 @@ permissions, labels, selection, valid section counts and their localized
 content. A toggled `ListHeader` supplies the production `DisclosureArrow` when
 no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 
-## Workspace header
+## Workspace Header
 
 [Open the recipe](../ux-demo/?component=recipe-workspace-header) · [TSX source](../ux-demo/recipes/workspace-header.tsx)
 
@@ -99,7 +99,7 @@ application owns open state, selection, the pushed detail, dismissal policy,
 and record actions. Do not put the primary title in a header spanning both
 columns, rebuild the dialog, or reach into private shadow parts.
 
-## Composer form
+## Composer Form
 
 [Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
 
@@ -118,7 +118,7 @@ Because upgraded Web Awesome fields retain live value properties, controlled
 resets synchronize both those properties and the rendered value attributes;
 the Reset action also announces `Draft reset` through the catalog live region.
 
-## List workspace states
+## List Workspace States
 
 [Open the recipe](../ux-demo/?component=recipe-list-workspace-states) · [TSX source](../ux-demo/recipes/list-workspace-states.tsx)
 
@@ -127,7 +127,7 @@ populated, stale/background refresh, and error/retry states. The recipe owns
 feedback placement; the app owns fetching, cache age, retry policy, and domain
 rows.
 
-## Compact toolbar choices and actions
+## Compact Toolbar Choices and Actions
 
 [Open the recipe](../ux-demo/?component=recipe-compact-toolbar) · [TSX source](../ux-demo/recipes/compact-toolbar.tsx)
 
@@ -140,7 +140,7 @@ widths the toolbar stacks its zones and wraps whole trailing groups onto another
 row, so the last action is never clipped. The app owns values, actions,
 persistence, and responsive priority.
 
-## Navigation stack
+## Navigation Stack
 
 [Open the recipe](../ux-demo/?component=recipe-navigation-stack) · [TSX source](../ux-demo/recipes/navigation-stack.tsx)
 
@@ -152,7 +152,7 @@ layout guide
 [`app-layouts.md`](app-layouts.md) for choosing among `NavStack`, `SplitView`,
 `Workbench`, and `TabNavigator`.
 
-## Loading inspector
+## Loading Inspector
 
 [Open the recipe](../ux-demo/?component=recipe-loading-inspector) · [TSX source](../ux-demo/recipes/loading-inspector.tsx)
 
@@ -166,7 +166,7 @@ the populated record — no separate skeleton markup. The composition is the poi
 record title instead of truncating it. The app owns the loading lifecycle and
 which values are still unknown.
 
-## Collapsible sidebar
+## Collapsible Sidebar
 
 [Open the recipe](../ux-demo/?component=recipe-collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx)
 

package/docs/split-view.md

@@ -114,12 +114,12 @@ compactStack={{
   list: { toolbar: { trailing: <ComposeGroup /> } },
   detail: {
     toolbar: { trailing: <ReplyGroup /> },
-    bottomToolbar: { label: "Message actions", leading: <MessageActions /> },
+    bottomToolbar: { label: "Message Actions", leading: <MessageActions /> },
   },
 }}
 ```
 
-The catalog's **Interactive compact drill-down** example exercises this exact
+The catalog's **Interactive Compact Drill-Down** example exercises this exact
 controlled flow: a list action sets the selected message, `detailActive` pushes
 its detail, and the wired Back action clears the selection to reveal the
 preserved list. It also forwards `compactStack`: a level-2 heading title over
@@ -128,7 +128,7 @@ bottom toolbar on the detail. Use the same structure in application demos so
 compact examples show the interaction rather than rendering a disconnected
 detail state.
 
-The catalog's **Resizable, collapsible list** example forwards `resizable`: a
+The catalog's **Resizable, Collapsible List** example forwards `resizable`: a
 hidden separator that still resizes the list (its committed width comes back
 through `wireResizableRegions`' `onCommit` into the app's size signal), a Hide
 control in the list's own toolbar, and a `FloatingToolbar` restore control in

package/docs/sunken-panel.md

@@ -8,7 +8,7 @@ issue tracker or component catalog.
 ```tsx
 import { SunkenPanel } from '@kerfjs/ui/sunken-panel';
 
-<SunkenPanel ariaLabel="Release workspace">
+<SunkenPanel ariaLabel="Release Workspace">
   <ReleaseSummary />
   <ReleaseChecks />
 </SunkenPanel>;
@@ -33,7 +33,7 @@ can shrink with its parent. Like `Grid`, `flex` accepts `true` (equivalent to
 
 ```tsx
 <List fill>
-  <Toolbar label="Work area" />
+  <Toolbar label="Work Area" />
   <SunkenPanel flex>
     <WorkArea />
   </SunkenPanel>

package/docs/surface-scaffold.md

@@ -54,7 +54,7 @@ import { remify } from '@kerfjs/ui/css-values';
 import { DialogSurface } from '@kerfjs/ui/surface-scaffold';
 
 <DialogSurface preferredWidth={remify(832)} viewportGutter={remify(8)} maxHeight="viewport" bodyInset="none">
-  <wa-dialog label="Close workspace">{/* Application-owned content and footer */}</wa-dialog>
+  <wa-dialog label="Close Workspace">{/* Application-owned content and footer */}</wa-dialog>
 </DialogSurface>;
 ```
 
@@ -86,12 +86,129 @@ itself stops scrolling. Combine it with `bodyInset="none"`.
 
 ```tsx
 <DialogSurface size="large" height={remify(640)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill">
-  <wa-dialog label="Repository status">
+  <wa-dialog label="Repository Status">
     <SplitView id="repo-split" label="Changes" listWidth={{ size: 432, maxFraction: 0.5 }} list={list} detail={detail} />
   </wa-dialog>
 </DialogSurface>;
 ```
 
+### Chat dialogs: a floating footer over a filling transcript
+
+A chat-style dialog keeps a heading or notices above one scrolling transcript
+and floats its composer over the body's block end. Two props compose it:
+
+- `bodyLayout="fill-last"` stacks the body's children: the leading children
+  keep their natural height, and the last one takes the remaining height and
+  owns its scrolling (a `scrollable` `List` transcript). The body itself stops
+  scrolling. `PopoverDialogSurface` accepts the same layout.
+- `footerPresentation="floating"` lays the footer over the body's block end,
+  `footerOffset` (a branded `CssLength`, default the 16px container inset)
+  from the panel's inline and block-end edges, on a transparent background.
+  The modal panel is its positioning context. The default `docked` footer
+  sits below the body as before.
+
+The register measures the footer (it follows a composer that grows, wraps, or
+hides) and the body reserves that height plus the offset after its own inset,
+with a matching `scroll-padding`. Flowing body content scrolls beneath the
+floating footer and its end stays reachable above it; with `fill` or
+`fill-last` the filling child's scrollport ends at the footer's top. Content
+is never hidden beneath the footer.
+
+To let a filling transcript scroll visibly beneath the floating footer, opt
+its scroller in with `scrollClearance="block-end"` (a `scrollable` `List`, or a
+`Pane`, as the `fill` or last `fill-last` child). The body then stops
+reserving the footer below that child, so the child reaches the panel's block
+end, and publishes the footer's clearance (measured height plus offset) as the
+inherited `--kui-scroll-clearance-block-end` context. The child adds it to its
+own block-end padding and `scroll-padding`: messages pass beneath the
+transparent footer mid-scroll, the last message rests above the composer at
+the end, and focus or `scrollIntoView` never leaves an item hidden beneath it.
+The context is general: chrome that overlays a region's block-start or
+block-end edge publishes `--kui-scroll-clearance-block-start` / `-end`, and a
+scroll owner opts in per edge (see `docs/layout.md` "Scroll clearance"). A
+dialog body clears any clearance inherited from the page.
+
+Choose the offset like any other responsive value: the scaffold adds no
+breakpoint. An 8px offset lines a composer up with the transcript's
+content-item edges when the body has `bodyInset="none"` and list geometry;
+`viewportGutter` and `footerOffset` can follow `deviceClass()` when a phone
+needs tighter edges. Put a [`Composer`](./composer.md) in the floating footer
+with `footerInset="none"`: its raised frame and shadow lift it over the
+transcript, and its field grows the measured footer. With `submitOnEnter` and
+`wireComposers(root)`, Enter sends through the same action as the Send button.
+
+```tsx
+<DialogSurface height={remify(560)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill-last" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
+  <wa-dialog label="Assistant">
+    <StateBanner title="Answers use the latest nightly build." tone="neutral" />
+    <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">
+      {messages.map((message) => (
+        <ContentItem bubble={message.mine ? 'end' : 'start'} appearance={message.mine ? 'brand-loud' : 'neutral'}>
+          <Text variant="span">{message.text}</Text>
+        </ContentItem>
+      ))}
+    </List>
+    <Composer submitOnEnter slot="footer" id="assistant-message" name="message" label="Message" placeholder="Ask about this build" actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>} />
+  </wa-dialog>
+</DialogSurface>;
+```
+
+### A floating title bar
+
+`headerPresentation="floating"` lays the dialog's header (its title and close
+control) over the body's block-start edge on the translucent chrome material,
+`--kui-chrome-material-raised` (the raised panel surface at 80% opacity)
+behind `--kui-chrome-material-filter` (a blur and saturation backdrop filter).
+Content passing beneath the title bar reads as softened color, not as
+competing text. The default `docked` header sits above the body as before.
+
+The register measures the header the same way it measures the footer (it
+follows a title that wraps, text that grows, or a `without-header` toggle).
+The body reserves the measured height before its own inset, with a matching
+`scroll-padding`, so flowing content starts below the title bar and scrolls
+beneath it. A dialog without the register has no measurement, so its header
+stays docked rather than covering content.
+
+To let a filling transcript scroll visibly beneath the title bar, make it the
+body's only child (`bodyLayout="fill"`, or `fill-last` with no leading rows)
+and opt its scroller in with block-start `scrollClearance`. The body then
+stops reserving the header, so the child reaches the panel's block-start
+edge, and publishes the header's height as `--kui-scroll-clearance-block-start`.
+Leading `fill-last` rows (a notice above the transcript) keep the body's
+reservation: they never sit beneath the title bar. Combined with a floating
+composer and `scrollClearance="both"`, the transcript scrolls beneath both:
+
+```tsx
+<DialogSurface height={remify(560)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill" headerPresentation="floating" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
+  <wa-dialog label="Release Thread">
+    <ToolbarText slot="label" text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />
+    <List gap="xs" controlInsets="tb" scrollable scrollClearance="both">
+      {bubbles}
+    </List>
+    <Composer submitOnEnter slot="footer" id="thread-message" name="message" label="Message" placeholder="Reply to the thread" actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>} />
+  </wa-dialog>
+</DialogSurface>;
+```
+
+Like a `Pane`'s overlay header, the title bar draws its divider as scroll
+state: a 1px line along its bottom edge only while the body, or a filling
+child that reaches beneath it, is scrolled away from its top, and none at
+rest. The register follows those scrollers (a nested scroller that starts
+below the title bar never counts), and the line is an inset shadow, so it
+never moves the header or the content.
+
+The material turns opaque under `prefers-reduced-transparency: reduce` or
+`prefers-contrast: more`, and where the browser lacks `backdrop-filter`; in
+forced colors the header paints `Canvas` with a `CanvasText` bottom edge.
+
+For a title with a short supporting line, slot a `ToolbarText` as the label
+(`<ToolbarText slot="label" text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />`).
+On the floating title bar an untoned `ToolbarText` keeps AA by itself: its
+title takes the normal text color and its description lifts halfway toward
+it. Any other quiet copy you place there can fall below AA over the content
+passing beneath it, so keep it in the body (see
+[Accessibility › Chrome material](accessibility.md#chrome-material)).
+
 Treat a dialog body as a `List` by default. When its rows or sections own their
 standard list geometry, set `bodyInset="none"` so the dialog does not add a
 second inset. Bare prose is still a list child: wrap it in `ListInsetText` so its
@@ -109,8 +226,22 @@ hand-built popover with application chrome CSS. It is a native
 `popover="auto"` section with `role="dialog"` that owns Kerf's dialog chrome
 (raised surface, border, large radius and shadow, and a backdrop) and the
 same geometry props as a modal `DialogSurface`: `size`, `preferredWidth`,
-`viewportGutter` (16px by default), `height` / `maxHeight`, and `bodyLayout`.
-Name it with `label` or `labelledBy`.
+`viewportGutter` (16px by default), `height` / `maxHeight`, and `bodyLayout`
+(`flow`, `fill`, or `fill-last`).
+Name it with `label` or `labelledBy`. To give it an accessible description,
+pass `describedBy`, the id of the element that holds the summary. It renders as
+`aria-describedby` on the `role="dialog"` root and usually names a title
+`ToolbarText`'s `descriptionId`:
+
+```tsx
+<PopoverDialogSurface id="connection-details" labelledBy="connection-title" describedBy="connection-summary" bodyLayout="fill-last">
+  <Toolbar label="Connection Details Heading" leading={<ToolbarText text="Connection Details" size="xlarge" id="connection-title" description="Connected to the build server." descriptionId="connection-summary" />} />
+  {details}
+</PopoverDialogSurface>;
+```
+
+`DialogSurface` has no `describedBy`. It wraps a `wa-dialog` that the app
+authors, so the app names and describes that dialog on its own markup.
 
 Open it with a control's `popoverTarget` (or `showPopover()`); the browser
 places it centered in the top layer, light-dismisses it, and restores nothing
@@ -121,8 +252,8 @@ layer and never wider than its container, for a catalog specimen or an inline
 preview.
 
 ```tsx
-<button type="button" popoverTarget="repository-status">Repository status</button>
-<PopoverDialogSurface id="repository-status" label="Repository status" preferredWidth={remify(1024)} height={remify(640)} viewportGutter={remify(8)} bodyLayout="fill">
+<button type="button" popoverTarget="repository-status">Repository Status</button>
+<PopoverDialogSurface id="repository-status" label="Repository Status" preferredWidth={remify(1024)} height={remify(640)} viewportGutter={remify(8)} bodyLayout="fill">
   <SplitView id="repo-split" label="Changes" list={list} detail={detail} />
 </PopoverDialogSurface>;
 ```
@@ -136,4 +267,4 @@ preserve `data-morph-skip-children` when its upgraded light-DOM items must retai
 identity across Kerf rerenders. Import `@kerfjs/ui/popup-menu/register` once for
 the focus handoff fix when wrapping a raw `wa-dropdown`.
 
-Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog`, measures each surface's footer for a floating footer's body clearance, draws a floating header's divider while content is scrolled beneath it, and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.