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

package/src/flows/labels.ts

@@ -3,6 +3,7 @@ import type { FlowConditionOperator, FlowNodeType, FlowQuestionType } from './fl
 export interface FlowEditorLabels {
   legend: Record<FlowNodeType, string>
   startNodeTooltip: string
+  detachedNodeTooltip: string
   liveCountTooltip: (count: number) => string
   edgeFallbackLabel: string
   // Rótulo por `actionKind` — o host estende esse mapa para registrar seus próprios kinds
@@ -13,10 +14,15 @@ export interface FlowEditorLabels {
   nodePanel: {
     title: string
     contextKey: string
+    nodeName: string
+    nodeNamePlaceholder: string
+    nodeNameHint: string
     questionType: string
     question: string
     options: string
     addOption: string
+    removeOption: string
+    close: string
     optionId: string
     optionLabel: string
     next: string
@@ -47,6 +53,27 @@ export interface FlowEditorLabels {
     conditionTrue: string
     conditionFalse: string
     conditionVariableMissing: string
+    media: string
+    mediaUnavailable: string
+  }
+  quickAdd: {
+    fromHandle: string
+    title: string
+    disconnect: string
+  }
+  /** Legenda do canvas: o que cada traço e cada contorno querem dizer. */
+  legendPanel: {
+    title: string
+    nodes: string
+    connections: string
+    linear: string
+    branch: string
+    fallback: string
+    crossFlow: string
+    live: string
+    selfLoop: string
+    detached: string
+    startNode: string
   }
   palette: {
     title: string
@@ -59,6 +86,8 @@ export interface FlowEditorLabels {
   flowMap: {
     nodeCount: (count: number) => string
     openFlow: string
+    toggleToMap: string
+    toggleToDetail: string
   }
   flowGroup: {
     focus: string
@@ -68,6 +97,67 @@ export interface FlowEditorLabels {
     tooltip: string
     goesTo: (label: string) => string
   }
+  collectionChain: {
+    feeds: (label: string) => string
+  }
+  /**
+   * Texto dos problemas encontrados por `validateGraph`. Vive aqui, e não no host, porque a tela
+   * composta é quem valida — deixar de fora obrigaria todo produto a repassar o mesmo mapa de
+   * funções só para a barra de erros aparecer.
+   */
+  validation: FlowValidationLabels
+  /** Barra de cima, estados de carregamento e ações do editor inteiro. */
+  workspace: {
+    title: string
+    subtitle: string
+    loading: string
+    loadError: string
+    saveGraph: string
+    saving: string
+    saveSuccess: string
+    saveError: string
+    organize: string
+    organizeTooltip: string
+    discardChanges: string
+    discardTooltip: string
+    discardConfirm: string
+    unsavedChangesConfirm: string
+  }
+  flowManager: {
+    newFlow: string
+    createTitle: string
+    key: string
+    keyHint: string
+    keyInvalid: string
+    label: string
+    showInMenu: string
+    menuOptionLabel: string
+    create: string
+    creating: string
+    deleteFlow: string
+    deleteConfirm: (label: string) => string
+    createError: string
+    deleteError: string
+  }
+}
+
+export interface FlowValidationLabels {
+  title: string
+  errors: (count: number) => string
+  warnings: (count: number) => string
+  noStart: string
+  brokenRef: (from: string, to: string) => string
+  choiceWithoutOptions: (id: string) => string
+  duplicatedOptionId: (id: string, optionId: string) => string
+  optionWithoutTarget: (id: string, optionLabel: string) => string
+  tooManyOptions: (id: string, count: number) => string
+  buttonTitleTooLong: (id: string, label: string) => string
+  listTitleTooLong: (id: string, label: string) => string
+  bodyTooLong: (id: string) => string
+  unreachable: (id: string) => string
+  deadEndQuestion: (id: string) => string
+  conditionIncomplete: (id: string) => string
+  conditionBranchMissing: (id: string, branch: string) => string
 }
 
 // Paridade de texto com financiamento-imobiliario-bot/apps/web/src/locales/modules/flows.ts —
@@ -81,12 +171,14 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     condition: 'Condição',
   },
   startNodeTooltip: 'Início do fluxo',
+  detachedNodeTooltip: 'Sem ligação de entrada — o bot não chega neste nó. Puxe um fio de outro card até ele.',
   liveCountTooltip: (count) => `${count} conversa(s) ativa(s) aqui agora`,
   edgeFallbackLabel: 'outro',
   actionKindLabels: {
     handoff: 'Encaminhar para atendimento',
     rate_limited_handoff: 'Encaminhar (limite de simulações atingido)',
     send_product_list: 'Enviar catálogo de produtos',
+    send_media: 'Enviar arquivos da biblioteca',
   },
   conditionOperatorLabels: {
     '>': 'maior que',
@@ -108,10 +200,15 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
   nodePanel: {
     title: 'Editar nó',
     contextKey: 'Chave (contexto)',
+    nodeName: 'Nome do nó (opcional)',
+    nodeNamePlaceholder: 'Ex.: Enviar tabela de preços',
+    nodeNameHint: 'Só aparece no editor — o cliente não vê.',
     questionType: 'Tipo de resposta',
     question: 'Texto da pergunta',
     options: 'Opções (choice)',
     addOption: 'Adicionar opção',
+    removeOption: 'Remover opção',
+    close: 'Fechar painel',
     optionId: 'Valor',
     optionLabel: 'Texto exibido',
     next: 'Próximo nó',
@@ -143,6 +240,26 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     conditionTrue: 'Se verdadeiro →',
     conditionFalse: 'Se falso →',
     conditionVariableMissing: 'Se a variável ainda não foi coletada →',
+    media: 'Arquivos enviados neste ponto',
+    mediaUnavailable: 'A biblioteca de arquivos não está disponível neste painel.',
+  },
+  quickAdd: {
+    fromHandle: 'Criar o próximo nó já ligado aqui',
+    title: 'Ligar em um nó novo',
+    disconnect: 'Desligar este fio (o nó continua no fluxo)',
+  },
+  legendPanel: {
+    title: 'Legenda',
+    nodes: 'Cards',
+    connections: 'Ligações',
+    linear: 'Segue direto para o próximo',
+    branch: 'Caminho de uma opção escolhida',
+    fallback: 'Quando a resposta não casa com nenhuma opção',
+    crossFlow: 'Salta para outro fluxo',
+    live: 'Tem conversa passando por aqui agora',
+    selfLoop: 'Volta ao mesmo card — repete a pergunta',
+    detached: 'Ninguém aponta para este card: o bot não chega nele',
+    startNode: 'Onde o fluxo começa',
   },
   palette: {
     title: 'Adicionar ao fluxo',
@@ -155,6 +272,8 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
   flowMap: {
     nodeCount: (count) => `${count} nó(s)`,
     openFlow: 'Abrir fluxo',
+    toggleToMap: 'Mapa de fluxos',
+    toggleToDetail: 'Voltar ao editor',
   },
   flowGroup: {
     focus: 'Focar neste fluxo',
@@ -164,6 +283,61 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     tooltip: 'Clique para abrir esse fluxo aqui do lado, ligado ao ponto de onde ele é chamado',
     goesTo: (label) => `↪ Vai para: ${label}`,
   },
+  collectionChain: {
+    feeds: (label) => `Alimenta: ${label}`,
+  },
+  validation: {
+    title: 'Antes de publicar',
+    errors: (count) => `${count} erro(s) — corrija antes de salvar`,
+    warnings: (count) => `${count} aviso(s)`,
+    noStart: 'O fluxo precisa de um nó inicial válido.',
+    brokenRef: (from, to) => `Nó "${from}": ligação aponta para "${to}", que não existe.`,
+    choiceWithoutOptions: (id) => `Nó "${id}": escolha sem nenhuma opção.`,
+    duplicatedOptionId: (id, optionId) => `Nó "${id}": valor de opção "${optionId}" duplicado.`,
+    optionWithoutTarget: (id, label) => `Nó "${id}": opção "${label}" não tem destino definido.`,
+    tooManyOptions: (id, count) => `Nó "${id}": ${count} opções — o WhatsApp aceita no máximo 10 em lista.`,
+    buttonTitleTooLong: (id, label) => `Nó "${id}": botão "${label}" passa de 20 caracteres.`,
+    listTitleTooLong: (id, label) => `Nó "${id}": item de lista "${label}" passa de 24 caracteres.`,
+    bodyTooLong: (id) => `Nó "${id}": texto passa de 1024 caracteres.`,
+    unreachable: (id) => `Nó "${id}" é inalcançável a partir do início do fluxo.`,
+    deadEndQuestion: (id) => `Nó "${id}": pergunta sem próximo passo definido.`,
+    conditionIncomplete: (id) => `Nó "${id}": condição incompleta — defina variável, operador e valor.`,
+    conditionBranchMissing: (id, branch) =>
+      `Nó "${id}": ramo "${branch === 'true' ? 'Verdadeiro' : 'Falso'}" sem destino definido.`,
+  },
+  workspace: {
+    title: 'Fluxos do Bot',
+    subtitle: 'Blueprint visual dos fluxos de conversa, sincronizado com o que está em produção.',
+    loading: 'Carregando fluxos…',
+    loadError: 'Não foi possível carregar os fluxos.',
+    saveGraph: 'Publicar alterações',
+    saving: 'Publicando…',
+    saveSuccess: 'Fluxo publicado! O bot já está usando a versão nova.',
+    saveError: 'Não foi possível salvar — verifique se todos os destinos apontam para nós existentes.',
+    organize: 'Organizar',
+    organizeTooltip: 'Reorganiza os nós automaticamente e salva as novas posições',
+    discardChanges: 'Desfazer alterações',
+    discardTooltip: 'Devolve os fluxos abertos ao que está publicado, descartando o que não foi salvo',
+    discardConfirm: 'Descartar todas as alterações não publicadas e voltar ao fluxo que está no ar?',
+    unsavedChangesConfirm:
+      'Você tem alterações não publicadas neste fluxo. Trocar de fluxo agora descarta essas edições. Continuar?',
+  },
+  flowManager: {
+    newFlow: 'Novo fluxo',
+    createTitle: 'Criar novo fluxo',
+    key: 'Identificador único',
+    keyHint: 'letras minúsculas, números e _ (ex.: promocoes_semana)',
+    keyInvalid: 'Use apenas letras minúsculas, números e _ (2 a 40 caracteres)',
+    label: 'Nome exibido',
+    showInMenu: 'Exibir como opção no menu principal do bot',
+    menuOptionLabel: 'Texto da opção no menu',
+    create: 'Criar fluxo',
+    creating: 'Criando…',
+    deleteFlow: 'Excluir fluxo',
+    deleteConfirm: (label) => `Excluir o fluxo "${label}"? Esta ação não pode ser desfeita.`,
+    createError: 'Não foi possível criar o fluxo.',
+    deleteError: 'Não foi possível excluir o fluxo.',
+  },
 }
 
 export function mergeFlowEditorLabels(override?: Partial<FlowEditorLabels>): FlowEditorLabels {
@@ -179,9 +353,15 @@ export function mergeFlowEditorLabels(override?: Partial<FlowEditorLabels>): Flo
     },
     questionTypeLabels: { ...DEFAULT_FLOW_EDITOR_LABELS.questionTypeLabels, ...override.questionTypeLabels },
     nodePanel: { ...DEFAULT_FLOW_EDITOR_LABELS.nodePanel, ...override.nodePanel },
+    quickAdd: { ...DEFAULT_FLOW_EDITOR_LABELS.quickAdd, ...override.quickAdd },
+    legendPanel: { ...DEFAULT_FLOW_EDITOR_LABELS.legendPanel, ...override.legendPanel },
     palette: { ...DEFAULT_FLOW_EDITOR_LABELS.palette, ...override.palette },
     flowMap: { ...DEFAULT_FLOW_EDITOR_LABELS.flowMap, ...override.flowMap },
     flowGroup: { ...DEFAULT_FLOW_EDITOR_LABELS.flowGroup, ...override.flowGroup },
     crossFlowPortal: { ...DEFAULT_FLOW_EDITOR_LABELS.crossFlowPortal, ...override.crossFlowPortal },
+    collectionChain: { ...DEFAULT_FLOW_EDITOR_LABELS.collectionChain, ...override.collectionChain },
+    validation: { ...DEFAULT_FLOW_EDITOR_LABELS.validation, ...override.validation },
+    workspace: { ...DEFAULT_FLOW_EDITOR_LABELS.workspace, ...override.workspace },
+    flowManager: { ...DEFAULT_FLOW_EDITOR_LABELS.flowManager, ...override.flowManager },
   }
 }

package/src/flows/workspaceContract.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * O subpath `/flows` precisa exportar a TELA, não só as peças.
+ *
+ * Existe porque a ausência disso já custou: exportando apenas `FlowMapCanvas`, `FlowPalette` e
+ * `FlowNodePanel`, o financiamento montou a tela por conta — 973 linhas de página mais um fork local
+ * dos componentes, que ficou atrás do pacote. O quickcart, para ter a mesma tela, teria que copiar o
+ * arquivo. É exatamente a divergência que `pluggable-module.md` §4 proíbe.
+ *
+ * O teste é de superfície, não de comportamento: não prova que o canvas desenha certo, prova que
+ * existe UM lugar onde a tela mora, e que ela aceita customização por contrato em vez de por fork.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import * as flows from './index'
+import { DEFAULT_FLOW_EDITOR_LABELS, mergeFlowEditorLabels } from './labels'
+
+const WORKSPACE_SOURCE = `${import.meta.dir}/FlowsWorkspace.tsx`
+
+describe('superfície composta', () => {
+  it('exporta a tela inteira', () => {
+    expect(typeof flows.FlowsWorkspace).toBe('function')
+  })
+
+  it('exporta as peças também — quem precisa de layout próprio não fica sem saída', () => {
+    // Workspace é o caminho recomendado, não uma prisão: um produto com layout radicalmente
+    // diferente compõe as peças, e isso é melhor que forkar o pacote.
+    for (const piece of ['FlowMapCanvas', 'FlowPalette', 'FlowNodePanel', 'FlowWhatsAppPreview']) {
+      expect(typeof (flows as Record<string, unknown>)[piece], piece).toBe('function')
+    }
+  })
+
+  it('as operações de grafo saem puras, sem passar pela tela', () => {
+    // São as que a tela consome de verdade (ver os imports em `FlowsWorkspace.tsx`). Exportá-las sem
+    // usá-las seria pior que não ter teste: teste verde sobre código que não roda em produção.
+    for (const operation of ['resolveConnection', 'applyConnection', 'removeNodeAndCleanRefs', 'mergedFlowKeysFrom']) {
+      expect(typeof (flows as Record<string, unknown>)[operation], operation).toBe('function')
+    }
+  })
+})
+
+describe('contrato de customização', () => {
+  it('nenhuma capacidade em forma de flag booleana `hasX`', async () => {
+    /**
+     * Capacidade opcional é por AUSÊNCIA de prop. `hasDelete` seria um segundo jeito de dizer o que
+     * `deletableFlowKeys` já diz, e dois jeitos divergem — alguém liga a flag sem a lista e a tela
+     * desenha um botão que não exclui nada.
+     */
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).not.toMatch(/readonly has[A-Z]/)
+  })
+
+  it('aceita labels, className e os slots de render', async () => {
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).toContain('labels?: Partial<')
+    // `className` é o que deixa o produto posicionar a tela no layout dele sem tocar no pacote.
+    expect(content).toContain('className?: string')
+    expect(content).toContain('renderMediaPicker?:')
+  })
+
+  it('nenhum texto visível escrito no componente — tudo passa por labels', async () => {
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+    /**
+     * Texto entre tags JSX que não seja `{...}`, que é o que `web.md` §6 proíbe.
+     *
+     * O `\s*` nas pontas não é detalhe: a primeira versão deste regex no notification-ui exigia o
+     * texto colado nas tags, e o Prettier põe o conteúdo em linha própria — o teste passava com
+     * `>\n  Configurações\n<` no meio do componente, provando nada.
+     */
+    const hardcoded = content.match(/>\s*[A-Za-zÀ-ÿ][A-Za-zÀ-ÿ ]{3,}\s*</g)
+
+    expect(hardcoded, `texto fixo: ${hardcoded?.join(' | ')}`).toBeNull()
+  })
+
+  it('o produto sobrescreve UM texto sem perder os outros do mesmo grupo', () => {
+    const merged = mergeFlowEditorLabels({ workspace: { ...DEFAULT_FLOW_EDITOR_LABELS.workspace, title: 'Jornadas' } })
+
+    expect(merged.workspace.title).toBe('Jornadas')
+    expect(merged.workspace.saveGraph).toBe(DEFAULT_FLOW_EDITOR_LABELS.workspace.saveGraph)
+  })
+
+  it('grupo novo de label entra no merge profundo', () => {
+    // Esquecer o grupo no `mergeFlowEditorLabels` deixa o override apagar os irmãos dele, e o
+    // sintoma é texto sumindo da tela — não erro.
+    for (const group of ['workspace', 'flowManager', 'validation', 'collectionChain'] as const) {
+      const merged = mergeFlowEditorLabels({ [group]: {} })
+
+      expect(Object.keys(merged[group]).length, group).toBe(Object.keys(DEFAULT_FLOW_EDITOR_LABELS[group]).length)
+    }
+  })
+})
+
+describe('focar um fluxo leva a câmera até ele', () => {
+  /**
+   * `focusFlow` trocava o fluxo primário e remesclava o canvas, mas nunca movia a viewport: a aba
+   * acendia, a tela continuava onde estava e o fluxo escolhido ficava fora do campo de visão — em
+   * "Consórcio", parado no início com o fluxo lá embaixo, clicar parecia não fazer nada.
+   *
+   * Teste de fonte, como os demais deste arquivo: não prova o enquadramento na tela, prova que o
+   * clique pede o enquadramento e que ele é restrito ao fluxo clicado.
+   */
+  it('focar um fluxo agenda o enquadramento dele', async () => {
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).toContain('setPendingFocusFlowKey(key)')
+  })
+
+  it('enquadra apenas os cards do fluxo focado, não o canvas inteiro', async () => {
+    // O canvas mostra o fecho transitivo inteiro. Um `fitView()` sem `nodes` devolveria a mesma
+    // visão de sempre — que é exatamente o defeito relatado.
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).toMatch(/fitView\(\{[\s\S]*?nodes: flowNodes\.map/)
+    expect(content).toMatch(/flowKey === pendingFocusFlowKey/)
+  })
+
+  it('limita o zoom, para um fluxo de dois nós não encher a tela', async () => {
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).toContain('maxZoom: FOCUS_MAX_ZOOM')
+  })
+})

package/src/hooks/useContainerWidth.ts

@@ -0,0 +1,35 @@
+/**
+ * Largura do próprio elemento, para decidir layout pelo espaço que ele tem — e não pelo tamanho da
+ * janela.
+ *
+ * Os breakpoints do Tailwind (`sm:`, `lg:`) leem a janela, e é aí que erram nestas telas: abrir a
+ * prévia do simulador, ou a lista de conversas ao lado, estreita a coluna sem a janela mudar de
+ * tamanho. O layout continua achando que está no desktop e espreme o conteúdo flexível — o campo de
+ * texto do composer e o nome do cliente no cabeçalho — para caber os botões, que não cedem.
+ *
+ * `undefined` enquanto não mediu (SSR e teste de markup incluídos): quem consome trata ausência de
+ * medida como espaçoso, que é o layout completo.
+ */
+
+import { useEffect, useState, type RefObject } from 'react'
+
+export function useContainerWidth(ref: RefObject<HTMLElement | null>): number | undefined {
+  const [width, setWidth] = useState<number | undefined>(undefined)
+
+  useEffect(() => {
+    const element = ref.current
+    if (!element || typeof ResizeObserver === 'undefined') return
+
+    // Sempre a mesma medida nos dois caminhos: o `contentRect` do observer desconta o padding e o
+    // `getBoundingClientRect` não. Misturar os dois desloca o limiar pela largura do padding — no
+    // cabeçalho, 32px — e o layout decide uma coisa ao montar e outra ao redimensionar.
+    const measure = () => setWidth(element.getBoundingClientRect().width)
+
+    measure()
+    const observer = new ResizeObserver(measure)
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [ref])
+
+  return width
+}

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,14 +1,14 @@
 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>
@@ -28,8 +28,12 @@ export function useConversationDocuments(
 
   const { data, loading, error, refetch } = useAsyncResource(
     () => (conversationId ? api.getDocuments(conversationId, params) : Promise.resolve([])),
-    [conversationId, params?.search, params?.page],
+    [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 }
 }

package/src/hooks/useConversationList.ts

@@ -1,16 +1,14 @@
 import { useConversations } from '../providers/ConversationsProvider'
 import { useAsyncResource } from './useAsyncResource'
-import type { ConversationSummary } from '../providers/types'
+import { conversationsOf, totalOf } from '../lib/paginated'
+import type { ConversationSummary, ListConversationsParams } from '../providers/types'
 
-export interface UseConversationListParams {
-  page?: number
-  limit?: number
-  waitingHuman?: boolean
-  search?: string
-}
+export type UseConversationListParams = ListConversationsParams
 
 export interface UseConversationListResult {
   conversations: ConversationSummary[]
+  /** 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>
@@ -23,10 +21,18 @@ export function useConversationList(params?: UseConversationListParams): UseConv
   }
   const { api } = context
 
+  // `filters` é objeto novo a cada render do host; serializar evita refetch em laço sem obrigar
+  // o consumidor a memoizar — omissão que só apareceria como loop de rede em produção.
+  const filtersKey = JSON.stringify(params?.filters ?? {})
+
   const { data, loading, error, refetch } = useAsyncResource(
     () => api.fetchConversations(params),
-    [params?.page, params?.limit, params?.waitingHuman, params?.search],
+    [params?.page, params?.limit, params?.waitingHuman, params?.search, filtersKey],
   )
 
-  return { conversations: data ?? [], loading, error, refetch }
+  if (data === undefined) {
+    return { conversations: [], total: 0, loading, error, refetch }
+  }
+
+  return { conversations: conversationsOf(data), total: totalOf(data), loading, error, refetch }
 }

package/src/hooks/useConversationMessages.ts

@@ -10,7 +10,7 @@ export interface UseConversationMessagesResult {
   refetch: () => Promise<void>
   sendMessage: (text: string) => Promise<MessagePayload>
   sendMedia: (data: { base64: string; mimeType: string; filename: string; caption?: string }) => Promise<MessagePayload>
-  sendTemplate: (data: { templateName: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
+  sendTemplate: (data: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
   markRead: () => Promise<void>
 }
 
@@ -51,7 +51,7 @@ export function useConversationMessages(
   )
 
   const sendTemplate = useCallback(
-    async (templateData: { templateName: string; languageCode?: string; bodyParams?: string[] }) => {
+    async (templateData: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => {
       await api.sendTemplate(conversationId, templateData)
       await refetch()
     },

package/src/hooks/useConversationRealtime.ts

@@ -10,14 +10,16 @@ export function useConversationRealtime(
   conversationId: string | undefined,
   onEvent: ConversationRealtimeHandler,
 ): void {
-  const context = useConversations()
+  const sse = useConversations()?.sse
   const onEventRef = useRef(onEvent)
   onEventRef.current = onEvent
 
+  // Depende da porta SSE, não do objeto de contexto inteiro: reabrir o stream é caro (um ticket por
+  // abertura) e o contexto é o que mais muda de identidade quando o host renderiza.
   useEffect(() => {
-    if (!context || !conversationId) return
+    if (!sse || !conversationId) return
 
-    const source = context.sse.connectConversationStream(conversationId)
+    const source = sse.connectConversationStream(conversationId)
     const handler = (event: MessageEvent) => onEventRef.current(event)
     source.addEventListener('message', handler)
 
@@ -25,20 +27,20 @@ export function useConversationRealtime(
       source.removeEventListener('message', handler)
       source.close()
     }
-  }, [context, conversationId])
+  }, [sse, conversationId])
 }
 
 // Assina o stream global (ex: novas conversas entrando na fila, notificações cross-conversa)
 // — mesma porta SSEProvider, sem conversationId.
 export function useGlobalRealtime(onEvent: ConversationRealtimeHandler): void {
-  const context = useConversations()
+  const sse = useConversations()?.sse
   const onEventRef = useRef(onEvent)
   onEventRef.current = onEvent
 
   useEffect(() => {
-    if (!context) return
+    if (!sse) return
 
-    const source = context.sse.connectGlobalStream()
+    const source = sse.connectGlobalStream()
     const handler = (event: MessageEvent) => onEventRef.current(event)
     source.addEventListener('message', handler)
 
@@ -46,5 +48,5 @@ export function useGlobalRealtime(onEvent: ConversationRealtimeHandler): void {
       source.removeEventListener('message', handler)
       source.close()
     }
-  }, [context])
+  }, [sse])
 }