@flamingo-stack/openframe-frontend-core 0.0.490-1506.3944.1 → 0.0.490

package/src/components/chat/index.ts

@@ -6,6 +6,7 @@ export * from './approval-batch-message'
 export * from './context-compaction-display'
 export * from './expand-chevron'
 export * from './thinking-display'
+export * from './guide-display'
 export * from './error-message-display'
 export * from './chat-container'
 export * from './chat-input'
@@ -75,11 +76,6 @@ export * from './types'
 // Chat hooks
 export * from './hooks'
 
-// Chat stream module — master reducer + dialog store + React wrapper
-// (Phase 3 of the chat unification; ONE accumulation path for SSE + NATS
-// + history replay).
-export * from './stream'
-
 // Chat utilities
 export * from './utils'
 

package/src/components/chat/thinking-display.tsx

@@ -4,7 +4,7 @@ import { forwardRef, useState } from "react"
 
 import { cn } from "../../utils/cn"
 import { DotsLoaderIcon } from "../icons-v2-generated"
-import { SimpleMarkdownRenderer } from "../ui/markdown/simple-markdown-renderer"
+import { SimpleMarkdownRenderer } from "../ui/simple-markdown-renderer"
 import { ExpandChevron } from "./expand-chevron"
 import { useCollapsible } from "./hooks/use-collapsible"
 import type { ThinkingDisplayProps } from "./types"

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

@@ -1,60 +1,70 @@
-<!-- source-hash: 60ad035125eceb97fa074f58783d5bc8 -->
-Defines TypeScript interfaces for API interactions and React hook contracts used across Flamingo's chat and dialog systems, covering NATS/JetStream subscriptions, real-time chunk processing, and REST-style request/response shapes.
+<!-- source-hash: 76966dd4845d1486e56288fc8033df68 -->
+Defines TypeScript interfaces for API interactions and React hook contracts used in the OpenFrame real-time chat and NATS messaging system.
 
 ## Key Components
 
-### Hook Options
-| Interface | Purpose |
-|---|---|
-| `UseChunkCatchupOptions` | Configure chunk catch-up replay with optional custom fetch function |
-| `UseNatsDialogSubscriptionOptions` | Core NATS WebSocket subscription config with reconnection backoff tuning |
-| `UseJetStreamDialogSubscriptionOptions` | JetStream-based subscription with sequence-based resume support |
-
-### Hook Return Types
-| Interface | Purpose |
-|---|---|
-| `UseChunkCatchupReturn` | Exposes catchup, processing, and buffering controls |
-| `UseNatsDialogSubscriptionReturn` | Connection state and reconnection counter |
-| `UseJetStreamDialogSubscriptionReturn` | Connection state plus current stream sequence |
-
-### Callbacks
-- **`RealtimeChunkCallbacks`** — Rich event callback map for streaming events: `onStreamStart`, `onStreamEnd`, `onSegmentsUpdate`, `onTokenUsage`, `onApprove`, `onReject`, `onEscalatedApproval`, `onApprovalResolved`, `onToolExecuted`, `onDialogClosed`, and more.
-
-### API Request/Response Types
-- **Chat** — `ChatAPIRequest` / `ChatAPIResponse`
-- **Dialogs** — `DialogCreateRequest/Response`, `DialogListRequest/Response`
-- **Approvals** — `ApprovalRequest` / `ApprovalResponse`
-- **Settings** — `ChatSettings`, `UpdateSettingsRequest/Response`
+### Hook Option Interfaces
+- **`UseChunkCatchupOptions`** — Configuration for chunk catch-up logic, including dialog ID, chunk callbacks, chat type filters, and an optional custom fetch function
+- **`UseNatsDialogSubscriptionOptions`** — NATS WebSocket subscription config with reconnection backoff tuning, auth lifecycle hooks, and client credentials
+- **`UseJetStreamDialogSubscriptionOptions`** — JetStream-specific variant adding stream name, sequence-based replay (`optStartSeq`), and consumer inactivity threshold
+- **`UseRealtimeChunkProcessorOptions`** — Controls chunk processing behavior: approval type routing, batch approvals, direct-mode barrier, and initial accumulator state for reconnection
+
+### Hook Return Interfaces
+- **`UseChunkCatchupReturn`** — Exposes `catchUpChunks`, `processChunk`, `resetAndCatchUp`, and buffering state controls
+- **`UseNatsDialogSubscriptionReturn`** / **`UseJetStreamDialogSubscriptionReturn`** — Connection/subscription status and reconnection counters; JetStream variant also tracks `currentStreamSeq`
+- **`UseRealtimeChunkProcessorReturn`** — `processChunk`, `getSegments`, `reset`, and `updateApprovalStatus`
+
+### Callback & Metadata Interfaces
+- **`RealtimeChunkCallbacks`** — Comprehensive event callback surface covering stream lifecycle (`onStreamStart`, `onStreamEnd`), message types (user, direct, system), tool execution (`onToolExecuted`, `onAgentBusy`), approval flows (`onApprove`, `onReject`, `onEscalatedApproval`, `onApprovalResolved`), token usage, and dialog closure
+- **`SegmentsUpdateMetadata`** — Carries append mode, compaction flags, and JetStream `streamSeq` for history deduplication
 
 ## Usage Example
 
 ```typescript
-const options: ChatStreamReducerOptions = {
-  callbacks: {
-    onSegmentsUpdate: (segments, meta) => {
-      if (meta?.append) appendToLastMessage(segments)
-      else setSegments(segments)
-    },
-    onApprovalResolved: (requestId, status, approvalType) => {
-      updateApprovalBadge(requestId, status)
-    },
-    onTokenUsage: (data) => console.log('Tokens used:', data),
+import type {
+  UseNatsDialogSubscriptionOptions,
+  UseRealtimeChunkProcessorOptions,
+  RealtimeChunkCallbacks,
+} from './api.types'
+
+const callbacks: RealtimeChunkCallbacks = {
+  onStreamStart: () => setStreaming(true),
+  onStreamEnd: () => setStreaming(false),
+  onSegmentsUpdate: (segments, meta) => {
+    if (meta?.append) appendSegments(segments)
+    else setSegments(segments)
   },
-  batchApprovalsEnabled: true,
+  onToolExecuted: (segment) => mergeToolResult(segment),
+  onApprovalResolved: (requestId, status, approvalType) => {
+    updateApprovalCard(requestId, status)
+  },
+}
+
+const processorOptions: UseRealtimeChunkProcessorOptions = {
+  callbacks,
   displayApprovalTypes: ['CLIENT'],
-  enableThinking: false,
+  batchApprovalsEnabled: true,
+  initialState: {
+    existingSegments: historicalSegments,
+    executingTools: new Map(),
+  },
 }
 
 const natsOptions: UseNatsDialogSubscriptionOptions = {
   enabled: true,
   dialogId: 'dialog-123',
+  topics: ['message'],
   getNatsWsUrl: () => 'wss://nats.example.com',
+  onBeforeReconnect: async () => refreshAuthToken(),
   reconnectionBackoff: {
     fastRetries: 3,
     fastRetryDelayMs: 500,
-    maxDelayMs: 30000,
+    maxDelayMs: 30_000,
     multiplier: 2,
   },
-  onBeforeReconnect: async () => refreshAuthToken(),
 }
-```
+```
+
+## Source
+
+[`api.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/api.types.ts)

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

@@ -1,51 +1,80 @@
-<!-- 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 |
-|--------|------|-------------|
-| `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 |
-| `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
 
 ```typescript
 import type {
+  ParsedChunkAction,
   AccumulatorState,
   MessageProcessingOptions,
-  StreamState
+  StreamState,
 } from './processing.types'
 
-
-// Initializing accumulator state
-const state: AccumulatorState = {
-  segments: [],
-  pendingApprovals: new Map(),
-  executingTools: new Map()
+// Narrow a parsed chunk action by discriminant
+function handleChunk(action: ParsedChunkAction) {
+  switch (action.action) {
+    case 'text':
+      console.log('Text received:', action.text)
+      break
+    case 'tool_execution':
+      console.log('Tool segment:', action.segment)
+      break
+    case 'approval_batch':
+      console.log('Batch approval', action.requestId, action.toolCalls)
+      break
+    case 'error':
+      console.error(action.error, action.details)
+      break
+  }
 }
 
-// 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: (requestId) => {
-    logRejection(requestId)
-  }
+  onReject: async (requestId) => {
+    await fetch(`/api/approvals/${requestId}/reject`, { method: 'POST' })
+  },
+}
+
+// Initialize accumulator state
+const state: AccumulatorState = {
+  segments: [],
+  pendingApprovals: new Map(),
+  executingTools: new Map(),
 }
 ```
 
-> NOTE: the wire-chunk vocabulary now lives in `src/chat-protocol/events.ts`
-> (`ChatStreamEvent`, produced by `decodeNatsChunk`). The old
-> `ParsedChunkAction` union and the `ChunkProcessor` contract were deleted
-> together with the legacy `chunk-parser`.
+**Source:** [`processing.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/processing.types.ts)

package/src/components/chat/types/api.types.ts

@@ -213,12 +213,79 @@ export interface RealtimeChunkCallbacks {
   onDialogClosed?: () => void
 }
 
-// NOTE: `UseRealtimeChunkProcessorOptions` / `UseRealtimeChunkProcessorReturn`
-// were DELETED along with the `useRealtimeChunkProcessor` compat hook. The
-// equivalents are `ChatStreamReducerOptions` + `ChatStreamReducer` in
-// `../stream/chat-stream-reducer`. `RealtimeChunkCallbacks` above SURVIVES:
-// it is still the canonical description of the effect names/args the reducer
-// emits via `ChatReducerEffect`.
+export interface UseRealtimeChunkProcessorOptions {
+  callbacks: RealtimeChunkCallbacks
+  /**
+   * Filter approval types that should be displayed directly
+   * Others will trigger onEscalatedApproval
+   * Default: ['CLIENT']
+   */
+  displayApprovalTypes?: string[]
+  /**
+   * Map of existing approval statuses
+   */
+  approvalStatuses?: Record<string, ChatApprovalStatus>
+  /**
+   * Initialize accumulator with existing state from incomplete historical message
+   * Used to continue building messages across page refreshes or reconnections
+   */
+  initialState?: {
+    /** Existing segments to continue building upon */
+    existingSegments?: MessageSegment[]
+    /** Pending approvals that haven't been resolved */
+    pendingApprovals?: Map<string, { command: string; explanation?: string; approvalType: string }>
+    /** Executing tools waiting for completion */
+    executingTools?: Map<string, ExecutingToolState>
+    /** Escalated approvals */
+    escalatedApprovals?: Map<
+      string,
+      { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
+    >
+  }
+  /**
+   * Consumer-owned (e.g. set in `openframe-oss-tenant` chat client via the
+   * `'batch-approvals'` feature flag and forwarded here). The lib does NOT
+   * default this to a batch-on behavior — when omitted it falls back to the
+   * legacy single-card rendering.
+   *
+   * When true: `APPROVAL_REQUEST` chunks containing `toolCalls[]` are rendered
+   * as a single batch card. When false / omitted: the batch is split into N
+   * legacy approval cards (one per tool that requires approval), all sharing
+   * the same `approvalRequestId`. Tools with `requiresApproval=false` are
+   * dropped from the UI in the unfolded mode.
+   */
+  batchApprovalsEnabled?: boolean
+  /**
+   * Engages the direct-mode barrier optimistically: once true, all AI-assistant
+   * chunks (text, thinking, tool executions, approvals, metadata, errors, etc.)
+   * are dropped and any open stream is torn down, leaving only human/control
+   * messages. A `DIRECT_MESSAGE` chunk engages the same barrier automatically
+   * regardless of this flag. Pass this from a host that already knows the dialog
+   * switched to direct mode (e.g. an optimistic mode toggle) to close the race
+   * window before the server emits the first `DIRECT_MESSAGE`.
+   *
+   * Do NOT set this when the host reconstructs history by replaying chunks
+   * through `processChunk` — a static flag would drop legitimate pre-switch AI
+   * history. Rely on the in-order `DIRECT_MESSAGE` detection instead.
+   */
+  isDirectMode?: boolean
+}
+
+export interface UseRealtimeChunkProcessorReturn {
+  /** Process a single chunk */
+  processChunk: (chunk: unknown) => void
+  /** Get current segments */
+  getSegments: () => MessageSegment[]
+  /** Reset the accumulator */
+  reset: () => void
+  /** Update approval status for a request */
+  updateApprovalStatus: (requestId: string, status: ChatApprovalStatus, resolvedByName?: string | null) => MessageSegment[]
+  /** Get pending approval requests */
+  getPendingApprovals: () => Map<
+    string,
+    { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
+  >
+}
 
 // ========== API Request Types ==========
 

package/src/components/chat/types/component.types.ts

@@ -556,6 +556,15 @@ export interface ThinkingDisplayProps extends HTMLAttributes<HTMLDivElement> {
   isStreaming?: boolean
 }
 
+// ========== Guide Display Props ==========
+
+export interface GuideDisplayProps extends HTMLAttributes<HTMLDivElement> {
+  /** Rendered guide body. `ChatMessageEnhanced` passes the SAME markdown
+   *  output a text segment gets, so `[card://]` cards and mention chips
+   *  behave identically inside a guide. */
+  children?: ReactNode
+}
+
 // ========== Model Display Props ==========
 
 export interface ModelDisplayProps extends HTMLAttributes<HTMLDivElement> {

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

@@ -10,6 +10,7 @@ import type { AssistantType, AuthorType, ChatApprovalStatus, MessageOwner } from
 export const MESSAGE_TYPE = {
   TEXT: 'TEXT',
   THINKING: 'THINKING',
+  GUIDE: 'GUIDE',
   EXECUTING_TOOL: 'EXECUTING_TOOL',
   EXECUTED_TOOL: 'EXECUTED_TOOL',
   APPROVAL_REQUEST: 'APPROVAL_REQUEST',
@@ -170,6 +171,15 @@ export type ThinkingSegment = {
   text: string
 }
 
+/** Guide answer body — the assistant's how-to/documentation reply, rendered as
+ *  a titled "OpenFrame Guide" card instead of a bare paragraph. `text` is
+ *  markdown, streamed in fragments like a `text` segment and coalesced by the
+ *  accumulator. */
+export type GuideSegment = {
+  type: 'guide'
+  text: string
+}
+
 export type ToolExecutionSegment = {
   type: 'tool_execution'
   data: ToolExecutionData
@@ -208,7 +218,7 @@ export type ContextCompactionSegment = {
   summary?: string
 }
 
-export type MessageSegment = TextSegment | ThinkingSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
+export type MessageSegment = TextSegment | ThinkingSegment | GuideSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
 
 export type MessageContent = string | MessageSegment[]
 
@@ -228,6 +238,11 @@ export interface ThinkingMessageData extends MessageDataBase {
   text?: string
 }
 
+export interface GuideMessageData extends MessageDataBase {
+  type: 'GUIDE'
+  text?: string
+}
+
 export interface ExecutingToolMessageData extends MessageDataBase {
   type: 'EXECUTING_TOOL'
   integratedToolType?: string
@@ -309,6 +324,7 @@ export interface ContextCompactionEndMessageData extends MessageDataBase {
 export type MessageData =
   | TextMessageData
   | ThinkingMessageData
+  | GuideMessageData
   | ExecutingToolMessageData
   | ExecutedToolMessageData
   | ApprovalRequestMessageData

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

@@ -3,14 +3,38 @@
  * Contains types for message parsing, accumulation, and processing
  */
 
-import type { MessageSegment, PendingToolCallData, ExecutingToolState } from './message.types'
+import type { MessageSegment, ProcessedMessage, ToolExecutionSegment, TokenUsageData, PendingToolCallData, ExecutingToolState } from './message.types'
 import type { ChatApprovalStatus, AssistantType } from './chat.types'
-import type { ChunkData } from './network.types'
-
-// NOTE: the `ParsedChunkAction` union that used to live here was DELETED
-// alongside the legacy `chunk-parser`. The wire → normalized-event
-// vocabulary is now `ChatStreamEvent` in `src/chat-protocol/events.ts`,
-// produced by `decodeNatsChunk`.
+import type { ChunkData, NatsMessageType } from './network.types'
+
+// ========== Parsed Chunk Result Types ==========
+
+export type ParsedChunkAction =
+  | { action: 'message_start' }
+  | { action: 'message_end' }
+  | { action: 'error'; error: string; details?: string }
+  | { action: 'metadata'; modelDisplayName: string; modelName: string; providerName: string; contextWindow: number }
+  | { action: 'text'; text: string }
+  | { action: 'thinking'; text: string }
+  | { action: 'guide'; text: string }
+  | { action: 'tool_execution'; segment: ToolExecutionSegment }
+  | { action: 'approval_request'; requestId: string; command: string; explanation?: string; approvalType: string }
+  | { action: 'approval_batch'; requestId: string; approvalType: string; toolCalls: PendingToolCallData[] }
+  | { action: 'approval_result'; requestId: string; approved: boolean; approvalType: string; resolvedByName?: string | null }
+  | {
+      action: 'message_request'
+      text: string
+      ownerType?: string
+      displayName?: string
+      userId?: string
+      contextItems?: Array<{ type: string; id: string }>
+    }
+  | { action: 'token_usage'; data: TokenUsageData }
+  | { action: 'direct_message'; text: string; ownerType?: string; displayName?: string; userId?: string }
+  | { action: 'system'; text: string }
+  | { action: 'context_compaction_start' }
+  | { action: 'context_compaction_end'; summary?: string }
+  | { action: 'dialog_closed' }
 
 // ========== Accumulator State ==========
 
@@ -58,13 +82,31 @@ export interface MessageProcessingOptions {
   batchApprovalsEnabled?: boolean
 }
 
-// NOTE: `ChunkProcessorOptions` (the options bag of the deleted
-// `ChunkProcessor`) and `MessageTransformer` were DELETED — both were left
-// behind by the chunk-processor removal with zero references in lib, hub, or
-// app.
+// ========== Chunk Processing Types ==========
+
+export interface ChunkProcessor {
+  processChunk: (chunk: ChunkData, messageType: NatsMessageType) => ParsedChunkAction | null
+  reset: () => void
+}
+
+export interface ChunkProcessorOptions {
+  onMessageStart?: () => void
+  onMessageEnd?: () => void
+  onError?: (error: string, details?: string) => void
+  onText?: (text: string) => void
+  onToolExecution?: (segment: MessageSegment) => void
+  onApprovalRequest?: (data: any) => void
+  onApprovalResult?: (data: any) => void
+  onMetadata?: (data: any) => void
+}
 
 // ========== Message Transformation Types ==========
 
+export interface MessageTransformer {
+  transform: (input: any) => ProcessedMessage | null
+  batch: (inputs: any[]) => ProcessedMessage[]
+}
+
 export interface TransformationOptions {
   preserveOriginal?: boolean
   mergeSegments?: boolean

package/src/components/chat/utils/.chunk-parser.md

@@ -0,0 +1,62 @@
+<!-- source-hash: c8c1cef3b3966f8791e7003c4f74429f -->
+Utilities for parsing raw NATS message chunks into typed, structured action objects consumed by the OpenFrame chat pipeline.
+
+## Key Components
+
+### `parseChunkToAction(chunk: unknown): ParsedChunkAction | null`
+The primary export. Accepts an untyped NATS chunk, inspects its `type` field against `MESSAGE_TYPE` constants, and returns a discriminated `ParsedChunkAction` union or `null` for unrecognized types. Handles the full message lifecycle including:
+
+- **Lifecycle signals:** `message_start`, `message_end`, `dialog_closed`
+- **Content:** `text`, `thinking`, `system`, `direct_message`
+- **Tool execution:** `tool_execution` (both `EXECUTING_TOOL` and `EXECUTED_TOOL` states)
+- **Approval flow:** `approval_request`, `approval_batch`, `approval_result`
+- **Metadata & telemetry:** `metadata`, `token_usage`, `context_compaction_start/end`
+- **Error handling:** `error`
+
+### `normalizeToolCalls(raw: unknown): PendingToolCallData[]` *(internal)*
+Safely coerces an untyped array into `PendingToolCallData[]`, filtering non-objects and providing safe defaults for all fields.
+
+### Predicate helpers
+Lightweight type guards for fast chunk classification without full parsing:
+
+| Function | Returns `true` when |
+|---|---|
+| `isControlChunk` | `MESSAGE_START` or `MESSAGE_END` |
+| `isErrorChunk` | `ERROR` type |
+| `isMetadataChunk` | `AI_METADATA` type |
+| `extractTextFromChunk` | `TEXT` type — returns the string or `null` |
+
+## Usage Example
+
+```typescript
+import {
+  parseChunkToAction,
+  isControlChunk,
+  isErrorChunk,
+} from './chunk-parser'
+
+// Parse an incoming NATS chunk
+const action = parseChunkToAction(rawChunk)
+
+if (action?.action === 'text') {
+  appendToTranscript(action.text)
+} else if (action?.action === 'approval_batch') {
+  promptUserApproval(action.toolCalls)
+}
+
+// Fast-path guards before full parse
+if (isErrorChunk(rawChunk)) {
+  handleError()
+}
+if (isControlChunk(rawChunk)) {
+  resetStreamState()
+}
+```
+
+## Notes
+
+- All field access is defensive — missing or wrong-typed properties fall back to safe defaults rather than throwing.
+- `approval_result` accepts both `resolvedByName` and `displayName` so realtime NATS chunks and GraphQL history replays produce identical output shapes.
+- `contextItems` on `message_request` back-fills `label` from `id` to satisfy the required `ChatContextItem` contract when no label is present on the wire.
+
+**Source:** [`https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chunk-parser.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chunk-parser.ts)

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

@@ -1,48 +1,57 @@
-<!-- source-hash: 85c0af6cd361347beeabcd097260378a -->
-Barrel export module that consolidates and re-exports all message processing, chat navigation, UI styling, and content utility functions for chat interfaces.
+<!-- source-hash: 0435e7889d0ba1d3a5186507e28737c9 -->
+Barrel export module for the message processing utilities library, re-exporting all public APIs from specialized sub-modules covering chat message parsing, navigation, attachments, icons, and more.
 
 ## Key Components
 
-| Category | Exports |
-|----------|---------|
-| **Message Accumulation** | `MessageSegmentAccumulator`, `createMessageSegmentAccumulator`, `AccumulatorCallbacks` |
-| **Historical Messages** | `processHistoricalMessages`, `extractErrorMessages`, `processHistoricalMessagesWithErrors` |
-| **Chat Navigation** | `handleChatNavClick`, `resolveExternalNavigation`, `decideNewTab`, `computeIsNewTab`, `buildAnchorProps` |
-| **Proxy Auth** | `getChatProxyAuth`, `setChatProxyAuth`, `clearChatProxyAuth`, `applyProxyAuth`, `chatAuthedFetch` |
-| **Attachments** | `formatChatAttachmentMarkdownForBubble`, `stripChatAttachmentMarkdown`, `buildChatAttachmentViewUrl` |
-| **UI / Styling** | `chatChipClass`, compact card class constants (`COMPACT_CARD_*`), `getStatusColorScheme` |
-| **Icon Registry** | `ICON_REGISTRY`, `getIconComponent`, `normalizeIconKey`, `getDynamicIcon` |
-| **Source Utilities** | `getSourceIconName`, `getSourceLabel`, `resolveSourceRowCTA`, `resolveSourceIcon` |
-| **Slash Commands** | `parseWireCommandOverride`, `sanitizeTitleForChat`, `buildDiscussAddendum` |
+| Export Group | Source Module | Description |
+|---|---|---|
+| Chunk parsing | `chunk-parser` | Parse streaming chunks into actions, detect control/error/metadata chunks |
+| Segment accumulator | `message-segment-accumulator` | Accumulate streaming message segments with callbacks |
+| Historical messages | `process-historical-messages` | Process and reconcile chat history with error extraction |
+| History merge | `history-merge` | Reconcile persisted history with realtime stream data |
+| Navigation | `execute-navigation`, `nav-click-handler`, `decide-new-tab` | Unified navigation primitive for new-tab/same-tab, internal/external, embed/host routing |
+| Chat attachment | `chat-attachment-markdown` | Format and strip attachment markdown, URL/token helpers |
+| Icon registry | `icon-registry`, `icon-library`, `source-icons` | Single source of truth for icon-name → component lookups |
+| Proxy auth | `chat-proxy-auth-storage`, `chat-authed-fetch` | localStorage adapter and authenticated fetch wrapper |
+| Slash commands | `slash-dispatch-utils` | Command parsing, entity filtering, and dispatch utilities |
+| Compact card | `compact-card-classes` | Shared CSS class constants and safe-href guard |
+| Scripted stream | `scripted-stream` | Re-exported wholesale via `export *` |
 
 ## Usage Example
 
 ```typescript
 import {
+  parseChunkToAction,
   createMessageSegmentAccumulator,
-  handleChatNavClick,
-  getChatProxyAuth,
-  getIconComponent,
-  formatChatAttachmentMarkdownForBubble,
-  decideNewTab,
+  executeNavigation,
+  resolveIcon,
   getStatusColorScheme,
-} from '@flamingo/chat-utils'
+  mergeHistoryWithRealtime,
+  formatChatAttachmentMarkdownForBubble,
+} from '@openframe/chat-utils'
+
+// Parse a streaming chunk
+const action = parseChunkToAction(rawChunk)
 
-// Accumulate streamed message segments
+// Accumulate message segments from a stream
 const accumulator = createMessageSegmentAccumulator({
-  onSegmentComplete: (segment) => console.log('Segment:', segment),
+  onSegmentComplete: (segment) => console.log('Segment done:', segment),
 })
 
-// Resolve navigation target for a chat link
-const { openInNewTab } = decideNewTab({
-  href: 'https://app.example.com/tickets/123',
-  surface: 'chat-bubble',
-  mode: 'web',
+// Execute navigation respecting new-tab rules
+executeNavigation({
+  href: '/tickets/123',
+  event: clickEvent,
+  surface: 'chat',
 })
 
-// Look up a registered icon by kebab-case key
-const Icon = getIconComponent('clickup')
+// Resolve an icon by name
+const Icon = resolveIcon('clickup')
+
+// Get agent status color scheme
+const colors = getStatusColorScheme('online')
+```
+
+## Source
 
-// Apply agent status color scheme to UI
-const colors = getStatusColorScheme('running')
-```
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)