@flamingo-stack/openframe-frontend-core 0.0.518-1663.4312.1 → 0.0.519

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

@@ -1584,6 +1584,24 @@ function EmbeddableChatInner({
     [sendMessage, readyAttachments, viewUrlPrefix, clearAttachments, contextItems],
   )
 
+  /**
+   * Picking an option on a clarification card — deliberately NOT `handleSend`.
+   *
+   * `handleSend` belongs to the composer: it appends the staged attachments'
+   * markdown to the text, ships the staged context items, and then clears both.
+   * Routing an ask click through it would (a) send `label + attachment markdown`
+   * where the backend's classifier expects the label VERBATIM to resolve which
+   * reading was picked, and (b) consume a draft's attachments/context into a
+   * one-word answer the user never attached them to. So the label goes out on
+   * its own and whatever is staged in the composer stays staged.
+   */
+  const handleAskSelect = useCallback(
+    (label: string) => {
+      sendMessage(label)
+    },
+    [sendMessage],
+  )
+
   // Admin "try-asking chips" → GUIDE-mode quick-action chips only (Mingo mode
   // deliberately doesn't surface them). Clicking one SENDS the query immediately
   // via the GuideWelcome `onQuickAction` → `handleSend` at the render site (no
@@ -2351,6 +2369,10 @@ function EmbeddableChatInner({
                       resolveContextIcon={resolveContextIcon}
                       renderContextItem={renderContextItem}
                       renderMention={renderMention}
+                      // Gated on `chatLoading` for the same reason the composer
+                      // is: no second send while a turn is in flight. Passive
+                      // demo hosts (previewMode) stay read-only.
+                      onAskSelect={chatLoading || previewMode ? undefined : handleAskSelect}
                       NavLinkAnchor={NavLinkAnchorViaRuntime}
                       // Real Mingo drawer: hide the message-list scrollbar
                       // (scroll stays functional). Scoped here via `className`

package/src/components/chat/hooks/.use-jetstream-dialog-subscription.md

@@ -13,29 +13,22 @@ The single exported hook. Accepts `UseJetStreamDialogSubscriptionOptions` and re
 |---|---|
 | `isConnected` | Whether the NATS WebSocket connection is live |
 | `isSubscribed` | Whether the JetStream consumer is active |
-| `reconnectionCount` | Increments whenever the live tail is re-established: a NATS reconnect, a JetStream ordered-consumer recreation, a resync after the page was hidden, or a host reporting either via `resyncSignal`. Callers refetch persisted history on every increment; one absence counts once even when two sources report it |
+| `reconnectionCount` | Increments whenever the live tail is re-established: a NATS reconnect, a JetStream ordered-consumer recreation, or a resync after the page was hidden. Callers refetch persisted history on every increment |
 | `currentStreamSeq` | Highest stream sequence number observed |
 
-**Host-supplied resync (`resyncSignal` option):**
-
-A counter the embedder bumps when it knows, from outside the page, that the tail may have missed something — an absence the page could not observe (a native shell whose window visibility never reaches `document.visibilityState`), or a write made on the page's behalf while it was away. Any increase is treated exactly like a reconnect. The value at mount is a baseline, rebased on every `dialogId` change so switching to a conversation with a lower count cannot swallow later resyncs.
-
 **Internal refs (stable across renders):**
 
 - `clientRef` — shared `NatsClient` instance
 - `lastRecoveryReportRef` — timestamp floor so a flapping consumer cannot storm callers with refetches
-- `resyncTimerRef` — trailing-edge timer collapsing resync requests within `RESYNC_COALESCE_MS`; cleared on dialog change and unmount so a request never crosses a conversation boundary
-- `lastResyncSignalRef` — baseline for `resyncSignal`, rebased per dialog
 - `subscriptionRef` — active `JetStreamSubscriptionHandle`
 - `highestStreamSeqRef` — tracks max stream sequence for gap-free resume
 
 **Effect order (declaration order matters):**
 
 1. **Connection effect** — acquires/releases the shared NATS client when `enabled` or `wsUrl` changes; drives the `startConnectionLifecycle` which emits status events.
-2. **Dialog reset effect** — resets `highestStreamSeqRef`, rebases the `resyncSignal` baseline, and drops any pending resync when `dialogId` changes, so a new dialog never inherits a stale start sequence or the previous dialog's refetch.
-3. **Visibility effect** — after the page has been hidden longer than `RESYNC_AFTER_HIDDEN_MS`, returning to view requests a resync: a hidden page can stop receiving without the socket ever closing, and nothing else reports that.
-4. **Host-signal effect** — an increase in `resyncSignal` requests a resync on the same path, for absences and out-of-band writes the page cannot see.
-5. **Subscription effect** — creates or recreates the ephemeral consumer when `isConnected`, `dialogId`, `topic`, `streamName`, or the reconnect counter change.
+2. **Dialog reset effect** — resets `highestStreamSeqRef` when `dialogId` changes so a new dialog never inherits a stale start sequence.
+3. **Visibility effect** — after the page has been hidden longer than `RESYNC_AFTER_HIDDEN_MS`, returning to view bumps the counter: a hidden page can stop receiving without the socket ever closing, and nothing else reports that.
+4. **Subscription effect** — creates or recreates the ephemeral consumer when `isConnected`, `dialogId`, `topic`, `streamName`, or the reconnect counter change.
 
 **Deliver policy logic:**
 

package/src/components/chat/hooks/use-jetstream-dialog-subscription.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import {
   acquireClient as acquireSharedClient,
   releaseClient as releaseSharedClient,
@@ -20,24 +20,7 @@ const DEFAULT_STREAM_NAME = 'CHAT_CHUNKS'
  * absence worth resyncing for. Alt-tabbing must not churn the consumer; a
  * window that sat in the tray must not come back showing a stale conversation.
  */
-export const RESYNC_AFTER_HIDDEN_MS = 10_000
-/**
- * How long resync requests are gathered before one is acted on.
- *
- * A single reveal can be reported twice: the page sees `visibilitychange`, and
- * a host that knows the window was away reports it too (`resyncSignal`),
- * neither able to tell whether the other noticed. Both land within a frame or
- * two of each other, being driven by the same OS event, and acting on both
- * rebuilds the consumer and refetches history twice for one reveal.
- *
- * Gathered on the TRAILING edge, so a request is deferred and never dropped.
- * Two reports of one reveal collapse into one rebuild; two genuinely different
- * signals — a notification reply landing just before the user opens the window
- * — also collapse into one, which is correct, because a single refetch after
- * the last of them covers both. The cost is a second of latency on a path whose
- * next step is a network round trip.
- */
-const RESYNC_COALESCE_MS = 1_000
+const RESYNC_AFTER_HIDDEN_MS = 10_000
 /**
  * Floor between two reported recoveries. Every recovery costs the caller a
  * history refetch, and a consumer that cannot hold its sequence — gap, reset,
@@ -77,7 +60,6 @@ export function useJetStreamDialogSubscription({
   clientConfig = {},
   reconnectionBackoff,
   inactiveThresholdMs,
-  resyncSignal = 0,
 }: UseJetStreamDialogSubscriptionOptions): UseJetStreamDialogSubscriptionReturn {
   const [isConnected, setIsConnected] = useState(false)
   const [isSubscribed, setIsSubscribed] = useState(false)
@@ -91,8 +73,6 @@ export function useJetStreamDialogSubscription({
   const [currentStreamSeq, setCurrentStreamSeq] = useState<number | null>(null)
 
   const lastRecoveryReportRef = useRef(0)
-  const resyncTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-  const lastResyncSignalRef = useRef(resyncSignal)
   const clientRef = useRef<NatsClient | null>(null)
   const subscriptionRef = useRef<JetStreamSubscriptionHandle | null>(null)
   const highestStreamSeqRef = useRef<number | null>(null)
@@ -265,26 +245,7 @@ export function useJetStreamDialogSubscription({
   // ignoring optStartSeq).
   useEffect(() => {
     highestStreamSeqRef.current = null
-    // A host's signal counts per dialog (it can carry a per-conversation term),
-    // so the baseline has to move with the dialog or a switch to one with a
-    // LOWER count would swallow every later resync for it.
-    lastResyncSignalRef.current = resyncSignal
     setCurrentStreamSeq(null)
-    // A resync gathered for the previous dialog must not land on this one: the
-    // counter says nothing about which conversation it meant, so callers would
-    // refetch the wrong one. The dialog change supersedes it — the new dialog
-    // loads its own history regardless. As cleanup, so it covers unmount too,
-    // which is the same rule.
-    return () => {
-      if (resyncTimerRef.current !== null) {
-        clearTimeout(resyncTimerRef.current)
-        resyncTimerRef.current = null
-      }
-    }
-    // `resyncSignal` is read as the new baseline, not depended on: reacting to
-    // it here would reset the baseline on the very change meant to trigger a
-    // resync, and the effect below owns that.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [dialogId])
 
   // Coming back into view after a real absence is treated exactly like a
@@ -295,20 +256,8 @@ export function useJetStreamDialogSubscription({
   // report that: the tail simply stays quiet, and the conversation on screen
   // stays frozen at whatever was there when the window went away (the user's
   // manual fix is a page refresh, which is exactly the history refetch this
-  // triggers). Rebuilds the consumer from the last sequence seen AND tells
-  // callers to refetch history.
-  //
-  // Every source funnels through here (see `RESYNC_COALESCE_MS`). Restarting
-  // the timer rather than dropping is what makes that safe: a request is only
-  // ever folded into the one that follows it, never discarded.
-  const requestResync = useCallback(() => {
-    if (resyncTimerRef.current !== null) clearTimeout(resyncTimerRef.current)
-    resyncTimerRef.current = setTimeout(() => {
-      resyncTimerRef.current = null
-      setReconnectionCount((c) => c + 1)
-    }, RESYNC_COALESCE_MS)
-  }, [])
-
+  // triggers). Bumping the counter rebuilds the consumer from the last sequence
+  // seen AND tells callers to refetch history.
   useEffect(() => {
     if (!enabled) return
     let hiddenSince = document.visibilityState === 'hidden' ? Date.now() : 0
@@ -321,27 +270,13 @@ export function useJetStreamDialogSubscription({
       const awayMs = hiddenSince === 0 ? 0 : Date.now() - hiddenSince
       hiddenSince = 0
       if (awayMs >= RESYNC_AFTER_HIDDEN_MS) {
-        requestResync()
+        setReconnectionCount((c) => c + 1)
       }
     }
 
     document.addEventListener('visibilitychange', onVisibilityChange)
     return () => document.removeEventListener('visibilitychange', onVisibilityChange)
-  }, [enabled, requestResync])
-
-  useEffect(() => {
-    // Held, not consumed, while disabled: it fires once on enable instead.
-    // A host reports a signal against the conversation, not against this hook's
-    // readiness, so one arriving while the caller is still assembling the
-    // subscription describes a gap in the history the caller is fetching right
-    // now. Dropping it would leave that fetch's result stale with nothing left
-    // to say so.
-    if (!enabled) return
-    // The mount value is a baseline, not a signal.
-    if (resyncSignal <= lastResyncSignalRef.current) return
-    lastResyncSignalRef.current = resyncSignal
-    requestResync()
-  }, [enabled, resyncSignal, requestResync])
+  }, [enabled])
 
   // Subscription lifecycle: (re)create the ephemeral JetStream consumer whenever
   // we transition into a connected state for a dialog, and whenever the dialog

package/src/components/chat/index.ts

@@ -7,6 +7,7 @@ export * from './context-compaction-display'
 export * from './expand-chevron'
 export * from './thinking-display'
 export * from './guide-display'
+export * from './ask-display'
 export * from './error-message-display'
 export * from './chat-container'
 export * from './chat-input'

package/src/components/chat/stream/__tests__/chat-stream-reducer.test.ts

@@ -1328,3 +1328,75 @@ describe('agentBusy on initializeWithState', () => {
     expect(r.state.streamingPhase).toBe('idle')
   })
 })
+
+/**
+ * `ask` — the guide-routing clarification card. Not a delta: one chunk carries
+ * the whole card, plus the intro sentence that must render as ordinary answer
+ * text IN FRONT of it. The post-MESSAGE_END path is the interesting one — the
+ * card routinely lands in a continuation, where the delta is appended to the
+ * finished bubble rather than replacing it.
+ */
+describe('createChatStreamReducer — ask cards', () => {
+  const ask = (question: string, seq?: number, text?: string): ChatStreamEvent => ({
+    type: 'ask',
+    ...(text ? { text } : {}),
+    question,
+    options: [
+      { label: 'Find documentation', description: 'How the feature works' },
+      { label: 'Work with workspace data' },
+    ],
+    ...(seq != null ? { seq } : {}),
+  })
+
+  it('renders the intro as text ahead of the card, in one bubble', () => {
+    const r = createChatStreamReducer({ transport: 'nats' })
+    r.apply({ type: 'turn-start', seq: 1 })
+    r.apply(ask('What do you want to work on?', 2, 'Docs, or your own workspace?'))
+
+    const last = r.state.messages[r.state.messages.length - 1]
+    expect(last.segments).toEqual([
+      { type: 'text', text: 'Docs, or your own workspace?' },
+      {
+        type: 'ask',
+        question: 'What do you want to work on?',
+        options: [
+          { label: 'Find documentation', description: 'How the feature works' },
+          { label: 'Work with workspace data' },
+        ],
+      },
+    ])
+  })
+
+  it('appends into the finished bubble after MESSAGE_END, keeping the reply', () => {
+    const r = createChatStreamReducer({ transport: 'nats' })
+    r.apply({ type: 'turn-start', seq: 1 })
+    r.apply({ type: 'text-delta', text: 'Working on it. ', seq: 2 })
+    r.apply({ type: 'turn-end', seq: 3 })
+    r.apply(ask('Which one?', 4, 'One thing first: '))
+
+    const last = r.state.messages[r.state.messages.length - 1]
+    // The intro COALESCES onto the completed reply (same rule as a post-END
+    // `text-delta`) — a slice off the accumulator used to drop it here.
+    expect(last.segments).toEqual([
+      { type: 'text', text: 'Working on it. One thing first: ' },
+      {
+        type: 'ask',
+        question: 'Which one?',
+        options: [
+          { label: 'Find documentation', description: 'How the feature works' },
+          { label: 'Work with workspace data' },
+        ],
+      },
+    ])
+  })
+
+  it('keeps two cards in one turn as separate segments (the card pages them)', () => {
+    const r = createChatStreamReducer({ transport: 'nats' })
+    r.apply({ type: 'turn-start', seq: 1 })
+    r.apply(ask('First?', 2))
+    r.apply(ask('Second?', 3))
+
+    const last = r.state.messages[r.state.messages.length - 1]
+    expect(last.segments?.map((s) => s.type)).toEqual(['ask', 'ask'])
+  })
+})

package/src/components/chat/stream/chat-stream-reducer.ts

@@ -1041,6 +1041,33 @@ export function createChatStreamReducer(
         break
       }
 
+      // A clarification card arrives whole, not as deltas. The intro sentence
+      // riding the same chunk goes in FIRST as ordinary answer text so it runs
+      // through the markdown body pipeline (and coalesces with any preamble the
+      // turn already streamed); the card follows as its own segment. Both land
+      // in one emit, so the bubble never shows the card ahead of its lead-in.
+      case 'ask': {
+        if (event.text) accumulator.appendText(event.text)
+        const segments = accumulator.addAsk(event.question, event.options)
+        if (isInStream || !hasEverStreamed) {
+          emitSegments(segments)
+          applySegmentsToState(segments, withSeqMeta(undefined))
+          break
+        }
+        // Post-MESSAGE_END: the delta is spelled out rather than sliced off the
+        // accumulator. `appendText` COALESCES into a trailing text segment, so a
+        // slice would silently drop the intro whenever the continuation already
+        // had text in flight; `appendToTrailingAssistant` re-coalesces it here
+        // instead, exactly like a `text-delta`.
+        const delta: MessageSegment[] = [
+          ...(event.text ? [{ type: 'text' as const, text: event.text }] : []),
+          { type: 'ask' as const, question: event.question, options: event.options },
+        ]
+        emitSegments(delta, { append: true })
+        applySegmentsToState(delta, withSeqMeta({ append: true }))
+        break
+      }
+
       case 'tool-execution': {
         const segment: ToolExecutionSegment = { type: 'tool_execution', data: event.data }
         // A starting tool run means the agent's turn is in progress even

package/src/components/chat/types/api.types.ts

@@ -131,22 +131,6 @@ export interface UseJetStreamDialogSubscriptionOptions {
   /** Consumer inactivity threshold in ms before NATS auto-cleans it. Defaults to the
    *  client's, and applies only to the first consumer — recreations use nats.ws's. */
   inactiveThresholdMs?: number
-  /**
-   * A counter the host bumps when it knows, from outside the page, that the tail
-   * may have missed something.
-   *
-   * The hook's own detector is `visibilitychange`, which a browser tab reports
-   * honestly and an embedding shell may not — and which says nothing at all
-   * about a write made on the page's behalf while it was away. A host holding
-   * either kind of knowledge bumps this instead of hoping the page noticed.
-   *
-   * Treated exactly like a reconnect: the consumer is rebuilt from the highest
-   * sequence already seen, and `reconnectionCount` moves so callers refetch
-   * persisted history. Any increase counts; the value itself means nothing, and
-   * an increase arriving alongside a `visibilitychange` costs one rebuild, not
-   * two.
-   */
-  resyncSignal?: number
 }
 
 export interface UseJetStreamDialogSubscriptionReturn {
@@ -154,12 +138,10 @@ export interface UseJetStreamDialogSubscriptionReturn {
   isSubscribed: boolean
   /**
    * Incremented each time the live tail is re-established: a NATS reconnect, a
-   * JetStream ordered-consumer recreation, the page returning to view after
-   * being hidden long enough to have missed something, or a host reporting the
-   * same via `resyncSignal`. All of them mean the same thing to the caller —
-   * the tail may have skipped messages, so persisted history has to be
-   * refetched. One absence counts once even when two sources report it.
-   * Starts at 0.
+   * JetStream ordered-consumer recreation, or the page returning to view after
+   * being hidden long enough to have missed something. All three mean the same
+   * thing to the caller — the tail may have skipped messages, so persisted
+   * history has to be refetched. Starts at 0.
    */
   reconnectionCount: number
   /** Highest JetStream stream sequence observed so far (null before first delivery). */

package/src/components/chat/types/component.types.ts

@@ -4,7 +4,7 @@
 
 import type { ComponentType, HTMLAttributes, ReactNode, TextareaHTMLAttributes } from 'react'
 import type { ApprovalBlockVariant, AssistantType, AuthorType, ChatApprovalStatus, ConnectionStatus } from './chat.types'
-import type { ApprovalRequestData, Message, MessageSegment, ToolExecutionData,
+import type { ApprovalRequestData, AskSegment, Message, MessageSegment, ToolExecutionData,
   ApprovalResolutionHandler,
 } from './message.types'
 import type { ChatRef } from '../chat-ref.types'
@@ -212,6 +212,15 @@ export interface ChatMessageEnhancedProps extends Omit<HTMLAttributes<HTMLDivEle
    * simply default to undefined on the receiver.
    */
   NavLinkAnchor?: NavLinkAnchorComponent
+  /**
+   * Picks an option on an `ask` (clarification) card in this message. Receives
+   * the option's label VERBATIM — the host sends it as the user's next message
+   * and the backend resolves the reply against the labels it offered.
+   *
+   * Omit to render ask cards read-only. Keep the identity stable
+   * (`useCallback` / module const): the message memo compares it by reference.
+   */
+  onAskSelect?: (label: string) => void
 }
 
 // ========== Chat Message List Props ==========
@@ -285,6 +294,10 @@ export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
    *  message's ChatMessageEnhanced. Owns the unified click rule
    *  (same-origin soft nav, cross-origin new tab). */
   NavLinkAnchor?: NavLinkAnchorComponent
+  /** Ask-card option pick. Forwarded verbatim to every message's
+   *  ChatMessageEnhanced; the host sends the received label as the user's next
+   *  message. Omit to render ask cards read-only. */
+  onAskSelect?: (label: string) => void
 }
 
 export interface ChatMessageListRef {
@@ -567,6 +580,20 @@ export interface GuideDisplayProps extends HTMLAttributes<HTMLDivElement> {
   children?: ReactNode
 }
 
+// ========== Ask Display Props ==========
+
+export interface AskDisplayProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /** The clarification cards to show. One entry per `ask` segment; a run of
+   *  consecutive segments is passed as ONE card with a pager, so a multi-question
+   *  turn reads as a single block instead of a stack of near-identical cards. */
+  cards: AskSegment[]
+  /** Picks an option. Receives the option's `label` VERBATIM — that string is
+   *  sent as the user's next message and the backend's classifier resolves it
+   *  against the labels it offered, so it must not be reworded. Omit to render
+   *  the card read-only (replayed history, observer surfaces). */
+  onSelect?: (label: string) => void
+}
+
 // ========== Model Display Props ==========
 
 export interface ModelDisplayProps extends HTMLAttributes<HTMLDivElement> {

package/src/components/chat/types/message.types.ts

@@ -11,6 +11,7 @@ export const MESSAGE_TYPE = {
   TEXT: 'TEXT',
   THINKING: 'THINKING',
   GUIDE: 'GUIDE',
+  ASK: 'ASK',
   EXECUTING_TOOL: 'EXECUTING_TOOL',
   EXECUTED_TOOL: 'EXECUTED_TOOL',
   APPROVAL_REQUEST: 'APPROVAL_REQUEST',
@@ -190,6 +191,28 @@ export type GuideSegment = {
   text: string
 }
 
+/** One reading the assistant offers in an `ask` card. `label` is BOTH the row's
+ *  headline and the exact text sent back when the row is picked — the backend's
+ *  guide classifier resolves the user's next message against the labels it
+ *  offered, so the reply must be the label verbatim. `description` is a short
+ *  clarifying line rendered under it. */
+export type AskOptionData = {
+  label: string
+  description?: string
+}
+
+/** Clarification card — the assistant asking WHICH reading of an ambiguous
+ *  question it should answer, rendered as a heading plus a list of clickable
+ *  options instead of prose bullets. NATS-only (the `ASK` chunk); the intro
+ *  sentence riding the same chunk becomes an ordinary `text` segment in front
+ *  of the card, so it goes through the normal markdown body pipeline. Unlike
+ *  the three delta streams an ask arrives whole — it is never coalesced. */
+export type AskSegment = {
+  type: 'ask'
+  question: string
+  options: AskOptionData[]
+}
+
 export type ToolExecutionSegment = {
   type: 'tool_execution'
   data: ToolExecutionData
@@ -228,7 +251,7 @@ export type ContextCompactionSegment = {
   summary?: string
 }
 
-export type MessageSegment = TextSegment | ThinkingSegment | GuideSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
+export type MessageSegment = TextSegment | ThinkingSegment | GuideSegment | AskSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
 
 export type MessageContent = string | MessageSegment[]
 
@@ -253,6 +276,16 @@ export interface GuideMessageData extends MessageDataBase {
   text?: string
 }
 
+/** Persisted `ASK` row (GraphQL `AskData`). `text` is the intro sentence, which
+ *  history replays as a text segment ahead of the card — same split the live
+ *  `ASK` chunk carries. */
+export interface AskMessageData extends MessageDataBase {
+  type: 'ASK'
+  text?: string
+  question?: string
+  options?: AskOptionData[]
+}
+
 export interface ExecutingToolMessageData extends MessageDataBase {
   type: 'EXECUTING_TOOL'
   integratedToolType?: string
@@ -335,6 +368,7 @@ export type MessageData =
   | TextMessageData
   | ThinkingMessageData
   | GuideMessageData
+  | AskMessageData
   | ExecutingToolMessageData
   | ExecutedToolMessageData
   | ApprovalRequestMessageData

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

@@ -930,102 +930,3 @@ describe('mid-stream refetch (turn partially persisted)', () => {
     expect(ids(merged)).toEqual([U0.id, A0.id, PERSISTED_PARTIAL.id, unrelatedLive.id])
   })
 })
-
-describe('ordering of surviving realtime messages', () => {
-  // The merge concatenates: all persisted history, then every realtime message
-  // the coverage rules kept, each side in its own order. These pin that
-  // contract, which nothing asserted before — the suite tested only WHICH
-  // messages survive, never where they land — and which an attempt to
-  // chronologically interleave the two sides repeatedly broke.
-  const H_U0: TestMessage = { ...U0, streamSeq: 5 }
-  const H_A0: TestMessage = { ...A0, streamSeq: 10 }
-  /**
-   * Sent from a notification while the window was away, and persisted. NO
-   * `streamSeq`: the backend does not stamp user MESSAGE_REQUEST rows, which is
-   * the missing signal that makes interleaving guesswork.
-   */
-  const AWAY_U: TestMessage = {
-    id: 'bbbb0001',
-    role: 'user',
-    content: 'replied from a notification',
-    timestamp: t(3000),
-  }
-  /** Mingo's answer to it. Assistant rows DO carry a sequence. */
-  const AWAY_A: TestMessage = {
-    id: 'bbbb0002',
-    role: 'assistant',
-    content: txt('answered while the window was away'),
-    timestamp: t(3100),
-    streamSeq: 80,
-  }
-
-  it('appends surviving realtime messages after all persisted history', () => {
-    // A technician direct message the snapshot has not caught up with. Its own
-    // role's persisted max (H_U0, seq 5) is below it, so coverage keeps it.
-    const unpersistedDirect: TestMessage = {
-      id: 'direct-1500-old',
-      role: 'user',
-      content: 'a direct message history has not persisted yet',
-      timestamp: t(1500),
-      streamSeq: 40,
-    }
-    const merged = mergeHistoryWithRealtime({
-      processedHistory: [H_U0, H_A0, AWAY_U, AWAY_A],
-      existingMessages: [H_U0, H_A0, unpersistedDirect],
-      streamingMessageId: null,
-      historyFetchedAt: 9000,
-      historyMaxStreamSeq: 80,
-      realtimeSeenStreamSeq: 40,
-    })
-
-    expect(ids(merged)).toEqual([H_U0.id, H_A0.id, AWAY_U.id, AWAY_A.id, unpersistedDirect.id])
-  })
-
-  it('keeps survivors in store order, sequence or no sequence', () => {
-    // The guard against reordering the two kinds against each other: an
-    // optimistic bubble carries no sequence and a replayed direct message does,
-    // and sorting by sequence would render the user's question below the reply
-    // that came after it.
-    const optimistic: TestMessage = {
-      id: 'optimistic-9400-x',
-      role: 'user',
-      content: 'just typed, no seq of its own',
-      timestamp: t(9400),
-    }
-    const laterDirect: TestMessage = {
-      id: 'direct-9500-x',
-      role: 'user',
-      content: 'and a direct message after it',
-      timestamp: t(9500),
-      streamSeq: 40,
-    }
-    const merged = mergeHistoryWithRealtime({
-      processedHistory: [H_U0, H_A0, AWAY_U, AWAY_A],
-      existingMessages: [H_U0, H_A0, optimistic, laterDirect],
-      streamingMessageId: null,
-      // Before either was minted, so neither can be in the snapshot.
-      historyFetchedAt: 9000,
-      historyMaxStreamSeq: 80,
-      realtimeSeenStreamSeq: 40,
-    })
-
-    expect(ids(merged)).toEqual([H_U0.id, H_A0.id, AWAY_U.id, AWAY_A.id, optimistic.id, laterDirect.id])
-  })
-
-  it('keeps history in snapshot order even when its sequences do not climb', () => {
-    // The snapshot is the server's account of the conversation; the merge is
-    // not entitled to second-guess it from a `streamSeq` that looks out of
-    // order, which is what any sort of the two sides together would do.
-    const outOfOrder: TestMessage = { ...H_A0, id: 'aaaa0009', streamSeq: 3 }
-    const merged = mergeHistoryWithRealtime({
-      processedHistory: [H_U0, outOfOrder, AWAY_U, AWAY_A],
-      existingMessages: [H_U0],
-      streamingMessageId: null,
-      historyFetchedAt: 9000,
-      historyMaxStreamSeq: 80,
-      realtimeSeenStreamSeq: 0,
-    })
-
-    expect(ids(merged)).toEqual([H_U0.id, outOfOrder.id, AWAY_U.id, AWAY_A.id])
-  })
-})