@kerfjs/ui 4.4.1 → 4.5.0-beta.1

package/docs/layout.md

@@ -0,0 +1,150 @@
+# Pane and content layout
+
+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
+<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>
+</Pane>
+```
+
+`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.
+Ordinary surface-like children use `.kui-content-item` and own their complete
+geometry:
+
+- 8px inline margin from the pane edge
+- 1px border, transparent by default
+- 8px internal padding and 8px internal gap
+- `calc(1px + remify(11px))`, or 12px, rounded corners
+
+Use `.kui-content-item--pill` for the 22px pill radius expressed as
+`calc(1px + remify(21px))`. Consumers can make a content item visible without
+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
+inline gutter instead of nesting them inside another padded content item. A
+conditional `StateBanner` remains visibly distinct because it communicates
+semantic status.
+
+## Public roles and tokens
+
+| 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`,
+`ValueTableRow`, tabs, and form controls. A value-table row separator starts at
+the row's 8px content inset, or at 40px when the row contains its 24px leading
+icon and 8px gap, and always ends 8px from the right edge. Each value-table row
+also keeps 8px of root-scaled block padding independently of its semantic inline
+inset. Most interactive rows and toolbar groups are 44px tall.
+Toolbar groups reserve a real 1px outer border around a 42px inner area, even
+when their border and background are transparent.
+`PanelHeader` is a plain top `Toolbar` used as a panel, dialog, or page heading
+and overrides no Toolbar styles. The leading zone holds the optional icon (a
+normal bordered `ToolbarControlGroup` given a brand fill with a matching border,
+a 22px glyph) and the title as extra-large `ToolbarText`; the app's trailing
+controls go straight into the trailing zone, and the icon group is omitted when
+no icon is passed. The optional subtitle is a separate row below the toolbar, its
+text left-aligned with the title text.
+
+## Spacing scale
+
+Spacing is not a free choice. The official scale is five canonical steps, each
+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.                                    |
+
+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
+canonical rhythm** — reach for them only as a deliberate exception, never as a
+default step. Prefer the five canonical tokens so spacing stays legible and
+consistent across every surface.
+
+## Ownership rules
+
+1. Do not pad a sidebar, main area, dialog, or `.kui-pane` shell. Children own
+   their own margin, border, background, padding, and radius.
+2. Use 24px gaps for major vertical separation and 8px gaps inside an item or
+   between toolbar groups. Do not confuse the two relationships.
+3. Wrap toolbar content in `ToolbarControlGroup`, including dormant text. A
+   transparent group still reserves the same 44px geometry as a visible group.
+4. Keep one scrolling content owner per pane. Toolbar and footer siblings stay
+   fixed while the content scrolls.
+5. A split item keeps dormant and interactive regions separate. For example,
+   `ListHeader` renders its title/count-or-badge cluster separately from its optional
+   logical-end 44px action. The header fills the available inline width and its
+   action glyph defaults to 18px; disclosure mode makes the title cluster itself
+   the button and supplies the production `DisclosureArrow` unless `actionIcon`
+   replaces it.
+   `ListActionRow` uses a noninteractive row root around sibling 44px primary
+   and trailing buttons. `ListItem.trailing` remains dormant content.
+   In multiline `ListItem` and `ListActionRow` rows, the leading icon stays
+   centered on the label's first line rather than the full wrapped label.
+6. Reading width, column placement, and responsive relocation remain application
+   decisions. The shared classes define local geometry, not the whole shell.
+7. A visible collapsible pane owns its collapse control in that pane's toolbar.
+   When the pane is hidden, move the restore control into the adjacent main
+   toolbar on the same logical edge: an inline-start pane restores from the
+   main toolbar's leading group, and an inline-end pane restores from its
+   trailing group. Do not leave an otherwise empty icon-only rail behind.
+
+At narrow widths or 200% zoom, relocate or stack panes before shrinking targets.
+The 8/1/8 item contract and 44px controls remain stable, so screenshots and
+focus-order tests exercise the same model at every viewport.

package/docs/nav-stack.md

@@ -0,0 +1,56 @@
+# Navigation stack
+
+`@kerfjs/ui/nav-stack` is an iOS-style push/pop navigation stack: views slide in
+and out over one another while the top chrome settles. A **single-pane layout is
+a `NavStack` with one entry**. It is one of the opt-in app layouts (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+
+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";
+```
+
+## State lives in the app
+
+Like every `@kerfjs/ui` component, `NavStack` is declarative: the app owns the
+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 /> },
+]);
+
+// 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);
+  },
+});
+
+// push / pop by editing the signal:
+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
+mounted (so their DOM state and focus survive) but hidden. Each entry carries a
+`key` (stable identity), `content`, an optional `title`, and optional per-view
+`toolbar` actions. The back control appears automatically once the stack has more
+than one entry; `wireNavStack`'s `onBack` is where the app pops its own signal.
+
+## Transitions
+
+`wireNavStack(root, { onBack, duration? })` observes the rendered stack and
+animates each change: a pushed view slides in from the trailing edge; a popped
+view slides back off it over the revealed view. It returns a disposer. The
+animation honors `prefers-reduced-motion` (transitions collapse to instant) and
+`duration: 0` disables it. Applicable at every device size and inside dialogs.

package/docs/recipes.md

@@ -0,0 +1,167 @@
+# Production composition recipes
+
+These seven reference compositions sit between individual primitives and product
+code. Open each stable UX-catalog route to run it, then copy the linked TSX and
+CSS. The examples import public package subpaths, use semantic layout owners,
+and keep state in a per-instance application adapter. They are not new
+monolithic components.
+
+Copy the recipe source together with the catalog-independent
+[`mount-recipe.ts`](../ux-demo/recipes/mount-recipe.ts) adapter. It mounts the
+controller at one stable application root, uses `delegateActions()` for recipe
+commands, forwards form and dialog lifecycle events, wires resize commits with
+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";
+
+const root = document.querySelector<HTMLElement>("#navigation")!;
+const stopRecipe = mountRecipe(root, createRecipe(announce));
+window.addEventListener("pagehide", stopRecipe, { once: true });
+```
+
+The adapter is delivered as reference source, not a new package runtime export.
+`delegate()` remains a valid alternative when an application needs selector-
+specific dispatch; either way, wire once at a stable root and retain disposal.
+
+## Desktop application shell
+
+[Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx) · [shared CSS](../ux-demo/recipes/recipes.css)
+
+Use `Toolbar`, controlled `ResizableRegion` panes, and one
+`.kui-pane__content` scroll owner per pane. The recipe owns the shell topology;
+the app owns routing, responsive pane visibility, sizes, persistence, and data.
+Keep each visible pane's collapse action in its own toolbar. Once hidden, put
+its restore action in the adjacent main toolbar on the same logical edge:
+leading for an inline-start sidebar and trailing for an inline-end inspector.
+Collapse the pane completely rather than preserving an empty icon rail.
+Adapt only public `--kui-layout-*` and component variables.
+
+## Navigation sidebar
+
+[Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
+
+One unpadded `.kui-pane` owns toolbar/content/footer structure. Its
+`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and other
+`.kui-content-item` children own their 8px margin, 1px border, and 8px padding.
+Rows and footer toolbar groups remain 44px tall. The app owns routes,
+permissions, labels, selection, valid section counts and their localized
+`countLabel` phrases, non-count badge content, disclosure state, and revealed
+content. A toggled `ListHeader` supplies the production `DisclosureArrow` when
+no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
+
+## Workspace header
+
+[Open the recipe](../ux-demo/?component=recipe-workspace-header) · [TSX source](../ux-demo/recipes/workspace-header.tsx)
+
+`PanelHeader` owns the page heading while one control cluster holds secondary,
+overflow, and primary actions. The app owns authorization and command policy;
+controls relocate without changing focus order.
+
+## List-detail dialog
+
+[Open the recipe](../ux-demo/?component=recipe-list-detail-dialog) · [TSX source](../ux-demo/recipes/list-detail-dialog.tsx)
+
+The production Web Awesome dialog owns modal focus and Escape; the thin recipe
+adapter restores the invoking control consistently after the hide event.
+`PanelHeader`, `ListHeader`, `ListItem`, and `ValueTable` own their included
+anatomy. The application owns open state, selection, dismissal policy, and
+record actions. `PanelHeader` places the trailing controls the app passes
+directly into its top toolbar's trailing zone.
+The header sits on the dialog edge while retaining its internal control inset;
+the selected title receives the full content gutter, the metadata table fills
+the available detail width between the usual outer margins, and the action
+cluster uses one outer gutter without a second content-item inset.
+Do not rebuild the dialog or reach into private shadow parts.
+
+## Composer form
+
+[Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
+
+`PanelHeader` supplies the task title and summary, with their ids referenced
+by the form. Production fields own labels, help, and native focus. The field
+and footer control edges sit directly on the shared 8px inline gutter rather
+than acquiring a second content-item padding inset; major children remain 24px
+apart and related controls use 8px gaps. The app owns
+validation, drafts, permissions, and transport. Persistent error or success
+feedback is the only nested semantic surface and uses `StateBanner`, not a toast.
+Because upgraded Web Awesome fields retain live value properties, controlled
+resets synchronize both those properties and the rendered value attributes;
+the Reset action also announces `Draft reset` through the catalog live region.
+
+## List workspace states
+
+[Open the recipe](../ux-demo/?component=recipe-list-workspace-states) · [TSX source](../ux-demo/recipes/list-workspace-states.tsx)
+
+The same content region moves deterministically through loading, empty,
+populated, stale/background refresh, and error/retry states. The recipe owns
+feedback placement; the app owns fetching, cache age, retry policy, and domain
+rows.
+
+## Compact toolbar choices and actions
+
+[Open the recipe](../ux-demo/?component=recipe-compact-toolbar) · [TSX source](../ux-demo/recipes/compact-toolbar.tsx)
+
+Use `ToolbarControlGroup` for related commands, `SegmentedControl` for a few
+visible exclusive choices, `Select` for a longer value list, and an ordinary
+button for an independent command. The app owns values, actions, persistence,
+and responsive priority.
+
+## Navigation stack
+
+[Open the recipe](../ux-demo/?component=recipe-navigation-stack) · [TSX source](../ux-demo/recipes/navigation-stack.tsx)
+
+Drill from a library list into a detail and back with `NavStack`
+(`@kerfjs/ui/nav-stack`): the app owns the stack as a signal of views and
+pushes/pops it, `NavStack` renders it, and `wireNavStack` slides the content and
+settles the chrome (reduced motion collapses the slide to instant). A live
+`deviceClass()` badge shows the current size/orientation. See the layout guide
+[`app-layouts.md`](app-layouts.md) for choosing among `NavStack`, `SplitView`,
+`Workbench`, and `TabScaffold`.
+
+## Loading inspector
+
+[Open the recipe](../ux-demo/?component=recipe-loading-inspector) · [TSX source](../ux-demo/recipes/loading-inspector.tsx)
+
+A record inspector whose per-record values load asynchronously. Every
+value-bearing component (`PanelHeader`, `ValueTable`/`ValueTableRow`, `Select`,
+`SegmentedControl`, `ListItem`, `StateBanner`) takes its `placeholder` from one
+loading flag, so the same real chrome renders a faithful loading state and then
+the populated record — no separate skeleton markup. The composition is the point;
+`Skeleton` is the primitive it builds on. The app owns the loading lifecycle and
+which values are still unknown.
+
+## Collapsible sidebar
+
+[Open the recipe](../ux-demo/?component=recipe-collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx)
+
+A mini app frame whose left navigation rail and bottom activity drawer are
+standalone `CollapsiblePanel`s (`@kerfjs/ui/collapsible-panel`) driven by
+`wireSidebar` (`@kerfjs/ui/wire-sidebar`). `CollapsiblePanelToggle` supplies the
+standard per-side glyph: a collapse toggle lives inside each panel and an expand
+toggle lives in the always-visible main header, so a collapsed panel is still
+reachable. `wireSidebar` owns the toggle delegation, moves focus into a panel on
+open and restores it to the trigger on close, and — when a `deviceClass()` reports
+`compact` — switches the open panel to a dismissable **overlay** (backdrop, Escape
+and backdrop-click collapse, and a trapped Tab ring, the ARIA dialog pattern). It
+also persists each panel's collapsed state through a supplied storage hook. The app
+owns each `collapsed` signal, the panel sizes, and the content; the wire owns the
+ephemeral interaction. For a full three-pane shell use `Workbench` instead — see
+[`app-layouts.md`](app-layouts.md). This recipe is covered end-to-end across
+Chromium, Firefox, and WebKit by `tests/browser/collapsible-sidebar-recipe.spec.ts`.
+
+## Rules shared by every recipe
+
+- Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one
+  `.kui-pane__content` scroll owner for each real boundary.
+- For direct `wa-*` JSX, import types from `@kerfjs/ui/webawesome`. Import only
+  individual Web Awesome registration modules and theme them with
+  `@kerfjs/ui/webawesome.css`.
+- Prefer public props and variables at the composition boundary. When a recipe
+  needs responsive topology, join only classes listed in the catalog's
+  `publicClasses`; do not copy component markup or select descendants by tag,
+  id, attribute alone, or an unlisted implementation class.
+- Start from the copyable mount adapter, or reproduce its complete boundary:
+  wire stable `data-action` hooks once and retain every disposer.

package/docs/split-view.md

@@ -0,0 +1,49 @@
+# Split view (list-detail)
+
+`@kerfjs/ui/split-view` is a list-detail layout: a list and a
+detail side by side on roomy screens, collapsing to a `NavStack` (list → detail)
+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";
+// plus nav-stack.css when the compact path is reachable, and
+// wireResizableRegions / wireNavStack for the interactive behavior.
+```
+
+## Responsive by device class
+
+`SplitView` is declarative; the app derives `compact` from the device class and
+tracks its own selection:
+
+```tsx
+const device = deviceClass();
+const selected = signal<string | null>(null);
+
+<SplitView
+  id="mail"
+  label="Mail"
+  compact={device.value.compact}
+  detailActive={selected.value !== null}
+  list={<ThreadList />}
+  detail={<Message id={selected.value} />}
+  listTitle="Threads"
+  detailTitle="Message"
+  resizable={{ size: 320, min: 220, max: 480 }}
+/>;
+```
+
+- **Roomy** (`compact: false`): both panes show. With `resizable`, the list sits
+  in a `ResizableRegion` (wire it with `wireResizableRegions`); without it the
+  list takes a fixed `--kui-split-view-list-width` (default 320px) and the detail
+  fills the rest.
+- **Compact** (`compact: true`): the split collapses to a `NavStack`. The list is
+  the root; when `detailActive` is true the detail is pushed over it with an
+  automatic back control (wire it with `wireNavStack`, whose `onBack` clears the
+  app's selection). This is the portrait-tablet / handset presentation; as a
+  dialog the compact form is a full-screen or large partial-cover modal.
+
+Compose the interactive wiring from the existing helpers — `SplitView` adds no
+wire of its own.

package/docs/sunken-panel.md

@@ -0,0 +1,53 @@
+# 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>;
+```
+
+The default `shape="rounded"` uses the shared rounded-rectangle radius. Choose
+`shape="square"` for a flush or edge-to-edge area that needs `border-radius: 0`:
+
+```tsx
+<SunkenPanel shape="square">
+  <Workspace />
+</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. The `square` shape deliberately overrides the radius
+property with zero; use `rounded` when customizing the radius token.

package/docs/tab-scaffold.md

@@ -0,0 +1,50 @@
+# Tab scaffold
+
+`@kerfjs/ui/tab-scaffold` 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).
+
+```ts
+import { TabScaffold } from "@kerfjs/ui/tab-scaffold";
+import { wireTabScaffold } from "@kerfjs/ui/wire-tab-scaffold";
+import "@kerfjs/ui/tab-scaffold.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
+clicks.
+
+```tsx
+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 />,
+    },
+  ]}
+/>;
+
+// once, after first render:
+const dispose = wireTabScaffold(root, {
+  onSelect: (id) => {
+    active.value = id;
+  },
+});
+```
+
+Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The
+bottom bar respects the home-indicator safe area (`env(safe-area-inset-bottom)`)
+and keeps 44px targets. On larger device classes, promote the tab set to a
+`Workbench` rail or a persistent sidebar instead of a bottom bar.

package/docs/type-contracts.md

@@ -0,0 +1,102 @@
+# 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 divider sides, 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`,
+  `SunkenPanel`, `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`, `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.
+- Replace `Toolbar({ divider: false })` with `dividerSides: ''`; the default
+  remains a bottom divider, while canonical combinations such as `tr` and
+  `trbl` select more physical edges.
+
+JavaScript runtime behavior remains defensive for previously emitted calls, but
+new TypeScript builds report these invalid or ignored combinations.