@softize/opus 17.0.0 → 17.2.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ 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.
 
+## 17.2.0 — 2026-09-12
+
+Páginas hospedadas por `PageShell` passam a apresentar o título no início do conteúdo, em
+`PageIntro`, e reservam a barra persistente para navegação e ações. O shorthand de `Page` aplica
+essa anatomia automaticamente, evitando repetir a página atual ao lado do breadcrumb.
+
+Na composição explícita dentro de `PageShell`, substitua `PageHeader` por `PageIntro`. Fora do
+shell, `PageHeader` continua sendo o cabeçalho convencional da página.
+
+## 17.1.0 — 2026-09-12
+
+Formulários de `Presentation` em Dialog e Drawer passam a oferecer `Cancelar` ao lado da ação
+principal. O retorno no header modal aparece somente quando a surface anterior também é um Dialog
+ou Drawer; a Page mantida ao fundo não cria uma etapa de navegação.
+
+Em Page hospedada por `PageShell`, a `Presentation` mantém navegação e ações na barra e apresenta o
+título no `PageIntro`. Ações que abrem outra Presentation usam o botão default para assumir a
+hierarquia primária do fluxo. Ações textuais de header e footer usam o tamanho `default`; `sm` fica
+reservado às operações densas de toolbar, seção e coleção.
+
 ## 17.0.0 — 2026-09-11
 
 A inspeção de `Presentation` passa a pertencer exclusivamente à Lens, que lê as definições estáticas

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

@@ -21,14 +21,13 @@ renderiza a barra, recebe a navegação conhecida pelo shell e oferece o alvo ca
 declaradas pela `Page` descendente. Essa barra existe somente por `PageShell`; `PageHeader` não
 possui variante visual para reproduzi-la dentro da página.
 
-Quando uma `Page` está dentro de `PageShell`, `PageHeader` continua sendo seu header estrutural.
-`PageTitle`, `PageNavigation`, `PageBack` e `PageActions` são projetados nos alvos da barra sem
-duplicar a anatomia no body. Na forma explícita, a página usa `PageHeader` e `PageBody`, com
-`PageIntro` opcional para contexto adicional no conteúdo. Fora de `PageShell`, `PageHeader` aparece
-dentro do container da página.
-
-`PageState` oculta somente `PageIntro`. A barra do `PageShell` permanece visível com navegação,
-título e ações mesmo quando o conteúdo carrega, falha ou está vazio. Uma ação que depende do
+Quando uma `Page` está dentro de `PageShell`, `PageIntro` é seu header estrutural no conteúdo.
+`PageTitle` permanece nessa região, enquanto `PageNavigation`, `PageBack` e `PageActions` são
+projetados nos alvos da barra. Na forma explícita, a página usa `PageIntro` e `PageBody`, sem
+`PageHeader`. Fora de `PageShell`, `PageHeader` continua dentro do container da página.
+
+`PageState` oculta o título de `PageIntro`. A barra do `PageShell` permanece visível com navegação
+e ações mesmo quando o conteúdo carrega, falha ou está vazio. Uma ação que depende do
 conteúdo deve se omitir por estado na própria rota.
 
 `PageShell` não substitui o shell completo da aplicação, não inclui sidebar e não cria navegação.
@@ -38,10 +37,9 @@ Ele apenas coordena a barra e a área em que uma única `Page` é renderizada.
 
 - shell e rota podem continuar conhecendo partes diferentes da página sem criar componentes locais
   de chrome;
-- título e ações têm destinos oficiais na barra;
+- o título inicia o conteúdo e as ações têm destino oficial na barra;
 - estados integrais preservam a barra e escondem somente a introdução do conteúdo;
-- a composição de `Page` com `PageHeader` é a mesma dentro e fora de `PageShell`; apenas seu destino
-  visual muda;
+- a composição explícita usa `PageIntro` dentro do shell e `PageHeader` fora dele;
 - `PageActionsTarget` continua disponível apenas para workspaces imersivos que não usam
   `PageShell`.
 
@@ -64,7 +62,7 @@ estado do conteúdo. A moldura do shell não deve oscilar com a consulta da rota
 
 ## Verificação
 
-- testes cobrem a projeção de navegação, título e ações, a permanência da barra e a ocultação de `PageIntro` em estados
+- testes cobrem o título no início do conteúdo, a projeção de navegação e ações, a permanência da barra e a ocultação de `PageIntro` em estados
   integrais;
 - a documentação demonstra a composição de `PageShell`, `PageIntro` e `Page` sem CSS externo;
 - consumidores removem barras paralelas e `PageActionsTarget` ao adotar o novo contrato.

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

@@ -19,11 +19,12 @@ capacidades em uma apresentação verificável.
 `Presentation` é o artefato declarativo que descreve um recurso independentemente da superfície em
 que aparece. `Surface` escolhe `page`, `dialog` ou `drawer` no momento da renderização.
 
-A anatomia portátil é `Header + Body + Footer?`. O header organiza horizontalmente
-`Navigation? + Title + Actions?`; o body contém o recurso; o footer contém ações de conclusão.
-Dialog e Drawer acrescentam o fechamento ao final das ações do header. Em Page, `PageShell` hospeda
-o mesmo header na barra persistente; uma introdução opcional pode existir no body sem mover nem
-duplicar o título estrutural.
+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.
 
 Uma action assume um de dois papéis:
 
@@ -48,12 +49,15 @@ estática, publicável no manifest e inspecionável pela Lens. A invocação é
 uma execução: identifica a Presentation, escolhe a surface, carrega somente input JSON e mantém a
 pilha de frames necessária para voltar. Ela não é publicada no manifest.
 
-`back` restaura o último frame da pilha. `close` encerra apenas dialog ou drawer e é inválido para
-page. `navigate` abre outra invocação por push ou substitui a atual; sincronizar esse estado com URL
-é responsabilidade do adaptador da aplicação quando refresh, deep link ou histórico forem
-necessários. O inspetor de desenvolvimento reúne definição, invocação, bindings resolvidos e
-diagnósticos, mascarando chaves sensíveis antes de expor o JSON. O inventário estático e seu JSON
-ficam disponíveis na Lens; a aplicação não adiciona um launcher flutuante ao shell.
+`back` restaura o último frame da pilha. Em Dialog ou Drawer, ele só é apresentado quando o frame
+anterior também é modal; a Page mantida ao fundo não cria uma etapa intermediária. `close` encerra
+apenas dialog ou drawer e é inválido para page. Formulários modais oferecem `Cancelar` como ação de
+abandono no footer, ao lado da conclusão. `navigate` abre outra invocação por push ou substitui a
+atual; sincronizar esse estado com URL é responsabilidade do adaptador da aplicação quando refresh,
+deep link ou histórico forem necessários. O inspetor de desenvolvimento reúne definição,
+invocação, bindings resolvidos e diagnósticos, mascarando chaves sensíveis antes de expor o JSON. O
+inventário estático e seu JSON ficam disponíveis na Lens; a aplicação não adiciona um launcher
+flutuante ao shell.
 
 ## Consequências
 
@@ -90,6 +94,8 @@ Foi descartada porque compatibilidade exige delegar cada kind ao pattern canôni
 - o manifest projeta Presentations sem callbacks nem dados server-only;
 - a lens lista e expõe o JSON integral de cada Presentation;
 - testes de invocação cobrem push, replace, back, close e rejeição de input não JSON;
+- testes do renderer cobrem a ausência de retorno entre Page e modal, o retorno entre modais e as
+  ações Cancelar/concluir do formulário;
 - o inspetor mascara segredo, token, cookie, autorização, senha e chave de API;
 - a Lens lista as definições registradas e abre o JSON integral sem depender da árvore React;
 - uma aplicação consumidora usa o pacote local por symlink durante a migração página por página.

package/docs/adr/0015-action-size-follows-interaction-density.md

@@ -0,0 +1,64 @@
+# ADR 0015 — O tamanho da ação acompanha a densidade da interação
+
+- **Status:** aceita.
+- **Data:** 2026-09-12.
+
+## Contexto
+
+O uso de `default` e `sm` passou a variar entre headers de Page, footers de Dialog e Drawer,
+toolbars e ações de listagem. Como tamanho também era usado para sugerir importância, duas decisões
+equivalentes podiam ganhar alturas diferentes, enquanto ações repetitivas ocupavam o mesmo espaço
+de uma conclusão da superfície.
+
+O Opus já separa contexto semântico, variante visual e tamanho. Misturar esses eixos impede que a
+mesma regra funcione quando uma ação muda de secundária para primária ou quando um recurso troca de
+Page para Dialog ou Drawer.
+
+## Decisão
+
+O tamanho comunica densidade e alcance da interação; `context` e `variant` comunicam hierarquia e
+risco.
+
+- ações textuais que decidem a superfície usam `default`: header de Page e footer de Page, Dialog
+  ou Drawer;
+- ações operacionais em toolbar, header de seção ou coleção densa usam `sm`;
+- ações internas de linha, célula ou campo usam `xs` ou `icon-xs`;
+- ações somente com ícone que pertencem ao chrome da superfície, como voltar e fechar, usam
+  `icon-sm`;
+- `lg` fica reservado a chamadas que deliberadamente precisam de uma área de toque maior, não a
+  uma ação primária comum.
+
+Patterns que conhecem a região aplicam o tamanho. Componentes estruturais genéricos não clonam nem
+reescrevem filhos arbitrários: em composição manual, o consumidor segue a mesma matriz. Alterar a
+ênfase de uma ação não altera seu tamanho dentro da região.
+
+## Consequências
+
+- Page, Dialog e Drawer mantêm proporção equivalente nas decisões principais;
+- toolbars e grids preservam densidade sem reduzir ações de conclusão;
+- `primary`, `neutral` e `danger` podem mudar sem provocar salto de altura;
+- exemplos e skills deixam de recomendar `sm` por todo cabeçalho compacto.
+
+## Alternativas consideradas
+
+### Usar `sm` em toda barra ou header
+
+Preservaria a menor altura possível, mas trataria uma decisão da página como operação repetitiva e
+criaria diferença em relação ao footer modal do mesmo recurso.
+
+### Fazer a ação primária sempre maior
+
+Reforçaria hierarquia, mas misturaria importância com densidade. A variante `solid` e o contexto
+`primary` já comunicam essa relação sem deslocar o layout.
+
+### Fazer `ButtonGroup` redimensionar qualquer filho
+
+Centralizaria parte da aparência, mas introduziria comportamento implícito e frágil para filhos que
+não são `Button`. A região ou o pattern conhece melhor o tamanho adequado.
+
+## Verificação
+
+- testes da `Presentation` conferem `default` em ações textuais do header e do footer;
+- testes de `ActionList` continuam cobrindo `sm` em toolbar e `icon-xs` nas ações de linha;
+- a documentação de Button e Page apresenta a mesma matriz;
+- revisão de consumidor trata divergência como exceção explícita, não como novo default.

package/package.json

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

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

@@ -40,10 +40,11 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    esses defaults na tela.
 7. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh.
-8. Compor superfícies pela gramática estrutural do catálogo: `Page` contém `PageHeader` e
-   `PageBody`; `Content` contém `ContentHeader` e `ContentBody`; Card, Drawer e Pane usam seus
+8. Compor superfícies pela gramática estrutural do catálogo: fora de `PageShell`, `Page` contém
+   `PageHeader` e `PageBody`; dentro dele, contém `PageIntro` e `PageBody`; `Content` contém
+   `ContentHeader` e `ContentBody`; Card, Drawer e Pane usam seus
    respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` (`title`,
-   `description`, `actions`) ou de `Content` (as mesmas mais `count`); não misturá-la com o
+   `actions`) ou de `Content` (`title`, `description`, `actions` e `count`); não misturá-la com o
    header explícito. O título da página não carrega contador. Ajustar o
    nível do heading pela hierarquia semântica, não pelo destaque visual. O `Page` mantém seu teto
    centralizado padrão de `80rem`.

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

@@ -3,8 +3,9 @@
 - Dispara: “Monte a tela de edição usando a form action do Opus.”
 - Não dispara: “Ajuste o CSS de um e-mail estático.”
 - Execução: implementar uma lista com modal roteável e provar loading, erro, vazio e back.
-- Execução estrutural: montar uma página de relatório com `Page > PageHeader + PageBody`, uma seção
-  `Content > ContentHeader + ContentBody`, `ActionFilterBar` separado do renderer, `ItemGroup` para
+- Execução estrutural: montar uma página de relatório isolada com `Page > PageHeader + PageBody`,
+  outra em `PageShell` com `Page > PageIntro + PageBody`, uma seção `Content > ContentHeader +
+  ContentBody`, `ActionFilterBar` separado do renderer, `ItemGroup` para
   uma coleção secundária e um `ActionFormDialog`; provar teto padrão de `80rem`, hierarquia por
   `level`, vazio estrutural sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento
   inferido e cancelamento `ghost` no modal.

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

@@ -4,14 +4,14 @@
 - Campos, labels, mensagens e invalidações pertencem ao contrato quando são parte da
   operação, não a uma tela isolada.
 - URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
-- `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
-  explícita é `Page > PageHeader (PageBack? | PageNavigation?, PageTitle,
+- `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Fora de
+  `PageShell`, sua forma explícita é `Page > PageHeader (PageBack? | PageNavigation?, PageTitle,
 PageActions?) + PageBody`; `title` e `actions` no próprio `Page` são a abreviação
   para o caso direto.
   Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
   real de largura; não reconstruir esse container em cada rota.
-- `PageIntro` é uma região opcional do body para contexto realmente útil; não substitui nem duplica
-  o título estrutural do `PageHeader`.
+- `PageIntro` é a região estrutural do título quando a página está em `PageShell`; fora dele, pode
+  substituir `PageHeader` quando o conteúdo precisar começar por uma introdução.
 - `PageHeader` é a região de cabeçalho dentro de uma `Page` isolada e organiza navegação, título e
   ações na mesma linha. Em uma subpágina simples, `PageBack` recebe o destino pai explícito e aparece
   antes do título como controle somente com ícone. Para mais de um ancestral relevante, use
@@ -20,11 +20,13 @@ PageActions?) + PageBody`; `title` e `actions` no próprio `Page` são a abrevia
   possuam chrome próprio.
 - Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
   O shell é o único responsável pela barra: fornece `navigation`; a `Page` descendente continua
-  declarando `title` e `actions`. O Opus mantém a barra de `3rem` e projeta título e ações nela.
-  Ações com texto na barra
-  usam `Button size="sm"`; ações somente com ícone usam `icon-sm`. Na forma explícita dentro do
-  shell, use `Page > PageHeader (PageNavigation?, PageTitle, PageActions?) + PageBody`, com
-  `PageIntro` opcional antes do body. Não monte
+  declarando `title` e `actions`. O Opus mantém a barra de `3rem`, projeta ações nela e inicia o
+  conteúdo com o título em `PageIntro`.
+  Ações com texto na barra usam o tamanho `default`, como as ações de footer de Dialog e Drawer;
+  ações somente com ícone de chrome usam `icon-sm`. O tamanho `sm` fica para ações operacionais em
+  toolbar, seção ou coleção densa, e `xs`/`icon-xs` para ações internas de linha ou célula. Contexto
+  e variante resolvem a hierarquia visual sem alterar essa medida. Na forma explícita dentro do
+  shell, use `Page > PageIntro (PageNavigation?, PageTitle, PageActions?) + PageBody`. Não monte
   `PaneHeader`, portal ou seletor global para reconstruir essa composição.
 - `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
   forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma

package/src/ui/components/patterns/form.tsx

@@ -719,7 +719,13 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
         {wrapFooter(
           <>
             {onCancel !== undefined && (
-              <Button type="button" form={formId} variant="ghost" onClick={onCancel}>
+              <Button
+                type="button"
+                form={formId}
+                variant="ghost"
+                disabled={disabled || isLoading}
+                onClick={onCancel}
+              >
                 {cancelLabel}
               </Button>
             )}

package/src/ui/components/patterns/page.tsx

@@ -34,7 +34,6 @@ const PageHeaderContext = createContext<PageHeadingRegion | null>(null);
 const PageIntegralStateContext = createContext(false);
 const PageActionsTargetContext = createContext<HTMLElement | null>(null);
 const PageNavigationTargetContext = createContext<HTMLElement | null>(null);
-const PageTitleTargetContext = createContext<HTMLElement | null>(null);
 const PageShellContext = createContext(false);
 const pageBarClassName =
   "flex h-12 shrink-0 items-center border-b border-border bg-background text-foreground";
@@ -124,7 +123,6 @@ export function PageShell({
   );
   const [navigationTarget, setNavigationTarget] =
     useState<HTMLDivElement | null>(null);
-  const [titleTarget, setTitleTarget] = useState<HTMLDivElement | null>(null);
 
   return (
     <div
@@ -152,20 +150,18 @@ export function PageShell({
         <PageShellNavigationSlot targetRef={setNavigationTarget}>
           {navigation}
         </PageShellNavigationSlot>
-        <PageShellTitleSlot targetRef={setTitleTarget} />
+        <PageShellTitleSlot />
         <PageShellActionsSlot targetRef={setActionsTarget}>
           {actions}
         </PageShellActionsSlot>
       </SurfaceHeader>
       <PageShellContext.Provider value>
         <PageNavigationTargetContext.Provider value={navigationTarget}>
-          <PageTitleTargetContext.Provider value={titleTarget}>
-            <PageActionsTarget target={actionsTarget}>
-              <div data-slot="page-shell-content" className="min-h-0 flex-1">
-                {children}
-              </div>
-            </PageActionsTarget>
-          </PageTitleTargetContext.Provider>
+          <PageActionsTarget target={actionsTarget}>
+            <div data-slot="page-shell-content" className="min-h-0 flex-1">
+              {children}
+            </div>
+          </PageActionsTarget>
         </PageNavigationTargetContext.Provider>
       </PageShellContext.Provider>
     </div>
@@ -254,10 +250,16 @@ export function Page({
   }, []);
   if (
     shorthand &&
-    nodes.some((node) => isValidElement(node) && node.type === PageHeader)
+    nodes.some(
+      (node) =>
+        isValidElement(node) &&
+        [PageHeader, PageIntro, PageBody, PageFooter].includes(
+          node.type as typeof PageHeader,
+        ),
+    )
   ) {
     throw new Error(
-      "Page não permite misturar propriedades de shorthand com PageHeader explícito.",
+      "Page não permite misturar propriedades de shorthand com composição explícita.",
     );
   }
   if (!shorthand) {
@@ -277,9 +279,9 @@ export function Page({
       headers.length + bodies.length + footers.length === nodes.length;
     const validShellComposition =
       insideShell &&
-      headers.length === 1 &&
+      headers.length === 0 &&
       bodies.length === 1 &&
-      intros.length <= 1 &&
+      intros.length === 1 &&
       footers.length <= 1 &&
       headers.length + intros.length + bodies.length + footers.length ===
         nodes.length;
@@ -290,7 +292,7 @@ export function Page({
     ) {
       throw new Error(
         insideShell
-          ? "Page explícito dentro de PageShell exige um PageHeader, um PageBody e aceita no máximo um PageIntro e um PageFooter como filhos diretos."
+          ? "Page explícito dentro de PageShell exige um PageIntro, um PageBody e aceita no máximo um PageFooter como filhos diretos."
           : "Page explícito exige um PageHeader ou PageIntro, um PageBody e no máximo um PageFooter como filhos diretos.",
       );
     }
@@ -298,10 +300,10 @@ export function Page({
   const content =
     shorthand && insideShell ? (
       <>
-        <PageHeader>
+        <PageIntro>
           <PageTitle>{title}</PageTitle>
           {actions !== undefined && <PageActions>{actions}</PageActions>}
-        </PageHeader>
+        </PageIntro>
         <PageBody>{children}</PageBody>
       </>
     ) : shorthand ? (
@@ -346,7 +348,7 @@ export function Page({
   );
 }
 
-/** Introdução opcional do conteúdo, separada da navegação persistente do shell. */
+/** Título estrutural no conteúdo de PageShell ou introdução opcional de uma Page isolada. */
 export function PageIntro({
   className,
   children,
@@ -358,12 +360,16 @@ export function PageIntro({
   requireParent(page !== null, "PageIntro", "Page");
   if (integralState) {
     if (!insideShell) return <></>;
-    const actions = Children.toArray(children).filter(
-      (node) => isValidElement(node) && node.type === PageActions,
+    const persistentSlots = Children.toArray(children).filter(
+      (node) =>
+        isValidElement(node) &&
+        [PageBack, PageNavigation, PageActions].includes(
+          node.type as typeof PageBack,
+        ),
     );
     return (
       <PageHeaderContext.Provider value="intro">
-        {actions}
+        {persistentSlots}
       </PageHeaderContext.Provider>
     );
   }
@@ -374,9 +380,11 @@ export function PageIntro({
         name="PageIntro"
         slot="page-intro"
         slots={{
+          leading: [PageBack, PageNavigation],
           title: PageTitle,
           actions: PageActions,
         }}
+        leadingPlacement="inline"
         className={className}
         {...props}
       >
@@ -431,10 +439,8 @@ export function PageTitle({
   ...props
 }: HTMLAttributes<HTMLHeadingElement>): ReactElement {
   const variant = useContext(PageHeaderContext);
-  const insideShell = useContext(PageShellContext);
-  const target = useContext(PageTitleTargetContext);
   requireParent(variant !== null, "PageTitle", "PageHeader ou PageIntro");
-  const title = (
+  return (
     <h1
       data-slot="page-title"
       className={cn(
@@ -446,10 +452,6 @@ export function PageTitle({
       {...props}
     />
   );
-  if (insideShell && variant === "header") {
-    return target === null ? <></> : createPortal(title, target);
-  }
-  return title;
 }
 
 export function PageActions({
@@ -495,11 +497,7 @@ export function PageNavigation({
   const variant = useContext(PageHeaderContext);
   const insideShell = useContext(PageShellContext);
   const target = useContext(PageNavigationTargetContext);
-  requireParent(
-    variant !== null,
-    "PageNavigation",
-    "PageHeader",
-  );
+  requireParent(variant !== null, "PageNavigation", "PageHeader ou PageIntro");
   const navigation = (
     <div
       data-slot="page-navigation-content"
@@ -507,7 +505,7 @@ export function PageNavigation({
       {...props}
     />
   );
-  if (insideShell && variant === "header") {
+  if (insideShell) {
     return target === null ? <></> : createPortal(navigation, target);
   }
   return navigation;
@@ -522,7 +520,7 @@ export function PageBack({
   const variant = useContext(PageHeaderContext);
   const insideShell = useContext(PageShellContext);
   const target = useContext(PageNavigationTargetContext);
-  requireParent(variant !== null, "PageBack", "PageHeader");
+  requireParent(variant !== null, "PageBack", "PageHeader ou PageIntro");
   const destination =
     typeof children === "string" ? children : "a página anterior";
   const accessibleLabel = ariaLabel ?? `Voltar para ${destination}`;
@@ -540,7 +538,7 @@ export function PageBack({
       </a>
     </Button>
   );
-  if (insideShell && variant === "header") {
+  if (insideShell) {
     return target === null ? <></> : createPortal(back, target);
   }
   return back;

package/src/ui/components/patterns/presentation.tsx

@@ -29,7 +29,11 @@ import type {
   ViewContract,
 } from "../../../core/contracts.ts";
 import { cn } from "../../lib/cn.ts";
-import { Button, buttonVariants } from "../primitives/button.tsx";
+import {
+  Button,
+  buttonVariants,
+  type ButtonSize,
+} from "../primitives/button.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Copyable } from "../primitives/copyable.tsx";
 import { DetailField, DetailGroup } from "../primitives/detail.tsx";
@@ -55,6 +59,7 @@ import {
   PageBody,
   PageFooter,
   PageHeader,
+  PageIntro,
   PageNavigation,
   PageTitle,
   useInsidePageShell,
@@ -143,7 +148,7 @@ function PresentationFrame({
     if (insidePageShell) {
       return (
         <Page className={cn("flex min-h-full flex-col", className)}>
-          <PageHeader>
+          <PageIntro>
             {navigation === undefined ? null : (
               <PageNavigation>{navigation}</PageNavigation>
             )}
@@ -153,7 +158,7 @@ function PresentationFrame({
                 <PresentationActions>{headerActions}</PresentationActions>
               </PageActions>
             )}
-          </PageHeader>
+          </PageIntro>
           <PageBody className="min-h-0 flex-1 overflow-y-auto">{body}</PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
@@ -298,6 +303,7 @@ function PresentationCommandTrigger({
   command,
   action,
   input,
+  size,
   disabled,
   onLoadingChange,
   onSuccess,
@@ -305,6 +311,7 @@ function PresentationCommandTrigger({
   command: PresentationCommand;
   action: SimpleContract<Record<string, unknown>, unknown>;
   input: Record<string, unknown>;
+  size: ButtonSize;
   disabled: boolean;
   onLoadingChange: (command: PresentationCommand, loading: boolean) => void;
   onSuccess: (data: unknown) => void;
@@ -318,6 +325,7 @@ function PresentationCommandTrigger({
       action={action}
       input={input}
       variant="ghost"
+      size={size}
       disabled={disabled}
       onLoadingChange={reportLoading}
       onSuccess={onSuccess}
@@ -374,6 +382,11 @@ export function Presentation({
     [context, invocation, onInvocationChange, onRefresh],
   );
 
+  const closeSurface = useCallback((): void => {
+    onOpenChange?.(false);
+    applyEffects([{ effect: "close" }]);
+  }, [applyEffects, onOpenChange]);
+
   const reportLoading = useCallback(
     (command: PresentationCommand, loading: boolean): void => {
       setLoadingCommands((current) => {
@@ -429,6 +442,10 @@ export function Presentation({
       string,
       unknown
     >;
+    // Header e footer são regiões de decisão da superfície, não toolbars operacionais.
+    // Seus comandos textuais usam a linha padrão; listas e grids continuam donos da
+    // densidade compacta de suas próprias ações.
+    const size: ButtonSize = "default";
     if (action.kind === "simple") {
       return (
         <PresentationCommandTrigger
@@ -436,6 +453,7 @@ export function Presentation({
           command={command}
           action={action as SimpleContract<Record<string, unknown>, unknown>}
           input={input}
+          size={size}
           disabled={isBlocked(command)}
           onLoadingChange={reportLoading}
           onSuccess={(data) => applyEffects(command.onSuccess, data)}
@@ -450,7 +468,7 @@ export function Presentation({
     return (
       <Button
         key={`${command.placement}:${command.action}`}
-        variant="ghost"
+        size={size}
         disabled={isBlocked(command)}
         onClick={() =>
           openTarget(
@@ -480,6 +498,11 @@ export function Presentation({
           action={bodyAction as FormContract<Record<string, unknown>, unknown>}
           defaultValues={bodyInput}
           submitLabel={definition.body.submitLabel}
+          onCancel={
+            invocation.surface === "page"
+              ? undefined
+              : closeSurface
+          }
           onSuccess={(data) => applyEffects(definition.body.onSuccess, data)}
           disabled={hasSurfaceBlock}
           onLoadingChange={setBodyLoading}
@@ -544,8 +567,12 @@ export function Presentation({
   const footerActions = definition.actions
     .filter((command) => command.placement === "footer")
     .map(renderCommand);
+  const parentSurface = invocation.stack.at(-1)?.surface;
+  const canGoBack =
+    parentSurface !== undefined &&
+    (invocation.surface === "page" || parentSurface !== "page");
   const navigation =
-    invocation.stack.length === 0 ? undefined : (
+    !canGoBack ? undefined : (
       <Button
         size="icon-sm"
         variant="ghost"
@@ -567,10 +594,11 @@ export function Presentation({
       footerActions={footerActions.length === 0 ? undefined : footerActions}
       open={open}
       onOpenChange={(nextOpen) => {
-        onOpenChange?.(nextOpen);
         if (!nextOpen && invocation.surface !== "page") {
-          applyEffects([{ effect: "close" }]);
+          closeSurface();
+          return;
         }
+        onOpenChange?.(nextOpen);
       }}
       className={className}
       bodyClassName={bodyClassNameProp}

package/src/ui/docs/content/button.md

@@ -24,14 +24,20 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 | Nome      | Medida  | Uso                                                                                                                              |
 | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | `xs`      | 1.5rem  | Ação dentro de um campo (`InputGroupButton`).                                                                                    |
-| `sm`      | 2rem    | Toolbar e cabeçalho densos, ao lado de `Select` e `Tabs` `sm`.                                                                   |
-| `default` | 2.25rem | A linha padrão, a mesma de `Input`.                                                                                              |
+| `sm`      | 2rem    | Ação operacional em toolbar, seção ou coleção densa, ao lado de `Select` e `Tabs` `sm`.                                         |
+| `default` | 2.25rem | Decisão da superfície em header de Page ou footer de Dialog/Drawer; é também a linha padrão de `Input`.                         |
 | `lg`      | 2.5rem  | Chamada principal com mais área de toque.                                                                                        |
 | `icon-xs` | 1.5rem  | Ação só de ícone dentro de um campo ou de uma linha densa; é o quadrado de `ActionTrigger` com `icon`.                           |
 | `icon-sm` | 1.75rem | Ação só de ícone em composições compactas que precisam de mais presença; também é o quadrado das setas do pager de `ActionList`. |
 | `icon`    | 2.25rem | Ação só de ícone na linha padrão.                                                                                                |
 | `icon-lg` | 2.5rem  | Ação só de ícone ao lado de um `lg`.                                                                                             |
 
+Escolha o tamanho pela região, não pela importância visual: `variant` e `context` resolvem a
+hierarquia da ação. Headers de Page e footers de Dialog/Drawer usam `default`; ações operacionais
+de seção, toolbar e coleção usam `sm`; ações dentro de linha ou célula usam `xs` ou `icon-xs`.
+Controles de chrome, como voltar e fechar, usam `icon-sm`. Assim a mesma decisão mantém a mesma
+altura mesmo quando uma superfície troca uma ação secundária por uma primária.
+
 ```tsx preview
 <Button size="xs">Mínimo</Button>
 <Button size="sm">Pequeno</Button>

package/src/ui/docs/content/page.md

@@ -2,15 +2,17 @@
 
 Use `Page` para manter título, ações, estado e conteúdo na mesma anatomia. Sozinha, ela apresenta
 `PageHeader` dentro do container. Quando a aplicação possui uma barra persistente, envolva a rota
-com `PageShell`: o shell fornece a navegação e a página projeta título e ações na barra.
+com `PageShell`: o shell fornece a navegação, a página projeta as ações na barra e o título inicia
+o conteúdo.
 
 `PageHeader` mantém navegação, título e ações na mesma linha. O container é centralizado e ocupa a
 largura disponível até `80rem` (`max-w-7xl`). Use `className` somente quando a composição pedir
 outro teto ou largura total.
 
 A forma curta é o padrão para páginas comuns. Fora de `PageShell`, ela cria `PageHeader` e
-`PageBody`. Dentro dele, cria `PageHeader` e `PageBody`, projetando o header na barra. A forma
-explícita permite acrescentar um `PageIntro` opcional no conteúdo sem duplicar o título estrutural.
+`PageBody`. Dentro dele, cria `PageIntro` e `PageBody`: o título fica na introdução e as ações são
+projetadas na barra. A forma explícita segue a mesma anatomia, sem duplicar o título ao lado do
+breadcrumb.
 Contadores e outros indicadores pertencem ao
 conteúdo que os explica.
 
@@ -64,8 +66,8 @@ posição introdutória sem transformar a trilha em ação.
 ## Barra persistente do shell
 
 Use `PageShell` quando o shell conhece o breadcrumb e a rota conhece título e ações. Não crie um
-`PaneHeader` paralelo nem esconda slots de `Page` com CSS. O Opus projeta `PageTitle` e
-`PageActions` na barra.
+`PaneHeader` paralelo nem esconda slots de `Page` com CSS. O Opus mantém o `PageTitle` no início do
+conteúdo e projeta somente navegação contextual e `PageActions` na barra.
 
 ```tsx preview col
 <PageShell
@@ -82,7 +84,7 @@ Use `PageShell` quando o shell conhece o breadcrumb e a rota conhece título e a
   <Page
     title="Clientes"
     actions={
-      <Button size="sm">
+      <Button>
         <Plus /> Novo cliente
       </Button>
     }
@@ -95,17 +97,17 @@ Use `PageShell` quando o shell conhece o breadcrumb e a rota conhece título e a
 A barra permanece visível durante `PageState`; uma introdução opcional desaparece. Se uma ação não
 puder ser executada sem o conteúdo, a própria rota deve omiti-la naquele estado.
 
-Na composição explícita dentro do shell, use `PageHeader` e `PageBody`:
+Na composição explícita dentro do shell, use `PageIntro` e `PageBody`:
 
 ```tsx preview col
 <PageShell navigation={<Breadcrumb>...</Breadcrumb>}>
   <Page>
-    <PageHeader>
+    <PageIntro>
       <PageTitle>Clientes</PageTitle>
       <PageActions>
-        <Button size="sm">Novo cliente</Button>
+        <Button>Novo cliente</Button>
       </PageActions>
-    </PageHeader>
+    </PageIntro>
     <PageBody>Conteúdo da listagem.</PageBody>
   </Page>
 </PageShell>
@@ -136,8 +138,9 @@ render(
 );
 ```
 
-Use `PageIntro` somente quando o conteúdo precisar de uma introdução adicional. Ele não substitui
-o `PageHeader`, não repete o título da página e pode ser omitido.
+Fora de `PageShell`, use `PageIntro` somente quando o conteúdo precisar de uma introdução em vez do
+header convencional. Dentro do shell, ele é a região estrutural do título e não deve ser combinado
+com `PageHeader`.
 
 ## Estados integrais
 
@@ -208,7 +211,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade | Tipo                          | Descrição                                                     |
 | ----------- | ----------------------------- | ------------------------------------------------------------- |
-| `children`  | `ReactNode`                   | Conteúdo introdutório opcional do body.                       |
+| `children`  | `ReactNode`                   | Título e ações da página dentro de `PageShell`, ou introdução de uma página isolada. |
 | `className` | `string`                      | Classes adicionais da região introdutória.                    |
 | demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região introdutória.           |
 

package/src/ui/docs/content/presentation.md

@@ -2,17 +2,23 @@
 um drawer. A superfície decide quanto espaço ocupar; o recurso continua com a mesma navegação,
 cabeçalho, body e rodapé.
 
-Nas três superfícies, o cabeçalho usa a mesma ordem horizontal: navegação ou retorno, título e ações.
-Dialog e Drawer acrescentam o fechamento ao final. Uma Page pode apresentar um `PageIntro` separado
-no body quando o conteúdo realmente precisar de uma introdução; ele não substitui nem duplica o
-título estrutural da Presentation.
+Dialog e Drawer mantêm no cabeçalho a ordem horizontal de navegação ou retorno, título e ações.
+O retorno aparece em uma surface modal somente
+quando ela foi aberta sobre outro Dialog ou Drawer; a Page ao fundo sustenta o modal, mas não cria
+uma etapa de navegação. Formulários modais encerram o footer com `Cancelar` e a ação principal.
+Em Page hospedada por `PageShell`, a barra concentra navegação e ações, enquanto o título abre o
+conteúdo em um `PageIntro`. Assim o breadcrumb não disputa espaço nem repete o título na mesma linha.
+Ações textuais de header e footer usam o tamanho `default`, pois pertencem à decisão da superfície;
+o tamanho `sm` permanece reservado às operações densas de toolbar, seção e coleção. Contexto e
+variante continuam definindo hierarquia visual sem alterar essa medida.
 
 Use esse padrão quando uma lista puder abrir um detalhe lateral, quando a mesma edição precisar
 funcionar em modal e em rota própria ou quando um fluxo começar compacto e crescer sem ganhar uma
 segunda implementação.
 
 Dentro de `PageShell`, a superfície `page` usa a anatomia real da aplicação: a Presentation projeta
-navigation, title e actions no header da barra e compõe `PageBody` e, quando necessário, `PageFooter`.
+navigation e actions no header da barra, apresenta o título em `PageIntro` e compõe `PageBody` e,
+quando necessário, `PageFooter`.
 Fora do shell, ela materializa o `PageHeader` completo para exemplos e superfícies independentes.
 Não envolva a Presentation em um card para simular a página; valide proporção, rolagem e ações no
 shell que efetivamente hospeda a rota.
@@ -35,6 +41,7 @@ const workspacePresentation = definePresentation({
 });
 
 function Example() {
+  const [open, setOpen] = React.useState(true);
   const [invocation, setInvocation] = React.useState(() =>
     definePresentationInvocation({
       schemaVersion: 1,
@@ -52,7 +59,10 @@ function Example() {
             key={value}
             size="sm"
             variant={invocation.surface === value ? "solid" : "outline"}
-            onClick={() => setInvocation({ ...invocation, surface: value })}
+            onClick={() => {
+              setInvocation({ ...invocation, surface: value });
+              setOpen(true);
+            }}
           >
             {value}
           </Button>
@@ -64,7 +74,12 @@ function Example() {
         definitions={[workspacePresentation]}
         actions={{ [workspaceUpdate.name]: workspaceUpdate }}
         invocation={invocation}
-        onInvocationChange={(next) => next && setInvocation(next)}
+        open={invocation.surface === "page" || open}
+        onOpenChange={setOpen}
+        onInvocationChange={(next) => {
+          if (next) setInvocation(next);
+          else setOpen(false);
+        }}
       />
     </div>
   );

package/src/ui/meta.ts

@@ -400,7 +400,7 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand cobre título e ações. Quando shell e rota conhecem partes diferentes da página, PageShell mantém a barra de 3rem e recebe navegação, título e ações da Page. PageIntro é um bloco opcional de introdução no conteúdo. Fora do shell, a forma explícita usa PageHeader para o cabeçalho completo. PageActionsTarget fica restrito a workspaces imersivos sem PageShell. PageState oculta somente PageIntro; informações importantes entram no corpo como Alert ou texto. Para uma região disponível à criação ou vínculo, use Empty.",
+      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand cobre título e ações. Quando shell e rota conhecem partes diferentes da página, PageShell mantém a barra de 3rem, recebe a navegação e projeta as ações da Page; o título inicia o conteúdo em PageIntro. Fora do shell, a forma explícita usa PageHeader para o cabeçalho completo. PageActionsTarget fica restrito a workspaces imersivos sem PageShell. PageState oculta somente PageIntro; informações importantes entram no corpo como Alert ou texto. Para uma região disponível à criação ou vínculo, use Empty.",
   },
   presentation: {
     name: "presentation",