@kerfjs/ui 5.0.0-beta.64 → 5.0.0-beta.66

package/ai/component-catalog.json

@@ -725,6 +725,7 @@
         "preferred initial focus targets when DOM order is insufficient",
         "per-view bottom toolbar content or a persistent fallback",
         "per-view leading, center, and trailing top-toolbar groups",
+        "per-view fixed header content above the active view's scroll area",
         "top-toolbar configuration, title size, and heading level",
         "whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers)"
       ],
@@ -735,6 +736,7 @@
         "configured top toolbar",
         "custom back icon or visible back text",
         "per-view bottom toolbar",
+        "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)"
@@ -811,6 +813,7 @@
         "kui-nav-stack__chrome-copy",
         "kui-nav-stack__chrome-copy--bottom",
         "kui-nav-stack__chrome-copy--exiting",
+        "kui-nav-stack__header",
         "kui-nav-stack__viewport",
         "kui-nav-stack__view",
         "kui-nav-stack__view--entering",
@@ -1079,7 +1082,9 @@
       "kind": "component",
       "source": "kerf",
       "description": "A desktop-class multi-panel workspace with independently collapsible, optionally drag-resizable left and right rails and a bottom drawer around one central work area.",
-      "uses": [],
+      "uses": [
+        "nav-stack"
+      ],
       "purpose": "Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.",
       "publicExports": [
         "Workbench",
@@ -1088,6 +1093,8 @@
         "WorkbenchMainBottomToolbar",
         "WorkbenchMainToolbar",
         "WorkbenchPanel",
+        "WorkbenchStaticPanel",
+        "WorkbenchNavigationPanel",
         "WorkbenchPanelResizable",
         "WorkbenchPanelToggle",
         "WorkbenchPanelToolbar",
@@ -1114,6 +1121,7 @@
         "panel presence and content",
         "collapsed state",
         "panel sizes",
+        "navigation panel view stack and push/pop actions when navStack is supplied",
         "responsive replacement below desktop",
         "collapse controls and focus policy"
       ],
@@ -1124,6 +1132,7 @@
         "bottom drawer",
         "all panels",
         "independently collapsed panels",
+        "navigation panel with per-screen toolbar, fixed header, and one scroll owner; standard toggle remains last and relocates while collapsed",
         "opt-in drag and keyboard resizable panels with min/max limits",
         "resizable rails that leave the work area a minimum width and shrink in proportion when the Workbench narrows",
         "rails or a drawer that present as overlays below a narrow or compact Workbench container breakpoint",
@@ -2439,10 +2448,12 @@
         "typed CssLength gap",
         "boolean, finite-keyword, or typed CssFlex flex",
         "fill: the layout root fills a definite-height parent",
-        "rootAttributes: safe data-* metadata on the root"
+        "rootAttributes: safe data-* metadata on the root",
+        "selectionMode=multiple: labeled multi-select grid for ContentItem tiles"
       ],
       "accessibility": [
-        "Grid adds layout only and no grid role; children retain responsibility for native or ARIA semantics.",
+        "Grid adds no role by default; selectionMode=multiple requires ariaLabel and supplies a multi-select grid for ContentItem row/gridcell tiles.",
+        "wireContentItems uses rendered tile positions for Left/Right/Up/Down and reaches the first or last tile with Home/End.",
         "Responsive column-count changes preserve source and focus order."
       ],
       "geometry": {
@@ -2731,7 +2742,8 @@
         "Choose a finite gap shorthand such as xs or m, or compose a typed length with @kerfjs/ui/css-values when the spacing scale is insufficient.",
         "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."
+        "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."
       ],
       "avoidWhen": [
         "Do not use List as semantic list markup; use ul/ol when list semantics are required and apply layout deliberately.",
@@ -2742,7 +2754,8 @@
       "appOwns": [
         "child semantics and content",
         "the bounded height needed for scrolling",
-        "typed gap, flex, alignment, and divider choices"
+        "typed gap, flex, alignment, and divider choices",
+        "the accessible label and selection state of a multi-select grid"
       ],
       "variants": [
         "no gap",
@@ -2757,10 +2770,11 @@
         "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",
-        "scroll dividers when named as wireScrollDividers targets chrome"
+        "scroll dividers when named as wireScrollDividers targets chrome",
+        "multi-select grid for rich ContentItem rows"
       ],
       "accessibility": [
-        "List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.",
+        "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."
       ],
       "geometry": {
@@ -3312,7 +3326,8 @@
       "useWhen": [
         "An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.",
         "A content item marks a real distinction and must read as visibly bounded: pass frame=\"framed\" (the border is always reserved, so geometry does not change).",
-        "A content item should follow a pill control's 22px radius: pass shape=\"pill\"."
+        "A content item should follow a pill control's 22px radius: pass shape=\"pill\".",
+        "A selectable rich card needs nested controls: use selectionMode=\"multiple\" inside a labeled List multi-select grid."
       ],
       "avoidWhen": [
         "Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.",
@@ -3342,19 +3357,22 @@
         "whether the item marks a real distinction that warrants a visible frame",
         "corner shape",
         "region semantics and accessible name",
-        "whether the item is a programmatic focus target"
+        "whether the item is a programmatic focus target",
+        "the selection set and Shift/Cmd extension for multi-select rich cards"
       ],
       "variants": [
         "unframed rounded item",
         "framed rounded item",
         "pill item",
         "framed pill item",
-        "named focus-target region"
+        "named focus-target region",
+        "multi-select rich grid row"
       ],
       "accessibility": [
         "An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role=\"region\").",
         "focusTarget makes the item a programmatic focus target (tabindex=\"-1\", never a tab stop), such as a NavStack view's data-nav-focus target.",
-        "The frame is decorative and never the only signal of state."
+        "The frame is decorative and never the only signal of state.",
+        "selectionMode=\"multiple\" renders a focusable row with aria-selected and a gridcell for nested controls; place it in a labeled List selectionMode=\"multiple\" grid. wireContentItems moves focus among rows with Up/Down and Home/End while nested controls retain those keys. Guard the app's delegated card action with isContentItemActivation so a nested control does not select the row."
       ],
       "geometry": {
         "margin": "self",
@@ -3837,7 +3855,8 @@
       },
       "useWhen": [
         "Combine DOM-owned free text with ordered editable/removable filter tokens in one searchbox.",
-        "Enable collapsible mode when an empty, unfocused search should reduce to one iconic action, standalone or inside a toolbar group."
+        "Enable collapsible mode when an empty, unfocused search should reduce to one iconic action, standalone or inside a toolbar group.",
+        "Use presentation=\"form-field\" for a structured search query beside Web Awesome form controls, with a visible label, optional hint, and required marker."
       ],
       "avoidWhen": [
         "Do not use for ordinary text input or separately labeled filter controls."
@@ -3852,19 +3871,22 @@
         "the grammar and evaluation callback when using the optional managed model, or parsing, suggestions, tokens, and query execution in manual mode",
         "results",
         "the revision that rebuilds the DOM-owned editor for a programmatic text replacement",
-        "optional override of the collapsible expand/collapse/focus, which wireTokenSearchFields manages by default (adopt an app expanded signal, opt out per behavior, or drive it via the returned handle)"
+        "optional override of the collapsible expand/collapse/focus, which wireTokenSearchFields manages by default (adopt an app expanded signal, opt out per behavior, or drive it via the returned handle)",
+        "validation of a required form-field value"
       ],
       "variants": [
         "tokens",
         "free text",
         "disabled",
-        "collapsible standalone or toolbar composition"
+        "collapsible standalone or toolbar composition",
+        "visible form-field label, hint, and required marker"
       ],
       "accessibility": [
         "Announce result changes when useful and keep tokens atomic during editing.",
         "Keep leading and trailing controls aligned to the first text line while content wraps. Managed Clear restores replacement focus before the next input task, preserving immediate typing and later focus handoffs without a frame delay.",
         "Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion before the next keystroke. Select All deletion preserves managed open state and replacement focus; persist both edited query and tokens. Visual wrapping remains available.",
-        "In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out."
+        "In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out.",
+        "The form-field presentation associates its visible label and optional hint with the searchbox, exposes aria-required when required, and lets wireTokenSearchFields focus the editor from a label click. The app validates required input."
       ],
       "geometry": {
         "margin": "none",

package/ai/component-composition.json

@@ -703,6 +703,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "per-view fixed header content above the active view's scroll area",
+          "owner": "application",
+          "required": false
+        },
         {
           "id": "top-toolbar configuration, title size, and heading level",
           "owner": "application",
@@ -783,6 +788,7 @@
           "kui-nav-stack__chrome-copy",
           "kui-nav-stack__chrome-copy--bottom",
           "kui-nav-stack__chrome-copy--exiting",
+          "kui-nav-stack__header",
           "kui-nav-stack__viewport",
           "kui-nav-stack__view",
           "kui-nav-stack__view--entering",
@@ -1075,6 +1081,11 @@
         },
         { "id": "collapsed state", "owner": "application", "required": false },
         { "id": "panel sizes", "owner": "application", "required": false },
+        {
+          "id": "navigation panel view stack and push/pop actions when navStack is supplied",
+          "owner": "application",
+          "required": false
+        },
         {
           "id": "responsive replacement below desktop",
           "owner": "application",
@@ -2088,7 +2099,8 @@
       },
       "accessibility": {
         "obligations": [
-          "Grid adds layout only and no grid role; children retain responsibility for native or ARIA semantics.",
+          "Grid adds no role by default; selectionMode=multiple requires ariaLabel and supplies a multi-select grid for ContentItem row/gridcell tiles.",
+          "wireContentItems uses rendered tile positions for Left/Right/Up/Down and reaches the first or last tile with Home/End.",
           "Responsive column-count changes preserve source and focus order."
         ]
       },
@@ -2258,6 +2270,11 @@
           "id": "typed gap, flex, alignment, and divider choices",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "the accessible label and selection state of a multi-select grid",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -2293,7 +2310,7 @@
       },
       "accessibility": {
         "obligations": [
-          "List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.",
+          "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."
         ]
       },
@@ -2746,6 +2763,11 @@
           "id": "whether the item is a programmatic focus target",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "the selection set and Shift/Cmd extension for multi-select rich cards",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -2770,7 +2792,8 @@
         "obligations": [
           "An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role=\"region\").",
           "focusTarget makes the item a programmatic focus target (tabindex=\"-1\", never a tab stop), such as a NavStack view's data-nav-focus target.",
-          "The frame is decorative and never the only signal of state."
+          "The frame is decorative and never the only signal of state.",
+          "selectionMode=\"multiple\" renders a focusable row with aria-selected and a gridcell for nested controls; place it in a labeled List selectionMode=\"multiple\" grid. wireContentItems moves focus among rows with Up/Down and Home/End while nested controls retain those keys. Guard the app's delegated card action with isContentItemActivation so a nested control does not select the row."
         ]
       },
       "cssValueProps": [],
@@ -3243,7 +3266,8 @@
           "Announce result changes when useful and keep tokens atomic during editing.",
           "Keep leading and trailing controls aligned to the first text line while content wraps. Managed Clear restores replacement focus before the next input task, preserving immediate typing and later focus handoffs without a frame delay.",
           "Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion before the next keystroke. Select All deletion preserves managed open state and replacement focus; persist both edited query and tokens. Visual wrapping remains available.",
-          "In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out."
+          "In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out.",
+          "The form-field presentation associates its visible label and optional hint with the searchbox, exposes aria-required when required, and lets wireTokenSearchFields focus the editor from a label click. The app validates required input."
         ]
       },
       "cssValueProps": [],

package/ai/components/content-item.md

@@ -13,6 +13,7 @@ Render one self-contained .kui-content child that owns its 8px inline margin, re
 - An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.
 - A content item marks a real distinction and must read as visibly bounded: pass frame="framed" (the border is always reserved, so geometry does not change).
 - A content item should follow a pill control's 22px radius: pass shape="pill".
+- A selectable rich card needs nested controls: use selectionMode="multiple" inside a labeled List multi-select grid.
 
 **Not when:**
 
@@ -44,6 +45,7 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 - pill item
 - framed pill item
 - named focus-target region
+- multi-select rich grid row
 
 ## Composition
 
@@ -53,7 +55,7 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 
 ## State and wiring
 
-**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; corner shape; region semantics and accessible name; whether the item is a programmatic focus target.
+**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; corner shape; region semantics and accessible name; whether the item is a programmatic focus target; the selection set and Shift/Cmd extension for multi-select rich cards.
 
 No wiring helper.
 
@@ -68,6 +70,7 @@ Margin: self · border: self · padding: self (layout role: structure). `self` m
 - An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role="region").
 - focusTarget makes the item a programmatic focus target (tabindex="-1", never a tab stop), such as a NavStack view's data-nav-focus target.
 - The frame is decorative and never the only signal of state.
+- selectionMode="multiple" renders a focusable row with aria-selected and a gridcell for nested controls; place it in a labeled List selectionMode="multiple" grid. wireContentItems moves focus among rows with Up/Down and Home/End while nested controls retain those keys. Guard the app's delegated card action with isContentItemActivation so a nested control does not select the row.
 
 ## Styling boundary
 

package/ai/components/grid.md

@@ -47,6 +47,7 @@ Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#k
 - boolean, finite-keyword, or typed CssFlex flex
 - fill: the layout root fills a definite-height parent
 - rootAttributes: safe data-\* metadata on the root
+- selectionMode=multiple: labeled multi-select grid for ContentItem tiles
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
@@ -74,7 +75,8 @@ Margin: none · border: none · padding: none (layout role: structure). `self` m
 
 ## Accessibility
 
-- Grid adds layout only and no grid role; children retain responsibility for native or ARIA semantics.
+- Grid adds no role by default; selectionMode=multiple requires ariaLabel and supplies a multi-select grid for ContentItem row/gridcell tiles.
+- wireContentItems uses rendered tile positions for Left/Right/Up/Down and reaches the first or last tile with Home/End.
 - Responsive column-count changes preserve source and focus order.
 
 ## Styling boundary

package/ai/components/list.md

@@ -16,6 +16,7 @@ Standardize vertical component layout, optional physical-side text/control inset
 - 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.
 
 **Not when:**
 
@@ -49,6 +50,7 @@ Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#k
 - fill: the layout root fills a definite-height parent
 - rootAttributes: safe data-\* metadata on the root
 - scroll dividers when named as wireScrollDividers targets chrome
+- multi-select grid for rich ContentItem rows
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
@@ -64,7 +66,7 @@ Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#k
 
 ## State and wiring
 
-**The app owns:** child semantics and content; the bounded height needed for scrolling; typed gap, flex, alignment, and divider choices.
+**The app owns:** 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.
 
 **Wiring:** `wireScrollDividers` is optional.
 
@@ -81,7 +83,7 @@ Margin: none · border: conditional · padding: conditional (layout role: naviga
 
 ## Accessibility
 
-- List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.
+- 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.
 
 ## Styling boundary

package/ai/components/nav-stack.md

@@ -43,6 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 - configured top toolbar
 - custom back icon or visible back text
 - per-view bottom toolbar
+- 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)
@@ -56,7 +57,7 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 
 ## State and wiring
 
-**The app owns:** ordered view stack and stable keys; view content and titles; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar content or a persistent fallback; per-view leading, center, and trailing top-toolbar groups; top-toolbar configuration, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers).
+**The app owns:** ordered view stack and stable keys; view content and titles; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar content or a persistent fallback; per-view leading, center, and trailing top-toolbar groups; per-view fixed header content above the active view's scroll area; top-toolbar configuration, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers).
 
 **Wiring:** `wireNavStack`, `wireScrollDividers` is required.
 
@@ -88,9 +89,9 @@ Margin: none · border: conditional · padding: child (layout role: structure).
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public class hooks (select for layout placement only, never to change the component's look): `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__header`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting`.
 
-Never put `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting` on an element you write; render `NavStack` instead (`KUI-L103`).
+Never put `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__header`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting` on an element you write; render `NavStack` instead (`KUI-L103`).
 
 Public tokens it reads: `--kui-nav-stack-transition-duration`. Set a token only where its public contract allows; prefer a prop.
 

package/ai/components/token-search-field.md

@@ -10,6 +10,7 @@ Token-controlled, optionally collapsible search editor with ordered, editable, r
 
 - Combine DOM-owned free text with ordered editable/removable filter tokens in one searchbox.
 - Enable collapsible mode when an empty, unfocused search should reduce to one iconic action, standalone or inside a toolbar group.
+- Use presentation="form-field" for a structured search query beside Web Awesome form controls, with a visible label, optional hint, and required marker.
 
 **Not when:**
 
@@ -40,6 +41,7 @@ Exact prop names and types: [`@kerfjs/ui/token-search-field`](../public-api-sign
 - free text
 - disabled
 - collapsible standalone or toolbar composition
+- visible form-field label, hint, and required marker
 
 ## Composition
 
@@ -79,6 +81,7 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 - Keep leading and trailing controls aligned to the first text line while content wraps. Managed Clear restores replacement focus before the next input task, preserving immediate typing and later focus handoffs without a frame delay.
 - Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion before the next keystroke. Select All deletion preserves managed open state and replacement focus; persist both edited query and tokens. Visual wrapping remains available.
 - In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out.
+- The form-field presentation associates its visible label and optional hint with the searchbox, exposes aria-required when required, and lets wireTokenSearchFields focus the editor from a label click. The app validates required input.
 
 ## Styling boundary
 

package/ai/components/workbench.md

@@ -25,7 +25,7 @@ Arrange a complex tool or editor as a stable central work area with optional per
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/workbench` — exports `Workbench`, `WorkbenchChromePlacement`, `WorkbenchCompactOverlay`, `WorkbenchMainBottomToolbar`, `WorkbenchMainToolbar`, `WorkbenchPanel`, `WorkbenchPanelResizable`, `WorkbenchPanelToggle`, `WorkbenchPanelToolbar`, `WorkbenchProps`, `WorkbenchResponsiveOverlayAt`.
+- JavaScript: `@kerfjs/ui/workbench` — exports `Workbench`, `WorkbenchChromePlacement`, `WorkbenchCompactOverlay`, `WorkbenchMainBottomToolbar`, `WorkbenchMainToolbar`, `WorkbenchPanel`, `WorkbenchStaticPanel`, `WorkbenchNavigationPanel`, `WorkbenchPanelResizable`, `WorkbenchPanelToggle`, `WorkbenchPanelToolbar`, `WorkbenchProps`, `WorkbenchResponsiveOverlayAt`.
 - CSS: the browser build of `@kerfjs/ui/workbench` pulls its CSS automatically; import `@kerfjs/ui/workbench.css` manually only without the `browser` export condition.
 - Wiring: `wireWorkbench` from `@kerfjs/ui/wire-workbench` (optional).
 - Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
@@ -43,6 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/workbench`](../public-api-signatures-v1
 - bottom drawer
 - all panels
 - independently collapsed panels
+- navigation panel with per-screen toolbar, fixed header, and one scroll owner; standard toggle remains last and relocates while collapsed
 - opt-in drag and keyboard resizable panels with min/max limits
 - resizable rails that leave the work area a minimum width and shrink in proportion when the Workbench narrows
 - rails or a drawer that present as overlays below a narrow or compact Workbench container breakpoint
@@ -60,6 +61,7 @@ Exact prop names and types: [`@kerfjs/ui/workbench`](../public-api-signatures-v1
 - Parents: any.
 - Contexts: `desktop-application-shell`.
 - Children: unrestricted.
+- Built from: [NavStack](./nav-stack.md).
 
 Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
 
@@ -70,7 +72,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 ## State and wiring
 
-**The app owns:** panel presence and content; collapsed state; panel sizes; responsive replacement below desktop; collapse controls and focus policy.
+**The app owns:** panel presence and content; collapsed state; panel sizes; navigation panel view stack and push/pop actions when navStack is supplied; responsive replacement below desktop; collapse controls and focus policy.
 
 **Wiring:** `wireWorkbench`, `wireScrollDividers` is optional.
 
@@ -111,6 +113,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Pane](./pane.md).
+- Components: [NavStack](./nav-stack.md), [Pane](./pane.md).
 - Docs: [`docs/workbench.md`](../../docs/workbench.md), [`docs/workbench.md#state-lives-in-the-app`](../../docs/workbench.md#state-lives-in-the-app).
 - UX catalog route: `?component=workbench`.