From 74b4317578669994cba5399cafc59125b3b5a3ee Mon Sep 17 00:00:00 2001
From: mlogclub <mlog1@qq.com>
Date: Wed, 29 Jul 2026 10:09:17 +0800
Subject: [PATCH] feat: refactor chat panel and message components for improved
 scrolling and message display

- Replaced manual scroll handling in ChatPanel with ConversationMessageScroller for better performance and maintainability.
- Introduced ConversationMessageBubble and ConversationMessageRow components for consistent message styling.
- Updated SupportChatMessageList to utilize new message components and scrolling logic.
- Added utility components for message scroller and message display, enhancing the overall chat experience.
- Updated package dependencies to include @shadcn/react for UI components.
---
 .../_components/detail.tsx                    | 377 +++++++-----------
 .../conversations/_components/chat-panel.tsx  | 206 +++-------
 .../chat/conversation-message-bubble.tsx      |  53 +++
 .../chat/conversation-message-row.tsx         | 104 +++++
 .../chat/conversation-message-scroller.tsx    | 151 +++++++
 web/components/support-chat/message-list.tsx  | 257 ++++--------
 web/components/ui/message-scroller.tsx        | 131 ++++++
 web/components/ui/message.tsx                 |  92 +++++
 web/package.json                              |   1 +
 web/pnpm-lock.yaml                            |  19 +
 10 files changed, 839 insertions(+), 552 deletions(-)
 create mode 100644 web/components/chat/conversation-message-bubble.tsx
 create mode 100644 web/components/chat/conversation-message-row.tsx
 create mode 100644 web/components/chat/conversation-message-scroller.tsx
 create mode 100644 web/components/ui/message-scroller.tsx
 create mode 100644 web/components/ui/message.tsx

diff --git a/web/app/dashboard/conversation-monitor/_components/detail.tsx b/web/app/dashboard/conversation-monitor/_components/detail.tsx
index a25e81c..6782109 100644
--- a/web/app/dashboard/conversation-monitor/_components/detail.tsx
+++ b/web/app/dashboard/conversation-monitor/_components/detail.tsx
@@ -2,13 +2,16 @@
 
 import { CheckCheckIcon, EyeIcon, MessageCircleMoreIcon } from "lucide-react";
 import Image from "next/image";
-import {
-  useCallback,
-  useEffect,
-  useLayoutEffect,
-  useRef,
-} from "react";
+import { useEffect } from "react";
 
+import { ConversationMessageBubble } from "@/components/chat/conversation-message-bubble";
+import {
+  ConversationMessageRow,
+} from "@/components/chat/conversation-message-row";
+import {
+  ConversationMessageScroller,
+  ConversationMessageScrollerItem,
+} from "@/components/chat/conversation-message-scroller";
 import { ImMessageHTML } from "@/components/im-message-html";
 import { useImageLightbox } from "@/components/image-lightbox";
 import { ProjectDialog } from "@/components/project-dialog";
@@ -114,51 +117,41 @@ function getParticipantIdentity(
   return participant.participantId || participant.externalParticipantId || "-";
 }
 
-function getMessageLayout(message: AdminMessage) {
-  if (message.senderType === "customer") {
-    return {
-      rowClassName: "justify-start",
-      bubbleClassName: "border-border/70 bg-muted/60 text-foreground shadow-sm",
-      htmlClassName: "[&_a]:text-foreground [&_a]:underline [&_img]:rounded-md",
-      recalledBubbleClassName:
-        "border-dashed border-border/70 bg-muted/40 text-muted-foreground",
-      recalledHtmlClassName: "text-muted-foreground [&_p]:text-muted-foreground",
-      metaClassName: "text-left",
-    };
+function getMessageAlign(message: AdminMessage): "start" | "end" {
+  return message.senderType === "customer" || message.senderType === "system"
+    ? "start"
+    : "end";
+}
+
+function getMessageVariant(message: AdminMessage) {
+  switch (message.senderType) {
+    case "agent":
+      return "agent" as const;
+    case "ai":
+      return "ai" as const;
+    case "system":
+      return "system" as const;
+    default:
+      return "customer" as const;
   }
-  if (message.senderType === "system") {
-    return {
-      rowClassName: "justify-center",
-      bubbleClassName:
-        "border-dashed border-border bg-muted/60 text-muted-foreground",
-      htmlClassName: "[&_a]:text-foreground [&_a]:underline [&_img]:rounded-md",
-      recalledBubbleClassName:
-        "border-dashed border-border/70 bg-muted/40 text-muted-foreground",
-      recalledHtmlClassName: "text-muted-foreground [&_p]:text-muted-foreground",
-      metaClassName: "text-center",
-    };
+}
+
+function getMessageHtmlClassName(message: AdminMessage, isRecalled: boolean) {
+  if (isRecalled) {
+    return message.senderType === "agent" || message.senderType === "ai"
+      ? "text-emerald-800 [&_p]:text-emerald-800"
+      : "text-muted-foreground [&_p]:text-muted-foreground";
   }
-  if (message.senderType === "ai") {
-    return {
-      rowClassName: "justify-end",
-      bubbleClassName: "border-primary/15 bg-primary/5 text-foreground shadow-sm",
-      htmlClassName: "[&_a]:text-foreground [&_a]:underline [&_img]:rounded-md",
-      recalledBubbleClassName:
-        "border-dashed border-emerald-200 bg-emerald-50 text-emerald-800",
-      recalledHtmlClassName: "text-emerald-800 [&_p]:text-emerald-800",
-      metaClassName: "text-right",
-    };
+  if (message.senderType === "agent") {
+    return "[&_p]:text-white [&_a]:text-white [&_a]:underline [&_img]:rounded-md";
   }
-  return {
-    rowClassName: "justify-end",
-    bubbleClassName: "border-transparent bg-emerald-600 text-white shadow-sm",
-    htmlClassName:
-      "[&_p]:text-white [&_a]:text-white [&_a]:underline [&_img]:rounded-md",
-    recalledBubbleClassName:
-      "border-dashed border-emerald-200 bg-emerald-50 text-emerald-800",
-    recalledHtmlClassName: "text-emerald-800 [&_p]:text-emerald-800",
-    metaClassName: "text-right",
-  };
+  return "[&_a]:text-foreground [&_a]:underline [&_img]:rounded-md";
+}
+
+function getRecalledBubbleClassName(message: AdminMessage) {
+  return message.senderType === "agent" || message.senderType === "ai"
+    ? "border-dashed border-emerald-200 bg-emerald-50 text-emerald-800"
+    : "border-dashed border-border/70 bg-muted/40 text-muted-foreground";
 }
 
 export function ConversationDetailDialog({
@@ -187,91 +180,14 @@ export function ConversationDetailDialog({
   const statusMeta = currentConversation
     ? getStatusMeta(currentConversation.status, t)
     : null;
-  const messageBottomRef = useRef<HTMLDivElement | null>(null);
-  const messagesScrollRootRef = useRef<HTMLDivElement | null>(null);
-  const loadMoreSentinelRef = useRef<HTMLDivElement | null>(null);
-  const pendingScrollAnchorRef = useRef<{
-    scrollHeight: number;
-    scrollTop: number;
-  } | null>(null);
-  const prevLoadingMoreRef = useRef(false);
   const { open: openImageLightbox, close: closeImageLightbox } =
     useImageLightbox();
 
-  const getMessagesViewport = useCallback((): HTMLElement | null => {
-    return (
-      messagesScrollRootRef.current?.querySelector(
-        '[data-slot="scroll-area-viewport"]',
-      ) ?? null
-    );
-  }, []);
-
   useEffect(() => {
     if (!open) {
       closeImageLightbox();
-      return;
     }
-    if (loading) {
-      return;
-    }
-    const bottom = messageBottomRef.current;
-    if (!bottom) {
-      return;
-    }
-    bottom.scrollIntoView({ block: "end", behavior: "smooth" });
-  }, [open, loading, closeImageLightbox]);
-
-  useLayoutEffect(() => {
-    const wasLoading = prevLoadingMoreRef.current;
-    prevLoadingMoreRef.current = loadingMoreMessages;
-    if (wasLoading && !loadingMoreMessages && pendingScrollAnchorRef.current) {
-      const vp = getMessagesViewport();
-      const anchor = pendingScrollAnchorRef.current;
-      pendingScrollAnchorRef.current = null;
-      if (vp && anchor) {
-        const delta = vp.scrollHeight - anchor.scrollHeight;
-        vp.scrollTop = anchor.scrollTop + delta;
-      }
-    }
-  }, [loadingMoreMessages, messages, getMessagesViewport]);
-
-  useEffect(() => {
-    if (!open || loading || !messagesHasMore || !onLoadMoreMessages) {
-      return;
-    }
-    const root = getMessagesViewport();
-    const sentinel = loadMoreSentinelRef.current;
-    if (!root || !sentinel) {
-      return;
-    }
-    const observer = new IntersectionObserver(
-      (entries) => {
-        const hit = entries.some((e) => e.isIntersecting);
-        if (!hit || loadingMoreMessages) {
-          return;
-        }
-        const vp = getMessagesViewport();
-        if (vp) {
-          pendingScrollAnchorRef.current = {
-            scrollHeight: vp.scrollHeight,
-            scrollTop: vp.scrollTop,
-          };
-        }
-        void onLoadMoreMessages();
-      },
-      { root, rootMargin: "120px 0px 0px 0px", threshold: 0 },
-    );
-    observer.observe(sentinel);
-    return () => observer.disconnect();
-  }, [
-    open,
-    loading,
-    messagesHasMore,
-    loadingMoreMessages,
-    messages.length,
-    onLoadMoreMessages,
-    getMessagesViewport,
-  ]);
+  }, [open, closeImageLightbox]);
 
   return (
     <ProjectDialog
@@ -364,8 +280,8 @@ export function ConversationDetailDialog({
           {t("conversationMonitor.loadingDetail")}
         </div>
       ) : currentConversation ? (
-        <div className="flex min-h-0 flex-1 flex-row overflow-hidden border-t">
-          <aside className="flex w-90 h-full shrink-0 flex-col overflow-hidden bg-muted/20 border-r border-b-0">
+        <div className="flex min-h-0 flex-1 flex-col overflow-hidden border-t md:flex-row">
+          <aside className="flex max-h-[46%] w-full shrink-0 flex-col overflow-hidden border-b bg-muted/20 md:h-full md:max-h-none md:w-90 md:border-r md:border-b-0">
             <div className="space-y-4 p-6">
               <div className="grid grid-cols-2 gap-3 text-sm">
                 <InfoItem
@@ -452,103 +368,40 @@ export function ConversationDetailDialog({
           </aside>
 
           <section className="flex h-full min-h-0 min-w-0 flex-1 flex-col overflow-hidden bg-background">
-            <div ref={messagesScrollRootRef} className="min-h-0 flex-1">
-              <ScrollArea className="h-full min-h-0 bg-muted/10">
-                <div className="space-y-4 px-6 py-5">
-                  {messagesHasMore ? (
-                    <div
-                      ref={loadMoreSentinelRef}
-                      className="flex min-h-8 flex-col items-center justify-center py-2 text-xs text-muted-foreground"
-                    >
-                      {loadingMoreMessages
-                        ? t("conversationMonitor.loadingOlder")
-                        : t("conversationMonitor.loadOlderHint")}
-                    </div>
-                  ) : null}
-                  {messages.length ? (
-                    messages.map((message) => {
-                      const layout = getMessageLayout(message);
-                      const isRecalled =
-                        Boolean(message.recalledAt) || message.sendStatus === 6;
-                      const isHtmlMessage =
-                        !isRecalled &&
-                        (message.messageType === "html" ||
-                          message.messageType === "attachment");
-                      const isImageMessage = !isRecalled && message.messageType === "image";
-
-                      return (
-                        <div
-                          key={message.id}
-                          className={`flex ${layout.rowClassName}`}
-                        >
-                          <div className="max-w-[85%] space-y-2">
-                            <div
-                              className={`text-xs text-muted-foreground ${layout.metaClassName}`}
-                            >
-                              <span>{getSenderLabel(message, t)}</span>
-                              <span className="mx-2">·</span>
-                              <span>{formatDateTime(message.sentAt)}</span>
-                              {isRecalled ? (
-                                <>
-                                  <span className="mx-2">·</span>
-                                  <span>{t("conversationMonitor.messageRecalled")}</span>
-                                </>
-                              ) : null}
-                            </div>
-                            <div
-                              className={`rounded-2xl border px-4 py-3 text-sm leading-6 ${
-                                isRecalled
-                                  ? layout.recalledBubbleClassName
-                                  : layout.bubbleClassName
-                              }`}
-                            >
-                              {isRecalled ? (
-                                <div className={layout.recalledHtmlClassName}>
-                                  {t("conversationMonitor.messageRecalledBody")}
-                                </div>
-                              ) : isHtmlMessage ? (
-                                <ImMessageHTML
-                                  html={renderIMMessageHTML(message)}
-                                  className={`${layout.htmlClassName} [&_img]:max-w-full [&_img]:cursor-zoom-in`}
-                                  onImageClick={openImageLightbox}
-                                />
-                              ) : isImageMessage ? (
-                                <MessageImage
-                                  src={getImageMessageUrl(message)}
-                                  alt={getMessageContent(message)}
-                                  onPreview={openImageLightbox}
-                                />
-                              ) : (
-                                <div className="whitespace-pre-wrap break-words">
-                                  {getMessageContent(message)}
-                                </div>
-                              )}
-                            </div>
-                            <div
-                              className={`text-xs text-muted-foreground ${layout.metaClassName}`}
-                            >
-                              {t("conversationMonitor.readStatus", {
-                                agent: message.agentRead
-                                  ? t("conversationMonitor.read")
-                                  : t("conversationMonitor.unread"),
-                                customer: message.customerRead
-                                  ? t("conversationMonitor.read")
-                                  : t("conversationMonitor.unread"),
-                              })}
-                            </div>
-                          </div>
-                        </div>
-                      );
-                    })
-                  ) : (
-                    <div className="flex h-full min-h-80 items-center justify-center rounded-xl border border-dashed bg-background text-sm text-muted-foreground">
-                      {t("conversationMonitor.emptyMessages")}
-                    </div>
-                  )}
-                  <div ref={messageBottomRef} />
+            <ConversationMessageScroller
+              key={currentConversation.id}
+              className="min-h-0 flex-1"
+              hasMoreOlder={messagesHasMore}
+              loadingOlder={loadingMoreMessages}
+              onLoadOlder={onLoadMoreMessages}
+              topSlot={
+                messagesHasMore ? (
+                  <div className="flex min-h-8 flex-col items-center justify-center py-2 text-xs text-muted-foreground">
+                    {loadingMoreMessages
+                      ? t("conversationMonitor.loadingOlder")
+                      : t("conversationMonitor.loadOlderHint")}
+                  </div>
+                ) : null
+              }
+            >
+              {messages.length ? (
+                messages.map((message) => (
+                  <ConversationMessageScrollerItem
+                    key={message.id}
+                    messageId={`${message.id}`}
+                  >
+                    <ConversationMonitorMessage
+                      message={message}
+                      onImagePreview={openImageLightbox}
+                    />
+                  </ConversationMessageScrollerItem>
+                ))
+              ) : (
+                <div className="flex h-full min-h-80 items-center justify-center rounded-xl border border-dashed bg-background text-sm text-muted-foreground">
+                  {t("conversationMonitor.emptyMessages")}
                 </div>
-              </ScrollArea>
-            </div>
+              )}
+            </ConversationMessageScroller>
           </section>
         </div>
       ) : (
@@ -560,6 +413,82 @@ export function ConversationDetailDialog({
   );
 }
 
+type ConversationMonitorMessageProps = {
+  message: AdminMessage;
+  onImagePreview: (src: string, alt?: string) => void;
+};
+
+function ConversationMonitorMessage({
+  message,
+  onImagePreview,
+}: ConversationMonitorMessageProps) {
+  const t = useI18n();
+  const isRecalled = Boolean(message.recalledAt) || message.sendStatus === 6;
+  const isHtmlMessage =
+    !isRecalled &&
+    (message.messageType === "html" || message.messageType === "attachment");
+  const isImageMessage = !isRecalled && message.messageType === "image";
+  const isSystem = message.senderType === "system";
+  const align = getMessageAlign(message);
+  const variant = isRecalled ? "recalled" : getMessageVariant(message);
+  const htmlClassName = getMessageHtmlClassName(message, isRecalled);
+
+  return (
+    <ConversationMessageRow
+      align={align}
+      centered={isSystem}
+      header={
+        <>
+          <span>{getSenderLabel(message, t)}</span>
+          <span>·</span>
+          <span>{formatDateTime(message.sentAt)}</span>
+          {isRecalled ? (
+            <>
+              <span>·</span>
+              <span>{t("conversationMonitor.messageRecalled")}</span>
+            </>
+          ) : null}
+        </>
+      }
+      footer={t("conversationMonitor.readStatus", {
+        agent: message.agentRead
+          ? t("conversationMonitor.read")
+          : t("conversationMonitor.unread"),
+        customer: message.customerRead
+          ? t("conversationMonitor.read")
+          : t("conversationMonitor.unread"),
+      })}
+    >
+      <ConversationMessageBubble
+        variant={variant}
+        className={isRecalled ? getRecalledBubbleClassName(message) : undefined}
+      >
+        {isRecalled ? (
+          <div className={htmlClassName}>
+            {t("conversationMonitor.messageRecalledBody")}
+          </div>
+        ) : isHtmlMessage ? (
+          <ImMessageHTML
+            html={renderIMMessageHTML(message)}
+            className={`${htmlClassName} [&_img]:max-w-full [&_img]:cursor-zoom-in`}
+            onImageClick={onImagePreview}
+          />
+        ) : isImageMessage ? (
+          <MessageImage
+            src={getImageMessageUrl(message)}
+            alt={getMessageContent(message)}
+            onPreview={onImagePreview}
+          />
+        ) : (
+          <div className="whitespace-pre-wrap break-words">
+            {getMessageContent(message)}
+          </div>
+        )}
+      </ConversationMessageBubble>
+    </ConversationMessageRow>
+  );
+}
+
 type InfoItemProps = {
   label: string;
   value: string;
diff --git a/web/app/dashboard/conversations/_components/chat-panel.tsx b/web/app/dashboard/conversations/_components/chat-panel.tsx
index adf235e..a62a2d3 100644
--- a/web/app/dashboard/conversations/_components/chat-panel.tsx
+++ b/web/app/dashboard/conversations/_components/chat-panel.tsx
@@ -5,7 +5,6 @@ import {
   type ReactNode,
   useCallback,
   useEffect,
-  useLayoutEffect,
   useRef,
   useState,
 } from "react";
@@ -20,6 +19,11 @@ import {
 import { toast } from "sonner";
 
 import { ConversationTransferDialog } from "@/components/conversation-actions/transfer-dialog";
+import {
+  ConversationMessageScroller,
+  ConversationMessageScrollerItem,
+  type ConversationMessageScrollerHandle,
+} from "@/components/chat/conversation-message-scroller";
 import { ImMessageHTML } from "@/components/im-message-html";
 import { useImageLightbox } from "@/components/image-lightbox";
 import { JsonTreeViewer } from "@/components/json-tree-viewer";
@@ -158,13 +162,10 @@ export function ChatPanel() {
   const setConversationFilter = useAgentConversationsStore(
     (state) => state.setConversationFilter,
   );
-  const messagesContainerRef = useRef<HTMLDivElement>(null);
-  const messagesContentRef = useRef<HTMLDivElement>(null);
-  const scrollBottomRafRef = useRef<number | null>(null);
-  const shouldStickToBottomRef = useRef(true);
-  const prependScrollAnchorRef = useRef<{ height: number; top: number } | null>(
+  const messagesScrollerRef = useRef<ConversationMessageScrollerHandle | null>(
     null,
   );
+  const shouldStickToBottomRef = useRef(true);
   const [claiming, setClaiming] = useState(false);
   const [claimDialogOpen, setClaimDialogOpen] = useState(false);
   const [transferDialogOpen, setTransferDialogOpen] = useState(false);
@@ -185,66 +186,19 @@ export function ChatPanel() {
     setConversationFilter("active" satisfies AgentConversationFilterKey);
   };
 
-  const getViewport = useCallback(
-    () => messagesContainerRef.current,
-    [],
-  );
-
-  const isNearBottom = useCallback(
-    (element: HTMLElement, threshold = 80) =>
-      element.scrollHeight - element.scrollTop - element.clientHeight <=
-      threshold,
-    [],
-  );
-
   const scrollToBottom = useCallback(() => {
-    const viewport = getViewport();
-    if (!viewport) {
-      return;
-    }
-    viewport.scrollTop = viewport.scrollHeight;
-  }, [getViewport]);
-
-  /**
-   * Match the widget message list: keep scrolling for a few frames until
-   * scrollHeight stabilizes, which prevents stacked scroll jumps.
-   */
-  const scheduleScrollToBottom = useCallback(
-    (attempts = 4) => {
-      if (scrollBottomRafRef.current !== null) {
-        cancelAnimationFrame(scrollBottomRafRef.current);
-      }
-      const run = (remaining: number, previousHeight = -1) => {
-        scrollBottomRafRef.current = requestAnimationFrame(() => {
-          const viewport = getViewport();
-          if (!viewport) {
-            scrollBottomRafRef.current = null;
-            return;
-          }
-          const currentHeight = viewport.scrollHeight;
-          scrollToBottom();
-          if (remaining > 1 && currentHeight !== previousHeight) {
-            run(remaining - 1, currentHeight);
-            return;
-          }
-          scrollBottomRafRef.current = null;
-        });
-      };
-      run(attempts);
-    },
-    [getViewport, scrollToBottom],
-  );
+    messagesScrollerRef.current?.scrollToBottom();
+  }, []);
 
   const handleImageSettled = useCallback(() => {
     if (!shouldStickToBottomRef.current) {
       return;
     }
-    scheduleScrollToBottom();
-  }, [scheduleScrollToBottom]);
+    scrollToBottom();
+  }, [scrollToBottom]);
 
   const maybeMarkConversationRead = useCallback(() => {
-    const viewport = getViewport();
-    if (!viewport || !conversation || loading) {
+    if (!conversation || loading || !shouldStickToBottomRef.current) {
       return;
     }
     if (
@@ -253,87 +207,19 @@ export function ChatPanel() {
     ) {
       return;
     }
-    if (!isNearBottom(viewport)) {
-      return;
-    }
     void markSelectedConversationRead().catch((error) => {
       toast.error(error instanceof Error ? error.message : t("conversation.markReadFailed"));
     });
   }, [
     conversation,
-    getViewport,
-    isNearBottom,
     loading,
     markSelectedConversationRead,
     t,
   ]);
 
   useEffect(() => {
-    const viewport = getViewport();
-    if (!viewport) {
-      return;
-    }
-
-    const handleScroll = () => {
-      shouldStickToBottomRef.current = isNearBottom(viewport);
-      if (shouldStickToBottomRef.current) {
-        maybeMarkConversationRead();
-      }
-    };
-
-    handleScroll();
-    viewport.addEventListener("scroll", handleScroll);
-    return () => {
-      viewport.removeEventListener("scroll", handleScroll);
-    };
-  }, [conversation?.id, getViewport, isNearBottom, maybeMarkConversationRead]);
-
-  useLayoutEffect(() => {
     shouldStickToBottomRef.current = true;
-    scheduleScrollToBottom();
-    return () => {
-      if (scrollBottomRafRef.current !== null) {
-        cancelAnimationFrame(scrollBottomRafRef.current);
-        scrollBottomRafRef.current = null;
-      }
-    };
-  }, [conversation?.id, scheduleScrollToBottom]);
-
-  useLayoutEffect(() => {
-    const viewport = getViewport();
-    if (!viewport) {
-      return;
-    }
-    const anchor = prependScrollAnchorRef.current;
-    if (anchor) {
-      prependScrollAnchorRef.current = null;
-      const nextHeight = viewport.scrollHeight;
-      viewport.scrollTop = nextHeight - anchor.height + anchor.top;
-      return;
-    }
-    if (shouldStickToBottomRef.current) {
-      scheduleScrollToBottom();
-    }
-  }, [messages, getViewport, scheduleScrollToBottom]);
-
-  useEffect(() => {
-    const content = messagesContentRef.current;
-    if (!content) {
-      return;
-    }
-
-    const observer = new ResizeObserver(() => {
-      if (!shouldStickToBottomRef.current) {
-        return;
-      }
-      scheduleScrollToBottom();
-    });
-
-    observer.observe(content);
-    return () => {
-      observer.disconnect();
-    };
-  }, [conversation?.id, scheduleScrollToBottom]);
+  }, [conversation?.id]);
 
   useEffect(() => {
     maybeMarkConversationRead();
@@ -358,18 +244,12 @@ export function ChatPanel() {
   }, [maybeMarkConversationRead]);
 
   const handleLoadOlder = async () => {
-    const viewport = getViewport();
-    if (!viewport || messagesLoadingMore || !messagesHasMore) {
+    if (messagesLoadingMore || !messagesHasMore) {
       return;
     }
-    prependScrollAnchorRef.current = {
-      height: viewport.scrollHeight,
-      top: viewport.scrollTop,
-    };
     try {
       await loadOlderMessages();
     } catch (error) {
-      prependScrollAnchorRef.current = null;
       toast.error(error instanceof Error ? error.message : t("conversation.loadHistoryFailed"));
     }
   };
@@ -450,12 +330,21 @@ export function ChatPanel() {
   }
 
   const messagesScroll = (
-    <div
-      ref={messagesContainerRef}
-      className="h-full min-h-0 flex-1 overflow-y-auto p-4 agent-desk-scrollbar"
-    >
-      <div ref={messagesContentRef} className="flex flex-col">
-        {!loading && messages.length > 0 && messagesHasMore ? (
+    <ConversationMessageScroller
+      key={conversation.id}
+      ref={messagesScrollerRef}
+      className="h-full min-h-0 flex-1"
+      viewportClassName="bg-transparent"
+      contentClassName="gap-0 p-4"
+      hasMoreOlder={!loading && messages.length > 0 && messagesHasMore}
+      loadingOlder={messagesLoadingMore}
+      onLoadOlder={handleLoadOlder}
+      onNearBottomChange={(nearBottom) => {
+        shouldStickToBottomRef.current = nearBottom;
+      }}
+      onNearBottomVisible={maybeMarkConversationRead}
+      topSlot={
+        !loading && messages.length > 0 && messagesHasMore ? (
           <div className="mb-4 flex justify-center">
             <Button
               type="button"
@@ -467,15 +356,20 @@ export function ChatPanel() {
               {messagesLoadingMore ? t("conversation.loading") : t("conversation.loadOlder")}
             </Button>
           </div>
-        ) : null}
-        {loading ? (
-          <div className="py-8 text-center text-sm text-muted-foreground">
-            {t("conversation.loading")}
-          </div>
-        ) : messages.length > 0 ? (
-          messages.map((message) => (
+        ) : null
+      }
+    >
+      {loading ? (
+        <div className="py-8 text-center text-sm text-muted-foreground">
+          {t("conversation.loading")}
+        </div>
+      ) : messages.length > 0 ? (
+        messages.map((message) => (
+          <ConversationMessageScrollerItem
+            key={message.id}
+            messageId={`${message.id}`}
+          >
             <MessageItem
-              key={message.id}
               message={message}
               onImageSettled={handleImageSettled}
               canRecall={message.senderType === "agent" && message.senderId === currentUserId}
@@ -485,14 +379,14 @@ export function ChatPanel() {
               }}
               onOpenWorkflowRun={openWorkflowRunDetail}
             />
-          ))
-        ) : (
-          <div className="py-8 text-center text-sm text-muted-foreground">
-            {t("conversation.emptyMessages")}
-          </div>
-        )}
-      </div>
-    </div>
+          </ConversationMessageScrollerItem>
+        ))
+      ) : (
+        <div className="py-8 text-center text-sm text-muted-foreground">
+          {t("conversation.emptyMessages")}
+        </div>
+      )}
+    </ConversationMessageScroller>
   );
 
   const bottomPanel = (
diff --git a/web/components/chat/conversation-message-bubble.tsx b/web/components/chat/conversation-message-bubble.tsx
new file mode 100644
index 0000000..ca324d0
--- /dev/null
+++ b/web/components/chat/conversation-message-bubble.tsx
@@ -0,0 +1,53 @@
+"use client"
+
+import type { ReactNode } from "react"
+
+import { cn } from "@/lib/utils"
+
+export type ConversationMessageVariant =
+  | "customer"
+  | "agent"
+  | "ai"
+  | "system"
+  | "recalled"
+
+type ConversationMessageBubbleProps = {
+  variant: ConversationMessageVariant
+  children: ReactNode
+  className?: string
+}
+
+function getBubbleClassName(variant: ConversationMessageVariant) {
+  switch (variant) {
+    case "customer":
+      return "border-border/70 bg-muted/60 text-foreground shadow-sm"
+    case "system":
+      return "border-dashed border-border bg-muted/60 text-muted-foreground"
+    case "ai":
+      return "border-primary/15 bg-primary/5 text-foreground shadow-sm"
+    case "agent":
+      return "border-transparent bg-emerald-600 text-white shadow-sm"
+    case "recalled":
+      return "border-dashed border-border/70 bg-muted/40 text-muted-foreground"
+    default:
+      return "border-border/70 bg-muted/60 text-foreground shadow-sm"
+  }
+}
+
+export function ConversationMessageBubble({
+  variant,
+  children,
+  className,
+}: ConversationMessageBubbleProps) {
+  return (
+    <div
+      className={cn(
+        "w-fit max-w-full rounded-2xl border px-4 py-3 text-sm leading-6",
+        getBubbleClassName(variant),
+        className,
+      )}
+    >
+      {children}
+    </div>
+  )
+}
diff --git a/web/components/chat/conversation-message-row.tsx b/web/components/chat/conversation-message-row.tsx
new file mode 100644
index 0000000..cb6b99e
--- /dev/null
+++ b/web/components/chat/conversation-message-row.tsx
@@ -0,0 +1,104 @@
+"use client"
+
+import type { ReactNode } from "react"
+
+import {
+  Message,
+  MessageAvatar,
+  MessageContent,
+  MessageFooter,
+  MessageHeader,
+} from "@/components/ui/message"
+import { cn } from "@/lib/utils"
+
+type ConversationMessageRowProps = {
+  align: "start" | "end"
+  centered?: boolean
+  header?: ReactNode
+  footer?: ReactNode
+  avatar?: ReactNode
+  children: ReactNode
+  className?: string
+  avatarClassName?: string
+  contentClassName?: string
+  headerClassName?: string
+  footerClassName?: string
+}
+
+export function ConversationMessageRow({
+  align,
+  centered = false,
+  header,
+  footer,
+  avatar,
+  children,
+  className,
+  avatarClassName,
+  contentClassName,
+  headerClassName,
+  footerClassName,
+}: ConversationMessageRowProps) {
+  if (centered) {
+    return (
+      <Message
+        align="start"
+        className={cn("justify-center", className)}
+      >
+        <MessageContent className={cn("w-fit max-w-[85%] items-center", contentClassName)}>
+          {header ? (
+            <MessageHeader className={cn("justify-center text-center", headerClassName)}>
+              {header}
+            </MessageHeader>
+          ) : null}
+          {children}
+          {footer ? (
+            <MessageFooter className={cn("justify-center text-center", footerClassName)}>
+              {footer}
+            </MessageFooter>
+          ) : null}
+        </MessageContent>
+      </Message>
+    )
+  }
+
+  return (
+    <Message align={align} className={className}>
+      {avatar ? (
+        <MessageAvatar className={cn("bg-transparent", avatarClassName)}>
+          {avatar}
+        </MessageAvatar>
+      ) : null}
+      <MessageContent
+        className={cn(
+          "max-w-[85%]",
+          align === "end" ? "items-end" : "items-start",
+          contentClassName,
+        )}
+      >
+        {header ? (
+          <MessageHeader
+            className={cn(
+              "gap-2 px-0",
+              align === "end" ? "justify-end text-right" : "justify-start text-left",
+              headerClassName,
+            )}
+          >
+            {header}
+          </MessageHeader>
+        ) : null}
+        {children}
+        {footer ? (
+          <MessageFooter
+            className={cn(
+              "gap-2 px-0",
+              align === "end" ? "justify-end text-right" : "justify-start text-left",
+              footerClassName,
+            )}
+          >
+            {footer}
+          </MessageFooter>
+        ) : null}
+      </MessageContent>
+    </Message>
+  )
+}
diff --git a/web/components/chat/conversation-message-scroller.tsx b/web/components/chat/conversation-message-scroller.tsx
new file mode 100644
index 0000000..d8deae0
--- /dev/null
+++ b/web/components/chat/conversation-message-scroller.tsx
@@ -0,0 +1,151 @@
+"use client"
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  type ReactNode,
+  type UIEvent,
+} from "react"
+
+import {
+  MessageScroller,
+  MessageScrollerButton,
+  MessageScrollerContent,
+  MessageScrollerItem,
+  MessageScrollerProvider,
+  MessageScrollerViewport,
+  useMessageScroller,
+  useMessageScrollerScrollable,
+} from "@/components/ui/message-scroller"
+import { cn } from "@/lib/utils"
+
+export type ConversationMessageScrollerHandle = {
+  scrollToBottom: () => void
+}
+
+type ConversationMessageScrollerProps = {
+  children: ReactNode
+  className?: string
+  viewportClassName?: string
+  contentClassName?: string
+  hasMoreOlder?: boolean
+  loadingOlder?: boolean
+  onLoadOlder?: () => void | Promise<void>
+  onNearBottomChange?: (nearBottom: boolean) => void
+  onNearBottomVisible?: () => void
+  topSlot?: ReactNode
+  scrollThreshold?: number
+}
+
+const ConversationMessageScrollerInner = forwardRef<
+  ConversationMessageScrollerHandle,
+  ConversationMessageScrollerProps
+>(function ConversationMessageScrollerInner(
+  {
+    children,
+    className,
+    viewportClassName,
+    contentClassName,
+    hasMoreOlder = false,
+    loadingOlder = false,
+    onLoadOlder,
+    onNearBottomChange,
+    onNearBottomVisible,
+    topSlot,
+    scrollThreshold = 120,
+  },
+  ref,
+) {
+  const { scrollToEnd } = useMessageScroller()
+  const scrollable = useMessageScrollerScrollable()
+  const loadingRef = useRef(false)
+  const nearBottomRef = useRef(false)
+  const onLoadOlderRef = useRef(onLoadOlder)
+  const onNearBottomChangeRef = useRef(onNearBottomChange)
+  const onNearBottomVisibleRef = useRef(onNearBottomVisible)
+
+  useEffect(() => {
+    onLoadOlderRef.current = onLoadOlder
+  }, [onLoadOlder])
+
+  useEffect(() => {
+    onNearBottomChangeRef.current = onNearBottomChange
+  }, [onNearBottomChange])
+
+  useEffect(() => {
+    onNearBottomVisibleRef.current = onNearBottomVisible
+  }, [onNearBottomVisible])
+
+  useEffect(() => {
+    loadingRef.current = loadingOlder
+  }, [loadingOlder])
+
+  useEffect(() => {
+    const nearBottom = !scrollable.end
+    nearBottomRef.current = nearBottom
+    onNearBottomChangeRef.current?.(nearBottom)
+    if (nearBottom) {
+      onNearBottomVisibleRef.current?.()
+    }
+  }, [scrollable.end])
+
+  useImperativeHandle(ref, () => ({
+    scrollToBottom: () => {
+      scrollToEnd({ behavior: "auto" })
+    },
+  }), [scrollToEnd])
+
+  const maybeLoadOlder = useCallback((viewport: HTMLElement) => {
+    if (!hasMoreOlder || loadingRef.current || !onLoadOlderRef.current) {
+      return
+    }
+    if (viewport.scrollTop > scrollThreshold) {
+      return
+    }
+    loadingRef.current = true
+    void Promise.resolve(onLoadOlderRef.current()).finally(() => {
+      loadingRef.current = false
+    })
+  }, [hasMoreOlder, scrollThreshold])
+
+  const handleScroll = useCallback(
+    (event: UIEvent<HTMLDivElement>) => {
+      maybeLoadOlder(event.currentTarget)
+    },
+    [maybeLoadOlder],
+  )
+
+  return (
+    <MessageScroller className={className}>
+      <MessageScrollerViewport
+        className={cn("agent-desk-scrollbar bg-muted/10", viewportClassName)}
+        onScroll={handleScroll}
+        preserveScrollOnPrepend
+      >
+        <MessageScrollerContent
+          className={cn("gap-4 px-6 py-5", contentClassName)}
+        >
+          {topSlot}
+          {children}
+        </MessageScrollerContent>
+      </MessageScrollerViewport>
+      <MessageScrollerButton />
+    </MessageScroller>
+  )
+})
+
+export const ConversationMessageScroller = forwardRef<
+  ConversationMessageScrollerHandle,
+  ConversationMessageScrollerProps
+>(function ConversationMessageScroller(props, ref) {
+  return (
+    <MessageScrollerProvider autoScroll defaultScrollPosition="end">
+      <ConversationMessageScrollerInner {...props} ref={ref} />
+    </MessageScrollerProvider>
+  )
+})
+
+export { MessageScrollerItem as ConversationMessageScrollerItem }
diff --git a/web/components/support-chat/message-list.tsx b/web/components/support-chat/message-list.tsx
index e423e7b..c225d18 100644
--- a/web/components/support-chat/message-list.tsx
+++ b/web/components/support-chat/message-list.tsx
@@ -6,10 +6,16 @@ import {
   useCallback,
   useEffect,
   useImperativeHandle,
-  useLayoutEffect,
   useRef,
 } from "react"
 
+import { ConversationMessageBubble } from "@/components/chat/conversation-message-bubble"
+import { ConversationMessageRow } from "@/components/chat/conversation-message-row"
+import {
+  ConversationMessageScroller,
+  ConversationMessageScrollerItem,
+  type ConversationMessageScrollerHandle,
+} from "@/components/chat/conversation-message-scroller"
 import { ImMessageHTML } from "@/components/im-message-html"
 import { useImageLightbox } from "@/components/image-lightbox"
 import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
@@ -79,150 +85,52 @@ export const SupportChatMessageList = forwardRef<SupportChatMessageListHandle, S
     ref
   ) {
     const t = useI18n()
-    const containerRef = useRef<HTMLDivElement>(null)
-    const contentRef = useRef<HTMLDivElement>(null)
-    const frameRef = useRef<number | null>(null)
+    const scrollerRef = useRef<ConversationMessageScrollerHandle | null>(null)
     const shouldStickToBottomRef = useRef(true)
     const onNearBottomVisibleRef = useRef(onNearBottomVisible)
     const safeMessages = Array.isArray(messages) ? messages : []
-    const lastMessageId = safeMessages.at(-1)?.id
 
     useEffect(() => {
       onNearBottomVisibleRef.current = onNearBottomVisible
     }, [onNearBottomVisible])
 
-    const isNearBottom = useCallback(
-      (element: HTMLElement, threshold = 80) =>
-        element.scrollHeight - element.scrollTop - element.clientHeight <= threshold,
-      []
-    )
-
     const scrollToBottom = useCallback(() => {
-      const container = containerRef.current
-      if (!container) {
-        return
-      }
-      container.scrollTop = container.scrollHeight
+      scrollerRef.current?.scrollToBottom()
     }, [])
 
-    const scheduleScrollToBottom = useCallback(
-      (attempts = 4) => {
-        if (frameRef.current !== null) {
-          cancelAnimationFrame(frameRef.current)
-        }
-
-        const run = (remaining: number, previousHeight = -1) => {
-          frameRef.current = requestAnimationFrame(() => {
-            const container = containerRef.current
-            if (!container) {
-              frameRef.current = null
-              return
-            }
-
-            const currentHeight = container.scrollHeight
-            scrollToBottom()
-            if (remaining > 1 && currentHeight !== previousHeight) {
-              run(remaining - 1, currentHeight)
-              return
-            }
-            frameRef.current = null
-          })
-        }
-
-        run(attempts)
-      },
-      [scrollToBottom]
-    )
-
     const handleImageSettled = useCallback(() => {
       if (shouldStickToBottomRef.current) {
-        scheduleScrollToBottom()
+        scrollToBottom()
         onNearBottomVisibleRef.current?.()
       }
-    }, [scheduleScrollToBottom])
+    }, [scrollToBottom])
 
     useImperativeHandle(ref, () => ({
       scrollToBottom,
     }))
 
-    useLayoutEffect(() => {
-      shouldStickToBottomRef.current = true
-      scheduleScrollToBottom()
-      return () => {
-        if (frameRef.current !== null) {
-          cancelAnimationFrame(frameRef.current)
-          frameRef.current = null
-        }
-      }
-    }, [lastMessageId, scheduleScrollToBottom])
-
-    useEffect(() => {
-      const container = containerRef.current
-      const content = contentRef.current
-      if (!container || !content) {
-        return
-      }
-
-      const handleScroll = () => {
-        shouldStickToBottomRef.current = isNearBottom(container)
-        if (shouldStickToBottomRef.current) {
-          onNearBottomVisible?.()
-        }
-      }
-
-      const resizeObserver = new ResizeObserver(() => {
-        if (shouldStickToBottomRef.current) {
-          scheduleScrollToBottom()
-        }
-      })
-
-      handleScroll()
-      container.addEventListener("scroll", handleScroll)
-      resizeObserver.observe(container)
-      resizeObserver.observe(content)
-      scrollToBottom()
-
-      return () => {
-        container.removeEventListener("scroll", handleScroll)
-        resizeObserver.disconnect()
-      }
-    }, [isNearBottom, onNearBottomVisible, scheduleScrollToBottom, scrollToBottom])
-
     const handleLoadOlder = useCallback(async () => {
       if (!onLoadOlder || loadingOlder || !hasMoreOlder) {
         return
       }
-      const container = containerRef.current
-      if (!container) {
-        return
-      }
-      const anchor = {
-        height: container.scrollHeight,
-        top: container.scrollTop,
-      }
-      try {
-        await onLoadOlder()
-      } catch {
-        return
-      }
-      requestAnimationFrame(() => {
-        requestAnimationFrame(() => {
-          const current = containerRef.current
-          if (!current) {
-            return
-          }
-          current.scrollTop = current.scrollHeight - anchor.height + anchor.top
-        })
-      })
+      await onLoadOlder()
     }, [hasMoreOlder, loadingOlder, onLoadOlder])
 
     return (
-      <div
-        ref={containerRef}
-        className="agent-desk-scrollbar flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto px-4 py-4"
-      >
-        <div ref={contentRef} className="flex flex-col gap-4">
-          {hasMoreOlder && onLoadOlder ? (
+      <ConversationMessageScroller
+        ref={scrollerRef}
+        className="flex min-h-0 flex-1"
+        viewportClassName="bg-transparent"
+        contentClassName="gap-4 px-4 py-4"
+        hasMoreOlder={hasMoreOlder}
+        loadingOlder={loadingOlder}
+        onLoadOlder={onLoadOlder}
+        onNearBottomChange={(nearBottom) => {
+          shouldStickToBottomRef.current = nearBottom
+        }}
+        onNearBottomVisible={onNearBottomVisible}
+        topSlot={
+          hasMoreOlder && onLoadOlder ? (
             <div className="flex justify-center py-1">
               <Button
                 type="button"
@@ -235,32 +143,36 @@ export const SupportChatMessageList = forwardRef<SupportChatMessageListHandle, S
                 {loadingOlder ? t("supportChat.loadingOlder") : t("supportChat.loadOlder")}
               </Button>
             </div>
-          ) : null}
+          ) : null
+        }
+      >
+        {safeMessages.length === 0 ? (
+          <div className="flex min-h-32 items-center justify-center px-3 py-6 text-center text-sm leading-6 text-muted-foreground">
+            {t("supportChat.emptyPrompt")}
+          </div>
+        ) : null}
 
-          {safeMessages.length === 0 ? (
-            <div className="flex min-h-32 items-center justify-center px-3 py-6 text-center text-sm leading-6 text-muted-foreground">
-              {t("supportChat.emptyPrompt")}
-            </div>
-          ) : null}
+        {safeMessages.map((message, index) => {
+          const previousMessage = index > 0 ? safeMessages[index - 1] : null
+          const showTimeline =
+            index === 0 ||
+            getDayKey(previousMessage?.sentAt) !== getDayKey(message.sentAt)
 
-          {safeMessages.map((message, index) => {
-            const previousMessage = index > 0 ? safeMessages[index - 1] : null
-            const showTimeline =
-              index === 0 ||
-              getDayKey(previousMessage?.sentAt) !== getDayKey(message.sentAt)
-
-            return (
+          return (
+            <ConversationMessageScrollerItem
+              key={message.id}
+              messageId={`${message.id}`}
+            >
               <MessageItem
-                key={message.id}
                 message={message}
                 showTimeline={showTimeline}
                 onImageSettled={handleImageSettled}
                 timelineLabel={getTimelineLabel(message.sentAt, t)}
               />
-            )
-          })}
-        </div>
-      </div>
+            </ConversationMessageScrollerItem>
+          )
+        })}
+      </ConversationMessageScroller>
     )
   }
 )
@@ -296,50 +208,51 @@ const MessageItem = memo(
           </div>
         ) : null}
 
-        <div className={cn("flex gap-2.5", isCustomer ? "justify-end" : "justify-start")}>
-          {!isCustomer ? (
-            <Avatar className="mt-5">
-              {avatarSrc ? <AvatarImage src={avatarSrc} alt="" /> : null}
-              <AvatarFallback className="bg-muted text-muted-foreground">
-                {fallbackName || t("supportChat.customerFallback")}
-              </AvatarFallback>
-            </Avatar>
-          ) : null}
-
-          <div
-            className={cn(
-              "flex max-w-[86%] flex-col gap-1.5",
-              isCustomer ? "items-end" : "items-start"
-            )}
-          >
-            <div className="flex flex-wrap items-center gap-x-2 gap-y-1 px-1 text-[11px] text-muted-foreground">
+        <ConversationMessageRow
+          align={isCustomer ? "end" : "start"}
+          avatar={
+            !isCustomer ? (
+              <Avatar>
+                {avatarSrc ? <AvatarImage src={avatarSrc} alt="" /> : null}
+                <AvatarFallback className="bg-muted text-muted-foreground">
+                  {fallbackName || t("supportChat.customerFallback")}
+                </AvatarFallback>
+              </Avatar>
+            ) : null
+          }
+          contentClassName="max-w-[86%] gap-1.5"
+          headerClassName="flex-wrap gap-x-2 gap-y-1 px-1 text-[11px]"
+          header={
+            <>
               <span className="font-medium">{senderName}</span>
               <span>{formatDateTime(message.sentAt)}</span>
               {isCustomer ? (
                 <span>{message.agentRead ? t("supportChat.agentRead") : t("supportChat.agentUnread")}</span>
               ) : null}
-            </div>
-            <div
+            </>
+          }
+        >
+          <ConversationMessageBubble
+            variant={isCustomer ? "customer" : "system"}
+            className={cn(
+              "rounded-lg border-0 px-3 py-2 text-sm leading-normal shadow-[0_10px_22px_rgba(15,23,42,0.06)]",
+              isCustomer
+                ? "bg-[#a9ea7a] text-[#161616] dark:bg-emerald-500 dark:text-emerald-950"
+                : "border border-border bg-card text-card-foreground dark:bg-background"
+            )}
+          >
+            <ImMessageHTML
+              html={htmlContent}
               className={cn(
-                "rounded-lg px-3 py-2 text-sm leading-normal shadow-[0_10px_22px_rgba(15,23,42,0.06)]",
                 isCustomer
-                  ? "bg-[#a9ea7a] text-[#161616] dark:bg-emerald-500 dark:text-emerald-950"
-                  : "border border-border bg-card text-card-foreground dark:bg-background"
+                  ? "[&_p]:text-[#161616] dark:[&_p]:text-emerald-950 [&_a]:text-[#161616] dark:[&_a]:text-emerald-950 [&_a]:underline [&_img]:cursor-zoom-in"
+                  : "[&_a]:text-card-foreground [&_a]:underline [&_img]:cursor-zoom-in"
               )}
-            >
-              <ImMessageHTML
-                html={htmlContent}
-                className={cn(
-                  isCustomer
-                    ? "[&_p]:text-[#161616] dark:[&_p]:text-emerald-950 [&_a]:text-[#161616] dark:[&_a]:text-emerald-950 [&_a]:underline [&_img]:cursor-zoom-in"
-                    : "[&_a]:text-card-foreground [&_a]:underline [&_img]:cursor-zoom-in"
-                )}
-                onImageSettled={onImageSettled}
-                onImageClick={open}
-              />
-            </div>
-          </div>
-        </div>
+              onImageSettled={onImageSettled}
+              onImageClick={open}
+            />
+          </ConversationMessageBubble>
+        </ConversationMessageRow>
       </div>
     )
   },
diff --git a/web/components/ui/message-scroller.tsx b/web/components/ui/message-scroller.tsx
new file mode 100644
index 0000000..be2fb5b
--- /dev/null
+++ b/web/components/ui/message-scroller.tsx
@@ -0,0 +1,131 @@
+"use client"
+
+import * as React from "react"
+import {
+  MessageScroller as MessageScrollerPrimitive,
+  useMessageScroller,
+  useMessageScrollerScrollable,
+  useMessageScrollerVisibility,
+} from "@shadcn/react/message-scroller"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { ArrowDownIcon } from "lucide-react"
+
+function MessageScrollerProvider(
+  props: React.ComponentProps<typeof MessageScrollerPrimitive.Provider>
+) {
+  return <MessageScrollerPrimitive.Provider {...props} />
+}
+
+function MessageScroller({
+  className,
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Root>) {
+  return (
+    <MessageScrollerPrimitive.Root
+      data-slot="message-scroller"
+      className={cn(
+        "group/message-scroller relative flex size-full min-h-0 flex-col overflow-hidden",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageScrollerViewport({
+  className,
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Viewport>) {
+  return (
+    <MessageScrollerPrimitive.Viewport
+      data-slot="message-scroller-viewport"
+      className={cn(
+        "size-full min-h-0 min-w-0 scroll-fade-b scrollbar-thin scrollbar-gutter-stable overflow-y-auto overscroll-contain contain-content data-autoscrolling:scrollbar-thumb-transparent data-autoscrolling:scrollbar-track-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageScrollerContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Content>) {
+  return (
+    <MessageScrollerPrimitive.Content
+      data-slot="message-scroller-content"
+      className={cn("flex h-max min-h-full flex-col gap-6", className)}
+      {...props}
+    />
+  )
+}
+
+function MessageScrollerItem({
+  className,
+  scrollAnchor = false,
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Item>) {
+  return (
+    <MessageScrollerPrimitive.Item
+      data-slot="message-scroller-item"
+      scrollAnchor={scrollAnchor}
+      className={cn(
+        "min-w-0 shrink-0 [contain-intrinsic-size:auto_10rem] [content-visibility:auto]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageScrollerButton({
+  direction = "end",
+  className,
+  children,
+  render,
+  variant = "secondary",
+  size = "icon-sm",
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Button> &
+  Pick<React.ComponentProps<typeof Button>, "variant" | "size">) {
+  return (
+    <MessageScrollerPrimitive.Button
+      data-slot="message-scroller-button"
+      data-direction={direction}
+      data-variant={variant}
+      data-size={size}
+      direction={direction}
+      className={cn(
+        "absolute inset-s-1/2 -translate-x-1/2 border-border bg-background text-foreground transition-[translate,scale,opacity] duration-200 hover:bg-muted hover:text-foreground data-[active=false]:pointer-events-none data-[active=false]:scale-95 data-[active=false]:opacity-0 data-[active=false]:duration-400 data-[active=false]:ease-[cubic-bezier(0.7,0,0.84,0)] data-[active=true]:translate-y-0 data-[active=true]:scale-100 data-[active=true]:opacity-100 data-[active=true]:ease-[cubic-bezier(0.23,1,0.32,1)] data-[direction=end]:bottom-4 data-[direction=end]:data-[active=false]:translate-y-full data-[direction=start]:top-4 data-[direction=start]:data-[active=false]:-translate-y-full rtl:translate-x-1/2 data-[direction=start]:[&_svg]:rotate-180",
+        className
+      )}
+      render={render ?? <Button variant={variant} size={size} />}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <ArrowDownIcon
+          />
+          <span className="sr-only">
+            {direction === "end" ? "Scroll to end" : "Scroll to start"}
+          </span>
+        </>
+      )}
+    </MessageScrollerPrimitive.Button>
+  )
+}
+
+export {
+  MessageScrollerProvider,
+  MessageScroller,
+  MessageScrollerViewport,
+  MessageScrollerContent,
+  MessageScrollerItem,
+  MessageScrollerButton,
+  useMessageScroller,
+  useMessageScrollerScrollable,
+  useMessageScrollerVisibility,
+}
diff --git a/web/components/ui/message.tsx b/web/components/ui/message.tsx
new file mode 100644
index 0000000..53437e8
--- /dev/null
+++ b/web/components/ui/message.tsx
@@ -0,0 +1,92 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function MessageGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-group"
+      className={cn("flex min-w-0 flex-col gap-2", className)}
+      {...props}
+    />
+  )
+}
+
+function Message({
+  className,
+  align = "start",
+  ...props
+}: React.ComponentProps<"div"> & { align?: "start" | "end" }) {
+  return (
+    <div
+      data-slot="message"
+      data-align={align}
+      className={cn(
+        "group/message relative flex w-full min-w-0 gap-2 text-sm data-[align=end]:flex-row-reverse",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageAvatar({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-avatar"
+      className={cn(
+        "flex w-fit min-w-8 shrink-0 items-center justify-center self-end overflow-hidden rounded-full bg-muted group-has-data-[slot=message-footer]/message:-translate-y-8",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-content"
+      className={cn(
+        "flex w-full min-w-0 flex-col gap-2.5 wrap-break-word group-data-[align=end]/message:*:data-slot:self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-header"
+      className={cn(
+        "flex max-w-full min-w-0 items-center px-3 text-xs font-medium text-muted-foreground group-has-data-[variant=ghost]/message:px-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-footer"
+      className={cn(
+        "flex max-w-full min-w-0 items-center px-3 text-xs font-medium text-muted-foreground group-has-data-[variant=ghost]/message:px-0 group-data-[align=end]/message:justify-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  MessageGroup,
+  Message,
+  MessageAvatar,
+  MessageContent,
+  MessageFooter,
+  MessageHeader,
+}
diff --git a/web/package.json b/web/package.json
index 6935d2b..f44c4a6 100644
--- a/web/package.json
+++ b/web/package.json
@@ -17,6 +17,7 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@hookform/resolvers": "^5.2.2",
+    "@shadcn/react": "^0.2.1",
     "@tanstack/react-table": "^8.21.3",
     "@tiptap/extension-image": "^3.20.2",
     "@tiptap/extension-link": "^3.20.2",
diff --git a/web/pnpm-lock.yaml b/web/pnpm-lock.yaml
index 6caec67..8abface 100644
--- a/web/pnpm-lock.yaml
+++ b/web/pnpm-lock.yaml
@@ -26,6 +26,9 @@ importers:
       '@hookform/resolvers':
         specifier: ^5.2.2
         version: 5.2.2(react-hook-form@7.71.2(react@19.2.3))
+      '@shadcn/react':
+        specifier: ^0.2.1
+        version: 0.2.1(@types/react@19.2.14)(react@19.2.3)
       '@tanstack/react-table':
         specifier: ^8.21.3
         version: 8.21.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -1191,6 +1194,17 @@ packages:
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
+  '@shadcn/react@0.2.1':
+    resolution: {integrity: sha512-5krgi3dRMKb5jH6a+qPzVJUy/54s0kKE4Rw4LjDfLqOdVQTWKUgxWf1kW8r912I0jX/Lzxqc+pgjkjWxUIK5BQ==}
+    peerDependencies:
+      '@types/react': '>=19'
+      react: '>=19'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      react:
+        optional: true
+
   '@sindresorhus/merge-streams@4.0.0':
     resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
     engines: {node: '>=18'}
@@ -5364,6 +5378,11 @@ snapshots:
 
   '@sec-ant/readable-stream@0.4.1': {}
 
+  '@shadcn/react@0.2.1(@types/react@19.2.14)(react@19.2.3)':
+    optionalDependencies:
+      '@types/react': 19.2.14
+      react: 19.2.3
+
   '@sindresorhus/merge-streams@4.0.0': {}
 
   '@standard-schema/utils@0.3.0': {}