@softize/opus 25.7.0 → 26.0.0

package/src/ui/docs/content/composer.md

@@ -63,13 +63,125 @@ render(
 )
 ```
 
+## Com imagens anexadas
+
+Quando a mensagem pode levar imagens, como um print de relatório para a IA reproduzir, passe
+`attachments`. O composer ganha o botão **Anexar imagem** na barra e uma faixa acima do campo, com a
+miniatura, o nome e o estado de cada imagem. Colar uma imagem no campo e soltá-la sobre o composer
+também anexam.
+
+O estado é do aplicativo, porque é ele quem envia e guarda a imagem. O composer faz a triagem e
+entrega os arquivos aceitos em `onAddFiles`; o aplicativo acrescenta cada um à lista como
+`uploading`, prepara a imagem com [`prepareImage`](#preparar-a-imagem-antes-do-envio), envia e muda o
+estado para `ready` ou `failed`. Depois do envio da mensagem, é o aplicativo que limpa a lista e
+revoga os endereços das miniaturas que criou.
+
+```tsx preview col
+const [text, setText] = React.useState('')
+const [items, setItems] = React.useState<ComposerAttachment[]>([])
+const nextId = React.useRef(1)
+const previews = React.useRef<Record<string, string>>({})
+
+// A miniatura é um endereço de objeto, que segura a imagem na memória até ser revogado.
+function release(id: string) {
+  const url = previews.current[id]
+  if (url !== undefined) URL.revokeObjectURL(url)
+  delete previews.current[id]
+}
+React.useEffect(() => () => Object.keys(previews.current).forEach(release), [])
+
+async function add(files: File[]) {
+  for (const file of files) {
+    const id = String(nextId.current++)
+    const prepared = await prepareImage(file)
+    if (!prepared.ok) {
+      setItems((list) => [...list, { id, name: file.name, status: 'failed', error: prepared.message }])
+      continue
+    }
+    previews.current[id] = URL.createObjectURL(prepared.file)
+    setItems((list) => [
+      ...list,
+      { id, name: prepared.file.name, status: 'uploading', previewUrl: previews.current[id] },
+    ])
+    // Aqui o aplicativo envia `prepared.file` ao próprio servidor.
+    await new Promise((r) => setTimeout(r, 800))
+    setItems((list) => list.map((item) => (item.id === id ? { ...item, status: 'ready' } : item)))
+  }
+}
+
+render(
+  <Composer
+    value={text}
+    onChange={setText}
+    onSubmit={() => {
+      items.forEach((item) => release(item.id))
+      setText('')
+      setItems([])
+    }}
+    placeholder="Cole, solte ou anexe um print…"
+    attachments={{
+      items,
+      onAddFiles: (files) => void add(files),
+      onRemove: (id) => {
+        release(id)
+        setItems((list) => list.filter((item) => item.id !== id))
+      },
+    }}
+  />,
+)
+```
+
+O envio passa com texto ou com pelo menos uma imagem pronta. Enquanto alguma imagem está sendo
+enviada, o botão de enviar espera; uma imagem com falha também bloqueia o envio até ser removida ou
+reenviada pelo aplicativo, para que nada do que está na faixa fique de fora sem aviso. Quem usa leitor
+de tela ouve quando uma imagem fica pronta ou falha, e, se o botão de anexar ficar desabilitado ao
+atingir o limite, o foco volta ao campo.
+
+A triagem aceita PNG, JPEG e WebP, até quatro imagens por mensagem; `accept` e `max` mudam esses
+limites. `accept` é um subconjunto desses três formatos, comparado com o tipo exato do arquivo, sem
+curinga como `image/*`. O que fica de fora é explicado acima do campo, como “Cada mensagem aceita até 4 imagens.”.
+Para dar outra explicação, passe `onReject`: o composer deixa de mostrar o aviso e entrega os
+arquivos recusados, com o motivo, ao aplicativo.
+
+Colar texto continua colando texto, mesmo quando a área de transferência também traz uma imagem, como
+ao copiar células de uma planilha. Uma imagem colada sem texto, como um print, recebe um nome que a
+pessoa reconhece na conversa: “Imagem colada 1.png”. A numeração não volta atrás: remover a primeira e
+colar outra dá “Imagem colada 3.png”, e nunca duas imagens com o mesmo nome no mesmo composer.
+
+O soltar que o composer recebe não sobe para os contêineres do aplicativo. Dentro do
+[Chat](/ui/chat#imagens-na-conversa), quem recebe o soltar é a conversa inteira.
+
+## Preparar a imagem antes do envio
+
+`prepareImage(file, options)` deixa a imagem pronta para ir à conversa. Ela lê só o cabeçalho do
+arquivo para conferir o formato, pelos bytes e não pela extensão, e as dimensões; uma foto acima de
+`maxPixels` é recusada antes de ser aberta, porque decodificá-la ocuparia centenas de megabytes de
+memória. Depois, reduz a imagem até o lado maior caber em `maxEdge`, mantendo a proporção e a
+orientação gravada pela câmera, de modo que a foto tirada com o celular em pé chega em pé; e codifica
+a imagem de novo, o que também descarta metadados como a localização. PNG continua PNG quando cabe em `maxBytes`; JPEG, WebP e o PNG que passa do teto viram
+JPEG com qualidade 0,85, sobre fundo branco.
+
+```ts
+const result = await prepareImage(file, { maxEdge: 1568, maxBytes: 3 * 1024 * 1024 })
+if (result.ok) {
+  await upload(result.file) // result.mediaType, result.width, result.height, result.size
+} else {
+  showError(result.message) // "Imagens animadas não são aceitas. Envie uma imagem parada…"
+}
+```
+
+A função não lança erro. Uma imagem fora dos formatos aceitos, animada, ilegível, com pixels demais ou
+que continua acima do teto depois de reduzida volta como `{ ok: false, reason, message }`, com a explicação pronta para a
+pessoa. Os padrões repetem os tetos do primeiro consumidor; passe os do seu produto, de preferência os
+mesmos que o servidor confere.
+
 ## Propriedades de Composer
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `string` | | Texto controlado; o dono do estado é quem compõe. |
 | `onChange` | `(value: string) => void` | | Recebe cada alteração do texto. |
-| `onSubmit` | `() => void` | | Chamado por Enter (sem Shift) ou pelo botão de enviar, somente quando há texto e nem `busy` nem `submitDisabled` estão ativos. |
+| `onSubmit` | `() => void` | | Chamado por Enter (sem Shift) ou pelo botão de enviar, somente quando há texto ou imagem pronta, nenhuma imagem está sendo enviada ou com falha, e nem `busy` nem `submitDisabled` estão ativos. |
 | `onHistoryPrevious` / `onHistoryNext` | `() => boolean` | | Navegação por ↑/↓ no histórico do dono; retorne `true` quando a tecla foi consumida. |
 | `busy` | `boolean` | `false` | Bloqueia o envio enquanto a operação anterior corre e troca o ícone de enviar por um spinner. O campo continua editável. |
 | `submitDisabled` | `boolean` | `false` | Bloqueia o envio por uma condição do consumidor, como um seletor ainda sem escolha. |
@@ -77,4 +189,35 @@ render(
 | `rows` | `number` | `1` | Linhas iniciais do campo, que cresce com o conteúdo até `10rem`. |
 | `autoFocus` | `boolean` | | Foca o campo ao montar. |
 | `actions` | `ReactNode` | | Controles discretos à esquerda do botão de enviar; com eles, o composer passa a ter duas linhas. |
+| `attachments` | `ComposerAttachments` | | Liga as imagens anexadas: botão **Anexar imagem**, faixa acima do campo, colar e soltar. Com ele, o composer passa a ter duas linhas. |
 | `className` | `string` | | Classes aplicadas à moldura do composer. |
+
+## Propriedades de ComposerAttachments
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `items` | `ComposerAttachment[]` | | Imagens anexadas à mensagem que está sendo escrita, na ordem da faixa. |
+| `onAddFiles` | `(files: File[]) => void` | | Recebe os arquivos aceitos pela triagem, vindos do botão, do colar ou do soltar. |
+| `onRemove` | `(id: string) => void` | | A pessoa removeu uma imagem da faixa; o foco volta ao campo. |
+| `max` | `number` | `4` | Limite de imagens por mensagem. O botão de anexar fica desabilitado quando ele é atingido. |
+| `accept` | `readonly AiImageMediaType[]` | PNG, JPEG e WebP | Formatos aceitos pelo botão e pela triagem, comparados com o tipo exato do arquivo. |
+| `onReject` | `(rejections: ComposerFileRejection[]) => void` | | Recebe os arquivos recusados, com o motivo `type` ou `limit`. Sem ele, o composer explica a recusa acima do campo. |
+
+`ComposerAttachment` é `{ id, name, status, previewUrl?, error? }`. `status` vale `uploading`,
+`ready` ou `failed`; `previewUrl` é o endereço da miniatura e `error` é o motivo mostrado quando a
+imagem falha.
+
+## Opções de prepareImage
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `maxEdge` | `number` | `1568` | Lado maior, em pixels, depois da redução. Imagens menores não são ampliadas. |
+| `maxBytes` | `number` | 3 MB | Teto da imagem preparada. Acima dele, o PNG vira `lossyType`; o que continua acima é recusado. |
+| `accept` | `readonly AiImageMediaType[]` | PNG, JPEG e WebP | Formatos aceitos na entrada, conferidos pelos primeiros bytes. |
+| `lossyType` | `'image/jpeg' \| 'image/webp'` | `'image/jpeg'` | Formato de JPEG, WebP e do PNG que passa do teto. |
+| `quality` | `number` | `0.85` | Qualidade da codificação com perdas, de 0 a 1. |
+| `maxPixels` | `number` | `40_000_000` | Teto de largura × altura da imagem original, lido do cabeçalho antes de decodificar. |
+
+O resultado é `{ ok: true, file, mediaType, width, height, size, resized }` ou
+`{ ok: false, reason, message }`, em que `reason` vale `unsupported-type`, `animated`,
+`too-many-pixels`, `too-large` ou `unreadable`.

package/src/ui/lib/prepare-image.ts

@@ -0,0 +1,386 @@
+/**
+ * Preparação de imagem no navegador antes do envio (ADR 0058, seção 6).
+ *
+ * Lê só o cabeçalho para conferir formato, animação e dimensões — e recusar, antes de decodificar,
+ * a imagem grande demais para a memória do navegador —, reduz o lado maior respeitando a orientação
+ * gravada pela câmera e codifica de novo sempre, o que também descarta metadados como a localização.
+ * Os tetos vêm do app; os padrões repetem os da ADR 0122 da Grand Brasil, primeiro consumidor.
+ */
+
+import type { AiImageMediaType } from '../../core/index.ts'
+
+/** Os formatos que a mensagem da IA aceita, na ordem em que são apresentados à pessoa. */
+export const IMAGE_MEDIA_TYPES: readonly AiImageMediaType[] = ['image/png', 'image/jpeg', 'image/webp']
+
+/** Padrões de `prepareImage`. O app deve passar os próprios tetos: o utilitário não decide teto
+ *  de produto. */
+export const PREPARE_IMAGE_DEFAULTS = {
+  /** Lado maior, em pixels, depois da redução (o limite de lado do nível padrão do Claude). */
+  maxEdge: 1568,
+  /** Teto por imagem depois da redução, em bytes (3 MB). */
+  maxBytes: 3 * 1024 * 1024,
+  /** Qualidade da codificação JPEG ou WebP. */
+  quality: 0.85,
+  /** Teto de pixels da imagem original (40 megapixels), conferido pelo cabeçalho antes de
+   *  decodificar: uma foto muito grande ocupa centenas de megabytes de memória ao abrir. */
+  maxPixels: 40_000_000,
+} as const
+
+export interface PrepareImageOptions {
+  /** Lado maior, em pixels, depois da redução. Padrão: 1568. */
+  maxEdge?: number
+  /** Teto em bytes da imagem preparada. Padrão: 3 MB. */
+  maxBytes?: number
+  /** Formatos aceitos na entrada. Padrão: PNG, JPEG e WebP. */
+  accept?: readonly AiImageMediaType[]
+  /** Formato da codificação com perdas, usado para JPEG, WebP e o PNG que passa do teto.
+   *  Padrão: `image/jpeg`. */
+  lossyType?: 'image/jpeg' | 'image/webp'
+  /** Qualidade da codificação com perdas, de 0 a 1. Padrão: 0,85. */
+  quality?: number
+  /** Teto de pixels (largura × altura) da imagem original, lido do cabeçalho antes de
+   *  decodificar. Padrão: 40 megapixels. */
+  maxPixels?: number
+}
+
+export type PrepareImageRejection =
+  | 'unsupported-type'
+  | 'animated'
+  | 'too-many-pixels'
+  | 'too-large'
+  | 'unreadable'
+
+export interface PreparedImage {
+  ok: true
+  /** A imagem preparada, com o nome ajustado à extensão do formato final. */
+  file: File
+  mediaType: AiImageMediaType
+  width: number
+  height: number
+  /** Tamanho em bytes. */
+  size: number
+  /** A imagem foi reduzida para caber em `maxEdge`. */
+  resized: boolean
+}
+
+export interface RejectedImage {
+  ok: false
+  reason: PrepareImageRejection
+  /** Explicação em pt-BR para a pessoa, pronta para a interface. */
+  message: string
+}
+
+export type PrepareImageResult = PreparedImage | RejectedImage
+
+const TYPE_LABELS: Record<string, string> = {
+  'image/png': 'PNG',
+  'image/jpeg': 'JPEG',
+  'image/webp': 'WebP',
+  'image/gif': 'GIF',
+}
+
+const EXTENSIONS: Record<AiImageMediaType, string> = {
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/webp': '.webp',
+}
+
+/** "PNG, JPEG ou WebP" — a lista de formatos aceitos como a pessoa a lê. */
+export function imageTypeList(types: readonly string[]): string {
+  const labels = types.map((type) => TYPE_LABELS[type] ?? type.replace(/^image\//, '').toUpperCase())
+  if (labels.length <= 1) return labels.join('')
+  return `${labels.slice(0, -1).join(', ')} ou ${labels[labels.length - 1]}`
+}
+
+/** "3 MB", "1,5 MB" — tamanho em megabytes como a pessoa o lê. */
+export function formatMegabytes(bytes: number): string {
+  const megabytes = bytes / (1024 * 1024)
+  return `${megabytes.toLocaleString('pt-BR', { maximumFractionDigits: 1 })} MB`
+}
+
+/** Quanto do início do arquivo é lido de uma vez. Basta para o cabeçalho de quase toda imagem;
+ *  o que estiver além (um bloco de metadados grande antes do quadro) é lido por partes. */
+const HEAD_BYTES = 64 * 1024
+
+/** Leitura por faixa, sem carregar o arquivo inteiro: o início fica em memória, o resto vem por
+ *  `slice` só quando a varredura dos blocos chega lá. */
+function byteReader(file: Blob, head: Uint8Array): (offset: number, length: number) => Promise<Uint8Array> {
+  return async (offset, length) => {
+    if (offset + length <= head.length) return head.subarray(offset, offset + length)
+    return new Uint8Array(await file.slice(offset, offset + length).arrayBuffer())
+  }
+}
+
+const ascii = (bytes: Uint8Array, start: number, end: number): string =>
+  String.fromCharCode(...bytes.subarray(start, end))
+const uint16be = (b: Uint8Array, i: number): number => (b[i] << 8) | b[i + 1]
+const uint32be = (b: Uint8Array, i: number): number => ((b[i] << 24) | (b[i + 1] << 16) | (b[i + 2] << 8) | b[i + 3]) >>> 0
+const uint24le = (b: Uint8Array, i: number): number => b[i] | (b[i + 1] << 8) | (b[i + 2] << 16)
+
+interface ImageHeader {
+  /** Formato pelos primeiros bytes; `null` quando não é um formato conhecido. */
+  type: string | null
+  /** Dimensões gravadas no cabeçalho, antes de aplicar a orientação; ausentes quando ilegíveis. */
+  width?: number
+  height?: number
+  animated: boolean
+}
+
+/** O formato real da imagem, pelos primeiros bytes. */
+function sniffType(bytes: Uint8Array): string | null {
+  if (bytes.length >= 8 && bytes[0] === 0x89 && ascii(bytes, 1, 4) === 'PNG') return 'image/png'
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg'
+  if (bytes.length >= 12 && ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 12) === 'WEBP') return 'image/webp'
+  if (bytes.length >= 4 && ascii(bytes, 0, 4) === 'GIF8') return 'image/gif'
+  return null
+}
+
+/** PNG: dimensões no `IHDR`, o primeiro bloco; animação (APNG) é o bloco `acTL` antes do `IDAT`. */
+async function inspectPng(head: Uint8Array, read: ReturnType<typeof byteReader>, size: number): Promise<ImageHeader> {
+  if (head.length < 24 || ascii(head, 12, 16) !== 'IHDR') return { type: 'image/png', animated: false }
+  const header: ImageHeader = { type: 'image/png', width: uint32be(head, 16), height: uint32be(head, 20), animated: false }
+  for (let offset = 8; offset + 8 <= size; ) {
+    const chunk = await read(offset, 8)
+    if (chunk.length < 8) break
+    const type = ascii(chunk, 4, 8)
+    if (type === 'acTL') return { ...header, animated: true }
+    if (type === 'IDAT' || type === 'IEND') break
+    offset += 12 + uint32be(chunk, 0)
+  }
+  return header
+}
+
+/** JPEG: dimensões no primeiro marcador de quadro (SOF0 a SOF15, sem DHT, JPG e DAC), depois dos
+ *  segmentos de aplicação, como o EXIF. */
+async function inspectJpeg(read: ReturnType<typeof byteReader>, size: number): Promise<ImageHeader> {
+  let offset = 2
+  for (let guard = 0; guard < 4096 && offset + 4 <= size; guard++) {
+    const segment = await read(offset, 9)
+    if (segment[0] !== 0xff) break
+    const marker = segment[1]
+    if (marker === 0xff) {
+      offset += 1 // Bytes de preenchimento antes do marcador.
+      continue
+    }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
+      offset += 2
+      continue
+    }
+    if (marker === 0xd9 || marker === 0xda) break // Fim, ou dados da imagem sem quadro declarado.
+    if (segment.length < 4) break
+    const isFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc
+    if (isFrame && segment.length >= 9) {
+      return { type: 'image/jpeg', height: uint16be(segment, 5), width: uint16be(segment, 7), animated: false }
+    }
+    const length = uint16be(segment, 2)
+    if (length < 2) break
+    offset += 2 + length
+  }
+  return { type: 'image/jpeg', animated: false }
+}
+
+/** WebP: dimensões no primeiro bloco (`VP8 `, `VP8L` ou `VP8X`); animação é o bit do `VP8X`. */
+function inspectWebp(head: Uint8Array): ImageHeader {
+  const chunk = head.length >= 16 ? ascii(head, 12, 16) : ''
+  if (chunk === 'VP8X' && head.length >= 30) {
+    return {
+      type: 'image/webp',
+      width: 1 + uint24le(head, 24),
+      height: 1 + uint24le(head, 27),
+      animated: (head[20] & 0x02) !== 0,
+    }
+  }
+  if (chunk === 'VP8 ' && head.length >= 30) {
+    return {
+      type: 'image/webp',
+      width: (head[26] | (head[27] << 8)) & 0x3fff,
+      height: (head[28] | (head[29] << 8)) & 0x3fff,
+      animated: false,
+    }
+  }
+  if (chunk === 'VP8L' && head.length >= 25 && head[20] === 0x2f) {
+    return {
+      type: 'image/webp',
+      width: 1 + (head[21] | ((head[22] & 0x3f) << 8)),
+      height: 1 + ((head[22] >> 6) | (head[23] << 2) | ((head[24] & 0x0f) << 10)),
+      animated: false,
+    }
+  }
+  return { type: 'image/webp', animated: false }
+}
+
+async function inspectHeader(file: Blob): Promise<ImageHeader> {
+  const head = new Uint8Array(await file.slice(0, HEAD_BYTES).arrayBuffer())
+  const type = sniffType(head)
+  const read = byteReader(file, head)
+  if (type === 'image/png') return inspectPng(head, read, file.size)
+  if (type === 'image/jpeg') return inspectJpeg(read, file.size)
+  if (type === 'image/webp') return inspectWebp(head)
+  return { type, animated: false }
+}
+
+/** "48 megapixels", "40,5 megapixels". */
+function formatMegapixels(pixels: number): string {
+  return `${(pixels / 1_000_000).toLocaleString('pt-BR', { maximumFractionDigits: 1 })} megapixels`
+}
+
+function reject(reason: PrepareImageRejection, message: string): RejectedImage {
+  return { ok: false, reason, message }
+}
+
+interface DecodedImage {
+  source: CanvasImageSource
+  width: number
+  height: number
+  release: () => void
+}
+
+/** Decodifica aplicando a orientação gravada pela câmera (EXIF): a foto tirada com o celular em
+ *  pé sai em pé, com largura e altura já trocadas. */
+async function decode(file: Blob): Promise<DecodedImage> {
+  if (typeof globalThis.createImageBitmap === 'function') {
+    let bitmap: ImageBitmap
+    try {
+      bitmap = await globalThis.createImageBitmap(file, { imageOrientation: 'from-image' })
+    } catch (error) {
+      // Navegador anterior ao valor `from-image` recusa a opção com TypeError; o padrão dele
+      // também aplica a orientação do arquivo.
+      if (!(error instanceof TypeError)) throw error
+      bitmap = await globalThis.createImageBitmap(file)
+    }
+    return { source: bitmap, width: bitmap.width, height: bitmap.height, release: () => bitmap.close() }
+  }
+  const url = URL.createObjectURL(file)
+  try {
+    const image = new Image()
+    // `from-image` é o padrão do CSS: dimensões naturais e `drawImage` seguem a orientação.
+    image.style.imageOrientation = 'from-image'
+    image.src = url
+    await image.decode()
+    return { source: image, width: image.naturalWidth, height: image.naturalHeight, release: () => {} }
+  } finally {
+    URL.revokeObjectURL(url)
+  }
+}
+
+type Encoder = (type: AiImageMediaType, quality: number) => Promise<Blob>
+
+/** Prepara o quadro na dimensão final e devolve o codificador. O desenho acontece na primeira
+ *  codificação e só se repete quando o fundo muda: JPEG não tem transparência e, sem fundo, o
+ *  transparente viraria preto. */
+function canvasFor(image: DecodedImage, width: number, height: number): Encoder {
+  const canvas: OffscreenCanvas | HTMLCanvasElement =
+    typeof globalThis.OffscreenCanvas === 'function'
+      ? new OffscreenCanvas(width, height)
+      : Object.assign(document.createElement('canvas'), { width, height })
+  const context = canvas.getContext('2d') as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null
+  if (context === null) throw new Error('canvas 2d indisponível')
+  let painted: 'transparent' | 'white' | null = null
+  const paint = (background: 'transparent' | 'white'): void => {
+    if (painted === background) return
+    context.clearRect(0, 0, width, height)
+    if (background === 'white') {
+      context.fillStyle = '#ffffff'
+      context.fillRect(0, 0, width, height)
+    }
+    context.imageSmoothingQuality = 'high'
+    context.drawImage(image.source, 0, 0, width, height)
+    painted = background
+  }
+  return async (type, quality) => {
+    paint(type === 'image/jpeg' ? 'white' : 'transparent')
+    const blob =
+      'convertToBlob' in canvas
+        ? await canvas.convertToBlob({ type, quality })
+        : await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, type, quality))
+    // Um navegador que não codifica o formato pedido devolve PNG em silêncio.
+    if (blob === null || blob.type !== type) throw new Error(`codificação ${type} indisponível`)
+    return blob
+  }
+}
+
+function renamed(name: string, type: AiImageMediaType): string {
+  const base = name.replace(/\.[^./\\]+$/, '') || 'imagem'
+  return `${base}${EXTENSIONS[type]}`
+}
+
+/**
+ * Prepara uma imagem para ir à conversa: confere o formato pelos bytes, recusa animação, reduz o
+ * lado maior até `maxEdge` e codifica de novo. PNG continua PNG quando cabe em `maxBytes`; o resto
+ * vira `lossyType` (JPEG por padrão) com `quality`. O que continua acima do teto é recusado.
+ *
+ * Nunca lança: uma falha vira `{ ok: false, reason, message }`, com a mensagem pronta para a pessoa.
+ */
+export async function prepareImage(file: Blob & { name?: string }, options: PrepareImageOptions = {}): Promise<PrepareImageResult> {
+  const maxEdge = options.maxEdge ?? PREPARE_IMAGE_DEFAULTS.maxEdge
+  const maxBytes = options.maxBytes ?? PREPARE_IMAGE_DEFAULTS.maxBytes
+  const accept = options.accept ?? IMAGE_MEDIA_TYPES
+  const lossyType = options.lossyType ?? 'image/jpeg'
+  const quality = options.quality ?? PREPARE_IMAGE_DEFAULTS.quality
+  const maxPixels = options.maxPixels ?? PREPARE_IMAGE_DEFAULTS.maxPixels
+  const unreadable = (): RejectedImage =>
+    reject('unreadable', 'Não foi possível abrir esta imagem. Confira o arquivo ou tente outra imagem.')
+
+  let header: ImageHeader
+  try {
+    header = await inspectHeader(file)
+  } catch {
+    return unreadable()
+  }
+
+  const sniffed = header.type
+  if (sniffed === null || !(accept as readonly string[]).includes(sniffed)) {
+    const found = sniffed !== null ? `Esta imagem está em ${TYPE_LABELS[sniffed] ?? sniffed}, formato não aceito. ` : ''
+    return reject('unsupported-type', `${found}Envie uma imagem ${imageTypeList(accept)}.`)
+  }
+  const sourceType = sniffed as AiImageMediaType
+  if (header.animated) {
+    return reject('animated', 'Imagens animadas não são aceitas. Envie uma imagem parada, como um print da tela.')
+  }
+  if (header.width === undefined || header.height === undefined || header.width <= 0 || header.height <= 0) {
+    return unreadable()
+  }
+  const pixels = header.width * header.height
+  if (pixels > maxPixels) {
+    return reject(
+      'too-many-pixels',
+      `A imagem tem ${formatMegapixels(pixels)}, acima do limite de ${formatMegapixels(maxPixels)}. ` +
+        'Reduza a imagem ou envie um recorte antes de anexar.',
+    )
+  }
+
+  let image: DecodedImage
+  try {
+    image = await decode(file)
+  } catch {
+    return unreadable()
+  }
+
+  try {
+    if (image.width <= 0 || image.height <= 0) return unreadable()
+    const scale = Math.min(1, maxEdge / Math.max(image.width, image.height))
+    const width = Math.max(1, Math.round(image.width * scale))
+    const height = Math.max(1, Math.round(image.height * scale))
+    const encode = canvasFor(image, width, height)
+
+    // PNG continua PNG quando cabe no teto; o resto, e o PNG que passa dele, vira `lossyType`.
+    let mediaType: AiImageMediaType = 'image/png'
+    let blob = sourceType === 'image/png' ? await encode('image/png', 1) : null
+    if (blob === null || blob.size > maxBytes) {
+      mediaType = lossyType
+      blob = await encode(mediaType, quality)
+    }
+    if (blob.size > maxBytes) {
+      return reject(
+        'too-large',
+        `A imagem continua com mais de ${formatMegabytes(maxBytes)} depois de reduzida. Recorte a imagem ou envie uma versão menor.`,
+      )
+    }
+    const prepared = new File([blob], renamed(file.name ?? 'imagem', mediaType), { type: mediaType })
+    return { ok: true, file: prepared, mediaType, width, height, size: prepared.size, resized: scale < 1 }
+  } catch {
+    return unreadable()
+  } finally {
+    image.release()
+  }
+}

package/src/ui/meta.ts

@@ -87,7 +87,7 @@ export const componentMeta = {
     name: "chat",
     ancestry: "opus",
     whenToUse:
-      "Monte uma conversa completa com mensagens, composição, carregamento e rolagem automática. A propriedade `send` aceita resposta integral ou streaming de eventos; use Composer quando precisar apenas da entrada de texto. Defina uma altura para o contêiner.",
+      "Monte uma conversa completa com mensagens, composição, carregamento e rolagem automática. A propriedade `send` aceita resposta integral ou streaming de eventos; no modo controlado, `composerAttachments` permite anexar imagens e o transcript mostra as que o aplicativo guardou. Use Composer quando precisar apenas da entrada de texto. Defina uma altura para o contêiner.",
   },
   checkbox: {
     name: "checkbox",
@@ -111,7 +111,7 @@ export const componentMeta = {
     name: "composer",
     ancestry: "opus",
     whenToUse:
-      "Receba texto para envio sem montar uma conversa completa. Enter envia, Shift+Enter quebra a linha e `actions` acrescenta uma faixa para seletores relacionados. O componente é controlado; use Chat quando também precisar de mensagens e estado da conversa.",
+      "Receba texto para envio sem montar uma conversa completa. Enter envia, Shift+Enter quebra a linha e `actions` acrescenta uma faixa para seletores relacionados. `attachments` permite anexar imagens pelo botão, colando ou soltando, com o estado mantido pelo aplicativo; `prepareImage` reduz a imagem antes do envio. O componente é controlado; use Chat quando também precisar de mensagens e estado da conversa.",
   },
   copyable: {
     name: "copyable",

package/src/ui/react.tsx

@@ -59,13 +59,30 @@ export type {
   ChatProps,
   ChatMessage,
   ChatArtifact,
+  ChatAttachment,
+  ChatAttachmentStatus,
   ChatTranscriptItem,
   ChatTranscriptMessage,
 } from "./components/primitives/chat.tsx";
 export { Ask } from "./components/primitives/ask.tsx";
 export type { AskProps } from "./components/primitives/ask.tsx";
 export { Composer } from "./components/primitives/composer.tsx";
-export type { ComposerProps } from "./components/primitives/composer.tsx";
+export type {
+  ComposerProps,
+  ComposerAttachment,
+  ComposerAttachmentStatus,
+  ComposerAttachments,
+  ComposerFileRejection,
+} from "./components/primitives/composer.tsx";
+// Preparação da imagem no navegador antes do envio (ADR 0058).
+export { prepareImage } from "./lib/prepare-image.ts";
+export type {
+  PrepareImageOptions,
+  PrepareImageRejection,
+  PrepareImageResult,
+  PreparedImage,
+  RejectedImage,
+} from "./lib/prepare-image.ts";
 export { Copyable } from "./components/primitives/copyable.tsx";
 export type { CopyableProps } from "./components/primitives/copyable.tsx";
 export {