@softize/opus 21.0.1 → 22.0.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ 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.
 
+## 22.0.0 — 2026-09-28
+
+As superfícies passam a usar uma introdução única e ganham composições explícitas para conteúdo
+seccionado, abas emolduradas e grupos de ações divididos. A mudança elimina wrappers e classes que
+os consumidores repetiam para montar essas formas, além de alinhar Drawer e Content ao raio
+estrutural vigente. É major porque remove `PageIntro`, muda a posição visual do cabeçalho nas páginas
+com `PageShell` e altera o acabamento padrão de Drawer, Tabs `line` e detalhes horizontais com
+divisórias.
+
+### Breaking
+
+**`PageIntro` foi removido.** `PageHeader` é a única introdução da página e reúne, nessa ordem,
+`PageNavigation`, `PageTitle` e `PageActions`. `PageShell` deixou de renderizar uma barra persistente:
+ele fornece navegação e ações contextuais ao header da página ativa. Migração: mova o título e o
+breadcrumb de `PageIntro` para `PageHeader`; remova imports de `PageIntro` e classes que compensavam
+a barra superior. `PageShell.headerClassName` também foi removida porque não existe mais uma barra
+própria para estilizar; remova a propriedade e, quando necessário, estilize o `PageHeader` da página.
+Um header sem conteúdo renderizável não cria região vazia.
+
+**Drawer usa moldura recuada.** `DrawerContent` passa a ter borda completa, `rounded-xl`, recorte e
+`0.25rem` de respiro em relação à viewport. Migração: remova classes locais de borda, raio, recorte e
+inset que reconstruíam essa moldura; preserve apenas dimensões deliberadas, como `max-w-*`.
+
+**`TabsList variant="line"` mudou de composição.** A linha-base respeita a largura recebida, a aba
+usa uma área interna da altura de Button com fundo somente no hover e o indicador ativo usa o
+contexto primário. `DialogBody` e `DrawerBody` não publicam mais `--opus-inline-gutter`. Migração:
+remova classes locais que estendiam a linha, simulavam o botão interno ou compensavam o gutter.
+
+**`DetailGroup` associa o tratamento tabular a `dividers`.** Em orientação horizontal, divisórias
+passam a aplicar padding por célula, fundo sutil nos rótulos e largura padrão de `8.5rem`, com ou sem
+moldura externa. `variant="framed"` sem divisórias deixa de alterar o fundo dos rótulos. Migração:
+declare `dividers` quando quiser a grade tabular; não use `framed` para escolher o tratamento interno.
+
+### Superfícies e controles
+
+- `Content` aceita `layout="continuous" | "sectioned"`. O layout seccionado exige `framed`, separa
+  o header com divisor e deixa o body sem recuo para tabelas, listas e grades que possuem células.
+  Molduras de Content usam `rounded-xl`, inclusive nos acabamentos `default` e `legend`.
+- `Tabs` aceita `framed`, que aplica borda, raio e recorte sem criar fundo próprio, e
+  `distribution="content" | "equal"`, que preserva a largura dos rótulos ou reparte igualmente a
+  largura disponível entre os gatilhos.
+- `ButtonGroup` aceita `framed` e `mode="divided"`; o modo insere divisores orientados entre os
+  controles sem incluí-los no cálculo de `distribution="equal"`.
+- `Button` aceita `context="warning"` em todas as variantes visuais.
+- O filtro composto de período do `ActionList` apresenta período antes do tipo de data, usa divisor
+  estrutural e aplica o foco ao grupo quando qualquer controle interno está aberto.
+
 ## 21.0.1 — 2026-09-26
 
 **Correção.** O `status()` do driver BullMQ podia devolver `status: 'done'` com `data: null` para um

package/bin/lib/check.mjs

@@ -121,13 +121,12 @@ const UI_SURFACE_PAIRS = new Map([
 // locais homônimos.
 const UI_STRUCTURAL_PARENTS = new Map([
   ["PageHeader", new Set(["Page"])],
-  ["PageIntro", new Set(["Page"])],
   ["PageBody", new Set(["Page"])],
   ["PageFooter", new Set(["Page"])],
-  ["PageTitle", new Set(["PageHeader", "PageIntro"])],
+  ["PageTitle", new Set(["PageHeader"])],
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
-  ["PageActions", new Set(["PageHeader", "PageIntro"])],
+  ["PageActions", new Set(["PageHeader"])],
   ["ContentHeader", new Set(["Content"])],
   ["ContentBody", new Set(["Content"])],
   ["ContentTitle", new Set(["ContentHeader"])],
@@ -191,11 +190,9 @@ const UI_STRUCTURAL_ROOTS = new Map([
     "Page",
     {
       header: "PageHeader",
-      alternateHeader: "PageIntro",
       body: "PageBody",
       footer: "PageFooter",
       headerRequired: false,
-      allowBothHeaders: true,
       shorthand: new Set(["title", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
       // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
@@ -219,7 +216,6 @@ const UI_STRUCTURAL_ROOTS = new Map([
 
 const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageHeader",
-  "PageIntro",
   "PageBody",
   "PageFooter",
   "PageTitle",
@@ -241,7 +237,7 @@ const UI_REMOVED_PROPS = new Map([
   [
     "PageHeader",
     new Map([
-      ["variant", "use `PageShell` para a barra persistente da página"],
+      ["variant", "o cabeçalho da página tem uma única apresentação rolável"],
     ]),
   ],
   [
@@ -265,6 +261,7 @@ const UI_REMOVED_PROPS = new Map([
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
+  ["PageIntro", "use `PageHeader` como a única introdução estrutural"],
   ["PageDescription", "mova contexto relevante para o início de `PageBody`"],
   [
     "DialogDescription",
@@ -289,14 +286,6 @@ const UI_STRUCTURAL_HEADERS = new Map([
       titleRequired: false,
     },
   ],
-  [
-    "PageIntro",
-    {
-      title: "PageTitle",
-      optional: new Set(["PageActions"]),
-      shorthand: new Set(),
-    },
-  ],
   [
     "ContentHeader",
     {
@@ -1118,11 +1107,14 @@ const jsxSpaceEntities = {
  * As demais entidades nomeadas ficam como estão: nenhuma delas vira espaço em branco.
  */
 function decodeJsxSpaceEntities(raw) {
-  return raw.replace(/&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g, (entity, dec, hex, name) => {
-    if (name !== undefined) return jsxSpaceEntities[name] ?? entity;
-    const code = dec !== undefined ? Number(dec) : Number.parseInt(hex, 16);
-    return code <= 0x10ffff ? String.fromCodePoint(code) : entity;
-  });
+  return raw.replace(
+    /&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g,
+    (entity, dec, hex, name) => {
+      if (name !== undefined) return jsxSpaceEntities[name] ?? entity;
+      const code = dec !== undefined ? Number(dec) : Number.parseInt(hex, 16);
+      return code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+    },
+  );
 }
 
 /**
@@ -1176,7 +1168,10 @@ function invalidSplitChildren(split, imports, localComponents) {
       return text(node.text, node);
     }
     if (ts.isNumericLiteral(node)) {
-      invalid.push({ label: `o número ${node.text}`, position: node.getStart() });
+      invalid.push({
+        label: `o número ${node.text}`,
+        position: node.getStart(),
+      });
       return;
     }
     if (
@@ -1206,7 +1201,8 @@ function invalidSplitChildren(split, imports, localComponents) {
       for (const nested of node.children) child(nested);
       return;
     }
-    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) element(node);
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node))
+      element(node);
   };
   for (const node of split.children) child(node);
   return invalid;
@@ -1215,7 +1211,8 @@ function invalidSplitChildren(split, imports, localComponents) {
 function directImportedJsxChildren(node, imports) {
   if (!ts.isJsxElement(node)) return [];
   return node.children.flatMap((child) => {
-    if (!ts.isJsxElement(child) && !ts.isJsxSelfClosingElement(child)) return [];
+    if (!ts.isJsxElement(child) && !ts.isJsxSelfClosingElement(child))
+      return [];
     const local = jsxLocalName(child);
     const imported = local === null ? undefined : imports.get(local);
     return imported === undefined ? [] : [{ node: child, component: imported }];
@@ -1224,7 +1221,8 @@ function directImportedJsxChildren(node, imports) {
 
 function jsxNumericAttribute(node, name) {
   const attribute = jsxAttribute(jsxOpening(node), name);
-  if (attribute === undefined || attribute.initializer === undefined) return null;
+  if (attribute === undefined || attribute.initializer === undefined)
+    return null;
   if (
     ts.isJsxExpression(attribute.initializer) &&
     attribute.initializer.expression !== undefined &&
@@ -1243,7 +1241,7 @@ function countPageHeadingSources(page, imports) {
   let count = 0;
   let states = 0;
   for (const child of directImportedJsxChildren(page, imports)) {
-    if (child.component === "PageHeader" || child.component === "PageIntro") {
+    if (child.component === "PageHeader") {
       count += directImportedJsxChildren(child.node, imports).filter(
         (entry) => entry.component === "PageTitle",
       ).length;
@@ -1271,7 +1269,8 @@ function countPageHeadingSources(page, imports) {
 
 function pageBodyHasOpaqueDescendant(page, imports) {
   for (const child of directImportedJsxChildren(page, imports)) {
-    if (child.component !== "PageBody" || !ts.isJsxElement(child.node)) continue;
+    if (child.component !== "PageBody" || !ts.isJsxElement(child.node))
+      continue;
     let opaque = false;
     const visit = (node) => {
       if (opaque) return;
@@ -1323,7 +1322,11 @@ export function checkUiStructure(file, text) {
       const local = jsxLocalName(node);
       const component = local === null ? null : imports.get(local);
       if (component === "Split" && ts.isJsxElement(node)) {
-        for (const child of invalidSplitChildren(node, imports, localComponents)) {
+        for (const child of invalidSplitChildren(
+          node,
+          imports,
+          localComponents,
+        )) {
           findings.push({
             rule: "ui-structure-split",
             level: "error",
@@ -1552,7 +1555,7 @@ export function checkUiStructure(file, text) {
               add(
                 node,
                 component,
-                "Page explícito exige exatamente um heading principal em PageHeader, PageIntro, Content level={1} ou PageState dentro de PageBody.",
+                "Page explícito exige exatamente um heading principal em PageHeader, Content level={1} ou PageState dentro de PageBody.",
               );
             }
           }

package/docs/adr/0004-page-content-state-is-composed.md

@@ -8,8 +8,9 @@
 > restaurá-lo em `ready`. A lista de responsabilidades abaixo já descreve o comportamento novo; o
 > adendo no fim deste arquivo registra o motivo, a alternativa descartada e o que se perde.
 >
-> **Atualização (2026-09-10).** Dentro de `PageShell`, o estado integral oculta somente
-> `PageIntro`. A barra pertence à moldura persistente e continua visível (ADR 0011).
+> **Atualização (2026-09-10, superada em 2026-09-28).** A ADR 0011 preservava a barra do
+> `PageShell` e ocultava somente `PageIntro`. A ADR 0029 removeu as duas regiões: `PageHeader` é a
+> única introdução e o estado integral a substitui por inteiro, dentro ou fora de `PageShell`.
 
 ## Contexto
 

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

@@ -13,6 +13,9 @@
 > **Atualização (2026-09-16).** O corpo abaixo descreve a anatomia da época em que foi escrito, não a
 > vigente: a apresentação `bar` da ADR 0010 saiu com a ADR 0011, e nenhum header estrutural carrega
 > mais descrição (ADRs 0018 e 0014). A anatomia atual está na documentação de cada família.
+>
+> **Atualização (2026-09-28).** A ADR 0033 substitui a decisão de prender a moldura externa do
+> Drawer à viewport: o painel agora usa moldura completa e recuada.
 
 ## Contexto
 

package/docs/adr/0006-semantic-context-precedes-visual-variant.md

@@ -44,6 +44,13 @@ quanto sua materialização (`btn-danger`, `btn-outline-danger`), mistura hierar
 inclui `light`/`dark`, que pertencem ao tema. Copiar a API manteria a ambiguidade que queremos
 remover. Rejeitada como contrato literal e aceita como referência de vocabulário.
 
+### Representar ações de cautela como neutras, perigosas ou com classes locais
+
+Uma ação pode pedir atenção sem ser destrutiva, como registrar uma tentativa sem sucesso. Tratá-la
+como `neutral` apaga essa diferença; tratá-la como `danger` exagera o risco; aplicar tokens de
+`warning` por `className` cria uma variante clandestina fora do contrato e não alcança tipos,
+documentação nem componentes que reutilizam `ButtonContext`. Rejeitada.
+
 ### Declarar contexto e variante como eixos independentes
 
 `context` escolhe a família de tokens e responde por que existe o realce. `variant` escolhe como a
@@ -59,12 +66,7 @@ O Opus define o vocabulário canônico:
 
 ```ts
 type UiContext =
-  | 'neutral'
-  | 'primary'
-  | 'info'
-  | 'success'
-  | 'warning'
-  | 'danger'
+  "neutral" | "primary" | "info" | "success" | "warning" | "danger";
 ```
 
 - `neutral`: estado normal, inativo ou sem julgamento positivo/negativo;
@@ -86,24 +88,29 @@ domínio não se torna a ação principal da interface. A metadata canônica pas
 Para componentes semânticos, `variant` descreve somente o tratamento visual:
 
 ```ts
-type SemanticVariant = 'solid' | 'subtle' | 'outline' | 'ghost' | 'link'
+type SemanticVariant = "solid" | "subtle" | "outline" | "ghost" | "link";
 ```
 
 Cada componente aceita apenas as variantes que consegue materializar com coerência. Os defaults
 iniciais são:
 
-| Componente | Contexto padrão | Variante padrão | Contextos permitidos |
-| --- | --- | --- | --- |
-| Button | `primary` | `solid` | `neutral`, `primary`, `danger` |
-| Badge | `neutral` | `subtle` | todos |
-| Alert | `neutral` | `subtle` | `neutral`, `info`, `success`, `warning`, `danger` |
-| Dot | `neutral` | `solid` | `neutral`, `primary`, `info`, `success`, `warning`, `danger` |
-| MetricCard | `neutral` | `subtle` no ícone | `neutral`, `info`, `success`, `warning`, `danger` |
+| Componente | Contexto padrão | Variante padrão   | Contextos permitidos                                         |
+| ---------- | --------------- | ----------------- | ------------------------------------------------------------ |
+| Button     | `primary`       | `solid`           | `neutral`, `primary`, `warning`, `danger`                    |
+| Badge      | `neutral`       | `subtle`          | todos                                                        |
+| Alert      | `neutral`       | `subtle`          | `neutral`, `info`, `success`, `warning`, `danger`            |
+| Dot        | `neutral`       | `solid`           | `neutral`, `primary`, `info`, `success`, `warning`, `danger` |
+| MetricCard | `neutral`       | `subtle` no ícone | `neutral`, `info`, `success`, `warning`, `danger`            |
 
 `solid`, `subtle` e `outline` podem compartilhar um contexto sem compartilhar classes. `ghost` e
 `link` ficam restritos a controles interativos. Cor e ícone continuam reforços: texto ou nome
 acessível comunica o significado.
 
+`warning` em `Button` representa uma ação de cautela não destrutiva: a pessoa pode prosseguir, mas
+o efeito merece atenção. `danger` permanece reservado a risco ou consequência perigosa. `info` e
+`success` continuam fora do subconjunto do botão até existir uma necessidade de ação observável;
+estado informativo ou resultado positivo, isoladamente, não justificam colorir um controle.
+
 Componentes cuja `variant` é exclusivamente estrutural ou local, como `plain | framed` e
 `default | line`, podem mantê-la. Ao criar API nova, preferir uma prop específica quando o nome do
 eixo for mais claro (`frame`, `layout`, `appearance`); não renomear primitives existentes sem ganho
@@ -161,6 +168,8 @@ for consultada.
 
 - Primitives semânticos passam a compartilhar um vocabulário e tokens contextuais.
 - Defaults podem variar por componente, mas a mesma palavra nunca muda de significado.
+- Ações de cautela não destrutivas usam os tokens canônicos de `warning`, sem classes locais nem
+  reclassificação como `danger`.
 - A API fica mais explícita em chamadas que precisam dos dois eixos.
 - A transição aumenta temporariamente tipos, testes e normalização por causa dos aliases.
 - Temas precisam oferecer tokens de superfície, borda, texto de ênfase e sólido para cada contexto,

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

@@ -12,6 +12,11 @@
 > `PageHeader`, `PageIntro` e `PageFooter` como opcionais e exige exatamente um heading principal —
 > `PageTitle`, `Content level={1}` ou um `PageState` ativo. As frases abaixo que pedem `PageIntro`
 > "sem `PageHeader`" descrevem a regra da 17.2 e não valem mais.
+>
+> **Atualização (2026-09-27).** A padronização posterior do chrome estrutural levou a barra do
+> `PageShell` dos `3rem` originais para `3.75rem`. A presença persistente da barra continua sendo a
+> decisão arquitetural desta ADR; sua medida pertence ao contrato vigente do componente, registrado
+> na documentação e nos testes do Opus, e não deve ser redefinida localmente pelo consumidor.
 
 ## Contexto
 

package/docs/adr/0013-presentation-is-a-portable-action-oriented-artifact.md

@@ -7,6 +7,9 @@
 > materializa título e comandos de header no `Content` que envolve o `ActionList`. Dialog e Drawer
 > continuam materializando esses elementos no header da superfície.
 >
+> **Atualização (2026-09-28).** A ADR 0029 removeu `PageIntro` e a barra persistente de
+> `PageShell`. As passagens abaixo sobre a anatomia de Page já refletem a introdução única.
+>
 > Uma Presentation pode declarar uma `route` absoluta com parâmetros. Nessa forma, URL, surface e
 > origem do registro passam a integrar o artefato; o adaptador da aplicação apenas conecta a spec ao
 > router hospedeiro.
@@ -29,10 +32,10 @@ que aparece. `Surface` escolhe `page`, `dialog` ou `drawer` no momento da render
 
 A anatomia portátil é `Header + Body + Footer?`, mas cada surface materializa seu header de acordo
 com o espaço disponível. Dialog e Drawer organizam horizontalmente
-`Navigation? + Title + Actions? + Close` e mantêm as ações de conclusão no footer. Em Page
-hospedada por `PageShell`, a barra persistente reúne navegação e ações; o título inicia o conteúdo
-em `PageIntro`, sem repetir a página atual ao lado do breadcrumb. Fora do shell, a Page materializa
-seu header completo no próprio container.
+`Navigation? + Title + Actions? + Close` e mantêm as ações de conclusão no footer. Em Page,
+`PageHeader` reúne navegação contextual, título e ações numa única introdução rolável. Quando a
+listagem fornece o heading principal por `Content level={1}`, o mesmo header pode conter somente a
+navegação ou as ações fornecidas pelo `PageShell`, sem criar uma segunda região visual.
 
 Uma action assume um de dois papéis:
 

package/docs/adr/0016-list-collection-header-belongs-to-content.md

@@ -4,6 +4,10 @@
 - **Data:** 2026-09-13.
 - **Revisa:** ADRs 0011 e 0013.
 
+> **Atualização (2026-09-28).** A ADR 0029 removeu `PageIntro` e a barra persistente de
+> `PageShell`. As regras abaixo preservam `Content` como dono do cabeçalho da coleção e usam
+> `PageHeader` como a única introdução da página.
+
 ## Contexto
 
 Páginas centradas em uma coleção colocavam o título no `PageIntro`, a criação na barra do
@@ -23,11 +27,12 @@ as ações da coleção, como criar um item. `ActionList` continua responsável
 atualização, visualização, resultados, estados e paginação. `toolbarActions` fica reservado a
 operações ligadas ao recorte corrente da lista, não ao comando primário de criar.
 
-`PageHeader` representa o chrome da página: navegação e ações globais. Dentro de `PageShell`,
-esses slots são projetados na barra; `PageIntro` permanece opcional para uma introdução própria da
-página. Uma `Page` explícita mantém exatamente um heading principal: `PageTitle` em header/intro,
-`Content level={1}` ou um `PageState` ativo no body. Quando `Content` fornece esse heading, a Page
-pode conter somente `PageBody`.
+`PageHeader` é a única introdução da página e reúne navegação contextual, título e ações globais.
+Dentro de `PageShell`, navegação e ações fornecidas pelo shell são compostas nesse mesmo header,
+sem barra persistente. Uma `Page` explícita mantém exatamente um heading principal: `PageTitle` em
+`PageHeader`, `Content level={1}` ou um `PageState` ativo no body. Quando `Content` fornece esse
+heading, a Page pode conter somente `PageBody`; se `PageShell` acrescentar navegação ou ações,
+`Page` materializa automaticamente o `PageHeader` que as recebe.
 
 Na `Presentation`, uma action `list` exibida como Page materializa o título e os comandos de header
 no `Content` que envolve o `ActionList`. Em Dialog e Drawer, o título e esses comandos continuam no
@@ -72,9 +77,9 @@ responsabilidades locais. Foi descartada para coleções; ações realmente glob
 
 ## Verificação
 
-- testes de `Page` cobrem `PageHeader + PageIntro + PageBody` e `PageBody` sem header;
+- testes de `Page` cobrem `PageHeader + PageBody` e `PageBody` sem header;
 - `opus check` aceita essa gramática e continua rejeitando slots duplicados ou fora da família;
-- testes de `Presentation` confirmam que Page de listagem usa `Content` e mantém a barra sem a ação
-  da coleção;
+- testes de `Presentation` confirmam que Page de listagem usa `Content` e mantém a introdução sem a
+  ação da coleção;
 - a documentação de `ActionList` recomenda `Content` e reserva `toolbarActions` ao recorte atual;
 - consumidores validam visualmente o título e a criação junto da listagem.

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

@@ -3,6 +3,7 @@
 - **Status:** aceita.
 - **Data:** 2026-09-23.
 - **Complementa:** ADRs 0005, 0014, 0018, 0019 e 0021.
+- **Superada em parte por:** ADR 0030, que permite anatomia seccionada em `Content` com moldura.
 
 ## Contexto
 
@@ -78,13 +79,13 @@ diferentes para coisas diferentes e permanecem assim.
 
 `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 |
+| 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.
@@ -102,15 +103,15 @@ A recomendação de escrever `border-b` e `border-t` no Card sai da documentaç
 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 |
+| 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.
@@ -127,7 +128,7 @@ A migração foi decidida sobre 374 usos reais das seis famílias na plataforma.
   `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 à
+… 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é.
@@ -141,15 +142,15 @@ A migração foi decidida sobre 374 usos reais das seis famílias na plataforma.
 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 | sim (`ContentMedia`) | 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 |
+| Slot        | Card | Content              | Page           | Dialog              | Drawer         | Pane |
+| ----------- | ---- | -------------------- | -------------- | ------------------- | -------------- | ---- |
+| Media       | sim  | sim (`ContentMedia`) | 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

package/docs/adr/0025-content-frame-treatment-does-not-change-semantics.md

@@ -3,6 +3,7 @@
 - **Status:** aceita.
 - **Data:** 2026-09-25.
 - **Complementa:** ADRs 0021 e 0023.
+- **Complementada por:** ADR 0030, que separa o `layout` da região do acabamento `frameVariant`.
 
 ## Contexto
 

package/docs/adr/0029-page-header-is-the-single-page-introduction.md

@@ -0,0 +1,71 @@
+# ADR 0029 — PageHeader é a única introdução estrutural da página
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+- **Substitui:** ADR 0011, quanto à barra persistente e à separação entre `PageHeader` e
+  `PageIntro`.
+- **Relacionada:** ADR 0016, quanto ao cabeçalho próprio de coleções.
+
+## Contexto
+
+`PageShell` separou a navegação e as ações globais numa barra persistente, enquanto `PageIntro`
+manteve o título no conteúdo. A separação estabilizou a posição das ações, mas criou duas regiões
+para identificar a mesma página. Nas rotas simples, a barra passou a repetir o item já selecionado
+na navegação da aplicação. Nas rotas profundas, o breadcrumb ficou visualmente distante do título
+que ele contextualiza.
+
+Breadcrumb é uma exceção para hierarquias que a navegação persistente não revela. Ele não precisa
+reservar uma faixa em todas as páginas, e uma página de primeiro nível não ganha contexto ao repetir
+seu próprio nome acima do título.
+
+## Decisão
+
+`PageHeader` é a única introdução estrutural de `Page`:
+
+- o header participa da rolagem normal do conteúdo;
+- `PageNavigation` ou `PageBack`, quando presente, ocupa uma linha acima da linha principal;
+- `PageTitle` e `PageActions` compõem a linha principal;
+- páginas sem hierarquia adicional não renderizam nem reservam espaço para navegação;
+- `PageIntro` deixa de fazer parte da anatomia pública;
+- `PageShell` pode coordenar navegação e ações conhecidas pela aplicação, mas não desenha uma barra;
+  esses valores são compostos pelo `PageHeader` da página ativa;
+- `PageState` integral continua substituindo o header e fornece o único heading do estado;
+- uma coleção pode continuar fornecendo o heading principal por `Content level={1}` sem criar um
+  `PageHeader` redundante.
+
+## Consequências
+
+- breadcrumb, título e ações voltam a pertencer à mesma região visual;
+- páginas simples começam diretamente pelo título;
+- a altura inicial do conteúdo pode variar quando existe breadcrumb, porque a variação agora
+  comunica hierarquia real;
+- consumidores combinam navegação, título e ações em um único `PageHeader` ao migrar da composição
+  explícita;
+- `PageShell` deixa de garantir navegação durante estados integrais, pois o estado substitui a
+  introdução completa da página;
+- a remoção de `PageIntro` é uma mudança incompatível e requer migração coordenada dos consumidores.
+
+## Alternativas descartadas
+
+### Manter a barra persistente somente quando houver breadcrumb
+
+Evitaria a repetição em páginas simples, mas preservaria duas anatomias para o mesmo cabeçalho e
+manteria a navegação distante do título nas páginas profundas.
+
+### Manter `PageIntro` como região opcional abaixo de `PageHeader`
+
+Preservaria compatibilidade, mas continuaria exigindo que cada página decidisse qual das duas
+regiões contém o título e as ações.
+
+### Copiar a composição no consumidor
+
+Validaria uma tela isolada mais rapidamente, porém criaria um segundo contrato visual fora do
+catálogo e não provaria que páginas declarativas e `Presentation` mantêm a mesma anatomia.
+
+## Verificação
+
+- testes de `Page` cobrem breadcrumb acima da linha de título e ações;
+- shorthand e composição explícita produzem a mesma anatomia;
+- `PageShell` não renderiza barra e entrega navegação e ações ao `PageHeader` descendente;
+- `PageState` integral mantém um único heading e remove o header;
+- testes de `Presentation` cobrem a mesma composição dentro e fora de `PageShell`.