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

package/src/preview/createPreviewWebhookClient.ts

@@ -6,24 +6,59 @@
  * Assina com WebCrypto porque `node:crypto` não existe no navegador. Os builders vêm dos contratos
  * (isomórficos) justamente para que o mesmo payload seja montado nos dois runtimes.
  *
- * ⚠️ Isto carrega o app secret de DESENVOLVIMENTO no bundle. Só existe para o docker local, e
- * `assertPreviewEnvironment` recusa rodar em produção — um segredo de dev vazado é irrelevante,
- * mas o hábito de embarcar segredo em frontend não é.
+ * ⚠️ SOMENTE EXECUÇÃO LOCAL. Isto carrega o app secret no bundle, e bundle é público onde quer que
+ * seja servido — em qualquer ambiente com URL acessível (homologação inclusive) usar esta fábrica
+ * equivale a publicar o segredo, e quem o tiver forja webhooks válidos daquele app da Meta: injeta
+ * mensagem de qualquer número e dispara os fluxos. `assertPreviewEnvironment` barra produção, mas
+ * homologação passaria, então a barreira não basta.
+ *
+ * Para qualquer ambiente publicado use `createPreviewBridgeClient`: o navegador manda a intenção e
+ * o servidor assina com o segredo que ele já tem.
  */
 
 import {
   buildInboundAudioPayload,
   buildInboundInteractivePayload,
+  buildInboundMediaPayload,
   buildInboundTextPayload,
   serializeWebhookPayload,
+  type InboundMediaType,
   type InteractiveReplyOption,
 } from '@adatechnology/meta-whatsapp-contracts/testing'
+import { createPreviewMediaUploader, type PreviewUploadedMedia } from './createPreviewMediaUploader'
 
 export type PreviewWebhookClient = {
   sendText(text: string): Promise<void>
   sendButtonReply(reply: InteractiveReplyOption): Promise<void>
   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 = {
+  readonly mediaType: InboundMediaType
+  /**
+   * Id que o host já usa para buscar o arquivo. Não é bytes: o webhook da Meta entrega mídia por
+   * referência, e o consumidor baixa depois — mandar base64 aqui simularia um payload que a Meta
+   * nunca produz, e o caminho testado deixaria de ser o de produção.
+   */
+  readonly mediaId: string
+  readonly mimeType?: string
+  readonly filename?: string
+  readonly caption?: string
 }
 
 export type CreatePreviewWebhookClientParams = {
@@ -31,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.')
@@ -57,7 +107,15 @@ export function assertPreviewEnvironment(isProduction: boolean): void {
   if (isProduction) throw new PreviewInProductionError()
 }
 
-async function signWithWebCrypto(params: { rawBody: string; appSecret: string }): Promise<string> {
+/**
+ * Assina um texto qualquer com o app secret, no mesmo formato do header da Meta.
+ *
+ * Exportada porque o preview precisa provar identidade em MAIS de um lugar: além de entregar a
+ * mensagem no webhook, ele lê o transcript de volta — e ler pela API de admin exigia uma sessão que
+ * a aba do simulador não tem. Assinar a leitura com o segredo que ele já carrega resolve sem token
+ * de admin e sem rota aberta.
+ */
+export async function signPreviewPayload(params: { rawBody: string; appSecret: string }): Promise<string> {
   const encoder = new TextEncoder()
   const key = await globalThis.crypto.subtle.importKey(
     'raw',
@@ -71,6 +129,55 @@ async function signWithWebCrypto(params: { rawBody: string; appSecret: string })
   return `sha256=${[...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, '0')).join('')}`
 }
 
+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
@@ -88,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 {
@@ -95,5 +216,7 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     sendButtonReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, buttonReply: reply })),
     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

@@ -23,18 +23,48 @@ export type { CreateMockConversationsApiParams } from './createMockConversations
 export { createMockSSEProvider } from './createMockSSEProvider'
 export type { CreateMockSSEProviderParams } from './createMockSSEProvider'
 
-export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES } from './previewFixtures'
+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 type { ConversationPreviewProps } from './ConversationPreview'
+export { mediaTypeOf } from './ConversationPreview'
+export type { ConversationPreviewProps, PreviewUploadedMedia } from './ConversationPreview'
+
+export { AudioRecorderButton, DEFAULT_AUDIO_RECORDER_BUTTON_LABELS } from '../AudioRecorderButton'
+export type { AudioRecorderButtonProps, AudioRecorderButtonLabels } from '../AudioRecorderButton'
 
 export {
   createPreviewWebhookClient,
+  signPreviewPayload,
   assertPreviewEnvironment,
   PreviewInProductionError,
   PreviewWebhookRejectedError,
+  PreviewMediaUploadRejectedError,
+  createPreviewMediaPoster,
+  DEFAULT_MEDIA_UPLOAD_PATH,
+} from './createPreviewWebhookClient'
+export type {
+  PreviewWebhookClient,
+  CreatePreviewWebhookClientParams,
+  SendPreviewMediaParams,
 } from './createPreviewWebhookClient'
-export type { PreviewWebhookClient, CreatePreviewWebhookClientParams } from './createPreviewWebhookClient'
+
+export { createPreviewBridgeClient, PreviewBridgeRejectedError } from './createPreviewBridgeClient'
+export type {
+  CreatePreviewBridgeClientParams,
+  PreviewInboundCommand,
+  SendPreviewInboundCommand,
+} from './createPreviewBridgeClient'
 
 export { startPreviewScript, DEFAULT_PREVIEW_SCRIPT } from './startPreviewScript'
 export type { PreviewScriptStep, StartPreviewScriptParams } from './startPreviewScript'
+export { PREVIEW_FILE_SAMPLES, resolvePreviewFileSample } from './previewFileSamples'
+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/mediaTypeOf.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'bun:test'
+import { mediaTypeOf } from './ConversationPreview'
+
+describe('mediaTypeOf', () => {
+  it('deriva imagem, vídeo e áudio pelo prefixo do MIME', () => {
+    expect(mediaTypeOf('image/jpeg')).toBe('image')
+    expect(mediaTypeOf('video/mp4')).toBe('video')
+    expect(mediaTypeOf('audio/webm')).toBe('audio')
+  })
+
+  it('trata o resto como documento, inclusive MIME desconhecido', () => {
+    expect(mediaTypeOf('application/pdf')).toBe('document')
+    expect(mediaTypeOf('')).toBe('document')
+  })
+})

package/src/preview/mockDocumentsSearch.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Guarda a busca da biblioteca no mock — que é a implementação de referência da UI do SDK e tem de
+ * casar com o `companyDocumentSearch` do backend, senão o preview ensina um comportamento que a
+ * tela real não entrega.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { createMockConversationsApi } from './createMockConversationsApi'
+import { createPreviewStore } from './previewStore'
+import { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES } from './previewFixtures'
+
+function buildApi() {
+  const store = createPreviewStore({ conversations: PREVIEW_CONVERSATIONS, messages: PREVIEW_MESSAGES })
+  return createMockConversationsApi({ store })
+}
+
+async function search(term: string): Promise<{ total: number; conversations: string[] }> {
+  const page = await buildApi().getAllDocuments!({ search: term })
+  return { total: page.total, conversations: [...new Set(page.documents.map((document) => document.conversationId))] }
+}
+
+describe('busca da biblioteca no mock', () => {
+  it('acha por nome do arquivo', async () => {
+    const result = await search('contrato')
+
+    expect(result.total).toBe(1)
+  })
+
+  it('acha por telefone da conversa', async () => {
+    const porNumero = await search('94444')
+
+    expect(porNumero.conversations).toEqual(['5511944443333'])
+    expect(porNumero.total).toBeGreaterThan(0)
+    // Discrimina de verdade: 98888 é conversa que existe nas fixtures, mas sem arquivo — se o
+    // predicado do telefone não estivesse valendo, esta busca devolveria a biblioteca inteira.
+    expect((await search('98888')).total).toBe(0)
+  })
+
+  // O caso real: o atendente copia o número como a tela o mostra.
+  it('acha com o telefone formatado, como aparece na tela', async () => {
+    const cru = await search('5511944443333')
+    const formatado = await search('+55 (11) 94444-3333')
+
+    expect(formatado.total).toBe(cru.total)
+    expect(formatado.total).toBeGreaterThan(0)
+  })
+
+  it('não devolve nada para número de outra conversa', async () => {
+    expect((await search('99999999999')).total).toBe(0)
+  })
+
+  // Sem dígito, o predicado do telefone não existe — senão qualquer palavra casaria toda conversa.
+  it('termo sem dígito filtra só por nome', async () => {
+    expect((await search('zzz-inexistente')).total).toBe(0)
+  })
+})

package/src/preview/preview.test.ts

@@ -145,8 +145,10 @@ describe('createMockConversationsApi', () => {
     const firstPage = await api.fetchConversations({ page: 1, limit: 2 })
     const waiting = await api.fetchConversations({ waitingHuman: true })
 
-    expect(firstPage).toHaveLength(2)
-    expect(waiting.every((conversation) => conversation.waitingHuman)).toBe(true)
+    expect(firstPage.conversations).toHaveLength(2)
+    // O total conta o conjunto filtrado inteiro, não a fatia — é o que a paginação da UI lê.
+    expect(firstPage.total).toBeGreaterThan(2)
+    expect(waiting.conversations.every((conversation) => conversation.waitingHuman)).toBe(true)
   })
 
   it('markRead zera as não-lidas vistas pela lista', async () => {
@@ -156,7 +158,7 @@ describe('createMockConversationsApi', () => {
     await api.markRead(BOT_CONVERSATION_ID)
     const conversations = await api.fetchConversations()
 
-    expect(conversations.find((item) => item.id === BOT_CONVERSATION_ID)?.unread).toBe(0)
+    expect(conversations.conversations.find((item) => item.id === BOT_CONVERSATION_ID)?.unread).toBe(0)
   })
 })
 

package/src/preview/previewFileSamples.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Guarda que o preview entrega arquivo do tipo que promete.
+ *
+ * O defeito que motivou o arquivo: `getDocumentUrl` devolvia sempre a mesma imagem PNG, então
+ * "visualizar" num PDF abria um PNG rotulado `application/pdf` e o leitor dizia que o arquivo era
+ * inválido. Aqui os bytes são decodificados e conferidos pela assinatura de cada formato — teste que
+ * só olhasse o prefixo da data URL passaria com o bug de volta.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { PREVIEW_FILE_SAMPLES, resolvePreviewFileSample } from './previewFileSamples'
+import { PREVIEW_DOCUMENTS } from './previewFixtures'
+
+function decode(dataUrl: string): { mimeType: string; bytes: Uint8Array } {
+  const [head, payload] = dataUrl.split(',')
+  const mimeType = head!.replace(/^data:/, '').replace(/;base64$/, '')
+  if (!head!.endsWith(';base64')) {
+    return { mimeType, bytes: new TextEncoder().encode(decodeURIComponent(payload!)) }
+  }
+  return { mimeType, bytes: Uint8Array.from(atob(payload!), (char) => char.charCodeAt(0)) }
+}
+
+function startsWith(bytes: Uint8Array, signature: readonly number[], offset = 0): boolean {
+  return signature.every((byte, index) => bytes[offset + index] === byte)
+}
+
+const ascii = (text: string): number[] => [...text].map((char) => char.charCodeAt(0))
+
+// Assinatura real de cada formato, não o rótulo do mimeType.
+const SIGNATURES: Record<string, (bytes: Uint8Array) => boolean> = {
+  'application/pdf': (bytes) => startsWith(bytes, ascii('%PDF-')),
+  'image/png': (bytes) => startsWith(bytes, [0x89, 0x50, 0x4e, 0x47]),
+  'image/jpeg': (bytes) => startsWith(bytes, [0xff, 0xd8, 0xff]),
+  'image/webp': (bytes) => startsWith(bytes, ascii('RIFF')) && startsWith(bytes, ascii('WEBP'), 8),
+  'video/mp4': (bytes) => startsWith(bytes, ascii('ftyp'), 4),
+  'audio/mp4': (bytes) => startsWith(bytes, ascii('ftyp'), 4),
+  // ID3 quando há tag, ou o sync do primeiro frame MPEG.
+  'audio/mpeg': (bytes) => startsWith(bytes, ascii('ID3')) || (bytes[0] === 0xff && (bytes[1]! & 0xe0) === 0xe0),
+  'audio/ogg': (bytes) => startsWith(bytes, ascii('OggS')),
+  'audio/aac': (bytes) => bytes[0] === 0xff && (bytes[1]! & 0xf0) === 0xf0,
+  'text/plain': (bytes) => bytes.length > 0,
+  'text/csv': (bytes) => bytes.length > 0,
+  // Todo pacote Office é zip: assinatura PK\x03\x04.
+  'application/zip': (bytes) => startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]),
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': (bytes) =>
+    startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]),
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': (bytes) =>
+    startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]),
+}
+
+describe('amostras de arquivo do preview', () => {
+  it('toda amostra declara o mimeType que anuncia', () => {
+    for (const [mimeType, dataUrl] of Object.entries(PREVIEW_FILE_SAMPLES)) {
+      expect(decode(dataUrl).mimeType).toBe(mimeType)
+    }
+  })
+
+  for (const [mimeType, isValid] of Object.entries(SIGNATURES)) {
+    it(`os bytes de ${mimeType} são realmente desse formato`, () => {
+      const sample = PREVIEW_FILE_SAMPLES[mimeType]
+      expect(sample).toBeDefined()
+      expect(isValid(decode(sample!).bytes)).toBe(true)
+    })
+  }
+
+  // O PDF sem xref/startxref é o caso que alguns leitores recusam de cara.
+  it('o PDF tem tabela xref e termina em %%EOF', () => {
+    const text = new TextDecoder().decode(decode(PREVIEW_FILE_SAMPLES['application/pdf']!).bytes)
+
+    expect(text).toContain('\nxref\n')
+    expect(text).toContain('startxref')
+    expect(text.trimEnd().endsWith('%%EOF')).toBe(true)
+  })
+})
+
+describe('resolvePreviewFileSample', () => {
+  it('descarta parâmetro do mimeType — áudio de WhatsApp chega com codecs', () => {
+    expect(resolvePreviewFileSample('audio/ogg; codecs=opus')).toBe(PREVIEW_FILE_SAMPLES['audio/ogg'])
+  })
+
+  // Tipos aceitos pela Meta sem amostra local (sem encoder amr/3gp nesta máquina): tocam pela
+  // família, em vez de devolver bytes de outro formato.
+  it('cai na família quando não há amostra do tipo exato', () => {
+    expect(resolvePreviewFileSample('audio/amr')).toBe(PREVIEW_FILE_SAMPLES['audio/mpeg'])
+    expect(resolvePreviewFileSample('video/3gp')).toBe(PREVIEW_FILE_SAMPLES['video/mp4'])
+    expect(resolvePreviewFileSample('image/heic')).toBe(PREVIEW_FILE_SAMPLES['image/png'])
+  })
+
+  // Office legado é OLE2, não zip: servir o docx aqui daria arquivo corrompido no Word. Melhor um
+  // texto que abre e se explica.
+  it('explica em texto quando não há como forjar o binário', () => {
+    const resolved = resolvePreviewFileSample('application/msword', 'procuracao.doc')
+
+    expect(resolved.startsWith('data:text/plain')).toBe(true)
+    expect(decodeURIComponent(resolved)).toContain('procuracao.doc')
+  })
+
+  it('não devolve vazio para tipo desconhecido', () => {
+    expect(resolvePreviewFileSample(undefined).length).toBeGreaterThan(0)
+    expect(resolvePreviewFileSample('application/octet-stream').length).toBeGreaterThan(0)
+  })
+})
+
+describe('biblioteca do preview', () => {
+  // A infidelidade que existia: a biblioteca listava só `document`, enquanto o backend linka as
+  // cinco espécies de mídia. Foto, vídeo, áudio e sticker apareciam na tela real e não no preview.
+  it('lista foto, vídeo, áudio e sticker junto dos documentos', () => {
+    const mimeTypes = (PREVIEW_DOCUMENTS['5511944443333'] ?? []).map((document) => document.mimeType)
+
+    expect(mimeTypes.some((mimeType) => mimeType.startsWith('image/'))).toBe(true)
+    expect(mimeTypes.some((mimeType) => mimeType.startsWith('video/'))).toBe(true)
+    expect(mimeTypes.some((mimeType) => mimeType.startsWith('audio/'))).toBe(true)
+    expect(mimeTypes).toContain('image/webp')
+  })
+
+  // Cada tipo que a Cloud API da Meta aceita para envio de mídia.
+  const ACCEPTED_BY_META = [
+    'image/jpeg',
+    'image/png',
+    'image/webp',
+    'video/mp4',
+    'video/3gp',
+    'audio/aac',
+    'audio/amr',
+    'audio/mpeg',
+    'audio/mp4',
+    'audio/ogg',
+    'application/pdf',
+    'application/msword',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.ms-excel',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    'application/vnd.ms-powerpoint',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    'text/plain',
+  ]
+
+  it('cobre todo tipo aceito pela Meta', () => {
+    const present = new Set((PREVIEW_DOCUMENTS['5511944443333'] ?? []).map((document) => document.mimeType))
+    const faltando = ACCEPTED_BY_META.filter((mimeType) => !present.has(mimeType))
+
+    expect(faltando).toEqual([])
+  })
+
+  it('todo item da biblioteca abre com bytes não vazios', () => {
+    for (const document of PREVIEW_DOCUMENTS['5511944443333'] ?? []) {
+      expect(decode(resolvePreviewFileSample(document.mimeType, document.filename)).bytes.length).toBeGreaterThan(0)
+    }
+  })
+})

package/src/preview/previewFileSamples.ts

@@ -0,0 +1,74 @@
+/**
+ * Bytes de verdade para o preview abrir.
+ *
+ * O mock antes devolvia a MESMA imagem PNG para qualquer documento, então clicar em "visualizar" num
+ * PDF entregava um PNG rotulado `application/pdf` e o leitor dizia que o arquivo era inválido. Cada
+ * amostra aqui é um arquivo mínimo porém legítimo do seu tipo: as de mídia foram geradas com ffmpeg
+ * e conferidas com ffprobe, o PDF tem xref/startxref/%%EOF, e os pacotes Office são zips com as
+ * partes obrigatórias (`[Content_Types].xml`, `_rels/.rels`, o documento).
+ *
+ * Não há amostra de `audio/amr`, `video/3gp` nem dos formatos binários legados do Office
+ * (`application/msword`, `application/vnd.ms-excel`, `application/vnd.ms-powerpoint`): não há
+ * encoder para eles nesta máquina e forjar OLE2 à mão daria arquivo corrompido — exatamente o que
+ * este módulo existe para evitar. Esses caem no texto explicativo de `resolvePreviewFileSample`,
+ * que abre sem erro e diz o que é.
+ *
+ * GERADO — não editar à mão.
+ */
+
+export const PREVIEW_FILE_SAMPLES: Readonly<Record<string, string>> = {
+  'application/pdf':
+    'data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9NZWRpYUJveFswIDAgMjYwIDExMF0vQ29udGVudHMgNCAwIFIvUmVzb3VyY2VzPDwvRm9udDw8L0YxIDUgMCBSPj4+Pj4+ZW5kb2JqCjQgMCBvYmo8PC9MZW5ndGggNjI+PnN0cmVhbQpCVCAvRjEgMTMgVGYgMTggNTUgVGQgKERvY3VtZW50byBkZSBleGVtcGxvIGRvIHByZXZpZXcpIFRqIEVUCmVuZHN0cmVhbWVuZG9iago1IDAgb2JqPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTEvQmFzZUZvbnQvSGVsdmV0aWNhPj5lbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTIgMDAwMDAgbiAKMDAwMDAwMDEwMSAwMDAwMCBuIAowMDAwMDAwMjExIDAwMDAwIG4gCjAwMDAwMDAzMTcgMDAwMDAgbiAKdHJhaWxlcjw8L1NpemUgNi9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjM3OAolJUVPRgo=',
+  'image/png':
+    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAIAAADYYG7QAAAACXBIWXMAAAABAAAAAQBPJcTWAAAATElEQVR4nO3OMRHAIAAAMbhDWo2hCYPdu/xIh0RB5rPP+JN1O/AlVISKUBEqQkWoCBWhIlSEilARKkJFqAgVoSJUhIpQESpCRagIlRcgDwI25HmPQAAAAABJRU5ErkJggg==',
+  'image/jpeg':
+    'data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAAQABAAD//gAQTGF2YzYyLjExLjEwMAD/2wBDAAgEBAQEBAUFBQUFBQYGBgYGBgYGBgYGBgYHBwcICAgHBwcGBgcHCAgICAkJCQgICAgJCQoKCgwMCwsODg4RERT/xABMAAEBAAAAAAAAAAAAAAAAAAAABAEBAQAAAAAAAAAAAAAAAAAAAAYQAQAAAAAAAAAAAAAAAAAAAAARAQAAAAAAAAAAAAAAAAAAAAD/wAARCAAwADADASIAAhEAAxEA/9oADAMBAAIRAxEAPwCUBRpwAAAAAAAAAAAAAAAB/9k=',
+  'image/webp': 'data:image/webp;base64,UklGRhoAAABXRUJQVlA4TA0AAAAvAAAAEAcQERGIiP4HAA==',
+  'video/mp4':
+    'data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAANdbW9vdgAAAGxtdmhkAAAAAAAAAAAAAAAAAAAD6AAAASwAAQAAAQAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAoh0cmFrAAAAXHRraGQAAAADAAAAAAAAAAAAAAABAAAAAAAAASwAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAEAAAABAAAAAAAAkZWR0cwAAABxlbHN0AAAAAAAAAAEAAAEsAAAIAAABAAAAAAIAbWRpYQAAACBtZGhkAAAAAAAAAAAAAAAAAAAoAAAAEABVxAAAAAAALWhkbHIAAAAAAAAAAHZpZGUAAAAAAAAAAAAAAABWaWRlb0hhbmRsZXIAAAABq21pbmYAAAAUdm1oZAAAAAEAAAAAAAAAAAAAACRkaW5mAAAAHGRyZWYAAAAAAAAAAQAAAAx1cmwgAAAAAQAAAWtzdGJsAAAAv3N0c2QAAAAAAAAAAQAAAK9hdmMxAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAEAAQABIAAAASAAAAAAAAAABFUxhdmM2Mi4xMS4xMDAgbGlieDI2NAAAAAAAAAAAAAAAGP//AAAANWF2Y0MBZAAK/+EAGGdkAAqs2UQmwEQAAAMABAAAAwBQPEiWWAEABmjr48siwP34+AAAAAAQcGFzcAAAAAEAAAABAAAAFGJ0cnQAAAAAAABO2gAAAAAAAAAYc3R0cwAAAAAAAAABAAAAAwAABAAAAAAUc3RzcwAAAAAAAAABAAAAAQAAAChjdHRzAAAAAAAAAAMAAAABAAAIAAAAAAEAAAwAAAAAAQAABAAAAAAcc3RzYwAAAAAAAAABAAAAAQAAAAMAAAABAAAAIHN0c3oAAAAAAAAAAAAAAAMAAALbAAAADgAAAAwAAAAUc3RjbwAAAAAAAAABAAADjQAAAGF1ZHRhAAAAWW1ldGEAAAAAAAAAIWhkbHIAAAAAAAAAAG1kaXJhcHBsAAAAAAAAAAAAAAAALGlsc3QAAAAkqXRvbwAAABxkYXRhAAAAAQAAAABMYXZmNjIuMy4xMDAAAAAIZnJlZQAAAv1tZGF0AAACrgYF//+q3EXpvebZSLeWLNgg2SPu73gyNjQgLSBjb3JlIDE2NSByMzIyMiBiMzU2MDVhIC0gSC4yNjQvTVBFRy00IEFWQyBjb2RlYyAtIENvcHlsZWZ0IDIwMDMtMjAyNSAtIGh0dHA6Ly93d3cudmlkZW9sYW4ub3JnL3gyNjQuaHRtbCAtIG9wdGlvbnM6IGNhYmFjPTEgcmVmPTMgZGVibG9jaz0xOjA6MCBhbmFseXNlPTB4MzoweDExMyBtZT1oZXggc3VibWU9NyBwc3k9MSBwc3lfcmQ9MS4wMDowLjAwIG1peGVkX3JlZj0xIG1lX3JhbmdlPTE2IGNocm9tYV9tZT0xIHRyZWxsaXM9MSA4eDhkY3Q9MSBjcW09MCBkZWFkem9uZT0yMSwxMSBmYXN0X3Bza2lwPTEgY2hyb21hX3FwX29mZnNldD0tMiB0aHJlYWRzPTIgbG9va2FoZWFkX3RocmVhZHM9MSBzbGljZWRfdGhyZWFkcz0wIG5yPTAgZGVjaW1hdGU9MSBpbnRlcmxhY2VkPTAgYmx1cmF5X2NvbXBhdD0wIGNvbnN0cmFpbmVkX2ludHJhPTAgYmZyYW1lcz0zIGJfcHlyYW1pZD0yIGJfYWRhcHQ9MSBiX2JpYXM9MCBkaXJlY3Q9MSB3ZWlnaHRiPTEgb3Blbl9nb3A9MCB3ZWlnaHRwPTIga2V5aW50PTI1MCBrZXlpbnRfbWluPTEwIHNjZW5lY3V0PTQwIGludHJhX3JlZnJlc2g9MCByY19sb29rYWhlYWQ9NDAgcmM9Y3JmIG1idHJlZT0xIGNyZj0yMy4wIHFjb21wPTAuNjAgcXBtaW49MCBxcG1heD02OSBxcHN0ZXA9NCBpcF9yYXRpbz0xLjQwIGFxPTE6MS4wMACAAAAAJWWIhAA///7mdfgUoKykhh+DdK6xVynnAWznTQ4fVSgMZ1FwY28AAAAKQZoibEN//qePiAAAAAgBnkF5Df8HfQ==',
+  'audio/mpeg':
+    'data:audio/mpeg;base64,SUQzBAAAAAAAIlRTU0UAAAAOAAADTGF2ZjYyLjMuMTAwAAAAAAAAAAAAAAD/40jAAAAAAAAAAAAASW5mbwAAAA8AAAAFAAAGwABVVVVVVVVVVVVVVVVVVVVVVVVVgICAgICAgICAgICAgICAgICAgICqqqqqqqqqqqqqqqqqqqqqqqqqqtXV1dXV1dXV1dXV1dXV1dXV1dXV//////////////////////////8AAAAATGF2YzYyLjExAAAAAAAAAAAAAAAAJALAAAAAAAAABsDR4nNFAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD/40jEAAAAA0gAAAAATEFNRTMuMTAwVVVVVVVVVVVVVVVMQU1FMy4xMDBVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVX/40jEAAAAA0gAAAAATEFNRTMuMTAwVVVVVVVVVVVVVVVMQU1FMy4xMDBVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVX/40jEAAAAA0gAAAAATEFNRTMuMTAwVVVVVVVVVVVVVVVMQU1FMy4xMDBVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVX/40jEAAAAA0gAAAAATEFNRTMuMTAwVVVVVVVVVVVVVVVMQU1FMy4xMDBVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVX/40jEAAAAA0gAAAAATEFNRTMuMTAwVVVVVVVVVVVVVVVMQU1FMy4xMDBVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVU=',
+  'audio/ogg':
+    'data:audio/ogg;base64,T2dnUwACAAAAAAAAAABXDTmmAAAAAKMnDKEBE09wdXNIZWFkAQE4AYC7AAAAAABPZ2dTAAAAAAAAAAAAAFcNOaYBAAAAZlPuKwE9T3B1c1RhZ3MMAAAATGF2ZjYyLjMuMTAwAQAAAB0AAABlbmNvZGVyPUxhdmM2Mi4xMS4xMDAgbGlib3B1c09nZ1MABLgmAAAAAAAAVw05pgIAAAA3uL6lCw8REhISEhISEhISeAvkwTbsxY2MSUaZpCaweAfJcifhROpV8fDA1d3pUmB4B8l5yMlXwKISI/rvZ/NkwOB4B8l5yMlXwKISI/rvZ/NkwOB4B8l5yMlXwKISI/rvZ/NkwOB4B8l5yMlXwKISI/rvZ/NkwOB4B8l5yMlXwKISI/rvZ/NkwOB4B8l5yMlXwKISI/rvZ/NkwOB4B8l5yMlXwKISI/rvZ/NkwOB4B8l5yMlXwKISI/rvZ/NkwOB4B8l5yMlXwKISI/rvZ/NkwOA=',
+  'audio/mp4':
+    'data:audio/mp4;base64,AAAAHGZ0eXBNNEEgAAACAE00QSBpc29taXNvMgAAAAhmcmVlAAAAQW1kYXTeAgBMYXZjNjIuMTEuMTAwAAIwQA4BGCAHARggBwEYIAcBGCAHARggBwEYIAcBGCAHARggBwEYIAcAAAMibW9vdgAAAGxtdmhkAAAAAAAAAAAAAAAAAAAD6AAAAMgAAQAAAQAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAk10cmFrAAAAXHRraGQAAAADAAAAAAAAAAAAAAABAAAAAAAAAMgAAAAAAAAAAAAAAAEBAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAkZWR0cwAAABxlbHN0AAAAAAAAAAEAAADIAAAEAAABAAAAAAHFbWRpYQAAACBtZGhkAAAAAAAAAAAAAAAAAACsRAAAJnRVxAAAAAAALWhkbHIAAAAAAAAAAHNvdW4AAAAAAAAAAAAAAABTb3VuZEhhbmRsZXIAAAABcG1pbmYAAAAQc21oZAAAAAAAAAAAAAAAJGRpbmYAAAAcZHJlZgAAAAAAAAABAAAADHVybCAAAAABAAABNHN0YmwAAABqc3RzZAAAAAAAAAABAAAAWm1wNGEAAAAAAAAAAQAAAAAAAAAAAAEAEAAAAACsRAAAAAAANmVzZHMAAAAAA4CAgCUAAQAEgICAF0AVAAAAAAB9AAAAB/oFgICABRIIVuUABoCAgAECAAAAIHN0dHMAAAAAAAAAAgAAAAkAAAQAAAAAAQAAAnQAAAAcc3RzYwAAAAAAAAABAAAAAQAAAAoAAAABAAAAPHN0c3oAAAAAAAAAAAAAAAoAAAAVAAAABAAAAAQAAAAEAAAABAAAAAQAAAAEAAAABAAAAAQAAAAEAAAAFHN0Y28AAAAAAAAAAQAAACwAAAAac2dwZAEAAAByb2xsAAAAAgAAAAH//wAAABxzYmdwAAAAAHJvbGwAAAABAAAACgAAAAEAAABhdWR0YQAAAFltZXRhAAAAAAAAACFoZGxyAAAAAAAAAABtZGlyYXBwbAAAAAAAAAAAAAAAACxpbHN0AAAAJKl0b28AAAAcZGF0YQAAAAEAAAAATGF2ZjYyLjMuMTAw',
+  'audio/aac':
+    'data:audio/aac;base64,//FQQAOf/N4CAExhdmM2Mi4xMS4xMDAAAjBADv/xUEABf/wBGCAH//FQQAF//AEYIAf/8VBAAX/8ARggB//xUEABf/wBGCAH//FQQAF//AEYIAf/8VBAAX/8ARggB//xUEABf/wBGCAH//FQQAF//AEYIAf/8VBAAX/8ARggBw==',
+  'text/plain': 'data:text/plain;base64,TGlzdGEgZGUgY29tcHJhcwotIGFycm96IDJrZwotIG9sZW8gMXVuCg==',
+  'text/csv': 'data:text/csv;base64,cHJvZHV0byxxdWFudGlkYWRlLHByZWNvCmFycm96LDIsMjQuOTAKb2xlbywxLDcuNTAK',
+  'application/zip':
+    'data:application/zip;base64,UEsDBBQAAAAIANFO/FwtmGOxGwAAABkAAAARAAAAY29tcHJvdmFudGUtMS50eHRLzs8tKMovS8wrSVVISVUoSExPzE3NK8nnAgBQSwMEFAAAAAgA0U78XCftV8YWAAAAFAAAABEAAABjb21wcm92YW50ZS0yLnR4dCtOTS/NS8lXSM7PLSjKL0vMK0nlAgBQSwECFAMUAAAACADRTvxcLZhjsRsAAAAZAAAAEQAAAAAAAAAAAAAAgAEAAAAAY29tcHJvdmFudGUtMS50eHRQSwECFAMUAAAACADRTvxcJ+1XxhYAAAAUAAAAEQAAAAAAAAAAAAAAgAFKAAAAY29tcHJvdmFudGUtMi50eHRQSwUGAAAAAAIAAgB+AAAAjwAAAAAA',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document':
+    'data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,UEsDBBQAAAAIANFO/Fx5bjPX6AAAAK0BAAATAAAAW0NvbnRlbnRfVHlwZXNdLnhtbH1QyU7DMBD9FWuuKHHggBCK0wPLETiUDxjZk8SqN3nc0v49Tlt6QIXjzFv1+tXeO7GjzDYGBbdtB4KCjsaGScHn+rV5AMEFg0EXAyk4EMNq6NeHRCyqNrCCuZT0KCXrmTxyGxOFiowxeyz1zJNMqDc4kbzrunupYygUSlMWDxj6Zxpx64p42df3qUcmxyCeTsQlSwGm5KzGUnG5C+ZXSnNOaKvyyOHZJr6pBJBXExbk74Cz7r0Ok60h8YG5vKGvLPkVs5Em6q2vyvZ/mys94zhaTRf94pZy1MRcF/euvSAebfjpL49zD99QSwMEFAAAAAgA0U78XJv9N+qtAAAAKQEAAAsAAABfcmVscy8ucmVsc43POw7CMAwG4KtE3mlaBoRQ0y4IqSsqB7ASN61oHkrCo7cnAwNFDIy2f3+W6/ZpZnanECdnBVRFCYysdGqyWsClP232wGJCq3B2lgQsFKFt6jPNmPJKHCcfWTZsFDCm5A+cRzmSwVg4TzZPBhcMplwGzT3KK2ri27Lc8fBpwNpknRIQOlUB6xdP/9huGCZJRydvhmz6ceIrkWUMmpKAhwuKq3e7yCzwpuarF5sXUEsDBBQAAAAIANFO/FyraIuoqgAAAOcAAAARAAAAd29yZC9kb2N1bWVudC54bWxFjksOwjAMBa8SZU9TWCBUNWWBxAngAKExbaTGjpzQz+1JyoLNPFt+Grm9rn4SM3B0hFoeq1oKwJ6sw0HL5+N+uEgRk0FrJkLQcoMor127NJb6jwdMIgswNouWY0qhUSr2I3gTKwqA+fYm9ibllQe1ENvA1EOM2e8ndarrs/LGoSzKF9mtZCjggtTdCBObRMKCgBV8mPJIIjDMDpZWlU4h7ww7fx71/7H7AlBLAQIUAxQAAAAIANFO/Fx5bjPX6AAAAK0BAAATAAAAAAAAAAAAAACAAQAAAABbQ29udGVudF9UeXBlc10ueG1sUEsBAhQDFAAAAAgA0U78XJv9N+qtAAAAKQEAAAsAAAAAAAAAAAAAAIABGQEAAF9yZWxzLy5yZWxzUEsBAhQDFAAAAAgA0U78XKtoi6iqAAAA5wAAABEAAAAAAAAAAAAAAIAB7wEAAHdvcmQvZG9jdW1lbnQueG1sUEsFBgAAAAADAAMAuQAAAMgCAAAAAA==',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':
+    'data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,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',
+}
+
+const FAMILY_FALLBACK: Readonly<Record<string, string>> = {
+  image: 'image/png',
+  video: 'video/mp4',
+  audio: 'audio/mpeg',
+  text: 'text/plain',
+}
+
+/**
+ * A data URL que o preview abre para um documento.
+ *
+ * Ordem: tipo exato → família (`audio/amr` toca como mp3, `video/3gp` como mp4) → nota em texto.
+ * A nota fecha o caso dos tipos sem amostra: abre num leitor de texto e explica, em vez de baixar
+ * um binário quebrado com extensão de Word.
+ */
+export function resolvePreviewFileSample(mimeType: string | undefined, filename?: string): string {
+  const normalized = (mimeType ?? '').split(';')[0]!.trim().toLowerCase()
+  const exact = PREVIEW_FILE_SAMPLES[normalized]
+  if (exact) return exact
+
+  const family = FAMILY_FALLBACK[normalized.split('/')[0] ?? '']
+  const byFamily = family ? PREVIEW_FILE_SAMPLES[family] : undefined
+  if (byFamily) return byFamily
+
+  const note = `Preview do SDK: nao existe amostra binaria valida para ${normalized || 'tipo desconhecido'}${
+    filename ? ` (${filename})` : ''
+  }. Na tela real este arquivo vem do storage.`
+  return `data:text/plain;charset=utf-8,${encodeURIComponent(note)}`
+}