@kerfjs/ui 5.0.0-beta.95 → 5.0.0-beta.96

package/ai/component-catalog.json

@@ -7,7 +7,9 @@
     {
       "export": "wireCatalog",
       "import": "@kerfjs/ui/wire-catalog",
-      "provides": ["wireScrollDividers"]
+      "provides": [
+        "wireScrollDividers"
+      ]
     }
   ],
   "entries": [
@@ -41,11 +43,15 @@
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
         "compact or default size, or a text-free dot (size: 'dot')",
-        "labeled or decorative duplicate"
+        "labeled or decorative duplicate",
+        "leading icon",
+        "title tooltip and data-* rootAttributes",
+        "maxWidth caps the badge and truncates long text with an ellipsis, defaulting the title to string or number content"
       ],
       "accessibility": [
         "Badge is non-interactive. Supply label when visible content is abbreviated, and ariaHidden when it repeats an accessible name owned by the surrounding component. A text-free dot must take either label (exposed as an image) or ariaHidden, which the types enforce.",
-        "Keep meaningful text visible because tone is supplementary."
+        "Keep meaningful text visible because tone is supplementary.",
+        "A label replaces abbreviated or symbolic visible text; the badge is then a labeled image (role img)."
       ],
       "geometry": {
         "margin": "none",
@@ -61,7 +67,9 @@
       },
       "wiring": [],
       "publicClasses": [
-        "kui-badge"
+        "kui-badge",
+        "kui-badge__icon",
+        "kui-badge__label"
       ],
       "publicTokens": [],
       "links": {
@@ -394,6 +402,8 @@
         "--kui-color-surface",
         "--kui-color-surface-raised",
         "--kui-color-surface-lowered",
+        "--kui-sunken-texture",
+        "--kui-sunken-surface",
         "--kui-color-text",
         "--kui-color-text-quiet",
         "--kui-color-text-link",
@@ -472,7 +482,7 @@
       "category": "Foundation",
       "kind": "composition",
       "source": "kerf",
-      "description": "Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, link color, and the html → body → .kui-app-root full-height chain.",
+      "description": "Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, semantic control cursors, link color, and the html → body → .kui-app-root full-height chain.",
       "uses": [],
       "purpose": "Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.",
       "publicExports": [],
@@ -497,10 +507,12 @@
       ],
       "variants": [
         "document-flow page (no .kui-app-root)",
-        "full-height application root"
+        "full-height application root",
+        "viewport-locked application root (data-viewport=\"locked\" on a body-child .kui-app-root: 100dvh and overflow clip on html, body, and the root)"
       ],
       "accessibility": [
-        "Links keep the semantic link color at zero specificity so application focus and link styles still apply."
+        "Links keep the semantic link color at zero specificity so application focus and link styles still apply.",
+        "Native controls get semantic cursors at zero specificity: pointer on enabled buttons, links, role=button, checkbox/radio/button-type inputs, selects, and checkbox/radio labels; not-allowed on disabled controls, aria-disabled role=button, and a disabled wa-button's base part; text on text-like inputs and textareas."
       ],
       "geometry": {
         "margin": "none",
@@ -671,7 +683,7 @@
         "border": "conditional",
         "padding": "child",
         "notes": [
-        "The pane is unpadded; separators are independently opt-in on logical edges and default off.",
+          "The pane is unpadded; separators are independently opt-in on logical edges and default off.",
           "Safe areas: the root and separators paint through unsafe areas while header, content, and footer pad the sides the pane still reaches (routed by --kui-edge-inset-*); content block insets are scroll padding.",
           "The scrolling content exposes its resolved logical inline padding to descendants as --kui-pane-content-inset-inline-start/end, including safe areas and deepInset.",
           "deepInset adds --kui-space-xs to every side of the scrolling content and its block scroll padding; header/footer chrome still owns safe-area padding at its edge.",
@@ -767,6 +779,11 @@
           "id": "tab-navigator",
           "relationship": "composes-with",
           "when": "Use one NavStack as each TabNavigator tab's persistent content."
+        },
+        {
+          "id": "content-swap",
+          "relationship": "nearest",
+          "when": "Use ContentSwap to swap content in place inside one region without navigation chrome."
         }
       ],
       "appOwns": [
@@ -932,7 +949,7 @@
         "back action"
       ],
       "variants": [
-        "fixed roomy split",
+        "fixed roomy split with listWidth: a pixel size, optionally capped at a fraction of the split's width",
         "resizable roomy split",
         "collapsed resizable list with a restore control",
         "compact list",
@@ -1471,7 +1488,8 @@
       "uses": [],
       "purpose": "Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.",
       "publicExports": [
-        "SunkenPanel"
+        "SunkenPanel",
+        "ensureSunkenTexture"
       ],
       "useWhen": [
         "A main content region or nested work area needs a darker/lowered background and one compact inset around a vertical stack.",
@@ -1578,6 +1596,7 @@
         "trailing priority for an expanded trailing control at compact or narrow widths",
         "trailing groups and a standalone primary wa-button wrap instead of clipping",
         "outer inset independently configurable from zone gap",
+        "compact density: a 40px header (34px band, 3px block insets) for an embedded panel, filled with compact ToolbarControlGroups",
         "app bar or bottom bar claiming its screen edges (safeAreaEdges)",
         "typed hideBelow/showBelow thresholds at the nearest Toolbar content width"
       ],
@@ -1713,6 +1732,11 @@
         {
           "id": "wa-button-group",
           "relationship": "prefer-over"
+        },
+        {
+          "id": "icon-toggle-button",
+          "relationship": "nearest",
+          "when": "Outside a Toolbar, a standalone icon-only toggle is an IconToggleButton."
         }
       ],
       "appOwns": [
@@ -1730,7 +1754,7 @@
         "default or compact size",
         "comfortable or tight density",
         "icon, text, mixed, or avatar content",
-        "raised, filled, or outline selected chrome",
+        "raised, filled, outline, or no selected chrome (group-wide or one control via data-selected-chrome=\"none\")",
         "brand, neutral, or pop selected tone",
         "nested dropdown trigger",
         "standard, compact, or list-zero dropdown menu inset",
@@ -1745,6 +1769,7 @@
       ],
       "accessibility": [
         "Name the group when its relationship is not evident from context.",
+        "A disabled native button (disabled, or aria-disabled=\"true\" when it must stay focusable) dims to half opacity with the not-allowed cursor and no hover surface; a disabled raw wa-button paints no hover surface either. Do not add disabled styling yourself.",
         "Name an icon-only button or link with aria-label, not title. Once any help-tag installer is imported (select/register, popup-menu/register, or help-tags/register), it shows an aria-hidden Web Awesome help tag repeating that name after a 500ms hover and at once on keyboard focus, hidden on a press and on Escape, and never joins aria-labelledby. A native title keeps the browser tooltip and gets no second tag."
       ],
       "geometry": {
@@ -1901,12 +1926,14 @@
       "purpose": "Configure recurring dialog and popup geometry without consumer ::part() overrides.",
       "publicExports": [
         "DialogSurface",
+        "PopoverDialogSurface",
         "PopupSurface"
       ],
       "useWhen": [
         "A Web Awesome dialog or dropdown needs a standard size, presentation, body/footer inset, or list-compatible menu inset.",
         "A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.",
-        "A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions."
+        "A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions.",
+        "A dialog that must leave the page interactive and close on Escape or an outside press uses PopoverDialogSurface; one that fills its body with a SplitView or Pane uses height and bodyLayout=\"fill\"."
       ],
       "avoidWhen": [
         "Do not use it as a generic layout wrapper or to replace application-owned modal state and focus lifecycle.",
@@ -1922,8 +1949,11 @@
       ],
       "variants": [
         "small, medium, or large dialog",
+        "data-* rootAttributes (a data-key) so sibling dialogs morph by identity",
         "modal, side-sheet, or fullscreen dialog",
         "typed modal preferred width, viewport gutter, and maximum height, including viewport cap",
+        "definite viewport-bounded modal height and a fill body layout for one child",
+        "non-modal light-dismiss PopoverDialogSurface, overlay or embedded in flow",
         "none, compact, or comfortable body and footer inset",
         "standard, compact, or zero-inset popup menu"
       ],
@@ -1948,6 +1978,7 @@
       "wiring": [],
       "publicClasses": [
         "kui-dialog-surface",
+        "kui-popover-dialog-surface",
         "kui-popup-surface"
       ],
       "publicTokens": [
@@ -2185,6 +2216,7 @@
         "small",
         "xsmall",
         "placeholder (loading)",
+        "description: quiet single-line supporting copy under a read-only title, aligned with its text, with descriptionId for aria-describedby",
         "dark (loud-surface foreground)",
         "typed hideBelow/showBelow thresholds at the nearest Toolbar content width"
       ],
@@ -2347,13 +2379,16 @@
         "compact, default, large, or xlarge size",
         "default or monospace font",
         "flush item geometry and tight line height",
-        "controlMargins selects exterior 8px gutters with canonical physical Sides"
+        "align start (default), center, or end for centered status copy or trailing values",
+        "controlMargins selects exterior 8px gutters with canonical physical Sides",
+        "wrap normal, anywhere, nowrap, or truncate; truncate places its ellipsis at the end, the start (keeping the tail), or the middle (keeping the last path segment or a character suffix)"
       ],
       "accessibility": [
         "Text renders a native paragraph by default; choose an h1 through h6 variant by document outline rather than appearance, or span for inline secondary text.",
         "Ordinary global, data, and ARIA attributes pass through to the native element.",
         "Choose tone, size, and font independently of the heading level so appearance does not distort the document outline.",
-        "FieldLabel is plain text, not a native label; give it an id and associate the preview group with aria-labelledby."
+        "FieldLabel is plain text, not a native label; give it an id and associate the preview group with aria-labelledby.",
+        "Start and middle truncation clip visually only: the whole value stays in the DOM in reading order, and Text shows it as the element's title unless the app supplies one."
       ],
       "geometry": {
         "margin": "self",
@@ -2466,7 +2501,13 @@
       "avoidWhen": [
         "Do not use for editable fields or row/column tabular data."
       ],
-      "alternatives": [],
+      "alternatives": [
+        {
+          "id": "framed-list",
+          "relationship": "nearest",
+          "when": "Use FramedList for rows of arbitrary content (copy and controls) in the same frame."
+        }
+      ],
       "appOwns": [
         "values",
         "formatting",
@@ -2476,7 +2517,10 @@
         "icon rows",
         "iconless rows",
         "compact density",
-        "placeholder (loading)"
+        "placeholder (loading)",
+        "minimum label column (labelWidth)",
+        "stacked presentation",
+        "stack below a compact or narrow table width"
       ],
       "accessibility": [
         "Name ValueTable with its label; ValueTableRow supplies dt/dd semantics, and row icons stay decorative unless meaning requires an accessible label."
@@ -2513,8 +2557,8 @@
         "--kui-value-table-border",
         "--kui-value-table-icon-size",
         "--kui-value-table-row-columns",
-        "--kui-value-table-row-padding-block",
-        "--kui-value-table-row-gap"
+        "--kui-value-table-row-gap",
+        "--kui-value-table-row-padding-block"
       ],
       "links": {
         "catalogRoute": "?component=value-table",
@@ -2522,6 +2566,193 @@
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
+    {
+      "id": "framed-list",
+      "name": "FramedList",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "An inset-grouped list: one rounded, bordered frame with dividers between rows of arbitrary content.",
+      "uses": [],
+      "purpose": "Group settings-style rows of arbitrary content (copy, keycaps, controls) in one framed surface with between-row dividers and an optional highlighted row, without app list CSS.",
+      "publicExports": [
+        "FramedList",
+        "FramedListRow"
+      ],
+      "useWhen": [
+        "Settings rows, account or source cards, or shortcut lists group several rows of arbitrary content in one framed surface."
+      ],
+      "avoidWhen": [
+        "Do not use for read-only label/value facts; use ValueTable.",
+        "Do not use for selectable navigation rows; use List with ListItem.",
+        "Do not pad or border its rows from application CSS; FramedListRow owns the inset and divider."
+      ],
+      "alternatives": [
+        {
+          "id": "value-table",
+          "relationship": "nearest",
+          "when": "Use ValueTable when every row is a label and a value."
+        },
+        {
+          "id": "list",
+          "relationship": "nearest",
+          "when": "Use List with ListItem for navigation or selectable rows."
+        }
+      ],
+      "appOwns": [
+        "row content and its controls",
+        "which row is highlighted",
+        "the list's accessible name"
+      ],
+      "variants": [
+        "lowered surface",
+        "base surface",
+        "highlighted row"
+      ],
+      "accessibility": [
+        "Renders a list (ul role=list, li rows); pass label when no heading names it. Highlight is visual; carry its meaning in row content or a control's state."
+      ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self",
+        "notes": [
+          "Rows own the 8px inset and the inset 1px divider above them; the frame owns the 8px margin, border, and radius."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/framed-list",
+        "manualCssImport": "@kerfjs/ui/framed-list.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-framed-list",
+        "kui-framed-list__row"
+      ],
+      "publicTokens": [
+        "--kui-framed-list-border",
+        "--kui-color-neutral-border-normal",
+        "--kui-color-surface-lowered",
+        "--kui-color-surface",
+        "--kui-color-brand-fill-quiet",
+        "--kui-layout-inline-margin",
+        "--kui-layout-item-padding",
+        "--kui-layout-rounded-radius"
+      ],
+      "rootElement": "ul",
+      "links": {
+        "catalogRoute": "?component=framed-list",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "summary-row",
+      "name": "SummaryRow",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A selectable, focusable summary of one item as a list row or a board card, with a state rail, a clamped title, trailing meta, and a metadata line.",
+      "uses": [],
+      "purpose": "Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.",
+      "publicExports": [
+        "SummaryRow"
+      ],
+      "useWhen": [
+        "A list or board shows many items as dense, selectable summaries with an identifier, a title, a timestamp, and metadata."
+      ],
+      "avoidWhen": [
+        "Do not use for navigation rows with a single label; use ListItem.",
+        "Do not use for selectable tiles of free-form content; use ContentItem with selectionMode.",
+        "Do not hand-roll row chrome (selection fill, rail, title clamp, edge rounding) in app CSS."
+      ],
+      "alternatives": [
+        {
+          "id": "list-item",
+          "relationship": "nearest",
+          "when": "Use ListItem for navigation rows."
+        },
+        {
+          "id": "content-item",
+          "relationship": "nearest",
+          "when": "Use ContentItem for selectable rich tiles."
+        }
+      ],
+      "appOwns": [
+        "the listbox container, selection set, and keyboard movement",
+        "the title, leading glyph, trailing meta, and metadata content",
+        "rail tone and dimming policy"
+      ],
+      "variants": [
+        "row",
+        "card",
+        "selected",
+        "dimmed",
+        "state rail",
+        "list edge start, end, or only",
+        "title line budget",
+        "deferred rendering"
+      ],
+      "accessibility": [
+        "Each SummaryRow is role=option with tabindex=0 and aria-selected; place rows in a labeled role=listbox and move focus with the arrow keys in the app. The rail is decorative; carry its meaning in text."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self",
+        "notes": [
+          "Rows sit flush in a list section and round only the corners at its edges; cards are borderless rounded cards."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/summary-row",
+        "manualCssImport": "@kerfjs/ui/summary-row.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-summary-row",
+        "kui-summary-row__rail",
+        "kui-summary-row__body",
+        "kui-summary-row__leading",
+        "kui-summary-row__content",
+        "kui-summary-row__title",
+        "kui-summary-row__trailing",
+        "kui-summary-row__metadata"
+      ],
+      "publicTokens": [
+        "--kui-color-neutral-border-quiet",
+        "--kui-color-text",
+        "--kui-color-surface",
+        "--kui-color-brand-border-normal",
+        "--kui-color-text-link",
+        "--kui-color-brand-fill-quiet",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-brand-fill-loud",
+        "--kui-color-pop-fill-loud",
+        "--kui-color-success-fill-loud",
+        "--kui-color-warning-fill-loud",
+        "--kui-color-danger-fill-loud",
+        "--kui-color-text-quiet",
+        "--kui-font-2xs",
+        "--kui-font-xs",
+        "--kui-layout-rounded-radius",
+        "--kui-space-2xs",
+        "--kui-space-s",
+        "--kui-space-xs"
+      ],
+      "rootElement": "div",
+      "links": {
+        "catalogRoute": "?component=summary-row",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "row",
       "name": "Row",
@@ -2641,7 +2872,7 @@
         "nowrap or wrapping",
         "top/right/bottom/left text and control inset combinations",
         "fill: the layout root fills a definite-height parent",
-        "rootAttributes: safe data-* metadata on the root"
+        "rootAttributes: safe data-*, aria-*, and structural role metadata on the root"
       ],
       "accessibility": [
         "Row adds layout only and no grouping role; children retain responsibility for native or ARIA semantics.",
@@ -2807,6 +3038,11 @@
           "id": "resize",
           "relationship": "interactive-alternative",
           "when": "Use ResizableRegion when people must adjust the boundary between tracks."
+        },
+        {
+          "id": "column-track",
+          "relationship": "nearest",
+          "when": "Use ColumnTrack for a board of columns that scroll sideways or page instead of wrapping."
         }
       ],
       "appOwns": [
@@ -2860,6 +3096,144 @@
         "recipe": "docs/layout.md#grid"
       }
     },
+    {
+      "id": "column-track",
+      "name": "ColumnTrack",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A horizontal track of equal, min-width columns that scrolls sideways, or pages one column at a time with peek and snapping.",
+      "uses": [],
+      "purpose": "Lay out a board of columns (kanban) as one horizontal scroll owner: equal columns that never shrink below a minimum, or a paged phone layout with a peeking next column and start snapping, without app track CSS.",
+      "publicExports": [
+        "ColumnTrack"
+      ],
+      "useWhen": [
+        "A board shows several parallel columns (kanban lanes) that must keep a readable width and scroll sideways, or page one at a time on a phone."
+      ],
+      "avoidWhen": [
+        "Do not use for a responsive grid that wraps; use Grid.",
+        "Do not use for two resizable panes; use SplitView or ResizableRegion.",
+        "Do not re-track a Grid from application CSS to get overflowing columns."
+      ],
+      "alternatives": [
+        {
+          "id": "grid",
+          "relationship": "nearest",
+          "when": "Use Grid when columns should wrap or collapse instead of scrolling."
+        }
+      ],
+      "appOwns": [
+        "the columns and their content",
+        "choosing scroll or paged layout (for example by device class)",
+        "drag and drop between columns"
+      ],
+      "variants": [
+        "scroll with a minimum column width",
+        "paged with peek and mandatory snapping"
+      ],
+      "accessibility": [
+        "Name the track with aria-label through rootAttributes when it is a landmark-like region; give each column a region name. Paged scrolling is smooth unless reduced motion is preferred."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "self",
+        "notes": [
+          "The track pads 8px inline and fills its parent's height; columns sit flush and own their insets and vertical scrolling."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/column-track",
+        "manualCssImport": "@kerfjs/ui/column-track.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-column-track",
+        "kui-column-track__columns"
+      ],
+      "publicTokens": [
+        "--kui-layout-inline-margin"
+      ],
+      "rootElement": "div",
+      "links": {
+        "catalogRoute": "?component=column-track",
+        "documentation": "docs/layout.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "content-swap",
+      "name": "ContentSwap",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Two content sides sharing one cell, swapped in place with a push, a crossfade, or no motion.",
+      "uses": [],
+      "purpose": "Swap arbitrary content in place (a dialog body that steps to a second page, a label or footer whose actions change) with Kerf-owned push or crossfade motion, reduced-motion handling, and an inert, hidden inactive side.",
+      "publicExports": [
+        "ContentSwap"
+      ],
+      "useWhen": [
+        "A region swaps between two contents in place, such as a dialog's two steps or a footer's action sets, and the change should read as motion."
+      ],
+      "avoidWhen": [
+        "Do not use for full navigation views with their own toolbars; use NavStack.",
+        "Do not use to swap more than two states at once; render the current pair.",
+        "Do not hand-roll stacked cells, inert handling, or push keyframes in app CSS."
+      ],
+      "alternatives": [
+        {
+          "id": "nav-stack",
+          "relationship": "nearest",
+          "when": "Use NavStack for full views with toolbars and back navigation."
+        }
+      ],
+      "appOwns": [
+        "which side is active and the push direction",
+        "both sides' content",
+        "the region's name"
+      ],
+      "variants": [
+        "push forward or backward",
+        "crossfade",
+        "none",
+        "full-width slot region"
+      ],
+      "accessibility": [
+        "The inactive side is inert and aria-hidden; label makes the swap a named region. Push mirrors in right-to-left documents. Reduced motion replaces the slide with a short fade."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none",
+        "notes": [
+          "Both sides share one grid cell; the region keeps the active side's height and clips the motion."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/content-swap",
+        "manualCssImport": "@kerfjs/ui/content-swap.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-content-swap",
+        "kui-content-swap__side"
+      ],
+      "publicTokens": [],
+      "rootElement": "div",
+      "links": {
+        "catalogRoute": "?component=content-swap",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "spacer",
       "name": "Spacer",
@@ -3151,18 +3525,21 @@
         "typed CssLength gap",
         "boolean, finite-keyword, or typed CssFlex flex",
         "scrollable",
+        "base or raised solid surface",
+        "document reading inset",
         "left/center/right/full horizontal alignment",
         "top/middle/bottom/full vertical alignment",
         "top/right/bottom/left divider combinations",
         "top/right/bottom/left text and control inset combinations",
         "fill: the layout root fills a definite-height parent",
-        "rootAttributes: safe data-* metadata on the root",
+        "rootAttributes: safe data-*, aria-*, and structural role on the root",
         "scroll dividers when named as wireScrollDividers targets chrome",
         "multi-select grid for rich ContentItem rows"
       ],
       "accessibility": [
         "List adds layout only and no list role by default; selectionMode=\"multiple\" makes it an aria-multiselectable grid with a required ariaLabel for selectable ContentItem rows.",
-        "Give a scrollable List a bounded block size and keep keyboard focus visible as its contents scroll."
+        "Give a scrollable List a bounded block size and keep keyboard focus visible as its contents scroll.",
+        "A focused scrollable List (a keyboard-focusable scroller) draws the theme focus ring inset and rounded inside its own box, so a rounded or clipping parent never cuts it off; do not restyle its focus."
       ],
       "geometry": {
         "margin": "none",
@@ -3203,9 +3580,14 @@
       ],
       "publicTokens": [
         "--kui-color-neutral-border-normal",
+        "--kui-color-surface",
+        "--kui-color-surface-raised",
         "--kui-layout-item-gap",
         "--kui-list-divider-color",
-        "--kui-list-gap"
+        "--kui-list-gap",
+        "--kui-space-l",
+        "--kui-space-m",
+        "--kui-space-xl"
       ],
       "links": {
         "catalogRoute": "?component=list",
@@ -3319,10 +3701,11 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Configurable navigation rows with structured labels, status/busy metadata, density, group dividers, and sibling primary/trailing native-button actions.",
+      "description": "Configurable navigation rows with structured labels, status/busy metadata, density, group dividers, and a primary native-button action beside a sibling trailing native button or trailing overflow PopupMenu.",
       "uses": [
         "lucide-icon",
-        "loading-spinner"
+        "loading-spinner",
+        "popup-menu"
       ],
       "purpose": "Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.",
       "publicExports": [
@@ -3343,7 +3726,8 @@
         }
       ],
       "useWhen": [
-        "A navigation or item row needs both a primary selectable action and an independently focusable trailing action."
+        "A navigation or item row needs both a primary selectable action and an independently focusable trailing action.",
+        "A command row needs a trailing \"…\" overflow menu (trailingMenu), optionally also opened at the pointer from the row's contextmenu with openPopupMenuAt."
       ],
       "avoidWhen": [
         "Use ListItem when trailing content is dormant metadata; use AppTab only for tablist semantics and ToolbarControlGroup only for toolbar controls.",
@@ -3366,7 +3750,8 @@
         "selection",
         "action handling",
         "domain data attributes",
-        "popover or context-menu policy"
+        "popover or context-menu policy",
+        "row order"
       ],
       "variants": [
         "selected",
@@ -3379,11 +3764,15 @@
         "description and status",
         "busy while retaining content",
         "interaction-revealed trailing action",
-        "before, after, or paired group divider"
+        "trailing overflow menu",
+        "before, after, or paired group divider",
+        "draggable row with dragging and drop-before / drop-after insertion states"
       ],
       "accessibility": [
         "The noninteractive root contains two sibling native buttons in primary-then-trailing focus order; each button has its own action, item identity, accessible name, and disabled state.",
-        "Selection semantics are exposed only by the primary button; label, icon, and trailingActionIcon are dormant SafeHtml and must not contain interactive descendants; never place an interactive descendant in ListItem.trailing."
+        "A trailingMenu replaces the trailing button with a PopupMenu trigger in the same position: an icon-only button named by trailingMenu.label that exposes aria-haspopup=\"menu\" and aria-expanded, moves focus into the menu, and returns focus to the trigger on Escape or a choice.",
+        "Selection semantics are exposed only by the primary button; label, icon, and trailingActionIcon are dormant SafeHtml and must not contain interactive descendants; never place an interactive descendant in ListItem.trailing.",
+        "A draggable row is dragged by its noninteractive root; with wireListReorder, Alt+Shift+ArrowUp/ArrowDown on its primary button moves it, and focus returns to that button after the application re-renders."
       ],
       "geometry": {
         "margin": "self",
@@ -3397,19 +3786,43 @@
           "browser-condition-css"
         ]
       },
-      "wiring": [],
-      "publicClasses": [
-        "kui-list-action-row",
-        "kui-list-action-row__icon",
-        "kui-list-action-row__label",
-        "kui-list-action-row__primary-label",
-        "kui-list-action-row__description",
-        "kui-list-action-row__status",
-        "kui-list-action-row__primary",
-        "kui-list-action-row__trailing-action"
-      ],
-      "publicTokens": [
-        "--kui-color-brand-border-quiet",
+      "wiring": [
+        {
+          "export": "wireListReorder",
+          "import": "@kerfjs/ui/wire-list-reorder",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-dragging",
+              "on": "ListActionRow rows being dragged",
+              "meaning": "\"true\" on every row a pointer drag is moving (the dragged row, or every selected row of its list when the dragged row is selected). Same attribute the `dragging` prop renders."
+            },
+            {
+              "name": "data-drop-position",
+              "on": "ListActionRow row under the pointer",
+              "meaning": "\"before\" or \"after\": the edge of this row the dragged rows would land beside. Same attribute the `dropPosition` prop renders."
+            }
+          ]
+        },
+        {
+          "export": "reorderListItems",
+          "import": "@kerfjs/ui/wire-list-reorder",
+          "required": false
+        }
+      ],
+      "publicClasses": [
+        "kui-list-action-row",
+        "kui-list-action-row__icon",
+        "kui-list-action-row__label",
+        "kui-list-action-row__primary-label",
+        "kui-list-action-row__description",
+        "kui-list-action-row__status",
+        "kui-list-action-row__primary",
+        "kui-list-action-row__trailing-action"
+      ],
+      "publicTokens": [
+        "--kui-color-brand-border-loud",
+        "--kui-color-brand-border-quiet",
         "--kui-color-brand-fill-normal",
         "--kui-color-neutral-border-normal",
         "--kui-color-neutral-fill-normal",
@@ -3426,6 +3839,9 @@
         "--kui-list-action-row-background",
         "--kui-list-action-row-border",
         "--kui-list-action-row-color",
+        "--kui-list-action-row-dragging-opacity",
+        "--kui-list-action-row-drop-indicator",
+        "--kui-list-action-row-drop-indicator-width",
         "--kui-list-action-row-hover-background",
         "--kui-list-action-row-hover-border",
         "--kui-list-action-row-selected-background",
@@ -3455,7 +3871,9 @@
       "purpose": "Selectable, disabled, trailing, and multiline action or link rows.",
       "publicExports": [
         "ListItem",
-        "ListItemLink"
+        "ListItemLink",
+        "wireListReorder",
+        "reorderListItems"
       ],
       "cssValueProps": [
         {
@@ -3483,6 +3901,11 @@
           "id": "list-action-row",
           "relationship": "nearest",
           "when": "The trailing region must be independently interactive."
+        },
+        {
+          "id": "summary-row",
+          "relationship": "nearest",
+          "when": "Use SummaryRow for dense selectable item summaries with metadata."
         }
       ],
       "appOwns": [
@@ -3491,7 +3914,8 @@
         "selection",
         "permissions",
         "action handling",
-        "domain data attributes"
+        "domain data attributes",
+        "row order"
       ],
       "variants": [
         "native link and external link",
@@ -3505,12 +3929,13 @@
         "spacious density",
         "centered icon beside a multiline label",
         "drag-target state",
+        "draggable row with dragging and drop-before / drop-after insertion states",
         "description and status",
         "busy while retaining content",
         "before, after, or paired group divider"
       ],
       "accessibility": [
-        "ListItem uses native button activation and pressed maps to aria-pressed; ListItemLink uses native anchor activation and external opens a new tab with safe rel and an announced default label. Both map selected to aria-current; disabled or loading links omit href and leave the tab order. rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls."
+        "ListItem uses native button activation and pressed maps to aria-pressed; ListItemLink uses native anchor activation and external opens a new tab with safe rel and an announced default label. Both map selected to aria-current; disabled or loading links omit href and leave the tab order. rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls. A draggable row reorders by pointer drag or, with wireListReorder, Alt+Shift+ArrowUp/ArrowDown; a placeholder is never draggable."
       ],
       "geometry": {
         "margin": "self",
@@ -3527,7 +3952,30 @@
           "browser-condition-css"
         ]
       },
-      "wiring": [],
+      "wiring": [
+        {
+          "export": "wireListReorder",
+          "import": "@kerfjs/ui/wire-list-reorder",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-dragging",
+              "on": "ListItem / ListItemLink rows being dragged",
+              "meaning": "\"true\" on every row a pointer drag is moving (the dragged row, or every selected row of its list when the dragged row is selected). Same attribute the `dragging` prop renders."
+            },
+            {
+              "name": "data-drop-position",
+              "on": "ListItem / ListItemLink row under the pointer",
+              "meaning": "\"before\" or \"after\": the edge of this row the dragged rows would land beside. Same attribute the `dropPosition` prop renders."
+            }
+          ]
+        },
+        {
+          "export": "reorderListItems",
+          "import": "@kerfjs/ui/wire-list-reorder",
+          "required": false
+        }
+      ],
       "publicClasses": [
         "kui-list-item",
         "kui-list-item__icon",
@@ -3538,6 +3986,7 @@
         "kui-list-item__trailing"
       ],
       "publicTokens": [
+        "--kui-color-brand-border-loud",
         "--kui-color-brand-border-normal",
         "--kui-color-brand-border-quiet",
         "--kui-color-brand-fill-quiet",
@@ -3547,6 +3996,7 @@
         "--kui-color-neutral-on-quiet",
         "--kui-color-neutral-border-quiet",
         "--kui-color-neutral-border-normal",
+        "--kui-radius-pill",
         "--kui-focus-ring",
         "--kui-list-item-color",
         "--kui-list-item-background",
@@ -3557,6 +4007,9 @@
         "--kui-list-item-drag-target-background",
         "--kui-list-item-drag-target-outline",
         "--kui-list-item-drag-target-outline-offset",
+        "--kui-list-item-dragging-opacity",
+        "--kui-list-item-drop-indicator",
+        "--kui-list-item-drop-indicator-width",
         "--kui-list-item-gap",
         "--kui-list-item-hover-background",
         "--kui-list-item-hover-border",
@@ -3760,6 +4213,8 @@
         "framed pill item",
         "base surface item",
         "neutral, info, pop, success, warning, or danger semantic item",
+        "brand-loud item (solid brand fill, on-loud foreground)",
+        "chat bubble at the start or end of the row (bubble), fit to its content up to 80%",
         "named focus-target region",
         "multi-select rich grid row"
       ],
@@ -4228,6 +4683,83 @@
         "recipe": "docs/accessibility.md#segmentedcontrol"
       }
     },
+    {
+      "id": "choice-chips",
+      "name": "ChoiceChips",
+      "category": "Controls",
+      "kind": "component",
+      "source": "kerf",
+      "description": "An exclusive, wrapping set of separated pill chips backed by native radios, with optional leading color swatches or icons.",
+      "uses": [
+        "lucide-icon"
+      ],
+      "purpose": "Choose one value from a visible set too large for a segmented track, such as a color palette with labeled swatches.",
+      "publicExports": [
+        "ChoiceChips"
+      ],
+      "useWhen": [
+        "Expose one exclusive choice among several visible options that must wrap onto more rows, such as a labeled color palette with swatches."
+      ],
+      "avoidWhen": [
+        "Use SegmentedControl for a few compact choices on one track.",
+        "Use Select when the choice list is long or space is tight.",
+        "Do not use it for removable tags (Chip) or for multiple selection."
+      ],
+      "alternatives": [
+        {
+          "id": "segmented-control",
+          "relationship": "nearest"
+        },
+        {
+          "id": "select",
+          "relationship": "nearest"
+        },
+        {
+          "id": "wa-radio-group",
+          "relationship": "prefer-over",
+          "when": "Use ChoiceChips instead of button-appearance radios that must wrap; a joined button group wraps into ragged rows with shared borders."
+        }
+      ],
+      "appOwns": [
+        "value",
+        "choices and labels",
+        "swatch colors",
+        "change action",
+        "form submission"
+      ],
+      "variants": [
+        "color swatch, transparent (struck-through) swatch, icon, or text-only choices",
+        "default or compact size",
+        "disabled group or disabled choices",
+        "required"
+      ],
+      "accessibility": [
+        "The group is a named role=\"radiogroup\" of native radios: one Tab stop, arrow keys move the selection, and the checked radio submits the form value.",
+        "Every choice keeps a visible text label; the swatch is decorative and the selection adds a heavier border, so neither relies on color alone."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/choice-chips",
+        "manualCssImport": "@kerfjs/ui/choice-chips.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-choice-chips"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=choice-chips",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/accessibility.md#choicechips"
+      }
+    },
     {
       "id": "token-search-field",
       "name": "TokenSearchField",
@@ -4391,13 +4923,25 @@
         {
           "path": "restoreInset",
           "grammar": "length",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
           "shorthands": [],
           "canonicalShorthands": [],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["restoreInset={space(\"xs\")}"]
+          "examples": [
+            "restoreInset={space(\"xs\")}"
+          ]
         }
       ],
       "useWhen": [
@@ -4433,8 +4977,8 @@
         "slide, fade-slide, or instant content",
         "clipped, scrolling, or popup-visible content",
         "inline, overlay, or hidden responsive presentation",
-        "safe-area restore control"
-        ,"top-corner or inline restore placement"
+        "safe-area restore control",
+        "top-corner or inline restore placement"
       ],
       "accessibility": [
         "Preserve separator naming, value ARIA, and keyboard behavior.",
@@ -4581,6 +5125,11 @@
         {
           "id": "wa-dropdown",
           "relationship": "prefer-over"
+        },
+        {
+          "id": "combobox",
+          "relationship": "nearest",
+          "when": "Use Combobox when people may type to filter or create a new value."
         }
       ],
       "appOwns": [
@@ -4665,6 +5214,117 @@
         "recipe": "docs/component-selection.md#web-awesome-overlap-policy"
       }
     },
+    {
+      "id": "combobox",
+      "name": "Combobox",
+      "category": "Controls",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A free-text field with a filtered suggestion list that can also create a new value.",
+      "uses": [],
+      "purpose": "Let people pick an existing value or create a new one by typing (tags, labels, recipients), with the themed field chrome, the ARIA combobox pattern, and a touch-safe font size, without a native datalist or app CSS.",
+      "publicExports": [
+        "Combobox",
+        "wireComboboxes"
+      ],
+      "useWhen": [
+        "People type to find an existing value among many, or create a new one (tags, labels, recipients)."
+      ],
+      "avoidWhen": [
+        "Do not use when only existing values are allowed and nothing needs typing; use Select.",
+        "Do not use for free text plus removable filter tokens in one editor; use TokenSearchField.",
+        "Do not style a native input with a datalist from app CSS."
+      ],
+      "alternatives": [
+        {
+          "id": "select",
+          "relationship": "nearest",
+          "when": "Use Select when only existing values are allowed."
+        },
+        {
+          "id": "token-search-field",
+          "relationship": "nearest",
+          "when": "Use TokenSearchField for search text with removable filter tokens."
+        }
+      ],
+      "appOwns": [
+        "the suggestions and the committed values",
+        "normalizing and validating created values",
+        "clearing the field after a commit"
+      ],
+      "variants": [
+        "with create",
+        "suggestions only (createLabel={false})",
+        "hint",
+        "disabled"
+      ],
+      "accessibility": [
+        "Native input with role=combobox, aria-autocomplete=list, aria-expanded, aria-controls, and aria-activedescendant; options are role=option in a listbox. The visible label is a real label; the hint is aria-describedby."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self",
+        "notes": [
+          "Label and hint sit on the value's text column (1px border + 8px padding); the 44px field matches a themed wa-input."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/combobox",
+        "manualCssImport": "@kerfjs/ui/combobox.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireComboboxes",
+          "import": "@kerfjs/ui/wire-comboboxes",
+          "required": true,
+          "reason": "Filters suggestions, moves the active option, and reports commits; without it the list never opens.",
+          "stateAttributes": [
+            {
+              "name": "data-value",
+              "on": "the create option (kui-combobox__option[data-create])",
+              "meaning": "The typed text the create option would commit; rewritten as the person types."
+            }
+          ]
+        }
+      ],
+      "publicClasses": [
+        "kui-combobox",
+        "kui-combobox__label",
+        "kui-combobox__hint",
+        "kui-combobox__control",
+        "kui-combobox__input",
+        "kui-combobox__listbox",
+        "kui-combobox__option"
+      ],
+      "publicTokens": [
+        "--kui-combobox-z-index",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-text-quiet",
+        "--kui-color-neutral-border-normal",
+        "--kui-color-text",
+        "--kui-color-surface",
+        "--kui-color-surface-raised",
+        "--kui-color-text-link",
+        "--kui-color-brand-fill-quiet",
+        "--kui-font-xs",
+        "--kui-font-s",
+        "--kui-layout-item-padding",
+        "--kui-layout-rounded-radius",
+        "--kui-shadow-l",
+        "--kui-space-2xs",
+        "--kui-space-xs"
+      ],
+      "rootElement": "div",
+      "links": {
+        "catalogRoute": "?component=combobox",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "anchored-surface",
       "name": "AnchoredSurface",
@@ -4685,8 +5345,14 @@
         "Use PopupMenu for a typed action menu, Select for a choice, and a modal dialog for a task that must block the page."
       ],
       "alternatives": [
-        { "id": "popup-menu", "relationship": "nearest" },
-        { "id": "wa-popup", "relationship": "prefer-over" }
+        {
+          "id": "popup-menu",
+          "relationship": "nearest"
+        },
+        {
+          "id": "wa-popup",
+          "relationship": "prefer-over"
+        }
       ],
       "appOwns": [
         "content and action policy",
@@ -4717,7 +5383,9 @@
       "delivery": {
         "browserImport": "@kerfjs/ui/anchored-surface",
         "manualCssImport": "@kerfjs/ui/anchored-surface.css",
-        "sideEffects": ["browser-condition-css"]
+        "sideEffects": [
+          "browser-condition-css"
+        ]
       },
       "wiring": [],
       "publicClasses": [],
@@ -4747,6 +5415,7 @@
       "purpose": "A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.",
       "publicExports": [
         "PopupMenu",
+        "openPopupMenu",
         "openPopupMenuAt",
         "closePopupMenu"
       ],
@@ -4785,7 +5454,7 @@
         "nested actions",
         "checked choices and trailing details",
         "danger tone and disabled reasons",
-        "context trigger",
+        "context trigger with a rendered anchor point and a zero-footprint anchor host",
         "placement"
       ],
       "usageExamples": [
@@ -4839,72 +5508,431 @@
       }
     },
     {
-      "id": "feedback",
-      "name": "Feedback",
-      "category": "Feedback",
-      "kind": "composition",
+      "id": "icon-button",
+      "name": "IconButton",
+      "category": "Controls",
+      "kind": "component",
       "source": "kerf",
-      "description": "Banners, empty states, and labeled progress.",
+      "description": "Square, icon-only Web Awesome button with a LucideIcon and a required accessible name.",
       "uses": [
-        "state-banner",
-        "empty-state",
-        "loading-spinner"
+        "wa-button",
+        "lucide-icon"
+      ],
+      "purpose": "Render an icon-only action as a square one form-control height on each side, so it matches an adjacent wa-input or Select, without ::part overrides.",
+      "publicExports": [
+        "IconButton"
       ],
-      "purpose": "Banners, empty states, and labeled progress.",
-      "publicExports": [],
       "useWhen": [
-        "Compose persistent status, empty/busy content, and compact loading feedback."
+        "An icon-only action stands alone or beside a form field, such as a Browse button next to a path input."
       ],
       "avoidWhen": [
-        "Do not collapse different message lifetimes or urgency into one visual treatment."
+        "Do not use inside a ToolbarControlGroup; the group owns its controls' geometry, so compose a native button with a LucideIcon there.",
+        "Do not use when the action needs a visible text label; use wa-button with text.",
+        "Do not override wa-button::part(base) width, min-height, or padding to square an icon button; use IconButton."
       ],
       "alternatives": [
         {
-          "id": "state-banner",
-          "relationship": "nearest"
-        },
-        {
-          "id": "empty-state",
-          "relationship": "nearest"
-        },
-        {
-          "id": "wa-callout",
-          "relationship": "prefer-over"
+          "id": "wa-button",
+          "relationship": "prefer-over",
+          "when": "Web Awesome squares a button only for a lone wa-icon; with a LucideIcon use IconButton."
         },
         {
-          "id": "wa-toast",
-          "relationship": "prefer-over"
+          "id": "list-inset-control",
+          "relationship": "composes-with",
+          "when": "Beside a field in a ListInsetControl the square keeps its size and aligns with the field below its label."
         }
       ],
       "appOwns": [
-        "state mapping",
-        "message lifetime",
-        "recovery policy"
+        "the delegated action",
+        "the accessible name",
+        "appearance, variant, and size choice"
       ],
       "variants": [
-        "banner",
-        "empty",
-        "busy",
-        "spinner"
+        "default appearance",
+        "plain",
+        "outlined",
+        "danger variant",
+        "disabled",
+        "xs, s, m, l, or xl size"
       ],
       "accessibility": [
-        "Choose polite status versus assertive alert deliberately."
+        "label is required and names the button through its LucideIcon (role img), since the button shows no text."
       ],
       "geometry": {
-        "margin": "child",
-        "border": "child",
-        "padding": "child"
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
       },
       "delivery": {
+        "browserImport": "@kerfjs/ui/icon-button",
+        "manualCssImport": "@kerfjs/ui/icon-button.css",
+        "registrationImport": "@awesome.me/webawesome/dist/components/button/button.js",
+        "themeCssImport": "@kerfjs/ui/webawesome.css",
         "sideEffects": [
-          "css"
+          "browser-condition-css",
+          "custom-element-registration"
         ]
       },
       "wiring": [],
-      "publicClasses": [],
+      "publicClasses": [
+        "kui-icon-button"
+      ],
       "publicTokens": [],
+      "rootElement": "wa-button",
       "links": {
-        "catalogRoute": "?component=feedback",
+        "catalogRoute": "?component=icon-button",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "icon-toggle-button",
+      "name": "IconToggleButton",
+      "category": "Controls",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A standalone icon-only toggle with a single contained toolbar group's geometry and pressed chrome.",
+      "uses": [
+        "lucide-icon"
+      ],
+      "purpose": "Render an icon-only aria-pressed toggle in content or a pane footer, where a Toolbar does not belong, with the 44px contained geometry and raised pressed face of a single ToolbarControlGroup.",
+      "publicExports": [
+        "IconToggleButton"
+      ],
+      "useWhen": [
+        "An icon-only on/off control (show a panel, a conversation) sits in content or a pane footer outside any Toolbar."
+      ],
+      "avoidWhen": [
+        "Do not use inside a Toolbar; compose a ToolbarControlGroup there.",
+        "Do not use for a momentary action; use IconButton.",
+        "Do not use for one-of-several choices; use SegmentedControl."
+      ],
+      "alternatives": [
+        {
+          "id": "toolbar-control-group",
+          "relationship": "nearest",
+          "when": "Inside a Toolbar, a single ToolbarControlGroup with a pressed button is the same control."
+        },
+        {
+          "id": "icon-button",
+          "relationship": "nearest",
+          "when": "Use IconButton for a momentary icon-only action."
+        }
+      ],
+      "appOwns": [
+        "the pressed state and its delegated action",
+        "the accessible name"
+      ],
+      "variants": [
+        "pressed",
+        "unpressed",
+        "pill or rounded shape",
+        "disabled"
+      ],
+      "accessibility": [
+        "Native button with aria-pressed and a required aria-label; with help tags registered it shows that label on hover and keyboard focus."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/icon-toggle-button",
+        "manualCssImport": "@kerfjs/ui/icon-toggle-button.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-icon-toggle-button",
+        "kui-icon-toggle-button__face"
+      ],
+      "publicTokens": [
+        "--kui-color-neutral-border-normal",
+        "--kui-color-neutral-fill-normal",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-surface",
+        "--kui-color-brand-on-quiet",
+        "--kui-shadow-s",
+        "--kui-focus-ring",
+        "--kui-layout-pill-radius",
+        "--kui-layout-rounded-radius",
+        "--kui-layout-highlight-inset"
+      ],
+      "rootElement": "button",
+      "links": {
+        "catalogRoute": "?component=icon-toggle-button",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "split-button",
+      "name": "SplitButton",
+      "category": "Controls",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A primary action with an attached options trigger on one loud semantic fill.",
+      "uses": [
+        "lucide-icon",
+        "loading-spinner"
+      ],
+      "purpose": "Render a prominent primary action plus an options trigger (provider, model, target) as one control with a semantic tone, full-width sizing, a busy presentation, and native aria-expanded on the trigger, outside any Toolbar.",
+      "publicExports": [
+        "SplitButton"
+      ],
+      "useWhen": [
+        "A prominent primary action has a closely related set of options chosen from an attached trigger, such as Drive with a provider menu or Deploy with targets."
+      ],
+      "avoidWhen": [
+        "Do not use for a plain action without options; use wa-button.",
+        "Do not use inside a Toolbar for a command menu; use PopupMenu in a ToolbarControlGroup.",
+        "Do not use wa-button-group to build one; its hosts do not forward aria-expanded or names to their inner buttons."
+      ],
+      "alternatives": [
+        {
+          "id": "wa-button-group",
+          "relationship": "prefer-over",
+          "when": "SplitButton's native halves expose names and aria-expanded directly."
+        },
+        {
+          "id": "popup-menu",
+          "relationship": "composes-with",
+          "when": "Open the app's options menu from optionsAction; PopupMenu remains the command menu inside a toolbar."
+        }
+      ],
+      "appOwns": [
+        "the primary and options actions",
+        "the options menu and its open state",
+        "the running state, tone switch, and copy"
+      ],
+      "variants": [
+        "brand, neutral, success, warning, or danger tone",
+        "content width or fill",
+        "busy",
+        "disabled primary or options"
+      ],
+      "accessibility": [
+        "Both halves are native buttons in a group; the options trigger exposes aria-haspopup, aria-expanded, and optional aria-controls, and needs optionsLabel. busy sets aria-busy on the primary."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/split-button",
+        "manualCssImport": "@kerfjs/ui/split-button.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-split-button",
+        "kui-split-button__options",
+        "kui-split-button__icon",
+        "kui-split-button__label"
+      ],
+      "publicTokens": [
+        "--kui-color-brand-fill-loud",
+        "--kui-color-brand-on-loud",
+        "--kui-color-neutral-fill-loud",
+        "--kui-color-neutral-on-loud",
+        "--kui-color-success-fill-loud",
+        "--kui-color-success-on-loud",
+        "--kui-color-warning-fill-loud",
+        "--kui-color-warning-on-loud",
+        "--kui-color-danger-fill-loud",
+        "--kui-color-danger-on-loud",
+        "--kui-focus-ring",
+        "--kui-font-weight-semibold",
+        "--kui-layout-rounded-radius",
+        "--kui-space-s",
+        "--kui-space-xs"
+      ],
+      "rootElement": "div",
+      "links": {
+        "catalogRoute": "?component=split-button",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "file-picker",
+      "name": "FilePicker",
+      "category": "Controls",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A compact browse trigger and a dashed drop zone around native file inputs, with wiring that reports chosen and dropped files.",
+      "uses": [],
+      "purpose": "Let people choose or drop files (attachments, evidence, imports) without app CSS: a link-toned browse trigger and a dashed drop target that highlights while dragging, both around visually hidden native file inputs.",
+      "publicExports": [
+        "FilePickerTrigger",
+        "FileDropZone",
+        "wireFilePickers",
+        "fileMatchesAccept"
+      ],
+      "useWhen": [
+        "People attach or import files by browsing or by dropping them onto a target."
+      ],
+      "avoidWhen": [
+        "Do not style a native file input or label from app CSS; use these components.",
+        "Do not rely on the drop zone alone; it also opens the chooser when clicked or activated from the keyboard."
+      ],
+      "alternatives": [
+        {
+          "id": "wa-button",
+          "relationship": "prefer-over",
+          "when": "A button cannot open the native chooser without script; the trigger is a label around the input."
+        }
+      ],
+      "appOwns": [
+        "what happens to the reported files (upload, validation, limits)",
+        "the list of chosen files",
+        "copy and accepted types"
+      ],
+      "variants": [
+        "browse trigger",
+        "drop zone",
+        "dragging",
+        "disabled",
+        "accept filter",
+        "multiple or single"
+      ],
+      "accessibility": [
+        "Each control is a label around a real file input that receives keyboard focus; the visible control shows the focus ring. Give the input an accessibleLabel when the visible copy is short."
+      ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self",
+        "notes": [
+          "The drop zone carries the 8px content-item inline margin; the trigger is a compact 32px inline control."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/file-picker",
+        "manualCssImport": "@kerfjs/ui/file-picker.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireFilePickers",
+          "import": "@kerfjs/ui/wire-file-pickers",
+          "required": true,
+          "reason": "Reports chosen and dropped files and accepts drops on the zone; without it drops open the file in the browser.",
+          "stateAttributes": [
+            {
+              "name": "data-dragging",
+              "on": "kui-file-picker (drop zone)",
+              "meaning": "\"true\" while files are dragged over the zone."
+            }
+          ]
+        }
+      ],
+      "publicClasses": [
+        "kui-file-picker",
+        "kui-file-picker__title",
+        "kui-file-picker__detail",
+        "kui-file-picker__input",
+        "kui-file-picker__icon"
+      ],
+      "publicTokens": [
+        "--kui-color-text-link",
+        "--kui-color-brand-fill-quiet",
+        "--kui-color-neutral-border-loud",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-text",
+        "--kui-focus-ring",
+        "--kui-font-xs",
+        "--kui-font-2xs",
+        "--kui-font-weight-semibold",
+        "--kui-layout-inline-margin",
+        "--kui-layout-rounded-radius",
+        "--kui-radius-pill",
+        "--kui-space-2xs",
+        "--kui-space-s",
+        "--kui-space-xs"
+      ],
+      "rootElement": "label",
+      "links": {
+        "catalogRoute": "?component=file-picker",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "feedback",
+      "name": "Feedback",
+      "category": "Feedback",
+      "kind": "composition",
+      "source": "kerf",
+      "description": "Banners, empty states, and labeled progress.",
+      "uses": [
+        "state-banner",
+        "empty-state",
+        "loading-spinner"
+      ],
+      "purpose": "Banners, empty states, and labeled progress.",
+      "publicExports": [],
+      "useWhen": [
+        "Compose persistent status, empty/busy content, and compact loading feedback."
+      ],
+      "avoidWhen": [
+        "Do not collapse different message lifetimes or urgency into one visual treatment."
+      ],
+      "alternatives": [
+        {
+          "id": "state-banner",
+          "relationship": "nearest"
+        },
+        {
+          "id": "empty-state",
+          "relationship": "nearest"
+        },
+        {
+          "id": "wa-callout",
+          "relationship": "prefer-over"
+        },
+        {
+          "id": "wa-toast",
+          "relationship": "prefer-over"
+        }
+      ],
+      "appOwns": [
+        "state mapping",
+        "message lifetime",
+        "recovery policy"
+      ],
+      "variants": [
+        "banner",
+        "empty",
+        "busy",
+        "spinner"
+      ],
+      "accessibility": [
+        "Choose polite status versus assertive alert deliberately."
+      ],
+      "geometry": {
+        "margin": "child",
+        "border": "child",
+        "padding": "child"
+      },
+      "delivery": {
+        "sideEffects": [
+          "css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=feedback",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#ambiguous-choices"
       }
@@ -4943,6 +5971,11 @@
         {
           "id": "wa-toast",
           "relationship": "prefer-over"
+        },
+        {
+          "id": "corner-status",
+          "relationship": "composes-with",
+          "when": "Host app-level progress in a viewport corner with CornerStatus instead of fixed-position CSS."
         }
       ],
       "appOwns": [
@@ -4964,6 +5997,7 @@
         "badge",
         "stacked copy",
         "action below",
+        "strip presentation",
         "placeholder (loading)"
       ],
       "accessibility": [
@@ -5040,7 +6074,8 @@
         "--kui-state-banner-success-foreground",
         "--kui-state-banner-warning-background",
         "--kui-state-banner-warning-border",
-        "--kui-state-banner-warning-foreground"
+        "--kui-state-banner-warning-foreground",
+        "--kui-shadow-l"
       ],
       "links": {
         "catalogRoute": "?component=state-banner",
@@ -5048,6 +6083,194 @@
         "recipe": "docs/component-selection.md#ambiguous-choices"
       }
     },
+    {
+      "id": "corner-status",
+      "name": "CornerStatus",
+      "category": "Feedback",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Non-dismissible app-level status pinned to a viewport corner in the top layer, hosting StateBanner.",
+      "uses": [
+        "state-banner"
+      ],
+      "purpose": "Show ongoing app-level progress such as \"Loading…\" or \"Updating tickets… 3 of 12\" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.",
+      "publicExports": [
+        "CornerStatus",
+        "wireCornerStatus"
+      ],
+      "useWhen": [
+        "Show ongoing app-level progress or status that has no better home beside the affected work and must stay visible until the work ends."
+      ],
+      "avoidWhen": [
+        "Do not use for transient, dismissible confirmation; use a toast.",
+        "Do not use for status that belongs beside the affected work; place a StateBanner there.",
+        "Do not position a StateBanner with fixed-position application CSS; use CornerStatus."
+      ],
+      "alternatives": [
+        {
+          "id": "state-banner",
+          "relationship": "composes-with",
+          "when": "Compose one or more StateBanners (urgency=\"status\") inside it; they stack."
+        },
+        {
+          "id": "wa-toast",
+          "relationship": "prefer-over",
+          "when": "A toast item is transient and always dismissible; CornerStatus stays until the application removes it."
+        }
+      ],
+      "appOwns": [
+        "status lifetime (render while the work runs, remove when it ends)",
+        "the composed StateBanner copy and progress",
+        "corner placement"
+      ],
+      "variants": [
+        "bottom-end",
+        "bottom-start",
+        "top-end",
+        "top-start",
+        "embedded (in flow)"
+      ],
+      "accessibility": [
+        "The host adds no role; the composed StateBanner with urgency=\"status\" is the polite live region.",
+        "Opening never moves focus, and there is no close button, light dismiss, or Escape handling to compete with dialogs.",
+        "A modal dialog opened while it shows stacks above it and makes it inert (unannounced); show progress the dialog's task depends on inside the dialog."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child",
+        "notes": [
+          "Placement owns the 16px viewport gutter plus device safe-area insets; a StateBanner inside drops its inline margin and gains elevation."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/corner-status",
+        "manualCssImport": "@kerfjs/ui/corner-status.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireCornerStatus",
+          "import": "@kerfjs/ui/wire-corner-status",
+          "required": true,
+          "reason": "Opens each overlay host in the top layer as renders insert it; without it the Popover API keeps the host hidden."
+        }
+      ],
+      "publicClasses": [
+        "kui-corner-status"
+      ],
+      "publicTokens": [
+        "--kui-corner-status-gutter",
+        "--kui-corner-status-z-index",
+        "--kui-safe-area-block-end",
+        "--kui-safe-area-block-start",
+        "--kui-safe-area-inline-end",
+        "--kui-safe-area-inline-start",
+        "--kui-space-m",
+        "--kui-space-xs"
+      ],
+      "rootElement": "div",
+      "links": {
+        "catalogRoute": "?component=corner-status",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#ambiguous-choices"
+      }
+    },
+    {
+      "id": "edge-activity-indicator",
+      "name": "EdgeActivityIndicator",
+      "category": "Feedback",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A layout-free top-edge activity strip with a traveling wave and an optional hanging status pill.",
+      "uses": [],
+      "purpose": "Signal ambient background activity (server work, sync) along the top edge of the viewport without allocating layout or taking the pointer, with Kerf-owned motion and reduced-motion handling.",
+      "publicExports": [
+        "EdgeActivityIndicator"
+      ],
+      "useWhen": [
+        "Ambient, app-wide background activity (server work, sync) should be visible without a modal, a banner, or any layout shift."
+      ],
+      "avoidWhen": [
+        "Do not use for progress the user waits on or must read; use CornerStatus or a StateBanner.",
+        "Do not use for known progress; use a progress bar.",
+        "Do not use it as the only record of important state; the bars are hidden from assistive technology."
+      ],
+      "alternatives": [
+        {
+          "id": "corner-status",
+          "relationship": "nearest",
+          "when": "Use CornerStatus for readable, non-dismissible app-level progress."
+        },
+        {
+          "id": "loading-spinner",
+          "relationship": "nearest",
+          "when": "Use LoadingSpinner for local activity beside the affected control."
+        }
+      ],
+      "appOwns": [
+        "the busy state",
+        "the optional status message",
+        "the tone"
+      ],
+      "variants": [
+        "busy or idle",
+        "with or without a status pill",
+        "semantic tone",
+        "safe-area inset or flush"
+      ],
+      "accessibility": [
+        "The strip is aria-hidden and pointer-inert; the optional pill is a polite live region that holds text only while it shows. Under reduced motion the wave and scale stop and the strip and pill only fade."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none",
+        "notes": [
+          "Fixed to the top edge below the device safe area; it allocates no layout."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/edge-activity-indicator",
+        "manualCssImport": "@kerfjs/ui/edge-activity-indicator.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-edge-activity-indicator",
+        "kui-edge-activity-indicator__strip",
+        "kui-edge-activity-indicator__message"
+      ],
+      "publicTokens": [
+        "--kui-edge-activity-indicator-z-index",
+        "--kui-safe-area-block-start",
+        "--kui-color-brand-fill-loud",
+        "--kui-color-brand-on-loud",
+        "--kui-color-neutral-fill-loud",
+        "--kui-color-neutral-on-loud",
+        "--kui-color-pop-fill-loud",
+        "--kui-color-pop-on-loud",
+        "--kui-color-success-fill-loud",
+        "--kui-color-success-on-loud",
+        "--kui-color-warning-fill-loud",
+        "--kui-color-warning-on-loud",
+        "--kui-color-danger-fill-loud",
+        "--kui-color-danger-on-loud",
+        "--kui-font-2xs",
+        "--kui-space-m",
+        "--kui-space-s"
+      ],
+      "rootElement": "div",
+      "links": {
+        "catalogRoute": "?component=edge-activity-indicator",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "empty-state",
       "name": "EmptyState",
@@ -5374,7 +6597,13 @@
         "Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need."
       ],
       "recommendation": "supported",
-      "alternatives": [],
+      "alternatives": [
+        {
+          "id": "icon-button",
+          "relationship": "prefer-kerf",
+          "when": "For an icon-only button with a LucideIcon, use IconButton for Web Awesome's square icon-button geometry."
+        }
+      ],
       "geometry": {
         "margin": "none",
         "border": "self",
@@ -5416,6 +6645,11 @@
         {
           "id": "segmented-control",
           "relationship": "prefer-kerf"
+        },
+        {
+          "id": "split-button",
+          "relationship": "prefer-kerf",
+          "when": "For a primary action with an attached options trigger, use SplitButton."
         }
       ],
       "geometry": {