@softize/opus 15.0.1 → 15.1.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ 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.
 
+## 15.1.0 — 2026-09-10
+
+`PageShell` passa a coordenar o chrome persistente quando shell e rota conhecem partes diferentes da
+página. O shell fornece a navegação e mantém uma barra de `3rem`; a `Page` descendente continua
+declarando título, descrição, ações e estados. As ações aparecem na barra sem portal montado pelo
+consumidor, enquanto título e descrição formam o novo `PageIntro` dentro do conteúdo.
+
+Em um estado integral, `PageShell` permanece visível e somente `PageIntro` é ocultado. A composição
+anterior de `Page`, `PageHeader` e `PageBody` não muda fora do shell. `PageActionsTarget` continua
+disponível para workspaces imersivos que já possuem uma moldura própria.
+
+**Migração opcional:** substitua barras paralelas e seletores que escondem slots por
+`PageShell navigation={...}` ao redor da rota. A página interna pode continuar na forma curta; use
+`PageIntro` e `PageBody` somente quando precisar da composição explícita.
+
 ## 15.0.1 — 2026-09-09
 
 Correções sobre a 15.0.0, publicada horas antes, todas vindas da revisão dela. Nenhuma novidade de

package/bin/lib/check.mjs

@@ -105,12 +105,13 @@ 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"])],
-  ["PageTitle", new Set(["PageHeader"])],
+  ["PageTitle", new Set(["PageHeader", "PageIntro"])],
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
-  ["PageDescription", new Set(["PageHeader"])],
-  ["PageActions", new Set(["PageHeader"])],
+  ["PageDescription", new Set(["PageHeader", "PageIntro"])],
+  ["PageActions", new Set(["PageHeader", "PageIntro"])],
   ["ContentHeader", new Set(["Content"])],
   ["ContentBody", new Set(["Content"])],
   ["ContentTitle", new Set(["ContentHeader"])],
@@ -166,6 +167,7 @@ const UI_STRUCTURAL_ROOTS = new Map([
     "Page",
     {
       header: "PageHeader",
+      alternateHeader: "PageIntro",
       body: "PageBody",
       shorthand: new Set(["title", "description", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
@@ -187,6 +189,7 @@ const UI_STRUCTURAL_ROOTS = new Map([
 
 const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageHeader",
+  "PageIntro",
   "PageBody",
   "PageTitle",
   "PageBack",
@@ -204,6 +207,8 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "AlertActions",
 ]);
 
+const UI_STRUCTURAL_CONTAINERS = new Set(["PageShell"]);
+
 const UI_STRUCTURAL_HEADERS = new Map([
   [
     "PageHeader",
@@ -219,6 +224,14 @@ const UI_STRUCTURAL_HEADERS = new Map([
       shorthand: new Set(),
     },
   ],
+  [
+    "PageIntro",
+    {
+      title: "PageTitle",
+      optional: new Set(["PageDescription", "PageActions"]),
+      shorthand: new Set(),
+    },
+  ],
   [
     "ContentHeader",
     {
@@ -793,6 +806,7 @@ function structuralJsxAncestorName(node, imports) {
       if (
         imported !== undefined &&
         (UI_STRUCTURAL_ROOTS.has(imported) ||
+          UI_STRUCTURAL_CONTAINERS.has(imported) ||
           UI_STRUCTURAL_PARENTS.has(imported) ||
           [...UI_STRUCTURAL_PARENTS.values()].some((parents) =>
             parents.has(imported),
@@ -805,6 +819,18 @@ function structuralJsxAncestorName(node, imports) {
   return null;
 }
 
+function hasJsxAncestor(node, imports, component) {
+  let current = node.parent;
+  while (current !== undefined) {
+    if (ts.isJsxElement(current) || ts.isJsxSelfClosingElement(current)) {
+      const local = jsxLocalName(current);
+      if (local !== null && imports.get(local) === component) return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
 function directStructuralChildren(node, imports) {
   if (!ts.isJsxElement(node)) return { names: [], hasOpaque: false };
   const names = [];
@@ -966,8 +992,15 @@ export function checkUiStructure(file, text) {
           attributes.has(attribute),
         );
         const children = directStructuralChildren(node, imports);
+        const insidePageShell =
+          component === "Page" && hasJsxAncestor(node, imports, "PageShell");
+        const acceptedHeaders = (
+          insidePageShell
+            ? [root.alternateHeader]
+            : [root.header, root.alternateHeader]
+        ).filter(Boolean);
         const structural =
-          children.names.includes(root.header) ||
+          acceptedHeaders.some((header) => children.names.includes(header)) ||
           children.names.includes(root.body);
         // A prop removida saiu do `shorthand`, então sozinha ela não marca o nó como forma curta:
         // ele cai no ramo explícito, que cobra header e body — uma segunda mensagem inteiramente
@@ -981,18 +1014,18 @@ export function checkUiStructure(file, text) {
           add(
             node,
             component,
-            `${component} não permite misturar propriedades de shorthand com ${root.header}/${root.body}.`,
+            `${component} não permite misturar propriedades de shorthand com ${acceptedHeaders.join("/")}/${root.body}.`,
             "ui-structure-mode",
           );
         } else if (!shorthand) {
-          const headers = children.names.filter(
-            (name) => name === root.header,
+          const headers = children.names.filter((name) =>
+            acceptedHeaders.includes(name),
           ).length;
           const bodies = children.names.filter(
             (name) => name === root.body,
           ).length;
           const unexpected = children.names.some(
-            (name) => name !== root.header && name !== root.body,
+            (name) => !acceptedHeaders.includes(name) && name !== root.body,
           );
           if (
             headers !== 1 ||
@@ -1003,7 +1036,7 @@ export function checkUiStructure(file, text) {
             add(
               node,
               component,
-              `${component} explícito exige exatamente um ${root.header} e um ${root.body} como filhos diretos.`,
+              `${component} explícito exige exatamente um ${acceptedHeaders.join(" ou ")} e um ${root.body} como filhos diretos.`,
             );
           }
         }

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

@@ -4,6 +4,9 @@
 > estados. Ela foi invertida: `PageState` passa a ocultá-lo em `loading`, `error` e `empty`, e a
 > 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).
 
 ## Contexto
 

package/docs/adr/0010-page-header-owns-page-chrome.md

@@ -4,6 +4,10 @@
 - **Data:** 2026-09-09.
 - **Complementa:** ADR 0005.
 
+> **Atualização (2026-09-10).** A ADR 0011 acrescenta `PageShell` para o caso em que shell e rota
+> conhecem partes diferentes da mesma página. A barra continua sendo a apresentação compacta do
+> cabeçalho, mas o título do conteúdo passa a `PageIntro` e as ações são coordenadas pelo Opus.
+
 ## Contexto
 
 Aplicações com sidebar passaram a montar uma barra superior separada de `PageHeader` para reunir

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

@@ -0,0 +1,70 @@
+# ADR 0011 — PageShell coordena o chrome persistente da página
+
+- **Status:** aceita.
+- **Data:** 2026-09-10.
+- **Revisa:** ADR 0010.
+
+## Contexto
+
+A ADR 0010 reuniu título, navegação e ações em `PageHeader`, mas partiu do pressuposto de que uma
+única camada conhece todos esses elementos. Em aplicações com navegação persistente, o shell conhece
+o breadcrumb e a moldura enquanto a rota conhece o título, as ações e o estado do conteúdo.
+
+Sem um contrato para essa divisão, consumidores criam uma barra com `PaneHeader`, projetam ações
+manualmente e escondem partes do `PageHeader` com CSS. O resultado parece correto, mas mantém duas
+anatomias concorrentes e faz um estado integral remover também a navegação persistente do shell.
+
+## Decisão
+
+`PageShell` representa a moldura persistente de uma página dentro de um shell de aplicação. Ele
+renderiza a apresentação em barra de `PageHeader`, recebe a navegação conhecida pelo shell e oferece
+o alvo canônico para ações declaradas pela `Page` descendente.
+
+Quando uma `Page` está dentro de `PageShell`, sua forma curta transforma título e descrição em
+`PageIntro`, dentro do conteúdo. `PageActions` continua declarado pela página, mas aparece na barra.
+Na forma explícita, a página usa `PageIntro` e `PageBody`. Fora de `PageShell`, a composição anterior
+com `PageHeader` continua válida; `PageIntro` também pode ser escolhido quando o conteúdo precisa de
+uma introdução sem navegação própria. As duas regiões não são equivalentes: `PageHeader` reúne o
+cabeçalho completo, enquanto `PageIntro` dá mais presença ao título dentro do conteúdo.
+
+`PageState` oculta somente `PageIntro`. A barra do `PageShell` permanece visível porque preserva
+navegação e ações globais 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.
+Ele apenas coordena a barra e a área em que uma única `Page` é renderizada.
+
+## Consequências
+
+- shell e rota podem continuar conhecendo partes diferentes da página sem criar componentes locais
+  de chrome;
+- título e descrição deixam de ser mascarados por seletores globais;
+- ações de página têm um único destino oficial na barra;
+- estados integrais preservam a barra e escondem somente a introdução do conteúdo;
+- a composição anterior de `Page` permanece compatível fora de `PageShell`;
+- `PageActionsTarget` continua disponível apenas para workspaces imersivos que não usam
+  `PageShell`.
+
+## Alternativas consideradas
+
+### Passar breadcrumb a cada rota
+
+Manteria toda a anatomia dentro de `Page`, mas faria cada página receber e repassar contexto que já
+pertence ao shell. Também duplicaria essa infraestrutura em seções com navegação própria.
+
+### Tornar o portal local um padrão da aplicação
+
+Resolveria somente o GrandBrasil e deixaria o design system sem contrato para a mesma divisão de
+responsabilidade em outros consumidores.
+
+### Fazer a barra desaparecer em estados integrais
+
+Repetiria o comportamento do header embutido, mas removeria navegação persistente por causa do
+estado do conteúdo. A moldura do shell não deve oscilar com a consulta da rota.
+
+## Verificação
+
+- testes cobrem a projeção das 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "15.0.1",
+  "version": "15.1.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/references/ui-patterns.md

@@ -10,6 +10,9 @@
   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.
+- Fora de `PageShell`, a composição explícita também pode trocar `PageHeader` por `PageIntro` quando
+  o conteúdo precisar somente de título, descrição e ações, sem retorno ou breadcrumb. `PageIntro`
+  dá mais presença ao título e não é uma abreviação visual de `PageHeader`.
 - `PageHeader` é a única região de cabeçalho da página. O default acompanha o container;
   `variant="bar"` apresenta a mesma anatomia como faixa compacta no topo. Em uma subpágina simples,
   `PageBack` recebe o destino pai explícito: aparece acima do título no default e como icon-only com
@@ -17,10 +20,17 @@
   `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome paralelo para uma `Page`.
   Ações com texto na barra usam `Button size="sm"`; ações somente com ícone usam `icon-sm`.
   `PageActionsTarget` fica reservado a workspaces imersivos que já possuam chrome próprio.
+- Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
+  O shell fornece `navigation`; a `Page` descendente continua declarando `title`, `description` e
+  `actions`. O Opus mantém a barra de `3rem`, projeta as ações nela e apresenta título e descrição
+  como `PageIntro` no conteúdo. Na forma explícita dentro do shell, use
+  `Page > PageIntro (PageTitle, PageDescription?, 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
-  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho some inteiro —
-  incluindo o `PageBack` —, o estado ocupa a área disponível e seu título assume o heading
+  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho da Page isolada
+  some inteiro — incluindo o `PageBack`; dentro de `PageShell`, somente `PageIntro` some e a barra
+  permanece. O estado ocupa a área disponível e seu título assume o heading
   principal, inclusive quando um componente intermediário renderiza o estado. Uma subpágina que
   dependa do retorno ao pai oferece essa saída pelo `action` do próprio `PageState`. O erro mantém
   `role="alert"`, usa a mesma composição central e sem moldura dos demais estados e apresenta a

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

@@ -1,8 +1,8 @@
 /**
  * <Page /> — esqueleto composto de página do back-office.
  *
- * A forma curta cobre o caso comum; a forma explícita expõe a mesma anatomia para composições
- * especiais. Ambas preservam o container centralizado com teto de 80rem.
+ * A forma curta cobre o caso comum; PageShell coordena a barra persistente quando shell e rota
+ * conhecem partes diferentes. Todas preservam o container centralizado com teto de 80rem.
  */
 
 import {
@@ -39,9 +39,114 @@ interface PageContextValue {
 }
 
 const PageContext = createContext<PageContextValue | null>(null);
-const PageHeaderContext = createContext<PageHeaderVariant | null>(null);
+type PageHeadingRegion = PageHeaderVariant | "intro";
+
+const PageHeaderContext = createContext<PageHeadingRegion | null>(null);
 const PageIntegralStateContext = createContext(false);
 const PageActionsTargetContext = 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";
+const pageBarContentClassName = "w-full py-2";
+
+function PageShellNavigationSlot({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  return (
+    <div
+      data-slot="page-shell-navigation"
+      className={cn("min-w-0 flex-1 overflow-hidden", className)}
+      {...props}
+    />
+  );
+}
+
+function PageShellActionsSlot({
+  targetRef,
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement> & {
+  targetRef: (target: HTMLDivElement | null) => void;
+}): ReactElement {
+  return (
+    <div
+      ref={targetRef}
+      data-slot="page-shell-actions"
+      className={cn("flex shrink-0 items-center gap-2", className)}
+      {...props}
+    />
+  );
+}
+
+export interface PageShellProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "children"
+> {
+  /** Navegação contextual conhecida pelo shell, normalmente um Breadcrumb. */
+  navigation?: ReactNode;
+  /** Ações do shell ou do recurso que antecedem as ações declaradas pela Page. */
+  actions?: ReactNode;
+  /** Uma Page descendente, diretamente ou através da rota ativa. */
+  children: ReactNode;
+  /** Classes do container interno da barra. */
+  headerClassName?: string;
+}
+
+/** Moldura persistente que coordena navegação do shell e ações da Page ativa. */
+export function PageShell({
+  navigation,
+  actions,
+  children,
+  className,
+  headerClassName,
+  ...props
+}: PageShellProps): ReactElement {
+  const [actionsTarget, setActionsTarget] = useState<HTMLDivElement | null>(null);
+
+  return (
+    <div
+      data-slot="page-shell"
+      className={cn(
+        "relative flex h-full min-h-0 min-w-0 flex-1 flex-col",
+        className,
+      )}
+      {...props}
+    >
+      <SurfaceHeader
+        name="PageShell"
+        slot="page"
+        slots={{
+          leading: PageShellNavigationSlot,
+          title: PageTitle,
+          description: PageDescription,
+          actions: PageShellActionsSlot,
+        }}
+        leadingPlacement="inline"
+        titleRequired={false}
+        contentClassName={cn(
+          pageBarContentClassName,
+          "px-3",
+          headerClassName,
+        )}
+        className={pageBarClassName}
+        data-variant="bar"
+      >
+        <PageShellNavigationSlot>{navigation}</PageShellNavigationSlot>
+        <PageShellActionsSlot targetRef={setActionsTarget}>
+          {actions}
+        </PageShellActionsSlot>
+      </SurfaceHeader>
+      <PageShellContext.Provider value>
+        <PageActionsTarget target={actionsTarget}>
+          <div data-slot="page-shell-content" className="min-h-0 flex-1">
+            {children}
+          </div>
+        </PageActionsTarget>
+      </PageShellContext.Provider>
+    </div>
+  );
+}
 
 export function PageActionsTarget({
   target,
@@ -97,6 +202,7 @@ export function Page({
   children,
   ...props
 }: PageProps): ReactElement {
+  const insideShell = useContext(PageShellContext);
   const shorthand = title !== undefined;
   const nodes = Children.toArray(children);
   const headers = nodes.filter(
@@ -105,6 +211,9 @@ export function Page({
   const bodies = nodes.filter(
     (node) => isValidElement(node) && node.type === PageBody,
   );
+  const intros = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageIntro,
+  );
   const activeStateCount = useRef(0);
   const [integralState, setIntegralState] = useState(false);
   const registerIntegralState = useCallback(() => {
@@ -127,13 +236,22 @@ export function Page({
     );
   }
   if (!shorthand) {
-    if (
-      headers.length !== 1 ||
-      bodies.length !== 1 ||
-      headers.length + bodies.length !== nodes.length
-    ) {
+    const validIntroComposition =
+      intros.length === 1 &&
+      headers.length === 0 &&
+      bodies.length === 1 &&
+      intros.length + bodies.length === nodes.length;
+    const validStandaloneComposition =
+      !insideShell &&
+      headers.length === 1 &&
+      intros.length === 0 &&
+      bodies.length === 1 &&
+      headers.length + bodies.length === nodes.length;
+    if (!validIntroComposition && !validStandaloneComposition) {
       throw new Error(
-        "Page explícito exige exatamente um PageHeader e um PageBody como filhos diretos.",
+        insideShell
+          ? "Page explícito dentro de PageShell exige exatamente um PageIntro e um PageBody como filhos diretos."
+          : "Page explícito exige exatamente um PageHeader ou PageIntro e um PageBody como filhos diretos.",
       );
     }
   }
@@ -146,7 +264,18 @@ export function Page({
     containerClassName: className,
   };
 
-  const content = shorthand ? (
+  const content = shorthand && insideShell ? (
+    <>
+      <PageIntro>
+        <PageTitle>{title}</PageTitle>
+        {description !== undefined && (
+          <PageDescription>{description}</PageDescription>
+        )}
+        {actions !== undefined && <PageActions>{actions}</PageActions>}
+      </PageIntro>
+      <PageBody>{children}</PageBody>
+    </>
+  ) : shorthand ? (
     <>
       <PageHeader>
         <PageTitle>{title}</PageTitle>
@@ -169,6 +298,7 @@ export function Page({
             data-slot="page"
             className={cn(
               "min-w-0 flex-1",
+              insideShell && "min-h-full",
               (headerVariant === "bar" || integralState) && "flex flex-col",
               // A barra contém a rolagem (`min-h-0`); o estado integral ocupa a altura
               // disponível (`min-h-full`). Emitir os dois juntos deixava o resultado por
@@ -198,6 +328,47 @@ export function Page({
   );
 }
 
+/** Introdução opcional do conteúdo, separada da navegação persistente do shell. */
+export function PageIntro({
+  className,
+  children,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  const page = useContext(PageContext);
+  const insideShell = useContext(PageShellContext);
+  const integralState = useContext(PageIntegralStateContext);
+  requireParent(page !== null, "PageIntro", "Page");
+  if (integralState) {
+    if (!insideShell) return <></>;
+    const actions = Children.toArray(children).filter(
+      (node) => isValidElement(node) && node.type === PageActions,
+    );
+    return (
+      <PageHeaderContext.Provider value="intro">
+        {actions}
+      </PageHeaderContext.Provider>
+    );
+  }
+
+  return (
+    <PageHeaderContext.Provider value="intro">
+      <SurfaceHeader
+        name="PageIntro"
+        slot="page-intro"
+        slots={{
+          title: PageTitle,
+          description: PageDescription,
+          actions: PageActions,
+        }}
+        className={className}
+        {...props}
+      >
+        {children}
+      </SurfaceHeader>
+    </PageHeaderContext.Provider>
+  );
+}
+
 /** A anatomia é a de `SurfaceHeader`, a mesma de `ContentHeader`; só os slots mudam de nome. */
 export interface PageHeaderProps extends HTMLAttributes<HTMLDivElement> {
   /** `default` fica no container; `bar` cria uma faixa compacta no topo da Page. */
@@ -228,12 +399,15 @@ export function PageHeader({
         leadingPlacement={variant === "bar" ? "inline" : "above"}
         contentClassName={
           variant === "bar"
-            ? cn("mx-auto w-full max-w-7xl px-8 py-2", page?.containerClassName)
+            ? cn(
+                pageBarContentClassName,
+                "mx-auto max-w-7xl px-8",
+                page?.containerClassName,
+              )
             : undefined
         }
         className={cn(
-          variant === "bar" &&
-            "shrink-0 border-b border-border bg-background text-foreground",
+          variant === "bar" && pageBarClassName,
           className,
         )}
         {...props}
@@ -249,14 +423,16 @@ export function PageTitle({
   ...props
 }: HTMLAttributes<HTMLHeadingElement>): ReactElement {
   const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageTitle", "PageHeader");
+  requireParent(variant !== null, "PageTitle", "PageHeader ou PageIntro");
   return (
     <h1
       data-slot="page-title"
       className={cn(
         variant === "bar"
           ? "truncate text-sm font-semibold"
-          : surfaceHeaderClasses.page.title,
+          : variant === "intro"
+            ? "text-3xl font-semibold tracking-tight"
+            : surfaceHeaderClasses.page.title,
         className,
       )}
       {...props}
@@ -269,7 +445,11 @@ export function PageDescription({
   ...props
 }: HTMLAttributes<HTMLParagraphElement>): ReactElement {
   const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageDescription", "PageHeader");
+  requireParent(
+    variant !== null,
+    "PageDescription",
+    "PageHeader ou PageIntro",
+  );
   return (
     <p
       data-slot="page-description"
@@ -289,13 +469,14 @@ export function PageActions({
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
   const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageActions", "PageHeader");
+  requireParent(variant !== null, "PageActions", "PageHeader ou PageIntro");
   const target = useContext(PageActionsTargetContext);
+  const insideShell = useContext(PageShellContext);
   const actions = (
     <div
       data-slot="page-actions"
       className={cn(
-        variant === "bar"
+        variant === "bar" || insideShell
           ? "flex shrink-0 items-center gap-2"
           : surfaceHeaderClasses.page.actions,
         className,
@@ -303,6 +484,7 @@ export function PageActions({
       {...props}
     />
   );
+  if (insideShell && target === null) return <></>;
   return target === null ? actions : createPortal(actions, target);
 }
 

package/src/ui/components/patterns/surface-header.tsx

@@ -57,6 +57,8 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
   leadingPlacement?: "above" | "inline";
   /** Classes de um container interno quando a moldura precisa ocupar toda a largura. */
   contentClassName?: string;
+  /** Permite uma superfície composta apenas pelas regiões leading/actions. */
+  titleRequired?: boolean;
 }
 
 /** Expande fragments de primeiro nível: o shorthand monta os slots dentro de um `<>`. */
@@ -74,6 +76,7 @@ export function SurfaceHeader({
   slots,
   leadingPlacement = "above",
   contentClassName,
+  titleRequired = true,
   className,
   children,
   ...props
@@ -100,7 +103,7 @@ export function SurfaceHeader({
     actionSlots.length;
 
   if (
-    titles.length !== 1 ||
+    (titleRequired ? titles.length !== 1 : titles.length > 1) ||
     leading.length > 1 ||
     counts.length > 1 ||
     descriptions.length > 1 ||
@@ -130,11 +133,11 @@ export function SurfaceHeader({
     throw new Error(
       distinctLeading.size > 1
         ? `${name} aceita ${[...distinctLeading].map(label).join(" ou ")} na região introdutória, nunca os dois na mesma superfície.`
-        : `${name} exige um ${label(slots.title)} e aceita no máximo um de cada: ${optionalSlots}.`,
+        : `${name} ${titleRequired ? `exige um ${label(slots.title)}` : `aceita no máximo um ${label(slots.title)}`} e aceita no máximo um de cada: ${optionalSlots}.`,
     );
   }
 
-  const heading = (
+  const heading = titles.length + counts.length + descriptions.length > 0 && (
     <div
       data-slot={`${slot}-heading`}
       className={cn("min-w-0", leadingPlacement === "inline" && "flex-1")}
@@ -153,7 +156,13 @@ export function SurfaceHeader({
       {leadingPlacement === "inline" && leading.length > 0 && (
         // `min-w-0` aqui é o que deixa a trilha do PageNavigation ceder e truncar; sem ele o
         // wrapper assume o min-content do breadcrumb e a compressão toda cai sobre o título.
-        <div data-slot={`${slot}-navigation`} className="flex min-w-0 items-center">
+        <div
+          data-slot={`${slot}-navigation`}
+          className={cn(
+            "flex min-w-0 items-center",
+            !heading && "flex-1",
+          )}
+        >
           {leading}
         </div>
       )}

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

@@ -1,22 +1,24 @@
 ## Esqueleto de página
 
-Use `Page` para manter navegação contextual, título, ações e conteúdo na mesma anatomia. O
-`PageHeader` padrão acompanha o conteúdo dentro do container; `variant="bar"` transforma o mesmo
-cabeçalho em uma faixa compacta no topo. Não monte um chrome paralelo para repetir essas regiões.
+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, a página fornece as ações e o título passa a
+`PageIntro` dentro do conteúdo.
 
 Em larguras amplas, as ações ficam no extremo oposto e acompanham a base do título e da descrição;
 em larguras estreitas, passam para uma linha abaixo. 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. Ela cria internamente `PageHeader` e `PageBody`;
-portanto, não produz uma estrutura visual ou semântica diferente da forma explícita. O cabeçalho é a
-mesma base estrutural de `Content`, mas reconhece somente título, descrição e ações. Contadores e
-outros indicadores pertencem ao conteúdo que os explica.
+A forma curta é o padrão para páginas comuns. Fora de `PageShell`, ela cria `PageHeader` e
+`PageBody`. Dentro dele, cria `PageIntro` e `PageBody`, enquanto envia as ações para a barra. A forma
+explícita permite escolher a região adequada: `PageHeader` reúne navegação e contexto; `PageIntro`
+dá mais presença ao título dentro do conteúdo. Contadores e outros indicadores pertencem ao
+conteúdo que os explica.
 
-`Page` também pode ocupar o painel principal de um shell com sidebar. Tabs ficam reservados a
-recortes da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell
-próprio quando o cabeçalho reduzir a área útil ou duplicar controles persistentes.
+`PageShell` não inclui sidebar nem inventa breadcrumb. Ele ocupa o painel principal já delimitado e
+mantém a barra com `3rem`, mesmo quando o conteúdo muda de estado. Tabs ficam reservados a recortes
+da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell próprio.
 
 Estados integrais de carregamento, falha ou ausência são compostos no body com `PageState`,
 detalhado abaixo. `Page` não recebe flags de dados: uma página pode agregar fontes independentes e
@@ -63,13 +65,63 @@ Não combine `PageBack` com breadcrumb. Use o retorno para um único pai conheci
 mais de um ancestral relevante, envolva o `Breadcrumb` em `PageNavigation`; ele ocupa a mesma
 posição introdutória sem transformar a trilha em ação.
 
-## Cabeçalho em barra
+## Barra persistente do shell
 
-Use `variant="bar"` quando título, retorno e ações precisarem formar uma faixa compacta e persistente
-no topo da página. `Page` estende a borda por toda a largura e mantém o conteúdo da barra alinhado ao
-mesmo teto do body. Nesse modo, `PageBack` vira icon-only e recebe tooltip e nome acessível “Voltar
-para {destino}”. Mantenha também as ações compactas: use `sm` em botões com texto e `icon-sm` em
-botões que exibem somente um ícone.
+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 `PageActions` na barra e
+transforma a introdução da forma curta em `PageIntro`.
+
+```tsx preview col
+<PageShell
+  navigation={
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>Vendas</BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbPage>Clientes</BreadcrumbPage>
+      </BreadcrumbList>
+    </Breadcrumb>
+  }
+>
+  <Page
+    title="Clientes"
+    actions={
+      <Button size="sm">
+        <Plus /> Novo cliente
+      </Button>
+    }
+  >
+    Conteúdo da listagem.
+  </Page>
+</PageShell>
+```
+
+A barra permanece visível durante `PageState`; somente a introdução 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 `PageIntro` e `PageBody`:
+
+```tsx preview col
+<PageShell navigation={<Breadcrumb>...</Breadcrumb>}>
+  <Page>
+    <PageIntro>
+      <PageTitle>Clientes</PageTitle>
+      <PageDescription>Cadastros disponíveis para atendimento.</PageDescription>
+      <PageActions>
+        <Button size="sm">Novo cliente</Button>
+      </PageActions>
+    </PageIntro>
+    <PageBody>Conteúdo da listagem.</PageBody>
+  </Page>
+</PageShell>
+```
+
+## Cabeçalho em barra da própria Page
+
+Use `PageHeader variant="bar"` quando uma página autocontida conhecer título, retorno e ações. Essa
+forma continua útil fora de um shell persistente. `PageBack` vira icon-only e recebe tooltip e nome
+acessível “Voltar para {destino}”. Use `sm` em botões com texto e `icon-sm` em botões somente com
+ícone.
 
 ```tsx preview col
 <Page className="max-w-none">
@@ -86,11 +138,8 @@ botões que exibem somente um ícone.
 </Page>
 ```
 
-Uma página comum não ganha a barra apenas por estar dentro de um shell. Escolha essa variante quando
-a faixa acrescentar contexto ou ações persistentes; sem isso, mantenha o header padrão.
-
-`PageActionsTarget` continua disponível para um workspace imersivo que já possua um chrome próprio.
-Ele projeta somente `PageActions` no elemento informado; não cria uma segunda região de cabeçalho.
+Não aninhe essa variante em `PageShell`, que já possui a barra. `PageActionsTarget` continua
+disponível para um workspace imersivo que tenha chrome próprio e não use `PageShell`.
 
 ## Composição explícita
 
@@ -118,16 +167,21 @@ render(
 );
 ```
 
+Use `PageIntro` no lugar de `PageHeader` quando a página precisar apenas de uma introdução no
+conteúdo, sem navegação própria. Dentro de `PageShell`, essa é a única composição explícita válida;
+fora dele, as duas formas são aceitas porque cumprem papéis diferentes.
+
 ## Estados integrais
 
 Use `PageState` quando carregamento, falha ou ausência substituírem todo o conteúdo principal. Na
 forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
 explícita, coloque-o sozinho dentro de `PageBody`. Enquanto `status` for `loading`, `error` ou
-`empty`, `Page` oculta o cabeçalho inteiro — incluindo o `PageBack` — e o estado ocupa a altura
-disponível. Uma subpágina que dependa desse retorno oferece a saída pelo `action` do próprio
+`empty`, uma `Page` isolada oculta o cabeçalho inteiro — incluindo `PageBack` — e o estado ocupa a
+altura disponível. Dentro de `PageShell`, a barra persistente permanece e somente `PageIntro` é
+ocultado. Uma subpágina isolada que dependa do retorno oferece a saída pelo `action` do próprio
 `PageState`. O título do estado assume o heading principal. Esse registro também funciona quando um
-componente intermediário decide qual `PageState` renderizar. Em `ready`, o cabeçalho e o conteúdo
-voltam à composição normal.
+componente intermediário decide qual `PageState` renderizar. Em `ready`, o cabeçalho ou a introdução
+e o conteúdo voltam à composição normal.
 
 ```tsx preview col
 <Page title="Relatório">
@@ -172,6 +226,25 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | `className`   | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
 | `children`    | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
 
+## Propriedades de PageShell
+
+| Propriedade       | Tipo                          | Descrição                                                              |
+| ----------------- | ----------------------------- | ---------------------------------------------------------------------- |
+| `navigation`      | `ReactNode`                   | Navegação contextual da barra, normalmente um `Breadcrumb`.            |
+| `actions`         | `ReactNode`                   | Ações conhecidas pelo shell, antes das ações declaradas pela `Page`.    |
+| `children`        | `ReactNode`                   | Rota que renderiza uma `Page` descendente.                              |
+| `headerClassName` | `string`                      | Classes adicionais do container interno da barra.                      |
+| `className`       | `string`                      | Classes adicionais da moldura.                                         |
+| demais            | Atributos de `HTMLDivElement` | Atributos nativos repassados à moldura.                                 |
+
+## Propriedades de PageIntro
+
+| Propriedade | Tipo                          | Descrição                                                        |
+| ----------- | ----------------------------- | ---------------------------------------------------------------- |
+| `children`  | `ReactNode`                   | Um `PageTitle` e, opcionalmente, descrição e ações da página.     |
+| `className` | `string`                      | Classes adicionais da região introdutória.                       |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região introdutória.               |
+
 ## Propriedades de PageHeader
 
 | Propriedade | Tipo                   | Padrão      | Descrição                                                        |
@@ -202,7 +275,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade | Tipo                              | Descrição                                              |
 | ----------- | --------------------------------- | ------------------------------------------------------ |
-| `children`  | `ReactNode`                       | Título principal `h1`; compacto na variante `bar`.     |
+| `children`  | `ReactNode`                       | Título principal `h1`; compacto na barra e ampliado em `PageIntro`. |
 | `className` | `string`                          | Classes adicionais do título.                          |
 | demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.                |
 

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, descrição e ações; a forma explícita acrescenta PageBack para retorno simples ou PageNavigation para uma trilha e permite `PageHeader variant=\"bar\"` quando a mesma anatomia precisar virar uma faixa compacta. No header padrão, PageBack fica acima do título; na barra, vira icon-only com tooltip. PageActionsTarget fica restrito a workspaces imersivos com chrome próprio. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState: ele oculta o header e ocupa a área disponível, centralizado e sem moldura. 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, descrição 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; título e descrição formam PageIntro no conteúdo. Fora dele, a forma explícita escolhe PageHeader para o cabeçalho completo ou PageIntro para uma introdução sem navegação; `PageHeader variant=\"bar\"` atende uma página autocontida. PageActionsTarget fica restrito a workspaces imersivos sem PageShell. PageState oculta o header da Page isolada ou somente PageIntro dentro de PageShell. Para uma região disponível à criação ou vínculo, use Empty.",
   },
   router: {
     name: "router",

package/src/ui/react.tsx

@@ -421,8 +421,10 @@ export type { DataStateProps } from "./components/patterns/data-state.tsx";
 
 // Esqueleto de página do back-office (main + container + header título/descrição/ação).
 export {
+  PageShell,
   Page,
   PageHeader,
+  PageIntro,
   PageNavigation,
   PageBack,
   PageTitle,
@@ -433,6 +435,7 @@ export {
 } from "./components/patterns/page.tsx";
 export type {
   PageProps,
+  PageShellProps,
   PageBackProps,
   PageHeaderProps,
   PageHeaderVariant,