@logicplanes/kaeso-ui 0.1.0 → 0.2.0

package/ai/component-registry.md

@@ -1,17 +1,17 @@
 # @logicplanes/kaeso-ui component registry
 
-Version 0.1.0. Generated from the component types, their descriptions and variants; do not edit.
+Version 0.2.0. Generated from the component types, their descriptions and variants; do not edit.
 
 ## app-frame
 
 `import { AppFrame, NavSheet } from "@logicplanes/kaeso-ui/app-frame";`
 
-- **padding** (app_frame_body): `none` — Edge to edge: lists and tables that bring their own row insets (default); `list` — A list or table under the header: 8px above the first row; rows bring their own side insets; `page` — A content page (overviews, charts, sections): 24px sides, 16px under the header, 48px at the end
-- **fill** (app_frame): `screen` — Fills the viewport (default); `parent` — Fills its container: previews, embedded tools
+- **padding** (app_frame_body): `none` (default) — Edge to edge: lists and tables that bring their own row insets (default); `list` — A list or table under the header: 8px above the first row; rows bring their own side insets; `page` — A content page (overviews, charts, sections): 24px sides, 16px under the header, 48px at the end
+- **fill** (app_frame): `screen` (default) — Fills the viewport (default); `parent` — Fills its container: previews, embedded tools
 
 ### AppFrame
 
-The page frame of an app: a skip link to the content, the sidebar, the inset panel and, on phones, a bar with a menu button.
+The page frame of an app: a skip link to the content, the sidebar, the inset panel and, on phones, a bar with a menu button. The navigation sheet's code loads once the page is idle or on the first tap; after a failed download the next tap or hover loads it again from a fresh address. Chromium and WebKit keep a failed download of a chunk the sheet shares with the rest of the app until the page is reloaded.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -22,6 +22,7 @@ The page frame of an app: a skip link to the content, the sidebar, the inset pan
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `corner` | `ReactNode` |  | A bottom-right status area. Unused by default. |
 | `fill` | `"screen" \| "parent"` | `screen` | `screen` fills the viewport (default); `parent` fills its container (previews, embedded tools). |
+| `phoneActions` | `ReactNode` |  | Icon buttons in the phone bar before the navigation toggle, such as search, so it is one tap away; pass `tooltip={false}` to each. |
 
 ### NavSheet
 
@@ -39,8 +40,8 @@ The sidebar as a floating panel from the left edge (a peek): the mobile navigati
 
 `import { Avatar, AvatarGroup } from "@logicplanes/kaeso-ui/avatar";`
 
-- **size** (avatar): `20` — 20px; `24` — 24px: rows and the org switcher (default); `28` — 28px; `32` — 32px; `40` — 40px: menus, profiles
-- **kind** (avatar): `person` — People are round; `org` — Organizations and projects: radius 8
+- **size** (avatar): `20` — 20px; `24` (default) — 24px: rows and the org switcher (default); `28` — 28px; `32` — 32px; `40` — 40px: menus, profiles
+- **kind** (avatar): `person` (default) — People are round; `org` — Organizations and projects: radius 8
 
 ### Avatar
 
@@ -71,7 +72,7 @@ Overlapping avatars with a 2px panel ring and a "+3".
 
 `import { Badge } from "@logicplanes/kaeso-ui/badge";`
 
-- **tone** (badge): `neutral` — Neutral (default); `success` — Success; `warning` — Warning; `danger` — Danger; `info` — Information; `outline` — A ring only; `ink` — Inverted, for the one thing that must stand out
+- **tone** (badge): `neutral` (default) — Neutral (default); `success` — Success; `warning` — Warning; `danger` — Danger; `info` — Information; `outline` — A ring only; `ink` — Inverted, for the one thing that must stand out
 
 ### Badge
 
@@ -86,8 +87,8 @@ A small pill label: 22px, 12/500. Words carry meaning; color supports them.
 
 `import { Banner } from "@logicplanes/kaeso-ui/banner";`
 
-- **tone** (banner): `neutral` — A neutral notice (default); `info` — Information; `success` — Something worked; `warning` — Attention needed soon; `danger` — Something failed or will fail
-- **layout** (banner): `inline` — Inside content: radius 14 (default); `full` — Across the top of the panel for global notices
+- **tone** (banner): `neutral` (default) — A neutral notice (default); `info` — Information; `success` — Something worked; `warning` — Attention needed soon; `danger` — Something failed or will fail
+- **layout** (banner): `inline` (default) — Inside content: radius 14 (default); `full` — Across the top of the panel for global notices
 
 ### Banner
 
@@ -108,9 +109,9 @@ An inline notice: a tint, an icon, an optional title, the text, actions at the e
 
 `import { Button } from "@logicplanes/kaeso-ui/button";`
 
-- **variant** (button): `primary` — Ink with a faint top light. Exactly one per view.; `secondary` — Raised, ring and a soft shadow. The default.; `ghost` — Transparent until hovered: toolbars, rows, quiet actions; `quiet` — A ghost in secondary text that darkens on hover: actions inside a field (clear, reveal, copy); `soft` — A fill without a ring: the active pill tab; `danger` — The destructive confirm, with the primary's material; `danger-secondary` — Raised with danger text; tints on hover. Destructive triggers.; `link` — Text with an underline, for actions inside sentences
-- **size** (button): `xs` — 24px: chips inside rows and tables only; `sm` — 32px: toolbars, headers, settings rows; `md` — 36px: the default; `lg` — 40px: prominent actions; `xl` — 48px: sign-in and setup forms, empty-state actions
-- **shape** (button): `pill` — Every button is a pill; `circle` — Icon-only: a circle of the same height
+- **variant** (button): `primary` — Ink with a faint top light. Exactly one per view.; `secondary` (default) — Raised, ring and a soft shadow. The default.; `ghost` — Transparent until hovered: toolbars, rows, quiet actions; `quiet` — A ghost in secondary text that darkens on hover: actions inside a field (clear, reveal, copy); `soft` — A fill without a ring: the active pill tab; `danger` — The destructive confirm, with the primary's material; `danger-secondary` — Raised with danger text; tints on hover. Destructive triggers.; `link` — Text with an underline, for actions inside sentences
+- **size** (button): `xs` — 24px: chips inside rows and tables only; `sm` — 32px: toolbars, headers, settings rows; `md` (default) — 36px: the default; `lg` — 40px: prominent actions; `xl` — 48px: sign-in and setup forms, empty-state actions
+- **shape** (button): `pill` (default) — Every button is a pill; `circle` — Icon-only: a circle of the same height
 
 ### Button
 
@@ -140,8 +141,8 @@ The button. Every one is a pill; icon-only buttons are circles (see `IconButton`
 
 `import { ButtonGroup } from "@logicplanes/kaeso-ui/button-group";`
 
-- **attached** (button_group): `true` — Connected: one outer pill with inner hairline dividers (default); `false` — Spaced: separate pills 8px apart
-- **size** (button_group): `xs` — 24px; `sm` — 32px; `md` — 36px (default); `lg` — 40px
+- **attached** (button_group): `true` (default) — Connected: one outer pill with inner hairline dividers (default); `false` — Spaced: separate pills 8px apart
+- **size** (button_group): `xs` — 24px; `sm` — 32px; `md` (default) — 36px (default); `lg` — 40px
 
 ### ButtonGroup
 
@@ -158,7 +159,7 @@ Related actions side by side: connected pills, or spaced with `attached={false}`
 
 `import { Calendar } from "@logicplanes/kaeso-ui/calendar";`
 
-- **mode** (calendar): `single` — One date (default); `range` — A range: a continuous strip between ink ends
+- **mode** (calendar): `single` (default) — One date (default); `range` — A range: a continuous strip between ink ends
 
 ### Calendar
 
@@ -181,15 +182,15 @@ The calendar: 36px day circles, today ringed, ranges as a continuous strip with
 
 `import { BarChart, ChartFrame, ChartLive, ChartTooltip, Donut, Gauge, Heatmap, Legend, Ring, Sankey, ShareBar, Sparkline, Swatch, TimeseriesChart } from "@logicplanes/kaeso-ui/charts";`
 
-- **layout** (bar_chart): `grouped` — Bars side by side per category (default); `stacked` — Bars stacked per category; `horizontal` — Horizontal bars for rankings
-- **chrome** (charts): `default` — Dashed 3 3 grid, tertiary 12px labels, a strong baseline; no frame
-- **size** (donut): `md` — 160px (default); `sm` — 140px; `lg` — 180px
-- **size** (gauge): `md` — 180px (default)
-- **layout** (heatmap): `week` — Hour × weekday (default); `year` — Day × week
-- **size** (sankey): `md` — Fills its width; 320px tall by default
-- **size** (share_bar): `md` — One 8px pill (default)
-- **size** (sparkline): `md` — 80×24 inline (default)
-- **kind** (timeseries_chart): `line` — 2px lines, hover dots only (default); `area` — Lines with a 10% fill (16% in dark mode); `stacked` — Stacked areas
+- **layout** (bar_chart): `grouped` (default) — Bars side by side per category (default); `stacked` — Bars stacked per category; `horizontal` — Horizontal bars for rankings
+- **chrome** (charts): `default` (default) — Dashed 3 3 grid, tertiary 12px labels, a strong baseline; no frame
+- **size** (donut): `md` (default) — 160px (default); `sm` — 140px; `lg` — 180px
+- **size** (gauge): `md` (default) — 180px (default)
+- **layout** (heatmap): `week` (default) — Hour × weekday (default); `year` — Day × week
+- **size** (sankey): `md` (default) — Fills its width; 320px tall by default
+- **size** (share_bar): `md` (default) — One 8px pill (default)
+- **size** (sparkline): `md` (default) — 80×24 inline (default)
+- **kind** (timeseries_chart): `line` (default) — 2px lines, hover dots only (default); `area` — Lines with a 10% fill (16% in dark mode); `stacked` — Stacked areas
 
 ### BarChart
 
@@ -405,7 +406,7 @@ A line or area chart of values over time, such as usage, with a crosshair and to
 
 `import { Checkbox, CheckboxGroup } from "@logicplanes/kaeso-ui/checkbox";`
 
-- **size** (checkbox): `md` — 18px, radius 5 (default)
+- **size** (checkbox): `md` (default) — 18px, radius 5 (default)
 
 ### Checkbox
 
@@ -478,7 +479,8 @@ Checkboxes that share one value, a list of the checked values.
 
 `import { Code } from "@logicplanes/kaeso-ui/code";`
 
-- **shape** (code): `auto` — Pill for a single word, radius 6 for anything longer (default); `pill` — Always a pill; `rounded` — Always radius 6
+- **shape** (code): `auto` (default) — Pill for a single word, radius 6 for anything longer (default); `pill` — Always a pill; `rounded` — Always radius 6
+- **flow** (code): `box` (default) — One box: it moves to the next line whole and wraps inside itself (default); `text` — Breaks with the sentence around it, each line keeping its fill and corners; for long code in running text; `cell` — Breaks with the text around it and ends square at a break, so no padding hangs past a narrow table cell; for long code in a table
 
 ### Code
 
@@ -486,14 +488,15 @@ Inline code: Geist Mono 13 on fill-1.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `flow` | `"cell" \| "text" \| "box"` | `box` | `text` for long code in running text, so it breaks with the sentence instead of jumping to its own line as one box; `cell` for the same in a table cell. |
 | `shape` | `"auto" \| "pill" \| "rounded"` | `auto` | A pill on one line, rounded corners when it wraps, or `auto` to choose by length. |
 
 ## code-block
 
 `import { CodeBlock, CodeHighlighted, JsonView } from "@logicplanes/kaeso-ui/code-block";`
 
-- **surface** (code_block): `well` — A well: radius 14, fill, no ring (default); `plain` — No surface, inside another well
-- **surface** (json_view): `well` — On a well (default); `plain` — No surface
+- **surface** (code_block): `well` (default) — A well: radius 14, fill, no ring (default); `plain` — No surface, inside another well
+- **surface** (json_view): `well` (default) — On a well (default); `plain` — No surface
 
 ### CodeBlock
 
@@ -508,7 +511,9 @@ Highlighted code on a well: Kaeso's monochrome theme, copy on hover, tabs, line
 | `highlightLines` | `number[]` | `[]` | 1-based line numbers to highlight. |
 | `lang` | `CodeLang` | `ts` | The language of the code, for highlighting. |
 | `lineNumbers` | `boolean` |  | Shows line numbers. |
+| `onTabChange` | `((label: string) => void)` |  | Called with the label of the tab a person chooses, to remember it. |
 | `surface` | `"well" \| "plain"` | `well` | On a filled well (`well`) or on the panel itself (`plain`). |
+| `tab` | `string` |  | The label of the tab to show, such as a language the reader chose before. A label the block lacks leaves its own choice. |
 | `tabs` | `CodeTab[]` |  | Several versions: "Python · Node · curl", shown as pill tabs. |
 | `title` | `ReactNode` |  | A file name in the title bar. |
 | `wrap` | `boolean` | `false` | Long lines wrap instead of scrolling sideways: code in a narrow column (a model's response). |
@@ -526,7 +531,9 @@ The same component as `CodeBlock`, under another name.
 | `highlightLines` | `number[]` | `[]` | 1-based line numbers to highlight. |
 | `lang` | `CodeLang` | `ts` | The language of the code, for highlighting. |
 | `lineNumbers` | `boolean` |  | Shows line numbers. |
+| `onTabChange` | `((label: string) => void)` |  | Called with the label of the tab a person chooses, to remember it. |
 | `surface` | `"well" \| "plain"` | `well` | On a filled well (`well`) or on the panel itself (`plain`). |
+| `tab` | `string` |  | The label of the tab to show, such as a language the reader chose before. A label the block lacks leaves its own choice. |
 | `tabs` | `CodeTab[]` |  | Several versions: "Python · Node · curl", shown as pill tabs. |
 | `title` | `ReactNode` |  | A file name in the title bar. |
 | `wrap` | `boolean` | `false` | Long lines wrap instead of scrolling sideways: code in a narrow column (a model's response). |
@@ -547,7 +554,7 @@ A folding JSON tree: copy any path, highlight a search. For request and response
 
 `import { Accordion, Collapsible } from "@logicplanes/kaeso-ui/collapsible";`
 
-- **state** (collapsible): `closed` — Closed: the chevron points to the row (default); `open` — Open: the chevron turns down and the content shows
+- **state** (collapsible): `closed` (default) — Closed: the chevron points to the row (default); `open` — Open: the chevron turns down and the content shows
 
 ### Accordion
 
@@ -578,7 +585,7 @@ A disclosure row: a chevron that rotates in 180ms, a measured height animation.
 
 `import { Autocomplete, Combobox, Highlight } from "@logicplanes/kaeso-ui/combobox";`
 
-- **size** (combobox): `sm` — 32px; `md` — 36px (default); `lg` — 40px; `xl` — 48px
+- **size** (combobox): `sm` — 32px; `md` (default) — 36px (default); `lg` — 40px; `xl` — 48px
 
 ### Autocomplete
 
@@ -650,7 +657,7 @@ Splits a label around the query: matched characters in text, the rest secondary
 
 `import { CommandPalette } from "@logicplanes/kaeso-ui/command-palette";`
 
-- **size** (command_palette): `md` — 640px, 20vh from the top (default)
+- **size** (command_palette): `md` (default) — 640px, 20vh from the top (default)
 
 ### CommandPalette
 
@@ -668,14 +675,15 @@ Splits a label around the query: matched characters in text, the rest secondary
 | `onQueryChange` | `((query: string) => void)` |  | Called as the query changes, for async groups. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
 | `placeholder` | `string` |  | Defaults to "Search or run a command" in the provider's language. |
+| `query` | `string` |  | The query in the field, when you control it; keep it in sync through onQueryChange. |
 
 ## copy-button
 
 `import { ClipboardText, CopyButton, InlineCopyText } from "@logicplanes/kaeso-ui/copy-button";`
 
-- **size** (clipboard_text): `sm` — 32px; `md` — 36px (default); `lg` — 40px
-- **variant** (copy_button): `ghost` — Inside fields and wells (default); `secondary` — On its own
-- **size** (copy_button): `xs` — 24px circle: inside rows and chips; `sm` — 32px circle: toolbars and headers (default); `md` — 36px circle: beside md controls; `lg` — 40px circle; `xl` — 48px circle
+- **size** (clipboard_text): `sm` — 32px; `md` (default) — 36px (default); `lg` — 40px
+- **variant** (copy_button): `ghost` (default) — Inside fields and wells (default); `secondary` — On its own
+- **size** (copy_button): `xs` — 24px circle: inside rows and chips; `sm` (default) — 32px circle: toolbars and headers (default); `md` — 36px circle: beside md controls; `lg` — 40px circle; `xl` — 48px circle
 
 ### ClipboardText
 
@@ -718,7 +726,7 @@ Inline mono text that copies itself on click, with a hover affordance. Never wid
 
 `import { DataTable } from "@logicplanes/kaeso-ui/data-table";`
 
-- **density** (data_table): `compact` — 36px rows; `default` — 40px rows (default); `comfortable` — 48px rows
+- **density** (data_table): `compact` — 36px rows; `default` (default) — 40px rows (default); `comfortable` — 48px rows
 
 ### DataTable
 
@@ -757,8 +765,8 @@ A table for many rows: sorting, selection, loading and empty states, more rows o
 
 `import { DatePicker, DateRangePicker, TimeInput } from "@logicplanes/kaeso-ui/date-picker";`
 
-- **size** (date_picker): `sm` — 32px; `md` — 36px (default); `lg` — 40px
-- **size** (time_input): `sm` — 32px: toolbars and compact forms; `md` — 36px: the default; `lg` — 40px; `xl` — 48px: sign-in and setup forms
+- **size** (date_picker): `sm` — 32px; `md` (default) — 36px (default); `lg` — 40px
+- **size** (time_input): `sm` — 32px: toolbars and compact forms; `md` (default) — 36px: the default; `lg` — 40px; `xl` — 48px: sign-in and setup forms
 
 ### DatePicker
 
@@ -841,7 +849,7 @@ Hours and minutes as two segments in one pill; arrows step, typing advances.
 
 `import { DeleteResource } from "@logicplanes/kaeso-ui/blocks/delete-resource";`
 
-- **confirm** (delete_resource): `typed` — The person types the resource's name (default); `simple` — A confirm button only, for reversible archives
+- **confirm** (delete_resource): `typed` (default) — The person types the resource's name (default); `simple` — A confirm button only, for reversible archives
 
 ### DeleteResource
 
@@ -862,11 +870,11 @@ Confirms deleting a resource: names the object and the consequence, asks for its
 
 ## dialog
 
-`import { AlertDialog, Dialog, LayerDialog, StepDialog } from "@logicplanes/kaeso-ui/dialog";`
+`import { AlertDialog, Dialog, DialogScope, LayerDialog, StepDialog } from "@logicplanes/kaeso-ui/dialog";`
 
-- **tone** (alert_dialog): `danger` — Destructive (default); `warning` — Risky but reversible; `info` — Neutral confirmation
-- **size** (dialog): `sm` — 440px: confirmations, short forms; `md` — 560px: forms (default); `lg` — 720px: two columns, previews
-- **size** (layer_dialog): `sm` — 440px: confirmations, short forms; `md` — 560px: forms (default); `lg` — 720px: two columns, previews
+- **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
+- **size** (layer_dialog): `sm` — 440px: confirmations, short forms; `md` (default) — 560px: forms (default); `lg` — 720px: two columns, previews
 
 ### AlertDialog
 
@@ -876,13 +884,13 @@ Confirms an irreversible action: names it, explains the consequence, optionally
 |---|---|---|---|
 | `confirmLabel` * | `string` |  | The confirm label, the verb and object: "Delete key". |
 | `description` * | `ReactNode` |  | The practical consequence. |
-| `onConfirm` * | `() => void \| Promise<void>` |  | Called when the action is confirmed; return a promise to keep the dialog busy until it ends. It closes when the promise resolves and stays open for another try when it rejects, so toast the error there. |
+| `onConfirm` * | `() => void \| Promise<unknown>` |  | Called when the action is confirmed; return a promise to keep the dialog busy until it ends. It closes when the promise resolves and stays open for another try when it rejects, so toast the error there. |
 | `title` * | `ReactNode` |  | Names the action: "Delete this key?" |
 | `cancelLabel` | `string` |  | Defaults to "Cancel" in the provider's language. |
 | `confirmText` | `string` |  | Typed confirmation: the person types this to enable the confirm. |
 | `defaultOpen` | `boolean` |  | Whether it starts open, when the component keeps its own state. |
 | `inline` | `boolean` |  | Renders in place, without a trigger, for review pages and tests. |
-| `loading` | `boolean` |  | Shows a spinner on the confirm while work runs (also automatic for a promise). |
+| `loading` | `boolean` |  | Shows a spinner on the confirm while work runs (also automatic for a promise); until it ends, the dialog stays open. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
 | `tone` | `"warning" \| "danger" \| "info"` |  | How serious the confirmation is; `danger` for actions that can't be undone. |
@@ -890,11 +898,12 @@ 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.
+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.
 
 | 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. |
 | `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. |
@@ -909,6 +918,15 @@ A modal dialog: 440 / 560 / 720, radius 20, title, description, body, actions.
 | `size` | `"md" \| "sm" \| "lg"` |  | The dialog's width. |
 | `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The trigger, a single element. |
 
+### DialogScope
+
+Opens a dialog's flow fresh every time: its children mount anew when `open` turns true and unmount once the Dialog, StepDialog, LayerDialog, AlertDialog, Sheet or CommandPalette inside has finished closing. Fields, steps, errors, results and secrets shown once never come back on the next open, and nothing changes while the dialog animates out.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` * | `ReactNode` |  | The component that keeps the flow's state and renders the dialog with the same `open`. |
+| `open` * | `boolean` |  | Whether the dialog inside is open; pass the value its `open` gets. |
+
 ### 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.
@@ -916,6 +934,7 @@ A stacked dialog: a second layer slides over the first (add model → review val
 | 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. |
 | `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). |
@@ -930,7 +949,7 @@ A stacked dialog: a second layer slides over the first (add model → review val
 
 ### 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 height: it grows or shrinks 200ms as the step changes, its top stays where it opened, and the new step drifts in from the side it comes from. Within a step it never shrinks, so nothing jumps while a step's content changes; it grows once if the content does. Steps a few pixels apart share one height. 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 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.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -942,15 +961,16 @@ A form split into steps, one question at a time, like sign-in: the step's title
 | `inline` | `boolean` |  | Render without a portal and backdrop, for documentation and state matrices. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
+| `result` | `StepDialogResult` |  | What the last step made, shown in the same dialog once it exists: its title, description, content, footer and size. Pass it after `onSubmit` succeeds, such as the created key with SecretReveal. |
 | `size` | `"md" \| "sm" \| "lg"` | `sm` | The dialog's width. |
-| `submitting` | `boolean` |  | Shows that the submission is underway. |
+| `submitting` | `boolean` |  | Shows that the submission is underway; until it ends, the dialog stays open and Back and Cancel wait. |
 | `tone` | `"danger" \| "default"` | `default` | `danger` for an action that destroys something: the last step's button turns red. |
 
 ## display-options
 
 `import { DisplayOptions } from "@logicplanes/kaeso-ui/display-options";`
 
-- **trigger** (display_options): `secondary` — A raised circle with a ring, like page-header buttons (default); `ghost` — A ghost circle
+- **trigger** (display_options): `secondary` (default) — A raised circle with a ring, like page-header buttons (default); `ghost` — A ghost circle
 
 ### DisplayOptions
 
@@ -970,7 +990,7 @@ Display options: view, grouping and ordering, toggles, properties.
 
 `import { Empty } from "@logicplanes/kaeso-ui/empty";`
 
-- **size** (empty): `lg` — Centered in a panel (default); `md` — Inside a section; `compact` — Inside tables and lists
+- **size** (empty): `lg` (default) — Centered in a panel (default); `md` — Inside a section; `compact` — Inside tables and lists
 
 ### Empty
 
@@ -989,7 +1009,7 @@ An empty state: a title, one sentence, one or two actions. No icon, no illustrat
 
 `import { Field, Fieldset } from "@logicplanes/kaeso-ui/field";`
 
-- **layout** (field): `vertical` — Label above the control (default); `horizontal` — Label in a 240px column on the left, from 768px
+- **layout** (field): `vertical` (default) — Label above the control (default); `horizontal` — Label in a 240px column on the left, from 768px
 
 ### Field
 
@@ -1017,7 +1037,7 @@ A group of fields under one legend.
 
 `import { FilterChip } from "@logicplanes/kaeso-ui/filter-chip";`
 
-- **size** (filter_chip): `sm` — 32px: toolbars (default)
+- **size** (filter_chip): `sm` (default) — 32px: toolbars (default)
 
 ### FilterChip
 
@@ -1044,7 +1064,7 @@ A filter as one pill: "Status is 2xx ×", each part opening a menu.
 
 `import { FilterRow } from "@logicplanes/kaeso-ui/filter-row";`
 
-- **size** (filter_row): `md` — Under a page header on an edge-to-edge page: 24px sides, 48px tall on one line like a toolbar; `inset` — In a settings column: 24px under the header (with the column's 8px), 16px above the list or table (chosen automatically)
+- **size** (filter_row): `md` (default) — Under a page header on an edge-to-edge page: 24px sides, 48px tall on one line like a toolbar; `inset` — In a settings column: 24px under the header (with the column's 8px), 16px above the list or table (chosen automatically)
 
 ### FilterRow
 
@@ -1061,7 +1081,7 @@ The row between a page's header and its list or table: pill tabs at the start, f
 
 `import { Flow } from "@logicplanes/kaeso-ui/flow";`
 
-- **node** (flow): `pill` — A raised pill (default); `box` — A rounded-14 box with a description line
+- **node** (flow): `pill` (default) — A raised pill (default); `box` — A rounded-14 box with a description line
 
 ### Flow
 
@@ -1080,7 +1100,7 @@ A node-and-connector diagram: the route "app → Kaeso → provider / model".
 
 `import { Heading } from "@logicplanes/kaeso-ui/heading";`
 
-- **size** (heading): `title-sm` — 17/24: section, dialog and sheet titles; `title` — 20/28: empty states, compact page titles; `title-lg` — 28/34: settings page titles, auth screens; `display` — 40/44: showcase headings, the setup screen
+- **size** (heading): `title-sm` (default) — 17/24: section, dialog and sheet titles; `title` — 20/28: empty states, compact page titles; `title-lg` — 28/34: settings page titles, auth screens; `display` — 40/44: showcase headings, the setup screen
 
 ### Heading
 
@@ -1096,7 +1116,7 @@ Heading levels map to the title tokens (4.3).
 
 `import { Icon } from "@logicplanes/kaeso-ui/icon";`
 
-- **size** (icon): `xs` — 14px, 1.75 stroke: chips, xs controls, inline hints; `sm` — 16px, 1.5 stroke: the default in controls and menus; `md` — 18px, 1.5 stroke: sidebar items, lg controls; `lg` — 20px, 1.5 stroke: xl controls, empty states; `xl` — 24px, 1.5 stroke: rare, large moments
+- **size** (icon): `xs` — 14px, 1.75 stroke: chips, xs controls, inline hints; `sm` (default) — 16px, 1.5 stroke: the default in controls and menus; `md` — 18px, 1.5 stroke: sidebar items, lg controls; `lg` — 20px, 1.5 stroke: xl controls, empty states; `xl` — 24px, 1.5 stroke: rare, large moments
 
 ### Icon
 
@@ -1112,8 +1132,8 @@ The one way to draw an icon: Hugeicons Stroke Rounded in currentColor.
 
 `import { IconButton } from "@logicplanes/kaeso-ui/icon-button";`
 
-- **variant** (icon_button): `ghost` — Toolbar and row actions (default); `quiet` — Secondary text that darkens on hover: inside fields; `secondary` — Raised circles with a ring: page-header buttons; `soft` — A filled circle; `primary` — The view's one primary action, as an icon; `danger` — Destructive; `danger-secondary` — Destructive, quieter
-- **size** (icon_button): `xs` — 24px circle: inside rows and chips; `sm` — 32px circle: toolbars and headers (default); `md` — 36px circle: beside md controls; `lg` — 40px circle; `xl` — 48px circle
+- **variant** (icon_button): `ghost` (default) — Toolbar and row actions (default); `quiet` — Secondary text that darkens on hover: inside fields; `secondary` — Raised circles with a ring: page-header buttons; `soft` — A filled circle; `primary` — The view's one primary action, as an icon; `danger` — Destructive; `danger-secondary` — Destructive, quieter
+- **size** (icon_button): `xs` — 24px circle: inside rows and chips; `sm` (default) — 32px circle: toolbars and headers (default); `md` — 36px circle: beside md controls; `lg` — 40px circle; `xl` — 48px circle
 
 ### IconButton
 
@@ -1137,13 +1157,13 @@ A circle with an icon, a required name, and a tooltip that says it.
 
 `import { Input, InputGroup, NumberInput, OTPInput, SearchInput, SensitiveInput, TagInput, Textarea } from "@logicplanes/kaeso-ui/input";`
 
-- **size** (input_group): `sm` — 32px: toolbars and compact forms; `md` — 36px: the default; `lg` — 40px; `xl` — 48px: sign-in and setup forms
-- **size** (input): `sm` — 32px: toolbars and compact forms; `md` — 36px: the default; `lg` — 40px; `xl` — 48px: sign-in and setup forms
-- **align** (number_input): `end` — Right-aligned tabular digits (default); `start` — Left-aligned
-- **size** (otp_input): `md` — 48px cells (default); `sm` — 40px cells
-- **kind** (sensitive_input): `secret` — Provider keys and tokens: never autocompleted (default); `password` — Passwords: browser password managers allowed, Caps Lock hint
-- **size** (tag_input): `md` — 36px at one row; grows as tags wrap (default)
-- **resize** (textarea): `auto` — Grows with its content to 8 lines, then scrolls (default); `vertical` — People can drag it taller
+- **size** (input): `sm` — 32px: toolbars and compact forms; `md` (default) — 36px: the default; `lg` — 40px; `xl` — 48px: sign-in and setup forms
+- **size** (input_group): `sm` — 32px: toolbars and compact forms; `md` (default) — 36px: the default; `lg` — 40px; `xl` — 48px: sign-in and setup forms
+- **align** (number_input): `end` (default) — Right-aligned tabular digits (default); `start` — Left-aligned
+- **size** (otp_input): `md` (default) — 48px cells (default); `sm` — 40px cells
+- **kind** (sensitive_input): `secret` (default) — Provider keys and tokens: never autocompleted (default); `password` — Passwords: browser password managers allowed, Caps Lock hint
+- **size** (tag_input): `md` (default) — 36px at one row; grows as tags wrap (default)
+- **resize** (textarea): `auto` (default) — Grows with its content to 8 lines, then scrolls (default); `vertical` — People can drag it taller
 
 ### Input
 
@@ -1313,14 +1333,14 @@ A multi-line field: radius 14 (multi-line text cannot be a pill), the same mater
 
 `import { ConversationView, EffectiveAccess, EnvironmentSnippet, KeyDisplay, LimitMeter, ModelLabel, ProviderBadge, ProviderCard, RequestTimeline, RightsMatrix, RolePicker, SecretReveal, StatusCode, UsageBreakdown } from "@logicplanes/kaeso-ui/kaeso";`
 
-- **density** (conversation): `default` — 24px between turns (default); `compact` — 16px, inside sheets
-- **layout** (effective_access): `rows` — A row per group: its name, what is granted in words, and how many (default)
-- **provider** (identity): `sm` — 16px, inside table cells; `md` — 20px (default); `lg` — 28px; `xl` — 40px: a provider's own page or card
-- **secret** (moments): `md` — The one-time secret on a well
-- **origin** (rights_matrix): `preset` — Comes from the role; `added` — Added on top of the role; `removed` — Removed from the role; `none` — Not granted
-- **mode** (rights_matrix): `edit` — Checkboxes, group toggles and requirement hints (default); `readOnly` — A mark per right and, under it, the roles that grant it
-- **appearance** (role_picker): `list` — 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` — Requests over the limit are refused; `soft` — Over the limit only alerts
+- **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
+- **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
 
 ### ConversationView
 
@@ -1505,7 +1525,7 @@ A stacked bar of token kinds with the numbers under it, in the fixed series mapp
 
 `import { Kbd, KbdSequence } from "@logicplanes/kaeso-ui/kbd";`
 
-- **tone** (kbd): `default` — On panels and raised surfaces; `onInk` — Inside ink surfaces (toasts, the selection bar)
+- **tone** (kbd): `default` (default) — On panels and raised surfaces; `onInk` — Inside ink surfaces (toasts, the selection bar)
 
 ### Kbd
 
@@ -1529,8 +1549,8 @@ A shortcut: `⌘ K`, or a sequence like `G then L`.
 
 `import { KeyValue } from "@logicplanes/kaeso-ui/key-value";`
 
-- **layout** (key_value): `columns` — Label and value side by side (default); `stacked` — Label above value, for narrow sheets; `grid` — Label above value, in columns: a wide sheet's details, two or more to a row
-- **columns** (key_value): `2` — Two to a row from 480px; one below (default); `3` — Three to a row from 480px; two below; `4` — Four to a row from 480px, for short values (counts, sizes); two below
+- **layout** (key_value): `columns` (default) — Label and value side by side (default); `stacked` — Label above value, for narrow sheets; `grid` — Label above value, in columns: a wide sheet's details, two or more to a row
+- **columns** (key_value): `2` (default) — Two to a row from 480px; one below (default); `3` — Three to a row from 480px; two below; `4` — Four to a row from 480px, for short values (counts, sizes); two below
 
 ### KeyValue
 
@@ -1547,7 +1567,7 @@ Label and value pairs (13 secondary label, 14 value), copyable values. Side by s
 
 `import { Label } from "@logicplanes/kaeso-ui/label";`
 
-- **size** (label): `md` — 14/500: field labels; `sm` — 13/500: compact forms
+- **size** (label): `md` (default) — 14/500: field labels; `sm` — 13/500: compact forms
 
 ### Label
 
@@ -1563,9 +1583,9 @@ The label of a form control.
 
 `import { Grid, Inline, Stack } from "@logicplanes/kaeso-ui/layout";`
 
-- **align** (layout): `start` — Align to the start; `center` — Center on the cross axis; `end` — Align to the end; `baseline` — Align text baselines; `stretch` — Stretch
-- **justify** (layout): `start` — Pack to the start; `center` — Center; `end` — Pack to the end; `between` — Space between
-- **columns** (layout): `1` — One column; `2` — Two columns from 768px; `3` — Three columns from 768px; `4` — Two, then four from 1024px; `6` — Three, then six from 1024px
+- **align** (layout): `start` — Align to the start; `center` — Center on the cross axis; `end` — Align to the end; `baseline` — Align text baselines; `stretch` (default) — Stretch
+- **justify** (layout): `start` (default) — Pack to the start; `center` — Center; `end` — Pack to the end; `between` — Space between
+- **columns** (layout): `1` — One column; `2` (default) — Two columns from 768px; `3` — Three columns from 768px; `4` — Two, then four from 1024px; `6` — Three, then six from 1024px
 
 ### Grid
 
@@ -1605,7 +1625,7 @@ A vertical stack.
 
 `import { Link } from "@logicplanes/kaeso-ui/link";`
 
-- **variant** (link): `inline` — Inside prose: text color with a quiet underline that turns solid on hover; `quiet` — Navigation-style links in footers and metadata; no underline until hover; `standalone` — A link on its own line (“Team overview ›”)
+- **variant** (link): `inline` (default) — Inside prose: text color with a quiet underline that turns solid on hover; `quiet` — Navigation-style links in footers and metadata; no underline until hover; `standalone` — A link on its own line (“Team overview ›”); `heading` — A heading's link to itself: the heading's own look, with a # beside it on hover and keyboard focus; `card` — A page to read next: a filled well with the page's name and one sentence about it
 
 ### Link
 
@@ -1616,13 +1636,13 @@ A link. Router links come from `LinkProvider`.
 | `children` * | `ReactNode` |  | The link's text. |
 | `href` * | `string` |  | The address the link goes to. |
 | `external` | `boolean` |  | Opens in a new tab, adds rel and a 14px ↗. Detected from the href when not set. |
-| `variant` | `"inline" \| "quiet" \| "standalone"` | `inline` | Underlined in text (`inline`), quiet in lists (`quiet`) or on its own line with an arrow (`standalone`). |
+| `variant` | `"heading" \| "inline" \| "quiet" \| "standalone" \| "card"` | `inline` | Underlined in text (`inline`), quiet in lists (`quiet`), on its own line with an arrow (`standalone`), inside a heading that links to itself (`heading`), or as a page to read next with its name and a sentence (`card`). |
 
 ## list
 
 `import { GroupHeader, List, ListRow, SelectionAction, SelectionBar } from "@logicplanes/kaeso-ui/list";`
 
-- **density** (list): `default` — 44px rows (default); `compact` — 36px rows
+- **density** (list): `default` (default) — 44px rows (default); `compact` — 36px rows
 
 ### GroupHeader
 
@@ -1713,9 +1733,9 @@ The floating capsule with the selection count and its actions: the toast's mater
 
 `import { Loader, Spinner } from "@logicplanes/kaeso-ui/loader";`
 
-- **size** (loader): `xs` — 14px: xs controls; `sm` — 16px: buttons, toasts, labels (default); `md` — 20px: xl buttons; `lg` — 24px: a region loading; `xl` — 32px: a page loading
-- **tone** (loader): `secondary` — Secondary text (default); `tertiary` — Tertiary text, the quietest: a page loading; `current` — The text color around it
-- **size** (spinner): `xs` — 14px: xs controls; `sm` — 16px: buttons, toasts, labels (default); `md` — 20px: xl buttons; `lg` — 24px: a region loading; `xl` — 32px: a page loading
+- **size** (loader): `xs` — 14px: xs controls; `sm` (default) — 16px: buttons, toasts, labels (default); `md` — 20px: xl buttons; `lg` — 24px: a region loading; `xl` — 32px: a page loading
+- **tone** (loader): `secondary` (default) — Secondary text (default); `tertiary` — Tertiary text, the quietest: a page loading; `current` — The text color around it
+- **size** (spinner): `xs` — 14px: xs controls; `sm` (default) — 16px: buttons, toasts, labels (default); `md` — 20px: xl buttons; `lg` — 24px: a region loading; `xl` — 32px: a page loading
 
 ### Loader
 
@@ -1744,8 +1764,8 @@ Kaeso's spinner: three routes on a ring, the lead in full color and the two behi
 
 `import { Logo } from "@logicplanes/kaeso-ui/logo";`
 
-- **markSize** (logo): `sm` — 20px high: the minimum in interfaces; `md` — 24px: compact navigation; `lg` — 32px; `xl` — 48px: empty and setup screens
-- **lockupSize** (logo): `sm` — 28px high (112px wide): the minimum; `md` — 32px: headers; `lg` — 40px: auth and setup screens
+- **markSize** (logo): `sm` — 20px high: the minimum in interfaces; `md` (default) — 24px: compact navigation; `lg` — 32px; `xl` — 48px: empty and setup screens
+- **lockupSize** (logo): `sm` (default) — 28px high (112px wide): the minimum; `md` — 32px: headers; `lg` — 40px: auth and setup screens
 
 ### Logo
 
@@ -1761,8 +1781,8 @@ Kaeso's spinner: three routes on a ring, the lead in full color and the two behi
 
 `import { Markdown } from "@logicplanes/kaeso-ui/markdown";`
 
-- **size** (markdown): `lg` — 15/22 text, 16px between blocks: a model's response, for reading; `body` — 14/20 text, 12px between blocks: responses and prompts (default); `small` — 13/18 text, 8px between blocks: reasoning, tool results, side notes
-- **tone** (markdown): `default` — Primary text (default); `secondary` — Quieter text: reasoning summaries and quotes
+- **size** (markdown): `lg` — 15/22 text, 16px between blocks: a model's response, for reading; `body` (default) — 14/20 text, 12px between blocks: responses and prompts (default); `small` — 13/18 text, 8px between blocks: reasoning, tool results, side notes
+- **tone** (markdown): `default` (default) — Primary text (default); `secondary` — Quieter text: reasoning summaries and quotes
 
 ### Markdown
 
@@ -1784,9 +1804,9 @@ Markdown, safely: headings, paragraphs, lists, tasks, code fences (CodeBlock), i
 
 `import { ContextMenu, Menubar } from "@logicplanes/kaeso-ui/menu";`
 
-- **item** (menu): `default` — An action; `danger` — A destructive action: red text, a red tint on highlight
-- **width** (menu): `auto` — 220–360px, from its content (default); `trigger` — As wide as its trigger
-- **description** (menu): `secondary` — The second line of a rich item (default); `danger` — A second line that warns: an organization scheduled for deletion
+- **item** (menu): `default` (default) — An action; `danger` — A destructive action: red text, a red tint on highlight
+- **width** (menu): `auto` (default) — 220–360px, from its content (default); `trigger` — As wide as its trigger
+- **description** (menu): `secondary` (default) — The second line of a rich item (default); `danger` — A second line that warns: an organization scheduled for deletion
 
 ### ContextMenu
 
@@ -1813,8 +1833,8 @@ A row of menus, as in a desktop app's title bar.
 
 `import { Meter, Progress } from "@logicplanes/kaeso-ui/meter";`
 
-- **tone** (meter): `auto` — Series 1 until the first alert threshold, warning after, danger at 100% (default); `neutral` — A plain share
-- **kind** (progress): `determinate` — A pill bar with a known amount; `indeterminate` — A 2px line at the top of a container
+- **tone** (meter): `auto` (default) — Series 1 until the first alert threshold, warning after, danger at 100% (default); `neutral` — A plain share
+- **kind** (progress): `determinate` (default) — A pill bar with a known amount; `indeterminate` — A 2px line at the top of a container
 
 ### Meter
 
@@ -1847,7 +1867,7 @@ Progress for work over a second: a determinate pill, or an indeterminate 2px lin
 
 `import { PageHeader } from "@logicplanes/kaeso-ui/page-header";`
 
-- **size** (page_header): `md` — 52px, no bottom line (default); on a phone the tabs take a second row
+- **size** (page_header): `md` (default) — 52px, no bottom line (default); on a phone the tabs take a second row
 
 ### PageHeader
 
@@ -1866,7 +1886,7 @@ The 52px header of a page: its title, pill tabs, actions. On a phone the tabs mo
 
 `import { AuthPage, EmptyPage, ListPage, OverviewPage } from "@logicplanes/kaeso-ui/blocks/pages";`
 
-- **page** (pages): `list` — Header, toolbar, a full-bleed List; `table` — Header, toolbar, a DataTable edge to edge; `overview` — A metric row, a chart, a breakdown and an optional aside; `empty` — Empty centered in the panel; `auth` — No chrome; a centered 400px column
+- **page** (pages): `list` (default) — Header, toolbar, a full-bleed List; `table` — Header, toolbar, a DataTable edge to edge; `overview` — A metric row, a chart, a breakdown and an optional aside; `empty` — Empty centered in the panel; `auth` — No chrome; a centered 400px column
 
 ### AuthPage
 
@@ -1922,7 +1942,7 @@ Big numbers, period controls, a chart on the panel, a breakdown, an optional rig
 
 `import { Pagination } from "@logicplanes/kaeso-ui/pagination";`
 
-- **variant** (pagination): `load-more` — A “Load more” pill while more rows exist, nothing once all are shown (cursor APIs, default); `cursor` — Previous and next circles, without a count; `pages` — Page numbers, for lists with a known number of pages
+- **variant** (pagination): `load-more` (default) — A “Load more” pill while more rows exist, nothing once all are shown (cursor APIs, default); `cursor` — Previous and next circles, without a count; `pages` — Page numbers, for lists with a known number of pages
 
 ### Pagination
 
@@ -1946,13 +1966,13 @@ Moves through long lists by pages, by cursor, or with a Load more button.
 
 `import { CompareGrid, Composer, ModelPicker, ParameterPanel, ParameterPopover, PromptSuggestions, ResponseMetrics, ResponseView, Thread, UserMessage } from "@logicplanes/kaeso-ui/playground";`
 
-- **divider** (compare_grid): `hairline` — 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` — 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` — Transparent until hovered: a column header (default); `default` — A raised pill with a ring: a form or toolbar
-- **layout** (parameter_panel): `popover` — Inside a 320px popover (ParameterPopover) (default); `panel` — A side panel or sheet: a little more room between groups
-- **align** (prompt_suggestions): `start` — Rows the composer's width, their text on its text (default); `center` — Centered under an empty thread's title
-- **size** (response_metrics): `sm` — 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` — 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
+- **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
+- **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
 
 ### CompareGrid
 
@@ -2128,7 +2148,7 @@ A person's turn: their prompt as quiet text that opens the turn, no bubble. A lo
 
 `import { HoverCard, Popover } from "@logicplanes/kaeso-ui/popover";`
 
-- **padding** (popover): `form` — 12px: forms and free content (default); `list` — 6px: lists of rows, concentric with 10px items; `none` — No padding: calendars and custom layouts
+- **padding** (popover): `form` (default) — 12px: forms and free content (default); `list` — 6px: lists of rows, concentric with 10px items; `none` — No padding: calendars and custom layouts
 
 ### HoverCard
 
@@ -2170,7 +2190,7 @@ Renders children into document.body after mount. Overlays use Base UI's own port
 
 `import { QRCode } from "@logicplanes/kaeso-ui/qr-code";`
 
-- **size** (qr_code): `md` — 160px: setup dialogs (default); `lg` — 200px: a page of its own
+- **size** (qr_code): `md` (default) — 160px: setup dialogs (default); `lg` — 200px: a page of its own
 
 ### QRCode
 
@@ -2187,7 +2207,7 @@ A QR code drawn as one SVG path: dark modules on white in both themes, with a qu
 
 `import { Radio, RadioCards } from "@logicplanes/kaeso-ui/radio";`
 
-- **variant** (radio): `default` — A list of radios with labels (default); `cards` — Rows inside a settings group with the radio at the end, for choices with descriptions
+- **variant** (radio): `default` (default) — A list of radios with labels (default); `cards` — Rows inside a settings group with the radio at the end, for choices with descriptions
 
 ### Radio
 
@@ -2244,7 +2264,7 @@ Choices with descriptions as rows in a settings group.
 
 `import { ResourceList } from "@logicplanes/kaeso-ui/blocks/resource-list";`
 
-- **grouping** (resource_list): `grouped` — Rows under group headers (default); `flat` — One list
+- **grouping** (resource_list): `grouped` (default) — Rows under group headers (default); `flat` — One list
 
 ### ResourceList
 
@@ -2265,7 +2285,7 @@ A console list of resources: search, group headers, row actions and a selection
 
 `import { ScrollArea } from "@logicplanes/kaeso-ui/scroll-area";`
 
-- **orientation** (scroll_area): `vertical` — Scrolls up and down; the content fades at an edge with more to scroll to (default); `horizontal` — Scrolls sideways; `both` — Both directions
+- **orientation** (scroll_area): `vertical` (default) — Scrolls up and down; the content fades at an edge with more to scroll to (default); `horizontal` — Scrolls sideways; `both` — Both directions
 
 ### ScrollArea
 
@@ -2283,7 +2303,7 @@ A scroll container with thin scrollbars in the strong line color that show on ho
 
 `import { AuthLayout, Section, SplitView } from "@logicplanes/kaeso-ui/section";`
 
-- **spacing** (section): `default` — 48px between sections (default); `none` — No outer spacing
+- **spacing** (section): `default` (default) — 48px between sections (default); `none` — No outer spacing
 
 ### AuthLayout
 
@@ -2324,7 +2344,7 @@ Main content and a 320px aside, separated by space and a subtle vertical line. O
 
 `import { Segmented } from "@logicplanes/kaeso-ui/segmented";`
 
-- **size** (segmented): `sm` — 32px track, 28px items: toolbars and popovers; `md` — 36px track, 32px items (default)
+- **size** (segmented): `sm` — 32px track, 28px items: toolbars and popovers; `md` (default) — 36px track, 32px items (default)
 
 ### Segmented
 
@@ -2347,8 +2367,8 @@ Two to five mutually exclusive options: 24h/7d/30d, List/Board, providers.
 
 `import { Select } from "@logicplanes/kaeso-ui/select";`
 
-- **appearance** (select): `default` — A raised pill with a ring (default); `ghost` — Inline in settings rows: “GPT-5 mini (default) ⌄”; `header` — Transparent until hovered, in full text colour: a column header's model
-- **size** (select): `sm` — 32px: settings rows and toolbars; `md` — 36px (default); `lg` — 40px; `xl` — 48px: sign-in and setup forms
+- **appearance** (select): `default` (default) — A raised pill with a ring (default); `ghost` — Inline in settings rows: “GPT-5 mini (default) ⌄”; `header` — Transparent until hovered, in full text colour: a column header's model
+- **size** (select): `sm` — 32px: settings rows and toolbars; `md` (default) — 36px (default); `lg` — 40px; `xl` — 48px: sign-in and setup forms
 
 ### Select
 
@@ -2386,8 +2406,8 @@ A pill that opens a list on the menu surface: check on the selected item, groups
 
 `import { Separator } from "@logicplanes/kaeso-ui/separator";`
 
-- **orientation** (separator): `horizontal` — A 1px line across; `vertical` — A 1px line down
-- **tone** (separator): `subtle` — Inside groups and tables (default); `default` — Between regions that tone and space cannot separate
+- **orientation** (separator): `horizontal` (default) — A 1px line across; `vertical` — A 1px line down
+- **tone** (separator): `subtle` (default) — Inside groups and tables (default); `default` — Between regions that tone and space cannot separate
 
 ### Separator
 
@@ -2403,7 +2423,7 @@ A 1px line. Use space and tone first; a line only where they cannot separate.
 
 `import { SettingsGroup, SettingsRow, SettingsSection } from "@logicplanes/kaeso-ui/settings";`
 
-- **row** (settings): `default` — Title and description: at least 64px; `single` — One line: 56px
+- **row** (settings): `default` (default) — Title and description: at least 64px; `single` — One line: 56px
 
 ### SettingsGroup
 
@@ -2449,8 +2469,8 @@ A settings section: a title-sm heading 48px above, 12px below; usually one Setti
 
 `import { Sheet } from "@logicplanes/kaeso-ui/sheet";`
 
-- **size** (sheet): `sm` — 480px (default); `md` — 640px: the request inspector; `lg` — 800px
-- **side** (sheet): `right` — From the right (default); `left` — From the left: the mobile sidebar; `bottom` — From the bottom: mobile menus
+- **size** (sheet): `sm` (default) — 480px (default); `md` — 640px: the request inspector; `lg` — 800px
+- **side** (sheet): `right` (default) — From the right (default); `left` — From the left: the mobile sidebar; `bottom` — From the bottom: mobile menus
 
 ### Sheet
 
@@ -2476,9 +2496,9 @@ A panel that slides in from the edge of the screen, for details and longer forms
 
 `import { BrandWordmark, Sidebar } from "@logicplanes/kaeso-ui/sidebar";`
 
-- **mode** (sidebar): `expanded` — 248px by default, resizable between 232 and 280; `rail` — 60px: icons only, labels in tooltips
-- **item** (sidebar): `default` — A navigation item; `active` — The current page
-- **caption** (sidebar): `secondary` — A quiet second line under the switcher's label (default); `danger` — A second line that warns: the organization is scheduled for deletion
+- **mode** (sidebar): `expanded` (default) — 248px by default, resizable between 232 and 280; `rail` — 60px: icons only, labels in tooltips
+- **item** (sidebar): `default` (default) — A navigation item; `active` — The current page
+- **caption** (sidebar): `secondary` (default) — A quiet second line under the switcher's label (default); `danger` — A second line that warns: the organization is scheduled for deletion
 
 ### BrandWordmark
 
@@ -2506,7 +2526,7 @@ Provided by NavSheet: how the sidebar's own toggle closes the sheet it floats in
 
 `import { Skeleton, SkeletonLine } from "@logicplanes/kaeso-ui/skeleton";`
 
-- **shape** (skeleton): `block` — Rounded blocks for charts and wells (default); `line` — A pill line for text; `circle` — Avatars and icons; `control` — The shape of a 36px control
+- **shape** (skeleton): `block` (default) — Rounded blocks for charts and wells (default); `line` — A pill line for text; `circle` — Avatars and icons; `control` — The shape of a 36px control
 
 ### Skeleton
 
@@ -2528,7 +2548,7 @@ Lines of text: the last one shorter.
 
 `import { Slider } from "@logicplanes/kaeso-ui/slider";`
 
-- **size** (slider): `md` — A 4px track in a 20px hit area (default)
+- **size** (slider): `md` (default) — A 4px track in a 20px hit area (default)
 
 ### Slider
 
@@ -2556,7 +2576,7 @@ A 4px pill track, an ink range and a 16px ink thumb; a value bubble while draggi
 
 `import { MetricRow, Stat, StatGrid, StatTile } from "@logicplanes/kaeso-ui/stat";`
 
-- **size** (stat): `md` — 28/32 metric (default); `sm` — 20/28 for dense rows
+- **size** (stat): `md` (default) — 28/32 metric (default); `sm` — 20/28 for dense rows
 
 ### MetricRow
 
@@ -2607,7 +2627,7 @@ One metric of a dashboard row: its label, the number, the change against the pre
 
 `import { Status, StatusDot } from "@logicplanes/kaeso-ui/status-dot";`
 
-- **tone** (status_dot): `success` — Healthy, active, succeeded; `warning` — Degraded, expiring; `danger` — Failed, disabled, down; `info` — Informational; `neutral` — Inactive, archived (default)
+- **tone** (status_dot): `success` — Healthy, active, succeeded; `warning` — Degraded, expiring; `danger` — Failed, disabled, down; `info` — Informational; `neutral` (default) — Inactive, archived (default)
 
 ### Status
 
@@ -2635,7 +2655,7 @@ A status word: "Active", "Expiring", "Down".
 
 `import { Surface } from "@logicplanes/kaeso-ui/surface";`
 
-- **kind** (surface): `panel` — The content panel: radius 12, hairline ring; `menu` — Menus, select and combobox lists: radius 16; `popover` — Popovers and hover cards: radius 16; `dialog` — Dialogs and the command palette: radius 20; `sheet` — Sheets: radius 16 on exposed corners; `group` — Settings groups: radius 14, ring and a whisper of shadow; `well` — Code, the key reveal, the JSON inspector: fill, no ring; `tooltip` — Chart tooltips and rich tooltips: radius 12
+- **kind** (surface): `panel` (default) — The content panel: radius 12, hairline ring; `menu` — Menus, select and combobox lists: radius 16; `popover` — Popovers and hover cards: radius 16; `dialog` — Dialogs and the command palette: radius 20; `sheet` — Sheets: radius 16 on exposed corners; `group` — Settings groups: radius 14, ring and a whisper of shadow; `well` — Code, the key reveal, the JSON inspector: fill, no ring; `tooltip` — Chart tooltips and rich tooltips: radius 12
 
 ### Surface
 
@@ -2649,7 +2669,7 @@ One of the library's surfaces, for content that needs the look of a panel, popov
 
 `import { SwapText } from "@logicplanes/kaeso-ui/swap-text";`
 
-- **align** (swap_text): `center` — Centered in the reserved width (default); `start` — Aligned to the start
+- **align** (swap_text): `center` (default) — Centered in the reserved width (default); `start` — Aligned to the start
 
 ### SwapText
 
@@ -2665,7 +2685,7 @@ Text that changes with state without changing size: all alternatives sit in one
 
 `import { Switch } from "@logicplanes/kaeso-ui/switch";`
 
-- **size** (switch): `sm` — 28×16, 12px thumb; `md` — 36×20, 16px thumb (default); `lg` — 44×24, 20px thumb
+- **size** (switch): `sm` — 28×16, 12px thumb; `md` (default) — 36×20, 16px thumb (default); `lg` — 44×24, 20px thumb
 
 ### Switch
 
@@ -2694,7 +2714,7 @@ A pill track and a round thumb that travels in 180ms.
 
 `import { Table } from "@logicplanes/kaeso-ui/table";`
 
-- **align** (table): `start` — Text (default); `end` — Numbers
+- **align** (table): `start` (default) — Text (default); `end` — Numbers
 
 ### Table
 
@@ -2704,7 +2724,7 @@ A plain table for small amounts of data; use `DataTable` for sorting, selection
 
 `import { PillTabs, Tabs } from "@logicplanes/kaeso-ui/tabs";`
 
-- **variant** (tabs): `underline` — Underline tabs for detail pages: 40px, a 2px ink indicator that slides; `pill` — Header tabs: separate 32px pills, the active one filled
+- **variant** (tabs): `underline` (default) — Underline tabs for detail pages: 40px, a 2px ink indicator that slides; `pill` — Header tabs: separate 32px pills, the active one filled
 
 ### PillTabs
 
@@ -2736,8 +2756,8 @@ Underline tabs for detail pages.
 
 `import { Pill, Tag } from "@logicplanes/kaeso-ui/tag";`
 
-- **size** (tag): `md` — 28px: metadata pills in lists and toolbars (default); `sm` — 24px: inside table rows
-- **variant** (tag): `raised` — Raised with a ring: metadata pills (default); `outline` — Ring only: unselected toggle pills; `soft` — Filled: selected toggle pills
+- **size** (tag): `md` (default) — 28px: metadata pills in lists and toolbars (default); `sm` — 24px: inside table rows
+- **variant** (tag): `raised` (default) — Raised with a ring: metadata pills (default); `outline` — Ring only: unselected toggle pills; `soft` — Filled: selected toggle pills
 
 ### Pill
 
@@ -2777,8 +2797,8 @@ A metadata pill: 28px, 13/500, an optional icon, an optional remove circle. A la
 
 `import { Text } from "@logicplanes/kaeso-ui/text";`
 
-- **variant** (text): `micro` — 11/14 500: keyboard keys and chart ticks only; `caption` — 12/16 500: group labels, badges, table headers; `small` — 13/18: descriptions, secondary cells, hints; `body` — 14/20: the default; `body-lg` — 15/22 500: settings row titles, dialog body; `title-sm` — 17/24 600: section and dialog titles; `title` — 20/28 600: empty-state and compact page titles; `title-lg` — 28/34 600: settings page titles, auth screens; `display` — 40/44 600: showcase headings, the setup screen; `metric` — 28/32 600 tabular: big numbers
-- **tone** (text): `default` — Primary text; `secondary` — Descriptions and metadata; `tertiary` — Placeholders and redundant hints; never the only carrier of meaning; `danger` — Errors, next to an icon or a word; `success` — Confirmation, next to an icon or a word; `warning` — Warnings, next to an icon or a word; `info` — Information in progress (syncing, queued), next to an icon or a word; `inherit` — Inherit from the parent
+- **variant** (text): `micro` — 11/14 500: keyboard keys and chart ticks only; `caption` — 12/16 500: group labels, badges, table headers; `small` — 13/18: descriptions, secondary cells, hints; `body` (default) — 14/20: the default; `body-lg` — 15/22 500: settings row titles, dialog body; `title-sm` — 17/24 600: section and dialog titles; `title` — 20/28 600: empty-state and compact page titles; `title-lg` — 28/34 600: settings page titles, auth screens; `display` — 40/44 600: showcase headings, the setup screen; `metric` — 28/32 600 tabular: big numbers
+- **tone** (text): `default` (default) — Primary text; `secondary` — Descriptions and metadata; `tertiary` — Placeholders and redundant hints; never the only carrier of meaning; `danger` — Errors, next to an icon or a word; `success` — Confirmation, next to an icon or a word; `warning` — Warnings, next to an icon or a word; `info` — Information in progress (syncing, queued), next to an icon or a word; `inherit` — Inherit from the parent
 - **weight** (text): `regular` — 400; `medium` — 500 (480 in dark mode); `semibold` — 600 (580 in dark mode)
 
 ### Text
@@ -2796,11 +2816,31 @@ Text in the type scale.
 | `variant` | `"title" \| "display" \| "title-sm" \| "title-lg" \| "body" \| "caption" \| "small" \| "micro" \| "body-lg" \| "metric"` | `body` | The type style, from `micro` to `display`. |
 | `weight` | `"medium" \| "regular" \| "semibold"` |  | The weight, when it differs from the type style's. |
 
+## theme-image
+
+`import { ThemeImage } from "@logicplanes/kaeso-ui/theme-image";`
+
+- **theme** (theme_image): `light` — Shown in the light theme and in print; `dark` — Shown in the dark theme
+
+### ThemeImage
+
+An image drawn twice, once for each theme: it follows the site's theme setting, not only the system's, and prints the light one.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `alt` * | `string` |  | What the image shows, read by screen readers and shown when it can't load. |
+| `dark` * | `string` |  | The image's address for the dark theme. |
+| `light` * | `string` |  | The image's address for the light theme and for print. |
+| `aria-describedby` | `string` |  | The id of a longer description, such as a diagram's text alternative. |
+| `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `height` | `number` |  | The image's own height in pixels, so the page keeps its place before it loads. |
+| `width` | `number` |  | The image's own width in pixels; the image shrinks to its container, never grows past this. |
+
 ## theme-menu
 
 `import { ThemeMenu } from "@logicplanes/kaeso-ui/theme-menu";`
 
-- **variant** (theme_menu): `ghost` — A ghost circle (default); `secondary` — A raised circle
+- **variant** (theme_menu): `ghost` (default) — A ghost circle (default); `secondary` — A raised circle
 
 ### ThemeMenu
 
@@ -2811,11 +2851,30 @@ System, light or dark, stored as `kaeso:theme`.
 | `size` | `"md" \| "sm"` | `sm` | The button's height. |
 | `variant` | `"secondary" \| "ghost"` | `ghost` | A filled button (`secondary`) or a quiet one (`ghost`). |
 
+## theme-select
+
+`import { ThemeSelect } from "@logicplanes/kaeso-ui/theme-select";`
+
+- **appearance** (theme_select): `ghost` (default) — A quiet pill for sidebars and toolbars (default); `default` — A raised pill with a ring
+- **size** (theme_select): `sm` (default) — 32px (default); `md` — 36px
+
+### ThemeSelect
+
+A select for system, light or dark, stored as `kaeso:theme`, with its label in the provider's language.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `appearance` | `"ghost" \| "default"` | `ghost` | A quiet pill for sidebars and toolbars (`ghost`) or a raised one with a ring (`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`. |
+| `fullWidth` | `boolean` |  | Width of the trigger follows its content (default) or fills the container, as in a sidebar's footer. |
+| `size` | `"md" \| "sm"` | `sm` | The height of the field. |
+
 ## timeline
 
 `import { Timeline } from "@logicplanes/kaeso-ui/timeline";`
 
-- **tone** (timeline): `neutral` — Ordinary events (default); `success` — Something completed; `warning` — Something changed that needs attention; `danger` — Something failed or was removed; `info` — Informational
+- **tone** (timeline): `neutral` (default) — Ordinary events (default); `success` — Something completed; `warning` — Something changed that needs attention; `danger` — Something failed or was removed; `info` — Informational
 
 ### Timeline
 
@@ -2830,7 +2889,7 @@ Events down a 1px line (the audit log): each event marks the line with a short 3
 
 `import { Toast, ToastCapsule, Toaster } from "@logicplanes/kaeso-ui/toast";`
 
-- **tone** (toast): `neutral` — A plain message (default); `success` — Success: a green check before the words; `error` — Errors: a red mark; announced as an alert; `warning` — Warnings; `info` — Information; `loading` — Work underway: a spinner
+- **tone** (toast): `neutral` (default) — A plain message (default); `success` — Success: a green check before the words; `error` — Errors: a red mark; announced as an alert; `warning` — Warnings; `info` — Information; `loading` — Work underway: a spinner
 
 ### Toast
 
@@ -2867,7 +2926,7 @@ Mount once near the root. Three visible at most; 5s, paused on hover and focus;
 
 `import { TableOfContents } from "@logicplanes/kaeso-ui/toc";`
 
-- **state** (table_of_contents): `default` — A heading; `active` — The heading in view, with a 2px ink bar
+- **state** (table_of_contents): `default` (default) — A heading; `active` — The heading in view, with a 2px ink bar
 
 ### TableOfContents
 
@@ -2884,7 +2943,7 @@ Mount once near the root. Three visible at most; 5s, paused on hover and focus;
 
 `import { Toolbar } from "@logicplanes/kaeso-ui/toolbar";`
 
-- **size** (toolbar): `md` — 48px, 24px side padding, under the page header (default); `inset` — 48px without side padding, inside padded content
+- **size** (toolbar): `md` (default) — 48px, 24px side padding, under the page header (default); `inset` — 48px without side padding, inside padded content
 
 ### Toolbar
 
@@ -2899,8 +2958,8 @@ A row of controls above a list or a chart.
 
 `import { Tooltip, TooltipProvider, TooltipSurface } from "@logicplanes/kaeso-ui/tooltip";`
 
-- **side** (tooltip): `top` — Above the trigger (default); `bottom` — Below the trigger; `left` — Left of the trigger; `right` — Right of the trigger
-- **shape** (tooltip): `pill` — Single line: a pill (default); `multiline` — Several lines: radius 12, max 280px
+- **side** (tooltip): `top` (default) — Above the trigger (default); `bottom` — Below the trigger; `left` — Left of the trigger; `right` — Right of the trigger
+- **shape** (tooltip): `pill` (default) — Single line: a pill (default); `multiline` — Several lines: radius 12, max 280px
 
 ### Tooltip