@softize/opus 15.2.2 → 16.0.0

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

@@ -1,12 +1,11 @@
 # ADR 0010 — PageHeader também representa o chrome compacto da página
 
-- **Status:** aceita.
+- **Status:** substituída pela ADR 0011.
 - **Data:** 2026-09-09.
 - **Complementa:** ADR 0005.
 
-> **Atualização (2026-09-10).** A ADR 0011 acrescenta `PageShell` para o caso em que shell e rota
-> conhecem partes diferentes da mesma página. A barra continua sendo a apresentação compacta do
-> cabeçalho, mas o título do conteúdo passa a `PageIntro` e as ações são coordenadas pelo Opus.
+> **Atualização (2026-09-11).** A ADR 0011 torna `PageShell` o único componente responsável pela
+> barra persistente. `PageHeader` volta a ter uma única apresentação dentro da página.
 
 ## Contexto
 

package/docs/adr/0011-page-shell-coordinates-persistent-page-chrome.md

@@ -17,8 +17,9 @@ anatomias concorrentes e faz um estado integral remover também a navegação pe
 ## Decisão
 
 `PageShell` representa a moldura persistente de uma página dentro de um shell de aplicação. Ele
-renderiza a apresentação em barra de `PageHeader`, recebe a navegação conhecida pelo shell e oferece
-o alvo canônico para ações declaradas pela `Page` descendente.
+renderiza a barra, recebe a navegação conhecida pelo shell e oferece o alvo canônico para ações
+declaradas pela `Page` descendente. Essa barra existe somente por `PageShell`; `PageHeader` não
+possui variante visual para reproduzi-la dentro da página.
 
 Quando uma `Page` está dentro de `PageShell`, sua forma curta transforma título e descrição em
 `PageIntro`, dentro do conteúdo. `PageActions` continua declarado pela página, mas aparece na barra.
@@ -41,7 +42,8 @@ Ele apenas coordena a barra e a área em que uma única `Page` é renderizada.
 - título e descrição deixam de ser mascarados por seletores globais;
 - ações de página têm um único destino oficial na barra;
 - estados integrais preservam a barra e escondem somente a introdução do conteúdo;
-- a composição anterior de `Page` permanece compatível fora de `PageShell`;
+- a composição de `Page` com `PageHeader` permanece disponível fora de `PageShell`, sem uma segunda
+  forma de produzir a barra;
 - `PageActionsTarget` continua disponível apenas para workspaces imersivos que não usam
   `PageShell`.
 

package/docs/adr/0012-modal-header-only-names-the-surface.md

@@ -0,0 +1,45 @@
+# ADR 0012 — O cabeçalho modal apenas nomeia a superfície
+
+- **Status:** aceita.
+- **Data:** 2026-09-11.
+
+## Contexto
+
+`DialogDescription` e `DrawerDescription` tornavam natural preencher o cabeçalho com uma segunda
+linha mesmo quando ela apenas repetia o título ou explicava a ação óbvia. O resultado era uma
+hierarquia mais pesada, mais espaço fixo antes da tarefa e textos que raramente ajudavam a pessoa a
+decidir.
+
+Há, porém, contexto que não pode desaparecer: consequências, restrições e instruções que mudam a
+decisão. Esse conteúdo pertence à tarefa, não ao nome da superfície. Também pode precisar participar
+da descrição acessível do modal.
+
+## Decisão
+
+- `DialogHeader` e `DrawerHeader` contêm o título e, quando necessário, mídia. Não existe API pública
+  `DialogDescription` ou `DrawerDescription`.
+- Contexto relevante aparece no início de `DialogBody` ou `DrawerBody`, como texto, `Alert` ou uma
+  composição própria. Texto que apenas repete o título ou a ação é omitido.
+- A API imperativa usa somente `body` para esse conteúdo. `ActionFormDialog` e `ActionListDialog`
+  oferecem `intro` no início do corpo; não oferecem `description`.
+- `DialogContent` e `DrawerContent` não inferem uma descrição. Quando um trecho conciso do corpo deve
+  descrever a superfície para tecnologias assistivas, o consumidor relaciona seu `id` por
+  `aria-describedby`.
+- `CommandDialog` mantém internamente uma instrução apenas para tecnologias assistivas, porque ela
+  explica o funcionamento do controle e não é copy visual do cabeçalho.
+
+## Consequências
+
+- Modais comuns começam mais perto da tarefa e não pedem texto de preenchimento.
+- Informações importantes continuam visíveis, mas ocupam a região rolável e podem usar o componente
+  semântico adequado.
+- A migração troca `description` por `body` na API imperativa, por `intro` nos wrappers e move conteúdo
+  declarativo relevante para o começo do corpo.
+- O checker reprova as APIs removidas com orientação de migração.
+
+## Verificação
+
+- o barrel público não exporta `DialogDescription` nem `DrawerDescription`;
+- os tipos das APIs imperativas não aceitam `description`;
+- testes cobrem `body`, `intro`, a relação acessível e os diagnósticos de migração;
+- a auditoria de docs, o inventário de copy, o typecheck e a suíte do pacote permanecem verdes.

package/docs/adr/0013-presentation-is-a-portable-action-oriented-artifact.md

@@ -0,0 +1,92 @@
+# ADR 0013 — Presentation é um artefato portátil orientado a actions
+
+- **Status:** aceita.
+- **Data:** 2026-09-11.
+
+## Contexto
+
+Page, Dialog e Drawer compartilham uma anatomia estrutural, mas consumidores ainda repetem a
+coordenação entre título, navegação, corpo, ações, estados e ciclo de abertura. Essa repetição
+dificulta apresentar o mesmo recurso em superfícies diferentes e impede que ferramentas analisem
+a interface antes de executar React.
+
+O Opus já declara actions `simple`, `form`, `list` e `view`. Um artefato de interface não deve
+reimplementar seus contratos, validação, autorização ou transporte; deve apenas compor essas
+capacidade em uma apresentação verificável.
+
+## Decisão
+
+`Presentation` é o artefato declarativo que descreve um recurso independentemente da superfície em
+que aparece. `Surface` escolhe `page`, `dialog` ou `drawer` no momento da renderização.
+
+A anatomia portátil é `Header + Body + Footer?`. O header organiza horizontalmente
+`Navigation? + Title + Actions?`; o body contém o recurso; o footer contém ações de conclusão.
+Dialog e Drawer acrescentam o fechamento ao final das ações do header. Page pode ainda usar
+navegação persistente fornecida pelo shell e uma introdução opcional dentro do body, sem mover nem
+duplicar o título estrutural.
+
+Uma action assume um de dois papéis:
+
+- conteúdo no body: actions `form`, `list` e `view` usam seus patterns canônicos;
+- comando no header ou footer: `simple` executa por `ActionTrigger`; os demais kinds abrem ou
+  navegam para outra Presentation que os apresenta como conteúdo.
+
+O kind declarado pela action determina o pattern. A Presentation não repete `presentation: form`
+ou `presentation: trigger`. Bindings declarativos fornecem input a partir de rota, registro, item,
+seleção, sessão, resultado, valor fixo ou relógio. Autorização permanece no servidor.
+
+Efeitos posteriores e coordenação de bloqueio são dados declarativos, não callbacks persistidos. O
+renderer pode coordenar os escopos `action`, `group` e `surface`, mas cada pattern continua dono de
+loading, erro, vazio, validação e repetição próprios.
+
+Presentations possuem identificador e versão de schema, são registradas no `opus.config.ts` e
+projetadas no manifest. A lens lê essa projeção; não infere a interface pelo JSX. Combinações
+inválidas, referências ausentes e bindings incompatíveis produzem diagnósticos antes do runtime.
+
+`PresentationDefinition` e `PresentationInvocation` têm ciclos de vida distintos. A definição é
+estática, publicável no manifest e inspecionável pela Lens. A invocação é o estado serializável de
+uma execução: identifica a Presentation, escolhe a surface, carrega somente input JSON e mantém a
+pilha de frames necessária para voltar. Ela não é publicada no manifest.
+
+`back` restaura o último frame da pilha. `close` encerra apenas dialog ou drawer e é inválido para
+page. `navigate` abre outra invocação por push ou substitui a atual; sincronizar esse estado com URL
+é responsabilidade do adaptador da aplicação quando refresh, deep link ou histórico forem
+necessários. O inspetor de desenvolvimento reúne definição, invocação, bindings resolvidos e
+diagnósticos, mascarando chaves sensíveis antes de expor o JSON.
+
+## Consequências
+
+- O mesmo recurso pode ser apresentado como page, dialog ou drawer sem três implementações.
+- Novas interfaces convencionais concentram código na declaração e na composição específica.
+- `ActionFormDialog`, `ActionListDialog` e wrappers equivalentes permanecem atalhos manuais, mas não
+  formam novos kinds do artefato.
+- Interfaces específicas continuam possíveis por nós de extensão explícitos; uma extensão não é
+  considerada portátil até possuir renderer registrado para as superfícies declaradas.
+- O schema evolui por versão e migração; consumidores não dependem de detalhes internos do renderer.
+
+## Alternativas consideradas
+
+### Persistir JSX ou callbacks
+
+Preservaria liberdade irrestrita, mas não seria serializável, verificável nem seguro para autoria
+por ferramentas. Foi descartada em favor de bindings e efeitos fechados.
+
+### Criar schemas separados para Page, Dialog e Drawer
+
+Representaria diretamente a aparência atual, mas triplicaria a composição e faria a superfície
+definir o recurso. Foi descartada porque as diferenças pertencem ao renderer.
+
+### Tratar toda action como ActionTrigger
+
+Uniformizaria comandos visualmente, mas perderia os ciclos próprios de formulário, lista e view.
+Foi descartada porque compatibilidade exige delegar cada kind ao pattern canônico.
+
+## Verificação
+
+- testes de schema cobrem versão, referências, kinds, placements e bindings;
+- testes do renderer exercitam `simple`, `form`, `list` e `view` nas superfícies válidas;
+- o manifest projeta Presentations sem callbacks nem dados server-only;
+- a lens lista e expõe o JSON integral de cada Presentation;
+- testes de invocação cobrem push, replace, back, close e rejeição de input não JSON;
+- o inspetor mascara segredo, token, cookie, autorização, senha e chave de API;
+- uma aplicação consumidora usa o pacote local por symlink durante a migração página por página.

package/docs/code-style.md

@@ -61,7 +61,12 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
     "allowedUppercase": ["CPF"],
     "exclude": ["scripts/fixtures/**"],
     "transforms": [
-      { "source": "src/account.ts", "line": 12, "role": "button", "transform": "uppercase" }
+      {
+        "source": "src/account.ts",
+        "line": 12,
+        "role": "button",
+        "transform": "uppercase"
+      }
     ],
     "exemptions": [
       {
@@ -78,24 +83,24 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
 }
 ```
 
-| Propriedade Opus | Papel no protocolo Base |
-|---|---|
-| `label`, `confirm.*Label`, `ActionTrigger.label` | `button` |
-| `title`, `examples[].name` | `title` |
-| `summary`, `description`, `examples[].description`, `expand.*.description` | `description` |
-| `messages.success`, `messages.error`, `messages.confirmation` | `success`, `error`, `message` |
-| `confirm.message` | `dialog-body` |
-| `fields.*.label`, `filters.*.label` | `label` |
-| `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` |
+| Propriedade Opus                                                                                                                                                                           | Papel no protocolo Base                                  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
+| `label`, `confirm.*Label`, `ActionTrigger.label`                                                                                                                                           | `button`                                                 |
+| `title`, `examples[].name`                                                                                                                                                                 | `title`                                                  |
+| `summary`, `description`, `examples[].description`, `expand.*.description`                                                                                                                 | `description`                                            |
+| `messages.success`, `messages.error`, `messages.confirmation`                                                                                                                              | `success`, `error`, `message`                            |
+| `confirm.message`                                                                                                                                                                          | `dialog-body`                                            |
+| `fields.*.label`, `filters.*.label`                                                                                                                                                        | `label`                                                  |
+| `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` |
+| `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
 
@@ -109,7 +114,7 @@ O extrator cobre três superfícies, sem heurística de nome:
    `@softize/opus/schema/zod`; metadata livre não é classificada por nome, declarações dinâmicas
    reprovam em vez de serem executadas e o dicionário mantém um snapshot imutável das entradas;
 3. texto estático em filhos e props de uma allowlist de componentes importados diretamente
-   de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogDescription`,
+   de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogBody`,
    `FieldLabel`, `TabsTrigger`, `Page`, `Input` e `DataState`. Alias e namespace de import
    continuam rastreáveis. `uppercase`, variantes como `sm:hover:uppercase`, modificadores
    `!uppercase`/`uppercase!` e classes em descendentes são projetados na superfície que

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "15.2.2",
+  "version": "16.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -153,6 +153,10 @@
       "types": "./src/seed/index.ts",
       "default": "./src/seed/index.ts"
     },
+    "./presentation": {
+      "types": "./src/presentation/index.ts",
+      "default": "./src/presentation/index.ts"
+    },
     "./server": {
       "types": "./src/server/index.ts",
       "default": "./src/server/index.ts"

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

@@ -6,26 +6,29 @@
 - 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 (PageBack? | PageNavigation?, PageTitle, PageDescription?,
-  PageActions?) + PageBody`; `title`, `description` e `actions` no próprio `Page` são a abreviação
+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.
 - Fora de `PageShell`, a composição explícita também pode trocar `PageHeader` por `PageIntro` quando
   o conteúdo precisar somente de título, descrição e ações, sem retorno ou breadcrumb. `PageIntro`
   dá mais presença ao título e não é uma abreviação visual de `PageHeader`.
-- `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.
+- `PageHeader` é a região de cabeçalho dentro de uma `Page` isolada e organiza navegação, título e
+  ações na mesma linha. Em uma subpágina simples, `PageBack` recebe o destino pai explícito e aparece
+  antes do título como controle somente com ícone. 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`. `PageActionsTarget` fica reservado a workspaces imersivos que já
+  possuam chrome próprio.
 - Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
-  O shell fornece `navigation`; a `Page` descendente continua declarando `title`, `description` e
-  `actions`. O Opus mantém a barra de `3rem`, projeta as ações nela e apresenta título e descrição
-  como `PageIntro` no conteúdo. Na forma explícita dentro do shell, use
-  `Page > PageIntro (PageTitle, PageDescription?, PageActions?) + PageBody`. Não monte `PaneHeader`,
-  portal ou seletor global para reconstruir essa composição.
+  O shell é o único responsável pela barra: fornece `navigation`; a `Page` descendente continua
+  declarando `title`, `description` e `actions`. O Opus mantém a barra de `3rem`, projeta as
+  ações nela e apresenta título e descrição como `PageIntro` no conteúdo. Ações com texto na barra
+  usam `Button size="sm"`; ações somente com ícone usam `icon-sm`. Na forma explícita dentro do
+  shell, use `Page > PageIntro (PageTitle, PageDescription?, PageActions?) + PageBody`. Não monte
+  `PaneHeader`, portal ou seletor global para reconstruir essa composição.
+- Quando a rota precisa de navegação própria além da navegação persistente do shell, declare
+  `PageNavigation` no `PageIntro`. Esse slot permanece com o recurso ao alternar entre Page, Dialog
+  e Drawer; não replique nele a navegação global já fornecida pelo shell.
 - `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 sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho da Page isolada
@@ -37,7 +40,7 @@
   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
+ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
   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.
@@ -64,6 +67,11 @@
   controles customizados pelo contexto. `ActionFormCard` e `ActionFormDialog` acrescentam a
   casca; não duplicar o form para obter card ou modal. Cancelamento em forms, confirmações e
   modais usa `ghost`, deixando o destaque visual para a ação principal.
+- Cabeçalhos de `Dialog` e `Drawer` apenas nomeiam a superfície com o título. Não preencher uma
+  segunda linha por hábito. Consequência, restrição ou instrução que realmente mude a tarefa entra
+  no início de `DialogBody`/`DrawerBody`, como texto ou `Alert`; wrappers usam `intro` e a API
+  imperativa usa `body`. Relacione texto conciso por `aria-describedby` somente quando ele também
+  precisar descrever a superfície para tecnologias assistivas.
 - `ActionList` mantém fetch, toolbar, loading, erro, retry, vazio, seleção e paginação enquanto
   permite três composições de resultado: tabela por `columns`, renderer completo por `children`
   ou views nomeadas. Usar `ActionFilterBar` isoladamente só quando outra superfície assumir a
@@ -100,12 +108,12 @@
 O dicionário declara o papel; a tela só escolhe onde o valor fica. Tabela de decisão aplicada
 por `DictionaryValue` e pelas colunas de `ActionList`:
 
-| Papel declarado | Exemplos | Forma | Contexto | Variante | Ícone | Tooltip |
-|---|---|---|---|---|---|---|
-| `classification` | Tipo de cliente, categoria, natureza | Badge | `neutral` | `outline`; ignora `context` da entrada | se a entrada declara `icon` do catálogo | se `description` acrescenta ao rótulo |
-| `status` | Aberto, resolvido, degradado | Badge | pela entrada; `neutral` por padrão | `subtle`; nunca `outline` | idem | idem |
-| `stage` | Prospect, cliente; etapa do funil | Badge | igual a `status` | `subtle` | idem | idem |
-| `plain` ou ausente | Fonte, formato, período | Texto | — | — | idem | idem |
+| Papel declarado    | Exemplos                             | Forma | Contexto                           | Variante                               | Ícone                                   | Tooltip                               |
+| ------------------ | ------------------------------------ | ----- | ---------------------------------- | -------------------------------------- | --------------------------------------- | ------------------------------------- |
+| `classification`   | Tipo de cliente, categoria, natureza | Badge | `neutral`                          | `outline`; ignora `context` da entrada | se a entrada declara `icon` do catálogo | se `description` acrescenta ao rótulo |
+| `status`           | Aberto, resolvido, degradado         | Badge | pela entrada; `neutral` por padrão | `subtle`; nunca `outline`              | idem                                    | idem                                  |
+| `stage`            | Prospect, cliente; etapa do funil    | Badge | igual a `status`                   | `subtle`                               | idem                                    | idem                                  |
+| `plain` ou ausente | Fonte, formato, período              | Texto | —                                  | —                                      | idem                                    | idem                                  |
 
 Regras que não dependem da tabela:
 
@@ -123,13 +131,22 @@ Exemplo correto — tipo e estágio em colunas próprias, apresentação do dici
 
 ```ts
 export const customerKindDict = t.dict(
-  { pf: { label: 'Pessoa física', icon: 'user' }, pj: { label: 'Empresa', icon: 'building' } },
-  { doc: 'Natureza da parte no cadastro global.', presentation: 'classification' },
-)
+  {
+    pf: { label: "Pessoa física", icon: "user" },
+    pj: { label: "Empresa", icon: "building" },
+  },
+  {
+    doc: "Natureza da parte no cadastro global.",
+    presentation: "classification",
+  },
+);
 export const customerStageDict = t.dict(
-  { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } },
-  { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
-)
+  {
+    prospect: { label: "Prospect" },
+    customer: { label: "Cliente", context: "success" },
+  },
+  { doc: "Estágio comercial atual da parte.", presentation: "stage" },
+);
 // contrato:
 //   columns: [{ key: 'name' }, { key: 'kind', label: 'Tipo' }, { key: 'stage', label: 'Estágio' }]
 //   output: z.object({ kind: customerKindDict.zod(), stage: customerStageDict.zod() })