@softize/opus 25.7.0 → 26.1.0

package/src/ui/docs/content/action-form.md

@@ -84,12 +84,21 @@ do mesmo peso visual. Nesse caso, o cancelamento muda para `outline`, salvo esco
 `cancelVariant`. Para apresentar o formulário como uma seção delimitada da página, use
 [`ActionFormCard`](/ui/action-form-card). As propriedades de cada wrapper estão na página dele.
 
-## Ajuda no rótulo
+## Hint visível ou ícone de help
 
-`FieldSpec.help` aparece como um ícone junto ao rótulo, com o texto em um tooltip. Escreva ali o
-critério, o efeito ou a limitação que o rótulo não diz; ajuda que só repete o rótulo deve ser omitida.
-Não existe texto auxiliar sob o campo: quem precisa de uma frase permanente abaixo do controle usa
-`FieldDescription` na composição própria.
+Use `FieldSpec.hint` abaixo do controle quando a pessoa precisar da informação para preencher
+corretamente ou prever o efeito da escolha. Exemplo: “Sem áreas selecionadas, a pasta aparece em
+todas as áreas.” O texto permanece visível e participa do `aria-describedby` do controle, junto
+do erro quando houver. Em uma composição própria, use `FieldDescription` com a mesma associação.
+
+Use `FieldSpec.help` no ícone junto à label para detalhes complementares, definições e exemplos
+opcionais. A pergunta é: sem abrir essa ajuda, a pessoa ainda consegue escolher corretamente?
+Se não, o trecho necessário deve ser hint. Não use o comprimento da frase como critério nem
+esconda uma condição obrigatória no tooltip. Omita texto que apenas repete a label.
+
+Hint e help podem coexistir se tiverem funções diferentes, sem duplicar a mesma frase. Um erro
+explica uma entrada inválida e sua correção; não substitui uma orientação necessária antes de
+preencher. Uma regra que afeta vários campos pertence ao corpo ou ao grupo correspondente.
 
 `LabelHelp` é esse mesmo ícone, exportado para um formulário sem contrato mostrar a ajuda no mesmo
 lugar:
@@ -185,3 +194,7 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 | Propriedade | Tipo     | Descrição                                                    |
 | ----------- | -------- | ------------------------------------------------------------ |
 | `help`      | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
+
+O `hint` aceita texto ou `I18nRef` e permanece visível; o contexto do formulário entrega o texto
+resolvido aos campos personalizados. O botão de `help` participa do Tab e abre por foco ou hover.
+Dialog e Drawer evitam que a ajuda seja o primeiro foco automático quando há outro controle.

package/src/ui/docs/content/action-list-dialog.md

@@ -96,6 +96,13 @@ const roleOptions = roles.items.map((role) => ({ value: role.id, label: role.nam
 </ActionListDialog>;
 ```
 
+## Orientação e contexto
+
+`description` apresenta a finalidade no cabeçalho, como “Escolha onde a pasta e suas subpastas
+aparecem.”. É opcional; não repita o título. `intro` apresenta no corpo informações necessárias
+à decisão que não pertencem a um campo específico. Regras, condições e consequências não ficam
+somente no subheading. Quando ambos são fornecidos, ambos participam de `aria-describedby`.
+
 ## Propriedades de ActionListDialog
 
 | Propriedade                                | Tipo                                | Padrão               | Descrição                                                                                         |
@@ -103,6 +110,7 @@ const roleOptions = roles.items.map((role) => ({ value: role.id, label: role.nam
 | `action / input`                           | `ListAction / TInput`               | `input`: `{}`        | O contrato e o escopo base da consulta. Uma mudança em `input` refaz a consulta; as invalidações declaradas por forms e triggers também. |
 | `open / onOpenChange`                      | `boolean / (open) => void`          |                      | Estado controlado do modal.                                                                       |
 | `title`                                    | `string`                            |                      | Nome da lista exibido no cabeçalho fixo.                                                          |
+| `description` | `ReactNode` | | Orientação opcional sob o título; não recebe regras de negócio. |
 | `intro`                                    | `ReactNode`                         |                      | Contexto relevante no início do corpo, como texto ou `Alert`.                                     |
 | `children`                                 | `(items, refetch) => ReactNode`     |                      | A composição dos itens. Carregamento, erro e vazio já são tratados pelo `ActionList`.            |
 | `note`                                     | `ReactNode`                         |                      | Contexto curto à esquerda da linha de ações. O total de itens já aparece no rodapé do `ActionList`. |

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

@@ -23,6 +23,7 @@ interface AiAdapter {
   runStream?(input: string | AiMessage[], opts: AiRunOptions): AsyncIterable<ChatEvent>
 }
 // opts: { system?, model?, maxTokens?, temperature? } — tudo tem default do driver.
+// AiMessage: { role: 'user' | 'assistant', content: string | AiContentPart[] } (ver Mensagem com imagem).
 ```
 
 ## Driver
@@ -125,6 +126,51 @@ O driver Anthropic emite o texto em trechos, à medida que chega, quando o clien
 `messages.stream`. Com um client que só tem `create`, como um client falso de teste, o texto de cada
 passo sai num único trecho. O componente [Chat](/ui/chat) consome os dois modos.
 
+## Mensagem com imagem
+
+Uma mensagem pode levar imagens junto com o texto, para o modelo ler um print, uma tabela ou um
+gráfico. Nesse caso, `content` deixa de ser texto e passa a ser uma lista de partes, em uma forma que
+não depende do provedor:
+
+```ts
+const messages: AiMessage[] = [
+  {
+    role: 'user',
+    content: [
+      { type: 'text', text: 'Imagem 1: vendas.png' },
+      { type: 'image', mediaType: 'image/png', data: base64 }, // sem o prefixo data:
+      { type: 'text', text: 'Reproduza este relatório.' },
+    ],
+  },
+]
+await runtime.aiFor(base)!.run(messages)
+```
+
+Os formatos aceitos são PNG, JPEG e WebP, e a imagem só pode estar em uma mensagem `user`. O driver
+Anthropic converte cada parte para o bloco da API, em `run` e em `runStream`; uma parte que ele não
+conhece, uma imagem em outro formato ou uma imagem na fala do assistente fazem a chamada falhar com
+erro antes de chegar ao provedor, em vez de a imagem sumir em silêncio. `complete` e `extract`
+continuam recebendo texto.
+
+A parte de imagem não tem nome. Para que a pessoa e o modelo possam falar da “imagem 2”, ponha uma
+parte de texto com o rótulo antes de cada imagem, como no exemplo. Imagens vão antes da pergunta,
+como a Anthropic recomenda.
+
+Quando precisar só do texto de uma mensagem, por exemplo para o título da conversa ou para montar um
+bloco de contexto, use `aiMessageText(message)`. Ele devolve o texto puro ou as partes de texto unidas
+por uma linha em branco, sem as imagens. Interpolar `content` direto num template produz
+“[object Object]” quando a mensagem tem partes, e o compilador não aponta esse uso.
+
+```ts
+import { aiMessageText } from '@softize/opus/ai'
+
+const title = aiMessageText(messages[0]).slice(0, 80) || 'Conversa com imagem'
+```
+
+O pacote não guarda imagem. Enviar, guardar, expirar e mostrar de novo a imagem são do aplicativo; na
+interface, o [Chat](/ui/chat#imagens-na-conversa) recebe as imagens prontas e mostra as que o
+aplicativo devolve no transcript.
+
 ## Limites atuais
 
 `run` e `runStream` aceitam o histórico da conversa, mas não mantêm memória longa nem resumem o

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

@@ -168,17 +168,111 @@ com o rótulo já humanizado pelo aplicativo; ou `''`, que mostra somente os pon
 “Pensando…” como nome acessível. No modo autogerenciado, o Chat decide o indicador sozinho e ignora
 `busy` e `activity`.
 
+## Imagens na conversa
+
+No modo controlado, a pessoa pode mandar imagens junto com o texto, como um print para a IA ler.
+Passe `composerAttachments`, com a mesma forma do `attachments` do [Composer](/ui/composer#com-imagens-anexadas):
+o composer ganha o botão **Anexar imagem** e a faixa de imagens, e soltar uma imagem em qualquer
+ponto da conversa também anexa. `onSend` passa a receber, além do texto, as imagens prontas; a
+mensagem pode ter só imagem, sem texto.
+
+O aplicativo guarda as imagens e devolve cada uma no item `user` do transcript, em `attachments`, com
+o endereço que a interface usa para mostrá-la. A fala da pessoa mostra as miniaturas acima do texto,
+com o nome como texto alternativo. Quando a imagem não está mais disponível, o item traz
+`status: 'expired'` e a conversa mostra um cartão com o nome e “Imagem expirada”.
+
+```tsx preview
+const nextId = useRef(2)
+const [items, setItems] = useState<ChatTranscriptItem[]>([
+  {
+    id: '1',
+    role: 'user',
+    content: 'Esse era o painel da semana passada.',
+    attachments: [{ id: 'a0', name: 'painel-antigo.png', mediaType: 'image/png', status: 'expired' }],
+  },
+])
+const [pending, setPending] = useState<ComposerAttachment[]>([])
+const sent = useRef<Record<string, { url: string; mediaType: string }>>({})
+
+// Os endereços de objeto seguram as imagens na memória: revogue ao remover e ao desmontar.
+function release(id: string) {
+  const image = sent.current[id]
+  if (image !== undefined) URL.revokeObjectURL(image.url)
+  delete sent.current[id]
+}
+useEffect(() => () => Object.keys(sent.current).forEach(release), [])
+
+async function add(files: File[]) {
+  for (const file of files) {
+    const id = `a${nextId.current++}`
+    const prepared = await prepareImage(file)
+    if (!prepared.ok) {
+      setPending((list) => [...list, { id, name: file.name, status: 'failed', error: prepared.message }])
+      continue
+    }
+    // Num app real, a imagem vai ao servidor aqui, e o endereço devolvido é o da aplicação.
+    const url = URL.createObjectURL(prepared.file)
+    sent.current[id] = { url, mediaType: prepared.mediaType }
+    setPending((list) => [...list, { id, name: prepared.file.name, status: 'ready', previewUrl: url }])
+  }
+}
+
+render(
+  <div className="h-96 rounded-lg border">
+    <Chat
+      messages={items}
+      composerAttachments={{
+        items: pending,
+        onAddFiles: (files) => void add(files),
+        onRemove: (id) => {
+          release(id)
+          setPending((list) => list.filter((item) => item.id !== id))
+        },
+      }}
+      onSend={(text, attachments = []) => {
+        setItems((list) => [
+          ...list,
+          {
+            id: String(nextId.current++),
+            role: 'user',
+            content: text,
+            attachments: attachments.map((a) => ({
+              id: a.id,
+              name: a.name,
+              status: 'available',
+              ...sent.current[a.id],
+            })),
+          },
+          { id: String(nextId.current++), role: 'assistant', content: 'Recebi a mensagem.' },
+        ])
+        setPending([])
+      }}
+    />
+  </div>,
+)
+```
+
+As miniaturas não passam pelo Markdown: a fala da pessoa continua sendo o que ela escreveu. Sirva o
+endereço pela própria aplicação ou como `data:`; o [Markdown](/ui/markdown) do pacote não carrega
+imagem de outra origem, e as miniaturas seguem o mesmo cuidado. O modo autogerenciado não aceita
+imagens: ele não tem como enviá-las, e `composerAttachments` é ignorado nele.
+
+O arraste de arquivos sobre a conversa é consumido pelo Chat e não sobe para os contêineres do
+aplicativo: um contêiner com o próprio soltar, como uma área de envio de arquivos, não recebe a mesma
+imagem duas vezes. Sem `composerAttachments`, o arraste segue para o contêiner, como antes.
+
 ## Propriedades de Chat
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `send` | `(messages: ChatMessage[]) => Promise<string> \| AsyncIterable<ChatEvent>` | | Modo autogerenciado: recebe o histórico com a nova mensagem e devolve a resposta inteira ou um stream de eventos. Ignorado no modo controlado. |
 | `messages` | `ChatTranscriptItem[]` | | Modo controlado: o transcript vem do aplicativo. Com ele, `onSend`, `busy` e `activity` passam a valer. |
-| `onSend` | `(text: string) => void \| boolean \| Promise<void \| boolean>` | | Modo controlado: recebe o texto enviado; retornar `false` devolve o texto ao composer. |
+| `onSend` | `(text: string, attachments?: ComposerAttachment[]) => void \| boolean \| Promise<void \| boolean>` | | Modo controlado: recebe o texto e, quando há `composerAttachments`, as imagens prontas. Retornar `false` devolve o texto ao composer; as imagens continuam na faixa. |
 | `busy` | `boolean` | `false` | Modo controlado: bloqueia o envio enquanto o turno corre; a digitação continua liberada. |
 | `activity` | `string \| null` | `undefined` | Modo controlado: indicador de atividade. `undefined` esconde, `null` mostra “Pensando…”, uma string mostra o rótulo e `''` mostra somente os pontos. |
 | `notice` | `ReactNode` | | Aviso do aplicativo acima do composer, como credencial expirada ou agente desatualizado. |
 | `composerActions` | `ReactNode` | | Seletores discretos na barra do composer, como agente, aplicativo ou escopo. |
+| `composerAttachments` | `ComposerAttachments` | | Modo controlado: liga as imagens anexadas no composer e o soltar sobre a conversa. Ignorado no modo autogerenciado. |
 | `composerClassName` | `string` | | Ajusta o contêiner externo do composer sem alcançar o DOM interno. |
 | `greeting` | `string` | | Texto do estado vazio; some quando a conversa começa. |
 | `empty` | `ReactNode` | | Estado vazio composto pelo aplicativo; vence `greeting` quando os dois existem. |
@@ -195,6 +289,7 @@ com o rótulo já humanizado pelo aplicativo; ou `''`, que mostra somente os pon
 | Tipo | Forma | Uso |
 |---|---|---|
 | `ChatMessage` | `{ id?, createdAt?, role: 'user' \| 'assistant', content }` | Histórico enviado a `send` e aceito por `initialMessages`. `createdAt` é um instante ISO-8601. |
-| `ChatTranscriptItem` | `ChatMessage` com `role` também `'error'`, ou `{ id?, createdAt?, role: 'artifact', artifact: ChatArtifact }` | Itens de `messages` no modo controlado. Mensagens `error` aparecem destacadas no transcript. |
+| `ChatTranscriptItem` | `ChatMessage` com `role` também `'error'` e `attachments?`, ou `{ id?, createdAt?, role: 'artifact', artifact: ChatArtifact }` | Itens de `messages` no modo controlado. Mensagens `error` aparecem destacadas no transcript; `attachments` só vale na fala `user`. |
+| `ChatAttachment` | `{ id, name, mediaType, width?, height?, status: 'available' \| 'expired', url? }` | Imagem de uma fala da pessoa. `url` é o endereço fornecido pelo aplicativo; a imagem expirada não precisa dele. |
 | `ChatTranscriptMessage` | Os itens de `ChatTranscriptItem` que têm `content` | Argumento de `renderMessageActions`. |
 | `ChatArtifact` | `{ kind, ref, title? }` | Algo produzido na conversa, como um link ou um relatório; `ref` é o endereço ou identificador. |

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

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

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

@@ -150,8 +150,21 @@ Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem)
 [`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
 quadrado `icon-sm` (1.75rem) por padrão.
 
-O cabeçalho não recebe descrição: um modal já é a superfície de uma tarefa, e o contexto que ajuda a
-decidir aparece no começo do corpo, como texto ou `Alert`.
+O cabeçalho aceita `DialogDescription` como subheading opcional para orientar sobre a finalidade.
+Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
+ficam junto dos controles ou em `DialogBody`. Uma frase curta também pode ser regra: o critério é se
+pular o texto compromete a decisão, não sua extensão.
+
+```tsx
+<DialogHeader>
+  <DialogTitle>Organizar pasta</DialogTitle>
+  <DialogDescription>Escolha onde a pasta e suas subpastas aparecem.</DialogDescription>
+</DialogHeader>
+```
+
+Na composição direta, associe o `id` do texto por `aria-describedby` em `DialogContent` quando ele
+descrever a superfície para tecnologias assistivas. A regra sobre seleção vazia pertence ao
+campo de áreas e permanece fora do subheading.
 
 ## Identificar a tarefa com um ícone
 
@@ -634,3 +647,12 @@ conteúdo no primeiro bloco de `DialogBody`. `DialogIntro` exige um `DialogTitle
 
 No formato compacto, mantenha `DialogTitle` e `DialogActions` no próprio `DialogHeader`. Para
 comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).
+
+## Propriedades de DialogDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação opcional sob o título em `DialogHeader` ou `DialogIntro`. |
+| `id` | `string` | | Identificador para associação acessível explícita. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `ComponentProps<"p">` | | Atributos nativos. |

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

@@ -148,8 +148,21 @@ Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem)
 [`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
 quadrado `icon-sm` (1.75rem) por padrão.
 
-O cabeçalho não recebe descrição: o painel já nomeia o recurso, e o contexto que ajuda a decidir
-aparece no começo do corpo, como texto ou `Alert`.
+O cabeçalho aceita `DrawerDescription` como subheading opcional para orientar sobre a finalidade.
+Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
+ficam junto dos controles ou em `DrawerBody`. Uma frase curta também pode ser regra: o critério é se
+pular o texto compromete a decisão, não sua extensão.
+
+```tsx
+<DrawerHeader>
+  <DrawerTitle>Organizar pasta</DrawerTitle>
+  <DrawerDescription>Escolha onde a pasta e suas subpastas aparecem.</DrawerDescription>
+</DrawerHeader>
+```
+
+Na composição direta, associe o `id` do texto por `aria-describedby` em `DrawerContent` quando ele
+descrever a superfície para tecnologias assistivas. A regra sobre seleção vazia pertence ao
+campo de áreas e permanece fora do subheading.
 
 ## Impedir o fechamento durante uma operação
 
@@ -301,3 +314,12 @@ Assim o título acompanha o conteúdo rolável enquanto o chrome permanece está
 
 No formato compacto, mantenha `DrawerTitle` e `DrawerActions` no próprio `DrawerHeader`. Para
 comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).
+
+## Propriedades de DrawerDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação opcional sob o título em `DrawerHeader` ou `DrawerIntro`. |
+| `id` | `string` | | Identificador para associação acessível explícita. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `ComponentProps<"p">` | | Atributos nativos. |

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

@@ -1,7 +1,7 @@
 ## Esqueleto de página
 
 Use `Page` para manter cabeçalho, estado e conteúdo na mesma anatomia. `PageHeader` é a única
-introdução estrutural: reúne navegação contextual opcional, título e ações. O container é
+introdução estrutural: reúne navegação contextual opcional, título, orientação opcional e ações. O container é
 centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). Use `className` somente quando
 a composição pedir outro teto ou largura total.
 
@@ -41,6 +41,19 @@ render(
 );
 ```
 
+## Orientar sobre a finalidade
+
+Use `description` na forma curta ou `PageDescription` em `PageHeader` quando uma frase breve
+ajudar a reconhecer a finalidade da página. Omita texto que só repita o título. Regras de negócio,
+limites e consequências ficam nos campos, ações ou corpo em que são necessários. Pular o
+subheading não deve comprometer a decisão nem a conclusão correta da tarefa.
+
+```tsx
+<Page title="Conhecimento" description="Consulte os materiais de apoio da sua área.">
+  <KnowledgeList />
+</Page>
+```
+
 ## Retorno para a página pai
 
 Use `PageBack` em uma subpágina simples. O destino é explícito para continuar correto após refresh ou
@@ -311,6 +324,7 @@ estado na própria seção com [`DataState`](/ui/data-state), [`ActionView`](/ui
 
 | Propriedade | Tipo                       | Padrão      | Descrição                                                                                                                                                          |
 | ----------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `description` | `ReactNode` | | Orientação opcional sob o título na forma curta. |
 | `title`     | `ReactNode`                |             | O h1 da página.                                                                                                                                                    |
 | `actions`   | `ReactNode`                |             | Ações contextuais no extremo oposto do cabeçalho.                                                                                                                  |
 | `layout`    | `'flow' \| 'fill'`         | `'flow'`    | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role e leva essa altura até uma `ActionList` composta em `PageBody`. |
@@ -414,3 +428,11 @@ ocupa a altura.
 | `retryLabel`   | `string`                                     | `'Tentar de novo'`                        | Texto do botão de recuperação.                                                                              |
 | `children`     | `ReactNode`                                  |                                           | Conteúdo renderizado somente em `ready`.                                                                    |
 | `className`    | `string`                                     |                                           | Classes da superfície de estado.                                                                            |
+
+## Propriedades de PageDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação breve e opcional; filho direto de `PageHeader`. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `HTMLAttributes<HTMLParagraphElement>` | | Atributos nativos. |

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

@@ -131,12 +131,11 @@ render(
     as="section"
     framed
     title="Plano atual"
-    description="Renova em 12 de maio."
     level={3}
   >
     <SurfaceBody>
       <p className="text-sm text-muted-foreground">
-        Até 10 workspaces e 50 agentes.
+        Renova em 12 de maio. Até 10 workspaces e 50 agentes.
       </p>
     </SurfaceBody>
     <SurfaceFooter>
@@ -511,3 +510,10 @@ um wrapper filho declara relações locais mais compactas.
 | ----------- | ----------- | ------ | ---------------------------------------------------- |
 | `children`  | `ReactNode` |        | Ações persistentes, alinhadas no fim da linha.       |
 | `className` | `string`    |        | Ajusta o rodapé, inclusive a distribuição das ações. |
+
+## Subheading e regras de negócio
+
+`description` e `SurfaceDescription` apresentam brevemente a finalidade da região. A orientação
+é opcional e não repete o título. A mesma regra vale para uma página (`level={1}`), uma seção ou
+um card: condições, limites e consequências necessários à decisão ficam no corpo ou junto do
+controle correspondente. Pular o subheading não deve comprometer a tarefa.

package/src/ui/lib/modal-layers.ts

@@ -143,6 +143,21 @@ function syncHosts(): void {
   }
 }
 
+/** A ajuda permanece no Tab, mas não toma o foco inicial do campo ao abrir um modal. */
+export function skipHelpOnAutoFocus(event: Event): void {
+  if (event.defaultPrevented || !(event.target instanceof HTMLElement)) return;
+  const candidates = tabbables(event.target).filter(
+    (element) => element.tagName !== "A",
+  );
+  if (candidates[0]?.dataset.slot !== "label-help") return;
+  const control = candidates.find(
+    (element) => element.dataset.slot !== "label-help",
+  );
+  if (control === undefined) return;
+  control.focus();
+  if (document.activeElement === control) event.preventDefault();
+}
+
 /** Elementos alcançáveis pelo Tab dentro de `root`, na ordem do documento. */
 function tabbables(root: HTMLElement): HTMLElement[] {
   const nodes: HTMLElement[] = [];
@@ -178,7 +193,10 @@ function tabbables(root: HTMLElement): HTMLElement[] {
 function focusFromKeyboard(element: HTMLElement): void {
   element.focus();
   // O Tab do navegador seleciona o texto do campo que recebe o foco; a passagem manual imita.
-  if (element instanceof HTMLInputElement && typeof element.select === "function") {
+  if (
+    element instanceof HTMLInputElement &&
+    typeof element.select === "function"
+  ) {
     element.select();
   }
 }
@@ -342,7 +360,10 @@ export function registerFloatingLayer(
   // podem tratar o Tab e marcá-lo com `preventDefault`.
   const onKeyDown = (event: KeyboardEvent): void => {
     if (!isTabKey(event) || event.defaultPrevented) return;
-    if (!layerExemptionsActive() || layerOf(document.activeElement) !== record) {
+    if (
+      !layerExemptionsActive() ||
+      layerOf(document.activeElement) !== record
+    ) {
       return;
     }
     const candidates = tabbables(host);
@@ -361,7 +382,10 @@ export function registerFloatingLayer(
     if (layerWherePersonIs() === record) escape()?.(event);
   };
   const observer = new MutationObserver(() => {
-    if (pointerAnchor !== null && pointerAnchor.parentNode !== pointerLayer?.host) {
+    if (
+      pointerAnchor !== null &&
+      pointerAnchor.parentNode !== pointerLayer?.host
+    ) {
       // O painel apertado saiu da camada, como quando é fechado por código e vira o FAB.
       pointerAnchor = null;
       pointerLayer = null;