@adatechnology/conversations-ui 0.1.0-rc.8 → 0.1.0

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/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])
 }

package/src/hooks/useScrollToLatestMessage.ts

@@ -0,0 +1,127 @@
+import { useCallback, useLayoutEffect, useRef, useState, type RefObject, type UIEvent } from 'react'
+
+/**
+ * Mantém a conversa no fim, como todo mensageiro.
+ *
+ * Abrir uma conversa no topo do histórico é errado por um motivo simples: o que interessa ao
+ * atendente é a última mensagem, e ele teria que rolar por semanas de conversa para chegar nela.
+ *
+ * Existe no pacote, e não em cada host, porque a regra tem duas sutilezas que se descobre só
+ * errando — o salto instantâneo na troca de conversa e o respeito a quem rolou para trás — e
+ * reimplementá-las em cada inbox garante que uma delas fique de fora.
+ */
+
+/**
+ * Distância do fim, em pixels, dentro da qual ainda consideramos o operador "acompanhando".
+ *
+ * Não é zero porque o navegador arredonda `scrollTop` fracionário em telas com zoom ou densidade
+ * alta: exigir o fim exato faria o painel achar que o operador rolou para trás sem ele ter tocado
+ * em nada, e a próxima mensagem não apareceria.
+ */
+const NEAR_BOTTOM_THRESHOLD_PX = 120
+
+/**
+ * Toda rolagem aqui é `'auto'` — nunca `'smooth'`.
+ *
+ * Tentamos suave para mensagem nova e medimos: em ambiente onde a rolagem suave está desligada, o
+ * `scrollTo({ behavior: 'smooth' })` **não faz nada e não avisa** — a mensagem nova simplesmente não
+ * entra na vista. E não dá para detectar isso pelo `prefers-reduced-motion`: no navegador em que
+ * reproduzimos, a media query respondia `false` e o smooth continuava sendo no-op.
+ *
+ * Trocar uma animação cosmética por garantia de que o operador vê a mensagem é barato: seguir uma
+ * mensagem nova salta a altura de uma bolha, que é quase imperceptível de qualquer forma.
+ */
+const SCROLL_BEHAVIOR: ScrollBehavior = 'auto'
+
+export type UseScrollToLatestMessageParams = {
+  /** Troca de conversa. Muda ⇒ salto instantâneo para o fim. */
+  readonly conversationId: string | undefined
+  /** Quantidade de mensagens carregadas. Cresce ⇒ acompanha o fim, se o operador estiver lá. */
+  readonly messageCount: number
+}
+
+export type UseScrollToLatestMessageResult = {
+  /** Vai no elemento que rola — tipicamente o `ConversationWallpaper`. */
+  readonly containerRef: RefObject<HTMLDivElement | null>
+  /** Ligue no `onScroll` do mesmo elemento: é o que detecta o operador lendo o histórico. */
+  readonly handleScroll: (event: UIEvent<HTMLDivElement>) => void
+  /** `true` quando o operador rolou para trás — serve a um botão "ir para a última". */
+  readonly isAwayFromBottom: boolean
+  readonly scrollToBottom: (behavior?: ScrollBehavior) => void
+}
+
+export function useScrollToLatestMessage({
+  conversationId,
+  messageCount,
+}: UseScrollToLatestMessageParams): UseScrollToLatestMessageResult {
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const [isAwayFromBottom, setIsAwayFromBottom] = useState(false)
+
+  /**
+   * Espelha `isAwayFromBottom` para o efeito de mensagens novas ler o valor atual sem depender dele.
+   *
+   * Se o efeito dependesse do estado, cada rolagem do operador o re-disparava e o puxava de volta
+   * para o fim — exatamente o que a checagem existe para evitar.
+   */
+  const isAwayFromBottomRef = useRef(false)
+
+  const scrollToBottom = useCallback((behavior: ScrollBehavior = SCROLL_BEHAVIOR) => {
+    const container = containerRef.current
+    if (!container) return
+    container.scrollTo({ top: container.scrollHeight, behavior })
+  }, [])
+
+  const handleScroll = useCallback((event: UIEvent<HTMLDivElement>) => {
+    const target = event.currentTarget
+    const distanceFromBottom = target.scrollHeight - target.scrollTop - target.clientHeight
+    const away = distanceFromBottom > NEAR_BOTTOM_THRESHOLD_PX
+
+    isAwayFromBottomRef.current = away
+    setIsAwayFromBottom((current) => (current === away ? current : away))
+  }, [])
+
+  /**
+   * Qual conversa já recebeu o salto de abertura.
+   *
+   * É o que separa "abriu a conversa" de "chegou mensagem", e não dá para usar só `conversationId`
+   * num efeito próprio: quando a conversa troca, a lista de mensagens ainda está vazia, então um
+   * salto ali rola um container sem conteúdo e não faz nada. O salto real precisa esperar a primeira
+   * leva de mensagens — e foi exatamente isso que deixou a conversa abrindo no topo.
+   */
+  const jumpedForConversationRef = useRef<string | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    const isNewConversation = jumpedForConversationRef.current !== conversationId
+
+    if (isNewConversation) {
+      // Zera antes de qualquer coisa: "rolado para trás" da conversa anterior não pode bloquear o
+      // salto de abertura desta.
+      isAwayFromBottomRef.current = false
+      setIsAwayFromBottom(false)
+
+      // Sem mensagens ainda — o salto acontece quando a primeira leva chegar.
+      if (messageCount === 0) return
+
+      jumpedForConversationRef.current = conversationId
+      /**
+       * `'auto'`, sempre. Animar a rolagem por meses de histórico demora, mostra um borrão de
+       * mensagens antigas que ninguém pediu, e some por completo onde a rolagem suave está desligada
+       * (`prefers-reduced-motion`, alguns navegadores automatizados) — a conversa simplesmente
+       * abriria no topo. Abertura é salto, não animação.
+       */
+      scrollToBottom(SCROLL_BEHAVIOR)
+      return
+    }
+
+    /**
+     * Mensagem nova: acompanha, mas só se o operador já estava no fim.
+     *
+     * Puxar a rolagem de quem está lendo o histórico é pior do que não mostrar a mensagem — ele perde
+     * a posição e não sabe por quê. Quem rolou para trás recebe `isAwayFromBottom` e decide.
+     */
+    if (isAwayFromBottomRef.current) return
+    scrollToBottom(SCROLL_BEHAVIOR)
+  }, [conversationId, messageCount, scrollToBottom])
+
+  return { containerRef, handleScroll, isAwayFromBottom, scrollToBottom }
+}