@softize/opus 30.0.0 → 31.1.0

package/docs/adr/0043-neutral-surfaces-and-interactions-use-opaque-role-tokens.md

@@ -71,3 +71,55 @@ distinguíveis e voltariam a depender de modifiers locais.
 - primitives neutras usam os mesmos tokens em light e dark, sem receitas locais equivalentes;
 - testes cobrem a projeção dos tokens e os estados de tabela, toggle, menu e navegação lateral;
 - a aplicação consumidora é compilada e verificada em páginas com canvas, card, formulário e grid.
+
+## Calibração da navegação — 2026-10-20
+
+O fundo `muted` opaco distingue a sidebar no claro, mas dá peso excessivo a essa área extensa
+no escuro. `sidebar` passa a representar a superfície de navegação, com `foreground` para o
+texto: usa `muted` no claro e `control` no escuro, acompanhando os eixos de aparência existentes.
+Os consumidores usam `bg-sidebar`, sem transparência nem ramificações locais por tema.
+
+Recalibrar `muted` globalmente alteraria também botões e fundos discretos já aprovados. Manter
+receitas `dark:` nos consumidores duplicaria a decisão. O alias semântico permite ajustar a
+navegação independentemente, sem introduzir outro controle de aparência ou mudar o fundo padrão
+da primitive Sidebar. Os testes de aparência incluem o novo papel nas verificações de contraste
+do texto, e a aplicação verifica as sidebars de Configurações e dos recursos nos dois temas.
+
+## Canvas branco no claro — 2026-10-20
+
+O preset claro passa a usar branco puro em canvas, controles, cards e popovers. A calibração
+quase branca anterior separava pouco as superfícies e ainda deixava o fundo geral acinzentado.
+Bordas, espaçamento e elevação continuam distinguindo as regiões; a sidebar mantém seu tom
+próprio. Esta decisão substitui a exigência de diferença de luminosidade entre essas superfícies
+no preset claro. Estados de interação, bordas e tema escuro preservam os valores calibrados.
+
+Com o canvas branco, a sidebar clara é recalibrada para luminosidade de 95% no preset,
+1,5 ponto abaixo de `muted`. Isso reforça a separação da navegação sem alterar os estados
+neutros globais. O token escuro continua no degrau de `control`.
+
+## Navegação interna — referência visual de 19/10/2026
+
+A referência fornecida distingue barra global, navegação interna e conteúdo. A calibração
+adotada cobre a navegação interna, quase branca (`#fcfcfc`), sobre conteúdo branco. O fundo da
+sidebar geral permanece como estava, por decisão explícita do produto. `sidebar` fica um ponto
+abaixo do canvas no claro e no degrau de `control` no escuro. Isso substitui a calibração clara
+de 95% acima.
+
+No preset claro, a seleção usa `#f0f0f0`. Hover usa um degrau intermediário (`#f4f4f4`) e pressão
+um degrau mais definido (`#e8e8e8`), pois esses estados não estão demonstrados na referência.
+Os tokens de interação continuam compartilhados entre os componentes. O escuro não muda.
+Os testes verificam as superfícies e os estados em conjunto, inclusive a leitura do texto.
+
+## Calibração escura — referência visual de 19/10/2026
+
+A referência escura usa conteúdo `#181818`, navegação interna `#1d1d1d`, seleção `#2f2f2f`
+e borda `#363636`. O canvas sobe para 9,4% de luminosidade no preset; a camada elevada fica
+em 11,4% e o controle em 10,4%. A sidebar interna acompanha a camada elevada. Muted, hover,
+seleção e pressão preservam os valores do preset escuro já calibrados.
+
+A primeira calibração preservou a base anterior da navegação global. Na validação seguinte,
+o produto definiu que a sidebar geral deve parecer contínua com o fundo, como no light.
+`sidebar-global` passa a acompanhar `background` nos dois temas. O fundo permanece opaco:
+a continuidade vem da igualdade de cor, sem depender de composição alpha. A navegação interna
+mantém seu papel distinto. A primitive Sidebar não impõe fundo; o hospedeiro escolhe o token.
+Os testes cobrem os valores, contraste do texto e a aplicação dos papéis nas duas regiões.

package/docs/adr/0044-neutral-appearance-derives-from-bounded-axes-per-mode.md

@@ -35,8 +35,11 @@ declara os presets dos dois modos e usa as entradas claras; `.dark` troca para a
 aplicação pode gravar os dois conjuntos no mesmo elemento, e alternar o tema não exige reaplicar
 nada.
 
-Com os eixos no preset, a derivação reproduz exatamente os valores calibrados pela ADR 0043. Quem
-não personaliza não percebe diferença.
+Na adoção inicial, os presets reproduziam os valores calibrados pela ADR 0043. A calibração de
+19/10/2026 reforça fundos discretos, estados e bordas no claro, separa `muted` de hover no escuro
+e reforça as bordas escuras. A escala continua opaca e o zero continua sendo o piso: os valores
+salvos dos quatro eixos são preservados, mas passam a atuar sobre a nova calibração. Os valores
+de referência atuais estão em `tests/ui/appearance-tuning.test.ts`.
 
 ### Limites
 
@@ -131,3 +134,25 @@ com os primitives existentes.
   opacos nos dois temas;
 - a aplicação consumidora verifica visualmente os extremos de cada eixo em páginas com canvas,
   card, formulário e grid, nos dois modos.
+
+## Ajuste do preset claro — 2026-10-20
+
+Canvas e controle passam a branco puro, acompanhando cards e popovers (emenda da ADR 0043).
+A separação inicial entre essas superfícies é zero no claro; o eixo de camadas continua podendo
+ampliá-la. A base dos estados neutros permanece um ponto abaixo do canvas para preservar a
+calibração de sidebar, muted, interação, borda e texto. O preset escuro permanece igual.
+
+## Calibração escura por referência — 19/10/2026
+
+O preset escuro passa a canvas de 9,4%, camada elevada de 11,4% e controle de 10,4%. A base
+mínima do canvas é 5,5%, em vez de preto puro; os eixos ainda só ampliam as separações a partir
+do preset. Os offsets de estado são compensados para manter muted, hover, seleção e pressão.
+Borda fica em 21%. `sidebar-global` acompanha o canvas nos dois temas, conforme a atualização da ADR 0043.
+
+## Redução proporcional do dark — 19/10/2026
+
+Após a calibração pela referência, as superfícies, linhas e estados neutros do dark recebem
+um fator final de 0,95 na luminosidade HSL. O fator é aplicado uma única vez na cor resultante,
+sem acumular redução entre canvas, controle e camada. A proporção entre esses valores é
+preservada; texto, primary, contextos semânticos e tema claro ficam inalterados. A calibração
+permanece interna ao tema, sem uma nova preferência pessoal.

package/docs/adr/0060-surface-composition-separates-chrome-and-intro.md

@@ -159,3 +159,145 @@ o título em uma composição inline com quebra, sem criar um novo slot estrutur
 
 `contentClassName` em Page e PageBody configura largura e alinhamento internos; `className`
 controla a moldura e o viewport, respectivamente. Presentation fora do shell preserva largura total.
+
+## Revisão de 16/10/2026 — Page com cabeçalho único
+
+A validação no consumidor Grand Brasil substitui o formato com intro de Page: título, ações
+e retorno pertencem ao header fixo; metadados vêm abaixo da linha principal. A Page ocupa
+a largura disponível, usa recuo de 2rem, título de 1,5rem, linha mínima de 2,25rem e ações
+`default`/`icon`. Regiões são sempre seccionadas. Drawer, Dialog e Surface mantêm as opções
+existentes e controles compactos. A separação entre `flow` e `fill` continua governando
+rolagem, sem alterar a anatomia.
+
+`PageBack` é uma ação de ícone com destino explícito e tooltip, primeira na região de ações.
+Breadcrumb não compõe a Page. A composição antiga de intro/navegação não é o caminho
+canônico e os consumidores devem migrar para PageHeader; Presentation gera a mesma estrutura.
+A alternativa de classes por consumidor foi descartada por repetir o contrato visual.
+Testes de Page, Presentation e anatomia cobrem medidas, heading único, retorno, estados
+integrais e preservação dos modais.
+
+Experimento local após a revisão: Page usa recuo de 1rem nas regiões, igual aos modais
+seccionados. O título também usa 1,125rem, como nos headers de Drawer e Dialog. As ações
+mantêm o tamanho normal de Page.
+
+Ajuste local seguinte: os cabeçalhos de Page, Drawer, Dialog e Surface compartilham
+ações `default`/`icon` e linha mínima de 2,25rem. O fechamento nativo dos modais usa
+a mesma escala; `closeSize` mantém as opções menores para composições explícitas.
+
+### Experimento de abas no cabeçalho
+
+Para manter a navegação entre painéis visível enquanto o corpo rola, os headers de
+Page, Drawer, Dialog e Surface aceitam `tabs`, contendo um `TabsList` do Tabs existente.
+A região entra abaixo da linha de título e ações, com o mesmo alinhamento lateral.
+O divisor inferior pertence ao header; a lista de abas não acrescenta outra linha.
+O estado, as relações ARIA e o teclado continuam no Tabs que envolve a superfície.
+
+Manter as abas no body exigiria repetir posicionamento e recuos em cada consumidor.
+Criar outro controlador duplicaria o contrato de Tabs. A região opcional no header
+é reversível e mantém a composição sem abas inalterada. Alertas e legendas de fieldset
+não aceitam essa navegação. O piloto é E-mails; testes verificam troca de painel,
+semântica, ausência de divisor duplicado e preservação da composição sem abas.
+
+O piloto separa ações gerais de ações da aba: `tabsActions` ocupa o extremo oposto
+a `tabs` na mesma faixa, sem participar do tablist. A região exige `tabs` e mantém
+os botões no fluxo normal de foco, com a mesma escala dos demais headers.
+
+### Ações das coleções
+
+Ações que afetam a coleção pertencem à toolbar do ActionList, inclusive criação,
+mesmo quando não dependem do recorte atual. Cabeçalhos preservam as ações gerais
+da superfície. Presentation ganha o placement explícito `toolbar`, válido apenas
+quando seu body declara uma action list; `header` continua significando o header.
+O comando pode declarar `label` para a apresentação contextual, sem renomear o
+contrato nem o formulário de destino. A criação pode assim exibir “Criar”. A validação
+rejeita toolbar em bodies sem lista, e o renderer deve manter header e toolbar distintos.
+
+## Consolidação de 18/10/2026 — anatomia única
+
+A validação da aplicação substitui a escolha entre composição compacta e intro por um
+cabeçalho único em Page, Dialog, Drawer e Surface. Título, descrição opcional, metadados e
+operações gerais pertencem ao Header; o Body contém o conteúdo. As exportações Intro e
+IntroActions dos modais são removidas, assim como `SurfaceLayout`, `surfaceLayout` da Page
+e `layout` visual de Surface, DialogContent e DrawerContent. Não há alias de compatibilidade.
+`Page.layout="flow" | "fill"` permanece: governa rolagem, não aparência.
+
+As regiões derivam seus divisores da vizinhança. Superfícies delimitadas usam recuo de 1rem
+em header, body e footer; a Surface sem moldura mantém alinhamento com o hospedeiro e ritmo
+de 1rem entre as regiões. A linha de cabeçalho reserva 2,25rem e ações usam tamanho normal.
+A semântica de alerta do Dialog continua própria: exige uma resposta e não é uma opção de
+densidade visual. Fieldset mantém legend nativa, em faixa quando delimitado.
+
+As abas pertencem ao header e os comandos de coleção à barra da lista. `tabsActions`, criado
+no experimento, é removido. Comandos de linha e seleção preservam seus slots. Exemplos,
+metadata, regras do checker e consumidores migram juntos; testes verificam API removida,
+regiões, foco, rolagem e criação contextual. Manter modos antigos foi descartado porque
+permitiria reintroduzir a divergência que motivou a revisão.
+
+A Surface sem moldura não acrescenta padding nem divisor entre regiões: o intervalo é
+1rem, alinhado ao hospedeiro. Fieldset sem moldura mantém legend sem sublinhado. Abas
+integradas conservam sua própria linha de seleção, encostada na base do Header.
+Surface nível 1 continua disponível fora da Page; dentro dela, seções são subordinadas
+e o título principal pertence ao PageHeader, ou ao PageState integral ativo.
+
+
+## Piloto: composição de documento
+
+A avaliação visual em Segurança reabre a escolha de composição sem reintroduzir Intro.
+`Page composition="document"` reúne Header, Body e Footer em uma coluna central de até
+56rem, com recuo externo de 1rem nas laterais e 2,5rem na vertical. A Page inteira rola
+na borda disponível; título e conteúdo seguem juntos, sem divisor entre as regiões.
+`composition="standard"` preserva o cabeçalho fixo e o corpo em toda a largura.
+A opção visual é independente de `layout`, que continua indicando ocupação; documento
+aceita somente `flow`, pois não delega rolagem a uma lista ou canvas interno.
+
+A Presentation encaminha `pageComposition` à Page que possui ou à Page do conteúdo.
+O piloto na aplicação fica restrito a Segurança, sem publicação nem propagação antes da
+avaliação visual. A escolha geral de divisores (`sectioned`) permanece em reavaliação;
+este piloto não restaura essa API nem altera Drawer e Dialog.
+
+## Experimento: largura independente da composição — 2026-10-18
+
+Preferências curtas precisam de uma coluna menor, enquanto tabelas precisam aproveitar a área
+central. A Page aceita `width="narrow" | "default" | "wide"`: limites de 42rem, 58rem ou toda a
+largura disponível. O limite envolve header, body e footer juntos, preservando seu alinhamento e
+padding. Sem largura explícita, documento conserva default e a composição standard conserva wide.
+A declaração serializável usa `page.width`; a prop width externa da Presentation continua exclusiva
+do dimensionamento de diálogos. A contribuição do shell repassa a largura à Page do consumidor.
+A alternativa de classes particulares por tela foi descartada para manter três escolhas revisáveis.
+Segurança e Conversas exercitam os extremos; E-mails conserva a largura intermediária.
+
+Na avaliação seguinte, a composição document passa a usar padding uniforme de 2,5rem.
+O limite da coluna continua incluindo esse padding. A composição standard preserva 1rem,
+assim como Drawer e Dialog; o recuo depende da composição, não da largura escolhida.
+
+## Correção: documento também pode preencher a altura — 2026-10-18
+
+Conversas revelou que a composição document não deve obrigar uma listagem a crescer na página.
+Ela passa a aceitar `layout="fill"`: mantém título, ausência de divisor e padding aberto, mas
+limita a coluna à altura disponível e entrega a rolagem aos resultados da ActionList. O padrão
+flow continua rolando título e conteúdo juntos. Isso substitui a restrição inicial do piloto;
+composição visual e ocupação de altura são escolhas independentes.
+
+## Consolidação: uma aparência de Page — 2026-10-18
+
+A avaliação concluiu que standard e document eram duas aparências para a mesma anatomia,
+sem usos distintos que justificassem a escolha em cada tela. A Page adota o visual aberto:
+padding de 2,5rem, título de 1,875rem, intervalo de 1,5rem após o cabeçalho e
+1rem entre as demais regiões, sem divisores. Removem-se composition,
+pageComposition e page.composition, sem aliases. Header, Body e Footer permanecem.
+
+Largura e ocupação continuam independentes: width narrow/default/wide e layout flow/fill.
+A largura omitida é wide, preservando o espaço das listagens existentes; os antigos documentos
+intermediários passam a declarar width default. Flow rola o conjunto; fill reserva altura para
+a região interna. Drawer e Dialog continuam delimitados, com seu padding de 1rem.
+A migração cobre consumidores e projeções; testes verificam herança da largura, fill e a anatomia
+única. Essa decisão substitui os dois tratamentos visuais dos experimentos anteriores.
+
+## Seções e cabeçalhos declarados em Configurações — 2026-10-18
+
+A adoção em toda a área de Configurações exige manter widgets com comportamento específico sem
+transferir a página inteira para body.component. Seções de conteúdo referenciam slots nomeados;
+seções de lista podem apresentar tabela ou itens por um adaptador tipado do contrato. Cabeçalho
+aceita referências a título dinâmico, metadados e ações, mantendo os slots nativos de cada superfície.
+Page.layout pode ser declarado junto de width. O runtime contém callbacks e dados, nunca código
+serializado. Referências ausentes falham antes da montagem; o JSON não aceita funções ou HTML.

package/docs/adr/0064-action-list-com-itens-e-fontes-externas.md

@@ -0,0 +1,47 @@
+# ADR 0064 — ActionList apresenta itens e conecta fontes externas
+
+- **Status:** experimental, piloto local em Segurança.
+- **Data:** 2026-10-18.
+
+## Contexto
+
+Coleções pequenas em Configurações usam ItemGroup com título, descrição e ações por item.
+ActionList já governa consulta, erro, vazio e paginação, mas exige uma função React para
+esse visual. Sessões pertencem ao IdP e não devem ganhar endpoint ou contrato de negócio
+paralelo apenas para reutilizar a lista.
+
+## Decisão
+
+ActionList recebe `item: { title, description? }`, cujos valores são nomes de campos do
+resultado. O objeto é serializável; a renderização usa ItemGroup, Item e separadores do
+catálogo. `rowActions` também atende itens. `title` nomeia a coleção e suas
+`toolbarActions` ficam junto dele; filtros continuam em sua própria barra quando existem.
+As ações podem receber contexto de resultados e refetch, sem uma consulta duplicada.
+Uma lista em itens esconde o rodapé quando há somente uma página, mas mantém o paginador
+quando há mais resultados. Tabelas e composições existentes conservam seu comportamento.
+
+A origem continua sendo uma action por padrão. A alternativa explícita `source` recebe
+uma chave de cache com escopo e um loader que retorna o envelope paginado. É um adaptador
+runtime de fonte externa, não uma action nem um endpoint. A consulta usa o mesmo mecanismo
+de cache e estados do driver. Fontes externas não mantêm cache após desmontar a lista e
+não herdam o transporte Opus. O adapter declara paginação real sobre o conjunto recebido;
+a UI nunca esconde registros para simular uma única página.
+
+No piloto, a fonte chama o cliente Better Auth existente e projeta somente identificador,
+nome do dispositivo e data formatada para a lista. Tokens ficam na closure do adapter para
+revogação, fora dos itens, do DOM, do cache da lista e de declarações JSON. Operações e
+permissões continuam no IdP. A fonte e callbacks não são serializáveis: a futura composição
+JSON deverá referenciá-los por registro, sem embutir funções ou credenciais.
+
+## Alternativas
+
+- Uma função children resolve o visual hoje, mas repete anatomia e impede declarar os campos.
+- Uma action de sessões paralela duplicaria a fronteira de autenticação.
+- Uma coleção inteiramente nova repetiria estados, paginação e invalidação do ActionList.
+
+## Verificação
+
+Testar consulta por action e fonte externa, estado inicial, erro e recuperação, vazio,
+ações por item, atualização, paginação e remoção na última página. No piloto, testar
+revogação com o cliente do IdP simulado e inspecionar o visual na rota real sem encerrar
+sessões de outras pessoas. O modo de tabela mantém suas regressões existentes.

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/0066-civil-date-input-and-calendar-list.md

@@ -0,0 +1,28 @@
+# ADR 0066 — Datas civis e calendário mensal na lista
+
+- **Status:** aceita para consolidação; publicação é uma etapa separada.
+- **Data:** 2026-10-22.
+
+## Contexto
+
+A gestão de expediente precisa escolher datas sem conversão de fuso e consultar um mês inteiro junto dos filtros de unidade e equipe. O input nativo varia entre navegadores, e uma grade implementada em cada consumidor repetiria navegação e acessibilidade. A experimentação no consumidor Grand Brasil validou a composição antes da consolidação desta API.
+
+## Decisão
+
+`DateInput` compõe Input, Popover e Calendar. Aceita digitação com máscara `DD/MM/AAAA`, colagem ISO e seleção por calendário; datas válidas são emitidas como `AAAA-MM-DD`. Entradas incompletas ou impossíveis permanecem visíveis e são emitidas sem convertê-las numa data válida, para o contrato poder rejeitá-las. O campo recebe foco; o ícone é um adorno. Clique abre o picker sem impedir digitação, Alt+Seta para baixo transfere o foco, e Escape fecha somente o popover. O renderer de `ActionForm` reconhece `widget: 'date'`, preservando controle, reset, validação e acessibilidade do formulário.
+
+`ActionList` e `ActionFilterBar` recebem `periodControl?: ReactNode`. A extensão substitui o seletor padrão no mesmo espaço, respeitando `periodPosition` e a composição com `period.basisFilter`. O consumidor controla o valor temporal e seu estado navegável. Com periodControl, ActionList ignora o preset padrão e os valores period/from/to do estado; somente o input fornecido pelo consumidor define o intervalo. O helper listStateToInput aceita applyPeriod: false para reproduzir esse recorte em detalhes roteados. Sem a propriedade, a API anterior mantém seu comportamento.
+
+`CalendarMonthView<TItem>` é uma visualização, consumida por `ActionList.views`. Recebe mês civil, itens, extração de data, conteúdo, nome acessível e ação por dia. Gera todas as datas do mês e agrupa os itens. A navegação usa setas, Home e End, com uma única parada de Tab. Consulta, filtros, loading, erro e vazio continuam pertencendo à lista. Regras de expediente e feriados ficam no domínio consumidor. A grade é separada do DayPicker por representar uma coleção com conteúdo e ação próprios em cada dia, sem modelo de seleção de datas. Adaptar os botões e o estado de seleção do DayPicker duplicaria essa semântica; a exceção preserva teclado e roles de grid sem copiar a primitiva. A primeira versão usa cabeçalhos em pt-BR e semanas iniciadas no domingo, explicitados na documentação.
+
+O Calendar compartilhado apresenta o mês com inicial maiúscula e barra antes do ano, preservando os formatters customizados. A raiz estável evita perder foco ao renderizar novamente. Dias selecionados usam o par de cores do botão primário sólido, incluindo as extremidades de intervalos.
+
+## Alternativas e consequências
+
+O input nativo foi experimentado e descartado pela inconsistência com os outros campos. Converter datas civis para timestamps criaria dependência de fuso sem necessidade. Copiar a barra de filtros ou inserir um calendário com consulta própria duplicaria responsabilidades já cobertas por ActionList.
+
+As extensões são aditivas. A mudança de legenda e de contraste alcança todos os consumidores do Calendar, portanto inclui regressão do modo de intervalo e dos formatters. Mês inválido em CalendarMonthView é erro de programação; consumidores validam sua entrada antes de renderizar.
+
+## Verificação
+
+Testes de DateInput cobrem máscara, cursor, teclado, datas inválidas, reset e integração com ActionForm. Testes da lista cobrem posicionamento do período e grade com navegação. Testes de Calendar cobrem identidade da raiz, formatter e seleção. Os gates da release incluem tipagem, suíte completa, Chromium e instalação de um consumidor a partir do tarball.

package/docs/adr/README.md

@@ -20,3 +20,9 @@ estar documentado na superfície correspondente, sem exigir a reconstrução des
 - [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).
+
+- [ADR 0066 — Datas civis e calendário mensal na lista](0066-civil-date-input-and-calendar-list.md).

package/package.json

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