@softize/opus 25.6.0 → 26.0.0

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-# Changelog do @softize/opus
+# Changelog
 
 O que muda em cada versão — e, quando quebra, **o que fazer**. Regras de leitura:
 minor = novidade compatível; major = breaking (a seção **Breaking** diz a migração).
@@ -7,6 +7,113 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 26.0.0 — 2026-10-09
+
+A conversa com a IA pode levar imagens (ADR 0058). Uma mensagem passa a aceitar texto e imagem
+juntos, o driver Anthropic envia as imagens ao modelo, e o `Composer` e o `Chat` recebem imagens
+coladas, soltas ou escolhidas pelo botão **Anexar imagem**. O pacote não guarda imagem: enviar,
+guardar, expirar e mostrar de novo são do aplicativo, que mantém o estado dos anexos.
+
+- **Mensagem com imagem.** `AiMessage.content` aceita `string | AiContentPart[]`, em que cada parte é
+  `{ type: 'text', text }` ou `{ type: 'image', mediaType, data }`, com PNG, JPEG ou WebP em base64.
+  Os tipos `AiContentPart` e `AiImageMediaType` saem de `@softize/opus` e de `@softize/opus/ai`.
+- **`aiMessageText(message)`.** Devolve o texto de uma mensagem: o próprio `content` quando é texto,
+  ou as partes de texto unidas por uma linha em branco, sem as imagens. Sai de `@softize/opus` e de
+  `@softize/opus/ai`.
+- **Driver Anthropic.** `run` e `runStream` convertem cada parte no bloco da API (`text`, ou `image`
+  com `source.type: 'base64'`). Uma parte desconhecida, uma lista de partes vazia, uma parte de texto
+  vazia, uma imagem fora dos três formatos ou uma imagem numa mensagem `assistant` fazem a chamada
+  lançar erro antes de chegar ao provedor, dizendo qual mensagem e qual parte.
+  `complete` e `extract` continuam recebendo texto.
+- **`Composer` com imagens.** A propriedade `attachments` liga o botão **Anexar imagem**, a faixa
+  acima do campo (miniatura, nome, estado `uploading`, `ready` ou `failed` e remover), colar e
+  soltar. A triagem aceita PNG, JPEG e WebP, até 4 por mensagem (`max` muda o limite, e `accept`,
+  tipado como `readonly AiImageMediaType[]`, escolhe um subconjunto dos três, sem curinga), e
+  explica a recusa acima do campo, ou a entrega a `onReject`. O envio passa com texto ou com uma
+  imagem pronta; espera enquanto alguma imagem está em envio e fica bloqueado com uma imagem em
+  falha, até ela ser removida ou reenviada. Uma região viva anuncia a imagem que fica pronta ou
+  falha, e o foco volta ao campo quando o botão de anexar fica desabilitado pelo limite. Colar
+  texto continua colando texto; a imagem colada sem texto recebe "Imagem colada 1.png", com um
+  número que não se repete no mesmo composer. O soltar que o composer consome não sobe para os
+  contêineres do aplicativo.
+- **`Chat` com imagens.** No modo controlado, `composerAttachments` liga as imagens no composer e o
+  soltar sobre a conversa inteira; `onSend(text, attachments)` recebe as imagens prontas, e a
+  mensagem pode ter só imagem. Sem `composerAttachments`, `onSend` continua sendo chamado só com o
+  texto. O item `user` do transcript aceita `attachments` (`ChatAttachment`,
+  com `id`, `name`, `mediaType`, dimensões, `status: 'available' | 'expired'` e o `url` dado pelo
+  aplicativo): a fala mostra as miniaturas acima do texto, com o nome como texto alternativo, e a
+  imagem expirada como um cartão com o nome e "Imagem expirada". O modo autogerenciado (`send`) não
+  aceita imagem. Com `composerAttachments`, o arraste de arquivos sobre o Chat é consumido nele
+  (`stopPropagation` em `dragenter`, `dragover`, `dragleave` e `drop`) e não chega a um contêiner do
+  aplicativo com o próprio soltar; sem ele, o arraste segue como antes.
+- **`prepareImage(file, options)`**, de `@softize/opus/ui/react`, prepara a imagem no navegador antes
+  do envio: lê só o cabeçalho para conferir o formato pelos bytes e as dimensões, recusa GIF, SVG,
+  imagem animada e, antes de decodificar, a imagem acima de `maxPixels` (padrão 40 megapixels);
+  reduz o lado maior a `maxEdge` (padrão 1568) respeitando a orientação EXIF
+  (`imageOrientation: 'from-image'`) e codifica de novo, descartando metadados. PNG continua PNG quando cabe em
+  `maxBytes` (padrão 3 MB); o resto vira JPEG com qualidade 0,85. Devolve o arquivo com tipo,
+  dimensões e tamanho, ou a recusa com o motivo e a mensagem em pt-BR.
+
+Sem as propriedades novas, o `Composer` e o `Chat` se comportam como antes.
+
+### Breaking
+
+**`AiMessage.content` passa a ser `string | AiContentPart[]`.** Código que lê `content` como texto
+deixa de compilar: `message.content.length`, `message.content.trim()`, uma função que recebe
+`string`, um driver de IA próprio que repassa `content` ao provedor. Migração: leia o texto com
+`aiMessageText(message)` e, num driver próprio, converta cada parte para o formato do provedor e
+recuse com erro a parte que ele não conhece.
+
+```ts
+import { aiMessageText } from '@softize/opus/ai'
+
+const title = aiMessageText(message).slice(0, 80) // antes: message.content.slice(0, 80)
+```
+
+O compilador não aponta o texto montado por interpolação (`${message.content}`) nem o que passa por
+`as`: com uma mensagem com imagem, esses pontos produzem "[object Object]" sem erro. Procure-os à
+parte (`grep -rn '\${[^}]*content' src`) e troque por `aiMessageText`. Um `ChatMessage` do `Chat`
+autogerenciado continua com `content: string` e segue atribuível a `AiMessage`.
+
+**`Chat.onSend` ganha o segundo parâmetro opcional `attachments?: ComposerAttachment[]`.** Em tempo de
+execução nada muda sem `composerAttachments`: a chamada continua `onSend(text)`. Um handler que já
+declarava um segundo parâmetro opcional de outro tipo, como `(text, options?) => …`, deixa de
+compilar ao ser passado direto. Migração: envolva-o (`onSend={(text) => runTurn(text)}`) ou, ao ligar
+as imagens, receba `attachments` explicitamente.
+
+## 25.7.0 — 2026-10-07
+
+Portais de documentação podem manter o mesmo mapa lateral em guias, ADRs e changelog. A superfície
+leve `@softize/opus/ui/docs/browser` passa a oferecer `DocHeader`, `DocCatalog`, `DocRecordDetail`
+e parsers de decisões e versões, sem carregar o catálogo do SDK nem o compilador de exemplos.
+O host continua responsável por fontes, rotas e autorização.
+
+`DocBrowser` aceita busca externa controlada, largura inicial da lateral, grupos inicialmente
+recolhidos, destinos globais, páginas fora da árvore e conteúdo do host no lugar de um guia. O modo
+editorial acrescenta contexto, sumário dos títulos renderizados e continuidade entre páginas.
+A busca revela resultados sem perder a escolha manual dos ramos abertos. As novas propriedades
+são opcionais: os consumidores existentes preservam a composição e os defaults anteriores.
+
+O cabeçalho compartilhado mantém a busca documental compacta e centralizada. Os catálogos têm
+busca textual própria dentro da página, independente do topo. ADRs apresentam contexto curto;
+changelog mantém o texto das versões e destaca cuidados de atualização. Não há tabela, filtros,
+controles de ordenação ou paginação nesses índices estáticos.
+
+A adaptação à largura da tela é restrita ao cabeçalho, à leitura editorial e aos catálogos do
+portal documental. A UI das aplicações e os componentes demonstrados nos exemplos vivos continuam
+com o contrato desktop a partir de `64rem` da ADR 0017.
+
+O portal do Opus passa a abrir pela documentação, com Visão geral, Instalação e Primeiros passos
+antes das referências. ADRs e Changelog entram na lateral; os endereços anteriores dos guias e do
+catálogo de UI são preservados. Não há migração obrigatória para quem não adotar essas composições.
+
+Links de `SidebarItem` podem declarar `href`, com o tratamento de foco dos botões e abertura em
+outra aba; sem esse campo, o item continua sendo um botão. A consulta do topo preserva a posição
+de leitura dos registros. O changelog limita os cuidados de atualização à seção `Breaking`, sem
+incluir novidades ou correções seguintes; resumos e detalhes preservam a ordem original das seções.
+O changelog embutido usa **Breaking: cuidados ao atualizar** no lugar de **Breaking — o que fazer**.
+O catálogo usa esse mesmo rótulo.
+
 ## 25.6.0 — 2026-10-07
 
 Aplicações que apresentam Markdown do próprio produto podem usar

package/docs/adr/0017-ui-assumes-a-fixed-desktop-layout.md

@@ -2,6 +2,7 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-15.
+- **Emenda:** 2026-10-07; portal documental delimitado pela ADR 0057.
 
 ## Contexto
 
@@ -28,6 +29,22 @@ Footers de formulário modal dimensionam as ações pelo conteúdo e usam `Cance
 `distribution="equal"` permanece uma escolha explícita para decisões de peso equivalente e,
 nesse caso, o cancelamento usa `outline`.
 
+### Exceção: portal de documentação
+
+O portal documental tem uma jornada de leitura distinta da UI operacional das aplicações. Conforme
+a ADR 0057, `DocHeader`, a leitura editorial de `DocBrowser` e `DocCatalog`/`DocRecordDetail`
+podem adaptar cabeçalho, espaçamento e sumário à largura da tela. A exceção foi aprovada para
+preservar a composição validada nos portais do Opus e da Grand Brasil.
+
+A exceção não torna responsivos `Split`, `Sidebar`, formulários, tabelas ou outros componentes da
+UI das aplicações. O host documental continua responsável pela composição de sua moldura em tela
+estreita. Exemplos vivos usam o mesmo contrato desktop dos componentes demonstrados; o portal não
+promete que todos os exemplos sejam adequados a telas menores que `64rem`.
+
+O gate permite variantes de viewport somente nos três arquivos documentais identificados na ADR
+0057. Arquivos novos, mesmo dentro de `docs/`, continuam sujeitos à regra até uma decisão explícita.
+Container queries não entram na exceção.
+
 ## Consequências
 
 - O mesmo componente preserva a composição a partir de `64rem`, inclusive dentro de panes,
@@ -50,5 +67,7 @@ nesse caso, o cancelamento usa `outline`.
 ## Verificação
 
 - Um teste de inventário reprova variantes de largura e container queries na UI viva.
+- O mesmo teste delimita a exceção documental por arquivo e comprova que ela não alcança componentes
+  da aplicação, outros arquivos documentais ou container queries.
 - Testes estruturais fixam layouts, larguras de modal e distribuição dos footers.
 - Documentação pública declara a largura mínima, o default por conteúdo e a exceção `equal`.

package/docs/adr/0057-doc-browser-permite-busca-no-chrome-do-consumidor.md

@@ -0,0 +1,152 @@
+# ADR 0057 — Portal documental compartilha navegação, busca e leitura
+
+- **Status:** aceita para implementação local; publicação pendente.
+- **Data:** 2026-10-07.
+
+## Contexto
+
+Portais de documentação precisam apresentar guias, decisões e entregas sem trocar o mapa de
+navegação a cada destino. O `DocBrowser` já organiza páginas, busca e árvore, mas sua composição
+original mantém o campo na lateral e não permite usar o cabeçalho ou substituir a leitura por um
+catálogo. Os portais do Opus e da Grand Brasil precisam dessas variações.
+
+Copiar a árvore, a filtragem e o grid em cada aplicação cria comportamentos concorrentes e repete
+defeitos de layout. Incorporar marca, rotas e autorização ao navegador, por outro lado, faria o SDK
+assumir decisões do produto hospedeiro. A extensão precisa compartilhar a composição sem transferir
+essas responsabilidades.
+
+## Decisão vigente
+
+A superfície leve `@softize/opus/ui/docs/browser` oferece navegação, cabeçalho e leitura para fontes
+fornecidas pelo host, sem importar o catálogo do Opus nem o compilador de exemplos vivos. A entrada
+histórica `@softize/opus/ui/docs` mantém o catálogo completo e reexporta a mesma composição.
+
+### Cabeçalho e busca documental
+
+`DocHeader` recebe marca, busca, ações e navegação opcional. Centraliza a geometria do topo, com
+busca compacta de até `22rem`, colunas simétricas nas extremidades e uma linha própria para o campo
+em telas menores que `64rem`. Não conhece tema, repositório, rotas ou estado de pesquisa.
+
+`DocBrowser.search` mantém duas composições:
+
+- `placement: "sidebar"` preserva o campo e o estado local existentes.
+- `placement: "external"` recebe o valor controlado pelo host, filtra a mesma árvore e não
+  renderiza um segundo campo.
+
+Nos dois portais, a busca documental mantém rótulo, apresentação, valor e função em guias,
+catálogos e registros. Pesquisa os guias na lateral; não se transforma silenciosamente numa busca
+de ADRs ou versões.
+
+### Hierarquia e leitura
+
+`sidebarSize` configura a largura inicial usando o `PaneSize` do `Split`. A omissão preserva
+`14rem`. `sidebarInitiallyCollapsed` permite começar com seções e grupos nomeados recolhidos,
+inclusive quando a pessoa abre uma página por URL direta. A busca revela os resultados
+temporariamente; limpá-la restaura os ramos abertos manualmente.
+
+`sidebarLinks` apresenta destinos globais após os capítulos, no mesmo nível visual e fora da
+sequência anterior/próxima. `active` identifica o catálogo atual. `navigationTitle` oferece um
+rótulo curto para uma página sem alterar seu título completo ou os termos pesquisáveis.
+
+Esses destinos usam `SidebarItem.href`, não uma cópia do estilo da linha. A extensão preserva o
+botão quando `href` é omitido, o foco nos dois modos e a abertura nativa em outra aba. Quando há
+`onClick`, somente a navegação simples é interceptada; o host mantém a decisão de roteamento.
+
+O modo opcional `editorial` acrescenta contexto, sumário dos headings realmente renderizados e
+links de continuidade segundo a ordem declarada. `additionalPages` preserva URLs de páginas fora
+da árvore e da sequência. O renderer de exemplos aceita `codeCollapsible={false}` quando ocultar
+o código interromperia uma explicação didática.
+
+### Catálogos e registros
+
+`content` substitui a área de leitura sem desmontar a árvore. Quando esse slot é fornecido, o
+host resolve rota e título; o navegador não escolhe uma página dos guias nem aplica seus redirects.
+`null` representa uma leitura intencionalmente vazia. `sidebar={false}` permite atender
+consumidores que precisem de uma página isolada, mas os dois portais mantêm a lateral em
+guias, catálogos e registros.
+
+`DocCatalog` oferece leitura editorial de registros estáticos, sem tabela, filtros, ordenação
+configurável ou paginação. ADRs apresentam número, título, metadata declarada e o primeiro
+parágrafo do contexto. Changelog apresenta texto integral por versão, com data e cuidados de
+atualização em destaque. Os registros mais recentes aparecem primeiro.
+
+Cada catálogo tem um campo textual na própria página. `query` e `onQueryChange` são controlados
+pelo host, independentemente da busca documental. Os portais preservam a consulta local ao abrir
+um registro e voltar, e a limpam ao trocar de catálogo; não limpam a consulta do topo pela navegação.
+
+`DocRecordDetail` apresenta somente o nome do catálogo antes do título, sem breadcrumb ou retorno
+duplicado. A navegação permanece na lateral. Para preservar os ramos abertos, o host mantém a mesma
+instância de `DocBrowser` entre guia, catálogo e registro.
+
+Os parsers projetam as mesmas fontes Markdown, sem cadastro editorial paralelo. Não inferem data
+ou status ausentes, resumo sem seção de contexto ou releases anteriores ao versionamento.
+Ressalvas do status permanecem no texto integral da ADR.
+
+Este índice estático é uma exceção deliberada ao uso de `ActionList`: publica arquivos versionados
+e funciona sem API da aplicação. Não substitui coleções de recursos servidas por actions.
+
+### Relação com o contrato desktop da UI
+
+A composição documental é uma exceção explícita à ADR 0017: `DocHeader.tsx`, `DocBrowser.tsx`
+(na leitura editorial) e `DocCatalog.tsx` (incluindo `DocRecordDetail`) podem usar variantes de
+viewport para organizar cabeçalho, sumário e espaçamento. A exceção fica restrita a esses arquivos;
+não libera toda a pasta `docs/` nem container queries. O gate verifica as funções de composição
+permitidas, sem liberar outras funções ou a montagem de `Split` no mesmo arquivo.
+
+Essa adaptação foi aprovada para o portal de leitura, não para a UI das aplicações. O host organiza
+sua moldura em telas estreitas; `Split`, `Sidebar` e os exemplos vivos não ganham um contrato
+responsivo por estarem dentro da documentação. Manter o portal inteiramente desktop descartaria
+a composição já validada; ampliar a exceção para toda a UI alteraria uma decisão fora deste escopo.
+
+## Alternativas consideradas
+
+### Manter campo, largura e leitura fixos
+
+Preservaria uma API menor, mas obrigaria portais autônomos a copiar a árvore ou adotar a composição
+do catálogo embutido. As novas propriedades são opcionais e mantêm os defaults existentes.
+
+### Compor todo o portal dentro de DocBrowser
+
+Centralizaria a implementação, ao custo de misturar identidade visual, navegação global,
+autorização e rotas do host com a leitura documental. `DocHeader` compartilha somente a geometria;
+`content` compartilha o mapa sem decidir os destinos.
+
+### Copiar grids e filtragem nos consumidores
+
+Evitaria a extensão do pacote, mas os primeiros consumidores já repetiram um desalinhamento do
+cabeçalho. `PageHeader` e `PageShell` organizam páginas de recursos, não o topo de um portal
+documental. Manter essas cópias deixaria o mesmo defeito com duas correções locais.
+
+### Tabela para decisões e entregas
+
+Foi implementada no protótipo com filtro, ordenação e paginação, mas rejeitada na avaliação visual.
+ADRs precisam de contexto para escolher a leitura; changelog precisa manter a continuidade do texto.
+A busca textual atende a consulta sem acrescentar controles de coleção.
+
+### Ocultar a lateral e trocar o alcance da busca no catálogo
+
+Também foi experimentado e substituído após avaliação. Ocultar a lateral interrompia o mapa;
+trocar o alcance do campo superior tornava a pesquisa ambígua. A decisão vigente mantém a lateral
+e separa a consulta documental da consulta local.
+
+## Consequências
+
+- Consumidores existentes preservam campo lateral, largura de `14rem` e composição não editorial.
+- A biblioteca mantém uma árvore e uma regra de busca; o host mantém conteúdo, rotas e autorização.
+- Os dois portais compartilham cabeçalho e catálogos sem compartilhar sua taxonomia específica.
+- Guias, índices e fontes acessíveis por URL direta precisam ser filtrados antes de chegar ao
+  navegador quando houver restrição de acesso. Esta composição não é uma fronteira de segurança.
+- A consolidação é um candidato local. A publicação e a adoção pela Grand Brasil são etapas
+  distintas, posteriores à revisão independente.
+
+## Verificação
+
+- Testes de `DocBrowser`: busca local e externa, vazio, largura configurável, lateral opcional,
+  persistência de grupos, expansão temporária, conteúdo do host, redirects e leitura editorial.
+- Testes de `DocHeader`: slots, atributos nativos e composição com ou sem busca e navegação.
+- Testes de `DocCatalog`: busca local controlada, independência do topo, ausência de controles de
+  coleção, texto integral das versões, incompatibilidades e abertura nativa em outra aba.
+- Testes dos parsers: metadata ausente, resumo canônico, acentos e termos combinados, texto integral
+  e ausência de versões retroativas fabricadas.
+- Inspeção dos dois portais: largura estreita, alinhamento do topo, lateral persistente, busca,
+  URLs diretas, ida ao registro e retorno ao catálogo.

package/docs/adr/0058-mensagem-da-ia-aceita-imagem-e-o-chat-recebe-anexos.md

@@ -0,0 +1,201 @@
+# ADR 0058 — A mensagem da IA aceita imagem, e o Chat recebe anexos que o app guarda
+
+- **Status:** aceita.
+- **Data:** 2026-10-09.
+- **Complementa:** a regra de crescimento por reincidência do `AiAdapter` (`core/types.ts`, nota do
+  contrato) e da entrada `@softize/opus/ai`; ADR 0050 (o `Markdown` não carrega imagem externa).
+- **Origem:** ADR 0122 da plataforma Grand Brasil, "A imagem anexada à conversa com a IA fica
+  guardada com a conversa", que pede ao pacote o corte 1 do plano dela.
+
+## Contexto
+
+A plataforma Grand Brasil decidiu que a pessoa pode colar, soltar ou escolher uma imagem na conversa
+com a IA, e que a IA a vê no mesmo turno. O caso que motivou a decisão é pedir ao assistente de
+Relatórios que reproduza um relatório a partir de um print. É o primeiro caso real de entrada que não
+é texto, e a superfície de IA do pacote cresce por reincidência: este é o caso que a cobra.
+
+Hoje o pacote só conhece texto em três pontos:
+
+- **O tipo da mensagem.** `AiMessage` é `{ role, content: string }`. `run` e `runStream` recebem
+  `string | AiMessage[]`.
+- **O driver Anthropic.** Ele monta as mensagens com `content: m.content`, sem conferir a forma. Uma
+  lista de blocos no formato da Anthropic passaria por acaso, forçada com um `as`, e qualquer outro
+  provedor do consumidor receberia uma forma que não conhece.
+- **A interface.** O `Composer` só habilita o envio com texto, e o `Chat` guarda `content: string` em
+  cada item. O modo controlado recebe o texto em `onSend(text)`.
+
+A guarda da imagem não é do pacote. Na Grand Brasil, o motor de IA guarda os bytes junto com a
+conversa, com retenção, governança e uma rota própria de envio. Outro consumidor pode guardar em
+outro lugar, ou não guardar. O que se repete em qualquer consumidor é a forma de levar a imagem ao
+modelo, a caixa de escrever com anexos e a preparação da imagem no navegador.
+
+## Decisão
+
+### 1. Conteúdo neutro na mensagem
+
+O núcleo ganha um tipo de conteúdo que não tem a forma de nenhum provedor:
+
+```ts
+type AiImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp'
+
+type AiContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image'; mediaType: AiImageMediaType; data: string } // base64, sem o prefixo data:
+
+interface AiMessage {
+  role: 'user' | 'assistant'
+  content: string | AiContentPart[]
+}
+```
+
+- Os formatos são PNG, JPEG e WebP, os três que os provedores conhecidos aceitam. GIF fica de fora.
+- A parte de imagem não leva nome. O rótulo que a pessoa e o modelo usam ("Imagem 1: print.png") é
+  uma parte de texto que o consumidor monta antes da imagem, como a Grand Brasil faz.
+- `content: string` continua válido. Quem só manda texto não muda nada na escrita.
+
+### 2. `aiMessageText` lê o texto de qualquer mensagem
+
+`aiMessageText(message)` devolve o texto de uma mensagem: o próprio `content` quando ele é texto, ou
+as partes de texto unidas por uma linha em branco. As imagens não entram. Serve para quem precisa só
+do texto, como título de conversa, contagem de caracteres ou um bloco de contexto montado por
+interpolação. Sai de `@softize/opus` e de `@softize/opus/ai`.
+
+### 3. O driver Anthropic converte cada parte
+
+- A parte `text` vira o bloco `text`, e a parte `image` vira o bloco `image` com
+  `source: { type: 'base64', media_type, data }`, em `run` e em `runStream`.
+- Uma parte de tipo desconhecido, uma lista de partes vazia, uma parte de texto vazia, uma imagem num
+  formato fora da lista ou uma imagem numa mensagem `assistant` fazem o driver lançar erro antes de
+  qualquer chamada, dizendo qual mensagem e qual parte. Nunca há descarte silencioso.
+- `complete` e `extract` continuam recebendo texto.
+
+### 4. A guarda é do consumidor
+
+O pacote não guarda imagem, não envia bytes a um servidor e não gera endereço. O `StorageAdapter`
+existente não entra nesta decisão. O consumidor escolhe o transporte (a Grand Brasil manda a imagem
+por uma rota própria, antes do turno) e entrega ao `Chat` o estado dos anexos e o endereço de cada
+imagem. Assim, retenção, expiração, governança e dado pessoal ficam com quem guarda.
+
+### 5. Composer e Chat recebem anexos controlados pelo app
+
+- O `Composer` ganha a propriedade `attachments`, e o `Chat`, a `composerAttachments`, com a mesma
+  forma: os anexos pendentes (`id`, nome, estado `uploading`, `ready` ou `failed`, miniatura e motivo
+  da falha), `onAddFiles`, `onRemove`, o limite por mensagem (padrão 4), os formatos aceitos
+  (`readonly AiImageMediaType[]`, padrão PNG, JPEG e WebP, sem curinga: um formato que a mensagem
+  não leva não pode ser aceito na faixa) e `onReject` opcional. Sem essa propriedade, não há faixa, botão, colar nem soltar
+  de arquivos: o composer é o de sempre.
+- Com a propriedade, o composer mostra a faixa de anexos acima do texto, com miniatura, nome, estado
+  e o botão de remover, e o botão **Anexar imagem** na barra. Colar uma imagem no campo, soltá-la
+  sobre a conversa ou escolhê-la pelo botão entregam os arquivos aceitos a `onAddFiles`. A imagem
+  colada recebe um nome gerado ("Imagem colada 1.png"), com um contador da instância que não volta
+  atrás, para que dois anexos da mesma conversa não tenham o mesmo nome. Colar texto continua colando texto, mesmo
+  quando a área de transferência também traz uma imagem, como acontece ao copiar células de uma
+  planilha.
+- A triagem recusa o que não está na lista de tipos e o que passaria do limite. Sem `onReject`, o
+  composer explica a recusa logo acima do campo; com `onReject`, a explicação é do app.
+- Uma região viva anuncia a imagem que fica pronta ou falha, porque a mudança na faixa é só visual.
+  Quando o botão de anexar fica desabilitado por atingir o limite, o foco volta ao campo.
+- O arraste de arquivos que o `Chat` (ou o `Composer` sozinho) consome não sobe para os contêineres
+  do app, que podem ter o próprio soltar, como o envio de arquivos a um acervo.
+- O envio passa com texto ou com pelo menos um anexo pronto. Ele espera os anexos em envio e não
+  passa com um anexo em falha: a pessoa remove o anexo, ou o app tenta de novo, para que nada do que
+  está na faixa fique de fora sem aviso.
+- O modo controlado recebe `onSend(text, attachments)`, com os anexos prontos, quando há
+  `composerAttachments`. Sem eles, a chamada continua `onSend(text)`: um handler que já tinha um
+  segundo parâmetro opcional, com outro significado, não recebe uma lista inesperada. Limpar a faixa
+  depois do envio é do app, que é o dono do estado. Retornar `false` devolve o texto ao campo, e os
+  anexos continuam na faixa.
+- O item `user` do transcript ganha `attachments`, com `id`, nome, tipo, dimensões, estado
+  (`available` ou `expired`) e o endereço da imagem fornecido pelo app. A fala da pessoa mostra as
+  miniaturas acima do texto, com o nome como texto alternativo. O anexo expirado aparece como um
+  cartão com o nome e "Imagem expirada". Uma fala só com imagem não mostra balão de texto vazio.
+- As miniaturas são um componente próprio, e não `![]()` no Markdown da mensagem: a fala da pessoa
+  continua sendo o que ela escreveu. O endereço vem do app, que deve servi-lo pela própria origem ou
+  como `data:`, como a ADR 0050 já recomenda.
+- O modo autogerenciado do `Chat` (`send(messages)`) não ganha anexo. Ele não tem transporte para a
+  imagem, e `ChatMessage` continua só com texto. Se um consumidor precisar, uma nova decisão define
+  como.
+
+### 6. Preparação da imagem no navegador
+
+`prepareImage(file, options)` prepara a imagem antes do envio, com os tetos que o app passa:
+
+- lê só o cabeçalho do arquivo, sem carregá-lo inteiro, para conferir o formato pelos primeiros
+  bytes, não pela extensão nem pelo tipo declarado, e recusa o que não está em `accept` (padrão PNG,
+  JPEG e WebP);
+- recusa PNG e WebP animados, que o modelo leria só pelo primeiro quadro;
+- lê largura e altura do cabeçalho e recusa, antes de decodificar, a imagem acima de `maxPixels`
+  (padrão 40 megapixels): decodificá-la ocuparia centenas de megabytes de memória do navegador;
+- reduz para que o lado maior não passe de `maxEdge` (padrão 1568 px), mantendo a proporção e a
+  orientação gravada pela câmera (EXIF), e codifica de novo sempre, o que descarta metadados como a
+  localização;
+- mantém PNG como PNG quando cabe em `maxBytes` (padrão 3 MB) e converte o resto para JPEG com
+  qualidade 0,85, sobre fundo branco; o que continua acima do teto é recusado;
+- devolve o arquivo preparado com tipo, dimensões e tamanho, ou a recusa com o motivo e uma mensagem
+  em pt-BR para a pessoa.
+
+Os padrões repetem os tetos da ADR 0122 da Grand Brasil, mas o consumidor deve passar os seus: o
+utilitário não decide teto de produto.
+
+## Por que é major
+
+`AiMessage.content` passa de `string` para `string | AiContentPart[]`. Quem lê `content` como texto
+deixa de compilar, e é de propósito: o compilador aponta os consumidores e os drivers que usam o
+conteúdo como texto, em vez de deixar a imagem sumir em silêncio. A migração é ler o texto com
+`aiMessageText(message)`.
+
+O compilador não aponta o texto montado por interpolação (`${message.content}`) nem o que passa por um
+`as`. Com uma lista de partes, esses pontos produziriam "[object Object]" sem erro. Dentro do pacote
+não há nenhum; nos consumidores, a migração precisa procurá-los à parte e cobri-los com teste.
+
+As mudanças de `Composer` e `Chat` preservam o comportamento de quem não usa anexo: sem as
+propriedades novas, a interface é a mesma, e `onSend` continua sendo chamado só com o texto. O tipo de
+`onSend` ganha o segundo parâmetro opcional; um handler que já declarava um segundo parâmetro
+opcional de outro tipo deixa de compilar e precisa ser envolvido, como `(text) => run(text)`.
+
+## Consequências
+
+- Um driver de IA do consumidor que repassava `content` sem conferir passa a receber partes neutras
+  quando o consumidor manda imagem. Cada driver converte as partes, ou recusa com erro claro.
+- O pacote cresce com a faixa de anexos e a preparação da imagem, usadas por um consumidor só por
+  enquanto. Ficam no pacote porque o `Chat` e o `Composer` são dele, e cada consumidor reconstruiria
+  a sua por cima de `composerActions`.
+- A redução no navegador limita tamanho e custo, mas não garante que o provedor não reduza de novo:
+  no nível padrão do Claude, uma imagem retangular de 1568 px ainda passa por redução na API.
+- O tipo e o estado de cada anexo continuam como texto no pacote. A plataforma que adota declara o
+  próprio vocabulário (na Grand Brasil, um `t.dict` no protocolo da IA).
+
+## Alternativas descartadas
+
+- **Campo opcional só para imagens em `AiMessage`.** Não quebraria ninguém, mas um driver que não o
+  conhece descartaria a imagem sem aviso, e o compilador não apontaria nada.
+- **Partes no formato da Anthropic.** Funcionaria só com esse driver. Os demais provedores, que a
+  Grand Brasil também usa, receberiam uma forma que não conhecem.
+- **Nome na parte de imagem.** A API da Anthropic não tem onde pôr o nome, e o rótulo em texto antes
+  da imagem já permite que a pessoa e o modelo falem de "imagem 2".
+- **O `Composer` envia e guarda a imagem.** Prenderia o pacote a um transporte e a uma guarda que
+  são do consumidor, com retenção e governança próprias.
+- **Anexo no modo autogerenciado.** Exigiria levar os bytes no histórico enviado a `send`, que é o
+  que a Grand Brasil recusou para o corpo do chat. Fica para quando um consumidor trouxer o caso.
+- **Aceitar a imagem animada e mandar só o primeiro quadro.** A pessoa acharia que o modelo viu a
+  animação; recusar com o motivo é mais honesto.
+
+## Verificação
+
+- Teste do driver: uma mensagem com texto e imagem chega ao client falso como bloco `text` e bloco
+  `image` com `source.type: 'base64'`, no `run` e no `runStream`; uma parte desconhecida, uma lista
+  vazia, uma parte de texto vazia, uma imagem num formato fora da lista e uma imagem em mensagem
+  `assistant` lançam erro sem chamar o client.
+- Teste de `aiMessageText` com texto puro e com partes.
+- Testes do `Composer` e do `Chat`: colar, soltar e escolher entregam o arquivo a `onAddFiles`;
+  colar texto continua colando; o envio passa só com imagem pronta e não passa com imagem em envio
+  ou em falha; tipo e limite são recusados com o motivo; o `Chat` mostra as miniaturas e o cartão de
+  imagem expirada, entrega `onSend(text, attachments)` e, sem `composerAttachments` ou no modo
+  autogerenciado, não mostra a faixa; o nome da imagem colada não se repete depois de remover uma;
+  a região viva anuncia pronta e falha; o foco volta ao campo no limite; o soltar consumido não
+  chega ao contêiner do app.
+- Testes de `prepareImage` com canvas simulado e em navegador real: uma imagem de 4000 px sai com
+  lado maior de 1568 px, o PNG que cabe continua PNG, o que passa vira JPEG, e GIF, SVG e imagem
+  animada são recusados com o motivo; as dimensões vêm do cabeçalho de PNG, JPEG e WebP (com e sem
+  perdas e estendido), sem ler o arquivo inteiro, e a imagem acima do teto de pixels é recusada sem
+  decodificar; um JPEG com EXIF de rotação sai em pé.

package/docs/adr/README.md

@@ -0,0 +1,12 @@
+---
+title: Decisões arquiteturais
+order: -1
+---
+# Decisões arquiteturais
+
+As ADRs registram o contexto, as alternativas e as consequências das decisões estruturais do
+Opus. Use a Documentação para compreender o contrato vigente; consulte esta área quando precisar
+entender por que uma restrição existe ou como ela evoluiu.
+
+Uma ADR preserva seu contexto histórico mesmo quando é substituída. O comportamento vigente deve
+estar documentado na superfície correspondente, sem exigir a reconstrução dessa sequência.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.6.0",
+  "version": "26.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ai/drivers/anthropic.ts

@@ -17,6 +17,7 @@ import { declaredJsonSchema } from '../../core/index.ts'
 import type {
   AiAdapter,
   AiCompleteOptions,
+  AiContentPart,
   AiMessage,
   AiRunOptions,
   AiRunResult,
@@ -101,6 +102,50 @@ function defaultToJsonSchema(schema: unknown): unknown {
   return zodToJsonSchema(schema as Parameters<typeof zodToJsonSchema>[0], { $refStrategy: 'none' })
 }
 
+const IMAGE_MEDIA_TYPES: ReadonlySet<string> = new Set(['image/png', 'image/jpeg', 'image/webp'])
+
+/** Converte o conteúdo neutro da mensagem (ADR 0058) para os blocos da API da Anthropic. Uma
+ *  parte desconhecida, uma parte de texto vazia, uma lista vazia, uma imagem fora dos formatos
+ *  aceitos ou uma imagem na fala do assistente lançam erro: nada é descartado em silêncio, e nada
+ *  chega a ser enviado. */
+function toAnthropicContent(message: AiMessage, index: number): unknown {
+  const { content } = message
+  if (typeof content === 'string') return content
+  // A API recusa lista vazia e bloco de texto sem texto; o erro aqui diz qual mensagem é.
+  if (content.length === 0) {
+    throw new Error(`ai/anthropic: mensagem ${index + 1} sem conteúdo (lista de partes vazia).`)
+  }
+  return content.map((part: AiContentPart, partIndex) => {
+    const where = `mensagem ${index + 1}, parte ${partIndex + 1}`
+    if (part.type === 'text') {
+      if (part.text.trim() === '') {
+        throw new Error(`ai/anthropic: parte de texto vazia (${where}).`)
+      }
+      return { type: 'text', text: part.text }
+    }
+    if (part.type === 'image') {
+      if (message.role !== 'user') {
+        throw new Error(`ai/anthropic: imagem só pode ir numa mensagem 'user' (${where}).`)
+      }
+      if (!IMAGE_MEDIA_TYPES.has(part.mediaType)) {
+        throw new Error(
+          `ai/anthropic: formato de imagem não aceito: "${String(part.mediaType)}" (${where}). ` +
+            'Use image/png, image/jpeg ou image/webp.',
+        )
+      }
+      return { type: 'image', source: { type: 'base64', media_type: part.mediaType, data: part.data } }
+    }
+    const unknownType = (part as { type?: unknown }).type
+    throw new Error(`ai/anthropic: parte de conteúdo desconhecida: "${String(unknownType)}" (${where}).`)
+  })
+}
+
+/** O histórico de entrada no formato da API, convertido antes da primeira chamada. */
+function toAnthropicMessages(input: string | AiMessage[]): Array<{ role: string; content: unknown }> {
+  if (typeof input === 'string') return [{ role: 'user', content: input }]
+  return input.map((m, i) => ({ role: m.role, content: toAnthropicContent(m, i) }))
+}
+
 interface ContentBlock {
   type: string
   text?: string
@@ -183,6 +228,9 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
     },
 
     async run(input: string | AiMessage[], opts: AiRunOptions): Promise<AiRunResult> {
+      // Mensagens no formato Anthropic — convertidas antes de tudo (uma parte inválida falha sem
+      // chamar a API) e crescem com tool_use/tool_result a cada passo.
+      const messages = toAnthropicMessages(input)
       const c = await client()
       const tools = withAskTool(
         opts.tools.map((t) => ({
@@ -192,11 +240,6 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
         })),
         opts,
       )
-      // Mensagens no formato Anthropic — crescem com tool_use/tool_result a cada passo.
-      const messages: Array<{ role: string; content: unknown }> =
-        typeof input === 'string'
-          ? [{ role: 'user', content: input }]
-          : input.map((m) => ({ role: m.role, content: m.content }))
 
       const maxSteps = opts.maxSteps ?? 8
       const calls: Array<{ name: string; input: unknown }> = []
@@ -242,6 +285,7 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
     },
 
     async *runStream(input: string | AiMessage[], opts: AiRunOptions): AsyncIterable<ChatEvent> {
+      const messages = toAnthropicMessages(input)
       const c = await client()
       const tools = withAskTool(
         opts.tools.map((t) => ({
@@ -251,10 +295,6 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
         })),
         opts,
       )
-      const messages: Array<{ role: string; content: unknown }> =
-        typeof input === 'string'
-          ? [{ role: 'user', content: input }]
-          : input.map((m) => ({ role: m.role, content: m.content }))
 
       const maxSteps = opts.maxSteps ?? 8
 

package/src/ai/index.ts

@@ -5,11 +5,14 @@
  * (texto → objeto VALIDADO por um `Schema` do protocolo — o mesmo tipo de schema
  * das actions vira o contrato da resposta do modelo). Driver em `ai/anthropic`.
  * A superfície é a mínima de backoffice e cresce por reincidência — não por
- * especulação (streaming, chat multi-turn e tools livres entram quando um caso
- * real cobrar).
+ * especulação. Streaming, chat multi-turn e mensagem com imagem (ADR 0058) já
+ * entraram assim; o resto espera um caso real.
  */
 
 export type { AiAdapter, AiCompleteOptions } from '../core/index.ts'
+// Mensagem com texto e imagem (ADR 0058): o tipo neutro de conteúdo e a leitura só do texto.
+export type { AiContentPart, AiImageMediaType, AiMessage } from '../core/index.ts'
+export { aiMessageText } from '../core/index.ts'
 // Elicitação — perguntar à pessoa no meio do turno (round-trip via `AiRunOptions.onAsk`).
 // O contrato (tipos) mora no core; aqui saem o nome reservado, o schema/descrição da tool e
 // o formatador. É o ponto de consistência pra qualquer consumidor (chat, copilot, MCP externo).