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

package/src/FileIcon.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'bun:test'
+
+import { resolveFileIconExtension } from './FileIcon'
+
+describe('resolveFileIconExtension', () => {
+  // Regressão: o painel de documentos passava só o mimeType, e o do Office é longo
+  // (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`), então docx, doc,
+  // xlsx e xls apareciam todos com o ícone genérico cinza.
+  const OFFICE_MIME_TYPES = [
+    {
+      filename: 'contrato.docx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      expected: 'docx',
+    },
+    { filename: 'procuracao.doc', mimeType: 'application/msword', expected: 'doc' },
+    {
+      filename: 'pedido.xlsx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      expected: 'xlsx',
+    },
+    { filename: 'tabela.xls', mimeType: 'application/vnd.ms-excel', expected: 'xls' },
+  ]
+
+  for (const testCase of OFFICE_MIME_TYPES) {
+    it(`resolve ${testCase.expected} pelo nome, já que o mimeType do Office não bate`, () => {
+      expect(resolveFileIconExtension(testCase.filename, testCase.mimeType)).toBe(testCase.expected)
+    })
+  }
+
+  it('resolve pelo mimeType quando o nome não tem extensão conhecida', () => {
+    expect(resolveFileIconExtension(undefined, 'application/pdf')).toBe('pdf')
+    expect(resolveFileIconExtension('recibo', 'application/zip')).toBe('zip')
+  })
+
+  it('devolve algo fora do mapa para tipo desconhecido, caindo no ícone genérico', () => {
+    expect(resolveFileIconExtension('backup', 'application/octet-stream')).toBe('octet-stream')
+  })
+
+  // Imagem, vídeo e áudio entram na biblioteca junto dos documentos — o backend linka as cinco
+  // espécies de mídia (image/audio/video/document/sticker), não só `document`.
+  const MEDIA_TYPES = [
+    { filename: 'foto.jpg', mimeType: 'image/jpeg', expected: 'jpg' },
+    { filename: 'prateleira.png', mimeType: 'image/png', expected: 'png' },
+    { filename: 'video-do-produto.mp4', mimeType: 'video/mp4', expected: 'mp4' },
+    { filename: 'antigo.3gp', mimeType: 'video/3gp', expected: '3gp' },
+    { filename: 'musica.mp3', mimeType: 'audio/mpeg', expected: 'mp3' },
+    { filename: 'recado.m4a', mimeType: 'audio/mp4', expected: 'm4a' },
+    { filename: 'lista-compras.txt', mimeType: 'text/plain', expected: 'txt' },
+    { filename: 'planilha.csv', mimeType: 'text/csv', expected: 'csv' },
+    {
+      filename: 'apresentacao.pptx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      expected: 'pptx',
+    },
+  ]
+
+  for (const testCase of MEDIA_TYPES) {
+    it(`resolve ${testCase.expected}`, () => {
+      expect(resolveFileIconExtension(testCase.filename, testCase.mimeType)).toBe(testCase.expected)
+    })
+  }
+
+  // Áudio e sticker chegam da Meta sem nome de arquivo: o backend salva o id da mídia como rótulo,
+  // então a única pista de tipo é o mimeType.
+  it('resolve pela família quando o nome é o id da mídia, sem extensão', () => {
+    expect(resolveFileIconExtension('wamid-abc123', 'image/webp')).toBe('image')
+    expect(resolveFileIconExtension('wamid-abc123', 'video/mp4')).toBe('video')
+    expect(resolveFileIconExtension('wamid-abc123', 'audio/aac')).toBe('audio')
+  })
+
+  // `audio/ogg; codecs=opus` é o formato do áudio de WhatsApp. Com o parâmetro colado, o subtipo
+  // viria "ogg; codecs=opus" e o áudio cairia no ícone genérico.
+  it('descarta parâmetro do mimeType', () => {
+    expect(resolveFileIconExtension('wamid-audio', 'audio/ogg; codecs=opus')).toBe('audio')
+  })
+
+  // Pelo subtipo, `audio/mp4` casaria a chave `mp4` — que é vídeo. A família vem primeiro
+  // justamente para um m4a não aparecer com ícone de filme.
+  it('não confunde audio/mp4 com vídeo', () => {
+    expect(resolveFileIconExtension(undefined, 'audio/mp4')).toBe('audio')
+    expect(resolveFileIconExtension(undefined, 'video/mp4')).toBe('video')
+  })
+})

package/src/FileIcon.tsx

@@ -1,4 +1,15 @@
-import { FileArchive, FileSpreadsheet, FileText, File as FileGeneric } from 'lucide-react'
+import {
+  FileArchive,
+  FileAudio,
+  FileImage,
+  FileSpreadsheet,
+  FileText,
+  FileVideo,
+  File as FileGeneric,
+  Presentation,
+} from 'lucide-react'
+
+import { cn } from './lib/cn'
 
 export interface FileIconProps {
   filename?: string
@@ -7,27 +18,93 @@ export interface FileIconProps {
   className?: string
 }
 
-const EXTENSION_STYLE: Record<string, { Icon: typeof FileText; colorClass: string }> = {
+type IconStyle = { Icon: typeof FileText; colorClass: string }
+
+// Um estilo por família, reaproveitado por todas as extensões dela: assim o ícone de um `.jpg`
+// resolvido pelo nome é o mesmo de um `image/jpeg` resolvido pelo mimeType. Com cor por extensão, a
+// mesma foto trocaria de cor conforme o dado que chegou junto.
+const IMAGE_STYLE: IconStyle = { Icon: FileImage, colorClass: 'text-violet-500' }
+const VIDEO_STYLE: IconStyle = { Icon: FileVideo, colorClass: 'text-fuchsia-500' }
+const AUDIO_STYLE: IconStyle = { Icon: FileAudio, colorClass: 'text-amber-500' }
+const SHEET_STYLE: IconStyle = { Icon: FileSpreadsheet, colorClass: 'text-green-600' }
+const WORD_STYLE: IconStyle = { Icon: FileText, colorClass: 'text-blue-500' }
+const SLIDES_STYLE: IconStyle = { Icon: Presentation, colorClass: 'text-orange-600' }
+const TEXT_STYLE: IconStyle = { Icon: FileText, colorClass: 'text-gray-500' }
+
+const EXTENSION_STYLE: Record<string, IconStyle> = {
   pdf: { Icon: FileText, colorClass: 'text-red-500' },
-  doc: { Icon: FileText, colorClass: 'text-blue-500' },
-  docx: { Icon: FileText, colorClass: 'text-blue-500' },
-  xls: { Icon: FileSpreadsheet, colorClass: 'text-green-600' },
-  xlsx: { Icon: FileSpreadsheet, colorClass: 'text-green-600' },
+  doc: WORD_STYLE,
+  docx: WORD_STYLE,
+  xls: SHEET_STYLE,
+  xlsx: SHEET_STYLE,
+  csv: SHEET_STYLE,
+  ppt: SLIDES_STYLE,
+  pptx: SLIDES_STYLE,
   zip: { Icon: FileArchive, colorClass: 'text-orange-500' },
+  txt: TEXT_STYLE,
+  plain: TEXT_STYLE,
+
+  image: IMAGE_STYLE,
+  jpg: IMAGE_STYLE,
+  jpeg: IMAGE_STYLE,
+  png: IMAGE_STYLE,
+  webp: IMAGE_STYLE,
+  gif: IMAGE_STYLE,
+  heic: IMAGE_STYLE,
+
+  video: VIDEO_STYLE,
+  mp4: VIDEO_STYLE,
+  '3gp': VIDEO_STYLE,
+  '3gpp': VIDEO_STYLE,
+  mov: VIDEO_STYLE,
+  webm: VIDEO_STYLE,
+
+  audio: AUDIO_STYLE,
+  mp3: AUDIO_STYLE,
+  mpeg: AUDIO_STYLE,
+  ogg: AUDIO_STYLE,
+  oga: AUDIO_STYLE,
+  opus: AUDIO_STYLE,
+  aac: AUDIO_STYLE,
+  amr: AUDIO_STYLE,
+  m4a: AUDIO_STYLE,
+  wav: AUDIO_STYLE,
 }
 
-function getExtension(filename?: string, mimeType?: string): string {
+const MEDIA_FAMILIES = new Set(['image', 'video', 'audio'])
+
+/**
+ * A chave de estilo do arquivo, na ordem em que cada dado é confiável.
+ *
+ * 1. **extensão do nome** — o mimeType do Office é longo (`…wordprocessingml.document`) e nunca
+ *    casaria, então quem olhasse só o mimeType perderia o ícone de Word e de Excel;
+ * 2. **família do mimeType** (`image/`, `video/`, `audio/`) — tem de vir ANTES do subtipo por causa
+ *    de `audio/mp4`: pelo subtipo, um áudio m4a ganharia o ícone de vídeo;
+ * 3. **subtipo** — cobre `application/pdf` e `application/zip`, que chegam sem nome de arquivo.
+ *
+ * Áudio de WhatsApp chega como `audio/ogg; codecs=opus`; o parâmetro depois do `;` é descartado,
+ * senão o subtipo viria `ogg; codecs=opus` e não casaria nada.
+ *
+ * Exportada para teste: é a regra que já regrediu uma vez no painel de documentos.
+ */
+export function resolveFileIconExtension(filename?: string, mimeType?: string): string {
   const fromFilename = filename?.split('.').pop()?.toLowerCase()
   if (fromFilename && EXTENSION_STYLE[fromFilename]) return fromFilename
-  return mimeType?.split('/')[1]?.toLowerCase() ?? ''
+
+  const [family, subtype] = (mimeType ?? '').split(';')[0]!.toLowerCase().split('/')
+  if (family && MEDIA_FAMILIES.has(family)) return family
+
+  return subtype ?? ''
 }
 
 // Melhoria sobre a paridade da bolha de documento (T6.7 usava um único ícone genérico
 // para qualquer tipo de arquivo) — ícone e cor variam por extensão/mimeType.
-export function FileIcon({ filename, mimeType, size = 20, className = '' }: FileIconProps) {
-  const extension = getExtension(filename, mimeType)
+export function FileIcon({ filename, mimeType, size = 20, className }: FileIconProps) {
+  const extension = resolveFileIconExtension(filename, mimeType)
   const style = EXTENSION_STYLE[extension] ?? { Icon: FileGeneric, colorClass: 'text-gray-500' }
   const { Icon, colorClass } = style
 
-  return <Icon size={size} className={`${colorClass} ${className}`.trim()} />
+  // `cn` em vez de concatenar: a cor por extensão é a base, e produto que passa `text-*` precisa
+  // ganhar dela — concatenado, quem vence é a ordem no CSS gerado, não a intenção de quem chamou.
+  return <Icon size={size} className={cn(colorClass, className)} />
 }

package/src/InteractiveMessage.test.tsx

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { InteractiveMessage } from './InteractiveMessage'
+import type { InteractivePayload } from './types'
+
+function render(payload: InteractivePayload): string {
+  return renderToStaticMarkup(<InteractiveMessage payload={payload} />)
+}
+
+describe('InteractiveMessage', () => {
+  it('formata negrito no corpo, como o aparelho faz', () => {
+    const markup = render({ type: 'button', body: { text: 'Qual o *prazo desejado*?' } })
+
+    expect(markup).toContain('<strong>prazo desejado</strong>')
+    expect(markup).not.toContain('*prazo desejado*')
+  })
+
+  it('formata cabeçalho e rodapé também', () => {
+    const markup = render({
+      type: 'list',
+      header: { text: '*Menu*' },
+      body: { text: 'corpo' },
+      footer: { text: '_Selecione_' },
+    })
+
+    expect(markup).toContain('<strong>Menu</strong>')
+    expect(markup).toContain('<em>Selecione</em>')
+  })
+
+  it('deixa título de opção literal, porque o WhatsApp não formata ali', () => {
+    const markup = render({
+      type: 'button',
+      body: { text: 'corpo' },
+      action: { buttons: [{ reply: { id: 'sim', title: '*Sim*' } }] },
+    })
+
+    expect(markup).toContain('*Sim*')
+    expect(markup).not.toContain('<strong>Sim</strong>')
+  })
+})

package/src/InteractiveMessage.tsx

@@ -0,0 +1,146 @@
+/**
+ * Menu interativo do WhatsApp — botões de resposta rápida e lista de opções.
+ *
+ * A mensagem é gravada com o payload cru que foi enviado à Meta, então a UI apenas o desenha; não
+ * há segunda fonte de verdade sobre quais opções existiam naquele momento. Sem isto, mensagem
+ * `interactive` aparecia como texto solto e o menu simplesmente sumia da conversa — inclusive no
+ * simulador, onde o operador precisa ver exatamente o que o cliente vê.
+ *
+ * `onSelect` é opcional de propósito: no histórico da inbox as opções são leitura (o operador não
+ * responde no lugar do cliente); no simulador elas são clicáveis.
+ */
+
+import { useState } from 'react'
+import type { InteractiveOption, InteractivePayload, InteractiveSelection } from './types'
+import { cn } from './lib/cn'
+import { parseWhatsAppFormatting } from './lib/whatsapp-formatting'
+
+/** `parseWhatsAppFormatting` emite `<strong>`/`<em>`/`<del>`, que o reset do Tailwind zera. */
+const FORMATTING_CLASSES = '[&_strong]:font-bold [&_em]:italic [&_del]:line-through'
+
+export interface InteractiveMessageLabels {
+  /** Fallback do rótulo do botão que abre a lista, quando o payload não traz um. */
+  openList: string
+}
+
+export const DEFAULT_INTERACTIVE_MESSAGE_LABELS: InteractiveMessageLabels = {
+  openList: 'Ver opções',
+}
+
+export interface InteractiveMessageProps {
+  payload: InteractivePayload
+  onSelect?: (selection: InteractiveSelection) => void
+  labels?: Partial<InteractiveMessageLabels>
+  className?: string
+}
+
+function collectRows(payload: InteractivePayload): InteractiveOption[] {
+  return (payload.action?.sections ?? []).flatMap((section) => section.rows ?? [])
+}
+
+function collectButtons(payload: InteractivePayload): InteractiveOption[] {
+  return (payload.action?.buttons ?? [])
+    .map((button) => button.reply)
+    .filter((reply): reply is InteractiveOption => reply !== undefined)
+}
+
+export function InteractiveMessage({ payload, onSelect, labels, className }: InteractiveMessageProps) {
+  const openListLabel = labels?.openList ?? DEFAULT_INTERACTIVE_MESSAGE_LABELS.openList
+  const [isListOpen, setIsListOpen] = useState(false)
+
+  const buttons = collectButtons(payload)
+  const sections = payload.action?.sections ?? []
+  const hasRows = collectRows(payload).length > 0
+  const isInteractable = onSelect !== undefined
+
+  return (
+    <div className={cn('flex flex-col gap-1', className)}>
+      {/* Cabeçalho, corpo e rodapé passam pela formatação do WhatsApp — o aparelho renderiza
+          `*negrito*` neles como em qualquer texto. Título e descrição de opção NÃO: ali o WhatsApp
+          mostra os asteriscos literais, e formatá-los aqui deixaria o simulador mais bonito que o
+          aparelho, que é o tipo de divergência que só aparece com o cliente na frente. */}
+      {payload.header?.text ? (
+        <p className={cn('text-sm font-semibold text-gray-900 dark:text-gray-100', FORMATTING_CLASSES)}>
+          {parseWhatsAppFormatting(payload.header.text)}
+        </p>
+      ) : null}
+
+      {payload.body?.text ? (
+        <p
+          className={cn(
+            'whitespace-pre-wrap break-words text-sm text-gray-900 dark:text-gray-100',
+            FORMATTING_CLASSES,
+          )}
+        >
+          {parseWhatsAppFormatting(payload.body.text)}
+        </p>
+      ) : null}
+
+      {payload.footer?.text ? (
+        <p className={cn('text-xs text-gray-500 dark:text-gray-400', FORMATTING_CLASSES)}>
+          {parseWhatsAppFormatting(payload.footer.text)}
+        </p>
+      ) : null}
+
+      {buttons.length > 0 ? (
+        <div className="mt-1 flex flex-col gap-1 border-t border-gray-200 pt-1 dark:border-gray-700">
+          {buttons.map((button) => (
+            <button
+              data-cv-tooltip={button.title} aria-label={button.title}
+              key={button.id}
+              type="button"
+              disabled={!isInteractable}
+              onClick={() => onSelect?.({ kind: 'button', option: button })}
+              className="rounded-md px-3 py-1.5 text-sm font-medium text-teal-700 transition-colors enabled:hover:bg-teal-50 disabled:cursor-default dark:text-teal-300 dark:enabled:hover:bg-teal-900/30"
+            >
+              {button.title}
+            </button>
+          ))}
+        </div>
+      ) : null}
+
+      {hasRows ? (
+        <div className="mt-1 border-t border-gray-200 pt-1 dark:border-gray-700">
+          <button
+            data-cv-tooltip={payload.action?.button ?? openListLabel} aria-label={payload.action?.button ?? openListLabel}
+            type="button"
+            onClick={() => setIsListOpen((open) => !open)}
+            aria-expanded={isListOpen}
+            className="w-full rounded-md px-3 py-1.5 text-sm font-medium text-teal-700 transition-colors hover:bg-teal-50 dark:text-teal-300 dark:hover:bg-teal-900/30"
+          >
+            ☰ {payload.action?.button ?? openListLabel}
+          </button>
+
+          {isListOpen ? (
+            <div className="mt-1 flex flex-col gap-1">
+              {sections.map((section, sectionIndex) => (
+                <div key={section.title ?? sectionIndex} className="flex flex-col">
+                  {section.title ? (
+                    <p className="px-3 py-1 text-xs font-semibold uppercase text-gray-500 dark:text-gray-400">
+                      {section.title}
+                    </p>
+                  ) : null}
+                  {(section.rows ?? []).map((row) => (
+                    <button
+                      data-cv-tooltip={row.title} aria-label={row.title}
+                      key={row.id}
+                      type="button"
+                      disabled={!isInteractable}
+                      onClick={() => onSelect?.({ kind: 'list', option: row })}
+                      className="rounded-md px-3 py-1.5 text-left text-sm text-gray-900 transition-colors enabled:hover:bg-gray-100 disabled:cursor-default dark:text-gray-100 dark:enabled:hover:bg-gray-700"
+                    >
+                      <span className="block">{row.title}</span>
+                      {row.description ? (
+                        <span className="block text-xs text-gray-500 dark:text-gray-400">{row.description}</span>
+                      ) : null}
+                    </button>
+                  ))}
+                </div>
+              ))}
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  )
+}

package/src/Lightbox.tsx

@@ -1,16 +1,31 @@
+export interface LightboxLabels {
+  /** Texto alternativo quando a imagem não tem legenda — sem ele o leitor de tela anuncia a URL. */
+  imageAlt: string
+  close: string
+}
+
 export interface LightboxProps {
   imageUrl: string
   caption?: string
   onClose: () => void
+  labels?: Partial<LightboxLabels>
 }
 
-export function Lightbox({ imageUrl, caption, onClose }: LightboxProps) {
+export const DEFAULT_LIGHTBOX_LABELS: LightboxLabels = {
+  imageAlt: 'Imagem',
+  close: 'Fechar',
+}
+
+export function Lightbox({ imageUrl, caption, onClose, labels }: LightboxProps) {
+  const imageAltLabel = labels?.imageAlt ?? DEFAULT_LIGHTBOX_LABELS.imageAlt
+  const closeLabel = labels?.close ?? DEFAULT_LIGHTBOX_LABELS.close
+
   return (
     <div className="fixed inset-0 z-50 bg-black/85 flex items-center justify-center p-4" onClick={onClose}>
       <div className="max-w-[90vw] max-h-[90vh] flex flex-col items-center" onClick={(e) => e.stopPropagation()}>
-        <img src={imageUrl} alt={caption ?? 'Image'} className="max-w-full max-h-[80vh] object-contain rounded-lg" />
+        <img src={imageUrl} alt={caption ?? imageAltLabel} className="max-w-full max-h-[80vh] object-contain rounded-lg" />
         {caption && <p className="text-white text-sm mt-3 text-center">{caption}</p>}
-        <button onClick={onClose} className="mt-4 px-4 py-2 bg-white/20 text-white rounded-lg hover:bg-white/30 transition-colors">Fechar</button>
+        <button data-cv-tooltip={closeLabel} aria-label={closeLabel} onClick={onClose} className="mt-4 px-4 py-2 bg-white/20 text-white rounded-lg hover:bg-white/30 transition-colors">{closeLabel}</button>
       </div>
     </div>
   )

package/src/MediaRenderer.tsx

@@ -1,9 +1,30 @@
-import { useState } from 'react'
+import { useState, type ReactNode } from 'react'
 import { AudioPlayer } from './AudioPlayer'
+import { AudioTranscription } from './AudioTranscription'
 import { FileIcon } from './FileIcon'
 import { useConversationLocales } from './ConversationLocalesProvider'
 import { formatFileSize } from './lib/format'
-import type { MessagePayload } from './types'
+import { cn } from './lib/cn'
+import type { MessagePayload, MessageTranscription } from './types'
+
+/**
+ * Rótulo curto do tipo, para a linha de baixo da bolha de documento.
+ *
+ * O subtipo cru do Office é gigantesco — `vnd.openxmlformats-officedocument.wordprocessingml.document`
+ * vira uma linha de 58 caracteres em caixa alta que estica a bolha, empurra a coluna da conversa e
+ * quebra o layout de três painéis. A extensão do arquivo diz a mesma coisa em quatro letras.
+ */
+export function documentTypeLabel(filename?: string, mimeType?: string): string {
+  const extension = filename?.split('.').pop()
+  if (extension && extension.length <= 5 && extension !== filename) return extension.toUpperCase()
+
+  const subtype = mimeType?.split(';')[0]?.split('/')[1]
+  if (!subtype) return 'FILE'
+  // Sem extensão e com subtipo longo (áudio/vídeo sem nome), fica o sufixo depois do último ponto:
+  // `…wordprocessingml.document` -> `DOCUMENT`, que ainda informa e não estoura.
+  const compacto = subtype.split('.').pop() ?? subtype
+  return compacto.slice(0, 12).toUpperCase()
+}
 
 function resolveMediaSource(message: MessagePayload): string | null {
   if (message.mediaUrl) return message.mediaUrl
@@ -30,6 +51,15 @@ export interface MediaRendererProps {
   // loadUrl/loadMedia de financiamento-imobiliario-bot/apps/web/src/components/MessageBubble.tsx,
   // porém delegando o fetch ao host em vez de hardcodar `/uploads/:id/download-url`.
   onResolveUrl?: ResolveMediaUrl
+  /**
+   * Pede ao backend a transcrição do áudio desta mensagem. Ausente, o bloco de transcrição só exibe
+   * o que já veio pronto — sem oferecer um botão que o host não sabe atender.
+   *
+   * O que devolver é exibido na hora, sem esperar refetch da lista.
+   */
+  onTranscribeAudio?: () => Promise<MessageTranscription | void>
+  /** Aplicado no wrapper de cada tipo de mídia — imagem, vídeo, áudio e documento. */
+  className?: string
 }
 
 function useLazyMediaUrl(message: MessagePayload, onResolveUrl?: ResolveMediaUrl) {
@@ -55,23 +85,49 @@ function useLazyMediaUrl(message: MessagePayload, onResolveUrl?: ResolveMediaUrl
   return { url, loading, error, load }
 }
 
-export function MediaRenderer({ message, onLightbox, onResolveUrl }: MediaRendererProps) {
+export function MediaRenderer({
+  message,
+  onLightbox,
+  onResolveUrl,
+  onTranscribeAudio,
+  className,
+}: MediaRendererProps) {
   const { bubble } = useConversationLocales()
   const eagerSrc = resolveMediaSource(message)
   const lazy = useLazyMediaUrl(message, onResolveUrl)
   const src = eagerSrc ?? lazy.url
   const canLazyLoad = !eagerSrc && hasLazyRef(message) && Boolean(onResolveUrl)
 
-  const lazyButtonClass = 'text-xs text-blue-600 underline flex items-center gap-1'
+  /**
+   * O carregamento sob demanda continua sendo um botão, mas com a forma da mídia que ele vai virar
+   * — um link sublinhado no meio da conversa lê como texto da mensagem, não como controle, e é a
+   * única bolha que não se parece com o que contém.
+   */
+  function LazyMediaButton({ icon, label }: { icon: ReactNode; label: string }) {
+    return (
+      <button
+        data-cv-tooltip={label} aria-label={label}
+        onClick={lazy.load}
+        disabled={lazy.loading}
+        className="flex min-w-[180px] items-center gap-2 rounded-lg bg-black/5 px-2 py-1.5 text-left transition-colors hover:bg-black/10 disabled:opacity-60 dark:bg-white/10 dark:hover:bg-white/15"
+      >
+        <span className="flex h-9 w-9 flex-shrink-0 items-center justify-center rounded-full bg-gray-600 text-white">
+          {icon}
+        </span>
+        <span className="truncate text-xs text-gray-600 dark:text-gray-300">{label}</span>
+      </button>
+    )
+  }
 
   switch (message.type) {
     case 'image':
     case 'sticker': {
       if (!src && canLazyLoad) {
         return (
-          <button onClick={lazy.load} className={lazyButtonClass}>
-            {lazy.loading ? bubble.mediaLoading : lazy.error ? bubble.mediaRetry : bubble.viewImage}
-          </button>
+          <LazyMediaButton
+            icon={<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><rect x="3" y="3" width="18" height="18" rx="2" ry="2" /><circle cx="8.5" cy="8.5" r="1.5" /><polyline points="21 15 16 10 5 21" /></svg>}
+            label={lazy.loading ? bubble.mediaLoading : lazy.error ? bubble.mediaRetry : bubble.viewImage}
+          />
         )
       }
       return (
@@ -89,9 +145,10 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl }: MediaRender
     case 'video': {
       if (!src && canLazyLoad) {
         return (
-          <button onClick={lazy.load} className={lazyButtonClass}>
-            {lazy.loading ? bubble.mediaLoading : lazy.error ? bubble.mediaRetry : bubble.viewVideo}
-          </button>
+          <LazyMediaButton
+            icon={<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><polygon points="23 7 16 12 23 17 23 7" /><rect x="1" y="5" width="15" height="14" rx="2" ry="2" /></svg>}
+            label={lazy.loading ? bubble.mediaLoading : lazy.error ? bubble.mediaRetry : bubble.viewVideo}
+          />
         )
       }
       return (
@@ -107,11 +164,28 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl }: MediaRender
       )
     }
     case 'audio': {
+      /**
+       * Fica fora do ramo de carregamento de propósito: a transcrição não depende dos bytes do
+       * áudio. Ler o que o cliente disse sem baixar e tocar a nota de voz é o caminho rápido do
+       * atendimento — e é justamente o que se perderia se o bloco só aparecesse depois do play.
+       */
+      const transcriptionBlock = (
+        <AudioTranscription
+          transcription={message.transcription}
+          isMine={message.direction === 'outbound'}
+          {...(onTranscribeAudio ? { onTranscribe: onTranscribeAudio } : {})}
+        />
+      )
+
       if (!src && canLazyLoad) {
         return (
-          <button onClick={lazy.load} className={lazyButtonClass}>
-            {lazy.loading ? bubble.mediaLoading : lazy.error ? bubble.mediaRetry : bubble.listenAudio}
-          </button>
+          <div className="min-w-[200px]">
+            <LazyMediaButton
+              icon={<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" className="translate-x-0.5"><polygon points="5 3 19 12 5 21 5 3" /></svg>}
+              label={lazy.loading ? bubble.mediaLoading : lazy.error ? bubble.mediaRetry : bubble.listenAudio}
+            />
+            {transcriptionBlock}
+          </div>
         )
       }
       return (
@@ -119,20 +193,21 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl }: MediaRender
           {src ? <AudioPlayer src={src} isMine={message.direction === 'outbound'} /> : (
             <div className="h-12 bg-gray-200 rounded-lg flex items-center justify-center text-gray-400 text-xs">{bubble.mediaUnavailable}</div>
           )}
+          {transcriptionBlock}
         </div>
       )
     }
     case 'document': {
-      const typeLabel = message.mimeType?.split('/')[1]?.toUpperCase() ?? 'FILE'
+      const typeLabel = documentTypeLabel(message.filename, message.mimeType)
       const sizeLabel = message.sizeBytes ? formatFileSize(message.sizeBytes) : null
       return (
-        <div className="flex items-center gap-3 min-w-[200px]">
+        <div className={cn('flex items-center gap-3 min-w-[200px]', className)}>
           <div className="w-10 h-10 bg-gray-200 rounded-lg flex items-center justify-center flex-shrink-0">
             <FileIcon filename={message.filename} mimeType={message.mimeType} />
           </div>
           <div className="flex-1 min-w-0">
             <p className="text-sm font-medium truncate">{message.filename ?? bubble.untitledDocument}</p>
-            <p className="text-xs text-gray-500">{sizeLabel ? `${typeLabel} · ${sizeLabel}` : typeLabel}</p>
+            <p className="truncate text-xs text-gray-500">{sizeLabel ? `${typeLabel} · ${sizeLabel}` : typeLabel}</p>
           </div>
           {src ? (
             <a href={src} download={message.filename} className="w-8 h-8 flex items-center justify-center rounded-full bg-gray-200 hover:bg-gray-300 flex-shrink-0 transition-colors" aria-label={bubble.downloadFile}>
@@ -140,6 +215,7 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl }: MediaRender
             </a>
           ) : canLazyLoad ? (
             <button
+              data-cv-tooltip={bubble.downloadFile}
               onClick={lazy.load}
               disabled={lazy.loading}
               className="w-8 h-8 flex items-center justify-center rounded-full bg-gray-200 hover:bg-gray-300 flex-shrink-0 transition-colors disabled:opacity-50"

package/src/MessageBubble.test.tsx

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { MessageBubble } from './MessageBubble'
+import type { MessagePayload } from './types'
+
+const IMAGE_MESSAGE: MessagePayload = {
+  id: 'msg-1',
+  type: 'image',
+  direction: 'outbound',
+  sender: 'agent',
+  timestamp: '2026-08-05T12:00:00.000Z',
+  filename: 'planta-baixa.png',
+  mediaUrl: 'https://cdn.test/planta-baixa.png',
+}
+
+describe('MessageBubble com mídia', () => {
+  it('mostra a legenda que veio no conteúdo do envio', () => {
+    const markup = renderToStaticMarkup(
+      <MessageBubble message={{ ...IMAGE_MESSAGE, content: 'Planta do 302' }} isMine />,
+    )
+
+    expect(markup).toContain('Planta do 302')
+  })
+
+  it('mostra a legenda que o cliente mandou junto da imagem', () => {
+    const markup = renderToStaticMarkup(
+      <MessageBubble message={{ ...IMAGE_MESSAGE, direction: 'inbound', sender: 'customer', caption: 'É esse?' }} isMine={false} />,
+    )
+
+    expect(markup).toContain('É esse?')
+  })
+
+  it('não repete o nome do arquivo como se fosse legenda', () => {
+    const markup = renderToStaticMarkup(
+      <MessageBubble message={{ ...IMAGE_MESSAGE, content: 'planta-baixa.png' }} isMine />,
+    )
+
+    expect(markup).not.toContain('>planta-baixa.png<')
+  })
+})