@flamingo-stack/openframe-frontend-core 0.0.583 → 0.0.584-1973.5420.1

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

@@ -3,6 +3,7 @@
  * Contains all message structures, segments, and content types
  */
 
+import type { ChatRef } from '../chat-ref.types';
 import type { AssistantType, AuthorType, ChatApprovalStatus, MessageOwner } from './chat.types';
 
 // ========== Message Type Definitions ==========
@@ -10,6 +11,8 @@ import type { AssistantType, AuthorType, ChatApprovalStatus, MessageOwner } from
 export const MESSAGE_TYPE = {
   TEXT: 'TEXT',
   THINKING: 'THINKING',
+  GUIDE: 'GUIDE',
+  SOURCES: 'SOURCES',
   ASK: 'ASK',
   EXECUTING_TOOL: 'EXECUTING_TOOL',
   EXECUTED_TOOL: 'EXECUTED_TOOL',
@@ -46,6 +49,26 @@ export const SCROLL_ANCHOR = { TOP: 'top', BOTTOM: 'bottom' } as const;
 
 export type ScrollAnchor = (typeof SCROLL_ANCHOR)[keyof typeof SCROLL_ANCHOR];
 
+export interface ChatSource {
+  index: number;
+  name: string;
+  path: string;
+  documentType: string;
+  externalUrl?: string;
+  targetPlatform?: string | null;
+  id?: string;
+  items?: Array<{
+    id: string;
+    documentType: string;
+    name: string;
+    externalUrl?: string;
+    targetPlatform?: string | null;
+    path?: string | null;
+  }>;
+  sourceRepo?: string;
+  label?: string;
+}
+
 // ========== Tool Execution Types ==========
 
 export interface ToolExecutionData {
@@ -391,6 +414,16 @@ export interface ThinkingMessageData extends MessageDataBase {
   text?: string;
 }
 
+export interface GuideMessageData extends MessageDataBase {
+  type: 'GUIDE';
+  payload?: Record<string, unknown>;
+}
+
+export interface SourcesMessageData extends MessageDataBase {
+  type: 'SOURCES';
+  payload?: Record<string, unknown>;
+}
+
 /** Persisted `ASK` row (GraphQL `AskData`). `text` is the intro sentence, which
  *  history replays as a text segment ahead of the card — same split the live
  *  `ASK` chunk carries. */
@@ -532,6 +565,8 @@ export interface ContextCompactionEndMessageData extends MessageDataBase {
 export type MessageData =
   | TextMessageData
   | ThinkingMessageData
+  | GuideMessageData
+  | SourcesMessageData
   | AskMessageData
   | ExecutingToolMessageData
   | ExecutedToolMessageData
@@ -576,6 +611,8 @@ export interface ProcessedMessage {
   authorType?: AuthorType;
   timestamp: Date;
   avatar?: string;
+  sources?: ChatSource[];
+  refs?: ChatRef[];
   /** Persisted last-chunk stream sequence carried through from
    *  `HistoricalMessage.lastChunkStreamSeq` (for assistant turns: the MAX
    *  across the grouped rows). Hosts stamp it onto the rendered message's
@@ -598,6 +635,8 @@ export interface Message {
   authorType?: AuthorType;
   timestamp?: Date;
   avatar?: string | null;
+  sources?: ChatSource[];
+  refs?: ChatRef[];
   /** Highest CONTENT chunk streamSeq that composed this message. Stamped on
    *  realtime synthetics so `mergeHistoryWithRealtime` can decide history
    *  coverage per-message (see `MergeableChatMessage.streamSeq`). */

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

@@ -17,12 +17,11 @@
  */
 
 import type { ChatRef } from '../chat-ref.types';
-import type { ChatSource } from '../hooks/use-sse-chat-adapter';
 import type { ChatAttachment } from '../utils/chat-attachment-markdown';
 import type { AuthorType } from './chat.types';
 import type { DialogItem } from './component.types';
 import type { ChatContextItem } from './context-item.types';
-import type { MessageSegment, ScrollAnchor } from './message.types';
+import type { ChatSource, MessageSegment, ScrollAnchor } from './message.types';
 
 // ─── Per-dialog token usage (Mingo backend telemetry) ────────────────────────
 
@@ -169,9 +168,11 @@ export interface UnifiedChatMessage {
    */
   timestamp?: Date | string | number;
 
-  /** Guide/SSE-only: document citations. Undefined in Mingo mode. */
+  /** Document citations for a Guide answer over SSE or NATS. */
   sources?: ChatSource[];
 
+  refs?: ChatRef[];
+
   /**
    * Per-message viewport-positioning hint. Common to both modes; the
    * message-list reads it to override default tail-on-stream behaviour

package/src/components/chat/utils/__tests__/process-historical-messages-golden.test.ts

@@ -391,3 +391,60 @@ describe('processHistoricalMessages — ASK rows', () => {
     expect(processHistoricalMessages(dialog).messages).toEqual([]);
   });
 });
+
+describe('processHistoricalMessages — Mingo source metadata', () => {
+  it.each(['GUIDE', 'SOURCES'] as const)('restores %s metadata on the same assistant turn', type => {
+    const dialog: HistoricalMessage[] = [
+      {
+        id: 'a1',
+        chatType: 'ADMIN_AI_CHAT',
+        createdAt: '2026-07-19T09:00:05Z',
+        owner: { type: 'ASSISTANT' },
+        messageData: [
+          {
+            type,
+            payload: {
+              sources: [
+                {
+                  index: 1,
+                  name: 'Install agent',
+                  path: 'docs/install.md',
+                  documentType: 'markdown',
+                },
+              ],
+              videos: [
+                {
+                  ref: '[card://video:mux-9b6586b494]',
+                  title: 'Community demo',
+                  url: 'https://stream.mux.com/playback-id.m3u8',
+                  metadata: { videoUrl: 'https://stream.mux.com/playback-id.m3u8' },
+                },
+              ],
+            },
+          },
+          { type: 'TEXT', text: 'Install the agent [1]. [card://video:mux-9b6586b494]' },
+        ],
+      },
+    ];
+
+    expect(processHistoricalMessages(dialog).messages[0]).toMatchObject({
+      role: 'assistant',
+      sources: [
+        {
+          index: 1,
+          name: 'Install agent',
+          path: 'docs/install.md',
+          documentType: 'markdown',
+        },
+      ],
+      refs: [
+        {
+          type: 'video',
+          id: 'mux-9b6586b494',
+          metadata: { videoUrl: 'https://stream.mux.com/playback-id.m3u8' },
+        },
+      ],
+      content: [{ type: 'text', text: 'Install the agent [1]. [card://video:mux-9b6586b494]' }],
+    });
+  });
+});

package/src/components/chat/utils/chat-source-metadata.ts

@@ -0,0 +1,19 @@
+import type { ChatRef } from '../chat-ref.types';
+import type { ChatSource } from '../types/message.types';
+
+export function mergeChatSources(current: ChatSource[] | undefined, incoming: ChatSource[]): ChatSource[] {
+  const sourcesByIndex = new Map((current ?? []).map(source => [source.index, source]));
+  incoming.forEach(source => {
+    if (!sourcesByIndex.has(source.index)) sourcesByIndex.set(source.index, source);
+  });
+  return Array.from(sourcesByIndex.values());
+}
+
+export function mergeChatRefs(current: ChatRef[] | undefined, incoming: ChatRef[]): ChatRef[] {
+  const refsByIdentity = new Map((current ?? []).map(ref => [`${ref.type}:${ref.id}`, ref]));
+  incoming.forEach(ref => {
+    const identity = `${ref.type}:${ref.id}`;
+    if (!refsByIdentity.has(identity)) refsByIdentity.set(identity, ref);
+  });
+  return Array.from(refsByIdentity.values());
+}

package/src/components/chat/utils/process-historical-messages.ts

@@ -33,7 +33,8 @@ import {
 } from '../../../chat-protocol/events';
 // One normalizer for ask rows, shared with the live decoder — history and the
 // stream must agree on which options are usable.
-import { normalizeAskOptions } from '../../../chat-protocol/nats-decoder';
+import { decodeNatsChunk, normalizeAskOptions } from '../../../chat-protocol/nats-decoder';
+import type { ChatRef } from '../chat-ref.types';
 import { applyApprovalStatusToSegment } from '../stream/message-mutations';
 import {
   MESSAGE_TYPE,
@@ -46,8 +47,10 @@ import {
   type MessageProcessingOptions,
   type MessageData,
   type MessageOwner,
+  type ChatSource,
 } from '../types';
 import { approvalDisplaysInline } from './approval-display';
+import { mergeChatRefs, mergeChatSources } from './chat-source-metadata';
 import { type MessageSegmentAccumulator, createMessageSegmentAccumulator } from './message-segment-accumulator';
 import { getCommandText } from './tool-call-helpers';
 
@@ -121,6 +124,10 @@ export function decodeHistoricalMessageData(data: MessageData): ChatStreamEvent
       }
       return null;
 
+    case MESSAGE_TYPE.GUIDE:
+    case MESSAGE_TYPE.SOURCES:
+      return decodeNatsChunk({ type: data.type, payload: data.payload });
+
     // Same completeness gate as the live decoder (`decodeNatsChunk`): a
     // persisted row without a question or without options is not a card the
     // user can answer, so it replays as nothing rather than as empty chrome.
@@ -591,6 +598,8 @@ export function processHistoricalMessages(
   // MAX persisted seq across the rows grouped into the current assistant turn
   // — carried onto the flushed message's streamSeq for per-role merge coverage.
   let currentAssistantStreamSeq: number | undefined;
+  let currentAssistantSources: ChatSource[] | undefined;
+  let currentAssistantRefs: ChatRef[] | undefined;
 
   /**
    * Flush the current assistant message to processedMessages.
@@ -608,6 +617,8 @@ export function processHistoricalMessages(
         authorType: assistantType,
         timestamp: currentAssistantTimestamp || new Date(),
         avatar: assistantAvatar,
+        ...(currentAssistantSources ? { sources: currentAssistantSources } : {}),
+        ...(currentAssistantRefs ? { refs: currentAssistantRefs } : {}),
         ...(currentAssistantStreamSeq !== undefined ? { streamSeq: currentAssistantStreamSeq } : {}),
       });
       accumulator.resetSegments();
@@ -623,6 +634,8 @@ export function processHistoricalMessages(
     currentAssistantTimestamp = null;
     lastAssistantId = null;
     currentAssistantStreamSeq = undefined;
+    currentAssistantSources = undefined;
+    currentAssistantRefs = undefined;
   };
 
   messages.forEach((msg, index) => {
@@ -689,6 +702,11 @@ export function processHistoricalMessages(
       messageDataArray.forEach(data => {
         const event = decodeHistoricalMessageData(data);
         if (!event) return;
+        if (event.type === 'sources') {
+          currentAssistantSources = mergeChatSources(currentAssistantSources, event.sources);
+          if (event.refs) currentAssistantRefs = mergeChatRefs(currentAssistantRefs, event.refs);
+          return;
+        }
         applyHistoryEvent(
           event,
           accumulator,