@kerfjs/ui 5.0.0-beta.49 → 5.0.0-beta.51

package/docs/accessibility.md

@@ -10,7 +10,7 @@ These are normative contracts for package components and consuming applications.
 - `ListHeader` owns action naming, disabled state, and disclosure `aria-expanded`. Toggle mode supplies one decorative 18px `DisclosureArrow` when `actionIcon` is omitted; it mirrors `expanded` while the native button's accessible name stays stable. The application must update that controlled state and reveal or hide real content. A valid `count` is visually rendered in an `aria-hidden` neutral pill while the required localized `countLabel` becomes part of the owning heading or disclosure button's accessible name; zero remains a real count. Its narrow `triggerAttributes` slot may describe a native popover or controlled-content relationship with `popoverTarget`, `popoverTargetAction`, `aria-controls`, and `aria-haspopup`; the application owns the target surface and its focus/dismissal behavior.
 - Dispose `wireTabBars` and `wireTokenSearchFields` with their owning view. Disposal cancels queued controlled-render focus restoration, so a torn-down view cannot reclaim focus from its successor.
 - `wireNavStack` moves focus into every newly active top view and remembers the last focused descendant of each mounted view for pop restoration. Mark a preferred initial heading or control with `data-nav-focus` (and `tabindex="-1"` when it is not normally tabbable); otherwise the helper uses the first enabled focusable descendant, then a programmatically focusable view-container fallback.
-- In any `.kui-pane`, menu rows, `ListHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `ListHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; do not reduce the target to the visible icon.
+- In any `.kui-pane`, menu rows, `ListHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `ListHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-list-header-action-icon-size` inside a fitted 36px hover square; a transparent hit layer extends the pointer target to at least 44 × 44 around that square without moving layout or enlarging the painted surface. Compact headers are 36px tall like the rest of the compact List family, so their action target is 44px wide and clamped to the 36px header height instead of reaching into a neighboring row. Do not reduce the target to the visible icon, and do not force the button itself to 44px.
 - `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
 - `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure. Its optional `badge` is persistent inline status/count content beside the title and is announced as part of the banner; keep it terse and do not rely on color alone for its meaning.
 - `EmptyState` reports busy state through `aria-busy` and never relies on an illustration as its label.
@@ -29,10 +29,23 @@ adding height or spacing. This also applies to `renderSelected`: selected conten
 stays separate from the control's stable accessible name. Applications do not
 need shadow-DOM patches or extra label styling.
 
-Use `presentation="toolbar-borderless"` with `size="compact"` inside a
-`ToolbarControlGroup`; set `focusRingOwner="group"` when that parent paints the
-composed focus ring. `selectedPresentation="icon-only"` hides only the visible
-selected label—the required `label` or `ariaLabel` still names the combobox.
+Use `presentation="toolbar-borderless"` inside a `ToolbarControlGroup`, with
+`size="compact"` in a compact group; set `focusRingOwner="group"` when that
+parent paints the composed focus ring. `selectedPresentation="icon-only"` hides
+only the visible selected label—the required `label` or `ariaLabel` still names
+the combobox. An icon-only trigger keeps its disclosure caret: the selected icon
+and caret form one pill with the same geometry as a popup-menu `wa-dropdown`
+trigger (8px inline padding on both sides, 12px from the icon to the caret, a
+40px default or 32px compact control height), so the caret still signals a
+choice list. Inside a group the trigger is inset evenly on every side (2px in a
+default group, 1px in a compact one) with a concentric radius; the group grows
+to the trigger's width, so a single group is wider than it is tall and its
+focus ring follows the pill while focused and while its listbox is open.
+Beside other controls in one group, the icon-only trigger is one more segment:
+it keeps the group's gap and its siblings' block inset, height, item radius,
+and hover pill. In a group with per-control rings (`focusRing="control"`, the
+default) it paints the same ring as its sibling buttons, even when
+`focusRingOwner="group"` was set, because no group ring would show focus.
 Navigation selects can use intrinsic `presentation="navigation"` plus
 `labelMaxWidth` for component-owned ellipsis. These props own the control's
 appearance; its parent continues to own outer placement.
@@ -85,13 +98,38 @@ popover or context menu.
 
 ## ResizableRegion
 
+Set `responsiveFillAt="narrow"` or `"compact"` when a responsive composition
+shows the region as its only inline track. The component then owns its
+full-width geometry and removes its dormant separator at that container
+breakpoint; the application owns which pane is visible.
+
 The handle exposes separator role, orientation, name, minimum, maximum, and current values. `wireResizableRegions()` adds:
 
 - the axis arrow keys in 16 px steps by default;
 - Shift+Arrow in 64 px steps;
 - Home and End for minimum and maximum;
 - primary-pointer drag with clamping;
-- preview callbacks while dragging and one commit callback on release.
+- a visible maximum: when a parent clamps the track below the requested size
+  (a `max-width` stage, a narrow container), pointer and keyboard resizing stop
+  at the size actually shown, and the handle announces that size in
+  `aria-valuenow` and that bound in `aria-valuemax`. Focusing the handle
+  reports a stale larger committed size as the shown size without committing
+  it, so the first key press moves the visible separator. The reported values
+  also stay current at rest: a `ResizeObserver` on each region and its parent
+  re-clamps them when the space changes, and a `MutationObserver` re-clamps
+  them after a re-render writes the rendered props back, so assistive
+  technology never reads an unclamped size between interactions (the
+  disposer disconnects both observers);
+- a whole hit target and focus ring at a clamped edge: when the separator has
+  less room past it than the handle's 10px overhang (a parent clamps the track
+  to its own edge), the region carries `data-handle-inset` and the handle sits
+  wholly inside it, so a clipping ancestor cannot cut off half the handle or
+  its focus ring. The ring is drawn inside the handle's box, so the region's
+  ends meeting a clipping edge never shave it either;
+- preview callbacks while dragging and one commit callback on release;
+- a live size that also resizes slide-motion content, so the content tracks the
+  separator during a drag or key press instead of waiting for the app to
+  re-render the committed size.
 
 The application owns persistence and collapsed/expanded policy. Keep the last expanded size outside the component and restore it when reopening. An optional `handleIcon` replaces only decorative dormant content; it must not contain controls or interactive roles because the separator remains the sole focus and interaction owner.
 
@@ -129,10 +167,15 @@ and — via `position` and `--kui-floating-toolbar-inset` — where it sits.
 ## Tabs
 
 `AppTab` renders one controlled tab. `TabBar` supplies the containing tab list,
-fixed leading/trailing regions, and a horizontally scrollable strip.
+fixed leading/trailing/end regions, and a horizontally scrollable strip.
 Use `TabBar.presentation` for rail, segmented, or inspector chrome,
 `allocation="fill"` when peers should divide the strip, and
 `trailingPlacement="adjacent"` when an action belongs beside the final tab.
+When that local action must coexist with a workspace-level action, put the
+workspace action in `end`; TabBar keeps the adjacent action immediately after
+the shrinkable/scrolling tabs and pins `end` at the far edge. Leading,
+trailing, and end actions remain visible and do not shrink. The component owns
+that geometry; applications must not override its anatomy to create the split.
 `AppTab` provides compact 32px, segmented, truncating-label, and icon-only
 presentations. Icon-only tabs keep the required `name` as the tab button's
 accessible name while visually hiding the duplicate label. These props own
@@ -237,9 +280,13 @@ standard per-side collapse/expand glyph (`PanelLeft*` / `PanelRight*` /
 `PanelBottom*`); place a collapse toggle inside the panel and an expand toggle in
 an always-visible location so it is reachable while collapsed. `wireSidebar()`
 moves focus into the panel when it opens and restores it to the trigger when it
-closes. When a `deviceClass()` reports `compact`, an open panel becomes an overlay
+closes; a trigger inside the now-hidden panel hands focus to the panel's toggle
+outside it instead, so an app may render the expand toggle only while the panel
+is collapsed. When a `deviceClass()` reports `compact`, an open panel becomes an overlay
 with a dismissable backdrop, Escape and backdrop-click collapse it, and Tab is
-trapped within it (the ARIA dialog pattern). The application owns each `collapsed`
+trapped within it (the ARIA dialog pattern). That modal state only ever begins
+from a user action: at wire-up on a compact device and on a wide → compact
+crossing, every panel starts collapsed, so no page load or resize traps focus. The application owns each `collapsed`
 signal, the panels, their sizes, and content; the wire may persist the collapsed
 state per panel.
 

package/docs/app-layouts.md

@@ -19,6 +19,79 @@ Derive responsiveness from `deviceClass()`: `compact` (a handset or portrait
 tablet) means "one pane at a time"; `atLeast('tablet')` / `atLeast('desktop')`
 gate the roomier presentations.
 
+Full-height shells retain `height: 100%` so they remain embeddable. Give a
+top-level shell a definite height chain by importing `@kerfjs/ui/document.css`
+and applying `.kui-app-root` to the direct mount container; see the
+[document baseline](document-baseline.md). Do not replace an embeddable shell's
+height with `100dvh`.
+
+## Safe areas
+
+On a device with unsafe areas (a notch, rounded corners, a home indicator) and a
+page that opts into them with `<meta name="viewport" content="…, viewport-fit=cover">`,
+the layouts handle the insets for you. There is nothing to configure:
+
+- **Surfaces paint edge to edge.** Pane and panel backgrounds, separators, and
+  dividers run through the unsafe area. A collapsible rail or drawer grows by
+  the inset it reaches, so its content keeps its configured width or height.
+- **Content is padded on the sides it touches.** Inline insets pad the sides a
+  region actually reaches. Block insets become padding _inside_ the scroll
+  container (with matching `scroll-padding`), so content scrolls under the
+  status bar or home indicator but its first and last items can always be
+  scrolled clear.
+- **Interior edges get nothing.** A `Workbench` center next to an expanded rail,
+  a `SplitView` detail beside its list, or a `NavStack` view under its chrome is
+  not inset on that edge. Collapse the rail and the center picks up the edge.
+- **No double inset.** Whichever region applies an inset clears it for its
+  descendants. A layout region whose only child is a `Pane` or another layout
+  lets that child own the insets. A `Pane` header or footer whose only child is
+  a `Toolbar` hands the inline insets to the toolbar, so the toolbar's dividers
+  still reach the edge.
+
+A plain `Pane` follows the same rules. It assumes it may touch every screen edge
+unless its layout says otherwise. When your own markup puts panes side by side,
+say which sides each pane reaches with `safeAreaEdges`:
+
+```tsx
+<div class="app-columns">
+  <Pane label="Library" safeAreaEdges={['block-start', 'block-end', 'inline-start']}>…</Pane>
+  <Pane label="Reader" safeAreaEdges={['block-start', 'block-end', 'inline-end']}>…</Pane>
+</div>
+```
+
+An app bar or bottom bar that sits directly at a screen edge, outside any
+`Pane` header or footer, claims its edges the same way. A `Toolbar` only pads
+the inline edges an owner hands it until you list the sides it reaches:
+
+```tsx
+<List fill>
+  <Toolbar
+    label="App bar"
+    safeAreaEdges={['block-start', 'inline-start', 'inline-end']}
+    leading={<ToolbarText text="Atlas" />}
+  />
+  <Row gap="none" flex>…panes that list block-end and their outer side…</Row>
+</List>
+```
+
+Each claimed side pads by the edge context, or the full device inset when
+nothing routes that edge, while the bar's surface and divider still reach the
+screen edge. A claimed toolbar inside a `Pane` header or footer adds nothing
+extra, because the pane already owns those edges.
+
+Pass `safeAreaEdges={[]}` for a pane that never sits at a screen edge. For a
+region you own, set `--kui-edge-inset-block-start`, `--kui-edge-inset-block-end`,
+`--kui-edge-inset-inline-start`, or `--kui-edge-inset-inline-end` to `0px` on the
+region for each edge it does not reach, and kerf descendants follow. A
+`CollapsiblePanel` does this for its direct flex siblings automatically. A
+panel wrapped in your own grid cell cannot see its siblings, so route those
+edges yourself.
+
+The device insets come from `--kui-safe-area-block-start`, `-block-end`,
+`-inline-start`, and `-inline-end`, which default to `env(safe-area-inset-*)`.
+Override them on `:root` to reserve room for app-owned chrome or to simulate a
+device in tests.
+
 ## Decision matrix
 
 | Situation                                                                    | Layout                                                                                          | Device threshold                                                                                                                   |

package/docs/catalog.md

@@ -23,8 +23,8 @@ npm install @kerfjs/ui # kerfjs is a peer; @kerfjs/ui/select/register is needed
 
 - **`sections`** — category-grouped entries: `{ category, entries: [{ id, name,
 description?, tags?, resources?, related? }] }`. Each entry becomes a sidebar
-  `ListItem` under a `ListHeader` for its category. Short `tags` render as quiet
-  trailing pills for decision metadata such as `Discouraged`.
+  `ListItem` under a `ListHeader` for its category. Short `tags` render through
+  the row's quiet status treatment for decision metadata such as `Discouraged`.
 - **`content`** — the rendered preview for the active entry. Keep a map of `id →
 () => SafeHtml` in your app and call `renderers[active]()` in your render.
 - **`brand`** — `{ title, subtitle?, logoUrl? }` for the sidebar header.
@@ -54,10 +54,25 @@ chosen component.
 
 Classify every entry before rendering it:
 
-| Entry kind            | Preview purpose                                                         | Geometry overlay                                                                    |
-| --------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| Focused component     | Show one public component, its meaningful variants, and adverse states. | `true`; the overlay inspects each selected specimen.                                |
-| Composition or recipe | Show several components cooperating as one product surface.             | `false`; child geometry remains unmarked so the composition can be read as a whole. |
+| Entry kind      | Preview purpose                                                                                         | Geometry overlay                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Component**   | Show one public component, its meaningful variants, and adverse states.                                 | `true`; the overlay inspects each selected specimen.                                |
+| **Composition** | Show components commonly used together in one focused container or surface.                             | `false`; child geometry remains unmarked so the composition can be read as a whole. |
+| **Recipe**      | Teach the recommended production approach to a specific task, including ownership and application glue. | `false`; child geometry remains unmarked so the complete approach can be read.      |
+
+These three kinds are exhaustive. Theme/foundation showcases use a functional
+category, third-party specimens use source metadata, and state galleries retain
+the kind of the thing they demonstrate; none needs another demo kind.
+
+Organize the catalog by functional group, with groups in descending product
+importance. Within every group, list all component demos before all composition
+demos. Order each kind by descending importance where a meaningful distinction
+exists, then alphabetically by display name to break ties. Put recipes after all
+component/composition groups, ordered by the same importance-then-alphabetical
+rule. Treat source order as the authored importance order when no explicit rank
+field exists. Show a `Composition` tag rather than repeating the word in a
+composition's display name; the generic `Catalog` accepts that through the
+entry's `tags` array.
 
 Keep `geometryOverlay` present and compute it from the active entry. Do not make
 it a permanent catalog-wide `true`, and do not give individual specimens their
@@ -76,6 +91,18 @@ own overlay implementation.
   generated note, then one specimen or one intentionally coupled specimen
   cluster. Use one row per variant/state; do not hand-author the helper's private
   classes.
+- Focused demos do not import local stylesheets, use inline `style`, or invent
+  styling-only `demo-*` classes. Prefer a public Kerf component, then a Web
+  Awesome surface when Kerf has no equivalent, then ordinary semantic HTML.
+  Use `CatalogExample.viewport` for bounded specimen width, height, frame,
+  surface, overflow, responsive visibility, and public custom-property values;
+  keep those constraints catalog-owned instead of recreating a demo stylesheet.
+  Component heights run `short` (220px) through `tall` (360px); frame an app
+  shell, whole-screen layout, or other application-sized recipe with
+  `height: "app"` (592px), and give its root `fill` rather than a frame `Pane`.
+  An app frame stands in for the screen: it is the containing block for
+  screen-fixed chrome, so a compact `CollapsiblePanel` overlay, its backdrop,
+  and restore controls dock to the frame's edges rather than the page's.
 - The specimen is an immediate child of `CatalogExample`. A focused component
   row should place the component root there, without a decorative card or
   spacing wrapper. A composition row may place the composition root there.
@@ -128,6 +155,9 @@ from structurally widened or JavaScript objects. Do not copy the helpers'
 private `kui-catalog-*` classes into preview markup.
 
 The app owns entry ids, `kind`, routing, sources, relationships, and test hooks.
+`Catalog.stageRootAttributes` places app-owned `data-*` state on the
+catalog-owned preview stage without an extra wrapper; `data-catalog-stage`
+remains protected.
 The helpers own their structural markers, label/note anatomy, alignment marker,
 and private classes. Component metadata such as margin/border/padding ownership
 lives in `component-catalog.json`; do not infer or overwrite it from overlay
@@ -189,7 +219,13 @@ facts that source can prove without guessing at rendered intent:
   are not empty, and composition routes do not add redundant skip markers;
 - every `@kerfjs/ui` import is a published package export and relative imports
   do not reach into `ui/src`;
-- demo JSX does not copy private `kui-catalog-*` structural classes; and
+- focused demos have no relative stylesheet imports, inline style attributes,
+  or styling-only `demo-*`, `wa-demo-*`, and token-search class names;
+- demo JSX does not copy private `kui-catalog-*` structural classes;
+- recipe sources (checked by `npm run check:recipes` with the same shared
+  analyzer) import no stylesheet other than public `@kerfjs/ui` CSS, set no
+  inline style, and name only published layout and Web Awesome classes; each
+  recipe declares its catalog frame through an exported `presentation`; and
 - the shell derives both geometry-overlay enablement and documented demo mode
   from the active entry's source and kind.
 
@@ -202,7 +238,7 @@ stage geometry is itself the reviewed specimen. Add the narrow waiver to
 [`catalog-conformance-exceptions.json`](../ux-demo/catalog-conformance-exceptions.json)
 with the exact route, source file, stable diagnostic ids, a substantive reason,
 and the reviewing `KF-*` ticket. Only helper/metadata rules are waivable;
-private imports, private markup, empty examples, composition overlay drift, and
+private imports, local styling, private markup, empty examples, composition overlay drift, and
 shell-mode drift always fail. The gate rejects duplicate, malformed, unused,
 and stale exceptions, so delete a waiver when its route adopts the standard
 helpers.
@@ -262,7 +298,10 @@ const entries: DemoEntry[] = [
 const sections: CatalogSection[] = [
   {
     category: "Examples",
-    entries: entries.map(({ kind: _kind, ...entry }) => entry),
+    entries: entries.map(({ kind, ...entry }) => ({
+      ...entry,
+      tags: kind === "composition" ? ["Composition"] : undefined,
+    })),
   },
 ];
 

package/docs/collapsible-panel.md

@@ -37,25 +37,85 @@ Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.
   is the app's: put a collapse toggle in the panel's own header and an expand toggle
   somewhere always-visible (a toolbar) so it is reachable while collapsed.
 - **`wireSidebar(root, { panels, deviceClass?, storage? })`** — the interaction
-  semantics. Each `panels` entry is `{ id, collapsed, toggleAction, storageKey? }`.
-  It:
+  semantics. Each `panels` entry is
+  `{ id, collapsed, toggleAction, storageKey?, inlineCollapsed? }`. It:
   - **toggles** the panel's `collapsed` signal when any `[data-action=toggleAction]`
     button is clicked, and remembers the trigger;
   - **manages focus** — moves focus into the panel when it opens, and restores it
-    to the trigger when it closes;
+    to the trigger when it closes. When that trigger is the collapse toggle inside
+    the now-hidden panel, focus goes to the panel's toggle outside it instead, so
+    an app may render its expand toggle only while the panel is collapsed (one
+    control per action, as the recipe does);
   - **presents a compact overlay** when `deviceClass.compact` is true (pass a
     `deviceClass()` signal): the open panel floats over the content with a
     dismissable backdrop, Escape and backdrop-click collapse it, and Tab is trapped
-    within the panel (the ARIA dialog pattern);
+    within the panel (the ARIA dialog pattern). The overlay and its backdrop are
+    fixed to the screen; an ancestor that establishes a containing block for
+    fixed descendants (such as the catalog's `height: "app"` frame) docks them to
+    its edges instead;
   - accepts `compactPresentation: "hidden"` when a compact application replaces
     the panel with different navigation instead of overlaying it;
+  - **starts every compact overlay closed** (see
+    [Compact initial state](#compact-initial-state));
   - keeps compact overlays exclusive by default, collapsing another open panel
     when a new one opens (`exclusiveCompact: false` opts out);
-  - **persists** the collapsed state to `storage` (default `localStorage`) under
-    `storageKey`, seeding the signal on wire-up.
+  - **persists** the inline collapsed state to `storage` (default
+    `localStorage`) under `storageKey`, seeding the signal on wire-up. An
+    overlay's open/closed state is never persisted;
+  - **owns the root's `data-collapsible-responsive` / `data-collapsible-overlay`
+    attributes and the injected backdrop.** Your app may re-render (and morph)
+    the wired root for reasons that never touch a panel signal — a nav
+    selection, say — and the morph drops attributes and nodes its template
+    doesn't emit. The wire observes the root and re-applies them before the
+    next paint, so don't render these attributes yourself.
 
   Returns a disposer. Retain it and call it on teardown.
 
+## Compact initial state
+
+A compact overlay is transient chrome the user summons, like a slide-over
+sidebar on a phone: it covers the content, traps focus, and must be dismissed.
+It therefore opens **only on a user action** (a toggle, or the app setting the
+signal in response to one), never by itself:
+
+- **Wire-up on a compact device.** Every panel starts collapsed, whatever its
+  signal, `inlineCollapsed`, or stored choice says. No backdrop, focus trap, or
+  Escape handling is active until the user opens a panel.
+- **Wide → compact crossing.** Open panels collapse; nothing covers the page.
+- **Compact → wide crossing.** Each panel returns to its remembered inline state
+  (open or collapsed), whatever the user did with the overlay meanwhile.
+- **Disposal** hands the inline state back to the signals.
+- **Persistence** records only the inline choice. A stored "open" rail restores
+  inline on a wide screen and is remembered, not opened, on a compact one.
+
+These presentation changes never move focus, except to rescue focus that a
+collapse would strand inside the hidden panel (it returns to the panel's last
+trigger). `compactPresentation: "hidden"` leaves the signals alone.
+
+`wireSidebar` runs after the first render, so an app that seeds an open inline
+default would render the rail open for that first frame on a compact device.
+Seed the signal from the device class instead, and declare the inline default
+with `inlineCollapsed` so a later wide crossing still opens it:
+
+```ts
+const device = deviceClass();
+const navCollapsed = signal(device.value.compact);
+// …
+wireSidebar(app, {
+  panels: [
+    {
+      id: "nav",
+      collapsed: navCollapsed,
+      toggleAction: "toggle-nav",
+      inlineCollapsed: false,
+    },
+  ],
+  deviceClass: device,
+});
+```
+
+A stored inline choice takes precedence over `inlineCollapsed`.
+
 ## Example
 
 ```tsx
@@ -68,8 +128,10 @@ import {
 import { wireSidebar } from "@kerfjs/ui/wire-sidebar";
 import "@kerfjs/ui/collapsible-panel.css";
 
-const navCollapsed = signal(false);
 const device = deviceClass();
+// Start collapsed on a compact device; `inlineCollapsed` keeps the open inline
+// default for wide screens.
+const navCollapsed = signal(device.value.compact);
 
 const app = document.querySelector("#app")!;
 mount(app, () => (
@@ -111,12 +173,22 @@ const stop = wireSidebar(app, {
       collapsed: navCollapsed,
       toggleAction: "toggle-nav",
       storageKey: "app.nav-collapsed",
+      inlineCollapsed: false,
     },
   ],
   deviceClass: device,
 });
 ```
 
+## Safe areas
+
+A panel grows by the unsafe inset of the edge it docks to and pads its content
+for every edge it touches except its interior edge. While expanded inline, it
+also clears that edge for its direct flex siblings, so a neighboring pane gains
+the inset when the panel collapses. When you wrap the panel in your own grid
+cell, set `--kui-edge-inset-*: 0px` on the sibling regions yourself (or pass
+`safeAreaEdges` to a sibling `Pane`). See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
 ## When to use which
 
 - One or two independent rails / a drawer you place yourself → **`CollapsiblePanel` +
@@ -138,5 +210,6 @@ persistence: [open it](../ux-demo/?component=recipe-collapsible-sidebar) or read
 [`recipes.md`](recipes.md#collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx).
 It is covered end-to-end across Chromium, Firefox, and WebKit by
 `tests/browser/collapsible-sidebar-recipe.spec.ts` (collapse/expand, focus
-move/restore, the compact overlay + Escape/backdrop dismiss, and the Tab trap),
+move/restore, the compact overlay + Escape/backdrop dismiss, the Tab trap, and
+the compact initial state across first load and wide/compact crossings),
 alongside the component/wire unit tests.

package/docs/component-contract.md

@@ -36,6 +36,19 @@ bounded `items[].property` form. Consumer catalogs can publish the same facts;
 ESLint, `kerf-ui-analyze`, and `kerf-ui-doctor` then issue the same stable
 `KUI-L013`–`KUI-L017` feedback for application and third-party components.
 
+`wiring.stateAttributes` lists the **wiring-owned state attributes**: the
+`data-*` attributes a wiring helper writes at runtime, such as
+`data-handle-inset` and `data-resizing`, which `wireResizableRegions` puts on a
+`ResizableRegion`. Each entry names the attribute, the element that carries it
+(`on`), the `helper` that writes it, and what it means. An application must not
+render, remove, or treat these attributes as its own state; tools use the list
+to tell them apart from app-authored attributes. They are declared once, on the
+helper's wiring item in the v1 catalog, and v2 flattens them. `check:catalog`
+reads each `wire*` helper's source and fails when its declarations differ from
+the `data-*` attributes it actually writes. First-party entries always carry
+the list, empty when their helpers write none; it is optional in extension
+catalogs.
+
 The generator starts with permissive defaults. An `any` mode records that the
 catalog has no defensible prohibition; it does not claim every composition is
 recommended. Objective rules live in
@@ -54,6 +67,21 @@ explicitly. Zones without that binding remain guidance and are never guessed
 from their ids. Static tools inspect only visible JSX structure and leave
 dynamic `SafeHtml` expressions to runtime and accessibility evaluation.
 
+### Native named-slot assignment
+
+Every public visual component with one stable conceptual root accepts an
+explicit `slot?: string` prop and forwards it to that root on every render
+branch. Use it when a Kerf component is a light-DOM child of a custom element,
+for example `StateBanner({ title: 'Ready', slot: 'status' })`. Omitting the prop
+omits the attribute.
+
+This contract does not open a generic native-attribute bag: components still
+accept only their documented props and narrow extension-attribute objects.
+`ResizableRegion` and `CollapsiblePanel` are deliberately excluded because each
+can return a region plus a sibling restore control, leaving no single root that
+can truthfully own native slot assignment. Their single-root controls and all
+alternate-root branches of supported components retain the contract.
+
 V1 consumers continue unchanged. V2 consumers read v1 for selection/delivery
 and v2 for composition. `npm run catalog:sync` projects every new component,
 recipe, and supported Web Awesome entry, and the completeness gate prevents
@@ -159,7 +187,7 @@ claim Kerf delivery paths for them.
 - Applications own signals/stores, product copy, domain-state mapping, persistence, routing, permissions, and transport.
 - Actions are `data-action` strings. Wire them at a stable root with `delegate()` or `delegateActions()` and retain the disposer.
 - A reusable component never owns per-instance mutable module state.
-- Consumers style through `--kui-*` semantic tokens and public component classes. Foundation tokens provide opinionated neutral, brand/info, non-status pop, success, warning, and danger fill/border/foreground roles. Stateful components expose local override variables; prefer an equivalent prop or token before writing a selector.
+- Consumers configure presentation through component props and documented `--kui-*` semantic tokens. Foundation tokens provide opinionated neutral, brand/info, non-status pop, success, warning, and danger fill/border/foreground roles. Application stylesheets must not select package component classes or descendants. If genuinely new structure needs CSS, encapsulate that structure and its stylesheet in an application-owned component; configure any nested Kerf components through their public APIs.
 
 `ListItem.rootAttributes`, `ListActionRow.rootAttributes`,
 `ListHeader.rootAttributes`, `AppTab.rootAttributes`,
@@ -194,23 +222,29 @@ visual anchor.
 ### Public CSS anatomy
 
 The `publicClasses` array on each entry in
-[`component-catalog.json`](../ai/component-catalog.json) is the exact supported
-anatomy boundary. A scoped selector may join documented public classes, such as
-`.workspace .kui-toolbar .kui-toolbar__trailing`, when composition-specific
-layout cannot be expressed by a prop or token. A class being public does not
-make copied component markup an invocation or transfer state and accessibility
-ownership to the application.
+[`component-catalog.json`](../ai/component-catalog.json) identifies stable
+anatomy for diagnostics, tooling, browser assertions, and package-owned
+composition. It is not an application customization API. Applications choose
+documented props and tokens; package components may compose other components
+only through those public contracts, never by styling a child's classes from a
+parent stylesheet.
 
 The v2 composition catalog additionally requires `boundaries.rootClass` to be
 either one exact member of `publicClasses` or `null` when the entry has no
 rendered class root. Runtime geometry tooling uses this explicit field; array
 order never implies root ownership.
 
-Do not select a component's descendant by element name, id, attribute alone, or
-an unlisted implementation class. Selectors such as `.kui-state-banner span`,
-`.kui-list-item [data-state]`, and `.kui-list-item .local-label` depend on
-private structure. If no prop, token, or cataloged class expresses a recurring
-need, request a supported hook instead of inferring one from rendered markup.
+Do not select a component root or descendant by class, element name, id, or
+attribute. Selectors such as `.workspace .kui-toolbar`,
+`.kui-state-banner span`, and `.kui-list-item [data-state]` cross the ownership
+boundary. If no prop or token expresses a recurring need, add the configuration
+to the owning component instead of inferring it from rendered markup.
+
+`Badge` owns the complete visual treatment for compact status, count, category,
+and metadata labels. Configure its semantic `tone`, `appearance`, `shape`, and
+`size`; do not recreate or override badge anatomy in an application or consuming
+component. Use `label` when visible content is abbreviated and `ariaHidden` only
+when a surrounding component already includes the same value in its accessible name.
 
 `ListItem` renders its leading icon and nested SVG at a root-scaled 18px by
 default while retaining the row's 44px minimum interactive target. Multiline
@@ -240,9 +274,8 @@ the logical end while the visible glyph defaults to 18px through
 
 `StateBanner` exposes instance-level `--kui-state-banner-background`,
 `--kui-state-banner-border`, `--kui-state-banner-foreground`,
-`--kui-state-banner-detail`, `--kui-state-banner-badge-background`,
-`--kui-state-banner-badge-foreground`, and action background variables. Its optional
-badge is a compact pill beside the title and follows the banner tone by default. Its five built-in
+`--kui-state-banner-detail` and action background variables. Its optional
+badge composes `Badge` beside the title and follows the banner tone by default. Its five built-in
 tones can be rethemed globally with
 `--kui-state-banner-{tone}-{background|border|foreground}`. Toolbar control,
 segmented-control, app-tab, and tab-bar colors likewise use their public
@@ -286,8 +319,10 @@ props. Its opaque string brand improves authoring correctness; it is not a CSS
 sanitizer or security boundary.
 `Row.flex` and `List.flex` likewise accept their boolean default, finite keywords, or `CssFlex`
 from `flex(grow, shrink, basis)`. `Skeleton` width/height use `CssSize`, radius
-uses `CssLength`, and `SelectChoice.color` uses `CssColor` from `uiColor()` or
-`colorVar()`. Never exchange these property grammars. List rows expose
+uses `CssLength`, and `SelectChoice.color` uses `CssForegroundColor` from
+`uiColor()` with a foreground token such as `success-on-quiet`, or from
+`foregroundColorVar()`. Fill tokens such as `success` are pale background tints
+and do not type-check there. Never exchange these property grammars. List rows expose
 `className`, public tokens, and semantic props instead of unrestricted `style`
 declarations.
 `.kui-content` gives major children 24px vertical separation.
@@ -299,21 +334,39 @@ changing geometry. `.kui-content-item--pill` selects the 22px radius.
 text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
 groups and inside items. For an ordinary icon/action control inside a group, use
 a plain `<button>` — the group styles `> button` fully, and it keeps the group
-free of a Web Awesome dependency and shadow DOM. Reach for `wa-button` only when
-you need a Web Awesome feature, chiefly the `slot="trigger"` button of a
-`wa-dropdown` popup menu. For a compact mixed-content group, set
-`nestedDropdown`; a text-and-caret trigger grows to its intrinsic width while an
-icon-only trigger can remain square. Compact mixed controls retain the standard
+free of a Web Awesome dependency and shadow DOM. Use `ToolbarActionLink` when
+the action must retain native anchor navigation; the group owns its geometry,
+hover, and focus treatment. Set `overflow="scroll"` when a row of controls must
+stay inside the available toolbar width. Set `visibility="compact-only"` for a
+group that replaces wider toolbar controls below the Toolbar's compact container
+breakpoint; do not hide the group with an application class. Reach for
+`wa-button` only when you need
+a Web Awesome feature, chiefly the `slot="trigger"` button of a `wa-dropdown`
+popup menu. For a compact mixed-content group, set `nestedDropdown`; a
+text-and-caret trigger grows to its intrinsic width while an icon-only trigger
+can remain square. A compact icon `<button>` is a 32px circle, so a selected
+compact segment never becomes an oval. An icon-only `Select` joins a group as
+one more segment with its siblings' inset, radius, hover, and focus ring; only a
+lone Select grows the group to its icon-and-caret pill. Set `menuInset` to configure the dropdown menu surface
+without application `::part(menu)` CSS. Compact mixed controls retain the standard
 item padding, omit an internal separator, and let the raised selected item paint
-over the outer border instead of shrinking to an inset highlight. The short text
-trigger has an engine-stable 66px floor because WebKit
-does not include the shadow caret in the custom-element host's intrinsic width;
-raise `--kui-toolbar-dropdown-trigger-width` for longer localized copy.
+over the outer border instead of shrinking to an inset highlight. The Web
+Awesome trigger's shadow base owns max-content sizing, so icons, localized text,
+and the shadow caret determine the width without a fixed host measurement.
+The enclosing `Toolbar` owns zone alignment and responsive topology: use
+`centerAlign="stretch"` when the center group should consume its track, and
+choose `responsive="stack"` with `responsiveAt="compact" | "narrow"`,
+`responsive="wrap"` for a heading whose title must stay whole, or
+`responsive="center-priority"` instead of selecting its zone classes from a
+parent stylesheet. No policy clips an action: the trailing zone, and a stacked
+center zone, wrap whole groups onto another row.
 `ListHeader` similarly separates its dormant title and
 optional count or badge from its optional 44px action. Use the mutually
 exclusive `count`/`countLabel` pair for non-negative safe-integer section
 quantities; reserve `badge` for non-count `SafeHtml`. Do not concatenate counts
-into the section label. Do not add padding to pane shells,
+into the section label. Set `width="content"` to shrink-wrap while retaining
+normal header geometry; `inline` is the separate zero-outer-geometry mode. Do
+not add padding to pane shells,
 double child-owned geometry with wrapper insets, or create competing scroll
 owners. The [layout contract](./layout.md) lists the public roles and tokens.
 
@@ -354,6 +407,14 @@ render, hands in its own via `collapsible.signals`, drives it through
 `handle.open`/`handle.close`, or disables any individual behavior — so transient
 UI is consistent by default without every app reinventing it.
 
+A public subpath that exposes several visual components is a folder-backed
+surface. Put each component in its own source file and give each visual
+component exactly one owned stylesheet alongside it. Keep the public
+compatibility entrypoints implementation-free: the JavaScript/TypeScript
+entrypoint only re-exports the folder modules, and the CSS entrypoint only
+imports their owner stylesheets. A shared public name is not permission to put
+several component implementations or visual contracts back into one file.
+
 `wireTokenSearchFields` is a deliberate exception, not the rule for `wire…`
 helpers. Its collapse behavior was _rich and error-prone_ — reveal, focus
 transfer, Escape, empty-blur collapse, focus return — the kind of transient chrome
@@ -371,6 +432,13 @@ render the section body, so a managed helper would remove no real complexity. Re
 for a managed default only when the transient behavior is substantial enough that
 hand-rolling it produces genuine, inconsistent variation.
 
+TabBar itself owns the inline geometry around those mechanics. Its tab list is
+the only shrinking, horizontally scrolling region; `leading`, `trailing`, and
+`end` action regions remain fixed. Set `trailingPlacement="adjacent"` when the
+trailing action belongs immediately after the final tab and use `end` for a
+separate action pinned to the far edge. Applications own the action content,
+but must not restyle TabBar descendants to recreate that allocation.
+
 CSS, the generated wrappers that make it
 reachable, and the registration module are the package's only declared side
 effects.
@@ -421,4 +489,4 @@ Keep product adapters outside the package: connection-state maps, ticket empty-s
 
 ## Testing contract
 
-Each behavior has focused unit coverage and a real-browser flow through the production-backed catalog. Consumer bundle tests enforce subpath CSS reachability, transitive component styles, root/SSR isolation, optional registration boundaries, and the CSS-only Web Awesome theme boundary. Visual evidence supplements—never replaces—keyboard, focus, state, and event assertions.
+Each behavior has focused unit coverage and a real-browser flow through the production-backed catalog. Consumer bundle tests enforce subpath CSS reachability, transitive component styles, root/SSR isolation, optional registration boundaries, and the CSS-only Web Awesome theme boundary. `npm run check:css-ownership` rejects application selectors into Kerf or Web Awesome components, a non-minimal catalog compatibility stylesheet, or a return of the shared recipe stylesheet. Visual evidence supplements—never replaces—keyboard, focus, state, and event assertions.