@flamingo-stack/openframe-frontend-core 0.0.508 → 0.0.509

package/src/components/chat/stream/delta-batcher.ts

@@ -0,0 +1,168 @@
+/**
+ * createDeltaBatcher — framework-free, append-only batching of the
+ * `text-delta` / `thinking-delta` / `guide-delta` events.
+ *
+ * WHY THIS IS SHARED (and not a hook-private detail): every host that drives a
+ * `ChatStreamReducer` from a raw transport needs the SAME batching, and a
+ * copy-paste of it drifts. The React wrapper (`useChatStreamReducer`) and any
+ * non-React mirror in a product app both consume this one implementation.
+ *
+ * Behaviour:
+ *   - `push(event, key)` queues delta events and returns true; anything else
+ *     returns false so the caller can flush + apply it synchronously (ordering:
+ *     completion state must always land on fully-applied deltas).
+ *   - CONSECUTIVE same-type deltas are COALESCED into one event (the reducer's
+ *     append semantics distribute over concatenation), so a 60-delta/sec turn
+ *     costs ONE `applyOne` per frame instead of 60. `text-delta` additionally
+ *     requires a matching `leading` flag before coalescing.
+ *   - A flush is scheduled on `requestAnimationFrame` when available, with a
+ *     timer fallback that is ALWAYS armed (rAF pauses in background tabs, and a
+ *     hidden chat panel must still keep its thread current).
+ *   - `key` is an opaque routing token handed back to `applyOne`. When it
+ *     changes, the pending batch is flushed against the PREVIOUS key first, so
+ *     deltas never land on the wrong dialog/side.
+ */
+
+import type {
+  ChatStreamEvent,
+  GuideDeltaEvent,
+  TextDeltaEvent,
+  ThinkingDeltaEvent,
+} from '../../../chat-protocol/events'
+
+export const DELTA_FLUSH_FALLBACK_MS = 50
+
+export type DeltaEvent = TextDeltaEvent | ThinkingDeltaEvent | GuideDeltaEvent
+
+export function isDeltaEvent(event: ChatStreamEvent): event is DeltaEvent {
+  return (
+    event.type === 'text-delta' ||
+    event.type === 'thinking-delta' ||
+    event.type === 'guide-delta'
+  )
+}
+
+export interface CreateDeltaBatcherOptions<K> {
+  /** Apply one (possibly coalesced) delta against `key`'s reducer. */
+  applyOne: (event: DeltaEvent, key: K | undefined) => void
+  /** Called after a flush that applied at least one delta. */
+  onFlushed?: (appliedCount: number) => void
+  /** Timer fallback in ms (default `DELTA_FLUSH_FALLBACK_MS`). */
+  fallbackMs?: number
+}
+
+export interface DeltaBatcher<K = unknown> {
+  /**
+   * Queue `event` when it is a delta (returns true). Non-delta events are NOT
+   * queued and return false — the caller flushes and applies them itself.
+   */
+  push(event: ChatStreamEvent, key?: K): boolean
+  /** Synchronously apply the pending batch and cancel any scheduled flush. */
+  flush(): void
+  /** Flush and release timers — call on teardown so tail deltas aren't lost. */
+  dispose(): void
+  /** Queued (post-coalescing) delta count. Test/diagnostic surface. */
+  readonly pendingCount: number
+}
+
+export function createDeltaBatcher<K = unknown>({
+  applyOne,
+  onFlushed,
+  fallbackMs = DELTA_FLUSH_FALLBACK_MS,
+}: CreateDeltaBatcherOptions<K>): DeltaBatcher<K> {
+  let pending: DeltaEvent[] = []
+  let pendingKey: K | undefined
+  let hasKey = false
+  let raf: number | null = null
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  function cancelScheduled(): void {
+    if (raf !== null) {
+      if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(raf)
+      raf = null
+    }
+    if (timer !== null) {
+      clearTimeout(timer)
+      timer = null
+    }
+  }
+
+  function flush(): void {
+    cancelScheduled()
+    if (pending.length === 0) return
+    const batch = pending
+    pending = []
+    const key = pendingKey
+    for (const delta of batch) applyOne(delta, key)
+    onFlushed?.(batch.length)
+  }
+
+  function schedule(): void {
+    if (raf !== null || timer !== null) return
+    if (typeof requestAnimationFrame === 'function') {
+      raf = requestAnimationFrame(() => {
+        raf = null
+        flush()
+      })
+    }
+    // Timer fallback ALWAYS armed: rAF pauses in background tabs.
+    timer = setTimeout(() => {
+      timer = null
+      flush()
+    }, fallbackMs)
+  }
+
+  return {
+    push(event, key) {
+      // A pending batch belonging to a previous key must land on ITS reducer
+      // before we start queueing for the new one.
+      if (!hasKey || !Object.is(pendingKey, key)) {
+        flush()
+        pendingKey = key
+        hasKey = true
+      }
+      if (!isDeltaEvent(event)) return false
+      const tail = pending[pending.length - 1]
+      // NEVER coalesce a delta whose seq does not ADVANCE past the tail's.
+      // Coalescing stamps the merged entry with the LAST pushed seq, so a
+      // redelivered / out-of-order delta arriving inside one frame would both
+      // concatenate its text (the reducer never sees it as a duplicate) and
+      // REWIND the batch's seq below an already-applied one. Pushing it as its
+      // own entry hands it to the reducer intact, where the `seq <=
+      // lastAppliedSeq` gate drops it — the batcher must not depend on hosts
+      // gating at dispatch.
+      // A seq-LESS tail is not "always advancing": merging a seq-BEARING delta
+      // onto it stamps the merged entry with that seq, which the reducer's gate
+      // then treats as the batch's position — a redelivered delta could rewind
+      // it. Coalesce onto a seq-less tail only when the incoming delta is
+      // likewise seq-less (a uniformly seq-less stream, e.g. SSE).
+      const seqAdvances =
+        tail?.seq == null ? event.seq == null : event.seq != null && event.seq > tail.seq
+      if (
+        tail &&
+        seqAdvances &&
+        tail.type === event.type &&
+        (tail.type !== 'text-delta' ||
+          (tail as TextDeltaEvent).leading === (event as TextDeltaEvent).leading)
+      ) {
+        pending[pending.length - 1] = {
+          ...tail,
+          text: tail.text + event.text,
+          ...(event.seq != null ? { seq: event.seq } : {}),
+        } as DeltaEvent
+      } else {
+        pending.push({ ...event })
+      }
+      schedule()
+      return true
+    },
+    flush,
+    dispose() {
+      flush()
+      cancelScheduled()
+    },
+    get pendingCount() {
+      return pending.length
+    },
+  }
+}

package/src/components/chat/stream/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Chat stream module — ONE master reader for every chat event source
+ * (SSE decoder, NATS chunk decoder, historical replay). See
+ * `chat-stream-reducer.ts` for the architecture note.
+ *
+ * NOTE: the pure message-mutation helpers (`appendToTrailingAssistant`,
+ * `applyToolExecutionToMessages`, …) are intentionally NOT star-exported
+ * here — their legacy public home is `use-nats-chat-adapter`, which
+ * re-exports them from `./message-mutations`; exporting the same bindings
+ * from two star-exported barrels would make them ambiguous and drop them
+ * from the chat barrel entirely.
+ */
+
+export {
+  createChatStreamReducer,
+  createEmptyTurnMeta,
+  type BeginSseSendOptions,
+  type ChatReducerEffect,
+  type ChatReducerState,
+  type ChatStreamReducer,
+  type ChatStreamReducerOptions,
+  type ChatTurnMetaState,
+  type EscalatedApprovalData,
+  type InitializeExtras,
+  type PendingEcho,
+} from './chat-stream-reducer'
+
+export {
+  createChatDialogStore,
+  DEFAULT_DIALOG_SIDE,
+  DEFAULT_MAX_REDUCERS,
+  MAX_PENDING_RETAIN_KEYS,
+  type ChatDialogSide,
+  type ChatDialogStore,
+  type CreateChatDialogStoreOptions,
+  type EvictedReducerState,
+} from './chat-dialog-store'
+
+// Framework-free delta batching — shared with NON-React hosts that drive a
+// reducer straight from a transport (they must NOT re-implement it).
+// `isDeltaEvent` + `DELTA_FLUSH_FALLBACK_MS` are deliberately NOT re-exported:
+// they are internals of the batcher (its own tests import them from the
+// module), and no consumer needs to classify or re-time deltas by hand.
+export {
+  createDeltaBatcher,
+  type CreateDeltaBatcherOptions,
+  type DeltaBatcher,
+  type DeltaEvent,
+} from './delta-batcher'
+
+export {
+  useChatStreamReducer,
+  type UseChatStreamReducerOptions,
+  type UseChatStreamReducerReturn,
+} from './use-chat-stream-reducer'

package/src/components/chat/stream/message-mutations.ts

@@ -0,0 +1,340 @@
+/**
+ * Pure message-mutation kernel for the master chat-stream reducer.
+ *
+ * These helpers were absorbed from `use-nats-chat-adapter.ts` in Phase 3 of
+ * the chat unification — they are the ONE implementation of "apply a stream
+ * fragment to a message thread". The reducer (`chat-stream-reducer.ts`) and
+ * the cross-side projections (`chat-dialog-store.ts`) both build on them.
+ *
+ * REFERENTIAL-STABILITY CONTRACT: every helper clones ONLY the touched
+ * message object (and the touched segment slot inside it). A value-level
+ * no-op — e.g. a replayed duplicate EXECUTED_TOOL whose merge would write
+ * identical values — returns the PRIOR references untouched, so React
+ * memoization over untouched messages survives redeliveries.
+ *
+ * Framework-free: no React, no timers.
+ */
+
+import type {
+  ApprovalBatchExecutionState,
+  ChatApprovalStatus,
+  MessageSegment,
+  ToolExecutionSegment,
+  ToolExecutionData,
+} from '../types'
+import type { UnifiedChatMessage } from '../types/unified-chat-state.types'
+
+export function nextId(role: 'user' | 'assistant'): string {
+  // Date.now() + counter sliver keeps ids monotonic even when two
+  // messages are produced inside the same ms tick (user + assistant
+  // placeholder fire back-to-back from a single sendMessage call).
+  return `${role}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`
+}
+
+/**
+ * Realtime user/direct/system chunks can be replays of rows already on
+ * screen. Content-window dedup is the LAST layer (seq-less transports only)
+ * — see the layer list in `chat-stream-reducer.ts`.
+ */
+export const CONTENT_DEDUP_WINDOW = 4
+export const SYSTEM_DEDUP_WINDOW = 10
+
+export function hasRecentMessage(
+  prev: UnifiedChatMessage[],
+  predicate: (message: UnifiedChatMessage) => boolean,
+  window: number,
+): boolean {
+  const start = Math.max(0, prev.length - window)
+  for (let i = prev.length - 1; i >= start; i--) {
+    if (predicate(prev[i])) return true
+  }
+  return false
+}
+
+/**
+ * Replace (or append) the trailing assistant message with the latest
+ * accumulated segments.
+ */
+export function updateTrailingAssistant(
+  prev: UnifiedChatMessage[],
+  segments: MessageSegment[],
+): UnifiedChatMessage[] {
+  const last = prev[prev.length - 1]
+  if (!last || last.role !== 'assistant') {
+    // No placeholder exists — append a fresh assistant message.
+    return [
+      ...prev,
+      {
+        id: nextId('assistant'),
+        role: 'assistant',
+        content: '',
+        segments,
+      },
+    ]
+  }
+  return [...prev.slice(0, -1), { ...last, segments }]
+}
+
+/**
+ * Append-mode counterpart of `updateTrailingAssistant` for post-MESSAGE_END
+ * continuation fragments (`SegmentsUpdateMetadata.append`). Coalesces
+ * trailing fragments of the same type, mirroring the accumulator; approval
+ * deltas upsert by request id so a replayed emit stays idempotent.
+ */
+export function appendToTrailingAssistant(
+  prev: UnifiedChatMessage[],
+  segments: MessageSegment[],
+): UnifiedChatMessage[] {
+  if (segments.length === 0) return prev
+  const last = prev[prev.length - 1]
+  if (!last || last.role !== 'assistant') {
+    return [
+      ...prev,
+      { id: nextId('assistant'), role: 'assistant', content: '', segments },
+    ]
+  }
+  const merged = [...(last.segments ?? [])]
+  for (const seg of segments) {
+    const tail = merged[merged.length - 1]
+    if (seg.type === 'text' && tail?.type === 'text') {
+      merged[merged.length - 1] = { type: 'text', text: tail.text + seg.text }
+    } else if (seg.type === 'thinking' && tail?.type === 'thinking') {
+      merged[merged.length - 1] = { type: 'thinking', text: tail.text + seg.text }
+    } else if (seg.type === 'guide' && tail?.type === 'guide') {
+      merged[merged.length - 1] = { type: 'guide', text: tail.text + seg.text }
+    } else if (seg.type === 'approval_batch') {
+      // Approval deltas must be IDEMPOTENT: the escalated-result emit can be
+      // seen twice (live + catch-up replay over hydrated history), so upsert
+      // by request id instead of raw-appending a duplicate card.
+      const idx = merged.findIndex(
+        (m) => m.type === 'approval_batch' && m.data.approvalRequestId === seg.data.approvalRequestId,
+      )
+      if (idx !== -1) merged[idx] = seg
+      else merged.push(seg)
+    } else if (seg.type === 'approval_request') {
+      // Legacy cards share one requestId across an unfolded batch — key on
+      // (requestId, command) so each tool's card upserts its own twin.
+      const idx = merged.findIndex(
+        (m) =>
+          m.type === 'approval_request' &&
+          m.data.requestId === seg.data.requestId &&
+          m.data.command === seg.data.command,
+      )
+      if (idx !== -1) merged[idx] = seg
+      else merged.push(seg)
+    } else {
+      // Other non-text segments are pushed RAW on purpose: EXECUTING↔EXECUTED
+      // pairing and batch merging are `applyToolExecutionToMessages`'s job
+      // (post-END tool chunks never reach this helper — the reducer routes
+      // them cross-message). Running the accumulator here would double-apply
+      // those rules.
+      merged.push(seg)
+    }
+  }
+  return [...prev.slice(0, -1), { ...last, segments: merged }]
+}
+
+/**
+ * Upsert a standalone context-compaction segment into the trailing assistant
+ * bubble. Compaction emissions arrive as the accumulator's CUMULATIVE array —
+ * only the compaction segment itself may be applied, or interleaved
+ * continuation text would duplicate. A `completed` segment replaces the last
+ * `started` one in place.
+ */
+export function upsertTrailingCompaction(
+  prev: UnifiedChatMessage[],
+  segments: MessageSegment[],
+): UnifiedChatMessage[] {
+  const compaction = [...segments].reverse().find((s) => s.type === 'context_compaction')
+  if (!compaction) return prev
+  const last = prev[prev.length - 1]
+  if (!last || last.role !== 'assistant') {
+    return [
+      ...prev,
+      { id: nextId('assistant'), role: 'assistant', content: '', segments: [compaction] },
+    ]
+  }
+  const existing = last.segments ?? []
+  // LAST 'started' segment (not first): with repeated compactions in one
+  // bubble the earlier ones are already completed-in-place, so the newest
+  // 'started' is the only one this completion can belong to.
+  const startedIdx = existing
+    .map((s) => s.type === 'context_compaction' && s.status === 'started')
+    .lastIndexOf(true)
+  const merged =
+    startedIdx !== -1
+      ? existing.map((s, i) => (i === startedIdx ? compaction : s))
+      : [...existing, compaction]
+  return [...prev.slice(0, -1), { ...last, segments: merged }]
+}
+
+/** Scoped value-compare for the fields a tool merge writes (status/type,
+ *  result, success, execId, restored title, parameters). Small objects —
+ *  JSON compare for `parameters` keeps a replayed duplicate a no-op even
+ *  when the transport rebuilt the object. */
+function sameToolData(a: ToolExecutionData, b: ToolExecutionData): boolean {
+  return (
+    a.type === b.type &&
+    a.integratedToolType === b.integratedToolType &&
+    a.toolFunction === b.toolFunction &&
+    a.toolTitle === b.toolTitle &&
+    a.result === b.result &&
+    a.success === b.success &&
+    a.toolExecutionRequestId === b.toolExecutionRequestId &&
+    (a.parameters === b.parameters ||
+      JSON.stringify(a.parameters ?? null) === JSON.stringify(b.parameters ?? null))
+  )
+}
+
+function sameExecutionState(
+  a: ApprovalBatchExecutionState | undefined,
+  b: ApprovalBatchExecutionState,
+): boolean {
+  return !!a && a.status === b.status && a.result === b.result && a.success === b.success
+}
+
+/**
+ * Cross-message tool-execution updater for post-MESSAGE_END tool chunks
+ * (approved commands executing after the approval bubble, async batch
+ * results). Scans messages from the end:
+ *  1) an `approval_batch` whose `toolCalls` contains the execution id →
+ *     merge into its `executions` map;
+ *  2) a matching `tool_execution` segment (same id, or EXECUTING with the
+ *     same tool for legacy id-less backends) → update in place;
+ *  3) no match → append the segment to the trailing assistant bubble.
+ *
+ * A value-level no-op (replayed duplicate) returns `prev` untouched.
+ */
+export function applyToolExecutionToMessages(
+  prev: UnifiedChatMessage[],
+  segment: ToolExecutionSegment,
+): UnifiedChatMessage[] {
+  const merged = mergeToolExecutionIfPresent(prev, segment)
+  if (merged !== null) return merged
+  return appendToTrailingAssistant(prev, [segment])
+}
+
+/**
+ * Merge-only variant of `applyToolExecutionToMessages` — the pure projection
+ * used for the cross-SIDE fan-out in `chat-dialog-store.ts`. Updates a
+ * matching batch slot / tool segment when present; returns `null` when
+ * nothing matches (the caller decides whether to append — projections never
+ * do, so a tool that belongs to one side only never grows a card on the
+ * other).
+ */
+export function mergeToolExecutionIfPresent(
+  prev: UnifiedChatMessage[],
+  segment: ToolExecutionSegment,
+): UnifiedChatMessage[] | null {
+  const toolData = segment.data
+  const execId = toolData.toolExecutionRequestId
+
+  for (let i = prev.length - 1; i >= 0; i--) {
+    const message = prev[i]
+    if (message.role !== 'assistant' || !message.segments) continue
+
+    for (let j = message.segments.length - 1; j >= 0; j--) {
+      const seg = message.segments[j]
+
+      if (
+        execId &&
+        seg.type === 'approval_batch' &&
+        seg.data.toolCalls.some((c) => c.toolExecutionRequestId === execId)
+      ) {
+        const prevExec: ApprovalBatchExecutionState | undefined = seg.data.executions?.[execId]
+        // Never downgrade a done batch slot back to executing (JetStream
+        // redelivery of the EXECUTING chunk after EXECUTED landed). Returning
+        // prev = matched-with-no-change, so the caller doesn't append either.
+        if (toolData.type === 'EXECUTING_TOOL' && prevExec?.status === 'done') {
+          return prev
+        }
+        const nextExec: ApprovalBatchExecutionState =
+          toolData.type === 'EXECUTED_TOOL'
+            ? { status: 'done', result: toolData.result, success: toolData.success }
+            : { status: 'executing', result: prevExec?.result, success: prevExec?.success }
+        // Value-level no-op (replayed duplicate) → prior references.
+        if (sameExecutionState(prevExec, nextExec)) return prev
+        const nextSegments = [...message.segments]
+        nextSegments[j] = {
+          ...seg,
+          data: { ...seg.data, executions: { ...(seg.data.executions ?? {}), [execId]: nextExec } },
+        }
+        const next = [...prev]
+        next[i] = { ...message, segments: nextSegments }
+        return next
+      }
+
+      if (seg.type === 'tool_execution') {
+        // KNOWN LIMIT (id-less chunks only — current backends always send
+        // toolExecutionRequestId): the fuzzy fallback pairs only with a
+        // segment still EXECUTING, so a replayed id-less EXECUTING/EXECUTED
+        // arriving after the pair completed matches nothing and falls to the
+        // caller's append (duplicate card). Widening the predicate to
+        // EXECUTED twins would instead swallow a LEGITIMATE second run of the
+        // same tool — without ids the two are indistinguishable, and losing a
+        // real run is worse than a duplicate card on a legacy transport.
+        const matches = execId
+          ? seg.data.toolExecutionRequestId === execId
+          : seg.data.type === 'EXECUTING_TOOL' &&
+            seg.data.integratedToolType === toolData.integratedToolType &&
+            seg.data.toolFunction === toolData.toolFunction
+        if (!matches) continue
+        // Never downgrade a completed segment back to EXECUTING (replayed
+        // EXECUTING chunk after its EXECUTED already landed).
+        if (toolData.type === 'EXECUTING_TOOL' && seg.data.type === 'EXECUTED_TOOL') {
+          return prev
+        }
+        const mergedData: ToolExecutionData = {
+          ...toolData,
+          toolTitle: toolData.toolTitle ?? seg.data.toolTitle,
+          parameters: toolData.parameters || seg.data.parameters,
+        }
+        // Value-level no-op (replayed duplicate) → prior references.
+        if (sameToolData(seg.data, mergedData)) return prev
+        const nextSegments = [...message.segments]
+        nextSegments[j] = { type: 'tool_execution', data: mergedData }
+        const next = [...prev]
+        next[i] = { ...message, segments: nextSegments }
+        return next
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Cross-message approval status flip (absorbed from the NATS adapter's
+ * `onApprovalResolved` handler). Idempotent + reference-preserving: only the
+ * messages/segments whose status (or resolvedByName) actually changes are
+ * cloned; a no-op returns `prev`.
+ */
+export function projectApprovalResolutionToMessages(
+  prev: UnifiedChatMessage[],
+  requestId: string,
+  status: ChatApprovalStatus,
+  resolvedByName?: string | null,
+): UnifiedChatMessage[] {
+  let changed = false
+  const next = prev.map((m) => {
+    if (m.role !== 'assistant' || !m.segments) return m
+    let msgChanged = false
+    const segs = m.segments.map((s) => {
+      if (s.type === 'approval_request' && s.data.requestId === requestId && s.status !== status) {
+        msgChanged = true
+        return { ...s, status }
+      }
+      if (s.type === 'approval_batch' && s.data.approvalRequestId === requestId) {
+        const nextResolvedBy = resolvedByName ?? s.resolvedByName
+        if (s.status === status && nextResolvedBy === s.resolvedByName) return s
+        msgChanged = true
+        return { ...s, status, resolvedByName: nextResolvedBy }
+      }
+      return s
+    })
+    if (!msgChanged) return m
+    changed = true
+    return { ...m, segments: segs }
+  })
+  return changed ? next : prev
+}

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

@@ -0,0 +1,126 @@
+'use client'
+
+/**
+ * useChatStreamReducer — thin React wrapper over a `ChatDialogStore` side.
+ *
+ *   - `useSyncExternalStore` over the store (snapshot identity is stable
+ *     between mutations, so untouched renders bail out);
+ *   - APPEND-ONLY DELTA BATCHING: delegated wholesale to the framework-free
+ *     `createDeltaBatcher` (same module) so a non-React host can share the
+ *     exact same coalescing/flush policy instead of re-implementing it.
+ *   - Any NON-delta event force-flushes the pending batch first, so ordering
+ *     is preserved and stream completion (`turn-end`, errors, approval
+ *     frames) always lands on fully-applied delta state. Adapters whose
+ *     transport has no terminal event (SSE) call `flushDeltas()` explicitly
+ *     before their end-of-turn command.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+import type { ChatStreamEvent } from '../../../chat-protocol/events'
+import {
+  DEFAULT_DIALOG_SIDE,
+  type ChatDialogSide,
+  type ChatDialogStore,
+} from './chat-dialog-store'
+import { createDeltaBatcher, type DeltaBatcher } from './delta-batcher'
+import type {
+  ChatReducerState,
+  ChatStreamReducer,
+  ChatStreamReducerOptions,
+} from './chat-stream-reducer'
+
+interface DialogKey {
+  dialogId: string
+  side: ChatDialogSide
+}
+
+export interface UseChatStreamReducerOptions {
+  store: ChatDialogStore
+  dialogId: string
+  side?: ChatDialogSide
+  /** Consulted once, when this (dialogId, side) reducer is first created. */
+  createReducerOptions?: () => ChatStreamReducerOptions
+}
+
+export interface UseChatStreamReducerReturn {
+  state: ChatReducerState
+  /** Apply a decoded event (deltas are batched; everything else immediate). */
+  applyEvent: (event: ChatStreamEvent) => void
+  /** Synchronously apply any pending delta batch. */
+  flushDeltas: () => void
+  /** Run reducer commands (adapter-driven, non-wire mutations). */
+  mutate: <T>(fn: (reducer: ChatStreamReducer) => T) => T
+  reducer: ChatStreamReducer
+}
+
+export function useChatStreamReducer({
+  store,
+  dialogId,
+  side = DEFAULT_DIALOG_SIDE,
+  createReducerOptions,
+}: UseChatStreamReducerOptions): UseChatStreamReducerReturn {
+  const optionsRef = useRef(createReducerOptions)
+  optionsRef.current = createReducerOptions
+
+  // Ensure the reducer exists before the first snapshot read.
+  const reducer = store.getReducer(dialogId, side, () => optionsRef.current?.() ?? {})
+
+  const getSnapshot = useCallback(() => store.getSnapshot(dialogId, side), [store, dialogId, side])
+  // Distinct server getter: `getSnapshot` is a pure read of a CLIENT-lived
+  // map, so reusing it for SSR would render a per-request-meaningless value
+  // (and, before it was made pure, silently accumulate reducers per request).
+  const getServerSnapshot = useCallback(() => store.getServerSnapshot(), [store])
+  const subscribe = useCallback((listener: () => void) => store.subscribe(listener), [store])
+  const state = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+
+  // Pin this key for as long as the hook is mounted, so the store's LRU can
+  // never evict a reducer a live panel is rendering.
+  useEffect(() => store.retain(dialogId, side), [store, dialogId, side])
+
+  // ── Delta batch ──────────────────────────────────────────────────────────
+  // Identity-stable key object: the batcher compares keys with `Object.is`,
+  // so it must only change when the (dialogId, side) VALUES change.
+  const keyRef = useRef<DialogKey>({ dialogId, side })
+  if (keyRef.current.dialogId !== dialogId || keyRef.current.side !== side) {
+    keyRef.current = { dialogId, side }
+  }
+  const storeRef = useRef(store)
+  storeRef.current = store
+
+  const batcherRef = useRef<DeltaBatcher<DialogKey> | null>(null)
+  if (batcherRef.current === null) {
+    batcherRef.current = createDeltaBatcher<DialogKey>({
+      applyOne: (event, key) => {
+        if (key) storeRef.current.apply(key.dialogId, key.side, event)
+      },
+    })
+  }
+  const batcher = batcherRef.current
+
+  const flushDeltas = useCallback(() => batcher.flush(), [batcher])
+
+  const applyEvent = useCallback(
+    (event: ChatStreamEvent) => {
+      // `push` flushes on key change and returns false for non-delta events;
+      // those flush the batch first (ordering) and apply synchronously, so
+      // completion state always lands on fully-applied deltas.
+      if (batcher.push(event, keyRef.current)) return
+      batcher.flush()
+      store.apply(dialogId, side, event)
+    },
+    [batcher, store, dialogId, side],
+  )
+
+  // Flush on unmount so a torn-down panel doesn't drop its tail deltas.
+  useEffect(() => () => batcher.dispose(), [batcher])
+
+  const mutate = useCallback(
+    <T,>(fn: (reducer: ChatStreamReducer) => T): T => store.mutate(dialogId, side, fn),
+    [store, dialogId, side],
+  )
+
+  return useMemo(
+    () => ({ state, applyEvent, flushDeltas, mutate, reducer }),
+    [state, applyEvent, flushDeltas, mutate, reducer],
+  )
+}