@softize/opus 25.6.0 → 26.0.0

package/src/ui/docs/DocCatalog.tsx

@@ -0,0 +1,255 @@
+import { useEffect, type ReactElement, type ReactNode } from "react";
+import { Search } from "lucide-react";
+import { Input } from "../components/primitives/input.tsx";
+import { Badge } from "../components/primitives/badge.tsx";
+import {
+  Alert,
+  AlertHeader,
+  AlertTitle,
+  AlertDescription,
+} from "../components/primitives/alert.tsx";
+import { Markdown, markdownIt } from "../components/primitives/markdown.tsx";
+import {
+  filterDocumentationRecords,
+  type DocumentationRecord,
+} from "./records.ts";
+import { navigate } from "../router.ts";
+
+function follow(
+  event: React.MouseEvent<HTMLAnchorElement>,
+  href: string,
+): void {
+  if (
+    event.button !== 0 ||
+    event.metaKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.altKey
+  )
+    return;
+  event.preventDefault();
+  navigate(href);
+}
+
+function DocumentationLink({
+  href,
+  children,
+}: {
+  href: string;
+  children: ReactNode;
+}): ReactElement {
+  return (
+    <a
+      href={href}
+      onClick={(event) => follow(event, href)}
+      className="underline-offset-4 hover:underline"
+    >
+      {children}
+    </a>
+  );
+}
+
+/** O resumo orienta a escolha; links e formatação continuam no documento completo. */
+function summaryText(source: string): string {
+  return (markdownIt.parseInline(source, {})[0]?.children ?? [])
+    .map((token) =>
+      token.type === "softbreak" || token.type === "hardbreak"
+        ? " "
+        : token.content,
+    )
+    .join("");
+}
+
+export interface DocCatalogProps {
+  title: string;
+  description: string;
+  records: readonly DocumentationRecord[];
+  /** Consulta local do catálogo, independente da busca documental do cabeçalho. */
+  query: string;
+  onQueryChange: (query: string) => void;
+  kind: "decisions" | "releases";
+}
+
+/** Leitura dos arquivos publicados, com busca textual e sem controles de coleção. */
+export function DocCatalog({
+  title,
+  description,
+  records,
+  query,
+  onQueryChange,
+  kind,
+}: DocCatalogProps): ReactElement {
+  const filtered = filterDocumentationRecords(records, query).sort(
+    (left, right) =>
+      kind === "decisions"
+        ? Number(right.id) - Number(left.id)
+        : right.id.localeCompare(left.id, "en", { numeric: true }),
+  );
+  return (
+    <div data-slot="doc-catalog" className="h-full overflow-y-auto">
+      <section className="mx-auto w-full max-w-3xl px-4 py-8 md:px-8 md:py-12">
+        <h1 className="text-3xl font-semibold tracking-tight">{title}</h1>
+        <p className="mt-3 text-base text-muted-foreground">{description}</p>
+        <div className="mt-6 max-w-[28rem]">
+          <Input
+            type="search"
+            icon={<Search aria-hidden="true" />}
+            aria-label={
+              kind === "decisions" ? "Buscar nas ADRs" : "Buscar no changelog"
+            }
+            placeholder={
+              kind === "decisions" ? "Buscar nas ADRs…" : "Buscar no changelog…"
+            }
+            value={query}
+            onChange={(event) => onQueryChange(event.target.value)}
+          />
+        </div>
+        <p
+          role="status"
+          aria-live="polite"
+          aria-atomic="true"
+          className={
+            query.trim() ? "mt-5 text-sm text-muted-foreground" : "sr-only"
+          }
+        >
+          {filtered.length} de {records.length} registros
+        </p>
+        <div className="mt-10 space-y-10">
+          {filtered.map((record) => (
+            <article
+              key={record.href}
+              data-slot="doc-catalog-entry"
+              className="border-t border-border/60 pt-6"
+            >
+              <div className="flex flex-wrap items-baseline gap-x-3 gap-y-2">
+                <h2 className="text-xl font-semibold tracking-tight">
+                  <DocumentationLink href={record.href}>
+                    {kind === "decisions"
+                      ? `ADR ${record.id} — ${record.title}`
+                      : record.id}
+                  </DocumentationLink>
+                </h2>
+                {kind === "releases" && (
+                  <span className="text-sm text-muted-foreground">
+                    {record.date ?? "Data não informada"}
+                  </span>
+                )}
+                {kind === "releases" && record.breaking !== undefined && (
+                  <Badge context="danger" variant="solid">
+                    Incompatível
+                  </Badge>
+                )}
+              </div>
+              {kind === "decisions" ? (
+                <>
+                  <p className="mt-2 text-sm text-muted-foreground">
+                    {record.date ?? "Data não informada"} ·{" "}
+                    {record.status ?? "Status não informado"}
+                  </p>
+                  {record.summary && (
+                    <p className="mt-3 text-sm leading-7">
+                      {summaryText(record.summary)}
+                    </p>
+                  )}
+                </>
+              ) : (
+                <>
+                  <div className="mt-3">
+                    <Markdown
+                      content={record.content ?? record.body}
+                      resolveHref={(href) =>
+                        href.startsWith("#") ? `${record.href}${href}` : href
+                      }
+                    />
+                  </div>
+                  {record.breaking !== undefined && (
+                    <Alert context="danger" role="note" className="mt-4">
+                      <AlertHeader>
+                        <AlertTitle>Breaking: cuidados ao atualizar</AlertTitle>
+                        <AlertDescription>
+                          <Markdown
+                            content={record.breaking}
+                            resolveHref={(href) =>
+                              href.startsWith("#") ? `${record.href}${href}` : href
+                            }
+                          />
+                        </AlertDescription>
+                      </AlertHeader>
+                    </Alert>
+                  )}
+                  {record.afterBreaking && (
+                    <div className="mt-3">
+                      <Markdown
+                        content={record.afterBreaking}
+                        resolveHref={(href) =>
+                          href.startsWith("#") ? `${record.href}${href}` : href
+                        }
+                      />
+                    </div>
+                  )}
+                </>
+              )}
+            </article>
+          ))}
+          {filtered.length === 0 && (
+            <p className="border-t border-border/60 pt-6 text-sm text-muted-foreground">
+              Nenhum registro encontrado. Tente outro termo.
+            </p>
+          )}
+        </div>
+      </section>
+    </div>
+  );
+}
+
+export interface DocRecordDetailProps {
+  catalogLabel: string;
+  children: ReactNode;
+}
+
+export function DocRecordDetail({
+  catalogLabel,
+  children,
+}: DocRecordDetailProps): ReactElement {
+  useEffect(() => {
+    let frame: number | undefined;
+    let locationKey: string | undefined;
+    const scrollToFragment = () => {
+      const nextKey = window.location.pathname + window.location.hash;
+      if (nextKey === locationKey) return;
+      locationKey = nextKey;
+      if (frame !== undefined) cancelAnimationFrame(frame);
+      if (!window.location.hash) return;
+      frame = requestAnimationFrame(() => {
+        let id = window.location.hash.slice(1);
+        try {
+          id = decodeURIComponent(id);
+        } catch {
+          /* Um fragmento inválido não interrompe a leitura. */
+        }
+        document.getElementById(id)?.scrollIntoView({ block: "start" });
+      });
+    };
+    scrollToFragment();
+    window.addEventListener("popstate", scrollToFragment);
+    window.addEventListener("hashchange", scrollToFragment);
+    return () => {
+      if (frame !== undefined) cancelAnimationFrame(frame);
+      window.removeEventListener("popstate", scrollToFragment);
+      window.removeEventListener("hashchange", scrollToFragment);
+    };
+  }, []);
+  return (
+    <div data-slot="doc-record-detail" className="h-full overflow-y-auto">
+      <div className="mx-auto max-w-3xl px-4 py-8 md:px-8">
+        <p
+          data-slot="doc-record-context"
+          className="mb-3 text-sm text-muted-foreground"
+        >
+          {catalogLabel}
+        </p>
+        <article>{children}</article>
+      </div>
+    </div>
+  );
+}

package/src/ui/docs/DocHeader.tsx

@@ -0,0 +1,74 @@
+import type {
+  ComponentProps,
+  CSSProperties,
+  ReactElement,
+  ReactNode,
+} from "react";
+import { cn } from "../lib/cn.ts";
+
+export interface DocHeaderProps extends Omit<
+  ComponentProps<"header">,
+  "children"
+> {
+  brand: ReactNode;
+  search?: ReactNode;
+  actions?: ReactNode;
+  navigation?: ReactNode;
+  /** Largura da coluna de marca, normalmente igual à lateral. Default: 17rem. */
+  brandWidth?: string;
+}
+
+/** Topo documental: controles alinhados e navegação global em uma linha própria. */
+export function DocHeader({
+  brand,
+  search,
+  actions,
+  navigation,
+  brandWidth = "17rem",
+  className,
+  style,
+  ...props
+}: DocHeaderProps): ReactElement {
+  return (
+    <header
+      data-slot="doc-header"
+      className={cn("shrink-0 border-b border-border bg-background", className)}
+      style={
+        { "--doc-header-brand-width": brandWidth, ...style } as CSSProperties
+      }
+      {...props}
+    >
+      <div
+        data-slot="doc-header-controls"
+        className="grid min-h-[4.25rem] grid-cols-[minmax(0,1fr)_auto] items-center gap-x-8 gap-y-4 px-4 py-3 md:px-8 lg:grid-cols-[var(--doc-header-brand-width)_minmax(0,1fr)_var(--doc-header-brand-width)]"
+      >
+        <div data-slot="doc-header-brand" className="min-w-0">
+          {brand}
+        </div>
+        <div
+          data-slot="doc-header-search"
+          className={cn(
+            "col-span-2 row-start-2 min-w-0 lg:col-span-1 lg:col-start-2 lg:row-start-1",
+            search == null && "hidden lg:block",
+          )}
+        >
+          <div className="mx-auto w-full max-w-[22rem]">{search}</div>
+        </div>
+        <div
+          data-slot="doc-header-actions"
+          className="col-start-2 row-start-1 flex items-center justify-end gap-1 lg:col-start-3"
+        >
+          {actions}
+        </div>
+      </div>
+      {navigation != null && (
+        <div
+          data-slot="doc-header-navigation"
+          className="overflow-x-auto px-4 md:px-8"
+        >
+          {navigation}
+        </div>
+      )}
+    </header>
+  );
+}

package/src/ui/docs/browser.tsx

@@ -3,7 +3,16 @@
  * Opus, o compilador de exemplos TSX nem os componentes usados apenas por esses exemplos.
  */
 export { DocBrowser } from './DocBrowser.tsx'
-export type { DocBrowserProps } from './DocBrowser.tsx'
+export { DocHeader } from './DocHeader.tsx'
+export { DocCatalog, DocRecordDetail } from './DocCatalog.tsx'
+export type { DocCatalogProps, DocRecordDetailProps } from './DocCatalog.tsx'
+export { decisionRecord, releaseRecords, parseChangelog, filterDocumentationRecords } from './records.ts'
+export type { DocumentationRecord } from './records.ts'
+export type { DocHeaderProps } from './DocHeader.tsx'
+export type {
+  DocBrowserProps,
+  DocBrowserSearchOptions,
+} from './DocBrowser.tsx'
 export { docSectionsFromFolder } from './folder.tsx'
 export type { FolderOptions, FolderPage } from './folder.tsx'
 export {

package/src/ui/docs/changelog.tsx

@@ -5,43 +5,13 @@
  * O parser é convenção-fina sobre o markdown (`## <versão> — <data>` + `### Breaking`);
  * o corpo de cada trecho segue renderizado pelo DocMarkdown (fidelidade total).
  */
-import { Badge } from '../react.tsx'
+import { Alert, AlertHeader, AlertTitle, AlertDescription, Badge } from '../react.tsx'
 import { DocMarkdown } from './markdown.tsx'
 // A fonte é o CHANGELOG DO PACOTE (raiz) — a mesma que viaja em node_modules.
 import changelogMd from '../../../CHANGELOG.md?raw'
-
-export interface ChangelogVersion {
-  version: string
-  date?: string
-  body: string
-  breaking?: string
-}
-
-export interface ParsedChangelog {
-  intro: string
-  versions: ChangelogVersion[]
-}
-
-/** Parseia o changelog: intro (antes do 1º `## `) + versões (`## x — data`, `### Breaking`). */
-export function parseChangelog(source: string): ParsedChangelog {
-  const chunks = `\n${source.trim()}`.split(/\n## /)
-  const intro = chunks[0]?.trim() ?? ''
-  const versions: ChangelogVersion[] = []
-  for (const chunk of chunks.slice(1)) {
-    const nl = chunk.indexOf('\n')
-    const header = (nl === -1 ? chunk : chunk.slice(0, nl)).trim()
-    const rest = nl === -1 ? '' : chunk.slice(nl + 1)
-    const [version, date] = header.split(/\s+—\s+/)
-    const [body, breaking] = rest.split(/\n### Breaking\s*\n/)
-    versions.push({
-      version: (version ?? header).trim(),
-      ...(date !== undefined ? { date: date.trim() } : {}),
-      body: (body ?? '').trim(),
-      ...(breaking !== undefined ? { breaking: breaking.trim() } : {}),
-    })
-  }
-  return { intro, versions }
-}
+import { parseChangelog } from './records.ts'
+export { parseChangelog } from './records.ts'
+export type { ChangelogVersion, ParsedChangelog } from './records.ts'
 
 export function ChangelogView({ source }: { source: string }): React.ReactElement {
   const { intro, versions } = parseChangelog(source)
@@ -56,16 +26,21 @@ export function ChangelogView({ source }: { source: string }): React.ReactElemen
               {v.date !== undefined && <span className="text-sm text-muted-foreground">{v.date}</span>}
               {v.breaking !== undefined && <Badge context="danger" variant="solid">Incompatível</Badge>}
             </div>
-            {v.body.length > 0 && (
+            {(v.beforeBreaking ?? v.body).length > 0 && (
               <div className="mt-3">
-                <DocMarkdown content={v.body} />
+                <DocMarkdown content={v.beforeBreaking ?? v.body} />
               </div>
             )}
             {v.breaking !== undefined && (
-              <div className="mt-4 rounded-md border border-destructive/30 bg-destructive/5 px-4 py-3">
-                <div className="mb-2 text-xs font-medium text-destructive">Breaking — o que fazer</div>
-                <DocMarkdown content={v.breaking} />
-              </div>
+              <Alert context="danger" role="note" className="mt-4">
+                <AlertHeader>
+                  <AlertTitle>Breaking: cuidados ao atualizar</AlertTitle>
+                  <AlertDescription><DocMarkdown content={v.breaking} /></AlertDescription>
+                </AlertHeader>
+              </Alert>
+            )}
+            {v.afterBreaking && (
+              <div className="mt-3"><DocMarkdown content={v.afterBreaking} /></div>
             )}
           </section>
         ))}
@@ -74,7 +49,7 @@ export function ChangelogView({ source }: { source: string }): React.ReactElemen
   )
 }
 
-/** O changelog do Opus pronto pra montar (site: página de topo; Maestro: página da doc). */
+/** O changelog do Opus pronto para montar no portal ou na documentação embutida. */
 export function OpusChangelog(): React.ReactElement {
   return <ChangelogView source={changelogMd} />
 }

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

@@ -222,7 +222,7 @@ receber só `{ id }`: o `id`, do tipo texto, é o único campo obrigatório da e
 se houver, têm valor padrão ou são opcionais. Os caminhos usam ponto para descer em objetos; um
 caminho que passa por uma lista vale para cada item, e um campo intermediário `null` aparece como
 `null`. Declare em `context` só o que orienta a conversa: o exemplo deixa fora contato, documento e
-endereço, e o nome já vai como `title`. Um caminho que termina num objeto ou numa lista leva tudo o
+endereço, e o nome já vai como `title`. Um caminho que termina em um objeto ou em uma lista leva tudo o
 que está abaixo dele, inclusive campos acrescentados depois à saída; para conferir num teste o que
 cada caminho alcança, use `assistantContextLeaves`, de `@softize/opus/assistant-schema`, sobre o
 schema de saída do manifest. Ela devolve, por caminho, as folhas em `leaves` e, em `open`, os pontos
@@ -272,7 +272,7 @@ caracteres. Um caminho que falta na saída em execução é omitido com o motivo
 aviso no log, sem falhar a leitura. Quem recebe a saída por outro canal, como o MCP, aplica a mesma
 projeção com `projectAssistantContext(assistant, output)`.
 
-Entregue o dado ao modelo como bloco delimitado, numa mensagem de dado, nunca no prompt de sistema.
+Entregue o dado ao modelo como bloco delimitado, em uma mensagem de dado, nunca no prompt de sistema.
 `resourceDataBlock`, de `@softize/opus/ai`, monta o bloco com o tipo, o id, o título, os dados e,
 quando houve corte ou ausência, `truncated` e `omitted`, e escapa dentro dos valores o que poderia
 fechar o delimitador. Quando o modelo chama a action dona como ferramenta, recebe a saída completa
@@ -326,7 +326,7 @@ de uma action que não existe, ou dois cenários para a mesma action, impedem o
 subir, e o erro lista os nomes.
 
 O Opus não decide onde os cenários ficam nem se entram no repositório. Eles não fazem parte da
-aplicação: podem ficar numa pasta ignorada pelo git e ser escritos durante a sessão de design,
+aplicação: podem ficar em uma pasta ignorada pelo git e ser escritos durante a sessão de design,
 quando forem necessários.
 
 Dados de design não pertencem ao contrato. Quando uma resposta específica importar para a revisão

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