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

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.98` and `kerfjs@5.0.0-beta.98`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.99` and `kerfjs@5.0.0-beta.99`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -122,8 +122,16 @@ declare function foregroundColorVar(name: `--${string}`, fallback?: CssForegroun
  * resolves the color syntax; this checks only that it is one declaration value.
  */
 declare function foregroundColor(value: string): CssForegroundColor;
+/**
+ * Use an application-chosen CSS color as a fill: a `ChoiceChips` swatch, a list
+ * row's `iconTile` color, or any other prop that takes a plain
+ * {@link CssColor}. It returns a `CssColor`, not a {@link CssForegroundColor},
+ * so a fill literal cannot reach a prop that paints text or an icon. The browser
+ * resolves the color syntax; this checks only that it is one declaration value.
+ */
+declare function fillColor(value: string): CssColor;
 
-export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiGap, type UiGapValue, type UiSpaceName, calc, colorVar, em, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
+export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiGap, type UiGapValue, type UiSpaceName, calc, colorVar, em, fillColor, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
 ```
 
 ## `@kerfjs/ui/disclosure-arrow`
@@ -157,6 +165,7 @@ import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 import { PaneSeparatorSide } from './pane.js';
+import './scroll-clearance-BikHljTc.js';
 
 type ToolbarPosition = 'header' | 'footer';
 /** Control-band density: `default` (60px with 44px groups) or `compact`. */
@@ -714,9 +723,10 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as StructuralRootAttributes } from './extension-attributes-mu8MFUl0.js';
 import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
+import { S as ScrollClearance } from './scroll-clearance-BikHljTc.js';
 import { S as Sides } from './sides-BPSWde0A.js';
-import { UiGap, CssFlexKeyword, CssFlex } from './css-values.js';
-export { CssLength, UiGapValue, UiSpaceName } from './css-values.js';
+import { UiGap, CssFlexKeyword, CssFlex, CssLength } from './css-values.js';
+export { UiGapValue, UiSpaceName } from './css-values.js';
 
 type ListRootAttributes = StructuralRootAttributes & Readonly<{
     'data-component'?: never;
@@ -726,6 +736,8 @@ type ListRootAttributes = StructuralRootAttributes & Readonly<{
     'data-h-align'?: never;
     'data-v-align'?: never;
     'data-scrollable'?: never;
+    'data-scroll-clearance'?: never;
+    'data-frame'?: never;
     'data-surface'?: never;
     'data-inset'?: never;
     'data-text-insets'?: never;
@@ -770,6 +782,35 @@ interface ListProps {
      * column and use `flex`; `fill` needs a definite-height parent.
      */
     scrollable?: boolean;
+    /**
+     * Clear chrome that lies over this scrollable List's block-start and/or
+     * block-end edge, such as a `DialogSurface` floating footer. The List adds
+     * the inherited `--kui-scroll-clearance-block-*` context that chrome
+     * publishes to its own block padding and `scroll-padding`, so its rows
+     * scroll visibly beneath the chrome while the first and last rows (and any
+     * row focused or scrolled into view) can still rest clear of it. Opt in only
+     * the one scroller that reaches the covered edge. Defaults to none.
+     */
+    scrollClearance?: ScrollClearance;
+    /**
+     * Draw a bordered, rounded frame around the stack: a 1px neutral border,
+     * the standard control radius, and a 4px inset on every side that keeps the
+     * first and last rows' focus rings inside a scrolling frame's clip. It
+     * replaces any `inset`/`textInsets`/`controlInsets`. With `scrollable` and
+     * `maxHeight` it is a bounded result picker of `ListItem` rows.
+     */
+    frame?: boolean;
+    /**
+     * The List's maximum block size, a typed `CssLength` from
+     * `@kerfjs/ui/css-values` (such as `rem(14)`). Pair it with `scrollable` so
+     * rows beyond it scroll; it bounds the List without a flex-column ancestor.
+     */
+    maxHeight?: CssLength;
+    /**
+     * The List's minimum block size, a typed `CssLength` (such as `rem(4.25)`),
+     * so a short or empty result set keeps a stable box. Defaults to no minimum.
+     */
+    minHeight?: CssLength;
     /**
      * Paint a solid surface behind the stack, including its insets: for a strip
      * of chrome (a banner above a sunken work area) that must not show the
@@ -802,16 +843,19 @@ interface ListProps {
  */
 type ListConfig = Pick<ListProps, 'gap' | 'hAlign' | 'vAlign' | 'dividerSides' | 'textInsets' | 'controlInsets'>;
 /** A stretch-aligned vertical stack with optional gap, flex, fill, scroll, and dividers. */
-declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, surface, inset, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
+declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, scrollClearance, frame, maxHeight, minHeight, surface, inset, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, HorizontalAlignment, List, type ListConfig, type ListInset, type ListProps, type ListSurface, ListVerticalAlignment, Sides, UiGap };
+export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, List, type ListConfig, type ListInset, type ListProps, type ListSurface, ListVerticalAlignment, ScrollClearance, Sides, UiGap };
 ```
 
 ## `@kerfjs/ui/list-action-row`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { L as ListIconTile } from './list-icon-tile-B8dr97OW.js';
+export { a as ListIconTileColor, b as ListIconTileTone } from './list-icon-tile-B8dr97OW.js';
 import { PopupMenuEntry, PopupMenuPlacement } from './popup-menu.js';
+import './css-values.js';
 import './semantic-content-BbzjvSu9.js';
 
 type ListActionRowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
@@ -819,6 +863,8 @@ type ListActionRowRootAttributes = Readonly<Record<`data-${string}`, string | un
     'data-action'?: never;
     'data-item-id'?: never;
     'data-has-icon'?: never;
+    'data-icon-tile'?: never;
+    'data-icon-tile-tone'?: never;
     'data-multiline'?: never;
     'data-density'?: never;
     'data-divider'?: never;
@@ -878,10 +924,13 @@ interface ListActionRowCommonProps {
     description?: string | SafeHtml;
     status?: string | SafeHtml;
     busy?: boolean;
+    /** Row height: `standard` is 44px; `compact` is 36px (42px with `iconTile`), the height of a compact `ListItem`. */
     density?: 'standard' | 'compact';
     divider?: 'none' | 'before' | 'after' | 'both';
     /** Decorative dormant content for the primary button. Must not contain interactive descendants. */
     icon?: SafeHtml;
+    /** Present `icon` in a filled 32px rounded tile with an 18px glyph: a quiet tone preset, or `{ color, foreground? }` for an application color. */
+    iconTile?: ListIconTile;
     action: string;
     itemId?: string;
     selected?: boolean;
@@ -908,16 +957,19 @@ interface ListActionRowCommonProps {
 }
 /** Exactly one trailing control: a native button (`trailingAction*`) or an overflow menu (`trailingMenu`). */
 type ListActionRowProps = ListActionRowCommonProps & (ListActionRowTrailingButtonProps | ListActionRowTrailingMenuProps);
-declare function ListActionRow({ label, description, status, busy, density, divider, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, trailingActionVisibility, trailingMenu, className, rootAttributes, trailingActionAttributes, slot, }: ListActionRowProps): SafeHtml;
+declare function ListActionRow({ label, description, status, busy, density, divider, icon, iconTile, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, trailingActionVisibility, trailingMenu, className, rootAttributes, trailingActionAttributes, slot, }: ListActionRowProps): SafeHtml;
 
-export { ListActionRow, type ListActionRowProps, type ListActionRowTrailingMenu };
+export { ListActionRow, type ListActionRowProps, type ListActionRowTrailingMenu, ListIconTile };
 ```
 
 ## `@kerfjs/ui/list-item`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { L as ListIconTile } from './list-icon-tile-B8dr97OW.js';
+export { a as ListIconTileColor, b as ListIconTileTone } from './list-icon-tile-B8dr97OW.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './css-values.js';
 
 type ListItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -932,6 +984,8 @@ type ListItemRootAttributes = Readonly<Record<`data-${string}`, string | undefin
     'data-state'?: never;
     'data-kui-disabled'?: never;
     'data-icon-align'?: never;
+    'data-icon-tile'?: never;
+    'data-icon-tile-tone'?: never;
     'data-dragging'?: never;
     'data-drop-position'?: never;
 }>;
@@ -940,6 +994,8 @@ interface ListItemProps {
     /** App-owned supporting text rendered in the component's stable label stack. */
     description?: string | SafeHtml;
     icon?: SafeHtml;
+    /** Present `icon` in a filled 32px rounded tile with an 18px glyph: a quiet tone preset, or `{ color, foreground? }` for an application color. */
+    iconTile?: ListIconTile;
     /** Dormant author content at the row's end; a placeholder renders it as a skeleton. */
     trailing?: KerfUiContent;
     /** Dormant status metadata rendered before trailing content; a placeholder renders it as a skeleton. */
@@ -981,11 +1037,11 @@ interface ListItemLinkProps extends Omit<ListItemProps, 'action' | 'pressed'> {
     action?: never;
     pressed?: never;
 }
-declare function ListItem({ label, description, icon, trailing, status, busy, density, divider, selected, action, itemId, className, pressed, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, rootAttributes, slot, }: ListItemProps): SafeHtml;
+declare function ListItem({ label, description, icon, iconTile, trailing, status, busy, density, divider, selected, action, itemId, className, pressed, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, rootAttributes, slot, }: ListItemProps): SafeHtml;
 /** A navigation row with native link activation and ListItem geometry. */
-declare function ListItemLink({ href, external, label, description, icon, trailing, status, busy, density, divider, selected, itemId, className, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, rootAttributes, slot, }: ListItemLinkProps): SafeHtml;
+declare function ListItemLink({ href, external, label, description, icon, iconTile, trailing, status, busy, density, divider, selected, itemId, className, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, rootAttributes, slot, }: ListItemLinkProps): SafeHtml;
 
-export { ListItem, ListItemLink, type ListItemLinkProps, type ListItemProps };
+export { ListIconTile, ListItem, ListItemLink, type ListItemLinkProps, type ListItemProps };
 ```
 
 ## `@kerfjs/ui/list-inset-control`
@@ -1447,6 +1503,15 @@ type Root = HTMLElement | Document;
  * - each app-owned `targets` pairing: a `Toolbar` or `List` named as chrome
  *   draws the divider on its facing side.
  *
+ * It also measures every `Pane` header laid over its content
+ * (`headerPresentation="overlay"`, with fixed chrome placement): it publishes
+ * the header's border-box block size on the Pane root as the inherited
+ * `--kui-scroll-clearance-block-start` context, and marks the root
+ * `data-header-overlay="measured"`, which moves the header over the content
+ * and has the content clear it. The measurement follows the header as it
+ * wraps, zooms, or changes content, and both are restored before paint if a
+ * re-render drops them.
+ *
  * Structure is re-read after every DOM change below root that can change a
  * pairing — a structural element or target id added, removed, or re-classed;
  * mutations inside scrolled content (a row's class, a list's rows) do not
@@ -1512,19 +1577,41 @@ declare function wireListReorder(root: HTMLElement | Document, { onReorder }: Wi
 export { type ListDropPosition, type ListReorder, type ListReorderSource, type ListReorderTarget, type WireListReorderOptions, reorderListItems, wireListReorder };
 ```
 
+## `@kerfjs/ui/wire-list-focus-scroll`
+
+```ts
+type Root = HTMLElement | Document;
+/**
+ * Bring a keyboard-focused row of a `scrollable` List below `root` fully into
+ * view, focus ring included. Engines differ on how `focus()` scrolls a partly
+ * hidden row: Chromium scrolls it to the nearest edge plus scroll padding,
+ * Firefox waits until about half of it is hidden and then centers it, and
+ * WebKit leaves it where it is. On `focusin`, when the newly focused element
+ * matches `:focus-visible` and its ring crosses the nearest scrollable List's
+ * clip, this calls `scrollIntoView({ block: 'nearest', inline: 'nearest' })`,
+ * which honors the List's ring-room scroll padding in every engine. Pointer
+ * focus is left alone, so a click never scrolls the row out from under the
+ * pointer. Returns a disposer.
+ */
+declare function wireListFocusScroll(root: Root): () => void;
+
+export { wireListFocusScroll };
+```
+
 ## `@kerfjs/ui/nav-stack`
 
 ```ts
-export { c as NavStack, N as NavStackProps, d as NavStackToolbarConfig, a as NavStackView, e as NavStackViewBottomToolbar, f as NavStackViewToolbar } from './nav-stack-Cp3Y8kJ9.js';
+export { c as NavStack, d as NavStackBottomToolbarPresentation, e as NavStackChromePresentation, N as NavStackProps, f as NavStackToolbarConfig, a as NavStackView, g as NavStackViewBottomToolbar, h as NavStackViewToolbar } from './nav-stack-VXTumzKa.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
+import './scroll-clearance-BikHljTc.js';
 import './sides-BPSWde0A.js';
 import './css-values.js';
 import './pane.js';
-import './panel-toolbar-CL9tYOkh.js';
+import './panel-toolbar-vg6Ir5Dy.js';
 import './toolbar.js';
 import './lucide-icon.js';
 import 'lucide';
@@ -1559,15 +1646,16 @@ export { type WireNavStackOptions, wireNavStack };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { N as NavStackProps, a as NavStackView } from './nav-stack-Cp3Y8kJ9.js';
+import { N as NavStackProps, a as NavStackView } from './nav-stack-VXTumzKa.js';
 import { ResizableRegionProps } from './resizable-region.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
+import './scroll-clearance-BikHljTc.js';
 import './sides-BPSWde0A.js';
 import './css-values.js';
 import './pane.js';
-import './panel-toolbar-CL9tYOkh.js';
+import './panel-toolbar-vg6Ir5Dy.js';
 import './toolbar.js';
 import './lucide-icon.js';
 import 'lucide';
@@ -1589,10 +1677,11 @@ interface SplitViewResizable extends Pick<ResizableRegionProps, 'separator' | 'h
 type SplitViewCompactViewToolbars = Pick<NavStackView, 'toolbar' | 'bottomToolbar'>;
 /**
  * The compact `NavStack`'s configuration: its toolbar configuration, back
- * control, persistent bottom toolbar, and chrome dividers forward to the
- * stack, and `list` / `detail` give each view its own toolbar groups.
+ * control, persistent bottom toolbar, chrome dividers, and chrome and
+ * bottom-toolbar presentations forward to the stack, and `list` / `detail`
+ * give each view its own toolbar groups.
  */
-interface SplitViewCompactStack extends Pick<NavStackProps, 'toolbarConfig' | 'backIcon' | 'backText' | 'hideToolbar' | 'bottomToolbar' | 'chromeDividers'> {
+interface SplitViewCompactStack extends Pick<NavStackProps, 'toolbarConfig' | 'backIcon' | 'backText' | 'hideToolbar' | 'bottomToolbar' | 'chromeDividers' | 'chromePresentation' | 'bottomToolbarPresentation'> {
     /** Toolbar content for the list (root) view. */
     list?: SplitViewCompactViewToolbars;
     /** Toolbar content for the pushed detail view. */
@@ -1661,6 +1750,7 @@ export { SplitView, type SplitViewCompactStack, type SplitViewCompactViewToolbar
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as ScrollClearance } from './scroll-clearance-BikHljTc.js';
 
 /**
  * Logical pane sides: where a {@link Pane} can show a separator and where it can
@@ -1686,6 +1776,9 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-appearance'?: never;
     'data-deep-inset'?: never;
     'data-outlined'?: never;
+    'data-scroll-clearance'?: never;
+    'data-header-presentation'?: never;
+    'data-header-overlay'?: never;
 }>;
 /** How a Pane's header and footer relate to its scrolling content. */
 type PaneChromePlacement = 'fixed' | 'auto';
@@ -1695,6 +1788,12 @@ type PaneChromePlacement = 'fixed' | 'auto';
  * chrome, as `wireScrollDividers` reports; `always`; or `none`.
  */
 type PaneChromeDividers = 'scroll' | 'always' | 'none';
+/**
+ * How a Pane's header relates to its scrolling content: `docked` in its own
+ * row above the content, or `overlay` laid over the content's top edge on the
+ * translucent chrome material, so content scrolls visibly beneath it.
+ */
+type PaneHeaderPresentation = 'docked' | 'overlay';
 /** Background treatment of the Pane's scrolling work surface. */
 type PaneAppearance = 'default' | 'sunken';
 interface PaneProps {
@@ -1723,8 +1822,35 @@ interface PaneProps {
      * The line is drawn inside the chrome, so no state moves the content.
      */
     chromeDividers?: PaneChromeDividers;
+    /**
+     * `docked` (default) gives the header its own row above the scrolling
+     * content. `overlay` lays the header over the content's top edge on the
+     * translucent chrome material (`--kui-chrome-material`, opaque under
+     * `prefers-reduced-transparency`, forced colors, or without
+     * `backdrop-filter`), so content scrolls visibly beneath it. Once
+     * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
+     * the pane it measures the header and publishes its height as the
+     * `--kui-scroll-clearance-block-start` context, which the content adds to
+     * its block-start padding and `scroll-padding` without any
+     * `scrollClearance` prop, so the first item, and anything focused or
+     * scrolled into view, rests clear of the header. Until then, and with
+     * `chromePlacement="auto"`, the header stays docked. Keep overlay header
+     * text in the normal text color: quiet text can fall below AA over the
+     * content passing beneath it.
+     */
+    headerPresentation?: PaneHeaderPresentation;
     /** Paint the scrolling work surface with the shared lowered-surface color. */
     appearance?: PaneAppearance;
+    /**
+     * Clear chrome that lies over the scrolling content's block-start and/or
+     * block-end edge, such as a `DialogSurface` floating footer over a filling
+     * Pane. The content scroller adds the inherited
+     * `--kui-scroll-clearance-block-*` context that chrome publishes to its block
+     * padding and `scroll-padding`, so content scrolls visibly beneath the chrome
+     * while its first and last items (and anything focused or scrolled into
+     * view) can still rest clear of it. Defaults to none.
+     */
+    scrollClearance?: ScrollClearance;
     /** Add 8px to every side of scrolling content (default: false). */
     deepInset?: boolean;
     /** Opt into keyboard (`0`) or programmatic (`-1`) focus on the Pane root. */
@@ -1765,16 +1891,16 @@ interface PaneProps {
  * or a CollapsiblePanel) forwards, so the app configures that pane instead of
  * styling it. An omitted or `undefined` field keeps the composite's default.
  */
-type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separators' | 'safeAreaEdges' | 'chromeDividers' | 'appearance' | 'deepInset' | 'tabIndex' | 'outlined'>;
+type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separators' | 'safeAreaEdges' | 'chromeDividers' | 'headerPresentation' | 'appearance' | 'deepInset' | 'scrollClearance' | 'tabIndex' | 'outlined'>;
 /**
  * An unpadded application column with optional fixed header/footer slots and one
  * scrolling vertical content owner. Separator lines are independently opt-in on
  * each logical edge, so the same component works as a sidebar, main area,
  * inspector, or dialog column.
  */
-declare function Pane({ header, children, footer, chromePlacement, chromeDividers, appearance, deepInset, tabIndex, outlined, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
+declare function Pane({ header, children, footer, chromePlacement, chromeDividers, headerPresentation, appearance, deepInset, scrollClearance, tabIndex, outlined, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
 
-export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlacement, type PaneConfig, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
+export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlacement, type PaneConfig, type PaneContentElement, type PaneElement, type PaneHeaderPresentation, type PaneProps, type PaneSeparatorSide, ScrollClearance };
 ```
 
 ## `@kerfjs/ui/workbench`
@@ -1782,16 +1908,17 @@ export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlac
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { b as NavPane, N as NavStackProps } from './nav-stack-Cp3Y8kJ9.js';
+import { b as NavPane, N as NavStackProps } from './nav-stack-VXTumzKa.js';
 import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
-import { a as PanelToolbar, c as PanelBottomToolbar, b as PanelChromePlacement, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
+import { a as PanelToolbar, c as PanelBottomToolbar, b as PanelChromePlacement, d as PanelToggle } from './panel-toolbar-vg6Ir5Dy.js';
 import { ToolbarConfig } from './toolbar.js';
 import './toolbar-text.js';
 import './css-values.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
+import './scroll-clearance-BikHljTc.js';
 import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
@@ -1882,7 +2009,11 @@ interface WorkbenchPanelBase {
      * with `wireWorkbench` from `@kerfjs/ui/wire-workbench`.
      */
     resizable?: boolean | WorkbenchPanelResizable;
-    /** Accessible name for the panel region. */
+    /**
+     * Accessible name for the panel region, in title style. A resizable
+     * panel's handle is named "Resize {label}", or "Resize Left Rail" /
+     * "Resize Right Rail" / "Resize Bottom Drawer" without one.
+     */
     label?: string;
     /** Opt into keyboard (`0`) or programmatic (`-1`) focus on the panel region. */
     tabIndex?: 0 | -1;
@@ -2179,8 +2310,8 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
-export { e as collapsiblePanelToggleIcon } from './panel-toolbar-CL9tYOkh.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-vg6Ir5Dy.js';
+export { e as collapsiblePanelToggleIcon } from './panel-toolbar-vg6Ir5Dy.js';
 import { ToolbarConfig } from './toolbar.js';
 import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
@@ -2191,6 +2322,7 @@ import './css-values.js';
 import './sides-BPSWde0A.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
+import './scroll-clearance-BikHljTc.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
 type CollapsiblePanelSide = PanelSide;
@@ -2397,6 +2529,7 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { PaneAppearance } from './pane.js';
+import './scroll-clearance-BikHljTc.js';
 
 interface TabNavigatorTabBase<Id extends string> {
     id: Id;
@@ -2448,6 +2581,12 @@ interface TabNavigatorTabDotBadge {
 }
 /** One bottom-bar destination: its label, optional icon and badge, and content. */
 type TabNavigatorTab<Id extends string = string> = TabNavigatorTabBase<Id> & (TabNavigatorTabCountBadge | TabNavigatorTabDotBadge);
+/**
+ * How a {@link TabNavigator}'s tab bar relates to the active scene: `docked`
+ * below it, or `overlay` laid over its bottom edge on the translucent chrome
+ * material, so the scene's content scrolls visibly beneath the bar.
+ */
+type TabNavigatorBarPresentation = 'docked' | 'overlay';
 interface TabNavigatorProps<Id extends string = string> {
     id: string;
     /** Accessible name for the tab bar. */
@@ -2472,6 +2611,20 @@ interface TabNavigatorProps<Id extends string = string> {
      * is the bar's own 1px top border, so no state moves the bar or a tab.
      */
     chromeDividers?: 'scroll' | 'always' | 'none';
+    /**
+     * `docked` (default) gives the tab bar its own band below the scenes.
+     * `overlay` lays it over the active scene's bottom edge on the translucent
+     * chrome material (opaque under reduced transparency, increased contrast,
+     * or without `backdrop-filter`; `Canvas` in forced colors), so content
+     * scrolls visibly beneath it, as under an iOS tab bar. `wireTabNavigator`
+     * measures the live bar (bottom safe area included) and the scenes hand
+     * its height to their content as the block-end `--kui-edge-inset-*`
+     * context, so a plain scene, a sole `Pane`, or a `NavStack` (and its own
+     * bottom toolbar, which then sits above the bar) rests its last item clear
+     * of it. Until then it stays docked. Unselected tab labels lift halfway
+     * toward the normal text color to keep AA over the content beneath.
+     */
+    barPresentation?: TabNavigatorBarPresentation;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -2484,9 +2637,9 @@ interface TabNavigatorProps<Id extends string = string> {
  * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of
  * a bottom bar. See `docs/23-app-layouts.md` §3.4.
  */
-declare function TabNavigator<Id extends string>({ id, label, tabs, active, separator, chromeDividers, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
+declare function TabNavigator<Id extends string>({ id, label, tabs, active, separator, chromeDividers, barPresentation, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
 
-export { TabNavigator, type TabNavigatorProps, type TabNavigatorTab };
+export { TabNavigator, type TabNavigatorBarPresentation, type TabNavigatorProps, type TabNavigatorTab };
 ```
 
 ## `@kerfjs/ui/wire-tab-navigator`
@@ -2498,7 +2651,9 @@ interface WireTabNavigatorOptions {
 }
 /**
  * Wire a `TabNavigator`'s bottom tab bar: clicking a tab calls `onSelect` with its
- * id (the app then updates its controlled `active`). Returns a disposer.
+ * id (the app then updates its controlled `active`). With
+ * `barPresentation="overlay"` it also measures the live bar and lays it over
+ * the scenes (see `TabNavigatorProps.barPresentation`). Returns a disposer.
  */
 declare function wireTabNavigator(root: Element, options: WireTabNavigatorOptions): () => void;
 
@@ -2661,13 +2816,14 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import './toolbar.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
+import './scroll-clearance-BikHljTc.js';
 import './workbench.js';
-import './nav-stack-Cp3Y8kJ9.js';
+import './nav-stack-VXTumzKa.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
-import './panel-toolbar-CL9tYOkh.js';
+import './panel-toolbar-vg6Ir5Dy.js';
 import './lucide-icon.js';
 import 'lucide';
 import './toolbar-text.js';
@@ -2688,15 +2844,31 @@ declare function Catalog({ id, brand, sections, active, content, collapsed, them
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'text-trigger' | 'none';
 interface CatalogExampleViewport {
     layout?: 'grid' | 'flex' | 'flex-column';
-    width?: 'full' | 'compact' | 'medium' | 'wide' | 'text' | 'control';
+    /** Specimen width. `sidebar` (272px, capped at the stage) shows a sidebar
+     *  pane's content at a production rail's width. */
+    width?: 'full' | 'sidebar' | 'compact' | 'medium' | 'wide' | 'text' | 'control';
     /** Fixed specimen height; `app` frames an application-sized recipe or layout.
      *  A fixed height is definite, so a child that fills with `height: 100%`
      *  (a horizontal `ResizableRegion`, say) spans the whole frame. */
     height?: 'short' | 'reduced' | 'medium' | 'tall' | 'app';
     /** A minimum the frame may grow past. It is not a definite height: a child
      *  sized with `height: 100%` falls back to its content height, so use
-     *  `height` when the specimen must fill the frame. */
-    minHeight?: 'short' | 'medium';
+     *  `height` when the specimen must fill the frame. `app` (592px) is the
+     *  application frame's height as a floor, for a stage that hosts a
+     *  frame-anchored top-layer specimen above in-flow content. */
+    minHeight?: 'short' | 'medium' | 'app';
+    /** Names the frame as a CSS anchor (`anchor-name`), so a top-layer
+     *  specimen whose own CSS sets `position-anchor` to this dashed-ident
+     *  positions against the frame as it would against its production anchor.
+     *  Anchor names are document-wide: give each frame on a page its own. */
+    anchorName?: `--${string}`;
+    /** Caps each in-flow child at a centered-or-start content column:
+     *  `compact` (440px), `medium` (640px), or `wide` (864px), each capped at
+     *  the frame. `[popover]` children keep their own geometry. Applies to
+     *  block, `grid`, and `flex-column` flows. */
+    contentWidth?: 'compact' | 'medium' | 'wide';
+    /** Where a `contentWidth` column sits in the frame; default `start`. */
+    contentAlign?: 'start' | 'center';
     frame?: 'solid' | 'dashed';
     surface?: 'default' | 'lowered';
     overflow?: 'hidden' | 'auto-x';
@@ -2799,13 +2971,14 @@ import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
+import './scroll-clearance-BikHljTc.js';
 import './workbench.js';
-import './nav-stack-Cp3Y8kJ9.js';
+import './nav-stack-VXTumzKa.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
-import './panel-toolbar-CL9tYOkh.js';
+import './panel-toolbar-vg6Ir5Dy.js';
 import './lucide-icon.js';
 import 'lucide';
 import './toolbar-text.js';
@@ -2853,13 +3026,14 @@ import './toolbar.js';
 import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
+import './scroll-clearance-BikHljTc.js';
 import './workbench.js';
-import './nav-stack-Cp3Y8kJ9.js';
+import './nav-stack-VXTumzKa.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
-import './panel-toolbar-CL9tYOkh.js';
+import './panel-toolbar-vg6Ir5Dy.js';
 import './lucide-icon.js';
 import 'lucide';
 import './toolbar-text.js';
@@ -3027,7 +3201,7 @@ import { CssColor } from './css-values.js';
 type ChoiceChipsSize = 'default' | 'compact';
 /**
  * A leading color dot: a {@link CssColor} from `uiColor()`, `colorVar()`, or
- * `foregroundColor()`, or `'transparent'` for the no-color swatch (an outlined
+ * `fillColor()`, or `'transparent'` for the no-color swatch (an outlined
  * dot struck through by a diagonal line).
  */
 type ChoiceChipsSwatch = CssColor | 'transparent';
@@ -3044,41 +3218,153 @@ interface ChoiceChipsChoice<Value extends string = string> {
     disabled?: boolean;
 }
 interface ChoiceChipsCommonProps<Value extends string> {
-    /** Native radio `name`: the form field the selected value submits under. */
+    /**
+     * Native input `name`: the form field the selected value (or, with
+     * `multiple`, every checked value) submits under.
+     */
     name: string;
-    /** The selected value. Omit (or pass `undefined`) for no selection. */
-    value?: NoInfer<Value>;
     choices: readonly ChoiceChipsChoice<Value>[];
-    /** Delegated `data-action` on every radio; listen for `change`. */
+    /** Delegated `data-action` on every input; listen for `change`. */
     action?: string;
     size?: ChoiceChipsSize;
     /** Disable the whole group. */
     disabled?: boolean;
-    /** Require a selection for native form validation. */
-    required?: boolean;
-    /** Associate the radios with a form outside their ancestor chain. */
+    /** Associate the inputs with a form outside their ancestor chain. */
     form?: string;
     id?: string;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-/** A radio group is named either by a string or by a visible heading's id. */
-type ChoiceChipsProps<Value extends string = string> = ChoiceChipsCommonProps<Value> & ({
+/** One exclusive value (the default), backed by native radios. */
+interface ChoiceChipsSingleProps<Value extends string = string> {
+    multiple?: false;
+    /** The selected value. Omit (or pass `undefined`) for no selection. */
+    value?: NoInfer<Value>;
+    /** Require a selection for native form validation. */
+    required?: boolean;
+}
+/**
+ * Any number of values, backed by native checkboxes: each pill is its own Tab
+ * stop, Space toggles it, and every checked value submits under `name`.
+ */
+interface ChoiceChipsMultipleProps<Value extends string = string> {
+    multiple: true;
+    /** The checked values. Omit (or pass `[]`) for none. */
+    value?: readonly NoInfer<Value>[];
+    /**
+     * Native `required` on a checkbox demands that one box, so a multiple group
+     * has no "at least one" requirement; validate the checked set in the app.
+     */
+    required?: never;
+}
+/** A group is named either by a string or by a visible heading's id. */
+type ChoiceChipsNaming = {
     label: string;
     labelledBy?: never;
 } | {
     labelledBy: string;
     label?: never;
-});
+};
+type ChoiceChipsProps<Value extends string = string> = ChoiceChipsCommonProps<Value> & (ChoiceChipsSingleProps<Value> | ChoiceChipsMultipleProps<Value>) & ChoiceChipsNaming;
+/**
+ * A wrapping set of pill chips backed by native inputs. By default it is an
+ * exclusive radio group: one Tab stop, arrow-key selection, and a real form
+ * value. With `multiple` it is a checkbox group: each pill toggles on its own
+ * and every checked value submits. Each choice may lead with a color swatch
+ * (including a struck-through transparent swatch) or an icon.
+ */
+declare function ChoiceChips<Value extends string>(props: ChoiceChipsProps<Value>): SafeHtml;
+
+export { ChoiceChips, type ChoiceChipsChoice, type ChoiceChipsMultipleProps, type ChoiceChipsNaming, type ChoiceChipsProps, type ChoiceChipsSingleProps, type ChoiceChipsSize, type ChoiceChipsSwatch };
+```
+
+## `@kerfjs/ui/composer`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
 /**
- * An exclusive, wrapping set of pill chips backed by native radios: one Tab
- * stop, arrow-key selection, and a real form value. Each choice may lead with
- * a color swatch (including a struck-through transparent swatch) or an icon.
+ * Application `data-*` identity on the Composer root, such as `data-key`;
+ * the composer's own configuration attributes stay protected.
  */
-declare function ChoiceChips<Value extends string>({ name, value, choices, action, size, disabled, required, form, id, className, slot, label, labelledBy, }: ChoiceChipsProps<Value>): SafeHtml;
+type ComposerRootAttributes = Readonly<Record<`data-${string}`, string | undefined>>;
+interface ComposerProps {
+    /** The message field's accessible name, in title style ("Message"). */
+    label: string;
+    /** Native textarea `name`: the form field the message submits under. */
+    name: string;
+    /**
+     * The textarea id. With a `hint`, the hint takes `<id>-hint` and becomes
+     * the field's accessible description.
+     */
+    id?: string;
+    /** The field's text: a draft to restore, or `''` after sending. */
+    value?: string;
+    /** Sentence-style example of what to write ("Ask about this build"). */
+    placeholder?: string;
+    /**
+     * Visible lines while the field is empty or short (default 1). The field
+     * grows with its content from here.
+     */
+    minRows?: number;
+    /**
+     * Lines the field grows to before it scrolls (default 8). At least
+     * `minRows`.
+     */
+    maxRows?: number;
+    /** Quiet, sentence-style supporting copy at the start of the action row. */
+    hint?: string;
+    /** Trailing controls in the action row, normally one brand Send button. */
+    actions: KerfUiContent;
+    /** Disable the field; the app disables its own actions. */
+    disabled?: boolean;
+    /**
+     * Opt in to Enter-to-send: with `wireComposers` running over an ancestor,
+     * Enter (or Cmd/Ctrl+Enter) in the field activates the first trailing
+     * action, Shift+Enter inserts a newline, and an Enter that commits an IME
+     * composition or meets an empty message does not send. The field announces
+     * the shortcut with `aria-keyshortcuts`.
+     */
+    submitOnEnter?: boolean;
+    /** Safe `data-*` identity on the root. */
+    rootAttributes?: ComposerRootAttributes;
+    className?: string;
+    /** Native named-slot assignment, such as a `wa-dialog`'s `footer`. */
+    slot?: string;
+}
+/**
+ * A chat or prompt composer: a raised frame whose border turns brand while
+ * focus is within, holding a borderless message field that grows with its
+ * content between `minRows` and `maxRows` lines, above an action row with an
+ * optional hint and trailing actions. The app owns the value and sending;
+ * `submitOnEnter` with `wireComposers` adds Enter-to-send.
+ */
+declare function Composer({ label, name, id, value, placeholder, minRows, maxRows, hint, actions, disabled, submitOnEnter, rootAttributes, className, slot, }: ComposerProps): kerfjs.SafeHtml;
 
-export { ChoiceChips, type ChoiceChipsChoice, type ChoiceChipsProps, type ChoiceChipsSize, type ChoiceChipsSwatch };
+export { Composer, type ComposerProps, type ComposerRootAttributes };
+```
+
+## `@kerfjs/ui/wire-composers`
+
+```ts
+type Root = HTMLElement | Document;
+/**
+ * Enter-to-send for every `Composer` rendered with `submitOnEnter` below
+ * root. In its field, Enter (alone or with Cmd or Ctrl) activates the
+ * composer's first trailing action, so a keyboard send runs the same
+ * delegated handler as a click. Shift+Enter and Alt+Enter insert a newline.
+ * Nothing is sent, and no newline is inserted, when the message is empty or
+ * whitespace-only, the key is auto-repeating, or the first action is
+ * disabled, loading, or `aria-disabled`. An Enter that commits an IME
+ * composition (`isComposing`, keyCode 229, or between `compositionstart` and
+ * `compositionend`) is left to the input method. Dispose with the owning
+ * application.
+ */
+declare function wireComposers(root: Root): () => void;
+
+export { wireComposers };
 ```
 
 ## `@kerfjs/ui/select`
@@ -3237,7 +3523,12 @@ interface StateBannerProps {
     urgency?: StateBannerUrgency;
     /** Keep the detail beside the title, or give it its own line. */
     copyLayout?: StateBannerCopyLayout;
-    /** Place the action beside the copy or on a separate trailing row. */
+    /**
+     * `trailing` (the default) puts the action beside the copy while the copy
+     * keeps its minimum readable width, and otherwise wraps it onto its own
+     * end-aligned trailing row, at any viewport or container width. `below`
+     * always gives the action that separate trailing row.
+     */
     actionPlacement?: StateBannerActionPlacement;
     /**
      * `card` (the default) is an inset, rounded, fully bordered banner beside
@@ -3391,7 +3682,7 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape, ensureSunken
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
-export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-DTcTXWMS.js';
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, l as TokenSearchTrailingActionAttributes, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-aYR0YAei.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 ```
@@ -3400,7 +3691,7 @@ import './semantic-content-BbzjvSu9.js';
 
 ```ts
 import { Signal } from 'kerfjs';
-import { d as TokenSearchModel } from './token-search-model-DTcTXWMS.js';
+import { d as TokenSearchModel } from './token-search-model-aYR0YAei.js';
 import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {
@@ -3689,10 +3980,16 @@ import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 import { BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
 import './css-values.js';
 
+/**
+ * A chip color role: a shared semantic tone, or `inherit`, which follows the
+ * surrounding foreground (a chip inside a `brand-loud` ContentItem bubble)
+ * and derives its fill, border, and focus ring from `currentColor`.
+ */
+type ChipTone = SemanticTone | 'inherit';
 interface ChipCommonProps {
     /** Decorative leading icon, normally an unsized LucideIcon. */
     icon?: SafeHtml;
-    tone?: SemanticTone;
+    tone?: ChipTone;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
     size?: BadgeSize;
@@ -3703,24 +4000,50 @@ interface ChipCommonProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-/** A removable chip needs both a delegated action and a specific accessible name. */
-type ChipProps = ChipCommonProps & ({
+type ChipLabelProps = {
     children: SafeHtml | string | number;
     truncate?: false;
 } | {
     children: string;
     truncate: true;
-}) & ({
+};
+interface ChipNoLinkProps {
+    href?: never;
+    download?: never;
+    external?: never;
+}
+/**
+ * A link chip renders a native `<a>` with Chip geometry. It cannot also carry
+ * a remove button, because a button inside a link is invalid.
+ */
+interface ChipLinkProps {
+    /** Native destination; the chip renders as an `<a>`. */
+    href: string;
+    /** Download the destination: `true`, or the suggested file name. */
+    download?: string | boolean;
+    /** Open in a new tab with a safe rel and announce that behavior. */
+    external?: boolean;
+    removeAction?: never;
+    removeLabel?: never;
+}
+/**
+ * A plain chip, a removable chip (a delegated action plus a specific
+ * accessible name), or a link chip (`href`, optional `download`/`external`).
+ */
+type ChipProps = ChipCommonProps & ChipLabelProps & (({
     removeAction: string;
     removeLabel: string;
-} | {
+} & ChipNoLinkProps) | ({
     removeAction?: never;
     removeLabel?: never;
-});
-/** A short label with an optional native remove button. The application owns removal. */
-declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, ...remove }: ChipProps): SafeHtml;
+} & ChipNoLinkProps) | ChipLinkProps);
+/**
+ * A short label with an optional native remove button, or a native link when
+ * `href` is set. The application owns removal and the link destination.
+ */
+declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, href, download, external, removeAction, removeLabel, }: ChipProps): SafeHtml;
 
-export { Chip, type ChipProps };
+export { Chip, type ChipProps, type ChipTone };
 ```
 
 ## `@kerfjs/ui/lucide-icon`
@@ -3788,9 +4111,24 @@ type DialogSurfaceHeight = CssLength | 'viewport';
 /**
  * How the dialog body lays out its children: `flow` (default) scrolls ordinary
  * content in the body; `fill` gives one child the body's whole height and
- * lets it own scrolling (a SplitView, a Pane, an editor).
+ * lets it own scrolling (a SplitView, a Pane, an editor); `fill-last` stacks
+ * the leading children at their natural height and gives the last child the
+ * remaining height to own its scrolling (a heading and notices above a
+ * scrolling transcript).
+ */
+type DialogSurfaceBodyLayout = 'flow' | 'fill' | 'fill-last';
+/**
+ * Where the dialog footer sits: `docked` (default) below the body, or
+ * `floating` over the body's block end, inset from the panel's inline and
+ * block-end edges on a transparent background (a chat composer).
+ */
+type DialogSurfaceFooterPresentation = 'docked' | 'floating';
+/**
+ * Where the dialog header sits: `docked` (default) above the body, or
+ * `floating` over the body's block-start edge on the translucent chrome
+ * material, so content scrolls visibly beneath the title bar.
  */
-type DialogSurfaceBodyLayout = 'flow' | 'fill';
+type DialogSurfaceHeaderPresentation = 'docked' | 'floating';
 /**
  * Application `data-*` identity on the DialogSurface root, such as
  * `data-key`; the surface's own configuration attributes stay protected.
@@ -3813,8 +4151,43 @@ interface DialogSurfaceProps {
      * height to fill. Takes precedence over `maxHeight`.
      */
     height?: DialogSurfaceHeight;
-    /** Body layout (default `flow`); `fill` lets one child own the body. */
+    /**
+     * Body layout (default `flow`); `fill` lets one child own the body and
+     * `fill-last` stacks fixed rows above one filling last child.
+     */
     bodyLayout?: DialogSurfaceBodyLayout;
+    /**
+     * Header placement (default `docked`); `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`, opaque under
+     * `prefers-reduced-transparency`, increased contrast, forced colors, or
+     * without `backdrop-filter`). The `/register` entry measures the header;
+     * the body reserves that height before its own inset, so its first content
+     * rests below the title bar. A `fill`/`fill-last` child that is the body's
+     * only child and opts into block-start `scrollClearance` (a `List` or
+     * `Pane`) takes the clearance inside its own scroll area instead, published
+     * as `--kui-scroll-clearance-block-start`, so its content scrolls visibly
+     * beneath the header. Unmeasured (without the register), the header stays
+     * docked. Keep header text in the normal text color: quiet text can fall
+     * below AA over the content passing beneath it.
+     */
+    headerPresentation?: DialogSurfaceHeaderPresentation;
+    /**
+     * Footer placement (default `docked`); `floating` lays the footer over the
+     * body's block end. The body reserves the footer's measured height so its
+     * last content is never hidden beneath it. A `fill`/`fill-last` child that
+     * opts into block-end `scrollClearance` (a `List` or `Pane`) takes that
+     * clearance inside its own scroll area instead, published as
+     * `--kui-scroll-clearance-block-end`, so its content scrolls visibly beneath
+     * the transparent footer.
+     */
+    footerPresentation?: DialogSurfaceFooterPresentation;
+    /**
+     * A floating footer's clearance from the panel's inline and block-end edges
+     * (default the 16px container inset). Choose a phone value such as
+     * `remify(8)` from `deviceClass()`; the scaffold adds no breakpoint.
+     */
+    footerOffset?: CssLength;
     /**
      * Safe `data-*` identity on the root. Give sibling dialogs distinct
      * `data-key`s so a re-render morphs each surface into itself instead of
@@ -3827,7 +4200,7 @@ interface DialogSurfaceProps {
     slot?: string;
 }
 /** Configure recurring Web Awesome dialog geometry without consumer ::part() CSS. */
-declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, bodyLayout, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, bodyLayout, headerPresentation, footerPresentation, footerOffset, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
 /** Where a PopoverDialogSurface appears: the top layer, or in flow. */
 type PopoverDialogSurfacePresentation = 'overlay' | 'embedded';
 /** Application `data-*` metadata on the surface root. */
@@ -3842,6 +4215,12 @@ type PopoverDialogSurfaceName = {
 type PopoverDialogSurfaceProps = PopoverDialogSurfaceName & {
     /** The root id: what an opening control's `popovertarget` names. */
     id?: string;
+    /**
+     * Id of the element whose text is the dialog's accessible description,
+     * such as a title `ToolbarText`'s `descriptionId`; rendered as
+     * `aria-describedby` on the `role="dialog"` root.
+     */
+    describedBy?: string;
     children: KerfUiContent;
     /**
      * `overlay` (default) is a native `popover="auto"` in the top layer:
@@ -3859,7 +4238,10 @@ type PopoverDialogSurfaceProps = PopoverDialogSurfaceName & {
     maxHeight?: DialogSurfaceMaxHeight;
     /** Edge clearance on each side of the viewport (default 16px). */
     viewportGutter?: CssLength;
-    /** Body layout (default `flow`); `fill` lets one child own the surface. */
+    /**
+     * Body layout (default `flow`); `fill` lets one child own the surface and
+     * `fill-last` stacks fixed rows above one filling last child.
+     */
     bodyLayout?: DialogSurfaceBodyLayout;
     rootAttributes?: PopoverDialogSurfaceDataAttributes;
     className?: string;
@@ -3873,7 +4255,7 @@ type PopoverDialogSurfaceProps = PopoverDialogSurfaceName & {
  * dismisses and leaves the page interactive. Use `DialogSurface` with
  * `wa-dialog` when the task must block the page.
  */
-declare function PopoverDialogSurface({ id, children, label, labelledBy, presentation, size, preferredWidth, height, maxHeight, viewportGutter, bodyLayout, rootAttributes, className, slot, }: PopoverDialogSurfaceProps): kerfjs.SafeHtml;
+declare function PopoverDialogSurface({ id, children, label, labelledBy, describedBy, presentation, size, preferredWidth, height, maxHeight, viewportGutter, bodyLayout, rootAttributes, className, slot, }: PopoverDialogSurfaceProps): kerfjs.SafeHtml;
 type PopupSurfaceInset = 'standard' | 'compact' | 'list-zero';
 interface PopupSurfaceProps {
     children: KerfUiContent;
@@ -3885,7 +4267,7 @@ interface PopupSurfaceProps {
 /** Configure recurring Web Awesome dropdown-menu geometry without consumer ::part() CSS. */
 declare function PopupSurface({ children, inset, className, slot, }: PopupSurfaceProps): kerfjs.SafeHtml;
 
-export { DialogSurface, type DialogSurfaceBodyLayout, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSize, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
+export { DialogSurface, type DialogSurfaceBodyLayout, type DialogSurfaceFooterPresentation, type DialogSurfaceHeaderPresentation, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSize, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
 ```
 
 ## `@kerfjs/ui/text`
@@ -4336,7 +4718,7 @@ export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 ## `@kerfjs/ui/token-search-model`
 
 ```ts
-export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, l as createTokenSearchModel } from './token-search-model-DTcTXWMS.js';
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, m as createTokenSearchModel } from './token-search-model-aYR0YAei.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 ```
@@ -4395,6 +4777,12 @@ import { PopoverOptions, OverlayContent, OverlayHandle } from 'kerfjs/overlay';
 interface AnchoredSurfaceOptions extends Pick<PopoverOptions, 'placement' | 'align' | 'gap' | 'dismiss' | 'initialFocus' | 'onDismiss' | 'outsideIgnore' | 'container'> {
     /** Accessible name for the non-modal dialog. */
     label: string;
+    /**
+     * Gutter in px kept between the surface and the viewport edges when it is
+     * clamped horizontally and fitted vertically. Default `8`, the same gutter as
+     * the surface's maximum size.
+     */
+    viewportMargin?: number;
     /**
      * Where to append the surface. Default: inside the anchor's open modal
      * dialog — a native `<dialog>`'s host slot, or a slot kerf creates in a
@@ -4403,20 +4791,42 @@ interface AnchoredSurfaceOptions extends Pick<PopoverOptions, 'placement' | 'ali
      * cannot resolve; an element inside an open modal closes the surface with it.
      */
     container?: Element;
+    /**
+     * Surface tone. `'default'` follows the anchor's color scheme. `'dark'` is
+     * the loud, inverse tone of a `ToolbarControlGroup` / `ToolbarText`
+     * `tone="dark"`, for a popup anchored to dark media chrome (a volume popup
+     * over a video preview): dark beside a light page and light beside a dark
+     * one, so the popup matches the control group that opened it. The surface
+     * takes the opposite of the anchor's color scheme, so it and every Kerf UI
+     * or Web Awesome component inside it resolve the same semantic
+     * `light-dark()` tokens to the other side: no new colors, no child
+     * overrides. While open it follows a live switch of that scheme (the OS
+     * preference, or an app theme class or attribute on an ancestor). Default
+     * `'default'`.
+     */
+    tone?: AnchoredSurfaceTone;
 }
+/** {@link AnchoredSurfaceOptions.tone}: follow the anchor's scheme, or invert it. */
+type AnchoredSurfaceTone = 'default' | 'dark';
 /** A viewport pointer location; `context` is the element under the pointer. */
 interface AnchoredSurfacePoint {
     x: number;
     y: number;
     /**
      * Pass the event target when opening from inside a modal dialog, native or
-     * Web Awesome (`wa-dialog`, `wa-drawer`).
+     * Web Awesome (`wa-dialog`, `wa-drawer`). The dark tone also reads its
+     * color scheme from `context`, so a region with its own `color-scheme` is
+     * honored; without it the scheme is the modal scope's (or the page's).
      */
     context?: Element;
 }
 /**
  * Open app-owned content beside an element. The surface owns its Kerf UI chrome;
  * kerfjs/overlay owns positioning, top-layer/modal hosting, focus, and dismissal.
+ * The surface stays `viewportMargin` inside the viewport edges and fits its
+ * height to the room beside the anchor (the roomier side when neither holds it),
+ * scrolling its content; `--kui-anchored-surface-available-height` exposes that
+ * room to the content, updated as the page scrolls or resizes.
  * The caller owns content, action policy, and calling `close()` when an action
  * completes. `initialFocus` defaults to the first focusable descendant; set it
  * to `false` for read-only help that should leave focus on its trigger.
@@ -4429,7 +4839,7 @@ declare function openAnchoredSurface(anchor: Element, content: OverlayContent, o
  */
 declare function openAnchoredSurfaceAt(point: AnchoredSurfacePoint, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
 
-export { type AnchoredSurfaceOptions, type AnchoredSurfacePoint, openAnchoredSurface, openAnchoredSurfaceAt };
+export { type AnchoredSurfaceOptions, type AnchoredSurfacePoint, type AnchoredSurfaceTone, openAnchoredSurface, openAnchoredSurfaceAt };
 ```
 
 ## `@kerfjs/ui/icon-button`
@@ -4674,7 +5084,7 @@ interface CornerStatusProps {
 }
 /**
  * A non-dismissible status surface pinned to a viewport corner — "Loading…",
- * "Updating tickets… 3 of 12" — for app-level progress that has no better
+ * "Updating Tickets… 3 of 12" — for app-level progress that has no better
  * home beside the affected work. The application owns its lifetime: render it
  * while the work runs and remove it when the work ends. It carries no role of
  * its own; the composed `StateBanner` is the polite live region. Use a toast