@softize/opus 29.0.0 → 31.0.0

package/docs/adr/0065-presentation-composes-settings-sections.md

@@ -0,0 +1,295 @@
+# ADR 0065 — Presentation compõe seções declaradas
+
+- **Status:** implementado localmente; ainda não publicado.
+- **Data:** 2026-10-18.
+
+## Contexto
+
+A composição centralizada e a lista em itens foram validadas visualmente, mas a definição
+publicável ainda conhece somente o título da página e uma boundary React opaca. Para migrar
+Configurações gradualmente, a definição precisa descrever a estrutura sem incorporar funções,
+credenciais ou uma segunda implementação do serviço de autenticação.
+
+## Decisão
+
+Estender Presentation com `page.composition` e a alternativa `body.sections`. O piloto suporta
+seções de itens estáticos e listas em itens conectadas a um adaptador externo registrado.
+Títulos, descrições, ordem, campos da lista e mensagens de consulta pertencem ao JSON. Cada
+seção tem id estável; a lista continua sendo renderizada por ActionList. A composição usa
+Surface e ItemGroup existentes e preserva o ritmo e o visual aprovados.
+
+Operações e conteúdo específico são extensões nomeadas no runtime: slots React para ações,
+valores, feedback e overlays; adaptadores tipados para fontes externas e suas ações por item
+ou coleção. Slots ausentes são erros, enquanto slots registrados com null são estados válidos.
+Os adaptadores são código confiável do consumidor, nunca expressões ou imports obtidos do JSON.
+A definição é publicável, mas essas extensões continuam dependentes do renderer registrado.
+
+O piloto não cria um motor genérico de formulários ou expressões. Forms, views e listas de
+actions continuam usando body.action. Abas e demais configurações serão avaliadas nos próximos
+pilotos. body.component permanece uma extensão válida. O schemaVersion 1 recebe uma extensão
+aditiva ainda local; consumidores antigos não interpretam sections e precisam ser atualizados
+antes de adotar uma definição que a utilize.
+
+## Alternativas e consequências
+
+Manter uma única boundary React não permitiria inspecionar a composição. Serializar JSX ou
+callbacks confundiria conteúdo declarativo com execução. Criar actions fictícias para o IdP
+violaria a fronteira existente. O modelo escolhido expõe as partes portáveis e nomeia cada
+extensão, mantendo a migração reversível por página.
+
+## Verificação
+
+Testar serialização e validação de ids, propriedades desconhecidas e campos inválidos; renderizar
+uma definição reconstruída de JSON; falhar diante de extensões ausentes; preservar estados da
+lista, comportamento de senha e revogação. O inventário de copy deve encontrar textos de seções
+e itens sem tratar ids de adaptadores ou nomes de campos como linguagem humana.
+
+## Segundo piloto: CRUD de Unidades
+
+Uma família de Presentations declara a lista, a criação e a edição com rotas próprias.
+A página usa `page.composition: document`; formulários continuam Dialog e derivam campos,
+validação, execução e invalidação dos contratos. Comandos `placement: row` declaram ações
+por item, bindings e destino; exclusão delega confirmação e execução ao ActionTrigger.
+Nesse recorte, bloqueio de comando por linha é sempre `action`, isolado por item.
+
+`body.cells` referencia um adaptador tipado, vinculado ao nome da list action. Ícones dos
+comandos de linha são referências ao registro runtime, sem importar uma biblioteca inteira.
+A API `bindPresentationCells` preserva a tipagem do item no consumidor; o renderer confere
+que o adaptador pertence à action antes de consultar. O switch Ativo permanece nessa
+extensão e usa a operação já existente. Reimplementar o switch e os ícones em uma linguagem
+arbitrária de expressões foi descartado: os contratos e componentes atuais já os resolvem.
+
+O piloto mantém o mecanismo existente de lookup do registro pela primeira página sem
+recorte. Um deep link fora dela continua exibindo ausência explícita; a migração não cria
+uma operação de consulta por id. A composição declarativa não altera permissões de servidor.
+Testes cobrem criar, editar, cancelar, validar, ativar/desativar e excluir com confirmação,
+além de referências de linha incompatíveis e ausência de adaptadores.
+
+## Terceiro piloto: abas de E-mails
+
+`body.tabs` declara ids, rótulos, ícones registrados, conteúdos nomeados e rotas opcionais;
+`defaultTab` identifica a aba inicial e `tabLabel` nomeia a navegação acessível. A composição
+usa Tabs e os slots de abas nativos dos headers de Page, Dialog e Drawer. O runtime pode
+controlar a seleção para sincronizá-la com a URL; sem controle, vale o estado local.
+As rotas são metadados consumidos pelo roteador da aplicação, sem imports ou execução no JSON.
+Ids duplicados e aba inicial inexistente são inválidos. Conteúdos e ícones ausentes falham
+antes de montar as consultas; apenas o painel ativo monta seu conteúdo.
+
+E-mails adota a composição document. Envios, Remetentes e Modelos mantêm seus componentes
+registrados, contratos, permissões, confirmações e formulários. Este passo declara a estrutura
+das abas, não converte os comportamentos específicos em uma linguagem de expressões.
+Testes verificam seleção, montagem do painel ativo, referências ausentes, ida e volta pela URL,
+links de formulários e ausência de controles administrativos para quem tem somente leitura.
+
+## Consolidação: páginas declarativas como destino
+
+A composição híbrida é uma etapa de migração, não o destino. E-mails deixa de registrar
+conteúdos opacos por aba: cada aba referencia outra Presentation. O host resolve navegação,
+área e permissões; a estrutura e as operações permanecem no artefato serializável.
+
+O protocolo recebe recursos finitos necessários ao comportamento existente: apresentação
+embutida, destino pai de rotas, exigência de permissão, condições de linha por comparação,
+confirmação específica, células textuais ou switch de action, lookups de formulário e formatos
+de view (texto, texto pré-formatado e HTML isolado). Não há eval, expressão JavaScript, import
+arbitrário ou handler serializado. HTML usa iframe sem permissões e CSP que bloqueia recursos
+externos, preservando a proteção da prévia anterior.
+
+O renderer reutiliza ActionList, ActionForm, ActionView, ActionTrigger e seus drivers. Condições
+visuais não concedem autorização; o servidor mantém os guards dos contratos. A seleção de abas
+e formulários por URL pertence ao host genérico. Formulários de edição preservam defaults do
+registro, ocultando campos conforme a metadata dos contratos. A recuperação por listagem mantém
+a limitação conhecida à primeira página, explicitando ausência ou falha de consulta.
+
+Critério de aceite: remover os quatro componentes específicos de E-mails sem movê-los para
+slots equivalentes. Testar artefato reconstruído de JSON, navegação, permissões, confirmação de
+risco de duplicidade, publicação, ativação, envio de teste e isolamento de HTML. Extensões
+runtime continuam admitidas para necessidades reais, com exceção explícita; não contam como
+migração completa de uma página.
+
+## Ampliação para Configurações — 18/10/2026
+
+A estrutura das demais configurações usa as mesmas seções, sem wrappers de página opacos.
+Controles próprios usam seções `content`; itens declaram associação acessível e posição do controle.
+Listas de actions podem usar adaptadores tipados, preservando filtros e células existentes.
+Cabeçalhos aceitam referências a dados dinâmicos, e a página transporta largura e layout.
+O painel de teste do agente ocupa uma coluna declarada, com rolagem independente do conteúdo.
+Abas podem referenciar tanto actions quanto seções; referências a componentes opacos continuam
+reprovadas nessa modalidade. Loading, falha e ausência podem substituir o corpo temporariamente.
+A autorização permanece nos contratos; as extensões não executam código vindo do JSON.
+
+## Arquivo autoral JSON e acesso — 18/10/2026
+
+Declarações podem residir em `presentations/*.json`, importadas por registros estáticos e validadas
+por `presentationSchema.parse`. O inventário de copy descobre esses arquivos e usa as mesmas regras
+semânticas das declarações TypeScript, preservando caminho, linha e hash do JSON. JSON inválido
+produz diagnóstico; não há execução de código ou resolução de imports a partir do documento.
+
+O renderer herda `requires` do contrato da action para o corpo, comandos, destinos e switches.
+A declaração pode adicionar uma restrição, mas não substituir a exigência do contrato. Uma lista
+de permissões usa alternativas, conforme a semântica de `requires` nas actions; lista vazia é
+inválida. Sem callback `can`, uma exigência explícita é negada. `canAccessPresentation` permite
+que o roteador consumidor confira essa mesma regra antes de buscar um registro por URL.
+
+A autorização efetiva continua em `authorize`. Condições de linha (`when`, como `canEdit` devolvido
+pelo servidor) complementam essa avaliação, sem presumir acesso a um registro apenas pela área.
+
+## Detalhe local de coleção — 18/10/2026
+
+Uma lista pode declarar `body.inspect` para abrir um detalhe especializado sem alterar a URL.
+Esse destino referencia um adaptador estático vinculado ao mesmo contrato da lista, recebe o item
+e um callback de fechamento. O renderer mantém a seleção e só monta o detalhe após o clique.
+É uma alternativa exclusiva a `open`/`opens`, que continuam responsáveis por destinos roteados.
+Permissão e condições de linha são verificadas ao abrir e ao renderizar; a autorização dos dados
+continua nas actions do detalhe. Registro ausente ou contrato incompatível falha antes da consulta.
+
+O caso atende transcrições de conversas e payloads de auditoria: conteúdos especializados legítimos,
+sem manter um wrapper por página para seleção, filtros ou estado de abertura. Não adiciona imports
+ou funções ao JSON nem converte um detalhe especializado em uma página opaca.
+
+## Opções de vínculos — 18/10/2026
+
+Lookups de formulário podem declarar opções estáticas anteriores às consultadas (como “Todas as
+unidades”) e um formatador de opção registrado e vinculado à list action. Isso preserva rótulos
+compostos e a indicação de cadastros inativos sem mover os formulários de volta para JSX. O JSON
+continua declarando campos, consultas, defaults, comandos e destinos. O formatador só projeta uma
+linha em opção; não busca dados nem executa commands. O renderer verifica registro/contrato antes
+de consultar e respeita o `requires` da action do lookup. Filtros iniciais de coleção usam a mesma
+API `filterDefaults` do ActionList e não sobrescrevem filtros explícitos da URL.
+
+A hidratação de detalhes roteados reutiliza `listStateToInput`, a mesma materialização que o
+ActionList usa para consultar. O host conserva canal, busca, ordenação e página ao abrir o formulário;
+a fonte de registro continua respeitando seu próprio contrato. Um link sem recorte ainda depende
+da página padrão da consulta, e o estado de ausência deve explicitar essa limitação.
+
+## Campos especializados — 18/10/2026
+
+`body.fieldComponents` associa campos de formulário a adaptadores registrados, vinculados à
+action e ao campo por `bindPresentationField`. O componente monta dentro de ActionForm e usa
+seu contexto; validação, envio, erros, footer e efeitos permanecem no formulário compartilhado.
+O registro rejeita campo inexistente, colisão com lookup e adaptador de outro contrato antes
+de montar controles. Não há imports nem funções no JSON.
+
+O primeiro consumidor é o questionário de motivos de perda: a estrutura variável das perguntas
+exige controles próprios, enquanto cadastro, edição, ativação e navegação seguem declarativos.
+Testes devem provar que o componente altera os dados submetidos, que o schema rejeita conteúdo
+inválido e que uma permissão negada impede a montagem do editor.
+
+Coleções com totais especializados declaram `body.beforeContent`, vinculado à list action por
+`bindPresentationListContent`. O adaptador recebe o input efetivo que ActionList materializa,
+incluindo período, filtros e escopo fixo. Assim, cartões de consumo podem consultar o resumo
+do período sem duplicar a montagem do recorte nem somar uma página da tabela. O conteúdo só
+monta depois do gate da coleção. Ausência ou incompatibilidade do adaptador falha antes da consulta.
+
+### Registro único e comandos de seção
+
+Uma Presentation pode declarar `source` com action `view` e bindings de entrada. O renderer
+carrega o registro, apresenta estados de leitura e disponibiliza o dado em `record`. A permissão
+da fonte é cumulativa com a da apresentação; acesso negado não consulta a fonte. Formulários
+endereçáveis declaram a mesma fonte e recebem os valores por bindings explícitos, preservando
+a lista de campos enviados. O cache do driver compartilha a leitura entre página e diálogo.
+
+Itens de seção podem declarar `value.field`, `empty` e `suffix`; `content` permanece reservado
+a controles específicos. Comandos com placement `section` são referenciados por action no
+campo `actions` da seção. Mensagens condicionais usam as condições finitas já existentes.
+Isso elimina wrappers de leitura/edição sem serializar funções nem enfraquecer autorização.
+
+A fonte também admite uma action list com seleção explícita por campo e parâmetro de rota,
+preservando o recorte e o limite do consumidor. Componentes registrados por
+`bindPresentationComponent` recebem input, contexto e controles de fechamento/aside; cada
+vínculo referencia um contrato existente e seu acesso é conferido antes da montagem.
+Não se executa o contrato só por registrar o componente. Uma operação simple de leitura pode
+abrir esse conteúdo; operações de escrita continuam executando pelo trigger.
+
+`formGroups` declara agrupamentos de campos. `initialValues` representa o rascunho inicial,
+que pode ainda ser inválido (por exemplo, nenhuma ferramenta selecionada); seus nomes são
+validados contra o contrato e o envio continua usando a validação de ActionForm. Bindings
+explícitos prevalecem sobre valores iniciais. Comandos de seção podem ter id próprio quando
+vários grupos abrem a mesma action, e nomes acessíveis preservam a distinção entre grupos.
+
+Rotas com registro podem declarar alternativas condicionais de mesma superfície, sem
+encadeamento, como a consulta de uma revisão da plataforma por um endereço legado de edição.
+O host verifica a permissão do destino e só então monta seu conteúdo. Fallbacks de criação
+exigem campos declarados e vêm exclusivamente da transição em memória, nunca da querystring.
+
+### Fontes externas, navegação e detalhes na busca
+
+A conta da pessoa continua sob responsabilidade do IdP. `externalSource` referencia um
+adaptador de leitura registrado pelo host; não cria uma action fictícia nem permite executar
+código no JSON. A leitura é local à montagem, cancela resultados obsoletos e respeita `requires`
+antes de iniciar. `source` e `externalSource` são mutuamente exclusivos. Campos vindos do IdP
+são conferidos pelo adaptador; não existe contrato Opus para inferir seu schema.
+
+`bindPresentationContent` registra controles de integrações externas sem atribuir-lhes um
+contrato inexistente. Formulários especializados podem declarar `body.footer`, recebendo o
+alvo do rodapé e o controle de ocupação da superfície; validação e persistência continuam
+no cliente oficial da integração. `links` declara navegação entre apresentações, sem simular
+uma operação de domínio. O destino também precisa passar pelo controle de acesso.
+
+Ações secundárias de seção usam `ghost`. Comandos e links podem declarar `icon`, uma
+referência ao registro de ícones do runtime, para ações reconhecíveis como editar. Nesse
+caso, o botão exibe somente o ícone e mantém o rótulo em tooltip e nome acessível. Links
+usam seu próprio `label`; comandos podem distinguir seções com `accessibleLabel`.
+Ações que precisam de texto para explicar o efeito conservam o rótulo visível. A escolha
+é explícita na definição, sem inferir ícones pelo texto nem alterar ações primárias.
+
+`route.query` identifica detalhes que compartilham o caminho da coleção. A seleção recebe
+um nome de parâmetro público e um nome de input; o host conserva os filtros ao abrir e retira
+somente a seleção ao fechar. Rotas de abas aceitam os mesmos parâmetros de caminho da página.
+A assistência recebe o contexto já carregado e não oferece seu botão durante a carga ou recusa.
+
+Atualizações de uma fonte já carregada não desmontam seu conteúdo. Consultas acompanhadas por
+SSE podem declarar `source.retainOnError` para conservar o último resultado e apresentar um
+aviso próprio. Isso não permite reutilizar um registro de outra chave nem libera comandos
+quando o monitoramento ou a consulta falhar.
+
+
+## Consolidação local: listas, canvas e fontes
+
+### Coleções completas sem paginação
+
+ActionList passa a respeitar `paginate: false`, já declarado no contrato ListAction.
+Nesse modo não envia `page`/`limit`, ignora paginação legada da URL, não mostra rodapé
+nem seletor de quantidade e preserva busca, ordenação, estados e recarga. O handler
+precisa retornar o recorte completo; aumentar artificialmente o limite ou apenas
+esconder o paginador foi descartado porque pode tornar registros inacessíveis.
+O modo omitido, cursor ou offset conserva o comportamento anterior. Não há uma segunda
+opção visual divergente no JSON de Presentation: a action é a fonte da decisão.
+
+### Recarga manual da lista
+
+O ActionList não apresenta comando de recarga manual na toolbar nem em `Opções da lista`.
+Invalidations de mutations e eventos do consumidor continuam atualizando os resultados;
+o estado de erro mantém `Tentar novamente`. Não se adiciona polling genérico.
+O menu reúne somente preferências e não aparece quando não há opções aplicáveis.
+ActionFilterBar isolado conserva seu `onRefresh` explícito, sem mudar consumidores próprios.
+
+### Protótipo de catálogo de habilidades
+
+`body.collection` referencia um renderer de coleção vinculado à action da lista. Ele recebe
+os itens da página atual, recarga, abertura governada e ações declaradas por item. A consulta,
+busca, paginação, estados e toolbar continuam no ActionList; permissões e destinos permanecem
+no JSON. Isso projeta o slot `children` já existente, evitando uma segunda listagem ou
+callbacks de navegação duplicados no consumidor. O renderer desenha apenas os resultados.
+
+O primeiro consumidor agrupa cards de habilidades por uma configuração visual local.
+Essas categorias não alteram o domínio nem a seleção feita pela IA. O agrupamento abrange
+somente a página carregada; não promete totais globais por categoria. Testes devem preservar
+destinos autorizados, comandos, busca e estados de lista.
+
+O renderer admite `body.rowContent` e `body.toolbarContent`, vinculados à mesma list action
+por adaptadores tipados. A linha personalizada convive com comandos declarados; não substitui
+paginação, filtro ou estado do ActionList. Referências ausentes ou de outra action falham antes
+da consulta. `successMessage` pertence ao comando e só é emitida após sucesso.
+
+Regiões content podem declarar `layout: fill` para ocupar a altura restante sem depender de uma
+lista. O elo registra a folha na cadeia de altura e interrompe sua propagação ao conteúdo próprio.
+`page.flush` permite conteúdo com recuo próprio. Abas embedded mantêm o contexto Tabs; framed e
+distribution são encaminhados à primitiva. Drawer respeita width wide, com expansão do assistente.
+
+Rotas aceitam parâmetros finitos e seletores compostos de busca. Restrições valem no matching e
+na geração de URL; nomes e bindings repetidos são inválidos. Fonte externa é identificada também
+pelo adaptador, não apenas pela chave de rota. Refetch de uma view não desmonta conteúdo já lido.
+
+Links com ícone podem declarar `showLabel: true` para manter o rótulo visível, usando
+o tamanho textual do botão e sem tooltip redundante. O padrão dos links com ícone
+continua sendo somente ícone, com rótulo acessível e tooltip.

package/docs/adr/README.md

@@ -16,3 +16,11 @@ estar documentado na superfície correspondente, sem exigir a reconstrução des
 - [ADR 0060 — Composição de superfícies com cabeçalho e intro](0060-surface-composition-separates-chrome-and-intro.md).
 
 - [ADR 0061 — O `CLAUDE.md` importa o `AGENTS.md`](0061-claude-md-imports-agents-md.md).
+
+- [ADR 0062 — Listas contidas e texto flexível](0062-listas-contidas-e-texto-flexivel.md).
+
+- [ADR 0063 — Metadados das superfícies em região própria](0063-metadados-das-superficies.md).
+
+- [ADR 0064 — ActionList apresenta itens e conecta fontes externas](0064-action-list-com-itens-e-fontes-externas.md).
+
+- [ADR 0065 — Presentation compõe seções declaradas](0065-presentation-composes-settings-sections.md).

package/package.json

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

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

@@ -43,31 +43,33 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 7. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh. Em `Presentation`, declarar `route`
    no artefato e deixar o adaptador apenas conectar a spec ao router da aplicação.
-8. Compor Page, Dialog e Drawer pela mesma gramática: no formato compacto, título e orientação
-   ficam no Header; com Intro, navegação e ações da superfície ficam no Header e a Intro abre o
-   Body com título, orientação e ações locais em IntroActions. Declarar a escolha pelos slots,
-   sem prop redundante. Usar PageIntro na Page explícita; a forma curta de Page já coloca title e
-   description na intro e actions no header. Não misturar shorthand com regiões explícitas.
-   Manter exatamente um heading principal, inclusive quando Surface level={1} nomeia uma coleção
-   ou PageState substitui a página. PageShell fornece contexto sem criar barra paralela; header
-   sem controles não reserva espaço. Preservar o teto de 80rem e separar composição de ocupação
-   de altura (flow/fill). Surface mantém o cabeçalho do conteúdo; Pane distribui espaço e recebe
-   uma superfície quando precisar de anatomia visual. Não criar Intro nem controles de navegação
-   artificiais para Surface ou Pane.
-   Em `Surface framed`, usar `layout="sectioned"` e `SurfaceBody flush` quando o filho direto já
-   controlar o recuo do body, como `DetailGroup` com divisores, lista ou tabela; não reconstruir
-   divisor, padding ou recorte por classes no consumidor. Em grupos de formulário,
-   `as="fieldset"` transforma o header em `legend` nativa sem variante visual paralela.
+8. Compor Page, Dialog, Drawer e Surface pela mesma anatomia: título, descrição opcional,
+   metadados e ações gerais no Header; conteúdo no Body; decisões no Footer. Não existem
+   `compact`, `sectioned`, `surfaceLayout`, `*Intro` nem a escolha visual `layout` nesses roots.
+   Preservar exatamente um heading principal. Page usa uma coluna aberta, padding de `2.5rem`
+   e título de `1.875rem`, sem divisores entre regiões. `width` limita a coluna; omitido, ocupa a
+   largura disponível. `Page.layout="flow"` rola a página inteira; `fill` mantém o header visível
+   e entrega a altura restante à lista ou à rolagem do body. Não oferecer `composition`.
+   PageBack recebe destino pai explícito e aparece como primeira ação de ícone no Header.
+   Não criar barra de breadcrumb. PageShell fornece ações sem barra paralela.
+   Headers usam botões `default`/`icon` e linha mínima de `2.25rem`. Regiões delimitadas têm recuo
+   de `1rem`, e bodies governam o ritmo vertical de `1rem`. Divisores são automáticos entre
+   regiões existentes. Surface sem moldura se alinha ao hospedeiro, sem recuo lateral ou inferior.
+   Usar `flush` quando o filho já controla o recuo; não reconstruir padding ou divisores na tela.
+   `tabs` integra a navegação ao Header; ações da coleção ficam em `ActionList.toolbarActions`
+   dentro do painel ativo. Pane distribui espaço e recebe Surface quando precisar de anatomia.
+   `Surface as="fieldset"` mantém legend nativa na faixa do cabeçalho, sem variante de moldura.
 9. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
 10. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
     responsáveis por `font-size` em `html`; medidas escaláveis da UI usam `rem` ou a escala
     relativa do Tailwind. Reservar `px` a hairlines e compensações presas à geometria da borda,
     com justificativa e cobertura explícitas.
-11. Em uma página centrada em coleção, compor `Surface + ActionList`: título e criação ficam em
-    extremos opostos do `SurfaceHeader`; a criação usa botão textual `default`, sem ícone, com
-    `Criar recurso`. Busca, filtros, atualização, estados e paginação permanecem no `ActionList`.
-    Reservar `toolbarActions` a operações ligadas ao recorte atual.
+11. Em uma página centrada em coleção, compor `Page + ActionList`; usar `Surface` para uma coleção
+    subordinada. Manter criação, importação e exportação em `ActionList.toolbarActions`, junto
+    de busca e filtros. Reservar ações do header à página ou superfície como um todo.
+    Usar botão textual normal, sem ícone, com `Criar`; preservar `Criar recurso` no nome acessível
+    e no título do formulário. Manter nomes específicos em menus com vários tipos de criação.
 12. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
 13. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
     `bg-card text-card-foreground` e `bg-popover text-popover-foreground`. Não depender da

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

@@ -4,13 +4,13 @@
 - Não dispara: “Ajuste o CSS de um e-mail estático.”
 - Execução: implementar uma lista com modal roteável e provar loading, erro, vazio e back.
 - Execução estrutural: montar uma página de relatório isolada com `Page > PageHeader + PageBody`,
-  outra em `PageShell` com navegação contextual acima de `Page > PageHeader + PageBody`, garantindo
+  outra em `PageShell` com ações contextuais no `PageHeader`, garantindo
   exatamente um `PageTitle` no header, e uma coleção nomeada com
   `Surface > SurfaceHeader + SurfaceBody > ActionList`. Provar que criação fica em
-  `SurfaceActions`, no extremo oposto ao título, como botão textual `default` sem ícone e com
-  `Criar recurso`, enquanto uma operação dependente do recorte usa `toolbarActions`; incluir
+  `ActionList.toolbarActions`, junto das operações do recorte, como botão textual normal sem ícone
+  com `Criar`, nome acessível `Criar recurso` e formulário com título específico; incluir
   `ActionFilterBar` separado do renderer, `ItemGroup` para
-  uma coleção secundária e um `ActionFormDialog`; provar teto padrão de `80rem`, hierarquia por
+  uma coleção secundária e um `ActionFormDialog`; provar ocupação de toda a largura e scroll somente no body, hierarquia por
   `level`, vazio estrutural sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento
   inferido e footer modal com largura natural, alinhado à direita e cancelamento `ghost`; incluir
   separadamente um caso deliberadamente equivalente com distribuição 50/50 e cancelamento
@@ -22,7 +22,7 @@
   rejeita a mistura entre props abreviadas e headers explícitos.
 - Execução de forma: compor uma tabela dentro de `Surface` sem moldura duplicada, manter a moldura
   estrutural standalone em `rounded-lg` e os controles internos em `rounded-md`.
-- Execução de Surface seccionada: compor `Surface framed layout="sectioned"` com mídia e
+- Execução de Surface: compor `Surface framed` com mídia e
   `DetailGroup` com divisores; provar header com divisor, `SurfaceBody flush` sem recuo e ausência
   de classes no consumidor que reconstruam essa anatomia. Provar `as="fieldset"` com `legend`
   nativa sem `frameVariant`.
@@ -79,8 +79,19 @@ da label, duplicação entre hint/help e perda de `aria-describedby` quando apar
 
 - Gatilho positivo: “Monte o detalhe de um recurso com menu da página separado do título.”
 - Gatilho negativo: “Explique por que a ADR antiga juntava título e ações”, sem pedido de UI.
-- Execução: montar o mesmo detalhe em Page, Dialog e Drawer com header de navegação/ações e intro
-  abrindo o body; montar também a versão compacta sem intro. Provar título único, ações locais em
-  IntroActions, nenhum header vazio na Page e transição de loading para conteúdo sem título duplicado.
-- Reprovar intro depois de texto, título simultâneo em header e intro, ações da superfície no título
-  ou adaptação de Pane para que ele volte a possuir anatomia visual.
+- Execução: montar o mesmo detalhe em Page, Dialog e Drawer com título e ações gerais no Header;
+  provar um único título, linha mínima de `2.25rem`, botões normais e transição de loading para
+  conteúdo sem duplicação. Page usa coluna aberta com padding de `2.5rem`, título de `1.875rem`,
+  largura independente e rolagem flow/fill; Drawer e Dialog preservam recuo de `1rem` e divisores. Conferir tabs nativas e operações
+  de coleção dentro do painel ativo, junto à listagem.
+- Reprovar `*Intro`, `compact`, `sectioned`, `surfaceLayout`, `tabsActions`, layout visual e
+  PageNavigation. Conferir que o checker orienta a migração. Não recriar anatomia em Pane.
+
+## Metadados e contadores
+
+- Execução: compor um detalhe com título, descrição e badges em PageMeta, DrawerMeta e DialogMeta;
+  conferir a faixa separada no Header. Em Surface, conferir que SurfaceCount
+  fica na linha do título e SurfaceMeta abaixo dela. Migrar um contador antigo e uma descrição
+  antiga sem alterar suas funções; provar a equivalência das formas curtas com `meta`.
+- Reprova: contador em SurfaceMeta, metadados em Description, dois Meta, Meta sem título,
+  Meta em fieldset ou DialogMeta em alerta.

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

@@ -7,25 +7,21 @@
 - Uma `Presentation` que representa esse estado declara `route.path` e `route.surface`. Rotas com
   parâmetro podem declarar `route.record` para hidratar o item a partir de uma Presentation de
   lista; não reconstruir essa decisão com condicionais no componente da página.
-- `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
-  explícita exige `PageBody`, exatamente um heading principal e aceita `PageHeader` e `PageFooter`.
-  Declare esse heading com PageTitle na PageIntro ou no PageHeader compacto, Surface level={1}
-  ou PageState ativo. A intro abre o body; ações locais usam PageIntroActions, enquanto PageActions
-  pertence ao header. A forma curta coloca title/description na intro e actions no header.
-  Não misturar as duas formas. Para ajustar a largura interna, usar contentClassName; className pertence ao container externo.
-- Na composição com intro, PageHeader reúne navegação contextual e ações da superfície na mesma
-  linha. PageBack recebe o destino pai explícito; para vários ancestrais relevantes, usar Breadcrumb
-  em PageNavigation. Não combinar retorno e breadcrumb, nem criar chrome paralelo. Na composição
-  compacta, título e orientação permanecem no header. PageActionsTarget fica reservado a workspaces
-  imersivos com chrome próprio.
-- Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
-  O shell entrega navegação e ações ao `PageHeader` descendente sem criar uma barra visual.
-  Ações com texto no cabeçalho usam `sm`, e ações somente com ícone usam `icon-sm`.
-  Ações de footer de Dialog e Drawer conservam `default`. 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. Em uma coleção, a ação de
-  criar usa botão textual `sm`, sem ícone, no extremo oposto do `SurfaceHeader`. Não monte
-  cabeçalho paralelo, portal ou seletor global para reconstruir essa composição.
+- `Page` fornece o `<main>` e a coluna com largura `narrow`, `default` ou `wide` (padrão). Sua forma explícita usa
+  `PageHeader` com `PageTitle`, `PageBody` e `PageFooter` opcional. A forma curta produz a mesma
+  anatomia; não misturar props abreviadas com slots explícitos. PageState ativo assume o título.
+- Page, Dialog, Drawer e Surface têm Header com título, descrição opcional, metadados e ações
+  gerais, Body com ritmo de `1rem` e Footer opcional. Não há `*Intro`, `compact`, `sectioned` ou
+  escolha visual de layout. `Page.layout` preserva somente a ocupação `flow`/`fill`.
+- Page tem uma aparência aberta, padding de `2.5rem` e título de `1.875rem`, sem divisores.
+  `flow` rola a página inteira; `fill` entrega a altura restante à lista ou ao body.
+  PageBack usa o destino pai e aparece como
+  primeira ação de ícone. PageShell entrega ações sem criar barra paralela; breadcrumbs
+  não fazem parte da composição. PageActionsTarget atende workspaces com chrome próprio.
+- Headers usam botões `default`/`icon` e linha mínima de `2.25rem`. Regiões delimitadas
+  de Drawer, Dialog e Surface conservam recuo de `1rem` e divisores automáticos. Surface sem moldura permanece
+  alinhada ao hospedeiro. A prop `tabs` integra a navegação ao Header; operações da coleção ficam
+  em `ActionList.toolbarActions` no painel ativo. Não reconstruir isso por portais ou seletores.
 - `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
@@ -36,18 +32,27 @@
   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.
 - `Surface` delimita uma região e segue a anatomia `Surface > SurfaceHeader (SurfaceMedia,
-SurfaceTitle, SurfaceDescription, SurfaceMeta, SurfaceActions) + SurfaceBody + SurfaceFooter`.
-  Os slots nunca ficam soltos. `title`, `description`, `count`, `media` e `actions` são a abreviação
-  para o caso direto e não podem ser misturados ao header explícito. Em `level={1}`, ações da
-  coleção ficam no extremo oposto ao título; a criação usa botão textual `sm`, sem ícone, com
-  `Criar recurso`.
+SurfaceTitle, SurfaceCount, SurfaceDescription, SurfaceMeta, SurfaceActions) + SurfaceBody + SurfaceFooter`.
+  Os slots nunca ficam soltos. `title`, `description`, `count`, `meta`, `media` e `actions` são a abreviação
+  para o caso direto e não podem ser misturados ao header explícito. Ações do header pertencem à
+  superfície como um todo; operações da coleção ficam em `ActionList.toolbarActions`.
   O diálogo de criação usa `Criar recurso` e o de edição, `Editar recurso`. `level` preserva a
-  hierarquia semântica do heading. `Surface framed` aceita `layout="sectioned"`; declare
+  hierarquia semântica do heading. Declare
   `SurfaceBody flush` quando o filho direto já possui recuo interno, como `DetailGroup` com
   divisores, lista ou tabela. `as="fieldset"` cria a `legend` nativa sem variante de moldura.
-- Uma página centrada em coleção compõe `Surface + ActionList`. O `SurfaceHeader` recebe título e
-  criação; o `ActionList` mantém busca, filtros, atualização, resultados, estados e paginação.
-  `toolbarActions` fica reservado a operações que dependem do recorte atual.
+- `PageMeta`, `DialogMeta` e `DrawerMeta` recebem badges, datas e autoria em faixa própria
+  após título, descrição e ações, dentro do Header da mesma família.
+  `SurfaceMeta` ocupa essa faixa em `SurfaceHeader`; `SurfaceCount` mantém o contador na linha
+  do título. Ao migrar, conferir manualmente os antigos `SurfaceMeta`: contadores passam a
+  `SurfaceCount`, frases de orientação a `SurfaceDescription`, e metadados permanecem em Meta.
+  Cada composição aceita um Meta e exige título. Page e Surface aceitam `meta` na forma curta;
+  fieldset e Dialog em `mode="alert"` não aceitam Meta. Informações necessárias à decisão
+  permanecem no corpo ou junto à ação correspondente.
+- Uma página centrada em coleção compõe `Page + ActionList`; coleções subordinadas podem usar
+  `Surface`. Criação, importação e exportação ficam em `toolbarActions`, junto de busca e filtros.
+  O botão de criação é textual normal, sem ícone, com `Criar` e nome acessível `Criar recurso`.
+  Menus com vários tipos de criação preservam os nomes específicos. Operações de seleção usam
+  `batchActions`, e operações individuais usam `rowActions`.
 - `Surface` e Drawer nomeiam a região principal como `SurfaceBody` e `DrawerBody`. `Pane` é apenas
   uma unidade dimensionável de `Split` e não possui anatomia interna. `*Content` permanece
   reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma estrutura, como