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

package/src/components/chat/__tests__/embeddable-chat-sources.test.tsx

@@ -0,0 +1,411 @@
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { decodeNatsChunk } from '../../../chat-protocol/nats-decoder';
+import { type ChatRuntime, ChatRuntimeContext } from '../../../contexts/chat-runtime-context';
+import { EmbeddableChat } from '../embeddable-chat';
+import { createChatStreamReducer } from '../stream/chat-stream-reducer';
+import type { UnifiedChatMessage, UnifiedChatState } from '../types/unified-chat-state.types';
+
+vi.mock('@mux/mux-player-react', () => ({
+  default: ({ src }: { src?: string }) => <div data-testid="mux-player" data-src={src} />,
+}));
+
+const runtime: ChatRuntime = {
+  endpoints: {
+    chatStreamUrl: '/test/chat',
+    approvalToolUrl: '/test/approve',
+    commandsUrl: '/test/commands',
+    buildListUrl: () => null,
+    attachmentUploadUrl: '/test/upload',
+    attachmentViewUrlPrefix: '/test/view/',
+    identityUrl: '/test/identity',
+  },
+  navigation: { mode: 'host' },
+  source: 'openframe',
+};
+
+function stateFor(messages: UnifiedChatMessage[]): UnifiedChatState {
+  const noop = () => {};
+  const asyncNoop = async () => {};
+  return {
+    messages,
+    isLoading: false,
+    streamingPhase: 'idle',
+    sendMessage: asyncNoop,
+    stopMessage: noop,
+    clearMessages: noop,
+    discussRef: noop,
+    displayRef: noop,
+    currentProvider: null,
+    currentModelLabel: null,
+    currentContextWindowMaxTokens: null,
+    currentInputTokens: null,
+    currentOutputTokens: null,
+    currentCacheHitRatePct: null,
+    currentUsageBreakdown: null,
+    dialogs: [{ id: 'dialog-1', title: 'Sources' }],
+    activeDialogId: 'dialog-1',
+    selectDialog: noop,
+    startNewDialog: () => Promise.resolve(null),
+    deleteDialog: asyncNoop,
+    renameDialog: asyncNoop,
+    archiveDialog: asyncNoop,
+    isDialogsLoading: false,
+    dialogsError: false,
+    reloadDialogs: noop,
+    isMessagesLoading: false,
+    hasMoreDialogs: false,
+    loadMoreDialogs: asyncNoop,
+    hasMoreMessages: false,
+    loadMoreMessages: asyncNoop,
+    approveRequest: asyncNoop,
+    rejectRequest: asyncNoop,
+    dialogTokenUsage: null,
+    connectionState: 'connected',
+  };
+}
+
+function renderChat(messages: UnifiedChatMessage[]) {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ChatRuntimeContext.Provider value={runtime}>
+        <DialogPrimitive.Root open>
+          <EmbeddableChat
+            shell="none"
+            defaultOpen
+            defaultActiveMode="mingo"
+            showInternalTrigger={false}
+            previewMode
+            mingoState={stateFor(messages)}
+          />
+        </DialogPrimitive.Root>
+      </ChatRuntimeContext.Provider>
+    </QueryClientProvider>,
+  );
+}
+
+beforeAll(() => {
+  vi.stubGlobal('matchMedia', () => ({
+    matches: false,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  }));
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      observe(): void {}
+      disconnect(): void {}
+      unobserve(): void {}
+    },
+  );
+  vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+    new Response(JSON.stringify({ commands: [] }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    }),
+  );
+});
+
+afterAll(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe('EmbeddableChat source strip', () => {
+  it('keeps sources attached to their assistant turn after later messages', () => {
+    renderChat([
+      {
+        id: 'assistant-1',
+        role: 'assistant',
+        content: 'Use the first guide [1].',
+        sources: [
+          {
+            index: 1,
+            name: 'First turn source',
+            path: 'docs/first',
+            documentType: 'docs',
+          },
+        ],
+      },
+      {
+        id: 'assistant-2',
+        role: 'assistant',
+        content: 'Use the second guide [1].',
+        sources: [
+          {
+            index: 1,
+            name: 'Second turn source',
+            path: 'docs/second',
+            documentType: 'docs',
+          },
+        ],
+      },
+      {
+        id: 'assistant-3',
+        role: 'assistant',
+        content: 'Here is a plain follow-up answer.',
+      },
+    ]);
+
+    expect(screen.getByText('[1] First turn source')).toBeInTheDocument();
+    expect(screen.getByText('[1] Second turn source')).toBeInTheDocument();
+  });
+
+  it('renders live SOURCES metadata in citation order with uncited overflow', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' });
+    for (const chunk of [
+      { type: 'MESSAGE_START', streamSeq: 1 },
+      {
+        type: 'SOURCES',
+        payload: {
+          sources: [
+            { index: 1, name: 'First source', path: 'first', documentType: 'docs' },
+            { index: 2, name: 'Second source', path: 'second', documentType: 'docs' },
+            { index: 3, name: 'Third source', path: 'third', documentType: 'docs' },
+            { index: 4, name: 'Fourth source', path: 'fourth', documentType: 'docs' },
+          ],
+          videos: [
+            {
+              ref: '[card://video:mux-9b6586b494]',
+              title: 'Product overview',
+              url: 'https://stream.mux.com/product-overview.m3u8',
+            },
+          ],
+        },
+        streamSeq: 2,
+      },
+      {
+        type: 'TEXT',
+        text:
+          'Compare the third source [3] with the first [1] and cite [3] once. ' +
+          'Watch [card://video:mux-9b6586b494].',
+        streamSeq: 3,
+      },
+      { type: 'MESSAGE_END', streamSeq: 4 },
+    ]) {
+      const event = decodeNatsChunk(chunk);
+      if (event) reducer.apply(event);
+    }
+
+    renderChat(reducer.state.messages);
+
+    const chips = screen.getAllByTitle(/source$/i);
+    expect(chips.map(chip => chip.textContent)).toEqual(['[3] Third source', '[1] First source']);
+    expect(screen.queryByText('[2] Second source')).not.toBeInTheDocument();
+    const expander = screen.getByRole('button', { name: 'Show 2 additional retrieved sources' });
+    expect(expander).toHaveTextContent('+2 more retrieved sources');
+
+    fireEvent.click(expander);
+
+    expect(screen.getByText('[2] Second source')).toBeInTheDocument();
+    expect(screen.getByText('[4] Fourth source')).toBeInTheDocument();
+    expect(screen.getByTestId('mux-player')).toHaveAttribute(
+      'data-src',
+      'https://stream.mux.com/product-overview.m3u8',
+    );
+  });
+
+  it('keeps every uncited source accessible behind the top-three fallback', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' });
+    for (const chunk of [
+      { type: 'MESSAGE_START', streamSeq: 1 },
+      {
+        type: 'SOURCES',
+        payload: {
+          sources: Array.from({ length: 5 }, (_, index) => ({
+            index: index + 1,
+            name: `Source ${index + 1}`,
+            path: `source-${index + 1}`,
+            documentType: 'docs',
+          })),
+        },
+        streamSeq: 2,
+      },
+      { type: 'TEXT', text: 'Here are the relevant materials.', streamSeq: 3 },
+      { type: 'MESSAGE_END', streamSeq: 4 },
+    ]) {
+      const event = decodeNatsChunk(chunk);
+      if (event) reducer.apply(event);
+    }
+
+    renderChat(reducer.state.messages);
+
+    expect(screen.getByText('[1] Source 1')).toBeInTheDocument();
+    expect(screen.getByText('[3] Source 3')).toBeInTheDocument();
+    expect(screen.queryByText('[4] Source 4')).not.toBeInTheDocument();
+
+    const expander = screen.getByRole('button', { name: 'Show 2 additional retrieved sources' });
+    fireEvent.click(expander);
+
+    expect(screen.getByText('[4] Source 4')).toBeInTheDocument();
+    expect(screen.getByText('[5] Source 5')).toBeInTheDocument();
+  });
+
+  it('renders a markdown card from matching source metadata when hydration is unavailable', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' });
+    for (const chunk of [
+      { type: 'MESSAGE_START', streamSeq: 1 },
+      {
+        type: 'SOURCES',
+        payload: {
+          sources: [
+            {
+              index: 1,
+              id: 'install-agent',
+              name: 'Install the OpenFrame agent on Windows',
+              path: 'getting-started/install-agent.md',
+              documentType: 'markdown',
+              sourceRepo: 'openframe-docs',
+            },
+          ],
+          cards: [
+            {
+              ref: '[card://markdown:install-agent]',
+              entityType: 'markdown',
+              entityId: 'install-agent',
+            },
+          ],
+        },
+        streamSeq: 2,
+      },
+      {
+        type: 'TEXT',
+        text: 'Follow [card://markdown:install-agent].',
+        streamSeq: 3,
+      },
+      { type: 'MESSAGE_END', streamSeq: 4 },
+    ]) {
+      const event = decodeNatsChunk(chunk);
+      if (event) reducer.apply(event);
+    }
+
+    renderChat(reducer.state.messages);
+
+    expect(screen.getByText('Install the OpenFrame agent on Windows')).toBeInTheDocument();
+    expect(screen.queryByText('FAILED')).not.toBeInTheDocument();
+  });
+
+  it('renders a matched source card when its display name equals its id', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' });
+    for (const chunk of [
+      { type: 'MESSAGE_START', streamSeq: 1 },
+      {
+        type: 'SOURCES',
+        payload: {
+          sources: [
+            {
+              index: 1,
+              id: 'install-agent',
+              name: 'install-agent',
+              path: 'getting-started/install-agent.md',
+              documentType: 'markdown',
+            },
+          ],
+          cards: [
+            {
+              ref: '[card://markdown:install-agent]',
+              entityType: 'markdown',
+              entityId: 'install-agent',
+            },
+          ],
+        },
+        streamSeq: 2,
+      },
+      { type: 'TEXT', text: 'Follow [card://markdown:install-agent].', streamSeq: 3 },
+      { type: 'MESSAGE_END', streamSeq: 4 },
+    ]) {
+      const event = decodeNatsChunk(chunk);
+      if (event) reducer.apply(event);
+    }
+
+    renderChat(reducer.state.messages);
+
+    expect(screen.getAllByText('install-agent').length).toBeGreaterThan(0);
+    expect(screen.queryByText('FAILED')).not.toBeInTheDocument();
+  });
+
+  it('does not treat an arbitrary enriched ref as matched source metadata', () => {
+    renderChat([
+      {
+        id: 'assistant-1',
+        role: 'assistant',
+        content: 'Follow [card://markdown:unmatched-doc].',
+        refs: [
+          {
+            type: 'markdown',
+            id: 'unmatched-doc',
+            title: 'Plausible but unmatched document',
+            url: null,
+            metadata: { path: 'docs/unmatched.md' },
+          },
+        ],
+      },
+    ]);
+
+    expect(screen.getByText('FAILED')).toBeInTheDocument();
+    expect(screen.queryByText('Plausible but unmatched document')).not.toBeInTheDocument();
+  });
+
+  it('opens every item carried by a grouped source', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' });
+    for (const chunk of [
+      { type: 'MESSAGE_START', streamSeq: 1 },
+      {
+        type: 'SOURCES',
+        payload: {
+          sources: [
+            {
+              index: 1,
+              name: 'Case Studies (3 records)',
+              path: 'case-studies',
+              documentType: 'case-study',
+              items: [
+                {
+                  id: 'case-study-1',
+                  name: 'Northstar MSP',
+                  path: 'case-studies/northstar',
+                  documentType: 'case-study',
+                },
+                {
+                  id: 'case-study-2',
+                  name: 'Blue Harbor IT',
+                  path: 'case-studies/blue-harbor',
+                  documentType: 'case-study',
+                },
+                {
+                  id: 'case-study-3',
+                  name: 'Summit Technology',
+                  path: 'case-studies/summit',
+                  documentType: 'case-study',
+                },
+              ],
+            },
+          ],
+        },
+        streamSeq: 2,
+      },
+      { type: 'TEXT', text: 'Here are three customer stories [1].', streamSeq: 3 },
+      { type: 'MESSAGE_END', streamSeq: 4 },
+    ]) {
+      const event = decodeNatsChunk(chunk);
+      if (event) reducer.apply(event);
+    }
+
+    renderChat(reducer.state.messages);
+
+    const groupedSource = screen.getByText('[1] Case Studies (3 records)');
+    fireEvent.mouseEnter(groupedSource);
+    fireEvent.click(groupedSource);
+
+    expect(screen.getByText('Northstar MSP')).toBeInTheDocument();
+    expect(screen.getByText('Blue Harbor IT')).toBeInTheDocument();
+    expect(screen.getByText('Summit Technology')).toBeInTheDocument();
+
+    fireEvent.click(groupedSource);
+
+    expect(screen.queryByText('Northstar MSP')).not.toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,52 @@
+import type { Root } from 'mdast';
+import { unified } from 'unified';
+import { describe, expect, it } from 'vitest';
+import { remarkStripCitations } from '../remark-strip-citations';
+
+describe('remarkStripCitations', () => {
+  it('removes a citation-only list without leaving broken punctuation', () => {
+    const tree: Root = {
+      type: 'root',
+      children: [
+        {
+          type: 'paragraph',
+          children: [{ type: 'text', value: 'Sources [1], [2], and [3] are cited.' }],
+        },
+      ],
+    };
+
+    const result = unified().use(remarkStripCitations).runSync(tree);
+
+    expect(result).toMatchObject({
+      children: [
+        {
+          children: [{ type: 'text', value: 'Sources are cited.' }],
+        },
+      ],
+    });
+  });
+
+  it('keeps prose punctuation while removing individual citations', () => {
+    const tree: Root = {
+      type: 'root',
+      children: [
+        {
+          type: 'paragraph',
+          children: [
+            { type: 'text', value: 'Install on Windows [1], verify the service [2], and confirm Devices [3].' },
+          ],
+        },
+      ],
+    };
+
+    const result = unified().use(remarkStripCitations).runSync(tree);
+
+    expect(result).toMatchObject({
+      children: [
+        {
+          children: [{ type: 'text', value: 'Install on Windows, verify the service, and confirm Devices.' }],
+        },
+      ],
+    });
+  });
+});

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

@@ -0,0 +1,93 @@
+import { render, screen } from '@testing-library/react';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { decodeNatsChunk } from '../../../chat-protocol/nats-decoder';
+import { createChatStreamReducer } from '../stream/chat-stream-reducer';
+import { ToolExecutionDisplay } from '../tool-execution-display';
+import type { ToolExecutionData } from '../types';
+
+const execution = (overrides: Partial<ToolExecutionData>): ToolExecutionData => ({
+  type: 'EXECUTING_TOOL',
+  integratedToolType: 'OPENFRAME',
+  toolFunction: 'search_docs',
+  ...overrides,
+});
+
+beforeAll(() => {
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      observe(): void {}
+      disconnect(): void {}
+      unobserve(): void {}
+    },
+  );
+});
+
+afterAll(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('ToolExecutionDisplay remote read activity', () => {
+  it('keeps a completed remote read concise through the real wire pipeline', () => {
+    const reducer = createChatStreamReducer({ transport: 'nats' });
+    for (const chunk of [
+      {
+        type: 'EXECUTING_TOOL',
+        integratedToolType: null,
+        toolFunction: 'remote_read',
+        title: 'Searching product documentation',
+        parameters: null,
+        toolExecutionRequestId: 'remote-read-1',
+      },
+      {
+        type: 'EXECUTED_TOOL',
+        integratedToolType: null,
+        toolFunction: 'remote_read',
+        result: null,
+        success: true,
+        toolExecutionRequestId: 'remote-read-1',
+      },
+    ]) {
+      const event = decodeNatsChunk(chunk);
+      if (event) reducer.apply(event);
+    }
+    const toolSegment = reducer.state.messages
+      .flatMap(message => message.segments ?? [])
+      .find(segment => segment.type === 'tool_execution');
+
+    expect(toolSegment?.type).toBe('tool_execution');
+    if (toolSegment?.type !== 'tool_execution') return;
+    render(<ToolExecutionDisplay message={toolSegment.data} />);
+
+    expect(screen.getByText('Searching product documentation')).toBeInTheDocument();
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+    expect(screen.queryByText('Remote read')).not.toBeInTheDocument();
+  });
+
+  it('keeps a typed local tool expandable when its body is absent', () => {
+    render(
+      <ToolExecutionDisplay
+        message={execution({
+          integratedToolType: 'OPENFRAME',
+          toolTitle: 'Refresh device inventory',
+        })}
+      />,
+    );
+
+    expect(screen.getByRole('button')).toBeInTheDocument();
+  });
+
+  it('keeps a backend-described remote read concise while running', () => {
+    render(
+      <ToolExecutionDisplay
+        message={execution({
+          integratedToolType: undefined,
+          toolTitle: 'Searching product documentation',
+        })}
+      />,
+    );
+
+    expect(screen.getByText('Searching product documentation')).toBeInTheDocument();
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+  });
+});

package/src/components/chat/chat-message-enhanced.tsx

@@ -103,6 +103,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
       renderContextItem,
       renderMention,
       renderEntityCard,
+      refs,
       onAskSelect,
       NavLinkAnchor,
       ...props
@@ -127,6 +128,11 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
     // literal `[card://...]` URL.
     const hasMarkerSupport = !!renderEntityCard;
 
+    const refsByKey = useMemo(
+      () => new Map((refs ?? []).map(reference => [`${reference.type}:${reference.id}`, reference])),
+      [refs],
+    );
+
     const segments = useMemo(() => normalizeContent(content), [content]);
 
     const askRuns = useMemo(() => groupAskRuns(segments), [segments]);
@@ -180,7 +186,14 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
     // (and its open menu) survives across chunks. Invalidated per key when the
     // render fn identity changes.
     const renderedCardNodeCache = useRef(
-      new Map<string, { render: ((ref: ChatRef) => React.ReactNode) | undefined; node: React.ReactNode }>(),
+      new Map<
+        string,
+        {
+          render: ((ref: ChatRef) => React.ReactNode) | undefined;
+          reference: ChatRef;
+          node: React.ReactNode;
+        }
+      >(),
     );
 
     /**
@@ -242,10 +255,17 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           // menu / re-fetching) on every stream chunk. Also dedups the same
           // key emitted twice within one message.
           let entry = cache.get(key);
-          if (!entry || entry.render !== render) {
-            // The marker is the ONLY data on the wire: cards hydrate by id
-            // from the host's per-object APIs, so a minimal {type, id}
-            // descriptor is all the renderer needs to mount the loader.
+          const enrichedRef = refsByKey.get(key);
+          const refForRender: ChatRef = enrichedRef ?? {
+            type: cardType,
+            id: cardId,
+            title: cardId,
+            url: null,
+          };
+          if (!entry || entry.render !== render || entry.reference !== refForRender) {
+            // Prefer same-turn SOURCES metadata when available. Otherwise
+            // cards hydrate by id from the host's per-object APIs, so a
+            // minimal {type, id} descriptor still mounts the loader.
             // For types with nothing to fetch the host's render() returns
             // null and we fall through to the bare-cardId fallback in the
             // `<a card://…>` override below.
@@ -257,13 +277,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
             // the id rather than `undefined`) and `url` to null (matches
             // the no-link semantics fetch-mode cards rely on — they
             // resolve their own URL after fetch).
-            const refForRender: ChatRef = {
-              type: cardType,
-              id: cardId,
-              title: cardId,
-              url: null,
-            };
-            entry = { render, node: render(refForRender) };
+            entry = { render, reference: refForRender, node: render(refForRender) };
             cache.set(key, entry);
           }
           const rendered = entry.node;
@@ -326,7 +340,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
         }
       });
       return { inlineByKey, partsBySegment, usedKeys };
-    }, [hasMarkerSupport, renderEntityCard, segments]);
+    }, [hasMarkerSupport, refsByKey, renderEntityCard, segments]);
 
     // Drop cached nodes for markers no longer present so the cache can't grow
     // unbounded as a long message's markers change. Deliberately an EFFECT,
@@ -716,6 +730,7 @@ const MemoizedChatMessageEnhanced = memo(ChatMessageEnhanced, (prevProps, nextPr
     // equality holds across streaming chunks.
     prevProps.renderMention === nextProps.renderMention &&
     prevProps.renderEntityCard === nextProps.renderEntityCard &&
+    prevProps.refs === nextProps.refs &&
     // Same stability contract as the renderers above: hosts pass a `useCallback`
     // (EmbeddableChat passes its memoized `handleSend`), so this holds across
     // streaming chunks instead of re-rendering every ask card per chunk.