@flamingo-stack/openframe-frontend-core 0.0.467 → 0.0.468-snapshot.20260723140929

package/src/components/chat/__tests__/chat-pending-turn.test.tsx

@@ -0,0 +1,209 @@
+/**
+ * Pending-turn + hidden-row contracts.
+ *
+ * Two reader-visible defects this pins against:
+ *
+ *  1. Approving a tool call minted an author-label row with NO body
+ *     ("Michael Assraf:" then nothing). The approval decision is
+ *     out-of-band metadata, so the reducer must not materialize a user
+ *     row for it at all — fixing it at render would leave dead state.
+ *  2. While the model was thinking, the transcript showed a second,
+ *     empty "Mingo:" row ABOVE the footer progress indicator — two
+ *     owners for one pending turn, and an `aria-live` log announcing a
+ *     bare "Mingo". Exactly one affordance must be present.
+ *
+ * Plus the two idioms that must SURVIVE both fixes: a hidden row that
+ * carries real text (auto-continuation directive) stays in state while
+ * never rendering, and the SYSTEM name-only row still renders.
+ */
+
+import { render } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { createChatStreamReducer } from '../stream/chat-stream-reducer'
+import {
+  AUTO_CONTINUATION_DIRECTIVE_PREFIX,
+  buildAutoContinuationDirective,
+} from '../utils/auto-continuation-directive'
+import type { Message } from '../types/message.types'
+
+// ─── Render harness (mirrors chat-message-list.test.tsx) ────────────────────
+
+const scrollToBottom = vi.fn()
+const stopScroll = vi.fn()
+
+function makeRef() {
+  const fn = ((el: HTMLElement | null) => {
+    ;(fn as { current: HTMLElement | null }).current = el
+  }) as ((el: HTMLElement | null) => void) & { current: HTMLElement | null }
+  fn.current = null
+  return fn
+}
+
+vi.mock('use-stick-to-bottom', () => ({
+  useStickToBottom: () => ({
+    scrollRef: makeRef(),
+    contentRef: makeRef(),
+    scrollToBottom,
+    stopScroll,
+  }),
+}))
+
+// Row stub that renders the author label the way the real component does
+// (`Name:`), so "labeled row with no body" is directly assertable.
+vi.mock('../chat-message-enhanced', () => ({
+  ChatMessageEnhanced: ({ name, content }: { name?: string; content: unknown }) => (
+    <div data-testid="row">
+      <span data-testid="row-name">{name ?? ''}</span>
+      <span data-testid="row-body">
+        {typeof content === 'string'
+          ? content
+          : Array.isArray(content)
+            ? content
+                .map((s) => (s && (s as { type?: string }).type === 'text' ? (s as { text: string }).text : '[seg]'))
+                .join('')
+            : ''}
+      </span>
+    </div>
+  ),
+}))
+
+import { ChatMessageList } from '../chat-message-list'
+
+class ObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+vi.stubGlobal('IntersectionObserver', ObserverStub)
+vi.stubGlobal('ResizeObserver', ObserverStub)
+
+const names = (c: HTMLElement) =>
+  Array.from(c.querySelectorAll('[data-testid="row-name"]')).map((n) => n.textContent)
+const bodies = (c: HTMLElement) =>
+  Array.from(c.querySelectorAll('[data-testid="row-body"]')).map((n) => n.textContent)
+
+// ─── State-level contracts ─────────────────────────────────────────────────
+
+describe('approval sends mint no visible user row', () => {
+  it('beginSseSend with empty text pushes only the assistant placeholder', () => {
+    const r = createChatStreamReducer({ transport: 'sse' })
+    // What `cardApprove` triggers: ('', { hidden: true, approvalAction }).
+    r.beginSseSend({ text: '', hidden: true, assistantName: 'Mingo AI' })
+
+    expect(r.state.messages).toHaveLength(1)
+    expect(r.state.messages[0].role).toBe('assistant')
+    expect(r.state.messages.some((m) => m.role === 'user')).toBe(false)
+    expect(r.state.streamingPhase).toBe('thinking')
+  })
+
+  it('pushOptimisticSend with empty text likewise mints no user row', () => {
+    const r = createChatStreamReducer({ transport: 'nats' })
+    r.pushOptimisticSend('', true)
+
+    expect(r.state.messages).toHaveLength(1)
+    expect(r.state.messages[0].role).toBe('assistant')
+  })
+
+  it('a normal send still mints the user row', () => {
+    const r = createChatStreamReducer({ transport: 'sse' })
+    r.beginSseSend({ text: 'hello', assistantName: 'Mingo AI' })
+
+    expect(r.state.messages).toHaveLength(2)
+    expect(r.state.messages[0]).toMatchObject({ role: 'user', content: 'hello' })
+    expect(r.state.messages[0].hidden).toBeUndefined()
+  })
+})
+
+describe('hidden rows that carry text', () => {
+  it('an auto-continuation directive IS state (the model sees it) but is flagged hidden', () => {
+    const directive = buildAutoContinuationDirective('create_ticket', { ticketId: '42' })
+    expect(directive.startsWith(AUTO_CONTINUATION_DIRECTIVE_PREFIX)).toBe(true)
+
+    const r = createChatStreamReducer({ transport: 'sse' })
+    r.beginSseSend({ text: directive, hidden: true, assistantName: 'Mingo AI' })
+
+    const userRow = r.state.messages.find((m) => m.role === 'user')
+    expect(userRow?.content).toBe(directive)
+    expect(userRow?.hidden).toBe(true)
+  })
+
+  it('never renders — the raw directive text must not reach the transcript', () => {
+    const directive = buildAutoContinuationDirective('create_ticket', { ticketId: '42' })
+    const messages: Message[] = [
+      { id: 'u1', role: 'user', name: 'Michael Assraf', content: 'my laptop is dead' },
+      { id: 'h1', role: 'user', name: 'Michael Assraf', content: directive, hidden: true },
+      { id: 'a1', role: 'assistant', name: 'Mingo', content: 'Opened a ticket.' },
+    ]
+    const { container } = render(<ChatMessageList dialogId="d" messages={messages} />)
+
+    expect(container.textContent).not.toContain(AUTO_CONTINUATION_DIRECTIVE_PREFIX)
+    expect(bodies(container)).toEqual(['my laptop is dead', 'Opened a ticket.'])
+  })
+})
+
+// ─── Render-level contracts ────────────────────────────────────────────────
+
+describe('a thinking turn has exactly ONE pending affordance', () => {
+  const pending: Message[] = [
+    { id: 'u1', role: 'user', name: 'Michael Assraf', content: 'what is broken?' },
+    { id: 'a1', role: 'assistant', name: 'Mingo', content: '', segments: [] },
+  ]
+
+  it('does not render the empty labeled assistant row while typing', () => {
+    const { container } = render(
+      <ChatMessageList dialogId="d" messages={pending} isTyping />,
+    )
+    // The bare "Mingo" label must be gone from the transcript entirely —
+    // removed from the DOM, not visually hidden (the list is an aria-live
+    // log; a zero-height node would still be announced).
+    expect(names(container)).toEqual(['Michael Assraf'])
+    expect(bodies(container)).toEqual(['what is broken?'])
+    // …and the single remaining owner is the polite status indicator.
+    expect(container.querySelectorAll('[role="status"]')).toHaveLength(1)
+  })
+
+  it('renders the assistant row as soon as it carries text', () => {
+    const withText: Message[] = [
+      pending[0],
+      { id: 'a1', role: 'assistant', name: 'Mingo', content: [{ type: 'text', text: 'Chec' }] },
+    ]
+    const { container } = render(
+      <ChatMessageList dialogId="d" messages={withText} isTyping />,
+    )
+    expect(names(container)).toEqual(['Michael Assraf', 'Mingo'])
+  })
+
+  it('renders the assistant row when it carries a NON-text segment (tool call)', () => {
+    const withTool: Message[] = [
+      pending[0],
+      {
+        id: 'a1',
+        role: 'assistant',
+        name: 'Mingo',
+        content: [
+          { type: 'tool_execution', toolExecutionRequestId: 'e1', status: 'executing' },
+        ] as Message['content'],
+      },
+    ]
+    const { container } = render(
+      <ChatMessageList dialogId="d" messages={withTool} isTyping />,
+    )
+    expect(names(container)).toEqual(['Michael Assraf', 'Mingo'])
+  })
+
+  it('renders a completed empty-ish assistant row when NOT typing', () => {
+    const { container } = render(<ChatMessageList dialogId="d" messages={pending} />)
+    expect(names(container)).toEqual(['Michael Assraf', 'Mingo'])
+  })
+})
+
+describe('the SYSTEM name-only row is a legitimate label-without-body', () => {
+  it('still renders', () => {
+    const messages: Message[] = [
+      { id: 'u1', role: 'user', name: 'Michael Assraf', content: 'hi' },
+      { id: 's1', role: 'user', name: 'Technician joined', content: '', authorType: 'system' },
+    ]
+    const { container } = render(<ChatMessageList dialogId="d" messages={messages} isTyping />)
+    expect(names(container)).toContain('Technician joined')
+  })
+})

package/src/components/chat/chat-composer.tsx

@@ -4,6 +4,7 @@ import * as React from 'react'
 import { ChatFooter } from './chat-container'
 import { ChatInput } from './chat-input'
 import { ChatAttachmentAddButton } from './chat-attachment-bar'
+import { ChatContextMemoryBar } from './chat-context-memory-bar'
 import {
   ChatComposerPlusMenu,
   ChatContextChipStrip,
@@ -11,6 +12,7 @@ import {
 } from './chat-context-picker'
 import { ModelDisplay } from './model-display'
 import { BoxArchiveIcon } from '../icons-v2-generated'
+import { cn } from '../../utils/cn'
 import type { ChatInputRef, ModelDisplayProps } from './types/component.types'
 import type {
   ChatContextItem,
@@ -49,6 +51,13 @@ export interface ChatComposerProps {
   onToggleContextItem?: (item: ChatContextItem) => void
   /** Remove an item (chip ×). */
   onRemoveContextItem?: (item: ChatContextItem) => void
+  /** Ambient CONTEXT MEMORY (Figma 271:38656) — the entities the host collected
+   *  from the user's navigation history and sends with every message. Rendered
+   *  as a summary strip at the top of the composer card, above the assigned-item
+   *  chips. Empty/omitted → no strip. */
+  contextMemoryItems?: ChatContextItem[]
+  /** Drop one entity from the context memory (dropdown row ×). */
+  onRemoveContextMemoryItem?: (item: ChatContextItem) => void
   /** Controlled picker open state. */
   contextPickerOpen?: boolean
   /** Open the picker (the `+` menu's "Assign Item"). */
@@ -94,6 +103,8 @@ export function ChatComposer({
   selectedContextItems,
   onToggleContextItem,
   onRemoveContextItem,
+  contextMemoryItems,
+  onRemoveContextMemoryItem,
   contextPickerOpen = false,
   onOpenContextPicker,
   onCloseContextPicker,
@@ -104,6 +115,7 @@ export function ChatComposer({
 }: ChatComposerProps) {
   const contextEnabled = !!contextPicker && !archived
   const selected = selectedContextItems ?? []
+  const memory = contextMemoryItems ?? []
 
   // type → icon lookup so the chips (composer + bubble) lead with their
   // entity-type glyph without the parent threading an extra resolver. Keyed on
@@ -184,23 +196,38 @@ export function ChatComposer({
               </p>
             </div>
           ) : contextEnabled ? (
-            // Unified card (Figma 1:6073): a context-chip header strip
-            // (`bg-ods-bg`, `border-b`) sits flush above the input; the card
-            // owns the border / radius / focus ring. No `overflow-hidden` so the
-            // picker popover can float above the input (chips get `rounded-t`).
+            // Unified card (Figma 1:6073 / 271:38656): the context-memory
+            // summary strip and the assigned-chip strip (both `bg-ods-bg`,
+            // `border-b`) stack flush above the input; the card owns the border
+            // / radius / focus ring. No `overflow-hidden` so the picker and the
+            // memory popover can float above the input (whichever strip comes
+            // first gets `rounded-t`).
             // `has-[[data-editor]:focus]` (not `focus-within`) so the accent
             // border reacts ONLY to the composer editor — not the picker's search
             // input or item buttons, which also live inside this card. The editor
             // is a `contentEditable` div (`data-editor`), not a `<textarea>`, so we
             // target its data attribute rather than the element name.
             <div className="rounded-md border border-ods-border bg-ods-card transition-colors has-[[data-editor]:focus]:border-ods-accent">
+              {/* Ambient navigation-history context — always the same items, so
+                  it sits furthest from the textarea. Self-hides when empty. */}
+              <ChatContextMemoryBar
+                items={memory}
+                onRemove={onRemoveContextMemoryItem}
+                resolveIcon={resolveContextIcon}
+                disabled={sending}
+                className="rounded-t-md"
+              />
               {selected.length > 0 && (
                 <ChatContextChipStrip
                   items={selected}
                   onRemove={onRemoveContextItem}
                   resolveIcon={resolveContextIcon}
                   disabled={sending}
-                  className="rounded-t-md border-b border-ods-border bg-ods-bg p-2"
+                  className={cn(
+                    'border-b border-ods-border bg-ods-bg p-2',
+                    // Only the TOP strip rounds into the card corner.
+                    memory.length === 0 && 'rounded-t-md',
+                  )}
                 />
               )}
               {/* Picker is rendered inside the `+` button (its `dropdown` prop)

package/src/components/chat/chat-context-memory-bar.tsx

@@ -0,0 +1,159 @@
+'use client'
+
+/**
+ * `<ChatContextMemoryBar>` — the composer's CONTEXT MEMORY strip
+ * (Figma node 271:38656).
+ *
+ * A one-line summary row pinned to the top of the composer card ("5 recently
+ * viewed items in context") with a `⋯` trigger that opens a dropdown listing
+ * every remembered entity, each removable via its `×`.
+ *
+ * This is the AMBIENT half of the composer's context UI — the entities the host
+ * accumulated from the user's navigation history and sends along with every
+ * message — as opposed to `<ChatContextChipStrip>`, which shows the items the
+ * user ASSIGNED to the message they're typing. Both sit above the input; memory
+ * on top (passive, always the same items), assigned chips closest to the
+ * textarea (active selection for this message).
+ *
+ * The lib owns only the chrome: items and removal are host-fed
+ * (`EmbeddableChat`'s `contextMemory` prop), and lead glyphs come from the
+ * picker's entity-type icon map via `resolveIcon`. Renders `null` when the host
+ * has nothing remembered, so it has no permanent footprint.
+ */
+
+import type * as React from 'react'
+import { useEffect, useRef, useState } from 'react'
+import { Ellipsis01Icon } from '../icons-v2-generated/interface/ellipsis-01-icon'
+import { XmarkCircleIcon } from '../icons-v2-generated/signs-and-symbols/xmark-circle-icon'
+import { cn } from '../../utils/cn'
+import { CONTEXT_ICON_CLASS, CONTEXT_LABEL_CLASS, CONTEXT_ROW_CLASS } from './context-items-list'
+import type { ChatContextItem } from './types/context-item.types'
+
+const itemKey = (item: { type: string; id: string }) => `${item.type}:${item.id}`
+
+export interface ChatContextMemoryBarProps {
+  /** Remembered entities, most-recent-first. Empty → the bar renders nothing. */
+  items: ChatContextItem[]
+  /** Drop one entity from the host's memory (dropdown row `×`). When omitted the
+   *  list is read-only. */
+  onRemove?: (item: ChatContextItem) => void
+  /** Lead-glyph resolver — the composer passes its entity-type icon map, so the
+   *  rows match the picker and the assigned chips. */
+  resolveIcon?: (item: ChatContextItem) => React.ReactNode
+  /** External disable (e.g. while a message is streaming). */
+  disabled?: boolean
+  className?: string
+}
+
+export function ChatContextMemoryBar({
+  items,
+  onRemove,
+  resolveIcon,
+  disabled = false,
+  className,
+}: ChatContextMemoryBarProps) {
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  // Removing the last remembered entity unmounts the bar; close first so a
+  // stale popover can't outlive its trigger.
+  useEffect(() => {
+    if (items.length === 0) setOpen(false)
+  }, [items.length])
+
+  // Outside-press close. Registered only while open. The root wraps BOTH the
+  // trigger and the popover, so a press on the `⋯` (inside root) is ignored here
+  // and handled by the button's own toggle.
+  //
+  // CAPTURE phase (the `true` 3rd arg): the chat lives inside a resizable drawer
+  // whose panel captures pointer events and whose composer sits on a
+  // `contentEditable`; a bubble-phase `document` listener can be pre-empted by
+  // an ancestor's `stopPropagation`, which is why a press outside the popover
+  // wasn't closing it. Capture runs top-down before any of that, so the handler
+  // always fires. `touchstart` covers tap-to-dismiss on touch devices.
+  useEffect(() => {
+    if (!open) return
+    const onOutside = (e: Event) => {
+      if (rootRef.current?.contains(e.target as Node)) return
+      setOpen(false)
+    }
+    document.addEventListener('mousedown', onOutside, true)
+    document.addEventListener('touchstart', onOutside, true)
+    return () => {
+      document.removeEventListener('mousedown', onOutside, true)
+      document.removeEventListener('touchstart', onOutside, true)
+    }
+  }, [open])
+
+  if (items.length === 0) return null
+
+  return (
+    // `relative` anchors the popover to this strip; `bottom-full` floats it
+    // above, matching the context picker's placement over the input.
+    <div
+      ref={rootRef}
+      className={cn(
+        'relative flex items-center gap-[var(--spacing-system-xs)] border-b border-ods-border bg-ods-bg p-[var(--spacing-system-xs)]',
+        className,
+      )}
+      onKeyDown={e => {
+        if (e.key === 'Escape' && open) {
+          e.preventDefault()
+          setOpen(false)
+        }
+      }}
+    >
+      <p className="min-w-0 flex-1 truncate text-h6 text-ods-text-secondary">
+        {items.length} recently viewed {items.length === 1 ? 'item' : 'items'} in context
+      </p>
+
+      <button
+        type="button"
+        aria-label="Show remembered context"
+        aria-expanded={open}
+        title="Show remembered context"
+        onClick={() => setOpen(o => !o)}
+        className={cn(
+          'flex size-4 shrink-0 items-center justify-center rounded outline-none transition-colors [&_svg]:size-4',
+          open ? 'text-ods-text-primary' : 'text-ods-text-secondary hover:text-ods-text-primary',
+          'focus-visible:text-ods-text-primary',
+        )}
+      >
+        <Ellipsis01Icon size={16} />
+      </button>
+
+      {open && (
+        <div
+          role="list"
+          aria-label="Remembered context"
+          // Mirrors `ChatContextPicker`'s popover chrome (border / card bg /
+          // shadow-md) and its scroll cap, so both dropdowns over the composer
+          // read as one component family.
+          className="absolute bottom-full right-0 z-50 mb-1 max-h-[min(340px,45vh)] w-[320px] max-w-[90vw] overflow-y-auto overscroll-contain rounded-md border border-ods-border bg-ods-card text-ods-text-primary shadow-md"
+        >
+          {items.map(item => (
+            // Not a `<button>`: the row itself is inert (only the `×` acts), so
+            // the remove control isn't nested inside another button.
+            <div key={itemKey(item)} role="listitem" className={CONTEXT_ROW_CLASS}>
+              {resolveIcon && <span className={CONTEXT_ICON_CLASS}>{resolveIcon(item)}</span>}
+              <span className={CONTEXT_LABEL_CLASS} title={item.label}>
+                {item.label}
+              </span>
+              {onRemove && (
+                <button
+                  type="button"
+                  onClick={() => onRemove(item)}
+                  disabled={disabled}
+                  aria-label={`Remove ${item.label} from context`}
+                  className="flex size-4 shrink-0 items-center justify-center text-ods-text-secondary outline-none transition-colors hover:text-ods-text-primary focus-visible:text-ods-text-primary disabled:cursor-not-allowed disabled:opacity-40 md:size-6"
+                >
+                  <XmarkCircleIcon className="size-4 shrink-0 md:size-6" />
+                </button>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

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

@@ -1,6 +1,6 @@
 "use client"
 
-import React, { forwardRef, memo, useMemo, useRef } from "react"
+import React, { forwardRef, memo, useEffect, useMemo, useRef } from "react"
 import { cn } from "../../utils/cn"
 import { isToday } from "../../utils/date-utils"
 import { formatDate, formatTime } from "../../utils/format-date"
@@ -11,7 +11,7 @@ import { ApprovalBatchMessage } from "./approval-batch-message"
 import { ErrorMessageDisplay } from "./error-message-display"
 import { ContextCompactionDisplay } from "./context-compaction-display"
 import { ThinkingDisplay } from "./thinking-display"
-import { SimpleMarkdownRenderer } from "../ui/simple-markdown-renderer"
+import { SimpleMarkdownRenderer } from "../ui/markdown/simple-markdown-renderer"
 import type { ChatRef } from "./chat-ref.types"
 import { remarkCardLinks } from "./remark-card-links"
 import { remarkMentionChips } from "./remark-mention-chips"
@@ -163,9 +163,9 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
         | { kind: 'text'; text: string }
         | { kind: 'block'; key: string; node: React.ReactNode }
       const partsBySegment = new Map<number, SegmentPart[]>()
-      if (!render) return { inlineByKey, partsBySegment }
-      const cache = renderedCardNodeCache.current
       const usedKeys = new Set<string>()
+      if (!render) return { inlineByKey, partsBySegment, usedKeys }
+      const cache = renderedCardNodeCache.current
       // Card keys already emitted as a hoisted block (`b-<key>`). The same
       // marker can legitimately appear twice in one message (LLM references
       // the same entity twice); we hoist the FIRST occurrence and skip the
@@ -275,20 +275,99 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           partsBySegment.set(segIdx, parts)
         }
       })
-      // Drop cached nodes for markers no longer present so the cache can't
-      // grow unbounded as a long message's markers change.
-      if (cache.size > usedKeys.size) {
-        for (const k of cache.keys()) {
-          if (!usedKeys.has(k)) cache.delete(k)
-        }
-      }
-      return { inlineByKey, partsBySegment }
+      return { inlineByKey, partsBySegment, usedKeys }
     }, [hasMarkerSupport, chatRefs, 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,
+    // not part of the memo above: pruning is a mutation, and doing it in the
+    // render phase is non-idempotent (StrictMode's double-invoke, or a render
+    // React throws away, would evict nodes the committed tree still uses and
+    // remount the cards it was built to preserve).
+    useEffect(() => {
+      const cache = renderedCardNodeCache.current
+      const usedKeys = renderingPlan?.usedKeys
+      if (!usedKeys) return
+      if (cache.size <= usedKeys.size) return
+      for (const k of [...cache.keys()]) {
+        if (!usedKeys.has(k)) cache.delete(k)
+      }
+    }, [renderingPlan])
+
+    // The plan is read through a REF inside the `<a>` override, not captured
+    // in the override's closure. `renderingPlan` is rebuilt on every text
+    // delta (its `segments` dep is a fresh array per delta), so depending on
+    // it here would give `cardComponentOverrides` a new identity every token
+    // — which re-creates the markdown engine's `components` memo and defeats
+    // its per-block `StreamingBlockRenderer` memoization for the WHOLE
+    // message, on every token. The ref keeps the override identity stable
+    // while still reading the current plan at call time.
+    const renderingPlanRef = useRef(renderingPlan)
+    renderingPlanRef.current = renderingPlan
+    const chatRefsRef = useRef(chatRefs)
+    chatRefsRef.current = chatRefs
+
+    // Ref-SET token. The override reads `chatRefsRef` at CALL time, but the
+    // markdown engine memoizes completed blocks on the override map's
+    // identity — so on a COMPLETED (no longer streaming) message, a ref that
+    // resolves late would never be re-read: nothing else about the renderer's
+    // props changes, the engine's memo bails, and the pill stays stuck on its
+    // fallback (`refMatch.title`, or the raw cardId) forever. Streaming is
+    // covered because `card://` blocks are excluded from the block cache; the
+    // completed path has no other escape.
+    //
+    // The token fingerprints VALUES, not just the key set: a later refs frame
+    // REPLACES the whole map for a send index, and the enrichment case that
+    // matters most — a `title` going from the raw cardId to the resolved
+    // document title — keeps the key set IDENTICAL. A key-only token would be
+    // unchanged, the override map would keep its identity, the engine's
+    // completed-block memo would bail, and the pill would stay on its fallback
+    // forever. Every `ChatRef` field is included because the host's
+    // `renderEntityCard` receives the whole ref and may render any of them.
+    //
+    // Still STABLE per text delta (the refs map doesn't change while tokens
+    // stream), and the cost is one pass over a handful of refs per CHANGED
+    // `chatRefs` identity — the dep list is unchanged.
+    //
+    // Fields are joined by `JSON.stringify`, NOT by a separator character.
+    // `title`, `preview` and `url` are free-form HOST strings, so any
+    // delimiter we pick is one the data may also contain: joined with a plain
+    // space, `title: 'a b'` + empty `url` fingerprints identically to
+    // `title: 'a'` + `url: 'b'`, silently reintroducing the stale-pill memo
+    // bail this token exists to fix. (An earlier revision used a literal NUL
+    // byte as the separator: collision-free in practice, but it made the
+    // source file itself binary to grep and diff tooling.) `JSON.stringify`
+    // escapes every field, so no value can forge a boundary.
+    //
+    // Caveat worth stating: `JSON.stringify` on `metadata` is key-ORDER
+    // dependent: two structurally equal objects built in different insertion
+    // orders fingerprint differently. Acceptable here because every refs map
+    // arrives from ONE decoder with a fixed field order, and the failure mode
+    // is a redundant re-render, never a stale pill.
+    const refsKey = useMemo(
+      () =>
+        Object.entries(chatRefs ?? {})
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+          .map(([k, v]) =>
+            JSON.stringify([
+              k,
+              v.type,
+              v.sourceRepo ?? null,
+              v.id,
+              v.title,
+              v.url ?? null,
+              v.targetPlatform ?? null,
+              v.date ?? null,
+              v.preview ?? null,
+              v.metadata ?? null,
+            ]),
+          )
+          .join('|'),
+      [chatRefs],
+    )
+
     const cardComponentOverrides = useMemo(() => {
       if (!hasMarkerSupport && !hasMentionSupport) return undefined
-      const refs = chatRefs ?? {}
-      const inlineByKey = renderingPlan?.inlineByKey
       return {
         // Override `<a>` to detect `card://` URLs emitted by `remarkCardLinks`.
         // The render result was pre-computed in `renderingPlan` so block-level
@@ -316,7 +395,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
               const cardType = stripped.slice(0, sepIdx)
               const cardId = stripped.slice(sepIdx + 1)
               const key = `${cardType}:${cardId}`
-              const inline = inlineByKey?.get(key)
+              const inline = renderingPlanRef.current?.inlineByKey.get(key)
               if (inline != null) return inline
               // Three fallback cases — keep them DISTINCT, never blur them
               // together. Mixing them up (which the old code did by reaching
@@ -340,7 +419,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
               //       title from an unrelated ref — that hides the bug and
               //       deceives the reader into thinking they're looking at
               //       a real card.
-              const refMatch: ChatRef | undefined = refs[key]
+              const refMatch: ChatRef | undefined = chatRefsRef.current?.[key]
               if (refMatch) {
                 return <span className="text-ods-text-primary">{refMatch.title}</span>
               }
@@ -382,7 +461,13 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           )
         },
       }
-    }, [hasMarkerSupport, hasMentionSupport, renderMention, chatRefs, renderingPlan, NavLinkAnchor])
+      // DEPS ARE DELIBERATELY MINIMAL — every one of them is stable across a
+      // streaming turn (booleans + host-stable fn/component identities, both
+      // enforced by this file's `memo` comparator). The rendering plan and the
+      // refs MAP are read through refs above precisely so they do NOT appear
+      // here; `refsKey` is the one ref-derived dep, and it only moves when the
+      // ref set OR any ref VALUE does (see its definition).
+    }, [hasMarkerSupport, hasMentionSupport, renderMention, NavLinkAnchor, refsKey])
 
     const getAvatarProps = () => {
       const displayName = name || (isUser ? "User" : assistantType === 'mingo' ? "Mingo" : "Fae")
@@ -493,6 +578,13 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
                     "min-w-0 w-full break-words text-h4",
                     isError ? "text-ods-error" : "text-ods-text-primary",
                   )
+                  // The engine's streaming path (atomic-block memoization +
+                  // fence tail-completion + aria-live) applies ONLY to the
+                  // actively streaming segment: last segment of a message
+                  // that is still typing. On completion `isTyping` flips
+                  // false and the engine does one authoritative
+                  // whole-document parse.
+                  const segmentIsStreaming = index === segments.length - 1 && !!isTyping
                   // No block markers in this segment → single
                   // SimpleMarkdownRenderer call (existing behaviour
                   // preserved for the vast majority of messages).
@@ -504,6 +596,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
                           textSize="compact"
                           additionalRemarkPlugins={cardRemarkPlugins}
                           componentOverrides={cardComponentOverrides}
+                          streaming={segmentIsStreaming}
                         />
                       </div>
                     )
@@ -531,6 +624,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
                               textSize="compact"
                               additionalRemarkPlugins={cardRemarkPlugins}
                               componentOverrides={cardComponentOverrides}
+                              streaming={segmentIsStreaming && pIdx === parts.length - 1}
                             />
                           )
                         }