@softize/opus 25.7.0 → 26.0.0

package/src/ui/components/primitives/composer.tsx

@@ -1,10 +1,58 @@
 import * as React from "react";
-import { SendHorizontalIcon } from "lucide-react";
+import { ImageIcon, ImagePlusIcon, SendHorizontalIcon, XIcon } from "lucide-react";
+import type { AiImageMediaType } from "../../../core/index.ts";
 import { cn } from "../../lib/cn.ts";
+import { IMAGE_MEDIA_TYPES, imageTypeList } from "../../lib/prepare-image.ts";
 import { Button } from "./button.tsx";
 import { Spinner } from "./spinner.tsx";
 import { Textarea } from "./textarea.tsx";
 
+/** Estado de um anexo pendente: enviando, pronto para ir com a mensagem ou com falha. */
+export type ComposerAttachmentStatus = "uploading" | "ready" | "failed";
+
+/** Um anexo pendente da mensagem, no estado que o app mantém (ADR 0058). */
+export interface ComposerAttachment {
+  /** Identidade estável do anexo, dada pelo app. */
+  id: string;
+  /** Nome mostrado na faixa; identifica o anexo também para leitores de tela. */
+  name: string;
+  status: ComposerAttachmentStatus;
+  /** Endereço da miniatura (por exemplo, `URL.createObjectURL` da imagem preparada). */
+  previewUrl?: string;
+  /** Motivo da falha, mostrado no lugar do estado quando `status` é `failed`. */
+  error?: string;
+}
+
+/** Um arquivo recusado pela triagem: fora dos tipos aceitos ou além do limite da mensagem. */
+export interface ComposerFileRejection {
+  file: File;
+  reason: "type" | "limit";
+}
+
+/**
+ * Anexos da mensagem, controlados pelo app (ADR 0058). O composer faz a triagem e mostra a faixa;
+ * preparar, enviar, guardar e limpar depois do envio são do app, que é o dono do transporte.
+ */
+export interface ComposerAttachments {
+  /** Anexos pendentes, na ordem em que aparecem na faixa. */
+  items: ComposerAttachment[];
+  /** Recebe os arquivos aceitos pela triagem — do botão, do colar ou do soltar. */
+  onAddFiles: (files: File[]) => void;
+  /** A pessoa removeu um anexo da faixa. */
+  onRemove: (id: string) => void;
+  /** Limite de anexos por mensagem. Padrão: 4. */
+  max?: number;
+  /** Formatos aceitos, um subconjunto dos que a mensagem da IA leva. Padrão: PNG, JPEG e WebP.
+   *  Não há curinga (`image/*`): a triagem compara o tipo exato do arquivo. */
+  accept?: readonly AiImageMediaType[];
+  /** Recebe os arquivos recusados. Presente, a explicação da recusa é do app; ausente, o
+   *  composer a mostra acima do campo. */
+  onReject?: (rejections: ComposerFileRejection[]) => void;
+}
+
+/** Limite padrão de anexos por mensagem. */
+export const COMPOSER_MAX_ATTACHMENTS = 4;
+
 export interface ComposerProps {
   /** Texto (controlado): o dono do estado é o consumidor — o `<Chat>` por dentro, ou o app
    *  (ex.: o composer de criação de sessão do Maestro, que nem tem histórico). */
@@ -29,15 +77,165 @@ export interface ComposerProps {
    *  embaixo); ausente → linha única (textarea + enviar inline), o composer clássico do Chat.
    *  Estilize os controles como discretos (ghost/sem borda) — a barra não é um formulário. */
   actions?: React.ReactNode;
+  /** Anexos da mensagem (ADR 0058). Presente → duas linhas, faixa de anexos acima do texto,
+   *  botão **Anexar imagem** na barra, colar e soltar imagens; ausente → só texto. */
+  attachments?: ComposerAttachments;
   className?: string;
 }
 
+/**
+ * Ponte interna entre o `<Chat>` e o seu composer: o Chat recebe o soltar sobre a conversa
+ * inteira e entrega os arquivos à mesma triagem do composer. Não faz parte da API pública.
+ */
+export const ComposerDropBridge = React.createContext<React.RefObject<
+  ((files: File[]) => void) | null
+> | null>(null);
+
+/** O arraste traz arquivos (e não texto ou um link). */
+export function dragHasFiles(transfer: DataTransfer | null): boolean {
+  return transfer !== null && Array.from(transfer.types ?? []).includes("Files");
+}
+
+const PASTED_EXTENSIONS: Record<string, string> = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+};
+
+/** A imagem colada chega como "image.png"; ganha um nome que a pessoa reconhece na conversa. O
+ *  número vem de um contador da instância, que não volta atrás: remover "Imagem colada 1" e colar
+ *  de novo dá "Imagem colada 3", e não uma segunda "Imagem colada 1" na mesma conversa. */
+function namePasted(file: File, position: number): File {
+  const extension = PASTED_EXTENSIONS[file.type];
+  if (extension === undefined) return file;
+  return new File([file], `Imagem colada ${position}${extension}`, {
+    type: file.type,
+    lastModified: file.lastModified,
+  });
+}
+
+function rejectionMessage(
+  rejections: ComposerFileRejection[],
+  accept: readonly AiImageMediaType[],
+  max: number,
+): string {
+  const parts: string[] = [];
+  if (rejections.some((r) => r.reason === "type")) {
+    parts.push(`Só é possível anexar imagens ${imageTypeList(accept)}.`);
+  }
+  if (rejections.some((r) => r.reason === "limit")) {
+    parts.push(
+      max === 1 ? "Cada mensagem aceita 1 imagem." : `Cada mensagem aceita até ${max} imagens.`,
+    );
+  }
+  return parts.join(" ");
+}
+
+/** O que mudou nos anexos desde o render anterior, para a região viva anunciar. */
+function statusAnnouncement(
+  previous: ReadonlyMap<string, ComposerAttachmentStatus>,
+  items: ComposerAttachment[],
+): string | null {
+  const changes: string[] = [];
+  for (const item of items) {
+    const before = previous.get(item.id);
+    if (before === item.status) continue;
+    if (item.status === "ready") changes.push(`${item.name} pronta para enviar.`);
+    else if (item.status === "failed") changes.push(`${item.name}: ${statusLabel(item)}`);
+  }
+  return changes.length > 0 ? changes.join(" ") : null;
+}
+
+function statusLabel(item: ComposerAttachment): string {
+  if (item.status === "uploading") return "Enviando…";
+  if (item.status === "failed") return item.error ?? "Não foi possível enviar.";
+  return "Pronta";
+}
+
+/** A faixa de anexos pendentes: miniatura, nome, estado e remover. */
+function AttachmentStrip({
+  items,
+  max,
+  onRemove,
+}: {
+  items: ComposerAttachment[];
+  max: number;
+  onRemove: (item: ComposerAttachment) => void;
+}): React.ReactElement {
+  return (
+    <div data-slot="composer-attachments" className="flex items-end gap-2 px-1 pb-1.5">
+      <ul aria-label="Imagens anexadas" className="flex min-w-0 flex-1 flex-wrap gap-1.5">
+        {items.map((item) => (
+          <li
+            key={item.id}
+            data-slot="composer-attachment"
+            data-status={item.status}
+            aria-busy={item.status === "uploading" || undefined}
+            className={cn(
+              "flex min-w-0 max-w-52 items-center gap-2 rounded-lg border bg-muted/40 p-1 text-xs",
+              item.status === "failed" ? "border-context-danger-border" : "border-border",
+            )}
+          >
+            <span className="relative grid size-10 shrink-0 place-items-center overflow-hidden rounded-md bg-muted">
+              {item.previewUrl !== undefined ? (
+                // O nome está ao lado: a miniatura é decorativa para leitores de tela.
+                <img src={item.previewUrl} alt="" className="size-full object-cover" />
+              ) : (
+                <ImageIcon aria-hidden className="size-4 text-muted-foreground" />
+              )}
+              {item.status === "uploading" && (
+                <span className="absolute inset-0 grid place-items-center bg-background/60">
+                  <Spinner size="xs" />
+                </span>
+              )}
+            </span>
+            <span className="min-w-0 flex-1 leading-tight">
+              <span className="block truncate font-medium text-foreground" title={item.name}>
+                {item.name}
+              </span>
+              <span
+                className={cn(
+                  "block truncate",
+                  item.status === "failed"
+                    ? "text-context-danger-emphasis"
+                    : "text-muted-foreground",
+                )}
+                title={item.status === "failed" ? statusLabel(item) : undefined}
+              >
+                {statusLabel(item)}
+              </span>
+            </span>
+            <Button
+              type="button"
+              size="icon-xs"
+              variant="ghost"
+              shape="pill"
+              aria-label={`Remover ${item.name}`}
+              onClick={() => onRemove(item)}
+              className="shrink-0 self-start text-muted-foreground hover:text-foreground"
+            >
+              <XIcon />
+            </Button>
+          </li>
+        ))}
+      </ul>
+      <span
+        data-slot="composer-attachment-count"
+        className="shrink-0 pb-1 text-xs text-muted-foreground"
+      >
+        {max === 1 ? `${items.length} de 1 imagem` : `${items.length} de ${max} imagens`}
+      </span>
+    </div>
+  );
+}
+
 /**
  * <Composer /> — a caixa de escrever da casa: textarea (Enter envia / Shift+Enter quebra
  * linha) numa pílula elevada (rounded-xl + border + shadow-sm), com o enviar dentro.
  * É o composer do `<Chat>` extraído pra ser reusável SOZINHO — o Maestro cria sessão com
  * ele (sem chat nenhum), e a GB prende seletores nele. Com `actions`, ganha uma barra
- * embaixo pros seletores; sem, é a linha única de sempre.
+ * embaixo pros seletores; sem, é a linha única de sempre. Com `attachments`, ganha a faixa
+ * de anexos e o botão **Anexar imagem** (ADR 0058).
  */
 export function Composer({
   value,
@@ -51,19 +249,118 @@ export function Composer({
   rows = 1,
   autoFocus,
   actions,
+  attachments,
   className,
 }: ComposerProps): React.ReactElement {
-  const canSubmit = value.trim() !== "" && !busy && !submitDisabled;
+  const items = attachments?.items ?? [];
+  const max = attachments?.max ?? COMPOSER_MAX_ATTACHMENTS;
+  const accept = attachments?.accept ?? IMAGE_MEDIA_TYPES;
+  const [notice, setNotice] = React.useState<string | null>(null);
+  const [dragging, setDragging] = React.useState(false);
+  const [announcement, setAnnouncement] = React.useState("");
+  const textareaRef = React.useRef<HTMLTextAreaElement>(null);
+  const fileInputRef = React.useRef<HTMLInputElement>(null);
+  const pastedCount = React.useRef(0);
+  const pickerUsed = React.useRef(false);
+  const previousStatus = React.useRef(new Map<string, ComposerAttachmentStatus>());
+  const bridge = React.useContext(ComposerDropBridge);
+  const full = items.length >= max;
+
+  // Anexo que fica pronto ou falha é anunciado: a mudança na faixa é só visual. O estado com que
+  // o composer nasce não é novidade e não é anunciado.
+  const statusKnown = React.useRef(false);
+  React.useEffect(() => {
+    const next = statusKnown.current ? statusAnnouncement(previousStatus.current, items) : null;
+    statusKnown.current = true;
+    previousStatus.current = new Map(items.map((item) => [item.id, item.status]));
+    if (next !== null) setAnnouncement(next);
+  }, [items]);
+
+  // Quem atinge o limite pelo botão fica com o foco num botão desabilitado; o foco vai ao campo.
+  React.useEffect(() => {
+    if (!full || !pickerUsed.current) return;
+    pickerUsed.current = false;
+    textareaRef.current?.focus();
+  }, [full]);
+
+  // Envio: texto ou pelo menos um anexo pronto; nunca com anexo em envio ou em falha, para que
+  // nada do que está na faixa fique de fora sem aviso.
+  const hasReady = items.some((item) => item.status === "ready");
+  const pending = items.some((item) => item.status !== "ready");
+  const canSubmit = (value.trim() !== "" || hasReady) && !pending && !busy && !submitDisabled;
   const fire = (): void => {
-    if (canSubmit) onSubmit();
+    if (!canSubmit) return;
+    setNotice(null);
+    onSubmit();
+  };
+  const twoRow = actions !== undefined || attachments !== undefined;
+
+  /** Triagem: tipo aceito e espaço na mensagem. Os aceitos vão ao app; os recusados, ao
+   *  `onReject` do app ou ao aviso do composer. */
+  const intake = (files: File[]): void => {
+    if (attachments === undefined || files.length === 0) return;
+    const remaining = Math.max(0, max - items.length);
+    const accepted: File[] = [];
+    const rejected: ComposerFileRejection[] = [];
+    for (const file of files) {
+      if (!(accept as readonly string[]).includes(file.type)) rejected.push({ file, reason: "type" });
+      else if (accepted.length >= remaining) rejected.push({ file, reason: "limit" });
+      else accepted.push(file);
+    }
+    if (accepted.length > 0) attachments.onAddFiles(accepted);
+    if (rejected.length > 0 && attachments.onReject !== undefined) {
+      attachments.onReject(rejected);
+      setNotice(null);
+    } else {
+      setNotice(rejected.length > 0 ? rejectionMessage(rejected, accept, max) : null);
+    }
+  };
+
+  // Dentro do <Chat>, o soltar é recebido pela conversa inteira e chega aqui pela ponte. A
+  // ponte acompanha cada render, para a triagem contar os anexos atuais.
+  React.useEffect(() => {
+    if (bridge === null) return;
+    bridge.current = attachments !== undefined ? intake : null;
+  });
+  React.useEffect(
+    () => () => {
+      if (bridge !== null) bridge.current = null;
+    },
+    [bridge],
+  );
+
+  const remove = (item: ComposerAttachment): void => {
+    attachments?.onRemove(item.id);
+    setNotice(null);
+    // O botão some com o anexo; o foco volta ao campo em vez de cair no documento.
+    textareaRef.current?.focus();
   };
-  const twoRow = actions !== undefined;
 
   const textarea = (
     <Textarea
+      ref={textareaRef}
       autoFocus={autoFocus}
       value={value}
       onChange={(e) => onChange(e.target.value)}
+      onPaste={
+        attachments === undefined
+          ? undefined
+          : (e) => {
+              // Texto vence: copiar células de uma planilha traz texto e uma imagem juntos, e
+              // quem cola ali quer o texto. Só a imagem sem texto, como um print, vira anexo.
+              if (e.clipboardData.getData("text/plain") !== "") return;
+              const files = Array.from(e.clipboardData.files ?? []);
+              if (files.length === 0) return;
+              e.preventDefault();
+              intake(
+                files.map((file) =>
+                  PASTED_EXTENSIONS[file.type] === undefined
+                    ? file
+                    : namePasted(file, (pastedCount.current += 1)),
+                ),
+              );
+            }
+      }
       onKeyDown={(e) => {
         if (e.key === "ArrowUp" && onHistoryPrevious?.()) {
           e.preventDefault();
@@ -101,29 +398,122 @@ export function Composer({
       {busy ? <Spinner size="sm" /> : <SendHorizontalIcon className="size-4" />}
     </Button>
   );
+  const attach = attachments !== undefined && (
+    <>
+      <Button
+        type="button"
+        size="icon-sm"
+        variant="ghost"
+        shape="pill"
+        aria-label="Anexar imagem"
+        title="Anexar imagem"
+        disabled={full}
+        onClick={() => {
+          pickerUsed.current = true;
+          fileInputRef.current?.click();
+        }}
+        onBlur={(e) => {
+          // Abrir o seletor tira o foco da janela (sem destino); ir a outro controle desfaz a marca.
+          if (e.relatedTarget !== null) pickerUsed.current = false;
+        }}
+        className="text-muted-foreground hover:text-foreground"
+      >
+        <ImagePlusIcon />
+      </Button>
+      <input
+        ref={fileInputRef}
+        data-slot="composer-file-input"
+        type="file"
+        accept={accept.join(",")}
+        multiple={max - items.length > 1}
+        hidden
+        tabIndex={-1}
+        onChange={(e) => {
+          intake(Array.from(e.target.files ?? []));
+          // Escolher o mesmo arquivo de novo precisa disparar `change` outra vez.
+          e.target.value = "";
+        }}
+      />
+    </>
+  );
+  // Fora do <Chat>, o próprio composer recebe o soltar.
+  const ownDrop = attachments !== undefined && bridge === null;
 
   return (
     <form
       data-slot="composer"
+      data-dragging={dragging || undefined}
       onSubmit={(e) => {
         e.preventDefault();
         fire();
       }}
+      onDragOver={
+        ownDrop
+          ? (e) => {
+              if (!dragHasFiles(e.dataTransfer)) return;
+              e.preventDefault();
+              e.stopPropagation();
+              setDragging(true);
+            }
+          : undefined
+      }
+      onDragLeave={
+        ownDrop
+          ? (e) => {
+              if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setDragging(false);
+            }
+          : undefined
+      }
+      onDrop={
+        ownDrop
+          ? (e) => {
+              if (!dragHasFiles(e.dataTransfer)) return;
+              e.preventDefault();
+              // O soltar foi consumido aqui; um contêiner do app não deve recebê-lo de novo.
+              e.stopPropagation();
+              setDragging(false);
+              intake(Array.from(e.dataTransfer.files));
+            }
+          : undefined
+      }
       className={cn(
         "rounded-xl border border-border bg-card text-card-foreground shadow-sm transition",
         twoRow ? "p-2" : "relative flex items-end gap-2 p-2 pl-3.5",
+        dragging && "border-primary ring-2 ring-primary/30",
         className,
       )}
     >
       {twoRow ? (
         <>
+          {attachments !== undefined && (
+            // Região viva montada desde o início: um aviso que nasce junto com ela não é
+            // anunciado por todos os leitores de tela.
+            <p
+              role="status"
+              data-slot="composer-attachment-notice"
+              className={cn(
+                notice === null ? "sr-only" : "px-1.5 pb-1.5 text-xs text-context-warning-emphasis",
+              )}
+            >
+              {notice}
+            </p>
+          )}
+          {attachments !== undefined && (
+            <p role="status" data-slot="composer-attachment-announcement" className="sr-only">
+              {announcement}
+            </p>
+          )}
+          {items.length > 0 && <AttachmentStrip items={items} max={max} onRemove={remove} />}
           {textarea}
           <div
             data-slot="composer-actions"
             className="mt-1 flex items-center justify-between gap-2"
           >
-            {/* Seletores à esquerda (discretos), enviar à direita. */}
-            <div className="flex min-w-0 items-center gap-1">{actions}</div>
+            {/* Anexar e seletores à esquerda (discretos), enviar à direita. */}
+            <div className="flex min-w-0 items-center gap-1">
+              {attach}
+              {actions}
+            </div>
             {send}
           </div>
         </>

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. |