@softize/opus 25.6.0 → 26.0.0

package/src/core/ai-message.ts

@@ -0,0 +1,20 @@
+import type { AiMessage } from './types.ts'
+
+/** Separa as partes de texto de uma mensagem na leitura: cada parte continua um parágrafo. */
+const TEXT_PART_SEPARATOR = '\n\n'
+
+/**
+ * O texto de uma mensagem da IA (ADR 0058): o próprio `content` quando ele é texto, ou as partes
+ * de texto unidas por uma linha em branco. As imagens não entram.
+ *
+ * Use onde só o texto importa — título de conversa, contagem de caracteres, bloco de contexto
+ * montado por interpolação. Interpolar `content` direto produz "[object Object]" quando a
+ * mensagem tem partes, e o compilador não aponta esse uso.
+ */
+export function aiMessageText(message: Pick<AiMessage, 'content'>): string {
+  const { content } = message
+  if (typeof content === 'string') return content
+  return content
+    .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+    .join(TEXT_PART_SEPARATOR)
+}

package/src/core/index.ts

@@ -113,6 +113,8 @@ export type {
   AiCompleteOptions,
   AiTool,
   AiMessage,
+  AiContentPart,
+  AiImageMediaType,
   AiRunOptions,
   AiRunResult,
   BoundAi,
@@ -243,6 +245,9 @@ export type {
 } from './runtime.ts'
 export { countReturnedRecords, hasInvalidEffect, resolveActionEffect } from './action-nature.ts'
 
+// — Mensagem da IA (ADR 0058) ———————————————————————————————————————————————————
+export { aiMessageText } from './ai-message.ts'
+
 // — Assistente do recurso (ADR 0053) ————————————————————————————————————————————
 export {
   ASSISTANT_CONTEXT_DEFAULT_CHARS,

package/src/core/types.ts

@@ -1383,10 +1383,33 @@ export interface AiTool {
   }
 }
 
-/** Turno de conversa (histórico multi-turn do chat). */
+/** Formatos de imagem que a mensagem aceita: os três que os provedores conhecidos leem (ADR 0058). */
+export type AiImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp'
+
+/**
+ * Parte de conteúdo de uma mensagem, sem a forma de nenhum provedor (ADR 0058). Cada driver
+ * converte as partes para o formato da sua API e recusa com erro o que não conhece.
+ *
+ * A imagem não leva nome: o rótulo que a pessoa e o modelo usam ("Imagem 1: print.png") é uma
+ * parte de texto que o consumidor monta antes dela.
+ */
+export type AiContentPart =
+  | { type: 'text'; text: string }
+  | {
+      type: 'image'
+      mediaType: AiImageMediaType
+      /** Bytes da imagem em base64, sem o prefixo `data:`. */
+      data: string
+    }
+
+/**
+ * Turno de conversa (histórico multi-turn do chat). `content` é texto ou uma lista de partes
+ * com texto e imagem (ADR 0058). Para ler só o texto, use `aiMessageText(message)`: interpolar
+ * `content` direto num template produz "[object Object]" quando a mensagem tem partes.
+ */
 export interface AiMessage {
   role: 'user' | 'assistant'
-  content: string
+  content: string | AiContentPart[]
 }
 
 /** Uma opção de resposta de uma pergunta de esclarecimento (`ask_user`). */

package/src/ui/components/patterns/sidebar.tsx

@@ -77,7 +77,9 @@ export interface SidebarItemProps {
   /** Complemento do tooltip no rail recolhido. */
   tooltipHint?: ReactNode;
   className?: string;
-  onClick: () => void;
+  /** Destino nativo. Com onClick, intercepta somente a navegação simples; preserva novas abas. */
+  href?: string;
+  onClick?: () => void;
 }
 
 /** Linha única de navegação: o alvo principal e seus controles são irmãos, nunca botões aninhados. */
@@ -95,8 +97,29 @@ export function SidebarItem({
   tooltipHint,
   className,
   onClick,
+  href,
 }: SidebarItemProps): React.ReactElement {
   const collapsed = useSidebarCollapsed();
+  const Target = href !== undefined && !disabled ? "a" : "button";
+  const targetProps =
+    Target === "a" ? { href } : { type: "button" as const, disabled };
+  const activate = (
+    event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>,
+  ) => {
+    if (href !== undefined) {
+      if (
+        event.button !== 0 ||
+        event.metaKey ||
+        event.ctrlKey ||
+        event.shiftKey ||
+        event.altKey ||
+        !onClick
+      )
+        return;
+      event.preventDefault();
+    }
+    onClick?.();
+  };
   const hasActions = actions !== undefined && actions !== null;
   // O rótulo cortado esmaece em vez de terminar em reticências; a medição do transbordo
   // mantém a máscara fora do rótulo que cabe inteiro na linha.
@@ -104,12 +127,11 @@ export function SidebarItem({
     useOverflowing<HTMLSpanElement>(label);
   if (collapsed) {
     const button = (
-      <button
-        type="button"
-        disabled={disabled}
+      <Target
+        {...targetProps}
         aria-label={label}
         aria-current={active ? "page" : undefined}
-        onClick={onClick}
+        onClick={activate}
         className={cn(
           "mx-auto grid size-10 place-items-center rounded-md transition-colors disabled:pointer-events-none disabled:opacity-40",
           "outline-none",
@@ -125,7 +147,7 @@ export function SidebarItem({
         >
           {icon}
         </span>
-      </button>
+      </Target>
     );
     // `className` vai no MESMO elemento nos dois modos — a linha —, senão a prop mudaria de alvo
     // conforme o rail estivesse recolhido, e o consumidor não teria como saber o que estilizou.
@@ -209,11 +231,10 @@ export function SidebarItem({
           )}
         </span>
       )}
-      <button
-        type="button"
-        disabled={disabled}
+      <Target
+        {...targetProps}
         aria-current={active ? "page" : undefined}
-        onClick={onClick}
+        onClick={activate}
         className={cn(
           "flex min-w-0 flex-1 items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-sm disabled:pointer-events-none",
           "outline-none",
@@ -254,7 +275,7 @@ export function SidebarItem({
             {badge}
           </span>
         )}
-      </button>
+      </Target>
       {hasActions && (
         <div
           data-slot="sidebar-item-actions"

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

@@ -1,7 +1,14 @@
 import * as React from 'react'
+import { ImageOffIcon } from 'lucide-react'
 import type { ChatEvent } from '../../../core/index.ts'
 import { cn } from '../../lib/cn.ts'
-import { Composer } from './composer.tsx'
+import {
+  Composer,
+  ComposerDropBridge,
+  dragHasFiles,
+  type ComposerAttachment,
+  type ComposerAttachments,
+} from './composer.tsx'
 import { Markdown } from './markdown.tsx'
 
 export interface ChatMessage {
@@ -20,10 +27,35 @@ export interface ChatArtifact {
   title?: string
 }
 
+/** Estado de um anexo já enviado: com a imagem disponível ou expirada pela retenção do app. */
+export type ChatAttachmentStatus = 'available' | 'expired'
+
+/** Imagem anexada a uma fala da pessoa (ADR 0058). A guarda é do app, que fornece o endereço. */
+export interface ChatAttachment {
+  id: string
+  /** Nome do arquivo; é o texto alternativo da miniatura e o título do cartão de expirada. */
+  name: string
+  /** Tipo da imagem (`image/png`, `image/jpeg`, `image/webp`). */
+  mediaType: string
+  width?: number
+  height?: number
+  status: ChatAttachmentStatus
+  /** Endereço da imagem, servido pela própria aplicação ou em `data:` (ADR 0050). Ausente na
+   *  imagem expirada. */
+  url?: string
+}
+
 /** Item do transcript no modo CONTROLADO (o app é o dono do estado — ex.: sala
  *  server-autoritativa com replay, como o ChatRail do Maestro). */
 export type ChatTranscriptItem =
-  | { id?: string; createdAt?: string; role: 'user' | 'assistant' | 'error'; content: string }
+  | {
+      id?: string
+      createdAt?: string
+      role: 'user' | 'assistant' | 'error'
+      content: string
+      /** Imagens da fala `user`, mostradas acima do texto. Ignorado nos outros papéis. */
+      attachments?: ChatAttachment[]
+    }
   | { id?: string; createdAt?: string; role: 'artifact'; artifact: ChatArtifact }
 
 export type ChatTranscriptMessage = Extract<ChatTranscriptItem, { content: string }>
@@ -37,9 +69,61 @@ function defaultHumanizeTool(name: string): string {
   return 'Trabalhando…'
 }
 
-/** A fala do usuário: fundo discreto, largura pelo conteúdo e sem se sobrepor ao histórico. */
-const UserTurn = React.memo(function UserTurn({ content }: { content: string }): React.ReactElement {
+/** As imagens de uma fala da pessoa, acima do texto. São um componente próprio, e não `![]()`
+ *  no Markdown: a fala continua sendo só o que a pessoa escreveu (ADR 0058). */
+function ChatUserAttachments({ attachments }: { attachments: ChatAttachment[] }): React.ReactElement {
   return (
+    <ul
+      data-slot="chat-user-attachments"
+      aria-label="Imagens enviadas"
+      className="flex max-w-[88%] flex-wrap justify-end gap-1.5 self-end"
+    >
+      {attachments.map((attachment) =>
+        attachment.status === 'available' && attachment.url !== undefined ? (
+          <li key={attachment.id} data-slot="chat-attachment" data-status="available">
+            <img
+              src={attachment.url}
+              alt={attachment.name}
+              width={attachment.width}
+              height={attachment.height}
+              loading="lazy"
+              decoding="async"
+              className="h-24 w-auto max-w-48 rounded-lg border border-border bg-muted object-cover"
+            />
+          </li>
+        ) : (
+          <li
+            key={attachment.id}
+            data-slot="chat-attachment"
+            data-status={attachment.status}
+            className="flex max-w-48 items-center gap-2 rounded-lg border border-dashed border-border bg-muted/40 px-3 py-2 text-xs"
+          >
+            <ImageOffIcon aria-hidden className="size-4 shrink-0 text-muted-foreground" />
+            <span className="min-w-0 leading-tight">
+              <span className="block truncate font-medium text-foreground" title={attachment.name}>
+                {attachment.name}
+              </span>
+              {attachment.status === 'expired' && (
+                <span className="block text-muted-foreground">Imagem expirada</span>
+              )}
+            </span>
+          </li>
+        ),
+      )}
+    </ul>
+  )
+}
+
+/** A fala do usuário: fundo discreto, largura pelo conteúdo e sem se sobrepor ao histórico.
+ *  As imagens vêm acima do texto; uma fala só com imagem não mostra balão vazio. */
+const UserTurn = React.memo(function UserTurn({
+  content,
+  attachments,
+}: {
+  content: string
+  attachments: ChatAttachment[] | undefined
+}): React.ReactElement {
+  const bubble = content !== '' && (
     <div
       data-slot="chat-user"
       className="w-fit max-w-[88%] self-end break-words rounded-xl bg-muted px-3 py-2 text-sm leading-snug"
@@ -47,6 +131,14 @@ const UserTurn = React.memo(function UserTurn({ content }: { content: string }):
       <Markdown content={content} />
     </div>
   )
+  if (attachments === undefined || attachments.length === 0) return <>{bubble}</>
+  // O espaço entre imagens e texto fica neste invólucro, sem mudar o ritmo da fala só com texto.
+  return (
+    <div data-slot="chat-user-content" className="flex w-full flex-col items-end gap-1.5">
+      <ChatUserAttachments attachments={attachments} />
+      {bubble}
+    </div>
+  )
 })
 
 export interface ChatProps {
@@ -58,9 +150,11 @@ export interface ChatProps {
   /** Modo CONTROLADO: o transcript vem daqui e o app é o dono do estado (transporte
    *  próprio — SSE com replay, etc.). Presente → `onSend`/`busy`/`activity` assumem. */
   messages?: ChatTranscriptItem[]
-  /** Modo controlado: recebe o texto enviado. Retornar `false` devolve o texto ao
-   *  composer (falha de envio — nada de perder o que o usuário digitou). */
-  onSend?: (text: string) => void | boolean | Promise<void | boolean>
+  /** Modo controlado: recebe o texto enviado e, só quando há `composerAttachments`, os anexos
+   *  prontos (lista possivelmente vazia). Sem `composerAttachments`, a chamada é `onSend(text)`,
+   *  como antes. Retornar `false` devolve o texto ao composer (falha de envio — nada de perder o
+   *  que o usuário digitou); os anexos continuam na faixa, que é do app. */
+  onSend?: (text: string, attachments?: ComposerAttachment[]) => void | boolean | Promise<void | boolean>
   /** Modo controlado: trava o composer enquanto o turno corre. */
   busy?: boolean
   /** Modo controlado: indicador vivo — `undefined` esconde, `null` mostra "Pensando…",
@@ -71,6 +165,10 @@ export interface ChatProps {
   /** Seletores discretos na barra do composer (o `actions` do `<Composer>`): agente,
    *  app, escopo… O lugar deles é a barra — `notice` é pra aviso, não pra controle. */
   composerActions?: React.ReactNode
+  /** Modo controlado: anexos da mensagem (o `attachments` do `<Composer>`, ADR 0058). Liga a
+   *  faixa de anexos, o botão **Anexar imagem**, colar e soltar imagens sobre a conversa. O app
+   *  prepara, envia, guarda e limpa os anexos. Ignorado no modo autogerenciado. */
+  composerAttachments?: ComposerAttachments
   /** Ajuste do contêiner externo do composer. O Chat mantém `p-3` por padrão; shells
    *  integrados podem alinhar esse inset aos painéis vizinhos sem alcançar o DOM interno. */
   composerClassName?: string
@@ -192,7 +290,7 @@ const ChatTranscript = React.memo(function ChatTranscript({
               data-message-created-at={turn.user.createdAt}
               className="group/chat-message mb-1 flex flex-col items-end justify-end py-1"
             >
-              <UserTurn content={turn.user.content} />
+              <UserTurn content={turn.user.content} attachments={turn.user.attachments} />
               {renderMessageActions !== undefined && (
                 <div
                   data-slot="chat-message-actions"
@@ -305,6 +403,7 @@ export function Chat({
   activity: activityProp,
   notice,
   composerActions,
+  composerAttachments,
   composerClassName,
   greeting,
   empty,
@@ -323,13 +422,21 @@ export function Chat({
   const [ownActivity, setOwnActivity] = React.useState<string | null>(null)
   const historyCursor = React.useRef<number | null>(null)
   const historyDraft = React.useRef('')
+  // Anexo só no modo controlado: o autogerenciado não tem transporte para a imagem (ADR 0058).
+  const attachments = controlled ? composerAttachments : undefined
+  const dropIntake = React.useRef<((files: File[]) => void) | null>(null)
+  const dragDepth = React.useRef(0)
+  const [dragging, setDragging] = React.useState(false)
 
   const items = controlled ? messages : ownItems
   const busy = controlled ? (busyProp ?? false) : ownBusy
   // Indicador: no controlado o app manda (undefined esconde); no autogerenciado segue o busy.
   const indicator = controlled ? activityProp : ownBusy ? ownActivity : undefined
   const inputHistory = React.useMemo(
-    () => items.filter((item): item is ChatMessage => item.role === 'user').map((item) => item.content),
+    () =>
+      items
+        .filter((item): item is ChatMessage => item.role === 'user' && item.content !== '')
+        .map((item) => item.content),
     [items],
   )
 
@@ -379,13 +486,16 @@ export function Chat({
 
   async function submit(): Promise<void> {
     const text = input.trim()
-    if (text === '' || busy) return
+    const ready = (attachments?.items ?? []).filter((item) => item.status === 'ready')
+    if ((text === '' && ready.length === 0) || busy) return
     historyCursor.current = null
     historyDraft.current = ''
     setInput('')
 
     if (controlled) {
-      const ok = await onSend?.(text)
+      // Sem anexo ligado, a chamada é a de sempre: um handler que já tinha um segundo parâmetro
+      // opcional, de outro significado, não recebe uma lista inesperada.
+      const ok = attachments !== undefined ? await onSend?.(text, ready) : await onSend?.(text)
       if (ok === false) setInput(text)
       return
     }
@@ -444,8 +554,52 @@ export function Chat({
     }
   }
 
+  // Soltar sobre a conversa inteira: a contagem de profundidade ignora o entra-e-sai dos filhos.
+  // O arraste de arquivos sobre o Chat é consumido aqui e não sobe: um contêiner do app com o
+  // próprio soltar (e a própria dica) não recebe o mesmo arraste uma segunda vez.
+  const dropHandlers: React.HTMLAttributes<HTMLDivElement> =
+    attachments === undefined
+      ? {}
+      : {
+          onDragEnter: (e) => {
+            if (!dragHasFiles(e.dataTransfer)) return
+            e.stopPropagation()
+            dragDepth.current += 1
+            setDragging(true)
+          },
+          onDragOver: (e) => {
+            if (!dragHasFiles(e.dataTransfer)) return
+            e.preventDefault()
+            e.stopPropagation()
+            e.dataTransfer.dropEffect = 'copy'
+          },
+          onDragLeave: (e) => {
+            if (!dragHasFiles(e.dataTransfer)) return
+            e.stopPropagation()
+            dragDepth.current = Math.max(0, dragDepth.current - 1)
+            if (dragDepth.current === 0) setDragging(false)
+          },
+          onDrop: (e) => {
+            if (!dragHasFiles(e.dataTransfer)) return
+            e.preventDefault()
+            e.stopPropagation()
+            dragDepth.current = 0
+            setDragging(false)
+            dropIntake.current?.(Array.from(e.dataTransfer.files))
+          },
+        }
+
   return (
-    <div data-slot="chat" className={cn('flex h-full flex-col', className)}>
+    <div data-slot="chat" className={cn('relative flex h-full flex-col', className)} {...dropHandlers}>
+      {dragging && (
+        <div
+          data-slot="chat-drop-hint"
+          aria-hidden
+          className="pointer-events-none absolute inset-2 z-10 grid place-items-center rounded-xl border-2 border-dashed border-primary bg-background/85 text-sm text-foreground"
+        >
+          Solte imagens para anexá-las à conversa.
+        </div>
+      )}
       <ChatTranscript
         items={items}
         indicator={indicator}
@@ -459,16 +613,19 @@ export function Chat({
           app…); o <Composer> sozinho segue sendo o caminho de quem não tem chat. */}
       <div data-slot="chat-composer" className={cn('shrink-0 p-3', composerClassName)}>
         {notice}
-        <Composer
-          value={input}
-          onChange={changeInput}
-          onSubmit={() => void submit()}
-          onHistoryPrevious={showPreviousInput}
-          onHistoryNext={showNextInput}
-          busy={busy}
-          placeholder={placeholder}
-          actions={composerActions}
-        />
+        <ComposerDropBridge.Provider value={dropIntake}>
+          <Composer
+            value={input}
+            onChange={changeInput}
+            onSubmit={() => void submit()}
+            onHistoryPrevious={showPreviousInput}
+            onHistoryNext={showNextInput}
+            busy={busy}
+            placeholder={placeholder}
+            actions={composerActions}
+            attachments={attachments}
+          />
+        </ComposerDropBridge.Provider>
       </div>
     </div>
   )