@softize/opus 17.1.0 → 17.2.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "17.1.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,13 +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.
+  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 > PageHeader (PageNavigation?, PageTitle, PageActions?) + PageBody`, com
-  `PageIntro` opcional antes do body. Não monte
+  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/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

@@ -148,18 +148,16 @@ function PresentationFrame({
     if (insidePageShell) {
       return (
         <Page className={cn("flex min-h-full flex-col", className)}>
-          <PageHeader>
+          <PageIntro>
             {navigation === undefined ? null : (
               <PageNavigation>{navigation}</PageNavigation>
             )}
+            <PageTitle>{title}</PageTitle>
             {headerActions === undefined ? null : (
               <PageActions>
                 <PresentationActions>{headerActions}</PresentationActions>
               </PageActions>
             )}
-          </PageHeader>
-          <PageIntro>
-            <PageTitle>{title}</PageTitle>
           </PageIntro>
           <PageBody className="min-h-0 flex-1 overflow-y-auto">{body}</PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}

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
@@ -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>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/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",