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

package/src/preview/createPreviewWebhookClient.test.ts

@@ -10,8 +10,10 @@ import {
   assertPreviewEnvironment,
   createPreviewWebhookClient,
   PreviewInProductionError,
+  PreviewMediaUploadRejectedError,
   PreviewWebhookRejectedError,
 } from './createPreviewWebhookClient'
+import { PREVIEW_MEDIA_ID_PREFIX } from './createPreviewMediaUploader'
 
 const APP_SECRET = 'dev-app-secret'
 const FROM = '5511988887777'
@@ -103,3 +105,90 @@ describe('assertPreviewEnvironment', () => {
     expect(() => assertPreviewEnvironment(false)).not.toThrow()
   })
 })
+
+/**
+ * O microfone do simulador depende disto existir no cliente.
+ *
+ * Enquanto o upload era prop de quem montava a tela, um produto tinha gravador e o outro não — e a
+ * diferença não aparecia em teste nenhum, porque cada host montava o seu. Aqui a garantia é do
+ * pacote: cliente montado, upload assinado, id prefixado.
+ */
+describe('createPreviewWebhookClient.uploadMedia', () => {
+  function createUploadFetch(status = 201): {
+    fetchImplementation: typeof fetch
+    calls: Array<{ url: string; signature: string; body: string }>
+  } {
+    const calls: Array<{ url: string; signature: string; body: string }> = []
+
+    const fetchImplementation = (async (url: string, init?: RequestInit) => {
+      const headers = (init?.headers ?? {}) as Record<string, string>
+      calls.push({ url: String(url), signature: headers['x-preview-signature'] ?? '', body: String(init?.body) })
+      return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => ({ data: { uploadId: 'upl_123' } }),
+      } as Response
+    }) as unknown as typeof fetch
+
+    return { fetchImplementation, calls }
+  }
+
+  const audioFile = () => new File([new Uint8Array([1, 2, 3])], 'nota.ogg', { type: 'audio/ogg' })
+
+  it('sobe na mesma origem do webhook e devolve o id já prefixado', async () => {
+    const { fetchImplementation, calls } = createUploadFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    const uploaded = await client.uploadMedia(audioFile())
+
+    expect(calls[0]?.url).toBe('http://localhost:3000/v1/preview/media')
+    expect(uploaded.mediaId).toBe(`${PREVIEW_MEDIA_ID_PREFIX}upl_123`)
+    expect(uploaded.mimeType).toBe('audio/ogg')
+  })
+
+  it('assina o MIME com o mesmo HMAC que o servidor confere', async () => {
+    const { fetchImplementation, calls } = createUploadFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await client.uploadMedia(audioFile())
+
+    const expected = `sha256=${createHmac('sha256', APP_SECRET).update('audio/ogg').digest('hex')}`
+    expect(calls[0]?.signature).toBe(expected)
+  })
+
+  it('usa caminho relativo quando a URL do webhook não tem origem', async () => {
+    const { fetchImplementation, calls } = createUploadFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: '/v1/webhook/whatsapp',
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await client.uploadMedia(audioFile())
+
+    expect(calls[0]?.url).toBe('/v1/preview/media')
+  })
+
+  it('avisa com erro próprio quando a rota de mídia recusa', async () => {
+    const { fetchImplementation } = createUploadFetch(404)
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await expect(client.uploadMedia(audioFile())).rejects.toBeInstanceOf(PreviewMediaUploadRejectedError)
+  })
+})

package/src/preview/createPreviewWebhookClient.ts

@@ -25,6 +25,7 @@ import {
   type InboundMediaType,
   type InteractiveReplyOption,
 } from '@adatechnology/meta-whatsapp-contracts/testing'
+import { createPreviewMediaUploader, type PreviewUploadedMedia } from './createPreviewMediaUploader'
 
 export type PreviewWebhookClient = {
   sendText(text: string): Promise<void>
@@ -32,6 +33,19 @@ export type PreviewWebhookClient = {
   sendListReply(reply: InteractiveReplyOption): Promise<void>
   sendAudio(mediaId: string): Promise<void>
   sendMedia(params: SendPreviewMediaParams): Promise<void>
+  /**
+   * Guarda um arquivo gravado e devolve o `mediaId` já prefixado, pronto para `sendMedia`.
+   *
+   * Existe no cliente, e não como prop de quem monta a tela, porque isto é exatamente o que ele já
+   * sabe fazer: falar com ESTE host usando ESTE segredo. Enquanto era responsabilidade do produto,
+   * o resultado prático foi um produto com microfone no simulador e outro sem — não por decisão,
+   * por esquecimento. Cliente montado, microfone na tela.
+   *
+   * Opcional porque o cliente-ponte só consegue oferecer isto quando sabe a rota de mídia (ou quando
+   * o host injeta a função): sem destino, gravar áudio seria falar para o vazio, e aí a tela
+   * corretamente não desenha o gravador.
+   */
+  uploadMedia?(file: File): Promise<PreviewUploadedMedia>
 }
 
 export type SendPreviewMediaParams = {
@@ -52,10 +66,25 @@ export type CreatePreviewWebhookClientParams = {
   readonly appSecret: string
   readonly from: string
   readonly phoneNumberId?: string
+  /**
+   * Rota que guarda o áudio gravado. Por padrão, `/v1/preview/media` na mesma origem do webhook.
+   *
+   * O padrão cobre o caso normal — as duas rotas são do mesmo servidor — e a prop existe para quem
+   * publica a API em outro host ou versiona o caminho.
+   */
+  readonly mediaUploadUrl?: string
   // Escape hatch para teste; em runtime real é sempre o fetch global.
   readonly fetchImplementation?: typeof fetch
 }
 
+/** Falha da rota de upload, separada da do webhook: os dois lados quebram por motivos diferentes. */
+export class PreviewMediaUploadRejectedError extends Error {
+  constructor(readonly status: number) {
+    super(`A rota de mídia do simulador recusou o upload (HTTP ${status}).`)
+    this.name = 'PreviewMediaUploadRejectedError'
+  }
+}
+
 export class PreviewInProductionError extends Error {
   constructor() {
     super('O preview de conversa carrega um app secret e não pode ser montado em produção.')
@@ -102,6 +131,53 @@ export async function signPreviewPayload(params: { rawBody: string; appSecret: s
 
 const signWithWebCrypto = signPreviewPayload
 
+export const DEFAULT_MEDIA_UPLOAD_PATH = '/v1/preview/media'
+
+/**
+ * Mesma origem do webhook: as duas rotas são do mesmo servidor no caso normal.
+ *
+ * Quando `webhookUrl` é relativa — que é o que sai de um `VITE_API_URL` vazio, com o front servido
+ * pela própria API — não há origem para resolver contra, e o caminho relativo já aponta para o
+ * lugar certo. `new URL` com base relativa lançaria, e o microfone morreria no `createClient`.
+ */
+export function defaultMediaUploadUrl(webhookUrl: string): string {
+  try {
+    return new URL(DEFAULT_MEDIA_UPLOAD_PATH, webhookUrl).toString()
+  } catch {
+    return DEFAULT_MEDIA_UPLOAD_PATH
+  }
+}
+
+/**
+ * O POST de mídia, sem a parte de assinatura — para os dois clientes usarem o mesmo caminho.
+ *
+ * O cliente-ponte autentica por sessão e o de webhook por HMAC; o que não muda é a rota, o formato
+ * do corpo e a leitura do `uploadId`. Duas cópias disso é como o prefixo de mídia divergiu antes.
+ */
+export function createPreviewMediaPoster(params: {
+  readonly url: string
+  readonly headers?: (mimeType: string) => Promise<Readonly<Record<string, string>>>
+  readonly fetchImplementation?: typeof fetch
+}): (file: File) => Promise<PreviewUploadedMedia> {
+  return createPreviewMediaUploader({
+    upload: async (request) => {
+      const performRequest = params.fetchImplementation ?? fetch
+      const extraHeaders = (await params.headers?.(request.mimeType)) ?? {}
+
+      const response = await performRequest(params.url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+        body: JSON.stringify(request),
+      })
+
+      if (!response.ok) throw new PreviewMediaUploadRejectedError(response.status)
+
+      const body = (await response.json()) as { data: { uploadId: string } }
+      return { uploadId: body.data.uploadId }
+    },
+  })
+}
+
 export function createPreviewWebhookClient(params: CreatePreviewWebhookClientParams): PreviewWebhookClient {
   const sendPayload = async (payload: ReturnType<typeof buildInboundTextPayload>): Promise<void> => {
     // Serializa uma vez só: assinar um texto e enviar outro (mesmo com o conteúdo igual) derruba a
@@ -119,6 +195,20 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     if (!response.ok) throw new PreviewWebhookRejectedError(response.status)
   }
 
+  /**
+   * Assina o MIME, não o binário — mesmo contrato da rota.
+   *
+   * Passar megabytes de base64 pelo HMAC do navegador travaria a aba a cada nota de voz; o que a
+   * assinatura protege aqui é o acesso à rota, e o binário já tem teto de tamanho no servidor.
+   */
+  const uploadMedia = createPreviewMediaPoster({
+    url: params.mediaUploadUrl ?? defaultMediaUploadUrl(params.webhookUrl),
+    headers: async (mimeType) => ({
+      'x-preview-signature': await signWithWebCrypto({ rawBody: mimeType, appSecret: params.appSecret }),
+    }),
+    ...(params.fetchImplementation ? { fetchImplementation: params.fetchImplementation } : {}),
+  })
+
   const envelope = { from: params.from, phoneNumberId: params.phoneNumberId }
 
   return {
@@ -127,5 +217,6 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     sendListReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, listReply: reply })),
     sendAudio: (mediaId) => sendPayload(buildInboundAudioPayload({ ...envelope, mediaId })),
     sendMedia: (media) => sendPayload(buildInboundMediaPayload({ ...envelope, ...media })),
+    uploadMedia,
   }
 }

package/src/preview/index.ts

@@ -25,6 +25,9 @@ export type { CreateMockSSEProviderParams } from './createMockSSEProvider'
 
 export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES, PREVIEW_DOCUMENTS } from './previewFixtures'
 
+export { ConversationSimulatorPanel, DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS } from './ConversationSimulatorPanel'
+export type { ConversationSimulatorPanelProps, ConversationSimulatorPanelLabels } from './ConversationSimulatorPanel'
+
 export { ConversationPreview } from './ConversationPreview'
 export { mediaTypeOf } from './ConversationPreview'
 export type { ConversationPreviewProps, PreviewUploadedMedia } from './ConversationPreview'
@@ -38,6 +41,9 @@ export {
   assertPreviewEnvironment,
   PreviewInProductionError,
   PreviewWebhookRejectedError,
+  PreviewMediaUploadRejectedError,
+  createPreviewMediaPoster,
+  DEFAULT_MEDIA_UPLOAD_PATH,
 } from './createPreviewWebhookClient'
 export type {
   PreviewWebhookClient,
@@ -59,3 +65,6 @@ export { createPreviewMediaResolver, previewFileUrl } from './previewMediaSource
 export { previewFileBase64 } from './previewMediaSource'
 export { MediaTypesPreview, MEDIA_TYPES_CONVERSATION_ID } from './MediaTypesPreview'
 export type { MediaTypesPreviewProps } from './MediaTypesPreview'
+
+export { createPreviewMediaUploader, PREVIEW_MEDIA_ID_PREFIX } from './createPreviewMediaUploader'
+export type { CreatePreviewMediaUploaderParams, PreviewMediaUploadRequest } from './createPreviewMediaUploader'

package/src/preview/previewMediaUploader.test.ts

@@ -0,0 +1,61 @@
+/**
+ * O teste que importa aqui é o do prefixo: ele é duplicado entre este pacote (UI) e o
+ * meta-whatsapp-module (backend), e divergir significa o simulador gerar um id que o servidor não
+ * reconhece — o áudio chega, o backend busca na Meta, volta 404 e ninguém entende por quê.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { PREVIEW_MEDIA_ID_PREFIX as CONTRACT_PREFIX } from '@adatechnology/meta-whatsapp-contracts'
+
+import { createPreviewMediaUploader, PREVIEW_MEDIA_ID_PREFIX } from './createPreviewMediaUploader'
+
+describe('createPreviewMediaUploader', () => {
+  it('reexporta o prefixo do contrato, sem cópia própria', () => {
+    expect(PREVIEW_MEDIA_ID_PREFIX).toBe(CONTRACT_PREFIX)
+  })
+
+  it('devolve o id prefixado com o uploadId da rota', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'chave/do/objeto' }) })
+
+    const result = await upload(new File([new Uint8Array([1, 2, 3])], 'nota.ogg', { type: 'audio/ogg' }))
+
+    expect(result.mediaId).toBe(`${CONTRACT_PREFIX}chave/do/objeto`)
+    expect(result.mimeType).toBe('audio/ogg')
+    expect(result.filename).toBe('nota.ogg')
+  })
+
+  it('manda o binário em base64 para a rota', async () => {
+    let recebido: string | undefined
+    const upload = createPreviewMediaUploader({
+      upload: async (request) => {
+        recebido = request.base64
+        return { uploadId: 'k' }
+      },
+    })
+
+    await upload(new File([new TextEncoder().encode('audio')], 'a.ogg', { type: 'audio/ogg' }))
+
+    expect(atob(recebido!)).toBe('audio')
+  })
+
+  // Gravador entrega áudio sem nome, e navegador antigo entrega sem mime.
+  it('preenche nome e mime quando o arquivo vem sem eles', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'k' }) })
+
+    const result = await upload(new File([new Uint8Array([1])], '', { type: '' }))
+
+    expect(result.mimeType).toBe('audio/ogg')
+    expect(result.filename).toBe('audio.ogg')
+  })
+
+  /**
+   * Espalhar o array de bytes como argumentos estoura a pilha em arquivo grande — o erro que só
+   * aparece na primeira gravação de verdade, nunca no clipe curto do teste.
+   */
+  it('converte arquivo grande sem estourar a pilha', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'k' }) })
+    const grande = new File([new Uint8Array(300_000)], 'longo.ogg', { type: 'audio/ogg' })
+
+    expect((await upload(grande)).mediaId).toContain(CONTRACT_PREFIX)
+  })
+})

package/src/providers/types.ts

@@ -1,4 +1,4 @@
-import type { MessagePayload } from '../types'
+import type { MessagePayload, MessageTranscription } from '../types'
 import type { ConversationChannel } from '../conversationChannel'
 
 export interface ListConversationsParams {
@@ -134,6 +134,17 @@ export interface ConversationsApi {
    * nem todo backend expõe a rota — quem não tem continua usando o builder local.
    */
   exportTranscript?(conversationId: string): Promise<{ transcript: string; filename: string }>
+
+  /**
+   * Transcreve o áudio de uma mensagem e devolve o resultado.
+   *
+   * **Opcional por capacidade.** Um host em modo automático transcreve na ingestão e não expõe rota
+   * nenhuma; um host sem engine configurado não transcreve de jeito algum. Nos dois casos o balão
+   * simplesmente não desenha o botão, em vez de oferecer uma ação que estoura no clique.
+   *
+   * `messageId` e não `conversationId`: transcrição é por áudio, e uma conversa tem vários.
+   */
+  transcribeAudio?(messageId: string): Promise<MessageTranscription>
 }
 
 /**

package/src/settings/TranscriptionSettingsForm.test.tsx

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { TranscriptionSettingsForm } from './TranscriptionSettingsForm'
+import type { TranscriptionSettingsFormProps } from './TranscriptionSettingsForm'
+
+/**
+ * Extrai uma tag pelo atributo, em vez de casar regex com a ordem dos atributos: o React SSR emite
+ * `checked=""` antes de `value=""`, então `/value="auto"[^>]*checked/` falha num componente correto.
+ */
+function findTag(markup: string, tagPattern: RegExp, contains: string): string | undefined {
+  return (markup.match(tagPattern) ?? []).find((tag) => tag.includes(contains))
+}
+
+function render(overrides: Partial<TranscriptionSettingsFormProps> = {}): string {
+  return renderToStaticMarkup(
+    <TranscriptionSettingsForm
+      enabled={false}
+      onEnabledChange={() => {}}
+      mode="onDemand"
+      onModeChange={() => {}}
+      onSave={() => {}}
+      {...overrides}
+    />,
+  )
+}
+
+describe('TranscriptionSettingsForm', () => {
+  it('esconde a escolha de modo enquanto estiver desligado', () => {
+    const markup = render({ enabled: false })
+
+    expect(markup).not.toContain('Quando transcrever')
+  })
+
+  it('mostra as duas opções de modo ao ligar', () => {
+    const markup = render({ enabled: true })
+
+    expect(markup).toContain('Quando transcrever')
+    expect(markup).toContain('Quando o atendente pedir')
+    expect(markup).toContain('Automaticamente')
+  })
+
+  it('marca o modo atual', () => {
+    const markup = render({ enabled: true, mode: 'auto' })
+    const radios = /<input type="radio"[^>]*>/g
+
+    expect(findTag(markup, radios, 'value="auto"')).toContain('checked')
+    expect(findTag(markup, radios, 'value="onDemand"')).not.toContain('checked')
+  })
+
+  /**
+   * "O ambiente consegue" é diferente de "esta empresa quer". Sem o aviso, o lojista ligaria o
+   * interruptor num ambiente sem engine, nada apareceria, e nada explicaria por quê.
+   */
+  it('avisa e bloqueia quando a capacidade não existe no servidor', () => {
+    const markup = render({ isAvailable: false })
+
+    expect(markup).toContain('não está disponível neste ambiente')
+    expect(findTag(markup, /<input type="checkbox"[^>]*>/g, 'type="checkbox"')).toContain('disabled')
+  })
+
+  it('não avisa nada quando a capacidade existe', () => {
+    const markup = render({ isAvailable: true })
+
+    expect(markup).not.toContain('não está disponível neste ambiente')
+  })
+
+  it('aceita rótulos do host', () => {
+    const markup = render({ labels: { sectionTitle: 'Áudio em texto' } })
+
+    expect(markup).toContain('Áudio em texto')
+    expect(markup).not.toContain('Transcrição de áudio')
+  })
+
+  it('desabilita o salvar enquanto salva', () => {
+    const markup = render({ saving: true })
+
+    expect(markup).toContain('Salvando...')
+    expect(findTag(markup, /<button type="submit"[^>]*>/g, 'type="submit"')).toContain('disabled')
+  })
+})

package/src/settings/TranscriptionSettingsForm.tsx

@@ -0,0 +1,189 @@
+import type { FormEvent } from 'react'
+import { AudioLines, Save } from 'lucide-react'
+import type { TranscriptionMode } from '../types'
+
+export interface TranscriptionSettingsFormLabels {
+  sectionTitle: string
+  enabled: string
+  enabledHint: string
+  modeTitle: string
+  modeAuto: string
+  modeAutoHint: string
+  modeOnDemand: string
+  modeOnDemandHint: string
+  unavailable: string
+  save: string
+  saving: string
+  saveSuccess: string
+}
+
+const DEFAULT_LABELS: TranscriptionSettingsFormLabels = {
+  sectionTitle: 'Transcrição de áudio',
+  enabled: 'Transcrever notas de voz',
+  enabledHint: 'Converte o áudio do cliente em texto, que o atendente lê e copia direto da conversa.',
+  modeTitle: 'Quando transcrever',
+  modeAuto: 'Automaticamente',
+  modeAutoHint: 'Toda nota de voz recebida é transcrita na hora. Mais cômodo, consome mais cota.',
+  modeOnDemand: 'Quando o atendente pedir',
+  modeOnDemandHint: 'Transcreve só ao clicar no botão da conversa. Consome cota apenas com áudio que alguém vai ler.',
+  unavailable: 'Transcrição não está disponível neste ambiente — fale com quem administra a instalação.',
+  save: 'Salvar',
+  saving: 'Salvando...',
+  saveSuccess: 'Configuração de transcrição salva.',
+}
+
+export interface TranscriptionSettingsFormProps {
+  enabled: boolean
+  onEnabledChange: (value: boolean) => void
+  mode: TranscriptionMode
+  onModeChange: (value: TranscriptionMode) => void
+  onSave: (event: FormEvent) => void
+  /**
+   * A capacidade existe no servidor (engine e credencial configurados)?
+   *
+   * Distinto de `enabled`: isto é "o ambiente consegue", aquilo é "esta empresa quer". Sem a
+   * distinção, um lojista ligaria o interruptor num ambiente sem engine e concluiria que o produto
+   * está quebrado — o texto nunca apareceria e nada explicaria por quê.
+   */
+  isAvailable?: boolean
+  saving?: boolean
+  saveSuccess?: boolean
+  labels?: Partial<TranscriptionSettingsFormLabels>
+}
+
+/**
+ * Interruptor de transcrição por empresa, para a tela de configurações.
+ *
+ * Puramente apresentacional, como os outros forms daqui: quem persiste é o host. O pacote não sabe a
+ * rota, e a política vive nas configurações do módulo (`settings.transcriptionEnabled`), não em
+ * variável de ambiente — mudar de ideia sobre transcrever não deveria exigir deploy.
+ */
+export function TranscriptionSettingsForm({
+  enabled,
+  onEnabledChange,
+  mode,
+  onModeChange,
+  onSave,
+  isAvailable = true,
+  saving = false,
+  saveSuccess = false,
+  labels: labelsOverride,
+}: TranscriptionSettingsFormProps) {
+  const labels = { ...DEFAULT_LABELS, ...labelsOverride }
+
+  return (
+    <section className="bg-white dark:bg-gray-800 rounded-xl border border-gray-200 dark:border-gray-700 overflow-hidden">
+      <div className="px-6 py-4 border-b border-gray-100 dark:border-gray-700">
+        <h2 className="text-sm font-semibold text-gray-900 dark:text-gray-100 flex items-center gap-1.5">
+          <AudioLines size={14} className="text-blue-600 dark:text-blue-400" />
+          {labels.sectionTitle}
+        </h2>
+      </div>
+
+      <form onSubmit={onSave} className="p-6 space-y-5">
+        {!isAvailable && (
+          <div className="bg-amber-50 dark:bg-amber-950/40 border border-amber-200 dark:border-amber-800 rounded-xl px-4 py-3 text-sm text-amber-800 dark:text-amber-300">
+            {labels.unavailable}
+          </div>
+        )}
+
+        <label className="flex items-start gap-3 cursor-pointer">
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={(event) => onEnabledChange(event.target.checked)}
+            disabled={!isAvailable}
+            className="mt-0.5 h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500 disabled:opacity-50"
+          />
+          <span>
+            <span className="block text-sm font-medium text-gray-700 dark:text-gray-300">{labels.enabled}</span>
+            <span className="block text-xs text-gray-500 dark:text-gray-400">{labels.enabledHint}</span>
+          </span>
+        </label>
+
+        {/* O modo só aparece quando ligado: escolher "quando transcrever" sem transcrever nada é uma
+            pergunta sem consequência, e ler as duas opções gasta atenção do operador à toa. */}
+        {enabled && (
+          <fieldset disabled={!isAvailable} className="space-y-2.5">
+            <legend className="text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">{labels.modeTitle}</legend>
+
+            <ModeOption
+              value="onDemand"
+              current={mode}
+              onSelect={onModeChange}
+              title={labels.modeOnDemand}
+              hint={labels.modeOnDemandHint}
+            />
+            <ModeOption
+              value="auto"
+              current={mode}
+              onSelect={onModeChange}
+              title={labels.modeAuto}
+              hint={labels.modeAutoHint}
+            />
+          </fieldset>
+        )}
+
+        {saveSuccess && (
+          <div className="bg-green-50 dark:bg-green-950/40 border border-green-200 dark:border-green-800 rounded-xl px-4 py-3 text-sm text-green-700 dark:text-green-400">
+            {labels.saveSuccess}
+          </div>
+        )}
+
+        <div className="flex justify-end">
+          <button
+            type="submit"
+            disabled={saving || !isAvailable}
+            className="flex items-center gap-2 bg-blue-600 hover:bg-blue-700 disabled:bg-blue-400 text-white font-semibold px-5 py-2.5 rounded-xl transition-colors text-sm"
+          >
+            {saving ? (
+              <span className="w-4 h-4 border-2 border-white/40 border-t-white rounded-full animate-spin" />
+            ) : (
+              <Save size={14} />
+            )}
+            {saving ? labels.saving : labels.save}
+          </button>
+        </div>
+      </form>
+    </section>
+  )
+}
+
+function ModeOption({
+  value,
+  current,
+  onSelect,
+  title,
+  hint,
+}: {
+  value: TranscriptionMode
+  current: TranscriptionMode
+  onSelect: (value: TranscriptionMode) => void
+  title: string
+  hint: string
+}) {
+  const isSelected = current === value
+
+  return (
+    <label
+      className={`flex items-start gap-3 cursor-pointer rounded-xl border px-4 py-3 transition-colors ${
+        isSelected
+          ? 'border-blue-500 bg-blue-50 dark:border-blue-500 dark:bg-blue-950/30'
+          : 'border-gray-200 hover:border-gray-300 dark:border-gray-700 dark:hover:border-gray-600'
+      }`}
+    >
+      <input
+        type="radio"
+        name="transcription-mode"
+        value={value}
+        checked={isSelected}
+        onChange={() => onSelect(value)}
+        className="mt-0.5 h-4 w-4 border-gray-300 text-blue-600 focus:ring-blue-500"
+      />
+      <span>
+        <span className="block text-sm font-medium text-gray-700 dark:text-gray-300">{title}</span>
+        <span className="block text-xs text-gray-500 dark:text-gray-400">{hint}</span>
+      </span>
+    </label>
+  )
+}