---

## ChatMessage
Renders one `ChatMessageData` — its ordered parts (markdown text via
StreamingMarkdown, reasoning, tool-call status lines, policy-checked attachment
chips) plus a citation footer, streaming placeholder, error/aborted Alert, a
hover-revealed copy/regenerate action bar and a timestamp. `layout="bubble"`
(default) tints and aligns per role; `layout="plain"` is a document-like
full-width Claude-style column. Untrusted URLs never render as inline media —
only as `urlPolicy`-checked download links. Compose many of these under
ChatMessageList; the consumer owns the `ChatMessageData[]`.

**Import:** `import { ChatMessage } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ChatMessage message={msg} onRegenerate={() => regenerate(msg.id)} />
```

### Variants
- density: comfortable, compact (default: comfortable)
- layout: bubble, plain (default: bubble)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| message | `ChatMessageData` | yes |  | The message to render. The component never mutates it. |
| ...ChatMessageVariants | `VariantProps` | no |  | Styling variants from ChatMessageVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| abortedLabel | `string` | no | 'Generation stopped' | Alert title for `status === 'aborted'`. |
| actions | `Snippet<[{ message: ChatMessageData }]>` | no |  | Action-bar override. Receives the message; default is copy (+ regenerate when `onRegenerate` is set). |
| avatar | `Snippet<[{ role: ChatRole }]>` | no |  | Avatar override. Receives the message role; default is the Avatar primitive with a role icon. |
| class | `string` | no |  | Extra classes merged onto the root element. |
| copiedLabel | `string` | no | 'Copied' | Accessible label shown briefly after a successful copy. |
| copyLabel | `string` | no | 'Copy message' | Accessible label / tooltip for the copy action. |
| errorLabel | `string` | no | 'Something went wrong' | Alert title for `status === 'error'`. |
| metadata | `Snippet<[{ message: ChatMessageData }]>` | no |  | Metadata override. Receives the message; default is `createdAt` as a `<time>` element. |
| onRegenerate | `() => void` | no |  | Provide to render a "Regenerate" action. Called on click. |
| onRetry | `() => void` | no |  | Provide to render a "Retry" button in the error/aborted Alert. Called on click. |
| partRenderers | `ChatPartRenderers` | no |  | Per-part-type render overrides (see `ChatPartRenderers`). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ChatMessage: {...} }}>`. Prefer this over `class` overrides for reusable custom looks. |
| regenerateLabel | `string` | no | 'Regenerate' | Accessible label / tooltip for the regenerate action. |
| retryLabel | `string` | no | 'Retry' | Label for the retry button in the error/aborted Alert. |
| roleLabels | `Partial<Record<ChatRole, string>>` | no |  | Display names per role, shown in the `plain`-layout header. |
| slotClasses | `Partial<Record<ChatMessageSlots, string>>` | no |  | Per-slot class overrides. Slots: root | container | header | roleName | avatar | bubble | partsFlow | attachment | attachmentIcon | attachmentName | attachmentSize | sourcesFooter | placeholder | statusAlert | footer | actions | actionButton | metadata. Reasoning and tool-call parts render through ReasoningDisclosure / ToolCallCard, which take their own `slotClasses`. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| urlPolicy | `MarkdownUrlPolicy` | no |  | URL policy applied to attachment links and forwarded to StreamingMarkdown / CitationChip. Strict by default (untrusted LLM/server output). Keep it referentially stable to avoid re-parsing streamed markdown. |
| density | `'comfortable' | 'compact'` | no | comfortable | Controls the density behavior and appearance of the ChatMessage component. Available options: comfortable, compact. |
| layout | `'bubble' | 'plain'` | no | bubble | Controls the layout behavior and appearance of the ChatMessage component. Available options: bubble, plain. |

Inherited from:
- Omit<ChatMessageVariants, 'role'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Types
```ts
type ChatPartRenderers = {
  [K in Exclude<ChatMessagePart['type'], 'source'>]?: Snippet<
    [Extract<ChatMessagePart, { type: K }>]
  >;
}
```

```ts
interface ChatMessageData {
/** Stable unique id — keyed `{#each}` identity, never an array index. */
  id: string;
  role: ChatRole;
  /** Ordered renderable segments. A plain text answer is `[{ type: 'text', text }]`. */
  parts: ChatMessagePart[];
  createdAt?: Date;
  /** Omitted counts as `complete`. */
  status?: ChatMessageStatus;
  /** Consumer-defined extras (model name, token counts, …). Not rendered by defaults. */
  metadata?: Record<string, unknown>;
}
```

```ts
type ChatMessagePart = | { type: 'text'; text: string }
  /** Model reasoning. Collapsed, tertiary presentation; `durationMs` feeds the "Thought for Xs" label. */
  | { type: 'reasoning'; text: string; durationMs?: number }
  /** A tool invocation with its lifecycle state. Rendered as a ToolCallCard by default; override via `partRenderers`. */
  | {
      type: 'tool-call';
      id: string;
      name: string;
      state: 'pending' | 'running' | 'complete' | 'error';
      input?: unknown;
      output?: unknown;
      errorMessage?: string;
    }
  /** A cited source. Same shape as CitationSource — also feeds StreamingMarkdown's `sources` for `[id]` markers. */
  | ({ type: 'source' } & CitationSource)
  /**
   * A file attached to the message. `url` is only ever rendered as a
   * policy-checked download link (never as an inline image/iframe) — LLM- or
   * server-supplied URLs are untrusted input.
   */
  | { type: 'attachment'; name: string; mimeType: string; size?: number; url?: string }
  /** Declarative A2UI payload (P4). Validated fail-loud by A2UIView; ignored by default renderers until then. */
  | { type: 'a2ui'; payload: unknown }
```

```ts
type ChatRole = 'user' | 'assistant' | 'system'
```

```ts
interface MarkdownUrlPolicy {
/**
   * Allowed link protocols (with trailing colon). Relative URLs are always
   * allowed for links. @default ['http:', 'https:', 'mailto:', 'tel:']
   */
  allowedLinkProtocols?: string[];
  /**
   * Prefix allowlist for image sources, matched against the normalized
   * absolute URL. Empty (the default) blocks every external image; relative
   * sources are allowed. Prefer deep, specific prefixes — broad ones are
   * open-redirect bait. `data:` images are blocked unless a `data:` prefix
   * is listed explicitly.
   * @default []
   */
  allowedImagePrefixes?: string[];
  /** Observability hook — fires once per blocked URL occurrence. */
  onBlocked?: (kind: 'link' | 'image', url: string) => void;
}
```

```ts
type ChatMessageStatus = 'streaming' | 'complete' | 'error' | 'aborted'
```

```ts
interface CitationSource {
/** Stable id — matches the `[id]` marker in the streamed markdown. */
  id: string;
  /** Human-readable source title, always shown in the popover (and as the chip label under `citationStyle="label"`). */
  title: string;
  /** Source URL. Rendered as an outbound link only when it passes the `urlPolicy`; a blocked or absent URL shows title/snippet with no link. */
  url?: string;
  /** Short excerpt shown under the title, clamped to ~3 lines. */
  snippet?: string;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`root`, `container`, `header`, `roleName`, `avatar`, `bubble`, `partsFlow`, `attachment`, `attachmentIcon`, `attachmentName`, `attachmentSize`, `sourcesFooter`, `placeholder`, `statusAlert`, `footer`, `actions`, `actionButton`, `metadata`