@softize/opus 25.6.0 → 26.0.0

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 {