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

package/ai/component-catalog.json

@@ -84,34 +84,39 @@
       "category": "Foundation",
       "kind": "component",
       "source": "kerf",
-      "description": "A short tag with semantic tone and an optional accessible remove button, including compact and disabled variants.",
+      "description": "A short tag with semantic or inherited tone, an optional accessible remove button, or a native link and download form, including compact and disabled variants.",
       "uses": [],
-      "purpose": "Render removable tags without application rules on Web Awesome internals.",
+      "purpose": "Render removable tags and file or link chips without application rules on Web Awesome internals or anchor chrome.",
       "publicExports": [
         "Chip"
       ],
       "useWhen": [
-        "Show a short tag that the application can remove through a delegated action, including a compact or disabled tag."
+        "Show a short tag that the application can remove through a delegated action, including a compact or disabled tag.",
+        "Show a downloadable file or a short link with chip geometry, such as the referenced files of a chat message; set tone inherit inside a brand-loud or neutral ContentItem bubble."
       ],
       "avoidWhen": [
         "Use Badge for non-interactive status and count metadata.",
-        "Do not use the remove button without a specific accessible name."
+        "Do not use the remove button without a specific accessible name.",
+        "Use ListItemLink for a navigation row and ToolbarActionLink for a toolbar link."
       ],
       "alternatives": [],
       "appOwns": [
         "tag text and identity",
         "remove action and list update",
+        "link destination and download file name",
         "disabled policy"
       ],
       "variants": [
-        "neutral, info, pop, success, warning, or danger tone",
+        "neutral, info, pop, success, warning, danger, or inherit tone",
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
         "compact or default size",
-        "removable or plain, enabled or disabled"
+        "removable, link, or plain, enabled or disabled"
       ],
       "accessibility": [
         "The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.",
+        "A link chip is a native anchor named by its visible label; external adds a safe rel, a new tab, and an \"(opens in new tab)\" name suffix, and a disabled link chip drops its destination and leaves the tab order.",
+        "The inherit tone paints no fill, so its label keeps the surrounding text contrast, and its focus ring follows the surrounding foreground.",
         "Keep meaningful tag text visible because tone is supplementary."
       ],
       "geometry": {
@@ -314,7 +319,7 @@
     },
     {
       "id": "foundation",
-      "name": "Foundation tokens",
+      "name": "Foundation Tokens",
       "category": "Foundation",
       "kind": "composition",
       "source": "kerf",
@@ -404,6 +409,9 @@
         "--kui-color-surface-lowered",
         "--kui-sunken-texture",
         "--kui-sunken-surface",
+        "--kui-chrome-material",
+        "--kui-chrome-material-raised",
+        "--kui-chrome-material-filter",
         "--kui-color-text",
         "--kui-color-text-quiet",
         "--kui-color-text-link",
@@ -478,7 +486,7 @@
     },
     {
       "id": "document-baseline",
-      "name": "Document baseline",
+      "name": "Document Baseline",
       "category": "Foundation",
       "kind": "composition",
       "source": "kerf",
@@ -544,7 +552,7 @@
     },
     {
       "id": "layout",
-      "name": "Application layout",
+      "name": "Application Layout",
       "category": "Foundation",
       "kind": "composition",
       "source": "kerf",
@@ -638,11 +646,14 @@
         "Pinned chrome needs a divider from the scrolling content only while content is scrolled beneath it (wireScrollDividers).",
         "A lowered background must cover the scrolling work viewport and blank space after short content without a second scroll container (appearance: sunken).",
         "A child table or other component needs edge-to-edge decoration with text aligned to other pane content.",
-        "An opaque edge-to-edge child needs a reserved vertical scrollbar gutter."
+        "An opaque edge-to-edge child needs a reserved vertical scrollbar gutter.",
+        "Scrolling content must pass beneath chrome laid over the pane edge (a DialogSurface floating footer) while its first and last items still rest clear of it (scrollClearance).",
+        "The header should float over the scrolling content on a translucent material so content scrolls visibly beneath it, with the first item still resting below the header (headerPresentation: overlay, measured by wireScrollDividers)."
       ],
       "avoidWhen": [
         "Do not use Pane as a padded card or add a competing scroll owner around its content slot.",
-        "Do not enable separators merely as decoration; use them only where the pane owns a real boundary."
+        "Do not enable separators merely as decoration; use them only where the pane owns a real boundary.",
+        "A ToolbarText description in an overlay header is fine: an untoned ToolbarText there takes the normal text color for its title and lifts its description halfway toward it, keeping AA over the content passing beneath. Do not put other quiet secondary text in an overlay header; keep it in the content."
       ],
       "alternatives": [
         {
@@ -661,7 +672,9 @@
         "whether the chrome dividers follow the scroll, always show, or never show (chromeDividers)",
         "default or sunken scrolling work surface (appearance)",
         "whether to reserve a vertical scrollbar gutter for opaque edge-to-edge content (--kui-pane-scrollbar-gutter)",
-        "optional keyboard or programmatic focus (tabIndex) and persistent focus outline (outlined)"
+        "optional keyboard or programmatic focus (tabIndex) and persistent focus outline (outlined)",
+        "whether the scrolling content clears overlaying chrome on its block edges (scrollClearance, also in PaneConfig, so a Workbench mainPane or panel pane, a CollapsiblePanel pane, or a NavStack view pane forwards it)",
+        "whether the header is docked in its own row or laid over the scrolling content on the translucent chrome material (headerPresentation, also in PaneConfig)"
       ],
       "variants": [
         "content only",
@@ -672,11 +685,14 @@
         "inline-start separator",
         "inline-end separator",
         "chrome dividers only while scrolled (default, wired by wireScrollDividers)",
-        "always or no chrome dividers"
+        "always or no chrome dividers",
+        "scrollClearance block-start, block-end, or both on the scrolling content",
+        "overlay header on the translucent chrome material (headerPresentation: overlay)"
       ],
       "accessibility": [
         "Choose semantic root and content elements that match the region and provide labels for landmark elements.",
-        "Keep fixed header/footer chrome outside the single scrolling content slot so reading and focus order remain coherent."
+        "Keep fixed header/footer chrome outside the single scrolling content slot so reading and focus order remain coherent.",
+        "An overlay header's text uses the normal text color, which keeps WCAG AA over the 80% chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter."
       ],
       "geometry": {
         "margin": "child",
@@ -687,7 +703,9 @@
           "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.",
-          "For opaque edge-to-edge children, --kui-pane-scrollbar-gutter: stable reserves a vertical scrollbar gutter outside the published content insets; the default is auto."
+          "For opaque edge-to-edge children, --kui-pane-scrollbar-gutter: stable reserves a vertical scrollbar gutter outside the published content insets; the default is auto.",
+          "scrollClearance adds the inherited --kui-scroll-clearance-block-start/end context, published by overlaying chrome, to the scrolling content block padding and scroll padding alongside safe areas and deepInset.",
+          "headerPresentation overlay: once wireScrollDividers measures the header, the header shares the content cell above the scroller, its border-box height is published as --kui-scroll-clearance-block-start on the Pane root, and the content clears it automatically; unwired or with chromePlacement auto, the header stays docked."
         ]
       },
       "delivery": {
@@ -712,6 +730,11 @@
               "name": "data-scroll-divider",
               "on": "kui-pane__header and kui-pane__footer",
               "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-header-overlay",
+              "on": "kui-pane",
+              "meaning": "measured once the wiring has measured an overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root (and a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered); the header then lies over the content, which clears it. Both are re-applied if a re-render drops them."
             }
           ]
         }
@@ -734,7 +757,10 @@
         "--kui-pane-content-inset-inline-start",
         "--kui-pane-content-inset-inline-end",
         "--kui-pane-scrollbar-gutter",
-        "--kui-sunken-panel-background"
+        "--kui-sunken-panel-background",
+        "--kui-chrome-material",
+        "--kui-chrome-material-filter",
+        "--kui-scroll-clearance-block-start"
       ],
       "links": {
         "catalogRoute": "?component=pane",
@@ -759,6 +785,8 @@
         "NavStackView",
         "NavStackToolbarConfig",
         "NavStackProps",
+        "NavStackChromePresentation",
+        "NavStackBottomToolbarPresentation",
         "NavStack"
       ],
       "useWhen": [
@@ -795,7 +823,9 @@
         "per-view leading, center, and trailing top-toolbar groups",
         "per-view header and footer with List and Pane configuration",
         "top-toolbar defaults, title size, and heading level",
-        "whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers)"
+        "whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers)",
+        "whether the top chrome docks above the active view or lies over it on the translucent chrome material (chromePresentation)",
+        "whether the bottom toolbar docks below the active view or lies over it on the translucent chrome material (bottomToolbarPresentation)"
       ],
       "variants": [
         "single root view",
@@ -807,13 +837,17 @@
         "persistent final top-toolbar group (panelToggle) when embedded in a Workbench panel",
         "persistent bottom-toolbar fallback",
         "chrome and bottom-toolbar dividers only while the active view scrolls beneath them (wired by wireScrollDividers)",
-        "permanent or no chrome dividers (chromeDividers always or none)"
+        "permanent or no chrome dividers (chromeDividers always or none)",
+        "translucent top chrome laid over the active view (chromePresentation overlay, measured by wireNavStack)",
+        "translucent bottom toolbar laid over the active view (bottomToolbarPresentation overlay, measured by wireNavStack)"
       ],
       "accessibility": [
         "Give the stack region an accessible label and every back control a stable action label; visible backText names the control itself.",
         "Set toolbarConfig.headingLevel when the view title is the page's or section's heading landmark.",
         "Use wireNavStack so each controlled push moves focus into the new top view and each pop restores the revealed view's remembered descendant.",
-        "Mark a preferred initial heading or control with data-nav-focus when the first enabled focusable descendant is not the right target."
+        "Mark a preferred initial heading or control with data-nav-focus when the first enabled focusable descendant is not the right target.",
+        "Overlay chrome (chromePresentation overlay) keeps WCAG AA over content passing beneath the translucent material: an untoned ToolbarText there takes the normal text color for its title and lifts its description halfway toward it; keep other quiet copy in the view. The material turns opaque under reduced transparency, increased contrast, forced colors, or without backdrop-filter.",
+        "An overlay bottom toolbar (bottomToolbarPresentation overlay) keeps the same AA rule: an untoned ToolbarText there lifts its title and description, and a default-tone ToolbarControlGroup in either overlaid bar takes the normal text color for its controls. Its 1px top edge stays visible in forced colors."
       ],
       "geometry": {
         "margin": "none",
@@ -821,7 +855,9 @@
         "padding": "child",
         "notes": [
           "The stack owns its full-height chrome and viewport; each view owns its internal content padding and scrollable content.",
-          "The top chrome's bottom line and the bottom toolbar's top line are scroll state (wireScrollDividers), drawn as an overlaid 1px pseudo-element on the chrome and the bottom toolbar's always-present 1px top border, so neither moves the chrome or the content."
+          "The top chrome's bottom line and the bottom toolbar's top line are scroll state (wireScrollDividers), drawn as an overlaid 1px pseudo-element on the chrome and the bottom toolbar's always-present 1px top border, so neither moves the chrome or the content.",
+          "chromePresentation overlay: once wireNavStack measures the live chrome (never a cross-fading copy), the chrome lies over the viewport's top edge and its border-box height, top safe area included, becomes the viewport's block-start --kui-edge-inset-* context, so a plain view, a sole Pane, or a nested layout pads and scroll-pads by it automatically; the chrome ends where a classic scrollbar in the active view begins, so its track stays uncovered; unwired, or with hideToolbar, the chrome stays docked.",
+          "bottomToolbarPresentation overlay: once wireNavStack measures the live bottom toolbar (never a cross-fading copy), the toolbar lies over the viewport's bottom edge and its border-box height, bottom safe area and divider border included, becomes the viewport's block-end --kui-edge-inset-* context, so a plain view, a sole Pane (its content, or its footer), or a nested layout pads and scroll-pads by it automatically and the last item rests just above the toolbar; it ends where a classic scrollbar in the active view begins; unwired, or while no bottom toolbar is shown, it stays docked. It is independent of chromePresentation, which governs only the top chrome."
         ]
       },
       "delivery": {
@@ -857,6 +893,16 @@
               "name": "data-nav-exiting",
               "on": "kui-nav-stack__view",
               "meaning": "\"true\" on a popped view the helper briefly re-inserts to slide it out."
+            },
+            {
+              "name": "data-chrome-overlay",
+              "on": "kui-nav-stack",
+              "meaning": "measured once the helper has measured an overlay chrome (chromePresentation: overlay) and published its border-box height on the stack root; the chrome then lies over the active view, which clears it through the block-start edge context. Both are re-applied if a re-render drops them."
+            },
+            {
+              "name": "data-bottom-toolbar-overlay",
+              "on": "kui-nav-stack",
+              "meaning": "measured once the helper has measured an overlay bottom toolbar (bottomToolbarPresentation: overlay) and published its border-box height on the stack root; the toolbar then lies over the active view, which clears it through the block-end edge context. Both are re-applied if a re-render drops them."
             }
           ]
         },
@@ -874,6 +920,11 @@
               "name": "data-scroll-divider",
               "on": "kui-nav-stack__chrome and kui-nav-stack__bottom",
               "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-header-overlay",
+              "on": "kui-pane",
+              "meaning": "measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it."
             }
           ]
         }
@@ -1018,6 +1069,16 @@
               "name": "data-nav-exiting",
               "on": "kui-nav-stack__view",
               "meaning": "\"true\" on a popped view the helper briefly re-inserts to slide it out."
+            },
+            {
+              "name": "data-chrome-overlay",
+              "on": "kui-nav-stack",
+              "meaning": "measured once the helper has measured the compact stack's overlay chrome (compactStack.chromePresentation: overlay) and published its border-box height on the stack root. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-bottom-toolbar-overlay",
+              "on": "kui-nav-stack",
+              "meaning": "measured once the helper has measured the compact stack's overlay bottom toolbar (compactStack.bottomToolbarPresentation: overlay) and published its border-box height on the stack root. Re-applied if a re-render drops it."
             }
           ]
         }
@@ -1090,13 +1151,15 @@
         "one NavStack per tab",
         "bar divider only while the active scene continues below it (wired by wireScrollDividers)",
         "permanent or no bar divider (chromeDividers always or none)",
-        "sunken active-scene separator (separator auto or hidden)"
+        "sunken active-scene separator (separator auto or hidden)",
+        "translucent tab bar laid over the active scene (barPresentation overlay, measured by wireTabNavigator)"
       ],
       "accessibility": [
         "Give the tablist an accessible label and keep exactly the active tab in the sequential focus order.",
         "Wire selection through the controlled active id while leaving inactive scenes mounted and hidden.",
         "A focusable scene is a tabpanel named by its tab label; optional scene tabIndex applies only while active.",
-        "A tab badge is aria-hidden; supply badgeLabel so the tab's accessible name becomes \"<label>, <badgeLabel>\" (it defaults to the badge text). The dot form, badge: true, has no text, so its badgeLabel is required."
+        "A tab badge is aria-hidden; supply badgeLabel so the tab's accessible name becomes \"<label>, <badgeLabel>\" (it defaults to the badge text). The dot form, badge: true, has no text, so its badgeLabel is required.",
+        "Over the overlay bar's translucent material, unselected labels lift halfway toward --kui-color-text and the selected label mixes 40% of it into the brand color, so both keep 4.5:1 over worst-case content; the material turns opaque under reduced transparency or increased contrast and paints Canvas with a CanvasText edge in forced colors."
       ],
       "geometry": {
         "margin": "none",
@@ -1104,7 +1167,8 @@
         "padding": "self",
         "notes": [
           "The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.",
-          "The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it."
+          "The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it.",
+          "barPresentation=overlay: once wireTabNavigator has measured the live bar (data-bar-overlay=measured), the bar is absolutely positioned over the scenes on --kui-chrome-material and the scenes route its border-box height (bottom safe area included) as the block-end --kui-edge-inset-* context, so a plain scene pads and scroll-pads by it and a sole Pane or NavStack clears it; unwired it stays docked."
         ]
       },
       "delivery": {
@@ -1135,6 +1199,11 @@
               "name": "data-scroll-divider",
               "on": "kui-tab-scaffold__bar",
               "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-header-overlay",
+              "on": "kui-pane",
+              "meaning": "measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it."
             }
           ]
         }
@@ -1294,6 +1363,11 @@
               "name": "data-scroll-divider",
               "on": "kui-pane__header and kui-pane__footer of each panel and work-area Pane",
               "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-header-overlay",
+              "on": "kui-pane",
+              "meaning": "measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it."
             }
           ]
         }
@@ -1449,6 +1523,11 @@
               "name": "data-scroll-divider",
               "on": "kui-pane__header and kui-pane__footer of each panel and work-area Pane",
               "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-header-overlay",
+              "on": "kui-pane",
+              "meaning": "measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it."
             }
           ]
         }
@@ -1634,6 +1713,11 @@
               "name": "data-scroll-divider",
               "on": "a Toolbar named as targets chrome",
               "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-header-overlay",
+              "on": "kui-pane",
+              "meaning": "measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it."
             }
           ]
         },
@@ -1770,7 +1854,9 @@
       "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."
+        "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.",
+        "In an overlay Pane header (headerPresentation=\"overlay\"), overlay NavStack chrome (chromePresentation=\"overlay\") or bottom toolbar (bottomToolbarPresentation=\"overlay\"), or a DialogSurface floating header's header-actions (headerPresentation=\"floating\"), a default-tone group (not dark-toned, not an avatar scrim) takes --kui-color-text for its controls, so they keep WCAG AA over content passing beneath the translucent chrome material.",
+        "A dark-toned group's hover paints a 14% surface wash over its loud fill, on one control of a group or across a lone control's whole group, so the on-loud icon keeps at least 3:1 over a light page and well above it in dark."
       ],
       "geometry": {
         "margin": "none",
@@ -1913,7 +1999,7 @@
     },
     {
       "id": "surface-scaffold",
-      "name": "Surface scaffolds",
+      "name": "Surface Scaffolds",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
@@ -1933,11 +2019,14 @@
         "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 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\"."
+        "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\".",
+        "A chat-style dialog floats its composer over the transcript with footerPresentation=\"floating\" and keeps a heading or notice above one scrolling transcript with bodyLayout=\"fill-last\".",
+        "A dialog's title bar should float over the body on the translucent chrome material so a transcript scrolls visibly beneath both the title bar and a floating composer (headerPresentation=\"floating\" with bodyLayout=\"fill\" and a List or Pane that opts into scrollClearance=\"both\")."
       ],
       "avoidWhen": [
         "Do not use it as a generic layout wrapper or to replace application-owned modal state and focus lifecycle.",
-        "Do not stack a dialog body inset around children that already own List or content-item geometry; use bodyInset none."
+        "Do not stack a dialog body inset around children that already own List or content-item geometry; use bodyInset none.",
+        "Do not put quiet secondary text of your own in a floating dialog header; it can fall below AA over the content passing beneath. A ToolbarText slotted as the dialog's label (or into header-actions) is fine: its title takes the normal text color and its description lifts halfway toward it, keeping AA."
       ],
       "alternatives": [],
       "appOwns": [
@@ -1953,12 +2042,20 @@
         "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",
+        "fill-last body layout: fixed rows above one filling, scrolling last child",
+        "docked or floating footer with a typed footerOffset; the body reserves the measured footer height",
+        "floating footer over a filling child that opts into block-end scrollClearance: content scrolls beneath the footer through the published --kui-scroll-clearance-block-end",
+        "docked or floating header (headerPresentation) on the translucent chrome material; the body reserves the measured header height",
+        "floating header over a filling only child that opts into block-start scrollClearance: content scrolls beneath the title bar through the published --kui-scroll-clearance-block-start",
+        "floating header divider as scroll state: a hairline under the title bar only while the body or a filling child beneath it is scrolled away from its top",
+        "non-modal light-dismiss PopoverDialogSurface, overlay or embedded in flow, named by label or labelledBy and described by describedBy",
         "none, compact, or comfortable body and footer inset",
         "standard, compact, or zero-inset popup menu"
       ],
       "accessibility": [
         "Supply the wrapped wa-dialog label and retain Web Awesome's native modal and focus behavior.",
+        "Name a PopoverDialogSurface with label or labelledBy, and describe it with describedBy (rendered as aria-describedby), usually a title ToolbarText descriptionId.",
+        "A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.",
         "Use popup surfaces only for real dropdown menus with named triggers."
       ],
       "geometry": {
@@ -1984,7 +2081,11 @@
       "publicTokens": [
         "--kui-radius-l",
         "--kui-wa-container-inset",
-        "--kui-wa-surface-inset"
+        "--kui-wa-surface-inset",
+        "--kui-chrome-material-raised",
+        "--kui-chrome-material-filter",
+        "--kui-scroll-clearance-block-start",
+        "--kui-scroll-clearance-block-end"
       ],
       "links": {
         "catalogRoute": "?component=surface-scaffold",
@@ -2040,6 +2141,30 @@
             "viewportGutter={remify(8)}"
           ]
         },
+        {
+          "path": "footerOffset",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "footerOffset={remify(8)}"
+          ]
+        },
         {
           "path": "maxHeight",
           "grammar": "length",
@@ -2222,7 +2347,8 @@
       ],
       "accessibility": [
         "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.",
-        "Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap."
+        "Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap.",
+        "In a Pane header with headerPresentation=\"overlay\" or NavStack chrome with chromePresentation=\"overlay\" (or its bottom toolbar with bottomToolbarPresentation=\"overlay\"), or slotted as the label (or into header-actions) of a DialogSurface header with headerPresentation=\"floating\", untoned text keeps WCAG AA over the translucent chrome material: the title takes --kui-color-text at every size and the description mixes --kui-color-text-quiet halfway toward it."
       ],
       "geometry": {
         "margin": "none",
@@ -3416,7 +3542,8 @@
         "lengthVar",
         "plus",
         "calc",
-        "flex"
+        "flex",
+        "wireListFocusScroll"
       ],
       "publicExportImports": {
         "px": "@kerfjs/ui/css-values",
@@ -3427,7 +3554,8 @@
         "lengthVar": "@kerfjs/ui/css-values",
         "plus": "@kerfjs/ui/css-values",
         "calc": "@kerfjs/ui/css-values",
-        "flex": "@kerfjs/ui/css-values"
+        "flex": "@kerfjs/ui/css-values",
+        "wireListFocusScroll": "@kerfjs/ui/wire-list-focus-scroll"
       },
       "cssValueProps": [
         {
@@ -3495,6 +3623,52 @@
             "flex=\"none\"",
             "flex={flex(1, 1, rem(20))}"
           ]
+        },
+        {
+          "path": "maxHeight",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "maxHeight={rem(14)}"
+          ]
+        },
+        {
+          "path": "minHeight",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "minHeight={rem(4.25)}"
+          ]
         }
       ],
       "useWhen": [
@@ -3504,7 +3678,10 @@
         "Use a finite flex keyword or the flex() builder when List participates in flexible layout.",
         "Apply the standard text or control inset to selected physical sides without an application wrapper.",
         "Align children horizontally or distribute them vertically with the same physical alignment vocabulary as Row.",
-        "Use selectionMode=\"multiple\" and ariaLabel to group selectable rich ContentItem rows in a multi-select grid."
+        "Use selectionMode=\"multiple\" and ariaLabel to group selectable rich ContentItem rows in a multi-select grid.",
+        "Use scrollClearance on the scrollable List that reaches an edge overlaid by chrome (a DialogSurface floating footer) so rows scroll visibly beneath it while the first and last rows still rest clear of it.",
+        "Render a bounded, framed result picker of ListItem rows (search results, duplicate candidates) with scrollable, frame, and typed maxHeight/minHeight instead of an app-owned bordered scroller.",
+        "Call wireListFocusScroll(root) once when keyboard users move focus through a scrollable List's rows, so Firefox and Safari bring a partly hidden focused row and its ring fully into view as Chromium does."
       ],
       "avoidWhen": [
         "Do not use List as semantic list markup; use ul/ol when list semantics are required and apply layout deliberately.",
@@ -3516,7 +3693,9 @@
         "child semantics and content",
         "the bounded height needed for scrolling",
         "typed gap, flex, alignment, and divider choices",
-        "the accessible label and selection state of a multi-select grid"
+        "the accessible label and selection state of a multi-select grid",
+        "which one scroller opts into scroll clearance (the one reaching the covered edge)",
+        "the result picker bounds (maxHeight/minHeight) and its rows"
       ],
       "variants": [
         "no gap",
@@ -3525,6 +3704,9 @@
         "typed CssLength gap",
         "boolean, finite-keyword, or typed CssFlex flex",
         "scrollable",
+        "scrollClearance block-start, block-end, or both: clears overlaying chrome inside the scroll area",
+        "frame: 1px neutral border, control radius, and a 4px focus-ring-safe inset",
+        "typed CssLength maxHeight and minHeight bounds",
         "base or raised solid surface",
         "document reading inset",
         "left/center/right/full horizontal alignment",
@@ -3539,14 +3721,19 @@
       "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.",
-        "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."
+        "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.",
+        "With wireListFocusScroll, a keyboard-focused (:focus-visible) element in a scrollable List whose focus ring crosses the clip is scrolled into view (block and inline nearest, honoring the ring-room scroll padding) in every engine; pointer focus never scrolls, so a click cannot move its row from under the pointer."
       ],
       "geometry": {
         "margin": "none",
         "border": "conditional",
         "padding": "conditional",
         "notes": [
-          "List adds no margin. dividerSides draws selected physical edges without changing geometry; textInsets adds the full 17px content inset and controlInsets adds 8px on selected sides, with text winning on overlap."
+          "List adds no margin. dividerSides draws selected physical edges without changing geometry; textInsets adds the full 17px content inset and controlInsets adds 8px on selected sides, with text winning on overlap.",
+          "scrollClearance adds the inherited --kui-scroll-clearance-block-start/end context, published by overlaying chrome, to the List block padding and scroll-padding on the opted-in edges; without it the context is ignored.",
+          "frame draws a 1px --kui-color-neutral-border-normal border with --kui-radius-m and a 4px --kui-space-2xs inset on every side (replacing inset/textInsets/controlInsets), exactly the focus-ring reach, so the first and last rows' rings stay inside the clip at the scroll extremes; maxHeight/minHeight bound the List directly.",
+          "Every scrollable List's block scroll padding is the focus-ring reach plus 2px of slack (6px, no change at rest), so any row focused or scrolled into view stops with its ring inside the clip; an unframed List's first and last rows still meet the clip at the scroll extremes, so use frame when they must show a whole ring.",
+          "As a direct child of a Pane's scrolling content, a List that does not scroll itself never shrinks below its rows (flex-shrink 0), so the content's block-end padding (a bottom safe area, an overlay NavStack bottom toolbar's clearance) follows its last row."
         ]
       },
       "delivery": {
@@ -3571,8 +3758,18 @@
               "name": "data-scroll-divider",
               "on": "a List named as targets chrome",
               "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-header-overlay",
+              "on": "kui-pane",
+              "meaning": "measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it."
             }
           ]
+        },
+        {
+          "export": "wireListFocusScroll",
+          "import": "@kerfjs/ui/wire-list-focus-scroll",
+          "required": false
         }
       ],
       "publicClasses": [
@@ -3723,11 +3920,48 @@
           "examples": [
             "className=\"app-row\""
           ]
+        },
+        {
+          "path": "iconTile.color",
+          "grammar": "color",
+          "helpers": [
+            "fillColor",
+            "uiColor",
+            "colorVar"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "iconTile={{ color: fillColor(\"#e5484d\") }}",
+            "iconTile={{ color: uiColor(\"brand-fill-loud\") }}",
+            "iconTile={{ color: colorVar(\"--app-category-color\") }}"
+          ]
+        },
+        {
+          "path": "iconTile.foreground",
+          "grammar": "color",
+          "helpers": [
+            "uiColor",
+            "foregroundColorVar",
+            "foregroundColor"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "iconTile={{ color: fillColor(\"#e5484d\"), foreground: foregroundColor(\"white\") }}",
+            "iconTile={{ color: uiColor(\"brand-fill-loud\"), foreground: uiColor(\"brand-on-loud\") }}",
+            "iconTile={{ color: colorVar(\"--app-tile\"), foreground: foregroundColorVar(\"--app-tile-ink\") }}"
+          ]
         }
       ],
       "useWhen": [
         "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."
+        "A command row needs a trailing \"…\" overflow menu (trailingMenu), optionally also opened at the pointer from the row's contextmenu with openPopupMenuAt.",
+        "A settings or command row identifies each entry by a colored icon tile (iconTile) instead of a bare glyph."
       ],
       "avoidWhen": [
         "Use ListItem when trailing content is dormant metadata; use AppTab only for tablist semantics and ToolbarControlGroup only for toolbar controls.",
@@ -3767,7 +4001,8 @@
         "trailing overflow menu",
         "before, after, or paired group divider",
         "position-aware divided-list corners: flat wherever a divider line (this row's or a neighbor's) meets the edge",
-        "draggable row with dragging and drop-before / drop-after insertion states"
+        "draggable row with dragging and drop-before / drop-after insertion states",
+        "filled leading icon tile (iconTile): a quiet tone preset (neutral, brand, success, warning, danger) or an application fill with an optional foreground; a 32px rounded tile holding an 18px glyph"
       ],
       "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.",
@@ -3850,7 +4085,21 @@
         "--kui-list-action-row-selected-color",
         "--kui-list-action-row-trailing-hover-background",
         "--kui-list-group-divider-color",
-        "--kui-font-xs"
+        "--kui-list-row-padding-inline",
+        "--kui-list-row-icon-size",
+        "--kui-font-xs",
+        "--kui-radius-m",
+        "--kui-color-brand-fill-quiet",
+        "--kui-color-brand-on-quiet",
+        "--kui-color-success-fill-quiet",
+        "--kui-color-success-border-quiet",
+        "--kui-color-success-on-quiet",
+        "--kui-color-warning-fill-quiet",
+        "--kui-color-warning-border-quiet",
+        "--kui-color-warning-on-quiet",
+        "--kui-color-danger-fill-quiet",
+        "--kui-color-danger-border-quiet",
+        "--kui-color-danger-on-quiet"
       ],
       "links": {
         "catalogRoute": "?component=list-action-row",
@@ -3888,10 +4137,47 @@
           "examples": [
             "className=\"app-row\""
           ]
+        },
+        {
+          "path": "iconTile.color",
+          "grammar": "color",
+          "helpers": [
+            "fillColor",
+            "uiColor",
+            "colorVar"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "iconTile={{ color: fillColor(\"#e5484d\") }}",
+            "iconTile={{ color: uiColor(\"brand-fill-loud\") }}",
+            "iconTile={{ color: colorVar(\"--app-category-color\") }}"
+          ]
+        },
+        {
+          "path": "iconTile.foreground",
+          "grammar": "color",
+          "helpers": [
+            "uiColor",
+            "foregroundColorVar",
+            "foregroundColor"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "iconTile={{ color: fillColor(\"#e5484d\"), foreground: foregroundColor(\"white\") }}",
+            "iconTile={{ color: uiColor(\"brand-fill-loud\"), foreground: uiColor(\"brand-on-loud\") }}",
+            "iconTile={{ color: colorVar(\"--app-tile\"), foreground: foregroundColorVar(\"--app-tile-ink\") }}"
+          ]
         }
       ],
       "useWhen": [
-        "Render a selectable, disabled, trailing, or multiline sidebar action row whose descendants must remain clipped to the rounded row boundary; use ListItemLink when the destination has an href and needs native link activation."
+        "Render a selectable, disabled, trailing, or multiline sidebar action row whose descendants must remain clipped to the rounded row boundary; use ListItemLink when the destination has an href and needs native link activation.",
+        "A settings or command row identifies each entry by a colored icon tile (iconTile) instead of a bare glyph."
       ],
       "avoidWhen": [
         "Do not use for an ordinary inline link, form button, isolated ARIA menuitem, or an interactive trailing action; use ListActionRow for sibling row actions.",
@@ -3934,7 +4220,8 @@
         "description and status",
         "busy while retaining content",
         "before, after, or paired group divider",
-        "position-aware divided-list corners: flat wherever a divider line (this row's or a neighbor's) meets the edge"
+        "position-aware divided-list corners: flat wherever a divider line (this row's or a neighbor's) meets the edge",
+        "filled leading icon tile (iconTile): a quiet tone preset (neutral, brand, success, warning, danger) or an application fill with an optional foreground; a 32px rounded tile holding an 18px glyph"
       ],
       "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. A draggable row reorders by pointer drag or, with wireListReorder, Alt+Shift+ArrowUp/ArrowDown; a placeholder is never draggable."
@@ -4028,11 +4315,24 @@
         "--kui-list-item-selected-color",
         "--kui-list-item-trailing-color",
         "--kui-list-group-divider-color",
+        "--kui-list-row-padding-inline",
+        "--kui-list-row-icon-size",
         "--kui-font-xs",
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
         "--kui-layout-item-padding",
-        "--kui-layout-rounded-radius"
+        "--kui-layout-rounded-radius",
+        "--kui-radius-m",
+        "--kui-color-brand-on-quiet",
+        "--kui-color-success-fill-quiet",
+        "--kui-color-success-border-quiet",
+        "--kui-color-success-on-quiet",
+        "--kui-color-warning-fill-quiet",
+        "--kui-color-warning-border-quiet",
+        "--kui-color-warning-on-quiet",
+        "--kui-color-danger-fill-quiet",
+        "--kui-color-danger-border-quiet",
+        "--kui-color-danger-on-quiet"
       ],
       "links": {
         "catalogRoute": "?component=list-item",
@@ -4266,7 +4566,7 @@
     },
     {
       "id": "application-tabs",
-      "name": "Application tabs",
+      "name": "Application Tabs",
       "category": "Navigation",
       "kind": "composition",
       "source": "kerf",
@@ -4549,6 +4849,11 @@
               "name": "data-scroll-divider",
               "on": "chrome named in wireScrollDividers targets (a TabBar strip has none)",
               "meaning": "The sides, in t/r/b/l order, on which that chrome currently draws its scroll divider. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-header-overlay",
+              "on": "kui-pane",
+              "meaning": "measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it."
             }
           ]
         }
@@ -4691,21 +4996,50 @@
       "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.",
+      "description": "A wrapping set of separated pill chips backed by native radios (one exclusive value) or, with multiple, native checkboxes (any number of values), 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.",
+      "purpose": "Choose one value, or with multiple any number of values, from a visible set too large for a segmented track, such as a color palette with labeled swatches or a set of annotation intents.",
       "publicExports": [
-        "ChoiceChips"
+        "ChoiceChips",
+        "fillColor"
+      ],
+      "publicExportImports": {
+        "fillColor": "@kerfjs/ui/css-values"
+      },
+      "cssValueProps": [
+        {
+          "path": "choices[].swatch",
+          "grammar": "color",
+          "helpers": [
+            "fillColor",
+            "uiColor",
+            "colorVar"
+          ],
+          "shorthands": [
+            "transparent"
+          ],
+          "canonicalShorthands": [
+            "transparent"
+          ],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "swatch: fillColor(\"#3b82f6\")",
+            "swatch: uiColor(\"brand-fill-loud\")",
+            "swatch: colorVar(\"--app-label-color\")"
+          ]
+        }
       ],
       "useWhen": [
-        "Expose one exclusive choice among several visible options that must wrap onto more rows, such as a labeled color palette with swatches."
+        "Expose one exclusive choice among several visible options that must wrap onto more rows, such as a labeled color palette with swatches.",
+        "Set multiple when the person may turn any number of visible, wrapping options on or off, such as label filters or annotation intents."
       ],
       "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."
+        "Use Select when the choice list is long or space is tight; a multiple Select keeps a long multi-value list behind one trigger.",
+        "Do not use it for removable tags (Chip)."
       ],
       "alternatives": [
         {
@@ -4731,13 +5065,16 @@
       ],
       "variants": [
         "color swatch, transparent (struck-through) swatch, icon, or text-only choices",
+        "single (radios) or multiple (checkboxes) selection",
         "default or compact size",
         "disabled group or disabled choices",
-        "required"
+        "required (single selection only)"
       ],
       "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."
+        "The single 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.",
+        "A multiple group is a named role=\"group\" of native checkboxes: each pill is a Tab stop, Space toggles it, its checked state is native, and every checked value submits under name.",
+        "Every choice keeps a visible text label; the swatch is decorative and the selection adds a heavier border, so neither relies on color alone.",
+        "Every color is a theme token, so a dark appearance scope (.wa-dark, .wa-invert, or any color-scheme: dark ancestor) restyles the chips for inverse chrome."
       ],
       "geometry": {
         "margin": "none",
@@ -4762,6 +5099,84 @@
         "recipe": "docs/accessibility.md#choicechips"
       }
     },
+    {
+      "id": "composer",
+      "name": "Composer",
+      "category": "Controls",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A raised chat or prompt composer: a framed message field that grows with its content above an action row with a hint and a send button.",
+      "uses": [
+        "text"
+      ],
+      "purpose": "Write a chat message or prompt in a raised frame whose border turns brand while focus is within, with a field that grows between row bounds and a trailing send action.",
+      "publicExports": [
+        "Composer",
+        "wireComposers"
+      ],
+      "useWhen": [
+        "Write a chat message, assistant prompt, or comment reply that is sent with a trailing action, especially in a DialogSurface floating footer over a transcript."
+      ],
+      "avoidWhen": [
+        "Use wa-textarea with a FieldLabel for an ordinary form field that is submitted with the rest of a form.",
+        "Do not wrap it in another framed ContentItem or card; it owns its frame, padding, and shadow."
+      ],
+      "alternatives": [
+        {
+          "id": "wa-textarea",
+          "relationship": "prefer-over",
+          "when": "Use Composer instead of a wa-textarea and a button in app-styled chrome for a chat or prompt composer; it owns the raised frame, focus-within border, auto-grow, and action row."
+        }
+      ],
+      "appOwns": [
+        "value",
+        "send action",
+        "keyboard shortcuts other than the opt-in Enter-to-send",
+        "disabled and busy state of its actions",
+        "placement"
+      ],
+      "variants": [
+        "minRows and maxRows bounds for the growing field",
+        "optional hint, described by the field when an id is given",
+        "disabled field",
+        "submitOnEnter: Enter or Cmd/Ctrl+Enter activates the first trailing action, Shift+Enter inserts a newline (with wireComposers)",
+        "slotted into a DialogSurface floating footer"
+      ],
+      "accessibility": [
+        "The field is a native textarea named by label; with an id, the hint is its accessible description.",
+        "The frame's brand border shows focus within, and the trailing actions keep their own names and focus rings.",
+        "With submitOnEnter the field announces aria-keyshortcuts=\"Enter\"; Shift+Enter keeps a newline, and an Enter that commits an IME composition never sends."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/composer",
+        "manualCssImport": "@kerfjs/ui/composer.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireComposers",
+          "import": "@kerfjs/ui/wire-composers",
+          "required": false,
+          "reason": "Only for submitOnEnter: turns Enter (or Cmd/Ctrl+Enter) in the field into a click on the first trailing action, skipping Shift+Enter, IME composition, empty or whitespace-only messages, auto-repeat, and a disabled or loading action."
+        }
+      ],
+      "publicClasses": [
+        "kui-composer"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=composer",
+        "documentation": "docs/composer.md",
+        "recipe": "docs/accessibility.md#composer"
+      }
+    },
     {
       "id": "token-search-field",
       "name": "TokenSearchField",
@@ -5365,13 +5780,19 @@
         "element anchor",
         "pointer anchor",
         "top or bottom placement",
-        "modal-dialog host"
+        "modal-dialog host",
+        "tone: 'dark' (the inverse tone of a dark ToolbarControlGroup, for popups anchored to media chrome)"
       ],
       "usageExamples": [
         {
           "title": "Interactive help",
           "description": "The trigger owns when to open; the returned handle closes when an action completes.",
           "code": "const handle = openAnchoredSurface(button, () => <HelpPanel />, { label: 'Field help' });\n// Close from the app's action handler: handle.close();"
+        },
+        {
+          "title": "Popup anchored to dark media chrome",
+          "description": "tone: 'dark' matches a ToolbarControlGroup tone=\"dark\": the surface takes the opposite of the anchor's color scheme (openAnchoredSurfaceAt reads it from point.context) and follows a live OS-preference or ancestor theme switch while open, so its content inherits the inverse text, border, and focus colors without overrides.",
+          "code": "openAnchoredSurface(volumeButton, () => <VolumeControls />, {\n  label: 'Volume',\n  tone: 'dark',\n  placement: 'top',\n});"
         }
       ],
       "accessibility": [
@@ -5468,16 +5889,16 @@
         {
           "title": "Flat selected choices",
           "description": "Headings separate sort dimensions; trailing safe content marks the active command without changing its accessible label.",
-          "code": "<PopupMenu\n  label=\"Sort chat\"\n  items={[\n    { kind: 'heading', label: 'Sort by' },\n    { label: 'Updated', action: 'sort-updated', details: sort === 'updated' ? tick : undefined },\n    { label: 'Priority', action: 'sort-priority', details: sort === 'priority' ? tick : undefined },\n    { kind: 'heading', label: 'Order' },\n    { label: 'Newest first', action: 'order-newest', details: order === 'newest' ? tick : undefined },\n  ]}\n/>"
+          "code": "<PopupMenu\n  label=\"Sort chat\"\n  items={[\n    { kind: 'heading', label: 'Sort By' },\n    { label: 'Updated', action: 'sort-updated', details: sort === 'updated' ? tick : undefined },\n    { label: 'Priority', action: 'sort-priority', details: sort === 'priority' ? tick : undefined },\n    { kind: 'heading', label: 'Order' },\n    { label: 'Newest First', action: 'order-newest', details: order === 'newest' ? tick : undefined },\n  ]}\n/>"
         },
         {
           "title": "Pointer anchored context menu",
           "description": "Keep the row's visible disabled action separate from the context menu anchor. Find the menu root with a stable data attribute.",
-          "code": "<PopupMenu\n  context\n  label=\"Demand actions\"\n  rootAttributes={{ 'data-demand-menu': '' }}\n  items={[{ label: 'Open', action: 'open-demand' }]}\n/>\n// In the app's row wiring:\nrow.addEventListener('contextmenu', (event) => {\n  event.preventDefault();\n  const menu = row.querySelector('[data-demand-menu]') as PopupMenuElement;\n  openPopupMenuAt(menu, event.clientX, event.clientY);\n});\n// Call closePopupMenu(menu) when the app needs to dismiss it."
+          "code": "<PopupMenu\n  context\n  label=\"Demand Actions\"\n  rootAttributes={{ 'data-demand-menu': '' }}\n  items={[{ label: 'Open', action: 'open-demand' }]}\n/>\n// In the app's row wiring:\nrow.addEventListener('contextmenu', (event) => {\n  event.preventDefault();\n  const menu = row.querySelector('[data-demand-menu]') as PopupMenuElement;\n  openPopupMenuAt(menu, event.clientX, event.clientY);\n});\n// Call closePopupMenu(menu) when the app needs to dismiss it."
         }
       ],
       "accessibility": [
-        "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. Web Awesome provides menu roles, nested arrow-key navigation, typeahead, and Escape.",
+        "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. The open menu takes the trigger's name (the context or icon-only label, or the visible text), and each submenu takes its parent item's label, so a screen reader announces a named menu and getByRole('menu', { name }) finds it. Web Awesome provides menu roles, nested arrow-key navigation, typeahead, and Escape.",
         "Once registered, an icon-only trigger shows its label as an aria-hidden Web Awesome help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip."
       ],
       "geometry": {
@@ -6095,7 +6516,7 @@
       "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.",
+      "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"
@@ -9350,7 +9771,7 @@
     },
     {
       "id": "recipe-app-shell",
-      "name": "Desktop application shell",
+      "name": "Desktop Application Shell",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
@@ -9395,7 +9816,7 @@
     },
     {
       "id": "recipe-navigation-sidebar",
-      "name": "Navigation sidebar",
+      "name": "Navigation Sidebar",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
@@ -9440,7 +9861,7 @@
     },
     {
       "id": "recipe-workspace-header",
-      "name": "Workspace header",
+      "name": "Workspace Header",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
@@ -9531,7 +9952,7 @@
     },
     {
       "id": "recipe-composer-form",
-      "name": "Composer form",
+      "name": "Composer Form",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
@@ -9579,7 +10000,7 @@
     },
     {
       "id": "recipe-list-workspace-states",
-      "name": "List workspace states",
+      "name": "List Workspace States",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
@@ -9624,7 +10045,7 @@
     },
     {
       "id": "recipe-compact-toolbar",
-      "name": "Compact toolbar choices and actions",
+      "name": "Compact Toolbar Choices and Actions",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
@@ -9670,7 +10091,7 @@
     },
     {
       "id": "recipe-navigation-stack",
-      "name": "Navigation stack",
+      "name": "Navigation Stack",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
@@ -9714,7 +10135,7 @@
     },
     {
       "id": "recipe-loading-inspector",
-      "name": "Loading inspector",
+      "name": "Loading Inspector",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
@@ -9763,7 +10184,7 @@
     },
     {
       "id": "recipe-collapsible-sidebar",
-      "name": "Collapsible sidebar",
+      "name": "Collapsible Sidebar",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",