@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

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

@@ -1,61 +1,60 @@
-<!-- source-hash: ba9f2a73586812d02d2b98db0ff1f6f0 -->
-TypeScript component prop interface definitions for a comprehensive chat UI system, providing type safety for React components used in AI-powered chat interfaces with approval workflows, tool execution displays, and dialog management.
+<!-- source-hash: 141d208f153f42ac4e3acd48496b0621 -->
+Defines all TypeScript prop and ref types for the chat UI component library, covering containers, headers, messages, message lists, inputs, and slash command affordances.
 
 ## Key Components
 
-**Core Chat Props**:
-- `ChatContainerProps` - Main chat wrapper with HTML div attributes
-- `ChatHeaderProps` - Header with user info, settings, and connection status
-- `ChatMessageEnhancedProps` - Enhanced messages supporting segments, typing states, and approval callbacks
-- `ChatMessageListProps` - Message list with scrolling, loading states, and approval handling
-- `ChatInputProps` - Text input with send functionality and response states
-
-**Specialized Component Props**:
-- `ToolExecutionDisplayProps` - Expandable tool execution results display
-- `ApprovalRequestMessageProps` - Interactive approval request with status handling
-- `ConnectionIndicatorProps` - Real-time connection status indicator
-- `ChatTypingIndicatorProps` - Animated typing indicator with customizable appearance
-- `ChatQuickActionProps` - Action buttons with hint animations and loading states
-
-**Navigation & Management**:
-- `ChatSidebarProps` - Dialog list with infinite scroll and creation states
-- `DialogListItemProps` - Individual dialog items with selection and unread counts
-- `ModelDisplayProps` - AI model information display with provider details
+### Core Component Props
+- **`ChatContainerProps`** — Extends `HTMLAttributes<HTMLDivElement>` for the root chat wrapper
+- **`ChatHeaderProps`** — Full header configuration including user info, connection status, ticket info, `fullWidth`, and `bare` display modes
+- **`ChatMessageEnhancedProps`** — Per-message props including role, content (`string | MessageSegment[]`), entity card rendering, and markdown link routing
+- **`ChatMessageListProps`** — Message list with infinite scroll, approval handling, avatar display, and forwarded `renderEntityCard`/`NavLinkAnchor` props
+- **`ChatMessageListRef`** — Imperative handle exposing `scrollToBottom`, `getScrollPosition`, and `setScrollPosition`
+- **`ConnectionIndicatorProps`** — Wraps `ConnectionStatus` for the connection state badge
+
+### Slash Commands
+- **`SlashCommandsProp`** — Consumer-supplied `fetchCommands` callback and optional `resolveSourceIcon` for autocomplete
+- **`SlashCommandSummary`** — Server-resolved command descriptor with `actions`, `argumentHint`, `label`, `displayOrder`, and `iconName`
+- **`SlashCommandActionId`** — String-literal union: `'browse' | 'search' | 'find' | 'display'`
+- **`SlashCommandSourceMeta`** — Icon component + label pair returned by `resolveSourceIcon`
+
+### Routing
+- **`NavLinkAnchorComponent`** — Host-supplied anchor component for markdown links, enabling unified routing (soft same-origin nav, new-tab cross-origin)
 
 ## Usage Example
 
 ```typescript
-import type { 
-  ChatMessageEnhancedProps, 
-  ChatInputProps, 
-  ApprovalRequestMessageProps 
+import type {
+  ChatMessageListProps,
+  ChatHeaderProps,
+  NavLinkAnchorComponent,
+  SlashCommandsProp,
 } from './component.types'
 
-// Enhanced message with approval handling
-const messageProps: ChatMessageEnhancedProps = {
-  role: 'assistant',
-  content: [
-    { type: 'text', content: 'Here is the analysis:' },
-    { 
-      type: 'approval_request', 
-      data: { requestId: 'req_123', action: 'execute_command' } 
-    }
-  ],
-  assistantType: 'mingo',
-  onApprove: async (requestId) => {
-    await approveRequest(requestId)
-  },
-  onReject: (requestId) => {
-    rejectRequest(requestId)
-  }
+// Host-supplied anchor delegates routing to app router
+const NavLinkAnchor: NavLinkAnchorComponent = ({ href, className, children }) => (
+  <a href={href} className={className}>{children}</a>
+)
+
+const headerProps: ChatHeaderProps = {
+  userName: 'Mingo AI',
+  connectionStatus: 'connected',
+  fullWidth: true,   // fills narrow side panel
+  bare: true,        // no card chrome inside Drawer
+}
+
+const listProps: ChatMessageListProps = {
+  messages,
+  fullWidth: true,
+  hasNextPage: true,
+  isFetchingNextPage: false,
+  onLoadMore: fetchOlderMessages,
+  renderEntityCard: (ref) => <EntityCard reference={ref} />,
+  NavLinkAnchor,
 }
 
-// Chat input with send handling
-const inputProps: ChatInputProps = {
-  onSend: (message) => sendMessage(message),
-  sending: false,
-  awaitingResponse: true,
-  maxRows: 4,
-  placeholder: "Ask Mingo anything..."
+const slashCommands: SlashCommandsProp = {
+  fetchCommands: async (prefix, signal) =>
+    fetch(`/api/docs/commands?q=${prefix}`, { signal }).then(r => r.json()),
+  resolveSourceIcon: (sourceId) => iconRegistry[sourceId],
 }
 ```

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

@@ -1,36 +1,29 @@
-<!-- source-hash: aea0bf978ce55f3fb2871d4071c7fd48 -->
-This TypeScript file serves as the main export barrel for type definitions, providing a centralized entry point for importing all types used throughout the system's chat, messaging, component, network, processing, and API layers.
+<!-- source-hash: 20e5ae4b1dc4695977d9dc1f7ed04663 -->
+Central barrel export file that re-exports all TypeScript types and interfaces from the chat module's type definitions.
 
 ## Key Components
 
-The file re-exports types from six specialized modules:
-
-- **chat.types** - Chat-related type definitions and interfaces
-- **message.types** - Message structure and formatting types  
-- **component.types** - UI component and React component types
-- **network.types** - Network request/response and connection types
-- **processing.types** - Data processing and transformation types
-- **api.types** - API endpoint and service interface types
+| Export Source | Description |
+|---|---|
+| `chat.types` | Core chat session and conversation types |
+| `message.types` | Message structure and content types |
+| `component.types` | UI component prop and 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 |
 
 ## Usage Example
 
 ```typescript
-// Import specific types from the barrel export
-import { ChatMessage, ApiResponse, ComponentProps } from './types'
-
-// Or import all types with namespace
-import * as Types from './types'
-
-// Use the imported types
-const message: Types.ChatMessage = {
-  id: '123',
-  content: 'Hello world',
-  timestamp: new Date()
-}
-
-const apiCall = async (): Promise<Types.ApiResponse> => {
-  // API implementation
-}
+// Import any chat-related type directly from the module root
+import {
+  ChatSession,
+  Message,
+  UnifiedChatState,
+  ApiResponse
+} from '@/types/chat'
 ```
 
-This barrel export pattern simplifies imports across the codebase by allowing consumers to import multiple related types from a single source rather than importing from individual type files.
+> All types are available from a single import path — no need to reference individual type files directly.

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

@@ -1,62 +1,72 @@
-<!-- source-hash: 85b8ef73de713600cd760aa44e399e60 -->
-This file defines comprehensive TypeScript types for message handling in a chat system that supports AI assistants, tool execution, and approval workflows.
+<!-- 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
 
-**Core Message Types:**
-- `MESSAGE_TYPE` - Constants for all message types (TEXT, EXECUTING_TOOL, APPROVAL_REQUEST, etc.)
-- `MessageData` - Union type for all possible message data structures from GraphQL/API
-- `MessageSegment` - Union type for different content segments (text, tool execution, approval requests, errors)
-- `ProcessedMessage` - Processed message structure for UI display
-- `HistoricalMessage` - Message structure for chat history storage
+### 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 Types:**
-- `ToolExecutionData` - Structure for tool execution parameters and results
-- `ExecutingToolMessageData` / `ExecutedToolMessageData` - API message data for tool operations
+### 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 System Types:**
-- `ApprovalRequestData` - Structure for approval requests with commands and explanations
-- `ApprovalResultData` - Structure for approval responses
-- `ApprovalRequestSegment` - UI segment with approval callbacks
+### 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
-// Creating a text message
-const textMessage: Message = {
-  id: 'msg-123',
-  role: 'assistant',
-  content: 'Hello! How can I help you today?',
-  assistantType: 'MINGO',
-  timestamp: new Date()
-}
+import {
+  MESSAGE_TYPE,
+  SCROLL_ANCHOR,
+  type Message,
+  type MessageSegment,
+  type ApprovalBatchData
+} from './message.types'
 
-// Creating a tool execution message
-const toolMessage: ProcessedMessage = {
-  id: 'msg-456',
-  role: 'assistant',
-  content: [{
-    type: 'tool_execution',
+// Build a message with mixed content segments
+const segments: MessageSegment[] = [
+  { type: 'text', text: 'Creating a ticket for you...' },
+  {
+    type: 'approval_batch',
     data: {
-      type: 'EXECUTING_TOOL',
-      integratedToolType: 'file_system',
-      toolFunction: 'readFile',
-      parameters: { path: '/config/settings.json' }
-    }
-  }],
-  timestamp: new Date()
-}
-
-// Creating an approval request segment
-const approvalSegment: ApprovalRequestSegment = {
-  type: 'approval_request',
-  data: {
-    command: 'sudo rm -rf /tmp/cache',
-    explanation: 'Clear temporary cache files',
-    approvalRequestId: 'req-789'
-  },
-  onApprove: async (requestId) => {
-    console.log(`Approved request: ${requestId}`)
+      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(),
 }
 ```

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

@@ -1,45 +1,71 @@
-<!-- source-hash: d5397c1feb5364b7246e4091ad6ce652 -->
-Defines comprehensive network communication types for NATS messaging, WebSocket connections, and API responses. Includes configuration constants, chunk data structures, and error handling types for real-time messaging systems.
+<!-- 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.
 
 ## Key Components
 
-**Core Types:**
-- `NatsMessageType` - Message classification ('message' | 'admin-message')
-- `NatsConnectionStatus` - Connection state management
-- `ChunkData` - Streaming data chunks with tool integration support
-- `WebSocketMessage` & `WebSocketConfig` - WebSocket communication setup
+### Types & Enums
 
-**Configuration:**
-- `NETWORK_CONFIG` - Network timing and limits constants
-- Connection timeouts, reconnect intervals, and message limits
+| 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` |
 
-**Response Types:**
-- `NetworkResponse<T>` - Standardized API response wrapper
-- `PaginatedResponse<T>` - Paginated data responses
-- `NetworkError` - Structured error information
+### Constants
+
+| Export | Description |
+|--------|-------------|
+| `NETWORK_CONFIG` | Frozen config object with timeouts, retry backoff, ping intervals, and message limits |
+| `NetworkConfig` | Inferred type from `NETWORK_CONFIG` |
+
+### Interfaces
+
+| 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` |
 
 ## Usage Example
 
 ```typescript
-import { ChunkData, NETWORK_CONFIG, WebSocketConfig } from './network.types'
-
-// Configure WebSocket connection
-const wsConfig: WebSocketConfig = {
-  url: 'ws://localhost:8080',
-  reconnect: true,
-  reconnectInterval: NETWORK_CONFIG.RECONNECT_TIME_WAIT_MS,
-  maxReconnectAttempts: 5,
-  onMessage: (event) => {
-    const chunk: ChunkData = JSON.parse(event.data)
-    console.log('Received chunk:', chunk.type, chunk.text)
+import type {
+  ChunkData,
+  FetchChunksFunction,
+  NetworkResponse,
+  PaginatedResponse,
+  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,
+})
+
+// Type-safe connection state handler
+function onStatusChange(status: NatsConnectionStatus) {
+  if (status === 'reconnecting') {
+    console.warn('NATS reconnecting...')
   }
 }
 
-// Handle streaming responses
-const processChunk = (chunk: ChunkData) => {
-  if (chunk.type === 'tool_call' && chunk.toolFunction) {
-    return executeFunction(chunk.toolFunction, chunk.parameters)
-  }
-  return chunk.text
+// Typed chunk fetch implementation
+const fetchChunks: FetchChunksFunction = async (dialogId, chatType, fromSequenceId) => {
+  const res = await api.get<ChunkData[]>(`/dialogs/${dialogId}/chunks`, {
+    params: { chatType, from: fromSequenceId },
+  })
+  return res.data
 }
+
+// Paginated API response
+const response: PaginatedResponse<ChunkData[]> = await fetchPage(dialogId, 1)
+console.log(`Page ${response.page} of ${response.totalPages}`)
 ```

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

@@ -1,50 +1,68 @@
-<!-- source-hash: 66e8aa55f2252ec223d9953d34fa0194 -->
-TypeScript definitions for message processing and transformation, providing a complete type system for handling streaming chat messages, tool executions, approvals, and data transformations.
+<!-- 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.
 
 ## Key Components
 
-**Core Processing Types:**
-- `ParsedChunkAction` - Union type defining all possible chunk processing actions (text, tool execution, approvals, metadata)
-- `AccumulatorState` - State container tracking message segments, text buffers, and pending operations
-- `MessageProcessingOptions` - Configuration for message processing including assistant settings and approval callbacks
-
-**Processing Infrastructure:**
-- `ChunkProcessor` - Interface for processing individual data chunks with reset capability
-- `StreamProcessor` - Interface for managing streaming operations with lifecycle controls
-- `MessageTransformer` - Interface for converting raw data into processed messages
-
-**Buffer Management:**
-- `BufferManager` - Interface for managing chunk buffers with size limits and overflow handling
-- `BufferOptions` - Configuration for buffer behavior including flush intervals and callbacks
+| 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 |
 
 ## Usage Example
 
 ```typescript
-import type { MessageProcessingOptions, AccumulatorState } from './processing.types'
+import type {
+  ParsedChunkAction,
+  AccumulatorState,
+  MessageProcessingOptions,
+  StreamState
+} from './processing.types'
 
-// Configure message processing
-const options: MessageProcessingOptions = {
-  assistantName: 'Fae',
-  assistantType: 'fae',
-  onApprove: async (requestId) => {
-    await handleApproval(requestId, true)
-  },
-  displayApprovalTypes: ['COMMAND_EXECUTION', 'FILE_ACCESS']
+// Handling a parsed chunk action via discriminated union
+function handleChunkAction(action: ParsedChunkAction): void {
+  switch (action.action) {
+    case 'text':
+      console.log('Received text:', action.text)
+      break
+    case 'tool_execution':
+      console.log('Tool executing:', action.segment)
+      break
+    case 'approval_batch':
+      console.log('Batch approval request:', action.requestId, action.toolCalls)
+      break
+    case 'error':
+      console.error('Processing error:', action.error, action.details)
+      break
+  }
 }
 
-// Initialize accumulator state
+// Initializing accumulator state
 const state: AccumulatorState = {
   segments: [],
-  currentTextBuffer: '',
   pendingApprovals: new Map(),
   executingTools: new Map()
 }
 
-// Process chunk with type safety
-const processor: ChunkProcessor = {
-  processChunk: (chunk, type) => {
-    return { action: 'text', text: chunk.content }
+// Configuring message processing
+const options: MessageProcessingOptions = {
+  assistantName: 'Mingo',
+  assistantType: 'mingo',
+  batchApprovalsEnabled: true,
+  displayApprovalTypes: ['shell', 'file'],
+  onApprove: async (requestId) => {
+    await submitApproval(requestId)
   },
-  reset: () => state.segments = []
+  onReject: (requestId) => {
+    logRejection(requestId)
+  }
 }
 ```

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

@@ -0,0 +1,41 @@
+<!-- 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.

package/src/components/chat/types/entities/.blog.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 1be58b263102c7ac63390d5cdc4b8cba -->
+Re-exports blog entity types from the canonical `src/types/blog.ts` lib, providing a single import path for the chat card entity barrel.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `BlogPost` | Full blog post row shape |
+| `BlogPostSummary` | Catalog projection for listing/cards |
+| `BlogPostPlatform` | Platform identifier type |
+| `BlogPostCategory` | Post-level category association |
+| `BlogPostTag` | Post-level tag association |
+| `BlogCategory` | Blog category entity |
+| `BlogTag` | Blog tag entity |
+| `BlogAuthor` | Author entity shape |
+| `BlogMediaAsset` | Media/image asset type |
+| `BlogStatus` | Post status enum/union |
+| `BlogPagination` | Pagination metadata shape |
+| `BlogSearchParams` | Search/filter query params |
+
+## Usage Example
+
+```typescript
+// Import blog types from the entities barrel (single path)
+import type {
+  BlogPost,
+  BlogPostSummary,
+  BlogAuthor,
+  BlogPagination,
+} from '@/entities/blog';
+
+// Full post row (e.g. detail page)
+function renderPost(post: BlogPost) {
+  return `${post.title} by ${post.author.name}`;
+}
+
+// Summary projection (e.g. catalog card)
+function renderCard(summary: BlogPostSummary) {
+  return `${summary.title} — ${summary.category}`;
+}
+```
+
+> **Note:** Do not define competing blog shapes in the hub layer. Always consume from this barrel to ensure a single source of truth via `@/types/blog`.

package/src/components/chat/types/entities/.case-study.md

@@ -0,0 +1,26 @@
+<!-- source-hash: ef274b40abb94a68897a27d2ef3214c4 -->
+Re-exports `CaseStudy` entity types from the canonical lib definition (`src/types/case-study.ts`) into the chat card consumer barrel — no local type definitions are introduced.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `CaseStudy` | Core case study entity shape |
+| `CaseStudyFilters` | Filter parameters for querying case studies |
+| `CaseStudyListResponse` | Paginated/list response wrapper for case study results |
+
+## Usage Example
+
+```typescript
+import type { CaseStudy, CaseStudyFilters, CaseStudyListResponse } from '@/entities/case-study';
+
+const filters: CaseStudyFilters = { tag: 'networking' };
+
+const response: CaseStudyListResponse = await fetchCaseStudies(filters);
+
+response.items.forEach((study: CaseStudy) => {
+  console.log(study.title);
+});
+```
+
+> All types originate from `@/types/case-study` — this barrel acts as a stable re-export boundary so chat card consumers are decoupled from the underlying lib path.