@softize/opus 12.8.1 → 12.9.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.9.0 — 2026-09-03
+
+`Chat` aceita `empty`, um nó React para o estado sem mensagens: o app compõe o vazio com os
+slots de `Empty` (marca, nome do agente, saudação administrável) e entrega no mesmo lugar do
+`greeting`, que continua valendo como atalho de uma frase. `empty` vence quando os dois existem
+e some quando a conversa começa; o slot ganha `data-variant="composed"`. Mudança aditiva.
+
 ## 12.8.1 — 2026-09-02
 
 Num monorepo pnpm em que o workspace do contrato e o da SPA resolvem cópias distintas do Opus

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.8.1",
+  "version": "12.9.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

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

@@ -71,6 +71,11 @@ export interface ChatProps {
   /** Texto do estado vazio (centrado, some quando a conversa começa). Não entra no
    *  transcript — é apresentação, não fala do assistente. */
   greeting?: string
+  /** Estado vazio composto pelo app (ex.: `EmptyHeader` com a marca, o nome e a saudação do
+   *  agente). Ocupa o mesmo lugar do `greeting` e vence quando os dois existem; `null` ou
+   *  `false` deixam o `greeting` valer; some quando a conversa começa. Prefira `greeting`
+   *  quando bastar uma frase. */
+  empty?: React.ReactNode
   /** Histórico inicial do modo autogerenciado (reidratação). Troque a `key` do componente
    *  ao trocar de conversa — o estado interno reinicia com estas mensagens. */
   initialMessages?: ChatMessage[]
@@ -107,6 +112,7 @@ interface ChatTranscriptProps {
   items: ChatTranscriptItem[]
   indicator: string | null | undefined
   greeting: string | undefined
+  empty: React.ReactNode | undefined
   renderArtifact: ChatProps['renderArtifact']
 }
 
@@ -120,11 +126,15 @@ const ChatTranscript = React.memo(function ChatTranscript({
   items,
   indicator,
   greeting,
+  empty,
   renderArtifact,
 }: ChatTranscriptProps): React.ReactElement {
   const scrollRef = React.useRef<HTMLDivElement>(null)
   const turns = React.useMemo(() => groupTurns(items), [items])
   const indicatorVisible = indicator !== undefined
+  // `null`/`false` em `empty` significam "sem nó" (o dado ainda não chegou): o greeting
+  // continua como fallback em vez de um wrapper composto vazio.
+  const composedEmpty = empty !== undefined && empty !== null && empty !== false
   React.useEffect(() => {
     scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight })
   }, [items, indicator])
@@ -135,11 +145,19 @@ const ChatTranscript = React.memo(function ChatTranscript({
       data-slot="chat-scroll"
       className="flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto p-4"
     >
-      {items.length === 0 && !indicatorVisible && greeting !== undefined && (
-        <div data-slot="chat-empty" className="m-auto max-w-[17.5rem] text-center text-muted-foreground">
-          <div className="mb-2 text-4xl">✦</div>
-          <p className="text-sm leading-relaxed">{greeting}</p>
+      {items.length === 0 && !indicatorVisible && composedEmpty ? (
+        <div data-slot="chat-empty" data-variant="composed" className="m-auto flex justify-center text-center">
+          {empty}
         </div>
+      ) : (
+        items.length === 0 &&
+        !indicatorVisible &&
+        greeting !== undefined && (
+          <div data-slot="chat-empty" className="m-auto max-w-[17.5rem] text-center text-muted-foreground">
+            <div className="mb-2 text-4xl">✦</div>
+            <p className="text-sm leading-relaxed">{greeting}</p>
+          </div>
+        )
       )}
       {turns.map((turn, ti) => (
         // Hierarquia do espaço: as falas de um mesmo turno são um raciocínio contínuo
@@ -235,6 +253,7 @@ export function Chat({
   composerActions,
   composerClassName,
   greeting,
+  empty,
   initialMessages,
   kickoff,
   renderArtifact,
@@ -374,6 +393,7 @@ export function Chat({
         items={items}
         indicator={indicator}
         greeting={greeting}
+        empty={empty}
         renderArtifact={renderArtifact}
       />
       {/* Composer da casa (pílula elevada, enviar dentro). Extraído no <Composer> — o Chat

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

@@ -15,6 +15,30 @@ Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por den
 </div>
 ```
 
+## Estado vazio composto
+
+Quando uma frase não basta — marca, nome do agente e saudação administrável, por exemplo — o
+app compõe o vazio com os slots de `Empty` e entrega em `empty`. O nó ocupa o mesmo lugar do
+`greeting`, vence quando os dois existem e some quando a conversa começa. Sem a moldura `Empty`
+em volta: o chat já é a estrutura, e a moldura tracejada é para região de criação.
+
+```tsx preview
+<div className="h-72 rounded-lg border">
+  <Chat
+    empty={
+      <EmptyHeader>
+        <EmptyMedia variant="icon">
+          <Sparkles />
+        </EmptyMedia>
+        <EmptyTitle>Copilot</EmptyTitle>
+        <EmptyDescription>Pergunte sobre vendas, estoque, oficina ou pessoas.</EmptyDescription>
+      </EmptyHeader>
+    }
+    send={async () => 'Pronto.'}
+  />
+</div>
+```
+
 ## O backend (o agente)
 
 O `send` posta a conversa no seu endpoint, que resolve o usuário e roda o agente sobre as actions `ai:enabled` — **como o usuário logado**:

package/src/ui/meta.ts

@@ -75,7 +75,7 @@ export const componentMeta = {
     name: 'chat',
     ancestry: 'opus',
     whenToUse:
-      'Chat da casa (lista de mensagens + composer) que gerencia a conversa por dentro (estado/loading/auto-scroll; Enter envia, Shift+Enter quebra linha). A inteligência vem da prop `send` — resposta inteira (Promise<string>) OU streaming (AsyncIterable<ChatEvent>: texto incremental, indicador vivo do tool, artefato via renderArtifact). No Opus, o backend liga em `runtime.aiFor(base).run(...)` ou `.runStream(...)`. Dê altura ao container (ex.: `h-full`).',
+      'Chat da casa (lista de mensagens + composer) que gerencia a conversa por dentro (estado/loading/auto-scroll; Enter envia, Shift+Enter quebra linha). A inteligência vem da prop `send` — resposta inteira (Promise<string>) OU streaming (AsyncIterable<ChatEvent>: texto incremental, indicador vivo do tool, artefato via renderArtifact). No Opus, o backend liga em `runtime.aiFor(base).run(...)` ou `.runStream(...)`. Estado vazio por `greeting` (frase) ou `empty` (nó composto com os slots de Empty). Dê altura ao container (ex.: `h-full`).',
   },
   'checkbox': {
     name: 'checkbox',