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

package/README.md

@@ -38,8 +38,10 @@ Browser verification always builds current source: both `npm run test:e2e`
 and direct focused Playwright commands run the catalog/conformance preflights
 and production build before preview. See the [UX catalog contract](./docs/ux-demo.md).
 Failed Playwright tests retain traces and screenshots alongside an HTML report.
-The CI `ui` job uploads the report and per-test failure evidence for 14 days when
-the browser suite fails; the artifact is named `ui-browser-failure-<run>-<attempt>`.
+CI runs the complete suite in concurrent Chromium, Firefox, and WebKit jobs,
+while the `ui` job checks the package. A failing browser job uploads its report
+and per-test evidence for 14 days as
+`ui-browser-failure-<browser>-<run>-<attempt>`.
 
 When authoring a component gallery, follow the single
 [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
@@ -233,8 +235,8 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `NavStack`                                                          | `@kerfjs/ui/nav-stack`                  | `@kerfjs/ui/nav-stack.css`             |
 | `wireNavStack`                                                      | `@kerfjs/ui/wire-nav-stack`             | —                                      |
 | `SplitView`                                                         | `@kerfjs/ui/split-view`                 | `@kerfjs/ui/split-view.css`            |
-| `TabScaffold`                                                       | `@kerfjs/ui/tab-scaffold`               | `@kerfjs/ui/tab-scaffold.css`          |
-| `wireTabScaffold`                                                   | `@kerfjs/ui/wire-tab-scaffold`          | —                                      |
+| `TabNavigator`                                                      | `@kerfjs/ui/tab-navigator`              | `@kerfjs/ui/tab-navigator.css`         |
+| `wireTabNavigator`                                                  | `@kerfjs/ui/wire-tab-navigator`         | —                                      |
 | `Workbench`                                                         | `@kerfjs/ui/workbench`                  | `@kerfjs/ui/workbench.css`             |
 | `wireWorkbench`                                                     | `@kerfjs/ui/wire-workbench`             | —                                      |
 | `CollapsiblePanel`, `CollapsiblePanelToggle`                        | `@kerfjs/ui/collapsible-panel`          | `@kerfjs/ui/collapsible-panel.css`     |
@@ -263,11 +265,11 @@ Application layouts are separate component subpaths. Browser-condition imports
 include their reachable CSS; use the matching manual CSS export when your
 bundler does not select the browser condition. Add a wire subpath when the
 layout has interactive behavior. The catalog
-entries for `nav-stack`, `split-view`, `tab-scaffold`, `workbench`, and
+entries for `nav-stack`, `split-view`, `tab-navigator`, `workbench`, and
 `collapsible-panel` document their selection rules, ownership boundaries,
 public classes, tokens, and focused demos. See
 [`docs/app-layouts.md`](./docs/app-layouts.md) for the layout decision matrix.
-`NavStack` and `TabScaffold` expose `chromeDividers="scroll" | "always" |
+`NavStack` and `TabNavigator` expose `chromeDividers="scroll" | "always" |
 "none"` for their chrome lines; `SplitView` forwards the setting to its
 compact stack. A sole `Pane` in a view or scene fills it, keeping the Pane's
 header in place while its own content scrolls.

package/ai/application-ui-diagnostic-ids-v1.json

@@ -107,6 +107,7 @@
     "KUI-T011"
   ],
   "retired": {
+    "KUI-C101": "Toolbar zones accept KerfUiContent directly; grouping is a recommended presentation choice, not a composition requirement. Kept in ids so existing profile exceptions still load.",
     "KUI-L005": "Folded into KUI-L019: any application rule whose subject is a cataloged component, forced dimensions included. Kept in ids so existing profile exceptions that name it still load."
   }
 }

package/ai/compile-time-contracts-v1.json

@@ -62,10 +62,10 @@
     },
     {
       "id": "KUI-T008",
-      "publicImport": "@kerfjs/ui/tab-scaffold",
-      "symbols": ["TabScaffoldTab", "TabScaffoldProps"],
+      "publicImport": "@kerfjs/ui/tab-navigator",
+      "symbols": ["TabNavigatorTab", "TabNavigatorProps"],
       "kind": "literal-identity",
-      "summary": "Literal TabScaffold active ids are constrained to the declared tab ids; dynamic integrations may widen the generic to string."
+      "summary": "Literal TabNavigator active ids are constrained to the declared tab ids; dynamic integrations may widen the generic to string."
     },
     {
       "id": "KUI-T009",

package/ai/component-catalog.json

@@ -478,7 +478,7 @@
       "publicExports": [],
       "useWhen": [
         "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."
       ],
       "avoidWhen": [
         "Do not put .kui-app-root on several sibling containers; each requests the full available document height.",
@@ -624,7 +624,8 @@
         "An application column needs shared header, content, and optional footer organization with exactly one scrolling content owner.",
         "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 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."
       ],
       "avoidWhen": [
         "Do not use Pane as a padded card or add a competing scroll owner around its content slot.",
@@ -667,8 +668,9 @@
         "border": "conditional",
         "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."
+        "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."
         ]
       },
       "delivery": {
@@ -712,6 +714,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"
       ],
       "links": {
@@ -745,7 +749,7 @@
       ],
       "avoidWhen": [
         "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": [
         {
@@ -754,9 +758,9 @@
           "when": "Promote a list-to-detail stack to SplitView once both regions fit together."
         },
         {
-          "id": "tab-scaffold",
+          "id": "tab-navigator",
           "relationship": "composes-with",
-          "when": "Use one NavStack as each TabScaffold tab's persistent content."
+          "when": "Use one NavStack as each TabNavigator tab's persistent content."
         }
       ],
       "appOwns": [
@@ -1011,27 +1015,27 @@
       }
     },
     {
-      "id": "tab-scaffold",
-      "name": "TabScaffold",
+      "id": "tab-navigator",
+      "name": "TabNavigator",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A controlled compact-device bottom tab scaffold that keeps every tab scene mounted so its navigation and scroll state survive selection changes.",
+      "description": "A controlled compact-device bottom tab navigator that keeps every destination scene mounted so its navigation and scroll state survive selection changes.",
       "uses": [
         "badge"
       ],
       "purpose": "Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.",
       "publicExports": [
-        "TabScaffoldTab",
-        "TabScaffoldProps",
-        "TabScaffold"
+        "TabNavigatorTab",
+        "TabNavigatorProps",
+        "TabNavigator"
       ],
       "useWhen": [
         "A handset or portrait-tablet app has two to five co-equal top-level destinations.",
         "Each destination must stay mounted so its NavStack and scroll position survive tab switches."
       ],
       "avoidWhen": [
-        "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": [
@@ -1072,22 +1076,22 @@
         "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."
         ]
       },
       "delivery": {
-        "moduleImport": "@kerfjs/ui/tab-scaffold",
-        "browserImport": "@kerfjs/ui/tab-scaffold",
-        "manualCssImport": "@kerfjs/ui/tab-scaffold.css",
+        "moduleImport": "@kerfjs/ui/tab-navigator",
+        "browserImport": "@kerfjs/ui/tab-navigator",
+        "manualCssImport": "@kerfjs/ui/tab-navigator.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [
         {
-          "export": "wireTabScaffold",
-          "import": "@kerfjs/ui/wire-tab-scaffold",
+          "export": "wireTabNavigator",
+          "import": "@kerfjs/ui/wire-tab-navigator",
           "required": true
         },
         {
@@ -1120,8 +1124,8 @@
       ],
       "publicTokens": [],
       "links": {
-        "catalogRoute": "?component=tab-scaffold",
-        "documentation": "docs/tab-scaffold.md",
+        "catalogRoute": "?component=tab-navigator",
+        "documentation": "docs/tab-navigator.md",
         "recipe": "docs/app-layouts.md#decision-matrix"
       }
     },
@@ -4299,6 +4303,11 @@
               "name": "data-empty",
               "on": "the text span inside kui-token-search__editor",
               "meaning": "\"true\" on that span while it holds no text."
+            },
+            {
+              "name": "data-placeholder-visible",
+              "on": "the kui-token-search root",
+              "meaning": "Tracks whether the DOM-owned editor is empty so its placeholder stays outside the editable area."
             }
           ]
         }

package/ai/component-composition-rules.json

@@ -11,38 +11,30 @@
       {
         "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"],
+      "mode": "any",
+      "concepts": [],
       "requiredConcepts": []
-    },
-    "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."
-      }
-    ]
+    }
   },
   "@kerfjs/ui:pane": {
     "_source": "docs/layout.md#anatomy",

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"
         ]
       },
@@ -963,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": [] },
@@ -1007,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",
@@ -1032,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."
           ]
         }
@@ -1427,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 },
         {
@@ -1554,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"
@@ -3499,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
 
@@ -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/{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.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
 
@@ -94,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).