@assistant-ui/mcp-docs-server 0.1.30 → 0.1.32

package/.docs/raw/docs/ink/primitives.mdx

@@ -159,6 +159,69 @@ Renders a suggestion button. Uses Ink `Box` + `Text`.
 | `send` | `boolean` | When true, automatically sends the message |
 | `clearComposer` | `boolean` | When true (default), replaces composer text; when false, appends |
 
+## Loading
+
+```tsx
+import { LoadingPrimitive } from "@assistant-ui/react-ink";
+```
+
+Composable loading UI for active runs. `LoadingPrimitive.Root` only renders
+while the current thread is running, so it pairs naturally with status rows in
+terminal chat layouts.
+
+```tsx
+<LoadingPrimitive.Root gap={1}>
+  <LoadingPrimitive.Spinner variant="bar" />
+  <LoadingPrimitive.Text>Analyzing codebase...</LoadingPrimitive.Text>
+  <LoadingPrimitive.ElapsedTime />
+</LoadingPrimitive.Root>
+```
+
+This renders a compact status line such as `[=== ] Analyzing codebase... (3s)`
+while the assistant is streaming.
+
+### Root
+
+Runtime-aware `Box` container that renders children only while
+`s.thread.isRunning` is true.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Status row content |
+| `...rest` | `BoxProps` | Standard Ink Box props |
+
+### Spinner
+
+Animated loader indicator. Supports the existing `ink-spinner` path plus a few
+built-in text-based variants for more terminal-native styles.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `variant` | `"spinner" \| "dots" \| "pulse" \| "bar" \| "bounce"` | Loader style (default: `"spinner"`) |
+| `type` | `ink-spinner` type | Spinner preset used when `variant="spinner"` |
+| `intervalMs` | `number` | Animation speed for non-spinner variants (default: `120`) |
+| `...rest` | `TextProps` | Standard Ink Text props |
+
+### Text
+
+Status label rendered as Ink `Text`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Message text (default: `"Thinking..."`) |
+| `...rest` | `TextProps` | Standard Ink Text props |
+
+### ElapsedTime
+
+Elapsed time indicator for the current run. Uses message timing metadata when
+available and falls back to a local timer so it still works during manual
+testing.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `format` | `(seconds: number) => string` | Custom formatter for the elapsed time label |
+| `...rest` | `TextProps` | Standard Ink Text props |
+
 ## Composer
 
 ```tsx
@@ -177,11 +240,12 @@ Container `Box` for the composer area.
 
 ### Input
 
-Ink `TextInput` wired to the composer runtime. Value is managed automatically.
+Terminal line editor wired to the composer runtime. Value is managed automatically and supports cursor-aware editing.
 
 ```tsx
 <ComposerPrimitive.Input
   submitOnEnter
+  multiLine
   placeholder="Type a message..."
   autoFocus
 />
@@ -192,6 +256,41 @@ Ink `TextInput` wired to the composer runtime. Value is managed automatically.
 | `submitOnEnter` | `boolean` | Whether Enter sends the message (default: `false`) |
 | `placeholder` | `string` | Placeholder text when empty |
 | `autoFocus` | `boolean` | Auto-focus on mount |
+| `multiLine` | `boolean` | When true, Enter inserts a newline unless `submitOnEnter` is enabled |
+| `onSubmit` | `(text: string) => void` | Overrides the default send behavior and receives the current composer text |
+
+Supported keyboard bindings:
+
+| Key | Action | Context |
+|-----|--------|---------|
+| `Left` / `Right` | Move cursor by one grapheme | Always |
+| `Backspace` / `Delete` | Remove the grapheme before / after the cursor | Always |
+| `Home` / `End` | Jump to buffer or line boundary | Buffer in single-line, line in multi-line |
+| `Up` / `Down` | Move between lines, preserving column when possible | Multi-line only |
+| `Ctrl+A` / `Ctrl+E` | Move to line start / end | Always |
+| `Ctrl+W` | Kill the word before the cursor | Always |
+| `Ctrl+D` | Delete the grapheme after the cursor | Always |
+| `Ctrl+U` / `Ctrl+K` | Kill from cursor to line start / end; in multi-line, `Ctrl+K` at end-of-line joins the next line | Always |
+| `Ctrl+J` | Insert a newline | Multi-line only; swallowed in single-line so it never submits |
+| `Alt+B` / `Alt+F` | Move by word backward / forward | Terminals that emit meta-key sequences |
+| `Alt+D` | Kill the word after the cursor | Terminals that emit meta-key sequences |
+| `Shift+Enter` | Insert a newline | Multi-line submit mode, terminals that distinguish it |
+
+Word boundaries and grapheme stepping use `Intl.Segmenter`, so emoji, accented letters, skin-tone modifiers, ZWJ sequences, and CJK ideographs each move and delete as a single character.
+
+Some bindings depend on terminal capabilities. iTerm2, Windows Terminal, and most Linux terminals emit `Alt`-letter combinations as `Esc`-prefixed sequences that Ink decodes as meta-key input; macOS Terminal.app requires enabling "Use Option as Meta key" in its preferences before `Alt+B` / `Alt+F` / `Alt+D` work as expected. `Shift+Enter` requires a terminal that supports the CSI-u protocol (iTerm2 3.4+, kitty, foot, and similar) — terminals that conflate it with `Enter` will fall back to the `submitOnEnter` behaviour.
+
+Example with custom submit handling:
+
+```tsx
+<ComposerPrimitive.Input
+  multiLine
+  submitOnEnter
+  onSubmit={(text) => {
+    console.log("submit", text);
+  }}
+/>
+```
 
 ### Send
 
@@ -237,6 +336,80 @@ Triggers attachment addition.
 </ComposerPrimitive.AddAttachment>
 ```
 
+### Queue
+
+Renders all queued composer items. Each item is wrapped in a `QueueItemByIndexProvider`, so `QueueItemPrimitive.*` can read item state and call queue actions inside the render prop. Backed by the shared `ComposerPrimitiveQueue` from `@assistant-ui/core/react`.
+
+```tsx
+<ComposerPrimitive.Queue>
+  {({ queueItem }) => (
+    <Box>
+      <QueueItemPrimitive.Text />
+      <QueueItemPrimitive.Steer>
+        <Text color="cyan">[Run Now]</Text>
+      </QueueItemPrimitive.Steer>
+      <QueueItemPrimitive.Remove>
+        <Text color="red">[x]</Text>
+      </QueueItemPrimitive.Remove>
+    </Box>
+  )}
+</ComposerPrimitive.Queue>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `(value: { queueItem: QueueItemState }) => ReactNode` | Render function called for each queue item |
+
+### Quote
+
+Renders the active composer quote preview. Children are only rendered while `s.composer.quote` is set, so this acts as both a container and a gate.
+
+```tsx
+<ComposerPrimitive.Quote>
+  <Box>
+    <Text dimColor>Quoting:</Text>
+    <ComposerPrimitive.QuoteText color="gray" />
+    <ComposerPrimitive.QuoteDismiss>
+      <Text color="red">[x]</Text>
+    </ComposerPrimitive.QuoteDismiss>
+  </Box>
+</ComposerPrimitive.Quote>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Quote preview content; only rendered when a quote is set |
+| `...rest` | `BoxProps` | Standard Ink Box props |
+
+### QuoteText
+
+Renders the quoted text from `s.composer.quote?.text`. Pass `children` to override the displayed value.
+
+```tsx
+<ComposerPrimitive.QuoteText color="gray" />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Override content; defaults to `s.composer.quote?.text` |
+| `...rest` | `TextProps` | Standard Ink Text props |
+
+### QuoteDismiss
+
+Pressable that clears the active quote by calling `aui.composer().setQuote(undefined)`.
+
+```tsx
+<ComposerPrimitive.QuoteDismiss>
+  <Text color="red">[x]</Text>
+</ComposerPrimitive.QuoteDismiss>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Button content |
+| `disabled` | `boolean` | Disable Enter activation and focus |
+| `...rest` | `BoxProps` | Standard Ink Box props |
+
 ### Conditional Rendering (Composer)
 
 Use `AuiIf` for conditional rendering based on composer state:
@@ -287,7 +460,7 @@ Conditional rendering based on composer state. Shared from `@assistant-ui/core/r
 ## Message
 
 ```tsx
-import { MessagePrimitive } from "@assistant-ui/react-ink";
+import { MessagePartPrimitive, MessagePrimitive } from "@assistant-ui/react-ink";
 ```
 
 ### Root
@@ -302,7 +475,7 @@ Container `Box` for a single message.
 
 ### Parts
 
-Renders message content parts via a `components` prop. Tool call and data parts automatically render registered tool UIs (via `useAssistantTool` / `useAssistantDataUI`), falling back to components provided here. A default `Text` component using Ink's `<Text>` is provided out of the box.
+Renders message content parts via a `components` prop. Tool call and data parts automatically render registered tool UIs (via `useAssistantTool` / `useAssistantDataUI`), falling back to components provided here. Default terminal-safe renderers are provided for text, reasoning, source, image, file, and data parts.
 
 ```tsx
 <MessagePrimitive.Parts>
@@ -314,10 +487,26 @@ Renders message content parts via a `components` prop. Tool call and data parts
 </MessagePrimitive.Parts>
 ```
 
+Override part rendering with app-owned components when you need richer terminal UI:
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    Image: () => <Text color="cyan">image available</Text>,
+    Reasoning: () => null,
+    data: {
+      by_name: {
+        weather_card: ({ data }) => <Text>{data.city}: {data.temperature}</Text>,
+      },
+    },
+  }}
+/>
+```
+
 ### Content (deprecated)
 
 <Callout type="warn">
-  Deprecated. Use `MessagePrimitive.Parts` instead. See the [v0.11 migration guide](/docs/reference/migrations/v0-11) for details.
+  Deprecated. Use `MessagePrimitive.Parts` instead. See the [v0.11 migration guide](/docs/migrations/v0-11) for details.
 </Callout>
 
 Renders message content parts using render props. Tool call and data parts automatically render registered tool UIs (via `useAssistantTool` / `useAssistantDataUI`), falling back to render props if provided.
@@ -339,6 +528,36 @@ Renders message content parts using render props. Tool call and data parts autom
 | `renderFile` | `(props: { part; index }) => ReactElement` | File part renderer |
 | `renderData` | `(props: { part; index }) => ReactElement` | Data part fallback |
 
+## MessagePartPrimitive
+
+Composable primitives for rendering the current message part inside part context from `MessagePrimitive.Parts`, `MessagePrimitive.PartByIndex`, or `PartByIndexProvider`.
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    Text: () => (
+      <>
+        <MessagePartPrimitive.Text />
+        <MessagePartPrimitive.InProgress>
+          <Text color="yellow"> ...</Text>
+        </MessagePartPrimitive.InProgress>
+      </>
+    ),
+    File: () => <MessagePartPrimitive.File dimColor />,
+  }}
+/>
+```
+
+| Primitive | Default terminal behavior |
+|-----------|---------------------------|
+| `MessagePartPrimitive.Text` | Renders text with Ink `<Text>` |
+| `MessagePartPrimitive.InProgress` | Renders children only while the current part status is `running` |
+| `MessagePartPrimitive.Image` | Renders `[image: filename]` or `[image]`; never emits image data or terminal image protocols |
+| `MessagePartPrimitive.File` | Renders `[file: filename mimeType]` or `[file: mimeType]`; never prints file data |
+| `MessagePartPrimitive.Source` | Renders source title and/or URL metadata |
+| `MessagePartPrimitive.Reasoning` | Renders conservative reasoning text by default; override or return `null` to suppress |
+| `MessagePartPrimitive.Data` | Renders `[data: name]` when no registered data renderer is available |
+
 ### PartByIndex
 
 Low-level provider that sets up the part context for a specific message part by index. Used internally by `MessagePrimitive.Parts`.
@@ -426,34 +645,118 @@ Renders user message attachments using the provided component configuration.
 import { AttachmentPrimitive } from "@assistant-ui/react-ink";
 ```
 
-Primitives for rendering individual attachments.
+Primitives for rendering individual attachments. Each primitive reads from the current attachment context (provided by `ComposerPrimitive.Attachments`, `ComposerPrimitive.AttachmentByIndex`, `MessagePrimitive.Attachments`, or `MessagePrimitive.AttachmentByIndex`).
 
 ### Root
 
-Container `Box` for an attachment.
+Container `Box` for an attachment. Forwards all `Box` props.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Attachment sub-components |
+| `...rest` | `ComponentProps<typeof Box>` | Forwarded to the underlying Ink `Box` |
 
 ### Name
 
-`Text` component displaying the attachment filename.
+`Text` component displaying `s.attachment.name`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `...rest` | `ComponentProps<typeof Text>` | Forwarded to the underlying Ink `Text` |
 
 ### Thumb
 
-`Text` component displaying the file extension.
+`Text` component displaying a short identifier for the attachment. Renders the file extension (`.pdf`, `.png`, …) when the name has one. Falls back to the attachment `type` (e.g. `image`, `document`) otherwise, and finally to `file`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `...rest` | `ComponentProps<typeof Text>` | Forwarded to the underlying Ink `Text` |
+
+### Status
+
+`Text` component rendering the current attachment status from `s.attachment.status`. Uses the same visual vocabulary as `ToolFallback`: spinner = uploading, `?` = pending action, `x` = error, `||` = paused. By default, completed attachments render nothing.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `showComplete` | `boolean` | When `true`, completed attachments render `+ ready` instead of `null` |
+| `...rest` | `Omit<ComponentProps<typeof Text>, "children">` | Forwarded to the underlying Ink `Text`. Caller-supplied `color` overrides the per-status default. `children` is not accepted; `Status` always renders its own content. |
 
 ### Remove
 
-Pressable that removes the attachment from the composer.
+`Pressable` that calls `aui.attachment().remove()` when activated (Enter while focused). Disabled when not focused or when the `disabled` prop is set.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Visual content for the button |
+| `disabled` | `boolean` | Skip focus registration and ignore Enter |
+| `...rest` | `ComponentProps<typeof Box>` | Forwarded to the underlying Pressable's `Box` |
 
 ```tsx
 <AttachmentPrimitive.Root>
   <AttachmentPrimitive.Thumb />
   <AttachmentPrimitive.Name />
+  <AttachmentPrimitive.Status />
   <AttachmentPrimitive.Remove>
     <Text color="red">[x]</Text>
   </AttachmentPrimitive.Remove>
 </AttachmentPrimitive.Root>
 ```
 
+## QueueItem
+
+```tsx
+import { QueueItemPrimitive } from "@assistant-ui/react-ink";
+```
+
+Primitives for rendering individual queued composer items. Use inside a `ComposerPrimitive.Queue` render prop, where the queue item context is set up by `QueueItemByIndexProvider`.
+
+### Text
+
+Renders the queue item's prompt with Ink `<Text>`. Pass `children` to override the displayed value.
+
+```tsx
+<QueueItemPrimitive.Text color="gray" />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Override content; defaults to `s.queueItem.prompt` |
+| `...rest` | `TextProps` | Standard Ink Text props |
+
+### Remove
+
+Pressable that removes the queue item by calling `aui.queueItem().remove()`.
+
+```tsx
+<QueueItemPrimitive.Remove>
+  <Text color="red">[x]</Text>
+</QueueItemPrimitive.Remove>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Button content |
+| `disabled` | `boolean` | Disable Enter activation and focus |
+
+Remaining props are forwarded to the underlying `Pressable` (Ink `Box` props).
+
+### Steer
+
+Pressable that promotes the queue item to run next by calling `aui.queueItem().steer()`.
+
+```tsx
+<QueueItemPrimitive.Steer>
+  <Text color="cyan">[Run Now]</Text>
+</QueueItemPrimitive.Steer>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Button content |
+| `disabled` | `boolean` | Disable Enter activation and focus |
+
+Remaining props are forwarded to the underlying `Pressable` (Ink `Box` props).
+
 ## ActionBar
 
 ```tsx
@@ -710,6 +1013,8 @@ Components for rendering code diffs in the terminal.
 
 Pre-composed component that combines all diff primitives for easy diff rendering. Accepts either a unified diff patch string or old/new file content for inline comparison.
 
+When a replacement is rendered as an equal-length adjacent `-`/`+` run, `DiffView` also highlights the changed word spans inside those lines. The existing prefixes, line numbers, folding, and primitive API surface stay the same. This intra-line behavior is internal to `DiffView`; `DiffPrimitive.Line` remains a line-level primitive.
+
 ```tsx
 // From a patch string
 <DiffView
@@ -838,3 +1143,75 @@ For custom layouts, use the primitives directly:
   </Box>
 </DiffPrimitive.Root>
 ```
+
+## StatusBar
+
+```tsx
+import { StatusBarPrimitive } from "@assistant-ui/react-ink";
+```
+
+Primitives for rendering a compact terminal status bar showing run state, model, message count, token usage, and latency. All sub-components read directly from the active thread state.
+
+### Root
+
+Container `Box` for the status bar. Forwards all `Box` props; pass `gap` to space its children.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Status bar sub-components |
+| `...rest` | `ComponentProps<typeof Box>` | Forwarded to the underlying Ink `Box` |
+
+### ModelName
+
+`Text` component displaying the current model name. The name is supplied as a prop — the primitive does not infer it from state.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `name` | `ReactNode` | Model label to render (default: `"unknown"`) |
+| `...rest` | `ComponentProps<typeof Text>` | Forwarded to the underlying Ink `Text` |
+
+### MessageCount
+
+`Text` component displaying the number of messages on the current thread, formatted as `N msgs` by default. Renders nothing when the thread is empty.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `format` | `(count: number) => string` | Custom formatter for the count (default: `` `${count} msgs` ``) |
+| `...rest` | `ComponentProps<typeof Text>` | Forwarded to the underlying Ink `Text` |
+
+### TokenCount
+
+`Text` component summing `metadata.timing.tokenCount` across all assistant messages on the thread, formatted with `toLocaleString()` + `" tokens"` by default. Renders nothing when the total is `0`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `format` | `(tokens: number) => string` | Custom formatter for the total (default: `` `${tokens.toLocaleString()} tokens` ``) |
+| `...rest` | `ComponentProps<typeof Text>` | Forwarded to the underlying Ink `Text` |
+
+### Latency
+
+`Text` component displaying `metadata.timing.tokensPerSecond` from the most recent assistant message, formatted as `N tok/s` (rounded) by default. Renders nothing when the field is missing.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `format` | `(tokensPerSecond: number) => string` | Custom formatter (default: `` `${Math.round(tokensPerSecond)} tok/s` ``) |
+| `...rest` | `ComponentProps<typeof Text>` | Forwarded to the underlying Ink `Text` |
+
+### Status
+
+`Text` component reporting the thread's run state. Resolves to `"running"` while `s.thread.isRunning`, otherwise inspects the most recent assistant message: `"error"` when its status is `incomplete` with reason `error`, `"cancelled"` when reason is `cancelled`, and `"idle"` for every other case. Pass `color` (or any `Text` prop) to style the label.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `format` | `(status: "idle" \| "running" \| "error" \| "cancelled") => string` | Custom label formatter (default: returns the state string verbatim) |
+| `...rest` | `ComponentProps<typeof Text>` | Forwarded to the underlying Ink `Text` |
+
+```tsx
+<StatusBarPrimitive.Root gap={1}>
+  <StatusBarPrimitive.Status />
+  <StatusBarPrimitive.ModelName name="gpt-5" />
+  <StatusBarPrimitive.MessageCount />
+  <StatusBarPrimitive.TokenCount />
+  <StatusBarPrimitive.Latency />
+</StatusBarPrimitive.Root>
+```