@softize/opus 18.4.0 → 19.0.0

package/CHANGELOG.md

@@ -7,6 +7,100 @@ 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.
 
+## 19.0.0 — 2026-09-24
+
+Card, Dialog, Drawer e Pane passam a derivar a anatomia da mesma infraestrutura que Page e Content
+já usavam. Cada superfície declara `layout="continuous" | "sectioned"` no seu componente raiz, e o
+layout responde por um pacote: recuo das regiões, ritmo vertical, escala do título, posição das
+ações, apresentação da mídia e divisores. O divisor passa a ser derivado da vizinhança das regiões —
+um header seguido de corpo desenha a linha; um header sozinho, não.
+
+Os headers passam a posicionar sozinhos o que antes o consumidor montava: mídia, título, descrição
+(onde a família a tem), ações no extremo oposto e o botão de fechar depois delas. `Dialog`, `Drawer`
+e `Pane` ganham slots de ações e de navegação; `Card` e `Pane` ganham slot de mídia; `Card` ganha
+título com nível semântico.
+
+A família `Pane` deixa de viver em dois módulos: raiz e slots agora moram juntos, com título,
+mídia, ações, descrição e página própria na documentação.
+
+`MetricCard` ganha ativação: com `onActivate`, `active` e `activationLabel`, a medida vira um
+controle que aplica o recorte que ela resume — o card passa a emitir `aria-pressed` e a anunciar o
+próprio nome. As três propriedades andam juntas pelo tipo; declarar `active` sem `onActivate` não
+compila. A marcação de ativo é a borda na cor primária: antes era um anel desenhado para fora da
+borda, que qualquer ancestral com `overflow-hidden` cortava. O anel de foco também passa a ser
+interno.
+
+Na mesma versão, a lista em `layout="fill"` troca a rolagem montada com um contêiner posicionado
+por uma grade de duas linhas: os resultados ocupam a folga, o rodapé se mede pelo conteúdo, e o
+contêiner da tabela abre mão da rolagem horizontal para não roubar do cabeçalho a referência do
+`sticky`. O rodapé encosta na última linha e mantém a mesma altura com e sem paginador. O detalhe
+aproxima o ícone do rótulo, na escala densa das superfícies produtivas.
+
+### Breaking
+
+**Headers validam seus slots.** `CardHeader`, `DialogHeader`, `DrawerHeader` e `PaneHeader` aceitam
+apenas os slots da família e no máximo um de cada. Nó solto dentro do header passa a lançar erro com
+a lista do que é aceito. Migração: envolva ações em `CardAction`, `DialogActions`, `DrawerActions`
+ou `PaneActions`; navegação em `DialogNavigation` ou `DrawerNavigation`; ícone em `CardMedia`,
+`DrawerMedia` ou `PaneMedia`. Descrição dentro do header de modal não tem slot e vai para o começo
+do corpo, como as ADRs 0014 e 0018 já determinavam.
+
+**`CardTitle` virou heading.** Era um `div` sem escala tipográfica; agora emite `h3` por padrão,
+aceita `level` para a hierarquia correta e declara a escala pelo layout. Migração: remova o heading
+que você embutia dentro dele e o `text-*` que aplicava por fora; passe `level` quando a página pedir
+outra hierarquia.
+
+**Divisores saem do consumidor.** `<CardHeader className="border-b">` e
+`<CardFooter className="border-t">` deixam de ser necessários: use `layout="sectioned"` no `Card`.
+As classes continuam funcionando, mas somam uma segunda linha sobre a derivada.
+
+**`PaneHeader` e `PaneFooter` ganharam recuo próprio** e o `Pane` passa a usar `inset="none"`
+sozinho quando contém slots estruturais. Migração: remova o `inset="none"` e o padding que a tela
+aplicava no header; remova também o `border-b-0`/`border-t-0` de quem desligava o divisor para
+redesenhá-lo à mão.
+
+**O rodapé do `Drawer` recebeu a faixa sutil do `Dialog`.** A ausência era divergência não declarada
+entre duas superfícies com a mesma anatomia; agora as duas usam o mesmo fundo. O título do Drawer
+também perdeu o `text-foreground` que só ele tinha.
+
+**Títulos de modal passam a truncar.** `DialogTitle` e `DrawerTitle` mantêm o nome da superfície em
+uma linha, com reticências quando não cabe, em vez de empurrar o corpo para baixo. O
+`mode="alert"` é a exceção: ali o título é centralizado e pode ocupar duas linhas, porque a
+resposta obrigatória não tem corpo para empurrar. As telas que já
+escreviam `truncate` podem remover a classe. Quando o nome precisar aparecer inteiro, ele pertence
+ao começo do corpo, não ao cabeçalho (ADR 0018).
+
+**Mídia com visual próprio.** Os slots de mídia aceitam `asChild`: uma marca que já se desenha —
+um orbe, um logotipo — ocupa o slot sem ganhar a moldura por cima, e continua herdando a escala.
+
+**O rodapé do `Drawer` mantém o `mt-auto`** que o `Dialog` não tem. A diferença passa a ser
+declarada: o conteúdo lateral raramente preenche a altura da janela, e sem isso o rodapé subiria
+atrás do corpo.
+
+**Divisor não se desliga por classe.** `border-b-0` no consumidor não apaga a linha derivada — ela
+vem de uma variante condicional, que vence uma classe simples. Uma superfície sem divisores é uma
+superfície `continuous`: troque o layout no root em vez de apagar a borda região a região.
+
+### Migração rápida
+
+1. Rode a aplicação e siga os erros dos headers: cada um diz o slot que falta.
+2. Remova `p-*`, `border-b`, `border-t`, `flex-row`, `justify-between` e `text-*` que existiam só
+   para corrigir o default da família.
+3. Troque `<Card>` + classes de divisor por `<Card layout="sectioned">`.
+4. Onde a tela remontava header com `div`, use os slots — eles agora posicionam sozinhos.
+
+## 18.5.0 — 2026-09-22
+
+`Content` passa a concentrar estrutura e apresentação de blocos com cabeçalho e corpo: aceita
+`as="section" | "fieldset"`, `variant="page" | "section"` e moldura opcional com
+`frameVariant="default" | "legend"`. O novo
+`IconTile` mantém a moldura do ícone como composição explícita, permitindo usar o mesmo ícone com
+ou sem esse apoio visual.
+
+`ActionList` deixa de aplicar moldura por padrão. No layout `fill`, mantém o cabeçalho fixo sobre a
+cor da superfície, com borda inferior durante a rolagem. Filtros avançados podem escolher o tratamento das seções sem
+recriar o fieldset no consumidor. Labels de campos e detalhes compartilham a mesma escala tipográfica.
+
 ## 18.4.0 — 2026-09-21
 
 `executions` acrescenta infraestrutura experimental de acompanhamento: snapshots versionados,

package/docs/adr/0020-icon-tiles-are-explicitly-composed.md

@@ -0,0 +1,46 @@
+# ADR 0020 — Molduras de ícone são compostas explicitamente
+
+- **Status:** aceita.
+- **Data:** 2026-09-18.
+
+## Contexto
+
+Várias interfaces apresentam um ícone dentro de uma pequena superfície quadrada. A mesma forma
+aparecia incorporada em componentes como `FieldLegend`, `ItemMedia` e `EmptyMedia`, ou era
+reconstruída pelo consumidor. Em `FieldLegend`, isso também vinculava a moldura à variante da
+legenda: o consumidor conseguia escolher o ícone, mas não se ele deveria receber a superfície.
+
+## Decisão
+
+`IconTile` passa a representar a moldura visual não interativa de um ícone. Ele compartilha a
+escala de tamanhos dos controles, declara a cor por `context` e oferece os tratamentos `subtle` e
+`outline`.
+
+Slots que aceitam conteúdo, como `FieldLegend.icon`, continuam genéricos. O consumidor passa um
+ícone diretamente quando quer somente o glifo ou compõe `<IconTile><Icon /></IconTile>` quando a
+moldura reforça a hierarquia. `ItemMedia variant="icon"` e `EmptyMedia variant="icon"` reutilizam
+a mesma base visual porque essas variantes já prometem a moldura.
+
+`IconTile` é somente apresentação. Quando o ícone aciona algo, deve-se usar `Button` com tamanho
+de ícone e nome acessível.
+
+## Consequências
+
+- A presença da moldura deixa de ser uma regra implícita da legenda.
+- Tamanho, arredondamento e preenchimento convergem entre consumidores.
+- Um slot permanece flexível sem acumular propriedades como `iconFramed` ou `iconTile`.
+- Migrações devem distinguir molduras decorativas de botões e indicadores semânticos.
+
+## Alternativas descartadas
+
+- **Adicionar uma propriedade à `FieldLegend`:** resolveria apenas uma superfície e ampliaria o
+  contrato toda vez que outra composição precisasse escolher a moldura.
+- **Manter classes livres em cada consumidor:** preservaria divergências de escala e acabamento.
+- **Usar `Button` desabilitado:** comunicaria interatividade onde não existe ação.
+
+## Verificação
+
+- teste estrutural cobre tamanho, variante e tamanho do glifo de `IconTile`;
+- teste de `FieldLegend` confirma que o slot não adiciona moldura por conta própria;
+- teste da API pública garante que o componente e seus metadados sejam exportados;
+- documentação de `Field` mostra a composição explícita.

package/docs/adr/0021-content-carries-structure-and-semantic-element.md

@@ -0,0 +1,65 @@
+# ADR 0021 — Content reúne estrutura visual e elemento semântico
+
+- **Status:** aceita.
+- **Data:** 2026-09-19.
+
+## Contexto
+
+Regiões com título e corpo usam `Content`, mas grupos de formulário precisam reconstruir a mesma
+estrutura com `FieldSet` e `FieldLegend`. Molduras aplicadas diretamente em `DetailGroup` também
+separam visualmente o título dos dados que ele nomeia. Essa sobreposição aumenta a quantidade de
+estruturas que a documentação e os consumidores precisam combinar.
+
+## Decisão
+
+`Content` continua responsável pela anatomia `Header + Body` e passa a aceitar:
+
+- `framed`, que aplica a moldura à região inteira;
+- `as="fieldset"`, que renderiza a raiz como `fieldset` e o título como `legend`.
+- `frameVariant="legend"`, que integra visualmente a legenda à borda quando esse acabamento for
+  escolhido de forma explícita.
+
+O default permanece `as="section"` sem moldura. `FieldGroup` organiza campos dentro do corpo e
+`DetailGroup` preserva a semântica de lista de definições sem assumir a moldura da região.
+`FieldSet` permanece disponível para compatibilidade e para composições que não precisam da
+anatomia completa de `Content`.
+
+No modo `fieldset`, a legenda aceita somente o título. Contador, descrição e ações não são filhos
+válidos de `legend`; consumidores que precisarem dessas regiões devem mantê-las no corpo ou usar
+uma `section`. A escolha de `fieldset` não define o acabamento visual: quando `framed` estiver
+presente, a moldura é contínua por padrão. Os filtros avançados preservam a legenda integrada à
+borda declarando `frameVariant="legend"`.
+
+## Consequências
+
+- A mesma API nomeia e delimita regiões de leitura e grupos de formulário.
+- A escolha do elemento semântico não fica acoplada à presença da moldura.
+- O recorte visual da borda deixa de ser consequência implícita do elemento semântico.
+- A forma curta continua sendo o caminho comum, enquanto a composição explícita permanece
+  disponível nos dois elementos.
+- A migração de `FieldSet` pode ser gradual e não exige remoção nesta versão.
+
+## Alternativas consideradas
+
+### Criar Panel
+
+Separaria a moldura de `Content`, mas criaria outra raiz com header e body para documentar e
+compor. Foi descartada porque `Content` já possui essa responsabilidade.
+
+### Renomear FieldSet para FieldGroup
+
+Produziria simetria nominal com `DetailGroup`, mas perderia a distinção entre a fronteira semântica
+do formulário e o layout interno dos campos. Foi descartada porque `FieldGroup` já representa esse
+layout.
+
+### Adicionar um booleano fieldset
+
+Permitiria alternar o elemento, mas trataria semântica como estado visual. Foi descartada em favor
+de `as`, que explicita o elemento renderizado.
+
+## Verificação
+
+- Testes de UI confirmam `section` e heading como defaults.
+- Testes de UI confirmam `fieldset`, `legend`, props nativas e ausência de heading nesse modo.
+- Testes reprovam slots incompatíveis com a legenda.
+- A documentação demonstra `Content + DetailGroup` e `Content as="fieldset" + FieldGroup`.

package/docs/adr/0023-surfaces-share-one-anatomy-and-two-layouts.md

@@ -0,0 +1,293 @@
+# ADR 0023 — Superfícies compartilham uma anatomia e dois layouts
+
+- **Status:** aceita.
+- **Data:** 2026-09-23.
+- **Complementa:** ADRs 0005, 0014, 0018, 0019 e 0021.
+
+## Contexto
+
+A ADR 0005 estabeleceu a gramática `Root > Header + Body + Footer` para as superfícies da casa. O
+vocabulário foi adotado, mas a implementação não: `Page` e `Content` derivam o header de uma
+infraestrutura interna comum, enquanto `Card`, `Dialog`, `Drawer` e `Pane` desenham o seu à mão.
+
+O efeito acumulado é mensurável no código de hoje:
+
+- **Três escalas de padding para o mesmo papel.** `p-3` no chrome de Page, `p-4` nos slots de Dialog
+  e Drawer, `px-5` no Card. `Card` é a única com ritmo vertical assimétrico (`pt-5 pb-3` no header,
+  `pt-3 pb-5` no footer). `Content`, `PageBody` e `PaneBody` não têm padding nenhum.
+- **`PaneHeader` sem padding e `PaneFooter` com `p-2`** — assimetria dentro da mesma família.
+- **`CardTitle` é um `div` sem escala tipográfica**, único título do conjunto que não é heading e
+  não declara tamanho; herda o que vier do contexto.
+- **Divisor automático em quatro famílias e manual no Card.** A documentação pública ensina o
+  consumidor a escrever `border-b` no `CardHeader` e `border-t` no `CardFooter`.
+- **`Dialog` e `Drawer` não têm slot de ações no header.** Quem precisa injeta nós soltos ao lado do
+  título, como `Presentation` faz hoje.
+- **A família `Pane` está partida**: a raiz mora em `split.tsx`, os slots em `sidebar.tsx`, a
+  documentação está na página da Sidebar e nenhum teste cobre a anatomia.
+- **`Drawer` duplica `Dialog`** com três divergências não declaradas: footer sem fundo, header sem a
+  supressão condicional do divisor e título com `text-foreground` a mais.
+- **Nenhuma suíte transversal** compara as famílias; cada divergência só aparece quando alguém
+  compõe as duas superfícies lado a lado.
+
+A evidência que motivou a decisão veio da tela do Evento de Pós-vendas: para aproximar dois Cards do
+recorte já usado por Dialog e Content, a tela precisou escrever `flex-row items-center gap-4
+border-b p-4` no header, `p-4` no body, `text-sm` no título, um `<h3>` dentro do `CardTitle` e o
+ícone dentro do texto. São cinco decisões estruturais tomadas pelo consumidor.
+
+As forças em tensão:
+
+- **Uniformidade × identidade da família.** Um modal, um card e um painel não precisam ter as mesmas
+  medidas; precisam ter a mesma gramática e o mesmo comportamento estrutural.
+- **Compatibilidade × correção.** Alterar o default de uma família muda todas as telas que já a
+  usam. Preservar o default errado perpetua o defeito que motivou a decisão.
+- **Uma API genérica × seis APIs específicas.** Um `<Surface>` público reduziria código e apagaria a
+  semântica de cada família; seis implementações independentes preservam a semântica e produzem a
+  divergência atual.
+
+## Decisão
+
+### 1. Uma infraestrutura interna, seis fachadas públicas
+
+As telas continuam usando `CardHeader`, `DialogHeader`, `DrawerHeader`, `PaneHeader`,
+`ContentHeader` e `PageHeader`. Não existe superfície genérica pública. `SurfaceHeader` e o novo
+módulo de anatomia permanecem internos: a aplicação não os importa.
+
+A anatomia compartilhada passa a viver em um único módulo interno, que responde por:
+
+- as classes de cada região (`header`, `body`, `footer`) por família e layout;
+- a escala visual do título, separada do nível semântico;
+- a posição e o tamanho das ações;
+- a apresentação da mídia;
+- os divisores entre regiões adjacentes;
+- o alinhamento horizontal comum entre as regiões da mesma superfície.
+
+Nenhuma família reimplementa essas regras. Quando uma família precisa divergir, a divergência é um
+valor declarado na tabela de anatomia, não uma classe escrita no componente.
+
+### 2. O layout é do root e chega aos slots por contexto
+
+`layout` é propriedade do componente raiz: `Card`, `DialogContent`, `DrawerContent` e `Pane`. Os
+slots não recebem `layout`; eles leem o contexto da superfície que os hospeda. Um slot usado fora da
+sua família continua sendo erro, como hoje.
+
+`Content` e `Page` não expõem `layout` de anatomia. `Content` é contínuo por definição e `Page`
+mantém `layout="flow" | "fill"`, que descreve ocupação de altura, não anatomia. São nomes
+diferentes para coisas diferentes e permanecem assim.
+
+### 3. O que cada layout significa
+
+`continuous` e `sectioned` não são a ausência e a presença de uma borda. Cada um é um pacote:
+
+| Aspecto | `continuous` | `sectioned` |
+| --- | --- | --- |
+| Divisores | nenhum | entre regiões adjacentes presentes |
+| Ritmo vertical | header aproxima-se do corpo; o espaço separa | regiões simétricas; o divisor separa |
+| Escala do título | a da família | a da família, um degrau mais contida quando a família tem duas |
+| Fundo do footer | igual ao da superfície | sutil, quando a família declara |
+| Alinhamento horizontal | idêntico entre header, body e footer | idêntico entre header, body e footer |
+
+O alinhamento horizontal é invariante dos dois layouts: o recuo lateral de header, body e footer de
+uma mesma superfície é sempre o mesmo valor. É o que a suíte transversal verifica.
+
+### 4. Os divisores são derivados, não escritos
+
+No layout `sectioned`, o divisor existe quando há duas regiões adjacentes. Um header seguido de nada
+não desenha linha; um footer que é a única região também não. A regra é estrutural e vive no
+componente, derivada da presença dos irmãos — não uma classe que o consumidor aplica.
+
+A recomendação de escrever `border-b` e `border-t` no Card sai da documentação.
+
+### 5. Defaults por família
+
+Os defaults preservam o que cada família já entrega hoje, exceto onde o comportamento atual é o
+defeito que esta decisão corrige:
+
+| Família | Default | Por quê |
+| --- | --- | --- |
+| `Card` | `continuous` | é o que a família entrega hoje: sem divisores, ritmo assimétrico |
+| `Dialog` (default) | `sectioned` | já tem divisores e faixas; o default nomeia o que existe |
+| `Dialog` (`mode="alert"`) | composição própria | a resposta obrigatória mantém sua anatomia centrada |
+| `Drawer` | `sectioned` | idem Dialog |
+| `Pane` | `sectioned` | header e footer já têm divisor |
+| `Content` | contínuo, sem opção | região semântica dentro de outra superfície |
+| `Page` | contínuo, sem opção | a separação do chrome pertence ao shell |
+
+Nenhum default muda de valor efetivo com esta ADR. O que muda é que o valor passa a ter nome,
+implementação única e teste.
+
+### 5.1. O que o inventário dos consumidores mostrou
+
+A migração foi decidida sobre 374 usos reais das seis famílias na plataforma. O que eles revelam:
+
+- **Nenhuma tela usa `CardDescription`, `ContentDescription`, `DialogDescription` ou equivalente.**
+  Toda descrição é um `<p className="text-sm text-muted-foreground">` escrito à mão. Quando esse
+  parágrafo está dentro de um `DialogHeader`, ele contraria a ADR 0018 e precisa ir para o corpo na
+  migração — não ganhar um slot novo no header.
+- **`Card` é usado como caixa sem slots em várias telas**, com o padding escolhido por elas (`p-3`,
+  `p-5`, `px-3 py-2`). O root do Card continua sem padding próprio: quem não usa slots continua
+  decidindo. O padding pertence aos slots, como hoje.
+- **Os dois `PaneHeader` do produto escrevem quase a mesma linha** (`flex h-[3.75rem] items-center
+  … p-3 … border-b-0`) em contextos diferentes. É a prova de que padding e divisor pertencem à
+  primitiva.
+- **Um comentário no código do login documenta o defeito**: o `py-3` do `CardBody` "conta com um
+  CardFooter, que o login não tem". O ritmo do layout contínuo precisa reagir à ausência do rodapé.
+- **Três testes de consumidor contradizem a unificação** e precisam de decisão explícita, não de
+  ajuste mecânico: um proíbe `p-4` no Card, outro exige `p-0` no `DrawerBody`, outro proíbe
+  `ContentHeader` em uma seção. Os dois primeiros fixam contornos; o terceiro fixa uma escolha de
+  composição que continua válida.
+
+### 6. Slots por família
+
+A anatomia é comum; o conjunto de slots continua sendo decisão de cada família, porque decisões
+anteriores já os delimitaram:
+
+| Slot | Card | Content | Page | Dialog | Drawer | Pane |
+| --- | --- | --- | --- | --- | --- | --- |
+| Media | sim | não | não | sim (`DialogMedia`) | sim | sim |
+| Title | sim | sim | sim | sim | sim | sim |
+| Description | sim | sim | não (ADR 0014) | não (ADR 0018) | não (ADR 0018) | não |
+| Meta | não | sim (contador) | não (ADR 0009) | não | não | não |
+| Actions | sim | sim | sim | sim | sim | sim |
+| Body | sim | sim | sim | sim | sim | sim |
+| Footer | sim | não | sim | sim | sim | sim |
+
+As ADRs 0009, 0014 e 0018 não são reabertas: Page, Dialog e Drawer continuam sem descrição no
+header, e Page continua sem contador. `Dialog`, `Drawer` e `Pane` ganham o slot de ações que hoje
+não têm — a ausência obrigava a injetar nós soltos ao lado do título, e o `Studio` a manter três
+anatomias paralelas para a mesma entrada declarativa. O botão de fechar continua sendo o último
+elemento da linha; as ações da tela ficam antes dele.
+
+`Pane` ganha também título e mídia. Hoje ele não tem nenhum dos dois, e as duas telas que precisam
+de um cabeçalho remontam a linha com `span`, incluindo o ícone dentro do texto.
+
+`Content` permanece sem footer: é uma região nomeada dentro de outra superfície, e um rodapé
+pertence à superfície que a hospeda.
+
+### 7. Título: hierarquia e tamanho são independentes
+
+O nível semântico vem de `level` (`1`–`6`) ou de `asChild`, e nunca do tamanho visual. O tamanho vem
+da família e do layout. `CardTitle` deixa de ser um `div` sem escala e passa a declarar as duas
+coisas, com `h3` como default — um card é uma seção dentro de uma página que já tem `h1`.
+
+### 8. Mídia reutiliza a moldura existente
+
+O slot de mídia usa `IconTile` ou a mesma infraestrutura visual dele. Nenhuma família cria outra
+escala de molduras.
+
+Quando a marca já tem visual próprio — um orbe, um logotipo —, `asChild` deixa o slot ceder o
+elemento para ela: a escala continua vindo da mesma fonte, e a moldura sai de cena em vez de ser
+desenhada por baixo.
+
+`DialogMedia` é a exceção declarada: no modo de alerta a mídia não acompanha uma linha de título,
+ela é o elemento de reconhecimento da resposta, e mantém a moldura maior e centrada. A exceção vale
+só nesse modo, deriva da mesma infraestrutura das demais e é coberta por teste. Fora do alerta, o
+`DialogMedia` é a mesma moldura das outras famílias.
+
+### 7.1. O Pane aceita conteúdo livre; as demais não
+
+`Card`, `Dialog`, `Drawer`, `Page` e `Content` sempre nomeiam alguma coisa: seus headers aceitam só
+os slots da família e reprovam nó solto, com uma mensagem que lista o que é aceito.
+
+`Pane` é a superfície genérica — a coluna que hospeda navegação, marca, busca ou chrome que não é
+título nem ação. Seu header aceita conteúdo livre ao lado dos slots, e esse conteúdo ocupa o mesmo
+espaço do heading, de modo que as ações continuam indo para o extremo oposto sem classe no
+consumidor. A permissividade é dele, não uma brecha geral: forçar a marca de uma barra lateral a
+virar "título" seria uniformidade sem semântica.
+
+O conteúdo livre é renderizado **dentro** da região de heading, depois do título e da descrição,
+qualquer que seja a ordem no JSX. Ele herda dali a largura que o heading absorve, o que é o que
+permite às ações continuarem no extremo oposto — mas também significa que uma busca colocada no
+header aparece **abaixo** do título, não ao lado dele. Um header que precise de algo antes do
+título usa o slot de mídia; um que precise de algo ao lado usa o de ações.
+
+### 8.1. Nível semântico em todas as fachadas
+
+Todo título de superfície aceita `level`. Nos modais, onde a primitiva de acessibilidade emite o
+elemento, o nível troca a tag do mesmo nó por composição, nunca aninha um heading dentro de outro, e
+não altera a escala. Sem `level`, vale o `h2` que a primitiva já emitia.
+
+### 9. `Pane` deixa de ser uma família partida
+
+Raiz e slots passam a viver no mesmo módulo, com validação de pertencimento, documentação própria e
+os mesmos testes das demais famílias. `split.tsx` continua dono do redimensionamento; `sidebar.tsx`
+continua dono da navegação. A fronteira deixa de ser acidental e passa a ser declarada.
+
+### 10. Compatibilidade
+
+Aliases depreciados existentes (`CardContent`, `PaneContent`) seguem seu plano de remoção; esta
+decisão não cria novos.
+
+Classes de recuo, ritmo e escala que o consumidor já aplica continuam funcionando: `className` é
+mesclado por último e vence. Uma tela que ainda escreve `p-4` no `CardHeader` não quebra, apenas
+deixa de precisar.
+
+**Os divisores são a exceção, e é uma exceção real.** Eles nascem de variantes condicionais
+(`:not(:last-child)`), que têm especificidade maior que uma classe simples: `border-b-0` no
+consumidor não desliga a linha derivada. Desligar o divisor de uma região isolada não é, portanto,
+uma decisão do consumidor — é decisão da superfície, e se expressa trocando o layout dela para
+`continuous`. A paleta de comandos é o caso dentro do próprio SDK: ela é contínua, e não um
+seccionado com a primeira linha apagada.
+
+Pela mesma razão, a regra que suprime o divisor entre um header e um rodapé adjacentes precisa
+vencer a que o cria — não basta vir depois dela na folha, porque a ordem das variantes não é nossa.
+
+## Consequências
+
+- Uma mudança de espaçamento, divisor ou escala passa a ter um lugar só; hoje tem seis.
+- Card ganha um modo que a aplicação já construía à mão, e a documentação deixa de ensinar o
+  contorno.
+- Dialog e Drawer ganham ações no header; `Presentation` deixa de injetar nós soltos.
+- Pane deixa de ser exceção não testada.
+- Consumidores que aplicavam classes de correção podem removê-las; quem não remover continua
+  funcionando, o que permite migração incremental.
+- O custo é concentrado: quase toda a superfície visual do SDK muda de implementação ao mesmo tempo,
+  e a rede de proteção precisa existir antes da migração, não depois.
+- Uma família que precise divergir passa a precisar declarar a divergência na tabela e cobri-la por
+  teste. Isso é deliberado: torna a diferença uma decisão, não um acidente.
+
+## Alternativas descartadas
+
+### Manter cada família com seu header
+
+Preservaria compatibilidade absoluta e evitaria o custo de migração. Foi descartada porque é o
+estado atual: produziu três escalas de padding, um título sem escala, divisores manuais em uma
+família e a documentação pública ensinando o contorno.
+
+### Expor um `<Surface>` genérico
+
+Reduziria o código a uma implementação e uma API. Foi descartada porque apagaria a semântica de cada
+família — um card, um modal e um painel deixariam de se distinguir no código da tela — e porque o
+ganho real está na infraestrutura interna, que este ADR unifica sem expor.
+
+### Unificar também as medidas entre famílias
+
+Um único recuo para todas as superfícies eliminaria a tabela de anatomia. Foi descartada porque as
+famílias têm densidades legítimas diferentes: o chrome de página é mais compacto que um card, e um
+modal tem largura controlada. O invariante que importa é o alinhamento dentro de cada superfície,
+não a igualdade entre superfícies diferentes.
+
+### Tratar `layout` como propriedade de cada slot
+
+Permitiria um header seccionado com um corpo contínuo. Foi descartada porque o layout é a relação
+entre as regiões: um divisor depende de quem está do outro lado. Propriedade por slot permitiria
+compor superfícies incoerentes sem erro.
+
+### Derivar os divisores por CSS no consumidor
+
+Manteria o componente menor. Foi descartada porque devolve ao consumidor a decisão que esta ADR
+retira dele, e porque a regra depende de presença de irmãos, que o componente conhece e a tela
+não.
+
+## Verificação
+
+- Uma suíte transversal parametrizada percorre as famílias configuráveis e verifica, para cada
+  layout: alinhamento horizontal idêntico entre header, body e footer; divisor apenas entre regiões
+  adjacentes presentes; escala do título independente do nível semântico; header com e sem mídia,
+  descrição e ações; ações no extremo oposto sem classe no consumidor; body sem header; header sem
+  footer; footer com e sem ações.
+- A mesma suíte verifica que `Page` e `Content` não expõem `sectioned` e que nenhuma família
+  reimplementa as classes de anatomia localmente.
+- Testes de família continuam cobrindo o que é específico de cada uma.
+- Exemplos vivos no catálogo apresentam a matriz de layouts e slots.
+- `opus check` continua reprovando slots fora da família.
+- Um teste de API pública reprova a exportação de `SurfaceHeader` ou do módulo de anatomia.

package/package.json

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