@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/chat/types/.index.md

@@ -1,29 +1,44 @@
-<!-- source-hash: 20e5ae4b1dc4695977d9dc1f7ed04663 -->
-Central barrel export file that re-exports all TypeScript types and interfaces from the chat module's type definitions.
+<!-- source-hash: 75c4ecf369e61a07b6662d1777b9777b -->
+Central barrel export file that re-exports all TypeScript type definitions for the OpenFrame chat system, providing a single import entry point for consumers.
 
 ## Key Components
 
-| Export Source | Description |
+All exports are sourced from the following modules:
+
+| Module | Description |
 |---|---|
-| `chat.types` | Core chat session and conversation types |
-| `message.types` | Message structure and content types |
-| `component.types` | UI component prop and state types |
+| `chat.types` | Core chat domain types |
+| `message.types` | Message structure and payload types |
+| `component.types` | UI component prop/state types |
 | `network.types` | Network request/response types |
-| `processing.types` | Message processing and transformation types |
-| `api.types` | API contract and endpoint types |
-| `entities` | Domain entity definitions |
-| `unified-chat-state.types` | Unified state management types for chat |
+| `processing.types` | Message processing pipeline types |
+| `api.types` | External API contract types |
+| `entities` | Shared domain entity definitions |
+| `context-item.types` | Context item types for AI/chat context |
+| `unified-chat-state.types` | Unified state management types |
 
 ## Usage Example
 
 ```typescript
-// Import any chat-related type directly from the module root
-import {
-  ChatSession,
-  Message,
+// Import any type directly from the package root — no need to reach into submodules
+import type {
+  ChatMessage,
+  NetworkRequest,
   UnifiedChatState,
-  ApiResponse
-} from '@/types/chat'
+  ContextItem,
+} from '@openframe/chat-types'
+```
+
+Instead of:
+
+```typescript
+// ❌ Avoid deep imports
+import type { ChatMessage } from '@openframe/chat-types/message.types'
+import type { UnifiedChatState } from '@openframe/chat-types/unified-chat-state.types'
 ```
 
-> All types are available from a single import path — no need to reference individual type files directly.
+## Notes
+
+- This file contains **no runtime logic** — it is purely a type re-export barrel.
+- Adding a new type module requires a corresponding `export *` line here to expose it to consumers.
+- See the [source file](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts) for the full export list.

package/src/components/chat/types/.message.types.md

@@ -1,32 +1,30 @@
-<!-- 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.
+<!-- source-hash: 91d6851796cacd6ea48ea0e1555aaf5a -->
+Defines all TypeScript types, interfaces, and constants for the chat message system, covering message lifecycle events, content structures, tool execution states, approval workflows, and historical/processed message representations.
 
 ## 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
+- **`MESSAGE_TYPE`** — Enum-style const object with 16 message types (`TEXT`, `THINKING`, `EXECUTING_TOOL`, `APPROVAL_REQUEST`, `CONTEXT_COMPACTION_START`, etc.)
+- **`SCROLL_ANCHOR`** — Per-message viewport hint (`top` | `bottom`) controlling chat scroll behavior on long assistant responses
 
 ### 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
+- **`ToolExecutionData`** — Wire payload for `EXECUTING_TOOL` / `EXECUTED_TOOL` events, including optional `toolExecutionRequestId` for merging into approval batches
+- **`ExecutingToolState`** — In-flight snapshot carried between executing/executed events to preserve `toolTitle` and `toolExplanation`
 
-### 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
+### Approval Workflow
+- **`ApprovalRequestData`** / **`ApprovalResultData`** — Single-command approval request/result payloads
+- **`PendingToolCallData`** — Individual tool call within a batch approval request
+- **`ApprovalBatchData`** — Batch of tool calls requiring approval, keyed by `toolExecutionRequestId`
+- **`ApprovalBatchExecutionState`** — Per-tool execution progress (`executing` | `done`) within a resolved batch
 
-### Message Segments (UI Rendering)
+### Message Segments
 - **`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
+### API Data Types
+- **`MessageData`** — Discriminated union of all wire-format message data types from GraphQL/API
+- **`HistoricalMessage`** — Persisted message row with `lastChunkStreamSeq` for realtime merge coverage
+- **`ProcessedMessage`** / **`Message`** — Normalized display-ready message with role, content, timestamps, and `streamSeq`
 
 ## Usage Example
 
@@ -34,39 +32,40 @@ Defines all message-related TypeScript types, interfaces, and constants used acr
 import {
   MESSAGE_TYPE,
   SCROLL_ANCHOR,
-  type Message,
+  type MessageData,
   type MessageSegment,
-  type ApprovalBatchData
+  type ApprovalBatchData,
+  type ProcessedMessage,
 } 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),
+// Check incoming message type
+function handleChunk(data: MessageData) {
+  if (data.type === MESSAGE_TYPE.EXECUTING_TOOL) {
+    console.log('Tool running:', data.toolFunction)
+  }
+  if (data.type === MESSAGE_TYPE.APPROVAL_REQUEST) {
+    console.log('Batch calls:', data.toolCalls?.length)
   }
-]
+}
 
-const msg: Message = {
-  id: 'msg_789',
+// Build a processed message for rendering
+const msg: ProcessedMessage = {
+  id: 'msg-1',
   role: 'assistant',
-  content: segments,
-  scrollAnchor: SCROLL_ANCHOR.TOP,
+  content: [
+    { type: 'text', text: 'Done! Here is the result.' },
+    { type: 'tool_execution', data: {
+        type: 'EXECUTED_TOOL',
+        integratedToolType: 'ticketing',
+        toolFunction: 'createTicket',
+        success: true,
+        result: '{"ticketId":"T-42"}',
+    }},
+  ],
   timestamp: new Date(),
+  streamSeq: 14,
 }
+
+// Scroll hint for long article responses
+const anchor = SCROLL_ANCHOR.TOP
 ```

package/src/components/chat/types/.network.types.md

@@ -1,63 +1,55 @@
-<!-- source-hash: 8a6f81705a1810d60982ff3e397e9ebc -->
-Defines TypeScript types and constants for all network and communication layers in the Flamingo platform, including NATS messaging, WebSocket connections, streaming chunk data, and API response shapes.
+<!-- source-hash: b3a25b6e2897d6d6248d3a4a28608f01 -->
+Defines TypeScript types and constants for network and communication infrastructure, covering NATS messaging, WebSocket connections, streaming chunk data, and generic API response shapes.
 
 ## Key Components
 
-### Types & Enums
+### Constants
+- **`NETWORK_CONFIG`** — Frozen configuration object with tunable network parameters (timeouts, retry backoff, message limits, ping intervals)
 
-| Export | Description |
-|--------|-------------|
-| `NatsMessageType` | Union type for NATS message categories: `'message'` or `'admin-message'` |
-| `NatsConnectionStatus` | Connection lifecycle states: `connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error` |
-| `NatsConnectionSource` | Origin of a NATS connection: `client`, `agent`, or `dashboard` |
+### NATS Types
+- **`NatsMessageType`** — Discriminates between `'message'` and `'admin-message'` NATS payloads
+- **`NatsConnectionStatus`** — Union of NATS lifecycle states (`connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error`)
+- **`NatsConnectionSource`** — Identifies the actor initiating a connection (`client`, `agent`, `dashboard`)
 
-### Constants
+### Chunk / Streaming Types
+- **`ChunkData`** — Core streaming payload; carries sequence IDs, stream state, tool execution metadata, approval workflow fields, and model/provider info. Supports an open index signature for extension
+- **`BufferedChunk`** — Wraps a `ChunkData` with its `NatsMessageType` for buffered delivery
 
-| Export | Description |
-|--------|-------------|
-| `NETWORK_CONFIG` | Frozen config object with timeouts, retry backoff, ping intervals, and message limits |
-| `NetworkConfig` | Inferred type from `NETWORK_CONFIG` |
+### WebSocket Types
+- **`WebSocketMessage`** — Generic typed message envelope with optional timestamp and ID
+- **`WebSocketConfig`** — Full WebSocket client configuration including reconnect strategy and lifecycle callbacks
 
-### Interfaces
+### Function Types
+- **`FetchChunksFunction`** — Typed async fetcher for polling `ChunkData[]` by dialog ID and chat type
 
-| Export | Description |
-|--------|-------------|
-| `ChunkData` | Streaming dialog chunk payload — carries sequence IDs, tool execution data, approval requests, model metadata, and stream state |
-| `BufferedChunk` | Wraps a `ChunkData` with its `NatsMessageType` for buffered delivery |
-| `WebSocketMessage` | Generic WebSocket envelope with `type`, `payload`, and optional metadata |
-| `WebSocketConfig` | Full WebSocket client configuration including reconnect strategy and event handlers |
-| `FetchChunksFunction` | Async function signature for polling dialog chunks by `dialogId` and `ChatType` |
-| `NetworkResponse<T>` | Standard API response wrapper with `success`, `data`, `error`, and `message` |
-| `PaginatedResponse<T>` | Extends `NetworkResponse<T>` with pagination metadata |
-| `NetworkError` | Structured error shape with `code`, `message`, optional `details`, and `timestamp` |
+### Response Types
+- **`NetworkResponse<T>`** — Generic success/error API envelope
+- **`PaginatedResponse<T>`** — Extends `NetworkResponse` with page, pageSize, totalCount, and totalPages
+- **`NetworkError`** — Structured error with code, message, optional details, and ISO timestamp
 
 ## Usage Example
 
 ```typescript
-import type {
-  ChunkData,
-  FetchChunksFunction,
-  NetworkResponse,
-  PaginatedResponse,
-  NatsConnectionStatus,
+import {
+  NETWORK_CONFIG,
+  type ChunkData,
+  type FetchChunksFunction,
+  type NetworkResponse,
+  type PaginatedResponse,
+  type NatsConnectionStatus,
 } from './network.types'
-import { NETWORK_CONFIG } from './network.types'
 
-// Use constants for consistent timeout configuration
-const client = createNatsClient({
-  timeout: NETWORK_CONFIG.CONNECT_TIMEOUT_MS,
-  reconnectTimeWait: NETWORK_CONFIG.RECONNECT_TIME_WAIT_MS,
-  maxPingOut: NETWORK_CONFIG.MAX_PING_OUT,
-})
+// Use frozen config values
+const timeout = NETWORK_CONFIG.CONNECT_TIMEOUT_MS // 10_000
 
-// Type-safe connection state handler
-function onStatusChange(status: NatsConnectionStatus) {
-  if (status === 'reconnecting') {
-    console.warn('NATS reconnecting...')
+// Type a NATS connection status handler
+function handleStatus(status: NatsConnectionStatus): void {
+  if (status === 'error') {
+    scheduleReconnect(NETWORK_CONFIG.RECONNECT_TIME_WAIT_MS)
   }
 }
 
-// Typed chunk fetch implementation
+// Type a chunk fetcher implementation
 const fetchChunks: FetchChunksFunction = async (dialogId, chatType, fromSequenceId) => {
   const res = await api.get<ChunkData[]>(`/dialogs/${dialogId}/chunks`, {
     params: { chatType, from: fromSequenceId },
@@ -65,7 +57,15 @@ const fetchChunks: FetchChunksFunction = async (dialogId, chatType, fromSequence
   return res.data
 }
 
-// Paginated API response
-const response: PaginatedResponse<ChunkData[]> = await fetchPage(dialogId, 1)
-console.log(`Page ${response.page} of ${response.totalPages}`)
-```
+// Consume a paginated API response
+async function loadHistory(): Promise<void> {
+  const response: PaginatedResponse<ChunkData[]> = await api.getHistory()
+  if (response.success) {
+    console.log(`Page ${response.page} of ${response.totalPages}`)
+  }
+}
+```
+
+## Source
+
+[`network.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/network.types.ts)

package/src/components/chat/types/.processing.types.md

@@ -1,21 +1,31 @@
-<!-- source-hash: 118d3a4cacf89174498282067448e4bf -->
-Defines TypeScript types for message processing pipeline operations, including chunk parsing, accumulator state management, stream control, and buffer management for AI chat message flows.
+<!-- source-hash: bdb71cca9908cf9cfebf089a00d84db8 -->
+Defines TypeScript types for the message processing pipeline, covering chunk parsing, state accumulation, stream control, and buffer management.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ParsedChunkAction` | Union type | Discriminated union of all possible chunk parse results (text, tool execution, approvals, metadata, etc.) |
-| `AccumulatorState` | Interface | Stateful container tracking message segments, pending approvals, and executing tools during stream processing |
-| `PendingApproval` | Interface | Represents an approval request awaiting user action (command, explanation, type) |
-| `MessageProcessingOptions` | Interface | Configuration for assistant rendering, approval callbacks, chat filtering, and batch approval UI |
-| `ChunkProcessor` | Interface | Contract for processing raw `ChunkData` into `ParsedChunkAction` results |
-| `ChunkProcessorOptions` | Interface | Lifecycle callbacks for chunk processing events |
-| `MessageTransformer` | Interface | Contract for transforming raw inputs into `ProcessedMessage` objects |
-| `StreamProcessor` | Interface | Full lifecycle control (start/stop/pause/resume/reset) for stream consumers |
-| `StreamState` | Interface | Snapshot of stream health: active status, buffered chunks, error log, and last activity timestamp |
-| `BufferManager` | Interface | CRUD-style contract for managing `ChunkData` buffers |
-| `BufferOptions` | Interface | Configuration for buffer capacity, flush intervals, and overflow handling callbacks |
+### Union Types
+- **`ParsedChunkAction`** — Discriminated union of all possible chunk parse results: `message_start`, `message_end`, `error`, `metadata`, `text`, `thinking`, `tool_execution`, `approval_request`, `approval_batch`, `approval_result`, `token_usage`, `direct_message`, `system`, `context_compaction_start/end`, `dialog_closed`
+
+### Accumulator State
+- **`AccumulatorState`** — Tracks in-flight message segments, pending approvals, and executing tool states during streaming
+- **`PendingApproval`** — Holds command, explanation, and approval type for a deferred approval card
+
+### Processing Configuration
+- **`MessageProcessingOptions`** — Runtime options passed to the processor: assistant identity, approval callbacks, chat type filter, approval status map, `displayApprovalTypes`, and `batchApprovalsEnabled` (consumer-owned feature flag)
+
+### Chunk Processing
+- **`ChunkProcessor`** — Interface for stateful chunk parsing with `processChunk` and `reset`
+- **`ChunkProcessorOptions`** — Lifecycle callbacks for chunk events (`onText`, `onToolExecution`, `onApprovalRequest`, etc.)
+
+### Message Transformation
+- **`MessageTransformer`** — Single and batch transform interface producing `ProcessedMessage` outputs
+- **`TransformationOptions`** — Flags for segment merging, timestamp formatting, and metadata inclusion
+
+### Stream & Buffer Management
+- **`StreamProcessor`** — Lifecycle control (`start`, `stop`, `pause`, `resume`, `reset`, `getState`)
+- **`StreamState`** — Runtime counters: active state, pause flag, processed message count, buffered chunks, error log
+- **`BufferManager`** — FIFO buffer operations (`add`, `flush`, `clear`, `size`, `isEmpty`, `isFull`)
+- **`BufferOptions`** — Max size, flush interval, and overflow/flush callbacks
 
 ## Usage Example
 
@@ -24,45 +34,47 @@ import type {
   ParsedChunkAction,
   AccumulatorState,
   MessageProcessingOptions,
-  StreamState
+  StreamState,
 } from './processing.types'
 
-// Handling a parsed chunk action via discriminated union
-function handleChunkAction(action: ParsedChunkAction): void {
+// Narrow a parsed chunk action by discriminant
+function handleChunk(action: ParsedChunkAction) {
   switch (action.action) {
     case 'text':
-      console.log('Received text:', action.text)
+      console.log('Text received:', action.text)
       break
     case 'tool_execution':
-      console.log('Tool executing:', action.segment)
+      console.log('Tool segment:', action.segment)
       break
     case 'approval_batch':
-      console.log('Batch approval request:', action.requestId, action.toolCalls)
+      console.log('Batch approval', action.requestId, action.toolCalls)
       break
     case 'error':
-      console.error('Processing error:', action.error, action.details)
+      console.error(action.error, action.details)
       break
   }
 }
 
-// Initializing accumulator state
-const state: AccumulatorState = {
-  segments: [],
-  pendingApprovals: new Map(),
-  executingTools: new Map()
-}
-
-// Configuring message processing
+// Configure message processing with batch approvals enabled
 const options: MessageProcessingOptions = {
   assistantName: 'Mingo',
   assistantType: 'mingo',
-  batchApprovalsEnabled: true,
-  displayApprovalTypes: ['shell', 'file'],
+  batchApprovalsEnabled: true, // consumer sets this from their feature flag
+  displayApprovalTypes: ['shell', 'file_write'],
   onApprove: async (requestId) => {
-    await submitApproval(requestId)
+    await fetch(`/api/approvals/${requestId}/approve`, { method: 'POST' })
+  },
+  onReject: async (requestId) => {
+    await fetch(`/api/approvals/${requestId}/reject`, { method: 'POST' })
   },
-  onReject: (requestId) => {
-    logRejection(requestId)
-  }
 }
-```
+
+// Initialize accumulator state
+const state: AccumulatorState = {
+  segments: [],
+  pendingApprovals: new Map(),
+  executingTools: new Map(),
+}
+```
+
+**Source:** [`processing.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/processing.types.ts)

package/src/components/chat/types/.unified-chat-state.types.md

@@ -1,41 +1,56 @@
-<!-- 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.
+<!-- source-hash: cae6679d748353879069b316add2f081 -->
+Unified contract type definitions for the `useChat` hook's transport-agnostic return shape, shared by both the SSE (Guide mode) and NATS (Mingo mode) transport adapters.
 
 ## 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 |
+|---|---|---|
+| `DialogTokenUsage` | Interface | Per-dialog token usage snapshot from the Mingo backend's GraphQL `dialogs` endpoint |
+| `ChatConnectionState` | Type | Transport-level connection status: `'connected' \| 'connecting' \| 'disconnected'` |
+| `StreamingPhase` | Type | Granular streaming indicator: `'idle' \| 'thinking' \| 'streaming'` |
+| `UnifiedUsageBreakdown` | Interface | SSE-only sub-call token costs for the Haiku rewriter/classifier/summarizer pipeline |
+| `UnifiedChatMessage` | Interface | Transport-agnostic message shape; Guide-only fields (`sources`, `chatRefs`) are optional |
+| `UnifiedSendMessageOptions` | Interface | Options accepted by `sendMessage` honoured by both transports |
+| `UnifiedChatState` | Interface | **Primary contract** — the full return shape both transport hooks must satisfy |
 
 ## 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 }) {
+import type {
+  UnifiedChatState,
+  UnifiedChatMessage,
+  UnifiedSendMessageOptions,
+  StreamingPhase,
+} from './unified-chat-state.types'
+
+// Consuming the contract without branching on transport mode
+function MyChatShell({ 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)
+  const handleSend = async (text: string, opts?: UnifiedSendMessageOptions) => {
+    await sendMessage(text, {
+      hidden: false,
+      attachments: opts?.attachments,
+      contextItems: opts?.contextItems,
+    })
   }
 
-  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} />
-    </>
-  )
+  // SSE-only fields are null in Mingo mode — guard before rendering
+  const modelLabel = chat.currentModelLabel ?? 'AI'
+  const phase: StreamingPhase = streamingPhase
+
+  return { messages, isLoading, phase, modelLabel, handleSend, 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.
+## Transport Compatibility
+
+| Field | SSE (Guide) | NATS (Mingo) |
+|---|---|---|
+| `sources`, `chatRefs` | ✅ Populated | `undefined` |
+| `currentProvider` / `currentModelLabel` | ✅ Populated | `null` |
+| `currentUsageBreakdown` | ✅ After trailing frame | `null` |
+| `DialogTokenUsage` (separate) | `null` | ✅ From GraphQL |
+| `discussRef` / `displayRef` | ✅ Active | no-op |
+
+> **Source:** [`unified-chat-state.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/unified-chat-state.types.ts)

package/src/components/chat/types/entities/.content-ref.md

@@ -1,41 +1,30 @@
-<!-- source-hash: c5cc84322439cd96dae36a797cb9a2cb -->
-Defines the `ContentRef` interface — the unified shape for link/embed references stored in JSONB columns across entities such as investor updates and performance baselines that surface "related content" rails.
+<!-- source-hash: d15c6ea0015118d3460fb4327e86fe26 -->
+Backwards-compatibility re-export stub that preserves existing import paths for `ContentRef` and `ContentRefWithReason` after their canonical definitions were relocated to `src/types/content-ref.ts`.
 
 ## Key Components
 
-### `ContentRef` Interface
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `type` | `string` | ✅ | Content type identifier (e.g., `"video"`, `"article"`) |
-| `id` | `string` | ✅ | Unique content identifier |
-| `slug` | `string` | ✅ | URL-friendly slug |
-| `url` | `string` | ✅ | Canonical URL of the referenced content |
-| `targetPlatform` | `string \| null` | ❌ | Platform hint (e.g., `"youtube"`, `"notion"`) |
-| `title` | `string` | ✅ | Display title |
-| `summary` | `string` | ❌ | Short description or excerpt |
-| `image_url` | `string` | ❌ | Thumbnail or preview image URL |
-| `image_bg_color` | `string` | ❌ | Background color for image placeholder |
-| `visibility` | `'public' \| 'internal'` | ✅ | Access scope |
-| `display_order` | `number` | ✅ | Sort position within its parent list |
+- **`ContentRef`** — re-exported from `src/types/content-ref.ts`; the canonical content reference type shared across the related-content rail and chat entities.
+- **`ContentRefWithReason`** — re-exported from `src/types/content-ref.ts`; extends `ContentRef` with a reason field.
 
 ## Usage Example
 
 ```typescript
-import type { ContentRef } from './content-ref';
-
-const ref: ContentRef = {
-  type: 'video',
-  id: 'abc123',
-  slug: 'q1-investor-update',
-  url: 'https://www.youtube.com/watch?v=abc123',
-  targetPlatform: 'youtube',
-  title: 'Q1 2025 Investor Update',
-  summary: 'Quarterly performance highlights and roadmap preview.',
-  image_url: 'https://img.youtube.com/vi/abc123/hqdefault.jpg',
-  visibility: 'internal',
-  display_order: 1,
+// Existing imports continue to work unchanged — no migration required.
+import type { ContentRef, ContentRefWithReason } from './content-ref';
+
+const ref: ContentRef = { id: '123', type: 'article' };
+
+const refWithReason: ContentRefWithReason = {
+  ...ref,
+  reason: 'Related to current investor update',
 };
 ```
 
-> **Note:** This type is shared across client and server. Server-side data utilities (e.g., JSONB serialization, fetch helpers) remain hub-side and should import this interface rather than redeclare it locally.
+> **Note:** Prefer importing directly from the canonical location for new code:
+> ```typescript
+> import type { ContentRef } from 'src/types/content-ref';
+> ```
+
+## Source
+
+[`content-ref.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/content-ref.ts)

package/src/components/chat/types/entities/.investor-update.md

@@ -1,35 +1,33 @@
-<!-- source-hash: cd90c6466cd8d12a5c8765efbf35dcb1 -->
-Defines the wire-shape types and a pure formatter for investor update entities, used across chat cards and `/api/investor-updates` API reads.
+<!-- source-hash: ef4cd58c55bef9dac453eefe4b6067ba -->
+Defines the wire-shape types for investor update entities used in chat cards and `/api/investor-updates` API responses, plus a pure date-range formatter utility.
 
 ## Key Components
 
 ### Interfaces
 
-| Interface | Purpose |
-|---|---|
-| `MetricEntry` | A single financial or KPI metric with current/previous values and visibility scope |
-| `HighlightEntry` | A titled highlight item (milestone, note, etc.) with optional description and visibility |
-| `InvestorUpdateHighlights` | Grouped collections of `HighlightEntry` items by category |
-| `InvestorUpdate` | Full wire shape for an investor update — covers content, media, SEO, HubSpot, authorship, and visibility |
+- **`MetricEntry`** — A single financial or operational metric with current/previous values, optional percentage change, and a `public | internal` visibility flag
+- **`HighlightEntry`** — A titled highlight item (e.g. product milestone, community update) with visibility control
+- **`InvestorUpdateHighlights`** — Groups highlight entries by category: `key_highlights`, `product_milestones`, `community_updates`, `upcoming_priorities`, and `financial_notes`
+- **`InvestorUpdate`** — The primary entity shape covering all update fields: content, video assets, financials, metrics, SEO metadata, HubSpot integration IDs, and audit timestamps
 
 ### Functions
 
-- **`formatInvestorUpdatePeriod`** — Pure formatter that converts `period_start` / `period_end` ISO strings into a human-readable range (e.g. `Mar 2025 - May 2025`). Falls back to `?` for missing endpoints.
+- **`formatInvestorUpdatePeriod(start, end, options?)`** — Formats a date range as a human-readable string (e.g. `Mar 2025 - May 2025`). Renders `?` for missing endpoints. Pins to UTC to ensure SSR/client hydration consistency.
 
 ## Usage Example
 
 ```typescript
-import type { InvestorUpdate, MetricEntry } from './investor-update';
-import { formatInvestorUpdatePeriod } from './investor-update';
+import type { InvestorUpdate, MetricEntry } from '@openframe-oss-lib/investor-update';
+import { formatInvestorUpdatePeriod } from '@openframe-oss-lib/investor-update';
 
-// Format a period range for display
+// Format a period label for display
 const label = formatInvestorUpdatePeriod('2025-03-01', '2025-05-31');
 // → "Mar 2025 - May 2025"
 
 const labelLong = formatInvestorUpdatePeriod('2025-03-01', null, { monthFormat: 'long' });
 // → "March 2025 - ?"
 
-// Type-safe metric entry
+// Typing a metric entry
 const mrr: MetricEntry = {
   current: 42000,
   previous: 38000,
@@ -40,6 +38,6 @@ const mrr: MetricEntry = {
 
 ## Notes
 
-- Visibility fields (`'public' | 'internal'`) control what surfaces in public-facing vs. internal views — filtering logic stays hub-side.
-- `section_visibility` is a freeform record allowing per-section overrides on any `InvestorUpdate`.
-- Server-side data utilities and DB access remain in `lib/data/investor-update-utils-shared.ts`; this file exports types and pure functions only.
+- Only **types** and the pure `formatInvestorUpdatePeriod` formatter are exported here. Server-side data utilities and visibility filters remain hub-side.
+- `section_visibility` allows per-section `public | internal` gating on the `InvestorUpdate` object independent of field-level `MetricEntry` / `HighlightEntry` visibility.
+- Source: [`investor-update.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/investor-update.ts)