@softize/opus 16.1.0 → 17.1.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ 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.
 
+## 17.1.0 — 2026-09-12
+
+Formulários de `Presentation` em Dialog e Drawer passam a oferecer `Cancelar` ao lado da ação
+principal. O retorno no header modal aparece somente quando a surface anterior também é um Dialog
+ou Drawer; a Page mantida ao fundo não cria uma etapa de navegação.
+
+Em Page hospedada por `PageShell`, a `Presentation` mantém navegação e ações na barra e apresenta o
+título no `PageIntro`. Ações que abrem outra Presentation usam o botão default para assumir a
+hierarquia primária do fluxo. Ações textuais de header e footer usam o tamanho `default`; `sm` fica
+reservado às operações densas de toolbar, seção e coleção.
+
+## 17.0.0 — 2026-09-11
+
+A inspeção de `Presentation` passa a pertencer exclusivamente à Lens, que lê as definições estáticas
+projetadas no manifest. `PresentationDevtoolsProvider`, `usePresentationRegistration` e
+`PresentationDevtools` deixam de existir; a aplicação não mantém um segundo registro de execução
+nem monta um launcher no shell. `PresentationInspector` permanece disponível para a Lens e para
+bancadas isoladas que precisem visualizar um snapshot mascarado.
+
+`Presentation` passa a consumir diretamente a definição, a invocação e o registry de contratos.
+O renderer delega actions `simple`, `form`, `list` e `view` a `ActionTrigger`, `ActionForm`,
+`ActionList` e `ActionView`; navegação e efeitos atualizam a invocação serializável. O gate cruza
+bindings com o schema de input das actions antes de publicar o manifest.
+Actions de formulário ocupam o footer estrutural da superfície e continuam associadas ao `<form>`.
+O body pode declarar `submitLabel` para nomear a conclusão específica do formulário.
+Durante uma action com `blocking: "surface"`, voltar, fechar, editar campos e submeter o formulário
+permanecem bloqueados até a conclusão.
+
+`PageShell` recebe navigation, title e actions do `PageHeader` descendente. `PageIntro` volta a ser
+somente uma introdução opcional do body. Page, Dialog e Drawer deixam de oferecer Description no
+header; contexto relevante começa no body.
+
+O fechamento padrão de `Dialog` e `Drawer` passa a ser um `Button` ghost somente com ícone no final
+do header. `showCloseButton` continua controlando sua presença. O `CommandDialog` adota um header
+compacto para preservar a mesma anatomia; não existe uma segunda posição flutuante para o close.
+
+**Breaking:** remova providers, registros e launchers de Presentation do shell. Use a projeção de
+Presentations na Lens para inspecionar as definições disponíveis. Migre a composição manual de
+`Presentation` para `definition`, `definitions`, `actions` e `invocation`. Remova `description` de
+`Page` e `PageDescription`; mova apenas o contexto relevante para o início de `PageBody`.
+
 ## 16.1.0 — 2026-09-11
 
 `PresentationDevtoolsProvider`, `usePresentationRegistration` e `PresentationDevtools` permitem

package/bin/lib/check.mjs

@@ -109,9 +109,8 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageBody", new Set(["Page"])],
   ["PageFooter", new Set(["Page"])],
   ["PageTitle", new Set(["PageHeader", "PageIntro"])],
-  ["PageBack", new Set(["PageHeader", "PageIntro"])],
-  ["PageNavigation", new Set(["PageHeader", "PageIntro"])],
-  ["PageDescription", new Set(["PageHeader", "PageIntro"])],
+  ["PageBack", new Set(["PageHeader"])],
+  ["PageNavigation", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader", "PageIntro"])],
   ["ContentHeader", new Set(["Content"])],
   ["ContentBody", new Set(["Content"])],
@@ -171,12 +170,13 @@ const UI_STRUCTURAL_ROOTS = new Map([
       alternateHeader: "PageIntro",
       body: "PageBody",
       footer: "PageFooter",
-      shorthand: new Set(["title", "description", "actions"]),
+      shorthand: new Set(["title", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
       // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
       // prop removida é cobrada aqui, nas duas formas de composição.
       removed: new Map([
         ["count", "o total pertence ao conteúdo que o explica"],
+        ["description", "mova contexto relevante para o início do body"],
       ]),
     },
   ],
@@ -199,7 +199,6 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageTitle",
   "PageBack",
   "PageNavigation",
-  "PageDescription",
   "PageActions",
   "ContentHeader",
   "ContentBody",
@@ -240,6 +239,10 @@ const UI_REMOVED_PROPS = new Map([
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
+  [
+    "PageDescription",
+    "mova contexto relevante para o início de `PageBody`",
+  ],
   [
     "DialogDescription",
     "mova contexto relevante para o início de `DialogBody`",
@@ -260,7 +263,6 @@ const UI_STRUCTURAL_HEADERS = new Map([
       optional: new Set([
         "PageBack",
         "PageNavigation",
-        "PageDescription",
         "PageActions",
       ]),
       exclusive: [new Set(["PageBack", "PageNavigation"])],
@@ -271,13 +273,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageIntro",
     {
       title: "PageTitle",
-      optional: new Set([
-        "PageBack",
-        "PageNavigation",
-        "PageDescription",
-        "PageActions",
-      ]),
-      exclusive: [new Set(["PageBack", "PageNavigation"])],
+      optional: new Set(["PageActions"]),
       shorthand: new Set(),
     },
   ],

package/bin/lib/copy.mjs

@@ -78,6 +78,7 @@ const AUDIT_REFERENCE =
   /^(?:https?:\/\/\S+|[a-z][a-z0-9-]*:\S+|(?:[A-Za-z0-9._-]+\/)+[A-Za-z0-9._#/-]+|[A-Za-z0-9._-]+\.(?:md|json|ya?ml)(?:#[^\s]+)?)$/u
 const CONTRACT_MODULES = new Set(['@softize/opus', '@softize/opus/core'])
 const CONTRACT_FACTORIES = new Set(['defineAction', 'defineContract'])
+const PRESENTATION_MODULES = new Set(['@softize/opus', '@softize/opus/presentation'])
 const SCHEMA_ZOD_MODULES = new Set(['@softize/opus/schema/zod'])
 const ACTION_BINDING_KEYS = new Set(['authorize', 'background', 'emits', 'handler', 'idempotency', 'loads'])
 
@@ -119,7 +120,6 @@ const JSX_CHILD_ROLES = new Map([
   ['MenuRadioItem', 'menu-item'],
   ['PopoverDescription', 'description'],
   ['PopoverTitle', 'title'],
-  ['PageDescription', 'description'],
   // O texto do PageBack é o NOME do destino ('Clientes'), como um item de trilha — não um
   // comando. Classificado como `button`, a política universal cobraria verbo de ação.
   ['PageBack', 'breadcrumb'],
@@ -268,7 +268,6 @@ const JSX_PROP_ROLES = new Map([
     'Page',
     new Map([
       ['title', 'title'],
-      ['description', 'description'],
     ]),
   ],
   [
@@ -386,7 +385,6 @@ const JSX_PROP_CLASS = new Map([
     'Page',
     new Map([
       ['title', 'className'],
-      ['description', 'className'],
     ]),
   ],
   ['Select', new Map([['placeholder', 'className']])],
@@ -1419,6 +1417,7 @@ export function extractCopyFromSource(file, sourceText) {
   const diagnostics = []
   let hasContract = false
   let hasDictionary = false
+  let hasPresentation = false
   const hasUiImport = sourceFile.statements.some(
     (statement) =>
       ts.isImportDeclaration(statement) &&
@@ -1550,6 +1549,22 @@ export function extractCopyFromSource(file, sourceText) {
     nestedObject(object, 'errors', (error, prefix) => addProperty(error, 'description', 'error', prefix))
   }
 
+  function extractPresentation(object) {
+    addProperty(object, 'title', 'title')
+    nestedObject(object, 'body', (body, prefix) => {
+      addProperty(body, 'submitLabel', 'button', prefix)
+      nestedObject(
+        body,
+        'fields',
+        (field, fieldPrefix) => {
+          addProperty(field, 'label', 'label', fieldPrefix)
+          addProperty(field, 'empty', 'empty-state', fieldPrefix)
+        },
+        prefix,
+      )
+    })
+  }
+
   function extractDictionary(call) {
     const entriesNode = call.arguments[0]
     const entries = resolveBinding(entriesNode, checker)
@@ -1595,6 +1610,10 @@ export function extractCopyFromSource(file, sourceText) {
     return name !== null && CONTRACT_FACTORIES.has(name) ? name : null
   }
 
+  function presentationFactory(expression) {
+    return importedMember(expression, (module) => PRESENTATION_MODULES.has(module)) === 'definePresentation'
+  }
+
   function opusComponent(tagName) {
     return importedMember(tagName, uiModule)
   }
@@ -2552,6 +2571,12 @@ export function extractCopyFromSource(file, sourceText) {
         else diagnostics.push(diagnostic(file, sourceFile, node.arguments[0], `${factory}(...)`, 'structure'))
       }
     }
+    if (ts.isCallExpression(node) && presentationFactory(node.expression) && node.arguments.length > 0) {
+      hasPresentation = true
+      const object = resolveBinding(node.arguments[0], checker)
+      if (ts.isObjectLiteralExpression(object)) extractPresentation(object)
+      else diagnostics.push(diagnostic(file, sourceFile, node.arguments[0], 'definePresentation(...)', 'structure'))
+    }
     if (ts.isCallExpression(node) && knownDictionaryFactory(node, checker) && node.arguments.length > 0) {
       hasDictionary = true
       extractDictionary(node)
@@ -2563,7 +2588,7 @@ export function extractCopyFromSource(file, sourceText) {
 
   return {
     hasContract,
-    hasCopySurface: hasContract || hasDictionary || hasUiImport,
+    hasCopySurface: hasContract || hasDictionary || hasPresentation || hasUiImport,
     entries,
     diagnostics,
   }

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

@@ -6,6 +6,9 @@
 > **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.
+>
+> **Atualização (2026-09-11).** As ADRs 0012 e 0014 removem Description dos headers de Page,
+> Dialog e Drawer. Contexto relevante começa no body.
 
 ## Contexto
 
@@ -24,7 +27,7 @@ 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`, `PageBack`, `PageNavigation`, `PageTitle`, `PageDescription`,
+- `Page` oferece `PageHeader`, `PageBack`, `PageNavigation`, `PageTitle`,
   `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`,
@@ -42,8 +45,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: `title`, `description` e `actions` nos dois,
-mais `count` no `Content`. A ADR 0009 tirou o contador do título da página.
+`Page` aceita também uma forma curta com `title` e `actions`. `Content` mantém `title`,
+`description`, `actions` e `count`. 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

@@ -4,6 +4,9 @@
 - **Data:** 2026-09-09.
 - **Substitui parcialmente:** ADR 0005, somente quanto a `PageMeta` e `count` em `Page`.
 
+> **Atualização (2026-09-11).** A ADR 0014 remove `PageDescription`; contexto útil pertence ao
+> início do body, e contadores continuam na seção que explicam.
+
 ## Contexto
 
 `Page` permitia colocar um total imediatamente ao lado do título por `count` ou `PageMeta`. O
@@ -16,7 +19,7 @@ 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
+`PageTitle` 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
@@ -54,4 +57,4 @@ quando o total for realmente necessário.
 - 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.
+- Documentação e metadata públicas apresentam somente título e ações.

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

@@ -21,16 +21,15 @@ renderiza a barra, recebe a navegação conhecida pelo shell e oferece o alvo ca
 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.
-Na forma explícita, a página usa `PageIntro` e `PageBody`. Fora de `PageShell`, a composição anterior
-com `PageHeader` continua válida; `PageIntro` também pode ser escolhido quando o conteúdo precisa de
-uma introdução sem navegação própria. As duas regiões não são equivalentes: `PageHeader` reúne o
-cabeçalho completo, enquanto `PageIntro` dá mais presença ao título dentro do conteúdo.
+Quando uma `Page` está dentro de `PageShell`, `PageHeader` continua sendo seu header estrutural.
+`PageTitle`, `PageNavigation`, `PageBack` e `PageActions` são projetados nos alvos da barra sem
+duplicar a anatomia no body. Na forma explícita, a página usa `PageHeader` e `PageBody`, com
+`PageIntro` opcional para contexto adicional no conteúdo. Fora de `PageShell`, `PageHeader` aparece
+dentro do container da página.
 
-`PageState` oculta somente `PageIntro`. A barra do `PageShell` permanece visível porque preserva
-navegação e ações globais mesmo quando o conteúdo carrega, falha ou está vazio. Uma ação que depende
-do conteúdo deve se omitir por estado na própria rota.
+`PageState` oculta somente `PageIntro`. A barra do `PageShell` permanece visível com navegação,
+título e ações mesmo quando o conteúdo carrega, falha ou está vazio. Uma ação que depende do
+conteúdo deve se omitir por estado na própria rota.
 
 `PageShell` não substitui o shell completo da aplicação, não inclui sidebar e não cria navegação.
 Ele apenas coordena a barra e a área em que uma única `Page` é renderizada.
@@ -39,11 +38,10 @@ Ele apenas coordena a barra e a área em que uma única `Page` é renderizada.
 
 - shell e rota podem continuar conhecendo partes diferentes da página sem criar componentes locais
   de chrome;
-- 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;
+- título e ações têm destinos oficiais na barra;
 - estados integrais preservam a barra e escondem somente a introdução do conteúdo;
-- a composição de `Page` com `PageHeader` permanece disponível fora de `PageShell`, sem uma segunda
-  forma de produzir a barra;
+- a composição de `Page` com `PageHeader` é a mesma dentro e fora de `PageShell`; apenas seu destino
+  visual muda;
 - `PageActionsTarget` continua disponível apenas para workspaces imersivos que não usam
   `PageShell`.
 
@@ -66,7 +64,7 @@ estado do conteúdo. A moldura do shell não deve oscilar com a consulta da rota
 
 ## Verificação
 
-- testes cobrem a projeção das ações, a permanência da barra e a ocultação de `PageIntro` em estados
+- testes cobrem a projeção de navegação, título e ações, a permanência da barra e a ocultação de `PageIntro` em estados
   integrais;
 - a documentação demonstra a composição de `PageShell`, `PageIntro` e `Page` sem CSS externo;
 - consumidores removem barras paralelas e `PageActionsTarget` ao adotar o novo contrato.

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

@@ -16,8 +16,9 @@ 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`.
+- `DialogHeader` e `DrawerHeader` contêm o título e as ações da faixa superior. O close padrão é uma
+  action ghost somente com ícone, inserida por último quando `showCloseButton` está ativo. Não existe
+  uma posição flutuante alternativa nem 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`
@@ -25,12 +26,13 @@ da descrição acessível do modal.
 - `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.
+- `CommandDialog` mantém um header compacto com título e close. A instrução que explica o controle
+  permanece disponível apenas para tecnologias assistivas.
 
 ## Consequências
 
 - Modais comuns começam mais perto da tarefa e não pedem texto de preenchimento.
+- Dialog, Drawer e CommandDialog mantêm a mesma anatomia de fechamento no header.
 - 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
@@ -41,5 +43,7 @@ da descrição acessível do modal.
 
 - o barrel público não exporta `DialogDescription` nem `DrawerDescription`;
 - os tipos das APIs imperativas não aceitam `description`;
+- `DialogContent` e `DrawerContent` não aceitam outra posição para o close;
+- testes confirmam que o close automático é um `Button` ghost dentro do header;
 - 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

@@ -12,18 +12,19 @@ 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.
+capacidades 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.
+A anatomia portátil é `Header + Body + Footer?`, mas cada surface materializa seu header de acordo
+com o espaço disponível. Dialog e Drawer organizam horizontalmente
+`Navigation? + Title + Actions? + Close` e mantêm as ações de conclusão no footer. Em Page
+hospedada por `PageShell`, a barra persistente reúne navegação e ações; o título inicia o conteúdo
+em `PageIntro`, sem repetir a página atual ao lado do breadcrumb. Fora do shell, a Page materializa
+seu header completo no próprio container.
 
 Uma action assume um de dois papéis:
 
@@ -48,11 +49,15 @@ estática, publicável no manifest e inspecionável pela Lens. A invocação é
 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.
+`back` restaura o último frame da pilha. Em Dialog ou Drawer, ele só é apresentado quando o frame
+anterior também é modal; a Page mantida ao fundo não cria uma etapa intermediária. `close` encerra
+apenas dialog ou drawer e é inválido para page. Formulários modais oferecem `Cancelar` como ação de
+abandono no footer, ao lado da conclusão. `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. O
+inventário estático e seu JSON ficam disponíveis na Lens; a aplicação não adiciona um launcher
+flutuante ao shell.
 
 ## Consequências
 
@@ -85,8 +90,12 @@ Foi descartada porque compatibilidade exige delegar cada kind ao pattern canôni
 
 - 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;
+- validação cruza bindings, chaves obrigatórias e valores fixos com o schema de input da action;
 - 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;
+- testes do renderer cobrem a ausência de retorno entre Page e modal, o retorno entre modais e as
+  ações Cancelar/concluir do formulário;
 - o inspetor mascara segredo, token, cookie, autorização, senha e chave de API;
+- a Lens lista as definições registradas e abre o JSON integral sem depender da árvore React;
 - uma aplicação consumidora usa o pacote local por symlink durante a migração página por página.

package/docs/adr/0014-structural-headers-do-not-carry-description.md

@@ -0,0 +1,35 @@
+# ADR 0014 — Headers estruturais não carregam descrição
+
+- **Status:** aceita.
+- **Data:** 2026-09-11.
+- **Complementa:** ADRs 0005, 0011 e 0012.
+
+## Contexto
+
+Uma segunda linha no header de Page, Dialog ou Drawer frequentemente repetia o título, antecipava
+o conteúdo óbvio ou existia apenas para preencher a composição. Isso aumentava a altura fixa da
+superfície e misturava o nome do recurso com instruções e consequências da tarefa.
+
+## Decisão
+
+Headers estruturais contêm navegação opcional, título e actions. Page não oferece a propriedade
+`description` nem `PageDescription`; Dialog e Drawer seguem a mesma regra conforme a ADR 0012.
+
+Contexto que altera compreensão ou decisão aparece no início do body. Ele pode ser texto, `Alert`,
+`Content` ou outra composição adequada. `PageState`, `Alert`, `Empty`, campos, métricas e seções
+continuam podendo ter descrição porque ela qualifica o estado ou conteúdo local, não o header da
+superfície.
+
+## Consequências
+
+- Page, Dialog e Drawer compartilham `Navigation? + Title + Actions?` no header.
+- A ausência de copy de preenchimento reduz altura e variação entre superfícies.
+- Informações úteis continuam possíveis, mas pertencem ao body e à semântica que explicam.
+- A remoção é incompatível e exige migrar contexto relevante para o início do body.
+
+## Verificação
+
+- os barrels não exportam `PageDescription`, `DialogDescription` ou `DrawerDescription`;
+- shorthand e tipos públicos não aceitam `description` nessas superfícies;
+- checker, documentação e testes orientam a migração para o body;
+- `PageState` e componentes de conteúdo local preservam suas descrições próprias.

package/docs/adr/0015-action-size-follows-interaction-density.md

@@ -0,0 +1,64 @@
+# ADR 0015 — O tamanho da ação acompanha a densidade da interação
+
+- **Status:** aceita.
+- **Data:** 2026-09-12.
+
+## Contexto
+
+O uso de `default` e `sm` passou a variar entre headers de Page, footers de Dialog e Drawer,
+toolbars e ações de listagem. Como tamanho também era usado para sugerir importância, duas decisões
+equivalentes podiam ganhar alturas diferentes, enquanto ações repetitivas ocupavam o mesmo espaço
+de uma conclusão da superfície.
+
+O Opus já separa contexto semântico, variante visual e tamanho. Misturar esses eixos impede que a
+mesma regra funcione quando uma ação muda de secundária para primária ou quando um recurso troca de
+Page para Dialog ou Drawer.
+
+## Decisão
+
+O tamanho comunica densidade e alcance da interação; `context` e `variant` comunicam hierarquia e
+risco.
+
+- ações textuais que decidem a superfície usam `default`: header de Page e footer de Page, Dialog
+  ou Drawer;
+- ações operacionais em toolbar, header de seção ou coleção densa usam `sm`;
+- ações internas de linha, célula ou campo usam `xs` ou `icon-xs`;
+- ações somente com ícone que pertencem ao chrome da superfície, como voltar e fechar, usam
+  `icon-sm`;
+- `lg` fica reservado a chamadas que deliberadamente precisam de uma área de toque maior, não a
+  uma ação primária comum.
+
+Patterns que conhecem a região aplicam o tamanho. Componentes estruturais genéricos não clonam nem
+reescrevem filhos arbitrários: em composição manual, o consumidor segue a mesma matriz. Alterar a
+ênfase de uma ação não altera seu tamanho dentro da região.
+
+## Consequências
+
+- Page, Dialog e Drawer mantêm proporção equivalente nas decisões principais;
+- toolbars e grids preservam densidade sem reduzir ações de conclusão;
+- `primary`, `neutral` e `danger` podem mudar sem provocar salto de altura;
+- exemplos e skills deixam de recomendar `sm` por todo cabeçalho compacto.
+
+## Alternativas consideradas
+
+### Usar `sm` em toda barra ou header
+
+Preservaria a menor altura possível, mas trataria uma decisão da página como operação repetitiva e
+criaria diferença em relação ao footer modal do mesmo recurso.
+
+### Fazer a ação primária sempre maior
+
+Reforçaria hierarquia, mas misturaria importância com densidade. A variante `solid` e o contexto
+`primary` já comunicam essa relação sem deslocar o layout.
+
+### Fazer `ButtonGroup` redimensionar qualquer filho
+
+Centralizaria parte da aparência, mas introduziria comportamento implícito e frágil para filhos que
+não são `Button`. A região ou o pattern conhece melhor o tamanho adequado.
+
+## Verificação
+
+- testes da `Presentation` conferem `default` em ações textuais do header e do footer;
+- testes de `ActionList` continuam cobrindo `sm` em toolbar e `icon-xs` nas ações de linha;
+- a documentação de Button e Page apresenta a mesma matriz;
+- revisão de consumidor trata divergência como exceção explícita, não como novo default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "16.1.0",
+  "version": "17.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -227,7 +227,7 @@
     "@radix-ui/react-slot": "^1.1.1",
     "@radix-ui/react-tabs": "^1.1.2",
     "@radix-ui/react-tooltip": "^1.1.6",
-    "@softize/base": "^2.2.1",
+    "@softize/base": "^2.3.0",
     "@tailwindcss/typography": "^0.5.20",
     "@types/markdown-it": "^14.1.2",
     "class-variance-authority": "^0.7.1",

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

@@ -8,7 +8,7 @@
   uma coleção secundária e um `ActionFormDialog`; provar teto padrão de `80rem`, hierarquia por
   `level`, vazio estrutural sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento
   inferido e cancelamento `ghost` no modal.
-- Execução abreviada: montar outra página com `<Page title description actions>` e uma seção com
+- Execução abreviada: montar outra página com `<Page title actions>` e uma seção com
   `<Content title description actions>`, provando que ambas produzem a mesma anatomia e que o lint
   rejeita a mistura entre props abreviadas e headers explícitos.
 - Execução de forma: compor uma tabela dentro de Card sem moldura duplicada, manter a moldura

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

@@ -5,14 +5,13 @@
   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 (PageBack? | PageNavigation?, PageTitle, PageDescription?,
-PageActions?) + PageBody`; `title`, `description` e `actions` no próprio `Page` são a abreviação
+  explícita é `Page > PageHeader (PageBack? | PageNavigation?, PageTitle,
+PageActions?) + PageBody`; `title` 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`.
+- `PageIntro` é uma região opcional do body para contexto realmente útil; não substitui nem duplica
+  o título estrutural do `PageHeader`.
 - `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
@@ -21,18 +20,18 @@ PageActions?) + PageBody`; `title`, `description` e `actions` no próprio `Page`
   possuam chrome próprio.
 - Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
   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
+  declarando `title` e `actions`. O Opus mantém a barra de `3rem` e projeta título e ações nela.
+  Ações com texto na barra usam o tamanho `default`, como as ações de footer de Dialog e Drawer;
+  ações somente com ícone de chrome usam `icon-sm`. O tamanho `sm` fica para ações operacionais em
+  toolbar, seção ou coleção densa, e `xs`/`icon-xs` para ações internas de linha ou célula. Contexto
+  e variante resolvem a hierarquia visual sem alterar essa medida. Na forma explícita dentro do
+  shell, use `Page > PageHeader (PageNavigation?, PageTitle, PageActions?) + PageBody`, com
+  `PageIntro` opcional antes do body. 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
-  some inteiro — incluindo o `PageBack`; dentro de `PageShell`, somente `PageIntro` some e a barra
+  some inteiro — incluindo o `PageBack`; dentro de `PageShell`, `PageIntro` some e a barra
   permanece. O estado ocupa a área disponível e seu título assume o heading
   principal, inclusive quando um componente intermediário renderiza o estado. Uma subpágina que
   dependa do retorno ao pai oferece essa saída pelo `action` do próprio `PageState`. O erro mantém
@@ -67,11 +66,13 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
   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.
+- Cabeçalhos de `Dialog` e `Drawer` nomeiam a superfície com o título e organizam suas ações. O close
+  padrão é uma action ghost somente com ícone no final do header; não crie uma posição flutuante
+  alternativa. 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

package/registry/templates/app/package.json

@@ -30,7 +30,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@softize/base": "^2.2.1",
+    "@softize/base": "^2.3.0",
     "@tailwindcss/vite": "^4.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",