@nurix/etna 0.20.37 → 0.20.38

package/data/harnesses/code/skills/design/components/collections.md

@@ -2,52 +2,59 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
+Components: Table, UiTable, List, Tree, FieldGrid, AnchoredScroller, Composer, MicInput, StreamingCursor, Marker
+
+Each imports from its own subpath as one namespace, with its parts as dotted members, e.g. `import { UiTable } from "@nurix/components/block/ui-table"` then `UiTable.Row`, `UiTable.Cell`. `Table` is the exception: a single generic root whose cell renderers stay flat named exports.
+
 ## Table
 
-Data table with sorting, pagination, and row selection. Zero-config `<Table data columns />` renders bare; selection, sorting, pagination, and resize are opt-in via `tableConfig`.
+Server-driven data table on a TanStack engine (`block/table`). Zero-config `<Table data columns />` renders bare; selection, sorting, pagination, resize and the grid keyboard model are opt-in via `tableConfig`. Install its two optional peer families first — `table` (`@tanstack/react-table`) and `spark` (`@mantine/charts @mantine/core recharts`, for the lazily loaded sparkline cell); a missing peer fails at the bundler with the package named.
 
 **Props:**
 
-- `data` - Array of row objects (must have `id` field)
+- `data` - Array of row objects (each must have an `id` string)
 - `columns` - Array of `ColumnDefinition` objects
-- `columnOrder` - Optional column order (defaults to column definition order)
-- `pagination` - `{ current, size, total, onChange }`
-- `sorting` - `{ columns, direction, onChange }` (max 3 sort columns)
+- `columnOrder` - Composite column ids in display order (defaults to column definition order)
+- `pagination` - `{ current, size, total, onChange }` — controlled and 1-indexed; slice `data` to the current page yourself
+- `sorting` - `{ columns, direction, onChange }` (max 3 sort columns) — `columns` takes composite ids
 - `onSelect` - Callback with selected row IDs
-- `onCellChange` - Write-back from `editable` cells: `({ rowId, columnId, slug, value }) => void` (data stays consumer-controlled)
+- `onCellChange` - Write-back from `editable` cells: `({ rowId, columnId, slug, value }) => void`; fires only on a real commit (a blur that typed nothing emits nothing), and the table never mutates `data`
 - `loading` - Show loading skeleton
-- `tableConfig` - Optional; `{ preset, rowSelection, sort, pagination, header, density, columnBorders, tableBorders, resize, autoHeight }`
+- `error` - `{ message, onRetry? }` — a failed fetch renders in place of the rows; wins over `loading`, which wins over the empty body
+- `tableConfig` - Optional; `{ preset, rowSelection, sort, pagination, header, density, columnBorders, tableBorders, resize, autoHeight, gridAria }`
+
+`density` is [compact|comfortable|spacious]; `columnBorders`/`tableBorders` are [none|all]. `preset: "classic"` sets a tinted short header row, comfortable density, the pagination footer and `tableBorders: "all"` in one key, and explicit keys override it. The pagination footer is opt-in (`pagination: true`); `gridAria` adds `role="grid"` with roving-tabindex arrow navigation.
 
-`preset: "classic"` restores the legacy look in one key; `resize` gates column drag handles; the pagination footer is opt-in (`pagination: true`).
+**Composite ids.** `sorting.columns` and `columnOrder` take `getColumnId()`'s `${slug}_${component}` id — `name_text` for a `slug: "name"`, `type: "text"` column. A bare `"name"` silently matches no column.
 
 ```tsx
 <Table
-  data={users}
+  data={pageRows}
   columns={columns}
   pagination={{ current: 1, size: 10, total: 100, onChange: setPagination }}
-  sorting={{ columns: ["name"], direction: "asc", onChange: setSorting }}
+  sorting={{ columns: ["name_text"], direction: "asc", onChange: setSorting }}
   onSelect={setSelectedIds}
-  tableConfig={{ rowSelection: true, resize: true }}
+  tableConfig={{ rowSelection: true, pagination: true, resize: true }}
 />
 ```
 
 ## ColumnDefinition
 
-Define table columns using the `defineColumn()` helper.
+Define table columns with the `defineColumn()` helper, which fills `component` from `type`, `hidden: false`, and empty `metadata`/`display`.
 
 **Fields:**
 
-- `slug` - Field key in data object
+- `slug` - Field key in the row object
 - `label` - Column header text
 - `type` - Data type: `text`, `number`, `boolean`, `date`, `enum`, `user`
-- `component` - Renderer (defaults from `type`): `text`, `number`, `boolean`, `date`, `select`, `multiselect`, `slider`, `rating`, `status`, `priority`, `assignee`, `sparkline`, `date-range`
+- `component` - Renderer (defaults from `type`: `enum` → `select`, `user` → `assignee`, otherwise the type string): `text`, `number`, `boolean`, `date`, `date-range`, `select`, `multiselect`, `slider`, `rating`, `status`, `priority`, `assignee`, `sparkline`
 - `hidden` - Hide column
 - `editable` - Activate the interactive widget; columns render the read-only display variant by default
 - `metadata` - Component-specific options (see table below)
-- `display` - `{ width, sortable }` (width optional — columns are fluid when unset)
-- `cell` - Custom render function `(row) => ReactNode`
+- `display` - `{ width, sortable }` (width optional — columns are fluid when unset; `sortable` defaults to true except for `boolean` and `user`)
+- `cell` - Custom render function `(row) => ReactNode`; wins over `component`
 
-For full control, pass your own `cell()` or import a renderer from `@nurix/components/block/table` (`StatusPill`, `SelectCell`, etc.) as an escape hatch.
+For full control, pass your own `cell()` and compose a renderer imported from `@nurix/components/block/table` — `EditableText`, `EditableNumber`, `EditableDate`, `EditableDateRange`, `BooleanCell`, `SliderCell`, `RatingCell`, `SelectCell`, `StatusCell`, `PriorityCell`, `AssigneeChip`, `MultiSelectCell`, `TableSparkline`. Each is a flat export so a consumer pays only for the renderers it imports.
 
 ### Metadata options by component
 
@@ -67,13 +74,13 @@ For full control, pass your own `cell()` or import a renderer from `@nurix/compo
 import { defineColumn } from "@nurix/components/block/table";
 
 const columns = [
-  defineColumn({
+  defineColumn<Row>({
     slug: "name",
     label: "Name",
     type: "text",
     editable: true,
   }),
-  defineColumn({
+  defineColumn<Row>({
     slug: "status",
     label: "Status",
     type: "enum",
@@ -82,14 +89,14 @@ const columns = [
       options: [{ value: "active", label: "Active", color: "#22c55e" }],
     },
   }),
-  defineColumn({
+  defineColumn<Row>({
     slug: "progress",
     label: "Progress",
     type: "number",
     component: "slider",
     metadata: { min: 0, max: 100 },
   }),
-  defineColumn({
+  defineColumn<Row>({
     slug: "createdAt",
     label: "Created",
     type: "date",
@@ -98,35 +105,196 @@ const columns = [
 ];
 ```
 
-## PageHeader
+## UiTable
+
+Bare native-table parts (`block/ui-table`) for markup you write yourself — no data model, no sort, no edit machinery. Reach for `Table` the moment the data needs sorting, editable cells or a `defineColumn` column set.
+
+**Sub-components:** `UiTable.Header`, `UiTable.Body`, `UiTable.Footer`, `UiTable.Head`, `UiTable.Row`, `UiTable.Cell`, `UiTable.Caption`
+
+- The root renders a `data-slot="table-container"` scroll wrapper around the `<table>`; `className` on `UiTable` styles the `<table>`, not the wrapper.
+- Mark a selected row with `data-selected` on `UiTable.Row` (paints on the accent; `data-state="selected"` paints nothing). Body rows take the hover wash; header and footer rows stay still.
+- No built-in loading, empty or error row — it renders exactly the rows it is given.
+
+```tsx
+<UiTable>
+  <UiTable.Header>
+    <UiTable.Row><UiTable.Head>Invoice</UiTable.Head></UiTable.Row>
+  </UiTable.Header>
+  <UiTable.Body>
+    <UiTable.Row><UiTable.Cell>INV001</UiTable.Cell></UiTable.Row>
+  </UiTable.Body>
+</UiTable>
+```
+
+## List
+
+Keyed collection whose rows you draw (`block/list`) — `item.id` is the React key, the selection key, the expand key and what row motion tracks. Rows with typed columns are `Table`; a chat transcript is `AnchoredScroller`. Activity feeds, record history, notification inboxes and card grids are `List` with a recipe.
+
+**Sub-components:** `List.Toolbar`, `List.Pagination` (the parts List renders from `toolbar` and `pagination`), `List.ItemErrorBoundary` (wraps every row: a render throw becomes a compact error state while the other rows stand)
+
+**Props:** `data`, `renderItem(item, index, { isExpanded, onToggle, view })`, `toolbar` (`{ search: { placeholder, keys }, filters: [{ key, label, options, multiple }], showExpandControls, actions }`), `pagination` (`{ current, size, total, onChange }` — when present, the parent has already filtered, sorted and paged), `expandedIds`/`defaultExpandedIds`/`onExpandedIdsChange` (`string[] | "all"`), `searchValue`/`defaultSearchValue`/`onSearchValueChange`, `filters`/`defaultFilters`/`onFiltersChange`, `onSelect`, `groupBy(item) → { key, label }` (a `Marker` separator before each run), `live` (holds rows arriving above the viewport behind an "N new" pill — keep `data` newest-first), `onLoadMore` + `hasMore` + `loadingMore`, `view` [list|card], `onItemActivate(id)`, `onItemError(error, id)`, `loading`, `error` (`{ message, onRetry? }`), `emptyState`, `labels`, `config` (`{ selection, density, dividers, animation: { type: slide|fade|scale|none }, expandable, pageSizeOptions, cardColumns }`)
+
+- No virtualization: every item in `data` renders, so page an unbounded collection with `onLoadMore` or `pagination`.
+- `expandedIds`, `searchValue` and `filters` go controlled the moment the prop is passed — `expandedIds={[]}` locks expansion closed unless `onExpandedIdsChange` drives it.
+
+```tsx
+<List
+  data={events}
+  renderItem={(event) => <FeedRow event={event} />}
+  groupBy={(event) => ({ key: dayKey(event), label: dayLabel(event) })}
+  toolbar={{ search: { keys: ["title"] }, filters: [{ key: "type", label: "Type", options }] }}
+  onLoadMore={loadOlder}
+  hasMore={hasMore}
+  loadingMore={isLoading}
+/>
+```
+
+## Tree
+
+Hierarchy built from flat records that name their parent (`block/tree`); `useTree` is exported beside it for fully custom markup.
 
-Config-driven page masthead with an optional stat ledger — router-agnostic (the consumer owns navigation). Import from `@nurix/components/block/page-header`.
+**Sub-components:** `Tree.Item`, `Tree.ItemLabel` (returned from `renderItem` when a row needs its own props or `render` element).
 
-**Props:** `title`, `eyebrow` (breadcrumb segments — strings or linked `Crumb`s; last is the current page), `description`, `statusSlot`, `actions`, `stats` (`Stat[]` ledger), `back` (`BackLink`), `onBack`, `onNavigate` (fired with a crumb's/stat's `href`), `statsAlign` [left|right], `tall`
+**Props:** `data`, `getParentId` (`null` for a top-level record), `isItemFolder`, `isItemDisabled`, `renderItem`, `selectionMode` [none|single|multiple], `selectedIds`/`defaultSelectedIds`/`onSelectedIdsChange`, `expandedIds`/`defaultExpandedIds` (an id list or `"all"`; default `[]`)/`onExpandedIdsChange`, `onItemActivate`
+
+- Keep the accessor functions stable — the rows re-flatten whenever `data` or an accessor changes identity. Records whose parent id names no record never render.
 
 ```tsx
-<PageHeader
-  title="Q3 Pipeline"
-  eyebrow={["Sales", "Pipelines"]}
-  actions={<Button size="sm">Export</Button>}
-  stats={[{ label: "Open deals", value: "142" }, { label: "Won", value: "$1.2M" }]}
+<Tree
+  aria-label="Files"
+  data={records}
+  getParentId={getParentId}
+  selectionMode="single"
+  onItemActivate={openFile}
+  renderItem={(item) => item.getItemData().name}
 />
 ```
 
+## FieldGrid
+
+One record's fields, column-driven and editable in place (`compound/field-grid`) — the description list. Skip it for one labelled form field (`compound/cell`) and for many records (`Table`).
+
+**Props:** `columns` (`FieldColumn[]`), `data` (the one record), `onDataChange(slug, value)`, `arrangement` [grid|strip] (default `grid`, the responsive labelled `<dl>`; `strip` is the compact icon-and-value band), `columnsPerRow` (grid only, 1–9, default 6), `labels` (`{ empty, on, off }`)
+
+**FieldColumn:** `id`, `slug`, `label`, `type` [text|number|boolean|date|slider|rating|enum|status|priority|assignee|avatar|avatarGroup|chip|timer], `options` (`[{ value, label, color, icon }]`), `readOnly`, `placeholder`, `min`/`max`/`step`, `format` (Intl number options), `colSpan`, `icon` (a Lucide icon, or `true` to pick one from `type` then `slug`), `validate(value)` (a returned message refuses the commit), `cell(value, record)` (wins over `type`)
+
+- Editing is opt-in twice: a column is read-only unless it sets `readOnly: false` **and** the grid received `onDataChange`. Each editor commits once (Enter or blur for text, the pick for options, the release for a slider).
+- The grid is naked — the strip's band chrome goes on the call site.
+
+```tsx
+<FieldGrid
+  arrangement="strip"
+  data={deal}
+  onDataChange={(slug, value) => updateDeal(deal.id, { [slug]: value })}
+  className="border-y bg-muted/30 px-5 py-3"
+  columns={[
+    { id: "stage", slug: "stage", label: "Stage", type: "status", options: stages, readOnly: false, icon: true },
+    { id: "amount", slug: "amount", label: "Amount", type: "number", format: { style: "currency", currency: "USD" } },
+  ]}
+/>
+```
+
+## Page and record headers
+
+No page-header block ships: compose the masthead at the call site. A title row and actions sit on a `Row`; a KPI ledger is several `Stat` (`element/stat`) on a `Row` beneath it, documented in [typography](typography.md); a record's labelled fields are `FieldGrid` with `arrangement="strip"`.
+
 ## Conversation surfaces
 
-Chat/AI message chrome; import each from its kebab-case subpath.
+Chat and message-thread chrome; import each from its own subpath.
+
+### AnchoredScroller
+
+Scroll region that sticks to the newest message and offers a jump control once the reader scrolls away (`block/anchored-scroller`). Install its optional peer family `anchored-scroller` (`@shadcn/react`) first. A plain scrollable region with no stick-to-bottom behavior is `element/scroll-area`.
+
+**Sub-components:** `AnchoredScroller.Provider`, `AnchoredScroller.Viewport`, `AnchoredScroller.Content`, `AnchoredScroller.Item`, `AnchoredScroller.Button`; hooks `useAnchoredScroller`, `useAnchoredScrollerScrollable`, `useAnchoredScrollerVisibility`
+
+**Props:** Provider — `shouldAutoScroll`, `defaultScrollPosition`; root — `labels` (`{ region, scrollToEnd, scrollToStart }`); Viewport — `shouldPreserveScrollOnPrepend` (default `true`); Item — `itemId`, `isScrollAnchor`; Button — `direction` [start|end] (default `end`), plus `Button`'s `variant`, `size`, `isIconOnly`
+
+- The hooks read the scroll store only from components rendered under `AnchoredScroller.Provider`.
+- Give every Item an `itemId` — `scrollToItem`, `visibleItemIds` and `currentAnchorId` key off it.
+
+```tsx
+<AnchoredScroller.Provider shouldAutoScroll defaultScrollPosition="end">
+  <AnchoredScroller labels={{ region: "Support thread" }}>
+    <AnchoredScroller.Viewport>
+      <AnchoredScroller.Content>
+        {messages.map((m) => (
+          <AnchoredScroller.Item key={m.id} itemId={m.id} isScrollAnchor={m.isTurnStart}>{renderMessage(m)}</AnchoredScroller.Item>
+        ))}
+      </AnchoredScroller.Content>
+    </AnchoredScroller.Viewport>
+    <AnchoredScroller.Button direction="end" />
+  </AnchoredScroller>
+</AnchoredScroller.Provider>
+```
+
+### Composer
+
+Chat message composer: textarea, attachments, a footer of controls and a send (`@nurix/components/block/composer`, plus `useStagedFiles`, `composerNoticeVariants`).
+
+**Props:** `onSubmit`, `onFilesDropped`, `reason` (blocks every send path and fills the Notice), `loading`, `accept`, `labels`
+
+**Sub-components:** `Composer.Header`, `Composer.Attachments`, `Composer.Textarea` (`onEnterSubmit`, `maxRows`), `Composer.Footer` (`start`, `end`), `Composer.Attach` (`onSelect`, `multiple`), `Composer.Send`, `Composer.Notice` (`intent` [neutral|danger])
+
+Enter submits (Shift+Enter is a newline) except while `reason` or `loading` holds the send. Render `Composer.Notice` unconditionally so a later reason announces. `useStagedFiles({ maxFiles })` returns `{ files, stage, remove, clear }`.
+
+```tsx
+<Composer onSubmit={send} onFilesDropped={stage} reason={closed ? "The window is closed." : undefined}>
+  <Composer.Attachments>{files.map(renderChip)}</Composer.Attachments>
+  <Composer.Textarea value={draft} onValueChange={setDraft} />
+  <Composer.Footer start={<Composer.Attach onSelect={stage} />} end={<Composer.Send disabled={!draft.trim()} />} />
+  <Composer.Notice />
+</Composer>
+```
+
+### MicInput
+
+Microphone toggle with a live level meter, as a latch over the caller's engine or over a built-in recorder (`@nurix/components/compound/mic-input`, plus `useMicInputState`, `useMicRecorder`; recorder mode needs the optional peer `react-voice-visualizer`).
+
+**Props:** `pressed`, `onPressedChange`, `onValueCommitted` (latch mode) or `recorder` (from `useMicRecorder()`), `status` [idle|listening|processing|error], `waveform` [true|false|"always"], `onError`, `labels`
+
+**Sub-components:** `MicInput.Trigger` (`size` [sm|default|lg]), `MicInput.Meter` (`variant` [static|history], `deviceId`)
+
+A denied microphone surfaces only through `onError` (meter) or `recorder.error`. A composer's voice button is a `Button` in `Composer.Footer`.
+
+```tsx
+<MicInput pressed={isRecording} onPressedChange={toggle} status={status}>
+  <MicInput.Meter variant="history" />
+  <MicInput.Trigger size="sm" />
+</MicInput>
+```
+
+### StreamingCursor
+
+The blinking caret at the tail of a live stream (`effect/streaming-cursor`); inline, `h-[1lh]`, `aria-hidden`, blink shipped in the library stylesheet. Change the element with `render` (no `as` or `asChild`). Before the first token, show `element/loader`; inside a code block, set `compound/code-block`'s `isStreaming` prop instead.
+
+```tsx
+<p>{streamedText}{isStreaming && <StreamingCursor className="ml-0.5" />}</p>
+```
+
+### Marker
+
+Muted full-width row for out-of-band thread content — a date divider or a system event (`element/marker`). It is not a notification badge; an unread dot on an avatar is `Avatar.Badge`.
+
+**Sub-components:** `Marker.Icon` (`aria-hidden` — put any meaning in the content text), `Marker.Content`; also `markerVariants`
+
+**Props:** `variant` [default|separator|border] (`separator` flanks centered content with hairlines; `border` underlines the row), `render` (non-interactive elements only — an action goes inside `Marker.Content` as a `Link` or `Button`)
+
+```tsx
+<Marker variant="separator">
+  <Marker.Content>Today</Marker.Content>
+</Marker>
+```
 
-- `message` — docs-style message rows: `MessageGroup`, `Message`, `MessageAvatar`, `MessageHeader`, `MessageContent`, `MessageFooter`, `MessageStatus` (`status` [sending|sent|failed…] with icon + `data-status`)
-- `message-scroller` — pinned-to-bottom scroll container for feeds: `MessageScrollerProvider`, `MessageScroller`, `MessageScrollerViewport`, `MessageScrollerContent`, `MessageScrollerItem`, `MessageScrollerButton` (jump-to-latest); hooks `useMessageScroller`, `useMessageScrollerScrollable`, `useMessageScrollerVisibility`
-- `bubble` — chat-bubble rows: `BubbleGroup`, `Bubble`, `BubbleContent`, `BubbleReactions`
-- `attachment` — file chips for composer/thread: `Attachment` (+ `AttachmentGroup`, `AttachmentMedia`, `AttachmentContent`, `AttachmentTitle`, `AttachmentDescription`, `AttachmentActions`, `AttachmentAction`, `AttachmentTrigger`); `size` [default|sm], dashed border in idle state, `data-[state=error]` styling
-- `marker` — inline annotation row in a stream: `Marker`, `MarkerIcon`, `MarkerContent`; `variant` [default|separator|border]
+## Fallback-only concepts
 
-## Other Collections
+No nurix primitive — build each from its plain-spec fallback in [index.md](index.md):
 
-- `activity-timeline` — `GanttChart`: D3-based activity timeline (`Task`, `TaskStatus`, `ViewMode`, `GanttChartProps` types; `DEFAULT_STATUS_COLORS`, `getTaskDuration` helpers)
-- `changes-list` — `ChangesList`: grouped change-history feed (`ChangeItem`, `EntityConfig`, `OperationConfig`, `GroupBy` types)
-- `header` — `Header`: config-driven page header taking a single `config: HeaderConfig` (breadcrumbs, profile, status bar, grid, actions sections); sub-components `HeaderBreadcrumbs`, `HeaderActions`, `HeaderSection`, `HeaderCell`
-- `list` — `List`: data list with `ListToolbar`, `ListPagination`, `ListItemErrorBoundary`
-- `ui-table` — `UiTable`, `UiTableHeader`, `UiTableBody`, `UiTableFooter`, `UiTableHead`, `UiTableRow`, `UiTableCell`, `UiTableCaption`: bare HTML-table primitives; prefer `Table`
+- `gantt-timeline`
+- `chat-bubble`
+- `json-viewer`
+- `virtualized-list`
+- `kanban-board`
+- `event-calendar`
+- `filter-toolbar`
+- `vertical-timeline`

package/data/harnesses/code/skills/design/components/feedback.md

@@ -2,46 +2,107 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-## EmptyState
+Components: Alert, Empty, ErrorBoundary, ErrorState, IssueReporter, Loader, NotificationBadge, Progress, Skeleton, SystemBanner, Toaster + toast
 
-Placeholder for empty content areas.
+Each imports from its own subpath; a compound is one namespace with its parts as dotted members, e.g. `import { Empty } from "@nurix/components/compound/empty-state"` then `Empty.Header`, `Empty.Title`. Status colour is always `intent` (`neutral` | `info` | `success` | `warning` | `danger`, on the `--intent-*` tokens); a `danger` notice is `role="alert"`, every other intent `role="status"`, and a `role` you pass wins.
 
-**Props:** `icon`, `title`, `description`, `action`
+## Empty
+
+Placeholder for an empty table body, panel, card or page (`compound/empty-state`).
+
+**Sub-components:** `Empty.Header`, `Empty.Media` (`variant` [default|icon]), `Empty.Title`, `Empty.Description`, `Empty.Content`
+
+- The root is unframed and fills a flex parent (`flex-1`); add `border` for the dashed frame, and a `min-h-*` or `h-full` inside a block-flow parent.
+- `variant="icon"` draws the muted `size-10` tile, sizes an unsized `svg` to `size-6`, and is `aria-hidden`; the bare default stays exposed so an illustration `img` keeps its `alt`.
+- Every part takes `render`; a root given a `role` is labelled by its Title. A 404 page is this composition — `min-h-[60vh]`, `<Empty.Title render={<h1 />}>`, a way back in `Empty.Content`; there is no `NotFound` export.
+- Not for data in flight (`Skeleton`, `Loader`) or a failed load (`ErrorState`); `block/list` renders its own through its `emptyState` prop.
 
 ```tsx
-<EmptyState
-  icon={<InboxIcon className="h-12 w-12 text-muted-foreground" />}
-  title="No messages"
-  description="Start a conversation to see messages here"
-  action={<Button>New Message</Button>}
-/>
+<Empty className="border">
+  <Empty.Header>
+    <Empty.Media variant="icon"><Inbox /></Empty.Media>
+    <Empty.Title>No messages</Empty.Title>
+    <Empty.Description>Start a conversation to see messages here.</Empty.Description>
+  </Empty.Header>
+  <Empty.Content><Button>New message</Button></Empty.Content>
+</Empty>
 ```
 
 ## Alert
 
-Dismissible status block; `Alert` is the container, `AlertTitle`/`AlertDescription` lay out the icon-led grid.
+Inline notice that stays on the page until the user acts or navigates away (`compound/alert`).
 
-**Props:** `variant` [default|destructive], `dismissible`, `onDismiss`, `dismissButton` (custom node, overrides the default X button)
+**Props:** `intent` [neutral|info|success|warning|danger] (default `neutral`, the card surface), `icon` (replaces the intent's glyph; `null` draws none), `onDismiss`, `labels` (`dismiss`), `render`
+**Sub-components:** `Alert.Title`, `Alert.Description`
+
+- Each status intent draws its own glyph; `neutral` draws none. Never place an `<svg>` child for the icon — pass `icon`.
+- `onDismiss` draws the X in its own trailing column and never hides the alert — visibility stays in the parent (`{isVisible && <Alert … />}`).
+- `<Alert.Title render={<h3 />}>` makes the title a real heading. A message that should clear itself is a toast.
 
 ```tsx
-<Alert variant="destructive" dismissible onDismiss={handleDismiss}>
-  <TriangleAlert />
-  <AlertTitle>Sync failed</AlertTitle>
-  <AlertDescription>Retry in a few minutes.</AlertDescription>
+<Alert intent="danger" onDismiss={() => setIsVisible(false)}>
+  <Alert.Title>Sync failed</Alert.Title>
+  <Alert.Description>Retry in a few minutes.</Alert.Description>
 </Alert>
 ```
 
-## Other Components
+## Toaster + toast
+
+Self-clearing notifications on Base UI Toast (`compound/toast`): mount `<Toaster />` once at the app root, call `toast()` from anywhere, inside or outside React.
+
+**`toast` options:** `title`, `description`, `intent` (the only colour route, draws the glyph), `icon` (`null` draws none), `timeout` (ms; defaults to the dwell token, `Infinity` holds), `priority` [high|low] (default assertive for `danger`, polite otherwise), `action` (`{ label, onClick }`), `onDismiss`, `id` (reusing one updates in place)
+**Methods:** `toast.promise(work, { pending, success, error })` (`error` always takes `danger`; a phase may be a function of the result), `toast.update(id, options)` (changes only the named fields), `toast.close(id?)`
+**Toaster props:** `side` [top|bottom] (default `bottom`), `align` [start|center|end] (default `end`, logical), `hasCloseButton` (default `true`), `labels` (`region`, `dismiss`); parts `Toaster.Root`, `.Content`, `.Title`, `.Description`, `.Action`, `.Close`
+
+- There are no `toast.success` / `toast.error` shortcuts — pass `intent`. Never mount a second `Toaster`: every one renders the same queue.
+
+```tsx
+toast({ title: "Saved", description: "Your changes are live.", intent: "success" });
+toast.promise(save(), { pending: "Saving…", success: "Saved", error: "Save failed" });
+```
+
+## SystemBanner
 
-- `loader` — `Loader`: five-dot pulse indicator; `size`, `gap`, `colors` (array, cycles if fewer than `numberOfDots`), `numberOfDots`, `height`
-- `progress` — `Progress`: Radix `Progress.Root`/`Indicator` pair; `value` (0–100)
-- `skeleton` — `Skeleton`: pulsing placeholder `div`; size it with `className` to match the final layout
-- `typing-indicator` — `TypingIndicator`: `users` (`string[]` or `{ id, name, avatar }[]`), `maxVisible` — stacked avatars plus "X and N others are typing…"
-- `error-boundary` — `ErrorBoundary`: class component catching render errors; `fallback`, `onError`, `onRetry` (default UI renders a retry link)
-- `not-found` — `NotFound`: built on `EmptyState`; `title`, `description`, `showHomeButton`, `onGoBack`
-- `sonner` — `Toaster`: theme-synced wrapper over `sonner`'s `Toaster`, watches `document.documentElement`'s `dark` class via a `MutationObserver`
-- `braille` — `Braille`: animated unicode-braille spinner; `spinner` (18 named patterns — `braille`, `braillewave`, `dna`, `scan`, `rain`, `scanline`, `pulse`, `snake`, `sparkle`, `cascade`, `columns`, `orbit`, `breathe`, `waverows`, `checkerboard`, `helix`, `fillsweep`, `diagswipe`), `interval` (ms, overrides the spinner's default), `label` (screen-reader text). The `inline-spinner` subpath exports the underlying frame registry and grid utilities: `spinners`, `gridToBraille`, `makeGrid`.
+Shell-chrome banner above the app for environment, impersonation or outage states (`element/system-banner`); also exports `systemBannerVariants`.
+
+**Props:** `title` (required), `description`, `intent` [neutral|info|success|warning|danger] (default `neutral`), `icon`, `action`, `onDismiss`, `labels` (`dismiss`, `actions`)
+**Sub-components:** `SystemBanner.Stack` (orders and divides banners; placing it is yours)
+
+- The banner stores no visibility: `onDismiss` renders the dismiss button and your callback unmounts it; omit it for a banner that must not be dismissed.
+- `description` wraps on a narrow viewport. A message in content flow is `Alert`.
 
 ```tsx
-<Braille spinner="dna" label="Loading" />
+<SystemBanner.Stack>
+  <SystemBanner intent="warning" title="Sandbox environment" description="Data resets nightly" />
+  <SystemBanner title="Viewing as Dana" action={<Button size="sm">Exit view-as</Button>} />
+</SystemBanner.Stack>
 ```
+
+## IssueReporter
+
+Report-a-problem dialog with screenshot capture and an environment snapshot (`block/issue-reporter`). Requires the optional peer `html2canvas-pro` — without it the DOM raster fails on every capture and each one falls back to a `getDisplayMedia` permission prompt.
+
+**Props:** `onSubmit(report)` (required; a rejection keeps the dialog open, a resolution closes and resets), `open` / `defaultOpen` / `onOpenChange`, `shortcut` (e.g. `"mod+shift+i"`; default `null`), `shouldCaptureOnOpen` (default `true`), `fields` (default one `textarea` named `text`; types text|textarea|number|select|radio|checkbox), `defaultValue`, `metadata` (value or function, resolved at submit), `maxScreenshots` (default 3), `diagnosticsSections` (default all; `[]` turns collection off), `renderDiagnostics`, `captureOptions` (`ignoreElement`, `maxWidth`, `imageType`…), `onCaptureError`, `labels`
+**Also exports:** `useScreenCapture(options)` → `[state, actions]`, `useDiagnostics({ sections, collectOnMount })` → `{ data, isLoading, error, refresh }`, `DIAGNOSTICS_SECTIONS` (`system`, `capabilities`, `webVitals`, `storage`, `serviceWorkers`), `CaptureError`
+
+- `IssueReport` carries `fields`, `screenshots`, `diagnostics`, `metadata`. Submit stays disabled until every `required` field is set **and** a field holds a value or a screenshot is attached.
+- A report needing no screenshot or diagnostics is a plain form over `compound/dialog`, not this.
+
+```tsx
+<IssueReporter
+  shortcut="mod+shift+i"
+  fields={[{ name: "text", type: "textarea", label: "What went wrong?", required: true }]}
+  metadata={() => ({ route: location.pathname })}
+  onSubmit={async (report) => sendToTracker(report)}
+/>
+```
+
+## Other Components
+
+- `loader` — `Loader` (`element/loader`): em-sized lattice in `currentColor` for open-ended work; `status` [pending|success|error] (default `pending`) settles the same glyph into a check or a cross, `label`, `successLabel`, `errorLabel`, `hasTimer`, `labels`. A "Thinking…" or typing row is `<Loader label="Typing" />` — there is no dots variant.
+- `progress` — `Progress` (`element/progress`): `value` (0–100, clamped; `null` is indeterminate), `label` (the accessible name), `variant` [linear|circular|fill] (default `linear`), `size` [sm|default|lg] (not on `fill`), `format` / `getAriaValueText` to reword the announcement.
+- `skeleton` — `Skeleton` (`element/skeleton`): pulsing `aria-hidden` `div` with no intrinsic size — size it with `className`, mark the container `aria-busy`, and pass `render={<span />}` inside phrasing content.
+- `notification-badge` — `NotificationBadge` (`element/notification-badge`): `value` (pass the real count; renders nothing at zero), `max` (default 99, shows `99+`), `variant` [count|dot], `intent`, `labels` (`dot`); em-sized from the text beside it, positioned by you on a `relative` trigger.
+- `error-state` — `ErrorState` (`compound/error-state`): failed-load block on Empty's geometry; `description` (required), `title`, `icon`, `onRetry` (renders Retry), `labels` (`retry`). Carries no live role; `block/list`, `block/table` and `block/tree` take `error={{ message, onRetry }}` instead.
+- `error-boundary` — `ErrorBoundary` (`lib/error-boundary`): catches render errors in the subtree it wraps; `onError` (its only way out — it logs nothing), `onRetry` (refetch here, or the subtree throws again), `fallback` (replaces the whole card, retry included).
+- No nurix primitive: `text-spinner` — build from the `index.md` fallback spec.