@kerfjs/ui 5.0.0-beta.17 → 5.0.0-beta.21

package/docs/examples/command-palette-adapter.tsx

@@ -26,17 +26,57 @@ export function mountCommandPaletteAdapter(
   const query = signal('');
   const render = () => {
     const needle = query.value.trim().toLocaleLowerCase();
-    const matches = commands.filter((command) => !needle ||
-      [command.label, ...(command.keywords ?? [])].some((value) => value.toLocaleLowerCase().includes(needle)));
-    return <section class="app-command-palette kui-content" aria-label="Command palette">
-      <div class="kui-content-item"><label for="app-command-query">Search commands</label><input id="app-command-query" type="search" value={query.value} autocomplete="off" data-command-query /></div>
-      <p class="kui-content-item" aria-live="polite">{matches.length} matching commands</p>
-      <ul class="kui-content-item" aria-label="Matching commands">{matches.map((command) => <li><button type="button" data-action="run-command" data-command-id={command.id}>{command.label}</button></li>)}</ul>
-      <footer class="kui-control-cluster kui-content-item" aria-label="Command palette actions">
-        <button type="button" data-action="clear-query">Clear search</button>
-        <button type="button" data-action="close-palette">Close</button>
-      </footer>
-    </section>;
+    const matches = commands.filter(
+      (command) =>
+        !needle ||
+        [command.label, ...(command.keywords ?? [])].some((value) =>
+          value.toLocaleLowerCase().includes(needle),
+        ),
+    );
+    return (
+      <section
+        class="app-command-palette kui-content"
+        aria-label="Command palette"
+      >
+        <div class="kui-content-item">
+          <label for="app-command-query">Search commands</label>
+          <input
+            id="app-command-query"
+            type="search"
+            value={query.value}
+            autocomplete="off"
+            data-command-query
+          />
+        </div>
+        <p class="kui-content-item" aria-live="polite">
+          {matches.length} matching commands
+        </p>
+        <ul class="kui-content-item" aria-label="Matching commands">
+          {matches.map((command) => (
+            <li>
+              <button
+                type="button"
+                data-action="run-command"
+                data-command-id={command.id}
+              >
+                {command.label}
+              </button>
+            </li>
+          ))}
+        </ul>
+        <footer
+          class="kui-control-cluster kui-content-item"
+          aria-label="Command palette actions"
+        >
+          <button type="button" data-action="clear-query">
+            Clear search
+          </button>
+          <button type="button" data-action="close-palette">
+            Close
+          </button>
+        </footer>
+      </section>
+    );
   };
 
   const stopMount = mount(root, render);
@@ -52,12 +92,22 @@ export function mountCommandPaletteAdapter(
     },
     'close-palette': onClose,
   });
-  const stopInput = delegate<HTMLInputElement>(root, 'input', '[data-command-query]', (_event, input) => {
-    query.value = input.value;
-  });
-  const stopEscape = delegate(root, 'keydown', '[data-command-query]', (event) => {
-    if ((event as KeyboardEvent).key === 'Escape') onClose();
-  });
+  const stopInput = delegate<HTMLInputElement>(
+    root,
+    'input',
+    '[data-command-query]',
+    (_event, input) => {
+      query.value = input.value;
+    },
+  );
+  const stopEscape = delegate(
+    root,
+    'keydown',
+    '[data-command-query]',
+    (event) => {
+      if ((event as KeyboardEvent).key === 'Escape') onClose();
+    },
+  );
   let disposed = false;
   return () => {
     if (disposed) return;

package/docs/examples/component-catalog-extension-v2.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "../../ai/component-catalog-extension-v2.schema.json",
+  "schemaVersion": 2,
+  "package": "@acme/ui",
+  "compatibility": {
+    "v1Catalog": "./component-catalog-extension.json",
+    "identity": "package:id"
+  },
+  "entries": [
+    {
+      "key": "@acme/ui:inspector",
+      "package": "@acme/ui",
+      "id": "inspector",
+      "name": "Inspector",
+      "kind": "composition",
+      "source": "application",
+      "parents": { "mode": "listed", "entries": ["@kerfjs/ui:layout"] },
+      "contexts": ["record-detail"],
+      "zones": [
+        {
+          "id": "header",
+          "accepts": ["@kerfjs/ui:panel-header"],
+          "cardinality": { "min": 1, "max": 1 },
+          "exclusiveWith": []
+        },
+        {
+          "id": "facts",
+          "accepts": ["@kerfjs/ui:value-table"],
+          "cardinality": { "min": 1, "max": 1 },
+          "exclusiveWith": []
+        }
+      ],
+      "children": {
+        "mode": "listed",
+        "concepts": ["@kerfjs/ui:panel-header", "@kerfjs/ui:value-table"],
+        "requiredConcepts": [
+          "@kerfjs/ui:panel-header",
+          "@kerfjs/ui:value-table"
+        ]
+      },
+      "state": [
+        { "id": "selected-record", "owner": "application", "required": true }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": {
+        "owner": "application",
+        "behaviors": [
+          "May move between inline-end pane and dialog at the application breakpoint."
+        ]
+      },
+      "layout": {
+        "roles": ["inspector"],
+        "geometry": {
+          "margin": "parent",
+          "border": "child",
+          "padding": "child"
+        }
+      },
+      "accessibility": {
+        "obligations": ["The header names the inspector region."]
+      },
+      "boundaries": {
+        "rootClass": "acme-inspector",
+        "publicClasses": ["acme-inspector"],
+        "publicTokens": []
+      },
+      "diagnostics": [
+        {
+          "id": "KUI-C901",
+          "severity": "error",
+          "when": "the header or facts zone is absent",
+          "message": "Inspector requires exactly one header and one facts region."
+        }
+      ],
+      "provenance": {
+        "selection": "docs/inspector.md",
+        "composition": "docs/inspector.md#composition-contract"
+      }
+    }
+  ]
+}

package/docs/examples/component-catalog-extension.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "../../ai/component-catalog-extension.schema.json",
+  "schemaVersion": 1,
+  "package": "@acme/ui",
+  "description": "Application-owned components composed with Kerf UI.",
+  "entries": [
+    {
+      "id": "acme-filter-chip",
+      "name": "FilterChip",
+      "kind": "component",
+      "purpose": "A removable application filter displayed inside a token-search workflow.",
+      "useWhen": [
+        "A saved application filter needs a compact visible label and remove action."
+      ],
+      "avoidWhen": [
+        "The value belongs to TokenSearchField's own controlled token collection."
+      ],
+      "publicClasses": ["acme-filter-chip"],
+      "publicTokens": ["--acme-filter-chip-accent"],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "documentation": "docs/filter-chip.md"
+    },
+    {
+      "id": "acme-inspector",
+      "name": "Inspector",
+      "kind": "composition",
+      "purpose": "An application inspector composed from Kerf panel, content, and value primitives.",
+      "useWhen": ["A selected record needs a titled fact-and-action region."],
+      "avoidWhen": ["A ValueTable alone expresses the complete interaction."],
+      "geometry": {
+        "margin": "parent",
+        "border": "child",
+        "padding": "child",
+        "notes": [
+          "The embedding pane positions the inspector; PanelHeader, ValueTable, and action groups retain their own geometry."
+        ]
+      },
+      "documentation": "docs/inspector.md"
+    }
+  ]
+}

package/docs/layout.md

@@ -1,26 +1,39 @@
 # Pane and content layout
 
-Import `@kerfjs/ui/layout.css` for the shared geometry used by sidebars, main
-areas, inspectors, and dialogs. The vocabulary deliberately describes structure
-rather than location: the same pane can be placed anywhere.
+Import `Pane` from `@kerfjs/ui/pane`. Browser-aware bundlers receive its CSS
+automatically; other consumers can import `@kerfjs/ui/pane.css`. Import
+`@kerfjs/ui/layout.css` as well when using the related content-item and control
+layout classes. The vocabulary deliberately describes structure rather than
+location: the same pane can be placed anywhere.
 
 ## Anatomy
 
 ```tsx
-<aside class="kui-pane">
-  <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
-  <div class="kui-pane__content kui-content">
+<Pane
+  element="aside"
+  label="Workspace"
+  contentElement="nav"
+  contentLabel="Workspace pages"
+  separators={["inline-end"]}
+  header={<Toolbar label="Workspace" ... />}
+  footer={<Toolbar label="Actions" ... />}
+>
     <section>...</section>
     <section>...</section>
-  </div>
-  <footer class="kui-pane__footer"><Toolbar label="Actions" ... /></footer>
-</aside>
+</Pane>
 ```
 
-`.kui-pane` has no padding. It reserves rows for an optional toolbar, one
-scrolling content area, and an optional footer. A main area or dialog often
-omits the footer; a navigation pane commonly uses all three. Fixed chrome stays
-outside `.kui-pane__content`, which is the pane's scroll owner.
+`Pane` has no padding. It reserves rows for an optional vertical header, one
+scrolling vertical content area, and an optional footer. A header may contain a
+top toolbar followed by secondary toolbar or status rows. A main area or dialog
+often omits the footer; a navigation pane commonly uses all three. Fixed chrome
+stays outside `.kui-pane__content`, which is the pane's only scroll owner.
+
+Pass any combination of logical sides to `separators`: `block-start`,
+`block-end`, `inline-start`, and `inline-end`. Every line is off by default and
+each enabled side uses `--kui-pane-separator-width` (1px) and
+`--kui-pane-separator-color` (`--kui-color-border`). Logical sides keep pane
+boundaries correct in both left-to-right and right-to-left layouts.
 
 `.kui-content` is a vertical stack with a 24px gap between major children.
 Sections may contain adjacent `ListItem` rows without adding another major gap.
@@ -37,6 +50,11 @@ Use `.kui-content-item--pill` for the 22px pill radius expressed as
 changing its geometry by setting `--kui-content-item-border` and
 `--kui-content-item-background`.
 
+Nested rounded edges stay concentric by subtracting their full inset from the
+outer radius. For example, `SegmentedControl` places each item behind a 1px
+control border and 1px control padding, so its default rounded-rectangle radius
+is 10px inside the control's 12px radius.
+
 A visible parent surface does not make every child another visible card. The
 composer recipe keeps its form as the single surface, uses `PanelHeader` for
 its task hierarchy, and places field and action control edges on the shared 8px
@@ -46,16 +64,17 @@ semantic status.
 
 ## Public roles and tokens
 
-| Need | Class | Token / default |
-| --- | --- | --- |
-| Unpadded toolbar/content/footer structure | `.kui-pane` | — |
-| Scrolling pane content | `.kui-pane__content` | — |
-| Major vertical rhythm | `.kui-content` | `--kui-layout-content-gap: 24px` |
-| Self-contained child geometry | `.kui-content-item` | 8px margin + 1px border + 8px padding |
-| Pill child | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px` |
-| Related controls | `.kui-control-cluster` | `--kui-layout-control-gap: 8px` |
-| Inline metadata | `.kui-inline-metadata` | `--kui-layout-metadata-gap: 4px` |
-| Explicit scroll owner outside a pane | `.kui-scroll-owner` | `overflow: auto` |
+| Need                                     | Class                     | Token / default                       |
+| ---------------------------------------- | ------------------------- | ------------------------------------- |
+| Unpadded header/content/footer structure | `Pane`, `.kui-pane`       | —                                     |
+| Scrolling pane content                   | `.kui-pane__content`      | —                                     |
+| Optional logical-edge separators         | `Pane.separators`         | `--kui-pane-separator-width: 1px`     |
+| Major vertical rhythm                    | `.kui-content`            | `--kui-layout-content-gap: 24px`      |
+| Self-contained child geometry            | `.kui-content-item`       | 8px margin + 1px border + 8px padding |
+| Pill child                               | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px`      |
+| Related controls                         | `.kui-control-cluster`    | `--kui-layout-control-gap: 8px`       |
+| Inline metadata                          | `.kui-inline-metadata`    | `--kui-layout-metadata-gap: 4px`      |
+| Explicit scroll owner outside a pane     | `.kui-scroll-owner`       | `overflow: auto`                      |
 
 The component layer applies the same contract to `Toolbar`, `ListHeader`,
 `ListItem`, `PanelHeader`, `StateBanner`, `ValueTable`,
@@ -81,16 +100,16 @@ expressing exactly one relationship — pick the step by **how connected two
 elements are**, not by eye. Every scalable value is `remify`-authored against the
 fixed 16px baseline, so it delivers as `rem`.
 
-| Value | Token | Relationship — when to use |
-| --- | --- | --- |
-| 0px | `--kui-space-none` | No separation. The elements read as a single unit (a control and its own affordance, adjacent `ListItem` rows). |
-| 4px | `--kui-space-2xs` | Very minor. Still one connected cluster, but readability or aesthetics demand a hair of air (inline metadata, an icon beside its label). |
-| 8px | `--kui-space-xs` | Standard. Between elements **within a group** — the content-item padding/gutter, gaps between toolbar controls in a group. |
-| 16px | `--kui-space-m` | Minor. Between **homogeneous groups** — two lists, two sibling sections of the same kind. |
-| 24px | `--kui-space-l` | Major. Between **heterogeneous groups** — the `.kui-content` rhythm between major, differing regions. |
+| Value | Token              | Relationship — when to use                                                                                                               |
+| ----- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| 0px   | `--kui-space-none` | No separation. The elements read as a single unit (a control and its own affordance, adjacent `ListItem` rows).                          |
+| 4px   | `--kui-space-2xs`  | Very minor. Still one connected cluster, but readability or aesthetics demand a hair of air (inline metadata, an icon beside its label). |
+| 8px   | `--kui-space-xs`   | Standard. Between elements **within a group** — the content-item padding/gutter, gaps between toolbar controls in a group.               |
+| 16px  | `--kui-space-m`    | Minor. Between **homogeneous groups** — two lists, two sibling sections of the same kind.                                                |
+| 24px  | `--kui-space-l`    | Major. Between **heterogeneous groups** — the `.kui-content` rhythm between major, differing regions.                                    |
 
-The two relationships that get confused most are 8px vs 24px: 8px is *inside* a
-group, 24px is *between* major, differing regions. 16px sits between them for
+The two relationships that get confused most are 8px vs 24px: 8px is _inside_ a
+group, 24px is _between_ major, differing regions. 16px sits between them for
 same-kind groups.
 
 `--kui-space-s` (12px) and `--kui-space-xl` (32px) exist but are **off the

package/docs/nav-stack.md

@@ -8,9 +8,9 @@ a `NavStack` with one entry**. It is one of the opt-in app layouts (see
 Import the component and its companion stylesheet:
 
 ```ts
-import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
-import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
-import '@kerfjs/ui/nav-stack.css';
+import { NavStack, type NavStackView } from "@kerfjs/ui/nav-stack";
+import { wireNavStack } from "@kerfjs/ui/wire-nav-stack";
+import "@kerfjs/ui/nav-stack.css";
 ```
 
 ## State lives in the app
@@ -20,16 +20,25 @@ stack as a `signal<NavStackView[]>`, `NavStack({ views })` renders it, and
 `wireNavStack` animates the transitions.
 
 ```tsx
-const views = signal<NavStackView[]>([{ key: 'inbox', title: 'Inbox', content: <InboxView /> }]);
+const views = signal<NavStackView[]>([
+  { key: "inbox", title: "Inbox", content: <InboxView /> },
+]);
 
 // render inside mount():
 <NavStack id="mail" label="Mail" views={views.value} />;
 
 // once, after first render:
-const dispose = wireNavStack(root, { onBack: () => { views.value = views.value.slice(0, -1); } });
+const dispose = wireNavStack(root, {
+  onBack: () => {
+    views.value = views.value.slice(0, -1);
+  },
+});
 
 // push / pop by editing the signal:
-views.value = [...views.value, { key: id, title: 'Message', content: <MessageView id={id} /> }];
+views.value = [
+  ...views.value,
+  { key: id, title: "Message", content: <MessageView id={id} /> },
+];
 ```
 
 `NavStack` renders every entry stacked, the last one active and the rest kept

package/docs/recipes.md

@@ -14,12 +14,12 @@ the public `onCommit` callback, retains every disposer, and returns one
 idempotent disposer:
 
 ```ts
-import { createRecipe } from './navigation-sidebar.js';
-import { mountRecipe } from './mount-recipe.js';
+import { createRecipe } from "./navigation-sidebar.js";
+import { mountRecipe } from "./mount-recipe.js";
 
-const root = document.querySelector<HTMLElement>('#navigation')!;
+const root = document.querySelector<HTMLElement>("#navigation")!;
 const stopRecipe = mountRecipe(root, createRecipe(announce));
-window.addEventListener('pagehide', stopRecipe, { once: true });
+window.addEventListener("pagehide", stopRecipe, { once: true });
 ```
 
 The adapter is delivered as reference source, not a new package runtime export.

package/docs/split-view.md

@@ -6,9 +6,9 @@ on compact ones. One of the opt-in app layouts (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
 ```ts
-import { SplitView } from '@kerfjs/ui/split-view';
-import { deviceClass } from '@kerfjs/ui/device-class';
-import '@kerfjs/ui/split-view.css';
+import { SplitView } from "@kerfjs/ui/split-view";
+import { deviceClass } from "@kerfjs/ui/device-class";
+import "@kerfjs/ui/split-view.css";
 // plus nav-stack.css when the compact path is reachable, and
 // wireResizableRegions / wireNavStack for the interactive behavior.
 ```

package/docs/sunken-panel.md

@@ -0,0 +1,43 @@
+# SunkenPanel
+
+`SunkenPanel` is a visually lowered application surface with one compact inset
+and a vertical content stack. Use it for a main work area or nested panel whose
+background should sit behind ordinary content, such as the primary stage in an
+issue tracker or component catalog.
+
+```tsx
+import { SunkenPanel } from '@kerfjs/ui/sunken-panel';
+
+<SunkenPanel ariaLabel="Release workspace">
+  <ReleaseSummary />
+  <ReleaseChecks />
+</SunkenPanel>;
+```
+
+## Ownership
+
+The root owns its lowered background, 8px padding, and 8px vertical gap.
+Children own their borders and internal geometry. The application owns child
+order, responsive placement, and scrolling; `SunkenPanel` deliberately does not
+create another scroll container.
+
+Use `ariaLabel` only when the surface is a distinct region people need to find
+by name. With a label, the root receives `role="region"`; without one it remains
+a non-landmark grouping.
+
+Do not use `SunkenPanel` merely to add padding, as a substitute for pane
+header/content/footer anatomy, or around a child that already owns the same
+outer surface.
+
+## Public styling boundary
+
+Override the public properties at the composition boundary:
+
+- `--kui-sunken-panel-background`
+- `--kui-sunken-panel-foreground`
+- `--kui-sunken-panel-padding`
+- `--kui-sunken-panel-gap`
+- `--kui-sunken-panel-radius`
+
+The public root class is `.kui-sunken-panel`. Prefer the properties above over
+styling descendants.

package/docs/tab-scaffold.md

@@ -7,9 +7,9 @@ opt-in app layouts (see [`../../docs/23-app-layouts.md`](../../docs/23-app-layou
 It is distinct from `TabBar` (document-oriented, reorderable strips).
 
 ```ts
-import { TabScaffold } from '@kerfjs/ui/tab-scaffold';
-import { wireTabScaffold } from '@kerfjs/ui/wire-tab-scaffold';
-import '@kerfjs/ui/tab-scaffold.css';
+import { TabScaffold } from "@kerfjs/ui/tab-scaffold";
+import { wireTabScaffold } from "@kerfjs/ui/wire-tab-scaffold";
+import "@kerfjs/ui/tab-scaffold.css";
 ```
 
 ## Controlled selection
@@ -19,20 +19,29 @@ The app owns the active tab (a signal); `TabScaffold` renders every tab's scene
 clicks.
 
 ```tsx
-const active = signal('home');
+const active = signal("home");
 
 <TabScaffold
   id="app"
   label="Sections"
   active={active.value}
   tabs={[
-    { id: 'home', label: 'Home', icon: <HomeIcon />, content: <HomeStack /> },
-    { id: 'search', label: 'Search', icon: <SearchIcon />, content: <SearchStack /> },
+    { id: "home", label: "Home", icon: <HomeIcon />, content: <HomeStack /> },
+    {
+      id: "search",
+      label: "Search",
+      icon: <SearchIcon />,
+      content: <SearchStack />,
+    },
   ]}
 />;
 
 // once, after first render:
-const dispose = wireTabScaffold(root, { onSelect: (id) => { active.value = id; } });
+const dispose = wireTabScaffold(root, {
+  onSelect: (id) => {
+    active.value = id;
+  },
+});
 ```
 
 Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The

package/docs/type-contracts.md

@@ -0,0 +1,99 @@
+# Compile-time contracts
+
+Kerf UI rejects invalid integrations at compile time only when TypeScript can
+prove the relationship from one call. The versioned
+[`compile-time-contracts-v1.json`](../ai/compile-time-contracts-v1.json)
+artifact names those guarantees with stable `KUI-T###` ids. Its source fixture
+is compiled twice: against `src/` and against declarations extracted from the
+actual `npm pack` tarball. `npm run check:catalog` also verifies that every
+contract still points to a real catalog entry/import and a symbol in the emitted
+public-signature artifact.
+
+## Strengthened contracts
+
+| ID         | Compile-time guarantee                                                                                                                                                                 |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KUI-T001` | `ListHeader` is a passive heading, a fully named/icon-bearing trailing action, or a controlled disclosure with `action` + `expanded`. Props ignored by the selected mode are rejected. |
+| `KUI-T002` | `Select` has a visible `label` or an `ariaLabel`.                                                                                                                                      |
+| `KUI-T003` | A literal `Select.value` belongs to its literal `choices`.                                                                                                                             |
+| `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                   |
+| `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` | `PanelHeader.summaryId` cannot exist without rendered `summary` content.                                                                                                               |
+| `KUI-T008` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                              |
+| `KUI-T009` | A literal `TabScaffold.active` id belongs to its literal `tabs`.                                                                                                                       |
+| `KUI-T010` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                      |
+| `KUI-T011` | Finite public variants have named exported union types, including tab activation, banner urgency, and all ToolbarControlGroup presentation axes.                                       |
+
+Literal identity inference is intentionally additive for dynamic applications.
+When choices or ids arrive at runtime and the state signal is correctly typed as
+`string`, widen the component explicitly:
+
+```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} ... />
+```
+
+The widening is an honest statement that TypeScript cannot know the runtime
+dataset. Do not cast a known literal typo merely to bypass the relationship.
+
+## Complete public-surface audit
+
+The following existing contracts were already exact and remain covered by the
+ordinary source/type gates:
+
+- required identity or accessible-name inputs on `AppTab`, `FloatingToolbar`,
+  `NavStack`, `SplitView`, `Workbench`, `TabBar`, `ResizableRegion`,
+  `SegmentedControl`, `TokenSearchField`, `PanelHeader`, and `ValueTable`;
+- finite variants exported or represented as literal props on `DisclosureArrow`,
+  `FloatingToolbar`, `Pane`, `ResizableRegion`, `SegmentedControl`, `StateBanner`,
+  `ToolbarText`, `CollapsiblePanel`, `Catalog`, and the wire helpers;
+- required controlled-state callbacks on `wireResizableRegions`, `wireTabBars`,
+  and `wireTabScaffold`;
+- mutually exclusive count/badge metadata on `ListHeader`; and
+- protected application metadata boundaries on `AppTab`, `ListItem`,
+  `ListActionRow`, `ListHeader`, `Pane`, `CatalogExample`, and
+  `CatalogExampleStack`.
+
+The remaining components (`LucideIcon`, `DisclosureArrow`, `Toolbar`,
+`ToolbarControlGroup`, `ListInsetControl`, `ListInsetText`, `LoadingSpinner`,
+`Skeleton`, `SunkenPanel`, `EmptyState`, `StateBanner`, `ValueTableRow`, and the
+pure helpers) have independent props with no further conditional invalid state
+that TypeScript can truthfully remove. Optional labels on decorative icons and
+unnamed non-landmark surfaces are intentional variants, not missing contracts.
+
+## Boundaries TypeScript cannot prove
+
+Types do not claim to validate:
+
+- the contents of `SafeHtml` slots (for example, “only AppTab children” or “no
+  interactive descendants”);
+- nonempty arrays, unique ids, numeric min/max ordering, or a controlled value
+  loaded from dynamic data;
+- equality between ids rendered in separate calls, elements discovered later in
+  the DOM, or an ARIA relationship's live target;
+- that a caller retained and invoked a wiring disposer; or
+- CSS class/token use inside arbitrary strings.
+
+Those remain catalog `KUI-C###` diagnostics, runtime filtering/guards, lint or
+browser assertions. Encoding them as permissive-looking TypeScript brands would
+move errors into casts without making the integration safer.
+
+## Migration from the earlier declarations
+
+- Add `actionLabel` and `actionIcon` to a non-toggle `ListHeader` action. For a
+  disclosure, set literal `toggle: true`, provide `action` and controlled
+  `expanded`, and remove trailing-action-only props.
+- Give every `Select` either `label` or `ariaLabel`. Use an explicit `<string>`
+  generic only for genuinely dynamic choice data.
+- Put `expanded`/expand-action props behind `collapsible: true`.
+- Replace `wireTokenSearchFields({ keyboard: true })` with either
+  `{ keyboard: { onRemoveToken } }` or
+  `{ keyboard: { removeAdjacentToken: false } }` when only caret navigation is
+  wanted.
+- Remove orphaned `summaryId`, or render the matching `summary`; add
+  `wrap: true` anywhere `ToolbarText.maxLines` is used.
+
+JavaScript runtime behavior remains defensive for previously emitted calls, but
+new TypeScript builds report these invalid or ignored combinations.