@adatechnology/conversations-ui 0.1.0-rc.3 → 0.1.0-rc.30

package/src/AudioRecorderButton.tsx

@@ -0,0 +1,248 @@
+/**
+ * Gravação de áudio no simulador, pelo microfone do próprio navegador.
+ *
+ * Existe porque áudio é o formato que mais chega de cliente real e o que mais quebra fluxo: sem
+ * poder gravar aqui, testar o caminho de transcrição exigia mandar mensagem do celular de alguém.
+ *
+ * O arquivo gravado sai daqui como `File` e segue exatamente o mesmo caminho de um anexo — quem
+ * hospeda e devolve o `mediaId` é o host, via `uploadMedia`.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { AudioPlayer } from './AudioPlayer'
+
+export interface AudioRecorderButtonLabels {
+  start: string
+  stop: string
+  unsupported: string
+  denied: string
+  review: string
+  send: string
+  discard: string
+  empty: string
+}
+
+export const DEFAULT_AUDIO_RECORDER_BUTTON_LABELS: AudioRecorderButtonLabels = {
+  start: 'Gravar áudio',
+  stop: 'Parar gravação',
+  unsupported: 'Este navegador não grava áudio.',
+  denied: 'Sem permissão para usar o microfone.',
+  review: 'Ouça antes de enviar',
+  send: 'Enviar áudio',
+  discard: 'Descartar áudio',
+  empty: 'Nada foi captado pelo microfone.',
+}
+
+export interface AudioRecorderButtonProps {
+  onRecorded: (file: File) => void | Promise<void>
+  onFailure?: (message: string) => void
+  /**
+   * Avisa quando a gravação começa e termina. O botão é um interruptor — o segundo toque é que
+   * envia — e sem um aviso fora dele o operador grava, não vê nada acontecer e desiste achando
+   * que o microfone está quebrado.
+   */
+  onRecordingChange?: (isRecording: boolean) => void
+  /**
+   * Abre uma etapa de revisão quando a gravação para: o áudio toca ali mesmo e só sai depois de
+   * confirmado. Ligado por padrão — voz é o único anexo que quem envia não viu antes de mandar, e
+   * sem ouvir não há como saber se o microfone captou alguma coisa. Desligar volta ao envio direto.
+   */
+  reviewBeforeSend?: boolean
+  /**
+   * Teto de duração da gravação, em milissegundos. Passado o tempo, o gravador para e envia o que
+   * tem. Produto com limite próprio sobrescreve.
+   */
+  maxDurationMilliseconds?: number
+  labels?: Partial<AudioRecorderButtonLabels>
+  disabled?: boolean
+}
+
+/**
+ * Cinco minutos: com o codec de voz do WhatsApp isso dá menos de 3MB, folgado dentro do teto de
+ * 16MB que a Meta impõe a áudio, e é mais do que qualquer recado de cliente. O corte automático
+ * existe porque gravação esquecida aberta só se descobre no envio, com o arquivo inteiro perdido.
+ */
+export const DEFAULT_MAX_RECORDING_MILLISECONDS = 5 * 60 * 1000
+
+/**
+ * Ordem de preferência de formato: os dois primeiros o WhatsApp aceita como áudio; `webm` é só
+ * saída de emergência para navegador que não grava mais nada — gravar em webm e descobrir na hora
+ * do envio que o formato é inválido é pior do que gravar já no formato certo.
+ */
+const RECORDING_FORMATS = [
+  { mimeType: 'audio/ogg;codecs=opus', uploadMimeType: 'audio/ogg', extension: 'ogg' },
+  { mimeType: 'audio/mp4', uploadMimeType: 'audio/mp4', extension: 'm4a' },
+  { mimeType: 'audio/webm', uploadMimeType: 'audio/webm', extension: 'webm' },
+] as const
+
+export type RecordingFormat = (typeof RECORDING_FORMATS)[number]
+
+/** Primeiro formato que o navegador sabe gravar, ou `undefined` se não souber gravar nenhum. */
+export function resolveRecordingFormat(): RecordingFormat | undefined {
+  if (typeof MediaRecorder === 'undefined') return undefined
+  // `isTypeSupported` não existe em toda implementação; onde falta, o primeiro da lista é o palpite.
+  if (typeof MediaRecorder.isTypeSupported !== 'function') return RECORDING_FORMATS[0]
+  return RECORDING_FORMATS.find((format) => MediaRecorder.isTypeSupported(format.mimeType))
+}
+
+type PendingRecording = { file: File; objectURL: string }
+
+export function AudioRecorderButton({
+  onRecorded,
+  onFailure,
+  onRecordingChange,
+  reviewBeforeSend = true,
+  maxDurationMilliseconds = DEFAULT_MAX_RECORDING_MILLISECONDS,
+  labels,
+  disabled,
+}: AudioRecorderButtonProps) {
+  const labelOf = (key: keyof AudioRecorderButtonLabels): string =>
+    labels?.[key] ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS[key]
+  const [isRecording, setIsRecording] = useState(false)
+  const [pending, setPending] = useState<PendingRecording | undefined>(undefined)
+  const recorderRef = useRef<MediaRecorder | null>(null)
+  const autoStopRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  // O `objectURL` é um recurso do documento, não do React: sem revogar, cada gravação descartada
+  // deixa o blob inteiro preso na memória da aba até um reload.
+  const discard = useCallback(() => {
+    setPending((current) => {
+      if (current) URL.revokeObjectURL(current.objectURL)
+      return undefined
+    })
+  }, [])
+
+  useEffect(() => discard, [discard])
+
+  const confirm = useCallback(() => {
+    if (!pending) return
+    void onRecorded(pending.file)
+    discard()
+  }, [discard, onRecorded, pending])
+
+  const stop = useCallback(() => {
+    recorderRef.current?.stop()
+  }, [])
+
+  const start = useCallback(async () => {
+    const format = resolveRecordingFormat()
+    if (!format || !navigator.mediaDevices?.getUserMedia) {
+      onFailure?.(labels?.unsupported ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.unsupported)
+      return
+    }
+
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+      const recorder = new MediaRecorder(stream, { mimeType: format.mimeType })
+      const chunks: Blob[] = []
+
+      recorder.addEventListener('dataavailable', (event) => {
+        if (event.data.size > 0) chunks.push(event.data)
+      })
+      recorder.addEventListener('stop', () => {
+        // Solta o microfone assim que para: sem isto o indicador de gravação do navegador fica
+        // aceso depois do envio, e o operador acha que o simulador continua ouvindo.
+        stream.getTracks().forEach((track) => track.stop())
+        clearTimeout(autoStopRef.current)
+        setIsRecording(false)
+        onRecordingChange?.(false)
+        recorderRef.current = null
+        // O `File` sai com o MIME sem os parâmetros de codec: `audio/ogg;codecs=opus` serve ao
+        // gravador, mas quem valida upload compara com `audio/ogg` puro.
+        const blob = new Blob(chunks, { type: format.uploadMimeType })
+        const file = new File([blob], `audio-${Date.now()}.${format.extension}`, {
+          type: format.uploadMimeType,
+        })
+
+        // Gravação vazia não vira anexo: microfone mudo ou permissão revogada no meio produzem um
+        // blob de zero byte, e mandá-lo adiante só falha lá na frente, sem dizer por quê.
+        if (blob.size === 0) {
+          onFailure?.(labelOf('empty'))
+          return
+        }
+
+        if (!reviewBeforeSend) {
+          void onRecorded(file)
+          return
+        }
+
+        setPending({ file, objectURL: URL.createObjectURL(blob) })
+      })
+
+      recorderRef.current = recorder
+      recorder.start()
+      autoStopRef.current = setTimeout(() => recorder.stop(), maxDurationMilliseconds)
+      setIsRecording(true)
+      onRecordingChange?.(true)
+    } catch {
+      onFailure?.(labels?.denied ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.denied)
+    }
+    // `labelOf` lê `labels` a cada render e não entra aqui; o que importa para recriar o gravador
+    // são o teto de duração, o destino da gravação e se há etapa de revisão.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [maxDurationMilliseconds, onFailure, onRecorded, onRecordingChange, reviewBeforeSend])
+
+  const toggleLabel = isRecording ? labelOf('stop') : labelOf('start')
+
+  return (
+    /* O painel de revisão flutua sobre o botão em vez de ocupar espaço na barra: o microfone mora
+       na caixa do botão de enviar, e empurrar o composer para cima a cada gravação faria a
+       conversa saltar. */
+    <div className="relative flex-shrink-0">
+      {pending && (
+        <div
+          role="group"
+          aria-label={labelOf('review')}
+          /* Largura presa à viewport, não ao conteúdo: ancorado à direita do microfone, qualquer
+             largura fixa maior que a tela sangra para fora no celular. `flex-wrap` é a segunda
+             rede — se o player e os dois botões não couberem lado a lado, os botões descem. */
+          className="absolute bottom-full right-0 z-20 mb-2 flex w-[calc(100vw-2rem)] max-w-[20rem] flex-wrap items-center justify-end gap-2 rounded-xl border border-gray-200 bg-white p-2 shadow-lg dark:border-gray-700 dark:bg-gray-800"
+        >
+          <div className="min-w-0 flex-1">
+            <AudioPlayer src={pending.objectURL} />
+          </div>
+          <button
+            type="button"
+            onClick={discard}
+            data-cv-tooltip={labelOf('discard')}
+            aria-label={labelOf('discard')}
+            className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-full text-gray-500 transition-colors hover:bg-gray-100 hover:text-red-500 dark:hover:bg-gray-700"
+          >
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round"><line x1="18" y1="6" x2="6" y2="18" /><line x1="6" y1="6" x2="18" y2="18" /></svg>
+          </button>
+          <button
+            type="button"
+            onClick={confirm}
+            data-cv-tooltip={labelOf('send')}
+            aria-label={labelOf('send')}
+            className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-full bg-emerald-500 text-white transition-colors hover:bg-emerald-600"
+          >
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><path d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z" /></svg>
+          </button>
+        </div>
+      )}
+      <button
+        type="button"
+        disabled={disabled || pending !== undefined}
+        onClick={() => (isRecording ? stop() : void start())}
+        data-cv-tooltip={toggleLabel}
+        aria-label={toggleLabel}
+        aria-pressed={isRecording}
+        /* Mesma caixa do botão de enviar: o microfone ocupa o lugar dele enquanto o campo está
+           vazio, e qualquer diferença de tamanho faz a barra pular a cada letra digitada. */
+        className={`flex h-10 w-10 items-center justify-center rounded-full transition-colors disabled:opacity-50 ${
+          isRecording
+            ? 'animate-pulse bg-red-500 text-white ring-4 ring-red-500/30 hover:bg-red-600'
+            : 'text-gray-500 hover:bg-gray-200 dark:hover:bg-gray-700'
+        }`}
+      >
+        {isRecording ? (
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><rect x="6" y="6" width="12" height="12" rx="2" /></svg>
+        ) : (
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round"><path d="M12 2a3 3 0 0 0-3 3v7a3 3 0 0 0 6 0V5a3 3 0 0 0-3-3z" /><path d="M19 11a7 7 0 0 1-14 0" /><line x1="12" y1="18" x2="12" y2="22" /></svg>
+        )}
+      </button>
+    </div>
+  )
+}

package/src/AudioTranscription.test.tsx

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { AudioTranscription } from './AudioTranscription'
+import type { MessageTranscription } from './types'
+
+function render(props: {
+  transcription?: MessageTranscription | null
+  onTranscribe?: () => Promise<void>
+}): string {
+  return renderToStaticMarkup(<AudioTranscription {...props} />)
+}
+
+const noop = async () => undefined
+
+describe('AudioTranscription', () => {
+  it('mostra o texto e oferece copiar', () => {
+    const markup = render({ transcription: { status: 'done', text: 'quero dois pães na chapa' } })
+
+    expect(markup).toContain('quero dois pães na chapa')
+    expect(markup).toContain('Copiar')
+  })
+
+  it('deixa o texto selecionável — é o caminho de quem não tem clipboard disponível', () => {
+    const markup = render({ transcription: { status: 'done', text: 'oi' } })
+
+    expect(markup).toContain('select-all')
+  })
+
+  it('não oferece copiar quando não há texto para copiar', () => {
+    const markup = render({ transcription: { status: 'done', text: '' } })
+
+    expect(markup).not.toContain('Copiar')
+  })
+
+  // Silêncio processado é diferente de não transcrito: sem essa distinção o operador clica em
+  // transcrever de novo atrás de um texto que não existe.
+  it('diz "sem fala detectada" em áudio processado e vazio, sem oferecer transcrever', () => {
+    const markup = render({ transcription: { status: 'done', text: '   ' } })
+
+    expect(markup).toContain('Sem fala detectada')
+    expect(markup).not.toContain('Transcrever áudio')
+  })
+
+  it('oferece transcrever quando nada foi avaliado ainda', () => {
+    const markup = render({ transcription: null, onTranscribe: noop })
+
+    expect(markup).toContain('Transcrever áudio')
+  })
+
+  // Mesmo padrão de takeover/release: sem a porta, a afordância não existe — melhor que um botão
+  // que estoura no clique.
+  it('não desenha nada quando não há transcrição nem forma de pedir uma', () => {
+    expect(render({ transcription: null })).toBe('')
+    expect(render({})).toBe('')
+  })
+
+  it('mostra falha com convite a tentar de novo', () => {
+    const markup = render({ transcription: { status: 'failed' }, onTranscribe: noop })
+
+    expect(markup).toContain('Falha ao transcrever')
+  })
+
+  it('trata pendente como em andamento — já foi tentado e vai sair', () => {
+    const markup = render({ transcription: { status: 'pending' }, onTranscribe: noop })
+
+    expect(markup).toContain('Transcrevendo...')
+  })
+
+  it('avisa formato não suportado sem oferecer retry — retentar não conserta codec', () => {
+    const markup = render({ transcription: { status: 'unsupported' }, onTranscribe: noop })
+
+    expect(markup).toContain('não suportado')
+    expect(markup).not.toContain('Transcrever novamente')
+  })
+
+  /**
+   * Medido: 1147 caracteres produziram uma bolha de 854px, mais alta que a área visível da conversa.
+   * Sem o recolhimento, uma nota de voz longa esconde as mensagens seguintes.
+   */
+  it('recolhe transcrição longa e oferece ver o texto completo', () => {
+    const markup = render({ transcription: { status: 'done', text: 'palavra '.repeat(60).trim() } })
+
+    expect(markup).toContain('ver transcrição completa')
+    expect(markup).toContain('-webkit-line-clamp')
+  })
+
+  it('não recolhe transcrição curta', () => {
+    const markup = render({ transcription: { status: 'done', text: 'quero dois pães' } })
+
+    expect(markup).not.toContain('ver transcrição completa')
+    expect(markup).not.toContain('-webkit-line-clamp')
+  })
+
+  // Recolher é sobre altura na tela; o operador cola o pedido inteiro no sistema interno.
+  it('mantém o texto inteiro no DOM mesmo recolhido, para o copiar levar tudo', () => {
+    const markup = render({ transcription: { status: 'done', text: 'primeira ' + 'meio '.repeat(70) + 'ultima' } })
+
+    expect(markup).toContain('primeira')
+    expect(markup).toContain('ultima')
+  })
+
+  it('oferece retranscrever quando já há texto e o host sabe transcrever', () => {
+    const markup = render({ transcription: { status: 'done', text: 'ruim' }, onTranscribe: noop })
+
+    expect(markup).toContain('Transcrever novamente')
+  })
+
+  it('não oferece retranscrever quando o host não sabe transcrever', () => {
+    const markup = render({ transcription: { status: 'done', text: 'ok' } })
+
+    expect(markup).toContain('ok')
+    expect(markup).not.toContain('Transcrever novamente')
+  })
+})

package/src/AudioTranscription.tsx

@@ -0,0 +1,252 @@
+import { useCallback, useState } from 'react'
+import { Check, Copy, FileText, Loader2, RefreshCw } from 'lucide-react'
+import { useConversationLocales } from './ConversationLocalesProvider'
+import { cn } from './lib/cn'
+import type { MessageTranscription } from './types'
+
+export interface AudioTranscriptionProps {
+  transcription?: MessageTranscription | null
+  /**
+   * Pede a transcrição ao backend. Ausente, o bloco nunca oferece o botão — um host em modo
+   * automático não tem rota para isso, e desenhar um botão que estoura no clique é pior do que não
+   * desenhar nada.
+   *
+   * O que for devolvido é exibido na hora. Sem isso o texto só apareceria no próximo refetch da
+   * lista, e transcrição não emite evento de tempo real: o operador clicaria, veria o spinner
+   * terminar e continuaria sem o texto na tela.
+   */
+  onTranscribe?: () => Promise<MessageTranscription | void>
+  isMine?: boolean
+}
+
+/** Feedback de "copiado" some sozinho — confirmação que exige clique para fechar é ruído. */
+const COPIED_FEEDBACK_MS = 2000
+
+/**
+ * Acima disto a transcrição nasce recolhida.
+ *
+ * Medido: 1147 caracteres (cerca de um minuto de fala) produziram uma bolha de 854px — mais alta que
+ * a área visível da conversa, empurrando todo o resto para fora. Nota de voz de três minutos
+ * triplicaria. O limite é em caracteres, e não em linhas de CSS, porque a decisão precisa acontecer
+ * antes de renderizar: `line-clamp` sozinho esconde o texto mas ainda paga o layout inteiro.
+ */
+const COLLAPSE_ABOVE_CHARS = 320
+
+/** Linhas visíveis quando recolhido — o bastante para saber do que o cliente está falando. */
+const COLLAPSED_LINE_CLAMP = 4
+
+/**
+ * Transcrição sob a nota de voz, com botão de copiar.
+ *
+ * Copiar é o motivo de o bloco existir: o operador cola o pedido do cliente no sistema interno, no
+ * orçamento, na busca. Seleção manual de texto dentro de um balão de chat é exatamente onde o
+ * arrasto do mouse falha — pega o balão vizinho, o horário, o nome do remetente.
+ *
+ * `navigator.clipboard.writeText` com try/catch silencioso, mesmo padrão de `MessageText.tsx`: a API
+ * exige contexto seguro e permissão, e um host servindo em HTTP simples não a tem. Falhar sem alarme
+ * é o certo — o texto continua na tela para seleção manual.
+ */
+export function AudioTranscription({ transcription, onTranscribe, isMine = false }: AudioTranscriptionProps) {
+  const { transcription: locales } = useConversationLocales()
+  const [hasCopied, setHasCopied] = useState(false)
+  const [isTranscribing, setIsTranscribing] = useState(false)
+  const [hasRequestFailed, setHasRequestFailed] = useState(false)
+  /**
+   * Resultado que acabou de voltar do backend, exibido antes de a lista ser refeita.
+   *
+   * Tem precedência sobre a prop porque é o dado mais novo: o refetch, quando vier, traz a mesma
+   * coisa. Sem isto o clique terminaria em nada visível.
+   */
+  const [justTranscribed, setJustTranscribed] = useState<MessageTranscription | undefined>()
+  const [isExpanded, setIsExpanded] = useState(false)
+
+  const effective = justTranscribed ?? transcription
+  const text = effective?.text?.trim() ?? ''
+  const status = effective?.status
+
+  // Nasce recolhido e o operador decide: abrir tudo por padrão faria a nota de voz longa esconder as
+  // mensagens seguintes, que é justamente o contexto de que ele precisa para responder.
+  const isLong = text.length > COLLAPSE_ABOVE_CHARS
+  const isTruncated = isLong && !isExpanded
+  const isDone = status === 'done'
+  const hasText = isDone && text.length > 0
+  // Silêncio já processado: dizer "sem fala detectada" evita o operador clicar em transcrever de novo
+  // atrás de um texto que não existe.
+  const isSilent = isDone && text.length === 0
+
+  const handleCopy = useCallback(async () => {
+    if (!text) return
+    try {
+      await navigator.clipboard.writeText(text)
+      setHasCopied(true)
+      setTimeout(() => setHasCopied(false), COPIED_FEEDBACK_MS)
+    } catch {
+      // Clipboard indisponível (contexto não seguro, permissão negada) — o texto segue selecionável.
+    }
+  }, [text])
+
+  const handleTranscribe = useCallback(async () => {
+    if (!onTranscribe || isTranscribing) return
+    setIsTranscribing(true)
+    setHasRequestFailed(false)
+    try {
+      const result = await onTranscribe()
+      if (result) setJustTranscribed(result)
+    } catch {
+      setHasRequestFailed(true)
+    } finally {
+      setIsTranscribing(false)
+    }
+  }, [onTranscribe, isTranscribing])
+
+  const dividerClass = isMine ? 'border-black/10 dark:border-white/10' : 'border-black/10 dark:border-white/10'
+
+  // Nada avaliado e sem rota para pedir: o balão fica como era antes da transcrição existir.
+  if (!status && !onTranscribe) return null
+
+  if (!status || status === 'pending' || status === 'failed') {
+    return (
+      <div className={`mt-1.5 border-t pt-1.5 ${dividerClass}`}>
+        <TranscribeButton
+          label={resolveActionLabel({ status, hasRequestFailed, isTranscribing, locales })}
+          isBusy={isTranscribing}
+          onClick={handleTranscribe}
+          isDisabled={!onTranscribe}
+        />
+      </div>
+    )
+  }
+
+  if (status === 'unsupported') {
+    return (
+      <div className={`mt-1.5 border-t pt-1.5 ${dividerClass}`}>
+        <p className="text-xs italic text-gray-500 dark:text-gray-400">{locales.unsupported}</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className={`mt-1.5 border-t pt-1.5 ${dividerClass}`}>
+      <div className="mb-0.5 flex items-center gap-1.5">
+        <FileText size={11} className="flex-shrink-0 text-gray-500 dark:text-gray-400" aria-hidden />
+        <span className="text-[11px] font-medium uppercase tracking-wide text-gray-500 dark:text-gray-400">
+          {locales.label}
+        </span>
+
+        {hasText && (
+          <button
+            onClick={handleCopy}
+            data-cv-tooltip={locales.copy}
+            aria-label={hasCopied ? locales.copied : locales.copy}
+            className="ml-auto flex flex-shrink-0 items-center gap-1 rounded px-1.5 py-0.5 text-[11px] text-gray-500 transition-colors hover:bg-black/5 hover:text-gray-700 dark:text-gray-400 dark:hover:bg-white/10 dark:hover:text-gray-200"
+          >
+            {hasCopied ? (
+              <>
+                <Check size={11} aria-hidden />
+                <span>{locales.copied}</span>
+              </>
+            ) : (
+              <>
+                <Copy size={11} aria-hidden />
+                <span>{locales.copy}</span>
+              </>
+            )}
+          </button>
+        )}
+      </div>
+
+      {isSilent ? (
+        <p className="text-xs italic text-gray-500 dark:text-gray-400">{locales.empty}</p>
+      ) : (
+        <>
+          {/* `select-all` para o clique único selecionar tudo: é o fallback quando o clipboard não
+              está disponível, e o caminho de quem prefere copiar com o teclado. */}
+          <p
+            className={cn(
+              'select-all whitespace-pre-wrap break-words text-[13px] leading-[18px] text-gray-700 dark:text-gray-200',
+              isTruncated && 'overflow-hidden',
+            )}
+            style={
+              isTruncated
+                ? {
+                    display: '-webkit-box',
+                    WebkitBoxOrient: 'vertical',
+                    WebkitLineClamp: COLLAPSED_LINE_CLAMP,
+                  }
+                : undefined
+            }
+          >
+            {text}
+          </p>
+          {/* O botão de copiar leva o texto INTEIRO, recolhido ou não — recolher é sobre altura na
+              tela, não sobre o que o operador cola no sistema interno. */}
+          {isLong && (
+            <button
+              data-cv-tooltip={isExpanded ? locales.showLess : locales.showMore} aria-label={isExpanded ? locales.showLess : locales.showMore}
+              onClick={() => setIsExpanded((current) => !current)}
+              className="mt-1 text-[11px] font-medium text-gray-500 underline decoration-dotted hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200"
+            >
+              {isExpanded ? locales.showLess : locales.showMore}
+            </button>
+          )}
+        </>
+      )}
+
+      {/* Retranscrever fica escondido atrás do hover do balão: é ação rara e paga cota de engine. */}
+      {onTranscribe && (
+        <button
+          data-cv-tooltip={isTranscribing ? locales.transcribing : locales.retry} aria-label={isTranscribing ? locales.transcribing : locales.retry}
+          onClick={handleTranscribe}
+          disabled={isTranscribing}
+          className="mt-1 flex items-center gap-1 text-[11px] text-gray-400 opacity-0 transition-opacity hover:text-gray-600 focus:opacity-100 group-hover:opacity-100 disabled:opacity-50 dark:text-gray-500 dark:hover:text-gray-300"
+        >
+          {isTranscribing ? <Loader2 size={10} className="animate-spin" aria-hidden /> : <RefreshCw size={10} aria-hidden />}
+          <span>{isTranscribing ? locales.transcribing : locales.retry}</span>
+        </button>
+      )}
+    </div>
+  )
+}
+
+function resolveActionLabel(params: {
+  status?: MessageTranscription['status']
+  hasRequestFailed: boolean
+  isTranscribing: boolean
+  locales: { transcribe: string; transcribing: string; retry: string; failed: string }
+}): string {
+  if (params.isTranscribing) return params.locales.transcribing
+  if (params.hasRequestFailed) return params.locales.retry
+  // `pending` é cota estourada ou falha transitória do lado do servidor: já foi tentado e vai sair,
+  // mas o operador que não quer esperar a retomada pode forçar agora.
+  if (params.status === 'pending') return params.locales.transcribing
+  if (params.status === 'failed') return params.locales.failed
+  return params.locales.transcribe
+}
+
+function TranscribeButton({
+  label,
+  isBusy,
+  isDisabled,
+  onClick,
+}: {
+  label: string
+  isBusy: boolean
+  isDisabled: boolean
+  onClick: () => void
+}) {
+  return (
+    <button
+      data-cv-tooltip={label} aria-label={label}
+      onClick={onClick}
+      disabled={isBusy || isDisabled}
+      className="flex items-center gap-1.5 rounded px-1.5 py-0.5 text-[11px] text-gray-500 transition-colors hover:bg-black/5 hover:text-gray-700 disabled:opacity-60 dark:text-gray-400 dark:hover:bg-white/10 dark:hover:text-gray-200"
+    >
+      {isBusy ? (
+        <Loader2 size={11} className="animate-spin" aria-hidden />
+      ) : (
+        <FileText size={11} aria-hidden />
+      )}
+      <span>{label}</span>
+    </button>
+  )
+}

package/src/Avatar.tsx

@@ -1,8 +1,18 @@
+export interface AvatarLabels {
+  /** Lido por leitor de tela quando não há nome nem imagem — a silhueta genérica. */
+  unnamedContact: string
+}
+
 export interface AvatarProps {
   name?: string | null
   avatarUrl?: string
   size?: 'sm' | 'md' | 'lg'
   className?: string
+  labels?: Partial<AvatarLabels>
+}
+
+export const DEFAULT_AVATAR_LABELS: AvatarLabels = {
+  unnamedContact: 'Contato sem nome',
 }
 
 const sizeClasses = {
@@ -36,8 +46,9 @@ function getBgColor(name: string | undefined | null): string {
 
 // Paridade com financiamento-imobiliario-bot/apps/web/src/components/Avatar.tsx —
 // mesmas iniciais (primeira+última letra), mesmo hash de cor, mesmas classes de tamanho.
-export function Avatar({ name, avatarUrl, size = 'md', className = '' }: AvatarProps) {
+export function Avatar({ name, avatarUrl, size = 'md', className = '', labels }: AvatarProps) {
   const sizeClass = sizeClasses[size]
+  const unnamedContactLabel = labels?.unnamedContact ?? DEFAULT_AVATAR_LABELS.unnamedContact
 
   if (avatarUrl) {
     return (
@@ -58,7 +69,7 @@ export function Avatar({ name, avatarUrl, size = 'md', className = '' }: AvatarP
       <div
         className={`${sizeClass} ${bgColor} rounded-full flex items-center justify-center text-white flex-shrink-0 ${className}`}
         role="img"
-        aria-label="Contato sem nome"
+        aria-label={unnamedContactLabel}
       >
         <svg viewBox="0 0 24 24" fill="currentColor" className="h-[60%] w-[60%]" aria-hidden>
           <path d="M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-4.42 0-8 2.24-8 5v1h16v-1c0-2.76-3.58-5-8-5Z" />
@@ -70,7 +81,7 @@ export function Avatar({ name, avatarUrl, size = 'md', className = '' }: AvatarP
   return (
     <div
       className={`${sizeClass} ${bgColor} rounded-full flex items-center justify-center text-white font-semibold flex-shrink-0 ${className}`}
-      title={name}
+      data-cv-tooltip={name}
     >
       {getInitials(name)}
     </div>