@softize/opus 25.7.0 → 26.1.0

package/src/ai/drivers/anthropic.ts

@@ -17,6 +17,7 @@ import { declaredJsonSchema } from '../../core/index.ts'
 import type {
   AiAdapter,
   AiCompleteOptions,
+  AiContentPart,
   AiMessage,
   AiRunOptions,
   AiRunResult,
@@ -101,6 +102,50 @@ function defaultToJsonSchema(schema: unknown): unknown {
   return zodToJsonSchema(schema as Parameters<typeof zodToJsonSchema>[0], { $refStrategy: 'none' })
 }
 
+const IMAGE_MEDIA_TYPES: ReadonlySet<string> = new Set(['image/png', 'image/jpeg', 'image/webp'])
+
+/** Converte o conteúdo neutro da mensagem (ADR 0058) para os blocos da API da Anthropic. Uma
+ *  parte desconhecida, uma parte de texto vazia, uma lista vazia, uma imagem fora dos formatos
+ *  aceitos ou uma imagem na fala do assistente lançam erro: nada é descartado em silêncio, e nada
+ *  chega a ser enviado. */
+function toAnthropicContent(message: AiMessage, index: number): unknown {
+  const { content } = message
+  if (typeof content === 'string') return content
+  // A API recusa lista vazia e bloco de texto sem texto; o erro aqui diz qual mensagem é.
+  if (content.length === 0) {
+    throw new Error(`ai/anthropic: mensagem ${index + 1} sem conteúdo (lista de partes vazia).`)
+  }
+  return content.map((part: AiContentPart, partIndex) => {
+    const where = `mensagem ${index + 1}, parte ${partIndex + 1}`
+    if (part.type === 'text') {
+      if (part.text.trim() === '') {
+        throw new Error(`ai/anthropic: parte de texto vazia (${where}).`)
+      }
+      return { type: 'text', text: part.text }
+    }
+    if (part.type === 'image') {
+      if (message.role !== 'user') {
+        throw new Error(`ai/anthropic: imagem só pode ir numa mensagem 'user' (${where}).`)
+      }
+      if (!IMAGE_MEDIA_TYPES.has(part.mediaType)) {
+        throw new Error(
+          `ai/anthropic: formato de imagem não aceito: "${String(part.mediaType)}" (${where}). ` +
+            'Use image/png, image/jpeg ou image/webp.',
+        )
+      }
+      return { type: 'image', source: { type: 'base64', media_type: part.mediaType, data: part.data } }
+    }
+    const unknownType = (part as { type?: unknown }).type
+    throw new Error(`ai/anthropic: parte de conteúdo desconhecida: "${String(unknownType)}" (${where}).`)
+  })
+}
+
+/** O histórico de entrada no formato da API, convertido antes da primeira chamada. */
+function toAnthropicMessages(input: string | AiMessage[]): Array<{ role: string; content: unknown }> {
+  if (typeof input === 'string') return [{ role: 'user', content: input }]
+  return input.map((m, i) => ({ role: m.role, content: toAnthropicContent(m, i) }))
+}
+
 interface ContentBlock {
   type: string
   text?: string
@@ -183,6 +228,9 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
     },
 
     async run(input: string | AiMessage[], opts: AiRunOptions): Promise<AiRunResult> {
+      // Mensagens no formato Anthropic — convertidas antes de tudo (uma parte inválida falha sem
+      // chamar a API) e crescem com tool_use/tool_result a cada passo.
+      const messages = toAnthropicMessages(input)
       const c = await client()
       const tools = withAskTool(
         opts.tools.map((t) => ({
@@ -192,11 +240,6 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
         })),
         opts,
       )
-      // Mensagens no formato Anthropic — crescem com tool_use/tool_result a cada passo.
-      const messages: Array<{ role: string; content: unknown }> =
-        typeof input === 'string'
-          ? [{ role: 'user', content: input }]
-          : input.map((m) => ({ role: m.role, content: m.content }))
 
       const maxSteps = opts.maxSteps ?? 8
       const calls: Array<{ name: string; input: unknown }> = []
@@ -242,6 +285,7 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
     },
 
     async *runStream(input: string | AiMessage[], opts: AiRunOptions): AsyncIterable<ChatEvent> {
+      const messages = toAnthropicMessages(input)
       const c = await client()
       const tools = withAskTool(
         opts.tools.map((t) => ({
@@ -251,10 +295,6 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
         })),
         opts,
       )
-      const messages: Array<{ role: string; content: unknown }> =
-        typeof input === 'string'
-          ? [{ role: 'user', content: input }]
-          : input.map((m) => ({ role: m.role, content: m.content }))
 
       const maxSteps = opts.maxSteps ?? 8
 

package/src/ai/index.ts

@@ -5,11 +5,14 @@
  * (texto → objeto VALIDADO por um `Schema` do protocolo — o mesmo tipo de schema
  * das actions vira o contrato da resposta do modelo). Driver em `ai/anthropic`.
  * A superfície é a mínima de backoffice e cresce por reincidência — não por
- * especulação (streaming, chat multi-turn e tools livres entram quando um caso
- * real cobrar).
+ * especulação. Streaming, chat multi-turn e mensagem com imagem (ADR 0058) já
+ * entraram assim; o resto espera um caso real.
  */
 
 export type { AiAdapter, AiCompleteOptions } from '../core/index.ts'
+// Mensagem com texto e imagem (ADR 0058): o tipo neutro de conteúdo e a leitura só do texto.
+export type { AiContentPart, AiImageMediaType, AiMessage } from '../core/index.ts'
+export { aiMessageText } from '../core/index.ts'
 // Elicitação — perguntar à pessoa no meio do turno (round-trip via `AiRunOptions.onAsk`).
 // O contrato (tipos) mora no core; aqui saem o nome reservado, o schema/descrição da tool e
 // o formatador. É o ponto de consistência pra qualquer consumidor (chat, copilot, MCP externo).

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

@@ -618,8 +618,9 @@ export type FieldWidget = BuiltInFieldWidget | (string & { readonly __opusCustom
 export interface FieldSpec {
   label: I18nRef
   placeholder?: I18nRef
-  /** Ajuda junto à label (ícone ⓘ + tooltip): critério, efeito ou limitação que a label não
-   *  diz. Ajuda que só repete a label deve ser omitida. */
+  /** Orientação necessária para preencher ou prever o efeito da escolha, sempre visível. */
+  hint?: I18nRef
+  /** Explicação complementar sob demanda junto à label; não recebe regras indispensáveis. */
   help?: I18nRef
 
   default?: unknown
@@ -1383,10 +1384,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/action-list-dialog.tsx

@@ -19,6 +19,7 @@ import {
   DialogContent,
   DialogHeader,
   DialogTitle,
+  DialogDescription,
 } from '../primitives/dialog.tsx'
 import { ActionList } from './list.tsx'
 import type { ListAction } from '../../../core/index.ts'
@@ -34,6 +35,8 @@ export interface ActionListDialogProps<
   open: boolean
   onOpenChange: (open: boolean) => void
   title: string
+  /** Orientação opcional sobre a finalidade; regras e consequências pertencem a intro ou aos campos. */
+  description?: ReactNode
   /** Conteúdo relevante apresentado antes da lista, como texto ou Alert. */
   intro?: ReactNode
   /** Nota à esquerda da linha de ações (contexto curto). O total já mora no rodapé. */
@@ -63,6 +66,7 @@ export function ActionListDialog<
   open,
   onOpenChange,
   title,
+  description,
   intro,
   note,
   actions,
@@ -75,19 +79,22 @@ export function ActionListDialog<
   children,
 }: ActionListDialogProps<TItem, TInput>): React.ReactElement {
   const introId = useId()
+  const descriptionId = useId()
+  const describedBy =
+    [description == null ? null : descriptionId, intro == null ? null : introId]
+      .filter(Boolean)
+      .join(' ') || undefined
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent
-        className={cn('max-w-3xl', className)}
-        aria-describedby={intro === undefined ? undefined : introId}
-      >
+      <DialogContent className={cn('max-w-3xl', className)} aria-describedby={describedBy}>
         <DialogHeader>
           <DialogTitle>{title}</DialogTitle>
+          {description != null && (
+            <DialogDescription id={descriptionId}>{description}</DialogDescription>
+          )}
         </DialogHeader>
         <DialogBody>
-          {intro !== undefined && (
-            <div id={introId}>{intro}</div>
-          )}
+          {intro != null && <div id={introId}>{intro}</div>}
           {(note !== undefined || actions !== undefined) && (
             <div
               data-slot="action-list-dialog-toolbar"

package/src/ui/components/patterns/form-dialog.tsx

@@ -16,6 +16,7 @@ import {
   DialogFooter,
   DialogHeader,
   DialogTitle,
+  DialogDescription,
 } from "../primitives/dialog.tsx";
 import { ActionForm, type ActionFormProps } from "./form.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
@@ -27,6 +28,8 @@ export interface ActionFormDialogProps<
   open: boolean;
   onOpenChange: (open: boolean) => void;
   title: string;
+  /** Orientação opcional sobre a finalidade; regras e consequências pertencem a intro ou aos campos. */
+  description?: ReactNode;
   /** Conteúdo relevante apresentado antes dos campos, como texto ou Alert. */
   intro?: ReactNode;
   /** Distribui as ações pela largura disponível somente quando as decisões pedem peso equivalente. */
@@ -40,6 +43,7 @@ export function ActionFormDialog<
   open,
   onOpenChange,
   title,
+  description,
   intro,
   onSuccess,
   onCancel,
@@ -48,15 +52,23 @@ export function ActionFormDialog<
   ...rest
 }: ActionFormDialogProps<TInput, TData>) {
   const introId = useId();
+  const descriptionId = useId();
+  const describedBy =
+    [description == null ? null : descriptionId, intro == null ? null : introId]
+      .filter(Boolean)
+      .join(" ") || undefined;
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       {/* Header e rodapé FIXOS, só o CORPO (campos) scrolla — o "X" não rola junto e
           forms longos não estouram a viewport. O content já é coluna flex com teto. */}
-      <DialogContent
-        aria-describedby={intro === undefined ? undefined : introId}
-      >
+      <DialogContent aria-describedby={describedBy}>
         <DialogHeader>
           <DialogTitle>{title}</DialogTitle>
+          {description != null && (
+            <DialogDescription id={descriptionId}>
+              {description}
+            </DialogDescription>
+          )}
         </DialogHeader>
         <ActionForm
           {...rest}
@@ -65,9 +77,7 @@ export function ActionFormDialog<
           // faixa da casa — fonte única). Os botões seguem dentro do <form> do ActionForm.
           body={(fields) => (
             <DialogBody>
-              {intro !== undefined && (
-                <div id={introId}>{intro}</div>
-              )}
+              {intro != null && <div id={introId}>{intro}</div>}
               {fields}
             </DialogBody>
           )}
@@ -84,7 +94,8 @@ export function ActionFormDialog<
           }}
           onCancel={onCancel ?? (() => onOpenChange(false))}
           cancelVariant={
-            cancelVariant ?? (footerDistribution === "equal" ? "outline" : "ghost")
+            cancelVariant ??
+            (footerDistribution === "equal" ? "outline" : "ghost")
           }
         />
       </DialogContent>

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

@@ -4,7 +4,7 @@
  * Dois modos, um motor:
  * - AUTO (sem children): monta TODOS os campos na ordem do contrato — zero JSX de campo.
  * - COMPOSIÇÃO (com children): você diagrama; <ActionFormField name /> coloca cada campo
- *   (label/help/widget/erro/asterisco derivados do contrato) onde quiser. Condicional é
+ *   (label/hint/help/widget/erro/asterisco derivados do contrato) onde quiser. Condicional é
  *   JSX ({cond && <ActionFormField/>}); opções de runtime entram por prop no campo. O
  *   FieldGroup canônico permanece nos dois modos; grids e seções entram como filhos explícitos.
  *
@@ -54,6 +54,7 @@ import { ToggleGroup } from "../primitives/toggle-group.tsx";
 import {
   Field,
   FieldError,
+  FieldDescription,
   FieldGroup,
   FieldLabel,
 } from "../primitives/field.tsx";
@@ -137,7 +138,9 @@ function inferFieldKind(schema: ZodTypeAny): FieldKind {
 interface FieldSpec {
   label?: string;
   placeholder?: string;
-  /** Ajuda na label: ícone ⓘ + tooltip no hover. */
+  /** Orientação necessária sempre visível abaixo do controle. */
+  hint?: string;
+  /** Detalhe complementar no ícone junto à label, disponível por hover ou foco. */
   help?: string;
   /** Override explícito do tipo de campo, quando o auto-detect do Zod não basta.
    *  Honra 'textarea' (string sem max), 'code' (textarea monoespaçada, ex.: SKILL.md),
@@ -206,9 +209,8 @@ function dictMetaOptions(schema: ZodTypeAny): SelectOption[] | undefined {
  * lugar (`<FieldLabel>Nome<LabelHelp help="…" /></FieldLabel>`) e o `opus copy` inventarie
  * o texto de `help` como helper-text.
  *
- * `tabIndex={-1}`: fica FORA do autofocus do diálogo (senão o modal foca no ícone ao abrir e
- * o tooltip vem aberto); abre só no hover. preventDefault: clicar o ícone não dispara o label
- * (não foca o input / não toggla).
+ * O botão participa do Tab e abre por foco ou hover. Dialog e Drawer preservam o foco
+ * inicial no controle, sem remover a ajuda da navegação por teclado. Clicar não ativa a label.
  */
 export function LabelHelp({
   help,
@@ -222,7 +224,8 @@ export function LabelHelp({
         <TooltipTrigger asChild>
           <button
             type="button"
-            tabIndex={-1}
+            data-slot="label-help"
+            tabIndex={0}
             aria-label="Ajuda"
             onClick={(e) => {
               // Clicar o ícone não ativa o label (não foca/toggla o campo).
@@ -344,7 +347,8 @@ export function ActionFormField({
   const errorMessage =
     typeof fieldError?.message === "string" ? fieldError.message : undefined;
   const errorId = errorMessage !== undefined ? `${name}-error` : undefined;
-  const describedBy = errorId;
+  const hintId = spec.hint?.trim() ? `${name}-hint` : undefined;
+  const describedBy = [hintId, errorId].filter(Boolean).join(" ") || undefined;
   useEffect(() => {
     if (errorMessage === undefined) return;
     const control = document.getElementById(name);
@@ -430,6 +434,9 @@ export function ActionFormField({
           </span>
           <LabelHelp help={spec.help} />
         </FieldLabel>
+        {hintId !== undefined && (
+          <FieldDescription id={hintId}>{spec.hint}</FieldDescription>
+        )}
         {errorMessage !== undefined && (
           <FieldError id={errorId}>{errorMessage}</FieldError>
         )}
@@ -683,6 +690,9 @@ export function ActionFormField({
         />
       )}
 
+      {hintId !== undefined && (
+        <FieldDescription id={hintId}>{spec.hint}</FieldDescription>
+      )}
       {errorMessage !== undefined && (
         <FieldError id={errorId}>{errorMessage}</FieldError>
       )}
@@ -774,7 +784,25 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
     string,
     ZodTypeAny | undefined
   >;
-  const fields = action.fields as Record<string, FieldSpec>;
+  // O contexto entrega texto resolvido também aos renderizadores de campo do consumidor.
+  const fields: Record<string, FieldSpec> = Object.fromEntries(
+    Object.entries(action.fields ?? {}).map(([name, declared]) => {
+      const spec = declared as FieldSpec;
+      return [
+        name,
+        {
+          ...spec,
+          label: msgText(spec.label, name),
+          placeholder:
+            spec.placeholder === undefined
+              ? undefined
+              : msgText(spec.placeholder, ""),
+          hint: spec.hint === undefined ? undefined : msgText(spec.hint, ""),
+          help: spec.help === undefined ? undefined : msgText(spec.help, ""),
+        },
+      ];
+    }),
+  );
 
   // Corpo e rodapé como SLOTS: por padrão renderizam inline; o ActionFormDialog injeta
   // DialogBody/DialogFooter (fonte única do scroll e da faixa). Os botões ficam DENTRO do

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

@@ -147,6 +147,8 @@ interface PageBaseProps extends Omit<
 
 interface PageShorthandProps extends PageBaseProps {
   title: ReactNode;
+  /** Orientação opcional sobre a finalidade da página; regras pertencem ao corpo. */
+  description?: ReactNode;
   actions?: ReactNode;
   children: ReactNode;
 }
@@ -224,6 +226,7 @@ function hasOpaquePageBodyContent(node: ReactNode): boolean {
 
 export function Page({
   title,
+  description,
   actions,
   layout = "flow",
   className,
@@ -343,6 +346,9 @@ export function Page({
     <>
       <PageHeader>
         <PageTitle>{title}</PageTitle>
+        {description !== undefined && (
+          <PageDescription>{description}</PageDescription>
+        )}
         {actions !== undefined && <PageActions>{actions}</PageActions>}
       </PageHeader>
       <PageBody>{children}</PageBody>
@@ -461,6 +467,7 @@ export function PageHeader({
         slots={{
           leading: [PageBack, PageNavigation],
           title: PageTitle,
+          description: PageDescription,
           actions: PageActions,
         }}
         leadingPlacement="above"
@@ -496,6 +503,21 @@ export function PageTitle({
   );
 }
 
+/** Orientação breve e dispensável para a decisão; não recebe regras de negócio. */
+export function PageDescription({
+  className,
+  ...props
+}: HTMLAttributes<HTMLParagraphElement>): ReactElement {
+  requireParent(useContext(PageHeaderContext), "PageDescription", "PageHeader");
+  return (
+    <p
+      data-slot="page-description"
+      className={cn(structuralHeaderClasses.page.description, className)}
+      {...props}
+    />
+  );
+}
+
 export function PageActions({
   className,
   ...props

package/src/ui/components/patterns/surface-anatomy.ts

@@ -60,7 +60,7 @@ interface FamilyAnatomy {
   regions: Record<SurfaceLayout, RegionAnatomy>;
   /** Escala visual do título. O nível semântico do heading é escolhido à parte. */
   title: Record<SurfaceLayout, string>;
-  /** Descrição no header, quando a família a oferece (ADRs 0014 e 0018 excluem modais). */
+  /** Descrição no header, quando a família a oferece (ADR 0059 inclui subheadings opcionais em modais). */
   description: string;
   /** Espaço entre mídia, título e ações na linha do header. */
   headerGap: string;