@softize/opus 19.0.0 → 20.1.0

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

@@ -1,7 +1,7 @@
-Ferramentas ancoradas à superfície de trabalho. Um canvas ou um editor raramente comporta mais
-uma faixa de chrome no topo: a trilha da aplicação já ocupa esse papel, e um segundo cabeçalho
-empilha duas faixas com a mesma função. A Dock coloca as ações sobre a própria superfície,
-agrupadas e sempre alcançáveis.
+Use `Dock` para as ferramentas de uma superfície de trabalho, como um canvas ou um editor. Essas
+telas raramente comportam mais uma barra no topo: a navegação da aplicação já ocupa esse lugar, e
+um segundo cabeçalho empilharia duas faixas com a mesma função. A Dock coloca as ações sobre a
+própria superfície, agrupadas e sempre alcançáveis.
 
 ```tsx preview
 <div className="relative h-40 w-full rounded-lg border border-border bg-muted/20">
@@ -23,8 +23,8 @@ agrupadas e sempre alcançáveis.
 
 O contêiner precisa ser `relative` — a Dock se ancora nele, não na janela. `position` escolhe a
 aresta: `bottom` (centro), `bottom-left` e `bottom-right`. Uma superfície pode ter mais de uma
-barra quando os papéis são distintos, como ferramentas ao centro e controles de viewport à
-esquerda.
+barra quando os papéis são distintos, como ferramentas ao centro e controles de visualização à
+direita.
 
 ## Grupos e divisórias
 
@@ -44,10 +44,43 @@ Mensagem de sucesso é transitória por natureza — some depois de confirmar
 permanece até o estado mudar. Essa decisão é da aplicação, que conhece o ciclo; o componente
 apenas reserva o lugar.
 
-`actions` recebe o que o recurso aberto permite fazer — em geral o mesmo menu que a linha dele
-tem na navegação. Assim a superfície deixa de ser o único lugar onde renomear ou excluir não
-alcançam o item que está na tela. Apenas o texto é região viva: anunciar o menu a cada mudança de
-estado seria ruído para quem usa leitor de tela.
+`actions` recebe o que o recurso aberto permite fazer — em geral o mesmo [`Menu`](/ui/menu) que a
+linha dele tem na navegação. Assim, renomear ou excluir também alcançam o item que está na tela.
+Apenas o texto é região viva: anunciar o menu a cada mudança de estado seria ruído para quem usa
+leitor de tela.
+
+No exemplo, o estado de falha fica no canto superior esquerdo com o menu do recurso, e os controles
+de visualização ficam no canto inferior direito.
+
+```tsx preview
+<div className="relative h-40 w-full rounded-lg border border-border bg-muted/20">
+  <SurfaceStatus
+    position="top-left"
+    context="danger"
+    actions={
+      <Menu>
+        <MenuTrigger asChild>
+          <Button variant="ghost" size="icon" aria-label="Ações do fluxo"><MoreHorizontal /></Button>
+        </MenuTrigger>
+        <MenuContent align="start">
+          <MenuItem><Pencil /> Renomear</MenuItem>
+          <MenuSeparator />
+          <MenuItem context="danger"><Trash2 /> Excluir</MenuItem>
+        </MenuContent>
+      </Menu>
+    }
+  >
+    Falha ao salvar
+  </SurfaceStatus>
+  <Dock label="Controles de visualização" position="bottom-right">
+    <DockGroup>
+      <DockAction icon={<ZoomOut />} label="Afastar" onClick={() => {}} />
+      <DockAction icon={<ZoomIn />} label="Aproximar" onClick={() => {}} />
+      <DockAction icon={<Maximize />} label="Ajustar à tela" onClick={() => {}} />
+    </DockGroup>
+  </Dock>
+</div>
+```
 
 ## Modo e execução
 
@@ -57,36 +90,36 @@ o rótulo, que também é o nome acessível.
 
 ## Teclado
 
-A barra é uma `toolbar`: as setas andam entre as ações e Home/End vão às pontas. Cada ação nomeia-se
-por tooltip, então `<TooltipProvider>` precisa existir na raiz do app — o esqueleto do `opus create`
-já monta.
+A barra é uma `toolbar`: as setas andam entre as ações e Home/End vão às pontas. Cada ação exibe o nome em um
+[tooltip](/ui/tooltip), então `<TooltipProvider>` precisa existir na raiz do app — o projeto criado
+por `opus create` já o monta.
 
 ## Propriedades de Dock
 
 | Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
 | `position` | `'bottom' \| 'bottom-left' \| 'bottom-right'` | `'bottom'` | Aresta do contêiner onde a barra se ancora. |
-| `label` | `string` | | Nome acessível da barra. |
-| `children` | `ReactNode` | | Os grupos de ações, em `DockGroup`. |
+| `label` | `string` | obrigatório | Nome acessível da barra. |
+| `children` | `ReactNode` | obrigatório | Os grupos de ações, em `DockGroup`. |
 | `className` | `string` | | Classes adicionais da barra. |
 
 ## Propriedades de DockGroup
 
 | Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
-| `children` | `ReactNode` | | As ações do grupo, em `DockAction`. A divisória antes do grupo é aplicada automaticamente, exceto no primeiro. |
+| `children` | `ReactNode` | obrigatório | As ações do grupo, em `DockAction`. A divisória antes do grupo é aplicada automaticamente, exceto no primeiro. |
 | `className` | `string` | | Classes adicionais do grupo. |
 
 ## Propriedades de DockAction
 
 | Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
-| `icon` | `ReactNode` | | Ícone exibido no botão. |
-| `label` | `string` | | Nome da ação; vira o nome acessível e o tooltip quando não há `hint`. |
+| `icon` | `ReactNode` | obrigatório | Ícone exibido no botão. |
+| `label` | `string` | obrigatório | Nome da ação; vira o nome acessível e o tooltip quando não há `hint`. |
 | `pressed` | `boolean` | | Presente quando a ação liga um modo: aplica o preenchimento e expõe `aria-pressed`. Ausente quando a ação apenas executa. |
 | `disabled` | `boolean` | `false` | Desabilita a ação e a tira da navegação por setas. |
 | `hint` | `ReactNode` | `label` | Conteúdo do tooltip quando ele precisa dizer mais que o rótulo. |
-| `onClick` | `() => void` | | Executa a ação ou alterna o modo. |
+| `onClick` | `() => void` | obrigatório | Executa a ação ou alterna o modo. |
 | `className` | `string` | | Classes adicionais do botão. |
 
 ## Propriedades de SurfaceStatus
@@ -96,3 +129,5 @@ já monta.
 | `position` | `'top-right' \| 'top-left'` | `'top-right'` | Canto da superfície onde o estado se ancora. |
 | `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O que o estado comunica; tinge borda e texto pela família semântica. |
 | `actions` | `ReactNode` | | Ações do recurso aberto, fora da região viva. |
+| `children` | `ReactNode` | | O texto do estado, anunciado pela região viva a cada mudança. |
+| `className` | `string` | | Classes adicionais do contêiner. |

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

@@ -1,6 +1,7 @@
 Indicador visual compacto para estados que já têm contexto. O tamanho permanece fixo; `context`
-seleciona o significado e `variant` escolhe ponto sólido ou contornado. Quando a cor reforça significado, `label` fornece o nome
-acessível. Sem `label`, o ponto é decorativo.
+seleciona o significado e `variant` escolhe ponto sólido ou contornado. Quando a cor reforça
+significado, `label` fornece o nome acessível. Sem `label`, o ponto é decorativo e fica oculto dos
+leitores de tela.
 
 ```tsx preview
 <div className="flex items-center gap-4">
@@ -8,11 +9,25 @@ acessível. Sem `label`, o ponto é decorativo.
   <Dot context="warning" label="Atenção" />
   <Dot context="danger" label="Falhou" />
   <Dot context="info" label="Publicado" />
-  <Dot context="neutral" aria-hidden />
+  <Dot context="neutral" />
 </div>
 ```
 
-Use `Badge` quando o estado precisar permanecer legível sem depender do contexto ao redor.
+Use [`Badge`](/ui/badge) quando o estado precisar permanecer legível sem depender do contexto ao
+redor.
+
+## Ponto contornado
+
+`variant="outline"` desenha só o contorno. Ele diferencia dois estados que compartilham o mesmo
+`context`, como uma execução agendada e uma em andamento. O `label` continua nomeando cada estado.
+
+```tsx preview
+<div className="flex items-center gap-4 text-sm">
+  <span className="flex items-center gap-2"><Dot context="success" label="Em execução" /> developer</span>
+  <span className="flex items-center gap-2"><Dot context="success" variant="outline" label="Agendado" /> reviewer</span>
+  <span className="flex items-center gap-2"><Dot context="neutral" variant="outline" label="Inativo" /> designer</span>
+</div>
+```
 
 ## Propriedades de Dot
 
@@ -20,4 +35,19 @@ Use `Badge` quando o estado precisar permanecer legível sem depender do context
 |---|---|---|---|
 | `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado da cor. |
 | `variant` | `'solid' \| 'outline'` | `'solid'` | Ponto preenchido ou só contornado. |
-| `label` | `string` | | Nome acessível quando a cor comunica estado; sem ele o ponto é decorativo (`aria-hidden`). |
+| `label` | `string` | | Nome acessível quando a cor comunica estado; o ponto passa a ser exposto como imagem com esse nome. Sem ele, o ponto é decorativo (`aria-hidden`). |
+
+Os demais atributos vão para o elemento `span`.
+
+## Função dotVariants
+
+`dotVariants({ context, variant })` retorna as classes do ponto para um elemento que não é
+renderizado pelo `Dot`. Os padrões são os mesmos do componente: `neutral` e `solid`. Sem o
+componente, o elemento não recebe `label` nem `aria-hidden`; trate a acessibilidade nele.
+
+```ts
+function dotVariants(options?: {
+  context?: DotContext | null
+  variant?: DotVariant | null
+}): string
+```

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

@@ -8,15 +8,15 @@ de fechamento.
 ```tsx preview
 <Drawer>
   <DrawerTrigger asChild>
-    <Button variant="outline">Ver detalhe</Button>
+    <Button variant="outline">Ver veículo</Button>
   </DrawerTrigger>
   <DrawerContent side="right">
     <DrawerHeader>
-      <DrawerTitle>Criar ticket</DrawerTitle>
+      <DrawerTitle>ABC-1D23</DrawerTitle>
     </DrawerHeader>
-    <DrawerBody className="text-sm text-muted-foreground">
-      <p>Ação · domínio Suporte</p>
-      <p>Campos, entrada/saída, arquivo…</p>
+    <DrawerBody className="space-y-1 text-sm text-muted-foreground">
+      <p>Corolla XEi 2022 · 38.400 km</p>
+      <p>Última revisão em 12 de maio.</p>
     </DrawerBody>
   </DrawerContent>
 </Drawer>
@@ -36,11 +36,11 @@ neutra e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
   </DrawerTrigger>
   <DrawerContent side="left">
     <DrawerHeader>
-      <DrawerTitle>Editar workspace</DrawerTitle>
+      <DrawerTitle>Editar veículo</DrawerTitle>
     </DrawerHeader>
     <DrawerBody className="space-y-2">
-      <Label htmlFor="ws-nome">Nome</Label>
-      <Input id="ws-nome" defaultValue="Empresa X" />
+      <Label htmlFor="vehicle-owner">Responsável</Label>
+      <Input id="vehicle-owner" defaultValue="Marina Alves" />
     </DrawerBody>
     <DrawerFooter>
       <ButtonGroup mode="spaced">
@@ -75,11 +75,11 @@ ruído.
   </DrawerTrigger>
   <DrawerContent layout="continuous">
     <DrawerHeader>
-      <DrawerTitle>Resumo da execução</DrawerTitle>
+      <DrawerTitle>Resumo da revisão</DrawerTitle>
     </DrawerHeader>
     <DrawerBody>
       <p className="text-sm text-muted-foreground">
-        Concluída em 2 minutos, sem falhas registradas.
+        Concluída em 2 horas, sem pendências registradas.
       </p>
     </DrawerBody>
   </DrawerContent>
@@ -98,7 +98,7 @@ título ocupa a folga, as ações vão para o extremo oposto e o botão de fecha
 nó que não seja um desses slots interrompe a renderização com um erro; contexto e conteúdo
 pertencem ao `DrawerBody`.
 
-`DrawerMedia` é a moldura de ícone da casa — o mesmo [`IconTile`](/ui/icon-tile) —, útil para
+`DrawerMedia` é a moldura de ícone do Opus — o mesmo [`IconTile`](/ui/icon-tile) —, útil para
 identificar o tipo do recurso aberto. `DrawerNavigation` carrega o retorno de um fluxo encadeado,
 em que o painel permanece aberto e troca de etapa.
 
@@ -110,7 +110,7 @@ em que o painel permanece aberto e troca de etapa.
   <DrawerContent side="right">
     <DrawerHeader>
       <DrawerNavigation>
-        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DrawerNavigation>
@@ -119,7 +119,7 @@ em que o painel permanece aberto e troca de etapa.
       </DrawerMedia>
       <DrawerTitle>ABC-1D23</DrawerTitle>
       <DrawerActions>
-        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+        <Button variant="ghost" size="icon" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DrawerActions>
@@ -131,15 +131,57 @@ em que o painel permanece aberto e troca de etapa.
 </Drawer>
 ```
 
+Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
+[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
+quadrado `icon-sm` (1.75rem) por padrão.
+
 O cabeçalho não recebe descrição: o painel já nomeia o recurso, e o contexto que ajuda a decidir
 aparece no começo do corpo, como texto ou `Alert`.
 
+## Impedir o fechamento durante uma operação
+
+Esc, o clique no overlay e o botão de fechar encerram o painel. Enquanto uma operação não puder ser
+interrompida, passe `closeDisabled` a `DrawerContent`: o botão de fechar continua visível, mas
+desabilitado, e Esc e o clique no overlay deixam de fechar o painel. Se você também passar
+`onEscapeKeyDown`, `onPointerDownOutside` ou `onInteractOutside`, esses handlers continuam sendo
+chamados antes do bloqueio.
+
+`closeDisabled` não alcança as ações que você compõe no painel, como um `Cancelar` com
+`DrawerClose`; desabilite-as pelo mesmo estado da operação. Quando a pessoa precisar responder antes
+de continuar, use [`Dialog mode="alert"`](/ui/dialog), que não fecha pelo clique externo.
+
+## Acessibilidade
+
+- `DrawerTitle` nomeia o painel para tecnologias assistivas. Quando um texto conciso do corpo também
+  precisar descrevê-lo, relacione seu `id` por `aria-describedby` em `DrawerContent`.
+- Com `modal` ativo, o padrão, o foco permanece dentro do painel e o restante da página fica
+  inacessível até o fechamento.
+- Ao fechar, o foco retorna ao gatilho.
+- O botão de fechar tem o nome acessível `Fechar`. Botões só com ícone no cabeçalho precisam de
+  `aria-label`.
+
 ## Propriedades de Drawer
 
-| Propriedade    | Tipo                      | Padrão | Descrição                                                          |
-| -------------- | ------------------------- | ------ | ------------------------------------------------------------------ |
-| `open`         | `boolean`                 |        | Estado no modo controlado.                                         |
-| `onOpenChange` | `(open: boolean) => void` |        | Atualiza o estado para permitir abertura ou fechamento por código. |
+| Propriedade    | Tipo                      | Padrão  | Descrição                                                                    |
+| -------------- | ------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `open`         | `boolean`                 |         | Estado no modo controlado.                                                   |
+| `defaultOpen`  | `boolean`                 | `false` | Abertura inicial no modo não controlado.                                     |
+| `onOpenChange` | `(open: boolean) => void` |         | Recebe as mudanças de abertura, inclusive Esc, overlay e botão de fechar.    |
+| `modal`        | `boolean`                 | `true`  | Mantém foco e interação restritos ao painel aberto e exibe o overlay.        |
+
+## Propriedades de DrawerTrigger
+
+| Propriedade | Tipo        | Padrão  | Descrição                                          |
+| ----------- | ----------- | ------- | -------------------------------------------------- |
+| `asChild`   | `boolean`   | `false` | Usa o filho como gatilho sem criar outro elemento. |
+| `children`  | `ReactNode` |         | Controle que abre o painel.                        |
+
+## Propriedades de DrawerClose
+
+| Propriedade | Tipo        | Padrão  | Descrição                                                   |
+| ----------- | ----------- | ------- | ----------------------------------------------------------- |
+| `asChild`   | `boolean`   | `false` | Aplica o fechamento ao filho; use com `Button`.             |
+| `children`  | `ReactNode` |         | Controle que fecha o painel, como o `Cancelar` do rodapé.   |
 
 ## Propriedades de DrawerContent
 
@@ -147,9 +189,11 @@ aparece no começo do corpo, como texto ou `Alert`.
 | ----------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
 | `side`            | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel aparece.                                                            |
 | `layout`          | `'continuous' \| 'sectioned'`            | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem.              |
-| `showCloseButton` | `boolean`                                | `true`    | Inclui a ação de fechamento no cabeçalho. Desative quando o painel exigir uma ação explícita. |
-| `closeDisabled`   | `boolean`                                | `false`   | Mantém a ação visível e impede fechar enquanto o painel está bloqueado.                    |
+| `showCloseButton` | `boolean`                                | `true`    | Inclui o botão de fechar no cabeçalho. Sem ele, Esc e o overlay continuam fechando o painel. |
+| `closeDisabled`   | `boolean`                                | `false`   | Mantém o botão de fechar visível e desabilitado e impede que Esc e o clique no overlay fechem o painel. |
 | `closeSize`       | `"xs" \| "sm"`                           | `"sm"`    | Define o tamanho da ação circular de fechar.                                               |
+| `className`       | `string`                                 |           | Ajusta o painel, como a largura.                                                           |
+| `children`        | `ReactNode`                              |           | Cabeçalho, corpo e rodapé.                                                                 |
 
 ## Propriedades de DrawerHeader
 

package/src/ui/docs/content/empty-value.md

@@ -1,7 +1,7 @@
-Valor ausente tem uma representação padrão. Nas células de tabela e nos pares de `DetailField`
-aparece o travessão, enquanto a leitura assistiva recebe “Não informado”. As colunas de
-`ActionList` e o `DetailField` já fazem isso sozinhos; um renderer customizado reutiliza a
-primitiva em vez de repetir a condicional.
+Valor ausente tem uma representação padrão. Nas células de tabela e nos pares de
+[`DetailField`](/ui/detail) aparece o travessão, enquanto a leitura assistiva recebe “Não
+informado”. As colunas de [`ActionList`](/ui/action-list) e o `DetailField` já fazem isso sozinhos;
+uma célula ou um componente próprio usa `EmptyValue` em vez de repetir a condicional.
 
 ```tsx preview
 <div className="flex items-center gap-6 text-sm">
@@ -15,8 +15,19 @@ primitiva em vez de repetir a condicional.
 ## O que conta como ausência
 
 `null`, `undefined`, string vazia e string só com espaços. `0`, `false` e coleções vazias são
-valores legítimos: quem apresenta booleanos e listas decide a própria forma. `isAbsentValue`
-exporta a mesma regra para renderers customizados.
+valores legítimos: quem apresenta booleanos e listas decide a própria forma. `isAbsentValue` aplica
+a mesma regra em células e componentes próprios.
+
+```ts
+function isAbsentValue(value: unknown): boolean
+```
+
+```tsx
+import { EmptyValue, isAbsentValue } from '@softize/opus/ui/react'
+
+// Em uma célula própria:
+isAbsentValue(row.phone) ? <EmptyValue compact /> : formatPhone(row.phone)
+```
 
 ## O domínio dá o significado
 
@@ -46,3 +57,6 @@ columns: [
 |---|---|---|---|
 | `label` | `string` | `'Não informado'` | O que a ausência significa neste domínio. |
 | `compact` | `boolean` | `false` | Célula compacta: travessão visível, rótulo só para leitura assistiva. |
+
+Os demais atributos, como `className`, vão para o elemento `span`. `EmptyValue` não aceita
+`children`: o texto entra por `label`.

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

@@ -4,9 +4,9 @@ Use `Empty` quando a própria região está disponível para receber ou criar co
 tracejada diferencia esse espaço de uma estrutura de dados já estabelecida e pode combinar título,
 descrição, mídia e ação.
 
-Para uma lista ou tabela carregada, mas sem registros, use `DataState` ou `ActionList`: a moldura
-sólida preserva a estrutura. Se a região já estiver emoldurada pelo pai, mantenha a borda somente
-no pai para evitar uma moldura dupla.
+Para uma lista ou tabela carregada, mas sem registros, use [`DataState`](/ui/data-state) ou
+[`ActionList`](/ui/action-list): a moldura sólida preserva a estrutura. Se a região já estiver
+emoldurada pelo pai, mantenha a borda somente no pai para evitar uma moldura dupla.
 
 ## Com ícone
 
@@ -78,3 +78,24 @@ ou mídias que tenham presença visual própria.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'default' \| 'icon'` | `'default'` | `icon` aplica uma moldura quadrada e muted; `default` exibe a mídia sem fundo. |
+
+## Propriedades de EmptyHeader
+
+`EmptyHeader` agrupa mídia, título e descrição no centro, com largura limitada para a leitura. Não
+tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyTitle
+
+`EmptyTitle` exibe a situação em destaque. Ele renderiza um `div`, sem nível de heading; quando a
+região precisar de um título na estrutura da página, passe `role="heading"` e `aria-level`. Não tem
+props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyDescription
+
+`EmptyDescription` apresenta a explicação em cor atenuada e sublinha os links filhos diretos. Não
+tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyActions
+
+`EmptyActions` empilha e centraliza as ações abaixo do cabeçalho. Não tem props próprias; aceita as
+de um elemento `div`.

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

@@ -4,9 +4,9 @@ title: Eventos
 
 # Eventos
 
-Use eventos quando uma action precisar anunciar um fato sem conhecer seus consumidores.
-`ctx.emit` publica o evento; reactions e integrações podem assiná-lo pelo `EventBusAdapter`. O
-formato declarado permanece o mesmo durante todo o fluxo.
+Use eventos quando uma action precisar anunciar um fato sem conhecer quem vai reagir a ele.
+`ctx.emit` publica o evento; reactions e integrações o recebem pelo `EventBusAdapter`. O formato do
+evento é o mesmo do handler que emite até quem consome.
 
 ## O contrato
 
@@ -24,6 +24,8 @@ interface DomainEvent<T = unknown> {
   tenant?: string | null
   data: T
   source: { action: string; actionId: string; correlation?: string }
+  trace?: TraceContext                           // trace da execução que emitiu
+  meta?: Record<string, unknown>                 // o terceiro argumento de ctx.emit
 }
 ```
 
@@ -32,10 +34,15 @@ interface DomainEvent<T = unknown> {
 ```ts
 import { mittEvents } from '@softize/opus/events/mitt'
 
-const bus = mittEvents()   // in-process (mesmo processo do runtime)
+const bus = mittEvents() // no mesmo processo do runtime
 ```
 
-## No runtime
+O `mitt` entrega pelo nome exato do evento ou por `*`, que recebe todos. Padrões parciais, como
+`nota.*`, não são reconhecidos: assine `*` e filtre no handler.
+
+## Emitir de uma action
+
+Configure o barramento no runtime e declare no binding os eventos que a action emite:
 
 ```ts
 const runtime = createRuntime({
@@ -43,19 +50,72 @@ const runtime = createRuntime({
   eventBus: bus,
 })
 
-// No handler: emite pelo tipo declarado; o core preenche id/timestamp/actor/source.
-handler: async (ctx, input) => {
-  const nota = await repo.create(input)
-  await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
-  return nota
-}
+export const notaEmitir = bindAction(notaEmitirContract, {
+  emits: ['nota.emitida'],
+  handler: async (ctx, input) => {
+    const nota = await repo.create(input)
+    // O runtime preenche id, timestamp, actor, tenant, source e trace.
+    await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
+    return nota
+  },
+})
 ```
 
-Actions declaram no contrato o que emitem (`emits: ['nota.emitida']`); o runtime avisa se
-o handler emitir algo não-declarado (`emitMode`). Uma reaction assina `nota.emitida` e roda
-como sua própria action rastreável (provenance `reaction`).
+`emits` pertence ao binding, como `handler`, e o runtime só o considera em actions `simple` e
+`form`. Quando uma delas declara `emits` e o handler emite um evento fora da lista, o runtime
+registra um aviso no log. Esse aviso vem de `config.warnUndeclaredEmits`, ativo por padrão fora de produção. Sem `emits`
+declarado, nenhum aviso é gerado.
+
+Em uma action `list` ou `view`, o tipo do binding aceita `emits`, mas a lista não entra no manifest
+nem na conferência dos eventos emitidos. Para que a declaração não pareça ter efeito, o runtime
+registra o aviso `runtime.action_field_ignored` quando a action é registrada com `config.dev` ativo,
+o padrão sempre que `config.env` não é `'production'`. O [`opus check`](/docs/cli) aponta o mesmo
+caso com a regra `ignored-by-kind`. Se a operação anuncia um fato, declare-a como `simple` ou `form`.
+
+`config.emitMode` decide o que acontece quando a publicação não é possível. No padrão, `lenient`, a
+falta de `EventBusAdapter` e uma falha de `publish` viram aviso no log e o handler segue. Em
+`strict`, as duas situações interrompem a action com `emit.no_bus` ou `emit.failed`.
+
+## Reagir a um evento
+
+Uma reaction executa código quando um evento é publicado. Como nas actions, a declaração pode ficar
+no código compartilhado e o efeito, no servidor:
+
+```ts
+import { bindReaction, defineReactionContract } from '@softize/opus/core'
+
+// shared/ — qual evento e o que a reação significa.
+export const notaAvisarFinanceiro = defineReactionContract<{ id: string; valor: number }>({
+  name: 'nota.avisar-financeiro',
+  on: 'nota.emitida',
+  description: 'Avisa o financeiro quando uma nota é emitida.',
+})
+
+// api/ — o efeito.
+export const notaAvisarFinanceiroImpl = bindReaction(notaAvisarFinanceiro, {
+  handler: async (ctx, event) => {
+    ctx.log.info('nota emitida', { id: event.data.id, valor: event.data.valor })
+  },
+})
+```
+
+Registre a reaction com as actions, em `defineDomain({ reactions: [notaAvisarFinanceiroImpl] })`
+ou em `runtime.register`. Com reactions registradas, o `start()` exige um `EventBusAdapter` e falha
+com `runtime.eventbus_required` quando ele não existe. `defineReaction` declara tudo num objeto só,
+quando não há separação entre cliente e servidor.
+
+A reaction roda com provenance `reaction`; `ctx.user` traz somente o `id` do autor do evento, e
+`ctx.tenantId`, o tenant do evento. O contexto não tem `can`: a decisão fica no `authorize(ctx, event)` opcional, e uma resposta `false` descarta o evento
+sem erro. Uma falha no handler é registrada no log e não chega à action que emitiu.
 
 ## Limites atuais
 
-O driver `mitt` é in-process — sem durabilidade nem entre-processos. Barramentos duráveis/
-distribuídos (Redis, NATS…) entram por reincidência de caso real.
+O driver `mitt` funciona no mesmo processo, sem durabilidade nem entrega entre processos.
+
+Uma reaction não encadeia outra por evento: dentro dela, `ctx.emit` descarta o evento sem publicá-lo.
+Com `config.dev` ativo, cada descarte registra o aviso `runtime.reaction_emit_ignored` no log, com o
+nome da reaction e do evento; em produção, o descarte continua silencioso. Quando outro consumidor
+precisa desse fato, emita o evento no handler da action que o produz e declare-o em `emits`.
+
+`retry`, `timeout`, `dedup` e `concurrency` são aceitos na declaração, mas o runtime ainda não os
+aplica: uma reaction que falha não é repetida.

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

@@ -9,7 +9,7 @@ O módulo é experimental e opt-in: instalar o Opus não passa a descobrir crons
 O executor continua dono do estado; este recurso mantém uma fotografia para consulta.
 
 Para colocar trabalho em segundo plano, use [Filas](/docs/queue). Para acompanhar trabalho já
-existente, adapte seu executor à projeção abaixo. Não usar a projeção para decidir reenvio ou retry.
+existente, adapte seu executor à projeção abaixo. Não use a projeção para decidir reenvio ou retry.
 
 ## Publicar uma fotografia
 
@@ -43,8 +43,8 @@ Cron que enfileira trabalho continua com
 `trigger: 'schedule'`; entrar na fila não cria outra execução. Retomada mantém o ID e avança
 revisão/tentativa conforme o executor. A projeção não valida transições de negócio.
 
-Uma falha de projeção lança erro para o adaptador tratar. Registrar essa falha e reconciliar
-depois a partir do executor; não deixar o erro provocar retry de um efeito já realizado.
+Uma falha de projeção lança erro para o adaptador tratar. Registre essa falha e reconcilie
+depois a partir do executor; não deixe o erro provocar retry de um efeito já realizado.
 `observe` não contém proteção automática para o fluxo de negócio do consumidor.
 
 ## Persistência e processos separados
@@ -60,7 +60,7 @@ durável; o aviso não é histórico nem fila de entrega.
 
 `pgExecutionChanges({ connect, onError, channel?, reconnectMs? })` compartilha uma conexão
 LISTEN entre seus assinantes. `connect` deve entregar uma conexão nova, já conectada, dedicada
-e com timeout de conexão configurado. Não fornecer uma conexão emprestada por um pooler
+e com timeout de conexão configurado. Não forneça uma conexão emprestada por um pooler
 transacional. O driver fecha a conexão quando sai o último assinante, registra falhas por
 `onError` e tenta reconectar após `reconnectMs` (padrão: 1.000 ms; mínimo: 100 ms).
 
@@ -87,15 +87,15 @@ async function openProgress(
 }
 ```
 
-Para `authorize(null)`, verificar sessão e direito de acompanhar. Para um aviso, verificar
+Para `authorize(null)`, verifique a sessão e o direito de acompanhar. Para um aviso, verifique
 também tenant, operação e recurso exato. Essa verificação ocorre novamente durante o stream,
 inclusive nos heartbeats e antes de emitir uma invalidação. Heartbeats revalidam a sessão
 independentemente da fila de avisos: a função pode receber um aviso e `null` concorrentemente.
 As actions de leitura devem aplicar a mesma política: filtrar a
 consulta por tenant não substitui autorização.
 
-O cliente recebe somente `event: invalidate` com `{}`. Ao recebê-lo, invalidar as queries das
-actions autorizadas. Manter uma conexão compartilhada no provider da aplicação, não uma por
+O cliente recebe somente `event: invalidate` com `{}`. Ao recebê-lo, invalide as queries das
+actions autorizadas. Mantenha uma conexão compartilhada no provider da aplicação, não uma por
 card. A primeira invalidação e a reconexão exigem nova fotografia; não há `Last-Event-ID` nem
 replay. O navegador pode usar `EventSource` com cookies same-origin e sua reconexão nativa.
 
@@ -105,9 +105,9 @@ de 128 avisos pendentes e 16 frames na saída; excedê-los encerra a conexão pa
 sem acumular um log em memória. Sessão é reavaliada no máximo a cada heartbeat enquanto a
 autorização responde; configure timeout no serviço de autorização para não mantê-la pendente.
 
-IDs, tenant e operação nos avisos são metadados operacionais internos. Não usar CPF, telefone,
+IDs, tenant e operação nos avisos são metadados operacionais internos. Não use CPF, telefone,
 e-mail ou segredo nesses identificadores. PostgreSQL NOTIFY não é uma fronteira de autorização:
-restringir as credenciais e o acesso ao banco. Nada do aviso é copiado para o SSE.
+restrinja as credenciais e o acesso ao banco. Nada do aviso é copiado para o SSE.
 
 ## Detectar ausência de sinal