@flamingo-stack/openframe-frontend-core 0.0.497 → 0.0.498-1506.4000.1

package/src/components/chat/__tests__/chat-message-list.test.tsx

@@ -1,15 +1,28 @@
-import { render } from '@testing-library/react'
+import { act, render } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { Message } from '../types/message.types'
 
 const scrollToBottom = vi.fn()
 const stopScroll = vi.fn()
 
+/**
+ * `detachCount` records `ref(null)` invocations. React calls a ref callback with
+ * null and then with the element whenever the callback IDENTITY changes, and the
+ * real `use-stick-to-bottom` responds to the null by disconnecting its
+ * ResizeObserver and dropping its scroll/wheel listeners — so counting detaches
+ * is how a test can see the adapter-identity churn that a plain recording ref
+ * would silently absorb.
+ */
 function makeRef() {
   const fn = ((el: HTMLElement | null) => {
+    if (el === null) (fn as { detachCount: number }).detachCount += 1
     ;(fn as { current: HTMLElement | null }).current = el
-  }) as ((el: HTMLElement | null) => void) & { current: HTMLElement | null }
+  }) as ((el: HTMLElement | null) => void) & {
+    current: HTMLElement | null
+    detachCount: number
+  }
   fn.current = null
+  fn.detachCount = 0
   return fn
 }
 const scrollRefMock = makeRef()
@@ -26,9 +39,16 @@ vi.mock('use-stick-to-bottom', () => ({
 
 // Keep the row renderer trivial — these tests exercise ChatMessageList's
 // scroll orchestration, not markdown rendering.
-vi.mock('../chat-message-enhanced', () => ({
-  ChatMessageEnhanced: ({ content }: { content: string }) => <div>{content}</div>,
-}))
+// Forwards the ref because the list registers each row element for the
+// per-message `scrollAnchor: 'top'` path.
+vi.mock('../chat-message-enhanced', async () => {
+  const { forwardRef } = await import('react')
+  return {
+    ChatMessageEnhanced: forwardRef<HTMLDivElement, { content: string }>(({ content }, ref) => (
+      <div ref={ref}>{content}</div>
+    )),
+  }
+})
 
 import { ChatMessageList } from '../chat-message-list'
 
@@ -40,7 +60,36 @@ class ObserverStub {
   disconnect() {}
 }
 vi.stubGlobal('IntersectionObserver', ObserverStub)
-vi.stubGlobal('ResizeObserver', ObserverStub)
+
+// Recording RO so the bottom-follow tests can drive a resize by hand.
+const resizeCallbacks: Array<() => void> = []
+class RecordingResizeObserver {
+  constructor(cb: () => void) {
+    resizeCallbacks.push(cb)
+  }
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+vi.stubGlobal('ResizeObserver', RecordingResizeObserver)
+/** Fire every live ResizeObserver callback — same effect as any content
+ *  or scroller-box size change in the real DOM. */
+const fireResize = () => {
+  for (const cb of resizeCallbacks) cb()
+}
+
+/** jsdom has no layout, so every box metric reads 0. The jump-to-bottom
+ *  button is driven off real geometry, so the tests supply it. */
+const setGeometry = (geo: { scrollHeight: number; clientHeight: number; scrollTop: number }) => {
+  const el = scrollRefMock.current
+  if (!el) throw new Error('scroller not mounted')
+  for (const [key, value] of Object.entries(geo)) {
+    Object.defineProperty(el, key, { value, configurable: true, writable: true })
+  }
+}
+
+// jsdom has no layout, so `scrollIntoView` is undefined.
+Element.prototype.scrollIntoView = vi.fn()
 
 const msg = (id: string, role: Message['role']): Message => ({
   id,
@@ -90,3 +139,329 @@ describe('ChatMessageList force-scroll decisions', () => {
     expect(scrollToBottom).not.toHaveBeenCalled()
   })
 })
+
+// The library's own `isAtBottom` lock is lost silently when the scroller's
+// box changes (source chips mounting below it) or when a card settling out
+// of its skeleton produces a resize-driven scroll the library reads as a
+// user gesture. The list therefore owns the INTENT and re-asserts on every
+// geometry change until a real gesture releases it.
+describe('ChatMessageList bottom-follow intent', () => {
+  beforeEach(() => {
+    scrollToBottom.mockClear()
+    resizeCallbacks.length = 0
+  })
+
+  const sendTurn = () => {
+    const initial = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const view = render(<ChatMessageList dialogId="d1" messages={initial} />)
+    // A user send arms the follow intent for the whole turn.
+    view.rerender(<ChatMessageList dialogId="d1" messages={[...initial, msg('m3', 'user')]} />)
+    scrollToBottom.mockClear()
+    return view
+  }
+
+  it('re-asserts the bottom on geometry changes after the send', () => {
+    sendTurn()
+    fireResize()
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  it('keeps re-asserting for late async growth (cards + covers resolving)', () => {
+    sendTurn()
+    fireResize()
+    fireResize()
+    fireResize()
+    expect(scrollToBottom).toHaveBeenCalledTimes(3)
+  })
+
+  it('releases the intent once the user scrolls up', () => {
+    sendTurn()
+    scrollRefMock.current?.dispatchEvent(
+      new WheelEvent('wheel', { deltaY: -120, bubbles: true }),
+    )
+    fireResize()
+    expect(scrollToBottom).not.toHaveBeenCalled()
+  })
+
+  it('ignores downward wheel (never an escape from the bottom)', () => {
+    sendTurn()
+    scrollRefMock.current?.dispatchEvent(
+      new WheelEvent('wheel', { deltaY: 120, bubbles: true }),
+    )
+    fireResize()
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  it('does not follow when autoScroll is off (passive demo hosts)', () => {
+    const initial = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const { rerender } = render(
+      <ChatMessageList dialogId="d1" messages={initial} autoScroll={false} />,
+    )
+    rerender(
+      <ChatMessageList dialogId="d1" messages={[...initial, msg('m3', 'user')]} autoScroll={false} />,
+    )
+    scrollToBottom.mockClear()
+    fireResize()
+    expect(scrollToBottom).not.toHaveBeenCalled()
+  })
+
+  it('hides jump-to-bottom while the thread is at the bottom', () => {
+    const view = sendTurn()
+    setGeometry({ scrollHeight: 1000, clientHeight: 500, scrollTop: 500 })
+    act(() => fireResize())
+    expect(view.queryByLabelText('Scroll to latest message')).toBeNull()
+  })
+
+  it('shows jump-to-bottom once the thread is away from the bottom', () => {
+    const view = sendTurn()
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 500 })
+    act(() => fireResize())
+    expect(view.queryByLabelText('Scroll to latest message')).not.toBeNull()
+  })
+
+  it('re-arms the intent when the user clicks jump-to-bottom', () => {
+    const view = sendTurn()
+    // User scrolls away: intent released, button appears.
+    scrollRefMock.current?.dispatchEvent(
+      new WheelEvent('wheel', { deltaY: -120, bubbles: true }),
+    )
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 500 })
+    act(() => fireResize())
+    expect(scrollToBottom).not.toHaveBeenCalled()
+
+    const button = view.getByLabelText('Scroll to latest message')
+    act(() => {
+      button.click()
+    })
+    expect(scrollToBottom).toHaveBeenCalled()
+
+    // …and the click re-armed the lock, so growth follows again.
+    scrollToBottom.mockClear()
+    act(() => fireResize())
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  // A drag that ends OUTSIDE the window (button released off-screen, or the
+  // tab losing focus mid-drag) never delivers `pointerup`, so a naive
+  // `pointerDown` flag stays true forever. Afterwards the very thing this
+  // component exists for — a fetch-mode card settling from skeleton to a
+  // SHORTER height, which clamps scrollTop down — is misread as a scroll-up
+  // gesture and silently drops the lock.
+  const dragThenScrollDown = (endEvent: { target: 'window'; type: string }) => {
+    sendTurn()
+    // Park away from the bottom so the at-bottom re-arm below can't mask the
+    // result, and seed `lastScrollTop`.
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 4000 })
+    window.dispatchEvent(new Event('pointerdown'))
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    // Drag ends where we can't see it.
+    if (endEvent.target === 'window') window.dispatchEvent(new Event(endEvent.type))
+    // Resize clamp: content shrank, scrollTop drops. NOT a gesture.
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 3800 })
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    scrollToBottom.mockClear()
+    act(() => fireResize())
+  }
+
+  it('keeps the intent when a pointercancel ended the drag (resize clamp is not a gesture)', () => {
+    dragThenScrollDown({ target: 'window', type: 'pointercancel' })
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  it('keeps the intent when the window lost focus mid-drag', () => {
+    dragThenScrollDown({ target: 'window', type: 'blur' })
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  // Focus events do not bubble but they DO capture, so a capture-phase `blur`
+  // listener on `window` fires for EVERY element blur in the document — the
+  // classic focus-delegation idiom. Registering the drag-end `blur` that way
+  // made any focus change during a pointer hold (most commonly the chat input
+  // blurring as the user presses down on the scrollbar) clear `pointerDown`,
+  // which is exactly what re-opens the yank-back-mid-drag bug. Only a TRUE
+  // window blur (which targets `window` itself) may end the drag.
+  it('a descendant element losing focus does not end the drag', () => {
+    sendTurn()
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 4000 })
+    window.dispatchEvent(new Event('pointerdown'))
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    // The chat input loses focus as the pointer goes down elsewhere.
+    const input = document.createElement('input')
+    document.body.appendChild(input)
+    input.focus()
+    input.blur()
+    input.remove()
+    // The drag is still live, so this held scroll-up IS a gesture.
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 3800 })
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    scrollToBottom.mockClear()
+    act(() => fireResize())
+    expect(scrollToBottom).not.toHaveBeenCalled()
+    window.dispatchEvent(new Event('pointerup'))
+  })
+
+  it('still disarms on a genuine scrollbar drag upward', () => {
+    sendTurn()
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 4000 })
+    window.dispatchEvent(new Event('pointerdown'))
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 3800 })
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    scrollToBottom.mockClear()
+    act(() => fireResize())
+    expect(scrollToBottom).not.toHaveBeenCalled()
+    window.dispatchEvent(new Event('pointerup'))
+  })
+
+  // Scrolling back down to the live end by hand expresses exactly the intent
+  // the jump-to-bottom button does — the lock has to re-arm, or the thread
+  // renders at-bottom (button hidden) and then silently drifts away.
+  it('re-arms the intent when the user scrolls back to the bottom by hand', () => {
+    sendTurn()
+    scrollRefMock.current?.dispatchEvent(new WheelEvent('wheel', { deltaY: -120, bubbles: true }))
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 500 })
+    act(() => fireResize())
+    expect(scrollToBottom).not.toHaveBeenCalled()
+
+    // …and back down to the end.
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 19500 })
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    scrollToBottom.mockClear()
+    act(() => fireResize())
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  it('does not re-arm while the user is still parked above the bottom', () => {
+    sendTurn()
+    scrollRefMock.current?.dispatchEvent(new WheelEvent('wheel', { deltaY: -120, bubbles: true }))
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 8000 })
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    scrollToBottom.mockClear()
+    act(() => fireResize())
+    expect(scrollToBottom).not.toHaveBeenCalled()
+  })
+
+  // A short scrollbar drag that starts at the live end and stays inside the
+  // 70px band disarms on the gesture and would immediately re-arm on the very
+  // same scroll event if the re-arm didn't wait for the drag to END — yanking
+  // the reader back down mid-drag, a miniature of the bug this block exists
+  // to prevent.
+  it('does not re-arm mid-drag when the drag stays inside the bottom band', () => {
+    sendTurn()
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 19500 })
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    window.dispatchEvent(new Event('pointerdown'))
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 19460 })
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    scrollToBottom.mockClear()
+    act(() => fireResize())
+    expect(scrollToBottom).not.toHaveBeenCalled()
+    window.dispatchEvent(new Event('pointerup'))
+  })
+
+  it('releases the intent for a top-anchored turn (it parks at the message top)', () => {
+    const initial = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const { rerender } = render(<ChatMessageList dialogId="d1" messages={initial} />)
+    const sent = [...initial, msg('m3', 'user')]
+    rerender(<ChatMessageList dialogId="d1" messages={sent} />)
+    const anchored: Message = { ...msg('m4', 'assistant'), scrollAnchor: 'top' }
+    rerender(<ChatMessageList dialogId="d1" messages={[...sent, anchored]} />)
+    scrollToBottom.mockClear()
+    fireResize()
+    expect(scrollToBottom).not.toHaveBeenCalled()
+  })
+})
+
+/**
+ * The whole bottom-follow subsystem — ResizeObserver, wheel/touch/keyboard
+ * escape hatches, the jump-to-bottom button — is installed by ONE effect whose
+ * deps were all identity-stable (`autoScroll` plus three `[]`-memoized values
+ * from `useStickToBottom`). `isLoading` was missing, and on the loading branch
+ * the component returns the skeleton, so `scrollRef.current` is null and the
+ * effect bails.
+ *
+ * Net result for any consumer following this repo's own prescribed
+ * "skeleton during fetch" pattern: the effect ran once against null refs and
+ * NEVER re-ran, so nothing was ever observed, `atBottom` stayed at its initial
+ * `true`, the WCAG escape hatch could not render, and the follow lock was never
+ * re-asserted — while the observers/listeners bound on a later round trip kept
+ * detached nodes alive.
+ */
+describe('ChatMessageList bottom-follow survives the loading skeleton', () => {
+  beforeEach(() => {
+    scrollToBottom.mockClear()
+    resizeCallbacks.length = 0
+  })
+
+  it('installs the follow observers when the skeleton is replaced by the list', () => {
+    const messages = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const { rerender } = render(
+      <ChatMessageList dialogId="d1" messages={messages} isLoading />,
+    )
+    // Nothing to observe while the skeleton is up.
+    expect(resizeCallbacks).toHaveLength(0)
+
+    rerender(<ChatMessageList dialogId="d1" messages={messages} />)
+    expect(resizeCallbacks.length).toBeGreaterThan(0)
+  })
+
+  it('shows the jump-to-bottom escape hatch after a loading round trip', () => {
+    const messages = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const view = render(<ChatMessageList dialogId="d1" messages={messages} />)
+    // A host loading another page / another dialog swaps the scroller out…
+    view.rerender(<ChatMessageList dialogId="d1" messages={messages} isLoading />)
+    view.rerender(<ChatMessageList dialogId="d1" messages={messages} />)
+
+    // …and the list must still notice it is scrolled away from the bottom.
+    setGeometry({ scrollHeight: 20000, clientHeight: 500, scrollTop: 0 })
+    act(() => {
+      scrollRefMock.current?.dispatchEvent(new Event('scroll'))
+    })
+    expect(view.queryByLabelText('Scroll to latest message')).not.toBeNull()
+  })
+
+  it('keeps the ref adapters identity-stable across re-renders', () => {
+    // The adapters are handed to `useStickToBottom`'s ref callbacks, and the
+    // library disconnects its ResizeObserver on `ref(null)` and builds a NEW
+    // one on re-attach. A fresh arrow per render therefore churned an observer
+    // (and two scroll listeners) on every committed frame — ~60/s while
+    // streaming — and reset the library's `previousHeight`, which is what it
+    // uses to choose between its `initial` and `resize` animations.
+    const messages = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const view = render(<ChatMessageList dialogId="d1" messages={messages} />)
+    const detachesAfterMount = {
+      scroll: scrollRefMock.detachCount,
+      content: contentRefMock.detachCount,
+    }
+
+    for (let i = 0; i < 5; i++) {
+      view.rerender(<ChatMessageList dialogId="d1" messages={[...messages]} />)
+    }
+
+    // A memoized adapter is never re-invoked with null, so the library keeps its
+    // observer and listeners for the whole mount.
+    expect(scrollRefMock.detachCount).toBe(detachesAfterMount.scroll)
+    expect(contentRefMock.detachCount).toBe(detachesAfterMount.content)
+    expect(scrollRefMock.current).not.toBeNull()
+  })
+})

package/src/components/chat/__tests__/chat-message-streaming-memo.test.tsx

@@ -0,0 +1,207 @@
+/**
+ * REGRESSION: `ChatMessageEnhanced` must hand the markdown engine a
+ * REFERENTIALLY STABLE `componentOverrides` map across a streamed turn.
+ *
+ * The engine memoizes each COMPLETED block (`StreamingBlockRenderer`) on its
+ * `components` prop identity. `ChatMessageEnhanced` is the sole production
+ * caller, and it used to defeat that memo one level up: `cardComponentOverrides`
+ * listed `renderingPlan` in its deps, `renderingPlan` is memoized on `segments`,
+ * and the stream reducer replaces `segments` on EVERY text delta. So the
+ * override map got a new identity per token → the engine's `components` memo
+ * re-created → every completed block re-parsed on every token.
+ *
+ * The engine's own streaming test cannot catch this: it passes a module-scope
+ * stable override map. This test drives the real component with the real
+ * per-delta `content` churn a reducer produces, and asserts at the SEAM (the
+ * props the component hands the renderer) rather than through the engine's
+ * internals — the two are separately owned.
+ */
+
+import React from 'react'
+import { describe, it, expect, vi } from 'vitest'
+import { render } from '@testing-library/react'
+import type { MessageSegment } from '../types'
+import type { ChatRef } from '../chat-ref.types'
+
+/** Every `componentOverrides` / `additionalRemarkPlugins` identity the
+ *  component handed the markdown renderer, in render order. */
+const seenOverrides: unknown[] = []
+const seenPlugins: unknown[] = []
+
+vi.mock('../../ui/markdown/simple-markdown-renderer', () => ({
+  SimpleMarkdownRenderer: ({
+    content,
+    componentOverrides,
+    additionalRemarkPlugins,
+  }: {
+    content: string
+    componentOverrides?: unknown
+    additionalRemarkPlugins?: unknown
+  }) => {
+    seenOverrides.push(componentOverrides)
+    seenPlugins.push(additionalRemarkPlugins)
+    return <div data-testid="md">{content}</div>
+  },
+}))
+
+import { ChatMessageEnhanced } from '../chat-message-enhanced'
+
+function NavLinkAnchor({ href, children }: React.AnchorHTMLAttributes<HTMLAnchorElement>) {
+  return <a href={href}>{children}</a>
+}
+const CHAT_REFS: Record<string, ChatRef> = {}
+const renderMention = () => null
+
+/** Fresh array per call — the reducer replaces `segments` on every delta. */
+const segmentsFor = (tail: string): MessageSegment[] => [
+  { type: 'text', text: `First paragraph, already complete.\n\n${tail}` },
+]
+
+describe('ChatMessageEnhanced — override identity across a streamed turn', () => {
+  it('keeps componentOverrides + remark plugins referentially stable per token', () => {
+    seenOverrides.length = 0
+    seenPlugins.length = 0
+
+    const props = {
+      role: 'assistant' as const,
+      isTyping: true,
+      chatRefs: CHAT_REFS,
+      renderMention,
+      NavLinkAnchor,
+    }
+
+    const view = render(<ChatMessageEnhanced {...props} content={segmentsFor('Tail')} />)
+    expect(seenOverrides.length).toBeGreaterThan(0)
+    const firstOverrides = seenOverrides[0]
+    const firstPlugins = seenPlugins[0]
+    expect(firstOverrides).toBeTruthy()
+
+    let tail = 'Tail'
+    for (let i = 0; i < 10; i += 1) {
+      tail += ` token${i}`
+      view.rerender(<ChatMessageEnhanced {...props} content={segmentsFor(tail)} />)
+    }
+
+    // ONE identity for the whole turn. Before the fix this produced a fresh
+    // object on each of the 11 renders.
+    expect(new Set(seenOverrides).size).toBe(1)
+    expect(seenOverrides.every((o) => o === firstOverrides)).toBe(true)
+    expect(new Set(seenPlugins).size).toBe(1)
+    expect(seenPlugins.every((p) => p === firstPlugins)).toBe(true)
+
+    // Sanity: the tail really did stream through.
+    expect(view.container.textContent).toContain('token9')
+  })
+
+  it('still resolves card markers through the CURRENT plan (ref-read, not closure)', () => {
+    seenOverrides.length = 0
+    const refs: Record<string, ChatRef> = {
+      'blog:abc': { type: 'blog', id: 'abc', title: 'Resolved Title', url: null },
+    }
+    render(
+      <ChatMessageEnhanced
+        role="assistant"
+        content={[{ type: 'text', text: 'See [card://blog:abc] for more.' }]}
+        chatRefs={refs}
+        NavLinkAnchor={NavLinkAnchor}
+      />,
+    )
+    const overrides = seenOverrides[0] as { a: React.FC<{ href: string; children?: React.ReactNode }> }
+    const out = render(<>{overrides.a({ href: 'card://blog:abc', children: 'x' })}</>)
+    expect(out.container.textContent).toBe('Resolved Title')
+  })
+
+  /**
+   * REGRESSION (round 3): a ref that resolves AFTER the message finished
+   * streaming must still reach the pill. The override reads `chatRefs`
+   * through a ref, so its own closure is fine — but the markdown engine
+   * memoizes completed blocks on the override map's IDENTITY. With
+   * `chatRefs` excluded from the override memo's deps entirely, the map kept
+   * its old identity, the engine bailed, and the marker rendered its raw-id
+   * fallback permanently.
+   */
+  it('gives componentOverrides a NEW identity when the ref set grows (completed message)', () => {
+    seenOverrides.length = 0
+    const content: MessageSegment[] = [{ type: 'text', text: 'See [card://blog:late] for more.' }]
+    const emptyRefs: Record<string, ChatRef> = {}
+    const props = {
+      role: 'assistant' as const,
+      isTyping: false,
+      content,
+      NavLinkAnchor,
+    }
+
+    const view = render(<ChatMessageEnhanced {...props} chatRefs={emptyRefs} />)
+    const before = seenOverrides[seenOverrides.length - 1] as {
+      a: React.FC<{ href: string; children?: React.ReactNode }>
+    }
+    // Unresolved: the raw card id is surfaced so the breakage is visible.
+    expect(render(<>{before.a({ href: 'card://blog:late', children: 'x' })}</>).container.textContent)
+      .toBe('late')
+
+    // Same content, same everything — only the refs map gains the entry.
+    const resolvedRefs: Record<string, ChatRef> = {
+      'blog:late': { type: 'blog', id: 'late', title: 'Late Title', url: null },
+    }
+    view.rerender(<ChatMessageEnhanced {...props} chatRefs={resolvedRefs} />)
+
+    const after = seenOverrides[seenOverrides.length - 1] as {
+      a: React.FC<{ href: string; children?: React.ReactNode }>
+    }
+    expect(after).not.toBe(before)
+    expect(render(<>{after.a({ href: 'card://blog:late', children: 'x' })}</>).container.textContent)
+      .toBe('Late Title')
+  })
+
+  /**
+   * REGRESSION (round 5): a later refs frame REPLACES the map for a send index
+   * with the SAME key set but richer values — the `title` going from the raw
+   * cardId to the resolved document title is the exact production case. A
+   * key-set-only token produced an identical string, so the override map kept
+   * its identity, the engine's completed-block memo bailed, and the pill stayed
+   * on its fallback forever. The token fingerprints VALUES now.
+   */
+  it('gives componentOverrides a NEW identity when a ref VALUE is enriched (same key set)', () => {
+    seenOverrides.length = 0
+    const content: MessageSegment[] = [{ type: 'text', text: 'See [card://blog:abc].' }]
+    const props = { role: 'assistant' as const, isTyping: false, content, NavLinkAnchor }
+
+    // First frame: the ref exists but its title is still the raw card id.
+    const stub: Record<string, ChatRef> = {
+      'blog:abc': { type: 'blog', id: 'abc', title: 'abc', url: null },
+    }
+    const view = render(<ChatMessageEnhanced {...props} chatRefs={stub} />)
+    const before = seenOverrides[seenOverrides.length - 1] as {
+      a: React.FC<{ href: string; children?: React.ReactNode }>
+    }
+    expect(render(<>{before.a({ href: 'card://blog:abc', children: 'x' })}</>).container.textContent)
+      .toBe('abc')
+
+    // Second frame: SAME key set, enriched value.
+    const enriched: Record<string, ChatRef> = {
+      'blog:abc': { type: 'blog', id: 'abc', title: 'Resolved Document Title', url: null },
+    }
+    view.rerender(<ChatMessageEnhanced {...props} chatRefs={enriched} />)
+
+    const after = seenOverrides[seenOverrides.length - 1] as {
+      a: React.FC<{ href: string; children?: React.ReactNode }>
+    }
+    expect(after).not.toBe(before)
+    expect(render(<>{after.a({ href: 'card://blog:abc', children: 'x' })}</>).container.textContent)
+      .toBe('Resolved Document Title')
+  })
+
+  /** …but a same-KEY refs object (new identity, same entries) must NOT churn
+   *  the override map — that is the streaming-stability guarantee above. */
+  it('keeps the override identity when only the refs object identity changes', () => {
+    seenOverrides.length = 0
+    const content: MessageSegment[] = [{ type: 'text', text: 'See [card://blog:abc].' }]
+    const ref: ChatRef = { type: 'blog', id: 'abc', title: 'T', url: null }
+    const props = { role: 'assistant' as const, content, NavLinkAnchor }
+
+    const view = render(<ChatMessageEnhanced {...props} chatRefs={{ 'blog:abc': ref }} />)
+    view.rerender(<ChatMessageEnhanced {...props} chatRefs={{ 'blog:abc': ref }} />)
+
+    expect(new Set(seenOverrides).size).toBe(1)
+  })
+})