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

package/docs/recipes.md

@@ -88,7 +88,11 @@ its label still names the modal — and the close button uses
 `data-dialog="close"`. Web Awesome keeps modal focus and Escape, and the thin
 recipe adapter restores the invoking control after the hide event.
 `DialogSurface` chooses the large modal with no body inset, because the panes
-own their geometry. On compact devices the dialog becomes a full-screen sheet
+own their geometry. Its explicit 16px `viewportGutter` and `maxHeight="viewport"`
+bound the roomy modal to the dynamic viewport; the compact fullscreen
+presentation retains its existing geometry. Application render state chooses
+the presentation and can likewise choose gutter/cap values for a compact modal.
+On compact devices the dialog becomes a full-screen sheet
 with its own labeled header and footer actions, and `SplitView` becomes a
 `NavStack` drill-down whose back control the application pops. The
 application owns open state, selection, the pushed detail, dismissal policy,

package/docs/split-view.md

@@ -86,15 +86,18 @@ resizable={{
 
 `compactStack` configures the compact `NavStack`: `toolbarConfig`, `backIcon`,
 `backText`, `hideToolbar`, the persistent `bottomToolbar`, and `chromeDividers`
-forward to the stack, and `list` / `detail` give each view its own top-toolbar groups
-(`leading`, `center`, trailing `toolbar`) and `bottomToolbar`:
+forward to the stack, and `list` / `detail` give each view its own structured
+top `toolbar` (`leading`, `center`, `trailing`) and `bottomToolbar`:
 
 ```tsx
 compactStack={{
   backText: "Threads",
   toolbarConfig: { headingLevel: 1 },
-  list: { toolbar: <ComposeGroup /> },
-  detail: { toolbar: <ReplyGroup />, bottomToolbar: <MessageActions /> },
+  list: { toolbar: { trailing: <ComposeGroup /> } },
+  detail: {
+    toolbar: { trailing: <ReplyGroup /> },
+    bottomToolbar: { label: "Message actions", leading: <MessageActions /> },
+  },
 }}
 ```
 

package/docs/surface-scaffold.md

@@ -12,6 +12,50 @@ Wrap one `wa-dialog` with `DialogSurface`. Choose `size` (`small`, `medium`, or
 `bodyInset` / `footerInset` (`none`, `compact`, or `comfortable`). The defaults
 match Kerf's medium modal, 8px body, and 16px footer rhythm.
 
+The modal size presets have preferred widths of 400px, 560px, and 800px,
+respectively, before the viewport width cap. Set `preferredWidth` to a branded
+`CssLength` when the desktop shell needs another width. It takes precedence over
+`size`, while the viewport cap still applies. For example, 832px and 480px
+desktop preferences can share the same responsive dialog without changing its
+resource tracks or preview aspect sizing.
+
+### Modal viewport bounds
+
+`viewportGutter` accepts a branded `CssLength` from `@kerfjs/ui/css-values`.
+It sets the minimum horizontal clearance; `preferredWidth` overrides the `size`
+preset when supplied. `maxHeight` accepts a branded length or `"viewport"`; explicit caps are
+clamped to the dynamic viewport height minus twice the gutter (16px per edge
+when the gutter is omitted). Negative gutters/caps clamp to zero. Omitting
+both options preserves Web Awesome's existing width and phone height caps.
+These options apply only to `presentation="modal"`; side sheets and fullscreen
+surfaces keep their own geometry.
+
+```tsx
+import '@kerfjs/ui/surface-scaffold/register';
+import { remify } from '@kerfjs/ui/css-values';
+import { DialogSurface } from '@kerfjs/ui/surface-scaffold';
+
+<DialogSurface preferredWidth={remify(832)} viewportGutter={remify(8)} maxHeight="viewport" bodyInset="none">
+  <wa-dialog label="Close workspace">{/* Application-owned content and footer */}</wa-dialog>
+</DialogSurface>;
+```
+
+This gives a desktop modal an 832px preferred width and a phone modal an 8px edge gutter with a `calc(100dvh - 16px)` height
+cap without application selectors on Kerf roots or Web Awesome parts. A cap
+is not a fixed height: short content stays naturally sized, and taller content
+scrolls in Web Awesome's body while its header/footer remain outside that
+scroll owner. Choosing a larger cap cannot guarantee that arbitrary content
+fits without scrolling; preview tracks, canvas aspect ratios and content sizing
+remain application-owned.
+
+Responsive policy is explicit application state: read `deviceClass()` during
+the render to choose the gutter, cap or presentation. For example use
+`viewportGutter={remify(device.value.handset ? 8 : 16)}` with `maxHeight="viewport"`.
+The scaffold introduces no hidden breakpoint or automatic fullscreen switch.
+An application can configure device-class breakpoints when its phone policy
+differs from the default. Prefer a typed cap such as `maxHeight={remify(640)}`
+when the modal should stop growing before the viewport bound.
+
 Treat a dialog body as a `List` by default. When its rows or sections own their
 standard list geometry, set `bodyInset="none"` so the dialog does not add a
 second inset. Bare prose is still a list child: wrap it in `ListInsetText` so its
@@ -26,3 +70,5 @@ padding for a child that already owns row insets, `compact` uses 4px, and
 preserve `data-morph-skip-children` when its upgraded light-DOM items must retain
 identity across Kerf rerenders. Import `@kerfjs/ui/popup-menu/register` once for
 the focus handoff fix when wrapping a raw `wa-dropdown`.
+
+Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.

package/docs/tab-scaffold.md

@@ -59,6 +59,63 @@ truncate horizontally with an ellipsis when a destination name exceeds its
 share of the bar. On larger device classes, promote the tab set to a
 `Workbench` rail or a persistent sidebar instead of a bottom bar.
 
+Set `deepInset: true` on a plain tab scene to add an 8px outer inline gutter
+to its scrolling content, giving ordinary content items a 16px edge inset.
+The default is `false`. A scene whose only child is a `Pane` or layout lets
+that child own its content gutter: for a nested `NavStack`, set
+`pane: { deepInset: true }` on its views instead. The scaffold bar and a
+stack's top toolbar remain full width.
+
+## A NavStack with a top toolbar and Pane
+
+Put the `NavStack` directly in a tab's `content`. Give each view a structured
+`toolbar` and `pane` configuration. Leave `bottomToolbar` off both the views
+and the stack: the scaffold's tab bar is the only bottom chrome. The view's
+Pane owns scrolling, while the stack keeps its toolbar above it and the
+scaffold keeps the tab bar below it.
+
+```tsx
+import { List } from "@kerfjs/ui/list";
+import { ListItem } from "@kerfjs/ui/list-item";
+import { NavStack, type NavStackView } from "@kerfjs/ui/nav-stack";
+
+const projectViews: NavStackView[] = [
+  {
+    key: "projects",
+    toolbar: { title: "Projects" },
+    pane: { appearance: "sunken" },
+    content: <List><ListItem label="Project Atlas" /></List>,
+  },
+];
+
+<TabScaffold
+  id="app"
+  label="Sections"
+  active={active.value}
+  tabs={[
+    {
+      id: "projects",
+      label: "Projects",
+      content: (
+        <NavStack
+          id="projects-stack"
+          label="Projects navigation"
+          views={projectViews}
+        />
+      ),
+    },
+    { id: "search", label: "Search", content: <SearchScene /> },
+  ]}
+/>;
+```
+
+The app owns each stack's view array and the scaffold's active tab. Call
+`wireTabScaffold` for tab selection and `wireNavStack` for back navigation
+and transitions, each on its own component root. Push a detail by appending
+a view with its own `toolbar` and `pane`; switching tabs keeps that view
+mounted. The catalog's **NavStack inside a tab** example demonstrates the
+push, tab switch, and return flow.
+
 Set a tab's `appearance: "sunken"` when its scene owns scrolling and should
 paint the lowered surface behind short or long content. For a scene whose
 only child is a `Pane` or `NavStack`, set appearance on that child's scroll

package/docs/ui-doctor.md

@@ -58,6 +58,29 @@ without that marker remain app-owned.
 The analyzer resolves a cataloged application component imported through an
 exact or wildcard TypeScript `paths` alias from the nearest consumer tsconfig,
 so the same root hook-class check applies in those files.
+
+## Component style naming
+
+The analyzer stage also checks colocated JSX/TSX components and stylesheets.
+When a stylesheet has a same-basename component module, or exactly one
+component module imports it, Doctor checks that the stylesheet filename is
+the component's kebab-case name (`KUI-D031`). A component that renders its own
+HTML element must put that kebab-case class on rendered markup (`KUI-D030`).
+For example, `WorkspaceHeader` pairs with `workspace-header.css` and renders
+`.workspace-header`. Thin components that only compose other components need
+no root class. Shared stylesheets declared in `ownershipGroups` are exempt
+from the naming check.
+
+Doctor reports `KUI-D032` when a paired stylesheet selects another local
+component's kebab-case class or its BEM descendants or modifiers. Move that
+rule to the owning component's stylesheet or use the component's public
+configuration. This check uses source declarations and CSS selectors; it does
+not execute component code. In changed mode, it reads other component sources
+to resolve ownership but reports only pairs containing a selected path. For
+broader cross-component ownership, including
+cataloged package components and hook classes, enable `ownership: "component"`
+with `implicitComponentOwnership: true` as described above.
+
 Set `"ownership": "component"` in `.kerf-ui-doctor.json` to enforce the same
 boundary between a consumer package's own cataloged components. The default is
 `"package"`. Selection-only entries participate too. A component owns its

package/docs/workbench.md

@@ -167,8 +167,9 @@ into `.kui-resizable-region__content`.
 
 A panel with `navStack` hosts a controlled `NavStack` in place of the static
 `content` and `Pane` slots. Give it a `toolbar` with a `toggle`; each
-`navStack.views` entry then supplies its own title, leading/center/trailing
-groups, fixed `header`, and scrolling `content`. The active view's toolbar is
+`navStack.views` entry then supplies its own structured `toolbar` with a title
+and leading/center/trailing groups, optional `header` / `footer` and `pane`
+configuration, and scrolling `content`. The active view's toolbar is
 the panel's only toolbar row, with the standard toggle always last. On
 collapse, marked groups from the active view and the toggle relocate to the
 work-area toolbar; the view stack stays mounted. The app owns the view array

package/doctor/component-style-checks.mjs

@@ -0,0 +1,224 @@
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, extname, relative, resolve } from 'node:path';
+
+import postcss from 'postcss';
+import ts from 'typescript';
+
+import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
+
+const scriptExtensions = new Set(['.tsx', '.jsx']);
+const kebab = (name) =>
+  name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+const componentName = (name) => /^[A-Z][A-Za-z0-9]*$/.test(name);
+const classNames = (value) =>
+  [...value.matchAll(/(?:^|\s)([a-z][a-z0-9_-]*)(?=\s|$)/g)].map(
+    (match) => match[1],
+  );
+const block = (name) => name.split(/__|--/)[0];
+
+function componentFacts(file, source) {
+  const syntax = file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.JSX;
+  const ast = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    syntax,
+  );
+  const components = new Map();
+  const visit = (node, owner) => {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name &&
+      componentName(node.name.text)
+    )
+      owner = node.name.text;
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      componentName(node.name.text)
+    )
+      owner = node.name.text;
+    if (
+      owner &&
+      (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node))
+    ) {
+      if (ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)) {
+        if (components.has(owner)) components.get(owner).intrinsic = true;
+        for (const attribute of node.attributes.properties) {
+          if (
+            !ts.isJsxAttribute(attribute) ||
+            !['class', 'className'].includes(attribute.name.text)
+          )
+            continue;
+          const value = attribute.initializer;
+          const literal =
+            value && ts.isStringLiteral(value)
+              ? value.text
+              : value &&
+                  ts.isJsxExpression(value) &&
+                  value.expression &&
+                  (ts.isStringLiteral(value.expression) ||
+                    ts.isNoSubstitutionTemplateLiteral(value.expression))
+                ? value.expression.text
+                : undefined;
+          if (literal)
+            for (const name of classNames(literal))
+              components.get(owner)?.add(name);
+        }
+      }
+    }
+    ts.forEachChild(node, (child) => visit(child, owner));
+  };
+  const declarations = (node) => {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name &&
+      componentName(node.name.text)
+    )
+      components.set(node.name.text, new Set());
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      componentName(node.name.text)
+    )
+      components.set(node.name.text, new Set());
+    ts.forEachChild(node, declarations);
+  };
+  declarations(ast);
+  visit(ast);
+  return components;
+}
+
+function diagnostic(id, file, line, message, action) {
+  return {
+    id,
+    severity: 'error',
+    stage: 'analyzer',
+    message,
+    location: { file, line, column: 1 },
+    action,
+    documentation: '@kerfjs/ui/docs/ui-doctor.md#component-style-naming',
+  };
+}
+
+export async function checkComponentStyles(
+  packageRoot,
+  inputs,
+  ownershipGroups = [],
+  selectedPaths,
+) {
+  const scripts = new Map();
+  const styles = new Map();
+  const importedBy = new Map();
+  for (const file of inputs) {
+    if (isUiTraversalExcluded(packageRoot, file)) continue;
+    const extension = extname(file);
+    if (scriptExtensions.has(extension)) {
+      const source = await readFile(file, 'utf8');
+      scripts.set(file, componentFacts(file, source));
+      for (const match of source.matchAll(
+        /\bimport\s*(?:['"]|[^;]*?\bfrom\s*['"])(\.[^'"]+\.css)['"]/g,
+      )) {
+        const style = resolve(dirname(file), match[1]);
+        const importers = importedBy.get(style) ?? [];
+        importers.push(file);
+        importedBy.set(style, importers);
+      }
+    } else if (extension === '.css')
+      styles.set(file, await readFile(file, 'utf8'));
+  }
+  const owners = new Map();
+  for (const [file, components] of scripts)
+    for (const [name, classes] of components)
+      if (classes.has(kebab(name)))
+        owners.set(kebab(name), { file, name, classes });
+  const diagnostics = [];
+  for (const [file, source] of styles) {
+    if (
+      ownershipGroups.some((group) =>
+        group.styleSources?.some(
+          (style) => resolve(packageRoot, style) === file,
+        ),
+      )
+    )
+      continue;
+    const stem = basename(file, '.css');
+    const pair =
+      [...scriptExtensions]
+        .map((extension) => resolve(dirname(file), `${stem}${extension}`))
+        .find((candidate) => scripts.has(candidate)) ??
+      (importedBy.get(file)?.length === 1
+        ? importedBy.get(file)[0]
+        : undefined);
+    if (!pair) continue;
+    const path = relative(packageRoot, file).replaceAll('\\', '/');
+    if (
+      selectedPaths?.length &&
+      !selectedPaths.includes(path) &&
+      !selectedPaths.includes(relative(packageRoot, pair).replaceAll('\\', '/'))
+    )
+      continue;
+    const components = scripts.get(pair);
+    const matching = [...components].find(([name]) => kebab(name) === stem);
+    if (!matching) {
+      const names = [...components.keys()];
+      if (names.length)
+        diagnostics.push(
+          diagnostic(
+            'KUI-D031',
+            path,
+            1,
+            `${basename(file)} is paired with ${basename(pair)}, but its component ${names[0]} calls for ${kebab(names[0])}.css.`,
+            `Rename the stylesheet and its import to ${kebab(names[0])}.css, or rename the component and source pair.`,
+          ),
+        );
+      continue;
+    }
+    const [name, renderedClasses] = matching;
+    if (renderedClasses.intrinsic && !renderedClasses.has(stem))
+      diagnostics.push(
+        diagnostic(
+          'KUI-D030',
+          relative(packageRoot, pair).replaceAll('\\', '/'),
+          1,
+          `${name} must render its own .${stem} root class.`,
+          `Add class="${stem}" to an element rendered by ${name}, then select that class in ${basename(file)}.`,
+        ),
+      );
+    let sheet;
+    try {
+      sheet = postcss.parse(source, { from: file });
+    } catch {
+      continue;
+    }
+    sheet.walkRules((rule) => {
+      if (
+        rule.parent?.type === 'atrule' &&
+        /keyframes$/i.test(rule.parent.name)
+      )
+        return;
+      const selected = [
+        ...new Set(
+          [...rule.selector.matchAll(/\.([a-z][a-z0-9_-]*)/gi)].map(
+            (match) => match[1],
+          ),
+        ),
+      ];
+      for (const className of selected) {
+        const foreign = owners.get(block(className));
+        if (!foreign || foreign.name === name) continue;
+        diagnostics.push(
+          diagnostic(
+            'KUI-D032',
+            path,
+            rule.source?.start?.line ?? 1,
+            `${basename(file)} selects .${className}, which belongs to ${foreign.name} in ${relative(packageRoot, foreign.file).replaceAll('\\', '/')}.`,
+            `Move this rule to ${kebab(foreign.name)}.css or configure ${foreign.name} through its public API.`,
+          ),
+        );
+      }
+    });
+  }
+  return diagnostics;
+}

package/doctor/index.mjs

@@ -27,6 +27,7 @@ import {
   UI_ANALYSIS_RULES,
 } from '../analyzer/index.mjs';
 import { evaluateUi, UI_EVALUATION_RULES } from '../evaluator/index.mjs';
+import { checkComponentStyles } from './component-style-checks.mjs';
 import {
   isForeignRuleDefinitionDiagnostic,
   projectConsumerCoreConfig,
@@ -53,6 +54,18 @@ export const UI_DOCTOR_RULES = Object.freeze({
     severity: 'error',
     title: 'Local component catalog is stale or invalid',
   },
+  'KUI-D030': {
+    severity: 'error',
+    title: 'Component root class does not match its name',
+  },
+  'KUI-D031': {
+    severity: 'error',
+    title: 'Component stylesheet does not match its name',
+  },
+  'KUI-D032': {
+    severity: 'error',
+    title: 'Stylesheet selects another component class',
+  },
 });
 
 const sourceExtensions = new Set([
@@ -480,7 +493,7 @@ async function installedPackageVersion(root, name) {
 }
 
 async function cacheKey(root, packageRoot, mode, paths, config) {
-  const files = await collectInputs(packageRoot, paths);
+  const files = await collectInputs(packageRoot);
   for (const directory of new Set([root, packageRoot])) {
     for (const name of [
       'package.json',
@@ -521,6 +534,14 @@ async function cacheKey(root, packageRoot, mode, paths, config) {
       }),
     )
     .update(await readFile(fileURLToPath(import.meta.url)));
+  hash.update(
+    await readFile(
+      resolve(
+        dirname(fileURLToPath(import.meta.url)),
+        'component-style-checks.mjs',
+      ),
+    ),
+  );
   for (const file of files)
     hash.update(portablePath(root, file)).update(await readFile(file));
   return hash.digest('hex');
@@ -1215,18 +1236,26 @@ export async function runUiDoctor({
                 signal,
               })
             : (async () => ({
-                diagnostics: normalizeAnalyzer(
-                  await analyzeUiProject({
-                    root: packageRoot,
-                    paths: selectedPaths,
-                    ownership: config.ownership ?? 'package',
-                    ownershipContext: config.ownershipContext ?? 'subject',
-                    implicitComponentOwnership:
-                      config.implicitComponentOwnership ?? false,
-                    ownershipGroups: config.ownershipGroups ?? [],
-                    knownRules: [...registeredRuleIds, ...eslintRuleIds],
-                  }),
-                ),
+                diagnostics: [
+                  ...normalizeAnalyzer(
+                    await analyzeUiProject({
+                      root: packageRoot,
+                      paths: selectedPaths,
+                      ownership: config.ownership ?? 'package',
+                      ownershipContext: config.ownershipContext ?? 'subject',
+                      implicitComponentOwnership:
+                        config.implicitComponentOwnership ?? false,
+                      ownershipGroups: config.ownershipGroups ?? [],
+                      knownRules: [...registeredRuleIds, ...eslintRuleIds],
+                    }),
+                  ),
+                  ...(await checkComponentStyles(
+                    packageRoot,
+                    await collectInputs(packageRoot),
+                    config.ownershipGroups ?? [],
+                    selectedPaths,
+                  )),
+                ],
               }))(),
         signal,
       ),

package/llms.txt

@@ -19,6 +19,10 @@ the folder modules, and CSS only imports their owner stylesheets.
 
 ### Shared semantic tones
 
+Use `ToolbarText tone="dark"` on a loud or photo-backed toolbar surface to
+match dark control groups. It applies to read-only headings and actionable
+titles at every size; default tone retains existing identity and heading colors.
+
 `SemanticTone` is the shared color-role type for `Badge`, `Chip`, `StateBanner`,
 and semantic `ContentItem` appearances: `neutral`, `info`, `pop`, `success`,
 `warning`, and `danger`. Import it as a type from `@kerfjs/ui`,
@@ -342,6 +346,11 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   compact, prominent, display, and code roles instead of global utility classes. It passes native attributes
   through; block variants own the standard transparent border plus item padding, while `span` owns none. Keep
   toolbar titles on `ToolbarText` and list-aligned bare prose on `ListInsetText`.
+  Text supports `controlMargins` with canonical physical Sides for an exterior 8px control gutter; it preserves border/padding and avoids an isolated Row wrapper. Avoid stacking it with parent insets. Inline spans retain native inline margin behavior.
+
+  `ToolbarControlGroup.tileTone` selects `neutral`, `brand`, `success`, `warning`, or `danger` quiet fill, matching quiet border, and on-quiet foreground for a non-interactive icon tile. Compose a contained `single` group whose only child is a direct decorative LucideIcon (`aria-hidden="true"`). Omission preserves the normal group palette. The prop does not recolor interactive, mixed, multi-control, or borderless groups; keep real actions in controls with their existing focus/hover/pressed treatments.
+  Expanded search groups accept `expandedOverflow="visible"` to anchor app-owned suggestion/date/help surfaces below their relative root; collapsed/default groups retain existing clipping. Apps own surface placement/dismissal and use `data-token-search-keep-open` or `collapsible.keepOpenOn` for focus.
+
 - **Space by the five-step scale, by relationship not by eye.** `0`
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
   group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
@@ -533,3 +542,28 @@ shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelTogg
 - [README.md](./README.md): package overview and the component subpath table.
 
 Neutral lowered surfaces and decorative neutral fills/borders are translucent theme colors; compose nested public components directly. Default/raised canvases, foregrounds, focus indicators, and loud contrast-bearing fills remain opaque. Do not assign depth-specific component tokens in demo wrappers.
+
+Navigation transition continuity: `wireNavStack` slides the incoming view over the preserved previous view on push and the outgoing view off on pop, cross-fades both live chrome surfaces with inert snapshots, and settles/cancels an interrupted transition before starting the next. Reduced motion and duration zero settle immediately.
+
+For a tab scene with drill-down, put a `NavStack` directly in `TabScaffoldTab.content`, configure each view's top `toolbar` and `pane`, and omit `bottomToolbar` at both levels so the scaffold bar remains the only bottom chrome. Wire both components on their own roots. The catalog's **NavStack inside a tab** example exercises push and tab switching.
+
+`Pane.deepInset` (and `PaneConfig.deepInset`) or `TabScaffoldTab.deepInset` on a plain scene adds an 8px outer gutter to the scroll content, so ordinary 8px item margins land 16px from the edge. Nested Row/List/Grid spacing stays at its default. Set a nested scene's Pane option instead of insetting its entire NavStack or toolbar.
+
+`ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow`/`showBelow`
+lengths (for example `px(416)`). Wire `wireToolbarVisibility(root)` from
+`@kerfjs/ui/wire-toolbar-visibility` and dispose on unmount. Thresholds use the
+nearest Toolbar content-box width: hideBelow hides strictly below, showBelow
+shows strictly below, with complementary behavior at equality. Percentages use
+that content width; em and custom properties use the item's own context. Invalid,
+negative, unresolved, or contradictory values leave the item visible under this
+width policy. Keep primary actions visible and offer a complementary overflow
+group. See `docs/component-contract.md` "Toolbar width visibility" for lifecycle
+details.
+
+Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. Keep popup sizing and position repairs out of consumer CSS.
+
+Modal `DialogSurface` bounds use typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`); explicit caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Application render state chooses responsive values, and preview layout remains application-owned.
+
+Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+
+Toolbar visibility measurement probes and invisible state children are helper-owned and survive Kerf rerenders through `data-morph-preserve`. Actual CSS visibility stays stable while rendering removes transient parent markers, preventing geometry-driven render feedback and repeated probe recreation. Toolbar replacement, explicit internal-node removal and disposal retain their existing behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.76",
+  "version": "5.0.0-beta.78",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -40,7 +40,8 @@
     "./dist/browser/*.js",
     "./dist/select-register.js",
     "./dist/popup-menu-register.js",
-    "./dist/help-tags-register.js"
+    "./dist/help-tags-register.js",
+    "./dist/surface-scaffold-register.js"
   ],
   "exports": {
     ".": {
@@ -90,6 +91,10 @@
       "browser": "./dist/browser/surface-scaffold.js",
       "import": "./dist/surface-scaffold.js"
     },
+    "./surface-scaffold/register": {
+      "types": "./dist/surface-scaffold-register.d.ts",
+      "import": "./dist/surface-scaffold-register.js"
+    },
     "./floating-toolbar": {
       "types": "./dist/floating-toolbar.d.ts",
       "browser": "./dist/browser/floating-toolbar.js",
@@ -215,6 +220,10 @@
       "types": "./dist/wire-scroll-dividers.d.ts",
       "import": "./dist/wire-scroll-dividers.js"
     },
+    "./wire-toolbar-visibility": {
+      "types": "./dist/wire-toolbar-visibility.d.ts",
+      "import": "./dist/wire-toolbar-visibility.js"
+    },
     "./nav-stack": {
       "types": "./dist/nav-stack.d.ts",
       "browser": "./dist/browser/nav-stack.js",

package/ux-demo/recipes/list-detail-dialog.tsx

@@ -1,3 +1,4 @@
+import '@kerfjs/ui/surface-scaffold/register';
 import '@kerfjs/ui/layout.css';
 import '@kerfjs/ui/nav-stack.css';
 import '@kerfjs/ui/split-view.css';
@@ -5,6 +6,7 @@ import '@kerfjs/ui/webawesome.css';
 import '@awesome.me/webawesome/dist/components/button/button.js';
 import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
 
+import { remify } from '@kerfjs/ui/css-values';
 import { deviceClass } from '@kerfjs/ui/device-class';
 import { List } from '@kerfjs/ui/list';
 import { ListItem } from '@kerfjs/ui/list-item';
@@ -184,6 +186,8 @@ export const createRecipe: RecipeFactory = (announce) => {
           <DialogSurface
             size="large"
             presentation={compact ? 'fullscreen' : 'modal'}
+            viewportGutter={remify(16)}
+            maxHeight="viewport"
             bodyInset="none"
             footerInset="comfortable"
           >

package/ux-demo/recipes/navigation-stack.tsx

@@ -58,7 +58,7 @@ const ITEMS: LibraryItem[] = [
 export const createRecipe: RecipeFactory = (announce) => {
   const listView = (): NavStackView => ({
     key: 'library',
-    title: 'Library',
+    toolbar: { title: 'Library' },
     content: (
       <List>
         <section>
@@ -79,7 +79,7 @@ export const createRecipe: RecipeFactory = (announce) => {
 
   const detailView = (item: LibraryItem): NavStackView => ({
     key: item.id,
-    title: item.label,
+    toolbar: { title: item.label },
     content: (
       <List controlInsets="t">
         <ContentItem>

package/dist/chunk-5PAVAR4B.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/actions/toolbar-text/toolbar-text.tsx"],"names":[],"mappings":";;;;AA8DO,SAAS,WAAA,CAAY;AAAA,EAC1B,IAAA;AAAA,EACA,IAAA,GAAO,SAAA;AAAA,EACP,SAAA,GAAY,EAAA;AAAA,EACZ,EAAA;AAAA,EACA,YAAA;AAAA,EACA,WAAA,GAAc,KAAA;AAAA,EACd,IAAA,GAAO,KAAA;AAAA,EACP,QAAA,GAAW,IAAA;AAAA,EACX,QAAA,GAAW,IAAA;AAAA,EACX,IAAA,GAAO,KAAA;AAAA,EACP,IAAA;AAAA,EACA;AACF,CAAA,EAAqB;AACnB,EAAA,MAAM,MAAA,GAAS,IAAA,IAAQ,QAAA,IAAY,IAAA,IAAQ,QAAA,GAAW,CAAA;AACtD,EAAA,IAAI,MAAA,KAAW,MAAA;AACb,IAAA,uBACE,GAAA;AAAA,MAAC,QAAA;AAAA,MAAA;AAAA,QACC,IAAA,EAAK,QAAA;AAAA,QACL,KAAA,EAAO,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,QAC5C,gBAAA,EAAe,cAAA;AAAA,QACf,WAAA,EAAW,IAAA;AAAA,QACX,WAAA,EAAW,OAAO,MAAA,GAAS,MAAA;AAAA,QAC3B,eAAA,EAAe,WAAW,MAAA,GAAY,OAAA;AAAA,QACtC,aAAA,EAAa,MAAA;AAAA,QACb,EAAA;AAAA,QACA,IAAA;AAAA,QAEA,QAAA,kBAAA,GAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAM,wBAAA,EAA0B,QAAA,EAAA,IAAA,EAAK;AAAA;AAAA,KAC7C;AAEJ,EAAA,uBACE,GAAA;AAAA,IAAC,MAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MAC5C,gBAAA,EAAe,cAAA;AAAA,MACf,WAAA,EAAW,IAAA;AAAA,MACX,WAAA,EAAW,OAAO,MAAA,GAAS,MAAA;AAAA,MAC3B,WAAA,EAAW,OAAO,MAAA,GAAS,MAAA;AAAA,MAC3B,eAAA,EAAe,WAAW,MAAA,GAAY,OAAA;AAAA,MACtC,gBAAA,EAAgB,MAAA,GAAS,MAAA,CAAO,QAAQ,CAAA,GAAI,MAAA;AAAA,MAC5C,KAAA,EAAO,MAAA,GAAS,CAAA,6BAAA,EAAgC,QAAQ,CAAA,CAAA,GAAK,MAAA;AAAA,MAC7D,kBAAA,EAAkB,cAAc,MAAA,GAAS,MAAA;AAAA,MACzC,EAAA;AAAA,MACA,IAAA,EAAM,eAAe,SAAA,GAAY,MAAA;AAAA,MACjC,YAAA,EAAY,YAAA,GAAe,MAAA,CAAO,YAAY,CAAA,GAAI,MAAA;AAAA,MAClD,WAAA,EAAW,cAAc,MAAA,GAAS,MAAA;AAAA,MAClC,IAAA;AAAA,MAEC,QAAA,EAAA,WAAA,mBACC,GAAA,CAAC,QAAA,EAAA,EAAS,KAAA,EAAO,EAAA,CAAG,CAAC,CAAA,EAAG,CAAA,mBAExB,GAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAM,wBAAA,EAA0B,QAAA,EAAA,IAAA,EAAK;AAAA;AAAA,GAE/C;AAEJ","file":"chunk-5PAVAR4B.js","sourcesContent":["import { em } from '../../../shared/styles/css-values.js';\nimport { Skeleton } from '../../feedback/skeleton/skeleton.js';\n\nexport type ToolbarTextSize =\n  'xlarge' | 'xlarge-fixed' | 'large' | 'default' | 'small' | 'xsmall';\n\n/** ARIA heading level for a title exposed as a heading landmark. */\nexport type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;\n\ninterface ToolbarTextBaseProps {\n  text: string;\n  size?: ToolbarTextSize;\n  className?: string;\n  /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */\n  id?: string;\n  /**\n   * Show a trailing ellipsis (…) where the text is truncated — on the single line\n   * (default), or at the `maxLines` boundary when wrapping. Set false to hard-clip\n   * instead. Default true.\n   */\n  ellipsis?: boolean;\n  /**\n   * Grow to fill the free space of the flex row it sits in (a Toolbar zone),\n   * truncating at the space left by its siblings instead of taking only its\n   * text's width. Default false.\n   */\n  fill?: boolean;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n  /**\n   * Cap wrapped text to this many lines, truncating past it. Only takes effect with\n   * `wrap`; ignored on a single line. `null`/omitted wraps without a line cap. Default null.\n   */\n}\n\ntype ToolbarTextWrappingProps =\n  | {\n      /** Wrap onto multiple lines; combine with `maxLines` to cap them. */\n      wrap: true;\n      maxLines?: number | null;\n    }\n  | { wrap?: false; maxLines?: never };\n\nexport type ToolbarTextProps = ToolbarTextBaseProps &\n  (\n    | ({\n        action?: never;\n        /** Expose `role=\"heading\"` and `aria-level` on read-only text. */\n        headingLevel?: HeadingLevel;\n        /** Render an unanimated loading skeleton instead of the text. */\n        placeholder?: boolean;\n      } & ToolbarTextWrappingProps)\n    | {\n        /** Render a native button with this delegated action; the app owns editing. */\n        action: string;\n        headingLevel?: never;\n        placeholder?: never;\n        wrap?: never;\n        maxLines?: never;\n      }\n  );\n\nexport function ToolbarText({\n  text,\n  size = 'default',\n  className = '',\n  id,\n  headingLevel,\n  placeholder = false,\n  wrap = false,\n  ellipsis = true,\n  maxLines = null,\n  fill = false,\n  slot,\n  action,\n}: ToolbarTextProps) {\n  const capped = wrap && maxLines != null && maxLines > 0;\n  if (action !== undefined)\n    return (\n      <button\n        type=\"button\"\n        class={`kui-toolbar-text ${className}`.trim()}\n        data-component=\"toolbar-text\"\n        data-size={size}\n        data-fill={fill ? 'true' : undefined}\n        data-ellipsis={ellipsis ? undefined : 'false'}\n        data-action={action}\n        id={id}\n        slot={slot}\n      >\n        <span class=\"kui-toolbar-text__text\">{text}</span>\n      </button>\n    );\n  return (\n    <span\n      class={`kui-toolbar-text ${className}`.trim()}\n      data-component=\"toolbar-text\"\n      data-size={size}\n      data-fill={fill ? 'true' : undefined}\n      data-wrap={wrap ? 'true' : undefined}\n      data-ellipsis={ellipsis ? undefined : 'false'}\n      data-max-lines={capped ? String(maxLines) : undefined}\n      style={capped ? `--kui-toolbar-text-max-lines:${maxLines}` : undefined}\n      data-placeholder={placeholder ? 'true' : undefined}\n      id={id}\n      role={headingLevel ? 'heading' : undefined}\n      aria-level={headingLevel ? String(headingLevel) : undefined}\n      aria-busy={placeholder ? 'true' : undefined}\n      slot={slot}\n    >\n      {placeholder ? (\n        <Skeleton width={em(8)} />\n      ) : (\n        <span class=\"kui-toolbar-text__text\">{text}</span>\n      )}\n    </span>\n  );\n}\n"]}