@adatechnology/conversations-ui 0.1.0-rc.20 → 0.1.0-rc.22

package/src/ConversationContextPanel.tsx

@@ -1,21 +1,34 @@
 /**
  * "Suas Seleções": o que o bot já coletou na conversa. Para o atendente que assume no meio, é a
- * diferença entre ler o transcript inteiro e ver o estado em duas linhas.
+ * diferença entre ler o transcript inteiro e ver o estado de relance.
  *
  * O pacote não interpreta o contexto — ele é `Record<string, unknown>` e cada produto nomeia as
  * próprias chaves. O host traduz para `entries`; aqui só se decide como mostrar.
+ *
+ * Desenho em paridade com financiamento-imobiliario-bot/apps/web/src/components/SelectionsSummary.tsx:
+ * card com gradiente, badge de contagem, pills de status no cabeçalho e grid de cards com borda
+ * colorida por estado. O que ficou diferente de lá, e por quê, está comentado no ponto.
  */
 
 import { useState } from 'react'
+import { Check, ChevronDown, ChevronUp, Clock, Pencil } from 'lucide-react'
 
 import { cn } from './lib/cn'
 import { useIsNarrow } from './useIsNarrow'
 
+/**
+ * `completed` tem valor, `pending` ainda não foi coletado, `editing` é o cliente refazendo a
+ * resposta. O host só precisa mandar `status` para o terceiro caso — os dois primeiros saem do
+ * próprio `value`, e exigir o campo quebraria quem já usa o painel.
+ */
+export type ConversationContextStatus = 'completed' | 'pending' | 'editing'
+
 export interface ConversationContextEntry {
   key: string
   label: string
   value?: string | undefined
   icon?: string
+  status?: ConversationContextStatus
 }
 
 export interface ConversationContextPanelLabels {
@@ -23,13 +36,16 @@ export interface ConversationContextPanelLabels {
   empty: string
   collapse: string
   expand: string
+  /** Placeholder do card ainda não coletado. */
+  notCollected: string
 }
 
 export const DEFAULT_CONVERSATION_CONTEXT_LABELS: ConversationContextPanelLabels = {
-  title: '📋 Suas Seleções',
+  title: 'Suas Seleções',
   empty: 'Nada coletado ainda nesta conversa.',
   collapse: 'fechar',
   expand: 'abrir',
+  notCollected: 'a coletar',
 }
 
 export interface ConversationContextPanelClassNames {
@@ -45,83 +61,220 @@ export interface ConversationContextPanelProps {
    * Estado inicial. Ausente, abre sozinho no desktop quando há algum dado preenchido.
    *
    * Existe porque "abre sozinho" nem sempre é o que o produto quer: com 1 de 6 campos preenchidos o
-   * painel ocupa altura mostrando quase só travessões, e empurra a conversa — que é o que se veio ver.
+   * painel ocupa altura mostrando quase só pendências, e empurra a conversa — que é o que se veio ver.
    */
   defaultOpen?: boolean
+  /**
+   * Rótulo do fluxo em curso, exibido em azul ao lado do título — no financiamento é o produto
+   * escolhido ("Consórcio", "MCMV"). Ausente, o cabeçalho fica só com título e contagens.
+   */
+  flowLabel?: string
   labels?: Partial<ConversationContextPanelLabels>
   className?: string
   classNames?: Partial<ConversationContextPanelClassNames>
 }
 
+function statusOf(entry: ConversationContextEntry): ConversationContextStatus {
+  if (entry.status) return entry.status
+  return entry.value ? 'completed' : 'pending'
+}
+
+/** Borda e fundo do card por estado. Pendente é tracejado — ver o comentário no grid. */
+const CARD_STYLE: Record<ConversationContextStatus, string> = {
+  completed: 'bg-white dark:bg-gray-800 border-2 border-green-200 dark:border-green-800 shadow-sm',
+  editing: 'bg-white dark:bg-gray-800 border-2 border-blue-200 dark:border-blue-800 shadow-sm',
+  pending: 'border-2 border-dashed border-gray-200 bg-white/40 dark:border-gray-700 dark:bg-gray-800/30',
+}
+
+const GLYPH_STYLE: Record<ConversationContextStatus, string> = {
+  completed: 'text-green-600 dark:text-green-400',
+  editing: 'text-blue-600 dark:text-blue-400',
+  pending: 'text-gray-400 dark:text-gray-500',
+}
+
+function StatusGlyph({ status }: { status: ConversationContextStatus }) {
+  const size = 11
+  if (status === 'completed') return <Check size={size} aria-hidden />
+  if (status === 'editing') return <Pencil size={size} aria-hidden />
+  return <Clock size={size} aria-hidden />
+}
+
+function CountPill({
+  status,
+  count,
+  className,
+}: {
+  status: ConversationContextStatus
+  count: number
+  className: string
+}) {
+  if (count === 0) return null
+
+  return (
+    <span className={cn('flex items-center gap-1 rounded-full px-2 py-0.5 text-xs font-medium', className)}>
+      <StatusGlyph status={status} />
+      {count}
+    </span>
+  )
+}
+
 export function ConversationContextPanel({
   entries,
   defaultOpen,
+  flowLabel,
   labels: labelsOverride,
   className,
   classNames,
 }: ConversationContextPanelProps) {
   const labels = { ...DEFAULT_CONVERSATION_CONTEXT_LABELS, ...labelsOverride }
-  const filled = entries.filter((entry) => Boolean(entry.value))
 
-  // Abre sozinho só quando há algo coletado: um painel de seis traços ocupa a altura da conversa
-  // sem informar nada. O contador continua visível fechado, que é o dado útil de relance.
+  const counts = { completed: 0, pending: 0, editing: 0 }
+  for (const entry of entries) counts[statusOf(entry)] += 1
+
+  // Abre sozinho só quando há algo coletado: um painel de seis pendências ocupa a altura da conversa
+  // sem informar nada. As contagens continuam visíveis fechado, que é o dado útil de relance.
   //
   // `undefined` = usuário ainda não mexeu. Guardar só um booleano não serve: o contexto chega
   // depois da montagem, então o estado inicial seria calculado com a lista vazia e o painel ficaria
   // fechado mesmo com dados.
   const isNarrow = useIsNarrow()
   const [manualOpen, setManualOpen] = useState<boolean | undefined>(undefined)
-  // No celular nasce fechado mesmo com dados: aberto, o painel consome ~150px da conversa. O
-  // contador no cabeçalho já entrega a informação de relance.
-  const open = manualOpen ?? defaultOpen ?? (!isNarrow && filled.length > 0)
+  // No celular nasce fechado mesmo com dados: aberto, o painel consome ~150px da conversa.
+  const open = manualOpen ?? defaultOpen ?? (!isNarrow && counts.completed > 0)
 
   return (
-    <section className={cn('border-b', classNames?.root, className)}>
-      <button
-        type="button"
-        onClick={() => setManualOpen(!open)}
-        aria-expanded={open}
-        title={open ? labels.collapse : labels.expand}
+    // Faixa azul clara com separador, como o wrapper do financiamento: sem ela o card encostava
+    // direto no papel de parede da conversa e os dois blocos se misturavam.
+    <div className={cn('border-b bg-blue-50/60 px-3 py-3 dark:border-gray-700 dark:bg-blue-950/20', className)}>
+      <section
         className={cn(
-          'flex w-full cursor-pointer items-center gap-2 px-4 py-3 text-left text-sm font-medium transition-colors hover:bg-gray-50 dark:hover:bg-gray-800',
-          classNames?.toggle,
+          'overflow-hidden rounded-lg border border-blue-200 bg-gradient-to-br from-blue-50 to-indigo-50 dark:border-blue-900 dark:from-blue-950/30 dark:to-indigo-950/30',
+          classNames?.root,
         )}
       >
-        <span aria-hidden className="text-xs">
-          {open ? '▾' : '▸'}
-        </span>
-        <span>{labels.title}</span>
-        <span className={cn('rounded-full bg-gray-200 px-2 text-xs dark:bg-gray-700', classNames?.counter)}>
-          {filled.length}/{entries.length}
-        </span>
-        {/* Rótulo escrito na ponta direita: o caret sozinho não dizia que a linha inteira fecha o
-            painel — a pergunta "cadê o botão de fechar?" veio daí. */}
-        <span aria-hidden className="ml-auto text-xs text-gray-500">
-          {open ? labels.collapse : labels.expand}
-        </span>
-      </button>
-
-      {open ? (
-        <div className={cn('px-4 pb-3', classNames?.body)}>
-          {entries.length === 0 ? (
-            <p className="text-xs text-gray-500">{labels.empty}</p>
-          ) : (
-            <dl className="grid grid-cols-2 gap-2 text-xs">
-              {entries.map((entry) => (
-                <div key={entry.key} className="min-w-0">
-                  <dt className="truncate text-gray-500">
-                    {entry.icon ? `${entry.icon} ` : ''}
-                    {entry.label}
-                  </dt>
-                  <dd className="truncate font-medium">
-                    {entry.value ? <span className="text-green-700 dark:text-green-400">✓ {entry.value}</span> : '—'}
-                  </dd>
-                </div>
-              ))}
-            </dl>
+        <button
+          type="button"
+          onClick={() => setManualOpen(!open)}
+          aria-expanded={open}
+          title={open ? labels.collapse : labels.expand}
+          className={cn(
+            'flex w-full cursor-pointer items-center justify-between gap-2 px-4 py-2.5 text-left transition-colors hover:bg-blue-100/40 dark:hover:bg-blue-900/20',
+            classNames?.toggle,
           )}
-        </div>
-      ) : null}
-    </section>
+        >
+          <span className="flex min-w-0 items-center gap-2">
+            <span aria-hidden className="text-base leading-none">
+              📋
+            </span>
+            <span className="truncate text-sm font-semibold text-gray-900 dark:text-gray-100">{labels.title}</span>
+            {flowLabel ? (
+              <span className="truncate text-xs font-medium text-blue-600 dark:text-blue-400">{flowLabel}</span>
+            ) : null}
+            <span
+              className={cn(
+                'inline-flex h-5 w-5 flex-shrink-0 items-center justify-center rounded-full bg-blue-600 text-xs font-medium text-white',
+                classNames?.counter,
+              )}
+            >
+              {entries.length}
+            </span>
+          </span>
+
+          <span className="flex flex-shrink-0 items-center gap-2">
+            <CountPill
+              status="completed"
+              count={counts.completed}
+              className="bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400"
+            />
+            <CountPill
+              status="editing"
+              count={counts.editing}
+              className="bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400"
+            />
+            <CountPill
+              status="pending"
+              count={counts.pending}
+              className="bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-400"
+            />
+            {open ? (
+              <ChevronUp size={15} className="flex-shrink-0 text-blue-500" aria-hidden />
+            ) : (
+              <ChevronDown size={15} className="flex-shrink-0 text-blue-500" aria-hidden />
+            )}
+          </span>
+        </button>
+
+        {open ? (
+          /**
+           * Teto de altura com rolagem interna, como no financiamento (`max-h-64 overflow-y-auto`).
+           * Sem isso o painel cresce sem limite — e cresce de verdade: o host anexa as chaves de
+           * contexto que ele não conhece ao fim da lista, então uma conversa com bastante estado
+           * empurrava a conversa inteira para fora da tela.
+           *
+           * A diferença: lá o teto envolve o cabeçalho também, então ele rola junto e sai de vista.
+           * Aqui só o corpo rola — o cabeçalho é o que fecha o painel, e perder o clique de fechar
+           * no meio da rolagem é pior do que a economia de uma linha de markup.
+           */
+          <div
+            className={cn(
+              'cv-scrollbar-thin max-h-64 overflow-y-auto border-t border-blue-200 px-4 pb-4 pt-1 dark:border-blue-900',
+              classNames?.body,
+            )}
+          >
+            {entries.length === 0 ? (
+              <p className="pt-2 text-xs text-gray-500 dark:text-gray-400">{labels.empty}</p>
+            ) : (
+              /**
+               * Três colunas no desktop, como no financiamento — com duas, seis campos viravam uma
+               * coluna alta que empurrava a conversa.
+               *
+               * O que não fizemos igual: lá o painel FILTRA o que não foi coletado, porque a fonte
+               * só guarda o que o cliente respondeu. Aqui a lista de campos é conhecida de antemão,
+               * e "falta endereço" é justamente o que o atendente precisa ver ao assumir. Então o
+               * pendente aparece — tracejado e apagado, para ler como lacuna e não como dado.
+               */
+              <dl className="mt-2 grid grid-cols-2 gap-2 lg:grid-cols-3">
+                {entries.map((entry) => {
+                  const status = statusOf(entry)
+
+                  return (
+                    <div
+                      key={entry.key}
+                      className={cn('min-w-0 rounded-lg p-2.5 transition-all', CARD_STYLE[status])}
+                    >
+                      <dt className="mb-1 flex items-center justify-center gap-1">
+                        {entry.icon ? (
+                          <span aria-hidden className="text-base leading-none">
+                            {entry.icon}
+                          </span>
+                        ) : null}
+                        <span className="truncate text-[10px] font-medium uppercase leading-none tracking-wide text-gray-500 dark:text-gray-400">
+                          {entry.label}
+                        </span>
+                        <span className={cn('flex-shrink-0 leading-none', GLYPH_STYLE[status])}>
+                          <StatusGlyph status={status} />
+                        </span>
+                      </dt>
+                      {/* `title` no valor: truncado no card, o texto completo só existe no tooltip. */}
+                      <dd
+                        className={cn(
+                          'truncate text-center text-xs font-semibold',
+                          entry.value
+                            ? 'text-gray-900 dark:text-gray-100'
+                            : 'italic font-normal text-gray-400 dark:text-gray-500',
+                        )}
+                        title={entry.value ?? labels.notCollected}
+                      >
+                        {entry.value ?? labels.notCollected}
+                      </dd>
+                    </div>
+                  )
+                })}
+              </dl>
+            )}
+          </div>
+        ) : null}
+      </section>
+    </div>
   )
 }

package/src/ConversationLocalesProvider.tsx

@@ -22,6 +22,20 @@ export interface ConversationLocales {
     untitledDocument: string
     downloadFile: string
   }
+  transcription: {
+    label: string
+    copy: string
+    copied: string
+    transcribe: string
+    transcribing: string
+    retry: string
+    failed: string
+    /** Áudio processado sem fala detectada — distinto de "não transcrito". */
+    empty: string
+    unsupported: string
+    showMore: string
+    showLess: string
+  }
   selection: {
     select: string
   }
@@ -53,6 +67,19 @@ const DEFAULT_LOCALES: ConversationLocales = {
     untitledDocument: 'Documento',
     downloadFile: 'Baixar',
   },
+  transcription: {
+    label: 'Transcrição',
+    copy: 'Copiar',
+    copied: 'Copiado!',
+    transcribe: 'Transcrever áudio',
+    transcribing: 'Transcrevendo...',
+    retry: 'Transcrever novamente',
+    failed: 'Falha ao transcrever — tentar novamente',
+    empty: 'Sem fala detectada',
+    unsupported: 'Formato de áudio não suportado para transcrição',
+    showMore: 'ver transcrição completa',
+    showLess: 'ver menos',
+  },
   selection: {
     select: 'Selecionar',
   },
@@ -76,6 +103,7 @@ export interface ConversationLocalesProviderProps {
 export function ConversationLocalesProvider({ children, locales }: ConversationLocalesProviderProps) {
   const merged: ConversationLocales = {
     bubble: { ...DEFAULT_LOCALES.bubble, ...locales?.bubble },
+    transcription: { ...DEFAULT_LOCALES.transcription, ...locales?.transcription },
     selection: { ...DEFAULT_LOCALES.selection, ...locales?.selection },
     dateDivider: { ...DEFAULT_LOCALES.dateDivider, ...locales?.dateDivider },
   }

package/src/MediaRenderer.tsx

@@ -1,10 +1,11 @@
 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 { cn } from './lib/cn'
-import type { MessagePayload } from './types'
+import type { MessagePayload, MessageTranscription } from './types'
 
 /**
  * Rótulo curto do tipo, para a linha de baixo da bolha de documento.
@@ -50,6 +51,13 @@ 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
 }
@@ -77,7 +85,13 @@ function useLazyMediaUrl(message: MessagePayload, onResolveUrl?: ResolveMediaUrl
   return { url, loading, error, load }
 }
 
-export function MediaRenderer({ message, onLightbox, onResolveUrl, className }: MediaRendererProps) {
+export function MediaRenderer({
+  message,
+  onLightbox,
+  onResolveUrl,
+  onTranscribeAudio,
+  className,
+}: MediaRendererProps) {
   const { bubble } = useConversationLocales()
   const eagerSrc = resolveMediaSource(message)
   const lazy = useLazyMediaUrl(message, onResolveUrl)
@@ -149,12 +163,28 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl, className }:
       )
     }
     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 (
-          <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}
-          />
+          <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 (
@@ -162,6 +192,7 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl, className }:
           {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>
       )
     }

package/src/MessageBubble.tsx

@@ -1,6 +1,6 @@
 import { useMemo, useState } from 'react'
 import { Check } from 'lucide-react'
-import type { InteractiveSelection, MessagePayload } from './types'
+import type { InteractiveSelection, MessagePayload, MessageTranscription } from './types'
 import { useConversationLocales } from './ConversationLocalesProvider'
 import { StatusTicks } from './StatusTicks'
 import { MediaRenderer, type ResolveMediaUrl } from './MediaRenderer'
@@ -30,6 +30,12 @@ export interface MessageBubbleProps {
    * no histórico da inbox: o operador vê o que foi oferecido, sem responder no lugar do cliente.
    */
   onInteractiveSelect?: (selection: InteractiveSelection) => void
+  /**
+   * Pede a transcrição do áudio. Ausente, o balão usa `transcribeAudio` do `ConversationsApi` do
+   * contexto — passe apenas para sobrescrever. Sem nenhum dos dois, o bloco de transcrição só exibe
+   * o que já veio pronto do backend.
+   */
+  onTranscribeAudio?: (messageId: string) => Promise<MessageTranscription | void>
   className?: string
 }
 
@@ -51,7 +57,7 @@ const MEDIA_TYPES = new Set(['image', 'audio', 'video', 'document', 'sticker'])
 // tailwind.config do host expondo as cores `whatsapp.*` — ver Wallpaper.tsx e T6.2.
 export function MessageBubble({
   message, isMine, senderName, isFirstInGroup = true, isSelecting = false, isSelected = false, onToggleSelect,
-  onResolveMediaUrl, onInteractiveSelect, className,
+  onResolveMediaUrl, onInteractiveSelect, onTranscribeAudio, className,
 }: MessageBubbleProps) {
   const { bubble, selection } = useConversationLocales()
   const [lightboxSrc, setLightboxSrc] = useState<string | null>(null)
@@ -66,6 +72,18 @@ export function MessageBubble({
     [onResolveMediaUrl, context?.api],
   )
 
+  /**
+   * `undefined` quando nem o host nem o `ConversationsApi` sabem transcrever — é essa ausência que o
+   * bloco de transcrição consulta para decidir se desenha a afordância, mesmo padrão de
+   * `takeover`/`release`.
+   */
+  const requestTranscription = useMemo(() => {
+    const transcribe = onTranscribeAudio ?? context?.api?.transcribeAudio?.bind(context.api)
+    if (!transcribe) return undefined
+    // Devolve o resultado em vez de descartar: é o que o bloco exibe na hora, sem esperar refetch.
+    return () => transcribe(message.id)
+  }, [onTranscribeAudio, context?.api, message.id])
+
   const bubbleColor = BUBBLE_COLOR[message.sender] ?? BUBBLE_COLOR.customer
   const hasError = message.status === 'failed'
   const isMedia = MEDIA_TYPES.has(message.type)
@@ -138,7 +156,12 @@ export function MessageBubble({
         )}
 
         {isMedia ? (
-          <MediaRenderer message={message} onLightbox={setLightboxSrc} onResolveUrl={resolveMediaUrl} />
+          <MediaRenderer
+            message={message}
+            onLightbox={setLightboxSrc}
+            onResolveUrl={resolveMediaUrl}
+            {...(requestTranscription ? { onTranscribeAudio: requestTranscription } : {})}
+          />
         ) : isInteractive && message.payload ? (
           // O texto da mensagem interativa mora dentro do payload (`body.text`), e `content` guarda
           // só uma cópia achatada para busca — renderizar `content` aqui duplicaria o corpo.

package/src/MessageComposer.tsx

@@ -1,4 +1,5 @@
 import { useState, useRef, useCallback, type KeyboardEvent, type ChangeEvent, type ReactNode } from 'react'
+import { AudioRecorderButton } from './AudioRecorderButton'
 import type { ConversationsFeatures } from './types'
 import { cn } from './lib/cn'
 import { EmojiPicker } from './EmojiPicker'
@@ -219,6 +220,24 @@ export const MessageComposer = ({
     }
   }, [text, setText])
 
+  /**
+   * Microfone por padrão, sem o host precisar compor nada.
+   *
+   * Antes o gravador era só um componente exportado e um slot vazio: cada inbox tinha que lembrar de
+   * juntar os dois. Dois produtos, dois resultados — um ligou, o outro não, e a ausência não dava
+   * erro nenhum. Um composer de WhatsApp sem microfone está incompleto, então o default certo é ter.
+   *
+   * Depende de `onAttach` porque áudio gravado é um arquivo para entregar, e microfone que grava sem
+   * ter para onde mandar é pior que microfone nenhum — o operador fala e o áudio evapora. É a mesma
+   * regra de capacidade usada no resto do pacote: sem a porta, a afordância não aparece.
+   *
+   * `idleAction` continua vencendo: quem já compunha o próprio gravador (com rótulos, limite de
+   * duração ou revisão diferentes) não muda de comportamento ao atualizar.
+   */
+  const effectiveIdleAction =
+    idleAction ??
+    (onAttach ? <AudioRecorderButton onRecorded={(file) => onAttach(file)} /> : undefined)
+
   const canSend = text.trim().length > 0 || attachments.length > 0
   const remaining = maxLength ? maxLength - text.length : null
 
@@ -310,8 +329,8 @@ export const MessageComposer = ({
           </>
         )}
 
-        {!canSend && idleAction ? (
-          <div className="flex-shrink-0">{idleAction}</div>
+        {!canSend && effectiveIdleAction ? (
+          <div className="flex-shrink-0">{effectiveIdleAction}</div>
         ) : (
           <button
             onClick={sendMessage}

package/src/Wallpaper.tsx

@@ -8,7 +8,7 @@
  * A classe `cv-wallpaper` continua no elemento para quem já sobrescreve por CSS.
  */
 
-import type { CSSProperties, ReactNode } from 'react'
+import { forwardRef, type CSSProperties, type ReactNode, type UIEvent } from 'react'
 
 import { cn } from './lib/cn'
 import { useIsDarkTheme } from './useDarkMode'
@@ -45,17 +45,31 @@ export interface ConversationWallpaperProps {
   className?: string
   /** Ajusta ou substitui o fundo padrão — para produto com identidade visual própria. */
   style?: CSSProperties
+  /**
+   * Rolagem da área de mensagens. Par do `ref`: é este elemento que rola, então é aqui que
+   * `useScrollToLatestMessage` observa a posição para saber se o operador está acompanhando o fim.
+   */
+  onScroll?: (event: UIEvent<HTMLDivElement>) => void
 }
 
-export function ConversationWallpaper({ children, className, style }: ConversationWallpaperProps) {
-  const isDark = useIsDarkTheme()
-
-  return (
-    <div
-      className={cn('cv-wallpaper', className)}
-      style={{ ...(isDark ? DARK_WALLPAPER : LIGHT_WALLPAPER), ...style }}
-    >
-      {children}
-    </div>
-  )
-}
+/**
+ * `forwardRef` porque quem controla a rolagem é de fora — o hook precisa do elemento para saltar
+ * até a última mensagem. `forwardRef` e não `ref` como prop: o pacote suporta React 18, onde
+ * ref-como-prop ainda não existe.
+ */
+export const ConversationWallpaper = forwardRef<HTMLDivElement, ConversationWallpaperProps>(
+  function ConversationWallpaper({ children, className, style, onScroll }, ref) {
+    const isDark = useIsDarkTheme()
+
+    return (
+      <div
+        ref={ref}
+        onScroll={onScroll}
+        className={cn('cv-wallpaper', className)}
+        style={{ ...(isDark ? DARK_WALLPAPER : LIGHT_WALLPAPER), ...style }}
+      >
+        {children}
+      </div>
+    )
+  },
+)