@flamingo-stack/openframe-frontend-core 0.0.588 → 0.0.589-1973.5571.1

package/src/components/chat/remark-strip-citations.ts

@@ -22,13 +22,16 @@ import type { Plugin } from 'unified';
 import { visit } from 'unist-util-visit';
 
 const CITATION_REGEX = /(^|\s)\[\d{1,2}(?:\s*,\s*\d{1,2})*\](?=[\s.,;:!?)\]]|$)/g;
+const CITATION_LIST_REGEX =
+  /(^|\s)(?:\[\d{1,2}(?:\s*,\s*\d{1,2})*\]\s*,\s*)+(?:(?:and|or)\s+)?\[\d{1,2}(?:\s*,\s*\d{1,2})*\](?=[\s.,;:!?)\]]|$)/g;
 
 export const remarkStripCitations: Plugin<[], Root> = () => {
   return (tree: Root) => {
     visit(tree, 'text', (node: Text, index, parent) => {
       if (!parent || typeof index !== 'number') return;
       if (!node.value || !node.value.includes('[')) return;
-      const withoutCitations = node.value.replace(CITATION_REGEX, '$1');
+      const withoutCitationLists = node.value.replace(CITATION_LIST_REGEX, '$1');
+      const withoutCitations = withoutCitationLists.replace(CITATION_REGEX, '$1');
       // No citation matched → leave the node untouched, INCLUDING its
       // whitespace (collapsing unconditionally would rewrite deliberate
       // spacing in prose like `array[1]  value`).
@@ -41,8 +44,7 @@ export const remarkStripCitations: Plugin<[], Root> = () => {
       // leaf and moves on to the next sibling, never re-entering this slot.
       parent.children.splice(index, 1, {
         ...node,
-        // Collapse doubled spaces the removal can leave mid-sentence.
-        value: withoutCitations.replace(/ {2,}/g, ' '),
+        value: withoutCitations.replace(/\s+([.,;:!?])/g, '$1').replace(/ {2,}/g, ' '),
       });
     });
   };

package/src/components/chat/stream/__tests__/chat-stream-reducer.test.ts

@@ -1289,3 +1289,59 @@ describe('createChatStreamReducer — ask cards', () => {
     expect(last.segments?.map(s => s.type)).toEqual(['ask', 'ask']);
   });
 });
+
+describe('createChatStreamReducer — Mingo source metadata', () => {
+  const sources = [
+    {
+      index: 1,
+      name: 'Enroll devices',
+      path: 'docs/enroll.md',
+      documentType: 'markdown',
+    },
+  ];
+
+  it('attaches metadata received before text to the same assistant turn', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' });
+    const refs = [
+      {
+        type: 'video',
+        id: 'mux-9b6586b494',
+        title: 'Community demo',
+        url: 'https://stream.mux.com/playback-id.m3u8',
+        metadata: { videoUrl: 'https://stream.mux.com/playback-id.m3u8' },
+      },
+    ];
+
+    reducer.apply({ type: 'turn-start', seq: 1 });
+    reducer.apply({ type: 'sources', sources, refs, seq: 2 });
+    reducer.apply({ type: 'text-delta', text: 'Follow the guide [1].', seq: 3 });
+
+    expect(reducer.state.messages).toHaveLength(1);
+    expect(reducer.state.messages[0]).toMatchObject({ sources, refs });
+  });
+
+  it('deduplicates cumulative metadata and does not leak it into the next turn', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' });
+
+    reducer.apply({ type: 'turn-start', seq: 1 });
+    reducer.apply({ type: 'sources', sources, seq: 2 });
+    reducer.apply({
+      type: 'sources',
+      sources: [
+        { ...sources[0], name: 'Duplicate' },
+        { index: 2, name: 'Install agent', path: 'docs/install.md', documentType: 'markdown' },
+      ],
+      seq: 3,
+    });
+    reducer.apply({ type: 'text-delta', text: 'First answer [1] [2].', seq: 4 });
+    reducer.apply({ type: 'turn-end', seq: 5 });
+    reducer.apply({ type: 'turn-start', seq: 6 });
+    reducer.apply({ type: 'text-delta', text: 'Second answer.', seq: 7 });
+
+    expect(reducer.state.messages[0].sources).toEqual([
+      sources[0],
+      { index: 2, name: 'Install agent', path: 'docs/install.md', documentType: 'markdown' },
+    ]);
+    expect(reducer.state.messages[1].sources).toBeUndefined();
+  });
+});

package/src/components/chat/stream/chat-stream-reducer.ts

@@ -60,6 +60,7 @@ import {
   type ParticipantEvent,
   type UsageEvent,
 } from '../../../chat-protocol/events';
+import type { ChatRef } from '../chat-ref.types';
 import type {
   ApprovalBatchSegment,
   ApprovalRequestSegment,
@@ -70,6 +71,7 @@ import type {
   ToolExecutionSegment,
   ExecutingToolState,
 } from '../types';
+import type { ChatSource } from '../types/message.types';
 import type { PendingApproval } from '../types/processing.types';
 import type {
   DialogTokenUsage,
@@ -78,6 +80,7 @@ import type {
   UnifiedUsageBreakdown,
 } from '../types/unified-chat-state.types';
 import { approvalDisplaysInline } from '../utils/approval-display';
+import { mergeChatRefs, mergeChatSources } from '../utils/chat-source-metadata';
 import {
   type MessageSegmentAccumulator,
   createMessageSegmentAccumulator,
@@ -676,6 +679,9 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
   let sendCount = 0;
   let sseCurrentText = '';
 
+  let pendingSources: ChatSource[] | undefined;
+  let pendingRefs: ChatRef[] | undefined;
+
   // ── Snapshot cache ─────────────────────────────────────────────────────
   let stateCache: ChatReducerState | null = null;
   function invalidate(): void {
@@ -773,6 +779,18 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
     setMessagesInternal(stampTrailingAssistantSeq(updateTrailingAssistant(messages, segments), seq));
   }
 
+  function attachPendingSourceMetadata(): void {
+    if (!pendingSources && !pendingRefs) return;
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== 'assistant') return;
+    const next = {
+      ...last,
+      ...(pendingSources ? { sources: pendingSources } : {}),
+      ...(pendingRefs ? { refs: pendingRefs } : {}),
+    };
+    setMessagesInternal([...messages.slice(0, -1), next]);
+  }
+
   function applyStreamStartToState(): void {
     setPhaseInternal('streaming');
     // A new stream must never overwrite a COMPLETED trailing assistant
@@ -966,6 +984,8 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
 
     switch (event.type) {
       case 'turn-start': {
+        pendingSources = undefined;
+        pendingRefs = undefined;
         isInStream = true;
         hasEverStreamed = true;
         turnStartedAt = Date.now();
@@ -981,6 +1001,15 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
         emit('onStreamEnd');
         setPhaseInternal('idle');
         accumulator.resetSegments();
+        pendingSources = undefined;
+        pendingRefs = undefined;
+        break;
+      }
+
+      case 'sources': {
+        pendingSources = mergeChatSources(pendingSources, event.sources);
+        if (event.refs) pendingRefs = mergeChatRefs(pendingRefs, event.refs);
+        attachPendingSourceMetadata();
         break;
       }
 
@@ -1017,10 +1046,12 @@ export function createChatStreamReducer(options: ChatStreamReducerOptions = {}):
         if (isInStream || !hasEverStreamed) {
           emitSegments(segments);
           applySegmentsToState(segments, withSeqMeta(undefined));
+          attachPendingSourceMetadata();
         } else {
           const delta: MessageSegment[] = [{ type: kind, text: event.text }];
           emitSegments(delta, { append: true });
           applySegmentsToState(delta, withSeqMeta({ append: true }));
+          attachPendingSourceMetadata();
         }
         break;
       }

package/src/components/chat/tool-execution-display.tsx

@@ -54,6 +54,9 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
 
     const hasResult = isExecuted && typeof message.result === 'string' && message.result.length > 0;
     const hasBody = argEntries.length > 0 || hasResult || isExecuting;
+    const isConciseRemoteRead =
+      !message.integratedToolType && !!message.toolTitle?.trim() && argEntries.length === 0 && !hasResult;
+    const isStaticRow = isClientView || isConciseRemoteRead;
 
     const renderStatusIcon = () => {
       if (isExecuting) return <DotsLoaderIcon size={16} className="text-ods-text-secondary" />;
@@ -82,7 +85,7 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
           {previewText}
         </div>
         <div className="flex h-5 w-5 shrink-0 items-center justify-center">{renderStatusIcon()}</div>
-        {!isClientView && (
+        {!isStaticRow && (
           <div className="flex h-5 w-5 shrink-0 items-center justify-center">
             <ExpandChevron expanded={expanded} />
           </div>
@@ -101,7 +104,7 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
         )}
         {...props}
       >
-        {isClientView ? (
+        {isStaticRow ? (
           // Client (Fae end-user): static, non-expandable row — no chevron, no
           // body. Just the explanation + status; command/args/result are hidden.
           <div className="flex w-full items-start gap-[var(--spacing-system-xs)] p-[var(--spacing-system-s)] text-left">

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

@@ -195,6 +195,8 @@ export interface ChatMessageEnhancedProps extends Omit<HTMLAttributes<HTMLDivEle
    * back to plain text title-only.
    */
   renderEntityCard?: (reference: ChatRef) => ReactNode;
+  /** Enriched references associated with this assistant answer. */
+  refs?: ChatRef[];
   /**
    * Host-provided anchor component for markdown links. When supplied, the
    * `<a>` override in the markdown renderer delegates to this component
@@ -304,6 +306,8 @@ export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
    *  ChatMessageEnhanced; the host sends the received label as the user's next
    *  message. Omit to render ask cards read-only. */
   onAskSelect?: (label: string) => void;
+  /** Renders content owned by one message directly after that message. */
+  renderAfterMessage?: (message: Message, index: number) => ReactNode;
 }
 
 export interface ChatMessageListRef {

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,

package/src/components/ui/hover-dropdown.tsx

@@ -106,6 +106,7 @@ export function HoverDropdown({
 }: HoverDropdownProps) {
   const [open, setOpen] = useState(false);
   const timeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const clickPinnedRef = useRef(false);
   const containerRef = useRef<HTMLDivElement>(null);
   const panelRef = useRef<HTMLDivElement>(null);
 
@@ -156,18 +157,22 @@ export function HoverDropdown({
   }, []);
 
   const hide = useCallback(() => {
+    if (clickPinnedRef.current) return;
     timeoutRef.current = setTimeout(() => setOpen(false), hideDelay);
   }, [hideDelay]);
 
   // Click handler — touch / mobile (no hover) + desktop users who
-  // expect clicking a chip to open a menu. Toggles the dropdown state
-  // so a second click closes it. `stopPropagation` prevents the click
+  // expect clicking a chip to open a menu. The first desktop click can arrive
+  // after mouse-enter already opened the panel; pin it open instead of blindly
+  // toggling it closed. A second click closes it. `stopPropagation` prevents the click
   // from bubbling to ancestor handlers (the chip's parent message
   // bubble shouldn't react to chip clicks).
   const toggle = useCallback((e: React.MouseEvent) => {
     e.stopPropagation();
     clearTimeout(timeoutRef.current);
-    setOpen(prev => !prev);
+    const pinned = !clickPinnedRef.current;
+    clickPinnedRef.current = pinned;
+    setOpen(pinned);
   }, []);
 
   // Every hook is above this line: an `items` list that goes from empty to