@flamingo-stack/openframe-frontend-core 0.0.248 → 0.0.250

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

@@ -0,0 +1,92 @@
+import { 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()
+
+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
+}
+const scrollRefMock = makeRef()
+const contentRefMock = makeRef()
+
+vi.mock('use-stick-to-bottom', () => ({
+  useStickToBottom: () => ({
+    scrollRef: scrollRefMock,
+    contentRef: contentRefMock,
+    scrollToBottom,
+    stopScroll,
+  }),
+}))
+
+// 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>,
+}))
+
+import { ChatMessageList } from '../chat-message-list'
+
+// jsdom ships neither observer; the component instantiates both
+// (load-more sentinel + top-anchor settle watcher).
+class ObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+vi.stubGlobal('IntersectionObserver', ObserverStub)
+vi.stubGlobal('ResizeObserver', ObserverStub)
+
+const msg = (id: string, role: Message['role']): Message => ({
+  id,
+  role,
+  content: `body of ${id}`,
+  timestamp: new Date(),
+})
+
+describe('ChatMessageList force-scroll decisions', () => {
+  beforeEach(() => {
+    scrollToBottom.mockClear()
+  })
+
+  it('snaps to bottom when the dialog changes', () => {
+    const { rerender } = render(<ChatMessageList dialogId="d1" messages={[msg('m1', 'user')]} />)
+    scrollToBottom.mockClear()
+    rerender(<ChatMessageList dialogId="d2" messages={[msg('x1', 'user')]} />)
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  it('snaps to bottom when a new user message is appended', () => {
+    const initial = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const { rerender } = render(<ChatMessageList dialogId="d1" messages={initial} />)
+    scrollToBottom.mockClear()
+    rerender(<ChatMessageList dialogId="d1" messages={[...initial, msg('m3', 'user')]} />)
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  it('does NOT scroll when an older page is prepended (load-more)', () => {
+    const initial = [msg('m3', 'user'), msg('m4', 'assistant')]
+    const { rerender } = render(
+      <ChatMessageList dialogId="d1" messages={initial} hasNextPage onLoadMore={() => {}} />,
+    )
+    scrollToBottom.mockClear()
+    const olderPage = [msg('m1', 'user'), msg('m2', 'assistant')]
+    rerender(
+      <ChatMessageList dialogId="d1" messages={[...olderPage, ...initial]} hasNextPage onLoadMore={() => {}} />,
+    )
+    expect(scrollToBottom).not.toHaveBeenCalled()
+  })
+
+  it('does NOT scroll on assistant-only appends (library owns streaming follow)', () => {
+    const initial = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const { rerender } = render(<ChatMessageList dialogId="d1" messages={initial} />)
+    scrollToBottom.mockClear()
+    rerender(<ChatMessageList dialogId="d1" messages={[...initial, msg('m3', 'assistant')]} />)
+    expect(scrollToBottom).not.toHaveBeenCalled()
+  })
+})

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

@@ -130,6 +130,11 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
     onLoadMoreRef.current = onLoadMore
     const isFetchingRef = useRef(isFetchingNextPage)
     isFetchingRef.current = isFetchingNextPage
+    // Fresh dialogId for the IntersectionObserver callback (its effect must
+    // not depend on `dialogId` or it would re-create on every dialog switch
+    // mid-stream; the ref keeps the snapshot's dialog tag current).
+    const dialogIdRef = useRef(dialogId)
+    dialogIdRef.current = dialogId
 
     // Tracks previous render state for explicit "force-stick" decisions
     // (dialog change, first message, new user message). The library
@@ -140,15 +145,19 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       lastMessageId: string | undefined
     }>({ dialogId: undefined, messageCount: 0, lastMessageId: undefined })
 
-    // Snapshot of the first message id + scrollHeight observed BEFORE
-    // a load-older prepend, so we can preserve the user's viewport
-    // position when older messages stream in above their current
-    // reading position.
-    const prependRef = useRef<{
-      firstMessageId: string | undefined
-      firstMessageContent: unknown
+    // Geometry snapshot captured the instant the top sentinel triggers
+    // onLoadMore (BEFORE the older page lands), applied once when the taller
+    // content commits. Keyed on the LOAD LIFECYCLE, not `messages[0].id`: the
+    // history processor groups consecutive assistant turns into one bubble
+    // keyed by the group's LAST id, so an older page that is all continuation
+    // of the first bubble grows that bubble in place WITHOUT changing its id.
+    // An id-based anchor misses that growth and leaves the reader pinned at
+    // the top (and the still-visible sentinel never re-fires).
+    const loadOlderAnchorRef = useRef<{
+      dialogId: string | undefined
       scrollHeight: number
-    }>({ firstMessageId: undefined, firstMessageContent: undefined, scrollHeight: 0 })
+      scrollTop: number
+    } | null>(null)
 
     // ---- Force-stick: dialog change / first-load / new user message --
     useEffect(() => {
@@ -156,6 +165,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
 
       const dialogChanged = dialogId !== prevRenderRef.current.dialogId
       const prevCount = prevRenderRef.current.messageCount
+      const prevLastId = prevRenderRef.current.lastMessageId
       const newCount = messages.length
       const currentLastId = messages[messages.length - 1]?.id
       prevRenderRef.current = { dialogId, messageCount: newCount, lastMessageId: currentLastId }
@@ -177,7 +187,18 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
         // user message DID arrive). When the user just sent a
         // message, they expect their bubble pinned to the bottom,
         // regardless of where they were scrolled.
-        const newSlice = messages.slice(prevCount)
+        //
+        // The tail must be located via the previous LAST message id,
+        // not `slice(prevCount)`: when load-older PREPENDS a page,
+        // count grows but the new messages are at the HEAD —
+        // `slice(prevCount)` would return already-rendered tail
+        // messages (which contain user bubbles) and force-scroll the
+        // reader away from the older page they just loaded. With the
+        // id-based slice a pure prepend yields an empty tail → no
+        // scroll, and the prepend-anchoring effect below keeps their
+        // viewport position.
+        const prevLastIdx = prevLastId ? messages.findIndex((m) => m.id === prevLastId) : -1
+        const newSlice = prevLastIdx >= 0 ? messages.slice(prevLastIdx + 1) : messages.slice(prevCount)
         const hasNewUser = newSlice.some((m) => m.role === 'user')
         if (hasNewUser) {
           void scrollToBottom({ animation: 'instant', ignoreEscapes: true })
@@ -230,49 +251,35 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
     }, [autoScroll, messages, dialogId, scrollToBottom, contentRef])
 
     // ---- Prepend anchoring (load-older) ------------------------------
-    // The library doesn't preserve user position when content prepends
-    // ABOVE the viewport. We do it ourselves: snapshot scrollHeight
-    // BEFORE the new render, then add the delta after to keep the
-    // user on the same message they were reading. `useLayoutEffect`
-    // so the scrollTop write lands before paint (no visible jump).
+    // The library doesn't preserve user position when content grows ABOVE
+    // the viewport. We do: from the pre-load geometry snapshot (taken in the
+    // sentinel callback), add the height the list gained and re-pin scrollTop
+    // so the message the user was reading stays put. `useLayoutEffect` so the
+    // write lands before paint (no visible jump). Covers both a pure prepend
+    // (new ids on top) and a boundary-merge (first bubble grows in place) —
+    // it measures total height delta, not message identity.
     useLayoutEffect(() => {
       const el = scrollRef.current
-      if (!el) {
-        prependRef.current = { firstMessageId: undefined, firstMessageContent: undefined, scrollHeight: 0 }
-        return
-      }
-
-      const currentFirstId = messages[0]?.id
-      const currentFirstContent = messages[0]?.content
-      const prevFirstId = prependRef.current.firstMessageId
-      const prevHeight = prependRef.current.scrollHeight
-
-      if (currentFirstId !== prevFirstId) {
-        // First-id changed → older messages prepended (verified by
-        // confirming the previous-first is still in the array at
-        // idx > 0; otherwise this is some other mutation).
-        if (prevFirstId && prevHeight > 0) {
-          const prevIdx = messages.findIndex((m) => m.id === prevFirstId)
-          if (prevIdx > 0) {
-            const addedHeight = el.scrollHeight - prevHeight
-            if (addedHeight > 0) el.scrollTop += addedHeight
-          }
-        }
-        prependRef.current = {
-          firstMessageId: currentFirstId,
-          firstMessageContent: currentFirstContent,
-          scrollHeight: el.scrollHeight,
-        }
+      const anchor = loadOlderAnchorRef.current
+      if (!el || !anchor) return
+      // Dialog switched out from under a pending load — abandon; the
+      // force-stick effect owns the new dialog's position.
+      if (anchor.dialogId !== dialogId) {
+        loadOlderAnchorRef.current = null
         return
       }
-      // Always keep `scrollHeight` snapshot fresh so the next prepend
-      // computes the right delta. The id/content updates only when
-      // those actually change to avoid churn.
-      prependRef.current.scrollHeight = el.scrollHeight
-      if (currentFirstContent !== prependRef.current.firstMessageContent) {
-        prependRef.current.firstMessageContent = currentFirstContent
-      }
-    }, [messages, scrollRef])
+      // Hold the anchor across the intermediate renders between firing
+      // onLoadMore and the older page committing (the isFetchingNextPage
+      // flip, and in some hosts a two-stage store update) — those don't grow
+      // the list. Apply on the first render where it actually grew taller,
+      // which is the prepend (new ids on top) or a boundary-merge (first
+      // bubble grew in place). Same-id boundary-merge is why this can't key
+      // on message count.
+      const addedHeight = el.scrollHeight - anchor.scrollHeight
+      if (addedHeight <= 0) return
+      loadOlderAnchorRef.current = null
+      el.scrollTop = anchor.scrollTop + addedHeight
+    }, [messages, dialogId, scrollRef])
 
     // ---- Per-message scrollAnchor (server-driven) --------------------
     // Server emits `scrollAnchor: 'top'` on the metadata leading frame
@@ -382,6 +389,14 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
     // ---- Load-more (infinite-scroll UP) ------------------------------
     // Distinct from stick-to-bottom; uses its own IntersectionObserver
     // on the top sentinel.
+    //
+    // `isFetchingNextPage` is in the deps so the observer is RE-CREATED when a
+    // fetch completes: IntersectionObserver fires no new callback while an
+    // element stays continuously intersecting, so after an older page lands
+    // with the sentinel still in view (small prepend, or rootMargin overlap)
+    // nothing would re-trigger until the user scrolled it out and back in.
+    // Re-observing re-evaluates the current intersection and fires again if
+    // the sentinel is still visible — load continues until it's pushed out.
     useEffect(() => {
       const scrollContainer = scrollRef.current
       const sentinelElement = sentinelRef.current
@@ -392,6 +407,16 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
           const entry = entries[0]
           if (!entry) return
           if (entry.isIntersecting && !isFetchingRef.current) {
+            // Snapshot pre-load geometry so the prepend-anchoring layout
+            // effect can re-pin scrollTop once the taller content commits.
+            const el = scrollRef.current
+            if (el) {
+              loadOlderAnchorRef.current = {
+                dialogId: dialogIdRef.current,
+                scrollHeight: el.scrollHeight,
+                scrollTop: el.scrollTop,
+              }
+            }
             onLoadMoreRef.current?.()
           }
         },
@@ -399,7 +424,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       )
       observer.observe(sentinelElement)
       return () => observer.disconnect()
-    }, [hasNextPage, scrollRef])
+    }, [hasNextPage, isFetchingNextPage, scrollRef])
 
     // Expose the scroll container ref to parents that need it (rare,
     // but the existing public contract). Library's `scrollRef` is a

package/src/components/chat/utils/__tests__/history-merge.test.ts

@@ -0,0 +1,339 @@
+import { describe, expect, it } from 'vitest'
+import type { MessageSegment } from '../../types'
+import {
+  computeHistoryPrepend,
+  flattenMessagePagesChronological,
+  maxPersistedStreamSeq,
+  type MergeableChatMessage,
+  mergeHistoryWithRealtime,
+} from '../history-merge'
+
+interface TestMessage extends MergeableChatMessage {
+  role: 'user' | 'assistant'
+}
+
+const txt = (s: string): MessageSegment[] => [{ type: 'text', text: s }]
+const t = (ms: number) => new Date(ms)
+const ids = (msgs: TestMessage[]) => msgs.map((m) => m.id)
+const batchSeg = {
+  type: 'approval_batch',
+  data: { approvalRequestId: 'req-9', toolCalls: [] },
+} as unknown as MessageSegment
+
+// Persisted history (Mongo ids), first fetched at t=1000
+const U0: TestMessage = { id: 'aaaa0001', role: 'user', content: 'first question', timestamp: t(500) }
+const A0: TestMessage = { id: 'aaaa0002', role: 'assistant', content: txt('first answer'), timestamp: t(600) }
+
+// A later turn that happened via realtime (optimistic user + streamed reply)
+const OPT1: TestMessage = { id: 'optimistic-2000-x', role: 'user', content: 'second question', timestamp: t(2000) }
+const SYN1: TestMessage = { id: 'assistant-2100-x', role: 'assistant', content: txt('second answer'), timestamp: t(2100) }
+
+// Persisted counterparts of that turn (what a FRESH fetch returns)
+const U1: TestMessage = { id: 'aaaa0003', role: 'user', content: 'second question', timestamp: t(2000) }
+const A1: TestMessage = { id: 'aaaa0004', role: 'assistant', content: txt('second answer'), timestamp: t(2100) }
+
+describe('mergeHistoryWithRealtime', () => {
+  it('keeps realtime messages newer than a STALE history snapshot (no data loss)', () => {
+    // Reopen a dialog: first merge runs against the cached snapshot fetched
+    // BEFORE the second turn existed. The completed reply must survive — the
+    // realtime transport will not redeliver chunks this client already consumed.
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [U0, A0, OPT1, SYN1],
+      streamingMessageId: null,
+      historyFetchedAt: 1000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, OPT1.id, SYN1.id])
+  })
+
+  it('replaces optimistic + synthetic messages with their persisted twins on a FRESH snapshot', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, A1],
+      existingMessages: [U0, A0, OPT1, SYN1],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, A1.id])
+  })
+
+  it('never drops the in-flight streaming synthetic', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1], // assistant turn not persisted yet
+      existingMessages: [U0, A0, OPT1, SYN1],
+      streamingMessageId: SYN1.id,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(SYN1.id)
+  })
+
+  it('dedupes mid-list synthetics against fresh history (no duplicated turns)', () => {
+    const OPT2: TestMessage = { id: 'optimistic-3000-x', role: 'user', content: 'third question', timestamp: t(3000) }
+    const SYN2: TestMessage = { id: 'assistant-3100-x', role: 'assistant', content: txt('third answer'), timestamp: t(3100) }
+    const U2: TestMessage = { id: 'aaaa0006', role: 'user', content: 'third question', timestamp: t(3000) }
+    const A2: TestMessage = { id: 'aaaa0007', role: 'assistant', content: txt('third answer'), timestamp: t(3100) }
+
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, A1, U2, A2],
+      existingMessages: [U0, A0, OPT1, SYN1, OPT2, SYN2],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, A1.id, U2.id, A2.id])
+  })
+
+  it('pins the more-complete synthetic over a partial history assistant (approval persistence race)', () => {
+    const partialHistA: TestMessage = { id: 'aaaa0005', role: 'assistant', content: [batchSeg], timestamp: t(2100) }
+    const fullSyn: TestMessage = {
+      id: 'assistant-2100-y',
+      role: 'assistant',
+      content: [...txt('second answer'), batchSeg],
+      timestamp: t(2100), // OLDER than the snapshot — pin must beat the freshness rule
+    }
+
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, partialHistA],
+      existingMessages: [U0, A0, OPT1, fullSyn],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(fullSyn.id)
+    expect(ids(merged)).not.toContain(partialHistA.id)
+  })
+
+  it('drops the synthetic when history is at least as complete for the same approval batch', () => {
+    const fullHistA: TestMessage = {
+      id: 'aaaa0005',
+      role: 'assistant',
+      content: [...txt('second answer'), batchSeg],
+      timestamp: t(2100),
+    }
+    const lesserSyn: TestMessage = {
+      id: 'assistant-2100-y',
+      role: 'assistant',
+      content: [batchSeg],
+      timestamp: t(9000), // even NEWER than the snapshot — explicit drop wins
+    }
+
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, fullHistA],
+      existingMessages: [U0, A0, OPT1, lesserSyn],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(fullHistA.id)
+    expect(ids(merged)).not.toContain(lesserSyn.id)
+  })
+
+  it('drops a replay-minted synthetic with a FRESH timestamp when seq coverage proves history contains it', () => {
+    // Chunk replay re-materializes an old turn into a synthetic stamped with
+    // the CURRENT time — newer than the snapshot, so the wall-clock rule
+    // would wrongly keep it next to its persisted twin (the "duplicated
+    // assistant message after navigating back" bug). Seq coverage is exact:
+    // history persisted through seq 80 >= client consumed through seq 80.
+    const replayedSyn: TestMessage = {
+      id: 'assistant-9999-r',
+      role: 'assistant',
+      content: txt('second answer'),
+      timestamp: t(9999), // newer than historyFetchedAt
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, A1],
+      existingMessages: [U0, A0, replayedSyn],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 80,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, A1.id])
+  })
+
+  it('keeps an old-looking synthetic when seq coverage proves history is BEHIND (persistence lag)', () => {
+    // Client consumed through seq 90 but history only persisted through 80 —
+    // dropping the synthetic would lose content, no matter how old its
+    // wall-clock timestamp looks.
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [U0, A0, OPT1, SYN1], // SYN1 timestamp 2100 <= fetchedAt
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 90,
+    })
+    expect(ids(merged)).toContain(SYN1.id)
+  })
+
+  it('falls back to the wall-clock rule when seq signals are unavailable', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, A1],
+      existingMessages: [U0, A0, OPT1, SYN1],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+      historyMaxStreamSeq: 0,
+      realtimeSeenStreamSeq: 0,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, A1.id])
+  })
+
+  it('keeps a just-sent optimistic message whose text repeats an older turn (stale snapshot)', () => {
+    // The user re-sends "first question" and the merge runs against a STALE
+    // snapshot (e.g. triggered by stream start). Content-dedup must not match
+    // it against the OLD persisted turn with the same text.
+    const repeat: TestMessage = { id: 'optimistic-9000-x', role: 'user', content: 'first question', timestamp: t(9000) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [U0, A0, repeat],
+      streamingMessageId: null,
+      historyFetchedAt: 1000,
+    })
+    expect(ids(merged)).toContain(repeat.id)
+  })
+
+  it('drops an optimistic repeat once the snapshot is fresh enough to contain its twin', () => {
+    const repeatPersisted: TestMessage = { id: 'bbbb0001', role: 'user', content: 'first question', timestamp: t(9000) }
+    const repeat: TestMessage = { id: 'optimistic-9000-x', role: 'user', content: 'first question', timestamp: t(9000) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, repeatPersisted],
+      existingMessages: [U0, A0, repeat],
+      streamingMessageId: null,
+      historyFetchedAt: 10_000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, repeatPersisted.id])
+  })
+
+  it('returns existing messages untouched when the history snapshot is empty', () => {
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [],
+      existingMessages: [OPT1, SYN1],
+      streamingMessageId: null,
+      historyFetchedAt: 10_000,
+    })
+    expect(merged).toEqual([OPT1, SYN1])
+  })
+
+  it('keeps a just-sent optimistic repeat even when seq coverage reports covered', () => {
+    // Optimistic messages are minted on send, not by chunks — seq coverage
+    // says nothing about them. Sent AFTER the snapshot → must survive even
+    // though its text matches an old persisted turn.
+    const repeat: TestMessage = { id: 'optimistic-9000-x', role: 'user', content: 'first question', timestamp: t(9000) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [U0, A0, repeat],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 80,
+    })
+    expect(ids(merged)).toContain(repeat.id)
+  })
+
+  it('pins the streaming twin even when it carries a persisted history id (adoption path)', () => {
+    // Chunk processors ADOPT an in-progress trailing assistant after a prior
+    // merge, so the streaming twin can have the SAME Mongo id as history's
+    // trailing message. The pin must beat the processed/raw id dedup or the
+    // turn vanishes from both lists.
+    const adopted: TestMessage = { id: 'aaaa0005', role: 'assistant', content: [batchSeg], timestamp: t(2100) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, adopted],
+      rawHistoryIds: new Set([U0.id, A0.id, U1.id, adopted.id]),
+      existingMessages: [U0, A0, adopted],
+      streamingMessageId: adopted.id,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toEqual([U0.id, A0.id, U1.id, adopted.id])
+  })
+
+  it('never drops the streaming twin in the approval-batch resolution (pins it instead)', () => {
+    // History's trailing assistant fully persisted the approval turn, but the
+    // same batch id belongs to the LIVE streaming bubble (continuation after
+    // approve). Dropping it would orphan the host's streaming pointer and
+    // make continuation chunks invisible.
+    const fullHistA: TestMessage = {
+      id: 'aaaa0005',
+      role: 'assistant',
+      content: [...txt('second answer'), batchSeg],
+      timestamp: t(2100),
+    }
+    const liveTwin: TestMessage = { id: 'assistant-2100-y', role: 'assistant', content: [batchSeg], timestamp: t(2100) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, fullHistA],
+      existingMessages: [U0, A0, OPT1, liveTwin],
+      streamingMessageId: liveTwin.id,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(liveTwin.id)
+    expect(ids(merged)).not.toContain(fullHistA.id)
+  })
+
+  it('resolves the approval batch against the most recent twin when several share the batch id', () => {
+    const partialHistA: TestMessage = { id: 'aaaa0005', role: 'assistant', content: [batchSeg], timestamp: t(2100) }
+    const staleTwin: TestMessage = { id: 'assistant-1000-old', role: 'assistant', content: [batchSeg], timestamp: t(1000) }
+    const fullTwin: TestMessage = {
+      id: 'assistant-2100-y',
+      role: 'assistant',
+      content: [...txt('second answer'), batchSeg],
+      timestamp: t(2100),
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0, U1, partialHistA],
+      existingMessages: [U0, A0, staleTwin, fullTwin],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(fullTwin.id)
+    expect(ids(merged)).not.toContain(partialHistA.id)
+    expect(ids(merged)).not.toContain(staleTwin.id)
+  })
+
+  it('keeps welcome bubbles (never persisted server-side)', () => {
+    const welcome: TestMessage = { id: 'welcome-d1', role: 'assistant', content: 'Hi!', timestamp: t(100) }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [U0, A0],
+      existingMessages: [welcome],
+      streamingMessageId: null,
+      historyFetchedAt: 5000,
+    })
+    expect(ids(merged)).toContain(welcome.id)
+  })
+})
+
+describe('computeHistoryPrepend', () => {
+  it('collects only messages above the first known id', () => {
+    const older: TestMessage = { id: 'aaaa0000', role: 'user', content: 'zeroth', timestamp: t(100) }
+    const result = computeHistoryPrepend([older, U0, A0], [U0, A0, SYN1])
+    expect(result).not.toBeNull()
+    expect(ids(result!.newMessages)).toEqual([older.id])
+    expect(result!.boundaryUpdates).toBeUndefined()
+  })
+
+  it('reports a boundary content refresh when the known boundary message changed', () => {
+    const updatedU0: TestMessage = { ...U0, content: 'first question (edited)' }
+    const result = computeHistoryPrepend([updatedU0, A0], [U0, A0])
+    expect(result).not.toBeNull()
+    expect(result!.newMessages).toEqual([])
+    expect(result!.boundaryMessageId).toBe(U0.id)
+    expect(result!.boundaryUpdates).toEqual({ content: 'first question (edited)' })
+  })
+
+  it('returns null when there is nothing to apply', () => {
+    expect(computeHistoryPrepend([U0, A0], [U0, A0])).toBeNull()
+  })
+})
+
+describe('page helpers', () => {
+  // Pages arrive DESC (newest page first, newest message first within a page).
+  const pages: { messages: { id: string; lastChunkStreamSeq?: number | null }[] }[] = [
+    { messages: [{ id: 'd', lastChunkStreamSeq: 40 }, { id: 'c', lastChunkStreamSeq: null }] },
+    { messages: [{ id: 'b', lastChunkStreamSeq: 20 }, { id: 'a' }] },
+  ]
+
+  it('flattenMessagePagesChronological reverses pages and messages into chronological order', () => {
+    expect(flattenMessagePagesChronological(pages).map((m) => m.id)).toEqual(['a', 'b', 'c', 'd'])
+    expect(flattenMessagePagesChronological(undefined)).toEqual([])
+  })
+
+  it('maxPersistedStreamSeq returns the highest stamped seq, 0 when absent', () => {
+    expect(maxPersistedStreamSeq(pages)).toBe(40)
+    expect(maxPersistedStreamSeq([{ messages: [{}] }])).toBe(0)
+    expect(maxPersistedStreamSeq(undefined)).toBe(0)
+  })
+})