@kerfjs/ui 5.0.0-beta.62 → 5.0.0-beta.63

package/README.md

@@ -342,6 +342,10 @@ guidance, public hooks, and explicit geometry ownership; then concatenate its
 identity alongside each input when ids could collide. This makes a combined
 tool reason about both sides of a composition using one vocabulary without
 pretending app-local components are `@kerfjs/ui` exports.
+For a consumer UX demo, `@kerfjs/ui/catalog-projection` derives rows and
+relationships from that extension; `kerf-catalog-demo --write` emits a typed
+module and `--check` catches drift. See the [catalog guide](./docs/catalog.md)
+for repository base and source path configuration.
 
 Composition-aware consumers use
 [`component-composition-extension.schema.json`](./ai/component-composition-extension.schema.json),

package/ai/component-catalog-extension.schema.json

@@ -52,6 +52,14 @@
           "items": { "type": "string" },
           "uniqueItems": true
         },
+        "uses": {
+          "description": "Directly composed Kerf or consumer catalog entry ids.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "source": { "$ref": "#/$defs/repositoryPath" },
+        "demoSource": { "$ref": "#/$defs/repositoryPath" },
         "geometry": { "$ref": "#/$defs/geometry" },
         "documentation": { "type": "string", "minLength": 1 }
       },
@@ -74,6 +82,11 @@
     },
     "geometryOwner": {
       "enum": ["self", "parent", "child", "none", "conditional"]
+    },
+    "repositoryPath": {
+      "description": "A repository-relative POSIX path without traversal or empty segments.",
+      "type": "string",
+      "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$"
     }
   }
 }

package/ai/component-catalog.json

@@ -1165,6 +1165,11 @@
           "import": "@kerfjs/ui/wire-workbench",
           "required": false,
           "stateAttributes": [
+            {
+              "name": "data-responsive-overlay-active",
+              "on": "kui-workbench__rail and kui-workbench__drawer",
+              "meaning": "Present while a panel's numeric responsiveOverlayAt threshold applies to the Workbench width; the same measurement drives overlay layout and collapsed-state transitions."
+            },
             {
               "name": "data-handle-inset",
               "on": "kui-workbench__rail",
@@ -1206,7 +1211,8 @@
         "kui-workbench__panel-content",
         "kui-workbench__handle",
         "kui-workbench__handle-icon",
-        "kui-workbench__restore"
+        "kui-workbench__restore",
+        "kui-workbench__backdrop"
       ],
       "publicTokens": [
         "--kui-workbench-rail-width",
@@ -3102,7 +3108,7 @@
         "border": "self",
         "padding": "self",
         "notes": [
-          "Public resting background and border, hover border, and selected border tokens can be scoped to a row or its containing list without changing the default tones."
+          "Public resting, hover, and selected text, fill, and border tokens can be scoped to a row or its containing list without changing the default tones."
         ]
       },
       "delivery": {

package/ai/component-composition.json

@@ -1091,6 +1091,12 @@
         "helpers": ["wireWorkbench", "wireScrollDividers"],
         "obligations": [],
         "stateAttributes": [
+          {
+            "name": "data-responsive-overlay-active",
+            "on": "kui-workbench__rail and kui-workbench__drawer",
+            "helper": "wireWorkbench",
+            "meaning": "Present while a panel's numeric responsiveOverlayAt threshold applies to the Workbench width; the same measurement drives overlay layout and collapsed-state transitions."
+          },
           {
             "name": "data-handle-inset",
             "on": "kui-workbench__rail",
@@ -1152,7 +1158,8 @@
           "kui-workbench__panel-content",
           "kui-workbench__handle",
           "kui-workbench__handle-icon",
-          "kui-workbench__restore"
+          "kui-workbench__restore",
+          "kui-workbench__backdrop"
         ],
         "publicTokens": [
           "--kui-workbench-rail-width",
@@ -2538,7 +2545,7 @@
           "border": "self",
           "padding": "self",
           "notes": [
-            "Public resting background and border, hover border, and selected border tokens can be scoped to a row or its containing list without changing the default tones."
+            "Public resting, hover, and selected text, fill, and border tokens can be scoped to a row or its containing list without changing the default tones."
           ]
         }
       },

package/ai/components/list-item.md

@@ -69,7 +69,7 @@ No wiring helper.
 
 Margin: self · border: self · padding: self (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- Public resting background and border, hover border, and selected border tokens can be scoped to a row or its containing list without changing the default tones.
+- Public resting, hover, and selected text, fill, and border tokens can be scoped to a row or its containing list without changing the default tones.
 
 ## Accessibility
 

package/ai/components/workbench.md

@@ -76,6 +76,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 **Wiring-owned state attributes** — never render, remove, or branch on these as app state:
 
+- `data-responsive-overlay-active` on `kui-workbench__rail and kui-workbench__drawer` (`wireWorkbench`): Present while a panel's numeric responsiveOverlayAt threshold applies to the Workbench width; the same measurement drives overlay layout and collapsed-state transitions.
 - `data-handle-inset` on `kui-workbench__rail` (`wireWorkbench`): Written by the shared resize wiring when the work-area minimum or a parent clamp holds a rail's maximum near its size. It carries no Workbench styling; the Workbench handle stays at the rail's inner edge.
 - `data-resizing` on `kui-workbench__rail` (`wireWorkbench`): Present on a resizable rail or the drawer while a pointer drag resizes it.
 - `data-scroll-overflow` on `kui-pane__content of each panel and work-area Pane` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
@@ -99,9 +100,9 @@ Margin: none · border: self · padding: child (layout role: structure). `self`
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public class hooks (select for layout placement only, never to change the component's look): `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore`, `kui-workbench__backdrop`.
 
-Never put `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore` on an element you write; render `Workbench` instead (`KUI-L103`).
+Never put `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore`, `kui-workbench__backdrop` on an element you write; render `Workbench` instead (`KUI-L103`).
 
 Public tokens it reads: `--kui-workbench-rail-width`, `--kui-workbench-drawer-height`, `--kui-workbench-popup-z`, `--kui-workbench-overlay-z`, `--kui-workbench-overlay-max-width`, `--kui-workbench-overlay-max-height`, `--kui-workbench-restore-inset`, `--kui-workbench-restore-z`, `--kui-workbench-overlay-dismiss-margin`. Set a token only where its public contract allows; prefer a prop.
 

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.62` and `kerfjs@5.0.0-beta.62`. 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.63` and `kerfjs@5.0.0-beta.63`. 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`
 
@@ -146,11 +146,14 @@ import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 
+type ToolbarPosition = 'header' | 'footer';
 interface ToolbarProps {
     leading?: KerfUiContent;
     center?: KerfUiContent;
     trailing?: KerfUiContent;
     label?: string;
+    /** Use footer semantics for a bottom toolbar; defaults to header. */
+    position?: ToolbarPosition;
     /**
      * Physical divider edges in canonical top/right/bottom/left order, drawn
      * always. Defaults to none: a toolbar pinned over or under scrolling content
@@ -200,9 +203,9 @@ interface ToolbarProps {
  * 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;
+declare function Toolbar({ leading, center, trailing, label, position, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { Sides, Toolbar, type ToolbarConfig, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarPosition, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -321,6 +324,10 @@ interface ToolbarControlGroupProps {
     relocateOnCollapse?: boolean;
     /** Add contrast behind photo-backed avatar content. */
     scrim?: boolean;
+    /** Block the group's controls and show a spinner without changing its dimensions. */
+    busy?: boolean;
+    /** Announced status while busy; defaults to “Working”. */
+    busyLabel?: string;
     /**
      * Avatar image URL. A single-control group paints it on the group; a
      * multi-control group paints it only on the pressed selection highlight.
@@ -329,7 +336,7 @@ interface ToolbarControlGroupProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, busy, busyLabel, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
 export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
 ```
@@ -413,9 +420,9 @@ interface PopupMenuItem {
     value?: string;
     /** Leading icon, typically a `LucideIcon`; it is placed in the item's icon slot. */
     icon?: SafeHtml;
-    /** A checked menu choice, including nested choices. */
+    /** A checkbox choice, including nested choices; omit for a plain command. */
     checked?: boolean;
-    /** Trailing safe content, such as a selected-choice tick. */
+    /** Trailing safe content, such as secondary status. */
     details?: SafeHtml;
     /** Destructive command styling. */
     tone?: 'default' | 'danger';
@@ -870,10 +877,22 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 type ContentItemFrame = 'none' | 'framed';
 /** Corner shape: the 12px rounded rectangle or the 22px pill. */
 type ContentItemShape = 'rounded' | 'pill';
+/** `single` uses option selection; `toggle` uses a pressed button. */
+type ContentItemSelectionMode = 'none' | 'single' | 'toggle';
 type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
 }>;
-interface ContentItemProps {
+type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-action'?: never;
+    'data-item-id'?: never;
+    'data-interactive'?: never;
+    'data-selected'?: never;
+    'data-disabled'?: never;
+    'data-selection-mode'?: never;
+    'data-kui-pressed'?: never;
+}>;
+interface ContentItemBaseProps {
     /** Item content; a plain string is allowed for bare copy. */
     children?: KerfUiContent | string;
     /**
@@ -896,19 +915,38 @@ interface ContentItemProps {
      */
     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;
 }
+type ContentItemProps = ContentItemBaseProps & ({
+    interactive?: false;
+    action?: never;
+    itemId?: never;
+    selectionMode?: never;
+    selected?: never;
+    disabled?: never;
+    /** Existing static `data-*` metadata remains available. */
+    rootAttributes?: ContentItemRootAttributes;
+} | {
+    /** Enable a keyboard reachable card; wire `wireContentItems` once on its containing root. */
+    interactive: true;
+    /** Delegated action dispatched by pointer, Enter, or Space. */
+    action: string;
+    itemId?: string;
+    selectionMode?: ContentItemSelectionMode;
+    selected?: boolean;
+    disabled?: boolean;
+    /** Safe app metadata; interaction attributes are component-owned. */
+    rootAttributes?: ContentItemInteractiveRootAttributes;
+});
 /**
  * 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;
+declare function ContentItem({ children, frame, shape, ariaLabel, focusTarget, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
 
-export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemShape };
+export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -1428,7 +1466,8 @@ interface PaneProps {
     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
+     * scrolling content. Omitted defaults to `scroll` for a plain pane and
+     * `always` for `appearance="sunken"`. `scroll` 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
@@ -1492,7 +1531,7 @@ 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-DqwtBxQL.js';
+import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
 import { ToolbarConfig } from './toolbar.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -1511,6 +1550,7 @@ type WorkbenchPanelToggle = PanelToggle;
  * `FloatingToolbar` in the work area's bottom-end corner.
  */
 type WorkbenchPanelToolbar = PanelToolbar;
+type WorkbenchPanelBottomToolbar = PanelBottomToolbar;
 /**
  * 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
@@ -1546,7 +1586,7 @@ interface WorkbenchMainBottomToolbar extends ToolbarConfig {
  * the Pane's `chromePlacement="auto"`; it applies to the pinned header and
  * footer together).
  */
-type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
+type WorkbenchChromePlacement = PanelChromePlacement;
 
 /**
  * The Workbench container breakpoint below which a panel presents as an
@@ -1554,7 +1594,7 @@ type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
  * breakpoints as `ResizableRegion`'s `responsiveFillAt` — or `never` to keep
  * it inline at every width.
  */
-type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never';
+type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never' | number;
 /**
  * How wide a rail's overlay is in a compact (448px or less) Workbench: `inset`
  * fills the Workbench less a dismiss margin on the side away from the rail's
@@ -1577,8 +1617,20 @@ interface WorkbenchPanel {
      * collapsed. With it, `content` renders in a `Pane` below the toolbar.
      */
     toolbar?: WorkbenchPanelToolbar;
-    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    /** Fixed content below a toolbar panel's top toolbar, above its scroll region. */
+    header?: KerfUiContent;
+    /** List layout for `header`; omitted fields keep List defaults. */
+    headerList?: ListConfig;
+    /** Placement of the top toolbar and header together; default `fixed`. */
+    headerPlacement?: WorkbenchChromePlacement;
+    /** Fixed content above a toolbar panel's bottom toolbar. */
     footer?: KerfUiContent;
+    /** List layout for `footer`; omitted fields keep List defaults. */
+    footerList?: ListConfig;
+    /** Fixed toolbar below `footer`, using footer semantics. */
+    bottomToolbar?: WorkbenchPanelBottomToolbar;
+    /** Placement of the footer and bottom toolbar together; default `fixed`. */
+    footerPlacement?: WorkbenchChromePlacement;
     /**
      * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
      * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
@@ -1610,8 +1662,9 @@ interface WorkbenchPanel {
     presentation?: ResizableRegionPresentation;
     /**
      * Present the panel as an overlay, without a separator, below a Workbench
-     * container breakpoint, and inline above it — the CSS decides, so the app
-     * needs no device-class check. A rail overlays from its side at full
+     * container breakpoint, and inline above it. `compact` and `narrow` use
+     * CSS container queries; a positive number is a pixel threshold measured
+     * by `wireWorkbench` and requires a `collapsed` signal. A rail overlays from its side at full
      * height, over the work area and an open drawer; the bottom drawer
      * overlays the bottom of the work-area column. Rails default to `narrow`
      * (pass `never` to keep one inline); the drawer defaults to inline.
@@ -1711,6 +1764,8 @@ interface WorkbenchProps {
      * shorter. Workbenches without a drawer ignore it.
      */
     mainMinHeight?: number;
+    /** Dim the work area below any open overlay and absorb outside presses; off by default. */
+    overlayBackdrop?: boolean;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -1728,9 +1783,9 @@ 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, mainPane, mainHeaderList, mainFooterList, 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, overlayBackdrop, 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 };
+export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelBottomToolbar, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
 ```
 
 ## `@kerfjs/ui/wire-workbench`
@@ -1770,6 +1825,13 @@ interface WireWorkbenchPanel {
      * keeps Tab inside it, and it closes on Escape or a press outside it.
      */
     collapsed?: Signal<boolean>;
+    /**
+     * Treat presses in a portal surface launched by this panel (for example a
+     * body-level menu or dialog) as inside it. The predicate receives each Node
+     * in the press's composed path; return true for the portal root. Ordinary
+     * presses outside the panel and its allowed surfaces still dismiss it.
+     */
+    keepOpenOn?: (target: Node) => boolean;
 }
 /** A resize the user made, after `wireWorkbench` wrote it to the size signal. */
 interface WorkbenchResize {
@@ -1851,16 +1913,18 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
-import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-DqwtBxQL.js';
-export { c as collapsiblePanelToggleIcon } from './panel-toolbar-DqwtBxQL.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
+export { e as collapsiblePanelToggleIcon } from './panel-toolbar-DDKh4uKd.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
 import './toolbar.js';
-import './sides-BPSWde0A.js';
-import './css-values.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
 type CollapsiblePanelSide = PanelSide;
@@ -1873,6 +1937,8 @@ type CollapsiblePanelToolbarToggle = PanelToggle;
  * {@link CollapsiblePanelRelocated} while it is collapsed.
  */
 type CollapsiblePanelToolbar = PanelToolbar;
+type CollapsiblePanelBottomToolbar = PanelBottomToolbar;
+type CollapsiblePanelChromePlacement = PanelChromePlacement;
 interface CollapsiblePanelToggleProps {
     /** The panel this toggle controls. */
     side: CollapsiblePanelSide;
@@ -1916,8 +1982,15 @@ interface CollapsiblePanelProps {
      * marked groups and toggle stay reachable while the panel is collapsed.
      */
     toolbar?: CollapsiblePanelToolbar;
-    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    /** Fixed content below a toolbar panel's top toolbar. */
+    header?: KerfUiContent;
+    headerList?: ListConfig;
+    headerPlacement?: CollapsiblePanelChromePlacement;
+    /** Fixed content above a toolbar panel's bottom toolbar. */
     footer?: KerfUiContent;
+    footerList?: ListConfig;
+    bottomToolbar?: CollapsiblePanelBottomToolbar;
+    footerPlacement?: CollapsiblePanelChromePlacement;
     /**
      * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
      * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
@@ -1951,7 +2024,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, pane, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, header, headerList, headerPlacement, footer, footerList, bottomToolbar, footerPlacement, pane, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
 interface CollapsiblePanelRelocatedProps {
     /** The panel's `id`. */
     panelId: string;
@@ -1971,7 +2044,7 @@ interface CollapsiblePanelRelocatedProps {
  */
 declare function CollapsiblePanelRelocated({ panelId, side, collapsed, toolbar, }: CollapsiblePanelRelocatedProps): SafeHtml;
 
-export { CollapsiblePanel, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
+export { CollapsiblePanel, type CollapsiblePanelBottomToolbar, type CollapsiblePanelChromePlacement, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
 ```
 
 ## `@kerfjs/ui/wire-sidebar`
@@ -2304,7 +2377,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-DqwtBxQL.js';
+import './panel-toolbar-DDKh4uKd.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2397,7 +2470,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-DqwtBxQL.js';
+import './panel-toolbar-DDKh4uKd.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2799,6 +2872,7 @@ export { Skeleton, type SkeletonProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssFlexKeyword, CssFlex } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type SunkenPanelShape = 'rounded' | 'square';
@@ -2808,6 +2882,10 @@ interface SunkenPanelProps {
     ariaLabel?: string;
     /** Corner shape: a rounded rectangle (default) or square corners. */
     shape?: SunkenPanelShape;
+    /** Grow or shrink within a flex parent, using Grid's typed flex contract. */
+    flex?: boolean | CssFlexKeyword | CssFlex;
+    /** Fill a parent with a definite height; use flex inside a flex layout. */
+    fill?: boolean;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -2817,7 +2895,7 @@ interface SunkenPanelProps {
  * stack. The panel owns its background and padding; children own their own
  * borders and internal geometry.
  */
-declare function SunkenPanel({ children, ariaLabel, shape, className, slot, }: SunkenPanelProps): kerfjs.SafeHtml;
+declare function SunkenPanel({ children, ariaLabel, shape, flex, fill, className, slot, }: SunkenPanelProps): kerfjs.SafeHtml;
 
 export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```
@@ -3091,8 +3169,8 @@ import { SafeHtml } from 'kerfjs';
 import { BadgeTone, BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
 
 interface ChipCommonProps {
-    /** Visible, non-interactive chip content. */
-    children: SafeHtml | string | number;
+    /** Decorative leading icon, normally an unsized LucideIcon. */
+    icon?: SafeHtml;
     tone?: BadgeTone;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
@@ -3106,6 +3184,12 @@ interface ChipCommonProps {
 }
 /** A removable chip needs both a delegated action and a specific accessible name. */
 type ChipProps = ChipCommonProps & ({
+    children: SafeHtml | string | number;
+    truncate?: false;
+} | {
+    children: string;
+    truncate: true;
+}) & ({
     removeAction: string;
     removeLabel: string;
 } | {
@@ -3113,7 +3197,7 @@ type ChipProps = ChipCommonProps & ({
     removeLabel?: never;
 });
 /** A short label with an optional native remove button. The application owns removal. */
-declare function Chip({ children, tone, appearance, shape, size, disabled, itemId, className, slot, ...remove }: ChipProps): SafeHtml;
+declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, ...remove }: ChipProps): SafeHtml;
 
 export { Chip, type ChipProps };
 ```
@@ -3125,18 +3209,21 @@ import * as kerfjs from 'kerfjs';
 import { IconNode } from 'lucide';
 
 type LucideNode = IconNode;
+type LucideIconSize = 'xs' | 's' | 'm' | 'l' | 'xl' | number;
 interface LucideIconProps {
     icon: LucideNode;
     name: string;
     className?: string;
     label?: string;
+    /** Named icon scale or positive pixel size, converted to rem. Omit for 1em. */
+    size?: LucideIconSize;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** Render a Lucide-compatible icon node without copying icon SVG strings. */
-declare function LucideIcon({ icon, name, className, label, slot, }: LucideIconProps): kerfjs.SafeHtml;
+declare function LucideIcon({ icon, name, className, label, size, slot, }: LucideIconProps): kerfjs.SafeHtml;
 
-export { LucideIcon, type LucideIconProps, type LucideNode };
+export { LucideIcon, type LucideIconProps, type LucideIconSize, type LucideNode };
 ```
 
 ## `@kerfjs/ui/surface-scaffold`
@@ -3187,8 +3274,9 @@ type TextSize = 'compact' | 'default' | 'large' | 'xlarge';
 type TextFont = 'default' | 'monospace';
 type TextBorder = 'transparent' | 'none';
 type TextLineHeight = 'default' | 'tight';
+type TextWrap = 'normal' | 'anywhere' | 'nowrap' | 'truncate';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
-type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
+type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
     variant?: TextVariant;
     /** Semantic foreground treatment. Defaults to the inherited foreground. */
@@ -3207,14 +3295,24 @@ type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     class?: string;
     className?: string;
 };
+type TextProps = TextCommonProps & ({
+    /** Wrap normally or break long unbroken strings. Defaults to normal. */
+    wrap?: 'normal' | 'anywhere';
+    /** Cap wrapped text to this positive number of lines. */
+    maxLines?: number;
+} | {
+    /** Keep one line, with or without an ellipsis. */
+    wrap: 'nowrap' | 'truncate';
+    maxLines?: never;
+});
 /**
  * Semantic heading, paragraph, or inline text. Block variants use the standard
  * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
-declare function Text({ variant: Variant, tone, size, font, border, flush, lineHeight, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
+declare function Text({ variant: Variant, tone, size, font, border, flush, lineHeight, wrap, maxLines, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
 
-export { Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant };
+export { Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
 ```
 
 ## `@kerfjs/ui/row`