@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.57

package/docs/app-layouts.md

@@ -44,7 +44,9 @@ the layouts handle the insets for you. There is nothing to configure:
   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
+  lets that child own the insets. That child fills the region — a `Workbench`
+  area or panel, a `NavStack` view, a `TabScaffold` scene — so a sole `Pane`'s
+  header stays pinned while its own content scrolls. 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.
 
@@ -79,13 +81,15 @@ 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.
+Pass `safeAreaEdges={[]}` for a pane that never sits at a screen edge. In an
+arrangement you own, give each `Pane` (and each edge-claiming `Toolbar`)
+`safeAreaEdges` listing only the sides its region reaches. The toolbar
+configurations layouts accept (a Workbench `mainToolbar` / `mainBottomToolbar`,
+and a Workbench panel's or `CollapsiblePanel`'s `toolbar`) forward
+`safeAreaEdges` to their `Toolbar` the same way.
+A `CollapsiblePanel` clears the edge it covers for its direct flex siblings
+automatically; a panel wrapped in your own grid cell cannot see its siblings,
+so pass the neighboring panes' `safeAreaEdges` 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-*)`.
@@ -129,6 +133,12 @@ device in tests.
   `content` a `NavStack`. On a tablet/desktop, render the same sections as a
   `Workbench` left rail instead of a bottom bar.
 
+Whatever the layout, call `wireScrollDividers(appRoot)` from
+`@kerfjs/ui/wire-scroll-dividers` once: every `Pane` a layout renders, every
+`NavStack`'s top chrome and bottom toolbar, and every `TabScaffold` bar then
+draw the line between the pinned chrome and the scrolling content only while
+content is scrolled beneath them, and toolbars need no divider of their own. See [Scroll dividers](layout.md#scroll-dividers).
+
 ## Dialogs
 
 Pick the dialog's inner layout by the same complexity axis, then apply the device

package/docs/catalog.md

@@ -281,7 +281,7 @@ import {
   wireCatalog,
   wireCatalogGeometryOverlay,
 } from "@kerfjs/ui/wire-catalog";
-import "@kerfjs/ui/styles.css"; // or import each primitive's CSS + @kerfjs/ui/catalog.css
+// A CSS-aware (browser-condition) bundler loads the Catalog's CSS with its import.
 
 type DemoKind = "component" | "composition";
 type DemoEntry = CatalogSection["entries"][number] & { kind: DemoKind };
@@ -396,9 +396,25 @@ revealCatalogEntry(app, initial, { block: "center" });
   Pass the same signal as `wireCatalog`'s `collapsed` option so the sidebar is
   wired as a Workbench rail (transient on small screens, focus handed to the
   relocated toggle).
-- **`headerPlacement` / `footerPlacement`** choose whether the entry toolbar and the
-  status + resource footer stay pinned (`fixed`, default) or scroll with the preview
-  (`scroll`) — useful where large text would leave pinned chrome little room.
+- **`headerPlacement` / `footerPlacement`** choose whether the entry toolbar and
+  description, and the status + resource footer, stay pinned (`fixed`), scroll with
+  the preview (`scroll`), or stay pinned while the entry pane is tall enough and
+  scroll with the preview when it is short (`auto`, the default) — so a short
+  window or large text never squeezes the preview out.
+- **`sidebar`** configures the sidebar rail — it forwards to the Workbench's left
+  rail: `size` (default 288px), `resizable` (`true` or `{ min, max }`),
+  `separator`, `collapseMotion`, `presentation`, `responsiveOverlayAt` (default
+  `narrow`), `compactOverlay` (default `inset`), and `toolbar` (the sidebar
+  header's `ToolbarConfig`). A resizable sidebar's width is app state like
+  `collapsed`: render your size signal as `sidebar.size` and pass the same signal
+  as `wireCatalog`'s `sidebarSize` (plus `sidebarStorageKey` to remember it).
+- **`mainToolbar` / `footerToolbar`** take the entry toolbar's and the resource
+  footer toolbar's `ToolbarConfig` (`dividerSides`, `centerAlign`, `responsive`,
+  `responsiveAt`, `safeAreaEdges`). The defaults are a wrapping entry toolbar
+  and a footer toolbar that stacks at `narrow`, all without dividers of their
+  own: `wireCatalog` wires `wireScrollDividers`, so the shell's panes draw
+  their chrome dividers only while scrolled; an omitted or
+  `undefined` field keeps them. Configure these instead of styling the shell.
 - **`theme`** is a global preference — the app's signal; `wireCatalog` only reports
   the toggle, the app applies the theme (the shell reads `theme` to show the toggle's
   opposite-state label). Omit `theme` to hide the toggle entirely.
@@ -415,7 +431,10 @@ matching options on `wireCatalog`) if they collide with your own action table.
 `Catalog` composes public components (`Workbench`, `Pane`, `Toolbar`, `List`,
 `ListHeader`, `ListItem`, `ListInsetText`, `Text`, …) and owns only the preview stage
 (the checkerboard and centered canvas), the geometry overlay, the example viewport
-options, and the brand mark's size. Import `@kerfjs/ui/styles.css` for the whole
-layer, or `@kerfjs/ui/catalog.css` plus `@kerfjs/ui/workbench.css` and each composed
-primitive's CSS. Like any Workbench it needs a definite containing height — the
+options, and the brand mark's size. A bundler that honors the `browser` export
+condition loads the Catalog's stylesheets and those of every component it renders
+internally with the `@kerfjs/ui/catalog` import alone — no dependence on which other
+subpaths the app happens to import. Without that condition, import
+`@kerfjs/ui/styles.css` for the whole layer, or `@kerfjs/ui/catalog.css` plus
+`@kerfjs/ui/workbench.css` and each composed primitive's CSS. Like any Workbench it needs a definite containing height — the
 `@kerfjs/ui/document.css` baseline's `.kui-app-root`.

package/docs/collapsible-panel.md

@@ -10,7 +10,10 @@ subpath-only, tree-shakeable modules that add nothing to the main barrel.
 npm install @kerfjs/ui # kerfjs is a peer
 ```
 
-Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.css`.
+A browser bundler that honors the `browser` export condition loads the panel's CSS
+and that of the components it renders (`Pane`, `Toolbar`, `ToolbarControlGroup`,
+`LucideIcon`) with `@kerfjs/ui/collapsible-panel`. Without that condition, import
+`@kerfjs/ui/collapsible-panel.css` plus those stylesheets alongside `foundation.css`.
 
 ## The pieces
 
@@ -57,7 +60,15 @@ Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.
   the rest of the page, including under the compact overlay's backdrop. The
   control takes `--kui-collapsible-panel-restore-z`, which defaults to two less
   than `--kui-collapsible-panel-overlay-z` (38); the backdrop defaults to one
-  less (39), so moving the overlay z-index moves both. Escape, a backdrop
+  less (39), so moving the overlay z-index moves both. While a left or right
+  overlay is open (the `wireSidebar` compact overlay, or
+  `presentation="overlay"`), the content's floating controls — restore
+  corners and any `FloatingToolbar` — are also hidden outright (out of the
+  tab order and the accessibility tree), so they never paint over the overlay
+  whatever stacking context the app creates; they return as it closes. The
+  overlay's own floating controls stay, and a bottom overlay hides nothing. A
+  horizontal `presentation="overlay"` `ResizableRegion` does the same for its
+  siblings. Escape, a backdrop
   press, or the panel's own close control reveals the control again, and a
   collapsed overlay leaves it clickable. `ResizableRegion`'s `restoreControl`
   follows the same rules, two below `--kui-resizable-region-overlay-z` (39).
@@ -118,8 +129,21 @@ Give a panel a `toolbar` (the same roles as a
 [Workbench panel toolbar](workbench.md#panel-toolbars)) and it composes its own
 top toolbar over a `Pane`, with an optional `footer` below its content:
 
-- `title` and `panelOnly` groups lead it and are available only while it is open;
-- `constant` groups and the standard `toggle: { action, name }` trail it.
+- `title` and `panelOnly` groups lead it and are available only while it is open,
+  as is optional `center` content;
+- `constant` groups and the standard `toggle: { action, name, showLabel?,
+hideLabel? }` trail it.
+
+The toolbar also takes the `Toolbar`'s configuration (`dividerSides`,
+`centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`); it draws no
+divider of its own unless `dividerSides` says so. The `Pane` under it draws
+the line under the toolbar only while its content is scrolled (see
+[Scroll dividers](./layout.md#scroll-dividers)), and takes the panel's `pane`
+(`PaneConfig`: `contentElement`, `contentLabel`, `separators`,
+`safeAreaEdges`, `chromeDividers`) — for example `{ contentElement: "nav",
+contentLabel: "Sections" }` for a navigation rail. An omitted or `undefined`
+field keeps the `Pane` default; without a `toolbar` there is no `Pane`, so
+`pane` is ignored.
 
 A standalone panel does not own the rest of the screen, so the app places a
 `CollapsiblePanelRelocated` in its own work-area toolbar: it renders the panel's
@@ -222,7 +246,6 @@ import {
   CollapsiblePanelToggle,
 } from "@kerfjs/ui/collapsible-panel";
 import { wireSidebar } from "@kerfjs/ui/wire-sidebar";
-import "@kerfjs/ui/collapsible-panel.css";
 
 const device = deviceClass();
 // Start collapsed on a compact device; `inlineCollapsed` keeps the open inline
@@ -289,10 +312,10 @@ panel to the compact overlay (`wireSidebar`) where the viewport cannot hold it.
 
 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).
+also clears that edge for every other direct child of its container, so a
+neighboring pane gains the inset when the panel collapses. When you wrap the panel in your own grid
+cell, pass each sibling `Pane` a `safeAreaEdges` that omits the edge the panel
+covers. See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
 
 ## When to use which
 

package/docs/component-contract.md

@@ -18,12 +18,33 @@ package delivery paths, Web Awesome's installed manifest, AI guidance, and
 documentation links. Nuanced prose in this contract and the selection guide
 remains authored rather than generated.
 
-### Composition catalog v2
-
-[`component-catalog-v2.json`](../ai/component-catalog-v2.json) adds a formal,
-machine-evaluable composition layer without changing the v1 selection and
-delivery contract. Every v1 entry projects once, in order, under the stable
-qualified key `package:id`. Each v2 entry explicitly covers parents/contexts,
+### Markdown component reference (AI entry point)
+
+[`ai/components/README.md`](../ai/components/README.md) and one
+`ai/components/<id>.md` page per catalog entry are the assistant-facing view of
+both catalogs. An assistant reads the index, then only the pages it uses,
+instead of loading the full JSON. Each page merges the entry's selection facts
+(purpose, use/avoid, alternatives), delivery (JavaScript subpath, CSS,
+registration, wiring helpers), a link into `public-api-signatures-v1.md` for
+exact props, composition (parents, contexts, zones with their JSX prop and
+cardinality, children), state and wiring ownership including wiring-owned
+state attributes, geometry, accessibility obligations, public class and token
+hooks framed as a styling boundary (components own their styles; configure
+through props rather than overriding internals), and `KUI-C###` diagnostics
+with their conditions. `scripts/sync-component-docs.mjs` renders them only from
+`component-catalog.json` and `component-composition.json` (plus the signature
+file's module headings for anchors), sorted and Prettier-formatted;
+`check:catalog` rejects a stale, missing, or orphaned page. The JSON files stay
+the canonical tool-facing sources.
+
+### Composition catalog
+
+[`component-composition.json`](../ai/component-composition.json) adds a formal,
+machine-evaluable composition layer beside `component-catalog.json` without
+changing its selection and delivery contract; it is a generated companion, not
+a newer version of that catalog. Every component-catalog entry projects once,
+in order, under the stable qualified key `package:id`. Each composition entry
+explicitly covers parents/contexts,
 named zones and cardinality, optional explicit JSX prop bindings, child concepts, state ownership, required wiring,
 responsive ownership, layout and geometry, accessibility obligations, public
 CSS boundaries, diagnostics, and provenance. A wrapper entry may add
@@ -31,6 +52,18 @@ CSS boundaries, diagnostics, and provenance. A wrapper entry may add
 composition checks treat its elements as each root rather than as an unknown
 child.
 
+`boundaries.placeableClasses` names the subset of `publicClasses` an
+application may write onto its own elements (layout utilities, the document
+root, item geometry on another carrier); absent means none, and every other
+public class is the component's rendered anatomy. `boundaries.rootElement`
+names the element a component renders around its own placeable classes
+(`content-item`: `div`), so a plain element of that tag carrying them is still
+the component recreated. `eslint-plugin-kerfjs`'s `ui-public-boundaries`
+reports both as `KUI-L103` with the export to render — for `@kerfjs/ui` and for
+every consumer catalog a `.kerf-ui-profile.json` declares, whatever the class
+prefix. `create-kerf-component` packages declare the same fields in
+`kerf.components.json`.
+
 An entry's optional `cssValueProps` makes CSS-adjacent prop grammar equally
 machine-evaluable. Each path records the property grammar, finite shorthands,
 canonical versus exceptional spacing choices, standalone and expression-only
@@ -46,7 +79,8 @@ ESLint, `kerf-ui-analyze`, and `kerf-ui-doctor` then issue the same stable
 (`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`
+helper's wiring item in the component catalog, and the composition catalog
+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
@@ -55,7 +89,7 @@ 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
-`component-catalog-v2-overrides.json` and may carry stable `KUI-C###`
+`component-composition-rules.json` and may carry stable `KUI-C###`
 diagnostics. A tool reports a diagnostic only after proving its exact `when`
 condition. Subjective choice, product policy, and visual taste remain prose.
 
@@ -64,7 +98,7 @@ Use `children` for one homogeneous primary region; use explicit named
 `SafeHtml` props for semantic positions or replacement content such as
 `header`, `footer`, `leading`, `trailing`, `icon`, and `action`. These are typed
 function-component props, not native web-component `<slot>` elements and not a
-generic `slots={{...}}` object. A v2 zone declares `jsx.prop` only when tooling
+generic `slots={{...}}` object. A composition zone declares `jsx.prop` only when tooling
 can soundly bind that zone to one public JSX prop; `children` is spelled
 explicitly. Zones without that binding remain guidance and are never guessed
 from their ids. Static tools inspect only visible JSX structure and leave
@@ -85,13 +119,14 @@ 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,
+Component-catalog consumers continue unchanged. Composition-aware consumers
+read `component-catalog.json` for selection/delivery and
+`component-composition.json` for composition. `npm run catalog:sync` projects every new component,
 recipe, and supported Web Awesome entry, and the completeness gate prevents
-silent omissions. Downstream catalogs use the v2 extension schema and types,
+silent omissions. Downstream catalogs use the composition extension schema and types,
 retain their own package identity, and qualify cross-catalog references. See
 the checked
-[`component-catalog-extension-v2.json`](./examples/component-catalog-extension-v2.json)
+[`component-composition-extension.json`](./examples/component-composition-extension.json)
 application-owned example.
 
 ### Compile-time contract boundary
@@ -117,10 +152,11 @@ layout/responsive conventions, and narrow rule exceptions there. Product
 records, copy, permissions, user preferences, and transport state do not belong
 in this policy file.
 
-Every catalog location names a v2 composition artifact. `selection` is optional
-for consumer packages whose generated metadata declares v1 selection guidance
-not applicable; `@kerfjs/ui` retains its required v1 selection artifact. This
-lets a generated `component-catalog-v2.json` participate directly without a
+Every catalog location names a composition artifact. `selection` is optional
+for consumer packages whose generated metadata declares component-catalog
+selection guidance not applicable; `@kerfjs/ui` retains its required
+`component-catalog.json` selection artifact. This
+lets a generated `component-composition.json` participate directly without a
 fabricated compatibility file.
 
 Discovery and precedence are deterministic:
@@ -147,6 +183,22 @@ I/O.
 See the
 [`application-ui-profile.json`](./examples/application-ui-profile.json) example.
 
+The package defaults avoid every `Discouraged` Web Awesome entry — each
+`webawesome` catalog entry whose `recommendation` is not `supported`, except the
+encouraged `wa-popup` primitive — under a concept whose `preferred` value is the
+Kerf component that wraps or replaces it (`command-menu` → `PopupMenu`,
+`value-selection` → `Select`, `application-tabs` → `TabBar`, `icon` →
+`LucideIcon`, `resizable-pane` → `ResizableRegion`, `exclusive-choice` →
+`SegmentedControl`, `hierarchy-navigation` → `List`, `embedded-media` →
+`ContentItem`). `eslint-plugin-kerfjs` `ui-preferences` (`KUI-L301`, also run by
+`kerf-ui-doctor`) therefore reports a Discouraged element written directly as a
+JSX tag (`<wa-dropdown>`) as well as through an imported component. A declared
+component's own source file is exempt, because that wrapper is the sanctioned
+owner of the element it renders. A unit test holds the avoid set and the
+catalog's Discouraged set equal in both directions, so neither can drift. A
+product that genuinely needs one of these elements records a narrow `KUI-L301`
+profile exception for the file that renders it.
+
 Catalog detail footers use one standard resource vocabulary and order. Build
 them with `catalogResources()` from `@kerfjs/ui/catalog-resources`: `Demo source`
 first, optional `Component source` and `Design template`, then `Guidance`.
@@ -232,7 +284,72 @@ 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
+Inside the package, a component never styles another component or writes
+another component's variables. When a child must adapt to a composing parent,
+the child styles itself in that context from its own stylesheet: the parent's
+class and state appear only in an ancestor compound, the styled compound is
+the child's own class (or one of the child's own unclassed internals below
+it), and the child reads context values the parent provides under the
+parent's name. `ResizableRegion` widens its edge extent by the unsafe inset a
+split `SplitView` provides, and a `Skeleton` derives its fill from a solid
+`Badge`'s on-solid color, both in their own stylesheets; an `AppTab` rounds its
+outer corners in a segmented `TabBar` and shares a fill-allocated strip from
+`app-tab.css`. A `PopupMenu` sizes
+its trigger and applies a group's `menuInset` in its own stylesheet, and an
+icon-only `Select` reads the control slot a `ToolbarControlGroup` provides
+(`--_kui-toolbar-control-group-slot-*`). A parent may still style its own
+elements keyed on a child's state, naming the child by class inside `:has()`
+(`:has(> .kui-select[open])`, or `TabBar` insetting a segmented strip that
+holds compact tabs), and it keeps styling raw native and raw Web
+Awesome children no kerf component owns, excluding kerf children by class
+(`wa-dropdown:not(.kui-popup-menu)`). `npm run check:css-ownership` enforces
+this in every component stylesheet (a `src/*.css` with a same-basename
+component), deriving the component names, the Web Awesome tags each component
+renders, and its composed children from `src/*.tsx`:
+
+- **Foreign classes.** Another component's class or `[data-component]` may
+  appear only in an ancestor compound or inside `:has()` / `:not()`; the
+  styled compound is the stylesheet's own class.
+- **Owned Web Awesome tags.** Kerf components are named by class, never by a
+  `wa-*` tag they render. A tag another component renders (`wa-dropdown`,
+  `wa-select`, `wa-option`, a `PopupMenu`'s trigger `wa-button`) — as the
+  subject, or as an ancestor whose internals the rule reaches — must be scoped
+  to that component by its class or excluded with `:not()`. A direct child
+  that cannot be the owner's internal
+  (`.kui-toolbar-control-group > wa-button`) needs no exclusion.
+- **Variables.** A stylesheet writes only its own `--_kui-<self>-*` private
+  variables, and never overrides a public `--kui-<other>-*` token that another
+  component reads. Shared foundation tokens (`--kui-layout-*`,
+  `--kui-color-*`, …) are not any one component's. Context a parent provides
+  is named after the parent.
+- **Context on any child.** Custom properties set on a subject that can be any
+  element (`.kui-x > *`, `> :not(…)`) also land on composed components' roots.
+- **Hook classes.** A class the component places on a composed kerf child's
+  root (`<ToolbarText className="kui-nav-stack__title">`, a class NavStack once styled) may not be styled;
+  the child styles itself in that context instead.
+
+The documented exceptions live with their reasons in
+`scripts/lib/css-ownership.mjs`, and an exception that stops matching fails the
+check, so the list only shrinks. The layout regions' inherited edge-inset
+context (`--kui-edge-inset-*` handed to a sole Pane or layout child and cleared
+for any other content, and a Toolbar clearing it for its zones) is the one
+design exception; the others name the open fix ticket.
+
+Applications and component packages built on the package follow the same
+rules, and the downstream tools enforce them against the composition catalog
+instead of package source: `kerf-ui-analyze` / `kerf-ui-doctor` report a rule
+whose subject is another package's component (`KUI-L019`), another
+component's private `--_*` variable (`KUI-L020`), an override of a token a
+typed prop sets (`KUI-L021`), and a hook class on a component's root
+(`KUI-L022`); `eslint-plugin-kerfjs`'s `ui-component-ownership` reports
+`KUI-L020` / `KUI-L021` in script. Both share the selector parsing in
+`analyzer/selectors.mjs` with `check:css-ownership`, and
+`check:css-ownership` fails when a component renders a Web Awesome tag the
+catalog does not list, so `KUI-L019` keeps covering every tag a kerf component
+renders. Each finding names the configuration to use and routes a missing
+prop to a component-gap report (see [the analyzer guide](./ui-analyzer.md#component-ownership-kui-l019kui-l022)).
+
+The 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.
@@ -258,11 +375,19 @@ rows align that 18px visual with the first inherited text line. The row clips
 descendant painting to its rounded root so labels, status, and dormant trailing
 content cannot escape its visible boundary. Rows with descriptions grow enough
 to keep their owned two-line label stack readable; use `multiline` when the
-primary label should wrap rather than truncate.
-
-`DisclosureArrow` uses an 18px root-scaled visual by default. Override
-`--kui-disclosure-arrow-size` on the component or its containing scope when a
-consumer needs another size. Kerf `Select` uses a separate Web Awesome expand
+primary label should wrap rather than truncate. A single-line row ends its
+primary label and description with an ellipsis before the trailing status
+slot, even when the label is one long word; a `multiline` row wraps instead,
+breaking a word wider than the label column (a long component or file name)
+rather than letting it run under the trailing slot. A string label in a
+`multiline` row gets line-break opportunities at its camelCase and acronym
+boundaries, so `QuickTicketComposer` wraps as `QuickTicket` / `Composer`
+rather than mid-word; breaking anywhere is only the last resort for a single
+word that is still too wide. The text and accessible name are unchanged. `ListActionRow` labels
+follow the same single-line and `multiline` rules before the trailing action.
+
+`DisclosureArrow` uses an 18px root-scaled visual by default. Pass its typed
+`size` prop when a consumer needs another size. Kerf `Select` uses a separate Web Awesome expand
 glyph contract, `--kui-disclosure-icon-scale: .5`; changing one contract does
 not implicitly change the other. Direction changes take the shortest rotation
 path; a 180-degree closed-to-open tie uses counterclockwise rotation.
@@ -304,7 +429,9 @@ inset. `ToolbarControlGroup` publishes its derived radius to nested toolbar
 highlights concentric when the group switches between pill and rounded shapes.
 
 `ResizableRegion` owns the Hot Sheet 2 split treatment: a persistent 1px
-separator with a compact grip that appears on hover or keyboard focus. Override
+separator with a compact grip that appears on hover or keyboard focus. The grip
+is drawn centered on the separator line even though the pointer target is wider
+than the line, so the handle never reads as offset into a pane. Override
 `--kui-resizable-region-separator-color`,
 `--kui-resizable-region-handle-color`, or
 `--kui-resizable-region-handle-active-color` on a region when its containing
@@ -341,9 +468,10 @@ and do not type-check there. Never exchange these property grammars. List rows e
 `className`, public tokens, and semantic props instead of unrestricted `style`
 declarations.
 `.kui-content` gives major children 24px vertical separation.
-`.kui-content-item` gives one child 8px inline margin, a real 1px border,
-8px padding, and 12px corners; border and background may be transparent without
-changing geometry. `.kui-content-item--pill` selects the 22px radius.
+`ContentItem` (`@kerfjs/ui/content-item`, rendering `.kui-content-item`) gives
+one child 8px inline margin, a real 1px border, 8px padding, and 12px corners;
+the border stays transparent unless `frame="framed"`, so framing never changes
+geometry. `shape="pill"` selects the 22px radius.
 
 `ToolbarControlGroup` is the unit of toolbar organization, even for dormant
 text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
@@ -357,13 +485,22 @@ 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; a popup menu is a `PopupMenu`, which renders its own
-trigger. For a compact mixed-content group, set `nestedDropdown`; a
+trigger. Nothing wraps inside a group: an icon sits beside its label on one
+row, and a group's controls never break onto a second line — the group sizes
+to its content and the enclosing `Toolbar`'s responsive policy relocates whole
+groups. 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
+without application `::part(menu)` CSS; the default `standard` keeps each menu's
+own inset (8px for a raw `wa-dropdown`, the Select listbox's 4px for a
+`PopupMenu`), while `compact` and `list-zero` apply to every nested menu. A
+`PopupMenu` and a `Select` draw one popup: the same caret that turns to face the
+open popup, fade-in surface, surface inset, row height and padding, reserved
+check column, current-row fill, and group titles, all read from one private
+popup-choice contract in `foundation.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 Web
 Awesome trigger's shadow base owns max-content sizing, so icons, localized text,
@@ -374,7 +511,12 @@ 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.
+center zone, wrap whole groups onto another row. The center zone never
+compresses below its content width, so when the leading identity, center, and
+trailing zones share a row that is too narrow, the leading title is what gives
+way: it truncates with an ellipsis (as a platform toolbar's title does) instead
+of the center group painting over it. When everything fits, the center group
+keeps its place, centered in the track between the leading and trailing zones.
 `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
@@ -400,6 +542,16 @@ padding + 24px icon + 8px gap) and 8px from the right edge for an icon-bearing
 row. Applications own the values, formatting, and whether an icon is decorative
 or meaningfully labeled.
 
+A row follows the settings-style key/value priority: the value keeps its
+content and the label gives way. The label and value are two content-sized
+columns that share the row's free space equally, each stopping once its content
+fits. A short value therefore stays whole on one line beside any label, and a
+long label takes the remaining width, wrapping at its spaces and ending a word
+wider than its column (a long component or file name) in an ellipsis before the
+value rather than running under it. A short label keeps its width beside a
+long value, which wraps; when both are long they split the row, so neither is
+starved.
+
 ## Imports and side effects
 
 Every component has an explicit JS and CSS subpath. In CSS-aware browser builds,