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

package/README.md

@@ -37,6 +37,9 @@ 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.
+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>`.
 
 When authoring a component gallery, follow the single
 [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)

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",

package/ai/component-catalog.json

@@ -761,13 +761,13 @@
       ],
       "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 +859,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",
@@ -1615,6 +1614,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 +1756,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 +1874,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 +1887,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 +1905,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 +1921,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 +1941,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 +2201,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."
             }
           ]
         }

package/ai/component-composition.json

@@ -697,7 +697,7 @@
           "required": false
         },
         {
-          "id": "view content and titles",
+          "id": "view content and structured top and bottom toolbar configurations",
           "owner": "application",
           "required": false
         },
@@ -712,7 +712,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 +722,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 +812,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",
@@ -1498,6 +1497,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."
           }
         ]
       },
@@ -1608,6 +1619,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 +1765,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 +1946,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."
           }
         ]
       },

package/ai/components/nav-stack.md

@@ -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.
 

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/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

@@ -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