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

package/docs/component-selection.md

@@ -183,7 +183,7 @@ beside a `ContentItem` value, and connect its id to the preview group's
 | One application tab — `AppTab`                                                                                          | A controlled app tab needs selection, close, drag, leading/trailing anatomy, compact/segmented/icon-only presentation, label truncation, safe domain metadata, or a product-specific close glyph.                                                                                                                                                        | Do not render it alone or use it for a small settings choice; compose in `TabBar`, or use `SegmentedControl`. Keep `closeIcon` noninteractive.                                                                                                                                                                                             | Compose in `TabBar`; let `wireTabBars` manage interaction. Put only domain `data-*` values in `rootAttributes`; use typed appearance props instead of descendant CSS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Tab identity, order, selection, close policy, content, domain metadata values, and outer placement.                                                      | `@kerfjs/ui/app-tab`                                                                      | [Tabs contract](./accessibility.md#tabs)                                            |
 | Application tab strip — `TabBar`, `wireTabBars`, `reorderTabs`                                                          | Tabs switch page regions and may overflow, close, reorder, fill a segmented inspector strip, sit beside a trailing action, or keep that adjacent action distinct from a far-edge end action.                                                                                                                                                             | Do not use it for a compact local view toggle; use `SegmentedControl`. Do not use it for a long choice list; use `Select`. Prefer it over Web Awesome `wa-tab-group`, `wa-tab`, and `wa-tab-panel` for Kerf app tabs.                                                                                                                      | Call `wireTabBars` once, retain the disposer, and apply `onReorder` synchronously; `reorderTabs` is the default array helper. Combine `trailingPlacement="adjacent"` with `end` for split actions; TabBar owns the shrinking/scrolling tab geometry and keeps both actions visible. Choose typed presentation/allocation props while the parent owns outer placement.                                                                                                                                                                                                                                                                                                                                                  | Ordered tabs, selection, panels, routing, closing, persistence, action content, and outer placement.                                                     | `@kerfjs/ui/tab-bar` plus `@kerfjs/ui/wire-tab-bars`                                      | [Tabs contract](./accessibility.md#tabs)                                            |
 | Panel, dialog, or page heading — `Toolbar` + `ToolbarText`                                                              | A panel, dialog, or page needs an extra-large title, optional icon, grouped trailing actions, and optional supporting copy.                                                                                                                                                                                                                              | Do not add a private heading wrapper or bespoke layout. The toolbar supplies structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior. In a narrow peripheral rail or drawer, where xlarge would truncate at the panel's minimum size, use the default `ToolbarText` size as pane identity.  | Connect title/supporting-copy ids to the host, group controls, and delegate actions. **For a page or view title set `headingLevel` (usually `1`)** on `ToolbarText`; omit it for a dialog title referenced by `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Open state, focus lifecycle, dismissal, controls, ids, copy, and heading level.                                                                          | `@kerfjs/ui/toolbar` + `@kerfjs/ui/toolbar-text`                                          | [Toolbar headings](./accessibility.md#toolbar-headings)                             |
-| Dialog or popup geometry — `DialogSurface`, `PopupSurface`                                                              | Recurring Web Awesome dialogs need standard sizes/presentations/body/footer insets, or dropdown menus need list-compatible inset ownership.                                                                                                                                                                                                              | Do not use these wrappers as generic layout or to replace native dialog/dropdown behavior. Avoid consumer `::part()` overrides and do not stack a dialog body inset around list-owned child geometry.                                                                                                                                      | Wrap one `wa-dialog` or `wa-dropdown`; choose the typed geometry while retaining native labeling, open state, focus, dismissal, and menu semantics. Compose a dialog body as a `List` by default, use `bodyInset="none"` when its children own list geometry, and wrap bare prose in `ListInsetText`.                                                                                                                                                                                                                                                                                                                                                                                                                  | State, focus lifecycle, dismissal, labels, content, and outer placement.                                                                                 | `@kerfjs/ui/surface-scaffold`                                                             | [Surface scaffolds](./surface-scaffold.md)                                          |
+| Dialog or popup geometry — `DialogSurface`, `PopupSurface`                                                              | Recurring Web Awesome dialogs need standard sizes/presentations/body/footer insets and typed modal viewport bounds, or dropdown menus need list-compatible inset ownership.                                                                                                                                                                              | Do not use these wrappers as generic layout or to replace native dialog/dropdown behavior. Avoid consumer `::part()` overrides and do not stack a dialog body inset around list-owned child geometry.                                                                                                                                      | Wrap one `wa-dialog` or `wa-dropdown`; choose the typed geometry while retaining native labeling, open state, focus, dismissal, and menu semantics. Compose a dialog body as a `List` by default, use `bodyInset="none"` when its children own list geometry, and wrap bare prose in `ListInsetText`.                                                                                                                                                                                                                                                                                                                                                                                                                  | State, focus lifecycle, dismissal, labels, content, and outer placement.                                                                                 | `@kerfjs/ui/surface-scaffold`                                                             | [Surface scaffolds](./surface-scaffold.md)                                          |
 | Key/value facts — `ValueTable`, `ValueTableRow`                                                                         | Read-only labels and values form a semantic definition list, optionally with a leading icon.                                                                                                                                                                                                                                                             | Do not use it for editable form fields or a row/column data grid; use native form or table semantics.                                                                                                                                                                                                                                      | Compose typed `ValueTableRow` entries; pass `icon` when a 24px leading icon adds useful context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Values, formatting, icon meaning, and empty/loading policy.                                                                                              | `@kerfjs/ui/value-table`                                                                  | [Component ownership](./component-contract.md#ownership-boundaries)                 |
 | Indeterminate activity — `LoadingSpinner`                                                                               | A Kerf surface needs compact, labeled or decorative indeterminate progress.                                                                                                                                                                                                                                                                              | Do not use it for known progress; use Web Awesome `wa-progress-bar` or `wa-progress-ring`. Direct Web Awesome UI may use `wa-spinner`; do not mix spinner systems within one surface.                                                                                                                                                      | Pass a label when the spinner conveys status; use size for a named icon step or positive pixel size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Loading lifecycle and adjacent status copy.                                                                                                              | `@kerfjs/ui/loading-spinner`                                                              | [Accessibility](./accessibility.md#shared-rules)                                    |
 | Loading placeholder — `Skeleton` + a component's `placeholder` prop                                                     | A value or a whole component is still loading and should hold its space as a subtle, unanimated block, keeping the layout stable — an inspector or detail view rendering its real chrome with per-record values absent.                                                                                                                                  | Do not use it for known progress (use `LoadingSpinner`), do not animate it, and do not hand-rebuild a component's empty state — set `placeholder` on the component instead. Prefer it over `wa-skeleton`, which the pure-Kerf primitives avoid to stay Web-Awesome-free.                                                                   | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render skeletons in its value slots with interactivity disabled; use the standalone `Skeleton` for a custom slot.                                                                                                                                                                                                                                                                                                                                                                                                                 | Loading lifecycle, which slots are unknown, and announcing the loading region.                                                                           | `@kerfjs/ui/skeleton`                                                                     | [Accessibility](./accessibility.md#shared-rules)                                    |

package/docs/layout.md

@@ -36,6 +36,26 @@ size) tall, and below that lets the whole pane scroll as one column, header,
 content, and footer together, so the content keeps its natural height. The
 default `fixed` always pins them.
 
+### Deep content inset
+
+Set `deepInset` on a `Pane` to add one 8px inline gutter to its scrolling
+content. A `ContentItem` or `ListItem` that normally sits 8px from the pane
+edge then sits 16px from it. The default is `false`. This extra gutter adds
+to any device safe-area inset, while the pane's header, footer, background,
+and separators still reach their usual edges.
+
+```tsx
+<Pane deepInset>
+  <ContentItem>Project Atlas</ContentItem>
+</Pane>
+```
+
+The pane leaves `--kui-layout-inline-margin` at its normal 8px value. Nested
+`Row`, `List`, and `Grid` therefore keep their usual item spacing; they do
+not inherit a doubled margin. `PaneConfig.deepInset` forwards through
+Workbench `mainPane`, panel `pane`, CollapsiblePanel `pane`, and a
+`NavStackView.pane`.
+
 ### Lowered work surfaces
 
 Set `appearance="sunken"` when the work area itself should use the lowered

package/docs/nav-stack.md

@@ -15,7 +15,7 @@ import { wireNavStack } from "@kerfjs/ui/wire-nav-stack";
 In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
 webpack do by default), the import above also
 loads NavStack's stylesheet and those of the components it renders internally
-(`Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `LucideIcon`). Without that condition, import the manual stylesheets instead:
+(`Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `Pane`, `List`, `LucideIcon`). Without that condition, import the manual stylesheets instead:
 `@kerfjs/ui/nav-stack.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
 
 ## State lives in the app
@@ -28,9 +28,12 @@ stack as a `signal<NavStackView[]>`, `NavStack({ views })` renders it, and
 const views = signal<NavStackView[]>([
   {
     key: "inbox",
-    title: "Inbox",
+    toolbar: { title: "Inbox" },
     content: <InboxView />,
-    bottomToolbar: <InboxStatus />,
+    bottomToolbar: {
+      label: "Inbox status",
+      leading: <InboxStatus />,
+    },
   },
 ]);
 
@@ -47,35 +50,39 @@ const dispose = wireNavStack(root, {
 // push / pop by editing the signal:
 views.value = [
   ...views.value,
-  { key: id, title: "Message", content: <MessageView id={id} /> },
+  { key: id, toolbar: { title: "Message" }, content: <MessageView id={id} /> },
 ];
 ```
 
 `NavStack` renders every entry stacked, the last one active and the rest kept
 mounted (so their DOM state survives) but hidden. Each entry carries a
-`key` (stable identity), `content`, an optional `title`, optional per-view
-`leading`, `center`, and trailing `toolbar` groups for the top toolbar, and an
-optional per-view `bottomToolbar`. The component-level
+`key` (stable identity), `content`, an optional `toolbar` object with `title`,
+`leading`, `center`, and `trailing` groups, and an optional structured
+`bottomToolbar`. The component-level structured
 `bottomToolbar` remains a persistent fallback for views that do not provide one.
-Each view can also provide `header`, pinned below its top toolbar and above
-that view's single scroll area. A fixed heading, notice, or section selector
-can therefore change with the active screen without adding another scroller.
+Each view can also provide `header`, `footer`, `headerList`, `footerList`, and
+`pane` configuration, as a `WorkbenchStaticPanel` does. With any of these,
+the view renders a `Pane`: its header and footer stay pinned around the view's
+scrolling content, and slide with that view during navigation. The header and
+footer list configuration forwards to their `List`s; `pane` forwards
+`contentElement`, `contentLabel`, `separators`, `safeAreaEdges`,
+`chromeDividers`, and `appearance` to the Pane. Without those fields, the view
+keeps its simple direct scroll area. Use `pane: { appearance: "sunken" }` for a
+lowered scrolling work surface.
 The back control appears automatically once the stack has more than one entry;
 `wireNavStack`'s `onBack` is where the app pops its own signal.
 
-Set a view's `appearance: "sunken"` to paint its scroll viewport with the
-shared lowered-surface color, including space after short content. When the
-view holds a `Pane` as its only child, set the appearance on the Pane instead
-if its content owns scrolling. See [Lowered work surfaces](layout.md#lowered-work-surfaces).
+See [Lowered work surfaces](layout.md#lowered-work-surfaces) for nested Pane
+and layout content.
 
 ## The top toolbar
 
 The top chrome is a real `Toolbar`, so it follows the same zone,
 group, and responsive rules as every other toolbar. Its leading zone holds the
 back control (a borderless `ToolbarControlGroup`, shown once the stack has
-depth), then the active view's `leading` groups, then the view's `title` as a
-`ToolbarText`. The view's `center` fills the center zone and its `toolbar`
-fills the trailing zone. Give each zone `ToolbarControlGroup`s or `ToolbarText`,
+depth), then `toolbar.leading`, then `toolbar.title` as a `ToolbarText`.
+`toolbar.center` fills the center zone and `toolbar.trailing` fills the
+trailing zone. Give each zone `ToolbarControlGroup`s or `ToolbarText`,
 as in any toolbar.
 
 Configure the toolbar with `toolbarConfig` instead of styling it:
@@ -95,7 +102,12 @@ Configure the toolbar with `toolbarConfig` instead of styling it:
 />
 ```
 
-- `toolbarConfig` forwards the `Toolbar` configuration (`dividerSides`,
+- Each view's `toolbar` can forward the `Toolbar` configuration (`dividerSides`,
+  `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and its `label`,
+  `titleSize`, and `headingLevel`. A view value overrides the corresponding
+  `toolbarConfig` default. Its `bottomToolbar` forwards the same `Toolbar`
+  configuration and has a required accessible `label`.
+- `toolbarConfig` supplies stack-wide defaults (`dividerSides`,
   `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and adds
   `label` (the toolbar's accessible name), `titleSize` (the title's
   `ToolbarText` size, default `large`), and `headingLevel` (expose the title as

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;
+}