@softize/opus 12.8.0 → 12.9.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ 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
+(peers diferentes), as colunas de dicionário zero-config do `ActionList` e o fallback de opções
+do `ActionForm` não encontravam o dicionário: a meta que `t.dict` grava no schema vivia num
+`WeakMap` por instância, invisível para a outra cópia. A meta anexada por `attachLogicalType`
+agora viaja também como propriedade não enumerável do próprio schema, chaveada por
+`Symbol.for('@softize/opus/logical-type')`, e `getLogicalType` a lê quando o `WeakMap` local não
+conhece o objeto. Sem mudança de API.
+
 ## 12.8.0 — 2026-09-02
 
 A apresentação de um dicionário passa a ser declarada no próprio `t.dict`, e não inferida por

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.8.0",
+  "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/core/logical-type.ts

@@ -5,12 +5,21 @@
  * labels de dict lendo a meta que viaja no schema do contrato, e a fronteira SPA
  * (gate de arquitetura) só deixa a UI tocar ui/lib/core. O `@softize/opus/schema`
  * re-exporta — a API pública não muda; as factories `t.*` seguem no driver.
+ *
+ * A meta é guardada de duas formas: num `WeakMap` desta instância e numa propriedade
+ * não enumerável do próprio schema, chaveada por `Symbol.for`. A segunda é o que
+ * atravessa instâncias do pacote: num monorepo pnpm, o workspace do contrato e o da
+ * SPA podem resolver cópias distintas do Opus (peers diferentes), e um `WeakMap` de
+ * uma cópia é invisível para a outra — o schema, não; ele é o mesmo objeto.
  */
 
 import type { LogicalTypeMeta } from './types.ts'
 
 const META = new WeakMap<object, LogicalTypeMeta>()
 
+/** Chave global da propriedade que carrega a meta no próprio schema. */
+export const LOGICAL_TYPE_PROPERTY = Symbol.for('@softize/opus/logical-type')
+
 /**
  * Anexa metadata logical type a qualquer schema (objeto). Drivers usam
  * internamente; consumers usam pra registrar tipos lógicos customizados.
@@ -20,12 +29,27 @@ export function attachLogicalType<S extends object>(
   meta: LogicalTypeMeta,
 ): S {
   META.set(schema, meta)
+  // Objeto congelado ou selado fica só no WeakMap — a assinatura aceita "qualquer objeto".
+  if (Object.isExtensible(schema)) {
+    Object.defineProperty(schema, LOGICAL_TYPE_PROPERTY, {
+      value: meta,
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    })
+  }
   return schema
 }
 
 /**
- * Lê a metadata logical type anexada. Retorna `undefined` se ausente.
+ * Lê a metadata logical type anexada, por esta instância ou por outra cópia do
+ * pacote que tenha anexado no mesmo objeto. Retorna `undefined` se ausente.
  */
 export function getLogicalType(schema: object): LogicalTypeMeta | undefined {
-  return META.get(schema)
+  const own = META.get(schema)
+  if (own !== undefined) return own
+  const carried = (schema as { [LOGICAL_TYPE_PROPERTY]?: unknown })[LOGICAL_TYPE_PROPERTY]
+  return carried !== null && typeof carried === 'object' && 'logicalType' in carried
+    ? (carried as LogicalTypeMeta)
+    : undefined
 }

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',