@softize/opus 13.1.0 → 15.0.0

package/bin/lib/db.mjs

@@ -189,6 +189,8 @@ export function helpDb() {
 
 Flags:
   --config <path>   Caminho interno ao projeto para opus.config.ts. Default: ./opus.config.ts
+                    O .env ao lado dele é carregado antes do config, então DATABASE_URL do
+                    projeto vale sem export manual; variável do ambiente vence o arquivo.
   --help, -h        Mostra esta mensagem
 
 O opus.config.ts precisa expor, pros comandos db:

package/docs/adr/0004-page-content-state-is-composed.md

@@ -1,5 +1,10 @@
 # ADR 0004 — O estado integral do conteúdo é composto dentro de Page
 
+> **Atualização (2026-09-09).** A decisão original preservava o cabeçalho da página em todos os
+> estados. Ela foi invertida: `PageState` passa a ocultá-lo em `loading`, `error` e `empty`, e a
+> restaurá-lo em `ready`. A lista de responsabilidades abaixo já descreve o comportamento novo; o
+> adendo no fim deste arquivo registra o motivo, a alternativa descartada e o que se perde.
+
 ## Contexto
 
 `Page` padroniza o `<main>`, o cabeçalho e o container de uma página. Hoje, consumidores que ainda
@@ -21,15 +26,21 @@ direto de `Page`, que materializa `PageBody`; na composição explícita, `PageS
 `PageState`:
 
 - recebe um estado discriminado entre `loading`, `error`, `empty` e `ready`;
-- preserva o cabeçalho da página em todos os estados;
-- compõe `Spinner`, `Alert` e `Empty` em vez de recriar suas superfícies;
+- oculta o cabeçalho em `loading`, `error` e `empty`, restaurando-o em `ready`;
+- registra sua presença no `Page` mesmo quando um componente intermediário o renderiza;
+- ocupa a altura disponível e usa o título visível do estado como heading principal;
+- centraliza os três estados integrais com uma anatomia visual comum e sem moldura;
+- preserva `role="status"` no carregamento e `role="alert"` na falha sem apresentar o erro como `Alert`;
 - aceita título, descrição, ícone e ação contextual sem exibir erro técnico;
+- apresenta a recuperação integral como botão `outline` textual; o ícone isolado fica restrito a
+  superfícies compactas;
 - expõe `data-slot="page-state"` e `data-status` para testes e análise estrutural;
 - renderiza o conteúdo sem moldura adicional em `ready`.
 
 Estados parciais continuam pertencendo a `DataState`, `ActionView`, `ActionList` ou `Alert`, conforme
-a fronteira afetada. Uma coleção vazia continua dentro da estrutura da coleção; `Empty` representa
-uma região disponível, uma escolha pendente ou uma próxima ação.
+a fronteira afetada. Uma coleção vazia continua dentro da estrutura da coleção. A moldura tracejada
+de `Empty` representa uma região disponível para criar ou vincular; ela não aparece automaticamente
+no vazio integral de uma página.
 
 ## Alternativas consideradas
 
@@ -51,7 +62,8 @@ telas equivalentes.
 
 ## Consequências
 
-- Consumidores ganham uma composição uniforme sem acoplar `Page` a hooks ou actions.
+- Consumidores ganham uma composição uniforme sem acoplar `Page` a hooks ou actions e sem repetir
+  classes de altura.
 - A copy específica do fluxo permanece no consumidor; defaults seguros cobrem usos simples.
 - Migrações precisam distinguir estado integral de estado parcial antes de substituir a composição.
 - O gate estrutural do consumidor deve impedir novos estados integrais montados manualmente.
@@ -63,3 +75,25 @@ telas equivalentes.
   composição explícita.
 - Consumidores verificam `data-slot="page-state"` nos estados integrais e mantêm testes próprios para
   recuperação e distinção entre erro e vazio.
+
+## Adendo (2026-09-09) — o cabeçalho é ocultado nos estados integrais
+
+**Contexto.** A decisão original preservava o cabeçalho em `loading`, `error` e `empty`. Na
+prática, uma página em carregamento mostrava título e ações de um conteúdo que ainda não existia, e
+uma página em erro oferecia ações sobre um conteúdo que falhou. A ADR 0010, ao trazer a
+apresentação em barra, tornou isso mais visível: a faixa ficava de pé, com ações inertes, sobre uma
+superfície de estado que ocupa a tela inteira.
+
+**Decisão.** `Page` oculta o `PageHeader` enquanto o `PageState` estiver em `loading`, `error` ou
+`empty`, e o restaura em `ready`. Não há opt-out. O nível semântico não se perde: a própria
+superfície de estado carrega `role="heading"` com `aria-level={1}`.
+
+**Alternativa descartada.** Ocultar apenas título, descrição e ações, preservando a região
+introdutória. Foi descartada para esta versão porque partiria o cabeçalho em duas regras de
+visibilidade e deixaria a barra materializada só para um botão, contrariando "um header sem
+conteúdo útil não é materializado" da ADR 0010.
+
+**O que se perde, e é conhecido.** Some junto o `PageBack`, então uma subpágina em erro fica sem o
+retorno in-page para o pai — justamente quando a pessoa mais precisa sair. Enquanto esta ADR não
+for revista, uma subpágina que dependa desse retorno oferece a saída pelo `action` do próprio
+`PageState`. Reavaliar se o custo aparecer em uso real.

package/docs/adr/0005-structural-surfaces-share-an-explicit-anatomy.md

@@ -3,6 +3,10 @@
 - **Status:** aceita.
 - **Data:** 2026-09-04.
 
+> **Atualização (2026-09-09).** Parcialmente substituída pela ADR 0009 quanto a `PageMeta` e ao
+> `count` de `Page`, e complementada pela ADR 0010, que acrescenta as apresentações `default` e
+> `bar` ao mesmo header. O corpo abaixo já traz a anatomia vigente.
+
 ## Contexto
 
 Os componentes estruturais da UI descrevem regiões equivalentes com APIs diferentes. `Dialog`
@@ -20,8 +24,9 @@ perdida para obter uma estrutura explícita.
 As superfícies mantidas pela casa adotam a gramática `Root > Header + Body + Footer`, com
 `Title`, `Description`, `Meta` e `Actions` pertencendo ao `Header` da mesma família.
 
-- `Page` oferece `PageHeader`, `PageTitle`, `PageDescription`, `PageMeta`, `PageActions` e
-  `PageBody`.
+- `Page` oferece `PageHeader`, `PageBack`, `PageNavigation`, `PageTitle`, `PageDescription`,
+  `PageActions` e `PageBody`. A ADR 0010 acrescenta as apresentações `default` e `bar` ao mesmo
+  header.
 - `Content` representa uma região de conteúdo semanticamente nomeada e oferece `ContentHeader`,
   `ContentTitle`, `ContentDescription`, `ContentMeta`, `ContentActions` e `ContentBody`.
 - `CardContent` passa a ter `CardBody` como nome canônico.
@@ -37,7 +42,8 @@ As superfícies mantidas pela casa adotam a gramática `Root > Header + Body + F
   `ItemActions` e `ItemFooter`. `ItemContent` permanece temporariamente como alias legado de
   corpo, mas deixa de envolver título e descrição no código novo.
 
-`Page` e `Content` aceitam também uma forma curta com `title`, `description`, `meta` e `actions`.
+`Page` e `Content` aceitam também uma forma curta: `title`, `description` e `actions` nos dois,
+mais `count` no `Content`. A ADR 0009 tirou o contador do título da página.
 Essa forma é açúcar sintático: produz a mesma árvore semântica, os mesmos estilos e os mesmos
 `data-slot` da composição explícita. Um consumidor não pode misturar as duas formas na mesma raiz.
 

package/docs/adr/0009-page-title-does-not-carry-a-counter.md

@@ -0,0 +1,57 @@
+# ADR 0009 — O título da página não carrega contador
+
+- **Status:** aceita.
+- **Data:** 2026-09-09.
+- **Substitui parcialmente:** ADR 0005, somente quanto a `PageMeta` e `count` em `Page`.
+
+## Contexto
+
+`Page` permitia colocar um total imediatamente ao lado do título por `count` ou `PageMeta`. O
+número competia com a identidade da página, não explicava sozinho o conjunto contado e repetia
+informação que já pertence à listagem ou a uma seção do conteúdo.
+
+`Content` também possui metadata, mas representa regiões menores em que o valor pode estar ligado
+ao título local e continuar compreensível dentro da própria seção.
+
+## Decisão
+
+`Page` deixa de aceitar `count` e de exportar `PageMeta`. O cabeçalho da página reconhece somente
+`PageTitle`, `PageDescription` e `PageActions`. Totais e outros indicadores pertencem ao conteúdo
+que os explica, como uma listagem, métrica ou seção composta com `Content`.
+
+`ContentMeta` e o `count` de `Content` permanecem disponíveis. A anatomia compartilhada continua
+sendo usada, mas cada família expõe apenas os slots coerentes com sua escala.
+
+## Consequências
+
+- O título da página volta a comunicar somente a identidade da superfície.
+- Consumidores removem contadores do cabeçalho em vez de deslocá-los para outra posição sem
+  contexto.
+- Uma página que precise destacar um total o apresenta no corpo, próximo do conjunto ou da métrica
+  correspondente.
+- A remoção de `count` e `PageMeta` é incompatível e entra somente na próxima versão major.
+
+## Alternativas consideradas
+
+### Manter o contador como opção
+
+Preservaria compatibilidade, mas manteria uma composição visual que a aplicação já decidiu não
+usar. Foi descartada porque uma opção pública continuaria incentivando o retorno do padrão.
+
+### Ocultar o contador apenas no tema
+
+Evitaria a migração imediata, mas deixaria contrato, documentação e DOM sustentando uma capacidade
+sem representação. Foi descartada porque esconder não remove o padrão.
+
+### Mover automaticamente o total para a descrição
+
+Preservaria a informação, mas o componente não conhece o que está sendo contado nem consegue
+escrever contexto correto. Foi descartada para que o consumidor escolha uma superfície semântica
+quando o total for realmente necessário.
+
+## Verificação
+
+- O tipo de `Page` não aceita `count` e o barrel público não exporta `PageMeta`.
+- Testes de UI verificam a anatomia curta e explícita sem `page-meta`.
+- Busca estrutural impede usos de `count` em `Page` nos consumidores migrados.
+- Documentação e metadata públicas apresentam somente título, descrição e ações.

package/docs/adr/0010-page-header-owns-page-chrome.md

@@ -0,0 +1,73 @@
+# ADR 0010 — PageHeader também representa o chrome compacto da página
+
+- **Status:** aceita.
+- **Data:** 2026-09-09.
+- **Complementa:** ADR 0005.
+
+## Contexto
+
+Aplicações com sidebar passaram a montar uma barra superior separada de `PageHeader` para reunir
+navegação contextual e ações. Essa separação cria dois cabeçalhos para a mesma página, distribui
+título, retorno e ações entre contratos concorrentes e permite reservar uma faixa vazia quando o
+shell não recebe conteúdo.
+
+O breadcrumb absoluto também repete a localização já comunicada pela sidebar e pelo título. Em uma
+subpágina simples, a necessidade real é retornar a um pai conhecido; em hierarquias mais profundas,
+é apresentar os ancestrais relevantes. Nenhum dos casos exige uma segunda anatomia de cabeçalho.
+
+## Decisão
+
+`PageHeader` é a única região de cabeçalho de uma `Page` e oferece duas apresentações:
+
+- `variant="default"` organiza título, descrição e ações dentro do container da página;
+- `variant="bar"` ocupa uma faixa compacta, delimitada por borda, no topo da página.
+
+`PageBack` pertence diretamente a `PageHeader` e recebe um destino explícito. Na apresentação
+padrão, aparece acima do conjunto de título e descrição como botão `ghost` com ícone e rótulo. Na
+barra, aparece como controle icon-only com tooltip e nome acessível derivados do destino visível.
+`PageBack` e breadcrumb não aparecem juntos: retorno simples usa `PageBack`; múltiplos ancestrais
+relevantes são compostos com `Breadcrumb` dentro de `PageNavigation`, na mesma posição do
+cabeçalho.
+
+A variante altera somente a apresentação. Título, descrição, retorno e ações continuam pertencendo
+semanticamente à mesma página. Um header sem conteúdo útil não é materializado para reservar
+altura, e o header é ocultado durante os estados integrais do `PageState` — inversão da decisão
+original da ADR 0004, argumentada no adendo dela. Para acompanhar o ritmo
+compacto da barra, ações com texto usam `Button size="sm"` e ações somente com ícone usam
+`Button size="icon-sm"`.
+
+## Consequências
+
+- shells deixam de precisar de um `PageChrome` paralelo para páginas comuns;
+- páginas de primeiro nível usam o header padrão e não ganham uma barra vazia;
+- subpáginas simples mantêm o retorno junto ao título na apresentação padrão;
+- recursos que precisam de uma faixa persistente podem escolher `variant="bar"` sem mover ações por
+  portal;
+- botões da barra deixam de misturar a escala normal da página com controles compactos;
+- workspaces imersivos ainda podem manter um shell próprio quando não são representados por `Page`.
+
+## Alternativas consideradas
+
+### Manter PageHeader e chrome separados
+
+Preservaria a implementação atual dos consumidores, mas continuaria dividindo uma única região
+semântica entre duas APIs e exigindo regras para decidir onde cada ação aparece.
+
+### Exibir breadcrumb absoluto em toda subpágina
+
+Ofereceria uma trilha uniforme, mas repetiria a navegação global já visível e ocuparia espaço com a
+página atual, que já está nomeada pelo título.
+
+### Usar sempre uma barra
+
+Fixaria a posição dos controles, mas reservaria altura em páginas que não possuem navegação
+contextual nem ações persistentes. A barra permanece uma escolha de apresentação, não o default.
+
+## Verificação
+
+- testes de `Page` cobrem as duas variantes, a posição de `PageBack`, sua acessibilidade e o destino
+  explícito;
+- `opus check` reconhece `PageBack` e `PageNavigation` somente como filhos diretos e mutuamente
+  exclusivos de `PageHeader`;
+- a documentação demonstra retorno simples nas duas apresentações e separa esse caso de breadcrumb;
+- consumidores removem barras paralelas à medida que migram para a anatomia de `Page`.

package/docs/code-style.md

@@ -86,13 +86,16 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
 | `messages.success`, `messages.error`, `messages.confirmation` | `success`, `error`, `message` |
 | `confirm.message` | `dialog-body` |
 | `fields.*.label`, `filters.*.label` | `label` |
-| `placeholder`, `hint`, `help` | `placeholder`, `helper-text` |
+| `placeholder`, `help` | `placeholder`, `helper-text` |
 | opções estáticas | `menu-item` |
 | `columns[].label`, `periods[].label` | `heading`, `tab` |
 | `Select.emptyText`, `Select.searchPlaceholder` | `empty-state`, `placeholder` |
 | `Select.options[].hint/triggerLabel/group` | `label`, `label`, `heading` |
 | `ActionTrigger.confirm.*` | papel correspondente do diálogo |
 | `t.dict` — `label`, `description`, `doc` das entradas e `doc` do dicionário | `label`, `description` |
+| `DataState`/`PageState`/`ActionList`/`ActionListDialog` — `emptyMessage`, `errorMessage`, `retryLabel`; `PageState`/`ActionListDialog` — `title`, `description`; `ActionView.emptyMessage` | `empty-state`, `error`, `button`, `title`, `description` |
+| `dialog.alert/confirm/prompt/choose()` — `title`, `description`, `body`, `action`, `cancel`, `placeholder`, `actions[].label` | papel correspondente do diálogo |
+| `TooltipContent` (children), `LabelHelp.help` | `label`, `helper-text` |
 
 ## Cobertura e significado do gate verde
 

package/docs/data-layer.md

@@ -70,6 +70,15 @@ opus db migrate       # aplica o SCHEMA IDEMPOTENTE + drift-check na sequência
 opus db scaffold      # gera rascunho a partir do diff (referência pro schema)
 ```
 
+**De onde vem a conexão.** O config do consumer costuma abrir o banco no topo do módulo,
+lendo `process.env` na hora do import. Por isso o CLI carrega o `.env` ao lado do
+`opus.config.ts` ANTES de importar o config — em `db`, `seed` e `gen`, num lugar só, para
+que nenhum comando possa esquecer. Variável já definida no ambiente vence o arquivo (a
+semântica do `--env-file` do Node), então `DATABASE_URL=... opus db migrate` e a injeção
+do container continuam mandando; ausência de `.env` é normal e não é erro. Sem isso, um
+projeto que guarda a URL no `.env` migrava o banco DEFAULT do config enquanto o runtime
+usava outro — o schema aplicado some do banco que a aplicação abre.
+
 **Schema idempotente evolutivo** (o padrão da casa, não migration versionada): UM
 script SQL (`config.schema`, ex. `src/db/schema.sql`) re-rodável — `CREATE IF NOT
 EXISTS` + guards `DO $$ IF EXISTS` cobrem nascer do zero E upgrade de prod no mesmo

package/package.json

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

package/registry/instructions/opus.md

@@ -17,9 +17,9 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
 - Não duplicar schemas, tipos de transporte, validação ou fetch que o contrato já fornece.
 - Em UI semântica, declarar primeiro `context` (`neutral`, `primary`, `info`, `success`, `warning`
   ou `danger`) e usar `variant` somente para o tratamento visual (`solid`, `subtle`, `outline`,
-  `ghost` ou `link`). Dicionários de status e estágio declaram `context`; `tone` e variantes
-  semânticas antigas são apenas compatibilidade de migração. `destructive` permanece uma
-  propriedade comportamental de actions e se projeta visualmente como `danger`.
+  `ghost` ou `link`). Dicionários de status e estágio declaram `context`; `tone` é apenas
+  compatibilidade de migração e as variantes semânticas antigas não existem mais. `destructive`
+  permanece uma propriedade comportamental de actions e se projeta visualmente como `danger`.
 - Declarar datasets persistentes com `defineSeed` + `bindSeed`, registrá-los em `opus.config.ts`
   e operá-los por `opus seed`; não criar comandos de seed paralelos nem reset implícito.
 - Regenerar o inventário com `opus copy` quando mudar copy em contrato ou componente Opus

package/registry/skills/build-opus-ui/SKILL.md

@@ -42,8 +42,9 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    o produto precisa de deep link, back/forward ou refresh.
 8. Compor superfícies pela gramática estrutural do catálogo: `Page` contém `PageHeader` e
    `PageBody`; `Content` contém `ContentHeader` e `ContentBody`; Card, Drawer e Pane usam seus
-   respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` ou `Content` com
-   `title`, `description`, `meta` e `actions`; não misturá-la com o header explícito. Ajustar o
+   respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` (`title`,
+   `description`, `actions`) ou de `Content` (as mesmas mais `count`); não misturá-la com o
+   header explícito. O título da página não carrega contador. Ajustar o
    nível do heading pela hierarquia semântica, não pelo destaque visual. O `Page` mantém seu teto
    centralizado padrão de `80rem`.
 9. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -5,18 +5,29 @@
   operação, não a uma tela isolada.
 - URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
 - `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
-  explícita é `Page > PageHeader (PageTitle, PageDescription, PageMeta, PageActions) + PageBody`;
-  `title`, `description`, `meta` e `actions` no próprio `Page` são a abreviação para o caso direto.
+  explícita é `Page > PageHeader (PageBack? | PageNavigation?, PageTitle, PageDescription?,
+  PageActions?) + PageBody`; `title`, `description` e `actions` no próprio `Page` são a abreviação
+  para o caso direto.
   Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
   real de largura; não reconstruir esse container em cada rota.
+- `PageHeader` é a única região de cabeçalho da página. O default acompanha o container;
+  `variant="bar"` apresenta a mesma anatomia como faixa compacta no topo. Em uma subpágina simples,
+  `PageBack` recebe o destino pai explícito: aparece acima do título no default e como icon-only com
+  tooltip na barra. Para mais de um ancestral relevante, use `Breadcrumb` dentro de
+  `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome paralelo para uma `Page`.
+  Ações com texto na barra usam `Button size="sm"`; ações somente com ícone usam `icon-sm`.
+  `PageActionsTarget` fica reservado a workspaces imersivos que já possuam chrome próprio.
 - `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
   forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
-  explícita, fica dentro de `PageBody`. O cabeçalho permanece visível. Estados de seção ou coleção
-  continuam em `DataState`, `ActionView`, `ActionList` ou `Alert`; não elevar uma falha parcial a
-  estado da página.
+  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho some, o estado
+  ocupa a área disponível e seu título assume o heading principal, inclusive quando um componente
+  intermediário renderiza o estado. O erro mantém `role="alert"`, usa a mesma composição central e
+  sem moldura dos demais estados e apresenta a recuperação como botão `outline` textual. Estados de
+  seção ou coleção continuam em `DataState`, `ActionView`, `ActionList` ou `Alert`; não elevar uma
+  falha parcial a estado da página.
 - `Content` delimita uma seção e segue a mesma anatomia: `Content > ContentHeader (ContentTitle,
   ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
-  solto. `title`, `description`, `meta` e `actions` no `Content` são a abreviação para o caso
+  solto. `title`, `description`, `count` e `actions` no `Content` são a abreviação para o caso
   direto e não podem ser misturados ao header explícito. `level` preserva a hierarquia semântica
   do heading.
 - Card, Drawer e Pane nomeiam a região principal como `CardBody`, `DrawerBody` e `PaneBody`.

package/registry/templates/app/src/App.tsx

@@ -1,5 +1,5 @@
 import type { z } from 'zod'
-import { Badge, Card, useListAction } from '@softize/opus/ui/react'
+import { Badge, Card, DataState, useListAction } from '@softize/opus/ui/react'
 import { Task, taskList } from './domains/tasks/actions/list.ts'
 
 type TaskItem = z.infer<typeof Task>
@@ -10,7 +10,7 @@ export function App(): React.ReactElement {
   // O front consome o CONTRATO via /api — o plugin opusDesign (vite.config.ts)
   // serve o backend no próprio dev server: dev normal executa o handler real;
   // `pnpm dev:design` responde com o mockHandler, isolado de qualquer backend.
-  const { items, isLoading } = useListAction<TaskItem>(taskList)
+  const { items, isLoading, error, refetch } = useListAction<TaskItem>(taskList)
 
   return (
     <main className="flex min-h-full items-center justify-center bg-background p-6">
@@ -19,9 +19,14 @@ export function App(): React.ReactElement {
         <p className="mb-4 text-sm text-muted-foreground">
           Esqueleto criado pelo opus create. A spec vive nas declarações do domínio.
         </p>
-        {isLoading ? (
-          <p className="text-sm text-muted-foreground">Carregando…</p>
-        ) : (
+        {/* Carregando, erro e vazio saem do DataState; a lista só cuida dos itens. */}
+        <DataState
+          loading={isLoading}
+          error={error ?? null}
+          empty={items.length === 0}
+          emptyMessage="Nenhuma tarefa ainda."
+          onRetry={() => refetch()}
+        >
           <ul className="space-y-2">
             {items.map((t) => (
               <li key={t.id} className="flex items-center justify-between gap-2 text-sm">
@@ -30,7 +35,7 @@ export function App(): React.ReactElement {
               </li>
             ))}
           </ul>
-        )}
+        </DataState>
       </Card>
     </main>
   )

package/src/core/types.ts

@@ -551,9 +551,8 @@ export type FieldWidget = BuiltInFieldWidget | (string & { readonly __opusCustom
 export interface FieldSpec {
   label: I18nRef
   placeholder?: I18nRef
-  hint?: I18nRef
-  /** Ajuda no hover/foco da label (ícone ⓘ + tooltip). `hint` = texto auxiliar SOB o campo;
-   *  `help` = explicação mais longa, escondida atrás do ícone na label. */
+  /** 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. */
   help?: I18nRef
 
   default?: unknown
@@ -629,7 +628,7 @@ export interface ListColumnSpec {
    *  'badge' (chip `outline` com o valor — legado; coluna de dicionário com `presentation`
    *  declarado usa `DictionaryValue` e dispensa este tipo). */
   type?: 'text' | 'number' | 'date' | 'badge'
-  /** Referência do dicionário registrado em `TbdlibProvider dicts` que esta coluna mostra,
+  /** Referência do dicionário registrado em `OpusProvider dicts` que esta coluna mostra,
    *  quando o schema de saída não carrega a meta de `t.dict` (ex.: campo `z.string()`).
    *  Coluna cujo campo de saída É um `t.dict().zod()` resolve sozinha, sem esta chave. */
   dictionary?: string

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -37,7 +37,10 @@ export interface ActionListDialogProps<TItem, TInput extends Record<string, unkn
   note?: ReactNode
   /** Ação à direita da linha — em geral o botão de criar. */
   actions?: ReactNode
-  emptyText?: string
+  /** Textos dos estados, repassados ao ActionList (e dele ao DataState). */
+  emptyMessage?: string
+  errorMessage?: string
+  retryLabel?: string
   /** Sobrepõe o vazio derivado (items.length === 0) — ex.: form inline aberto. */
   empty?: (items: TItem[]) => boolean
   /** Carga EXTRA agregada à do fetch (ex.: a query irmã que os children precisam). */
@@ -57,7 +60,9 @@ export function ActionListDialog<TItem, TInput extends Record<string, unknown> =
   description,
   note,
   actions,
-  emptyText,
+  emptyMessage,
+  errorMessage,
+  retryLabel,
   empty,
   loading,
   className,
@@ -80,7 +85,9 @@ export function ActionListDialog<TItem, TInput extends Record<string, unknown> =
           <ActionList<TInput, TItem>
             action={action as unknown as ListAction<TInput, TItem>}
             input={(input ?? {}) as TInput}
-            {...(emptyText !== undefined ? { emptyMessage: emptyText } : {})}
+            {...(emptyMessage !== undefined ? { emptyMessage } : {})}
+            {...(errorMessage !== undefined ? { errorMessage } : {})}
+            {...(retryLabel !== undefined ? { retryLabel } : {})}
             {...(empty !== undefined ? { empty } : {})}
             {...(loading !== undefined ? { loading } : {})}
           >

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

@@ -12,7 +12,7 @@
  *
  * Namespace `dialog` de propósito: `window.alert/confirm/prompt` são globais do browser, e
  * um import esquecido cairia no nativo (cinza, sem tema) sem erro. `window.dialog` não
- * existe — a família fica imune ao footgun. `confirm()` segue exportado como alias.
+ * existe — a família fica imune ao footgun.
  *
  * Por baixo é o <Dialog mode="alert">: `role="alertdialog"`, não fecha no clique fora, foco preso
  * — a semântica que uma interrupção que EXIGE resposta pede. ESC/Cancelar resolve o "não"
@@ -59,16 +59,12 @@ export interface ConfirmOptions extends DialogBase {
   cancel?: string
   /** Contexto do botão de confirmação. */
   context?: Extract<UiContext, 'primary' | 'danger'>
-  /** @deprecated Use `context="danger"`. */
-  variant?: 'default' | 'destructive'
 }
 
 /** `prompt` — uma string livre. Form de verdade (campos, contrato) → ActionFormDialog. */
 export interface PromptOptions extends DialogBase {
   cancel?: string
   context?: Extract<UiContext, 'primary' | 'danger'>
-  /** @deprecated Use `context="danger"`. */
-  variant?: 'default' | 'destructive'
   placeholder?: string
   defaultValue?: string
 }
@@ -107,16 +103,6 @@ function requireHost(fn: string): Error | null {
   )
 }
 
-function rejectAmbiguousContext(
-  fn: string,
-  options: ConfirmOptions | PromptOptions,
-): Error | null {
-  if (options.context === undefined || options.variant === undefined) return null
-  return new Error(
-    `${fn} não permite combinar context com uma variante semântica legada.`,
-  )
-}
-
 function validateChoose<TResult extends string>(options: ChooseOptions<TResult>): Error | null {
   if (options.actions.length === 0) {
     return new Error('dialog.choose() exige pelo menos uma ação.')
@@ -145,8 +131,6 @@ export const dialog = {
   },
   /** Pergunta sim/não. `Promise<boolean>` — fechar/ESC resolve `false`. */
   confirm(options: ConfirmOptions): Promise<boolean> {
-    const ambiguous = rejectAmbiguousContext('dialog.confirm()', options)
-    if (ambiguous !== null) return Promise.reject(ambiguous)
     const err = requireHost('dialog.confirm()')
     if (err !== null) return Promise.reject(err)
     return new Promise<boolean>((resolve) => {
@@ -155,8 +139,6 @@ export const dialog = {
   },
   /** Pede uma string. `Promise<string | null>` — fechar/ESC/Cancelar resolve `null`. */
   prompt(options: PromptOptions): Promise<string | null> {
-    const ambiguous = rejectAmbiguousContext('dialog.prompt()', options)
-    if (ambiguous !== null) return Promise.reject(ambiguous)
     const err = requireHost('dialog.prompt()')
     if (err !== null) return Promise.reject(err)
     return new Promise<string | null>((resolve) => {
@@ -180,11 +162,6 @@ export const dialog = {
   },
 }
 
-/** @deprecated Alias retrocompatível — use `dialog.confirm()`. */
-export function confirm(options: ConfirmOptions): Promise<boolean> {
-  return dialog.confirm(options)
-}
-
 /**
  * O host — um por app, no shell. Enfileira: uma por vez (duas caixas empilhadas seriam
  * ambíguas sobre qual clique respondeu o quê).
@@ -228,11 +205,8 @@ export function DialogHost(): React.ReactElement {
     else p.resolve(value)
   }
 
-  const variant = current !== undefined && (current.kind === 'confirm' || current.kind === 'prompt')
-    ? current.variant
-    : undefined
   const context = current !== undefined && (current.kind === 'confirm' || current.kind === 'prompt')
-    ? current.context ?? (variant === 'destructive' ? 'danger' : 'primary')
+    ? current.context ?? 'primary'
     : 'primary'
   const defaultAction = current?.kind === 'alert' ? 'OK' : 'Confirmar'
 
@@ -344,6 +318,3 @@ export function DialogHost(): React.ReactElement {
     </Dialog>
   )
 }
-
-/** @deprecated Alias retrocompatível — monte `<DialogHost />`. */
-export const ConfirmHost = DialogHost