@flamingo-stack/openframe-frontend-core 0.0.490-1506.3944.1 → 0.0.490

package/dist/utils/markdown-section-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-section-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/markdown-section-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,4DAA4D;IAC5D,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAUD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,eAAe,EAAE,CA+CnB"}
+{"version":3,"file":"markdown-section-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/markdown-section-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,4DAA4D;IAC5D,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAUD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,eAAe,EAAE,CAoEnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.490-1506.3944.1",
+  "version": "0.0.490",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -102,12 +102,6 @@
       "require": "./dist/platform-domains.cjs",
       "default": "./dist/platform-domains.js"
     },
-    "./chat-protocol": {
-      "types": "./dist/chat-protocol/index.d.ts",
-      "import": "./dist/chat-protocol/index.js",
-      "require": "./dist/chat-protocol/index.cjs",
-      "default": "./dist/chat-protocol/index.js"
-    },
     "./components/ui/file-manager": {
       "types": "./dist/components/ui/file-manager/index.d.ts",
       "import": "./dist/components/ui/file-manager/index.js",

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

@@ -1,4 +1,4 @@
-import { act, render } from '@testing-library/react'
+import { render } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { Message } from '../types/message.types'
 
@@ -26,16 +26,9 @@ vi.mock('use-stick-to-bottom', () => ({
 
 // Keep the row renderer trivial — these tests exercise ChatMessageList's
 // scroll orchestration, not markdown rendering.
-// 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>
-    )),
-  }
-})
+vi.mock('../chat-message-enhanced', () => ({
+  ChatMessageEnhanced: ({ content }: { content: string }) => <div>{content}</div>,
+}))
 
 import { ChatMessageList } from '../chat-message-list'
 
@@ -47,36 +40,7 @@ class ObserverStub {
   disconnect() {}
 }
 vi.stubGlobal('IntersectionObserver', 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()
+vi.stubGlobal('ResizeObserver', ObserverStub)
 
 const msg = (id: string, role: Message['role']): Message => ({
   id,
@@ -126,255 +90,3 @@ 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()
-  })
-})

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

@@ -1,6 +1,6 @@
 "use client"
 
-import React, { forwardRef, memo, useEffect, useMemo, useRef } from "react"
+import React, { forwardRef, memo, 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,8 @@ 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/markdown/simple-markdown-renderer"
+import { GuideDisplay } from "./guide-display"
+import { SimpleMarkdownRenderer } from "../ui/simple-markdown-renderer"
 import type { ChatRef } from "./chat-ref.types"
 import { remarkCardLinks } from "./remark-card-links"
 import { remarkMentionChips } from "./remark-mention-chips"
@@ -163,16 +164,21 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
         | { kind: 'text'; text: string }
         | { kind: 'block'; key: string; node: React.ReactNode }
       const partsBySegment = new Map<number, SegmentPart[]>()
-      const usedKeys = new Set<string>()
-      if (!render) return { inlineByKey, partsBySegment, usedKeys }
+      if (!render) return { inlineByKey, partsBySegment }
       const cache = renderedCardNodeCache.current
+      const usedKeys = new Set<string>()
       // 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
       // duplicates so two siblings never collide on the same React key.
       const emittedBlockKeys = new Set<string>()
       segments.forEach((segment, segIdx) => {
-        if (segment.type !== 'text') return
+        // Both markdown-bearing segment types take part: a `guide` body is
+        // authored by the same LLM and carries the same `[card://]` markers,
+        // so skipping it here left its markers with no `inlineByKey` entry and
+        // no hoisted card — the `<a card://>` override silently degraded them
+        // to a bare title / id.
+        if (segment.type !== 'text' && segment.type !== 'guide') return
         const text = segment.text
         const parts: SegmentPart[] = []
         let cursor = 0
@@ -275,99 +281,20 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           partsBySegment.set(segIdx, parts)
         }
       })
-      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)
+      // 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)
+        }
       }
-    }, [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],
-    )
+      return { inlineByKey, partsBySegment }
+    }, [hasMarkerSupport, chatRefs, renderEntityCard, segments])
 
     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
@@ -395,7 +322,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
               const cardType = stripped.slice(0, sepIdx)
               const cardId = stripped.slice(sepIdx + 1)
               const key = `${cardType}:${cardId}`
-              const inline = renderingPlanRef.current?.inlineByKey.get(key)
+              const inline = 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
@@ -419,7 +346,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 = chatRefsRef.current?.[key]
+              const refMatch: ChatRef | undefined = refs[key]
               if (refMatch) {
                 return <span className="text-ods-text-primary">{refMatch.title}</span>
               }
@@ -461,13 +388,53 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           )
         },
       }
-      // 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])
+    }, [hasMarkerSupport, hasMentionSupport, renderMention, chatRefs, renderingPlan, NavLinkAnchor])
+
+    /**
+     * Body of a markdown-bearing segment (`text` / `guide`).
+     *
+     * No block markers in this segment → a single SimpleMarkdownRenderer call
+     * (the vast majority of messages). Otherwise the text is split at each
+     * marker and block payloads are interleaved: each text chunk includes its
+     * trailing marker so the inline pill renders at the right position via the
+     * `<a>` override, and block payloads land AS SIBLINGS between text chunks —
+     * HTML-valid (block DOM never nests inside `<p>`) AND positionally correct
+     * (the block appears where the marker is in the flow, not at the segment's
+     * end). Stable React keys come from the card key (block) and chunk position
+     * (text); streaming token-by-token reuses the same React instances so
+     * `<Video>` doesn't remount mid-play.
+     */
+    const renderSegmentBody = (segIndex: number, text: string) => {
+      const parts = renderingPlan?.partsBySegment.get(segIndex)
+      if (!parts || parts.length === 0) {
+        return (
+          <SimpleMarkdownRenderer
+            content={text}
+            textSize="compact"
+            additionalRemarkPlugins={cardRemarkPlugins}
+            componentOverrides={cardComponentOverrides}
+          />
+        )
+      }
+      return parts.map((part, pIdx) => {
+        if (part.kind === 'text') {
+          return (
+            <SimpleMarkdownRenderer
+              key={`t-${pIdx}`}
+              content={part.text}
+              textSize="compact"
+              additionalRemarkPlugins={cardRemarkPlugins}
+              componentOverrides={cardComponentOverrides}
+            />
+          )
+        }
+        return (
+          <div key={`b-${part.key}`} className="my-3">
+            {part.node}
+          </div>
+        )
+      })
+    }
 
     const getAvatarProps = () => {
       const displayName = name || (isUser ? "User" : assistantType === 'mingo' ? "Mingo" : "Fae")
@@ -573,69 +540,19 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           {(!isSystem || segments.length > 0) && <div className="flex flex-col gap-2">
             {segments.map((segment, index) => {
                 if (segment.type === 'text') {
-                  const parts = renderingPlan?.partsBySegment.get(index)
-                  const wrapperClass = cn(
-                    "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).
-                  if (!parts || parts.length === 0) {
-                    return (
-                      <div key={index} className={wrapperClass}>
-                        <SimpleMarkdownRenderer
-                          content={segment.text}
-                          textSize="compact"
-                          additionalRemarkPlugins={cardRemarkPlugins}
-                          componentOverrides={cardComponentOverrides}
-                          streaming={segmentIsStreaming}
-                        />
-                      </div>
-                    )
-                  }
-                  // Block markers present → split text at each marker
-                  // and interleave block payloads. Each text chunk
-                  // includes its trailing marker so the inline pill
-                  // renders at the right position via the `<a>`
-                  // override. Block payloads land AS SIBLINGS between
-                  // text chunks — HTML-valid (block DOM never nests
-                  // inside `<p>`) AND positionally correct (block
-                  // appears where the marker is in the flow, not at
-                  // the segment's end). Stable React keys come from
-                  // the card key (block) and chunk position (text);
-                  // streaming token-by-token reuses the same React
-                  // instances so `<Video>` doesn't remount mid-play.
                   return (
-                    <div key={index} className={wrapperClass}>
-                      {parts.map((part, pIdx) => {
-                        if (part.kind === 'text') {
-                          return (
-                            <SimpleMarkdownRenderer
-                              key={`t-${pIdx}`}
-                              content={part.text}
-                              textSize="compact"
-                              additionalRemarkPlugins={cardRemarkPlugins}
-                              componentOverrides={cardComponentOverrides}
-                              streaming={segmentIsStreaming && pIdx === parts.length - 1}
-                            />
-                          )
-                        }
-                        return (
-                          <div key={`b-${part.key}`} className="my-3">
-                            {part.node}
-                          </div>
-                        )
-                      })}
+                    <div
+                      key={index}
+                      className={cn(
+                        "min-w-0 w-full break-words text-h4",
+                        isError ? "text-ods-error" : "text-ods-text-primary",
+                      )}
+                    >
+                      {renderSegmentBody(index, segment.text)}
                     </div>
                   )
+                } else if (segment.type === 'guide') {
+                  return <GuideDisplay key={index}>{renderSegmentBody(index, segment.text)}</GuideDisplay>
                 } else if (segment.type === 'tool_execution') {
                   return (
                     <ToolExecutionDisplay