@kerfjs/ui 5.0.0-beta.97 → 5.0.0-beta.99

package/docs/component-selection.md

@@ -61,6 +61,13 @@ mockup or another application:
 The package's defaults are the starting design, not an empty canvas. A custom
 component or rule should explain which missing behavior or structure it owns.
 
+Write the copy by the package rule as you choose components: a component's
+naming props (button and menu-item labels, segment and `Select` choices,
+`ToolbarText` titles, `ListHeader` labels, field labels) take title style, and
+its describing props (`description`, `detail`, hints, placeholders, tooltips,
+option text, status) take sentence style. See
+[Writing interface copy](./writing.md#capitalization).
+
 **Don't fight the components.** The package is built to look right without an
 application customization layer. Before adding `padding`, `margin`, `width`,
 `height`, `border`, `background`, a wrapper card, or a decoration, check whether
@@ -187,8 +194,14 @@ selection entries.
 For arbitrary interactive help or popup content beside a control, use
 [`openAnchoredSurface`](anchored-surface.md) with an accessible label; use
 `openAnchoredSurfaceAt` for pointer coordinates. It owns the Kerf UI surface,
-placement, focus, dismissal, and modal-dialog hosting while the app owns its
-content and action policy. Use `PopupMenu` for a typed command list.
+placement (an 8px viewport gutter, and a height fitted to the room beside the
+anchor with scrolling content), focus, dismissal, and modal-dialog hosting while
+the app owns its content and action policy. Never add media queries or
+`max-height` overrides to make a surface fit a phone. For a popup anchored to
+dark media chrome (a `ToolbarControlGroup tone="dark"` over a preview), pass
+`tone: 'dark'` rather than building an app-owned dark panel: the surface takes
+the group's inverse tone and its content inherits the matching colors. Use
+`PopupMenu` for a typed command list.
 
 Kerf UI does not export a command-palette component. Do not invent a package
 command-palette import.
@@ -229,6 +242,7 @@ beside a `ContentItem` value, and connect its id to the preview group's
 | Self-contained content child — `ContentItem`                                                                            | An ordinary surface-like child of a `Pane` or `.kui-content` stack needs the shared 8px margin / 1px border / 8px padding geometry; pass `frame="framed"` only when it marks a real distinction, `appearance="surface"` or a semantic appearance for coordinated surface colors, and `shape="pill"` for the 22px radius.                                 | Do not wrap a component that already owns content-item geometry (`ListItem`, `ListHeader`, `StateBanner`, `Toolbar`, `ValueTable`) or pad around it — that double-insets. Do not frame an item only to make it look contained. Use `SunkenPanel` for a lowered inset stack and `ListInsetText` for bare text that only needs to align.     | Pass the item content as children; choose `appearance` (`transparent` default, `surface`, or a semantic status), `frame`, and `shape` instead of writing CSS. Put safe `data-*` metadata in `rootAttributes`; `ariaLabel` names a distinct region and `focusTarget` makes it a programmatic focus target.                                                                                                                                                                                                                                                                                                                                                                                                              | The content, surface or status appearance, and whether it marks a distinction worth a visible frame.                                                     | `@kerfjs/ui/content-item`                                                                 | [Content items](./layout.md#content-items)                                          |
 | Application column — `Pane`                                                                                             | A sidebar, main area, inspector, or dialog needs shared vertical header/content/footer organization, one scroll owner, and optional edge separators.                                                                                                                                                                                                     | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane.                                                                                                                                                                                | Import `Pane`, use `children` for its homogeneous primary content and the named `SafeHtml` prop slots `header`/`footer` for optional fixed chrome, then opt into only the needed logical-edge separators; add `ContentItem` children as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge.                                                                                                                                                                                                                                                                         | Layout hierarchy, reading width, responsive relocation, pane visibility state, slot semantics, labels, and separator placement.                          | `@kerfjs/ui/pane`                                                                         | [Pane anatomy](./layout.md#anatomy)                                                 |
 | Scroll dividers — `wireScrollDividers`                                                                                  | Pinned chrome (a `Pane` header or footer, a `NavStack` top chrome or bottom toolbar, a `TabNavigator` bar, the sides of a `TabBar` strip, or app-owned chrome around a scroller) needs a divider only while content is scrolled away beneath it.                                                                                                         | Do not keep a static toolbar divider to fake it or write a border onto another component; each component draws its own line from the wiring's state.                                                                                                                                                                                       | Call `wireScrollDividers` once at the app root and retain the disposer; it covers every `Pane`, `NavStack`, `TabNavigator`, and `TabBar` below it. Name app-owned arrangements in `targets` by id; a `Toolbar` or `List` named as chrome draws its facing side. Configure a pane with `chromeDividers` (`scroll` default, `always`, `none`).                                                                                                                                                                                                                                                                                                                                                                           | Which panes follow the scroll, app-owned targets, and the disposer.                                                                                      | `@kerfjs/ui/wire-scroll-dividers`                                                         | [Scroll dividers](./layout.md#scroll-dividers)                                      |
+| Keyboard focus scroll in scrollable Lists — `wireListFocusScroll`                                                       | Rows of a `scrollable` List are reached by keyboard (Tab, or the app's own arrow-key focus moves) and must come fully into view, focus ring included, in Firefox and Safari too: their `focus()` leaves a partly hidden row clipped.                                                                                                                     | Do not call `scrollIntoView` from app focus handlers or style the List; do not wire it for pointer-only lists.                                                                                                                                                                                                                             | Call `wireListFocusScroll(root)` once at the app root and retain the disposer. On keyboard (`:focus-visible`) focus inside a `scrollable` List it scrolls the focused element into view only when its ring crosses the clip; pointer focus is left alone.                                                                                                                                                                                                                                                                                                                                                                                                                                                              | The disposer.                                                                                                                                            | `@kerfjs/ui/wire-list-focus-scroll`                                                       | [Framed result pickers](./layout.md#framed-result-pickers)                          |
 | One-pane navigation — `NavStack`                                                                                        | A compact flow pushes into details while keeping earlier views mounted, or a single-pane screen needs the same stable layout contract.                                                                                                                                                                                                                   | Do not use it when list and detail should remain visible together; use `SplitView`. Do not use it alone for co-equal top-level destinations; use one stack per `TabNavigator` tab.                                                                                                                                                         | Keep the ordered view array controlled, put view-specific bottom chrome on each view (or use the component fallback), import its CSS explicitly, and call `wireNavStack` for back delegation, content-slide/chrome-cross-fade transitions, and focus move/restore. Mark a preferred initial target with `data-nav-focus` when DOM order is insufficient.                                                                                                                                                                                                                                                                                                                                                               | View keys/content/titles, push and pop actions, preferred initial focus targets, and per-view or persistent bottom toolbar content.                      | `@kerfjs/ui/nav-stack`                                                                    | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
 | Responsive list-detail — `SplitView`                                                                                    | A primary list and related detail belong together on roomy devices but become a one-pane drill-down on compact devices.                                                                                                                                                                                                                                  | Do not use it for a single linear flow or a multi-panel editor shell.                                                                                                                                                                                                                                                                      | Provide controlled selection/detail state and device class; opt into resize wiring only when the separator is user adjustable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Selection, detail content, compact back action, device policy, and optional persisted width.                                                             | `@kerfjs/ui/split-view`                                                                   | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
 | Compact top-level destinations — `TabNavigator`                                                                         | A handset or portrait-tablet app has two to five co-equal destinations whose scenes and nested navigation must remain mounted across switches.                                                                                                                                                                                                           | Do not use it for document tabs, reorderable work items, or a desktop navigation rail.                                                                                                                                                                                                                                                     | Keep the active id controlled, import its CSS explicitly, and call `wireTabNavigator`; commonly place one `NavStack` in each tab scene.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Destination definitions, active id, routing, persistence, and roomy-device replacement.                                                                  | `@kerfjs/ui/tab-navigator`                                                                | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
@@ -242,7 +256,7 @@ beside a `ContentItem` value, and connect its id to the preview group's
 | Panel, dialog, or page heading — `Toolbar` + `ToolbarText`                                                              | A panel, dialog, or page needs an extra-large title, optional icon, grouped trailing actions, and optional supporting copy.                                                                                                                                                                                                                              | Do not add a private heading wrapper or bespoke layout. The toolbar supplies structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior. In a narrow peripheral rail or drawer, where xlarge would truncate at the panel's minimum size, use the default `ToolbarText` size as pane identity.  | Connect title/supporting-copy ids to the host, group controls, and delegate actions. **For a page or view title set `headingLevel` (usually `1`)** on `ToolbarText`; omit it for a dialog title referenced by `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Open state, focus lifecycle, dismissal, controls, ids, copy, and heading level.                                                                          | `@kerfjs/ui/toolbar` + `@kerfjs/ui/toolbar-text`                                          | [Toolbar headings](./accessibility.md#toolbar-headings)                             |
 | Dialog or popup geometry — `DialogSurface`, `PopoverDialogSurface`, `PopupSurface`                                      | Recurring Web Awesome dialogs need standard sizes/presentations/body/footer insets, typed modal viewport bounds, a definite height, or a body one child fills; a dialog must stay non-modal and light-dismiss; or dropdown menus need list-compatible inset ownership.                                                                                   | Do not use these wrappers as generic layout or to replace native dialog/dropdown behavior. Avoid consumer `::part()` overrides and do not stack a dialog body inset around list-owned child geometry.                                                                                                                                      | Wrap one `wa-dialog` or `wa-dropdown`; choose the typed geometry while retaining native labeling, open state, focus, dismissal, and menu semantics. Compose a dialog body as a `List` by default, use `bodyInset="none"` when its children own list geometry, and wrap bare prose in `ListInsetText`. Set `height` with `bodyLayout="fill"` when one `SplitView` or `Pane` should fill the body. For a non-modal, light-dismiss dialog render `PopoverDialogSurface` (native `popover="auto"`, opened by a `popoverTarget` control or `showPopover()`), never a hand-built popover with app chrome CSS; `presentation="embedded"` shows it in flow.                                                                    | State, focus lifecycle, dismissal, labels, content, and outer placement.                                                                                 | `@kerfjs/ui/surface-scaffold`                                                             | [Surface scaffolds](./surface-scaffold.md)                                          |
 | Key/value facts — `ValueTable`, `ValueTableRow`                                                                         | Read-only labels and values form a semantic definition list, optionally with a leading icon.                                                                                                                                                                                                                                                             | Do not use it for editable form fields or a row/column data grid; use native form or table semantics.                                                                                                                                                                                                                                      | Compose typed `ValueTableRow` entries; pass `icon` when a 24px leading icon adds useful context. Set `labelWidth` for a minimum label column, `presentation="stacked"` to put each value under its label, or `stackBelow` (`compact` 512px, `narrow` 576px) to stack only while the table is that narrow; never override `--kui-value-table-row-columns` for these.                                                                                                                                                                                                                                                                                                                                                    | Values, formatting, icon meaning, and empty/loading policy.                                                                                              | `@kerfjs/ui/value-table`                                                                  | [Component ownership](./component-contract.md#ownership-boundaries)                 |
-| Framed rows of arbitrary content — `FramedList`, `FramedListRow`                                                        | Settings rows, account or source cards, or a shortcut list group several rows of copy and controls in one rounded frame with dividers between them.                                                                                                                                                                                                      | Do not use it for read-only label/value facts; use `ValueTable`. Do not use it for selectable navigation rows; use `List` with `ListItem`. Do not pad or border rows from application CSS.                                                                                                                                                 | Compose any row content (a `Row` of copy, a keycap, `IconButton`s) in each `FramedListRow`; mark the row being edited `highlighted`. Name the list with `label` when no heading does.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Row content, controls, which row is highlighted, and the list's name.                                                                                    | `@kerfjs/ui/framed-list`                                                                  | [Feedback accessibility](./accessibility.md#shared-rules)                           |
+| Framed rows of arbitrary content — `FramedList`, `FramedListRow`                                                        | Settings rows, account or source cards, or a shortcut list group several rows of copy and controls in one rounded frame with dividers between them.                                                                                                                                                                                                      | Do not use it for read-only label/value facts; use `ValueTable`. Do not use it for selectable navigation rows or a bounded result picker; use `List` with `ListItem` (a picker adds `frame`, `scrollable`, and `maxHeight`). Do not pad or border rows from application CSS.                                                               | Compose any row content (a `Row` of copy, a keycap, `IconButton`s) in each `FramedListRow`; mark the row being edited `highlighted`. Name the list with `label` when no heading does.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Row content, controls, which row is highlighted, and the list's name.                                                                                    | `@kerfjs/ui/framed-list`                                                                  | [Feedback accessibility](./accessibility.md#shared-rules)                           |
 | Selectable item summaries — `SummaryRow`                                                                                | A list or board shows many items as dense, selectable summaries: an identifier and title, a timestamp, and a metadata line (tickets, tasks).                                                                                                                                                                                                             | Do not use it for navigation rows; use `ListItem`. Do not use it for free-form selectable tiles; use `ContentItem`. Do not hand-roll row chrome.                                                                                                                                                                                           | Pass `title`, optional `leading`, `trailingMeta`, and `metadata`; choose `presentation` (`row` or `card`), `rail`, `selected`, `dimmed`, `listEdge`, and `titleLines`. Put rows in a labeled `role="listbox"` and own selection and arrow-key focus in the app.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | The listbox, selection, keyboard movement, content, rail tone, and dimming.                                                                              | `@kerfjs/ui/summary-row`                                                                  | [Feedback accessibility](./accessibility.md#shared-rules)                           |
 | Indeterminate activity — `LoadingSpinner`                                                                               | A Kerf surface needs compact, labeled or decorative indeterminate progress.                                                                                                                                                                                                                                                                              | Do not use it for known progress; use Web Awesome `wa-progress-bar` or `wa-progress-ring`. Direct Web Awesome UI may use `wa-spinner`; do not mix spinner systems within one surface.                                                                                                                                                      | Pass a label when the spinner conveys status; use size for a named icon step or positive pixel size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Loading lifecycle and adjacent status copy.                                                                                                              | `@kerfjs/ui/loading-spinner`                                                              | [Accessibility](./accessibility.md#shared-rules)                                    |
 | Loading placeholder — `Skeleton` + a component's `placeholder` prop                                                     | A value or a whole component is still loading and should hold its space as a subtle, unanimated block, keeping the layout stable — an inspector or detail view rendering its real chrome with per-record values absent.                                                                                                                                  | Do not use it for known progress (use `LoadingSpinner`), do not animate it, and do not hand-rebuild a component's empty state — set `placeholder` on the component instead. Prefer it over `wa-skeleton`, which the pure-Kerf primitives avoid to stay Web-Awesome-free.                                                                   | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render skeletons in its value slots with interactivity disabled; use the standalone `Skeleton` for a custom slot.                                                                                                                                                                                                                                                                                                                                                                                                                 | Loading lifecycle, which slots are unknown, and announcing the loading region.                                                                           | `@kerfjs/ui/skeleton`                                                                     | [Accessibility](./accessibility.md#shared-rules)                                    |
@@ -254,10 +268,11 @@ beside a `ContentItem` value, and connect its id to the preview group's
 | Value selection — `Select`                                                                                              | A controlled form, toolbar, or compact navigation value comes from a moderate or long choice list, possibly grouped, icon-bearing, icon-only when closed, or truncating. Set `multiple` with an array `value` when the person may choose any number of them; add `selectedPresentation="icon-only"` and a fixed `triggerIcon` for a toolbar filter menu. | Do not use it for commands; use `PopupMenu`. Do not use it for a small visible choice set; use `SegmentedControl`. Prefer it over direct `wa-select`, `wa-option`, or value-like `wa-dropdown`/`wa-dropdown-item` composition.                                                                                                             | Import `@kerfjs/ui/select/register` once for registration and current-request animation ownership; listen for standard input/change events. Do not add consumer popup timing or positioning repairs. Use typed presentation props rather than consumer `::part()` overrides; let the parent own placement.                                                                                                                                                                                                                                                                                                                                                                                                             | Controlled value, validation, choices, domain mapping, and outer placement.                                                                              | `@kerfjs/ui/select`                                                                       | [Web Awesome integration](../README.md#web-awesome-theme)                           |
 | Pick or create a value by typing — `Combobox`, `wireComboboxes`                                                         | People type to find an existing value among many or create a new one (tags, labels, recipients).                                                                                                                                                                                                                                                         | Do not use it when only existing values are allowed; use `Select`. Do not use it for search text with removable filter tokens; use `TokenSearchField`. Do not style a native input with a datalist.                                                                                                                                        | Pass `id`, `label`, and `suggestions` (strings or `{ value, label }`), plus `placeholder`, `hint`, and `createLabel` (or `false` for suggestions only). Call `wireComboboxes(root, { onCommit })` once; it filters, moves the active option with the arrows, and reports `{ id, value, created, input }` on Enter, a comma, or a click.                                                                                                                                                                                                                                                                                                                                                                                | Suggestions, committed values, normalization, and clearing the field.                                                                                    | `@kerfjs/ui/combobox`, `@kerfjs/ui/wire-comboboxes`                                       | [Feedback accessibility](./accessibility.md#shared-rules)                           |
 | Small exclusive choice — `SegmentedControl`                                                                             | A few visible choices switch a compact view or setting, with toolbar, rounded, or pill presentation.                                                                                                                                                                                                                                                     | Do not use it for tabpanel semantics; use `TabBar`. Do not use it for many choices; use `ChoiceChips` when they stay visible and wrap, or `Select` for a long list. Prefer it over `wa-button-group` when the controls select one value.                                                                                                   | Delegate its action, read `data-segment-value`, update `value`, and rerender.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Controlled value, labels, action, and persistence.                                                                                                       | `@kerfjs/ui/segmented-control`                                                            | [SegmentedControl contract](./accessibility.md#segmentedcontrol)                    |
-| Wrapping exclusive choice — `ChoiceChips`                                                                               | Several visible options, too many for one segmented track, must wrap onto more rows — a labeled color palette with swatches, a tag color, a category.                                                                                                                                                                                                    | Do not use it for a few compact choices on one track; use `SegmentedControl`. Do not use it for a long list or tight space; use `Select`. Do not use it for removable tags (`Chip`) or multiple selection. Prefer it over `wa-radio-group` with `appearance="button"` radios, which wrap as a ragged joined group.                         | Pass a form `name`, a `label` or `labelledBy`, and the controlled `value`; delegate the `action` on `change`, read the radio `value`, and rerender. Lead choices with a `swatch` (`CssColor` or `'transparent'`) or an `icon`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Controlled value, choices, swatch colors, change handling, and form submission.                                                                          | `@kerfjs/ui/choice-chips`                                                                 | [ChoiceChips contract](./accessibility.md#choicechips)                              |
+| Wrapping visible choice — `ChoiceChips`                                                                                 | Several visible options, too many for one segmented track, must wrap onto more rows — a labeled color palette with swatches, a tag color, a category. Set `multiple` with an array `value` when any number may be on, such as label filters or annotation intents.                                                                                       | Do not use it for a few compact choices on one track; use `SegmentedControl`. Do not use it for a long list or tight space; use `Select`. Do not use it for removable tags (`Chip`). Prefer it over `wa-radio-group` with `appearance="button"` radios, which wrap as a ragged joined group.                                               | Pass a form `name`, a `label` or `labelledBy`, and the controlled `value`; delegate the `action` on `change`, read the radio `value` (or, with `multiple`, the checked boxes under `name`), and rerender. Place it in a dark appearance scope for inverse chrome rather than restyling it. Lead choices with a `swatch` (`CssColor` or `'transparent'`) or an `icon`.                                                                                                                                                                                                                                                                                                                                                  | Controlled value, choices, swatch colors, change handling, and form submission.                                                                          | `@kerfjs/ui/choice-chips`                                                                 | [ChoiceChips contract](./accessibility.md#choicechips)                              |
+| Chat or prompt composer — `Composer`, `wireComposers`                                                                   | A chat message, assistant prompt, or reply is written in a raised frame and sent with a trailing action, often in a `DialogSurface` floating footer over a transcript.                                                                                                                                                                                   | Do not use it for an ordinary form field submitted with the rest of a form; use `wa-textarea` with a `FieldLabel`. Do not wrap it in another framed `ContentItem` or card; it owns its frame, padding, and shadow. Prefer it over a `wa-textarea` and a button in app-styled chrome.                                                       | Pass a `name`, a title-style `label`, an `id` when it has a `hint`, and the trailing `actions` (a brand Send `wa-button`). Bound the growing field with `minRows` and `maxRows`. Read and clear the textarea from the send action. For Enter-to-send, set `submitOnEnter` and call `wireComposers(root)` once; Enter clicks the first trailing action, Shift+Enter is a newline, and IME commits never send.                                                                                                                                                                                                                                                                                                           | Value, sending, shortcuts beyond the opt-in Enter-to-send, and the disabled or busy state of its actions.                                                | `@kerfjs/ui/composer`, `@kerfjs/ui/wire-composers`                                        | [Composer](./composer.md)                                                           |
 | Structured search editor — `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields` | Free text and ordered, editable, removable filter tokens share one searchbox; enable `collapsible` when an empty, unfocused field should reduce to one iconic action, standalone or in a toolbar group.                                                                                                                                                  | Do not use it for ordinary text entry; use a native input or Web Awesome `wa-input`. Do not use it when filters belong in separate form controls.                                                                                                                                                                                          | Read DOM-owned text on input, empty `textContent` on clear, and use `placeTokenSearchCaret` after explicit controlled focus changes. Call `wireTokenSearchFields` from `@kerfjs/ui/wire-token-search-fields` once so Enter submits without adding a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. In `collapsible` mode it also manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse); bind the field's `expanded` to the signal on the returned handle (`handle.expanded(id)`) or adopt your own via `collapsible.signals`, and opt out per behavior only when the app must own it. | Parsing, suggestions, tokens, query execution, results, announcements, and — only if overriding the default — the collapsible `expanded` signal.         | `@kerfjs/ui/token-search-field`                                                           | [TokenSearchField contract](./accessibility.md#tokensearchfield)                    |
 | Persistent inline status — `StateBanner`                                                                                | A neutral, info, pop, success, warning, or danger message belongs next to the affected work; pop highlights featured or novel content without implying status.                                                                                                                                                                                           | Do not use pop as a success, warning, or danger substitute. Do not use StateBanner for a no-content screen; use `EmptyState`. Do not use it for transient confirmation; use a toast. Web Awesome `wa-callout` is the ecosystem alternative for Web Awesome-owned content.                                                                  | Delegate an optional action; choose alert urgency only for attention-requiring failure. Use the optional tone-tinted `badge` for a terse count or status beside the title, not as the only expression of meaning.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | State mapping, message lifetime, retry/action behavior, badge content, and copy.                                                                         | `@kerfjs/ui/state-banner`                                                                 | [Feedback accessibility](./accessibility.md#shared-rules)                           |
-| App-level progress in a corner — `CornerStatus`, `wireCornerStatus`                                                     | Ongoing app-wide work, such as "Loading…" or "Updating tickets… 3 of 12", needs a non-dismissible status that has no better home beside the affected work.                                                                                                                                                                                               | Do not use it for transient, dismissible confirmation; use a toast. Do not use it for status that belongs beside the affected work; place a `StateBanner` there. Do not position a `StateBanner` with fixed-position application CSS.                                                                                                      | Compose one or more `StateBanner`s with `urgency="status"`; they stack. Call `wireCornerStatus` once so each overlay host opens in the top layer as renders insert it. It never takes focus and has no close button, light dismiss, or Escape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Status lifetime (render while the work runs, remove when it ends), banner copy and progress, and corner placement.                                       | `@kerfjs/ui/corner-status`, `@kerfjs/ui/wire-corner-status`                               | [Feedback accessibility](./accessibility.md#shared-rules)                           |
+| App-level progress in a corner — `CornerStatus`, `wireCornerStatus`                                                     | Ongoing app-wide work, such as "Loading…" or "Updating Tickets… 3 of 12", needs a non-dismissible status that has no better home beside the affected work.                                                                                                                                                                                               | Do not use it for transient, dismissible confirmation; use a toast. Do not use it for status that belongs beside the affected work; place a `StateBanner` there. Do not position a `StateBanner` with fixed-position application CSS.                                                                                                      | Compose one or more `StateBanner`s with `urgency="status"`; they stack. Call `wireCornerStatus` once so each overlay host opens in the top layer as renders insert it. It never takes focus and has no close button, light dismiss, or Escape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Status lifetime (render while the work runs, remove when it ends), banner copy and progress, and corner placement.                                       | `@kerfjs/ui/corner-status`, `@kerfjs/ui/wire-corner-status`                               | [Feedback accessibility](./accessibility.md#shared-rules)                           |
 | Ambient edge activity — `EdgeActivityIndicator`                                                                         | App-wide background activity (server work, sync) should be visible along the top edge without a modal, a banner, or a layout shift.                                                                                                                                                                                                                      | Do not use it for progress the user waits on or must read; use `CornerStatus`. Do not use it for known progress; use a progress bar. Do not make it the only record of important state.                                                                                                                                                    | Drive `busy`; pass an optional `message` for a polite status pill and a `tone`. It sits below the top safe area (or flush with `inset="none"`), takes no pointer, and only fades under reduced motion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | The busy state, message, and tone.                                                                                                                       | `@kerfjs/ui/edge-activity-indicator`                                                      | [Feedback accessibility](./accessibility.md#shared-rules)                           |
 | Empty or busy content area — `EmptyState`                                                                               | A content region has no items, cannot proceed, or is loading and needs explanation plus an optional action.                                                                                                                                                                                                                                              | Do not use it for an inline status update; use `StateBanner`. Do not use it for transient success; use `wa-toast`/`wa-toast-item` or the application's toast system.                                                                                                                                                                       | Delegate its optional action; it composes `LoadingSpinner` when busy.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Empty/busy policy, recovery action, illustration, and copy.                                                                                              | `@kerfjs/ui/empty-state`                                                                  | [Feedback ownership](./component-contract.md#extracted-versus-application-specific) |
 
@@ -304,6 +319,18 @@ title minimum height, and border-width tokens for section density.
 Set `--kui-list-group-divider-color` on a containing `List` to give
 `ListHeader`, `ListItem`, and `ListActionRow` the same before/after divider
 color; each row otherwise uses the quiet neutral border tone.
+Set `--kui-list-row-padding-inline` on a containing `List` to give `ListItem`
+and `ListActionRow` rows one leading inline inset: both start their leading
+icons on the same edge at any value, and the token defaults to
+`--kui-layout-item-padding`. `--kui-list-item-padding-inline` still overrides
+it for `ListItem` rows alone, so use the shared token whenever the two row kinds
+share a list.
+Both row kinds also draw their untiled leading icon at one shared size,
+`--kui-list-row-icon-size` (default 18px), so a list that mixes them starts
+their labels on one edge too. Set it on the containing `List` to resize both
+row kinds together; `--kui-list-item-icon-size` still overrides it for
+`ListItem` rows alone. An `iconTile` keeps its 32px tile and 18px glyph at any
+value.
 For a filled command list, set `--kui-list-item-background` and
 `--kui-list-item-border` on the list or row. Scope `--kui-list-item-color`,
 `--kui-list-item-hover-background`, `--kui-list-item-selected-color`, and
@@ -324,7 +351,10 @@ trailing zone that should take a full second row when expanded. `responsiveAt`
 chooses the compact or narrow container breakpoint. The leading identity stays
 in the first row. Set `centerAlign="balanced"` when the center zone must sit on
 the toolbar's midpoint despite unequal or empty side content; it gives the
-leading and trailing zones equal tracks. `--kui-toolbar-leading-min-width`,
+leading and trailing zones equal tracks. A lone `ToolbarText` in a balanced
+center is a navigation-bar title: the side zones keep their content width and
+the title truncates first, centered while the sides leave room (NavStack uses
+this once it shows a back control). `--kui-toolbar-leading-min-width`,
 `--kui-toolbar-trailing-gap`, `--kui-toolbar-trailing-justify`, and the
 `--kui-toolbar-*-padding-inline` zone tokens adjust local geometry without
 selecting toolbar anatomy from application CSS.
@@ -356,7 +386,7 @@ group; set `--kui-token-search-editor-min-width` only when a wider editor is
 required.
 
 - `Toolbar` serves persistent app chrome and headings; the zone contents and accessible naming distinguish the purpose.
-- `TabBar` changes tabpanels and supports overflow/reorder; `SegmentedControl` chooses among a few compact views; `ChoiceChips` keeps a larger exclusive set visible as wrapping pills; `Select` handles a longer value list.
+- `TabBar` changes tabpanels and supports overflow/reorder; `SegmentedControl` chooses among a few compact views; `ChoiceChips` keeps a larger exclusive set (or, with `multiple`, any-number set) visible as wrapping pills; `Select` handles a longer value list.
 
 Use `AppTab presentation="icon-only"` with its `name` kept as the accessible
 tab name. For segmented tabs that should show names in a wide reader and icons
@@ -384,7 +414,9 @@ beside that pinned tab. `wireTabBars` measures the pinned inset and provides
 enough end scroll room for the last peer to align there; a partial peer can
 still appear at the trailing edge as an overflow cue. This mode also aligns a
 newly selected tab at the pinned edge in LTR and RTL. Set the prop on the bar,
-without styling its strip or tab internals.
+without styling its strip or tab internals. With `snapTabs`, keep the trailing
+zone non-shrinking (the default `--kui-tab-bar-trailing-flex`): the reserved
+end room counts toward the strip's share when both zones shrink.
 Set the public
 `--kui-app-tab-pinned-background` token if the surrounding surface differs from
 the default; the pinned tab must cover peers as they scroll beneath it. Its
@@ -398,8 +430,13 @@ scroll correction.
 - `StateBanner` persists beside affected work; `EmptyState` replaces absent content; `wa-callout` is contextual ecosystem content; `wa-toast` and `wa-toast-item` are transient and must not carry the only copy of important state.
 
 For a banner with multi-line supporting copy, use `copyLayout="stacked"` to put
-the detail below the title and badge. Use `actionPlacement="below"` when its
-action needs a separate trailing row. The default values keep both inline;
+the detail below the title and badge. The default `actionPlacement="trailing"`
+keeps the action beside the copy while the copy has room and moves it to its
+own end-aligned trailing row when the banner is narrow (a phone, a sidebar),
+so a group of buttons never squeezes or covers the title; no breakpoint or
+`actionPlacement` switch is needed for narrow layouts. Use
+`actionPlacement="below"` when the action should always take a separate
+trailing row. The default copy layout keeps the detail inline;
 `--kui-state-banner-copy-gap` and `--kui-state-banner-copy-row-gap` adjust the
 stacked copy's spacing at an instance boundary.
 
@@ -494,8 +531,13 @@ To apply a saved search or restore a query programmatically, call `model.replace
 When one root contains both kinds of field, a registered model enables chip keyboard behavior only for its own field. Other fields keep native editing unless the root opts into `keyboard` with an application removal callback.
 For an icon action at the end of the field, pass `trailingAction` with `icon`,
 accessible `label`, and delegated `action` (plus optional `id`). The component
-renders a button that fills the trailing hit target. Reserve `trailing` for
-passive content such as a shortcut hint.
+renders a compact button beside the clear button, with the same size, hover,
+focus ring, and cursor, in every presentation. For a help toggle that opens a
+surface, set `expanded` (and `haspopup`, plus `controls` while it is open); for
+an on/off toggle, set `pressed`. The open or pressed state keeps the hover fill.
+Put domain `data-*` metadata in `attributes`. Never style your own button into
+the `trailing` slot; reserve `trailing` for passive content such as a shortcut
+hint.
 Set `fill` on a collapsible `TokenSearchField` in a stretched Toolbar center to
 use the available width when expanded; the field and its search group retain
 their compact widths when collapsed.
@@ -505,6 +547,8 @@ unset.
 
 `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 composition
 
 Use `ToolbarText tone="dark"` on a loud or photo-backed toolbar surface to
@@ -573,7 +617,7 @@ the control's dimensions, shows `LoadingSpinner` in its icon slot, sets
 | ------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | Identity or title text         | `<ToolbarText text="…" size="large" />` (or `xlarge` for a page/panel title that fits) | Wrap in a `single` borderless group only when it must align with adjacent control pills                           |
 | One or more icon/text buttons  | `<ToolbarControlGroup>{buttons}</ToolbarControlGroup>`                                 | Use `buttonAppearance="push"` for toggle buttons with `aria-pressed`; `single` for a lone control                 |
-| One primary application action | `trailing={<wa-button variant="brand">New ticket…</wa-button>}`                        | The standalone button keeps its Web Awesome chrome; use `variant="danger"` when the action is destructive         |
+| One primary application action | `trailing={<wa-button variant="brand">New Ticket…</wa-button>}`                        | The standalone button keeps its Web Awesome chrome; use `variant="danger"` when the action is destructive         |
 | An exclusive view switch       | `<ToolbarControlGroup><SegmentedControl … /></ToolbarControlGroup>`                    | Not `TabBar`, which switches tabpanels                                                                            |
 | A value list                   | `<ToolbarControlGroup><Select … /></ToolbarControlGroup>`                              | Register `@kerfjs/ui/select/register` once; use `focusRingOwner="group"` so focus follows the group's geometry    |
 | A command menu                 | `<ToolbarControlGroup single nestedDropdown><PopupMenu … /></ToolbarControlGroup>`     | Register `@kerfjs/ui/popup-menu/register` once; set `menuInset` on the group                                      |
@@ -634,7 +678,7 @@ menu.
     label="Sort"
     icon={<LucideIcon icon={ArrowDownAZ} name="arrow-down-a-z" />}
     items={[
-      { label: "Recently updated", action: "sort-recent" },
+      { label: "Recently Updated", action: "sort-recent" },
       { label: "Priority", action: "sort-priority" },
     ]}
   />
@@ -653,7 +697,7 @@ items shape covers single-line and batch actions; compute each batch child's
 <PopupMenu
   label="Line actions"
   items={[
-    { label: 'Copy reference', action: 'copy-reference', attributes: { 'data-item-id': lineId } },
+    { label: 'Copy Reference', action: 'copy-reference', attributes: { 'data-item-id': lineId } },
     { label: 'Decide', submenu: [
       { kind: 'heading', label: 'Review' },
       { label: 'Approve', action: 'decide', checked: current === 'approve', attributes: { 'data-item-id': lineId, 'data-decision': 'approve' } },
@@ -670,8 +714,11 @@ items shape covers single-line and batch actions; compute each batch child's
 For a flat command menu with persistent sort choices, group commands under
 `heading` entries and set `checked` explicitly on each choice. Checked rows
 show a checkmark; the background marks the current keyboard row, as in `Select`.
-Only items with `checked: true` or `checked: false` reserve checkmark space.
-Omit `checked` for a plain command, including one beside checkbox items.
+Items with `checked: true` or `checked: false` reserve checkmark space, and so
+does every plain command in a menu level (the top menu or one submenu) that
+holds such an item, so icons and labels line up across the level; a level
+without a choice keeps the compact start. Omit `checked` for a plain command,
+including one beside checkbox items.
 Commands still dispatch their own `data-action` once on pointer and keyboard
 selection.
 
@@ -715,6 +762,9 @@ remain siblings. `trailingActionVisibility="interaction"` keeps the action
 available on hover and keyboard focus and automatically leaves it visible on
 non-hover devices. These props own presentation only—the application still
 owns labels, status meaning, action policy, selection, and domain metadata.
+`density="compact"` makes a single-line row 36px tall (42px with `iconTile`),
+the same height as a compact `ListItem`, so the two row kinds stay level in a
+dense mixed list; a standard row is 44px.
 
 When the trailing control is an overflow menu ("…" with Edit, Delete, …),
 pass `trailingMenu: { label, icon, items, placement?, disabled? }` instead of
@@ -832,6 +882,40 @@ requires a string label so the title cannot lose text hidden inside markup.
 </Chip>
 ```
 
+## File and link chips
+
+Give `Chip` an `href` when a short chip should open or download something,
+such as the files a chat message references. The chip becomes a native `<a>`
+with the same geometry, icon slot, truncation, and focus ring, plus hover
+feedback. `download` is `true` or the suggested file name; `external` opens a
+new tab with `rel="noopener noreferrer"` and announces it, like
+`ListItemLink`. A link chip cannot also carry a remove button. Use
+`ListItemLink` for a navigation row and `ToolbarActionLink` in a toolbar.
+
+Inside a `brand-loud` or `neutral` `ContentItem` bubble, set
+`tone="inherit"`: the chip follows the bubble's foreground and draws its shape
+with a currentColor border (soft for `quiet`, full strength for `outline` and
+`solid`) instead of a fill, so its label keeps the bubble's text contrast.
+Its hover strengthens the border and underlines the label, and its focus ring
+follows the foreground. Semantic tones keep their fills and add a currentColor
+wash on hover. File names are data: keep their spelling.
+
+```tsx
+<Row gap="xs" wrap>
+  {files.map((file) => (
+    <Chip
+      tone="inherit"
+      href={file.url}
+      download={file.name}
+      icon={<LucideIcon icon={FileText} name="file-text" />}
+      truncate
+    >
+      {file.name}
+    </Chip>
+  ))}
+</Row>
+```
+
 ## Wrapping exclusive choices
 
 Use `ChoiceChips` when one value is chosen from a visible set that does not
@@ -844,7 +928,8 @@ The pills wrap with the standard 8px control gap; never wrap a
 borders turn ragged across rows.
 
 Lead a choice with `swatch` for a color (a `CssColor` from `uiColor()`,
-`colorVar()`, or `foregroundColor()`), `swatch: 'transparent'` for the
+`colorVar()`, or the `fillColor` helper — `fillColor('#3b82f6')` — for an
+application-chosen CSS color; never `foregroundColor()` for a fill), `swatch: 'transparent'` for the
 no-color option (an outlined dot struck through diagonally), or a decorative
 `icon`. Keep every label visible: the swatch and the selected tint are
 supplementary. Name the group with `label`, or with `labelledBy` pointing at a
@@ -859,12 +944,54 @@ visible `FieldLabel`.
   action="select-command-color"
   choices={[
     { value: 'transparent', label: 'Transparent', swatch: 'transparent' },
-    { value: 'blue', label: 'Blue', swatch: foregroundColor('#3b82f6') },
-    { value: 'green', label: 'Green', swatch: foregroundColor('#22c55e') },
+    { value: 'blue', label: 'Blue', swatch: fillColor('#3b82f6') },
+    { value: 'green', label: 'Green', swatch: fillColor('#22c55e') },
   ]}
 />
 ```
 
+### Wrapping multiple choices
+
+Set `multiple` when the person may turn any number of the visible options on
+or off — label filters, or the intents an annotation carries. The same pills
+are then native checkboxes in a `role="group"`: each pill is a Tab stop, Space
+toggles it, and every checked value submits under `name`. `value` becomes a
+`readonly Value[]` (the type rejects a single value, and a single group
+rejects an array). Delegate the `action` on `change` and read the checked
+boxes by `name`, which lists them in choice order. A multiple group takes no `required`. Prefer a
+multiple `Select` when the option list is long or space is tight.
+
+On dark inverse chrome, such as a media viewer, put the chips inside a dark
+appearance scope (`.wa-dark`, or any `color-scheme: dark` ancestor) rather
+than restyling them: every chip color is a theme token that follows the scope.
+
+```tsx
+<ChoiceChips
+  name="intents"
+  label="Annotation Intents"
+  multiple
+  value={annotation.intents}
+  action="toggle-annotation-intent"
+  choices={[
+    { value: 'comment', label: 'Comment' },
+    { value: 'bug', label: 'Bug' },
+    { value: 'question', label: 'Question' },
+  ]}
+/>
+```
+
+```ts
+delegateActions(root, 'change', {
+  'toggle-annotation-intent': () => {
+    annotation.intents = [
+      ...root.querySelectorAll<HTMLInputElement>(
+        'input[name="intents"]:checked',
+      ),
+    ].map((box) => box.value);
+  },
+});
+```
+
 ## Web Awesome overlap policy
 
 Web Awesome catalog coverage means supported and themed, not preferred. Import

package/docs/composer.md

@@ -0,0 +1,143 @@
+# Composer
+
+`Composer` (`@kerfjs/ui/composer`, CSS `@kerfjs/ui/composer.css`) is the chat
+or prompt composer: the place a person writes a message, assistant prompt, or
+reply and sends it with a trailing action. It replaces app-owned composer
+chrome, such as a `wa-textarea` and a button wrapped in application CSS that
+draws a frame, a focus border, and a shadow.
+
+## Contract
+
+```tsx
+<Composer
+  id="assistant-message"
+  name="message"
+  label="Message"
+  placeholder="Ask about this build"
+  hint="Answers use the latest nightly build."
+  minRows={1}
+  maxRows={8}
+  actions={
+    <wa-button variant="brand" data-action="send-message">
+      Send
+    </wa-button>
+  }
+/>
+```
+
+- **Frame.** The root is a raised surface (`--kui-color-surface-raised`) with
+  the standard 1px neutral border, the large radius (`--kui-radius-l`), and
+  `--kui-shadow-l`. While focus is anywhere within it, including on a trailing
+  action, the border turns `--kui-color-brand-border-loud`. The frame owns
+  8px padding, so a composer placed 8px from a container edge puts its text on
+  the same 17px column as a `List` of content items beside it.
+- **Field.** A native, borderless `<textarea>` named by `label`. It sizes to
+  its content with `field-sizing: content`, between `minRows` (default 1) and
+  `maxRows` (default 8) lines, and scrolls past the maximum. Both bounds are
+  positive integers, and `maxRows` is at least `minRows`; otherwise `Composer`
+  throws a `RangeError`. In an engine without `field-sizing`, the field keeps
+  a fixed height of three lines, clamped to the bounds, and scrolls.
+- **Action row.** Below the field: an optional quiet `hint` at the text start
+  and the trailing `actions`, normally one brand Send button. With an `id`,
+  the hint is the field's accessible description (`<id>-hint`).
+- **Value.** `value` seeds the field (a restored draft, or `''`). The app
+  reads the textarea in its send action, clears it, and re-renders.
+- **Disabled.** `disabled` disables the field; the app disables or marks busy
+  its own actions.
+- **Placement.** `slot` assigns it to a web component slot, such as a
+  `wa-dialog`'s `footer`. `rootAttributes` takes safe `data-*` identity.
+- **Enter to send.** `submitOnEnter` opts in to the keyboard contract below;
+  it marks the root `data-submit-on-enter="true"` (protected from
+  `rootAttributes`) and gives the field `aria-keyshortcuts="Enter"`.
+
+The app owns sending, any other keyboard shortcut, what a sent message looks
+like, and where the composer sits.
+
+## Enter to send
+
+Set `submitOnEnter` and call `wireComposers` once over an ancestor of every
+such composer; it returns a disposer:
+
+```ts
+import { wireComposers } from '@kerfjs/ui/wire-composers';
+
+const stopComposers = wireComposers(app);
+```
+
+In an opted-in composer's field:
+
+| Key                                          | Result                                                                                                    |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Enter, Cmd+Enter, Ctrl+Enter                 | Clicks the composer's **first trailing action**; the newline is suppressed.                               |
+| Shift+Enter, Alt+Enter                       | Inserts a newline, as in any textarea.                                                                    |
+| Enter committing an IME composition          | Left to the input method: `isComposing`, keyCode 229, or between `compositionstart` and `compositionend`. |
+| Enter on an empty or whitespace-only message | Nothing: no send and no newline.                                                                          |
+| Auto-repeating Enter (key held down)         | Nothing.                                                                                                  |
+
+The first trailing action is the first `wa-button`, `button`, or
+`[data-action]` element inside `actions`. Clicking it means the keyboard send
+runs the same delegated `data-action` handler as a pointer send, so the app
+writes one send handler that reads the field, clears it, and re-renders. The
+click does not move focus, so the person keeps typing. Nothing is sent while
+the field is `disabled`, or while that action has a `disabled` attribute or
+property, a `loading` attribute (a busy `wa-button`), or
+`aria-disabled="true"`; the Enter is still suppressed, so a message waiting on
+a busy Send does not gain a newline.
+
+Leave `submitOnEnter` off for a long-form prompt where Enter should be a
+newline, and send with the action alone. A visible `hint` may also state the
+shortcut ("Enter to send, Shift+Enter for a new line") when the audience may
+not expect it; `aria-keyshortcuts` already announces it to assistive
+technology.
+
+## In a chat dialog
+
+A chat dialog floats the composer over its transcript. Use a `DialogSurface`
+with `bodyLayout="fill-last"` and `footerPresentation="floating"` (and
+`footerInset="none"`, since the composer draws its own frame), and slot the
+composer into the footer:
+
+```tsx
+<DialogSurface height={remify(560)} bodyInset="none" bodyLayout="fill-last" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
+  <wa-dialog id="assistant" label="Assistant">
+    <StateBanner title="Answers use the latest nightly build." tone="neutral" />
+    <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">{messages}</List>
+    <Composer submitOnEnter slot="footer" id="assistant-message" name="message" label="Message" placeholder="Ask about this build" actions={send} />
+  </wa-dialog>
+</DialogSurface>;
+```
+
+The floating footer is transparent, so the composer's own frame and shadow
+lift it over the transcript. The transcript's `scrollClearance="block-end"`
+lets messages scroll visibly beneath the composer while the last one still
+comes to rest above it, following the composer's measured height as it grows.
+Without the opt-in, the dialog body reserves that height below the transcript
+instead.
+
+## Do not
+
+- Wrap it in a framed `ContentItem`, card, or bordered container; it owns its
+  frame, padding, and shadow.
+- Style its field, frame, or action row from application CSS. A variation it
+  does not offer is a component gap.
+- Use it for an ordinary form field submitted with the rest of a form; use
+  `wa-textarea` with a `FieldLabel`.
+
+## Verification
+
+`tests/unit/composer.test.tsx` covers serialization, the hint description,
+row bounds, and protected attributes; `tests/unit/wire-composers.test.tsx`
+covers the Enter-to-send matrix (modifiers, IME, empty, repeat, disabled
+field and actions, first action only, disposal). `tests/browser/composer.spec.ts` covers
+the focus-within border, growth up to `maxRows` and then scrolling, the action
+row geometry, and the send flow at wide and phone widths, and, in Chromium,
+Firefox, and WebKit, Enter, Shift+Enter, Cmd/Ctrl+Enter, empty messages, and
+IME composition (dispatched composition events and keyCode 229). In
+Chromium it also drives a real IME composition through the DevTools protocol
+(`Input.imeSetComposition`, then `Input.insertText` to commit). That test
+asserts the engine's own event order: an Enter keydown flagged `isComposing`
+while composing, the committing `Process` keydown with keyCode 229, then
+`compositionend`. None of those sends, the committed text lands in the field,
+and the next Enter sends it;
+`tests/browser/surface-scaffold.spec.ts` covers the composer in the floating
+footer of the chat dialog, including Enter to send.

package/docs/design/templates/choice-chips/multiple-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 88" width="600" height="88"><defs><clipPath id="ishc0"><rect x="21" y="21" width="68.8" height="30" rx="15"/></clipPath><clipPath id="ishc1"><rect x="33" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp2"><rect x="51" y="29" width="26.8" height="14"/></clipPath><clipPath id="ct3"><rect x="51" y="29" width="26.8" height="14"/></clipPath><clipPath id="ishc4"><rect x="111.8" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp5"><rect x="129.8" y="29" width="52.3" height="14"/></clipPath><clipPath id="ct6"><rect x="129.8" y="29" width="52.3" height="14"/></clipPath><clipPath id="ishc7"><rect x="204.1" y="21" width="76.4" height="30" rx="15"/></clipPath><clipPath id="ishc8"><rect x="216.1" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp9"><rect x="234.1" y="29" width="34.4" height="14"/></clipPath><clipPath id="ct10"><rect x="234.1" y="29" width="34.4" height="14"/></clipPath><clipPath id="ishc11"><rect x="302.5" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp12"><rect x="320.5" y="29" width="47.2" height="14"/></clipPath><clipPath id="ct13"><rect x="320.5" y="29" width="47.2" height="14"/></clipPath><clipPath id="ishc14"><rect x="401.7" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp15"><rect x="419.7" y="29" width="41.1" height="14"/></clipPath><clipPath id="ct16"><rect x="419.7" y="29" width="41.1" height="14"/></clipPath></defs><rect x="20" y="20" width="70.8" height="32" rx="16" fill="rgb(40,57,66)"/><g clip-path="url(#ishc0)"><path d="M17 17h76.8v38H17zm19 5h38.8a14 14 0 0 1 14 14 14 14 0 0 1-14 14H36a14 14 0 0 1-14-14 14 14 0 0 1 14-14" fill="rgb(100,210,255)" fill-rule="evenodd"/></g><rect x="20.5" y="20.5" width="70" height="31" rx="15.5" fill="none" stroke="rgb(100,210,255)" stroke-width="1"/><rect x="33" y="30" width="12" height="12" rx="6" fill="rgb(239,68,68)"/><g clip-path="url(#ishc1)"><path d="M29 26h20v20H29zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(245,245,247,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp2)"><g clip-path="url(#ct3)"><text x="51" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(138,203,255)">Bug</text></g></g><rect x="98.8" y="20" width="96.3" height="32" rx="16" fill="rgb(28,28,30)"/><rect x="99.5" y="20.5" width="95" height="31" rx="15.5" fill="none" stroke="rgba(253,253,255,0.196)" stroke-width="1"/><rect x="111.8" y="30" width="12" height="12" rx="6" fill="rgb(59,130,246)"/><g clip-path="url(#ishc4)"><path d="M107.8 26h20v20h-20zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(245,245,247,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp5)"><g clip-path="url(#ct6)"><text x="129.81" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(245,245,247)">Feature</text></g></g><rect x="203.1" y="20" width="78.4" height="32" rx="16" fill="rgb(40,57,66)"/><g clip-path="url(#ishc7)"><path d="M200.1 17h84.4v38h-84.4zm19 5h46.4a14 14 0 0 1 14 14 14 14 0 0 1-14 14h-46.4a14 14 0 0 1-14-14 14 14 0 0 1 14-14" fill="rgb(100,210,255)" fill-rule="evenodd"/></g><rect x="203.5" y="20.5" width="77" height="31" rx="15.5" fill="none" stroke="rgb(100,210,255)" stroke-width="1"/><rect x="216.1" y="30" width="12" height="12" rx="6" fill="rgb(34,197,94)"/><g clip-path="url(#ishc8)"><path d="M212.1 26h20v20h-20zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(245,245,247,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp9)"><g clip-path="url(#ct10)"><text x="234.06" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(138,203,255)">Docs</text></g></g><rect x="289.5" y="20" width="91.2" height="32" rx="16" fill="rgb(28,28,30)"/><rect x="289.5" y="20.5" width="91" height="31" rx="15.5" fill="none" stroke="rgba(253,253,255,0.196)" stroke-width="1"/><rect x="302.5" y="30" width="12" height="12" rx="6" fill="rgb(168,85,247)"/><g clip-path="url(#ishc11)"><path d="M298.5 26h20v20h-20zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(245,245,247,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp12)"><g clip-path="url(#ct13)"><text x="320.47" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(245,245,247)">Design</text></g></g><rect x="388.7" y="20" width="85.1" height="32" rx="16" fill="rgb(28,28,30)"/><rect x="389.5" y="20.5" width="84" height="31" rx="15.5" fill="none" stroke="rgba(253,253,255,0.196)" stroke-width="1"/><rect x="401.7" y="30" width="12" height="12" rx="6" fill="rgb(107,114,128)"/><g clip-path="url(#ishc14)"><path d="M397.7 26h20v20h-20zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(245,245,247,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp15)"><g clip-path="url(#ct16)"><text x="419.7" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(245,245,247)">Chore</text></g></g></svg>

package/docs/design/templates/choice-chips/multiple.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 88" width="600" height="88"><defs><clipPath id="ishc0"><rect x="21" y="21" width="68.8" height="30" rx="15"/></clipPath><clipPath id="ishc1"><rect x="33" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp2"><rect x="51" y="29" width="26.8" height="14"/></clipPath><clipPath id="ct3"><rect x="51" y="29" width="26.8" height="14"/></clipPath><clipPath id="ishc4"><rect x="111.8" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp5"><rect x="129.8" y="29" width="52.3" height="14"/></clipPath><clipPath id="ct6"><rect x="129.8" y="29" width="52.3" height="14"/></clipPath><clipPath id="ishc7"><rect x="204.1" y="21" width="76.4" height="30" rx="15"/></clipPath><clipPath id="ishc8"><rect x="216.1" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp9"><rect x="234.1" y="29" width="34.4" height="14"/></clipPath><clipPath id="ct10"><rect x="234.1" y="29" width="34.4" height="14"/></clipPath><clipPath id="ishc11"><rect x="302.5" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp12"><rect x="320.5" y="29" width="47.2" height="14"/></clipPath><clipPath id="ct13"><rect x="320.5" y="29" width="47.2" height="14"/></clipPath><clipPath id="ishc14"><rect x="401.7" y="30" width="12" height="12" rx="6"/></clipPath><clipPath id="cp15"><rect x="419.7" y="29" width="41.1" height="14"/></clipPath><clipPath id="ct16"><rect x="419.7" y="29" width="41.1" height="14"/></clipPath></defs><rect x="20" y="20" width="70.8" height="32" rx="16" fill="rgb(214,233,249)"/><g clip-path="url(#ishc0)"><path d="M17 17h76.8v38H17zm19 5h38.8a14 14 0 0 1 14 14 14 14 0 0 1-14 14H36a14 14 0 0 1-14-14 14 14 0 0 1 14-14" fill="rgb(0,117,219)" fill-rule="evenodd"/></g><rect x="20.5" y="20.5" width="70" height="31" rx="15.5" fill="none" stroke="rgb(0,117,219)" stroke-width="1"/><rect x="33" y="30" width="12" height="12" rx="6" fill="rgb(239,68,68)"/><g clip-path="url(#ishc1)"><path d="M29 26h20v20H29zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(29,29,31,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp2)"><g clip-path="url(#ct3)"><text x="51" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(26,93,207)">Bug</text></g></g><rect x="98.8" y="20" width="96.3" height="32" rx="16" fill="rgb(255,255,255)"/><rect x="99.5" y="20.5" width="95" height="31" rx="15.5" fill="none" stroke="rgba(0,0,28,0.18)" stroke-width="1"/><rect x="111.8" y="30" width="12" height="12" rx="6" fill="rgb(59,130,246)"/><g clip-path="url(#ishc4)"><path d="M107.8 26h20v20h-20zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(29,29,31,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp5)"><g clip-path="url(#ct6)"><text x="129.81" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(29,29,31)">Feature</text></g></g><rect x="203.1" y="20" width="78.4" height="32" rx="16" fill="rgb(214,233,249)"/><g clip-path="url(#ishc7)"><path d="M200.1 17h84.4v38h-84.4zm19 5h46.4a14 14 0 0 1 14 14 14 14 0 0 1-14 14h-46.4a14 14 0 0 1-14-14 14 14 0 0 1 14-14" fill="rgb(0,117,219)" fill-rule="evenodd"/></g><rect x="203.5" y="20.5" width="77" height="31" rx="15.5" fill="none" stroke="rgb(0,117,219)" stroke-width="1"/><rect x="216.1" y="30" width="12" height="12" rx="6" fill="rgb(34,197,94)"/><g clip-path="url(#ishc8)"><path d="M212.1 26h20v20h-20zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(29,29,31,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp9)"><g clip-path="url(#ct10)"><text x="234.06" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(26,93,207)">Docs</text></g></g><rect x="289.5" y="20" width="91.2" height="32" rx="16" fill="rgb(255,255,255)"/><rect x="289.5" y="20.5" width="91" height="31" rx="15.5" fill="none" stroke="rgba(0,0,28,0.18)" stroke-width="1"/><rect x="302.5" y="30" width="12" height="12" rx="6" fill="rgb(168,85,247)"/><g clip-path="url(#ishc11)"><path d="M298.5 26h20v20h-20zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(29,29,31,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp12)"><g clip-path="url(#ct13)"><text x="320.47" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(29,29,31)">Design</text></g></g><rect x="388.7" y="20" width="85.1" height="32" rx="16" fill="rgb(255,255,255)"/><rect x="389.5" y="20.5" width="84" height="31" rx="15.5" fill="none" stroke="rgba(0,0,28,0.18)" stroke-width="1"/><rect x="401.7" y="30" width="12" height="12" rx="6" fill="rgb(107,114,128)"/><g clip-path="url(#ishc14)"><path d="M397.7 26h20v20h-20zm10 5a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5" fill="rgba(29,29,31,0.2)" fill-rule="evenodd"/></g><g clip-path="url(#cp15)"><g clip-path="url(#ct16)"><text x="419.7" y="41" font-family="system-ui, &quot;-apple-system&quot;, sans-serif" font-size="14" font-weight="650" fill="rgb(29,29,31)">Chore</text></g></g></svg>