@flamingo-stack/openframe-frontend-core 0.0.458-snapshot.20260720215024 → 0.0.458

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

@@ -1,12 +1,12 @@
 "use client"
 
-import { useRef, useState, useEffect, useLayoutEffect, useImperativeHandle, forwardRef } from "react"
+import { useRef, useEffect, useLayoutEffect, useImperativeHandle, forwardRef } from "react"
 import { useStickToBottom } from "use-stick-to-bottom"
 import { cn } from "../../utils/cn"
 import { OverlayScrollArea } from '../ui/overlay-scroll-area'
 import { ChatMessageEnhanced } from "./chat-message-enhanced"
 import { ChatMessageListSkeleton } from "./chat-message-skeleton"
-import { DotsLoaderIcon, Arrow02DownIcon } from "../icons-v2-generated"
+import { DotsLoaderIcon } from "../icons-v2-generated"
 import { CyclingPhrase } from "./cycling-phrase"
 import type { ChatMessageListProps } from "./types"
 import { SCROLL_ANCHOR } from "./types/message.types"
@@ -28,11 +28,6 @@ const STREAMING_WORDS = [
   'Riffing',
 ] as const
 
-/** Distance from the bottom (px) still counted as "at the bottom".
- *  Mirrors `use-stick-to-bottom`'s internal `STICK_TO_BOTTOM_OFFSET_PX`
- *  so the jump-to-bottom button and the library agree on the boundary. */
-const BOTTOM_THRESHOLD_PX = 70
-
 /*
  * Stick-to-bottom: `use-stick-to-bottom` (stackblitz-labs)
  *
@@ -59,9 +54,6 @@ const BOTTOM_THRESHOLD_PX = 70
  *    chat / sent a message; show me the bottom immediately").
  *  - **Load-more sentinel** (top-of-list IntersectionObserver) for
  *    infinite-scroll-UP. Distinct concern from stick-to-bottom.
- *  - **Bottom-follow intent** (see `followBottomRef` below). The
- *    library's follow is gated on its own `isAtBottom` flag, which this
- *    list's layout can lose silently; we own the INTENT and re-assert.
  *
  * `useStickToBottom`'s returned refs are MUTABLE refs + ref callbacks
  * — pass them directly as `ref={scrollRef}` / `ref={contentRef}`.
@@ -151,45 +143,6 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
     const dialogIdRef = useRef(dialogId)
     dialogIdRef.current = dialogId
 
-    // ---- Bottom-follow intent (list-owned lock) ----------------------
-    // The library follows the bottom only while ITS OWN `isAtBottom` flag
-    // is true, and this list's layout loses that flag silently in two
-    // ways:
-    //
-    //  1. **The scroller's own box changes.** The library's
-    //     ResizeObserver watches `contentRef` (INSIDE the scroller) only.
-    //     The streaming loader unmounting and the host's source-chip row
-    //     mounting — both siblings BELOW the scroller (see render) —
-    //     change the scroller's `clientHeight`, which moves the bottom
-    //     without emitting anything the library can observe.
-    //  2. **Resize-induced scroll events read as a user gesture.**
-    //     Fetch-mode entity cards mount as a skeleton and settle to a
-    //     different height; a shrink clamps `scrollTop` down, and the
-    //     library's scroll handler can see that as a scroll-UP and
-    //     permanently escape the lock (its `resizeDifference` guard is a
-    //     `setTimeout(…, 1)` race, so this is intermittent).
-    //
-    // Either way the thread stops following mid-turn. It bites hardest on
-    // card-heavy answers — a slash-command listing (`/getting-started`)
-    // renders a dozen fetch-mode cards with cover images that keep
-    // resolving for SECONDS after the stream ends, so everything after
-    // the lock was lost lands below the fold.
-    //
-    // Fix: this list owns the INTENT. Sending a message (or opening a
-    // dialog) arms it; only a real user scroll-up gesture — or a
-    // top-anchored turn, which deliberately parks elsewhere — disarms it.
-    // While armed, ANY geometry change re-asserts `scrollToBottom`, and
-    // because that call also re-sets the library's `isAtBottom`, a lost
-    // lock self-heals instead of being permanent.
-    const followBottomRef = useRef(false)
-
-    // Drives the jump-to-bottom affordance. Derived from GEOMETRY, not
-    // from the library's `isAtBottom`: that flag is the one this list
-    // loses silently (see above), and a stale `true` would hide the
-    // button in exactly the situation it exists for. Threshold mirrors
-    // the library's own `STICK_TO_BOTTOM_OFFSET_PX`.
-    const [atBottom, setAtBottom] = useState(true)
-
     // Tracks previous render state for explicit "force-stick" decisions
     // (dialog change, first message, new user message). The library
     // covers ongoing streaming; these are about INTENT transitions.
@@ -226,13 +179,11 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
 
       if (dialogChanged) {
         // Opening a different chat — instant snap to bottom.
-        followBottomRef.current = true
         void scrollToBottom({ animation: 'instant', ignoreEscapes: true })
         return
       }
       if (newCount > 0 && prevCount === 0) {
         // First message arrived in an empty chat — instant snap.
-        followBottomRef.current = true
         void scrollToBottom({ animation: 'instant', ignoreEscapes: true })
         return
       }
@@ -257,193 +208,54 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
         const newSlice = prevLastIdx >= 0 ? messages.slice(prevLastIdx + 1) : messages.slice(prevCount)
         const hasNewUser = newSlice.some((m) => m.role === 'user')
         if (hasNewUser) {
-          // Arms the follow intent for the WHOLE turn: the answer's
-          // async growth (attachment images, streamed tokens, entity
-          // cards resolving out of their skeletons long after the
-          // stream ends) is re-asserted by the follow effect below.
-          // This replaces the old per-`<img>` `load`-handler hack —
-          // same defect class, but the ResizeObserver sees every
-          // source of growth, not just images present at send time.
-          followBottomRef.current = true
           void scrollToBottom({ animation: 'instant', ignoreEscapes: true })
+
+          // Image-attachment growth follow-up: if the new user message
+          // carries inline `<img>` elements (chat-attachment markdown
+          // emits `![alt](/api/storage/view/...)` which the markdown
+          // renderer turns into `<img>` / Next.js `<Image>`), those
+          // images load AFTER the initial paint. Each image-load grows
+          // the bubble height, but `useStickToBottom`'s `resize:
+          // 'smooth'` spring sometimes loses anchor under rapid
+          // resize events from Next.js Image's progressive
+          // dimensioning (observed: scroll lands 50-100px short of
+          // bottom — exactly one image-load short).
+          //
+          // Fix: after the initial scrollToBottom snaps, scan the
+          // content area for `<img>` elements that haven't loaded
+          // yet, and attach one-time `load` handlers that re-trigger
+          // `scrollToBottom`. Idempotent — runs for any image,
+          // affects only the new-user-message diff (effect dep is
+          // `messages`).
+          //
+          // `requestAnimationFrame` so the DOM has the new bubble
+          // before we query. Without rAF the new-message `<img>`s
+          // haven't been committed yet — querySelectorAll returns
+          // an empty set.
+          requestAnimationFrame(() => {
+            const el = contentRef.current
+            if (!el) return
+            const imgs = el.querySelectorAll('img')
+            imgs.forEach((img) => {
+              if (img.complete) return
+              const onLoad = () => {
+                img.removeEventListener('load', onLoad)
+                img.removeEventListener('error', onLoad)
+                // `ignoreEscapes: true` because the user may have
+                // accidentally moved scroll during the image-load
+                // window; we want their fresh send to be visible.
+                void scrollToBottom({ animation: 'instant', ignoreEscapes: true })
+              }
+              img.addEventListener('load', onLoad, { once: true })
+              img.addEventListener('error', onLoad, { once: true })
+            })
+          })
         }
         // Assistant-only new messages → the library's resize-watch
         // already keeps the bottom locked when the user hasn't
         // escaped. No explicit call needed; spring animation runs.
       }
-    }, [autoScroll, messages, dialogId, scrollToBottom])
-
-    // ---- Follow the bottom while the intent is armed -----------------
-    // Installs once per mount (all deps are stable). See the
-    // `followBottomRef` comment above for WHY this exists.
-    useEffect(() => {
-      if (!autoScroll) return
-      const scroller = scrollRef.current
-      const content = contentRef.current
-      if (!scroller || !content) return
-
-      // Re-assert on ANY geometry change. Deliberately WITHOUT
-      // `ignoreEscapes`: the library must stay free to hand control back
-      // on a real gesture mid-animation. Re-asserting is precisely what
-      // re-sets its `isAtBottom`, so a silently-lost lock recovers on the
-      // next resize instead of staying broken for the rest of the turn.
-      // Cheap to call repeatedly — the library returns the in-flight
-      // promise when an animation with the same behaviour is running.
-      const measure = () => {
-        const distance = scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight
-        setAtBottom(distance <= BOTTOM_THRESHOLD_PX)
-      }
-
-      const reassert = () => {
-        if (followBottomRef.current) void scrollToBottom({ animation: 'smooth' })
-        // Measured on every geometry change, follow armed or not: a
-        // sibling growing below the scroller moves the bottom without
-        // any scroll event, and the button has to notice.
-        measure()
-      }
-
-      const ro = new ResizeObserver(reassert)
-      ro.observe(content)   // tokens, entity cards, images
-      ro.observe(scroller)  // streaming loader / source chips below it
-
-      // --- user-intent disarm ---------------------------------------
-      // Only a deliberate move AWAY from the bottom releases the lock.
-      // Resize-derived scroll events are NOT gestures, which is exactly
-      // the distinction the library's heuristic gets wrong.
-      const disarm = () => {
-        followBottomRef.current = false
-      }
-      const onWheel = (e: WheelEvent) => {
-        if (e.deltaY < 0) disarm()
-      }
-      const onKeyDown = (e: KeyboardEvent) => {
-        if (e.key === 'ArrowUp' || e.key === 'PageUp' || e.key === 'Home') disarm()
-      }
-      let touchY: number | null = null
-      const onTouchStart = (e: TouchEvent) => {
-        touchY = e.touches[0]?.clientY ?? null
-      }
-      const onTouchMove = (e: TouchEvent) => {
-        const y = e.touches[0]?.clientY
-        if (y == null || touchY == null) return
-        if (y > touchY) disarm() // finger travels DOWN → content moves up
-        touchY = y
-      }
-      // Scrollbar drag emits neither wheel nor touch — a scrollTop
-      // DECREASE while the pointer is held down is the same intent.
-      //
-      // ALL pointer listeners are on `window`, deliberately. The viewport is
-      // wrapped in `OverlayScrollArea`, and OverlayScrollbars appends its
-      // scrollbar handles to the HOST element, NOT to the viewport we hold in
-      // `scroller`. A `pointerdown` on the overlay thumb therefore never
-      // reaches `scroller`, so listening there would leave `pointerDown`
-      // false and the user would be yanked back down mid-drag — the exact
-      // gesture this block exists to honor. `window` covers the native
-      // scrollbar and the overlay thumb alike.
-      //
-      // The POINTER listeners use CAPTURE phase. The currently-installed
-      // OverlayScrollbars was checked and calls no `stopPropagation` on its
-      // pointer path, so bubble would work today — but capture makes the
-      // guarantee structural instead of contingent on a third party's
-      // internals (a library bump, or any host component between us and
-      // `window`, could otherwise strand `pointerDown` at `false` and
-      // reintroduce the yank-back bug).
-      //
-      // `blur` deliberately does NOT use capture. Focus events don't bubble
-      // but they DO capture, so a capture listener on `window` fires for
-      // EVERY element blur in the document (the focus-delegation idiom) —
-      // any focus change during a hold, e.g. the chat input blurring as the
-      // user presses down on the scrollbar, would clear `pointerDown` and
-      // re-open the very yank-back bug this block prevents. A TRUE window
-      // blur targets `window` itself, so an at-target (bubble-phase)
-      // listener still receives it: capture buys nothing and costs
-      // correctness. Verified in jsdom: descendant blur reaches the capture
-      // listener only; window blur reaches both.
-      //
-      // `pointerDown` must be cleared by every way a drag can END, not just
-      // `pointerup`: a button released OUTSIDE the window, or the tab losing
-      // focus mid-drag, delivers no `pointerup` at all and would leave the
-      // flag stuck true. From then on ANY resize-induced scrollTop clamp — a
-      // fetch-mode card settling from skeleton to a shorter height, i.e. the
-      // exact case this whole block exists for — reads as a scroll-up gesture
-      // and drops the lock. Same for merely HOLDING the button down (text
-      // selection) while a card shrinks. Hence `pointercancel` + window
-      // `blur`.
-      let pointerDown = false
-      let lastScrollTop = scroller.scrollTop
-      const onPointerDown = () => {
-        pointerDown = true
-      }
-      // A drag that RELEASES at the live end expresses the same intent as
-      // clicking jump-to-bottom. The scroll events during that drag can't
-      // re-arm (see the gate in `onScroll`), and releasing the button emits
-      // no further `scroll`, so the re-arm is evaluated once here, when the
-      // gesture is actually over.
-      const rearmIfAtBottom = () => {
-        if (followBottomRef.current) return
-        const distance = scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight
-        if (distance <= BOTTOM_THRESHOLD_PX) followBottomRef.current = true
-      }
-      const endPointer = () => {
-        pointerDown = false
-        rearmIfAtBottom()
-      }
-      const onScroll = () => {
-        const st = scroller.scrollTop
-        if (pointerDown && st < lastScrollTop) disarm()
-        lastScrollTop = st
-        // Landing at the bottom by hand is the SAME expressed intent as
-        // clicking jump-to-bottom, so it re-arms a lock an earlier scroll-up
-        // released. Without it the thread sits at-bottom (button hidden,
-        // because `atBottom` is true) and then silently drifts away as the
-        // answer grows.
-        //
-        // Gated on the drag being OVER (`!pointerDown`). A mid-drag `scroll`
-        // is not a gesture that has ended, and a short scrollbar drag that
-        // starts at the live end stays inside the 70px band — so re-arming
-        // here would undo the `disarm()` two lines above on the very same
-        // event and yank the reader back down mid-drag. Releasing the button
-        // at the bottom still re-arms on the next scroll (or, if none
-        // follows, on the next deliberate return to the end).
-        if (
-          !pointerDown &&
-          !followBottomRef.current &&
-          scroller.scrollHeight - st - scroller.clientHeight <= BOTTOM_THRESHOLD_PX
-        ) {
-          followBottomRef.current = true
-        }
-        measure()
-      }
-      measure()
-
-      const winCapture = { capture: true, passive: true } as const
-
-      scroller.addEventListener('wheel', onWheel, { passive: true })
-      scroller.addEventListener('keydown', onKeyDown)
-      scroller.addEventListener('touchstart', onTouchStart, { passive: true })
-      scroller.addEventListener('touchmove', onTouchMove, { passive: true })
-      window.addEventListener('pointerdown', onPointerDown, winCapture)
-      scroller.addEventListener('scroll', onScroll, { passive: true })
-      window.addEventListener('pointerup', endPointer, winCapture)
-      window.addEventListener('pointercancel', endPointer, winCapture)
-      // Bubble phase, NOT capture — see the note above.
-      window.addEventListener('blur', endPointer, { passive: true })
-
-      return () => {
-        ro.disconnect()
-        scroller.removeEventListener('wheel', onWheel)
-        scroller.removeEventListener('keydown', onKeyDown)
-        scroller.removeEventListener('touchstart', onTouchStart)
-        scroller.removeEventListener('touchmove', onTouchMove)
-        // `capture` must match the add call or the listener is not removed.
-        window.removeEventListener('pointerdown', onPointerDown, { capture: true })
-        scroller.removeEventListener('scroll', onScroll)
-        window.removeEventListener('pointerup', endPointer, { capture: true })
-        window.removeEventListener('pointercancel', endPointer, { capture: true })
-        // Added WITHOUT capture — the remove must match.
-        window.removeEventListener('blur', endPointer)
-      }
-    }, [autoScroll, scrollRef, contentRef, scrollToBottom])
+    }, [autoScroll, messages, dialogId, scrollToBottom, contentRef])
 
     // ---- Passive-demo hard pin (pinBottom) ---------------------------
     // Scripted in-page replays (the Fae/Mingo demos) have no human at the
@@ -573,10 +385,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       // `stopScroll` MUST precede scrollIntoView — the imperative scrollTop
       // write is what the library's geometry tracker uses to flip
       // `escapedFromLock`, so any in-flight scrollToBottom spring is
-      // first cancelled. The list-owned follow intent is released for the
-      // same reason: this turn deliberately parks at the message TOP, so
-      // its own async growth must NOT drag the reader to the bottom.
-      followBottomRef.current = false
+      // first cancelled.
       stopScroll()
       // Instant (not smooth): the markdown body contains async <img>
       // children whose loads race a 300ms smooth animation and leave
@@ -720,139 +529,76 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       !(pendingApprovals && pendingApprovals.length > 0)
 
     return (
-      <div className="flex-1 min-h-0 flex flex-col">
-        {/* Positioning box for the jump-to-bottom button: it wraps ONLY the
-            scroller, so `absolute bottom-…` really is the scroller's lower
-            edge. The outer flex column also holds the streaming loader and the
-            approvals bar, and anchoring against THAT box put the button over
-            the loader for the whole of every stream — precisely when it is
-            most likely to be visible. */}
-        <div className="relative flex-1 min-h-0 flex flex-col">
-          <OverlayScrollArea
-            viewportRef={setScrollRef}
-            className="flex-1 min-h-0"
-            contentClassName={cn(
-              "flex flex-col overflow-x-hidden",
-              // `overscroll-contain` (default ON, opt-out via `overscrollContain={false}`):
-              // reaching the top/bottom of the thread must NOT chain the wheel/
-              // touch scroll to the page behind the chat — e.g. the company-hub
-              // deck (native body scroll + sticky slide panels) would otherwise
-              // advance slides while you scroll the chat (fixed in #1501; kept as
-              // the prop default here). Passive in-page DEMO chats disable it so
-              // the surrounding page keeps scrolling normally when the pointer is
-              // over the (non-interactive) thread.
-              overscrollContain && "overscroll-contain",
-              className,
+      <div className="relative flex-1 min-h-0 flex flex-col">
+        <OverlayScrollArea
+          viewportRef={setScrollRef}
+          className="flex-1 min-h-0"
+          contentClassName={cn(
+            "flex flex-col overflow-x-hidden",
+            // `overscroll-contain` (default ON, opt-out via `overscrollContain={false}`):
+            // reaching the top/bottom of the thread must NOT chain the wheel/
+            // touch scroll to the page behind the chat — e.g. the company-hub
+            // deck (native body scroll + sticky slide panels) would otherwise
+            // advance slides while you scroll the chat (fixed in #1501; kept as
+            // the prop default here). Passive in-page DEMO chats disable it so
+            // the surrounding page keeps scrolling normally when the pointer is
+            // over the (non-interactive) thread.
+            overscrollContain && "overscroll-contain",
+            className,
+          )}
+          {...props}
+        >
+          <div
+            ref={setContentRef}
+            className={cn(
+              // `fullWidth=true` drops the centered-narrow column for
+              // side-panel hosts (e.g. multi-platform-hub Mingo). Same
+              // semantics as ChatHeader / ChatInput / ChatFooter.
+              fullWidth
+                ? "flex w-full flex-col pb-[var(--spacing-system-xs)] min-w-0"
+                : "mx-auto flex w-full max-w-ods-content-narrow flex-col pb-[var(--spacing-system-xs)] min-w-0",
+              contentClassName ?? "px-[var(--spacing-system-m)]",
             )}
-            {...props}
+            style={{ minHeight: '100%' }}
           >
-            <div
-              ref={setContentRef}
-              className={cn(
-                // `fullWidth=true` drops the centered-narrow column for
-                // side-panel hosts (e.g. multi-platform-hub Mingo). Same
-                // semantics as ChatHeader / ChatInput / ChatFooter.
-                fullWidth
-                  ? "flex w-full flex-col pb-[var(--spacing-system-xs)] min-w-0"
-                  : "mx-auto flex w-full max-w-ods-content-narrow flex-col pb-[var(--spacing-system-xs)] min-w-0",
-                contentClassName ?? "px-[var(--spacing-system-m)]",
-              )}
-              style={{ minHeight: '100%' }}
-            >
-              {hasNextPage && (
-                <div ref={sentinelRef} className="h-px" />
-              )}
-              <div className="flex-1" />
-              {messages.map((message, index) => {
-                // Hidden messages (synthetic continuation prompts the host
-                // injects after an approval card) are part of the API
-                // conversation history but never render. Skipping here
-                // keeps the visible thread coherent — see
-                // `Message.hidden` doc-comment in message.types.ts.
-                if (message.hidden) return null
-                // ONE OWNER for the pending turn. Both send paths mint an empty
-                // assistant placeholder (the accumulation target — it MUST stay
-                // in state) and flip the phase to 'thinking'. Rendering it here
-                // too would put an author label with no body in the transcript
-                // WHILE the footer loader below already represents the same
-                // pending turn — two owners, and an `aria-live` log that
-                // announces a bare "Mingo". The footer loader wins (it is
-                // already `role="status" aria-live="polite"`, sits outside the
-                // scroller so it can't jitter the thread, and cycles the
-                // progress phrase), so the placeholder is not rendered AT ALL
-                // until it carries something visible — removed from the live
-                // region, not merely hidden. Mirrors `endSseTurn`, which prunes
-                // an empty trailing assistant AFTER a turn; this closes the same
-                // window BEFORE the first token. Any non-text segment (tool
-                // execution, approval card, thinking) counts as visible.
-                const isEmptyPendingTurn =
-                  index === messages.length - 1 &&
-                  isTyping &&
-                  message.role === 'assistant' &&
-                  !hasNonEmptyContent(message.content) &&
-                  (!Array.isArray(message.content) ||
-                    message.content.every((s) => s.type === 'text'))
-                if (isEmptyPendingTurn) return null
-                return (
-                  <ChatMessageEnhanced
-                    key={message.id}
-                    ref={getRegisterMessageEl(message.id)}
-                    role={message.role}
-                    name={message.name}
-                    content={message.content}
-                    timestamp={message.timestamp}
-                    isTyping={index === messages.length - 1 && isTyping && message.role === 'assistant'}
-                    avatar={showAvatars ? message.avatar : null}
-                    showAvatar={showAvatars}
-                    assistantType={message.assistantType || assistantType}
-                    approvalVariant={approvalVariant}
-                    authorType={message.authorType}
-                    assistantIcon={message.role !== 'user' ? assistantIcon : undefined}
-                    chatRefs={message.chatRefs}
-                    contextItems={message.contextItems}
-                    resolveContextIcon={resolveContextIcon}
-                    renderContextItem={renderContextItem}
-                    renderMention={renderMention}
-                    renderEntityCard={renderEntityCard}
-                    NavLinkAnchor={NavLinkAnchor}
-                  />
-                )
-              })}
-            </div>
-          </OverlayScrollArea>
-
-          {/* Jump to bottom. The manual escape hatch from auto-scroll that
-              every 2026 chat surface ships (AI Elements calls it
-              `ConversationScrollButton`) and the WCAG 2.2.2 counterpart to
-              moving content: the reader can always get back to the live
-              end without hunting for it. Positioned inside the scroller's
-              OWN `relative` wrapper above, so `bottom` really is the
-              scroller's lower edge and not the outer column's (which also
-              carries the streaming loader). It costs the thread no layout
-              height either way — a sibling would shrink the scroller and
-              move the very bottom it points at. Hidden while at the bottom
-              and in passive demo hosts. */}
-          {autoScroll && !atBottom && messages.length > 0 && (
-            <button
-              type="button"
-              onClick={() => {
-                // Clicking IS the intent to return to the live end, so it
-                // re-arms the follow lock a scroll-up had released.
-                followBottomRef.current = true
-                void scrollToBottom({ animation: 'smooth' })
-              }}
-              aria-label="Scroll to latest message"
-              className={cn(
-                "absolute bottom-[var(--spacing-system-s)] left-1/2 -translate-x-1/2 z-10",
-                "flex items-center justify-center size-9 rounded-full",
-                "bg-ods-card text-ods-text-primary border border-ods-border shadow-lg",
-                "hover:bg-ods-bg-hover transition-colors",
-              )}
-            >
-              <Arrow02DownIcon size={16} />
-            </button>
-          )}
-        </div>
+            {hasNextPage && (
+              <div ref={sentinelRef} className="h-px" />
+            )}
+            <div className="flex-1" />
+            {messages.map((message, index) => {
+              // Hidden messages (synthetic continuation prompts the host
+              // injects after an approval card) are part of the API
+              // conversation history but never render. Skipping here
+              // keeps the visible thread coherent — see
+              // `Message.hidden` doc-comment in message.types.ts.
+              if (message.hidden) return null
+              return (
+                <ChatMessageEnhanced
+                  key={message.id}
+                  ref={getRegisterMessageEl(message.id)}
+                  role={message.role}
+                  name={message.name}
+                  content={message.content}
+                  timestamp={message.timestamp}
+                  isTyping={index === messages.length - 1 && isTyping && message.role === 'assistant'}
+                  avatar={showAvatars ? message.avatar : null}
+                  showAvatar={showAvatars}
+                  assistantType={message.assistantType || assistantType}
+                  approvalVariant={approvalVariant}
+                  authorType={message.authorType}
+                  assistantIcon={message.role !== 'user' ? assistantIcon : undefined}
+                  chatRefs={message.chatRefs}
+                  contextItems={message.contextItems}
+                  resolveContextIcon={resolveContextIcon}
+                  renderContextItem={renderContextItem}
+                  renderMention={renderMention}
+                  renderEntityCard={renderEntityCard}
+                  NavLinkAnchor={NavLinkAnchor}
+                />
+              )
+            })}
+          </div>
+        </OverlayScrollArea>
 
         {/* Footer-pinned streaming loader — outside the scroller so it
             doesn't jitter as the streaming message grows. Color is set

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

@@ -1510,12 +1510,6 @@ function EmbeddableChatInner({
         content: m.segments && m.segments.length > 0 ? m.segments : m.content,
         timestamp,
         assistantType: m.role === 'assistant' ? ('mingo' as const) : undefined,
-        // `hidden` is load-bearing, NOT cosmetic: it carries synthetic rows
-        // (e.g. an auto-continuation directive) that the LLM must see but the
-        // reader must not. Dropping it here made the raw directive text render
-        // as an ordinary bubble. This field-by-field rebuild has to forward it
-        // explicitly — see `Message.hidden` and `chat-message-list`'s skip.
-        ...(m.hidden ? { hidden: true } : {}),
         ...(m.chatRefs ? { chatRefs: m.chatRefs } : {}),
         ...(m.scrollAnchor ? { scrollAnchor: m.scrollAnchor } : {}),
         // Forward attached context items so the user bubble renders its chips.

package/src/components/chat/hooks/.index.md

@@ -5,7 +5,7 @@ Barrel export file for the chat hooks module, re-exporting all public hooks from
 
 | Export Group | Hooks |
 |---|---|
-| **Realtime / Streaming** | `useChunkCatchup`, `useJetstreamDialogSubscription`, `useNatsDialogSubscription` |
+| **Realtime / Streaming** | `useChunkCatchup`, `useRealtimeChunkProcessor`, `useJetstreamDialogSubscription`, `useNatsDialogSubscription` |
 | **UI Utilities** | `useCollapsible`, `useCloseOnNavigation`, `useChatCardItem` |
 | **Chat Core** | `useChat`, `useSSE`, `useChatIdentity`, `useChatAttachments`, `useChatAttachmentImageGallery`, `useSlashCommands` |
 | **Transport Adapters** | `useSSEChatAdapter`, `useNatsChatAdapter` |

package/src/components/chat/hooks/.use-nats-chat-adapter.md

@@ -21,7 +21,7 @@ Main hook. Composes three internal hooks:
 ```text
 useNatsDialogSubscription  →  live NATS event tail
          ↓
-decodeNatsChunk + reducer  →  chunk → ChatStreamEvent → state
+useRealtimeChunkProcessor  →  chunk → MessageSegment[]
          ↓
 useChunkCatchup            →  back-fills missed chunks on reconnect/activation
 ```

package/src/components/chat/hooks/.use-realtime-chunk-processor.md

@@ -0,0 +1,50 @@
+<!-- source-hash: e37a3772ece6c09122bfe5d89ce800e0 -->
+Real-time NATS streaming chunk processor hook that converts raw streaming messages into typed message segments, managing stream state, tool execution, and approval workflows.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `useRealtimeChunkProcessor` | Hook | Primary hook for processing NATS stream chunks into UI-ready message segments |
+| `accumulatorRef` | Internal Ref | Holds a `MessageSegmentAccumulator` instance that tracks and builds segments across chunk events |
+| `isInStreamRef` | Internal Ref | Tracks whether a `MESSAGE_START`/`MESSAGE_END` boundary is active |
+| `hasEverStreamedRef` | Internal Ref | Distinguishes cold-start vs. resumed-dialog continuation mode |
+| `pendingEscalatedRef` | Internal Ref | Tracks escalated (non-display) approval requests awaiting results |
+
+### Handled Chunk Actions
+
+| Action | Behavior |
+|--------|----------|
+| `message_start` / `message_end` | Opens/closes stream window, resets segment accumulator |
+| `text` / `thinking` | Appends to accumulator; uses append mode post-stream |
+| `tool_execution` | Routes to accumulator in-stream, or `onToolExecuted` post-stream |
+| `approval_request` | Renders inline or escalates based on `displayApprovalTypes` |
+| `approval_batch` | Renders batch card or unfolds into legacy cards if `batchApprovalsEnabled = false` |
+| `approval_result` | Resolves escalated or inline approvals, updates accumulator status |
+| `error` | Parses error detail and emits error segment |
+
+## Usage Example
+
+```typescript
+const { processChunk } = useRealtimeChunkProcessor({
+  callbacks: {
+    onSegmentsUpdate: (segments, opts) => updateMessage(segments, opts),
+    onStreamStart: () => setStreaming(true),
+    onStreamEnd: () => setStreaming(false),
+    onApprove: (requestId) => approveToolCall(requestId),
+    onReject: (requestId) => rejectToolCall(requestId),
+    onEscalatedApproval: (requestId, data) => notifyTechnician(requestId, data),
+    onApprovalResolved: (requestId, status) => syncStatus(requestId, status),
+    onError: (error) => console.error(error),
+  },
+  displayApprovalTypes: ['CLIENT'],
+  approvalStatuses: { 'req-123': 'pending' },
+  enableThinking: false,
+  batchApprovalsEnabled: true,
+})
+
+// Feed raw NATS chunks directly
+natsSubscription.on('message', (msg) => processChunk(msg.data))
+```
+
+> **Note:** `batchApprovalsEnabled` defaults to `true`. Pass `false` to fall back to legacy per-call approval cards. Consumers using `onApprovalResolved` should omit `onSegmentsUpdate` handling for approval results to avoid bubble overwrites during status flips.

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

@@ -5,6 +5,7 @@ export * from './use-collapsible'
 export * from './use-scripted-stream'
 export * from './use-jetstream-dialog-subscription'
 export * from './use-nats-dialog-subscription'
+export * from './use-realtime-chunk-processor'
 
 // Chat hooks migrated from hub `hooks/*` (Task #7).
 export * from './use-slash-commands'