@softize/opus 24.0.0 → 24.1.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ 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.
 
+## 24.1.0 — 2026-10-02
+
+O `Markdown` deixa de carregar imagem com endereço absoluto (`https:`, `http:` ou `//host`). No
+lugar dela fica o texto alternativo, num `span` com `data-slot="markdown-external-image"`, sem link.
+O conteúdo vem de modelo, e um `<img>` é buscado pelo navegador sem clique: um modelo induzido por
+injeção de prompt poderia levar dados da conversa no endereço da imagem (ADR 0050). Imagem com
+endereço relativo e as imagens `data:` que o markdown-it já aceitava continuam renderizando. A
+regra vale para a instância compartilhada, então chat, painéis e documentação mudam juntos. Quem
+exibia imagem absoluta da própria origem passa a usar o endereço relativo.
+
+## 24.0.1 — 2026-10-01
+
+Em `DialogHeader` e `DrawerHeader` com navegação e título, os dois passam a formar um grupo com
+intervalo de `0.5rem`. Antes, o voltar ou o recolher ficava a `1rem` do título, a mesma distância
+que separa o título das ações. As ações e o botão de fechar continuam fora do grupo, separados pelo
+intervalo da família, e a mídia mantém a distância que já tinha até o título (ADR 0049). A API não
+muda. Nessa combinação, a navegação passa a ficar dentro de `dialog-header-context` ou
+`drawer-header-context`; seletores que exigiam um filho direto de `dialog-header-row` ou
+`drawer-header-row` precisam usar o descendente, e seletores pelo `data-slot` da navegação
+continuam válidos.
+
+A documentação ganha a página **UI > Design > Composições**, que mostra como montar `Page`,
+`Dialog`, `Drawer` e `Surface` com cabeçalho, corpo e rodapé, onde cada ação fica e quando o título
+vai no cabeçalho ou na intro. A mesma tarefa aparece em cada superfície; `Dialog` e `Drawer`
+aparecem nos layouts `sectioned` e `continuous`, e um exemplo de `Pane` mostra a `Surface` completa
+dentro de um `Split`. As páginas de `Page`, `Dialog`, `Drawer` e `Pane` apontam para a nova
+referência no ponto em que a escolha aparece.
+
 ## 24.0.0 — 2026-10-01
 
 `ToggleGroup` passa a compartilhar a gramática estrutural de `ButtonGroup`: `mode` aceita

package/docs/adr/0049-inline-navigation-groups-with-the-heading.md

@@ -0,0 +1,95 @@
+# ADR 0049 — Navegação inline forma um grupo com o título
+
+- **Status:** aceita.
+- **Data:** 2026-10-01.
+- **Complementa:** ADR 0023, quanto à linha do cabeçalho de Dialog e Drawer; ADR 0048, quanto ao
+  formato compacto, com título no cabeçalho.
+
+## Contexto
+
+`StructuralHeader` monta a linha do cabeçalho de Dialog e Drawer com `leadingPlacement="inline"`:
+a navegação abre a linha, a mídia e o título vêm em seguida, as ações ficam no extremo oposto e o
+botão de fechar entra por último. Até a 24.0.0, todos esses nós eram irmãos da mesma linha flex e
+recebiam o intervalo da família, que em Dialog e Drawer é `gap-4` (`1rem`).
+
+Com um único intervalo, o voltar ou o recolher ficava tão longe do título quanto o título ficava das
+ações. A proximidade não distinguia duas relações diferentes:
+
+- a navegação diz de onde a pessoa veio ou como sair da etapa, e só faz sentido lida junto com o
+  nome da tela;
+- as ações operam sobre a superfície inteira e formam um conjunto próprio, com ritmo interno denso
+  (`gap-2`, de `surfaceActionsClasses`).
+
+A ADR 0048 fixou a escolha entre a intro e o formato compacto, em que o título permanece no
+cabeçalho. A página **Composições** passou a mostrar as duas formas lado a lado, e a distância
+uniforme ficou evidente no Drawer compacto, em que o recolher do painel precede o título.
+
+## Decisão
+
+Quando um `StructuralHeader` com `leadingPlacement="inline"` recebe navegação e heading, os dois
+formam um grupo contextual:
+
+1. Um wrapper `data-slot="<slot>-header-context"` (`flex min-w-0 flex-1 items-center gap-2`)
+   envolve a navegação e o heading. O intervalo entre eles passa a ser `gap-2` (`0.5rem`).
+2. As ações e o botão de fechar ficam fora do grupo, como irmãos dele na linha
+   `<slot>-header-row`, e continuam separados pelo intervalo da família (`gap-4` em Dialog e
+   Drawer). O ritmo interno das ações não muda.
+3. O grupo ocupa a folga (`flex-1`) e aceita compressão (`min-w-0`): as ações seguem no extremo
+   oposto e o título continua truncando quando não cabe.
+4. Quando há mídia na linha, mídia e heading ficam num wrapper `<slot>-header-identity` que
+   reaplica as classes da linha da família. A aproximação vale só entre a navegação e o que vem
+   depois dela; a distância da mídia até o título é a mesma que existiria sem navegação.
+5. A navegação mantém `data-slot="<slot>-navigation"` dentro do grupo, para que seletores de teste
+   e de CSS continuem encontrando a região nas duas apresentações.
+
+Fora dessa combinação nada muda: navegação sem título, título sem navegação,
+`leadingPlacement="above"`, usado pela `Page`, e o `Dialog mode="alert"`, cujo cabeçalho não usa
+`StructuralHeader`. `SurfaceHeader` não tem slot de navegação, e as intros (`DialogIntro` e
+`DrawerIntro`) também não aceitam navegação.
+
+A regra mora uma vez em `structural-header.tsx`. Dialog e Drawer a herdam porque ambos declaram
+`leadingPlacement="inline"` e passam `surfaceHeaderRowClasses(family)` como `rowClassName`; nenhuma
+família reescreve o intervalo.
+
+## Consequências
+
+- Em Dialog e Drawer com navegação e título, o voltar ou o recolher passa de `1rem` para `0.5rem`
+  do título, ou da mídia que o antecede. Ações e fechamento mantêm a mesma posição e o mesmo ritmo.
+- A API pública não muda, por isso a correção sai como patch (24.0.1).
+- O DOM ganha um nível nessa combinação, e dois quando há mídia: a navegação deixa de ser filha
+  direta de `<slot>-header-row` e passa a ser filha de `<slot>-header-context`. Seletores que
+  dependiam do filho direto, como `[data-slot=drawer-header-row] > [data-slot=drawer-navigation]`,
+  precisam usar o descendente; seletores pelo `data-slot` da navegação continuam válidos.
+- Uma família nova que adote a linha inline com navegação herda o agrupamento sem configuração. Se
+  ela precisar de outra relação entre navegação e título, a mudança é desta ADR, não de um
+  `className` local.
+
+## Alternativas consideradas
+
+- **Manter o intervalo único.** Não exige mudança, mas iguala duas relações diferentes.
+  Descartada.
+- **Reduzir o intervalo da linha inteira para `gap-2`.** Aproximaria navegação e título, mas também
+  aproximaria as ações do título, que é a separação que a família precisa preservar. Descartada.
+- **Ajustar a margem no slot de navegação de cada família**, por exemplo com `-mr-2` em
+  `DrawerNavigation`. Resolveria o caso visual, mas espalharia uma decisão da anatomia
+  compartilhada por cada família e dependeria de compensar um intervalo que continua existindo.
+  Descartada.
+- **Levar a navegação para dentro do wrapper do heading.** Misturaria uma região de controle com o
+  bloco que nomeia a superfície e mudaria o elemento que absorve a compressão do título. Descartada.
+- **Aplicar `gap-2` também entre mídia e título quando houver navegação.** Seria mais simples, mas
+  faria a distância da mídia até o título depender da presença da navegação. Descartada.
+- **Expor o intervalo como propriedade pública.** Abriria uma variação por consumidor para uma
+  relação que deve ser igual em todas as superfícies. Descartada.
+
+## Verificação
+
+- `tests/ui/drawer.test.tsx` fixa a regra no Drawer: com navegação, título e ações, a linha mantém
+  `gap-4`, o grupo `drawer-header-context` usa `gap-2` e contém o título, `drawer-actions` mantém
+  `gap-2` e não há wrapper de identidade sem mídia. Com mídia, `drawer-header-identity` fica dentro
+  do grupo, mantém `gap-4` e reúne mídia e título, sem a navegação.
+- `tests/ui/dialog.test.tsx` cobre a mesma regra no Dialog com navegação, mídia, título e ações,
+  inclusive as ações como filhas diretas da linha, fora do grupo.
+- Os testes existentes cobrem as combinações que não mudam: navegação e ações sem título continuam
+  na mesma linha, e ações isoladas continuam no extremo final.
+- Na página **UI > Design > Composições**, o Drawer compacto exibe o recolher e o título no
+  cabeçalho e serve de verificação visual da regra.

package/docs/adr/0050-markdown-does-not-load-external-images.md

@@ -0,0 +1,64 @@
+# ADR 0050 — Markdown não carrega imagem externa
+
+- **Status:** aceita.
+- **Data:** 2026-10-02.
+- **Complementa:** a decisão registrada em `markdown.tsx` de renderizar com `html: false`, porque o
+  conteúdo vem de pessoas e de modelos.
+
+## Contexto
+
+O `Markdown` é o renderer único do pacote: o chat, os painéis e a documentação usam a mesma
+instância do markdown-it. Ele já escapa HTML do fonte e o markdown-it já recusa links
+`javascript:` e `data:text/html`. Faltava uma terceira via: `![](https://host/x.png?d=…)` virava um
+`<img>` que o navegador busca sozinho, sem nenhum clique.
+
+Isso importa porque boa parte desse conteúdo é escrita por um modelo. Um modelo induzido por
+injeção de prompt (um documento, uma resposta de ferramenta, uma mensagem de terceiro) pode montar
+o endereço de uma imagem com dados da conversa e deixar que o navegador de quem lê os entregue ao
+host. Num relatório salvo, isso acontece também com quem abre o relatório depois.
+
+Nenhum consumidor conhecido depende de imagem externa no Markdown: a documentação do pacote não usa
+imagem em Markdown, e a plataforma Grand Brasil não tem imagem externa em documentos, Base de
+conhecimento nem relatórios.
+
+## Decisão
+
+1. O `Markdown` não renderiza `<img>` para endereço absoluto, com esquema (`https:`, `http:`) ou
+   relativo ao protocolo (`//host`). No lugar da imagem fica o texto alternativo dela, num
+   `span` com `data-slot="markdown-external-image"`, sem link: seguir o endereço exigiria um
+   clique, mas um link montado pelo modelo não deve ser oferecido como se fosse da imagem.
+2. Endereço relativo (`/caminho`, `./arquivo.png`) continua renderizando a imagem, porque é servido
+   pela própria aplicação. As imagens em `data:` que o markdown-it já aceita (`png`, `gif`, `jpeg`,
+   `webp`) também continuam: não fazem requisição.
+3. A regra vale para a instância compartilhada `markdownIt`, então chat, painéis e documentação
+   seguem o mesmo comportamento. Não há opção para liberar imagem externa; um consumidor que
+   precise disso traz o caso concreto para uma decisão nova.
+
+## Consequências
+
+- Uma resposta ou um relatório com imagem externa mostra o texto alternativo no lugar da imagem.
+- A defesa não depende de cada aplicação configurar uma Content Security Policy com `img-src`,
+  embora uma CSP continue sendo uma segunda camada recomendada.
+- Imagem absoluta da própria origem também deixa de carregar. Não há uso conhecido; se aparecer,
+  o caminho é usar o endereço relativo.
+- A imagem relativa continua fazendo uma requisição à própria origem, com os cookies de quem lê. Se
+  a aplicação tiver um redirecionamento aberto ou um proxy de imagem, o mesmo vetor volta por ali.
+  É mais um motivo para manter a CSP com `img-src` como segunda camada.
+
+## Alternativas consideradas
+
+- **Bloquear toda imagem.** Fecharia também o resíduo da imagem relativa, mas tiraria imagens que a
+  própria aplicação serve (anexos, ilustrações de documentação) sem um vetor conhecido que o
+  justifique hoje.
+- **Transformar a imagem externa em link.** Mantém o endereço acessível, mas oferece com aparência
+  legítima um link montado pelo modelo; o texto alternativo basta para a leitura.
+- **Lista de origens permitidas ou proxy de imagem.** Exigiriam configuração por aplicação e um
+  serviço novo para um uso que não existe. Ficam para quando um consumidor trouxer o caso.
+- **Só CSP na aplicação.** Depende de cada consumidor configurar e não vale fora do navegador da
+  aplicação (por exemplo, na documentação publicada). Fica como segunda camada, não como a defesa.
+
+## Verificação
+
+- Teste do `Markdown`: imagem `https:`, `//host`, com maiúsculas, com esquema em entidade, por
+  referência, dentro de link e em célula de tabela não geram `<img>` e mostram o texto alternativo;
+  imagem relativa e `data:image/png` continuam gerando `<img>`.

package/package.json

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

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

@@ -230,20 +230,52 @@ export function StructuralHeader({
   );
   // A região introdutória carrega o mesmo `data-slot` nas duas apresentações: seletor de teste
   // ou de CSS que funcione no header padrão precisa funcionar na barra.
-  const row = (
-    <>
-      {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.
+  // Navegação e título formam um contexto com intervalo de 0,5rem (ADR 0049). O intervalo da
+  // linha continua separando esse contexto das ações, e a mídia mantém, até o título, o mesmo
+  // intervalo que teria sem navegação.
+  const rowMedias = mediaPlacement === "row" ? medias : [];
+  const inlineContext =
+    leadingPlacement === "inline" && leading.length > 0 && heading ? (
+      <Wrapper
+        data-slot={`${slot}-header-context`}
+        className="flex min-w-0 flex-1 items-center gap-2"
+      >
         <Wrapper
           data-slot={`${slot}-navigation`}
-          className={cn("flex min-w-0 items-center", !heading && "flex-1")}
+          className="flex min-w-0 items-center"
         >
           {leading}
         </Wrapper>
-      )}
-      {mediaPlacement === "row" && medias}
-      {heading}
+        {rowMedias.length > 0 ? (
+          <Wrapper
+            data-slot={`${slot}-header-identity`}
+            className={cn("flex min-w-0 items-center gap-3", rowClassName)}
+          >
+            {rowMedias}
+            {heading}
+          </Wrapper>
+        ) : (
+          heading
+        )}
+      </Wrapper>
+    ) : null;
+  const row = (
+    <>
+      {inlineContext}
+      {inlineContext === null &&
+        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.
+          <Wrapper
+            data-slot={`${slot}-navigation`}
+            className={cn("flex min-w-0 items-center", !heading && "flex-1")}
+          >
+            {leading}
+          </Wrapper>
+        )}
+      {inlineContext === null && mediaPlacement === "row" && medias}
+      {inlineContext === null && heading}
       {!heading && leading.length === 0 && (
         <Wrapper
           data-slot={`${slot}-header-spacer`}

package/src/ui/components/primitives/markdown.tsx

@@ -17,6 +17,23 @@ import MarkdownIt from 'markdown-it'
  *  opções próprias divergiriam no primeiro edge case, e "mesmo motor" viraria promessa. */
 export const markdownIt = new MarkdownIt({ html: false, linkify: true })
 
+/**
+ * Imagem com endereço absoluto não carrega (ADR 0050). O conteúdo vem de modelo, e um `<img>` é
+ * buscado pelo navegador sem clique: um modelo induzido por injeção de prompt poderia levar dados
+ * da conversa no endereço. Fica o texto alternativo; imagem relativa e `data:` seguem normais.
+ */
+const EXTERNAL_IMAGE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i
+const renderImage = markdownIt.renderer.rules.image
+markdownIt.renderer.rules.image = (tokens, idx, options, env, self) => {
+  const token = tokens[idx]!
+  const src = token.attrGet('src') ?? ''
+  if (EXTERNAL_IMAGE.test(src) && !src.toLowerCase().startsWith('data:')) {
+    const alt = self.renderInlineAsText(token.children ?? [], options, env)
+    return `<span data-slot="markdown-external-image">${markdownIt.utils.escapeHtml(alt)}</span>`
+  }
+  return renderImage!(tokens, idx, options, env, self)
+}
+
 export interface MarkdownProps {
   content: string
   className?: string

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

@@ -0,0 +1,479 @@
+---
+title: Composições
+---
+
+# Composições
+
+Use esta página para decidir como montar uma tela antes de escolher as propriedades de cada
+componente. `Page`, `Dialog`, `Drawer` e `Surface` se organizam da mesma forma: um cabeçalho, um
+corpo e um rodapé com a decisão da etapa. Cada família admite as ações e a navegação indicadas na
+tabela abaixo. Em `Page`, `Dialog` e `Drawer`, o corpo também pode começar por uma intro que leva o
+título. `Pane` fica fora dessa organização: ele só reserva, dentro de um `Split`, o espaço em que
+uma `Surface` aparece.
+
+Todos os exemplos mostram a mesma tarefa, editar uma ordem de serviço, em superfícies diferentes.
+As propriedades de cada componente ficam nas páginas da família: [`Page`](/ui/page),
+[`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer), [`Surface`](/ui/surface) e [`Pane`](/ui/pane).
+
+## As regiões de cada superfície
+
+Cada família dá um nome próprio a cada região. A tabela mostra a correspondência entre elas.
+
+| Região               | Page                                        | Dialog                        | Drawer                        | Surface                       |
+| -------------------- | ------------------------------------------- | ----------------------------- | ----------------------------- | ----------------------------- |
+| Navegação            | `PageNavigation` ou `PageBack`              | `DialogNavigation`            | `DrawerNavigation`            | Não existe                    |
+| Título no cabeçalho  | `PageTitle`                                 | `DialogTitle`                 | `DrawerTitle`                 | `SurfaceTitle`                |
+| Ações do cabeçalho   | `PageActions`                               | `DialogActions`               | `DrawerActions`               | `SurfaceActions`              |
+| Intro                | `Surface level={1}` no início do `PageBody` | `DialogIntro`                 | `DrawerIntro`                 | Não existe                    |
+| Ações da intro       | Ações da `Surface level={1}`                | `DialogIntroActions`          | `DrawerIntroActions`          | Não existe                    |
+| Corpo                | `PageBody`                                  | `DialogBody`                  | `DrawerBody`                  | `SurfaceBody`                 |
+| Rodapé               | `PageFooter`                                | `DialogFooter`                | `DrawerFooter`                | `SurfaceFooter`               |
+| Divisores            | Antes do `PageFooter`                       | `sectioned` (padrão)          | `sectioned` (padrão)          | `sectioned`                   |
+| Sem divisores        | Cabeçalho e corpo                           | `continuous`                  | `continuous`                  | `continuous` (padrão)         |
+
+`layout` escolhe entre as duas anatomias em `DialogContent`, `DrawerContent` e `Surface`. Em
+`sectioned`, uma linha separa as regiões vizinhas; em `continuous`, o espaço faz essa separação. Na
+`Surface`, `sectioned` exige `framed` ou `elevation="raised"`, para que a linha tenha um limite. A
+`Page` não oferece anatomia `sectioned`: cabeçalho e corpo são contínuos, enquanto o `PageFooter`
+é uma faixa própria, separada por sua borda superior. O `layout` da página decide apenas a ocupação
+de altura.
+
+## Onde cada ação fica
+
+A posição de uma ação informa a que ela se refere. Escolha o lugar pelo alcance da ação, não pelo
+espaço livre na tela.
+
+| Lugar      | Use para                                                                                                   |
+| ---------- | ---------------------------------------------------------------------------------------------------------- |
+| Navegação  | Sair ou voltar na estrutura: a trilha da página, a etapa anterior de um fluxo modal ou recolher o painel.  |
+| Cabeçalho  | Ações que valem para a superfície inteira, como abrir uma conversa sobre o registro.                       |
+| Intro      | Ações ligadas ao título e ao conteúdo, como ver o histórico do registro.                                    |
+| Rodapé     | A decisão da etapa: **Cancelar** em `ghost` e a ação principal sólida, alinhadas à direita.                |
+
+Em `Dialog` e `Drawer`, a navegação abre a linha do cabeçalho e fica junto do título, a `0.5rem`
+dele. As ações ficam no extremo oposto, antes do botão de fechar, e mantêm a distância maior da
+família até o título. Na `Page`, a navegação fica acima do título; quando o título está na intro,
+ela divide a linha com as ações da página.
+
+Em `Dialog` e `Drawer`, cabeçalho e rodapé permanecem visíveis enquanto o corpo rola; a intro rola
+junto com o conteúdo.
+
+## Título no cabeçalho ou na intro
+
+O título pode ficar em dois lugares, e essa escolha define a composição:
+
+- **Com intro:** o cabeçalho guarda só a navegação, as ações da superfície e o fechamento. O título
+  abre o corpo junto das ações do conteúdo. Use quando esses controles da superfície precisam
+  continuar estáveis e separados do registro aberto.
+- **Compacta:** título, ações do conteúdo e ações da superfície dividem a linha do cabeçalho, e a
+  intro é omitida. Use quando uma linha basta para nomear a tarefa e agir sobre ela.
+
+Na composição compacta, coloque as ações do conteúdo antes das ações da superfície, no mesmo slot de
+ações. Em `Dialog` e `Drawer`, o título no cabeçalho trunca quando não cabe na linha; na intro, ele
+usa uma escala maior e quebra em mais de uma linha.
+
+## Dialog
+
+Abra cada combinação para comparar. As linhas trocam o `layout` de `DialogContent`; as colunas
+trocam o lugar do título. O campo e o rodapé são os mesmos nos quatro casos.
+
+```tsx preview
+function OrderField() {
+  const id = useId();
+  return (
+    <div className="space-y-2">
+      <Label htmlFor={id}>Responsável</Label>
+      <Input id={id} defaultValue="Marina Alves" />
+    </div>
+  );
+}
+
+function DialogWithIntro({ layout, label }) {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline">{label}</Button>
+      </DialogTrigger>
+      <DialogContent layout={layout}>
+        <DialogHeader>
+          <DialogActions>
+            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+              <MessageCircle />
+            </Button>
+          </DialogActions>
+        </DialogHeader>
+        <DialogBody>
+          <DialogIntro>
+            <DialogTitle>Editar ordem de serviço</DialogTitle>
+            <DialogIntroActions>
+              <Button variant="outline" size="sm">
+                Ver histórico
+              </Button>
+            </DialogIntroActions>
+          </DialogIntro>
+          <OrderField />
+        </DialogBody>
+        <DialogFooter>
+          <ButtonGroup mode="spaced">
+            <DialogClose asChild>
+              <Button variant="ghost">Cancelar</Button>
+            </DialogClose>
+            <Button>Salvar</Button>
+          </ButtonGroup>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function CompactDialog({ layout, label }) {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline">{label}</Button>
+      </DialogTrigger>
+      <DialogContent layout={layout}>
+        <DialogHeader>
+          <DialogMedia>
+            <Wrench />
+          </DialogMedia>
+          <DialogTitle>Editar ordem de serviço</DialogTitle>
+          <DialogActions>
+            <Button variant="outline" size="sm">
+              Ver histórico
+            </Button>
+            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+              <MessageCircle />
+            </Button>
+          </DialogActions>
+        </DialogHeader>
+        <DialogBody>
+          <OrderField />
+        </DialogBody>
+        <DialogFooter>
+          <ButtonGroup mode="spaced">
+            <DialogClose asChild>
+              <Button variant="ghost">Cancelar</Button>
+            </DialogClose>
+            <Button>Salvar</Button>
+          </ButtonGroup>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+render(
+  <div className="grid grid-cols-2 gap-3">
+    <DialogWithIntro layout="sectioned" label="Seccionado com intro" />
+    <CompactDialog layout="sectioned" label="Seccionado compacto" />
+    <DialogWithIntro layout="continuous" label="Contínuo com intro" />
+    <CompactDialog layout="continuous" label="Contínuo compacto" />
+  </div>,
+);
+```
+
+Prefira `continuous` para uma tarefa curta, em que a linha entre as regiões seria ruído. O `Dialog`
+não recebe navegação neste exemplo: use `DialogNavigation` quando o modal trocar de etapa e a pessoa
+precisar voltar à anterior.
+
+## Drawer
+
+O `Drawer` segue a mesma grade. A navegação aparece aqui como o controle de recolher o painel: um
+`DrawerClose` dentro de `DrawerNavigation`, com `showCloseButton={false}` para que o painel não tenha
+dois controles de fechamento.
+
+```tsx preview
+function OrderField() {
+  const id = useId();
+  return (
+    <div className="space-y-2">
+      <Label htmlFor={id}>Responsável</Label>
+      <Input id={id} defaultValue="Marina Alves" />
+    </div>
+  );
+}
+
+function CollapseButton() {
+  return (
+    <DrawerClose asChild>
+      <Button variant="ghost" size="icon" aria-label="Recolher painel">
+        <ChevronsRight />
+      </Button>
+    </DrawerClose>
+  );
+}
+
+function DrawerWithIntro({ layout, label }) {
+  return (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button variant="outline">{label}</Button>
+      </DrawerTrigger>
+      <DrawerContent layout={layout} showCloseButton={false}>
+        <DrawerHeader>
+          <DrawerNavigation>
+            <CollapseButton />
+          </DrawerNavigation>
+          <DrawerActions>
+            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+              <MessageCircle />
+            </Button>
+          </DrawerActions>
+        </DrawerHeader>
+        <DrawerBody>
+          <DrawerIntro>
+            <DrawerTitle>Editar ordem de serviço</DrawerTitle>
+            <DrawerIntroActions>
+              <Button variant="outline" size="sm">
+                Ver histórico
+              </Button>
+            </DrawerIntroActions>
+          </DrawerIntro>
+          <OrderField />
+        </DrawerBody>
+        <DrawerFooter>
+          <ButtonGroup mode="spaced">
+            <DrawerClose asChild>
+              <Button variant="ghost">Cancelar</Button>
+            </DrawerClose>
+            <Button>Salvar</Button>
+          </ButtonGroup>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>
+  );
+}
+
+function CompactDrawer({ layout, label }) {
+  return (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button variant="outline">{label}</Button>
+      </DrawerTrigger>
+      <DrawerContent layout={layout} showCloseButton={false}>
+        <DrawerHeader>
+          <DrawerNavigation>
+            <CollapseButton />
+          </DrawerNavigation>
+          <DrawerTitle>Editar ordem de serviço</DrawerTitle>
+          <DrawerActions>
+            <Button variant="outline" size="sm">
+              Ver histórico
+            </Button>
+            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+              <MessageCircle />
+            </Button>
+          </DrawerActions>
+        </DrawerHeader>
+        <DrawerBody>
+          <OrderField />
+        </DrawerBody>
+        <DrawerFooter>
+          <ButtonGroup mode="spaced">
+            <DrawerClose asChild>
+              <Button variant="ghost">Cancelar</Button>
+            </DrawerClose>
+            <Button>Salvar</Button>
+          </ButtonGroup>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>
+  );
+}
+
+render(
+  <div className="grid grid-cols-2 gap-3">
+    <DrawerWithIntro layout="sectioned" label="Seccionado com intro" />
+    <CompactDrawer layout="sectioned" label="Seccionado compacto" />
+    <DrawerWithIntro layout="continuous" label="Contínuo com intro" />
+    <CompactDrawer layout="continuous" label="Contínuo compacto" />
+  </div>,
+);
+```
+
+Mantenha `DrawerNavigation`, `DrawerTitle` e `DrawerActions` como filhos diretos de
+`DrawerHeader`: o cabeçalho reconhece os slots pelo componente e interrompe a renderização diante de
+qualquer outro nó, inclusive um componente local que devolva um slot. Por isso, o exemplo extrai
+apenas o botão de recolher. Sem o botão de fechar, Esc e o clique no overlay continuam fechando o
+painel.
+
+## Page
+
+A `Page` não tem um slot de intro. Com intro, o `PageHeader` guarda a navegação e as ações da
+página, e uma `Surface level={1}` abre o `PageBody` com o título e as ações do conteúdo. A página
+precisa de exatamente um heading principal, por isso o `PageHeader` dessa composição não leva
+`PageTitle`.
+
+```tsx preview col
+render(
+  <div className="w-full overflow-hidden rounded-lg border border-border">
+    <Page>
+      <PageHeader>
+        <PageNavigation>
+          <Breadcrumb>
+            <BreadcrumbList>
+              <BreadcrumbItem>Oficina</BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>Ordens de serviço</BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbPage>OS-1842</BreadcrumbPage>
+            </BreadcrumbList>
+          </Breadcrumb>
+        </PageNavigation>
+        <PageActions>
+          <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <MessageCircle />
+          </Button>
+        </PageActions>
+      </PageHeader>
+      <PageBody>
+        <Surface
+          as="section"
+          level={1}
+          title="Editar ordem de serviço"
+          actions={
+            <Button variant="outline" size="sm">
+              Ver histórico
+            </Button>
+          }
+        >
+          <div className="space-y-2">
+            <Label htmlFor="page-intro-owner">Responsável</Label>
+            <Input id="page-intro-owner" defaultValue="Marina Alves" />
+          </div>
+        </Surface>
+      </PageBody>
+      <PageFooter>
+        <ButtonGroup mode="spaced">
+          <Button variant="ghost">Cancelar</Button>
+          <Button>Salvar</Button>
+        </ButtonGroup>
+      </PageFooter>
+    </Page>
+  </div>,
+);
+```
+
+Na composição compacta, `PageTitle` entra no `PageHeader` e as ações do conteúdo passam para
+`PageActions`, antes das ações da página. A forma curta, `<Page title actions>`, produz esse mesmo
+cabeçalho; nela, a navegação vem do [`PageShell`](/ui/page).
+
+```tsx preview col
+render(
+  <div className="w-full overflow-hidden rounded-lg border border-border">
+    <Page>
+      <PageHeader>
+        <PageNavigation>
+          <Breadcrumb>
+            <BreadcrumbList>
+              <BreadcrumbItem>Oficina</BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>Ordens de serviço</BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbPage>OS-1842</BreadcrumbPage>
+            </BreadcrumbList>
+          </Breadcrumb>
+        </PageNavigation>
+        <PageTitle>Editar ordem de serviço</PageTitle>
+        <PageActions>
+          <Button variant="outline" size="sm">
+            Ver histórico
+          </Button>
+          <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <MessageCircle />
+          </Button>
+        </PageActions>
+      </PageHeader>
+      <PageBody>
+        <div className="space-y-2">
+          <Label htmlFor="page-compact-owner">Responsável</Label>
+          <Input id="page-compact-owner" defaultValue="Marina Alves" />
+        </div>
+      </PageBody>
+      <PageFooter>
+        <ButtonGroup mode="spaced">
+          <Button variant="ghost">Cancelar</Button>
+          <Button>Salvar</Button>
+        </ButtonGroup>
+      </PageFooter>
+    </Page>
+  </div>,
+);
+```
+
+Use `PageFooter` quando a página for uma etapa com decisão própria, como esta edição.
+
+## Pane com Surface
+
+`Pane` declara uma coluna de um [`Split`](/ui/split) e não desenha nada: não tem cabeçalho, corpo,
+rodapé, recuo, borda nem fundo. Quando a coluna precisa dessas regiões, componha uma `Surface`
+dentro dela. A `Surface` não tem intro, então o título fica no `SurfaceHeader`, como na composição
+compacta.
+
+```tsx preview col
+render(
+  <div className="h-80 w-full overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="14rem">
+        <Sidebar className="w-full">
+          <SidebarNav
+            navLabel="Ordens de serviço"
+            activeId="os-1842"
+            groups={[
+              {
+                items: [
+                  { id: "os-1842", label: "OS-1842" },
+                  { id: "os-1839", label: "OS-1839" },
+                  { id: "os-1835", label: "OS-1835" },
+                ],
+              },
+            ]}
+          />
+        </Sidebar>
+      </Pane>
+      <Pane grow>
+        <Surface
+          as="section"
+          framed
+          elevation="raised"
+          layout="sectioned"
+          className="flex h-full flex-col"
+        >
+          <SurfaceHeader>
+            <SurfaceMedia>
+              <Wrench />
+            </SurfaceMedia>
+            <SurfaceTitle>Editar ordem de serviço</SurfaceTitle>
+            <SurfaceActions>
+              <Button variant="outline" size="sm">
+                Ver histórico
+              </Button>
+              <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+                <MessageCircle />
+              </Button>
+            </SurfaceActions>
+          </SurfaceHeader>
+          <SurfaceBody className="min-h-0 flex-1 overflow-y-auto">
+            <div className="space-y-2">
+              <Label htmlFor="pane-owner">Responsável</Label>
+              <Input id="pane-owner" defaultValue="Marina Alves" />
+            </div>
+          </SurfaceBody>
+          <SurfaceFooter>
+            <ButtonGroup mode="spaced">
+              <Button variant="ghost">Cancelar</Button>
+              <Button>Salvar</Button>
+            </ButtonGroup>
+          </SurfaceFooter>
+        </Surface>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+Os dois panes recebem conteúdos diferentes sem mudar de componente: o primeiro hospeda uma
+[`Sidebar`](/ui/sidebar), que já tem anatomia própria, e o segundo, uma `Surface` completa. A
+rolagem também pertence ao conteúdo: a `Surface` ocupa a altura do pane com `flex h-full flex-col`,
+e o `SurfaceBody` declara `min-h-0 flex-1 overflow-y-auto` para rolar entre o cabeçalho e o rodapé.

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

@@ -109,8 +109,10 @@ compartilham a anatomia, e um fluxo que troca de superfície não muda de aparê
 
 O cabeçalho reconhece quatro slots — `DialogNavigation`, `DialogMedia`, `DialogTitle` e
 `DialogActions` — e posiciona cada um: a navegação abre a linha, o título ocupa a folga, as ações
-vão para o extremo oposto e o botão de fechar entra depois delas. Um nó que não seja um desses
-slots interrompe a renderização com um erro; contexto e conteúdo pertencem ao `DialogBody`.
+vão para o extremo oposto e o botão de fechar entra depois delas. A navegação fica a `0.5rem` do
+título, ou da mídia que o antecede, para se ler junto dele; as ações mantêm a distância maior da
+família. Um nó que não seja um desses slots interrompe a renderização com um erro; contexto e
+conteúdo pertencem ao `DialogBody`.
 
 Use `DialogActions` para uma ação da tela que precisa ficar à vista sem competir com o rodapé, como
 abrir um assistente ou alternar um modo de visualização. Use `DialogNavigation` para o retorno de um
@@ -463,7 +465,7 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Arqu
 
 | Propriedade       | Tipo                          | Padrão        | Descrição                                                                                                                                                                                                     |
 | ----------------- | ----------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `showCloseButton` | `boolean`                     | `true`        | No modo padrão, inclui a ação de fechamento no header; o modo de alerta exige uma resposta identificável.                                                                                                     |
+| `showCloseButton` | `boolean`                     | `true`        | No modo padrão, inclui a ação de fechamento no cabeçalho; o modo de alerta exige uma resposta identificável.                                                                                                  |
 | `closeDisabled`   | `boolean`                     | `false`       | Mantém o botão de fechar visível e desabilitado e impede que Esc e o clique externo fechem a superfície. Handlers como `onEscapeKeyDown` e `onPointerDownOutside` continuam sendo chamados antes do bloqueio. |
 | `closeSize`       | `"xs" \| "sm"`                | `"sm"`        | Define o tamanho da ação circular de fechar.                                                                                                                                                                  |
 | `layout`          | `'continuous' \| 'sectioned'` | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. Ignorado em `mode="alert"`.                                                                                                         |
@@ -601,7 +603,7 @@ imperativa.
 
 ## Intro separada do chrome
 
-Quando o header contém apenas navegação, ações globais e o fechamento, coloque o título do
+Quando o cabeçalho contém apenas navegação, ações globais e o fechamento, coloque o título do
 conteúdo no primeiro bloco de `DialogBody`. `DialogIntro` exige um `DialogTitle` e aceita um
 `DialogIntroActions`; o body continua responsável pelo espaço antes, entre e depois dos blocos.
 
@@ -627,4 +629,5 @@ conteúdo no primeiro bloco de `DialogBody`. `DialogIntro` exige um `DialogTitle
 </Dialog>
 ```
 
-No formato compacto, mantenha `DialogTitle` e `DialogActions` no próprio `DialogHeader`.
+No formato compacto, mantenha `DialogTitle` e `DialogActions` no próprio `DialogHeader`. Para
+comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).

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

@@ -102,9 +102,10 @@ rodapé produz uma linha só. A tela não escreve `border-b` nem `border-t`.
 
 O cabeçalho reconhece quatro slots — `DrawerNavigation`, `DrawerMedia`, `DrawerTitle` e
 `DrawerActions` — e posiciona cada um: a navegação abre a linha, a mídia vem antes do título, o
-título ocupa a folga, as ações vão para o extremo oposto e o botão de fechar entra depois delas. Um
-nó que não seja um desses slots interrompe a renderização com um erro; contexto e conteúdo
-pertencem ao `DrawerBody`.
+título ocupa a folga, as ações vão para o extremo oposto e o botão de fechar entra depois delas. A
+navegação fica a `0.5rem` do título, ou da mídia que o antecede, para se ler junto dele; as ações
+mantêm a distância maior da família. Um nó que não seja um desses slots interrompe a renderização
+com um erro; contexto e conteúdo pertencem ao `DrawerBody`.
 
 `DrawerMedia` reserva o espaço que identifica o tipo do recurso aberto, sem acrescentar moldura.
 Componha [`IconTile`](/ui/icon-tile) quando ela ajudar na hierarquia. `DrawerNavigation` carrega o
@@ -265,7 +266,7 @@ o conteúdo controlar o próprio inset e um wrapper filho para relações intern
 
 ## Intro separada do chrome
 
-Quando o header contém apenas o recolhimento, ações globais e o fechamento, use `DrawerIntro`
+Quando o cabeçalho contém apenas o recolhimento, ações globais e o fechamento, use `DrawerIntro`
 como primeiro bloco de `DrawerBody`. Ele exige um `DrawerTitle` e aceita `DrawerIntroActions`.
 Assim o título acompanha o conteúdo rolável enquanto o chrome permanece estável.
 
@@ -295,4 +296,5 @@ Assim o título acompanha o conteúdo rolável enquanto o chrome permanece está
 </Drawer>
 ```
 
-No formato compacto, mantenha `DrawerTitle` e `DrawerActions` no próprio `DrawerHeader`.
+No formato compacto, mantenha `DrawerTitle` e `DrawerActions` no próprio `DrawerHeader`. Para
+comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).

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

@@ -6,9 +6,9 @@ centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). Use `clas
 a composição pedir outro teto ou largura total.
 
 A forma curta é o padrão para páginas comuns e cria `PageHeader` e `PageBody`. A forma explícita
-exige exatamente um heading principal. Use `PageTitle` no header, `Surface level={1}` no body, ou
-deixe um `PageState` ativo assumir esse papel. O header pode ser omitido quando o próprio conteúdo
-nomeia a página. Contadores e outros indicadores pertencem ao conteúdo que os explica.
+exige exatamente um heading principal. Use `PageTitle` no cabeçalho, `Surface level={1}` no body,
+ou deixe um `PageState` ativo assumir esse papel. O cabeçalho pode ser omitido quando o próprio
+conteúdo nomeia a página. Contadores e outros indicadores pertencem ao conteúdo que os explica.
 
 A `Page` é contínua por definição e não há divisores entre suas regiões. O `layout` da `Page` não
 é a anatomia de superfície de
@@ -109,7 +109,7 @@ navegação e as ações do shell no `PageHeader` rolável da página ativa.
 Durante `PageState`, o cabeçalho inteiro desaparece e o título do estado assume o heading principal.
 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, combine navegação, título e ações no mesmo header:
+Na composição explícita, combine navegação, título e ações no mesmo cabeçalho:
 
 ```tsx preview col
 <PageShell
@@ -137,7 +137,7 @@ Na composição explícita, combine navegação, título e ações no mesmo head
 
 ## Composição explícita
 
-Use os slots quando a página precisar compor o header diretamente. Não misture propriedades da
+Use os slots quando a página precisar compor o cabeçalho diretamente. Não misture propriedades da
 forma curta com `PageHeader` ou `PageBody`.
 
 ```tsx preview col
@@ -161,6 +161,8 @@ render(
 Em uma página de listagem, [`Surface`](/ui/surface) pode fornecer o título e as ações da coleção,
 deixando `Page` apenas com `PageBody`. Se `PageShell` fornecer navegação ou ações nesse caso, `Page`
 materializa somente o `PageHeader` necessário para recebê-las, sem duplicar o heading de `Surface`.
+[Composições](/ui/compositions) compara essa forma, com o título no corpo, à forma compacta, com o
+título no cabeçalho.
 
 ## Ações de etapa no rodapé
 
@@ -392,10 +394,10 @@ ocupa a altura.
 
 ## Propriedades de PageActionsTarget
 
-| Propriedade | Tipo                  | Descrição                                                    |
-| ----------- | --------------------- | ------------------------------------------------------------ |
-| `target`    | `HTMLElement \| null` | Destino externo das ações; `null` mantém as ações no header. |
-| `children`  | `ReactNode`           | Árvore de página que poderá declarar `PageActions`.          |
+| Propriedade | Tipo                  | Descrição                                                       |
+| ----------- | --------------------- | --------------------------------------------------------------- |
+| `target`    | `HTMLElement \| null` | Destino externo das ações; `null` mantém as ações no cabeçalho. |
+| `children`  | `ReactNode`           | Árvore de página que poderá declarar `PageActions`.             |
 
 ## Propriedades de PageState
 

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

@@ -27,7 +27,8 @@ render(
 
 Quando a região precisa de cabeçalho, corpo, rodapé ou aparência elevada, componha uma
 [`Surface`](/ui/surface) dentro do pane. Quando o filho já é uma estrutura completa, como
-`Sidebar`, ele pode ocupar o pane diretamente.
+`Sidebar`, ele pode ocupar o pane diretamente. [Composições](/ui/compositions) mostra um pane com
+`Surface` completa, com cabeçalho, corpo rolável e rodapé.
 
 ## Redimensionamento
 

package/src/ui/docs/registry.tsx

@@ -49,6 +49,7 @@ import tokensMd from "./content/tokens.md?raw";
 import semanticContextMd from "./content/semantic-context.md?raw";
 import communicationMd from "./content/communication.md?raw";
 import customizationMd from "./content/customization.md?raw";
+import compositionsMd from "./content/compositions.md?raw";
 
 // — Componentes —
 import accordionMd from "./content/accordion.md?raw";
@@ -395,6 +396,11 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Comunicação",
             render: doc(communicationMd),
           },
+          {
+            slug: "compositions",
+            title: "Composições",
+            render: doc(compositionsMd),
+          },
           {
             slug: "customization",
             title: "Customização",