@logicplanes/kaeso-ui 0.2.1 → 0.3.0

package/ai/component-registry.md

@@ -1,6 +1,6 @@
 # @logicplanes/kaeso-ui component registry
 
-Version 0.2.1. Generated from the component types, their descriptions and variants; do not edit.
+Version 0.3.0. Generated from the component types, their descriptions and variants; do not edit.
 
 ## app-frame
 
@@ -213,6 +213,8 @@ Bars for comparing values across categories: grouped, stacked, or horizontal for
 | `layout` | `"horizontal" \| "grouped" \| "stacked"` | `grouped` | `grouped` puts each category's bars side by side (default), `stacked` stacks them, and `horizontal` draws bars across for rankings. |
 | `loading` | `boolean` |  | The data is loading: the chart keeps its height and shows a quiet loading bar. |
 | `onRetry` | `(() => void)` |  | Called when Try again is pressed after `error`; without it, the button doesn't show. |
+| `partial` | `{ first?: boolean; last?: boolean; ongoing?: boolean \| undefined; } \| undefined` |  | Marks the `first` or `last` category as covering only part of its span: its bars are drawn lighter and its tooltip says "partial". `ongoing` marks the last one as still counting, such as today, and says "so far". |
+| `shares` | `boolean` | `true` | Shows each series' share of the category's total in the tooltip (on by default). Turn it off when one series is part of another, such as errors within requests. |
 
 ### ChartFrame
 
@@ -392,7 +394,8 @@ A line or area chart of values over time, such as usage, with a crosshair and to
 | `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data. By default it shows when every value is 0. |
 | `emptyText` | `ReactNode` |  | What the empty state says. Defaults to "No data for this period" in the provider's language. |
 | `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails. |
-| `formatTime` | `((t: Date) => string)` |  | Names a point's time in the tooltip, the table and for screen readers, where a point stands for more than its instant: "Week of 3 Aug", "Aug 2026". The axis keeps its calendar ticks. |
+| `formatTick` | `((t: Date) => string)` |  | Names the times under the axis ("3 Aug", "2026"). Defaults to calendar ticks in `timeZone`; pass it with `tickAt="points"` for buckets. |
+| `formatTime` | `((t: Date) => string)` |  | Names a point's time in the tooltip, the table and for screen readers, where a point stands for more than its instant: "Week of 3 Aug", "Aug 2026". |
 | `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats values on the axis and in the tooltip. |
 | `height` | `number` | `240` | The plot's height in px (240 by default). |
 | `hideLegend` | `boolean` |  | Hide the legend (one series). |
@@ -400,7 +403,11 @@ A line or area chart of values over time, such as usage, with a crosshair and to
 | `kind` | `"stacked" \| "line" \| "area"` | `line` | `line` draws lines (default), `area` adds a light fill under each line, and `stacked` stacks the areas. |
 | `loading` | `boolean` |  | The data is loading: the chart keeps its height and shows a quiet loading bar. |
 | `onRetry` | `(() => void)` |  | Called when Try again is pressed after `error`; without it, the button doesn't show. |
+| `partial` | `{ first?: boolean; last?: boolean; ongoing?: boolean \| undefined; } \| undefined` |  | Marks the `first` or `last` point as covering only part of its span: the line to it is dashed and its tooltip says "partial". `ongoing` marks the last one as still counting, such as today, and says "so far". |
+| `shares` | `boolean` | `true` | Shows each series' share of the point's total in the tooltip (on by default). Turn it off when one series is part of another, such as errors within requests. |
 | `threshold` | `{ value: number; label: string; }` |  | A threshold line (a budget) in danger, dashed. |
+| `tickAt` | `"time" \| "points"` | `time` | `time` labels round times, as many as fit (default). `points` sets each point in the middle of an equal step and labels every nth one, as a bar chart places and labels its categories, so a bar chart of the same days lines up with it. |
+| `timeZone` | `string` |  | The zone the axis and the default labels read times in, such as "UTC" for days counted in UTC. Defaults to the zone set with `setFormatTimeZone`, else the viewer's. |
 
 ## checkbox
 
@@ -600,7 +607,7 @@ Free text with suggestions.
 | `defaultValue` | `string` |  | The text in the input on first render. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
@@ -615,19 +622,20 @@ Free text with suggestions.
 
 ### Combobox
 
-A pill input with a filtered list: matched characters highlighted, async, chips for many, create.
+A pill input with a filtered list: matched characters highlighted, async, chips for many, create. It shows the first 100 matches and says how many more there are; for lists people scroll through, use `CommandList`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `options` * | `ComboboxOption[]` |  | The options to choose from. |
 | `aria-label` | `string` |  | The accessible name, for when there is no visible label. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `createLabel` | `((label: string) => string)` |  | The words of the offer to add what was typed; `Add “…”` by default. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `defaultValue` | `string \| string[] \| null` |  | The value on first render, when the component keeps its own value. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
 | `emptyText` | `ReactNode` |  | What the empty list says: "No models match". Defaults to "No results" in the provider's language. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
 | `label` | `ReactNode` |  | The visible label. |
@@ -635,12 +643,13 @@ A pill input with a filtered list: matched characters highlighted, async, chips
 | `loading` | `boolean` |  | Shows a quiet progress line at the top of the list (async results). |
 | `multiple` | `boolean` |  | Allows choosing more than one option; `value` is then a list. |
 | `name` | `string` |  | The field name the value is sent under in a form. |
-| `onCreate` | `((label: string) => void)` |  | Offers "Create “…”" when nothing matches exactly. |
+| `onCreate` | `((label: string) => void)` |  | Offers "Add “…”" when nothing matches exactly. |
 | `onInputValueChange` | `((value: string) => void)` |  | Called with the text typed into the input. |
 | `onValueChange` | `((value: string \| null) => void) \| ((value: string[]) => void)` |  | Called with the chosen value, or the list of values with `multiple`. |
 | `optional` | `boolean` |  | Adds “Optional” to the label, for forms where most fields are required. |
 | `placeholder` | `string` |  | Text shown while there is no value. |
 | `required` | `boolean` |  | Marks it as required in a form. |
+| `searchDelay` | `number` |  | Milliseconds of quiet typing before `onInputValueChange` is called, so a server search runs once per pause, not per keystroke. |
 | `size` | `"md" \| "sm" \| "lg" \| "xl"` |  | The height of the input. |
 | `value` | `string \| string[] \| null` |  | The chosen value, or a list of values with `multiple`, when you control it. |
 
@@ -653,6 +662,73 @@ Splits a label around the query: matched characters in text, the rest secondary
 | `query` * | `string` |  | The part of the text to highlight, ignoring case. |
 | `text` * | `string` |  | The text to show. |
 
+## command-list
+
+`import { CommandList, PickerPopover, PickerTrigger } from "@logicplanes/kaeso-ui/command-list";`
+
+- **height** (command_list): `popover` (default) — At most 480px or 70% of the window, shrinking to its rows: a popover (default); `inline` — Its rows' height up to 360px in a raised frame, kept while searching: a dialog step; `fill` — Fills its parent: a phone sheet or a command palette
+- **size** (command_list): `md` (default) — A 44px search over 34px rows (default); `lg` — A 56px search over 40px rows: the command palette
+- **width** (picker_popover): `sm` — 320px: providers and short lists; `md` (default) — 400px (default); `lg` — 560px: models with their details
+
+### CommandList
+
+A search field over a long list that stays fast with thousands of rows: fuzzy matches on every row's words, groups with sticky captions, the best matches first, arrows, Home, End and Page keys, Enter to choose. The base of every picker.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `aria-label` * | `string` |  | The list's accessible name. |
+| `groups` * | `CommandListGroup[]` |  | The rows, in groups; a group with a label gets a sticky caption with its mark and count, and a loading group keeps its caption while it has no rows yet. |
+| `autoFocus` | `boolean` |  | Focuses the search field when it appears, as in a popover or a dialog step. |
+| `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
+| `defaultQuery` | `string` |  | The search text on first render. |
+| `emptyText` | `ReactNode` |  | What the list says when nothing matches: "No models match". |
+| `escapeClears` | `boolean` | `true` | Escape first clears the search, and only an empty search lets Escape close what holds the list (true by default). |
+| `footer` | `ReactNode` |  | A line under the list, such as key hints. |
+| `height` | `"fill" \| "popover" \| "inline"` |  | How tall it is: bounded in a popover, a fixed raised frame in a dialog, or filling a phone sheet. Inside `PickerPopover` it follows the popover. |
+| `inputProps` | `{ [attribute: `data-${string}`]: string; }` |  | Data attributes for the search field, such as a marker other code looks for. |
+| `loading` | `boolean` |  | Shows a quiet progress line at the top while more rows load. |
+| `match` | `((item: CommandListItem, query: string) => number)` | `(item: CommandListItem, query: string) => commandMatch(query, [item.label, ...(item.keywords ?? [])])` | Scores a row against the search: above 0 keeps it, and higher scores come first. Fuzzy matching on the label and keywords by default. |
+| `multiple` | `boolean` |  | Rows toggle with a checkbox instead of choosing one. |
+| `onEscape` | `(() => void)` |  | Called on Escape when the search field is already empty. |
+| `onInputKeyDown` | `((event: KeyboardEvent<HTMLInputElement>) => void)` |  | Called first with every key pressed in the search field; call `preventDefault` to replace the list's own handling. |
+| `onQueryChange` | `((query: string) => void)` |  | Called with the search text. |
+| `onSelect` | `((value: string) => void)` |  | Called with the value of the row chosen with Enter or a click. |
+| `placeholder` | `string` |  | The search field's placeholder and accessible name ("Search" by default). |
+| `query` | `string` |  | The search text, when you control it. |
+| `searchPrefix` | `ReactNode` |  | Something before the search text, such as the page a palette is on. |
+| `size` | `"md" \| "lg"` | `md` | The search field's and the rows' height: 34px rows, or 40px in the command palette. |
+| `toolbar` | `ReactNode` |  | Controls under the search field: filter chips or a toggle. |
+| `value` | `string \| readonly string[] \| null` |  | The chosen value, or the chosen values with `multiple`. |
+
+### PickerPopover
+
+The frame a picker opens in: a popover under its trigger on wider screens, a full-screen sheet with the search on top on phones.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` * | `ReactNode` |  | The `CommandList`. |
+| `title` * | `string` |  | The popover's accessible name and the sheet's title on phones. |
+| `trigger` * | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The button that opens it, usually a `PickerTrigger`. |
+| `align` | `"start" \| "end"` | `start` | Which edge of the trigger the popover lines up with. |
+| `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
+| `open` | `boolean` |  | Whether it is open, when you control it. |
+| `width` | `"md" \| "sm" \| "lg"` | `md` | The popover's width on wider screens. |
+
+### PickerTrigger
+
+The pill that opens a picker and shows its value, in the same looks and sizes as `Select`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `appearance` | `"ghost" \| "default" \| "header"` | `default` | A raised pill, quiet in a settings row, or transparent in a column header. |
+| `children` | `ReactNode` |  | The chosen value as it should read; the placeholder shows without it. |
+| `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
+| `fullWidth` | `boolean` |  | Fills the container. |
+| `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
+| `placeholder` | `ReactNode` |  | Text shown while nothing is chosen. |
+| `size` | `"md" \| "sm" \| "lg" \| "xl"` | `md` | The height of the pill. |
+
 ## command-palette
 
 `import { CommandPalette } from "@logicplanes/kaeso-ui/command-palette";`
@@ -748,6 +824,7 @@ A table for many rows: sorting, selection, loading and empty states, more rows o
 | `loading` | `boolean` |  | Shows skeleton rows while the first page loads. |
 | `loadingMore` | `boolean` |  | Shows that more rows are loading. |
 | `manualSorting` | `boolean` |  | Sorting happens on the server: the data arrives sorted. |
+| `onHiddenColumnsChange` | `((ids: string[]) => void)` |  | Called with the ids of the columns left out at the table's width, so a kept column can show what they held. |
 | `onLoadMore` | `(() => void)` |  | Called to load the next rows. |
 | `onRetry` | `(() => void)` |  | Shows a Retry button when loading failed. |
 | `onRowClick` | `((row: T) => void)` |  | Called when a row is clicked; rows then show that they can be opened. |
@@ -782,7 +859,7 @@ A pill showing the date; a popover with the calendar and a typed ISO field.
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
 | `disabledDays` | `((date: Date) => boolean)` |  | Returns `true` for days that can't be chosen. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
@@ -808,7 +885,7 @@ A pill showing the range ("Oct 1 – Oct 12") or its preset ("Last 30 days"); pr
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
 | `disabledDays` | `((date: Date) => boolean)` |  | Returns `true` for days that can't be chosen. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
@@ -834,7 +911,7 @@ Hours and minutes as two segments in one pill; arrows step, typing advances.
 | `defaultValue` | `string` |  | The time on first render, as `HH:mm`. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
@@ -874,7 +951,9 @@ Confirms deleting a resource: names the object and the consequence, asks for its
 
 - **tone** (alert_dialog): `danger` (default) — Destructive (default); `warning` — Risky but reversible; `info` — Neutral confirmation
 - **size** (dialog): `sm` — 440px: confirmations, short forms; `md` (default) — 560px: forms (default); `lg` — 720px: two columns, previews
+- **anchor** (dialog): `center` (default) — Centered on the screen (default); `top` — A fixed top edge, for content that changes height, such as the steps of a StepDialog
 - **size** (layer_dialog): `sm` — 440px: confirmations, short forms; `md` (default) — 560px: forms (default); `lg` — 720px: two columns, previews
+- **anchor** (layer_dialog): `center` (default) — Centered on the screen (default); `top` — A fixed top edge, for content that changes height, such as the steps of a StepDialog
 
 ### AlertDialog
 
@@ -898,12 +977,13 @@ Confirms an irreversible action: names it, explains the consequence, optionally
 
 ### Dialog
 
-A modal dialog: 440 / 560 / 720, radius 20, title, description, body, actions. ⌘Enter submits. It stays centered while its content changes, growing or shrinking 200ms from the size it has; the body scrolls between the header and the footer when the content is taller than the screen. Its content unmounts once it has closed; state kept beside it, like a field, a step or a secret, goes in a component inside a DialogScope.
+A modal dialog: 440 / 560 / 720, radius 20, title, description, body, actions. Enter in a single-line field and ⌘/Ctrl+Enter anywhere submit; Enter in a text area adds a line. It stays centered (or, with `anchor="top"`, keeps its top edge) while its content changes, growing or shrinking 200ms from the size it has; the body scrolls between the header and the footer when the content is taller than the screen. Its content unmounts once it has closed; state kept beside it, like a field, a step or a secret, goes in a component inside a DialogScope.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `title` * | `ReactNode` |  | The dialog's heading, also its accessible name. |
-| `busy` | `boolean` |  | Keeps the dialog open while work it started is underway: Escape, a press outside, the close circle, Dialog.Close and ⌘Enter do nothing, so a request is never abandoned or sent twice. |
+| `anchor` | `"center" \| "top"` |  | Where it sits: centered, or with a fixed top edge for content that changes height, so the title never moves. |
+| `busy` | `boolean` |  | Keeps the dialog open while work it started is underway: Escape, a press outside, the close circle, Dialog.Close, Enter and ⌘Enter do nothing, so a request is never abandoned or sent twice. |
 | `children` | `ReactNode` |  | The dialog's content and actions. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `defaultOpen` | `boolean` |  | Whether it starts open, when the component keeps its own state. |
@@ -913,8 +993,9 @@ A modal dialog: 440 / 560 / 720, radius 20, title, description, body, actions.
 | `hideClose` | `boolean` |  | Hide the close circle (rare). |
 | `inline` | `boolean` |  | Render without a portal and backdrop, for documentation and state matrices. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
-| `onSubmit` | `(() => void)` |  | ⌘Enter calls this (usually the primary action). |
+| `onSubmit` | `(() => void)` |  | Enter in a single-line field and ⌘/Ctrl+Enter anywhere call this (usually the primary action); Enter in a text area, a search field, a combobox or a picker, and the Enter that confirms an input method's text, keep their own meaning. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
+| `persistent` | `boolean` |  | A press outside doesn't close it, for forms that would lose what was typed; Escape and the close circle still do. Every StepDialog is persistent. |
 | `size` | `"md" \| "sm" \| "lg"` |  | The dialog's width. |
 | `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The trigger, a single element. |
 
@@ -929,12 +1010,13 @@ Opens a dialog's flow fresh every time: its children mount anew when `open` turn
 
 ### LayerDialog
 
-A stacked dialog: a second layer slides over the first (add model → review values); back returns. The layers below stay as they were. Moving to a layer puts the focus on its first field, or its primary action; Back returns it to the control that opened the layer, scrolled where it was. ⌘/Ctrl+Enter calls onSubmit on every layer.
+A stacked dialog: a second layer slides over the first (add model → review values); back returns. The layers below stay as they were. Moving to a layer puts the focus on its first field, or its primary action; Back returns it to the control that opened the layer, scrolled where it was. Enter in a single-line field and ⌘/Ctrl+Enter call onSubmit on every layer.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `layers` * | `DialogLayer[]` |  | The layers, each with its title, content and footer; one shows at a time, and the ones below it stay mounted and hidden. |
-| `busy` | `boolean` |  | Keeps the dialog open while work it started is underway: Escape, a press outside, the close circle, Dialog.Close and ⌘Enter do nothing, so a request is never abandoned or sent twice. |
+| `anchor` | `"center" \| "top"` |  | Where it sits: centered, or with a fixed top edge for layers of different heights. |
+| `busy` | `boolean` |  | Keeps the dialog open while work it started is underway: Escape, a press outside, the close circle, Dialog.Close, Enter and ⌘Enter do nothing, so a request is never abandoned or sent twice. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `defaultOpen` | `boolean` |  | Whether it starts open, when the component keeps its own state. |
 | `hideClose` | `boolean` |  | Hide the close circle (rare). |
@@ -942,14 +1024,15 @@ A stacked dialog: a second layer slides over the first (add model → review val
 | `layer` | `number` |  | The visible layer; layers above the first slide over it. |
 | `onLayerChange` | `((layer: number) => void)` |  | Called with the index of the layer shown. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
-| `onSubmit` | `(() => void)` |  | ⌘/Ctrl+Enter calls this on every layer; pass the action of the layer shown. |
+| `onSubmit` | `(() => void)` |  | Enter in a single-line field and ⌘/Ctrl+Enter call this on every layer; pass the action of the layer shown. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
+| `persistent` | `boolean` |  | A press outside doesn't close it, for forms that would lose what was typed; Escape and the close circle still do. Every StepDialog is persistent. |
 | `size` | `"md" \| "sm" \| "lg"` |  | The dialog's width. |
 | `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The trigger, a single element. |
 
 ### StepDialog
 
-A form split into steps, one question at a time, like sign-in: the step's title and fields, Back and Continue, the action on the last step. Enter in a field and ⌘/Ctrl+Enter continue. The dialog takes each step's own height and stays centered: it grows or shrinks 200ms from the size it has as the step changes, and the new step drifts in from the side it comes from. With `result`, what the last step made (a key shown once) takes the steps' place in the same dialog, at its own size. Continue and Back move the focus into the step they show (its first field; without one, the primary action, or Back when the last step destroys), and a screen reader hears which step it is.
+A form split into steps, one question at a time, like sign-in: the step's title and fields, Back and Continue, the action on the last step. Enter in a single-line field and ⌘/Ctrl+Enter continue. The dialog takes each step's own height and keeps its top edge where it opened: it grows or shrinks 200ms downward from the size it has as the step changes, so the title never jumps, and the new step drifts in from the side it comes from. With `result`, what the last step made (a key shown once) takes the steps' place in the same dialog, at its own size. Continue and Back move the focus into the step they show (its first field; without one, the primary action, or Back when the last step destroys), and a screen reader hears which step it is.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -980,7 +1063,7 @@ Display options: view, grouping and ordering, toggles, properties.
 |---|---|---|---|
 | `footer` | `ReactNode` |  | Content at the bottom of the options, such as a reset button. |
 | `inline` | `boolean` |  | Render the panel inline (documentation and state matrices). |
-| `properties` | `{ options: { value: string; label: string; }[]; value: string[]; onChange: (v: string[]) => void; }` |  | The properties shown for each item. |
+| `properties` | `{ options: { value: string; label: string; }[]; value: string[]; onChange: (v: string[]) => void; hidden?: string[]; }` |  | The properties shown for each item; `hidden` names those that are on but left out because they don't fit, such as table columns at a narrow width. |
 | `rows` | `DisplayOptionsRow[]` |  | Rows of choices, such as grouping and ordering. |
 | `toggles` | `DisplayOptionsToggle[]` |  | Switches, such as showing archived items. |
 | `trigger` | `"secondary" \| "ghost"` | `secondary` | The look of the button that opens the options. |
@@ -1018,7 +1101,7 @@ The aria wiring a control needs, whether it sits in a <Field> or wraps itself in
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `description` | `ReactNode` |  | One sentence of help under the label. |
-| `error` | `ReactNode` |  | The error message: it marks the field invalid and is read out with the description, but isn't drawn under the field, so show it in a toast too. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color: it marks the field invalid and is read out with the description. |
 | `id` | `string` |  | The id of the control inside, so the label points to it. |
 | `invalid` | `boolean` |  | Marks the field invalid without a message. |
 | `label` | `ReactNode` |  | The field's label. |
@@ -1051,14 +1134,18 @@ A filter as one pill: "Status is 2xx ×", each part opening a menu.
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `defaultValuesOpen` | `boolean` |  | Open the value menu when the chip appears: a filter just added asks for its value at once. |
+| `groups` | `CommandListGroup[]` |  | Choices as ready-made searchable list groups, in place of `values`: rows with marks and details and headings with logos, such as `useModelGroups` or `useProviderGroups` build. |
 | `multiple` | `boolean` |  | Several values may be chosen. |
 | `onOperatorChange` | `((operator: string) => void)` |  | Called with the chosen comparison. |
 | `onRemove` | `(() => void)` |  | Called when the filter is removed. |
 | `onSelectedChange` | `((selected: string[]) => void)` |  | Called with the chosen values. |
+| `onValuesOpenChange` | `((open: boolean) => void)` |  | Called when the value menu opens or closes, so a filter just added can go away when it closes without a value. |
 | `operators` | `string[]` |  | The comparisons people can choose, such as “is” and “is not”. |
 | `propertyIcon` | `IconSvgElement` |  | The icon of the property the filter applies to. |
+| `searchable` | `boolean` |  | Gives the value menu a search field however few choices it has. |
 | `selected` | `string[]` | `[]` | The chosen values. |
-| `values` | `FilterChipChoice[]` |  | Choices for the value menu. |
+| `values` | `FilterChipChoice[]` |  | Choices for the value menu: past 8 it gets a search field, past 50 it opens a fast searchable list grouped by each choice's `group`, such as models by provider. |
+| `width` | `"md" \| "sm" \| "lg"` |  | How wide the searchable list opens: `sm` for providers, `lg` for models with their details. |
 
 ## filter-row
 
@@ -1175,7 +1262,7 @@ A pill text field with the secondary material and the field focus. Takes label,
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
@@ -1211,8 +1298,9 @@ Numbers that stay exact: right-aligned tabular digits, a unit, stepper circles o
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `defaultValue` | `string` |  | The number on first render, as text. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `hideStepper` | `boolean` |  | Hide the stepper circles. |
+| `integer` | `boolean` |  | Whole numbers only, such as a count of days: a numeric keypad on phones and no thousands separators in the field. |
 | `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
@@ -1254,7 +1342,7 @@ Search: a leading icon, a clear circle when filled, an optional shortcut hint. E
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
@@ -1276,7 +1364,7 @@ Masked by default with an eye circle to reveal. Monospace when revealed, never a
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `defaultRevealed` | `boolean` | `false` | Start revealed. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
 | `kind` | `"password" \| "secret"` | `secret` | A password (never revealed once saved) or a secret such as an API key. |
 | `label` | `ReactNode` |  | The visible label. |
@@ -1299,17 +1387,18 @@ Removable tags in a field: Enter, comma and paste split; Backspace removes the l
 | `defaultValue` | `string[]` |  | The tags on first render. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
 | `name` | `string` |  | The field name the value is sent under in a form. |
+| `onInputValueChange` | `((draft: string) => void)` |  | Called with the text typed but not added as a tag yet, so a form can count it before it is added. |
 | `onValueChange` | `((value: string[]) => void)` |  | Called with the tags whenever one is added or removed. |
 | `optional` | `boolean` |  | Adds “Optional” to the label, for forms where most fields are required. |
 | `placeholder` | `string` |  | Text shown while there is no value. |
 | `required` | `boolean` |  | Marks it as required in a form. |
-| `separators` | `string[]` |  | Characters that end a tag, besides Enter. |
-| `validate` | `((tag: string) => string \| true)` |  | Return true for a valid tag, or a message saying what is wrong. Invalid tags stay, marked with a danger ring, and show the message as their tooltip (and to a screen reader); errors are never drawn under the field, so toast it too when someone submits. |
+| `separators` | `string[]` |  | Characters that end a tag, besides Enter; pasted text also splits at line breaks and tabs. |
+| `validate` | `((tag: string) => string \| true)` |  | Return true for a valid tag, or a message saying what is wrong. Invalid tags stay, marked with a danger ring, and show the message as their tooltip; the first one also shows under the field. |
 | `value` | `string[]` |  | The tags, when you control them. |
 
 ### Textarea
@@ -1320,7 +1409,7 @@ A multi-line field: radius 14 (multi-line text cannot be a pill), the same mater
 |---|---|---|---|
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
@@ -1331,20 +1420,30 @@ A multi-line field: radius 14 (multi-line text cannot be a pill), the same mater
 
 ## kaeso
 
-`import { ConversationView, EffectiveAccess, EnvironmentSnippet, KeyDisplay, LimitMeter, ModelLabel, ProviderBadge, ProviderCard, RequestTimeline, RightsMatrix, RolePicker, SecretReveal, StatusCode, UsageBreakdown } from "@logicplanes/kaeso-ui/kaeso";`
+`import { CapabilityIcons, ConversationView, EffectiveAccess, EnvironmentSnippet, KeyDisplay, LimitMeter, ModelLabel, ProviderBadge, ProviderCard, ProviderPicker, RequestTimeline, RightsMatrix, RolePicker, SecretReveal, StatusCode, UsageBreakdown } from "@logicplanes/kaeso-ui/kaeso";`
 
 - **density** (conversation): `default` (default) — 24px between turns (default); `compact` — 16px, inside sheets
 - **layout** (effective_access): `rows` (default) — A row per group: its name, what is granted in words, and how many (default)
 - **provider** (identity): `sm` — 16px, inside table cells; `md` (default) — 20px (default); `lg` — 28px; `xl` — 40px: a provider's own page or card
 - **secret** (moments): `md` (default) — The one-time secret on a well
+- **appearance** (provider_picker): `list` (default) — A search field over every provider, always open: a dialog step (default); `select` — A pill that opens the searchable list: forms and toolbars
 - **origin** (rights_matrix): `preset` — Comes from the role; `added` — Added on top of the role; `removed` — Removed from the role; `none` (default) — Not granted
 - **mode** (rights_matrix): `edit` (default) — Checkboxes, group toggles and requirement hints (default); `readOnly` — A mark per right and, under it, the roles that grant it
 - **appearance** (role_picker): `list` (default) — Every role as a row with its description, built-in then custom (default): invites and role changes; `select` — A pill that opens the roles: filters, table rows and tight forms
 - **limit** (usage): `hard` (default) — Requests over the limit are refused; `soft` — Over the limit only alerts
 
+### CapabilityIcons
+
+A model's capabilities as small icons, each named in a tooltip and read as one list by screen readers.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `capabilities` | `Capability[]` | `[]` | The capabilities: tools, reasoning, vision, pdf, structuredOutput. |
+| `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+
 ### ConversationView
 
-A model conversation from a request log: role captions, prose, tool calls and results, reasoning, images, refusals.
+A model conversation from a request log: role captions, prose, tool calls and results, reasoning, images, refusals. Inline images show; remote ones are links, so viewing a log never fetches them.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1388,6 +1487,7 @@ A redacted key: mono 13 with its state dot, copy of the redacted form, and its a
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `copy` | `boolean` | `true` | Hide the copy circle. |
 | `state` | `KeyState` | `active` | The key's state; disabled, expired and archived keys are shown dimmed. |
+| `stateBadge` | `boolean` | `true` | Shows the state's badge beside a key that isn't active (on by default); turn it off where a heading already names the state. |
 
 ### LimitMeter
 
@@ -1416,16 +1516,19 @@ A model: provider mark, display name, then its id in mono, capability icons with
 | `provider` * | `string` |  | The provider id, such as `openai` or `anthropic`. |
 | `capabilities` | `Capability[]` | `[]` | What the model can do, shown as small marks after its name. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `mark` | `boolean` | `true` | Shows the provider's mark first (default); turn it off in a list grouped under each provider's mark. |
 | `name` | `string` |  | The display name, first. |
+| `providerName` | `string` |  | The provider's name from the gateway's provider list, which names its mark for screen readers; the id without it. |
 
 ### ProviderBadge
 
-A provider's mark on a quiet tile, in the text color so it follows the theme; a letter for providers without one.
+A provider's mark on a quiet tile, in the provider's own one-colour version for the theme; for providers without one, the first letter of their name.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `provider` * | `string` |  | The provider id, such as `openai` or `anthropic`. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `name` | `string` |  | The provider's name from the gateway's provider list: the badge's accessible name, the text `withName` writes and the source of the letter; the id without it. |
 | `size` | `"md" \| "sm" \| "lg" \| "xl"` | `md` | The badge's size. |
 | `withName` | `boolean` |  | Writes the provider's name next to its mark. |
 
@@ -1442,6 +1545,32 @@ A provider and how this place reaches it: its mark, name and connection, the key
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `detail` | `ReactNode` |  | A line under the provider's name, such as how many keys it has. |
 | `keyLabel` | `ReactNode` |  | The key: its name and last four characters, and when it was last used. |
+| `name` | `string` |  | The provider's name from the gateway's provider list, as the card's title; the id without it. |
+
+### ProviderPicker
+
+Choosing a provider from any number of them: a search field over every provider, connected ones first with their key counts, then the rest from A to Z, each with its mark. Always open in a dialog step, or a pill that opens it in forms and toolbars.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `providers` * | `ProviderPickerOption[]` |  | The providers: id, name, whether the organization has connected it, and a short hint such as its key count. |
+| `allLabel` | `string` |  | Select only: a first option for no provider in particular, such as "All providers"; choosing it reports `null`. |
+| `appearance` | `"list" \| "select"` |  | An always-open list for a dialog step, or a pill that opens it. |
+| `aria-label` | `string` |  | The accessible name, for when there is no visible label. |
+| `autoFocus` | `boolean` |  | List only: focuses the search field when it appears. |
+| `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
+| `description` | `ReactNode` |  | One sentence of help under the label. |
+| `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
+| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `label` | `ReactNode` |  | The visible label. |
+| `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
+| `onValueChange` | `((id: string \| null) => void)` |  | Called with the chosen provider's id, or `null` for `allLabel`. |
+| `optional` | `boolean` |  | Adds “Optional” to the label, for forms where most fields are required. |
+| `placeholder` | `string` |  | The search field's placeholder; in a pill without `allLabel`, also the text shown while nothing is chosen. |
+| `required` | `boolean` |  | Marks it as required in a form. |
+| `size` | `"md" \| "sm"` |  | Select only: the height of the pill. |
+| `value` | `string \| null` |  | The chosen provider's id, when you control it. |
 
 ### RequestTimeline
 
@@ -1518,7 +1647,7 @@ A stacked bar of token kinds with the numbers under it, in the fixed series mapp
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tokens` * | `Partial<Record<"input" \| "output" \| "cacheRead" \| "cacheWrite" \| "reasoning", number>>` |  | Tokens by kind: input, output, cache reads and writes, reasoning. |
+| `tokens` * | `Partial<Record<"input" \| "output" \| "cacheRead" \| "cacheWrite" \| "reasoning", number>>` |  | Tokens by kind: input, output, cache reads and writes, reasoning. A kind left out isn't listed, for kinds that can't apply, such as output for embeddings; pass 0 to list it. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 
 ## kbd
@@ -1593,7 +1722,7 @@ A responsive grid.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `align` | `"start" \| "end" \| "baseline" \| "stretch" \| "center"` | `center` | How items line up within their cells. |
+| `align` | `"start" \| "end" \| "center" \| "baseline" \| "stretch"` | `center` | How items line up within their cells. |
 | `as` | `ElementType` |  | The element or component to render as, such as `section` or `ul`. |
 | `columns` | `4 \| 1 \| 2 \| 3 \| 6` | `2` | The number of columns. |
 | `gap` | `0 \| 24 \| 20 \| 32 \| 40 \| 4 \| 2 \| 6 \| 8 \| 12 \| 16 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
@@ -1604,7 +1733,7 @@ A horizontal row that wraps.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `align` | `"start" \| "end" \| "baseline" \| "stretch" \| "center"` | `center` | How items line up across the row. |
+| `align` | `"start" \| "end" \| "center" \| "baseline" \| "stretch"` | `center` | How items line up across the row. |
 | `as` | `ElementType` |  | The element or component to render as, such as `section` or `ul`. |
 | `gap` | `0 \| 24 \| 20 \| 32 \| 40 \| 4 \| 2 \| 6 \| 8 \| 12 \| 16 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
 | `justify` | `"start" \| "end" \| "center" \| "between"` |  | How items are spread along the main axis. |
@@ -1616,7 +1745,7 @@ A vertical stack.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `align` | `"start" \| "end" \| "baseline" \| "stretch" \| "center"` | `center` | How items line up across the column. |
+| `align` | `"start" \| "end" \| "center" \| "baseline" \| "stretch"` | `center` | How items line up across the column. |
 | `as` | `ElementType` |  | The element or component to render as, such as `section` or `ul`. |
 | `gap` | `0 \| 24 \| 20 \| 32 \| 40 \| 4 \| 2 \| 6 \| 8 \| 12 \| 16 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
 | `justify` | `"start" \| "end" \| "center" \| "between"` |  | How items are spread along the main axis. |
@@ -1685,6 +1814,7 @@ The console list: 44px rows on the panel, no lines, metadata on the right, keybo
 | `selectionActions` | `ReactNode` |  | Actions in the floating selection bar. |
 | `selectionBar` | `boolean` | `true` | The floating selection bar; off where the host shows the count itself, as in a dialog. |
 | `virtualizeAbove` | `number` | `100` | Virtualize above this many rows (100). |
+| `wrapSubtitle` | `boolean` | `false` | Lets a subtitle under its title wrap instead of ending with an ellipsis, for descriptions people read in full. |
 
 ### ListRow
 
@@ -1707,6 +1837,7 @@ One row: checkbox, glyph, id, title, subtitle, metadata, date, avatar, hover act
 | `selectable` | `boolean` |  | Shows the row's checkbox. |
 | `selected` | `boolean` |  | Marks the row as selected. |
 | `selecting` | `boolean` |  | Shows checkboxes on every row while some are selected. |
+| `wrapSubtitle` | `boolean` | `false` | Lets a subtitle under its title wrap. Set by `List`. |
 
 ### SelectionAction
 
@@ -1964,15 +2095,16 @@ Moves through long lists by pages, by cursor, or with a Load more button.
 
 ## playground
 
-`import { CompareGrid, Composer, ModelPicker, ParameterPanel, ParameterPopover, PromptSuggestions, ResponseMetrics, ResponseView, Thread, UserMessage } from "@logicplanes/kaeso-ui/playground";`
+`import { CompareGrid, Composer, ModelPicker, ParameterPanel, ParameterPopover, PromptSuggestions, Reasoning, ResponseMetrics, ResponseView, Thread, UserMessage } from "@logicplanes/kaeso-ui/playground";`
 
 - **divider** (compare_grid): `hairline` (default) — Columns separated by a hairline, edge to edge (default); `none` — No line between columns: columns that sit in panels of their own
 - **size** (composer): `md` (default) — Text 14/20, 8px around the buttons; the outline concentric with them (16 + 8) (default); `sm` — The same box starting one line tall: a follow-up field under a thread
 - **appearance** (model_picker): `ghost` (default) — Transparent until hovered: a column header (default); `default` — A raised pill with a ring: a form or toolbar
 - **layout** (parameter_panel): `popover` (default) — Inside a 320px popover (ParameterPopover) (default); `panel` — A side panel or sheet: a little more room between groups
 - **align** (prompt_suggestions): `start` (default) — Rows the composer's width, their text on its text (default); `center` — Centered under an empty thread's title
+- **state** (reasoning): `done` (default) — Finished: “Thought for 4.2 s”, closed until opened (default); `live` — Still reasoning: “Thinking” pulses quietly and the latest line shows beside it
 - **size** (response_metrics): `sm` (default) — 12/16: a column footer or under a turn (default); `md` — 13/18: a response on its own
-- **status** (response_view): `pending` — Sent, nothing back yet: an empty line where the text will start, nothing drawn; `streaming` — Arriving: the text grows, earlier lines never re-wrap; Thinking is live; `done` (default) — Complete (default); `stopped` — Stopped by the person: the text so far and “Stopped”; `error` — Failed: “No response” and Retry. The error itself is a toast
+- **status** (response_view): `pending` — Sent, nothing back yet: an empty line where the text will start, nothing drawn; `streaming` — Arriving: the text grows, earlier lines never re-wrap; Thinking is live; `done` (default) — Complete (default); `stopped` — Stopped by the person: the text so far and “Stopped”; `incomplete` — Cut off by the model: the text so far and why, such as “Stopped at the output limit”; `error` — Failed: the error in place of the response, and Retry
 
 ### CompareGrid
 
@@ -2020,22 +2152,36 @@ The prompt box: a text box that grows with what is written up to `maxRows`, then
 
 ### ModelPicker
 
-A model, picked from the project's catalogue: the provider mark, name and id (ModelLabel), grouped by provider.
+A model from a catalogue of any size: a pill showing the chosen model that opens a searchable list, grouped by provider under sticky captions with marks and counts, connected providers first and recent models on top, with a Provider filter that lists only the providers whose models match the search. Each row shows the name, the id, capabilities, context and price; deprecated models wait behind a toggle.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `options` * | `ModelPickerOption[]` |  | The models to choose from. |
-| `appearance` | `"ghost" \| "default"` | `ghost` | A quiet button (`ghost`) or a filled one (`default`). |
+| `options` * | `ModelPickerOption[]` |  | The models: value, provider, id, name, capabilities, context window, a formatted price, a short note such as why it is disabled, and whether it is deprecated. |
+| `allLabel` | `string` |  | Single only: a first option for no model in particular, such as "All models"; choosing it reports an empty string. |
+| `appearance` | `"ghost" \| "default"` |  | A quiet button (`ghost`) or a filled one (`default`). |
 | `aria-label` | `string` |  | The picker's accessible name ("Model" by default). |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
-| `defaultValue` | `string \| null` |  | The chosen model on first render. |
+| `defaultValue` | `string \| string[] \| null` |  | The chosen model, or models with `multiple`, on first render. |
+| `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
+| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `fullWidth` | `boolean` |  | Fills the container. |
 | `groupByProvider` | `boolean` |  | Groups the list by provider (true by default when there are several). |
-| `onValueChange` | `((value: string) => void)` |  | Called with the chosen model. |
+| `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
+| `label` | `ReactNode` |  | The visible label. |
+| `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
+| `multiple` | `boolean` |  | Allows choosing several models; `value` is then a list. |
+| `onOpenChange` | `((open: boolean) => void)` |  | Called when the list opens or closes. |
+| `onValueChange` | `((value: string) => void) \| ((value: string[]) => void)` |  | Called with the chosen model, or the list of models with `multiple`. |
+| `open` | `boolean` |  | Whether the list is open, when you control it. |
+| `optional` | `boolean` |  | Adds “Optional” to the label, for forms where most fields are required. |
 | `placeholder` | `string` |  | Text shown while there is no value. |
-| `size` | `"md" \| "sm"` | `sm` | The button's height. |
-| `value` | `string \| null` |  | The chosen model, when you control it. |
+| `providers` | `ModelPickerProvider[]` |  | The providers' names and whether each is connected; connected providers come first. |
+| `recent` | `readonly string[]` |  | Values of recently used models, shown first while the search is empty. |
+| `required` | `boolean` |  | Marks it as required in a form. |
+| `size` | `"md" \| "sm"` |  | The button's height. |
+| `value` | `string \| string[] \| null` |  | The chosen model, or models with `multiple`, when you control it. |
 
 ### ParameterPanel
 
@@ -2088,14 +2234,31 @@ Example prompts before a thread starts: up to three lines of plain secondary tex
 | `aria-label` | `string` |  | The list's accessible name. Defaults to "Example prompts" in the provider's language. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 
+### Reasoning
+
+A model's reasoning behind a quiet disclosure, closed by default: “Thought for 4.2 s” when it is done, “Thinking” with the latest line beside it while it streams. Opened, the reasoning reads in small secondary text beside a line. The Playground and the request log show reasoning with it.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` |  | What the open disclosure shows in place of `text`, such as why the reasoning can't be shown. |
+| `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `defaultOpen` | `boolean` |  | Whether it starts open. |
+| `duration` | `number` |  | How long the model reasoned, in milliseconds: “Thought for 4.2 s”. |
+| `hint` | `ReactNode` |  | A short note beside the title, such as “Redacted by the provider”; while `live`, the latest line of the reasoning shows there instead. |
+| `live` | `boolean` | `false` | The reasoning is still arriving: “Thinking” pulses quietly and its latest line shows beside it. |
+| `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
+| `open` | `boolean` |  | Whether it is open, when you control it. |
+| `text` | `string` |  | The reasoning, as Markdown. |
+| `title` | `ReactNode` |  | The title in place of “Thinking” or “Thought for …”, such as “Reasoning” in a request log. |
+
 ### ResponseMetrics
 
-A response's numbers on one line: time to first token, total time, tokens in → out (and reasoning), cost. Tabular figures, labels in tertiary text. While `live`, values not known yet show "—" in the room they will take; before any response the line is empty, its height kept.
+A response's numbers on one line: time to first token, total time, tokens ("412 in · 168 out", and reasoning), cost to the millionth of a dollar, as request logs show it. Tabular figures, labels in tertiary text. While `live`, values not known yet show "—" in the room they will take; before any response the line is empty, its height kept.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `cost` | `string \| null` |  | USD as a decimal string: "0.004213". |
+| `cost` | `string \| null` |  | USD as a decimal string: "0.004213" reads "$0.004213", and zero reads "$0". |
 | `duration` | `number \| null` |  | Milliseconds from sending to the last token. |
 | `inputTokens` | `number \| null` |  | The tokens sent, once known. |
 | `live` | `boolean` | `false` | A response is arriving: values not known yet show a quiet "—" in the room they will take. |
@@ -2108,20 +2271,22 @@ A response's numbers on one line: time to first token, total time, tokens in →
 
 ### ResponseView
 
-A model's response as it arrives: Markdown text for reading (15/22), the reasoning summary in a "Thinking" disclosure (closed by default, live while it streams), and calm states for a stop or a failure. Errors themselves are toasts; the response says only that there is none.
+A model's response as it arrives: Markdown text for reading (15/22), the reasoning summary in a "Thinking" disclosure (closed by default, live while it streams), and calm states for a stop, a cut-off reply or a failure, which shows its error in place.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` | `string` |  | The response's accessible name ("GPT-5 response" in a comparison). Defaults to "Response" in the provider's language. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `defaultReasoningOpen` | `boolean` |  | Whether the reasoning starts expanded. |
+| `error` | `string` |  | Why the reply failed, shown under "No response" with status "error": the gateway's message in the reader's language; `code` spans render as code. |
 | `footer` | `ReactNode` |  | Under the response: its metrics, actions. |
+| `incompleteReason` | `string` |  | Why the model cut the reply off, with status "incomplete": `max_output_tokens` reads "Stopped at the output limit", `content_filter` names the filter. |
 | `onReasoningOpenChange` | `((open: boolean) => void)` |  | Called when the reasoning is expanded or collapsed. |
-| `onRetry` | `(() => void)` |  | Sends the turn again; shown with an error or a stop. |
+| `onRetry` | `(() => void)` |  | Sends the turn again; shown with an error, a stop or a cut-off reply. |
 | `reasoning` | `string` |  | The reasoning summary so far, as Markdown. A "Thinking" disclosure shows it, closed by default. |
 | `reasoningDuration` | `number` |  | How long the model reasoned, in milliseconds: "Thought for 4.2 s". |
 | `reasoningOpen` | `boolean` |  | Whether the reasoning is expanded, when you control it. |
-| `status` | `"done" \| "error" \| "streaming" \| "pending" \| "stopped"` | `done` | Where the reply stands: waiting, streaming, done, stopped or failed. |
+| `status` | `"done" \| "error" \| "streaming" \| "pending" \| "stopped" \| "incomplete"` | `done` | Where the reply stands: waiting, streaming, done, stopped, cut off by the model (incomplete) or failed. |
 | `text` | `string` |  | The output text so far, as Markdown. |
 
 ### Thread
@@ -2260,6 +2425,26 @@ Choices with descriptions as rows in a settings group.
 | `orientation` | `"horizontal" \| "vertical"` | `vertical` | Lays the items out in a row (`horizontal`) or a column (`vertical`). |
 | `value` | `string` |  | The chosen option, when you control it. |
 
+## release-art
+
+`import { ReleaseArt } from "@logicplanes/kaeso-ui/release-art";`
+
+- **shape** (release_art): `banner` (default) — 16:9: the head of a dialog or a card (default); `wide` — 21:9: a wide strip above a page's content
+
+### ReleaseArt
+
+A release's artwork: flat geometric art in one of eight styles and Kaeso's palettes, drawn from a stored art spec or a seed, with an optional title floating on it.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` * | `string` |  | What the picture shows, read by screen readers: "Kaeso 0.1.0". |
+| `seed` * | `string` |  | What the artwork is drawn from when there is no `art`, e.g. `0.1.0`; the same seed always draws the same picture. |
+| `art` | `ReleaseArtSpec` |  | The release's stored artwork, e.g. from `nextReleaseArt`; it always draws the same picture and wins over `seed`. |
+| `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `eyebrow` | `ReactNode` |  | Small text above the title, e.g. “What's new in Kaeso”. |
+| `shape` | `"banner" \| "wide"` | `banner` | The artwork's aspect ratio. |
+| `title` | `ReactNode` |  | Large text on the artwork, e.g. the version number. |
+
 ## resource-list
 
 `import { ResourceList } from "@logicplanes/kaeso-ui/blocks/resource-list";`
@@ -2384,7 +2569,7 @@ A pill that opens a list on the menu surface: check on the selected item, groups
 | `defaultValue` | `string \| string[] \| null` |  | The value on first render, when the component keeps its own value. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
-| `error` | `ReactNode` |  | Deprecated. Errors are toasts, never text under a field: `error` marks the control invalid and stays its description for screen readers, but isn't drawn. Pass `invalid` and toast the message. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `fullWidth` | `boolean` |  | Width of the trigger follows its content (default) or fills the container. |
 | `icon` | `IconSvgElement` |  | Leading icon in the trigger. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
@@ -2474,7 +2659,7 @@ A settings section: a title-sm heading 48px above, 12px below; usually one Setti
 
 ### Sheet
 
-A panel that slides in from the edge of the screen, for details and longer forms.
+A panel that slides in from the edge of the screen, for details and longer forms. While it slides out it keeps showing what it showed when it was open, so a page can let go of the row as soon as it closes.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2620,6 +2805,7 @@ One metric of a dashboard row: its label, the number, the change against the pre
 | `change` | `{ value: number; better?: "up" \| "down"; }` |  | The change against the previous period, as a fraction (0.12 is +12%). `better` says which direction is good: errors are better down. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `detail` | `ReactNode` |  | A quiet line under the number: "vs. the previous 30 days", "0.4% of requests". |
+| `loading` | `boolean` |  | While the numbers load: the value, the change and the trend show their shape at the tile's final height. |
 | `trend` | `number[]` |  | One value per day (or step), drawn as a sparkline across the tile. A tile without it has no room for one; pass `[]` while a trend loads to keep it. |
 | `trendColor` | `string` |  | The trend's color; the first series color by default. |
 
@@ -2637,6 +2823,7 @@ The same component under its plain name.
 |---|---|---|---|
 | `children` | `ReactNode` |  | The word that carries the meaning. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `icon` | `IconSvgElement` |  | A mark before the word in the same color, e.g. `icons.success` for “Up to date”. |
 | `size` | `"md" \| "sm"` | `md` | The text size. |
 | `tone` | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` | `neutral` | The status it marks. |
 
@@ -2648,6 +2835,7 @@ A status word: "Active", "Expiring", "Down".
 |---|---|---|---|
 | `children` | `ReactNode` |  | The word that carries the meaning. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `icon` | `IconSvgElement` |  | A mark before the word in the same color, e.g. `icons.success` for “Up to date”. |
 | `size` | `"md" \| "sm"` | `md` | The dot's size. |
 | `tone` | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` | `neutral` | The status the dot marks; keep it next to words that say the same. |