<!-- source-hash: 5419513463f6ad2b09f3c013740a3568 -->
Shared TypeScript contract defining the unified state shape and supporting types that all chat transport hooks (SSE and NATS) must satisfy, enabling transport-agnostic consumption by UI components.

## Key Components

| Export | Kind | Description |
|--------|------|-------------|
| `StreamingPhase` | Type | `'idle' \| 'thinking' \| 'streaming'` — granular in-flight status for the streaming indicator UI |
| `UnifiedUsageBreakdown` | Interface | SSE-only per-turn LLM telemetry (Haiku pipeline costs + routed answer metadata); always `null` in Mingo/NATS mode |
| `UnifiedChatMessage` | Interface | Transport-agnostic message shape; SSE-only fields (`sources`, `chatRefs`) are optional, Mingo-safe |
| `UnifiedSendMessageOptions` | Interface | Options for `sendMessage` — `hidden` (suppress UI render) and `attachments` (SSE-only image uploads) |
| `UnifiedChatState` | Interface | The primary contract: full return shape every transport hook must implement, covering messages, actions, loading state, and SSE-only LLM metadata |

## Usage Example

```typescript
// Consumer component — works identically for SSE (Guide) or NATS (Mingo)
import type { UnifiedChatState, UnifiedSendMessageOptions } from './unified-chat-state.types'

function ChatShell({ chat }: { chat: UnifiedChatState }) {
  const { messages, isLoading, streamingPhase, sendMessage, stopMessage } = chat

  async function handleSubmit(text: string, attachments?: ChatAttachment[]) {
    const options: UnifiedSendMessageOptions = { attachments }
    await sendMessage(text, options)
  }

  return (
    <>
      {/* SSE-only metadata — safely null in Mingo mode */}
      {chat.currentModelLabel && <ModelDisplay label={chat.currentModelLabel} />}
      {streamingPhase === 'thinking' && <span>Thinking...</span>}
      {streamingPhase === 'streaming' && <span>Streaming...</span>}
      <MessageList messages={messages.filter(m => !m.hidden)} />
      <ChatInput onSubmit={handleSubmit} disabled={isLoading} onStop={stopMessage} />
    </>
  )
}
```

> **Transport isolation:** `currentProvider`, `currentModelLabel`, `currentUsageBreakdown`, and related token fields are `null` in Mingo/NATS mode. Always guard with a null check before rendering LLM metadata.