<!-- source-hash: 08cea50ef9b44d5ac821b066fa03a785 -->
Defines all message-related TypeScript types, interfaces, and constants used across the Flamingo chat system — covering message lifecycle events, tool execution, approval flows, and rendered content segments.

## Key Components

### Constants
- **`MESSAGE_TYPE`** — Enum-like const object for all message event types (e.g. `TEXT`, `THINKING`, `EXECUTING_TOOL`, `APPROVAL_REQUEST`, `ERROR`, `CONTEXT_COMPACTION_*`, etc.)
- **`SCROLL_ANCHOR`** — Viewport positioning hint (`top` | `bottom`) controlling chat scroll behavior per message

### Tool Execution
- **`ToolExecutionData`** — Payload for `EXECUTING_TOOL` / `EXECUTED_TOOL` events, including tool identity, parameters, and optional merge ID
- **`ExecutingToolState`** — In-flight snapshot held between execution events to preserve `toolTitle` across merge

### Approval Flow
- **`ApprovalRequestData`** / **`ApprovalResultData`** — Single-tool approval request/result payloads
- **`ApprovalBatchData`** / **`PendingToolCallData`** / **`ApprovalBatchExecutionState`** — Batch approval structures for multi-tool proposals with per-tool execution tracking

### Message Segments (UI Rendering)
- **`MessageSegment`** — Union of `TextSegment`, `ThinkingSegment`, `ToolExecutionSegment`, `ApprovalRequestSegment`, `ApprovalBatchSegment`, `ErrorSegment`, `ContextCompactionSegment`
- **`MessageContent`** — `string | MessageSegment[]`

### Wire / API Data Types
- **`MessageData`** — Discriminated union of all backend-sourced message data shapes (`TextMessageData`, `ExecutingToolMessageData`, `ApprovalRequestMessageData`, `AIMetadataMessageData`, etc.)
- **`TokenUsageData`** — Input/output/total/context token counts

### Core Message Interfaces
- **`Message`** — Primary chat message object with role, content, scroll anchor, `chatRefs` for entity cards, and `hidden` flag for synthetic continuation turns
- **`ProcessedMessage`** — Normalized display-ready message derived from raw history
- **`HistoricalMessage`** — Raw persisted message shape from GraphQL/API

## Usage Example

```typescript
import {
  MESSAGE_TYPE,
  SCROLL_ANCHOR,
  type Message,
  type MessageSegment,
  type ApprovalBatchData
} from './message.types'

// Build a message with mixed content segments
const segments: MessageSegment[] = [
  { type: 'text', text: 'Creating a ticket for you...' },
  {
    type: 'approval_batch',
    data: {
      approvalRequestId: 'req_123',
      approvalType: 'CLIENT',
      toolCalls: [
        {
          toolExecutionRequestId: 'exec_456',
          toolName: 'create_ticket',
          toolTitle: 'Create Support Ticket',
          requiresApproval: true,
          approvalType: 'CLIENT',
        }
      ]
    },
    status: 'PENDING',
    onApprove: async (id) => console.log('Approved:', id),
  }
]

const msg: Message = {
  id: 'msg_789',
  role: 'assistant',
  content: segments,
  scrollAnchor: SCROLL_ANCHOR.TOP,
  timestamp: new Date(),
}
```