@adatechnology/conversations-ui 0.3.1 → 0.3.2

package/dist/index.d.ts

@@ -1643,6 +1643,11 @@ interface UseConversationMessagesResult {
         bodyParams?: string[];
     }) => Promise<void>;
     markRead: () => Promise<void>;
+    /** Busca a página anterior de mensagens e prepende ao histórico já carregado. */
+    loadOlderMessages: () => Promise<void>;
+    loadingOlderMessages: boolean;
+    /** `false` assim que uma página vier menor que o limite — não há mais o que buscar antes dela. */
+    hasMoreOlderMessages: boolean;
 }
 declare function useConversationMessages(conversationId: string, params?: {
     limit?: number;
@@ -1941,6 +1946,8 @@ interface ConversationsWorkspaceLabels {
     readonly templateModalSend: (count: number) => string;
     readonly messagesSelected: (count: number) => string;
     readonly copySelected: string;
+    readonly loadOlderMessages: string;
+    readonly loadingOlderMessages: string;
     readonly composerPlaceholder: string;
     readonly attachFailure: string;
     /** Tira um arquivo da fila antes de enviar. */

package/dist/index.js

@@ -4040,7 +4040,30 @@ function MessagesWorkspace({
 }
 
 // src/hooks/useConversationMessages.ts
-import { useCallback as useCallback7 } from "react";
+import { useCallback as useCallback7, useEffect as useEffect10, useMemo as useMemo3, useRef as useRef7, useState as useState15 } from "react";
+var OLDER_MESSAGES_PAGE_LIMIT = 50;
+function dedupeMessagesById(messages) {
+  const seenIds = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const message of messages) {
+    if (seenIds.has(message.id)) continue;
+    seenIds.add(message.id);
+    deduped.push(message);
+  }
+  return deduped;
+}
+function prependOlderMessages(accumulated, olderPage) {
+  const existingIds = new Set(accumulated.map((message) => message.id));
+  const newMessages = olderPage.filter((message) => !existingIds.has(message.id));
+  return [...newMessages, ...accumulated];
+}
+function shouldFetchOlderMessages(state) {
+  if (state.isLoading || !state.hasMore) return false;
+  return Boolean(state.oldestMessage);
+}
+function pageIndicatesMoreOlderMessages(pageLength, limit) {
+  return pageLength >= limit;
+}
 function useConversationMessages(conversationId, params) {
   const context = useConversations();
   if (!context) {
@@ -4051,6 +4074,38 @@ function useConversationMessages(conversationId, params) {
     () => api.fetchMessages(conversationId, params),
     [conversationId, params?.limit, params?.before]
   );
+  const [olderMessages, setOlderMessages] = useState15([]);
+  const [hasMoreOlderMessages, setHasMoreOlderMessages] = useState15(true);
+  const [loadingOlderMessages, setLoadingOlderMessages] = useState15(false);
+  const loadingOlderMessagesRef = useRef7(false);
+  useEffect10(() => {
+    setOlderMessages([]);
+    setHasMoreOlderMessages(true);
+  }, [conversationId]);
+  const messages = useMemo3(() => dedupeMessagesById([...olderMessages, ...data ?? []]), [olderMessages, data]);
+  const loadOlderMessages = useCallback7(async () => {
+    const oldestMessage = messages[0];
+    if (!shouldFetchOlderMessages({
+      isLoading: loadingOlderMessagesRef.current,
+      hasMore: hasMoreOlderMessages,
+      oldestMessage
+    }))
+      return;
+    if (!oldestMessage) return;
+    loadingOlderMessagesRef.current = true;
+    setLoadingOlderMessages(true);
+    try {
+      const olderPage = await api.fetchMessages(conversationId, {
+        limit: OLDER_MESSAGES_PAGE_LIMIT,
+        before: oldestMessage.timestamp
+      });
+      if (!pageIndicatesMoreOlderMessages(olderPage.length, OLDER_MESSAGES_PAGE_LIMIT)) setHasMoreOlderMessages(false);
+      setOlderMessages((current) => prependOlderMessages(current, olderPage));
+    } finally {
+      loadingOlderMessagesRef.current = false;
+      setLoadingOlderMessages(false);
+    }
+  }, [api, conversationId, hasMoreOlderMessages, messages]);
   const sendMessage = useCallback7(
     async (text) => {
       const message = await api.sendMessage(conversationId, text);
@@ -4075,20 +4130,32 @@ function useConversationMessages(conversationId, params) {
     [api, conversationId, refetch]
   );
   const markRead = useCallback7(() => api.markRead(conversationId), [api, conversationId]);
-  return { messages: data ?? [], loading, error, refetch, sendMessage, sendMedia, sendTemplate, markRead };
+  return {
+    messages,
+    loading,
+    error,
+    refetch,
+    sendMessage,
+    sendMedia,
+    sendTemplate,
+    markRead,
+    loadOlderMessages,
+    loadingOlderMessages,
+    hasMoreOlderMessages
+  };
 }
 
 // src/hooks/useScrollToLatestMessage.ts
-import { useCallback as useCallback8, useLayoutEffect, useRef as useRef7, useState as useState15 } from "react";
+import { useCallback as useCallback8, useLayoutEffect, useRef as useRef8, useState as useState16 } from "react";
 var NEAR_BOTTOM_THRESHOLD_PX = 120;
 var SCROLL_BEHAVIOR = "auto";
 function useScrollToLatestMessage({
   conversationId,
   messageCount
 }) {
-  const containerRef = useRef7(null);
-  const [isAwayFromBottom, setIsAwayFromBottom] = useState15(false);
-  const isAwayFromBottomRef = useRef7(false);
+  const containerRef = useRef8(null);
+  const [isAwayFromBottom, setIsAwayFromBottom] = useState16(false);
+  const isAwayFromBottomRef = useRef8(false);
   const scrollToBottom = useCallback8((behavior = SCROLL_BEHAVIOR) => {
     const container = containerRef.current;
     if (!container) return;
@@ -4101,7 +4168,7 @@ function useScrollToLatestMessage({
     isAwayFromBottomRef.current = away;
     setIsAwayFromBottom((current) => current === away ? current : away);
   }, []);
-  const jumpedForConversationRef = useRef7(void 0);
+  const jumpedForConversationRef = useRef8(void 0);
   useLayoutEffect(() => {
     const isNewConversation = jumpedForConversationRef.current !== conversationId;
     if (isNewConversation) {
@@ -4148,12 +4215,12 @@ function useConversationContext(conversationId) {
 }
 
 // src/hooks/useConversationRealtime.ts
-import { useEffect as useEffect10, useRef as useRef8 } from "react";
+import { useEffect as useEffect11, useRef as useRef9 } from "react";
 function useConversationRealtime(conversationId, onEvent) {
   const sse = useConversations()?.sse;
-  const onEventRef = useRef8(onEvent);
+  const onEventRef = useRef9(onEvent);
   onEventRef.current = onEvent;
-  useEffect10(() => {
+  useEffect11(() => {
     if (!sse || !conversationId) return;
     const source = sse.connectConversationStream(conversationId);
     const handler = (event) => onEventRef.current(event);
@@ -4166,9 +4233,9 @@ function useConversationRealtime(conversationId, onEvent) {
 }
 function useGlobalRealtime(onEvent) {
   const sse = useConversations()?.sse;
-  const onEventRef = useRef8(onEvent);
+  const onEventRef = useRef9(onEvent);
   onEventRef.current = onEvent;
-  useEffect10(() => {
+  useEffect11(() => {
     if (!sse) return;
     const source = sse.connectGlobalStream();
     const handler = (event) => onEventRef.current(event);
@@ -4181,14 +4248,14 @@ function useGlobalRealtime(onEvent) {
 }
 
 // src/hooks/useConversationActions.ts
-import { useMemo as useMemo3 } from "react";
+import { useMemo as useMemo4 } from "react";
 function useConversationActions(conversationId) {
   const context = useConversations();
   if (!context) {
     throw new Error("useConversationActions requires an ancestor <ConversationsProvider>");
   }
   const { api } = context;
-  return useMemo3(
+  return useMemo4(
     () => ({
       takeover: api.takeover ? () => api.takeover(conversationId) : void 0,
       release: api.release ? () => api.release(conversationId) : void 0,
@@ -4203,7 +4270,7 @@ function useInboxActions() {
     throw new Error("useInboxActions requires an ancestor <ConversationsProvider>");
   }
   const { api } = context;
-  return useMemo3(
+  return useMemo4(
     () => ({
       markAllRead: api.markAllRead ? () => api.markAllRead() : void 0,
       listTemplates: api.listTemplates ? () => api.listTemplates() : void 0
@@ -4347,11 +4414,11 @@ async function sendQueuedMessage(params) {
 }
 
 // src/quickReplies/QuickRepliesWorkspace.tsx
-import { useEffect as useEffect13, useId as useId2, useRef as useRef11, useState as useState18 } from "react";
+import { useEffect as useEffect14, useId as useId2, useRef as useRef12, useState as useState19 } from "react";
 import { Pencil as Pencil2, Plus as Plus2, Trash2 as Trash23 } from "lucide-react";
 
 // src/quickReplies/useQuickRepliesWorkspace.ts
-import { useCallback as useCallback10, useEffect as useEffect12, useState as useState17 } from "react";
+import { useCallback as useCallback10, useEffect as useEffect13, useState as useState18 } from "react";
 
 // src/quickReplies/quickReplyAttachmentUpload.ts
 function validateAttachmentFiles(files, currentCount, limits) {
@@ -4383,7 +4450,7 @@ function moveAttachment(list, index, direction) {
 }
 
 // src/quickReplies/useQuickReplyAttachmentUploads.ts
-import { useCallback as useCallback9, useEffect as useEffect11, useRef as useRef9, useState as useState16 } from "react";
+import { useCallback as useCallback9, useEffect as useEffect12, useRef as useRef10, useState as useState17 } from "react";
 
 // src/quickReplies/createUploadQueue.ts
 function createUploadQueue(maxConcurrent) {
@@ -4439,11 +4506,11 @@ function useQuickReplyAttachmentUploads({
   attachmentsCount,
   onUploaded
 }) {
-  const [pendingUploads, setPendingUploads] = useState16([]);
-  const [attachmentRejections, setAttachmentRejections] = useState16([]);
-  const uploadQueueRef = useRef9(createUploadQueue(3));
-  const isMountedRef = useRef9(true);
-  useEffect11(
+  const [pendingUploads, setPendingUploads] = useState17([]);
+  const [attachmentRejections, setAttachmentRejections] = useState17([]);
+  const uploadQueueRef = useRef10(createUploadQueue(3));
+  const isMountedRef = useRef10(true);
+  useEffect12(
     () => () => {
       isMountedRef.current = false;
       uploadQueueRef.current.abortAll();
@@ -4621,15 +4688,15 @@ function useQuickRepliesWorkspace({
   labels,
   attachmentSizeLimits
 }) {
-  const [quickReplies, setQuickReplies] = useState17([]);
-  const [isLoading, setIsLoading] = useState17(false);
-  const [loadError, setLoadError] = useState17(void 0);
-  const [search, setSearch] = useState17("");
-  const [editing, setEditing] = useState17(void 0);
-  const [fieldErrors, setFieldErrors] = useState17({});
-  const [isSaving, setIsSaving] = useState17(false);
-  const [saveError, setSaveError] = useState17(void 0);
-  const [deletingId, setDeletingId] = useState17(void 0);
+  const [quickReplies, setQuickReplies] = useState18([]);
+  const [isLoading, setIsLoading] = useState18(false);
+  const [loadError, setLoadError] = useState18(void 0);
+  const [search, setSearch] = useState18("");
+  const [editing, setEditing] = useState18(void 0);
+  const [fieldErrors, setFieldErrors] = useState18({});
+  const [isSaving, setIsSaving] = useState18(false);
+  const [saveError, setSaveError] = useState18(void 0);
+  const [deletingId, setDeletingId] = useState18(void 0);
   const uploadAttachment = useCallback10((attachment) => {
     setEditing((current) => current ? { ...current, attachments: [...current.attachments, attachment] } : current);
   }, []);
@@ -4648,7 +4715,7 @@ function useQuickRepliesWorkspace({
     attachmentsCount: editing?.attachments.length ?? 0,
     onUploaded: uploadAttachment
   });
-  useEffect12(() => {
+  useEffect13(() => {
     if (!api.listQuickReplies) return;
     let cancelled = false;
     setIsLoading(true);
@@ -4976,7 +5043,7 @@ function QuickReplyWhatsAppPreview({ body, variables, attachments, labels }) {
 }
 
 // src/quickReplies/AttachmentsFormSection.tsx
-import { useRef as useRef10 } from "react";
+import { useRef as useRef11 } from "react";
 import { Paperclip as Paperclip3, X as X4 } from "lucide-react";
 import { Fragment as Fragment7, jsx as jsx27, jsxs as jsxs24 } from "react/jsx-runtime";
 function AttachmentsFormSection({
@@ -4991,7 +5058,7 @@ function AttachmentsFormSection({
   onMoveAttachment,
   onDismissRejections
 }) {
-  const attachmentFileInputRef = useRef10(null);
+  const attachmentFileInputRef = useRef11(null);
   return /* @__PURE__ */ jsxs24("div", { className: "space-y-2", children: [
     /* @__PURE__ */ jsx27("span", { className: "block text-sm font-medium", children: text.attachmentsTitle }),
     attachments.length === 0 && pendingUploads.length === 0 ? /* @__PURE__ */ jsx27("p", { className: "text-xs text-gray-500 dark:text-gray-400", children: text.attachmentsEmpty }) : /* @__PURE__ */ jsxs24("ul", { className: "space-y-1", children: [
@@ -5126,15 +5193,15 @@ function QuickRepliesWorkspace({
   attachmentSizeLimits
 }) {
   const text = { ...DEFAULT_QUICK_REPLIES_WORKSPACE_LABELS, ...labels };
-  const bodyFieldRef = useRef11(null);
+  const bodyFieldRef = useRef12(null);
   const formId = useId2();
   const titleFieldId = `${formId}-title`;
   const shortcutFieldId = `${formId}-shortcut`;
   const bodyFieldId = `${formId}-body`;
-  const [confirmingDeleteId, setConfirmingDeleteId] = useState18(null);
-  const deleteButtonRefs = useRef11({});
-  const confirmButtonRef = useRef11(null);
-  useEffect13(() => {
+  const [confirmingDeleteId, setConfirmingDeleteId] = useState19(null);
+  const deleteButtonRefs = useRef12({});
+  const confirmButtonRef = useRef12(null);
+  useEffect14(() => {
     if (confirmingDeleteId) confirmButtonRef.current?.focus();
   }, [confirmingDeleteId]);
   const cancelDeleteConfirm = (id) => {
@@ -5469,11 +5536,11 @@ function QuickRepliesWorkspace({
 }
 
 // src/workspace/ConversationsWorkspace.tsx
-import { useEffect as useEffect19, useMemo as useMemo6, useState as useState25 } from "react";
+import { useEffect as useEffect20, useMemo as useMemo7, useState as useState26 } from "react";
 import { Check as Check2, CheckCheck, FlaskConical, Hourglass as Hourglass2, Mail as Mail2, MessagesSquare } from "lucide-react";
 
 // src/workspace/BulkTemplateModal.tsx
-import { useEffect as useEffect14, useMemo as useMemo4, useState as useState19 } from "react";
+import { useEffect as useEffect15, useMemo as useMemo5, useState as useState20 } from "react";
 import { jsx as jsx29, jsxs as jsxs26 } from "react/jsx-runtime";
 function BulkTemplateModal({
   labels,
@@ -5487,10 +5554,10 @@ function BulkTemplateModal({
     throw new Error("BulkTemplateModal requires an ancestor <ConversationsProvider>");
   }
   const { api } = context;
-  const [templates, setTemplates] = useState19([]);
-  const [search, setSearch] = useState19("");
-  const [selected, setSelected] = useState19("");
-  useEffect14(() => {
+  const [templates, setTemplates] = useState20([]);
+  const [search, setSearch] = useState20("");
+  const [selected, setSelected] = useState20("");
+  useEffect15(() => {
     let active = true;
     void api.listTemplates?.().then((loaded) => {
       if (active) setTemplates(loaded);
@@ -5500,7 +5567,7 @@ function BulkTemplateModal({
       active = false;
     };
   }, [api]);
-  const filtered = useMemo4(() => {
+  const filtered = useMemo5(() => {
     const term = search.trim().toLowerCase();
     if (!term) return templates;
     return templates.filter((template) => template.name.toLowerCase().includes(term));
@@ -5564,7 +5631,48 @@ function BulkTemplateModal({
 }
 
 // src/workspace/ConversationPane.tsx
-import { useCallback as useCallback13, useEffect as useEffect17, useRef as useRef15, useState as useState23 } from "react";
+import { useCallback as useCallback14, useEffect as useEffect18, useRef as useRef17, useState as useState24 } from "react";
+
+// src/hooks/useLoadOlderMessagesScroll.ts
+import { useCallback as useCallback11, useLayoutEffect as useLayoutEffect2, useRef as useRef13 } from "react";
+var NEAR_TOP_THRESHOLD_PX = 200;
+function computeScrollTopAfterPrepend(before, scrollHeightAfter) {
+  return before.scrollTop + (scrollHeightAfter - before.scrollHeight);
+}
+function useLoadOlderMessagesScroll({
+  containerRef,
+  oldestMessageId,
+  hasMore,
+  loading,
+  onLoadOlder
+}) {
+  const pendingSnapshotRef = useRef13(null);
+  const previousOldestMessageIdRef = useRef13(oldestMessageId);
+  const triggerLoadOlder = useCallback11(() => {
+    if (loading || !hasMore) return;
+    const container = containerRef.current;
+    if (!container) return;
+    pendingSnapshotRef.current = { scrollHeight: container.scrollHeight, scrollTop: container.scrollTop };
+    onLoadOlder();
+  }, [containerRef, hasMore, loading, onLoadOlder]);
+  const handleScroll = useCallback11(
+    (event) => {
+      if (event.currentTarget.scrollTop > NEAR_TOP_THRESHOLD_PX) return;
+      triggerLoadOlder();
+    },
+    [triggerLoadOlder]
+  );
+  useLayoutEffect2(() => {
+    const idChanged = previousOldestMessageIdRef.current !== oldestMessageId;
+    previousOldestMessageIdRef.current = oldestMessageId;
+    const container = containerRef.current;
+    const pending = pendingSnapshotRef.current;
+    if (!idChanged || !container || !pending) return;
+    pendingSnapshotRef.current = null;
+    container.scrollTop = computeScrollTopAfterPrepend(pending, container.scrollHeight);
+  }, [oldestMessageId, containerRef]);
+  return { handleScroll, triggerLoadOlder };
+}
 
 // src/quickReplies/resolveConversationVariables.ts
 var MARKER_PATTERN = /^\{\{\s*([\w.]+)\s*\}\}$/;
@@ -5585,7 +5693,7 @@ function resolveConversationVariables({
 }
 
 // src/workspace/QueuedAttachmentsList.tsx
-import { useEffect as useEffect15, useRef as useRef12, useState as useState20 } from "react";
+import { useEffect as useEffect16, useRef as useRef14, useState as useState21 } from "react";
 import { jsx as jsx30, jsxs as jsxs27 } from "react/jsx-runtime";
 function nameOf(item) {
   return item.kind === "local" ? item.file.name : item.filename;
@@ -5601,16 +5709,16 @@ function AttachmentThumbnail({
   getThumbnailUrl
 }) {
   const isImage = mimeTypeOf(item).startsWith("image/");
-  const [url, setUrl] = useState20(item.kind === "local" ? void 0 : item.previewUrl);
+  const [url, setUrl] = useState21(item.kind === "local" ? void 0 : item.previewUrl);
   const localFile = item.kind === "local" ? item.file : void 0;
   const uploadId = item.kind === "stored" ? item.uploadId : void 0;
-  useEffect15(() => {
+  useEffect16(() => {
     if (!isImage || !localFile) return;
     const objectUrl = URL.createObjectURL(localFile);
     setUrl(objectUrl);
     return () => URL.revokeObjectURL(objectUrl);
   }, [isImage, localFile]);
-  useEffect15(() => {
+  useEffect16(() => {
     if (!isImage || !uploadId || !getThumbnailUrl) return;
     let cancelled = false;
     getThumbnailUrl(uploadId).then((resolved) => {
@@ -5628,11 +5736,11 @@ function departedItemsOf(previouslyRendered, items) {
   return previouslyRendered.filter((item) => !currentKeys.has(attachmentKey(item)));
 }
 function useDepartingItems(items) {
-  const [rendered, setRendered] = useState20(items);
-  const [departingKeys, setDepartingKeys] = useState20(/* @__PURE__ */ new Set());
-  const renderedRef = useRef12(rendered);
+  const [rendered, setRendered] = useState21(items);
+  const [departingKeys, setDepartingKeys] = useState21(/* @__PURE__ */ new Set());
+  const renderedRef = useRef14(rendered);
   renderedRef.current = rendered;
-  useEffect15(() => {
+  useEffect16(() => {
     const removedItems = departedItemsOf(renderedRef.current, items);
     if (removedItems.length === 0) {
       setRendered(items);
@@ -5716,10 +5824,10 @@ function QueuedAttachmentsList({
 }
 
 // src/workspace/useComposerQueue.ts
-import { useCallback as useCallback12, useEffect as useEffect16, useRef as useRef14, useState as useState22 } from "react";
+import { useCallback as useCallback13, useEffect as useEffect17, useRef as useRef16, useState as useState23 } from "react";
 
 // src/workspace/useComposerAttachmentRetry.ts
-import { useCallback as useCallback11, useRef as useRef13, useState as useState21 } from "react";
+import { useCallback as useCallback12, useRef as useRef15, useState as useState22 } from "react";
 function useComposerAttachmentRetry(params) {
   const {
     conversationId,
@@ -5733,9 +5841,9 @@ function useComposerAttachmentRetry(params) {
     labels,
     sendInFlightRef
   } = params;
-  const retryIdempotencyKeyRef = useRef13(void 0);
-  const retryingKeysRef = useRef13(/* @__PURE__ */ new Set());
-  const [retryingKeys, setRetryingKeys] = useState21(/* @__PURE__ */ new Set());
+  const retryIdempotencyKeyRef = useRef15(void 0);
+  const retryingKeysRef = useRef15(/* @__PURE__ */ new Set());
+  const [retryingKeys, setRetryingKeys] = useState22(/* @__PURE__ */ new Set());
   function markRetrying(key) {
     retryingKeysRef.current.add(key);
     setRetryingKeys(new Set(retryingKeysRef.current));
@@ -5811,7 +5919,7 @@ function useComposerAttachmentRetry(params) {
     }
     void retryStoredAttachment(item).finally(release);
   }
-  const resetRetryState = useCallback11(() => {
+  const resetRetryState = useCallback12(() => {
     retryIdempotencyKeyRef.current = void 0;
     retryingKeysRef.current.clear();
     setRetryingKeys(/* @__PURE__ */ new Set());
@@ -5822,12 +5930,12 @@ function useComposerAttachmentRetry(params) {
 // src/workspace/useComposerQueue.ts
 function useComposerQueue(params) {
   const { conversationId, draft, setDraft, api, labels, onSendAttachments, refetch, setSendFailure } = params;
-  const [queue, setQueue] = useState22([]);
-  const [attachmentStatus, setAttachmentStatus] = useState22({});
-  const [isSendingDraft, setIsSendingDraft] = useState22(false);
-  const sendInFlightRef = useRef14(false);
-  const idempotencyKeyRef = useRef14(void 0);
-  const currentConversationIdRef = useRef14(conversationId);
+  const [queue, setQueue] = useState23([]);
+  const [attachmentStatus, setAttachmentStatus] = useState23({});
+  const [isSendingDraft, setIsSendingDraft] = useState23(false);
+  const sendInFlightRef = useRef16(false);
+  const idempotencyKeyRef = useRef16(void 0);
+  const currentConversationIdRef = useRef16(conversationId);
   const { retryQueuedAttachment, resetRetryState, retryingKeys } = useComposerAttachmentRetry({
     conversationId,
     currentConversationIdRef,
@@ -5840,7 +5948,7 @@ function useComposerQueue(params) {
     sendInFlightRef,
     ...onSendAttachments ? { onSendAttachments } : {}
   });
-  useEffect16(() => {
+  useEffect17(() => {
     currentConversationIdRef.current = conversationId;
     setQueue([]);
     setAttachmentStatus({});
@@ -5849,11 +5957,11 @@ function useComposerQueue(params) {
     setIsSendingDraft(false);
     resetRetryState();
   }, [conversationId, resetRetryState]);
-  const enqueueAttachments = useCallback12((items) => {
+  const enqueueAttachments = useCallback13((items) => {
     if (items.length === 0) return;
     setQueue((current) => [...current, ...items]);
   }, []);
-  const removeQueuedAttachment = useCallback12((item) => {
+  const removeQueuedAttachment = useCallback13((item) => {
     setQueue((current) => current.filter((queued) => attachmentKey(queued) !== attachmentKey(item)));
   }, []);
   async function runSend(action, fallback) {
@@ -5991,12 +6099,14 @@ function ConversationPane({
     throw new Error("ConversationPane requires an ancestor <ConversationsProvider>");
   }
   const { api } = context;
-  const { messages, refetch } = useConversationMessages(conversation.id);
+  const { messages, refetch, loadOlderMessages, loadingOlderMessages, hasMoreOlderMessages } = useConversationMessages(
+    conversation.id
+  );
   const { context: conversationContext } = useConversationContext(conversation.id);
-  const [documentsOpen, setDocumentsOpen] = useState23(false);
-  const [sendFailure, setSendFailure] = useState23(void 0);
-  const [selectedMessageIds, setSelectedMessageIds] = useState23(/* @__PURE__ */ new Set());
-  const [draft, setDraft] = useState23(initialComposerText ?? "");
+  const [documentsOpen, setDocumentsOpen] = useState24(false);
+  const [sendFailure, setSendFailure] = useState24(void 0);
+  const [selectedMessageIds, setSelectedMessageIds] = useState24(/* @__PURE__ */ new Set());
+  const [draft, setDraft] = useState24(initialComposerText ?? "");
   const {
     queue,
     enqueueAttachments,
@@ -6016,8 +6126,8 @@ function ConversationPane({
     refetch,
     setSendFailure
   });
-  const thumbnailUrlCacheRef = useRef15(/* @__PURE__ */ new Map());
-  const getQueuedAttachmentThumbnailUrl = useCallback13(
+  const thumbnailUrlCacheRef = useRef17(/* @__PURE__ */ new Map());
+  const getQueuedAttachmentThumbnailUrl = useCallback14(
     (uploadId) => {
       const cached = thumbnailUrlCacheRef.current.get(uploadId);
       if (cached) return cached;
@@ -6028,7 +6138,7 @@ function ConversationPane({
     },
     [api]
   );
-  useEffect17(() => {
+  useEffect18(() => {
     setSelectedMessageIds(/* @__PURE__ */ new Set());
     setDraft(initialComposerText ?? "");
   }, [conversation.id, initialComposerText]);
@@ -6048,6 +6158,13 @@ function ConversationPane({
     setSelectedMessageIds(/* @__PURE__ */ new Set());
   }
   const scroll = useScrollToLatestMessage({ conversationId: conversation.id, messageCount: messages.length });
+  const loadOlder = useLoadOlderMessagesScroll({
+    containerRef: scroll.containerRef,
+    oldestMessageId: messages[0]?.id,
+    hasMore: hasMoreOlderMessages,
+    loading: loadingOlderMessages,
+    onLoadOlder: () => void loadOlderMessages()
+  });
   useConversationRealtime(conversation.id, () => {
     void refetch();
   });
@@ -6131,32 +6248,38 @@ function ConversationPane({
     contextEntries && contextEntries.length > 0 || flowLabel ? /* @__PURE__ */ jsx31(ConversationContextPanel, { entries: contextEntries ?? [], ...flowLabel ? { flowLabel } : {} }) : null,
     /* @__PURE__ */ jsx31(ConversationDocumentsPanel, { conversationId: conversation.id, open: documentsOpen }),
     renderAboveTranscript?.(conversation, conversationContext),
-    /* @__PURE__ */ jsx31(
+    /* @__PURE__ */ jsxs28(
       ConversationWallpaper,
       {
         ref: scroll.containerRef,
-        onScroll: scroll.handleScroll,
+        onScroll: (event) => {
+          scroll.handleScroll(event);
+          loadOlder.handleScroll(event);
+        },
         className: "cv-workspace-transcript",
-        children: messages.map((message, index) => {
-          const previous = index > 0 ? messages[index - 1] : void 0;
-          const startsNewDay = !previous || new Date(message.timestamp).toDateString() !== new Date(previous.timestamp).toDateString();
-          return /* @__PURE__ */ jsxs28("div", { children: [
-            startsNewDay ? /* @__PURE__ */ jsx31(DateDivider, { iso: message.timestamp }) : null,
-            /* @__PURE__ */ jsx31(
-              MessageBubble,
-              {
-                message,
-                isMine: message.direction === "outbound",
-                isFirstInGroup: !previous || previous.sender !== message.sender,
-                ...messageSelection ? {
-                  isSelecting: selectedMessageIds.size > 0,
-                  isSelected: selectedMessageIds.has(message.id),
-                  onToggleSelect: () => toggleMessageSelected(message.id)
-                } : {}
-              }
-            )
-          ] }, message.id);
-        })
+        children: [
+          hasMoreOlderMessages ? /* @__PURE__ */ jsx31("div", { className: "cv-workspace-load-older", children: /* @__PURE__ */ jsx31("button", { type: "button", onClick: loadOlder.triggerLoadOlder, disabled: loadingOlderMessages, children: loadingOlderMessages ? labels.loadingOlderMessages : labels.loadOlderMessages }) }) : null,
+          messages.map((message, index) => {
+            const previous = index > 0 ? messages[index - 1] : void 0;
+            const startsNewDay = !previous || new Date(message.timestamp).toDateString() !== new Date(previous.timestamp).toDateString();
+            return /* @__PURE__ */ jsxs28("div", { children: [
+              startsNewDay ? /* @__PURE__ */ jsx31(DateDivider, { iso: message.timestamp }) : null,
+              /* @__PURE__ */ jsx31(
+                MessageBubble,
+                {
+                  message,
+                  isMine: message.direction === "outbound",
+                  isFirstInGroup: !previous || previous.sender !== message.sender,
+                  ...messageSelection ? {
+                    isSelecting: selectedMessageIds.size > 0,
+                    isSelected: selectedMessageIds.has(message.id),
+                    onToggleSelect: () => toggleMessageSelected(message.id)
+                  } : {}
+                }
+              )
+            ] }, message.id);
+          })
+        ]
       }
     ),
     messageSelection && selectedMessageIds.size > 0 ? /* @__PURE__ */ jsxs28("div", { className: "cv-workspace-selection", children: [
@@ -6196,9 +6319,11 @@ function ConversationPane({
         onSend: () => void handleRichSend(),
         ...onSendAttachments ? {
           onAttachFiles: (files) => enqueueAttachments(
-            Array.from(files).map(
-              (file) => ({ kind: "local", localId: crypto.randomUUID(), file })
-            )
+            Array.from(files).map((file) => ({
+              kind: "local",
+              localId: crypto.randomUUID(),
+              file
+            }))
           )
         } : onAttach ? {
           onAttachFiles: (files) => {
@@ -6444,6 +6569,8 @@ var DEFAULT_CONVERSATIONS_WORKSPACE_LABELS = {
   templateModalSend: (count) => `Enviar para ${count}`,
   messagesSelected: (count) => `${count} mensagem${count === 1 ? "" : "s"} selecionada${count === 1 ? "" : "s"}`,
   copySelected: "Copiar",
+  loadOlderMessages: "Carregar mensagens anteriores",
+  loadingOlderMessages: "Carregando\u2026",
   composerPlaceholder: "Responder como atendente\u2026",
   attachFailure: "Falha ao enviar o arquivo.",
   attachmentRemove: "Remover anexo",
@@ -6462,7 +6589,7 @@ var DEFAULT_CONVERSATIONS_WORKSPACE_LABELS = {
 };
 
 // src/workspace/useConversationsInbox.ts
-import { useCallback as useCallback14, useEffect as useEffect18, useMemo as useMemo5, useRef as useRef16, useState as useState24 } from "react";
+import { useCallback as useCallback15, useEffect as useEffect19, useMemo as useMemo6, useRef as useRef18, useState as useState25 } from "react";
 var CONVERSATIONS_PER_PAGE = 50;
 function defaultDescribeFailure(error) {
   const status = error.status;
@@ -6480,14 +6607,14 @@ function useConversationsInbox(params = {}) {
   const perPage = params.perPage ?? CONVERSATIONS_PER_PAGE;
   const markReadOnOpen = params.markReadOnOpen ?? true;
   const describeFailure = params.describeFailure ?? defaultDescribeFailure;
-  const [waitingOnly, setWaitingOnly] = useState24(false);
-  const [windowFilter, setWindowFilter] = useState24(CONVERSATION_WINDOW.ALL);
-  const [channelFilter, setChannelFilter] = useState24(CHANNEL_FILTER_ALL);
-  const [search, setSearch] = useState24("");
-  const [page, setPage] = useState24(1);
-  const [selectedId, setSelectedId] = useState24(void 0);
-  const [selectedIds, setSelectedIds] = useState24(/* @__PURE__ */ new Set());
-  const [busy, setBusy] = useState24(false);
+  const [waitingOnly, setWaitingOnly] = useState25(false);
+  const [windowFilter, setWindowFilter] = useState25(CONVERSATION_WINDOW.ALL);
+  const [channelFilter, setChannelFilter] = useState25(CHANNEL_FILTER_ALL);
+  const [search, setSearch] = useState25("");
+  const [page, setPage] = useState25(1);
+  const [selectedId, setSelectedId] = useState25(void 0);
+  const [selectedIds, setSelectedIds] = useState25(/* @__PURE__ */ new Set());
+  const [busy, setBusy] = useState25(false);
   const { conversations, total, loading, error, refetch } = useConversationList({
     ...waitingOnly ? { waitingHuman: true } : {},
     ...search ? { search } : {},
@@ -6495,12 +6622,12 @@ function useConversationsInbox(params = {}) {
     ...params.serverPaginated ? { page, limit: perPage } : {}
   });
   useGlobalRealtime(
-    useCallback14(() => {
+    useCallback15(() => {
       void refetch();
     }, [refetch])
   );
-  const now = useMemo5(() => Date.now(), [conversations]);
-  const filtered = useMemo5(
+  const now = useMemo6(() => Date.now(), [conversations]);
+  const filtered = useMemo6(
     () => conversations.filter(
       (conversation) => channelFilter === CHANNEL_FILTER_ALL || (conversation.channel ?? DEFAULT_CONVERSATION_CHANNEL) === channelFilter
     ).filter(
@@ -6512,16 +6639,16 @@ function useConversationsInbox(params = {}) {
   const pageCount = Math.max(1, Math.ceil(totalForPaging / perPage));
   const currentPage = Math.min(page, pageCount);
   const pageConversations = params.serverPaginated ? filtered : filtered.slice((currentPage - 1) * perPage, currentPage * perPage);
-  useEffect18(() => {
+  useEffect19(() => {
     setPage(1);
   }, [search, waitingOnly, windowFilter, channelFilter]);
-  useEffect18(() => {
+  useEffect19(() => {
     if (selectedId && !conversations.some((conversation) => conversation.id === selectedId)) {
       setSelectedId(void 0);
     }
   }, [conversations, selectedId]);
-  const lastMarkReadAttempt = useRef16(void 0);
-  useEffect18(() => {
+  const lastMarkReadAttempt = useRef18(void 0);
+  useEffect19(() => {
     if (!markReadOnOpen || !selectedId) return;
     const opened = conversations.find((conversation) => conversation.id === selectedId);
     if (!opened || opened.unread === 0) return;
@@ -6531,7 +6658,7 @@ function useConversationsInbox(params = {}) {
     void api.markRead(selectedId).then(() => refetch()).catch(() => {
     });
   }, [markReadOnOpen, selectedId, conversations, refetch, api]);
-  const toggleSelected = useCallback14((conversationId) => {
+  const toggleSelected = useCallback15((conversationId) => {
     setSelectedIds((current) => {
       const next = new Set(current);
       if (next.has(conversationId)) next.delete(conversationId);
@@ -6541,7 +6668,7 @@ function useConversationsInbox(params = {}) {
   }, []);
   const pageIds = pageConversations.map((conversation) => conversation.id);
   const allOnPageSelected = pageIds.length > 0 && pageIds.every((id) => selectedIds.has(id));
-  const toggleSelectAllOnPage = useCallback14(() => {
+  const toggleSelectAllOnPage = useCallback15(() => {
     setSelectedIds((current) => {
       const next = new Set(current);
       if (allOnPageSelected) pageIds.forEach((id) => next.delete(id));
@@ -6549,7 +6676,7 @@ function useConversationsInbox(params = {}) {
       return next;
     });
   }, [allOnPageSelected, pageIds]);
-  const runOnSelection = useCallback14(
+  const runOnSelection = useCallback15(
     async (action) => {
       setBusy(true);
       try {
@@ -6562,7 +6689,7 @@ function useConversationsInbox(params = {}) {
     },
     [selectedIds, refetch]
   );
-  const runConversationAction = useCallback14(
+  const runConversationAction = useCallback15(
     async (action, conversationId) => {
       if (!action) return;
       setBusy(true);
@@ -6685,10 +6812,10 @@ function ConversationsWorkspace({
     ...markReadOnOpen === void 0 ? {} : { markReadOnOpen },
     ...serverPaginated ? { serverPaginated } : {}
   });
-  const [simulatorOpen, setSimulatorOpen] = useState25(false);
-  const [templateModalOpen, setTemplateModalOpen] = useState25(false);
-  const [openedFromLink, setOpenedFromLink] = useState25(void 0);
-  useEffect19(() => {
+  const [simulatorOpen, setSimulatorOpen] = useState26(false);
+  const [templateModalOpen, setTemplateModalOpen] = useState26(false);
+  const [openedFromLink, setOpenedFromLink] = useState26(void 0);
+  useEffect20(() => {
     const link = initialConversationId ?? initialWhatsappNumber;
     if (!link || openedFromLink === link) return;
     const target = inbox.conversations.find(
@@ -6708,11 +6835,11 @@ function ConversationsWorkspace({
     simulator && (simulator.enabled ?? true) && (simulator.render ?? transport)
   );
   const showSimulator = simulatorEnabled && simulatorOpen && Boolean(selected);
-  const simulatorClient = useMemo6(
+  const simulatorClient = useMemo7(
     () => transport && selectedId ? transport({ conversationId: selectedId, channel, handle }) : void 0,
     [transport, selectedId, channel, handle]
   );
-  const paneUtilities = useMemo6(() => {
+  const paneUtilities = useMemo7(() => {
     if (!selected) return void 0;
     const fromProduct = extraUtilitiesFor?.(selected) ?? [];
     if (!simulatorEnabled) return fromProduct;

package/dist/preview/index.js

@@ -705,7 +705,9 @@ function createMockConversationsApi(params) {
     },
     fetchMessages(conversationId, fetchParams) {
       return withLatency(() => {
-        const messages = params.store.listMessages(conversationId);
+        const allMessages = params.store.listMessages(conversationId);
+        const before = fetchParams?.before;
+        const messages = before ? allMessages.filter((message) => message.timestamp < before) : allMessages;
         const limit = fetchParams?.limit;
         return limit ? messages.slice(-limit) : messages;
       });

package/dist/styles.css

@@ -526,6 +526,22 @@
   font-size: 0.875rem;
   color: #6b7280;
 }
+.cv-workspace-load-older {
+  display: flex;
+  justify-content: center;
+  padding: 0.5rem 0;
+}
+.cv-workspace-load-older button {
+  min-height: 2.75rem;
+  border-radius: 0.375rem;
+  border: 1px solid var(--cv-border, #e5e7eb);
+  padding: 0 0.75rem;
+  font-size: 0.8125rem;
+  color: #6b7280;
+}
+.cv-workspace-load-older button:disabled {
+  opacity: 0.6;
+}
 .dark .cv-workspace-notice {
   border-top-color: #374151;
   background: #1f2937;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/conversations-ui",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "WhatsApp conversation UI components — parametrizável por endpoint, tema e feature flags",
   "publishConfig": {
     "access": "public"

package/src/hooks/useConversationMessages.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  dedupeMessagesById,
+  pageIndicatesMoreOlderMessages,
+  prependOlderMessages,
+  shouldFetchOlderMessages,
+} from './useConversationMessages'
+import type { MessagePayload } from '../types'
+
+function buildMessage(id: string, timestamp: string): MessagePayload {
+  return { id, type: 'text', content: id, direction: 'inbound', sender: 'customer', timestamp }
+}
+
+describe('dedupeMessagesById', () => {
+  it('mantém a primeira ocorrência de cada id e descarta as repetidas', () => {
+    const first = buildMessage('1', '2026-09-01T10:00:00.000Z')
+    const duplicate = buildMessage('1', '2026-09-01T10:00:00.000Z')
+    const second = buildMessage('2', '2026-09-01T10:01:00.000Z')
+
+    expect(dedupeMessagesById([first, duplicate, second])).toEqual([first, second])
+  })
+})
+
+describe('prependOlderMessages', () => {
+  it('prepende a página anterior descartando o que já estava carregado', () => {
+    const accumulated = [buildMessage('3', '2026-09-01T10:02:00.000Z')]
+    const olderPage = [buildMessage('1', '2026-09-01T10:00:00.000Z'), buildMessage('2', '2026-09-01T10:01:00.000Z')]
+
+    expect(prependOlderMessages(accumulated, olderPage)).toEqual([...olderPage, ...accumulated])
+  })
+
+  it('não duplica quando a mesma página anterior chega de novo', () => {
+    const message = buildMessage('1', '2026-09-01T10:00:00.000Z')
+    const accumulated = [message]
+
+    expect(prependOlderMessages(accumulated, [message])).toEqual([message])
+  })
+})
+
+describe('shouldFetchOlderMessages', () => {
+  const oldestMessage = buildMessage('1', '2026-09-01T10:00:00.000Z')
+
+  it('busca quando não há requisição em voo, ainda há mais páginas e existe uma mensagem mais antiga', () => {
+    expect(shouldFetchOlderMessages({ isLoading: false, hasMore: true, oldestMessage })).toBe(true)
+  })
+
+  it('não dispara requisição concorrente enquanto uma já está em voo', () => {
+    expect(shouldFetchOlderMessages({ isLoading: true, hasMore: true, oldestMessage })).toBe(false)
+  })
+
+  it('para de buscar quando uma página anterior já veio incompleta (hasMore=false)', () => {
+    expect(shouldFetchOlderMessages({ isLoading: false, hasMore: false, oldestMessage })).toBe(false)
+  })
+
+  it('não busca sem mensagem mais antiga para servir de before', () => {
+    expect(shouldFetchOlderMessages({ isLoading: false, hasMore: true, oldestMessage: undefined })).toBe(false)
+  })
+})
+
+describe('pageIndicatesMoreOlderMessages', () => {
+  it('página completa (igual ao limite) indica que pode haver mais', () => {
+    expect(pageIndicatesMoreOlderMessages(50, 50)).toBe(true)
+  })
+
+  it('página menor que o limite indica que não há mais mensagens antigas', () => {
+    expect(pageIndicatesMoreOlderMessages(12, 50)).toBe(false)
+  })
+
+  it('página vazia indica que não há mais mensagens antigas', () => {
+    expect(pageIndicatesMoreOlderMessages(0, 50)).toBe(false)
+  })
+})
+
+describe('preservação do histórico ao chegar mensagem nova (SSE/polling)', () => {
+  it('combina o acumulado antigo com a janela recente sem perder páginas já carregadas', () => {
+    const olderMessages = [buildMessage('1', '2026-09-01T10:00:00.000Z'), buildMessage('2', '2026-09-01T10:01:00.000Z')]
+    const recentWindowBeforeNewMessage = [buildMessage('3', '2026-09-01T10:02:00.000Z')]
+    const recentWindowAfterNewMessage = [
+      buildMessage('3', '2026-09-01T10:02:00.000Z'),
+      buildMessage('4', '2026-09-01T10:03:00.000Z'),
+    ]
+
+    const before = dedupeMessagesById([...olderMessages, ...recentWindowBeforeNewMessage])
+    const after = dedupeMessagesById([...olderMessages, ...recentWindowAfterNewMessage])
+
+    expect(before.map((message) => message.id)).toEqual(['1', '2', '3'])
+    expect(after.map((message) => message.id)).toEqual(['1', '2', '3', '4'])
+  })
+})

package/src/hooks/useConversationMessages.ts

@@ -1,8 +1,11 @@
-import { useCallback } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useConversations } from '../providers/ConversationsProvider'
 import { useAsyncResource } from './useAsyncResource'
 import type { MessagePayload } from '../types'
 
+/** Tamanho da página ao buscar mensagens anteriores — mesmo padrão do `before` sem `limit`. */
+const OLDER_MESSAGES_PAGE_LIMIT = 50
+
 export interface UseConversationMessagesResult {
   messages: MessagePayload[]
   loading: boolean
@@ -12,6 +15,59 @@ export interface UseConversationMessagesResult {
   sendMedia: (data: { base64: string; mimeType: string; filename: string; caption?: string }) => Promise<MessagePayload>
   sendTemplate: (data: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
   markRead: () => Promise<void>
+  /** Busca a página anterior de mensagens e prepende ao histórico já carregado. */
+  loadOlderMessages: () => Promise<void>
+  loadingOlderMessages: boolean
+  /** `false` assim que uma página vier menor que o limite — não há mais o que buscar antes dela. */
+  hasMoreOlderMessages: boolean
+}
+
+/** Descarta qualquer mensagem cujo `id` já apareceu antes, mantendo a primeira ocorrência. */
+export function dedupeMessagesById(messages: readonly MessagePayload[]): MessagePayload[] {
+  const seenIds = new Set<string>()
+  const deduped: MessagePayload[] = []
+  for (const message of messages) {
+    if (seenIds.has(message.id)) continue
+    seenIds.add(message.id)
+    deduped.push(message)
+  }
+  return deduped
+}
+
+/**
+ * Soma uma página de mensagens antigas ao acumulado já carregado, sem duplicar.
+ *
+ * Duplicar aconteceria numa corrida onde a mesma página chegasse duas vezes — o `id` é a única
+ * garantia de identidade da mensagem, o timestamp usado no `before` não basta sozinho.
+ */
+export function prependOlderMessages(
+  accumulated: readonly MessagePayload[],
+  olderPage: readonly MessagePayload[],
+): MessagePayload[] {
+  const existingIds = new Set(accumulated.map((message) => message.id))
+  const newMessages = olderPage.filter((message) => !existingIds.has(message.id))
+  return [...newMessages, ...accumulated]
+}
+
+export type LoadOlderMessagesGuardState = {
+  readonly isLoading: boolean
+  readonly hasMore: boolean
+  readonly oldestMessage: MessagePayload | undefined
+}
+
+/**
+ * Decide se vale a pena buscar a página anterior: nunca com uma busca já em voo (evita requisição
+ * concorrente), nunca depois que uma página já veio incompleta, e nunca sem uma mensagem mais
+ * antiga para servir de `before`.
+ */
+export function shouldFetchOlderMessages(state: LoadOlderMessagesGuardState): boolean {
+  if (state.isLoading || !state.hasMore) return false
+  return Boolean(state.oldestMessage)
+}
+
+/** A página veio menor que o limite pedido: não há mais nada antes dela para buscar. */
+export function pageIndicatesMoreOlderMessages(pageLength: number, limit: number): boolean {
+  return pageLength >= limit
 }
 
 // Camada headless: dados + ações de uma conversa, sem nenhuma tela acoplada — o produto
@@ -32,6 +88,52 @@ export function useConversationMessages(
     [conversationId, params?.limit, params?.before],
   )
 
+  const [olderMessages, setOlderMessages] = useState<MessagePayload[]>([])
+  const [hasMoreOlderMessages, setHasMoreOlderMessages] = useState(true)
+  const [loadingOlderMessages, setLoadingOlderMessages] = useState(false)
+  /**
+   * Espelha `loadingOlderMessages`: o guarda de concorrência precisa ler o valor atual na hora do
+   * clique/scroll, e o estado do React só reflete depois do próximo render.
+   */
+  const loadingOlderMessagesRef = useRef(false)
+
+  // Trocar de conversa zera a paginação de mensagens antigas — a anterior podia já ter esgotado o
+  // histórico, e isso não pode vazar para a conversa que acabou de abrir.
+  useEffect(() => {
+    setOlderMessages([])
+    setHasMoreOlderMessages(true)
+  }, [conversationId])
+
+  const messages = useMemo(() => dedupeMessagesById([...olderMessages, ...(data ?? [])]), [olderMessages, data])
+
+  const loadOlderMessages = useCallback(async () => {
+    const oldestMessage = messages[0]
+    if (
+      !shouldFetchOlderMessages({
+        isLoading: loadingOlderMessagesRef.current,
+        hasMore: hasMoreOlderMessages,
+        oldestMessage,
+      })
+    )
+      return
+    // `shouldFetchOlderMessages` já garante isto — repetido aqui só para o compilador estreitar o tipo.
+    if (!oldestMessage) return
+
+    loadingOlderMessagesRef.current = true
+    setLoadingOlderMessages(true)
+    try {
+      const olderPage = await api.fetchMessages(conversationId, {
+        limit: OLDER_MESSAGES_PAGE_LIMIT,
+        before: oldestMessage.timestamp,
+      })
+      if (!pageIndicatesMoreOlderMessages(olderPage.length, OLDER_MESSAGES_PAGE_LIMIT)) setHasMoreOlderMessages(false)
+      setOlderMessages((current) => prependOlderMessages(current, olderPage))
+    } finally {
+      loadingOlderMessagesRef.current = false
+      setLoadingOlderMessages(false)
+    }
+  }, [api, conversationId, hasMoreOlderMessages, messages])
+
   const sendMessage = useCallback(
     async (text: string) => {
       const message = await api.sendMessage(conversationId, text)
@@ -60,5 +162,17 @@ export function useConversationMessages(
 
   const markRead = useCallback(() => api.markRead(conversationId), [api, conversationId])
 
-  return { messages: data ?? [], loading, error, refetch, sendMessage, sendMedia, sendTemplate, markRead }
+  return {
+    messages,
+    loading,
+    error,
+    refetch,
+    sendMessage,
+    sendMedia,
+    sendTemplate,
+    markRead,
+    loadOlderMessages,
+    loadingOlderMessages,
+    hasMoreOlderMessages,
+  }
 }

package/src/hooks/useLoadOlderMessagesScroll.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'bun:test'
+
+import { computeScrollTopAfterPrepend } from './useLoadOlderMessagesScroll'
+
+describe('computeScrollTopAfterPrepend', () => {
+  it('mantém o mesmo ponto visual somando ao scrollTop a altura que o conteúdo antigo acrescentou', () => {
+    // Container tinha 2000px de conteúdo, operador em 300px do topo; a página anterior somou 800px.
+    const before = { scrollHeight: 2000, scrollTop: 300 }
+    expect(computeScrollTopAfterPrepend(before, 2800)).toBe(1100)
+  })
+
+  it('não desloca a rolagem quando a altura não muda', () => {
+    const before = { scrollHeight: 2000, scrollTop: 300 }
+    expect(computeScrollTopAfterPrepend(before, 2000)).toBe(300)
+  })
+
+  it('funciona a partir do topo absoluto (scrollTop=0)', () => {
+    const before = { scrollHeight: 2000, scrollTop: 0 }
+    expect(computeScrollTopAfterPrepend(before, 2500)).toBe(500)
+  })
+})

package/src/hooks/useLoadOlderMessagesScroll.ts

@@ -0,0 +1,76 @@
+import { useCallback, useLayoutEffect, useRef, type RefObject, type UIEvent } from 'react'
+
+/**
+ * Chegar perto do topo do transcript dispara a busca da página anterior, e a posição de rolagem é
+ * recalculada depois que o DOM cresce por cima do ponto atual — sem isso, prepender mensagens
+ * empurra visualmente tudo para baixo e o operador perde a linha onde estava lendo.
+ */
+const NEAR_TOP_THRESHOLD_PX = 200
+
+export type ScrollHeightSnapshot = {
+  readonly scrollHeight: number
+  readonly scrollTop: number
+}
+
+/** Novo `scrollTop` que mantém o mesmo ponto visual depois que o conteúdo cresceu por cima. */
+export function computeScrollTopAfterPrepend(before: ScrollHeightSnapshot, scrollHeightAfter: number): number {
+  return before.scrollTop + (scrollHeightAfter - before.scrollHeight)
+}
+
+export type UseLoadOlderMessagesScrollParams = {
+  readonly containerRef: RefObject<HTMLDivElement | null>
+  /** `id` da mensagem mais antiga já carregada — muda quando uma página nova é prependida. */
+  readonly oldestMessageId: string | undefined
+  readonly hasMore: boolean
+  readonly loading: boolean
+  readonly onLoadOlder: () => void
+}
+
+export type UseLoadOlderMessagesScrollResult = {
+  /** Ligue no `onScroll` do mesmo elemento que `containerRef`. */
+  readonly handleScroll: (event: UIEvent<HTMLDivElement>) => void
+  /** Para o botão "Carregar mensagens anteriores" — mesma lógica do gatilho por scroll. */
+  readonly triggerLoadOlder: () => void
+}
+
+export function useLoadOlderMessagesScroll({
+  containerRef,
+  oldestMessageId,
+  hasMore,
+  loading,
+  onLoadOlder,
+}: UseLoadOlderMessagesScrollParams): UseLoadOlderMessagesScrollResult {
+  const pendingSnapshotRef = useRef<ScrollHeightSnapshot | null>(null)
+  const previousOldestMessageIdRef = useRef(oldestMessageId)
+
+  const triggerLoadOlder = useCallback(() => {
+    if (loading || !hasMore) return
+    const container = containerRef.current
+    if (!container) return
+
+    pendingSnapshotRef.current = { scrollHeight: container.scrollHeight, scrollTop: container.scrollTop }
+    onLoadOlder()
+  }, [containerRef, hasMore, loading, onLoadOlder])
+
+  const handleScroll = useCallback(
+    (event: UIEvent<HTMLDivElement>) => {
+      if (event.currentTarget.scrollTop > NEAR_TOP_THRESHOLD_PX) return
+      triggerLoadOlder()
+    },
+    [triggerLoadOlder],
+  )
+
+  useLayoutEffect(() => {
+    const idChanged = previousOldestMessageIdRef.current !== oldestMessageId
+    previousOldestMessageIdRef.current = oldestMessageId
+
+    const container = containerRef.current
+    const pending = pendingSnapshotRef.current
+    if (!idChanged || !container || !pending) return
+
+    pendingSnapshotRef.current = null
+    container.scrollTop = computeScrollTopAfterPrepend(pending, container.scrollHeight)
+  }, [oldestMessageId, containerRef])
+
+  return { handleScroll, triggerLoadOlder }
+}

package/src/preview/createMockConversationsApi.ts

@@ -108,7 +108,11 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
 
     fetchMessages(conversationId, fetchParams): Promise<MessagePayload[]> {
       return withLatency(() => {
-        const messages = params.store.listMessages(conversationId)
+        const allMessages = params.store.listMessages(conversationId)
+        const before = fetchParams?.before
+        // Mesma semântica do backend real: com `before`, corta tudo a partir dessa mensagem (ela
+        // não volta) para simular a paginação de "carregar mensagens anteriores" no preview.
+        const messages = before ? allMessages.filter((message) => message.timestamp < before) : allMessages
         const limit = fetchParams?.limit
         return limit ? messages.slice(-limit) : messages
       })

package/src/styles.css

@@ -482,6 +482,25 @@
   color: #6b7280;
 }
 
+.cv-workspace-load-older {
+  display: flex;
+  justify-content: center;
+  padding: 0.5rem 0;
+}
+
+.cv-workspace-load-older button {
+  min-height: 2.75rem;
+  border-radius: 0.375rem;
+  border: 1px solid var(--cv-border, #e5e7eb);
+  padding: 0 0.75rem;
+  font-size: 0.8125rem;
+  color: #6b7280;
+}
+
+.cv-workspace-load-older button:disabled {
+  opacity: 0.6;
+}
+
 .dark .cv-workspace-notice {
   border-top-color: #374151;
   background: #1f2937;

package/src/workspace/ConversationPane.tsx

@@ -22,6 +22,7 @@ import { buildTranscriptFilename, buildTranscriptText, downloadTextFile } from '
 import { useConversationContext } from '../hooks/useConversationContext'
 import { useConversationMessages } from '../hooks/useConversationMessages'
 import { useConversationRealtime } from '../hooks/useConversationRealtime'
+import { useLoadOlderMessagesScroll } from '../hooks/useLoadOlderMessagesScroll'
 import { useScrollToLatestMessage } from '../hooks/useScrollToLatestMessage'
 import { useConversations } from '../providers/ConversationsProvider'
 import type { ConversationSummary } from '../providers/types'
@@ -151,7 +152,9 @@ export function ConversationPane({
   }
   const { api } = context
 
-  const { messages, refetch } = useConversationMessages(conversation.id)
+  const { messages, refetch, loadOlderMessages, loadingOlderMessages, hasMoreOlderMessages } = useConversationMessages(
+    conversation.id,
+  )
   const { context: conversationContext } = useConversationContext(conversation.id)
   const [documentsOpen, setDocumentsOpen] = useState(false)
   const [sendFailure, setSendFailure] = useState<string | undefined>(undefined)
@@ -230,6 +233,16 @@ export function ConversationPane({
   // interessa. O hook salta ao trocar de conversa sem arrastar quem estiver lendo o histórico.
   const scroll = useScrollToLatestMessage({ conversationId: conversation.id, messageCount: messages.length })
 
+  // Chegar perto do topo busca a página anterior e devolve a rolagem ao mesmo ponto visual — sem
+  // isso, prepender mensagens antigas empurraria o operador para o meio do histórico.
+  const loadOlder = useLoadOlderMessagesScroll({
+    containerRef: scroll.containerRef,
+    oldestMessageId: messages[0]?.id,
+    hasMore: hasMoreOlderMessages,
+    loading: loadingOlderMessages,
+    onLoadOlder: () => void loadOlderMessages(),
+  })
+
   // O evento traz só `{ direction, sender }` — quem tem o conteúdo é a query.
   useConversationRealtime(conversation.id, () => {
     void refetch()
@@ -352,9 +365,19 @@ export function ConversationPane({
           mesma aparência, senão o preview deixa de ser referência confiável. */}
       <ConversationWallpaper
         ref={scroll.containerRef}
-        onScroll={scroll.handleScroll}
+        onScroll={(event) => {
+          scroll.handleScroll(event)
+          loadOlder.handleScroll(event)
+        }}
         className="cv-workspace-transcript"
       >
+        {hasMoreOlderMessages ? (
+          <div className="cv-workspace-load-older">
+            <button type="button" onClick={loadOlder.triggerLoadOlder} disabled={loadingOlderMessages}>
+              {loadingOlderMessages ? labels.loadingOlderMessages : labels.loadOlderMessages}
+            </button>
+          </div>
+        ) : null}
         {messages.map((message, index) => {
           const previous = index > 0 ? messages[index - 1] : undefined
           const startsNewDay =
@@ -424,9 +447,11 @@ export function ConversationPane({
             ? {
                 onAttachFiles: (files: FileList) =>
                   enqueueAttachments(
-                    Array.from(files).map(
-                      (file): QueuedAttachment => ({ kind: 'local', localId: crypto.randomUUID(), file }),
-                    ),
+                    Array.from(files).map((file): QueuedAttachment => ({
+                      kind: 'local',
+                      localId: crypto.randomUUID(),
+                      file,
+                    })),
                   ),
               }
             : onAttach

package/src/workspace/labels.ts

@@ -32,6 +32,8 @@ export interface ConversationsWorkspaceLabels {
   readonly templateModalSend: (count: number) => string
   readonly messagesSelected: (count: number) => string
   readonly copySelected: string
+  readonly loadOlderMessages: string
+  readonly loadingOlderMessages: string
   readonly composerPlaceholder: string
   readonly attachFailure: string
   /** Tira um arquivo da fila antes de enviar. */
@@ -81,6 +83,8 @@ export const DEFAULT_CONVERSATIONS_WORKSPACE_LABELS: ConversationsWorkspaceLabel
   templateModalSend: (count) => `Enviar para ${count}`,
   messagesSelected: (count) => `${count} mensagem${count === 1 ? '' : 's'} selecionada${count === 1 ? '' : 's'}`,
   copySelected: 'Copiar',
+  loadOlderMessages: 'Carregar mensagens anteriores',
+  loadingOlderMessages: 'Carregando…',
   composerPlaceholder: 'Responder como atendente…',
   attachFailure: 'Falha ao enviar o arquivo.',
   attachmentRemove: 'Remover anexo',