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

package/README.md

@@ -37,6 +37,11 @@ back to the root or component-local support code placed in the wrong folder.
 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.
+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)
@@ -230,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`     |
@@ -260,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

@@ -29,6 +29,9 @@
     "KUI-D010",
     "KUI-D011",
     "KUI-D020",
+    "KUI-D030",
+    "KUI-D031",
+    "KUI-D032",
     "KUI-L001",
     "KUI-L002",
     "KUI-L003",
@@ -104,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,20 +758,20 @@
           "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": [
         "ordered view stack and stable keys",
-        "view content and titles",
+        "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 content or a persistent fallback",
+        "per-view bottom toolbar or a persistent structured 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",
+        "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)"
       ],
       "variants": [
@@ -859,7 +863,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",
@@ -1012,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": [
@@ -1073,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
         },
         {
@@ -1121,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"
       }
     },
@@ -1615,6 +1618,16 @@
               "name": "data-toolbar-visibility-probe",
               "on": "private aria-hidden measurement boxes under Toolbar",
               "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",
+              "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",
+              "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
             }
           ]
         }
@@ -1747,6 +1760,16 @@
               "name": "data-toolbar-visibility-probe",
               "on": "private aria-hidden measurement boxes under Toolbar",
               "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",
+              "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",
+              "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
             }
           ]
         }
@@ -1855,7 +1878,7 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Typed Web Awesome dialog and popup surface sizing, presentation, and inset composition.",
+      "description": "Typed Web Awesome dialog preferred widths and viewport bounds, presentation, and popup inset composition.",
       "uses": [
         "wa-dialog",
         "wa-dropdown",
@@ -1868,7 +1891,8 @@
       ],
       "useWhen": [
         "A Web Awesome dialog or dropdown needs a standard size, presentation, body/footer inset, or list-compatible menu inset.",
-        "A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText."
+        "A 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."
       ],
       "avoidWhen": [
         "Do not use it as a generic layout wrapper or to replace application-owned modal state and focus lifecycle.",
@@ -1885,6 +1909,7 @@
       "variants": [
         "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"
       ],
@@ -1900,8 +1925,10 @@
       "delivery": {
         "browserImport": "@kerfjs/ui/surface-scaffold",
         "manualCssImport": "@kerfjs/ui/surface-scaffold.css",
+        "registrationImport": "@kerfjs/ui/surface-scaffold/register",
         "sideEffects": [
-          "browser-condition-css"
+          "browser-condition-css",
+          "custom-element-registration"
         ]
       },
       "wiring": [],
@@ -1918,7 +1945,86 @@
         "catalogRoute": "?component=surface-scaffold",
         "documentation": "docs/surface-scaffold.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
-      }
+      },
+      "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)}"
+          ]
+        }
+      ]
     },
     {
       "id": "floating-toolbar",
@@ -2099,6 +2205,16 @@
               "name": "data-toolbar-visibility-probe",
               "on": "private aria-hidden measurement boxes under Toolbar",
               "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",
+              "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",
+              "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
             }
           ]
         }
@@ -4187,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",