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

package/docs/{tab-scaffold.md → tab-navigator.md}

@@ -1,32 +1,47 @@
-# Tab scaffold
+# Tab navigator
 
-`@kerfjs/ui/tab-scaffold` is a mobile-first, iOS-like bottom tab bar that switches
+`@kerfjs/ui/tab-navigator` is a mobile-first, iOS-like bottom tab bar that switches
 between major app sections, where **each tab keeps its own content mounted** —
 usually a `NavStack`, so each tab's stack and scroll survive a switch. One of the
 opt-in app layouts (see [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 It is distinct from `TabBar` (document-oriented, reorderable strips).
 
+## Migration from TabScaffold
+
+The deprecated `TabScaffold` API was removed during the 5.0 beta series. Replace names and import
+paths when updating an app:
+
+| Previous                                                                           | Current                                                                                |
+| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `TabScaffold`, `TabScaffoldTab`, `TabScaffoldProps` from `@kerfjs/ui/tab-scaffold` | `TabNavigator`, `TabNavigatorTab`, `TabNavigatorProps` from `@kerfjs/ui/tab-navigator` |
+| `wireTabScaffold`, `WireTabScaffoldOptions` from `@kerfjs/ui/wire-tab-scaffold`    | `wireTabNavigator`, `WireTabNavigatorOptions` from `@kerfjs/ui/wire-tab-navigator`     |
+| `@kerfjs/ui/tab-scaffold.css`                                                      | `@kerfjs/ui/tab-navigator.css`                                                         |
+
+Props, rendered DOM classes, data attributes, and wiring behavior are unchanged.
+The old JS and CSS subpaths are no longer exported. Import the new CSS path
+when your build does not use the package's `browser` condition.
+
 ```ts
-import { TabScaffold } from "@kerfjs/ui/tab-scaffold";
-import { wireTabScaffold } from "@kerfjs/ui/wire-tab-scaffold";
+import { TabNavigator } from "@kerfjs/ui/tab-navigator";
+import { wireTabNavigator } from "@kerfjs/ui/wire-tab-navigator";
 ```
 
 In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
 webpack do by default), the import above also
-loads TabScaffold's stylesheet and those of the components it renders internally
+loads TabNavigator's stylesheet and those of the components it renders internally
 (the tab `Badge`). Without that condition, import the manual stylesheets instead:
-`@kerfjs/ui/tab-scaffold.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+`@kerfjs/ui/tab-navigator.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
 
 ## Controlled selection
 
-The app owns the active tab (a signal); `TabScaffold` renders every tab's scene
-(only the active one visible) plus the bottom bar, and `wireTabScaffold` reports
+The app owns the active tab (a signal); `TabNavigator` renders every tab's scene
+(only the active one visible) plus the bottom bar, and `wireTabNavigator` reports
 clicks.
 
 ```tsx
 const active = signal("home");
 
-<TabScaffold
+<TabNavigator
   id="app"
   label="Sections"
   active={active.value}
@@ -42,14 +57,14 @@ const active = signal("home");
 />;
 
 // once, after first render:
-const dispose = wireTabScaffold(root, {
+const dispose = wireTabNavigator(root, {
   onSelect: (id) => {
     active.value = id;
   },
 });
 ```
 
-Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, optional `badge`
+Each `TabNavigatorTab` has an `id`, `label`, optional `icon`, optional `badge`
 and `badgeLabel` (see [Tab badges](#tab-badges)), and `content`. The
 bottom bar paints through the home-indicator safe area and pads for it and for
 the side insets, while each scene pads for the top and side insets (a scene
@@ -63,16 +78,16 @@ 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
+`pane: { deepInset: true }` on its views instead. The navigator 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
+and the stack: the navigator'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.
+navigator keeps the tab bar below it.
 
 ```tsx
 import { List } from "@kerfjs/ui/list";
@@ -88,7 +103,7 @@ const projectViews: NavStackView[] = [
   },
 ];
 
-<TabScaffold
+<TabNavigator
   id="app"
   label="Sections"
   active={active.value}
@@ -109,8 +124,8 @@ const projectViews: NavStackView[] = [
 />;
 ```
 
-The app owns each stack's view array and the scaffold's active tab. Call
-`wireTabScaffold` for tab selection and `wireNavStack` for back navigation
+The app owns each stack's view array and the navigator's active tab. Call
+`wireTabNavigator` 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

package/docs/type-contracts.md

@@ -20,7 +20,7 @@ public-signature artifact.
 | `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                                                                                                                                                                                                                                 |
 | `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                                                                                                                                                                                                                                    |
 | `KUI-T007` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                                                                                                                                                                                                                                              |
-| `KUI-T008` | A literal `TabScaffold.active` id belongs to its literal `tabs`.                                                                                                                                                                                                                                                                                                                                       |
+| `KUI-T008` | A literal `TabNavigator.active` id belongs to its literal `tabs`.                                                                                                                                                                                                                                                                                                                                      |
 | `KUI-T009` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                                                                                                                                                                                                                                      |
 | `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all AppTab, TabBar, ToolbarControlGroup, and Select presentation axes; the convenience root barrel re-exports them.                                                                                                                                                               |
 | `KUI-T011` | Semantic component zones use the recursive `KerfUiContent` type: `SafeHtml`, runtime-empty booleans/nullish values, and readonly nested arrays are valid; arbitrary strings, numbers, and signals are rejected. Explicit text positions such as `ListInsetText` retain their text exception.                                                                                                           |
@@ -51,7 +51,7 @@ When choices or ids arrive at runtime and the state signal is correctly typed as
 ```tsx
 <Select<string> value={loadedValue.value} choices={loadedChoices.value} ... />
 <SegmentedControl<string> value={mode.value} choices={loadedModes.value} ... />
-<TabScaffold<string> active={active.value} tabs={loadedTabs.value} ... />
+<TabNavigator<string> active={active.value} tabs={loadedTabs.value} ... />
 ```
 
 The widening is an honest statement that TypeScript cannot know the runtime
@@ -69,7 +69,7 @@ ordinary source/type gates:
   `FloatingToolbar`, `Pane`, `ResizableRegion`, `SegmentedControl`, `StateBanner`,
   `SunkenPanel`, `ToolbarText`, `CollapsiblePanel`, `Catalog`, and the wire helpers;
 - required controlled-state callbacks on `wireResizableRegions`, `wireTabBars`,
-  and `wireTabScaffold`, and the required app-owned size signals on
+  and `wireTabNavigator`, and the required app-owned size signals on
   `wireWorkbench`;
 - mutually exclusive count/badge metadata on `ListHeader`; and
 - protected application metadata boundaries on `AppTab`, `ListItem`,

package/docs/ui-analyzer.md

@@ -289,6 +289,11 @@ the id stays in `ai/application-ui-diagnostic-ids-v1.json` (listed under
 `retired`) so a profile exception that already names it still loads. Remove
 such exceptions at your convenience.
 
+`KUI-C101` was likewise retired when Toolbar zones were aligned with their
+`KerfUiContent` props. Direct content is valid; `ToolbarControlGroup` remains a
+presentation choice for shared control chrome. The id stays in the registry so
+existing profile exceptions still load, but new profiles should not use it.
+
 ## Loud fill / on-loud pairing (`KUI-L018`)
 
 The shipped Web Awesome theme pairs every `--wa-color-{tone}-fill-loud` with a

package/docs/ui-doctor.md

@@ -64,15 +64,25 @@ so the same root hook-class check applies in those files.
 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`).
+the component's kebab-case name (`KUI-D031`). A component whose returned root
+is its own HTML element must put that kebab-case class on rendered markup
+(`KUI-D030`). Static base tokens in template, concatenated, and conditional
+class expressions count only when every path contains the token.
+An opaque class expression stays unclassified instead of producing a missing
+root-class error.
 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
+`.workspace-header`. A local composition catalog can explicitly declare a
+different `boundaries.rootClass` or `publicClasses` and list its stylesheet
+under the selection entry's `styleSources`; Doctor honors that declared alias
+for both checks. The catalog stage remains responsible for validating the
+metadata. Thin components that return another component need no root class,
+even when they render nested HTML as children. Helpers declared in the same
+module share that module's CSS ownership; a module exporting several visual
+components can use a shared stylesheet name. Shared stylesheets declared in
+`ownershipGroups` are exempt from the naming check.
+
+Doctor reports `KUI-D032` when a paired stylesheet selects another module's
+local component 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

package/doctor/component-style-checks.mjs

@@ -4,17 +4,197 @@ import { basename, dirname, extname, relative, resolve } from 'node:path';
 import postcss from 'postcss';
 import ts from 'typescript';
 
+import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
 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();
+  name
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .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];
+const unknown = '\u0000';
+
+function combinations(left, right) {
+  if (left.length * right.length > 32) return [unknown];
+  return left.flatMap((a) => right.map((b) => a + b));
+}
+
+function staticPatterns(node, bindings = new Map(), seen = new Set()) {
+  if (!node) return [unknown];
+  if (ts.isIdentifier(node) && bindings.has(node.text) && !seen.has(node.text))
+    return staticPatterns(
+      bindings.get(node.text),
+      bindings,
+      new Set([...seen, node.text]),
+    );
+  if (
+    ts.isCallExpression(node) &&
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'join'
+  ) {
+    const target = node.expression.expression;
+    const array = ts.isIdentifier(target) ? bindings.get(target.text) : target;
+    if (array && ts.isArrayLiteralExpression(array)) {
+      const separator =
+        node.arguments[0] && ts.isStringLiteral(node.arguments[0])
+          ? node.arguments[0].text
+          : ',';
+      let patterns = [''];
+      for (const [index, element] of array.elements.entries())
+        patterns = combinations(
+          patterns,
+          staticPatterns(element, bindings, seen).map(
+            (part) => `${index ? separator : ''}${part}`,
+          ),
+        );
+      return patterns;
+    }
+  }
+  if (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isTypeAssertionExpression(node)
+  )
+    return staticPatterns(node.expression, bindings, seen);
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+    return [node.text];
+  if (ts.isConditionalExpression(node))
+    return [
+      ...new Set([
+        ...staticPatterns(node.whenTrue, bindings, seen),
+        ...staticPatterns(node.whenFalse, bindings, seen),
+      ]),
+    ];
+  if (ts.isTemplateExpression(node)) {
+    let patterns = [node.head.text];
+    for (const span of node.templateSpans)
+      patterns = combinations(
+        combinations(patterns, staticPatterns(span.expression, bindings, seen)),
+        [span.literal.text],
+      );
+    return patterns;
+  }
+  if (
+    ts.isBinaryExpression(node) &&
+    node.operatorToken.kind === ts.SyntaxKind.PlusToken
+  )
+    return combinations(
+      staticPatterns(node.left, bindings, seen),
+      staticPatterns(node.right, bindings, seen),
+    );
+  return [unknown];
+}
+
+function guaranteedClasses(node, bindings) {
+  if (!node) return new Set();
+  if (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isTypeAssertionExpression(node)
+  )
+    return guaranteedClasses(node.expression, bindings);
+  const patterns = staticPatterns(node, bindings);
+  const classes = new Set(classNames(patterns[0]));
+  for (const pattern of patterns.slice(1)) {
+    const other = new Set(classNames(pattern));
+    for (const name of classes) if (!other.has(name)) classes.delete(name);
+  }
+  return classes;
+}
+
+function returnedIntrinsic(node) {
+  while (node && ts.isParenthesizedExpression(node)) node = node.expression;
+  if (node && ts.isConditionalExpression(node))
+    return (
+      returnedIntrinsic(node.whenTrue) && returnedIntrinsic(node.whenFalse)
+    );
+  const tag =
+    node && ts.isJsxElement(node)
+      ? node.openingElement.tagName
+      : node && ts.isJsxSelfClosingElement(node)
+        ? node.tagName
+        : undefined;
+  return Boolean(tag && ts.isIdentifier(tag) && /^[a-z]/.test(tag.text));
+}
+
+function belongsToComponentReturn(node, owner) {
+  let scope = node.parent;
+  while (scope && !ts.isFunctionLike(scope)) scope = scope.parent;
+  if (!scope) return false;
+  if (ts.isFunctionDeclaration(scope)) return scope.name?.text === owner;
+  return (
+    ts.isArrowFunction(scope) &&
+    ts.isVariableDeclaration(scope.parent) &&
+    ts.isIdentifier(scope.parent.name) &&
+    scope.parent.name.text === owner
+  );
+}
+
+async function catalogAliases(workspaceRoot, packageRoot) {
+  const aliases = new Map();
+  const profile = await loadApplicationUiProfile({
+    workspaceRoot,
+    startDirectory: packageRoot,
+    knownRules: [],
+    packageProfile: resolve(
+      import.meta.dirname,
+      '../ai/application-ui-profile.defaults.json',
+    ),
+  });
+  for (const catalog of profile.profile?.catalogs ?? []) {
+    const owner = profile.provenance?.[`$catalogs.${catalog.package}`];
+    if (!owner || !catalog.selection?.path) continue;
+    try {
+      const selection = JSON.parse(
+        await readFile(resolve(dirname(owner), catalog.selection.path), 'utf8'),
+      );
+      const composition = catalog.composition?.path
+        ? JSON.parse(
+            await readFile(
+              resolve(dirname(owner), catalog.composition.path),
+              'utf8',
+            ),
+          )
+        : { entries: [] };
+      const composed = new Map(
+        (composition.entries ?? []).map((entry) => [entry.key, entry]),
+      );
+      for (const entry of selection.entries ?? []) {
+        if (!entry.source || !entry.name) continue;
+        const source = resolve(dirname(owner), entry.source);
+        const relativeSource = relative(packageRoot, source);
+        if (relativeSource === '..' || relativeSource.startsWith('../'))
+          continue;
+        const detail = composed.get(
+          `${selection.package ?? catalog.package}:${entry.id}`,
+        );
+        const classes = [
+          detail?.boundaries?.rootClass,
+          ...(detail?.boundaries?.publicClasses ?? []),
+          ...(entry.publicClasses ?? []),
+        ].filter(Boolean);
+        const styleSources = [
+          ...(detail?.styleSources ?? []),
+          ...(entry.styleSources ?? []),
+        ].map((style) => resolve(dirname(owner), style));
+        aliases.set(`${source}:${entry.name}`, {
+          classes: new Set(classes),
+          styles: new Set(styleSources),
+        });
+      }
+    } catch {
+      // The catalog stage reports invalid or missing artifacts.
+    }
+  }
+  return aliases;
+}
 
 function componentFacts(file, source) {
   const syntax = file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.JSX;
@@ -39,12 +219,18 @@ function componentFacts(file, source) {
       componentName(node.name.text)
     )
       owner = node.name.text;
+    else if (
+      owner &&
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.initializer
+    )
+      components.get(owner)?.bindings.set(node.name.text, node.initializer);
     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) ||
@@ -52,22 +238,44 @@ function componentFacts(file, source) {
           )
             continue;
           const value = attribute.initializer;
-          const literal =
+          const classes =
             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);
+              ? classNames(value.text)
+              : value && ts.isJsxExpression(value)
+                ? guaranteedClasses(
+                    value.expression,
+                    components.get(owner)?.bindings,
+                  )
+                : [];
+          if (
+            value &&
+            ts.isJsxExpression(value) &&
+            staticPatterns(
+              value.expression,
+              components.get(owner)?.bindings,
+            ).every((pattern) => pattern === unknown)
+          )
+            components.get(owner).uncertain = true;
+          for (const name of classes) components.get(owner)?.add(name);
         }
       }
     }
+    if (
+      owner &&
+      ts.isReturnStatement(node) &&
+      belongsToComponentReturn(node, owner) &&
+      returnedIntrinsic(node.expression)
+    )
+      components.get(owner).intrinsic = true;
+    if (
+      owner &&
+      ts.isArrowFunction(node) &&
+      ts.isVariableDeclaration(node.parent) &&
+      ts.isIdentifier(node.parent.name) &&
+      node.parent.name.text === owner &&
+      returnedIntrinsic(node.body)
+    )
+      components.get(owner).intrinsic = true;
     ts.forEachChild(node, (child) => visit(child, owner));
   };
   const declarations = (node) => {
@@ -76,13 +284,19 @@ function componentFacts(file, source) {
       node.name &&
       componentName(node.name.text)
     )
-      components.set(node.name.text, new Set());
+      components.set(
+        node.name.text,
+        Object.assign(new Set(), { bindings: new Map() }),
+      );
     if (
       ts.isVariableDeclaration(node) &&
       ts.isIdentifier(node.name) &&
       componentName(node.name.text)
     )
-      components.set(node.name.text, new Set());
+      components.set(
+        node.name.text,
+        Object.assign(new Set(), { bindings: new Map() }),
+      );
     ts.forEachChild(node, declarations);
   };
   declarations(ast);
@@ -99,6 +313,11 @@ function diagnostic(id, file, line, message, action) {
     location: { file, line, column: 1 },
     action,
     documentation: '@kerfjs/ui/docs/ui-doctor.md#component-style-naming',
+    meaning: {
+      'KUI-D030': 'Component root class does not match its name',
+      'KUI-D031': 'Component stylesheet does not match its name',
+      'KUI-D032': 'Stylesheet selects another component class',
+    }[id],
   };
 }
 
@@ -107,7 +326,9 @@ export async function checkComponentStyles(
   inputs,
   ownershipGroups = [],
   selectedPaths,
+  workspaceRoot = packageRoot,
 ) {
+  const aliases = await catalogAliases(workspaceRoot, packageRoot);
   const scripts = new Map();
   const styles = new Map();
   const importedBy = new Map();
@@ -160,10 +381,14 @@ export async function checkComponentStyles(
     )
       continue;
     const components = scripts.get(pair);
-    const matching = [...components].find(([name]) => kebab(name) === stem);
+    const matching =
+      [...components].find(([name]) => kebab(name) === stem) ??
+      [...components].find(([name]) =>
+        aliases.get(`${pair}:${name}`)?.styles.has(file),
+      );
     if (!matching) {
       const names = [...components.keys()];
-      if (names.length)
+      if (names.length === 1)
         diagnostics.push(
           diagnostic(
             'KUI-D031',
@@ -176,7 +401,14 @@ export async function checkComponentStyles(
       continue;
     }
     const [name, renderedClasses] = matching;
-    if (renderedClasses.intrinsic && !renderedClasses.has(stem))
+    const declaredClasses =
+      aliases.get(`${pair}:${name}`)?.classes ?? new Set();
+    if (
+      renderedClasses.intrinsic &&
+      !renderedClasses.uncertain &&
+      !renderedClasses.has(stem) &&
+      ![...declaredClasses].some((className) => renderedClasses.has(className))
+    )
       diagnostics.push(
         diagnostic(
           'KUI-D030',
@@ -207,7 +439,8 @@ export async function checkComponentStyles(
       ];
       for (const className of selected) {
         const foreign = owners.get(block(className));
-        if (!foreign || foreign.name === name) continue;
+        if (!foreign || foreign.name === name || foreign.file === pair)
+          continue;
         diagnostics.push(
           diagnostic(
             'KUI-D032',

package/doctor/index.mjs

@@ -1254,6 +1254,7 @@ export async function runUiDoctor({
                     await collectInputs(packageRoot),
                     config.ownershipGroups ?? [],
                     selectedPaths,
+                    root,
                   )),
                 ],
               }))(),

package/llms.txt

@@ -349,6 +349,7 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   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.
+  Toolbar zones accept `KerfUiContent` directly. Use `ToolbarText` for identity and `ToolbarControlGroup` for related controls that need its shared chrome; a bare control keeps its own styling and accessibility responsibilities.
   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`
@@ -380,10 +381,10 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   with `chromeDividers="scroll"` then draws the line under its header only while content is scrolled beneath
   it and the line over its footer only while more content lies below (never
   when the content fits), every `NavStack`'s top chrome and bottom toolbar and
-  every `TabScaffold` bar do the same around the active view or scene, and
+  every `TabNavigator` bar do the same around the active view or scene, and
   every `TabBar` marks each side of its strip with tabs scrolled out of view. Configure a pane with `chromeDividers`
   (`scroll` for a plain pane by default, `always` for a sunken pane by default,
-  or explicit `scroll`, `always`, `none`), and a `NavStack` or `TabScaffold`
+  or explicit `scroll`, `always`, `none`), and a `NavStack` or `TabNavigator`
   with its own `chromeDividers` (same values; a `SplitView` forwards it through
   `compactStack`); name app-owned chrome in `targets`.
   Never add a border, or a permanent `dividerSides`, to fake one.
@@ -487,7 +488,7 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   consuming component. Use a real button or link for interactive content.
   For new content without a count, use the text-free `size="dot"` form: it
   takes no children, and needs a `label` (announced as an image) or
-  `ariaHidden` when its owner announces it. A `TabScaffold` tab shows the dot
+  `ariaHidden` when its owner announces it. A `TabNavigator` tab shows the dot
   with `badge: true` plus its required `badgeLabel`.
 - **Use `Chip` for removable tags.** Give the native remove button a delegated
   `removeAction` and a specific `removeLabel`; the application updates the tag
@@ -502,13 +503,13 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
 `Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
 `wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
 `wireScrollDividers` (scroll-state dividers for every `Pane`, `NavStack`,
-`TabScaffold`, and `TabBar`),
+`TabNavigator`, and `TabBar`),
 `ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
 `LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
 tree-shakeable, declarative with `wire…` helpers; the browser build of each layout
 subpath loads its CSS and that of the components it renders, and a companion
 CSS subpath remains for pipelines without the `browser` condition):
-`NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
+`NavStack`, `SplitView`, `Workbench`, `TabNavigator`, driven by `deviceClass()` from
 `@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
 shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
 
@@ -534,7 +535,7 @@ shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelTogg
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
 - [workbench.md](./docs/workbench.md): the `Workbench` multi-panel shell, its collapse policies, and opt-in `resizable` panels driven by `wireWorkbench` (`@kerfjs/ui/wire-workbench`: drag, keyboard, min/max, persistence, compact suspension), the `mainMinSize` / `mainMinHeight` work-area minimums (default 320px wide beside any inline rail, 120px tall above the drawer) that resizable panels stop at and inline panels shrink around, and a panel's `responsiveOverlayAt` (`narrow` / `compact`, rails and the bottom drawer) that presents it as an overlay below a Workbench container breakpoint without a device-class check; a panel given its `collapsed` signal is a transient overlay (collapsed on entering the breakpoint, takes focus and keeps Tab inside while open, closed by Escape or an outside press, focus returned; `dismissOverlays`), and overlays are exclusive by default (opening one closes the others; `exclusiveOverlays: false` opts out).
-- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
+- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabNavigator` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
 - [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
 - [ai/components/README.md](./ai/components/README.md): the generated per-component markdown reference — the assistant entry point over both JSON catalogs.
 - [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
@@ -545,9 +546,10 @@ Neutral lowered surfaces and decorative neutral fills/borders are translucent th
 
 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.
+For a tab scene with drill-down, put a `NavStack` directly in `TabNavigatorTab.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.
+`Pane.deepInset` (and `PaneConfig.deepInset`) or `TabNavigatorTab.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.
+For a child table whose decoration spans the Pane while its text stays aligned, use the Pane content slot's inherited `--kui-pane-content-inset-inline-start` and `--kui-pane-content-inset-inline-end`: negate them for the child's logical margins and add them to cell padding. They include safe areas and `deepInset`; see `docs/app-layouts.md#edge-to-edge-content-inside-a-pane`.
 
 `ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow`/`showBelow`
 lengths (for example `px(416)`). Wire `wireToolbarVisibility(root)` from