@kerfjs/ui 5.0.0-beta.77 → 5.0.0-beta.79

package/ai/component-composition.json

@@ -642,7 +642,8 @@
           "padding": "child",
           "notes": [
             "The pane is unpadded; separators are independently opt-in on logical edges and default off.",
-            "Safe areas: the root and separators paint through unsafe areas while header, content, and footer pad the sides the pane still reaches (routed by --kui-edge-inset-*); content block insets are scroll padding."
+            "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."
           ]
         }
       },
@@ -670,6 +671,8 @@
           "--kui-pane-separator-color",
           "--kui-pane-separator-width",
           "--kui-pane-chrome-background",
+          "--kui-pane-content-inset-inline-start",
+          "--kui-pane-content-inset-inline-end",
           "--kui-sunken-panel-background"
         ]
       },
@@ -697,7 +700,7 @@
           "required": false
         },
         {
-          "id": "view content and titles",
+          "id": "view content and structured top and bottom toolbar configurations",
           "owner": "application",
           "required": false
         },
@@ -712,7 +715,7 @@
           "required": false
         },
         {
-          "id": "per-view bottom toolbar content or a persistent fallback",
+          "id": "per-view bottom toolbar or a persistent structured fallback",
           "owner": "application",
           "required": false
         },
@@ -722,12 +725,12 @@
           "required": false
         },
         {
-          "id": "per-view fixed header content above the active view's scroll area",
+          "id": "per-view header and footer with List and Pane configuration",
           "owner": "application",
           "required": false
         },
         {
-          "id": "top-toolbar configuration, title size, and heading level",
+          "id": "top-toolbar defaults, title size, and heading level",
           "owner": "application",
           "required": false
         },
@@ -812,7 +815,6 @@
           "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",
@@ -964,10 +966,10 @@
       }
     },
     {
-      "key": "@kerfjs/ui:tab-scaffold",
+      "key": "@kerfjs/ui:tab-navigator",
       "package": "@kerfjs/ui",
-      "id": "tab-scaffold",
-      "name": "TabScaffold",
+      "id": "tab-navigator",
+      "name": "TabNavigator",
       "kind": "component",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -1008,8 +1010,8 @@
       ],
       "wiring": {
         "required": true,
-        "helpers": ["wireTabScaffold", "wireScrollDividers"],
-        "obligations": ["Use wireTabScaffold as documented."],
+        "helpers": ["wireTabNavigator", "wireScrollDividers"],
+        "obligations": ["Use wireTabNavigator as documented."],
         "stateAttributes": [
           {
             "name": "data-scroll-overflow",
@@ -1033,7 +1035,7 @@
           "border": "conditional",
           "padding": "self",
           "notes": [
-            "The scaffold owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.",
+            "The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.",
             "The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border."
           ]
         }
@@ -1428,30 +1430,26 @@
         {
           "id": "leading",
           "jsx": { "prop": "leading" },
-          "accepts": ["toolbar-text", "toolbar-control-group"],
+          "accepts": ["KerfUiContent"],
           "cardinality": { "min": 0, "max": "unbounded" },
           "exclusiveWith": []
         },
         {
           "id": "center",
           "jsx": { "prop": "center" },
-          "accepts": ["toolbar-text", "toolbar-control-group"],
+          "accepts": ["KerfUiContent"],
           "cardinality": { "min": 0, "max": "unbounded" },
           "exclusiveWith": []
         },
         {
           "id": "trailing",
           "jsx": { "prop": "trailing" },
-          "accepts": ["toolbar-text", "toolbar-control-group", "wa-button"],
+          "accepts": ["KerfUiContent"],
           "cardinality": { "min": 0, "max": "unbounded" },
           "exclusiveWith": []
         }
       ],
-      "children": {
-        "mode": "listed",
-        "concepts": ["toolbar-text", "toolbar-control-group", "wa-button"],
-        "requiredConcepts": []
-      },
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
       "state": [
         { "id": "actions", "owner": "application", "required": false },
         {
@@ -1498,6 +1496,18 @@
             "on": "private aria-hidden measurement boxes under Toolbar",
             "helper": "wireToolbarVisibility",
             "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+          },
+          {
+            "name": "data-morph-preserve",
+            "on": "private aria-hidden measurement boxes and visibility state children",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+          },
+          {
+            "name": "data-toolbar-visibility-state",
+            "on": "private hidden children of width-managed items and paired busy statuses",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
           }
         ]
       },
@@ -1543,14 +1553,7 @@
           "--kui-toolbar-zone-padding-inline"
         ]
       },
-      "diagnostics": [
-        {
-          "id": "KUI-C101",
-          "severity": "error",
-          "when": "a direct zone child is neither ToolbarText nor ToolbarControlGroup nor a standalone wa-button in trailing",
-          "message": "Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup, plus one standalone primary wa-button in trailing, are direct zone children."
-        }
-      ],
+      "diagnostics": [],
       "provenance": {
         "selection": "ai/component-catalog.json",
         "composition": "docs/component-selection.md#toolbar-composition"
@@ -1608,6 +1611,18 @@
             "on": "private aria-hidden measurement boxes under Toolbar",
             "helper": "wireToolbarVisibility",
             "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+          },
+          {
+            "name": "data-morph-preserve",
+            "on": "private aria-hidden measurement boxes and visibility state children",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+          },
+          {
+            "name": "data-toolbar-visibility-state",
+            "on": "private hidden children of width-managed items and paired busy statuses",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
           }
         ]
       },
@@ -1742,7 +1757,68 @@
           "Use popup surfaces only for real dropdown menus with named triggers."
         ]
       },
-      "cssValueProps": [],
+      "cssValueProps": [
+        {
+          "path": "preferredWidth",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["preferredWidth={remify(832)}"]
+        },
+        {
+          "path": "viewportGutter",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["viewportGutter={remify(8)}"]
+        },
+        {
+          "path": "maxHeight",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["viewport"],
+          "canonicalShorthands": ["viewport"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["maxHeight=\"viewport\"", "maxHeight={remify(640)}"]
+        }
+      ],
       "boundaries": {
         "rootClass": "kui-dialog-surface",
         "publicClasses": ["kui-dialog-surface", "kui-popup-surface"],
@@ -1862,6 +1938,18 @@
             "on": "private aria-hidden measurement boxes under Toolbar",
             "helper": "wireToolbarVisibility",
             "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+          },
+          {
+            "name": "data-morph-preserve",
+            "on": "private aria-hidden measurement boxes and visibility state children",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+          },
+          {
+            "name": "data-toolbar-visibility-state",
+            "on": "private hidden children of width-managed items and paired busy statuses",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
           }
         ]
       },
@@ -3403,6 +3491,12 @@
             "on": "the text span inside kui-token-search__editor",
             "helper": "wireTokenSearchFields",
             "meaning": "\"true\" on that span while it holds no text."
+          },
+          {
+            "name": "data-placeholder-visible",
+            "on": "the kui-token-search root",
+            "helper": "wireTokenSearchFields",
+            "meaning": "Tracks whether the DOM-owned editor is empty so its placeholder stays outside the editable area."
           }
         ]
       },

package/ai/components/README.md

@@ -21,7 +21,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Pane](./pane.md) — Organize a sidebar, main area, inspector, or dialog column into fixed vertical header/footer chrome around one scrolling content owner.
 - [NavStack](./nav-stack.md) — Present a single linear or drill-down flow while preserving each prior view's state, scroll position, and place in the stack.
 - [SplitView](./split-view.md) — Present a selectable list and its detail together when space permits, with a one-pane drill-down replacement on compact devices.
-- [TabScaffold](./tab-scaffold.md) — Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.
+- [TabNavigator](./tab-navigator.md) — Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.
 - [Workbench](./workbench.md) — Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.
 - [CollapsiblePanel](./collapsible-panel.md) — Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.
 - [SunkenPanel](./sunken-panel.md) — Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.

package/ai/components/document-baseline.md

@@ -11,7 +11,7 @@ Opt-in document-level defaults: border-box sizing, body margin/font/surface, nat
 Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
 
 - An application wants Kerf UI to own document-level box sizing, body typography, native table-cell and form-control font metrics, surface, and link color.
-- A full-height shell (Workbench, SplitView, NavStack, or TabScaffold) mounts into one direct container: put .kui-app-root on that container.
+- A full-height shell (Workbench, SplitView, NavStack, or TabNavigator) mounts into one direct container: put .kui-app-root on that container.
 
 **Not when:**
 

package/ai/components/nav-stack.md

@@ -16,12 +16,12 @@ Present a single linear or drill-down flow while preserving each prior view's st
 **Not when:**
 
 - Do not use NavStack when a list and detail should remain visible together; use SplitView.
-- Do not use it for co-equal top-level destinations on compact devices; wrap one stack per destination in TabScaffold.
+- Do not use it for co-equal top-level destinations on compact devices; wrap one stack per destination in TabNavigator.
 
 **Alternatives:**
 
 - [SplitView](./split-view.md) (roomy-alternative) — Promote a list-to-detail stack to SplitView once both regions fit together.
-- [TabScaffold](./tab-scaffold.md) (composes-with) — Use one NavStack as each TabScaffold tab's persistent content.
+- [TabNavigator](./tab-navigator.md) (composes-with) — Use one NavStack as each TabNavigator tab's persistent content.
 
 ## Imports
 
@@ -57,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; 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).
+**The app owns:** ordered view stack and stable keys; view content and structured top and bottom toolbar configurations; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar or a persistent structured fallback; 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).
 
 **Wiring:** `wireNavStack`, `wireScrollDividers` is required.
 
@@ -90,9 +90,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__header`, `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__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__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`).
+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`).
 
 Public tokens it reads: `--kui-nav-stack-transition-duration`. Set a token only where its public contract allows; prefer a prop.
 
@@ -100,6 +100,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [SplitView](./split-view.md), [TabScaffold](./tab-scaffold.md).
+- Components: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [SplitView](./split-view.md), [TabNavigator](./tab-navigator.md).
 - Docs: [`docs/nav-stack.md`](../../docs/nav-stack.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
 - UX catalog route: `?component=nav-stack`.

package/ai/components/pane.md

@@ -14,6 +14,7 @@ Organize a sidebar, main area, inspector, or dialog column into fixed vertical h
 - A pane boundary needs an opt-in separator on any combination of logical sides.
 - 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.
 
 **Not when:**
 
@@ -76,6 +77,7 @@ Margin: child · border: conditional · padding: child (layout role: structure).
 
 - The pane is unpadded; separators are independently opt-in on logical edges and default off.
 - Safe areas: the root and separators paint through unsafe areas while header, content, and footer pad the sides the pane still reaches (routed by --kui-edge-inset-\*); content block insets are scroll padding.
+- The scrolling content exposes its resolved logical inline padding to descendants as --kui-pane-content-inset-inline-start/end, including safe areas and deepInset.
 
 ## Accessibility
 
@@ -90,7 +92,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-pane`, `kui-pane__content`, `kui-pane__footer`, `kui-pane__header`, `kui-pane__toolbar` on an element you write; render `Pane` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-edge-inset-block-end`, `--kui-edge-inset-block-start`, `--kui-edge-inset-inline-end`, `--kui-edge-inset-inline-start`, `--kui-pane-separator-color`, `--kui-pane-separator-width`, `--kui-pane-chrome-background`, `--kui-sunken-panel-background`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-edge-inset-block-end`, `--kui-edge-inset-block-start`, `--kui-edge-inset-inline-end`, `--kui-edge-inset-inline-start`, `--kui-pane-separator-color`, `--kui-pane-separator-width`, `--kui-pane-chrome-background`, `--kui-pane-content-inset-inline-start`, `--kui-pane-content-inset-inline-end`, `--kui-sunken-panel-background`. Set a token only where its public contract allows; prefer a prop.
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 

package/ai/components/surface-scaffold.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:surface-scaffold` · Kerf UI · component · Structure
 
-Typed Web Awesome dialog and popup surface sizing, presentation, and inset composition.
+Typed Web Awesome dialog preferred widths and viewport bounds, presentation, and popup inset composition.
 
 ## When to use
 
@@ -12,6 +12,7 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 
 - 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.
 
 **Not when:**
 
@@ -22,7 +23,8 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 
 - JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `PopupSurface`.
 - CSS: the browser build of `@kerfjs/ui/surface-scaffold` pulls its CSS automatically; import `@kerfjs/ui/surface-scaffold.css` manually only without the `browser` export condition.
-- Declared side effects: browser-condition-css.
+- Registration: import `@kerfjs/ui/surface-scaffold/register` once (a side effect).
+- Declared side effects: browser-condition-css, custom-element-registration.
 
 ## Props
 
@@ -32,9 +34,16 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 
 - small, medium, or large dialog
 - modal, side-sheet, or fullscreen dialog
+- typed modal preferred width, viewport gutter, and maximum height, including viewport cap
 - none, compact, or comfortable body and footer inset
 - standard, compact, or zero-inset popup menu
 
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `preferredWidth`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `preferredWidth={remify(832)}`
+- `viewportGutter`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `viewportGutter={remify(8)}`
+- `maxHeight`: length grammar; raw values: forbid; shorthands `viewport`; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `maxHeight="viewport"`
+
 ## Composition
 
 - Parents: any.

package/ai/components/{tab-scaffold.md → tab-navigator.md}

@@ -1,10 +1,10 @@
-# TabScaffold
+# TabNavigator
 
 <!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
 
-`@kerfjs/ui:tab-scaffold` · Kerf UI · component · Structure
+`@kerfjs/ui:tab-navigator` · Kerf UI · component · Structure
 
-A controlled compact-device bottom tab scaffold that keeps every tab scene mounted so its navigation and scroll state survive selection changes.
+A controlled compact-device bottom tab navigator that keeps every destination scene mounted so its navigation and scroll state survive selection changes.
 
 ## When to use
 
@@ -15,7 +15,7 @@ Switch among two to five co-equal top-level destinations on compact devices whil
 
 **Not when:**
 
-- Do not use TabScaffold for document tabs or reorderable work items; use TabBar.
+- Do not use TabNavigator for document tabs or reorderable work items; use TabBar.
 - Do not retain the bottom bar on desktop when the same destinations should be promoted to a Workbench rail or sidebar.
 
 **Alternatives:**
@@ -25,15 +25,15 @@ Switch among two to five co-equal top-level destinations on compact devices whil
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/tab-scaffold` — exports `TabScaffoldTab`, `TabScaffoldProps`, `TabScaffold`.
-- CSS: the browser build of `@kerfjs/ui/tab-scaffold` pulls its CSS automatically; import `@kerfjs/ui/tab-scaffold.css` manually only without the `browser` export condition.
-- Wiring: `wireTabScaffold` from `@kerfjs/ui/wire-tab-scaffold` (required).
+- JavaScript: `@kerfjs/ui/tab-navigator` — exports `TabNavigatorTab`, `TabNavigatorProps`, `TabNavigator`.
+- CSS: the browser build of `@kerfjs/ui/tab-navigator` pulls its CSS automatically; import `@kerfjs/ui/tab-navigator.css` manually only without the `browser` export condition.
+- Wiring: `wireTabNavigator` from `@kerfjs/ui/wire-tab-navigator` (required).
 - Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/tab-scaffold`](../public-api-signatures-v1.md#kerfjsuitab-scaffold), [`@kerfjs/ui/wire-tab-scaffold`](../public-api-signatures-v1.md#kerfjsuiwire-tab-scaffold), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signatures-v1.md#kerfjsuitab-navigator), [`@kerfjs/ui/wire-tab-navigator`](../public-api-signatures-v1.md#kerfjsuiwire-tab-navigator), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -55,9 +55,9 @@ Exact prop names and types: [`@kerfjs/ui/tab-scaffold`](../public-api-signatures
 
 **The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers).
 
-**Wiring:** `wireTabScaffold`, `wireScrollDividers` is required.
+**Wiring:** `wireTabNavigator`, `wireScrollDividers` is required.
 
-- Use wireTabScaffold as documented.
+- Use wireTabNavigator as documented.
 
 **Wiring-owned state attributes** — never render, remove, or branch on these as app state:
 
@@ -68,7 +68,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-scaffold`](../public-api-signatures
 
 Margin: none · border: conditional · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- The scaffold owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.
+- The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.
 - The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border.
 
 ## Accessibility
@@ -83,12 +83,12 @@ The component owns its own styles. Configure it through its props and variants;
 
 Public class hooks (select for layout placement only, never to change the component's look): `kui-tab-scaffold`, `kui-tab-scaffold__scenes`, `kui-tab-scaffold__scene`, `kui-tab-scaffold__bar`, `kui-tab-scaffold__tab`, `kui-tab-scaffold__tab-icon`, `kui-tab-scaffold__tab-badge`, `kui-tab-scaffold__tab-label`.
 
-Never put `kui-tab-scaffold`, `kui-tab-scaffold__scenes`, `kui-tab-scaffold__scene`, `kui-tab-scaffold__bar`, `kui-tab-scaffold__tab`, `kui-tab-scaffold__tab-icon`, `kui-tab-scaffold__tab-badge`, `kui-tab-scaffold__tab-label` on an element you write; render `TabScaffold` instead (`KUI-L103`).
+Never put `kui-tab-scaffold`, `kui-tab-scaffold__scenes`, `kui-tab-scaffold__scene`, `kui-tab-scaffold__bar`, `kui-tab-scaffold__tab`, `kui-tab-scaffold__tab-icon`, `kui-tab-scaffold__tab-badge`, `kui-tab-scaffold__tab-label` on an element you write; render `TabNavigator` instead (`KUI-L103`).
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 
 ## Related
 
 - Components: [Badge](./badge.md), [AppTab](./tabs.md), [Workbench](./workbench.md).
-- Docs: [`docs/tab-scaffold.md`](../../docs/tab-scaffold.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
-- UX catalog route: `?component=tab-scaffold`.
+- Docs: [`docs/tab-navigator.md`](../../docs/tab-navigator.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
+- UX catalog route: `?component=tab-navigator`.

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

@@ -70,6 +70,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 - `data-token-search-text` on `the text span inside kui-token-search__editor` (`wireTokenSearchFields`): Marks the plain-text span the helper inserts when the editor is emptied.
 - `data-empty` on `the text span inside kui-token-search__editor` (`wireTokenSearchFields`): "true" on that span while it holds no text.
+- `data-placeholder-visible` on `the kui-token-search root` (`wireTokenSearchFields`): Tracks whether the DOM-owned editor is empty so its placeholder stays outside the editable area.
 
 ## Geometry
 

package/ai/components/toolbar-control-group.md

@@ -88,6 +88,8 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 - `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
 - `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
+- `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.
+- `data-toolbar-visibility-state` on `private hidden children of width-managed items and paired busy statuses` (`wireToolbarVisibility`): Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback.
 
 ## Geometry
 

package/ai/components/toolbar-text.md

@@ -67,6 +67,8 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures
 
 - `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
 - `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
+- `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.
+- `data-toolbar-visibility-state` on `private hidden children of width-managed items and paired busy statuses` (`wireToolbarVisibility`): Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback.
 
 ## Geometry
 

package/ai/components/toolbar.md

@@ -47,14 +47,14 @@ Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.m
 
 - Parents: any.
 - Contexts: `application-chrome`, `page-header`, `panel-header`, `dialog-header`.
-- Children: only [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
+- Children: unrestricted.
 - Built from: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [PopupMenu](./popup-menu.md).
 
 Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
 
-- `leading` — JSX prop `leading`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md); any number.
-- `center` — JSX prop `center`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md); any number.
-- `trailing` — JSX prop `trailing`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md); any number.
+- `leading` — JSX prop `leading`; accepts `KerfUiContent`; any number.
+- `center` — JSX prop `center`; accepts `KerfUiContent`; any number.
+- `trailing` — JSX prop `trailing`; accepts `KerfUiContent`; any number.
 
 ## State and wiring
 
@@ -68,6 +68,8 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 - `data-scroll-divider` on `a Toolbar named as targets chrome` (`wireScrollDividers`): 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.
 - `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
 - `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
+- `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.
+- `data-toolbar-visibility-state` on `private hidden children of width-managed items and paired busy statuses` (`wireToolbarVisibility`): Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback.
 
 ## Geometry
 
@@ -92,10 +94,6 @@ Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-font-sans`,
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 
-## Diagnostics
-
-- `KUI-C101` (error) when a direct zone child is neither ToolbarText nor ToolbarControlGroup nor a standalone wa-button in trailing: Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup, plus one standalone primary wa-button in trailing, are direct zone children.
-
 ## Related
 
 - Components: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [PopupMenu](./popup-menu.md).