@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.100

package/llms.txt

@@ -6,64 +6,550 @@
 > generate correct, good-looking kerf UI — it is not a catalog to browse.
 
 ```bash
-npm install kerfjs @kerfjs/ui   # kerfjs is a peer; Web Awesome is an optional peer
+npm install kerfjs @kerfjs/ui # kerfjs is a peer; Web Awesome is an optional peer
 ```
 
 Import each component from its own subpath (`@kerfjs/ui/list-item`, `@kerfjs/ui/toolbar`,
 …); the browser build pulls that component's reachable CSS automatically, so do not
 maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 
+The sunken/lowered background is semi-transparent: Web Awesome's
+`--wa-color-surface-lowered` is mirrored by `--kui-color-surface-lowered` and
+used by `--kui-color-neutral-fill-quiet`. `SunkenPanel`, sunken
+`Pane`/`Workbench`/`TabNavigator` surfaces, and Web Awesome
+`appearance="sunken"` use that tint by default through their optional
+`--kui-sunken-panel-background` / `--kui-wa-sunken-background` override tokens.
+Each layer composites over its backdrop. Intentional nested layers create
+depth; avoid a wrapper or extra background that paints the same visual surface
+twice. Check contrast in both color schemes over the actual backdrop. See
+[contextual transparency](./docs/webawesome-theme.md#contextual-transparency).
+
+For arbitrary interactive help or popup content, use `openAnchoredSurface` or
+`openAnchoredSurfaceAt` from `@kerfjs/ui/anchored-surface`; see
+[AnchoredSurface](./docs/anchored-surface.md). The app owns content and actions.
+Inside a native `<dialog>`, `wa-dialog`, or `wa-drawer`, the surface stays
+interactive and closes with the dialog. It keeps an 8px viewport gutter
+(`viewportMargin`) and fits its height to the room beside the anchor, scrolling
+its content, so do not add media queries or `max-height` overrides.
+`tone: 'dark'` gives a popup anchored to dark media chrome the inverse tone of a
+`ToolbarControlGroup tone="dark"`; its content inherits the matching colors.
+For a public subpath containing several visual components, use a folder with one
+component per source file and one owned stylesheet per visual component. Keep its
+compatibility entrypoints implementation-free: JavaScript/TypeScript only re-exports
+the folder modules, and CSS only imports their owner stylesheets.
+
+### Shared semantic tones
+
+Use `ToolbarText tone="dark"` on a loud or photo-backed toolbar surface to
+match dark control groups. It applies to read-only headings and actionable
+titles at every size; default tone retains existing identity and heading colors.
+
+`SemanticTone` is the shared color-role type for `Badge`, `Chip`, `StateBanner`,
+and semantic `ContentItem` appearances: `neutral`, `info`, `pop`, `success`,
+`warning`, and `danger`. Import it as a type from `@kerfjs/ui`,
+`@kerfjs/ui/badge`, `@kerfjs/ui/state-banner`, or `@kerfjs/ui/content-item`.
+Use `info` for the role backed by the existing `--kui-color-brand-*` tokens.
+Migrate Badge/Chip `tone="brand"` to `tone="info"`; `BadgeTone` and
+`StateBannerTone` remain deprecated aliases of `SemanticTone`.
+
+## The rule: components own their styles
+
+Configure components through their typed props (size, density, inset,
+presentation, `ToolbarConfig`, `PaneConfig`, …); never restyle one from outside.
+No application or parent CSS may select a `.kui-*` class, a `[data-component]`
+root, a `wa-*` element a Kerf component renders, or its `::part()`s, and no
+writing another component's `--_kui-*` / `--kui-*` variables where a prop
+exists. When a component adapts inside another, it styles itself in that
+context in its own stylesheet. A missing prop is a component gap to report,
+not a reason to override — and your own components follow the same rule.
+
 ## How to build a screen (retrieval order)
 
+First make the design decision: state what the user must read or do, find the
+Kerf or consuming-app component whose purpose and interaction match, and
+configure it. Compose `Toolbar`, `List`, `Row`, `Grid`, `ContentItem`, and the
+other primitives before creating markup or CSS. A local component should own a
+real domain behavior or new structure; a wrapper made only to re-space or
+re-skin an existing component is the wrong choice. Ask what each `div`, `span`,
+fragment, class, and CSS rule contributes. Remove it if a component already
+owns the semantics, surface, inset, scrollport, or gap. Use the spacing scale
+to show relationships, keep useful negative space, and align neighboring text
+and control edges. Check the result against adjacent screens at wide and narrow
+widths. The concrete [decision pass](./docs/component-selection.md#decision-pass-before-jsx-or-css)
+explains when to reuse, compose, extend, or use native HTML.
+
 1. **Pick the component from the interface need**, not by appearance — read
    [component-selection.md](./docs/component-selection.md) (the problem→component
    matrix, with imports, wiring, ownership, and alternatives).
 2. **Get exact signatures before emitting code** — read
    [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) (real prop names,
    callback shapes, disposer return types).
-3. **For exhaustive, structured facts** (ids, exports, variants, `publicClasses`,
-   relationships, side effects) load the
-   [Machine-readable component catalog](./ai/component-catalog.json) — the
-   canonical checked-in source; its schema is alongside it.
-4. **Apply the rules below and in** [skill.md](./ai/skill.md).
+3. **Look up each component you use** in the
+   [component reference index](./ai/components/README.md) — one line per
+   entry — then read only those `ai/components/<id>.md` pages (1–7 KB each):
+   use/avoid, imports and side effects, a link to exact props, legal parents,
+   zones with their JSX prop and child count, app- and wiring-owned state,
+   geometry, accessibility, the styling boundary (configure through props;
+   never override internals), and `KUI-C###` diagnostics. Do not load the
+   large JSON catalogs just to choose or compose components; the pages are
+   generated from them.
+   **Tools and mechanical checks** use the JSON sources instead: the
+   [Machine-readable component catalog](./ai/component-catalog.json) (ids,
+   exports, variants, `publicClasses`, relationships, side effects, and
+   geometry ownership) — the canonical checked-in source; its schema is
+   alongside it. Also load the
+   consuming application's catalog extension when present; generate one from the
+   [Consumer catalog extension schema](./ai/component-catalog-extension.schema.json)
+   when app-owned components must participate in selection or alignment.
+   A tool loads the [Composition catalog](./ai/component-composition.json) — a
+   generated composition layer beside the component catalog, not a replacement
+   for it — to mechanically evaluate parents, contexts, zones/cardinality,
+   children, state, wiring (including the wiring-owned `stateAttributes` an app
+   must never render or remove), responsive/layout/accessibility rules, and
+   public boundaries. The component catalog stays the selection and delivery
+   surface; the composition layer joins catalogs by `package:id`. Consumer
+   composition catalogs use
+   [the composition extension schema](./ai/component-composition-extension.schema.json).
+   Load [compile-time contracts](./ai/compile-time-contracts-v1.json) for stable
+   `KUI-T###` ids, exact declaration symbols, and the boundary between rejected
+   source states and relationships that still require runtime/catalog checks.
+   Before generating application UI, discover `.kerf-ui-profile.json` with the
+   shipped [application profile API](./ai/application-ui-profile.mjs). Merge
+   package defaults, workspace policy, then parent-to-child directory policy;
+   honor its package-qualified preferences, approved theme/density, semantic
+   tokens, layout conventions, and narrow source-located exceptions. Validation
+   is catalog-aware per layer, including parent values later overridden by a
+   child; synchronous hosts use [application-ui-profile-sync.cjs](./ai/application-ui-profile-sync.cjs).
+   See the
+   [workspace profile example](./docs/examples/application-ui-profile.json).
+   A zone's optional `jsx.prop` is its only authoritative JSX binding; never
+   infer one from the zone id. Use `children` for one homogeneous primary
+   region and explicit named content prop slots for semantic positions or
+   replacement content. These slots use the recursive `KerfUiContent` type:
+   `SafeHtml`, runtime-empty boolean/nullish values, and readonly nested arrays.
+   Put conditionals and mapped component arrays directly in them; do not add a
+   `Fragment` only to satisfy types. Arbitrary strings, numbers, and signals are
+   rejected unless a component explicitly exposes a text position such as
+   `ListInsetText`. These are typed props, not native `<slot>` elements,
+   wrapper slot components, or a generic `slots` object. Leave unresolved
+   dynamic expressions unknown.
+   Stable single-root Kerf UI components separately accept the explicit native
+   `slot="name"` prop for light-DOM composition inside a custom element and
+   preserve it across rerenders. Do not infer arbitrary native-attribute
+   spreading from this narrow interop contract. `ResizableRegion` and
+   `CollapsiblePanel` remain excluded because their optional restore controls
+   make their output multi-root; `CollapsiblePanelToggle` remains slot-capable.
+4. **When authoring a component gallery**, load
+   [catalog-authoring.json](./ai/catalog-authoring.json), then follow its
+   authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract).
+   Use its component/composition/recipe taxonomy and functional-group,
+   importance, alphabetical-tie, and recipes-last ordering policy. Focused
+   demos and recipes use public components plus `CatalogExample.viewport`,
+   never local stylesheets, inline styles, or styling-only classes. A frame
+   that a top-layer specimen anchors to takes `viewport.anchorName`, and a
+   centered column takes `viewport.contentWidth` + `contentAlign`.
+5. **Apply the rules below and in** [skill.md](./ai/skill.md).
+6. **Before calling an integration complete**, run
+   [`kerf-ui-doctor`](./docs/ui-doctor.md). Its portable JSON report merges
+   profile/catalog, TypeScript, Kerf ESLint, and static analyzer diagnostics;
+   CSS-adjacent component props are checked from catalog `cssValueProps`, so
+   prefer its canonical shorthand or typed helper over raw CSS strings; a
+   `--wa-color-{tone}-fill-loud` override without a governing `on-loud` (same
+   or ancestor scope, possibly in a co-loaded stylesheet), or whose literal
+   pair measures below 4.5:1, is review finding `KUI-L018` (set both); CSS that restyles a component
+   (`KUI-L019`), touches its private `--_*` variables (`KUI-L020`), overrides a token a typed prop sets
+   (`KUI-L021`), or styles it through a hook class on its root (`KUI-L022`) is an error: configure the
+   component instead, and report a component gap when no prop exists; application-component imports may use TypeScript `paths` aliases; use `"ownership": "component"` with catalog `styleSources` to apply this boundary between an app's own components; repair source-located errors until exit 0. Use full mode for release gates;
+   generated `dist`/`coverage`, dependency, cache, evidence, and nested-worktree
+   directories are excluded consistently from every static stage.
+   [`kerf-ui-analyze`](./docs/ui-analyzer.md) remains available when only static
+   layout diagnostics are wanted; its review findings are a bounded human/AI
+   review queue rather than an objective aesthetic score.
+7. **Evaluate the running application** by explicitly enabling the doctor's
+   browser stage or directly invoking
+   [`kerf-ui-evaluate`](./docs/ui-evaluator.md). Preserve its `KUI-B###`
+   browser evidence and screenshots; record hierarchy/rhythm/density/aesthetic
+   ratings separately with a named reviewer rather than presenting them as
+   objective assertions.
+
+## Application interaction choices
+
+For ordinary server-backed freshness, prefer event-driven updates, subscriptions,
+or explicit user refresh when they meet the product need. Use fixed-interval
+polling when periodic sampling is genuinely required or no suitable update
+channel exists; choose the interval deliberately and cancel the timer when its
+owning view is disposed.
+
+Make cursor cues match enabled behavior: use a pointer for actionable targets,
+grab/grabbing or resize cues for actual drag and resize affordances, and a
+default or disabled cue when an action is unavailable. Keep the semantic
+control, keyboard behavior, focus treatment, and disabled state aligned with
+the cursor; the cursor alone cannot explain an interaction. See
+[accessibility contracts](./docs/accessibility.md) and
+[interaction principles](./docs/apple-hig.md#interaction).
+
+## Interface copy capitalization
+
+Follow Apple's split, the package default: **names are title style;
+descriptions are sentence style.** Title style: buttons, menu items and menu
+headings, popup-menu triggers, segments, `Select` choices, tabs,
+page/view/pane/dialog/toolbar titles, back labels, `ListHeader` and column
+headings, field labels, icon-only control names, and fragment
+`EmptyState`/`StateBanner` titles ("Save Draft", "Back to Inbox"). Sentence
+style: body copy, descriptions, details, messages, tooltips, placeholders,
+checkbox/switch/radio option text, and status lines ("Saved just now"). Title
+style capitalizes the first and last word and phrasal-verb particles ("Log
+In"); it lowercases articles, coordinating conjunctions, `to` in infinitives,
+`as`, and prepositions of four letters or fewer elsewhere. Keep brand spellings
+and user data as written. `kerf-ui-doctor` reports violations in known
+title-style labels as `KUI-D040`. See
+[Writing interface copy](./docs/writing.md#capitalization).
 
 ## Core rules (do the right thing)
 
+- **Prefer a Kerf UI component over a Web Awesome component over a raw HTML
+  tag**, using each for what it is good at. Never render a `Discouraged` Web
+  Awesome element (`wa-dropdown`, `wa-button-group`, `wa-select`, `wa-tab-group`,
+  `wa-icon`, …) directly; reach it only through the Kerf component that wraps or
+  replaces it (`PopupMenu`, `SegmentedControl`, `Select`, `TabBar`,
+  `LucideIcon`), and file a component gap rather than dropping to the raw tag.
 - **Reach for the primitive, not for CSS.** The package is built to look right
-  *unstyled*. Before adding `padding`, `margin`, `width`, `height`, `border`,
-  `background`, a wrapper card, or a decoration, check whether the component, the
-  pane, or the content-item already owns it — it almost always does. Prefer a
-  component prop or a `--kui-*` token; write CSS only for genuinely new structure,
-  and then only join a component's documented `publicClasses` (never reach in by
-  tag/id/attribute or an unlisted class).
+  without an application customization layer. Before adding `padding`, `margin`,
+  `width`, `height`, `border`, `background`, a wrapper card, or a decoration,
+  check whether the component, pane, or content-item already owns it. Prefer a
+  component prop — `FloatingToolbar inset`, `DisclosureArrow size`, `ListHeader
+headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
+  visibly bounded content item — over overriding its `--kui-*` token. CSS for genuinely new structure
+  belongs to the application-owned component that renders it and must not select
+  nested Kerf or Web Awesome components.
 - **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
-  own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
+  own the geometry (8px inline margin + 1px border + 8px padding). Render an
+  ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) with
+  typed `frame` (`none`/`framed`) and `shape` (`rounded`/`pill`) props instead
+  of hand-writing `<div class="kui-content-item">`. For a chat transcript, set
+  `bubble="start"` (other participants) or `bubble="end"` with
+  `appearance="brand-loud"` (the person's own messages): the item fits its
+  message up to 80% of the row. Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
+- **Opt into document globals explicitly.** Import `@kerfjs/ui/document.css`
+  once for border-box sizing, token-backed body/link presentation, inherited
+  native table-cell and form-control font metrics, zero body margin, and
+  zero-specificity semantic cursors for native controls (pointer, not-allowed
+  when disabled, text on text inputs). Put `.kui-app-root` on the one direct mount container only when a
+  percentage-height shell needs the provided `html` → `body` → app-root height
+  chain. Add `data-viewport="locked"` to that body-child root for a
+  full-viewport shell whose document never scrolls (`100dvh` and
+  `overflow: clip` on `html`, `body`, and the root). The baseline is not part of `styles.css` or component browser imports.
+- **Use compact layout options where needed.** `Text flush lineHeight="tight"`
+  fits short dialog copy, and `Text align="center"` centers wrapping status
+  copy; `ValueTable density="compact"` reduces row spacing,
+  with public row column, padding, and gap tokens for specific metadata layouts.
+  `ToolbarText size="xsmall"` suits a dense rail heading. The
+  `TokenSearchField` editor shrinks in narrow groups; its minimum width can be
+  set with `--kui-token-search-editor-min-width`.
+- **Label read-only field previews.** Use `FieldLabel` from `@kerfjs/ui/text`
+  in `ListInsetControl sides="trl"` above a `ContentItem` value. Connect its
+  id to the preview group's `aria-labelledby`; use the live control's own
+  `label` while editing.
+- **Use Toolbar zone options.** `responsive="trailing-priority"` moves an
+  expanded trailing control to a full second row at `responsiveAt`; the leading
+  title remains above it. Public leading-min-width, trailing-gap/justify, and
+  per-zone inline-padding tokens cover app-specific toolbar geometry.
+  In a stacked Toolbar, `ToolbarControlGroup placement="end"` places a collapsed
+  search at its row's trailing edge; `sizing="fill"` gives its expanded state a
+  full row and a reduced-motion-aware downward entrance.
+  `--kui-toolbar-inset: 0px` removes an embedded Toolbar's outer padding and
+  corresponding minimum-height allowance while preserving its zone gap and
+  safe-area compensation. For a shorter header embedded in a panel or card,
+  pass `density="compact"` (40px: a 34px control band and 3px block insets)
+  and give its groups `size="compact"`; never shrink a Toolbar with CSS.
+  Composites forward `density` from their `ToolbarConfig` (Workbench panel,
+  main, and bottom toolbars, CollapsiblePanel, NavStack, SplitView) and size
+  the groups they compose (panel toggles, the back button) to match; pass
+  `density` to `CollapsiblePanelRelocated` when its toolbar is compact.
+- **Name panel toggles in title style.** A panel toolbar's
+  `toggle: { action, name }` uses `name` as the toggle group's accessible name
+  and in the default "Show …" / "Hide …" label, so pass a title-style panel
+  name (`name: "Navigator"` gives "Show Navigator"); it is never recapitalized.
+- **Position region restore controls declaratively.** A ResizableRegion has a
+  background token, `contentOverflow="visible"` for an anchored popup,
+  top/bottom `restorePosition`, typed `restoreInset`, and
+  `restorePlacement="inline"` for normal flow. FloatingToolbar also has
+  `placement="inline"`, per-edge inset tokens, and `safeAreaInsets`.
+- **Configure list rows through their APIs.** `ListItem density="spacious"`
+  gives option rows more room. `multiline` wraps labels, with
+  `multilineIconAlign="center"` when the icon should center on the whole copy.
+  `divider` owns row separators and `state="drag-target"` paints the drop
+  target. For lines only between rows, give every row but the last
+  `divider="after"` (the last `"none"`); a row's corners are flat wherever a
+  divider line meets them, so the group rounds only its outer corners on
+  hover and selection. For a reorderable list, set `draggable` + `itemId` on `ListItem`,
+  `ListItemLink`, or `ListActionRow` rows and call `wireListReorder` (from
+  `@kerfjs/ui/wire-list-reorder`) once; it paints the dimmed dragging rows and
+  the before/after insertion line, supports Alt+Shift+ArrowUp/ArrowDown, and
+  reports `{ listId, sourceIds, target: { id, position }, source }` for
+  `reorderListItems`. The `dragging` / `dropPosition` props render the same
+  states from app-owned drag state. For keyboard row navigation in a
+  `scrollable` List, call `wireListFocusScroll` (from
+  `@kerfjs/ui/wire-list-focus-scroll`) once: it scrolls a keyboard-focused row
+  whose focus ring crosses the clip into view in Firefox and Safari too.
+  Public ListItem tokens set row, icon, label, and trailing geometry;
+  ListHeader `size="xs|sm|m|l|xl"` sets label scale independently of
+  `headingLevel` (`sm` keeps the current FieldLabel-sized uppercase style;
+  `m`/`l`/`xl` match themed h5/h4/h3). Its height, title padding, and border
+  tokens tune section density. A semantic `count` requires `countLabel` and
+  excludes other indicators; `badge` and `status` may render together, and
+  either may be explicitly `undefined` in conditional app state.
+  For a filled command list, scope `--kui-list-item-background`,
+  `--kui-list-item-color`, `--kui-list-item-border`,
+  `--kui-list-item-hover-background`, `--kui-list-item-hover-border`,
+  `--kui-list-item-selected-background`, `--kui-list-item-selected-color`,
+  and `--kui-list-item-selected-border` at the list or row boundary.
+  To align `ListItem` and `ListActionRow` rows in one list on a custom
+  leading inset, set `--kui-list-row-padding-inline` on the `List` (never
+  `--kui-list-item-padding-inline`, which moves only `ListItem` rows). Both
+  row kinds draw an 18px untiled leading icon by default, so their labels
+  align; resize both with `--kui-list-row-icon-size` on the `List` (never
+  `--kui-list-item-icon-size`, which resizes only `ListItem` icons).
+- **Use `Row` for horizontal and `List` for vertical layout.** Both expose
+  physical `hAlign`/`vAlign` props and typed gaps. Row defaults to left/full,
+  an `xs` gap, and no wrapping; List retains full/top and zero-gap defaults.
+  Use canonical physical `textInsets` or `controlInsets` sides in
+  `t`/`r`/`b`/`l` order; text geometry wins on overlapping sides.
+  `ListInsetText` and `ListInsetControl` inset every side by default and accept
+  the same `sides` grammar for selective edges.
+  List additionally supplies
+  optional typed `gap`, `flex`, vertical scrolling, and canonical
+  `dividerSides` (`t`/`r`/`b`/`l` order). It adds no list semantics; children own
+  those, and only one bounded region should own scrolling. Pass a finite spacing
+  shorthand (`gap="xs"`, `gap="m"`) or a complete `CssLength` from the CSS-free
+  `@kerfjs/ui/css-values` builders; raw CSS strings are rejected. Use `flex()`
+  for List flex, typed lengths for Skeleton geometry, and
+  foreground colors for choice icons and `LucideIcon.color`: `uiColor()` with an `*-on-*`/text token,
+  `foregroundColorVar()`, or `foregroundColor()` for a custom CSS color; fill tokens such as `uiColor('success-fill-quiet')` do not
+  type-check. Fills (a `ChoiceChips` swatch, a row `iconTile` color) take a
+  plain `CssColor`: `fillColor('#3b82f6')` for a custom CSS color, `uiColor()`,
+  or `colorVar()`; never `foregroundColor()` for a fill. These brands are intentionally
+  not interchangeable; rows use classes/tokens/props rather than raw `style`.
+  Set `LucideIcon.inline` for an icon in `Text` or prose; it changes the SVG
+  from block to inline-block without changing its inherited 1em size.
+- **Use `Grid` for equal-width columns.** Set a fixed positive `columns` count
+  or typed `minColumnWidth` for automatic container-width collapse, never both.
+  The app owns the outer width and child semantics; use custom CSS grid for
+  asymmetric/intrinsic tracks and `ResizableRegion` for adjustable boundaries.
+  `Grid.gap` and `Grid.flex` use the same typed grammars as Row.
+  `Grid.textInsets` and `Grid.controlInsets` select physical sides for the
+  standard 17px text and 8px control inset; text wins on overlap.
+  For selectable document tiles, use `selectionMode="multiple"` and a required
+  `ariaLabel`, with `ContentItem selectionMode="multiple"` children. Wire
+  `wireContentItems` for spatial arrow navigation and Enter/Space activation.
+- **Give a layout root `fill`, not a frame `Pane`.** A Row, List, or Grid that
+  is the sole layout root of a definite-height parent takes its full height
+  with `fill` and carries safe `data-*` markers through `rootAttributes`.
+  Inside a flex layout use `flex` instead.
+- **Keep Web Awesome on the shared inset tiers.** `webawesome.css` uses
+  `--kui-wa-control-inset` (8px controls/items) and
+  `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside
+  Accordion, Card, Details, Callout, and Include), while
+  plain Details keep their body flush while plain Accordion items inset both
+  trigger and body, framed Details use the 16px container inset only on the
+  trigger, and framed Accordion items use it on both regions;
+  `--kui-wa-container-inset` keeps Tab Panel at 16px. Dialog body and footer use
+  the surface (8px) and container (16px) tiers respectively, independent of the
+  dialog's shared `--spacing`. Override the tier at the narrowest useful scope
+  instead of restyling individual shadow parts.
+  Filled badges use each semantic variant's quiet fill with normal text for
+  WCAG-AA compact-copy contrast. Override
+  `--kui-wa-badge-filled-background` and
+  `--kui-wa-badge-filled-foreground` as a contrast-safe pair instead of adding
+  host selectors.
+  When a dialog provides another dismissal affordance, add `hide-actions` to
+  the `wa-dialog` host; the theme hides its directly exported `header-actions`
+  part without an unsupported chained `::part()` selector.
+  Checkbox and Radio Group option regions also receive the shared 8px inline
+  outer inset because those groups have no bordered field shell. The Color
+  Picker trigger receives the same inset for the same unbordered geometry.
+  Slider's complete interactive region uses the shared 8px logical inline outer
+  inset without shifting its already-aligned label.
+  Known Date's Month/Day/Year captions and bordered text-like field hints align
+  with field values at the shared 9px border-plus-padding inset. OTP Input's
+  label uses the same uppercase xs/650 treatment and its label and hint share
+  that 9px alignment.
+- `Select` requires a visible `label` or an `ariaLabel` for a visually hidden
+  accessible name. Set `multiple` with an array `value` for any number of
+  choices: the popup stays open while choices toggle and closes on an outside
+  press or Escape, and the closed control summarizes the chosen labels. A
+  toolbar filter menu adds `selectedPresentation="icon-only"` and a fixed
+  `triggerIcon`: the trigger shows that icon plus a count badge while any
+  choice is chosen, and its accessible name ends with the chosen labels.
+  Set `caret={false}` on an icon-only toolbar Select to make a round trigger;
+  a custom `renderSelected` icon stays centered, and the default keeps the
+  visible caret.
+  `SelectChoice.disabled` keeps an unavailable option visible but unselectable;
+  `disabledReason` adds its tooltip. For multiple selects, opt in to
+  `selectAllLabel` and `clearLabel` footer buttons to select enabled choices
+  or clear the value through ordinary change events. The app owns the updated
+  controlled value and localized action labels.
+  Icon-only Selects (single or multiple) and icon-only `PopupMenu`s show an
+  `aria-hidden` Web Awesome help tag repeating that name (and a Select's
+  choice) on hover and keyboard focus, hidden while the popup is open; the
+  register import installs it, so do not add a `title` or tooltip of your own.
+  The same installer tags an icon-only `<button>` or link inside a
+  `ToolbarControlGroup` named by `aria-label` (no visible text or `title`);
+  import `@kerfjs/ui/help-tags/register` once when a toolbar has such buttons
+  but no registered Select or PopupMenu.
+  The package names the internal combobox, including custom
+  selected content; consumers do not need shadow-DOM naming workarounds.
+  Import `select/register` once for the canonical animation lifecycle: stale
+  close/show completions cannot override a later request. Consumers must not
+  repair popup timing or anchor placement; raw Web Awesome selects stay native.
+  Use `hint` for supporting text below the control and `placeholderText` only
+  for the empty value inside it; loading placeholders retain the visible hint.
 - **Trust the defaults.** Render a control at its natural size and color (a
   `LucideIcon` is 24px); if it looks wrong, fix the surrounding layout, not the
   control. Never force a component's width/height to size it — that leaves a halo
   or a stretched oval.
+- **Make room for an expanded search instead of growing it past what fits.** A
+  collapsible search group grows into the space beside its sibling groups; if
+  that space is too small, the siblings wrap onto a new row while it opens.
+  Size the expanded search to what fits (`--kui-token-search-expanded-width`,
+  or `sizing="grow"` with a `growBasis` that fits), and if a useful search
+  cannot fit beside the other controls, set aside those controls while the
+  search is open: mark them `visibility="yield-to-expanded-sibling"` (they
+  leave a 480px-or-narrower toolbar while a sibling is expanded) or gather
+  them behind a "…" `PopupMenu` overflow group. The app decides which
+  controls yield.
 - **Toolbars hold only `ToolbarText` and `ToolbarControlGroup`.** Never put a bare
   button, input, link, or loose markup in a `leading`/`center`/`trailing` zone.
   Wrap every control — `SegmentedControl`, `Select`, a collapsible
-  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. A
-  toolbar popup menu is a `single` `ToolbarControlGroup` around a `wa-dropdown`
-  (its `slot="trigger"` `wa-button` is the toolbar button, kept under
-  `data-morph-skip-children`).
-- **`PanelHeader` is *the* panel/dialog/page heading.** A plain toolbar with an
-  optional bordered icon group, an extra-large `ToolbarText` title, the trailing
-  controls you pass, and an optional subtitle below — do not hand-build a heading
-  row or restyle a toolbar into one.
+  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. For an
+  ordinary icon/action control inside the group use a **plain `<button>`** (the
+  group styles it fully) — that is the default; reach for `wa-button` only when you
+  need a Web Awesome feature. A toolbar popup menu is a `PopupMenu`
+  (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`)
+  in a `single` `ToolbarControlGroup` with `nestedDropdown`; never hand-write
+  `wa-dropdown` markup for a menu. Let the group size the trigger from its icon,
+  localized text, and caret. Set `overflow="wrap"` for independent action links
+  that must remain fully visible at narrow widths; whole links move to a second
+  row, as in the catalog resource footer. `PopupMenu` items also support nested `submenu`
+  actions, headings, dividers, checked or trailing choice marks, danger tone,
+  and disabled reasons; nested headings/dividers stay out of keyboard choices;
+  use `context` with `anchor` + `openPopupMenu` (or `openPopupMenuAt`) and
+  `closePopupMenu` for pointer-anchored row menus; the menu owns its
+  zero-footprint anchor host, so add no wrapper or CSS. `openPopupMenuAt`
+  also opens a button-triggered menu at the pointer for one opening. A row's
+  trailing "…" overflow menu is `ListActionRow`'s `trailingMenu` (`label`,
+  `icon`, `items`, optional `placement` and `disabled`), which renders a
+  `PopupMenu` as the row's sibling trailing control. Do not force a dropdown or button width. Nothing
+  wraps inside a group: an icon sits beside its label on one row, and a
+  `ToolbarText` is one ellipsized line unless you opt into `wrap`/`maxLines`. A
+  Select or PopupMenu trigger drops its focus ring while its popup is open and
+  the ring follows the control's shape; never add ring CSS. Compact
+  mixed groups keep standard item padding and raised selected chrome without an
+  internal separator; the selected item paints over the outer border. For an
+  avatar control, set `content="avatar"` and `avatarImage` on the group instead of
+  inserting an `img`; a lone control paints the group and a multi-button group
+  paints only its pressed highlight. Dividers earn their place: a `Toolbar`
+  draws none by default and pinned chrome gets its line from scroll state (see
+  the scroll-divider rule below); never fake one with a border or pad below a
+  divider to make it look right.
+- **Use one direct toolbar composition for panel/dialog/page headings.** Put an
+  optional icon in a `ToolbarControlGroup`, an extra-large `ToolbarText` directly
+  in the leading zone, and actions in a trailing group. A short supporting
+  line ("Changes save automatically.") is the `ToolbarText` `description`:
+  quiet, one truncating line under the title, aligned with its text, with
+  `descriptionId` for `aria-describedby`. Longer copy is app-owned content
+  below. Do not create a private heading wrapper or restyle the
+  toolbar. A narrow peripheral rail or drawer, where extra-large would truncate
+  at its minimum size, names itself with the default `ToolbarText` size.
+  `ToolbarText size="xlarge-fixed"` keeps the 20px `--kui-font-l` heading step;
+  `xlarge` retains the responsive page-title clamp.
+- **Use `Text` for ordinary semantic headings, paragraphs, and inline secondary
+  text outside toolbar title zones.** Omit `variant` for the default `p`, pass
+  `h1`–`h6` based on the document outline, or use `variant="span"` inside a row,
+  label, or table cell without adding box geometry. Independently compose `tone="quiet|danger"`,
+  `size="compact|large|xlarge"`, and `font="monospace"` for supporting, error,
+  compact, prominent, display, and code roles instead of global utility classes. It passes native attributes
+  through; block variants own the standard transparent border plus item padding, while `span` owns none. Keep
+  toolbar titles on `ToolbarText` and list-aligned bare prose on `ListInsetText`.
+  Text supports `controlMargins` with canonical physical Sides for an exterior 8px control gutter; it preserves border/padding and avoids an isolated Row wrapper. Avoid stacking it with parent insets. Inline spans retain native inline margin behavior.
+
+  `ToolbarControlGroup.tileTone` selects `neutral`, `brand`, `success`, `warning`, or `danger` quiet fill, matching quiet border, and on-quiet foreground for a non-interactive icon tile. Compose a contained `single` group whose only child is a direct decorative LucideIcon (`aria-hidden="true"`). Omission preserves the normal group palette. The prop does not recolor interactive, mixed, multi-control, or borderless groups; keep real actions in controls with their existing focus/hover/pressed treatments.
+  `ListItem`, `ListItemLink`, and `ListActionRow` take `iconTile` to present their leading `icon` in a filled 32px rounded tile holding an 18px glyph, for settings or command rows that identify each entry by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`) for the same quiet fill, matching quiet border, and on-quiet foreground as `ToolbarControlGroup.tileTone`, or `{ color, foreground? }` for an application color: `color` is a `CssColor` (`uiColor()`, `colorVar()`, or `fillColor('#e5484d')`) and `foreground` a `CssForegroundColor`; without one, the glyph is black or white, whichever contrasts with the fill. The tile sits 6px clear of a standard 44px row (a compact row is at least 42px tall), moves the label to the tile's edge, and keeps its colors when the row is hovered or selected. Never wrap the icon in your own tile or resize the row's icon slot.
+  Toolbar zones accept `KerfUiContent` directly. Use `ToolbarText` for identity and `ToolbarControlGroup` for related controls that need its shared chrome; a bare control keeps its own styling and accessibility responsibilities.
+  Expanded search groups accept `expandedOverflow="visible"` to anchor app-owned suggestion/date/help surfaces below their relative root; collapsed/default groups retain existing clipping. Apps own surface placement/dismissal and use `data-token-search-keep-open` or `collapsible.keepOpenOn` for focus.
+
 - **Space by the five-step scale, by relationship not by eye.** `0`
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
   group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
-  regions). 12px/32px are off-scale exceptions.
+  regions). 12px/32px are off-scale exceptions. Prefer direct `Row.gap`/`List.gap`
+  shorthands for repeated rhythm; use `Spacer` for one typed empty width/height
+  or flexible main-axis gap. Use `space`, `px`, `rem`, `em`, `pct`, `lengthVar`, and
+  `calc(plus(...))` for typed runtime composition. `remify()` is source-CSS only.
+- **Keep nested highlight corners concentric.** Inset hover and selection surfaces
+  follow the owning control's pill or rounded shape; their radius is the outer
+  radius minus `--kui-layout-highlight-inset`. Do not give an inner highlight an
+  unrelated radius.
 - **Panes share one child-owned geometry.** Sidebars, main areas, inspectors, and
-  dialogs all use an unpadded `.kui-pane` (optional `.kui-pane__toolbar`, one
-  scrolling `.kui-pane__content`, optional `.kui-pane__footer`). A visible pane owns
-  its collapse control; a hidden pane's restore moves to the adjacent main
-  toolbar's matching edge — no icon-only rail. Keep one scroll owner per region.
+  dialogs all render `Pane`: an unpadded `.kui-pane` (optional header, one
+  scrolling `.kui-pane__content`, optional footer). Use `tabIndex={0}` for a
+  whole-surface Tab stop or `-1` for programmatic
+  focus on Pane, SunkenPanel, static ContentItem, or a plain TabNavigator scene;
+  `outlined` holds its standard focus ring for an app state such as a drop target.
+  Workbench uses `mainTabIndex`/`mainOutlined` for the center and
+  `tabIndex`/`outlined` per rail or drawer. Hidden scenes and collapsed panels
+  suppress those states. Never write a component's anatomy classes onto your
+  own element to recreate it (`KUI-L103`); only the catalog's `placeableClasses`
+  (layout utilities, `.kui-app-root`,
+  `.kui-content-item` on a non-div carrier) belong there. A visible pane owns
+  its collapse control (the last control of its last group); a hidden pane's
+  restore moves to the adjacent main toolbar's matching edge — no icon-only
+  rail — and a collapsed drawer's restore sits in the bottom toolbar or a
+  `FloatingToolbar` beside the drawer, near where its effect appears. Align
+  text to text and icons to icons across a pane; a border is decoration, never
+  the alignment anchor. Keep one scroll owner per region.
+- **Dividers between pinned chrome and scrolling content are scroll state.**
+  Toolbars draw no divider by default. Call `wireScrollDividers(appRoot)`
+  (`@kerfjs/ui/wire-scroll-dividers`) once and keep its disposer: every `Pane`
+  with `chromeDividers="scroll"` then draws the line under its header only while content is scrolled beneath
+  it and the line over its footer only while more content lies below (never
+  when the content fits), every `NavStack`'s top chrome and bottom toolbar and
+  every `TabNavigator` bar do the same around the active view or scene, and
+  every `TabBar` marks each side of its strip with tabs scrolled out of view. Configure a pane with `chromeDividers`
+  (`scroll` for a plain pane by default, `always` for a sunken pane by default,
+  or explicit `scroll`, `always`, `none`), and a `NavStack` or `TabNavigator`
+  with its own `chromeDividers` (same values; a `SplitView` forwards it through
+  `compactStack`); name app-owned chrome in `targets`.
+  A `TabNavigator` also takes `separator="auto" | "hidden"`: auto draws the
+  bar's top edge beside a sunken active scene or nested Pane even when content
+  fits; hidden suppresses that edge, including scroll dividers.
+  Never add a border, or a permanent `dividerSides`, to fake one.
+  For a header that floats over its scrolling content, set
+  `headerPresentation="overlay"` on the `Pane` (or in `PaneConfig`). It paints
+  the translucent chrome material (`--kui-chrome-material`, opaque under
+  reduced transparency, increased contrast, and forced colors). The same
+  `wireScrollDividers` call measures the header and publishes its height as
+  block-start scroll clearance, which the content clears automatically. Keep
+  overlay-header text in the normal text color.
+  For a translucent stack bar laid over the active view, set
+  `chromePresentation="overlay"` on the `NavStack`. `wireNavStack` measures
+  the top chrome and hands its height (top safe area included) to the views
+  as their block-start inset, so a plain view or a sole `Pane` clears it
+  automatically. Keep its text in the normal text color. For a translucent
+  bottom toolbar, set `bottomToolbarPresentation="overlay"` (separate from
+  `chromePresentation`); `wireNavStack` hands its height (bottom safe area
+  included) to the views as their block-end inset, so the last item rests
+  just above it. Its `ToolbarText` and default-tone `ToolbarControlGroup`
+  controls lift themselves to AA. For a translucent tab bar, set
+  `barPresentation="overlay"` on the `TabNavigator`; `wireTabNavigator`
+  measures the bar and the scenes hand its height to their content as the
+  block-end inset. Its tab labels lift themselves to AA.
+  While a side overlay is open (a Workbench rail overlay, a `wireSidebar` compact
+  overlay, an overlay `CollapsiblePanel` or horizontal `ResizableRegion`), the
+  layout hides the covered work area's `FloatingToolbar`s and restore corners
+  itself (unfocusable, out of the accessibility tree) until it closes — do not
+  hide them from overlay state yourself.
 - **State and behavior live in the app.** Components take semantic `data-action`
   strings and controlled values; wire them once with `delegate()`/`delegateActions()`
   or the disposer-returning `wire…` helpers, and own domain copy, transport, and
@@ -72,10 +558,33 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 - **App state is domain/persisted; helpers own only ephemeral mechanics.** Keep
   navigation stacks, tab selection and order, pane sizes, and `collapsed`/`expanded`
   disclosure flags in the app — they are data or persisted layout, and the app reads
-  them to render. The `wire…` helpers own the *ephemeral* parts: `wireNavStack` the
-  push/pop animation, `wireTabBars` the overflow autoscroll and drag preview,
-  `wireResizableRegions` the live drag preview; they report committed changes via
-  callbacks. The one richer case is `wireTokenSearchFields`, which manages the
+  them to render. The `wire…` helpers own the _ephemeral_ parts: `wireNavStack` the
+  content-slide, per-view top/bottom chrome cross-fade, and focus move/restore
+  (mark a preferred new-view target with `data-nav-focus`), `wireTabBars` the
+  overflow autoscroll, drag preview, and
+  replacement focus after controlled automatic tab activation,
+  `wireResizableRegions` the live drag preview, `wireScrollDividers` the
+  scroll-state attributes from which a `Pane` draws its chrome dividers and a
+  `TabBar` its overflow dividers; they report committed changes via
+  callbacks. For a tab-local action plus a separate far-edge action, set
+  `TabBar trailingPlacement="adjacent"`, put the local action in `trailing`, and
+  the workspace action in `end`; the component keeps both visible while its tab
+  list shrinks and scrolls, without application descendant CSS. Each action
+  zone accepts one ToolbarControlGroup or a standalone `wa-button` for its own
+  Web Awesome chrome. Managed
+  TokenSearchField clear also preserves open state and replacement
+  editor focus before the next input task, so shortcut-letter typing stays in search.
+  Select All deletion does the same; deletion
+  restoration finishes before the next keystroke rather than on a delayed frame.
+  Persist both query and remaining tokens read from an edited field; change
+  `revision` to replace unmanaged DOM-owned text programmatically, or call
+  `model.replace({ query, tokens })` for a model-managed field. In grammar-assisted
+  search, a model rule's `suggest(input, state)` receives current committed tokens
+  so suggestions can omit selected values; one-argument callbacks still work.
+  A sibling helper can call `model.commit(value)` for the active `name:` prefix
+  even when that value is not suggested; invalid values and missing prefixes
+  leave state unchanged.
+  The one richer case is `wireTokenSearchFields`, which manages the
   collapsible field's expand/collapse/focus by default (on, per-behavior opt-out) and
   exposes the `expanded` signal on its handle — bind it in render or hand in your own
   via `collapsible.signals`. Do not hand-roll open/collapse/focus that helper
@@ -85,47 +594,258 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   so a sibling suggestions/date popover does not collapse an empty field), opt-in
   atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via
   `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an
-  `onEdit({id, editor})` input callback — so the app can drop its own keydown/input
+  `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — so the app can drop its own keydown/input
   boilerplate while still owning parsing and controlled token state.
+  When `onEdit` or `onRemoveToken` changes tokens and the controlled render
+  replaces the focused editor, the helper hands focus and caret to the new
+  editor in the same task (end stays at end), so do not add a refocus
+  `MutationObserver` or `requestAnimationFrame`.
 - **Placeholder loading state, don't rebuild it.** For a value or component that is
   still loading, set `placeholder` on the component (`Select`, `ListHeader`,
-  `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
+  `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`,
   `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
-  slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
-  parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
-  markup. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
+  slots as subtle **unanimated** skeleton blocks and interactivity disabled. Only
+  unknown values change: a placeholder is never dimmed or styled as disabled (a
+  control you disabled keeps its live disabled tone), so a parent composes a
+  faithful loading view (e.g. an inspector) without hand-rebuilding markup.
+  Component-drawn chrome stays live: a `ListItem` or `ListActionRow` keeps its
+  `busy` spinner while its `status` (and a `ListItem`'s `trailing`) content
+  become skeletons. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
   (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
-  `LoadingSpinner` for known busy activity instead.
+  `LoadingSpinner` for known busy activity instead. Set its `size` prop to a
+  named icon step or positive pixel number when the inherited 1em is unsuitable.
+- **Keep ListItem content inside the row.** The rounded `ListItem` root clips
+  overflowing label, status, and dormant trailing content. Set `multiline` when
+  the primary label should wrap; use `ListActionRow` instead when trailing content
+  must be interactive.
+- **Dialog bodies are lists by default.** Compose rows and sections in `List`,
+  use `DialogSurface bodyInset="none"` when those children own their geometry,
+  and wrap bare prose in `ListInsetText` so it shares the standard list gutter
+  without stacking a second body inset.
+- **Use a StateBanner badge only for compact supporting status.** Pass the
+  optional string `badge` for a terse count or status beside the title. It
+  inherits the banner tone and is announced with the banner, so keep its text
+  meaningful and never rely on color alone.
+- **Configure StateBanner copy and action placement.** `copyLayout="stacked"`
+  puts detail below the title and badge; `actionPlacement="below"` always
+  gives the action a separate trailing row. The default trailing action stays
+  beside the copy while it has room and wraps onto its own trailing row on a
+  narrow banner, so do not switch placement per breakpoint.
+  `presentation="strip"` renders a flush, square, full-width band for a
+  layout edge with tone-colored `dividerSides` (bottom by default) instead of
+  the inset rounded card; never restyle a card into a strip.
+- **Use `SplitButton` for a primary action with options.** One loud semantic
+  fill with a native primary button and an options trigger (`aria-expanded`,
+  `aria-haspopup`); `tone`, `fill`, `busy`, and `disabled` are props. Never
+  build one from `wa-button-group` or app CSS on native buttons.
+- **Use `IconToggleButton` for an icon toggle outside a Toolbar.** In content or a
+  pane footer, `IconToggleButton({ icon, iconName, label, pressed, action })`
+  gives a native `aria-pressed` button the single contained toolbar group's
+  geometry; never wrap a `ToolbarControlGroup` outside a toolbar or restyle a
+  button to match it.
+- **Let an icon-state toggle skip selected chrome.** When a pressed toggle's
+  glyph already shows its state (an empty or filled star), set
+  `data-selected-chrome="none"` on that button, or `selectedChrome="none"` on
+  its `ToolbarControlGroup`; never override the group's pressed-button styles.
+- **Lay out a `ValueTable` through its props.** `labelWidth` sets a minimum
+  label column, `presentation="stacked"` puts values under labels, and
+  `stackBelow="compact" | "narrow"` stacks only while the table is narrower
+  than 512px/576px; do not override `--kui-value-table-row-columns`.
+- **Show selectable item summaries with `SummaryRow`.** One `role="option"`
+  per item as a list `row` or board `card`, with a state `rail`, a clamped
+  `title`, `trailingMeta`, a `metadata` line, `selected`, `dimmed`, and
+  `listEdge` rounding; the app owns the listbox and keyboard movement. Never
+  hand-roll ticket-row chrome.
+- **Group settings rows in `FramedList`.** For rows of arbitrary content in
+  one rounded frame with dividers between them (settings, account cards,
+  shortcut lists), compose `FramedListRow`s; `ValueTable` is the same frame for
+  label/value facts. Never hand-roll a `ul` with borders and row padding.
+- **Bound a result picker with a framed `List`.** For a bordered, scrolling
+  list of `ListItem` rows (search results, duplicate candidates), use
+  `<List scrollable frame maxHeight={rem(14)} minHeight={rem(4.25)}>`:
+  `frame` draws a 1px neutral border, the control radius, and a 4px inset
+  that keeps the first and last rows' focus rings inside the clip, and the
+  typed `CssLength` bounds need no flex-column ancestor. Never wrap a List in
+  an app div with `max-height`, `overflow`, and a border.
+- **Square an icon-only button with `IconButton`.** Web Awesome squares a
+  `wa-button` only for a lone `wa-icon`; with a `LucideIcon` use
+  `IconButton({ icon, iconName, label })` (label required) instead of
+  overriding `wa-button::part(base)`. Inside a `ToolbarControlGroup` keep a
+  native `button`; the group owns its geometry.
+- **Paint a strip's surface with `List surface`.** `surface="base"` or
+  `"raised"` fills a List and its insets with a solid surface (a banner strip
+  above a sunken work area); never wrap it in app CSS that sets a background.
+- **Use `Combobox` to pick or create a value by typing.** A themed native
+  input on the ARIA combobox pattern with filtered suggestions and an optional
+  create option; `wireComboboxes(root, { onCommit })` reports `{ id, value,
+created, input }`. Never use a hand-styled `<input list>` + `<datalist>`.
+- **Pick or drop files with `FilePickerTrigger` / `FileDropZone`.** Both wrap
+  a real, visually hidden file input; `wireFilePickers(root, { onFiles })`
+  reports browsed and dropped files and highlights the zone while dragging.
+  Never hand-style a file input, its label, or a dashed drop target.
+- **Swap content in place with `ContentSwap`.** Two sides share one cell;
+  `active`, `transition` (`push`, `crossfade`, `none`), and `direction` drive
+  Kerf-owned motion with an inert, hidden inactive side and reduced-motion
+  fallback. Use `NavStack` for full views with toolbars.
+- **Lay out a kanban board with `ColumnTrack`.** Equal columns that never
+  narrow below `minColumnWidth` scroll sideways; `layout="paged"` pages one
+  column at a time with a peek and snapping. Never re-track a `Grid` or
+  hand-roll scroll-snap CSS.
+- **Show ambient activity with `EdgeActivityIndicator`.** A layout-free,
+  pointer-inert top-edge strip whose bars ripple while `busy`, with an optional
+  polite `message` pill; Kerf owns the wave and reduced motion. Never hand-roll
+  fixed bars, keyframes, or a hanging pill in app CSS.
+- **Host app-level progress in `CornerStatus`.** For a non-dismissible
+  "Loading…" or "Updating… N of M" with no home beside the affected work, put
+  a `StateBanner` (`urgency="status"`) inside `CornerStatus` and call
+  `wireCornerStatus` once: a top-layer manual popover at a safe-area-aware
+  corner, with no close button, light dismiss, Escape, or focus change. Never
+  position a banner with fixed-position CSS or hide a toast's close part.
+- **Size a Select through its API.** `triggerWidth` chooses `fit-content`,
+  `max-content`, or `fill`; `--kui-select-trigger-max-width` caps it. For custom
+  selected text, use the public color, font-size, and font-weight tokens; the
+  closed value ellipsizes when space runs out. `presentation="title"` gives a
+  rail view heading a 36px bold, flush-start trigger and adjacent caret;
+  `focusRingInset` keeps its ring inside clipping ancestors.
+- **Configure application tabs at their owners.** AppTab's `icon-only`
+  presentation keeps `name` accessible, `labelMaxWidth` ellipsizes a long name,
+  `nameOverflow="visible"` shows the full name during inline loading, and
+  `dropTarget` highlights a drag-over without changing selection. `attention`
+  uses `--kui-app-tab-attention-color`. TabBar's public
+  `--kui-tab-bar-strip-*` tokens set compact strip geometry.
+  An inspector TabBar uses the shared rounded rectangle radius on its strip
+  and inset segmented tabs; an ordinary segmented TabBar keeps pill ends and
+  smaller interior tab corners. Configure the presentation instead of
+  restyling AppTab.
+  Set `pinned` on the first AppTab to keep it visible within a scrolling
+  tablist; it remains in keyboard order. Use `--kui-app-tab-pinned-background`
+  for the surrounding surface and keep that backdrop opaque.
+- **Use `Badge` for compact non-interactive metadata.** Configure its semantic
+  tone, appearance, shape, and size instead of creating badge CSS in an app or
+  consuming component. Use a real button or link for interactive content.
+  For new content without a count, use the text-free `size="dot"` form: it
+  takes no children, and needs a `label` (announced as an image) or
+  `ariaHidden` when its owner announces it. A `TabNavigator` tab shows the dot
+  with `badge: true` plus its required `badgeLabel`. A text badge takes a
+  decorative leading `icon`, a `title` tooltip, and `data-*` `rootAttributes`
+  for app identity; never wrap a Badge or nest a `Row` in it for those.
+  For app-supplied text that can run long (a tag or category name), set
+  `maxWidth` (a `CssLength`, such as `px(160)`): the label truncates with an
+  ellipsis and string or number content becomes the hover `title`.
+- **Use `Chip` for removable tags.** Give the native remove button a delegated
+  `removeAction` and a specific `removeLabel`; the application updates the tag
+  list. `itemId` identifies the chip to the action handler. `size="compact"`
+  gives a 20px chip and 16px remove button; `disabled` disables removal.
+- **Use a link `Chip` for downloadable files and short links.** `href` renders a
+  native `<a>` with chip geometry; `download` (`true` or a file name) and
+  `external` (new tab, safe rel, announced) are optional, and a link chip has
+  no remove button. Inside a ContentItem bubble set `tone="inherit"` so it
+  follows the bubble's foreground instead of styling an anchor yourself.
+- **Use `ChoiceChips` for a wrapping exclusive choice.** When one value comes
+  from a visible set too large for a `SegmentedControl` track (a nine-color
+  palette in a 560px dialog), render separate pills backed by native radios:
+  one Tab stop, arrow-key selection, and a real form value under `name`. Name
+  the group with `label` or `labelledBy`, lead choices with a `swatch`
+  (`CssColor` such as `fillColor('#3b82f6')`, or `'transparent'` for the struck-through no-color dot) or an
+  `icon`, and handle the delegated `action` on `change`. Never wrap a
+  `SegmentedControl` or button-appearance `wa-radio` set instead. Set
+  `multiple` (with a `readonly Value[]` `value`) when any number may be on:
+  the same pills become native checkboxes in a `role="group"`, each a Tab stop
+  that Space toggles, and every checked value submits under `name`. On dark
+  inverse chrome, place the chips in a dark appearance scope (`.wa-dark`)
+  instead of restyling them.
+
+- **Use `Composer` for a chat or prompt composer.** `@kerfjs/ui/composer`
+  renders a raised frame (standard border, large radius, `shadow-l`) whose
+  border turns brand while focus is within, a borderless textarea that grows
+  between `minRows` (default 1) and `maxRows` (default 8) lines and then
+  scrolls, and an action row with an optional quiet `hint` and the trailing
+  `actions` (a brand Send button). Name it with a title-style `label`; give it
+  an `id` so the hint describes the field. Slot it into a `DialogSurface`
+  floating footer (`footerInset="none"`) over a transcript. Never rebuild
+  composer chrome around a `wa-textarea` with app CSS. For Enter-to-send, set
+  `submitOnEnter` and call `wireComposers(root)` from
+  `@kerfjs/ui/wire-composers` once: Enter or Cmd/Ctrl+Enter clicks the first
+  trailing action, Shift+Enter inserts a newline, and an IME composition
+  commit or an empty message never sends. Never hand-roll that handler.
 
 ## Public exports
 
-`LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`,
-`PanelHeader`, `ListItem`, `ListActionRow`, `ListHeader`, `SegmentedControl`,
+`Badge`, `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarActionLink`, `FloatingToolbar`, `ToolbarText`, `Text`,
+`ListItem`, `ListActionRow` (+ `wireListReorder`, `reorderListItems`), `wireListFocusScroll`, `ListHeader`, `ListInsetControl`,
+`ListInsetText`, `SegmentedControl`, `ChoiceChips`, `Composer`,
 `Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
 `wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`wireScrollDividers` (scroll-state dividers for every `Pane`, `NavStack`,
+`TabNavigator`, and `TabBar`),
 `ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
 `LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
-tree-shakeable, declarative with `wire…` helpers, each with a companion CSS import):
-`NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
+tree-shakeable, declarative with `wire…` helpers; the browser build of each layout
+subpath loads its CSS and that of the components it renders, and a companion
+CSS subpath remains for pipelines without the `browser` condition):
+`NavStack`, `SplitView`, `Workbench`, `TabNavigator`, driven by `deviceClass()` from
 `@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
 shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
-+ `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
-`@kerfjs/ui/catalog` is another opt-in shell — a
-`Catalog` component + `wireCatalog` helper for building a component-gallery catalog
-(collapsible category sidebar + preview stage + resources footer) from your own
-entries; controlled/stateless like the layouts. `@kerfjs/ui/webawesome` is a
-type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
-declared side effects.
+
+- `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence; a compact overlay starts closed and opens only on a user action, and `inlineCollapsed` declares a panel's inline default).
+  `@kerfjs/ui/catalog` is another opt-in shell — a
+  `Catalog` component + `wireCatalog` helper for building a component-gallery catalog
+  (collapsible category sidebar + preview stage + resources footer, with
+  focus-preserving active-row reveal for long desktop sidebars) from your own
+  entries; controlled/stateless like the layouts. Its optional contrast, reduced
+  motion, theme, and preview-background controls are built in; pass state and
+  `wireCatalog` callbacks instead of recreating their toolbar markup, while your
+  app owns applying and persisting preferences. For any Catalog demo, follow
+  the [authoritative authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
+  rather than inferring structure from the shell or private CSS. The shipped
+  Catalog stage fills the preview scroller for short specimens and grows with
+  tall ones in every consumer; do not add a demo-specific height or backdrop
+  override.
+  `@kerfjs/ui/webawesome` is a
+  type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
+  declared side effects.
 
 ## Reference
 
 - [skill.md](./ai/skill.md): the full rule set + a common-mistakes table (the shipped AI skill).
 - [design-philosophy.md](./docs/design-philosophy.md): why kerf UI is shaped this way — the decision principles behind the rules above.
+- [writing.md](./docs/writing.md): interface copy — the title-style vs. sentence-style capitalization rule per element, from Apple's guidance.
 - [layout.md](./docs/layout.md): the pane/content-item geometry, public roles/tokens, and the spacing scale.
 - [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
-- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
-- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists).
-- [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.
+- [workbench.md](./docs/workbench.md): the `Workbench` multi-panel shell, its collapse policies, and opt-in `resizable` panels driven by `wireWorkbench` (`@kerfjs/ui/wire-workbench`: drag, keyboard, min/max, persistence, compact suspension), the `mainMinSize` / `mainMinHeight` work-area minimums (default 320px wide beside any inline rail, 120px tall above the drawer) that resizable panels stop at and inline panels shrink around, and a panel's `responsiveOverlayAt` (`narrow` / `compact`, rails and the bottom drawer) that presents it as an overlay below a Workbench container breakpoint without a device-class check; a panel given its `collapsed` signal is a transient overlay (collapsed on entering the breakpoint, takes focus and keeps Tab inside while open, closed by Escape or an outside press, focus returned; `dismissOverlays`), and overlays are exclusive by default (opening one closes the others; `exclusiveOverlays: false` opts out).
+- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabNavigator` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
+- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
+- [ai/components/README.md](./ai/components/README.md): the generated per-component markdown reference — the assistant entry point over both JSON catalogs.
+- [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
+- [compile-time-contracts-v1.json](./ai/compile-time-contracts-v1.json) + [type-contracts.md](./docs/type-contracts.md): stable compile diagnostics, packed-declaration proof, migrations, and explicit non-goals.
 - [README.md](./README.md): package overview and the component subpath table.
+
+Neutral lowered surfaces and decorative neutral fills/borders are translucent theme colors; compose nested public components directly. Default/raised canvases, foregrounds, focus indicators, and loud contrast-bearing fills remain opaque. Do not assign depth-specific component tokens in demo wrappers.
+
+Navigation transition continuity: `wireNavStack` slides the incoming view over the preserved previous view on push and the outgoing view off on pop, cross-fades both live chrome surfaces with inert snapshots, and settles/cancels an interrupted transition before starting the next. Reduced motion and duration zero settle immediately.
+
+For a tab scene with drill-down, put a `NavStack` directly in `TabNavigatorTab.content`, configure each view's top `toolbar` and `pane`, and omit `bottomToolbar` at both levels so the scaffold bar remains the only bottom chrome. Wire both components on their own roots. The catalog's **NavStack inside a tab** example exercises push and tab switching.
+
+`Pane.deepInset` (and `PaneConfig.deepInset`) or `TabNavigatorTab.deepInset` on a plain scene adds 8px on all four sides of the scroll content, so ordinary 8px item margins land 16px from the inline edge. Nested Row/List/Grid spacing stays at its default. Set a nested scene's Pane option instead of insetting its entire NavStack or toolbar.
+For a child table whose decoration spans the Pane while its text stays aligned, use the Pane content slot's inherited `--kui-pane-content-inset-inline-start` and `--kui-pane-content-inset-inline-end`: negate them for the child's logical margins and add them to cell padding. They include safe areas and `deepInset`; see `docs/app-layouts.md#edge-to-edge-content-inside-a-pane`.
+
+`ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow`/`showBelow`
+lengths (for example `px(416)`). Wire `wireToolbarVisibility(root)` from
+`@kerfjs/ui/wire-toolbar-visibility` and dispose on unmount. Thresholds use the
+nearest Toolbar content-box width: hideBelow hides strictly below, showBelow
+shows strictly below, with complementary behavior at equality. Percentages use
+that content width; em and custom properties use the item's own context. Invalid,
+negative, unresolved, or contradictory values leave the item visible under this
+width policy. Keep primary actions visible and offer a complementary overflow
+group. See `docs/component-contract.md` "Toolbar width visibility" for lifecycle
+details.
+
+Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. Keep popup sizing and position repairs out of consumer CSS.
+
+Key sibling `DialogSurface`s that render conditionally with `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself; never wrap one in a keyed app `div`. Modal `DialogSurface` bounds use typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`); explicit caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Application render state chooses responsive values, and preview layout remains application-owned. `height` sets a definite bounded modal size and `bodyLayout="fill"` lets one child fill the body; `bodyLayout="fill-last"` keeps leading rows at their height above one filling last child, and `footerPresentation="floating"` (with a typed `footerOffset`) floats a chat composer over the body while the body reserves its measured height; give the transcript `scrollClearance="block-end"` (a `scrollable` `List` or a `Pane`) to let it scroll beneath the composer, with the last message still resting above it, through the published `--kui-scroll-clearance-block-end` context (overlaying chrome publishes `--kui-scroll-clearance-block-start` / `-end`; one scroller per covered edge opts in; a composed Pane opts in through `PaneConfig.scrollClearance` on a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`). `headerPresentation="floating"` lays the title bar over the body on the translucent `--kui-chrome-material-raised` (opaque under reduced transparency, increased contrast, and forced colors); the register measures it and the body reserves it, and a `fill` body's only child with `scrollClearance="both"` scrolls beneath both the title bar and a floating composer through the published `--kui-scroll-clearance-block-start`. `PopoverDialogSurface` is the non-modal, light-dismiss counterpart on the native Popover API, with the same size props and an `embedded` in-flow presentation; `describedBy` sets its `aria-describedby` (usually a title `ToolbarText`'s `descriptionId`).
+
+Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+
+Toolbar visibility measurement probes and invisible state children are helper-owned and survive Kerf rerenders through `data-morph-preserve`. Actual CSS visibility stays stable while rendering removes transient parent markers, preventing geometry-driven render feedback and repeated probe recreation. Toolbar replacement, explicit internal-node removal and disposal retain their existing behavior.