@kerfjs/ui 5.0.0-beta.77 → 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
@@ -59,6 +74,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 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 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
+navigator 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>,
+  },
+];
+
+<TabNavigator
+  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 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
+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/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

@@ -58,6 +58,39 @@ 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 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`. 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
+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,457 @@
+import { readFile } from 'node:fs/promises';
+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-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;
+  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;
+    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)) {
+        for (const attribute of node.attributes.properties) {
+          if (
+            !ts.isJsxAttribute(attribute) ||
+            !['class', 'className'].includes(attribute.name.text)
+          )
+            continue;
+          const value = attribute.initializer;
+          const classes =
+            value && ts.isStringLiteral(value)
+              ? 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) => {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name &&
+      componentName(node.name.text)
+    )
+      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,
+        Object.assign(new Set(), { bindings: new Map() }),
+      );
+    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',
+    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],
+  };
+}
+
+export async function checkComponentStyles(
+  packageRoot,
+  inputs,
+  ownershipGroups = [],
+  selectedPaths,
+  workspaceRoot = packageRoot,
+) {
+  const aliases = await catalogAliases(workspaceRoot, packageRoot);
+  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) ??
+      [...components].find(([name]) =>
+        aliases.get(`${pair}:${name}`)?.styles.has(file),
+      );
+    if (!matching) {
+      const names = [...components.keys()];
+      if (names.length === 1)
+        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;
+    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',
+          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 || foreign.file === pair)
+          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;
+}