@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.57

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.55` and `kerfjs@5.0.0-beta.55`. 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.57` and `kerfjs@5.0.0-beta.57`. 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`
 
@@ -48,9 +48,8 @@ type CssColor = CssValue & {
  * a surface. Mint it with {@link uiColor} and a foreground token name
  * ({@link UiForegroundColorName}) or with {@link foregroundColorVar}. It is a
  * {@link CssColor}, but a plain `CssColor` is not a foreground color: fill,
- * border, and surface tokens (including the `success` / `warning` / `danger` /
- * `pop` fill aliases) are pale backgrounds that leave a foreground nearly
- * invisible.
+ * border, and surface tokens are pale backgrounds that leave a foreground
+ * nearly invisible.
  */
 type CssForegroundColor = CssColor & {
     readonly [cssForegroundColorBrand]: 'CssForegroundColor';
@@ -60,16 +59,11 @@ type CssFlexBasis = CssLength | 'auto' | 'content' | 'min-content' | 'max-conten
 type CssSizeKeyword = 'auto' | 'min-content' | 'max-content' | 'fit-content';
 /** A complete width/height value accepted by dimension-valued UI props. */
 type CssSize = CssLength | CssSizeKeyword;
-declare const uiColorNames: readonly ["accent", "accent-text", "border", "border-quiet", "brand-border-loud", "brand-border-normal", "brand-border-quiet", "brand-fill-loud", "brand-fill-normal", "brand-fill-quiet", "brand-on-fill", "brand-on-loud", "brand-on-normal", "brand-on-quiet", "danger", "danger-border-loud", "danger-border-normal", "danger-border-quiet", "danger-fill-loud", "danger-fill-normal", "danger-fill-quiet", "danger-on-fill", "danger-on-loud", "danger-on-normal", "danger-on-quiet", "danger-text", "neutral-border-loud", "neutral-border-normal", "neutral-border-quiet", "neutral-fill-loud", "neutral-fill-normal", "neutral-fill-quiet", "neutral-on-loud", "neutral-on-normal", "neutral-on-quiet", "pop", "pop-border-loud", "pop-border-normal", "pop-border-quiet", "pop-fill-loud", "pop-fill-normal", "pop-fill-quiet", "pop-on-fill", "pop-on-loud", "pop-on-normal", "pop-on-quiet", "pop-text", "success", "success-border-loud", "success-border-normal", "success-border-quiet", "success-fill-loud", "success-fill-normal", "success-fill-quiet", "success-on-fill", "success-on-loud", "success-on-normal", "success-on-quiet", "success-text", "surface", "surface-lowered", "surface-raised", "text", "text-link", "text-quiet", "warning", "warning-border-loud", "warning-border-normal", "warning-border-quiet", "warning-fill-loud", "warning-fill-normal", "warning-fill-quiet", "warning-on-fill", "warning-on-loud", "warning-on-normal", "warning-on-quiet", "warning-text"];
+declare const uiColorNames: readonly ["brand-border-loud", "brand-border-normal", "brand-border-quiet", "brand-fill-loud", "brand-fill-normal", "brand-fill-quiet", "brand-on-fill", "brand-on-loud", "brand-on-normal", "brand-on-quiet", "danger-border-loud", "danger-border-normal", "danger-border-quiet", "danger-fill-loud", "danger-fill-normal", "danger-fill-quiet", "danger-on-fill", "danger-on-loud", "danger-on-normal", "danger-on-quiet", "neutral-border-loud", "neutral-border-normal", "neutral-border-quiet", "neutral-fill-loud", "neutral-fill-normal", "neutral-fill-quiet", "neutral-on-loud", "neutral-on-normal", "neutral-on-quiet", "pop-border-loud", "pop-border-normal", "pop-border-quiet", "pop-fill-loud", "pop-fill-normal", "pop-fill-quiet", "pop-on-fill", "pop-on-loud", "pop-on-normal", "pop-on-quiet", "success-border-loud", "success-border-normal", "success-border-quiet", "success-fill-loud", "success-fill-normal", "success-fill-quiet", "success-on-fill", "success-on-loud", "success-on-normal", "success-on-quiet", "surface", "surface-lowered", "surface-raised", "text", "text-link", "text-quiet", "warning-border-loud", "warning-border-normal", "warning-border-quiet", "warning-fill-loud", "warning-fill-normal", "warning-fill-quiet", "warning-on-fill", "warning-on-loud", "warning-on-normal", "warning-on-quiet"];
 /** Names of the public `--kui-color-*` semantic tokens. */
 type UiColorName = (typeof uiColorNames)[number];
-/**
- * The semantic tokens that paint a foreground: the `*-on-*` roles, the text
- * roles, and their `*-text` compatibility aliases. The bare `success`,
- * `warning`, `danger`, `pop`, and `accent` aliases are quiet fills, not
- * foregrounds.
- */
-type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | `${string}-text` | 'text' | 'text-quiet' | 'text-link'>;
+/** The semantic tokens that paint a foreground: the `*-on-*` and text roles. */
+type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | 'text' | 'text-quiet' | 'text-link'>;
 /** Kerf UI's complete spacing-token vocabulary. `s` and `xl` are exceptions. */
 type UiSpaceName = 'none' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl';
 /** Create a complete pixel length. */
@@ -124,6 +118,7 @@ export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, ty
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { CssLength } from './css-values.js';
 
 type DisclosureDirection = 'up' | 'down' | 'left' | 'right';
 interface DisclosureArrowProps {
@@ -132,11 +127,13 @@ interface DisclosureArrowProps {
     closedDirection?: DisclosureDirection;
     /** Replacement icons should use right as their unrotated orientation. */
     icon?: SafeHtml;
+    /** Typed box size for the square visual. Default: `remify(18px)`. */
+    size?: CssLength;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function DisclosureArrow({ open, openDirection, closedDirection, icon, className, slot, }: DisclosureArrowProps): SafeHtml;
+declare function DisclosureArrow({ open, openDirection, closedDirection, icon, size, className, slot, }: DisclosureArrowProps): SafeHtml;
 
 export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 ```
@@ -145,23 +142,32 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { D as DividerSides } from './divider-sides-BzB6rphT.js';
 import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 interface ToolbarProps {
     leading?: KerfUiContent;
     center?: KerfUiContent;
     trailing?: KerfUiContent;
     label?: string;
-    /** Physical divider edges in canonical top/right/bottom/left order. Defaults to bottom. */
-    dividerSides?: DividerSides;
+    /**
+     * Physical divider edges in canonical top/right/bottom/left order, drawn
+     * always. Defaults to none: a toolbar pinned over or under scrolling content
+     * gets its divider from the scroll state instead — a `Pane` draws the line
+     * between its chrome and content while content is scrolled away beneath it,
+     * and `wireScrollDividers` `targets` can name a toolbar as chrome, which
+     * then draws its facing side the same way.
+     */
+    dividerSides?: Sides;
     /** Horizontal treatment of the center zone. Defaults to centered content. */
     centerAlign?: 'center' | 'stretch';
     /**
      * Component-owned responsive layout; applications choose the policy rather
      * than restyling toolbar internals. Under every policy the trailing zone
-     * wraps its groups instead of clipping an action.
+     * wraps its groups instead of clipping an action, and the center zone keeps
+     * its whole content width: when the zones do not fit one row, the leading
+     * title truncates with an ellipsis rather than the center overlapping it.
      * - `none` keeps one row; the leading identity truncates first.
      * - `stack` stacks the zones at `responsiveAt`, wrapping stacked control
      *   groups onto further rows.
@@ -186,9 +192,15 @@ interface ToolbarProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+/**
+ * A toolbar's configuration, apart from its content: the props a composite
+ * that renders a `Toolbar` for the app (a Workbench or CollapsiblePanel
+ * toolbar) forwards, so the app configures that toolbar instead of styling it.
+ */
+type ToolbarConfig = Pick<ToolbarProps, 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
 declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { DividerSides, Toolbar, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -219,6 +231,12 @@ interface ToolbarTextBaseProps {
      * instead. Default true.
      */
     ellipsis?: boolean;
+    /**
+     * Grow to fill the free space of the flex row it sits in (a Toolbar zone),
+     * truncating at the space left by its siblings instead of taking only its
+     * text's width. Default false.
+     */
+    fill?: boolean;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
@@ -231,7 +249,7 @@ type ToolbarTextWrappingProps = {
     maxLines?: never;
 };
 type ToolbarTextProps = ToolbarTextBaseProps & ToolbarTextWrappingProps;
-declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, slot, }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
 ```
@@ -316,6 +334,7 @@ export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, ty
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssLength } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 /** Where a {@link FloatingToolbar} floats within its positioned container. */
@@ -330,6 +349,13 @@ interface FloatingToolbarProps {
      * Default: `'bottom-end'`.
      */
     position?: FloatingToolbarPosition;
+    /**
+     * Distance from the container edges named by `position`. Default:
+     * `space('m')` (16px, 8px past a top toolbar's own inset). Omit it inside a
+     * `Workbench`, `CollapsiblePanel`, or `ResizableRegion` restore corner: the
+     * corner owns the inset there and sets it to zero.
+     */
+    inset?: CssLength;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -339,14 +365,17 @@ interface FloatingToolbarProps {
  * ancestor — a transparent, forced-dark cluster of controls (e.g. a drawer
  * restore button) that sits over the content but NOT over dialogs or overlays
  * (it is not in the top layer). It is inset from the container edges by
- * `--kui-floating-toolbar-inset` (default `--kui-space-m`, i.e. 8px more than a
- * top toolbar's own inset); override that token, on the toolbar or an
- * ancestor, to move it. Inside a `Workbench`, `CollapsiblePanel`, or
+ * `inset` (default `--kui-space-m`, i.e. 8px more than a top toolbar's own
+ * inset); pass a typed length to move it. Inside a `Workbench`, `CollapsiblePanel`, or
  * `ResizableRegion` restore corner the corner owns the inset, so the toolbar
- * floats from the corner's own position. The app owns the controls and their
- * behavior — wire them with `delegate()` as usual.
+ * floats from the corner's own position. While one of those layouts has a
+ * side overlay open over the toolbar's region (a Workbench rail overlay, a
+ * `wireSidebar` compact overlay, an overlay `CollapsiblePanel` or horizontal
+ * `ResizableRegion`), the toolbar is hidden — unfocusable and out of the
+ * accessibility tree — until the overlay closes. The app owns the controls
+ * and their behavior — wire them with `delegate()` as usual.
  */
-declare function FloatingToolbar({ children, label, position, className, slot, }: FloatingToolbarProps): kerfjs.SafeHtml;
+declare function FloatingToolbar({ children, label, position, inset, className, slot, }: FloatingToolbarProps): kerfjs.SafeHtml;
 
 export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };
 ```
@@ -431,6 +460,7 @@ export { PopupMenu, type PopupMenuDivider, type PopupMenuEntry, type PopupMenuHe
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { HeadingLevel } from './toolbar-text.js';
 
 type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -471,6 +501,8 @@ interface ListHeaderBaseProps {
 type ListHeaderModeProps = {
     /** Render the title as a controlled disclosure trigger. */
     toggle: true;
+    /** A toggle's label is its button text, not a heading. */
+    headingLevel?: never;
     action: string;
     expanded: boolean;
     actionIcon?: SafeHtml;
@@ -480,6 +512,11 @@ type ListHeaderModeProps = {
 } | {
     /** Render a separately named trailing action. */
     toggle?: false;
+    /**
+     * Native heading level (`h1`–`h6`) of the label. Default `2`. Match the
+     * document outline; the visual treatment does not change.
+     */
+    headingLevel?: HeadingLevel;
     action: string;
     actionLabel: string;
     actionIcon: SafeHtml;
@@ -489,6 +526,11 @@ type ListHeaderModeProps = {
 } | {
     /** Render a passive section heading. */
     toggle?: false;
+    /**
+     * Native heading level (`h1`–`h6`) of the label. Default `2`. Match the
+     * document outline; the visual treatment does not change.
+     */
+    headingLevel?: HeadingLevel;
     action?: never;
     actionLabel?: never;
     actionIcon?: never;
@@ -513,7 +555,7 @@ type ListHeaderIndicatorProps = {
     status?: SafeHtml;
 };
 type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps & ListHeaderModeProps;
-declare function ListHeader({ label, count, countLabel, badge, status, density, divider, inline, width, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
+declare function ListHeader({ label, headingLevel, count, countLabel, badge, status, density, divider, inline, width, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -523,10 +565,10 @@ export { ListHeader, type ListHeaderProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
-import { D as DividerSides, S as Sides } from './divider-sides-BzB6rphT.js';
 import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -558,7 +600,7 @@ interface ListProps {
     /** Own vertical scrolling and overscroll containment. */
     scrollable?: boolean;
     /** Physical divider edges in canonical top/right/bottom/left order. */
-    dividerSides?: DividerSides;
+    dividerSides?: Sides;
     /** Physical sides that receive the standard 17px text inset. */
     textInsets?: Sides;
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
@@ -569,10 +611,17 @@ interface ListProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+/**
+ * A list's configuration, apart from its content and styling hooks: the props a
+ * composite that renders a `List` for the app (the Workbench's `mainHeader` /
+ * `mainFooter` chrome) forwards, so the app configures that list instead of
+ * styling it. An omitted or `undefined` field keeps the composite's default.
+ */
+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, gap, flex, fill, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, DividerSides, HorizontalAlignment, List, type ListProps, ListVerticalAlignment, Sides, UiSpaceName };
+export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, List, type ListConfig, type ListProps, ListVerticalAlignment, Sides, UiSpaceName };
 ```
 
 ## `@kerfjs/ui/list-action-row`
@@ -702,8 +751,8 @@ export { ListItem, type ListItemProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 interface ListInsetControlProps {
     /** Control(s) that own their own border and padding (e.g. an input, a `wa-*`). */
@@ -729,8 +778,8 @@ export { ListInsetControl, type ListInsetControlProps, Sides };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 type ListInsetTextRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -741,13 +790,6 @@ interface ListInsetTextProps {
     children: KerfUiContent | string;
     /** Physical inset sides in canonical top/right/bottom/left order. Defaults to all sides. */
     sides?: Sides;
-    /**
-     * @deprecated Pass `sides="rl"` instead. Keep only the horizontal geometry (inline margin, left/right border, and
-     * left/right padding) and drop the vertical margin, border, and padding. Use it
-     * when the text edge must still align with bordered items but the line should not
-     * add its own vertical box space — tight text layout inside a content region.
-     */
-    horizontalOnly?: boolean;
     className?: string;
     /** Safe `data-*` metadata; component-owned structural attributes stay protected. */
     rootAttributes?: ListInsetTextRootAttributes;
@@ -759,14 +801,65 @@ interface ListInsetTextProps {
  * transparent border, and 8px padding — so a plain string lines up with
  * bordered `.kui-content` items (its text edge lands at the same 17px inset).
  * Use it for text elements that have no margin, border, or padding of their own.
- * Pass `horizontalOnly` to keep the horizontal inset but drop the vertical box
+ * Pass `sides="rl"` to keep the horizontal inset but drop the vertical box
  * space for tight text layout.
  */
-declare function ListInsetText({ children, sides, horizontalOnly, className, rootAttributes, slot, }: ListInsetTextProps): kerfjs.SafeHtml;
+declare function ListInsetText({ children, sides, className, rootAttributes, slot, }: ListInsetTextProps): kerfjs.SafeHtml;
 
 export { ListInsetText, type ListInsetTextProps, Sides };
 ```
 
+## `@kerfjs/ui/content-item`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** Whether the item's always-reserved 1px border is transparent or visible. */
+type ContentItemFrame = 'none' | 'framed';
+/** Corner shape: the 12px rounded rectangle or the 22px pill. */
+type ContentItemShape = 'rounded' | 'pill';
+type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+}>;
+interface ContentItemProps {
+    /** Item content; a plain string is allowed for bare copy. */
+    children?: KerfUiContent | string;
+    /**
+     * `framed` paints the standard neutral border in the 1px the item always
+     * reserves, so framing never changes geometry. Frame only an item that
+     * marks a real distinction. Defaults to `none` (transparent border).
+     */
+    frame?: ContentItemFrame;
+    /** Corner shape. Defaults to `rounded`. */
+    shape?: ContentItemShape;
+    /**
+     * Names the item as a distinct region (`role="region"`). Omit it for an
+     * ordinary item, which stays a non-landmark grouping.
+     */
+    ariaLabel?: string;
+    /**
+     * Makes the item a programmatic focus target (`tabindex="-1"`, never a tab
+     * stop), for example the preferred initial focus of a NavStack view when
+     * combined with `data-nav-focus` in `rootAttributes`.
+     */
+    focusTarget?: boolean;
+    className?: string;
+    /** Safe `data-*` metadata; component-owned structural attributes stay protected. */
+    rootAttributes?: ContentItemRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * One self-contained `.kui-content` child: an 8px inline margin, a real 1px
+ * border (transparent unless `framed`), 8px padding, and a rounded or pill
+ * radius. It owns that whole geometry, so wrappers must not add more.
+ */
+declare function ContentItem({ children, frame, shape, ariaLabel, focusTarget, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
+
+export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemShape };
+```
+
 ## `@kerfjs/ui/value-table`
 
 ```ts
@@ -938,11 +1031,89 @@ declare function wireTabBars(root: HTMLElement | Document, { onReorder, activati
 export { TabActivation, type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
 ```
 
+## `@kerfjs/ui/wire-scroll-dividers`
+
+```ts
+/**
+ * An app-owned scroll arrangement outside a `Pane`: the `id` of the element
+ * that scrolls and the `id`s of the pinned chrome on each physical side of it.
+ * Each named chrome element shows its divider on the side facing the scroller
+ * while content is scrolled away beyond that side. Ids are resolved below the
+ * wired root on every refresh, so a re-render that replaces an element keeps
+ * the pairing.
+ */
+interface ScrollDividerTarget {
+    /** The `id` of the scrolling element. */
+    scroller: string;
+    /** Chrome above the scroller: shows its bottom divider once scrolled down. */
+    top?: string;
+    /**
+     * Chrome right of the scroller: shows its left divider while content is
+     * hidden beyond the scroller's right edge (never when nothing overflows).
+     */
+    right?: string;
+    /**
+     * Chrome below the scroller: shows its top divider while content is hidden
+     * beyond the scroller's bottom edge (never when nothing overflows).
+     */
+    bottom?: string;
+    /** Chrome left of the scroller: shows its right divider once scrolled right. */
+    left?: string;
+}
+interface WireScrollDividersOptions {
+    /**
+     * App-owned scroll arrangements to pair beyond the ones found by structure
+     * (every `Pane`'s header and footer around its content, every `NavStack`'s
+     * and `TabScaffold`'s chrome around its active region, and every `TabBar`
+     * strip).
+     */
+    targets?: readonly ScrollDividerTarget[];
+}
+/**
+ * Wire scroll dividers below `root`: a divider between pinned chrome and the
+ * content that scrolls beside it shows only while content is scrolled away
+ * from that edge. Near edges (top, left) hide at the scroll start; far edges
+ * (bottom, right) hide at the scroll end and whenever nothing overflows.
+ *
+ * The wiring only reports scroll state; each component draws its own divider
+ * from it. It writes `data-scroll-overflow` (the edges with hidden content, in
+ * canonical `t`/`r`/`b`/`l` order) on each scroller, and `data-scroll-divider`
+ * (the sides to draw) on each paired chrome element:
+ *
+ * - every `Pane` with a header or footer: its header shows a bottom divider and
+ *   its footer a top divider (drawn by the Pane, per its `chromeDividers`);
+ * - every `NavStack`'s top chrome and bottom toolbar around its active view,
+ *   and every `TabScaffold`'s bar under its active scene: the chrome shows a
+ *   bottom (top chrome) or top (bottom toolbar, bar) divider. The scroller is
+ *   whichever element actually scrolls there: the view or scene itself, or,
+ *   through a sole child with no chrome of its own on that edge, a `Pane`'s
+ *   content or a nested `NavStack` / `TabScaffold` region (a Pane's own header
+ *   or footer draws that boundary instead);
+ * - every `TabBar` strip: the bar draws a divider on each side of the strip
+ *   whose tabs are scrolled out of view;
+ * - each app-owned `targets` pairing: a `Toolbar` or `List` named as chrome
+ *   draws the divider on its facing side.
+ *
+ * Structure is re-read after every DOM change below root (a re-render that
+ * drops the attributes gets them back before paint), scroll is tracked with
+ * one capturing listener, and size changes of each scroller and its children
+ * with a `ResizeObserver`. Returns a disposer that removes every attribute it
+ * wrote. See `docs/23-app-layouts.md` §3.7.
+ */
+declare function wireScrollDividers(root: HTMLElement | Document, { targets }?: WireScrollDividersOptions): () => void;
+
+export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDividers };
+```
+
 ## `@kerfjs/ui/nav-stack`
 
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { ToolbarConfig } from './toolbar.js';
+import { ToolbarTextSize, HeadingLevel } from './toolbar-text.js';
+import './pane.js';
+import './sides-BPSWde0A.js';
 
 /**
  * One entry in a {@link NavStack}. The app owns the stack as an array (usually a
@@ -954,23 +1125,62 @@ interface NavStackView {
     content: KerfUiContent;
     /** Title shown in the top toolbar for this view. */
     title?: string;
+    /** Leading groups for this view's top toolbar, after the back control and before the title. */
+    leading?: KerfUiContent;
+    /** Center content for this view's top toolbar (placed per `toolbarConfig.centerAlign`). */
+    center?: KerfUiContent;
     /** Trailing actions for this view's top toolbar. */
     toolbar?: KerfUiContent;
     /** Bottom toolbar for this view. Cross-fades with the top chrome on navigation. */
     bottomToolbar?: KerfUiContent;
 }
+/**
+ * The top toolbar's configuration. Its `ToolbarConfig` forwards to the real
+ * `Toolbar` the stack renders; by default that toolbar draws no divider and
+ * claims the top and side safe-area edges the stack still touches.
+ */
+interface NavStackToolbarConfig extends ToolbarConfig {
+    /** Accessible name of the top toolbar (default: none). */
+    label?: string;
+    /** Size of the view title's `ToolbarText` (default `large`). */
+    titleSize?: ToolbarTextSize;
+    /** Expose the view title as a heading at this level (default: a plain span). */
+    headingLevel?: HeadingLevel;
+}
 interface NavStackProps {
     id: string;
     /** Accessible name for the stack region. */
     label: string;
     /** The stack, root first; the last entry is the active top view. */
     views: NavStackView[];
-    /** Accessible label for the back control (default "Back"). */
+    /** Accessible label for the icon-only back control (default "Back"). */
     backLabel?: string;
+    /** The back control's icon (default a chevron-left `LucideIcon`). */
+    backIcon?: KerfUiContent;
+    /**
+     * Visible text beside the back icon, such as the previous view's title
+     * (default: icon only). When set, the text names the control and
+     * `backLabel` is not used.
+     */
+    backText?: string;
+    /** The top toolbar's configuration, forwarded to its `Toolbar`. */
+    toolbarConfig?: NavStackToolbarConfig;
     /** Hide the top toolbar entirely (rare — a fully custom-chrome view). */
     hideToolbar?: boolean;
     /** Optional persistent bottom toolbar used when the active view does not provide one. */
     bottomToolbar?: KerfUiContent;
+    /**
+     * The line under the top chrome and over the bottom toolbar, where they
+     * meet the active view. `scroll` (default) shows the chrome's line only
+     * while the view's content is scrolled beneath it, and the bottom
+     * toolbar's only while more content lies below — never when the content
+     * fits — once `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is
+     * wired above the stack; unwired, neither shows. `always` shows both
+     * without the wiring; `none` neither, even when wired. The line is drawn
+     * inside the chrome, so no state moves the chrome or the content. A
+     * `toolbarConfig.dividerSides` edge is the Toolbar's own and is unaffected.
+     */
+    chromeDividers?: 'scroll' | 'always' | 'none';
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -978,12 +1188,14 @@ interface NavStackProps {
 /**
  * A navigation stack (iOS-style push/pop). Renders every entry stacked, the last
  * one active; `@kerfjs/ui/wire-nav-stack`'s `wireNavStack` slides the content and
- * cross-fades the chrome across a change. A single-pane layout is a `NavStack`
- * with one entry. See `docs/23-app-layouts.md` §3.1.
+ * cross-fades the chrome across a change. Its top chrome is a real `Toolbar`: the
+ * back control and title lead, the active view's `leading` / `center` / `toolbar`
+ * content fills the zones, and `toolbarConfig` configures it. A single-pane
+ * layout is a `NavStack` with one entry. See `docs/23-app-layouts.md` §3.1.
  */
-declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className, slot, }: NavStackProps): kerfjs.SafeHtml;
+declare function NavStack({ id, label, views, backLabel, backIcon, backText, toolbarConfig, hideToolbar, bottomToolbar, chromeDividers, className, slot, }: NavStackProps): kerfjs.SafeHtml;
 
-export { NavStack, type NavStackProps, type NavStackView };
+export { NavStack, type NavStackProps, type NavStackToolbarConfig, type NavStackView };
 ```
 
 ## `@kerfjs/ui/wire-nav-stack`
@@ -1013,13 +1225,39 @@ export { type WireNavStackOptions, wireNavStack };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { NavStackProps, NavStackView } from './nav-stack.js';
+import { ResizableRegionProps } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './toolbar.js';
+import './pane.js';
+import './sides-BPSWde0A.js';
+import './toolbar-text.js';
 
-interface SplitViewResizable {
+/**
+ * The roomy list pane's `ResizableRegion`: its committed `size` and `min` /
+ * `max` limits, plus the region configuration that forwards unchanged
+ * (`separator`, `handleIcon`, `contentOverflow`, and collapse:
+ * `collapsed`, `transitioning`, `collapseMotion`, `restoreControl`,
+ * `restorePosition`). Omitted options keep the region's defaults.
+ */
+interface SplitViewResizable extends Pick<ResizableRegionProps, 'separator' | 'handleIcon' | 'contentOverflow' | 'collapsed' | 'transitioning' | 'collapseMotion' | 'restoreControl' | 'restorePosition'> {
     size: number;
     min: number;
     max: number;
 }
+/** One compact view's top- and bottom-toolbar content (see `NavStackView`). */
+type SplitViewCompactViewToolbars = Pick<NavStackView, 'leading' | 'center' | '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.
+ */
+interface SplitViewCompactStack extends Pick<NavStackProps, 'toolbarConfig' | 'backIcon' | 'backText' | 'hideToolbar' | 'bottomToolbar' | 'chromeDividers'> {
+    /** Toolbar content for the list (root) view. */
+    list?: SplitViewCompactViewToolbars;
+    /** Toolbar content for the pushed detail view. */
+    detail?: SplitViewCompactViewToolbars;
+}
 interface SplitViewProps {
     id: string;
     label: string;
@@ -1041,6 +1279,8 @@ interface SplitViewProps {
     detailTitle?: string;
     /** Back label for the compact NavStack (default "Back"). */
     backLabel?: string;
+    /** Compact NavStack configuration and per-view toolbars. */
+    compactStack?: SplitViewCompactStack;
     /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */
     resizable?: SplitViewResizable;
     className?: string;
@@ -1054,9 +1294,9 @@ interface SplitViewProps {
  * resizable wiring with `wireResizableRegions` and the compact back with
  * `wireNavStack`.
  */
-declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className, slot, }: SplitViewProps): kerfjs.SafeHtml;
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, compactStack, resizable, className, slot, }: SplitViewProps): kerfjs.SafeHtml;
 
-export { SplitView, type SplitViewProps, type SplitViewResizable };
+export { SplitView, type SplitViewCompactStack, type SplitViewCompactViewToolbars, type SplitViewProps, type SplitViewResizable };
 ```
 
 ## `@kerfjs/ui/pane`
@@ -1084,7 +1324,17 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-safe-area-block-end'?: never;
     'data-safe-area-inline-start'?: never;
     'data-safe-area-inline-end'?: never;
+    'data-chrome-placement'?: never;
+    'data-chrome-dividers'?: never;
 }>;
+/** How a Pane's header and footer relate to its scrolling content. */
+type PaneChromePlacement = 'fixed' | 'auto';
+/**
+ * When a Pane draws the divider between its pinned header or footer and its
+ * scrolling content: `scroll` while content is scrolled away beneath that
+ * chrome, as `wireScrollDividers` reports; `always`; or `none`.
+ */
+type PaneChromeDividers = 'scroll' | 'always' | 'none';
 interface PaneProps {
     /** Optional fixed chrome above the scrolling content, arranged vertically. */
     header?: KerfUiContent;
@@ -1092,6 +1342,24 @@ interface PaneProps {
     children?: KerfUiContent;
     /** Optional fixed chrome below the scrolling content. */
     footer?: KerfUiContent;
+    /**
+     * Whether the header and footer stay pinned around the scrolling content.
+     * `fixed` (default) always pins them. `auto` pins them while the pane is
+     * tall enough, and below 480px of height (30rem, so it scales with the text
+     * size) lets the whole pane scroll as one column, so tall chrome can never
+     * squeeze the content to nothing.
+     */
+    chromePlacement?: PaneChromePlacement;
+    /**
+     * The divider under the header and over the footer, where they meet the
+     * scrolling content. `scroll` (default) shows the header's divider only
+     * while the content is scrolled down, and the footer's only while more
+     * content lies below — never when the content fits — once
+     * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
+     * the pane; unwired, neither shows. `always` shows both; `none` neither.
+     * The line is drawn inside the chrome, so no state moves the content.
+     */
+    chromeDividers?: PaneChromeDividers;
     /** Root semantics. Defaults to `div`. */
     element?: PaneElement;
     /** Scrolling content semantics. Defaults to `div`. */
@@ -1120,29 +1388,39 @@ interface PaneProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+/**
+ * A pane's configuration, apart from its content and styling hooks: the props a
+ * composite that renders a `Pane` for the app (a Workbench panel or work area,
+ * 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'>;
 /**
  * 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, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
+declare function Pane({ header, children, footer, chromePlacement, chromeDividers, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
 
-export { Pane, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
+export { Pane, type PaneChromeDividers, type PaneChromePlacement, type PaneConfig, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
 ```
 
 ## `@kerfjs/ui/workbench`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { ListConfig } from './list.js';
+import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BFQxFITu.js';
-import { ToolbarProps } from './toolbar.js';
+import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BN4x0rth.js';
+import { ToolbarConfig } from './toolbar.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
-import './divider-sides-BzB6rphT.js';
-import './pane.js';
 
 /** The standard toggle a Workbench renders for a panel (see {@link PanelToggle}). */
 type WorkbenchPanelToggle = PanelToggle;
@@ -1155,8 +1433,13 @@ type WorkbenchPanelToggle = PanelToggle;
  * `FloatingToolbar` in the work area's bottom-end corner.
  */
 type WorkbenchPanelToolbar = PanelToolbar;
-/** The work area's top toolbar; collapsed rails add their groups to it. */
-interface WorkbenchMainToolbar {
+/**
+ * The work area's top toolbar; collapsed rails add their groups to it. Its
+ * configuration forwards to its `Toolbar`. It draws no divider of its own by
+ * default: the work area's `Pane` draws one under its header chrome, wherever
+ * that chrome ends, while `main` is scrolled (`mainPane.chromeDividers`).
+ */
+interface WorkbenchMainToolbar extends ToolbarConfig {
     label: string;
     /** The work area's title, usually an extra-large `ToolbarText`. */
     title?: KerfUiContent;
@@ -1165,26 +1448,27 @@ interface WorkbenchMainToolbar {
     center?: KerfUiContent;
     /** Groups at the trailing edge, before a collapsed right rail's groups. */
     trailing?: KerfUiContent;
-    /** The toolbar's narrow-width policy (see `Toolbar.responsive`). */
-    responsive?: ToolbarProps['responsive'];
-    responsiveAt?: ToolbarProps['responsiveAt'];
 }
-/** The work area's bottom toolbar; a collapsed drawer adds its groups to it. */
-interface WorkbenchMainBottomToolbar {
+/**
+ * The work area's bottom toolbar; a collapsed drawer adds its groups to it.
+ * Its configuration forwards to its `Toolbar`. It draws no divider of its own
+ * by default: the work area's `Pane` draws one over its footer chrome while
+ * more of `main` lies below (`mainPane.chromeDividers`).
+ */
+interface WorkbenchMainBottomToolbar extends ToolbarConfig {
     label: string;
     leading?: KerfUiContent;
+    center?: KerfUiContent;
     trailing?: KerfUiContent;
 }
 /**
- * The work area: the app's `main` under `mainToolbar` (and above
- * `mainBottomToolbar`), with each collapsed panel's groups added to the
- * toolbar on its side. Without either toolbar, `main` renders as given.
+ * Whether the work area's header or footer chrome stays pinned (`fixed`),
+ * scrolls away with the content (`scroll`), or stays pinned while the work
+ * area is tall enough and scrolls with the content when it is short (`auto`,
+ * the Pane's `chromePlacement="auto"`; it applies to the pinned header and
+ * footer together).
  */
-/**
- * Whether the work area's header or footer chrome stays pinned (`fixed`) or
- * scrolls away with the content (`scroll`).
- */
-type WorkbenchChromePlacement = 'fixed' | 'scroll';
+type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
 
 /**
  * The Workbench container breakpoint below which a panel presents as an
@@ -1217,6 +1501,14 @@ interface WorkbenchPanel {
     toolbar?: WorkbenchPanelToolbar;
     /** Optional bottom toolbar under a `toolbar` panel's content. */
     footer?: KerfUiContent;
+    /**
+     * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
+     * `{ contentElement: 'nav', contentLabel: 'Sections' }` for a navigation
+     * rail. Omitted or `undefined` fields keep the `Pane` defaults. Ignored
+     * without a `toolbar`, where `content` renders as given.
+     */
+    pane?: PaneConfig;
     /** Whether the panel is currently collapsed (the app owns this). */
     collapsed?: boolean;
     /**
@@ -1294,13 +1586,34 @@ interface WorkbenchProps {
      */
     mainBottomToolbar?: WorkbenchMainBottomToolbar;
     /**
-     * Whether `mainToolbar` and `mainHeader` stay pinned (`fixed`, default) or
+     * Whether `mainToolbar` and `mainHeader` stay pinned (`fixed`, default),
      * scroll away with `main` (`scroll`) — useful where large text would leave
-     * pinned chrome little room.
+     * pinned chrome little room — or stay pinned while the work area is tall
+     * enough and scroll with `main` when it is short (`auto`).
      */
     mainHeaderPlacement?: WorkbenchChromePlacement;
     /** The same for `mainFooter` and `mainBottomToolbar` (default `fixed`). */
     mainFooterPlacement?: WorkbenchChromePlacement;
+    /**
+     * Configuration for the work area's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`), which it has whenever it
+     * has a toolbar, `mainHeader`, or `mainFooter`; without that chrome, `main`
+     * renders as given and this is ignored. Omitted or `undefined` fields keep
+     * the `Pane` defaults.
+     */
+    mainPane?: PaneConfig;
+    /**
+     * Configuration for the `List` that holds `mainHeader` (`gap`, `hAlign`,
+     * `vAlign`, `dividerSides`, `textInsets`, `controlInsets`). Omitted or
+     * `undefined` fields keep the defaults (no divider: the work area's
+     * `Pane` draws the line under its header chrome).
+     */
+    mainHeaderList?: ListConfig;
+    /**
+     * The same for the `List` that holds `mainFooter` (no divider by default:
+     * the work area's `Pane` draws the line over its footer chrome).
+     */
+    mainFooterList?: ListConfig;
     leftRail?: WorkbenchPanel;
     rightRail?: WorkbenchPanel;
     bottomDrawer?: WorkbenchPanel;
@@ -1337,7 +1650,7 @@ interface WorkbenchProps {
  * lives outside it and stays reachable). A panel may opt in to drag and keyboard resizing with
  * `resizable`, which `wireWorkbench` drives. See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
 
 export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
 ```
@@ -1460,12 +1773,15 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BFQxFITu.js';
-export { c as collapsiblePanelToggleIcon } from './panel-toolbar-BFQxFITu.js';
+import { PaneConfig } from './pane.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BN4x0rth.js';
+export { c as collapsiblePanelToggleIcon } from './panel-toolbar-BN4x0rth.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import './lucide-icon.js';
 import 'lucide';
+import './toolbar.js';
+import './sides-BPSWde0A.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
 type CollapsiblePanelSide = PanelSide;
@@ -1523,6 +1839,14 @@ interface CollapsiblePanelProps {
     toolbar?: CollapsiblePanelToolbar;
     /** Optional bottom toolbar under a `toolbar` panel's content. */
     footer?: KerfUiContent;
+    /**
+     * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
+     * `{ contentElement: 'nav', contentLabel: 'Sections' }` for a navigation
+     * rail. Omitted or `undefined` fields keep the `Pane` defaults. Ignored
+     * without a `toolbar`, where `children` renders as given.
+     */
+    pane?: PaneConfig;
     separator?: ResizableRegionSeparator;
     collapseMotion?: ResizableRegionCollapseMotion;
     contentOverflow?: ResizableRegionContentOverflow;
@@ -1548,7 +1872,7 @@ interface CollapsiblePanelProps {
  * and persistence semantics, and with `CollapsiblePanelToggle` for the standard
  * affordance. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.
  */
-declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, footer, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, footer, pane, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
 interface CollapsiblePanelRelocatedProps {
     /** The panel's `id`. */
     panelId: string;
@@ -1645,7 +1969,7 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-interface TabScaffoldTab<Id extends string = string> {
+interface TabScaffoldTabBase<Id extends string> {
     id: Id;
     label: string;
     /** Decorative icon shown above the label in the bottom bar. */
@@ -1653,6 +1977,40 @@ interface TabScaffoldTab<Id extends string = string> {
     /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
     content: KerfUiContent;
 }
+/** A tab with an optional count or short-status badge. */
+interface TabScaffoldTabCountBadge {
+    /**
+     * Optional count or short status shown as a solid danger `Badge` at the
+     * top-trailing corner of the tab icon (the iOS tab-bar badge). Omitted, `''`,
+     * or non-finite numbers render no badge. The visual badge is `aria-hidden`;
+     * its meaning reaches assistive technology through `badgeLabel`.
+     *
+     * Pass `true` instead for the text-free dot (new content without a count).
+     */
+    badge?: string | number;
+    /**
+     * Localized phrase folded into the tab's accessible name as
+     * `"<label>, <badgeLabel>"` (for example `"3 unread"` → `"Inbox, 3 unread"`).
+     * Defaults to the badge text itself. Ignored when no badge renders.
+     */
+    badgeLabel?: string;
+}
+/** A tab with the text-free dot badge (new content without a count). */
+interface TabScaffoldTabDotBadge {
+    /**
+     * `true` shows a solid danger dot `Badge` at the top-trailing corner of the
+     * tab icon — the iOS tab-bar dot for new content without a count.
+     */
+    badge: true;
+    /**
+     * Required localized phrase folded into the tab's accessible name as
+     * `"<label>, <badgeLabel>"` (for example `"New activity"` →
+     * `"Feed, New activity"`). A dot has no text, so this is its only meaning.
+     */
+    badgeLabel: string;
+}
+/** One bottom-bar destination: its label, optional icon and badge, and content. */
+type TabScaffoldTab<Id extends string = string> = TabScaffoldTabBase<Id> & (TabScaffoldTabCountBadge | TabScaffoldTabDotBadge);
 interface TabScaffoldProps<Id extends string = string> {
     id: string;
     /** Accessible name for the tab bar. */
@@ -1660,6 +2018,16 @@ interface TabScaffoldProps<Id extends string = string> {
     tabs: readonly TabScaffoldTab<Id>[];
     /** The controlled active tab id (the app owns selection). */
     active: NoInfer<Id>;
+    /**
+     * The line over the tab bar, where it meets the active scene. `scroll`
+     * (default) shows it only while more of the scene's content lies below —
+     * never at the scroll end or when the content fits — once
+     * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
+     * the scaffold; unwired, it does not show. `always` shows it without the
+     * wiring; `none` never, even when wired. The line is the bar's own 1px top
+     * border, so no state moves the bar or a tab.
+     */
+    chromeDividers?: 'scroll' | 'always' | 'none';
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -1672,7 +2040,7 @@ interface TabScaffoldProps<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 TabScaffold<Id extends string>({ id, label, tabs, active, className, slot, }: TabScaffoldProps<Id>): SafeHtml;
+declare function TabScaffold<Id extends string>({ id, label, tabs, active, chromeDividers, className, slot, }: TabScaffoldProps<Id>): SafeHtml;
 
 export { TabScaffold, type TabScaffoldProps, type TabScaffoldTab };
 ```
@@ -1838,9 +2206,20 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 ```ts
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
-import { a as CatalogProps } from './types-D6vzj-VT.js';
-export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-D6vzj-VT.js';
+import { a as CatalogProps } from './types-BuHELdXR.js';
+export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-BuHELdXR.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './toolbar.js';
+import './pane.js';
+import './sides-BPSWde0A.js';
+import './workbench.js';
+import './list.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './resizable-region.js';
+import './panel-toolbar-BN4x0rth.js';
+import './lucide-icon.js';
+import 'lucide';
 
 /**
  * Controlled, stateless component-catalog shell: a `Workbench` whose left rail
@@ -1849,7 +2228,7 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
  * standard toggle moves into the entry toolbar while it is collapsed, and on
  * a small screen the sidebar overlays the stage like any Workbench rail.
  */
-declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, className, slot, }: CatalogProps): kerfjs.SafeHtml;
+declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, sidebar, mainToolbar, footerToolbar, className, slot, }: CatalogProps): kerfjs.SafeHtml;
 
 /** How a specimen aligns its visible edge with its `ListHeader` label. */
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
@@ -1920,9 +2299,20 @@ export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleP
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { C as CatalogResource } from './types-D6vzj-VT.js';
+import { C as CatalogResource } from './types-BuHELdXR.js';
 import './semantic-content-BbzjvSu9.js';
 import 'kerfjs';
+import './toolbar.js';
+import './pane.js';
+import './sides-BPSWde0A.js';
+import './workbench.js';
+import './list.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './resizable-region.js';
+import './panel-toolbar-BN4x0rth.js';
+import './lucide-icon.js';
+import 'lucide';
 
 /**
  * Standard resource labels for a Kerf catalog detail footer. Keep these labels
@@ -1990,6 +2380,17 @@ interface WireCatalogOptions {
      * open overlay closes it.
      */
     collapsed?: Signal<boolean>;
+    /**
+     * The app-owned sidebar width signal for a Catalog rendered with
+     * `sidebar={{ resizable: true, size: sidebarSize.value }}`. Each committed
+     * drag or keyboard resize is written to it.
+     */
+    sidebarSize?: Signal<number>;
+    /**
+     * With `sidebarSize`, load and save the width under this storage key so the
+     * catalog remembers the user's sidebar width.
+     */
+    sidebarStorageKey?: string;
     /** The Catalog's `id`, when it is not the default `kui-catalog`. */
     id?: string;
 }
@@ -2024,9 +2425,11 @@ declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
  * item selection (and the related-entry popup menu), the sidebar collapse toggle, and
  * the theme toggle. The app owns the `active`/`collapsed`/`theme` signals and updates
  * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.
- * Returns a disposer.
+ * It also wires the scroll dividers below root (`wireScrollDividers`), so the
+ * catalog's panes and every example in it show their chrome dividers only
+ * while scrolled. Returns a disposer.
  */
-declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, id: catalogId, }: WireCatalogOptions): () => void;
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, sidebarSize, sidebarStorageKey, id: catalogId, }: WireCatalogOptions): () => void;
 
 export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
 ```
@@ -2075,6 +2478,7 @@ export { SegmentedControl, type SegmentedControlAppearance, type SegmentedContro
 import { SafeHtml } from 'kerfjs';
 import { CssForegroundColor } from './css-values.js';
 import { LucideNode } from './lucide-icon.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import 'lucide';
 
 interface SelectChoice<Value extends string = string> {
@@ -2086,7 +2490,8 @@ interface SelectChoice<Value extends string = string> {
      * Foreground color for the optional icon: a semantic foreground token such
      * as `uiColor('success-on-quiet')`, or an application-owned
      * `foregroundColorVar('--app-icon-color')`. Fill tokens such as
-     * `uiColor('success')` are pale background tints and do not type-check.
+     * `uiColor('success-fill-quiet')` are pale background tints and do not
+     * type-check.
      */
     color?: CssForegroundColor;
     group?: string;
@@ -2110,7 +2515,6 @@ type SelectSelectedPresentation = 'label' | 'icon-only';
 type SelectFocusRingOwner = 'select' | 'group';
 interface SelectBaseProps<Value extends string = string> {
     name: string;
-    value: NoInfer<Value>;
     choices: readonly SelectChoice<Value>[];
     className?: string;
     /** Empty-value hint text shown in the closed control (the native select placeholder). */
@@ -2119,14 +2523,11 @@ interface SelectBaseProps<Value extends string = string> {
     hint?: string;
     disabled?: boolean;
     fitMenu?: boolean;
-    renderSelected?: (choice: SelectChoice<Value>) => SafeHtml;
     /** Render as an unanimated loading skeleton: the label above a static, empty control box. */
     placeholder?: boolean;
     /** Form (default), borderless toolbar, or intrinsic navigation chrome. */
     presentation?: SelectPresentation;
     size?: SelectSize;
-    /** Show only the selected choice icon while retaining the Select's accessible name. */
-    selectedPresentation?: SelectSelectedPresentation;
     /** Let an enclosing ToolbarControlGroup paint the composed focus ring. */
     focusRingOwner?: SelectFocusRingOwner;
     /** Maximum closed-control label width in CSS pixels before ellipsis. */
@@ -2134,10 +2535,50 @@ interface SelectBaseProps<Value extends string = string> {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-type SelectProps<Value extends string = string> = SelectBaseProps<Value> & SelectAccessibleName;
-declare function Select<Value extends string>({ name, value, label, ariaLabel, choices, className, placeholderText, hint, disabled, fitMenu, renderSelected, placeholder, presentation, size, selectedPresentation, focusRingOwner, labelMaxWidth, slot, }: SelectProps<Value>): SafeHtml;
+/** One chosen value (the default). */
+interface SelectSingleValueProps<Value extends string = string> {
+    multiple?: false;
+    value: NoInfer<Value>;
+    renderSelected?: (choice: SelectChoice<Value>) => SafeHtml;
+    /** Show only the selected choice icon while retaining the Select's accessible name. */
+    selectedPresentation?: SelectSelectedPresentation;
+    triggerIcon?: never;
+}
+/**
+ * Any number of chosen values. The popup stays open while the person toggles
+ * choices and closes on an outside click, Escape, or focus leaving; the closed
+ * control summarizes the chosen labels in choice order.
+ */
+interface SelectMultipleLabelProps<Value extends string = string> {
+    multiple: true;
+    value: readonly NoInfer<Value>[];
+    renderSelected?: never;
+    selectedPresentation?: 'label';
+    triggerIcon?: never;
+}
+/**
+ * A multiple Select drawn as an icon-only toolbar trigger, such as a
+ * "Filter by label" funnel. No single choice is selected, so the trigger shows
+ * a fixed `triggerIcon` naming the menu's purpose; while any choice is chosen
+ * a count badge sits beside it, and the combobox's accessible name ends with
+ * the chosen labels in choice order.
+ */
+interface SelectMultipleIconProps<Value extends string = string> {
+    multiple: true;
+    value: readonly NoInfer<Value>[];
+    renderSelected?: never;
+    selectedPresentation: 'icon-only';
+    /**
+     * The trigger's fixed icon, typically a `LucideIcon` naming the menu's
+     * purpose (a funnel for a filter), independent of the selection.
+     */
+    triggerIcon: KerfUiContent;
+}
+type SelectMultipleValueProps<Value extends string = string> = SelectMultipleLabelProps<Value> | SelectMultipleIconProps<Value>;
+type SelectProps<Value extends string = string> = SelectBaseProps<Value> & SelectAccessibleName & (SelectSingleValueProps<Value> | SelectMultipleValueProps<Value>);
+declare function Select<Value extends string>(props: SelectProps<Value>): SafeHtml;
 
-export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectPresentation, type SelectProps, type SelectSelectedPresentation, type SelectSize };
+export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectMultipleIconProps, type SelectMultipleLabelProps, type SelectMultipleValueProps, type SelectPresentation, type SelectProps, type SelectSelectedPresentation, type SelectSingleValueProps, type SelectSize };
 ```
 
 ## `@kerfjs/ui/state-banner`
@@ -2272,7 +2713,7 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
-import * as kerfjs from 'kerfjs';
+import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchToken {
@@ -2315,6 +2756,8 @@ interface TokenSearchFieldBaseProps {
     removeAction?: string;
     clearAction?: string;
     clearLabel?: string;
+    /** Icon for the clear button. Default: the Lucide `x` glyph token chips also use. */
+    clearIcon?: SafeHtml;
     className?: string;
     editorAttributes?: TokenSearchEditorAttributes;
     /** Native named-slot assignment when composed inside a web component. */
@@ -2338,7 +2781,7 @@ interface TokenSearchFieldValue {
     query: string;
     tokens: TokenSearchToken[];
 }
-declare function TokenSearchField({ id, label, query, tokens, revision, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, className, editorAttributes, slot, }: TokenSearchFieldProps): kerfjs.SafeHtml;
+declare function TokenSearchField({ id, label, query, tokens, revision, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, clearIcon, className, editorAttributes, slot, }: TokenSearchFieldProps): SafeHtml;
 /** Read editable text and ordered token offsets from a rendered TokenSearchField editor. */
 declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonly TokenSearchToken[]): TokenSearchFieldValue;
 /** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
@@ -2548,10 +2991,17 @@ import { SafeHtml } from 'kerfjs';
 type BadgeTone = 'neutral' | 'brand' | 'pop' | 'success' | 'warning' | 'danger';
 type BadgeAppearance = 'quiet' | 'solid' | 'outline';
 type BadgeShape = 'pill' | 'rounded';
+/** Size of a text badge. A text-free dot is the separate `size: 'dot'` form. */
 type BadgeSize = 'compact' | 'default';
-interface BadgeProps {
-    children: SafeHtml | string | number;
+interface BadgeCommonProps {
     tone?: BadgeTone;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** A badge that shows a short status, count, or category as visible text. */
+interface BadgeTextProps extends BadgeCommonProps {
+    children: SafeHtml | string | number;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
     size?: BadgeSize;
@@ -2559,14 +3009,35 @@ interface BadgeProps {
     label?: string;
     /** Hide a repeated visual badge from assistive technology. */
     ariaHidden?: boolean;
-    className?: string;
-    /** Native named-slot assignment when composed inside a web component. */
-    slot?: string;
 }
+/** A labeled dot, announced as an image with its own accessible name. */
+interface BadgeDotLabeled {
+    /** Accessible name for the dot, for example `"New activity"`. */
+    label: string;
+    ariaHidden?: false;
+}
+/** A decorative dot whose meaning the owning component already announces. */
+interface BadgeDotDecorative {
+    label?: never;
+    ariaHidden: true;
+}
+/**
+ * A text-free status dot (the iOS "new content" dot): a small solid circle in
+ * the badge's tone. It has no visible text, so it must either carry its own
+ * accessible `label` (exposed as an image) or be `ariaHidden` because the
+ * surrounding component already folds its meaning into an accessible name.
+ */
+type BadgeDotProps = BadgeCommonProps & {
+    size: 'dot';
+    children?: never;
+    appearance?: never;
+    shape?: never;
+} & (BadgeDotLabeled | BadgeDotDecorative);
+type BadgeProps = BadgeTextProps | BadgeDotProps;
 /** Compact, non-interactive metadata whose tone, emphasis, and shape are configured by props. */
-declare function Badge({ children, tone, appearance, shape, size, label, ariaHidden, className, slot, }: BadgeProps): SafeHtml;
+declare function Badge(props: BadgeProps): SafeHtml;
 
-export { Badge, type BadgeAppearance, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTone };
+export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone };
 ```
 
 ## `@kerfjs/ui/lucide-icon`
@@ -2668,9 +3139,9 @@ export { Text, type TextBorder, type TextContent, type TextFont, type TextProps,
 ```ts
 import * as kerfjs from 'kerfjs';
 import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
-import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;