@adatechnology/conversations-ui 0.1.0-rc.2 → 0.1.0-rc.4

package/src/conversationWindow.test.ts

@@ -0,0 +1,90 @@
+/**
+ * A classificação de janela decide se o atendente pode mandar texto livre. Errar a fronteira não
+ * quebra a tela — faz o WhatsApp recusar o envio depois, longe da causa.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { CONVERSATION_WINDOW, formatStalledFor, windowOf } from './conversationWindow'
+import { CONVERSATION_CHANNEL, contactFlag, formatContactHandle } from './conversationChannel'
+
+const NOW = new Date('2026-07-27T12:00:00.000Z').getTime()
+const HOUR = 60 * 60 * 1000
+
+function hoursAgo(hours: number): string {
+  return new Date(NOW - hours * HOUR).toISOString()
+}
+
+describe('windowOf', () => {
+  it('classifica por faixa de horas desde o último contato do cliente', () => {
+    expect(windowOf({ lastInboundAt: hoursAgo(0), now: NOW })).toBe(CONVERSATION_WINDOW.FRESH)
+    expect(windowOf({ lastInboundAt: hoursAgo(11.9), now: NOW })).toBe(CONVERSATION_WINDOW.FRESH)
+    expect(windowOf({ lastInboundAt: hoursAgo(15), now: NOW })).toBe(CONVERSATION_WINDOW.WARNING)
+    expect(windowOf({ lastInboundAt: hoursAgo(22), now: NOW })).toBe(CONVERSATION_WINDOW.CRITICAL)
+    expect(windowOf({ lastInboundAt: hoursAgo(30), now: NOW })).toBe(CONVERSATION_WINDOW.EXPIRED)
+  })
+
+  // As fronteiras são exatamente onde o erro custa caro: 24h em ponto já é recusa da Meta.
+  it('trata as fronteiras como início da faixa seguinte', () => {
+    expect(windowOf({ lastInboundAt: hoursAgo(12), now: NOW })).toBe(CONVERSATION_WINDOW.WARNING)
+    expect(windowOf({ lastInboundAt: hoursAgo(21), now: NOW })).toBe(CONVERSATION_WINDOW.CRITICAL)
+    expect(windowOf({ lastInboundAt: hoursAgo(24), now: NOW })).toBe(CONVERSATION_WINDOW.EXPIRED)
+  })
+
+  // Sem inbound não há janela aberta; classificar como expirada evita prometer texto livre.
+  it('considera expirada quando o cliente nunca escreveu', () => {
+    expect(windowOf({ lastInboundAt: null, now: NOW })).toBe(CONVERSATION_WINDOW.EXPIRED)
+  })
+
+  // O defeito que isto tranca: aplicar a regra do WhatsApp ao chat de site bloquearia o composer
+  // num canal onde nada expira.
+  it('nunca expira em canal sem janela de sessão', () => {
+    expect(windowOf({ lastInboundAt: hoursAgo(720), now: NOW, channel: CONVERSATION_CHANNEL.WEBCHAT })).toBe(
+      CONVERSATION_WINDOW.FRESH,
+    )
+    expect(windowOf({ lastInboundAt: null, now: NOW, channel: CONVERSATION_CHANNEL.WEBCHAT })).toBe(
+      CONVERSATION_WINDOW.FRESH,
+    )
+  })
+
+  it('mantém a regra do WhatsApp quando o canal não é informado', () => {
+    expect(windowOf({ lastInboundAt: hoursAgo(30), now: NOW })).toBe(
+      windowOf({ lastInboundAt: hoursAgo(30), now: NOW, channel: CONVERSATION_CHANNEL.WHATSAPP }),
+    )
+  })
+})
+
+describe('formatContactHandle', () => {
+  it('formata telefone no WhatsApp e arroba nas redes', () => {
+    expect(formatContactHandle({ handle: '5511988887777', channel: CONVERSATION_CHANNEL.WHATSAPP })).toBe(
+      '+55 (11) 98888-7777',
+    )
+    expect(formatContactHandle({ handle: 'marina.alves', channel: CONVERSATION_CHANNEL.INSTAGRAM })).toBe(
+      '@marina.alves',
+    )
+    expect(formatContactHandle({ handle: '@ja.tem', channel: CONVERSATION_CHANNEL.INSTAGRAM })).toBe('@ja.tem')
+  })
+
+  it('encurta a sessão anônima do chat de site', () => {
+    expect(formatContactHandle({ handle: 'sess_9f2a7c41b8', channel: CONVERSATION_CHANNEL.WEBCHAT })).toBe(
+      'Visitante 7c41b8',
+    )
+  })
+
+  // Bandeira em @perfil não significaria nada: o identificador não carrega país.
+  it('só devolve bandeira quando o identificador é telefone', () => {
+    expect(contactFlag({ handle: '5511988887777' })).toBe('🇧🇷')
+    expect(contactFlag({ handle: 'marina.alves', channel: CONVERSATION_CHANNEL.INSTAGRAM })).toBe('')
+  })
+})
+
+describe('formatStalledFor', () => {
+  it('formata dias, horas e minutos', () => {
+    expect(formatStalledFor(hoursAgo(5 * 24 + 6.2), NOW)).toBe('5d 6h:12m')
+    expect(formatStalledFor(hoursAgo(3.5), NOW)).toBe('3h:30m')
+    expect(formatStalledFor(hoursAgo(0.25), NOW)).toBe('15m')
+  })
+
+  it('não devolve tempo negativo para carimbo no futuro', () => {
+    expect(formatStalledFor(new Date(NOW + HOUR).toISOString(), NOW)).toBe('0m')
+  })
+})

package/src/conversationWindow.ts

@@ -0,0 +1,78 @@
+/**
+ * Janela de sessão: o intervalo em que o canal aceita mensagem livre do atendente. No WhatsApp são
+ * 24h desde o último contato do cliente; fora dela só template. Cada canal tem a sua regra — e há
+ * canal sem janela nenhuma — então a política vem de `capabilitiesOf`, não de constante fixa.
+ *
+ * Mora no SDK porque é regra de plataforma, não de produto: todo projeto que usa este pacote
+ * precisa dela para saber o que o atendente ainda consegue fazer.
+ */
+
+import { capabilitiesOf, type ConversationChannel } from './conversationChannel'
+
+const MINUTE_MS = 60_000
+const HOUR_MS = 60 * MINUTE_MS
+const DAY_MS = 24 * HOUR_MS
+
+export const CONVERSATION_WINDOW = {
+  ALL: 'all',
+  FRESH: 'fresh',
+  WARNING: 'warning',
+  CRITICAL: 'critical',
+  EXPIRED: 'expired',
+} as const
+export type ConversationWindow = (typeof CONVERSATION_WINDOW)[keyof typeof CONVERSATION_WINDOW]
+
+export const WINDOW_FILTERS = [
+  { value: CONVERSATION_WINDOW.ALL, label: 'Todas', dotClass: '' },
+  { value: CONVERSATION_WINDOW.FRESH, label: '<12h', dotClass: 'bg-green-500' },
+  { value: CONVERSATION_WINDOW.WARNING, label: '12-21h', dotClass: 'bg-yellow-500' },
+  { value: CONVERSATION_WINDOW.CRITICAL, label: '21-24h', dotClass: 'bg-red-500' },
+  { value: CONVERSATION_WINDOW.EXPIRED, label: '>24h', dotClass: 'bg-gray-400' },
+] as const
+
+// Proporções da janela: 12h e 21h numa janela de 24h, mas expressas como fração para acompanharem
+// canais com janela de outro tamanho.
+const WARNING_RATIO = 0.5
+const CRITICAL_RATIO = 0.875
+
+export type WindowOfParams = {
+  readonly lastInboundAt: string | null
+  readonly now: number
+  /** Ausente = `whatsapp`. */
+  readonly channel?: ConversationChannel | undefined
+}
+
+/**
+ * Sem `lastInboundAt` o cliente nunca escreveu, então não há janela aberta — classificar como
+ * expirada é o comportamento seguro: evita o atendente tentar texto livre e receber recusa.
+ *
+ * Canal sem janela de sessão (chat de site) é sempre `fresh`: ali nada expira, e marcar expirado
+ * bloquearia o composer inventando um limite que a plataforma não impõe.
+ */
+export function windowOf(params: WindowOfParams): ConversationWindow {
+  const capabilities = capabilitiesOf(params.channel)
+  if (!capabilities.hasSessionWindow) return CONVERSATION_WINDOW.FRESH
+
+  if (!params.lastInboundAt) return CONVERSATION_WINDOW.EXPIRED
+
+  const windowMs = capabilities.windowHours * HOUR_MS
+  const elapsed = params.now - new Date(params.lastInboundAt).getTime()
+
+  if (elapsed >= windowMs) return CONVERSATION_WINDOW.EXPIRED
+  // Faixas proporcionais à janela do canal, e não fixas em 12h/21h: um canal com janela diferente
+  // de 24h teria os avisos nos lugares errados.
+  if (elapsed >= windowMs * CRITICAL_RATIO) return CONVERSATION_WINDOW.CRITICAL
+  if (elapsed >= windowMs * WARNING_RATIO) return CONVERSATION_WINDOW.WARNING
+  return CONVERSATION_WINDOW.FRESH
+}
+
+export function formatStalledFor(lastAt: string, now: number): string {
+  const elapsed = Math.max(0, now - new Date(lastAt).getTime())
+  const days = Math.floor(elapsed / DAY_MS)
+  const hours = Math.floor((elapsed % DAY_MS) / HOUR_MS)
+  const minutes = Math.floor((elapsed % HOUR_MS) / MINUTE_MS)
+
+  if (days > 0) return `${days}d ${hours}h:${String(minutes).padStart(2, '0')}m`
+  if (hours > 0) return `${hours}h:${String(minutes).padStart(2, '0')}m`
+  return `${minutes}m`
+}

package/src/flows/FlowMapCanvas.tsx

@@ -1,7 +1,7 @@
 import { useMemo } from 'react'
 import { ReactFlow, Background, Controls, MarkerType, type Node, type Edge } from '@xyflow/react'
 import '@xyflow/react/dist/style.css'
-import { useDarkMode } from '../useDarkMode'
+import { useIsDarkTheme } from '../useDarkMode'
 import { flowMapNodeTypes, type FlowMapNodeData } from './FlowMapNode'
 import { computeFlowMapLayout, crossFlowTargetsOf, type FlowGraphData } from './flowGraph'
 import { DEFAULT_FLOW_EDITOR_LABELS, type FlowEditorLabels } from './labels'
@@ -23,7 +23,7 @@ export interface FlowMapCanvasProps {
 // visão hierárquica onde cada fluxo é um único nó, ligado por saltos "flow:<key>".
 export function FlowMapCanvas({ graphs, rootKey, onOpenFlow, labels: labelsOverride }: FlowMapCanvasProps) {
   const labels = { ...DEFAULT_FLOW_EDITOR_LABELS, ...labelsOverride }
-  const { isDark } = useDarkMode()
+  const isDark = useIsDarkTheme()
   const positions = useMemo(() => computeFlowMapLayout(graphs, rootKey), [graphs, rootKey])
 
   const nodes = useMemo<Node[]>(

package/src/hooks/useConversationDocuments.ts

@@ -14,8 +14,10 @@ export interface UseConversationDocumentsResult {
   refetch: () => Promise<void>
 }
 
+// Aceita `undefined` como "ainda não buscar", igual a `useConversationRealtime`: a lista de anexos
+// é consulta extra, e quem só abre o painel sob demanda não deve pagar por ela em toda conversa.
 export function useConversationDocuments(
-  conversationId: string,
+  conversationId: string | undefined,
   params?: UseConversationDocumentsParams,
 ): UseConversationDocumentsResult {
   const context = useConversations()
@@ -25,7 +27,7 @@ export function useConversationDocuments(
   const { api } = context
 
   const { data, loading, error, refetch } = useAsyncResource(
-    () => api.getDocuments(conversationId, params),
+    () => (conversationId ? api.getDocuments(conversationId, params) : Promise.resolve([])),
     [conversationId, params?.search, params?.page],
   )
 

package/src/index.ts

@@ -19,7 +19,60 @@ export { MessageText } from './MessageText'
 export { MessageTimestamp } from './MessageTimestamp'
 export { MessageTail } from './MessageTail'
 
-export { useDarkMode } from './useDarkMode'
+// Operação da inbox: janela de 24h da Meta, linha com ações e painéis do atendimento. Regras da
+// plataforma e do ofício de atender, não de um produto — por isso moram aqui.
+export { CONVERSATION_WINDOW, WINDOW_FILTERS, windowOf, formatStalledFor } from './conversationWindow'
+export type { WindowOfParams } from './conversationWindow'
+// Canal de origem: capacidades por plataforma (janela de sessão, reabertura, tipo de identificador).
+export {
+  CONVERSATION_CHANNEL,
+  DEFAULT_CONVERSATION_CHANNEL,
+  CHANNEL_CAPABILITIES,
+  channelFiltersFor,
+  CHANNEL_FILTER_ALL,
+  REOPEN_MECHANISM,
+  HANDLE_KIND,
+  capabilitiesOf,
+  formatContactHandle,
+  contactFlag,
+} from './conversationChannel'
+export type {
+  ConversationChannel,
+  ChannelCapabilities,
+  ChannelFilter,
+  ChannelFilterOption,
+  ReopenMechanism,
+  HandleKind,
+  FormatContactHandleParams,
+} from './conversationChannel'
+export type { ConversationWindow } from './conversationWindow'
+export { ConversationRow } from './ConversationRow'
+export { ChannelIcon, CHANNEL_BRAND_COLOR } from './ChannelIcon'
+export type { ChannelIconProps } from './ChannelIcon'
+export type { ConversationRowProps, ConversationRowClassNames } from './ConversationRow'
+export { ConversationHeader, DEFAULT_CONVERSATION_HEADER_LABELS } from './ConversationHeader'
+export type {
+  ConversationHeaderProps,
+  ConversationHeaderLabels,
+  ConversationHeaderClassNames,
+} from './ConversationHeader'
+export { ConversationContextPanel, DEFAULT_CONVERSATION_CONTEXT_LABELS } from './ConversationContextPanel'
+export type {
+  ConversationContextPanelProps,
+  ConversationContextEntry,
+  ConversationContextPanelLabels,
+  ConversationContextPanelClassNames,
+} from './ConversationContextPanel'
+export { WindowExpiredNotice, isWindowBlocking, DEFAULT_WINDOW_EXPIRED_LABELS } from './WindowExpiredNotice'
+export type { WindowExpiredNoticeProps, WindowExpiredNoticeLabels } from './WindowExpiredNotice'
+export type { ConversationDocumentsPanelClassNames } from './ConversationDocumentsPanel'
+export { ConversationDocumentsPanel, DEFAULT_CONVERSATION_DOCUMENTS_LABELS } from './ConversationDocumentsPanel'
+export type { ConversationDocumentsPanelProps, ConversationDocumentsPanelLabels } from './ConversationDocumentsPanel'
+export { buildTranscriptText, buildTranscriptFilename, downloadTextFile } from './conversationTranscript'
+export type { BuildTranscriptTextParams } from './conversationTranscript'
+
+export { useDarkMode, useIsDarkTheme } from './useDarkMode'
+export { useIsNarrow, NARROW_MAX_WIDTH_PX } from './useIsNarrow'
 export { useWaitingNotifications } from './useWaitingNotifications'
 
 export { ConversationsProvider, useConversations } from './providers/ConversationsProvider'
@@ -29,6 +82,11 @@ export { ConversationsProvider, useConversations } from './providers/Conversatio
 export { WhatsAppTemplateSettingsForm } from './settings/WhatsAppTemplateSettingsForm'
 export { WhatsAppCreateTemplateForm } from './settings/WhatsAppCreateTemplateForm'
 export { WelcomeFarewellForm } from './settings/WelcomeFarewellForm'
+export {
+  WhatsAppTemplatesSettings,
+  TEMPLATE_SETTINGS_TAB,
+  DEFAULT_TEMPLATES_SETTINGS_LABELS,
+} from './settings/WhatsAppTemplatesSettings'
 export { TopicsForm } from './settings/TopicsForm'
 
 // Camada headless (T6.9) — hooks de dados/ações independentes de qualquer tela, para o
@@ -44,17 +102,23 @@ export { formatPhone, phoneInitials } from './lib/phone'
 export { formatTimestamp, formatFileSize } from './lib/format'
 
 export type { MessagePayload, ConversationsUIConfig, ConversationsTheme, ConversationsFeatures } from './types'
-export type { ConversationsApi, SSEProvider, ConversationSummary, ConversationDocument } from './providers/types'
+export type {
+  ConversationsApi,
+  SSEProvider,
+  ConversationEventSource,
+  ConversationSummary,
+  ConversationDocument,
+} from './providers/types'
 
 export type { MessageBubbleProps } from './MessageBubble'
 export type { ConversationWallpaperProps } from './Wallpaper'
 export type { ConversationLocales, ConversationLocalesProviderProps } from './ConversationLocalesProvider'
 export type { AudioPlayerProps } from './AudioPlayer'
 export type { EmojiPickerProps } from './EmojiPicker'
-export type { MessageComposerProps } from './MessageComposer'
+export type { MessageComposerProps, MessageComposerClassNames } from './MessageComposer'
 export type { WhatsAppMessageEditorProps } from './WhatsAppMessageEditor'
 export type { SimpleEmojiPickerProps } from './SimpleEmojiPicker'
-export type { DateDividerProps } from './DateDivider'
+export type { DateDividerProps, DateDividerClassNames } from './DateDivider'
 export type { AvatarProps } from './Avatar'
 export type { ConversationListItemProps } from './ConversationListItem'
 export type { StatusTicksProps } from './StatusTicks'
@@ -77,6 +141,11 @@ export type {
   WhatsAppCreateTemplateFormLabels,
 } from './settings/WhatsAppCreateTemplateForm'
 export type { WelcomeFarewellFormProps, WelcomeFarewellFormLabels } from './settings/WelcomeFarewellForm'
+export type {
+  WhatsAppTemplatesSettingsProps,
+  WhatsAppTemplatesSettingsLabels,
+  TemplateSettingsTab,
+} from './settings/WhatsAppTemplatesSettings'
 export type { TopicsFormProps, TopicItem, TopicsFormLabels } from './settings/TopicsForm'
 
 export type { UseConversationMessagesResult } from './hooks/useConversationMessages'

package/src/lib/cn.ts

@@ -0,0 +1,15 @@
+/**
+ * Junta classes resolvendo conflitos de utilitário do Tailwind.
+ *
+ * Concatenar não basta: a ordem no atributo `class` não decide nada, quem decide é a ordem no CSS
+ * gerado. Com `px-4` na base e `px-2` vindo do host, o Tailwind emite `px-2` antes de `px-4` e a
+ * base ganharia — justo o caso de quem quer apertar o espaçamento. O `twMerge` descarta a classe
+ * base quando o host manda uma da mesma família, então o override do produto sempre vence.
+ */
+
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}

package/src/lib/phone.ts

@@ -20,6 +20,40 @@ export function formatPhone(number: string): string {
   return number
 }
 
+// Mapa explícito em vez de derivar o emoji do código: prefixos são ambíguos (1 = EUA e Canadá,
+// 7 = Rússia e Cazaquistão) e mostrar a bandeira errada é pior do que não mostrar nenhuma.
+const COUNTRY_FLAG_BY_DIAL_CODE: Readonly<Record<string, string>> = {
+  '55': '🇧🇷',
+  '351': '🇵🇹',
+  '34': '🇪🇸',
+  '54': '🇦🇷',
+  '56': '🇨🇱',
+  '57': '🇨🇴',
+  '52': '🇲🇽',
+  '598': '🇺🇾',
+  '595': '🇵🇾',
+  '44': '🇬🇧',
+  '49': '🇩🇪',
+  '39': '🇮🇹',
+  '33': '🇫🇷',
+}
+
+/**
+ * Devolve string vazia quando não reconhece o país — quem renderiza decide se some com o espaço.
+ */
+export function phoneCountryFlag(number: string): string {
+  const digits = number.replace(/\D/g, '')
+
+  // Do prefixo mais longo para o mais curto: '55' casaria antes de '551' e daria bandeira errada
+  // em países de código de três dígitos.
+  for (const length of [3, 2, 1]) {
+    const flag = COUNTRY_FLAG_BY_DIAL_CODE[digits.slice(0, length)]
+    if (flag) return flag
+  }
+
+  return ''
+}
+
 export function phoneInitials(number: string): string {
   const digits = number.replace(/\D/g, '')
   return digits.slice(-2)

package/src/preview/ConversationPreview.tsx

@@ -0,0 +1,148 @@
+/**
+ * Visão lado-cliente: você digita como se fosse o cliente no WhatsApp e vê o bot responder. A
+ * mensagem sai assinada para o webhook real, então o que roda aqui é o mesmo caminho de staging e
+ * produção — webhook, parser, motor de conversa.
+ *
+ * É o layout de conversa de verdade (wallpaper, divisor de data, agrupamento de bolhas), não uma
+ * casca de teste: o preview serve para julgar copy e fluxo, e isso só funciona se o que se vê
+ * aqui for o que o cliente vê no aparelho dele.
+ *
+ * O SSE só avisa que algo mudou (`{ direction, sender }`, sem conteúdo), então a chegada de um
+ * evento dispara refetch. É assim que o servidor funciona; renderizar direto do evento
+ * funcionaria no mock e quebraria em produção.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { MessagePayload } from '../types'
+import type { SSEProvider } from '../providers/types'
+import { MessageBubble } from '../MessageBubble'
+import { MessageComposer } from '../MessageComposer'
+import { DateDivider } from '../DateDivider'
+import { ConversationWallpaper } from '../Wallpaper'
+import type { PreviewWebhookClient } from './createPreviewWebhookClient'
+
+export type ConversationPreviewProps = {
+  client: PreviewWebhookClient
+  sse: SSEProvider
+  conversationId: string
+  loadMessages: (conversationId: string) => Promise<MessagePayload[]>
+  placeholder?: string
+}
+
+// Mesma janela usada pelo WhatsApp para colar bolhas do mesmo autor: acima disso, a mensagem
+// recomeça um grupo (com rabicho e espaçamento maior).
+const GROUPING_WINDOW_MS = 5 * 60 * 1000
+
+type RenderedMessage = {
+  readonly message: MessagePayload
+  readonly isFirstInGroup: boolean
+  readonly showDateDivider: boolean
+}
+
+function decorate(messages: readonly MessagePayload[]): RenderedMessage[] {
+  return messages.map((message, index) => {
+    const previous = index > 0 ? messages[index - 1] : undefined
+    const currentTime = new Date(message.timestamp).getTime()
+    const previousTime = previous ? new Date(previous.timestamp).getTime() : 0
+
+    return {
+      message,
+      isFirstInGroup:
+        !previous || previous.sender !== message.sender || currentTime - previousTime > GROUPING_WINDOW_MS,
+      showDateDivider:
+        !previous || new Date(message.timestamp).toDateString() !== new Date(previous.timestamp).toDateString(),
+    }
+  })
+}
+
+export function ConversationPreview({
+  client,
+  sse,
+  conversationId,
+  loadMessages,
+  placeholder,
+}: ConversationPreviewProps) {
+  const [messages, setMessages] = useState<MessagePayload[]>([])
+  const [failure, setFailure] = useState<string | undefined>(undefined)
+  const loadMessagesRef = useRef(loadMessages)
+  const bottomRef = useRef<HTMLDivElement>(null)
+  loadMessagesRef.current = loadMessages
+
+  const refresh = useCallback(async (): Promise<void> => {
+    try {
+      setMessages(await loadMessagesRef.current(conversationId))
+    } catch {
+      // Conversa que ainda não existe é o estado normal do primeiro contato — a API responde erro
+      // e a tela deve mostrar o transcript vazio, não uma falha.
+      setMessages([])
+    }
+  }, [conversationId])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  useEffect(() => {
+    const source = sse.connectConversationStream(conversationId)
+    const handler = (): void => {
+      void refresh()
+    }
+
+    source.addEventListener('message', handler)
+    return () => {
+      source.removeEventListener('message', handler)
+      source.close()
+    }
+  }, [sse, conversationId, refresh])
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
+  }, [messages])
+
+  const rendered = useMemo(() => decorate(messages), [messages])
+
+  async function handleSend(text: string): Promise<void> {
+    setFailure(undefined)
+    try {
+      await client.sendText(text)
+      // O bot responde de forma assíncrona e o ping do SSE cobre isso; este refresh é para a
+      // própria mensagem enviada aparecer na hora, sem esperar o ciclo de evento.
+      await refresh()
+    } catch (error) {
+      // A recusa mais provável é assinatura inválida (segredo divergente do que a API valida), e
+      // ela precisa aparecer na tela: silenciada, o sintoma vira "mandei e não aconteceu nada".
+      setFailure(error instanceof Error ? error.message : 'Falha ao entregar a mensagem no webhook.')
+    }
+  }
+
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      <ConversationWallpaper className="flex-1 min-h-0 overflow-y-auto px-4 py-3">
+        {rendered.map(({ message, isFirstInGroup, showDateDivider }) => (
+          <div key={message.id}>
+            {showDateDivider ? <DateDivider iso={message.timestamp} /> : null}
+            <MessageBubble
+              message={message}
+              // Na visão do cliente, "minha" mensagem é a que ele enviou — inbound do ponto de
+              // vista do servidor.
+              isMine={message.direction === 'inbound'}
+              isFirstInGroup={isFirstInGroup}
+            />
+          </div>
+        ))}
+        <div ref={bottomRef} />
+      </ConversationWallpaper>
+
+      {failure ? (
+        <p role="alert" className="px-4 py-2 text-sm text-red-600 dark:text-red-400">
+          {failure}
+        </p>
+      ) : null}
+
+      <MessageComposer
+        onSend={(text) => void handleSend(text)}
+        placeholder={placeholder ?? 'Escreva como o cliente…'}
+      />
+    </div>
+  )
+}

package/src/preview/createMockConversationsApi.ts

@@ -0,0 +1,111 @@
+/**
+ * `ConversationsApi` servido pelo store em memória. Como o pacote é headless e recebe a API por
+ * injeção, o preview de atendimento humano não precisa de servidor, banco nem Meta: é só outra
+ * implementação deste mesmo contrato.
+ *
+ * Toda resposta é assíncrona e passa por um atraso configurável — API instantânea esconde estados
+ * de carregamento, e é neles que a inbox costuma mostrar defeito.
+ */
+
+import type { MessagePayload } from '../types'
+import type { ConversationDocument, ConversationsApi, ConversationSummary } from '../providers/types'
+import type { PreviewStore } from './previewStore'
+
+// PNG 1x1 transparente: o suficiente para o MediaRenderer ter algo válido para desenhar.
+const PREVIEW_IMAGE_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYGD4DwABBAEAX+XyEgAAAABJRU5ErkJggg=='
+
+export type CreateMockConversationsApiParams = {
+  readonly store: PreviewStore
+  readonly latencyMs?: number
+  readonly agentName?: string
+}
+
+const DEFAULT_LATENCY_MS = 120
+
+export function createMockConversationsApi(params: CreateMockConversationsApiParams): ConversationsApi {
+  const latencyMs = params.latencyMs ?? DEFAULT_LATENCY_MS
+
+  async function withLatency<TResult>(produce: () => TResult): Promise<TResult> {
+    await new Promise((resolve) => setTimeout(resolve, latencyMs))
+    return produce()
+  }
+
+  return {
+    fetchConversations(fetchParams): Promise<ConversationSummary[]> {
+      return withLatency(() => {
+        const conversations = params.store.listConversations({
+          waitingHuman: fetchParams?.waitingHuman,
+          search: fetchParams?.search,
+        })
+
+        const limit = fetchParams?.limit ?? conversations.length
+        const page = fetchParams?.page ?? 1
+        return conversations.slice((page - 1) * limit, page * limit)
+      })
+    },
+
+    fetchMessages(conversationId, fetchParams): Promise<MessagePayload[]> {
+      return withLatency(() => {
+        const messages = params.store.listMessages(conversationId)
+        const limit = fetchParams?.limit
+        return limit ? messages.slice(-limit) : messages
+      })
+    },
+
+    sendMessage(conversationId, text): Promise<MessagePayload> {
+      return withLatency(() =>
+        params.store.appendMessage({ conversationId, content: text, direction: 'outbound', sender: 'agent' }),
+      )
+    },
+
+    sendMedia(conversationId, data): Promise<MessagePayload> {
+      return withLatency(() =>
+        params.store.appendMessage({
+          conversationId,
+          content: data.caption ?? data.filename,
+          direction: 'outbound',
+          sender: 'agent',
+        }),
+      )
+    },
+
+    sendTemplate(conversationId, data): Promise<void> {
+      return withLatency(() => {
+        params.store.appendMessage({
+          conversationId,
+          content: `[template] ${data.templateName}`,
+          direction: 'outbound',
+          sender: 'agent',
+        })
+      })
+    },
+
+    markRead(conversationId): Promise<void> {
+      return withLatency(() => params.store.markRead(conversationId))
+    },
+
+    getContext(conversationId): Promise<Record<string, unknown>> {
+      return withLatency(() => {
+        const conversation = params.store.listConversations().find((item) => item.id === conversationId)
+        return {
+          currentState: conversation?.currentState ?? 'unknown',
+          mode: conversation?.mode ?? 'bot',
+          preview: true,
+        }
+      })
+    },
+
+    getDocuments(): Promise<ConversationDocument[]> {
+      return withLatency(() => [])
+    },
+
+    getDocumentUrl(): Promise<string> {
+      return withLatency(() => `data:image/png;base64,${PREVIEW_IMAGE_BASE64}`)
+    },
+
+    getMediaProxyUrl(): Promise<{ mimeType: string; data: string }> {
+      return withLatency(() => ({ mimeType: 'image/png', data: PREVIEW_IMAGE_BASE64 }))
+    },
+  }
+}

package/src/preview/createMockSSEProvider.ts

@@ -0,0 +1,40 @@
+/**
+ * `SSEProvider` servido pelo store em memória. Mesmo mapeamento de canal do servidor
+ * (`conv:<conversationId>` e `global`), para que a UI não perceba a troca.
+ */
+
+import type { SSEProvider } from '../providers/types'
+import { createMockEventSource } from './mockEventSource'
+import { conversationChannel, GLOBAL_CHANNEL, type PreviewStore } from './previewStore'
+
+export type CreateMockSSEProviderParams = {
+  readonly store: PreviewStore
+}
+
+export function createMockSSEProvider(params: CreateMockSSEProviderParams): SSEProvider {
+  function connect(channel: string): ReturnType<typeof createMockEventSource> {
+    const source = createMockEventSource()
+    const unsubscribe = params.store.subscribe(channel, (emission) => {
+      source.emit(emission.event, emission.payload)
+    })
+
+    const close = source.close.bind(source)
+    // O unsubscribe tem de acontecer no close, senão cada remontagem de componente deixa um
+    // listener preso no store e a mesma mensagem chega duplicada na UI.
+    source.close = (): void => {
+      unsubscribe()
+      close()
+    }
+
+    return source
+  }
+
+  return {
+    connectConversationStream(conversationId: string) {
+      return connect(conversationChannel(conversationId))
+    },
+    connectGlobalStream() {
+      return connect(GLOBAL_CHANNEL)
+    },
+  }
+}