@softize/opus 25.7.0 → 26.1.0

package/CHANGELOG.md

@@ -7,6 +7,101 @@ 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.1.0 — 2026-10-09
+
+Subheadings descrevem a finalidade da superfície; orientações necessárias ficam visíveis no corpo
+ou junto ao campo (ADR 0059).
+
+- `Page` aceita `description`. `PageDescription`, `DialogDescription` e `DrawerDescription`
+  compõem o cabeçalho ou a introdução declarada da superfície.
+- `ActionFormDialog` e `ActionListDialog` recebem `description` para o cabeçalho. `intro` continua
+  no corpo, para regras e consequências da tarefa; ambos participam da descrição acessível.
+- `FieldSpec.hint` declara orientação visível abaixo do controle. `ActionFormField` associa hint
+  e erro por `aria-describedby`; `help` continua sendo a ajuda opcional junto à label.
+- Os textos dos campos resolvem `I18nRef` pelo texto padrão também nos renderizadores próprios.
+  O ícone de ajuda participa do Tab e abre por foco, sem tomar o foco inicial de outro controle
+  em Dialog e Drawer.
+- O inventário de copy, o validador estrutural, a skill de UI e os exemplos da documentação
+  reconhecem esses papéis sem proibir subheadings de maneira indiscriminada.
+
+**O que fazer:** rode `opus setup` e `opus copy`; revise a posição das orientações existentes.
+Renderizadores próprios de campos devem apresentar `hint` e associá-lo ao controle, preservando
+os erros. Nenhum texto migra automaticamente de `help` para `hint`.
+
+## 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

package/bin/lib/check.mjs

@@ -152,6 +152,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageBody", new Set(["Page"])],
   ["PageFooter", new Set(["Page"])],
   ["PageTitle", new Set(["PageHeader"])],
+  ["PageDescription", new Set(["PageHeader"])],
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader"])],
@@ -173,6 +174,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["DialogNavigation", new Set(["DialogHeader"])],
   ["DialogMedia", new Set(["DialogHeader"])],
   ["DialogTitle", new Set(["DialogHeader", "DialogIntro"])],
+  ["DialogDescription", new Set(["DialogHeader", "DialogIntro"])],
   ["DialogActions", new Set(["DialogHeader"])],
   ["DrawerHeader", new Set(["DrawerContent"])],
   ["DrawerBody", new Set(["DrawerContent"])],
@@ -182,6 +184,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["DrawerNavigation", new Set(["DrawerHeader"])],
   ["DrawerMedia", new Set(["DrawerHeader"])],
   ["DrawerTitle", new Set(["DrawerHeader", "DrawerIntro"])],
+  ["DrawerDescription", new Set(["DrawerHeader", "DrawerIntro"])],
   ["DrawerActions", new Set(["DrawerHeader"])],
   ["AlertMedia", new Set(["Alert"])],
   ["AlertHeader", new Set(["Alert"])],
@@ -215,13 +218,12 @@ const UI_STRUCTURAL_ROOTS = new Map([
       body: "PageBody",
       footer: "PageFooter",
       headerRequired: false,
-      shorthand: new Set(["title", "actions"]),
+      shorthand: new Set(["title", "description", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
       // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
       // prop removida é cobrada aqui, nas duas formas de composição.
       removed: new Map([
         ["count", "o total pertence ao conteúdo que o explica"],
-        ["description", "mova contexto relevante para o início do body"],
       ]),
     },
   ],
@@ -244,6 +246,7 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageBody",
   "PageFooter",
   "PageTitle",
+  "PageDescription",
   "PageBack",
   "PageNavigation",
   "PageActions",
@@ -308,24 +311,7 @@ const UI_REMOVED_PROPS = new Map([
       ["variant", "o cabeçalho da página tem uma única apresentação rolável"],
     ]),
   ],
-  [
-    "ActionFormDialog",
-    new Map([
-      [
-        "description",
-        "use `intro` somente para contexto relevante no início do corpo",
-      ],
-    ]),
-  ],
-  [
-    "ActionListDialog",
-    new Map([
-      [
-        "description",
-        "use `intro` somente para contexto relevante no início do corpo",
-      ],
-    ]),
-  ],
+
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
@@ -338,15 +324,6 @@ const UI_REMOVED_COMPONENTS = new Map([
   ["PaneDescription", "use `SurfaceDescription` dentro de `SurfaceHeader`"],
   ["PaneActions", "use `SurfaceActions` dentro de `SurfaceHeader`"],
   ["PageIntro", "use `PageHeader` como a única introdução estrutural"],
-  ["PageDescription", "mova contexto relevante para o início de `PageBody`"],
-  [
-    "DialogDescription",
-    "mova contexto relevante para o início de `DialogBody`",
-  ],
-  [
-    "DrawerDescription",
-    "mova contexto relevante para o início de `DrawerBody`",
-  ],
   // Content e Card deram lugar a Surface (ADR 0045).
   [
     "Content",
@@ -383,7 +360,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "DialogIntro",
     {
       title: "DialogTitle",
-      optional: new Set(["DialogIntroActions"]),
+      optional: new Set(["DialogIntroActions", "DialogDescription"]),
       shorthand: new Set(),
     },
   ],
@@ -391,7 +368,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "DrawerIntro",
     {
       title: "DrawerTitle",
-      optional: new Set(["DrawerIntroActions"]),
+      optional: new Set(["DrawerIntroActions", "DrawerDescription"]),
       shorthand: new Set(),
     },
   ],
@@ -399,7 +376,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageHeader",
     {
       title: "PageTitle",
-      optional: new Set(["PageBack", "PageNavigation", "PageActions"]),
+      optional: new Set(["PageBack", "PageNavigation", "PageActions", "PageDescription"]),
       exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
       titleRequired: false,

package/bin/lib/copy.mjs

@@ -99,9 +99,9 @@ const JSX_CHILD_ROLES = new Map([
   ['Button', 'button'],
   ['CommandEmpty', 'empty-state'],
   ['CommandItem', 'menu-item'],
-  ['DialogDescription', 'dialog-body'],
+  ['DialogDescription', 'description'],
   ['DialogTitle', 'title'],
-  ['DrawerDescription', 'dialog-body'],
+  ['DrawerDescription', 'description'],
   ['DrawerTitle', 'title'],
   ['EmptyDescription', 'empty-state'],
   ['EmptyTitle', 'title'],
@@ -123,6 +123,7 @@ const JSX_CHILD_ROLES = new Map([
   // comando. Classificado como `button`, a política universal cobraria verbo de ação.
   ['PageBack', 'breadcrumb'],
   ['PageTitle', 'title'],
+  ['PageDescription', 'description'],
   ['SurfaceDescription', 'description'],
   ['SurfaceTitle', 'title'],
   ['TableCaption', 'description'],
@@ -182,7 +183,7 @@ const JSX_PROP_ROLES = new Map([
     'ActionFormDialog',
     new Map([
       ['title', 'title'],
-      ['description', 'dialog-body'],
+      ['description', 'description'],
       ['intro', 'dialog-body'],
       ['submitLabel', 'button'],
       ['cancelLabel', 'button'],
@@ -202,7 +203,7 @@ const JSX_PROP_ROLES = new Map([
     'ActionListDialog',
     new Map([
       ['title', 'title'],
-      ['description', 'dialog-body'],
+      ['description', 'description'],
       ['intro', 'dialog-body'],
       ['emptyMessage', 'empty-state'],
       ['errorMessage', 'error'],
@@ -255,6 +256,7 @@ const JSX_PROP_ROLES = new Map([
     'Page',
     new Map([
       ['title', 'title'],
+      ['description', 'description'],
     ]),
   ],
   [
@@ -1503,6 +1505,7 @@ export function extractCopyFromSource(file, sourceText) {
     addProperty(object, 'label', 'label', prefix)
     addProperty(object, 'placeholder', 'placeholder', prefix)
     addProperty(object, 'help', 'helper-text', prefix)
+    addProperty(object, 'hint', 'helper-text', prefix)
     nestedObject(object, 'options', optionItems, prefix)
   }
 

package/docs/adr/0014-structural-headers-do-not-carry-description.md

@@ -1,6 +1,6 @@
 # ADR 0014 — Headers estruturais não carregam descrição
 
-- **Status:** aceita.
+- **Status:** substituída pela ADR 0059 (subheading opcional para orientação).
 - **Data:** 2026-09-11.
 - **Complementa:** ADRs 0005, 0011 e 0018.
 

package/docs/adr/0018-modal-header-only-names-the-surface.md

@@ -3,7 +3,7 @@
 > Publicada originalmente com o número 0012, que colidia com a ADR de Produtos de Dados do mesmo
 > dia. Renumerada em 2026-09-16; o conteúdo não mudou.
 
-- **Status:** aceita.
+- **Status:** parcialmente substituída pela ADR 0059 (subheading opcional no cabeçalho).
 - **Data:** 2026-09-11.
 
 ## Contexto

package/docs/adr/0023-surfaces-share-one-anatomy-and-two-layouts.md

@@ -158,6 +158,10 @@ anteriores já os delimitaram:
 | Body        | sim  | sim                  | sim            | sim                 | sim            | sim  |
 | Footer      | sim  | não                  | sim            | sim                 | sim            | sim  |
 
+> **Atualização (2026-10-09):** a ADR 0059 substitui a restrição de descrição abaixo. Page, Dialog
+> e Drawer passam a aceitar subheading opcional de orientação; regras necessárias ficam no corpo
+> ou junto dos controles. A tabela registra a decisão original desta ADR.
+
 As ADRs 0009, 0014 e 0018 não são reabertas: Page, Dialog e Drawer continuam sem descrição no
 header, e Page continua sem contador. `Dialog`, `Drawer` e `Pane` ganham o slot de ações que hoje
 não têm — a ausência obrigava a injetar nós soltos ao lado do título, e o `Studio` a manter três

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/0059-subheadings-orient-without-carrying-business-rules.md

@@ -0,0 +1,51 @@
+# ADR 0059 — Subheadings orientam sem carregar regras de negócio
+
+- **Status:** aceita para implementação local; publicação pendente.
+- **Data:** 2026-10-09.
+- **Substitui:** ADR 0014.
+- **Substitui parcialmente:** ADRs 0018 e 0023, quanto à proibição de descrição no cabeçalho.
+
+## Contexto
+
+A proibição de descrições nos cabeçalhos evitou texto de preenchimento, mas também deslocou
+orientações úteis para o corpo. A distinção necessária é semântica: uma frase que apresenta a
+finalidade da superfície pode ser ignorada sem comprometer a tarefa; uma regra ou consequência
+necessária à decisão precisa estar visível no ponto em que será usada.
+
+## Decisão
+
+Page, Surface (inclusive os usos antes atendidos por Content e Card), Dialog e Drawer aceitam um
+subheading opcional sob o título. A API usa `description` e os slots `PageDescription`,
+`SurfaceDescription`, `DialogDescription` e `DrawerDescription`. Não há texto padrão nem obrigação
+de preencher esse espaço. Frases que apenas repetem o título são omitidas.
+
+“Escolha onde a pasta ‘Produtos’ e suas subpastas aparecem.” orienta a tarefa e pode ocupar esse
+slot. “O motivo define se a observação é obrigatória e qual pendência será criada.” comunica regras:
+as condições precisam acompanhar os respectivos campos, ações ou conteúdo. O tamanho da frase não
+altera essa classificação. A pergunta de revisão é: ao pular o subheading, a pessoa ainda consegue
+decidir e concluir corretamente?
+
+`ActionFormDialog` e `ActionListDialog` separam `description`, orientação no cabeçalho, de `intro`,
+contexto necessário no corpo. Quando ambos existem, a descrição acessível relaciona ambos os IDs.
+Nas composições diretas, o consumidor mantém controle explícito de `aria-describedby`.
+A API imperativa de decisões permanece com `body`: confirmações devem apresentar seus efeitos no
+conteúdo da decisão. Fieldsets mantêm somente nome e mídia na legenda.
+
+## Alternativas e consequências
+
+Manter a proibição exigiria recriar subheadings no consumidor. Mover toda descrição para o
+cabeçalho esconderia regras em uma região visual secundária. A escolha preserva os textos
+necessários no corpo e permite orientação breve com a anatomia compartilhada.
+
+As APIs são aditivas; `intro` existente não muda de lugar. A classificação semântica exige revisão
+contextual de copy e não pode ser provada por uma busca de palavras ou limite de caracteres.
+`FieldSpec.hint` mantém visível a orientação necessária junto ao controle; `help` oferece detalhe
+complementar no ícone. Ambos podem coexistir sem repetir texto. Hint e erro participam da descrição
+acessível do controle. A escolha depende da necessidade para decidir, não do tamanho da frase.
+A Base mantém o princípio de comunicação; o Opus mantém componentes, documentação e extração.
+
+## Verificação
+
+Testar composição, omissão, coexistência com `intro`, associação acessível e extração de copy.
+O checker deve aceitar os novos slots em seus pais e continuar rejeitando anatomias inválidas.
+Validar no consumidor os exemplos de organização de pastas e configuração de motivos de perda.

package/docs/adr/README.md

@@ -10,3 +10,5 @@ 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.
+
+- [ADR 0059 — Subheadings orientam sem carregar regras de negócio](0059-subheadings-orient-without-carrying-business-rules.md).

package/package.json

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

package/registry/skills/build-opus-ui/references/evaluations.md

@@ -66,3 +66,11 @@
   sobreporem.
 - Reprova: dimensionar select inline de filtro pelo conteúdo ou pela label (`min-w-*` solto,
   largura calculada), em vez da largura fixa do pattern.
+
+## Orientação, hint e help
+
+Construir um formulário com orientação breve no cabeçalho, regra de seleção vazia e explicação
+complementar do termo. Esperado: `description` orienta a finalidade, `hint` mantém visível o efeito
+de deixar vazio e `help` oferece somente o detalhe opcional. `intro` continua no corpo quando a
+regra afeta vários campos. Reprovar regra obrigatória somente em subheading ou tooltip, repetição
+da label, duplicação entre hint/help e perda de `aria-describedby` quando aparece um erro.

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -10,11 +10,11 @@
 - `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
   explícita exige `PageBody`, exatamente um heading principal e aceita `PageHeader` e `PageFooter`.
   Declare esse heading com `PageTitle` no header, `Surface level={1}` ou um `PageState` ativo no
-  body. `PageHeader` é a única introdução estrutural e reúne navegação, título e ações. `title` e `actions` no
-  próprio `Page` são a abreviação para o caso direto.
+  body. `PageHeader` é a única introdução estrutural e reúne navegação, título, `PageDescription`
+  opcional e ações. `title`, `description` e `actions` no próprio `Page` abreviam o caso direto.
   Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
   real de largura; não reconstruir esse container em cada rota.
-- `PageHeader` declara navegação contextual, título e ações. Em uma subpágina simples, `PageBack`
+- `PageHeader` declara navegação contextual, título, subheading opcional e ações. Em uma subpágina simples, `PageBack`
   recebe o destino pai explícito e aparece acima da linha do título como controle somente com
   ícone. Para mais de um ancestral relevante, use
   `Breadcrumb` dentro de `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome
@@ -92,7 +92,9 @@ SurfaceTitle, SurfaceDescription, SurfaceMeta, SurfaceActions) + SurfaceBody + S
   cancelamento a `outline`.
 - Cabeçalhos de `Dialog` e `Drawer` nomeiam a superfície com o título e organizam suas ações. O close
   padrão é o `CloseButton` (`neutral`, `subtle`, pílula) no final do header, sem posição flutuante
-  alternativa. Não preencher uma segunda linha por hábito. Consequência, restrição ou instrução que
+  alternativa. `PageDescription`, `SurfaceDescription`, `DialogDescription` e `DrawerDescription`
+  orientam brevemente sobre a finalidade; wrappers usam `description`. Omitir repetição do título.
+  Pular esse subheading não pode comprometer a decisão. Consequência, restrição ou instrução que
   realmente mude a tarefa entra no início de `DialogBody`/`DrawerBody`, como texto ou `Alert`;
   wrappers usam `intro` e a API imperativa usa `body`. Relacione texto conciso por
   `aria-describedby` somente quando ele também precisar descrever a superfície para tecnologias
@@ -219,3 +221,11 @@ cells={{
 // Risco comportamental usado como nome visual.
 <Button variant="destructive">Excluir</Button>
 ```
+
+## Orientação de campo
+
+Usar `FieldSpec.hint` para condição, formato ou consequência necessários à escolha, sempre visível
+abaixo do controle. Reservar `FieldSpec.help` ao ícone com detalhe complementar sob demanda.
+Omitir repetição da label; combinar ambos somente com funções distintas. Regra de vários campos
+pertence ao corpo ou ao grupo. Em composição manual, `FieldDescription` e erro entram juntos no
+`aria-describedby` do controle.