@adatechnology/conversations-ui 0.1.0-rc.1 → 0.1.0-rc.11

package/src/conversationTranscript.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'bun:test'
+import { buildTranscriptFilename, buildTranscriptText } from './conversationTranscript'
+import type { MessagePayload } from './types'
+
+const NUMBER = '5511988887777'
+
+function message(partial: Partial<MessagePayload>): MessagePayload {
+  return {
+    id: 'm1',
+    type: 'text',
+    direction: 'inbound',
+    sender: 'customer',
+    timestamp: '2026-07-27T12:00:00.000Z',
+    ...partial,
+  }
+}
+
+describe('buildTranscriptText', () => {
+  it('escreve cabeçalho e uma linha por mensagem', () => {
+    const text = buildTranscriptText({
+      messages: [
+        message({ id: 'm1', content: 'oi' }),
+        message({ id: 'm2', content: 'Olá!', direction: 'outbound', sender: 'bot' }),
+      ],
+      whatsappNumber: NUMBER,
+      clientName: 'Marina',
+    })
+
+    expect(text).toContain('Conversa: Marina')
+    expect(text).toContain(`Número: ${NUMBER}`)
+    expect(text).toContain('Mensagens: 2')
+    expect(text).toContain('Cliente: oi')
+    expect(text).toContain('Bot: Olá!')
+  })
+
+  // Sem isto a linha sairia vazia e o histórico esconderia que houve um anexo ali.
+  it('marca o tipo quando a mensagem não tem texto', () => {
+    const text = buildTranscriptText({ messages: [message({ type: 'audio' })], whatsappNumber: NUMBER })
+
+    expect(text).toContain('<audio>')
+  })
+
+  it('usa o nome do atendente quando existe, em vez do papel genérico', () => {
+    const text = buildTranscriptText({
+      messages: [message({ direction: 'outbound', sender: 'agent', agentName: 'Ana', content: 'já separei' })],
+      whatsappNumber: NUMBER,
+    })
+
+    expect(text).toContain('Ana: já separei')
+  })
+
+  it('cai no número quando não há nome do cliente', () => {
+    const text = buildTranscriptText({ messages: [], whatsappNumber: NUMBER })
+
+    expect(text).toContain(`Conversa: ${NUMBER}`)
+  })
+})
+
+describe('buildTranscriptFilename', () => {
+  it('inclui número e data', () => {
+    expect(buildTranscriptFilename(NUMBER, new Date('2026-07-27T23:00:00.000Z'))).toBe(
+      `conversa-${NUMBER}-2026-07-27.txt`,
+    )
+  })
+})

package/src/conversationTranscript.ts

@@ -0,0 +1,64 @@
+/**
+ * Serialização do transcript para download. Fica no pacote porque o formato de um histórico de
+ * WhatsApp legível não é regra de negócio de ninguém — e porque o host que já tem as mensagens em
+ * tela não deveria precisar de rota nova só para salvar um arquivo.
+ *
+ * Funções puras, separadas do disparo do download: é o que permite testá-las sem DOM.
+ */
+
+import type { MessagePayload } from './types'
+
+const SENDER_LABEL: Record<MessagePayload['sender'], string> = {
+  customer: 'Cliente',
+  bot: 'Bot',
+  agent: 'Atendente',
+}
+
+export type BuildTranscriptTextParams = {
+  readonly messages: readonly MessagePayload[]
+  readonly whatsappNumber: string
+  readonly clientName?: string | undefined
+}
+
+/**
+ * Formato próximo ao export nativo do WhatsApp (`[data hora] Autor: texto`), que é o que pessoas e
+ * ferramentas de suporte já sabem ler.
+ */
+export function buildTranscriptText(params: BuildTranscriptTextParams): string {
+  const header = [
+    `Conversa: ${params.clientName ?? params.whatsappNumber}`,
+    `Número: ${params.whatsappNumber}`,
+    `Mensagens: ${params.messages.length}`,
+    '',
+  ]
+
+  const lines = params.messages.map((message) => {
+    const stamp = new Date(message.timestamp).toLocaleString('pt-BR')
+    const author = message.agentName ?? SENDER_LABEL[message.sender]
+    // Mídia sem legenda não tem texto nenhum; marcar o tipo evita uma linha vazia sem explicação.
+    const body = message.content ?? message.caption ?? `<${message.type}>`
+    return `[${stamp}] ${author}: ${body}`
+  })
+
+  return [...header, ...lines].join('\n')
+}
+
+export function buildTranscriptFilename(whatsappNumber: string, generatedAt: Date): string {
+  const stamp = generatedAt.toISOString().slice(0, 10)
+  return `conversa-${whatsappNumber}-${stamp}.txt`
+}
+
+/**
+ * Dispara o download no navegador. `revokeObjectURL` no fim não é higiene opcional: sem ele cada
+ * export retém o blob inteiro em memória até a aba fechar.
+ */
+export function downloadTextFile(filename: string, content: string): void {
+  const blob = new Blob([content], { type: 'text/plain;charset=utf-8' })
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+
+  anchor.href = url
+  anchor.download = filename
+  anchor.click()
+  URL.revokeObjectURL(url)
+}

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/emojiCatalog.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'bun:test'
+import { EMOJI_CATEGORIES, searchEmojis } from './emojiCatalog'
+
+describe('searchEmojis', () => {
+  it('devolve o catálogo inteiro quando não há termo', () => {
+    const total = EMOJI_CATEGORIES.reduce((sum, category) => sum + category.entries.length, 0)
+    expect(searchEmojis('').length).toBe(total)
+    expect(searchEmojis('   ').length).toBe(total)
+  })
+
+  it('acha pela palavra sem acento e com acento', () => {
+    const semAcento = searchEmojis('coracao').map((entry) => entry.emoji)
+    const comAcento = searchEmojis('coração').map((entry) => entry.emoji)
+
+    expect(semAcento).toContain('❤️')
+    expect(comAcento).toContain('❤️')
+  })
+
+  it('ignora caixa e casa por prefixo, não pelo meio da palavra', () => {
+    expect(searchEmojis('CASA').map((entry) => entry.emoji)).toContain('🏠')
+    // "sa" está dentro de "casa", mas não é prefixo de nenhuma palavra-chave dela.
+    expect(searchEmojis('sa').map((entry) => entry.emoji)).not.toContain('🏠')
+  })
+
+  it('atravessa categorias, não só a aberta', () => {
+    const resultados = searchEmojis('pagamento').map((entry) => entry.emoji)
+
+    expect(resultados).toContain('💳')
+    expect(resultados.length).toBeGreaterThan(1)
+  })
+
+  it('devolve vazio quando nada casa, em vez de cair no catálogo inteiro', () => {
+    expect(searchEmojis('xyzabc')).toEqual([])
+  })
+})

package/src/emojiCatalog.ts

@@ -0,0 +1,189 @@
+/**
+ * Catálogo de emojis com palavras-chave em português, usado pela busca do seletor.
+ *
+ * Fica em módulo próprio (e não dentro do `EmojiPicker`) porque a busca precisa varrer TODAS as
+ * categorias, não só a aberta — o índice é montado uma vez, no carregamento, e não a cada tecla.
+ *
+ * As palavras-chave são de busca, não legendas: incluem sinônimos e formas sem acento, porque quem
+ * digita rápido escreve "coracao" e "polegar" com a mesma frequência que a forma correta.
+ */
+
+export type EmojiEntry = {
+  readonly emoji: string
+  readonly keywords: readonly string[]
+}
+
+export type EmojiCategory = {
+  readonly name: string
+  readonly entries: readonly EmojiEntry[]
+}
+
+export const EMOJI_CATEGORIES: readonly EmojiCategory[] = [
+  {
+    name: 'Smileys',
+    entries: [
+      { emoji: '😀', keywords: ['sorriso', 'feliz', 'alegre'] },
+      { emoji: '😃', keywords: ['sorriso', 'feliz', 'animado'] },
+      { emoji: '😄', keywords: ['sorriso', 'feliz', 'risada'] },
+      { emoji: '😁', keywords: ['sorriso', 'dentes', 'feliz'] },
+      { emoji: '😅', keywords: ['alivio', 'alívio', 'suor', 'nervoso'] },
+      { emoji: '😂', keywords: ['risada', 'chorando', 'engracado', 'engraçado'] },
+      { emoji: '🤣', keywords: ['risada', 'rolando', 'engracado', 'engraçado'] },
+      { emoji: '😊', keywords: ['sorriso', 'timido', 'tímido', 'feliz'] },
+      { emoji: '😇', keywords: ['anjo', 'inocente', 'santo'] },
+      { emoji: '🙂', keywords: ['sorriso', 'leve', 'ok'] },
+      { emoji: '😉', keywords: ['piscada', 'piscar', 'flerte'] },
+      { emoji: '😌', keywords: ['aliviado', 'calmo', 'tranquilo'] },
+      { emoji: '😍', keywords: ['amor', 'apaixonado', 'coracao', 'coração', 'olhos'] },
+      { emoji: '🥰', keywords: ['amor', 'apaixonado', 'carinho'] },
+      { emoji: '😘', keywords: ['beijo', 'amor', 'carinho'] },
+      { emoji: '😋', keywords: ['gostoso', 'delicia', 'delícia', 'lingua', 'língua'] },
+      { emoji: '😜', keywords: ['lingua', 'língua', 'brincadeira', 'piscada'] },
+      { emoji: '🤪', keywords: ['maluco', 'doido', 'brincadeira'] },
+      { emoji: '🤔', keywords: ['pensando', 'duvida', 'dúvida', 'hmm'] },
+      { emoji: '🤗', keywords: ['abraco', 'abraço', 'carinho'] },
+      { emoji: '😐', keywords: ['neutro', 'serio', 'sério', 'indiferente'] },
+      { emoji: '😴', keywords: ['dormindo', 'sono', 'cansado'] },
+      { emoji: '😭', keywords: ['chorando', 'triste', 'lagrima', 'lágrima'] },
+      { emoji: '😢', keywords: ['triste', 'chorando', 'lagrima', 'lágrima'] },
+      { emoji: '😡', keywords: ['raiva', 'bravo', 'irritado'] },
+      { emoji: '😱', keywords: ['susto', 'medo', 'assustado'] },
+      { emoji: '🤯', keywords: ['explodindo', 'chocado', 'surpresa'] },
+      { emoji: '😎', keywords: ['oculos', 'óculos', 'legal', 'estiloso'] },
+      { emoji: '🥳', keywords: ['festa', 'comemorar', 'aniversario', 'aniversário'] },
+      { emoji: '😷', keywords: ['mascara', 'máscara', 'doente', 'saude', 'saúde'] },
+    ],
+  },
+  {
+    name: 'Gestos',
+    entries: [
+      { emoji: '👍', keywords: ['joia', 'jóia', 'polegar', 'ok', 'positivo', 'curtir'] },
+      { emoji: '👎', keywords: ['polegar', 'negativo', 'ruim', 'nao', 'não'] },
+      { emoji: '👌', keywords: ['ok', 'certo', 'perfeito'] },
+      { emoji: '✌️', keywords: ['paz', 'vitoria', 'vitória', 'dois'] },
+      { emoji: '🤞', keywords: ['sorte', 'dedos', 'cruzados', 'torcendo'] },
+      { emoji: '🤙', keywords: ['chama', 'ligar', 'shaka'] },
+      { emoji: '👋', keywords: ['tchau', 'ola', 'olá', 'aceno', 'oi'] },
+      { emoji: '✋', keywords: ['mao', 'mão', 'parar', 'pare'] },
+      { emoji: '👏', keywords: ['palmas', 'aplauso', 'parabens', 'parabéns'] },
+      { emoji: '🙌', keywords: ['comemorar', 'maos', 'mãos', 'sucesso'] },
+      { emoji: '🤝', keywords: ['acordo', 'aperto', 'mao', 'mão', 'negocio', 'negócio', 'parceria'] },
+      { emoji: '🙏', keywords: ['obrigado', 'reza', 'oracao', 'oração', 'por favor'] },
+      { emoji: '✍️', keywords: ['escrever', 'assinar', 'assinatura'] },
+      { emoji: '💪', keywords: ['forca', 'força', 'musculo', 'músculo', 'braco', 'braço'] },
+      { emoji: '👇', keywords: ['abaixo', 'baixo', 'apontar', 'seta'] },
+      { emoji: '👉', keywords: ['direita', 'apontar', 'seta'] },
+      { emoji: '☝️', keywords: ['acima', 'cima', 'apontar', 'atencao', 'atenção'] },
+    ],
+  },
+  {
+    name: 'Corações',
+    entries: [
+      { emoji: '❤️', keywords: ['coracao', 'coração', 'amor', 'vermelho'] },
+      { emoji: '🧡', keywords: ['coracao', 'coração', 'laranja'] },
+      { emoji: '💛', keywords: ['coracao', 'coração', 'amarelo'] },
+      { emoji: '💚', keywords: ['coracao', 'coração', 'verde'] },
+      { emoji: '💙', keywords: ['coracao', 'coração', 'azul'] },
+      { emoji: '💜', keywords: ['coracao', 'coração', 'roxo'] },
+      { emoji: '🖤', keywords: ['coracao', 'coração', 'preto'] },
+      { emoji: '🤍', keywords: ['coracao', 'coração', 'branco'] },
+      { emoji: '💔', keywords: ['coracao', 'coração', 'partido', 'triste'] },
+      { emoji: '💕', keywords: ['coracao', 'coração', 'amor', 'casal'] },
+      { emoji: '💖', keywords: ['coracao', 'coração', 'brilho', 'amor'] },
+      { emoji: '💝', keywords: ['coracao', 'coração', 'presente', 'laco', 'laço'] },
+    ],
+  },
+  {
+    name: 'Negócios',
+    entries: [
+      { emoji: '🏠', keywords: ['casa', 'imovel', 'imóvel', 'residencia', 'residência', 'moradia'] },
+      { emoji: '🏡', keywords: ['casa', 'imovel', 'imóvel', 'jardim', 'moradia'] },
+      { emoji: '🏢', keywords: ['predio', 'prédio', 'empresa', 'escritorio', 'escritório'] },
+      { emoji: '🏦', keywords: ['banco', 'financiamento', 'agencia', 'agência'] },
+      { emoji: '🔑', keywords: ['chave', 'casa', 'entrega', 'imovel', 'imóvel'] },
+      { emoji: '📄', keywords: ['documento', 'papel', 'contrato', 'arquivo'] },
+      { emoji: '📋', keywords: ['prancheta', 'lista', 'documento', 'checklist'] },
+      { emoji: '📝', keywords: ['anotar', 'escrever', 'nota', 'formulario', 'formulário'] },
+      { emoji: '✅', keywords: ['ok', 'certo', 'aprovado', 'concluido', 'concluído', 'check'] },
+      { emoji: '❌', keywords: ['errado', 'negado', 'recusado', 'cancelar'] },
+      { emoji: '⚠️', keywords: ['atencao', 'atenção', 'alerta', 'cuidado'] },
+      { emoji: '💰', keywords: ['dinheiro', 'valor', 'saco', 'grana', 'pagamento'] },
+      { emoji: '💵', keywords: ['dinheiro', 'nota', 'valor', 'pagamento'] },
+      { emoji: '💳', keywords: ['cartao', 'cartão', 'credito', 'crédito', 'pagamento'] },
+      { emoji: '🧾', keywords: ['recibo', 'nota', 'fiscal', 'comprovante'] },
+      { emoji: '📊', keywords: ['grafico', 'gráfico', 'relatorio', 'relatório', 'dados'] },
+      { emoji: '📈', keywords: ['grafico', 'gráfico', 'subindo', 'crescimento', 'alta'] },
+      { emoji: '📉', keywords: ['grafico', 'gráfico', 'caindo', 'queda', 'baixa'] },
+      { emoji: '🗓️', keywords: ['calendario', 'calendário', 'data', 'agenda', 'prazo'] },
+      { emoji: '⏰', keywords: ['relogio', 'relógio', 'hora', 'prazo', 'alarme'] },
+      { emoji: '📞', keywords: ['telefone', 'ligar', 'contato', 'chamada'] },
+      { emoji: '📱', keywords: ['celular', 'telefone', 'whatsapp', 'contato'] },
+      { emoji: '📧', keywords: ['email', 'e-mail', 'mensagem', 'contato'] },
+      { emoji: '📎', keywords: ['anexo', 'clipe', 'arquivo'] },
+      { emoji: '🔍', keywords: ['buscar', 'procurar', 'lupa', 'pesquisa', 'consulta'] },
+      { emoji: '🤖', keywords: ['robo', 'robô', 'bot', 'assistente', 'automatico', 'automático'] },
+      { emoji: '💬', keywords: ['mensagem', 'conversa', 'balao', 'balão', 'chat'] },
+    ],
+  },
+  {
+    name: 'Objetos',
+    entries: [
+      { emoji: '🎁', keywords: ['presente', 'brinde', 'surpresa'] },
+      { emoji: '🎉', keywords: ['festa', 'comemorar', 'parabens', 'parabéns'] },
+      { emoji: '🎊', keywords: ['festa', 'confete', 'comemorar'] },
+      { emoji: '🎂', keywords: ['bolo', 'aniversario', 'aniversário', 'festa'] },
+      { emoji: '💡', keywords: ['ideia', 'ideía', 'lampada', 'lâmpada', 'dica'] },
+      { emoji: '🔔', keywords: ['sino', 'aviso', 'notificacao', 'notificação', 'lembrete'] },
+      { emoji: '⭐', keywords: ['estrela', 'favorito', 'avaliacao', 'avaliação'] },
+      { emoji: '🔥', keywords: ['fogo', 'quente', 'destaque', 'top'] },
+      { emoji: '🚀', keywords: ['foguete', 'rapido', 'rápido', 'lancamento', 'lançamento'] },
+      { emoji: '💻', keywords: ['computador', 'notebook', 'trabalho'] },
+      { emoji: '📷', keywords: ['foto', 'camera', 'câmera', 'imagem'] },
+      { emoji: '🚗', keywords: ['carro', 'veiculo', 'veículo', 'automovel', 'automóvel'] },
+      { emoji: '✈️', keywords: ['aviao', 'avião', 'viagem', 'voo'] },
+    ],
+  },
+  {
+    name: 'Comida',
+    entries: [
+      { emoji: '🍔', keywords: ['hamburguer', 'hambúrguer', 'lanche', 'comida'] },
+      { emoji: '🍕', keywords: ['pizza', 'comida', 'lanche'] },
+      { emoji: '🍟', keywords: ['batata', 'frita', 'lanche'] },
+      { emoji: '🍿', keywords: ['pipoca', 'cinema', 'filme'] },
+      { emoji: '🍞', keywords: ['pao', 'pão', 'padaria'] },
+      { emoji: '🧀', keywords: ['queijo', 'comida'] },
+      { emoji: '🥗', keywords: ['salada', 'saudavel', 'saudável', 'comida'] },
+      { emoji: '☕', keywords: ['cafe', 'café', 'bebida', 'quente'] },
+      { emoji: '🍺', keywords: ['cerveja', 'bebida', 'chopp'] },
+      { emoji: '🍷', keywords: ['vinho', 'bebida', 'taca', 'taça'] },
+      { emoji: '🥂', keywords: ['brinde', 'comemorar', 'champanhe'] },
+      { emoji: '🥤', keywords: ['refrigerante', 'bebida', 'copo'] },
+    ],
+  },
+] as const
+
+/**
+ * Índice achatado: a busca ignora categoria, porque quem digita "casa" quer o resultado venha de
+ * onde vier. A ordem preserva a das categorias, então o resultado sai agrupado por afinidade sem
+ * precisar ordenar.
+ */
+const ALL_ENTRIES: readonly EmojiEntry[] = EMOJI_CATEGORIES.flatMap((category) => category.entries)
+
+function normalize(value: string): string {
+  return value
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '')
+    .trim()
+}
+
+/**
+ * Busca por prefixo de palavra-chave, não por substring: "ca" traz "casa" e "cartão", mas "sa" não
+ * traz "casa" — casar no meio da palavra devolvia resultado que ninguém consegue explicar.
+ */
+export function searchEmojis(query: string): readonly EmojiEntry[] {
+  const term = normalize(query)
+  if (!term) return ALL_ENTRIES
+
+  return ALL_ENTRIES.filter((entry) => entry.keywords.some((keyword) => normalize(keyword).startsWith(term)))
+}

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/useConversationActions.ts

@@ -0,0 +1,56 @@
+import { useMemo } from 'react'
+import { useConversations } from '../providers/ConversationsProvider'
+import type { ConversationTemplate } from '../providers/types'
+
+export interface UseConversationActionsResult {
+  /** `undefined` quando a API do host não implementa a operação — a UI esconde a afordância. */
+  takeover: (() => Promise<void>) | undefined
+  release: (() => Promise<void>) | undefined
+  finalize: (() => Promise<void>) | undefined
+}
+
+/**
+ * Ações de atendimento de UMA conversa, já ligadas ao id.
+ *
+ * Separado de `useConversationMessages` porque assumir e devolver conversa também acontece a
+ * partir da lista, onde nenhuma thread está aberta — embutir nas mensagens obrigaria a carregar
+ * a thread inteira só para desenhar um botão na linha.
+ */
+export function useConversationActions(conversationId: string): UseConversationActionsResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useConversationActions requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  return useMemo(
+    () => ({
+      takeover: api.takeover ? () => api.takeover!(conversationId) : undefined,
+      release: api.release ? () => api.release!(conversationId) : undefined,
+      finalize: api.finalize ? () => api.finalize!(conversationId) : undefined,
+    }),
+    [api, conversationId],
+  )
+}
+
+export interface UseInboxActionsResult {
+  markAllRead: (() => Promise<void>) | undefined
+  listTemplates: (() => Promise<ConversationTemplate[]>) | undefined
+}
+
+/** Ações que valem para a caixa inteira, sem conversa selecionada. */
+export function useInboxActions(): UseInboxActionsResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useInboxActions requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  return useMemo(
+    () => ({
+      markAllRead: api.markAllRead ? () => api.markAllRead!() : undefined,
+      listTemplates: api.listTemplates ? () => api.listTemplates!() : undefined,
+    }),
+    [api],
+  )
+}

package/src/hooks/useConversationDocuments.ts

@@ -1,21 +1,23 @@
 import { useConversations } from '../providers/ConversationsProvider'
 import { useAsyncResource } from './useAsyncResource'
-import type { ConversationDocument } from '../providers/types'
+import { documentsOf, totalOf } from '../lib/paginated'
+import type { ConversationDocument, ListDocumentsParams } from '../providers/types'
 
-export interface UseConversationDocumentsParams {
-  search?: string
-  page?: number
-}
+export type UseConversationDocumentsParams = ListDocumentsParams
 
 export interface UseConversationDocumentsResult {
   documents: ConversationDocument[]
+  /** Total no servidor. Cai para o tamanho da página quando a API devolve só o array. */
+  total: number
   loading: boolean
   error: Error | undefined
   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,9 +27,13 @@ export function useConversationDocuments(
   const { api } = context
 
   const { data, loading, error, refetch } = useAsyncResource(
-    () => api.getDocuments(conversationId, params),
-    [conversationId, params?.search, params?.page],
+    () => (conversationId ? api.getDocuments(conversationId, params) : Promise.resolve([])),
+    [conversationId, params?.search, params?.page, params?.limit, params?.source, params?.sortDirection],
   )
 
-  return { documents: data ?? [], loading, error, refetch }
+  if (data === undefined) {
+    return { documents: [], total: 0, loading, error, refetch }
+  }
+
+  return { documents: documentsOf(data), total: totalOf(data), loading, error, refetch }
 }