@softize/opus 22.1.0 → 23.0.0

package/CHANGELOG.md

@@ -7,6 +7,79 @@ 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.
 
+## 23.0.0 — 2026-09-29
+
+Esta major conclui a separação entre contrato e dados de design, simplifica a hierarquia de
+`Content` e dá a Tabs uma anatomia pública única para navegação. A seção **Breaking** reúne as
+migrações obrigatórias.
+
+### Breaking
+
+`mockHandler` foi removido de `ActionBase`, contratos, actions de lista, runtime e `runAction`,
+concluindo a ADR 0037. O core não lê mais `OPUS_MODE`: o plugin `opusDesign()` liga cenários ou
+respostas geradas como handlers antes de registrar as actions no runtime. Migração: remova cada
+`mockHandler`; quando a resposta específica importar para o design, transforme-a em cenário com
+`defineDesignScenario`. Testes devem passar a action produzida por `bindAction` ao `runAction`.
+
+Filtros `select` de escolha única aceitam `presentation: "toggle"` para manter opções curtas e
+mutuamente exclusivas visíveis em um grupo conectado. A apresentação padrão continua sendo
+`Select`; estado, URL, defaults e input da action não mudam. Opções vindas de dicionário também
+apresentam o ícone declarado na entrada, sempre acompanhado pelo rótulo.
+
+`TabsList` passa a usar somente a linha de navegação e deixa de aceitar `variant`. Migração: remova
+`variant="line"`; usos da antiga superfície preenchida devem representar escolha de valor com
+`ToggleGroup`, usando `variant="outline"` quando precisarem de borda.
+
+A anatomia pública de Tabs passa a nomear estrutura, não o mecanismo da primitiva:
+`TabsTrigger` vira `TabsListItem` e `TabsContent` vira `TabsPanel`. A mudança não mantém aliases;
+consumidores devem atualizar imports e JSX no mesmo upgrade.
+
+`Content` deixa de aceitar `variant="page" | "section"`. `level={1}` identifica o conteúdo
+principal, aplica automaticamente a escala de `PageHeader` e usa o mesmo intervalo de `1.5rem`
+entre header e body; níveis de 2 a 6 preservam a apresentação compacta de seção. Migração: remova
+`variant="page"` e mantenha `level={1}`. Não existe substituição para `variant="section"`, que era
+o comportamento dos níveis internos.
+
+### Filtros e controles
+
+`Toggle` e `ToggleGroupItem` em `variant="outline"` preservam a borda no estado ativo e usam um
+fundo sutil distinto dela, inclusive no tema escuro.
+
+## 22.2.0 — 2026-09-29
+
+As actions passam a declarar o que fazem com os dados (ADR 0041). Dois campos novos no contrato,
+ambos opcionais nesta versão:
+
+- **`effect: 'read' | 'write'`** diz se a action só lê ou altera estado. `list` e `view` já são
+  leitura, porque são servidas por `GET`, e não declaram; declarar `effect: 'write'` nelas é recusado
+  ao registrar a action (`runtime.invalid_action_effect`) e apontado pelo `opus check`. `simple` e
+  `form` declaram.
+- **`personalData: boolean`** diz se a resposta contém dados que identificam pessoas.
+
+Com os dois declarados, o runtime:
+
+- marca no `AuditRecord` toda execução bem-sucedida de action com `personalData: true`
+  (`personalData: { records }`, com a quantidade devolvida) e registra `effect`, qualquer que seja o
+  consumidor. Com `audit: false`, a exposição ainda gera um registro mínimo, sem entrada nem saída
+  (`meta.exposureOnly`). Execução com erro, enfileiramento em segundo plano e resposta simulada do
+  modo design não são marcados;
+- acrescenta `opus.action.effect` e `opus.action.personal_data` aos atributos do span;
+- projeta `effect` e `personalData` no manifest;
+- publica nas ferramentas de IA (`runtime.aiTools()`) e no `ListTools` do MCP as anotações
+  `readOnlyHint` e `destructiveHint` (numa escrita, sempre explícito, porque o MCP trata a ausência
+  como destrutiva), e em `_meta` os campos `com.softize.opus/effect` e
+  `com.softize.opus/personal-data`.
+
+O `opus check` conta, numa linha de aviso que não reprova, quantas actions `simple` ou `form` não
+declaram `effect` e quantas actions não declaram `personalData`.
+
+**O que fazer:** rode `opus gen` depois do bump. O manifest passa a ter `effect` e `personalData` em
+toda action (`null` quando não declarado), e sem regenerar o `manifest:check` falha mesmo sem mudança
+de código. O resto é gradual: declare `effect` nas actions `simple` e `form` e `personalData` em
+todas; uma major futura passará a exigir as duas declarações. Um sink de audit que descarta leituras
+(`actionKind` `list` ou `view`) deve preservar as que trazem `personalData`, se a aplicação precisar
+registrar a exposição.
+
 ## 22.1.0 — 2026-09-28
 
 Os dados do modo design saem do contrato (ADR 0037). No modo design, toda action passa a responder
@@ -346,7 +419,7 @@ página (ADR 0024). A `Presentation` de lista em `layout="fill"` passa a entrega
 lista ocupa a altura da página e só os resultados rolam.
 
 Quem encadeava `flex min-h-0 flex-1 flex-col` à mão pode remover as classes; mantidas, continuam
-funcionando. Com um contêiner próprio entre `ContentBody` e a lista, como um `TabsContent`, a lista
+funcionando. Com um contêiner próprio entre `ContentBody` e a lista, como um `TabsPanel`, a lista
 continua em `flow`: declare `layout="fill"` nela e dê ao contêiner `flex min-h-0 flex-1 flex-col`.
 
 ### Superfícies e patterns

package/bin/cli.mjs

@@ -40,13 +40,14 @@ async function cmdCheck(dir) {
     for (const error of materialization.errors) log('error', `✗ opus check: ${error}`)
     process.exit(1)
   }
-  const { files, actions, contracts, deprecatedMockHandlers, findings, hasMarker } = await scanDir(root)
-  // Aviso de migração, não violação: uma linha só, para não poluir o gate a cada execução.
-  if (deprecatedMockHandlers > 0) {
+  const { files, actions, contracts, missingEffect, missingPersonalData, findings, hasMarker } =
+    await scanDir(root)
+
+  if (missingEffect > 0 || missingPersonalData > 0) {
     log(
       'warn',
-      `⚠ opus check: ${deprecatedMockHandlers} action(s) ainda declaram \`mockHandler\`, que sai na próxima major. ` +
-        'No modo design, a action sem mock já responde com dado gerado; use `defineDesignScenario` quando o design precisar de um cenário (ADR 0037).',
+      `⚠ opus check: ${missingEffect} action(s) simple/form sem \`effect\` e ${missingPersonalData} sem \`personalData\`. ` +
+        'Declare se a action lê ou escreve e se devolve dado pessoal; uma major futura passará a exigir as duas declarações (ADR 0041).',
     )
   }
 

package/bin/lib/check.mjs

@@ -51,12 +51,13 @@ const FIELD_GROUP = {
   errors: 1,
   input: 2,
   output: 2,
+  effect: 2,
+  personalData: 2,
   public: 3,
   requires: 3,
   authorize: 3,
   loads: 3,
   handler: 4,
-  mockHandler: 4,
   audit: 5,
   confirm: 5,
   invalidates: 5,
@@ -515,6 +516,7 @@ export function parseActions(fileName, sourceText) {
           form: callee,
           name: strProp(obj, "name"),
           kind: strProp(obj, "kind"),
+          effect: strProp(obj, "effect"),
           keys: objKeys(obj),
           ident: constIdent(node),
           exported: isExported(node),
@@ -575,6 +577,12 @@ export function lintAction(a) {
   if (!a.kind) at("kind", `${a.form} sem \`kind\``);
   else if (!KINDS.has(a.kind))
     at("kind", `kind "${a.kind}" inválido (use simple|form|list|view)`);
+  // ADR 0041: list e view são servidas por GET — leitura pelo protocolo.
+  if ((a.kind === "list" || a.kind === "view") && a.effect === "write")
+    at(
+      "effect",
+      `${a.kind} é servida por GET e não pode declarar effect: 'write'; use simple ou form para escrever`,
+    );
 
   // field-order: os campos conhecidos devem ter group-index não-decrescente
   let lastGroup = -1;
@@ -585,7 +593,7 @@ export function lintAction(a) {
     if (g < lastGroup) {
       at(
         "field-order",
-        `campo "${k}" fora de ordem (depois de "${lastKey}") — siga identidade→docs→input/output→authorize→handler→comportamento`,
+        `campo "${k}" fora de ordem (depois de "${lastKey}") — siga identidade→docs→input/output e natureza (effect, personalData)→authorize→handler→comportamento`,
       );
       break;
     }
@@ -642,8 +650,9 @@ export function checkProject(sources) {
   const productDeclarations = [];
   const entityNames = new Set();
   const actionNames = new Set();
-  // `mockHandler` obsoleto (ADR 0037): contado, não reprovado — a minor ainda o aceita.
-  let deprecatedMockHandlers = 0;
+  // Natureza da action (ADR 0041): declarações ausentes são contadas, não reprovadas, na minor.
+  let missingEffect = 0;
+  let missingPersonalData = 0;
 
   for (const { file, text } of sources) {
     const declarations = parseDataProducts(file, text);
@@ -668,7 +677,11 @@ export function checkProject(sources) {
         if (item.name !== null) actionNames.add(item.name);
       }
       for (const f of lintAction(item)) findings.push({ ...f, file });
-      if (item.keys.includes("mockHandler")) deprecatedMockHandlers += 1;
+      if (item.form !== "bindAction") {
+        const writesByGet = item.kind === "list" || item.kind === "view";
+        if (!writesByGet && !item.keys.includes("effect")) missingEffect += 1;
+        if (!item.keys.includes("personalData")) missingPersonalData += 1;
+      }
     }
   }
 
@@ -774,7 +787,8 @@ export function checkProject(sources) {
     actions,
     contracts,
     dataProducts: productDeclarations.length,
-    deprecatedMockHandlers,
+    missingEffect,
+    missingPersonalData,
     findings,
   };
 }
@@ -1925,7 +1939,7 @@ async function walkUiFiles(dir, acc = []) {
   return acc;
 }
 
-/** Escaneia um diretório → { files, actions, contracts, deprecatedMockHandlers, findings, hasMarker }.
+/** Escaneia um diretório → { files, actions, contracts, findings, hasMarker }.
  *  `hasMarker` = o diretório é um projeto opus (tem opus.json na raiz). */
 export async function scanDir(rootDir) {
   rootDir = canonicalProjectDirectory(rootDir);
@@ -1955,7 +1969,8 @@ export async function scanDir(rootDir) {
     actions: checked.actions,
     contracts: checked.contracts,
     dataProducts: checked.dataProducts,
-    deprecatedMockHandlers: checked.deprecatedMockHandlers,
+    missingEffect: checked.missingEffect,
+    missingPersonalData: checked.missingPersonalData,
     findings: [...checked.findings, ...uiFindings],
     hasMarker,
   };

package/bin/lib/copy.mjs

@@ -128,7 +128,7 @@ const JSX_CHILD_ROLES = new Map([
   ['PaneTitle', 'title'],
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
-  ['TabsTrigger', 'tab'],
+  ['TabsListItem', 'tab'],
   // A Base não tem papel `tooltip`. O tooltip nomeia um controle icon-only, logo é um
   // fragmento (sem ponto final), não uma frase; `label` é o papel que reflete isso.
   ['TooltipContent', 'label'],

package/bin/lib/gen-manifest.mjs

@@ -53,6 +53,8 @@ function shapeAction(a) {
     authorize: a.authorize,
     public: a.public,
     automatable: a.automatable,
+    effect: a.effect ?? null,
+    personalData: a.personalData ?? null,
     internal: a.internal,
     successStatus: a.successStatus,
     input: a.input,

package/bin/lib/gen-runner.mjs

@@ -51,6 +51,8 @@
  *       successStatus?: number,
  *       public?: boolean,
  *       automatable?: boolean,             // aceita execução pelo sistema (ADR 0028)
+ *       effect: 'read'|'write'|null,       // efeito resolvido; list/view = read (ADR 0041)
+ *       personalData: boolean|null,        // devolve dado pessoal; null = não declarado
  *       internal?: boolean,
  *       rateLimit?: { window, max },
  *       confirm?: ConfirmSpec,
@@ -375,6 +377,9 @@ function serializeAction(action, ctx) {
     authorize: serializeAuthorize(action.authorize),
     public: action.public === true,
     automatable: action.automatable === true,
+    // ADR 0041: `list` e `view` são leitura pelo protocolo; null = não declarado.
+    effect: action.kind === "list" || action.kind === "view" ? "read" : (action.effect ?? null),
+    personalData: typeof action.personalData === "boolean" ? action.personalData : null,
     internal: action.internal === true,
     successStatus: action.successStatus,
     input: safeToJsonSchema(action.input, ctx),
@@ -461,6 +466,8 @@ function serializeFilters(filters) {
       placeholder: spec.placeholder ?? null,
       type: spec.type ?? null,
       multiple: spec.multiple === true,
+      presentation: spec.presentation ?? null,
+      allowEmpty: spec.allowEmpty ?? null,
       mode: spec.mode ?? null,
       operators: Array.isArray(spec.operators) ? spec.operators : null,
       path: spec.path ?? null,

package/bin/lib/gen-stubs.mjs

@@ -182,7 +182,9 @@ function stripNullsFromFields(record) {
     for (const [k, v] of Object.entries(spec)) {
       if (v === null || v === undefined) continue
       if (k === 'hasShowWhen' || k === 'hasRequireWhen') continue
-      if (typeof v === 'boolean' && v === false) continue
+      // `false` costuma ser o default implícito e não precisa viajar. `allowEmpty` é a
+      // exceção: seu default é aceitar vazio, então `false` altera o comportamento.
+      if (typeof v === 'boolean' && v === false && k !== 'allowEmpty') continue
       clean[k] = v
     }
     out[name] = clean

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

@@ -62,7 +62,7 @@ por propriedades continua disponível temporariamente dentro de `Content`, mas a
 explícita usa os slots da família.
 
 `Content` técnico mantém seu nome quando representa o contêiner montado por uma primitiva ou um
-painel controlado, como `DialogContent`, `PopoverContent`, `TabsContent` e `AccordionContent`.
+painel controlado, como `DialogContent`, `PopoverContent`, `TabsPanel` e `AccordionContent`.
 `CarouselContent` também permanece porque representa o trilho técnico da primitiva, não o body de
 uma superfície estrutural. No `Empty`, a antiga região `EmptyContent` não é um body: como contém
 somente comandos, seu nome canônico passa a ser `EmptyActions`.

package/docs/adr/0032-tab-baseline-respects-the-container-inset.md

@@ -2,7 +2,8 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionada:** ADR 0023, quanto ao alinhamento horizontal dentro de superfícies.
+- **Relacionadas:** ADR 0023, quanto ao alinhamento horizontal dentro de superfícies; ADR 0040,
+  que torna a linha a única apresentação de `TabsList`.
 
 ## Contexto
 
@@ -23,14 +24,16 @@ continua pertencendo à anatomia da superfície, e Tabs apenas ocupa a largura q
 
 ### Emenda de 2026-09-28 — a aba combina uma área de botão e o indicador
 
-Na variante horizontal `line`, o gatilho mantém duas camadas: uma área interna com os estados
-interativos e a mesma altura de um Button do tamanho correspondente, e o indicador ancorado na
-linha-base da lista. A área interna permanece transparente e recebe fundo apenas no hover; a aba
-ativa se distingue pelo indicador primário. Um respiro de `0.375rem` separa as duas camadas no uso
-comum; dentro de `Tabs framed`, ele aumenta para `0.5rem` e acompanha o padding superior da moldura.
+Na apresentação horizontal que então se chamava `line`, o gatilho mantém duas camadas: uma área
+interna com os estados interativos e a mesma altura de um Button do tamanho correspondente, e o
+indicador ancorado na linha-base da lista. A área interna permanece transparente e recebe fundo
+apenas no hover; a aba ativa se distingue pelo indicador primário. Um respiro de `0.375rem` separa
+as duas camadas no uso comum; dentro de `Tabs framed`, ele aumenta para `0.5rem` e acompanha o
+padding superior da moldura.
 
-Essa apresentação pertence ao Opus: consumidores escolhem `variant="line"` e não repetem classes
-de fundo, raio, padding ou interação para obter o estado selecionado.
+Essa apresentação pertence ao Opus: consumidores não repetem classes de fundo, raio, padding ou
+interação para obter o estado selecionado. Desde a ADR 0040, a linha é a única apresentação de
+`TabsList` e `variant` não faz mais parte da API.
 
 ## Consequências
 
@@ -38,7 +41,7 @@ de fundo, raio, padding ou interação para obter o estado selecionado.
 - A seleção permanece indicada pela linha inferior, sem manter um segundo fundo persistente.
 - Drawer e Dialog não mantêm uma integração implícita com Tabs.
 - Um consumidor que realmente precise de uma linha até as bordas deve compor essa apresentação de
-  forma explícita, pois ela não é mais o comportamento padrão da variante `line`.
+  forma explícita, pois ela não faz parte do comportamento canônico de `TabsList`.
 
 ## Alternativas descartadas
 
@@ -54,6 +57,7 @@ sem consumidor conhecido. A composição explícita é suficiente caso essa nece
 
 ## Verificação
 
-O teste da variante `line` verifica que a linha usa `inset-inline: 0`, inclusive quando Tabs está
-dentro de `DrawerBody`. O mesmo teste verifica a separação estrutural entre a superfície interna e
-o indicador da aba ativa. A documentação viva demonstra a variante com os limites do contêiner.
+O teste da apresentação horizontal verifica que a linha usa `inset-inline: 0`, inclusive quando
+Tabs está dentro de `DrawerBody`. O mesmo teste verifica a separação estrutural entre a superfície
+interna e o indicador da aba ativa. A documentação viva demonstra a linha com os limites do
+contêiner.

package/docs/adr/0034-tabs-can-own-a-frame-without-owning-a-surface.md

@@ -2,7 +2,8 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionadas:** ADR 0023, quanto à anatomia das superfícies; ADR 0032, quanto à linha-base das abas.
+- **Relacionadas:** ADR 0023, quanto à anatomia das superfícies; ADR 0032, quanto à linha-base das
+  abas; ADR 0040, que substitui a escolha de variante em `TabsList`.
 
 ## Contexto
 
@@ -23,9 +24,10 @@ Quando ativa, `framed` aplica ao root a moldura estrutural canônica para esse b
 `rounded-xl` e recorte do conteúdo. Ela não aplica token de fundo nem de foreground. O conjunto
 herda a superfície do contêiner em que foi composto.
 
-Essa propriedade não altera a apresentação de `TabsList`, a seleção, o tamanho nem a orientação. O
-consumidor continua escolhendo esses comportamentos nas APIs existentes, inclusive
-`TabsList variant="line"`.
+Essa propriedade não altera a apresentação de `TabsList`, a seleção, o tamanho nem a orientação. À
+época desta decisão, o consumidor ainda escolhia a apresentação com `TabsList variant="line"`.
+Essa parte foi substituída pela ADR 0040, que tornou a linha a única apresentação; a independência
+entre moldura e apresentação permanece válida.
 
 ## Consequências
 
@@ -33,8 +35,8 @@ consumidor continua escolhendo esses comportamentos nas APIs existentes, inclusi
 - Em Drawer, Dialog ou Pane, a moldura acompanha o fundo da superfície externa nos temas claro e
   escuro.
 - `Card` continua correto quando as abas realmente precisarem de uma superfície semântica própria.
-- `framed` permanece independente de `TabsList variant`, que descreve apenas a apresentação da
-  lista.
+- `framed` permanece independente da apresentação de `TabsList`; desde a ADR 0040, a lista usa
+  somente a linha de navegação e não aceita `variant`.
 
 ## Alternativas descartadas
 

package/docs/adr/0036-tabs-declares-trigger-distribution.md

@@ -2,7 +2,9 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionadas:** ADR 0032, quanto à composição da variante `line`; ADR 0034, quanto à moldura de Tabs; ADR 0035, quanto ao eixo de distribuição em grupos de controles.
+- **Relacionadas:** ADR 0032, quanto à composição da linha; ADR 0034, quanto à moldura de Tabs; ADR
+  0035, quanto ao eixo de distribuição em grupos de controles; ADR 0040, que substitui a escolha de
+  variante em `TabsList`.
 
 ## Contexto
 
@@ -11,10 +13,11 @@ entre os gatilhos. A view de Evento usa quatro abas no cabeçalho de um bloco em
 derivadas do texto deixam esse cabeçalho visualmente desequilibrado, embora todas as seções tenham o
 mesmo nível.
 
-Hoje, a variante horizontal `line` força cada gatilho a usar a largura do próprio conteúdo. Um
-consumidor que precise de larguras iguais teria de sobrescrever o `flex` interno ou reconstruir a
-lista com grid, duplicando uma decisão que já existe em `ButtonGroup` como
-`distribution="content" | "equal"`.
+Na API vigente quando esta decisão foi registrada, a variante horizontal `line` forçava cada
+gatilho a usar a largura do próprio conteúdo. Um consumidor que precisasse de larguras iguais teria
+de sobrescrever o `flex` interno ou reconstruir a lista com grid, duplicando uma decisão que já
+existia em `ButtonGroup` como `distribution="content" | "equal"`. A ADR 0040 depois tornou a linha
+a única apresentação e removeu `variant`, sem alterar o problema de distribuição resolvido aqui.
 
 ## Decisão
 
@@ -30,9 +33,9 @@ largura nem o layout dos painéis de conteúdo.
 ## Consequências
 
 - Consumidores escolhem a mesma linguagem de distribuição usada por `ButtonGroup`.
-- `TabsList variant="line"` continua responsável pela linha e pelos estados visuais; não recebe
-  classes de layout no consumidor.
-- A view de Evento declara `distribution="equal"` no `Tabs` sem alterar cada `TabsTrigger`.
+- `TabsList` continua responsável pela linha e pelos estados visuais; desde a ADR 0040, não aceita
+  `variant` nem recebe classes de layout no consumidor.
+- A view de Evento declara `distribution="equal"` no `Tabs` sem alterar cada `TabsListItem`.
 - Usos existentes preservam a distribuição pelo conteúdo.
 
 ## Alternativas descartadas

package/docs/adr/0037-design-data-lives-outside-the-contract.md

@@ -1,6 +1,6 @@
 # ADR 0037 — Dados do modo design ficam fora do contrato
 
-- **Status:** aceita; a primeira etapa saiu na 22.1.0, e a remoção fica para a 23.0.0.
+- **Status:** aceita; transição concluída na 23.0.0.
 - **Data:** 2026-09-28.
 - **Relacionadas:** ADR 0002 (seeds estruturados).
 

package/docs/adr/0038-content-level-defines-primary-presentation.md

@@ -0,0 +1,62 @@
+# ADR 0038 — O nível do Content define sua apresentação principal
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Complementa:** ADRs 0016, 0021, 0023 e 0029.
+
+## Contexto
+
+`Content` aceitava duas declarações independentes para a mesma hierarquia: `level={1}` fazia da
+região o heading principal da `Page`, enquanto `variant="page"` escolhia a escala visual desse
+mesmo papel. Todos os consumidores válidos precisavam repetir as duas propriedades, e o contrato
+também permitia combinações contraditórias como um heading principal com aparência de seção.
+
+A duplicação ainda produzia ritmos diferentes entre páginas equivalentes. Quando `PageHeader`
+fornecia o heading, `Page` separava introdução e corpo por `1.5rem`; quando `Content` fornecia o
+heading principal, a raiz mantinha os `0.75rem` próprios de uma seção interna.
+
+## Decisão
+
+`Content` deixa de expor `variant`. O nível semântico passa a selecionar a única apresentação
+válida para esse componente:
+
+- `level={1}` identifica o conteúdo principal, usa a escala de `PageHeader` e separa header e body
+  por `1.5rem` no layout contínuo;
+- níveis de 2 a 6 identificam seções internas e preservam a escala e o intervalo de `0.75rem`;
+- `fieldset` permanece uma seção interna: sua legenda não participa da hierarquia de headings.
+
+`Page` continua sendo a superfície estrutural, e `heading: "content"` continua declarando na
+`Presentation` quem possui o heading principal. A decisão não transforma `Content` em `Page`; ela
+remove uma escolha visual que não tinha significado independente dentro de `Content`.
+
+## Consequências
+
+- combinações contraditórias deixam de ser representáveis;
+- consumidores removem `variant="page"` e preservam `level={1}`;
+- o ritmo do conteúdo principal fica igual ao de páginas cujo heading pertence a `PageHeader`;
+- a remoção da propriedade é incompatível e exige migração coordenada dos consumidores;
+- a escala interna continua centralizada em `SurfaceHeader`, sem duplicação no consumidor.
+
+## Alternativas descartadas
+
+### Manter variant e corrigir somente o espaço
+
+Corrigiria o sintoma visual, mas preservaria a duplicação e os estados inválidos no contrato.
+
+### Renomear variant para role
+
+Tornaria a intenção mais explícita, porém continuaria exigindo duas propriedades para declarar o
+mesmo papel e permitiria que elas divergissem.
+
+### Derivar a apresentação da presença em Page
+
+Acoplaria `Content` ao local de renderização. O heading principal já é declarado diretamente por
+`level={1}` e pode ser validado por `Page` sem outro contexto implícito.
+
+## Verificação
+
+- testes de `Content` confirmam escala e intervalo de página no nível 1 e de seção nos demais;
+- tipos e exemplos públicos não aceitam mais `variant` em `Content`;
+- testes de `Page`, `Presentation` e preenchimento preservam `Content level={1}` como heading
+  principal;
+- consumidores compilam sem `variant="page"`.

package/docs/adr/0039-filter-presentation-is-independent-from-filter-type.md

@@ -0,0 +1,62 @@
+# ADR 0039 — A apresentação do filtro é independente de seu tipo
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Complementa:** ADR 0019.
+
+## Contexto
+
+`FilterSpec` declara o significado e o transporte de cada filtro, mas a interface apresentava todo
+filtro `select` com o mesmo controle. Escolhas únicas, curtas e mutuamente exclusivas — como um
+canal com três opções — continuavam escondidas em um menu mesmo quando a comparação direta entre
+as alternativas era mais útil.
+
+Transformar `toggle` em um novo `type` misturaria apresentação com valor: tanto o menu quanto o
+grupo produzem a mesma string, ocupam o mesmo campo no estado navegável e chegam sem mudança à
+action.
+
+## Decisão
+
+`FilterSpec` passa a aceitar `presentation: "select" | "toggle"`. A ausência da propriedade
+preserva `select` como apresentação padrão.
+
+`toggle` aplica-se a filtros `type: "select"` de escolha única e usa as mesmas opções, valor de
+repouso, regra de vazio, dependências e atualização de estado do controle padrão. A apresentação
+mostra todas as opções em um `ToggleGroup` conectado e não permite desmarcar a opção ativa quando o
+filtro não aceita vazio. Quando a opção vem de um dicionário e sua entrada declara um ícone do
+catálogo, o grupo apresenta ícone e rótulo juntos.
+
+O tipo do filtro continua descrevendo o valor e sua operação. A apresentação escolhe somente o
+controle usado para editá-lo.
+
+## Consequências
+
+- contratos podem expor escolhas pequenas e fechadas sem reconstruir a barra no consumidor;
+- URL, input da action, defaults e handlers permanecem inalterados;
+- filtros existentes continuam usando `Select` sem migração;
+- `toggle` não se aplica a seleção múltipla, lookup, texto, número ou data;
+- conjuntos extensos ou pesquisáveis continuam usando `Select`.
+
+## Alternativas descartadas
+
+### Criar `type: "toggle"`
+
+Duplicaria a semântica de `select` e exigiria que serialização, validação e adaptadores conhecessem
+um tipo cujo valor não mudou.
+
+### Compor o ToggleGroup em cada página
+
+Preservaria o contrato incompleto e duplicaria a sincronização entre controle, URL, default e input
+efetivo da action.
+
+### Trocar automaticamente selects com poucas opções
+
+Quantidade de opções não determina a melhor apresentação. O contrato precisa declarar a intenção,
+sem uma heurística visual invisível.
+
+## Verificação
+
+- teste do `ActionFilterBar` confirma que `presentation: "toggle"` renderiza todas as opções e
+  atualiza o mesmo campo de filtro;
+- teste de regressão confirma que um `select` sem apresentação continua usando `Select`;
+- typecheck impede valores de apresentação fora do vocabulário público.

package/docs/adr/0040-tabs-use-a-single-navigation-presentation.md

@@ -0,0 +1,60 @@
+# ADR 0040 — Tabs usa uma única apresentação de navegação
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Substitui parcialmente:** ADR 0032, ADR 0034 e ADR 0036 quanto à escolha de variante em `TabsList`.
+
+## Contexto
+
+`TabsList` oferecia uma superfície preenchida e uma variante com linha. A superfície preenchida
+ficava visualmente próxima de um controle segmentado, embora `Tabs` represente navegação entre
+painéis e um `ToggleGroup` represente escolha de valores. A mesma aparência para comportamentos
+diferentes dificultava escolher o componente correto e levou filtros a serem descritos como tabs.
+
+## Decisão
+
+`TabsList` usa somente a linha de navegação e deixa de aceitar `variant`. Cada `TabsListItem`
+continua associado a um `TabsPanel` pelo mesmo valor. Orientação, tamanho, distribuição e moldura
+permanecem propriedades independentes do conjunto.
+
+A anatomia pública nomeia a posição de cada parte: `TabsListItem` pertence a `TabsList`, enquanto
+`TabsPanel` identifica o painel associado. Os nomes anteriores, `TabsTrigger` e `TabsContent`, não
+são mantidos como aliases porque há um único consumidor e a migração é atômica.
+
+Escolhas únicas ou múltiplas que alteram um valor no contexto atual usam `ToggleGroup`. Quando o
+grupo precisa de um contorno conectado, o consumidor declara `variant="outline"` com `spacing={0}`;
+a borda pertence aos itens e as arestas internas duplicadas são removidas pela primitiva.
+
+## Consequências
+
+- Tabs mantém uma identidade visual única e vinculada à navegação entre painéis.
+- Filtros e escolhas de formulário não usam semântica de tabs para obter uma aparência compacta.
+- Consumidores removem `variant="line"`; não há substituição para a antiga superfície preenchida.
+- Consumidores renomeiam `TabsTrigger` para `TabsListItem` e `TabsContent` para `TabsPanel`.
+- A documentação de ToggleGroup explicita como formar o contorno conectado.
+
+## Alternativas descartadas
+
+### Manter duas variantes em TabsList
+
+Preservaria flexibilidade visual, mas manteria a ambiguidade entre navegação e escolha de valor.
+
+### Compartilhar uma apresentação segmentada entre Tabs e ToggleGroup
+
+Permitiria a mesma aparência com semânticas distintas, mas não resolveria a dificuldade de leitura
+observada no produto. A linha torna a navegação reconhecível sem depender do contexto ao redor.
+
+### Preservar Trigger e Content como nomes públicos
+
+Manteria proximidade com a primitiva subjacente, mas nomearia mecanismo e conteúdo genérico em vez
+da anatomia exposta ao consumidor. `ListItem` e `Panel` deixam a composição legível no JSX.
+
+## Verificação
+
+- o tipo público de `TabsList` não aceita `variant`;
+- a exportação pública oferece `TabsListItem` e `TabsPanel`, sem aliases para os nomes anteriores;
+- testes da primitiva confirmam a linha-base, o indicador ativo e a distribuição;
+- testes do `ActionFilterBar` confirmam que `presentation: "toggle"` usa seleção exclusiva sem
+  alterar o estado transportado para a action;
+- a documentação de Tabs não oferece apresentação preenchida e a de ToggleGroup demonstra o grupo
+  conectado com borda.