@softize/opus 18.5.0 → 20.0.0

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

@@ -1,9 +1,12 @@
 ## Navegação entre páginas
 
-Componha `Pagination`, `PaginationContent` e um `PaginationItem` para cada link. `page` fornece o
+Use `Pagination` quando uma coleção for dividida em páginas e a pessoa precisar saltar entre elas.
+Em uma listagem derivada de uma action, [`ActionList`](/ui/action-list) já monta esta paginação no
+rodapé; componha-a diretamente apenas em coleções próprias.
+
+Monte `Pagination`, `PaginationContent` e um `PaginationItem` para cada link. `page` fornece o
 número e o nome acessível; `isActive` identifica a página atual. Os controles mantêm altura fixa e
-a largura cresce quando o número precisa de mais espaço. `ActionList` usa esta mesma primitiva no
-rodapé.
+a largura cresce quando o número precisa de mais espaço.
 
 ```tsx preview
 <Pagination>
@@ -30,8 +33,9 @@ rodapé.
 ## Números longos
 
 A largura mínima é quadrada e cresce conforme o conteúdo. Na escala densa de um rodapé, as setas e a
-elipse usam `size="icon-sm"` (o quadrado de 1.75rem da escala única, com o glifo de 0.875rem); os
-números, que não têm um degrau de 1.75rem na escala, ajustam por `className` (`h-7 min-w-7 text-xs`).
+elipse usam `size="icon-sm"`, o quadrado de `1.75rem` da escala única, com ícone de `0.875rem`. Os
+números não têm um degrau textual de `1.75rem` na escala e, por isso, recebem a mesma medida por
+`className`, como no exemplo.
 
 ```tsx preview
 <Pagination>
@@ -148,3 +152,7 @@ render(
 |---|---|---|---|
 | `size` | `'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'icon'` | Quadrado da escala única; use o mesmo tamanho das setas ao lado. |
 | `className` | `string` | | Classes adicionais aplicadas à elipse. |
+
+`Pagination` renderiza um `<nav>` com o nome acessível “Paginação”, `PaginationContent` um `<ul>` e
+`PaginationItem` um `<li>`. Os três não têm propriedades próprias e aceitam as props nativas do
+respectivo elemento, incluindo `className`.

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

@@ -0,0 +1,300 @@
+## A coluna encaixada em um layout
+
+Use `Pane` para a coluna ou faixa que ocupa uma das posições de um [`Split`](/ui/split): a
+navegação à esquerda, o inspetor à direita, a lista que abre o detalhe ao lado. O `Split` decide a
+relação espacial e o redimensionamento; o `Pane` decide o que existe dentro da área recebida.
+
+No formato mais simples, o pane é uma caixa com recuo e o conteúdo é seu.
+
+```tsx preview
+render(
+  <div className="h-56 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="16rem" className="bg-muted/30">
+        <p className="text-sm text-muted-foreground">Navegação.</p>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conteúdo.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+## Cabeçalho, corpo e rodapé
+
+Quando a área precisa de regiões fixas e de um corpo que rola, componha os slots. `PaneHeader`
+nomeia a região, `PaneBody` ocupa o espaço restante e concentra a rolagem vertical, e `PaneFooter`
+mantém à vista o que não pode sair da tela.
+
+```tsx preview
+render(
+  <div className="h-72 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="18rem">
+        <PaneHeader>
+          <PaneMedia>
+            <MessagesSquare />
+          </PaneMedia>
+          <PaneTitle>Conversas</PaneTitle>
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Nova conversa">
+              <SquarePen />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody className="space-y-1">
+          <p className="text-sm">Revisão do contrato</p>
+          <p className="text-sm text-muted-foreground">Importação de clientes</p>
+          <p className="text-sm text-muted-foreground">Fila de execuções</p>
+        </PaneBody>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Ver arquivadas</Button>
+        </PaneFooter>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conversa selecionada.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+O cabeçalho reconhece quatro slots — `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions` —
+e monta a linha sozinho: mídia, título e descrição de um lado, ações no extremo oposto. A ordem em
+que os slots são escritos não altera a posição. Cada slot aparece no máximo uma vez: repetir um
+deles interrompe a renderização com um erro que lista os slots aceitos.
+
+Título e descrição truncam quando a coluna encolhe, em vez de quebrar a altura da faixa.
+
+Nas ações do cabeçalho, use `Button` `ghost` no tamanho `icon-sm` (1.75rem), como nos exemplos. O
+pane é uma superfície densa, com título e descrição em escala menor, e o quadrado menor acompanha
+essa escala. [`Dialog`](/ui/dialog) e [`Drawer`](/ui/drawer) usam `icon` (2.25rem) no voltar e nas
+ações do cabeçalho, e a [`Presentation`](/ui/presentation) usa o mesmo tamanho no voltar e no botão
+que abre o assistente.
+
+## Busca ou marca no cabeçalho
+
+Uma coluna às vezes precisa, no topo, de algo que não é título nem ação: uma busca que filtra a
+lista, a marca de uma barra lateral. Escreva esse conteúdo direto dentro do `PaneHeader`, ao lado
+dos slots. Só o `Pane` aceita conteúdo livre no cabeçalho; os headers de `Card`, `Dialog` e `Drawer`
+aceitam apenas os próprios slots.
+
+```tsx preview
+render(
+  <div className="h-56 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="18rem">
+        <PaneHeader>
+          <Input icon={<Search />} placeholder="Buscar conversa" aria-label="Buscar conversa" />
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Nova conversa">
+              <SquarePen />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody className="space-y-1">
+          <p className="text-sm">Revisão do contrato</p>
+          <p className="text-sm text-muted-foreground">Importação de clientes</p>
+        </PaneBody>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conversa selecionada.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+O conteúdo livre ocupa o lugar do título e absorve a largura disponível, por isso as ações
+continuam no extremo oposto. Quando há título, o conteúdo livre vem sempre depois do título e da descrição,
+qualquer que seja a ordem no JSX: uma busca escrita junto de um `PaneTitle` aparece abaixo dele, não
+ao lado. Para algo antes do título, use `PaneMedia`; para algo ao lado, use `PaneActions`.
+
+## Escolher entre seccionado e contínuo
+
+`layout` declara a anatomia da superfície inteira e fica no root; os slots leem esse valor e não o
+recebem. Cada valor é um pacote de recuo, ritmo vertical e divisores.
+
+| Aspecto | `sectioned` (padrão) | `continuous` |
+| --- | --- | --- |
+| Divisores | entre as regiões vizinhas | nenhum |
+| Faixa do cabeçalho | altura fixa de `3.75rem` | acompanha o conteúdo |
+| Ritmo vertical | regiões simétricas | o cabeçalho se aproxima do corpo |
+
+O padrão `sectioned` é o pane de operação: a faixa do cabeçalho tem a mesma altura da barra do
+[`PageShell`](/ui/page), então uma navegação lateral e o chrome da página se alinham na mesma
+linha. Use `continuous` quando o pane for um bloco de leitura contínuo, sem fronteiras a marcar.
+
+Os divisores são derivados da vizinhança: cada região desenha a linha quando há uma região do outro
+lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um rodapé produz uma
+linha só. A tela não escreve `border-b` nem `border-t`.
+
+No `continuous`, um cabeçalho sem corpo nem rodapé fecha o pane com o mesmo recuo que tem em cima.
+Uma classe `pb-*` no `PaneHeader` não altera esse recuo: a regra só vale quando o cabeçalho é a
+última região e tem precedência sobre o `className`. No `sectioned`, a faixa tem altura fixa e
+centraliza a linha, então não há recuo de baixo a ajustar.
+
+## Recuo do pane e recuo das regiões
+
+`inset` é o respiro interno do pane sem slots: `md` por padrão, com `none`, `sm` e `lg`
+disponíveis. Quando `PaneHeader`, `PaneBody` ou `PaneFooter` são filhos **diretos** do pane, o recuo
+passa a ser de cada região e o `inset` vira `none` sozinho — é o que permite ao divisor alcançar a
+borda da coluna.
+
+O ajuste enxerga só o primeiro nível. Se os slots vierem dentro de outro componente — é o caso da
+`Sidebar`, que traz a superfície e o colapso —, o pane não sabe que eles existem: declare
+`inset="none"` você mesmo, ou a coluna ganha um recuo que empurra o divisor para dentro.
+
+## A matriz de layouts e slots
+
+As regiões são independentes: a coluna usa só as que precisa, nos dois layouts, e os divisores
+acompanham as regiões presentes.
+
+```tsx preview col
+render(
+  <div className="grid grid-cols-2 gap-4">
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneHeader>
+          <PaneTitle>Seccionado</PaneTitle>
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+              <Ellipsis />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Cabeçalho, corpo e rodapé.</p>
+        </PaneBody>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Configurações</Button>
+        </PaneFooter>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane layout="continuous" className="h-full">
+        <PaneHeader>
+          <PaneMedia>
+            <ChartNoAxesColumn />
+          </PaneMedia>
+          <PaneTitle>Contínuo com mídia</PaneTitle>
+          <PaneDescription>O espaço separa as regiões.</PaneDescription>
+        </PaneHeader>
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Sem rodapé e sem divisores.</p>
+        </PaneBody>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Só corpo: nenhuma fronteira a marcar.</p>
+        </PaneBody>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneHeader>
+          <PaneMedia context="primary">
+            <Folder />
+          </PaneMedia>
+          <PaneTitle>Sem corpo</PaneTitle>
+        </PaneHeader>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Ação persistente</Button>
+        </PaneFooter>
+      </Pane>
+    </div>
+  </div>,
+);
+```
+
+## Onde termina o Pane
+
+Três componentes dividem a responsabilidade de uma coluna, e trocá-los de papel é a origem mais
+comum de layout duplicado:
+
+| Componente | Responsabilidade |
+| --- | --- |
+| [`Split`](/ui/split) | Relação espacial entre as áreas e, com `resizable`, o arraste da fronteira. |
+| `Pane` | Tamanho recebido, recuo e as regiões internas: cabeçalho, corpo e rodapé. |
+| [`Sidebar`](/ui/sidebar) | Superfície da navegação lateral e o estado de colapso dos destinos. |
+
+Tamanho inicial, limites e persistência do layout são declarados no `Pane` e operados pelo `Split`
+— a [página do Split](/ui/split) trata deles. Uma `Sidebar` é composta dentro de um `Pane` e usa os
+mesmos slots para o próprio cabeçalho e rodapé; ela não tem regiões próprias.
+
+## Hierarquia do título
+
+`PaneTitle` é um heading. `level` escolhe a hierarquia do documento, de `1` a `6`, com `2` como
+padrão. O tamanho visual vem da família e do `layout`, não do nível, então corrigir a estrutura do
+documento não muda a aparência da faixa.
+
+## Propriedades de Pane
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `layout` | `'continuous' \| 'sectioned'` | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. |
+| `inset` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`, ou `'none'` com slots diretos | Respiro interno do pane sem slots; slots dentro de outro componente exigem declarar. |
+| `id` | `string` | | Identidade estável usada pelo layout redimensionável e persistido. |
+| `initialSize` | `number \| string` | | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
+| `minSize` / `maxSize` | `number \| string` | | Limites aplicados pelo `Split` quando ele é redimensionável. |
+| `grow` | `boolean` | `false` | Ocupa o espaço remanescente no layout simples. |
+| `className` | `string` | | Ajusta a coluna. |
+| `children` | `ReactNode` | | Conteúdo direto ou os slots estruturais. |
+
+## Propriedades de PaneHeader
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions`, no máximo um de cada, e conteúdo livre, que aparece depois do título e da descrição. |
+| `className` | `string` | | Ajusta a faixa fixa sobre o recuo do layout. |
+
+## Propriedades de PaneMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'xs'` | Tamanho da moldura e do glifo na escala compartilhada. |
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor. |
+| `variant` | `'subtle' \| 'outline'` | `'subtle'` | Usa preenchimento tonal ou acrescenta borda. |
+| `className` | `string` | | Ajusta a moldura sem substituir a escala. |
+| `asChild` | `boolean` | `false` | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
+
+## Propriedades de PaneTitle
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `className` | `string` | | Ajusta o título, que trunca quando não cabe. |
+
+## Propriedades de PaneDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Frase curta de apoio sob o título; trunca quando não cabe. |
+| `className` | `string` | | Ajusta a descrição. |
+
+## Propriedades de PaneActions
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Controles no extremo oposto ao título. |
+| `className` | `string` | | Ajusta o agrupamento das ações. |
+
+## Propriedades de PaneBody
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Conteúdo que ocupa o espaço entre cabeçalho e rodapé. |
+| `className` | `string` | | Ajusta a região flexível e rolável. |
+
+`PaneContent` continua exportado como alias depreciado de `PaneBody` e sai em uma próxima versão
+maior. Código novo usa `PaneBody`.
+
+## Propriedades de PaneFooter
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Navegação ou ações que precisam permanecer acessíveis no rodapé. |
+| `className` | `string` | | Ajusta a faixa fixa sobre o recuo do layout. |

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

@@ -2,7 +2,8 @@
 
 Use `Popover` para apresentar conteúdo livre junto a um gatilho, sem abrir um modal.
 `PopoverHeader` agrupa título e descrição; o restante do painel aceita formulários curtos ou
-detalhes.
+detalhes. Para uma lista de ações, use [`Menu`](/ui/menu); para uma dica curta ao passar o ponteiro,
+use [`Tooltip`](/ui/tooltip).
 
 ```tsx preview
 <Popover>
@@ -12,7 +13,7 @@ detalhes.
   <PopoverContent align="start">
     <PopoverHeader>
       <PopoverTitle>Renomear</PopoverTitle>
-      <PopoverDescription>O slug técnico não muda — só o título.</PopoverDescription>
+      <PopoverDescription>O endereço da sessão continua o mesmo; só o título muda.</PopoverDescription>
     </PopoverHeader>
     <div className="mt-3 space-y-2">
       <Label htmlFor="pop-titulo">Título</Label>
@@ -23,9 +24,14 @@ detalhes.
 </Popover>
 ```
 
-## Alinhamento
+O painel mede `18rem` de largura por padrão e abre abaixo do gatilho. Clicar fora ou pressionar
+Esc fecha o painel.
 
-`align` posiciona o painel em relação ao gatilho e `sideOffset` define a distância entre eles.
+## Posição e largura
+
+`side` escolhe o lado preferido, `align` alinha o painel ao gatilho e `sideOffset` define a
+distância entre eles. Quando não há espaço no lado escolhido, o painel abre no lado oposto. Ajuste
+a largura com `className`, como `w-56` para `14rem`.
 
 ```tsx preview
 <Popover>
@@ -40,6 +46,12 @@ detalhes.
     <PopoverDescription>Alinhado à borda direita do gatilho.</PopoverDescription>
   </PopoverContent>
 </Popover>
+<Popover>
+  <PopoverTrigger asChild><Button variant="ghost">À direita</Button></PopoverTrigger>
+  <PopoverContent side="right" className="w-56">
+    <PopoverDescription>Abre ao lado direito do gatilho.</PopoverDescription>
+  </PopoverContent>
+</Popover>
 ```
 
 ## Propriedades de Popover
@@ -47,7 +59,15 @@ detalhes.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `open` | `boolean` | | Estado no modo controlado. |
-| `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado para permitir abertura ou fechamento por código. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado quando o painel abre ou fecha; atualize `open` com o valor recebido. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
+| `modal` | `boolean` | `false` | Com `true`, prende o foco no painel e bloqueia a interação com o restante da página enquanto ele está aberto. |
+
+## Propriedades de PopoverTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Faz do filho (por exemplo, um `Button`) o gatilho, em vez de renderizar outro `<button>`. |
 
 ## Propriedades de PopoverAnchor
 
@@ -59,5 +79,22 @@ não introduzir um nó extra; sem ele, o `PopoverTrigger` é a âncora.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Lado preferido do painel; sem espaço, ele abre no lado oposto. |
 | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
 | `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |
+| `className` | `string` | | Classes do painel. A largura padrão é `w-72` (`18rem`). |
+
+## Propriedades de PopoverHeader
+
+`PopoverHeader` empilha `PopoverTitle` e `PopoverDescription` com espaçamento curto. Não tem props
+próprias; aceita as de um elemento `div`.
+
+## Propriedades de PopoverTitle
+
+`PopoverTitle` destaca o nome do painel com peso médio. Ele renderiza um `div`, sem nível de
+heading. Não tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de PopoverDescription
+
+`PopoverDescription` apresenta o texto de apoio em cor atenuada. Não tem props próprias; aceita as
+de um elemento `p`.

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

@@ -1,45 +1,11 @@
-`Presentation` preserva a identidade de um recurso quando o contexto pede uma página, um dialog ou
-um drawer. A superfície decide quanto espaço ocupar; o recurso continua com a mesma navegação,
-cabeçalho, body e rodapé.
-
-Dialog e Drawer mantêm no cabeçalho a ordem horizontal de navegação ou retorno, título e ações.
-O retorno aparece em uma surface modal somente
-quando ela foi aberta sobre outro Dialog ou Drawer; a Page ao fundo sustenta o modal, mas não cria
-uma etapa de navegação. Formulários modais dimensionam o footer pelo conteúdo, com `Cancelar` em
-`ghost` e a ação principal sólida.
-Em Page hospedada por `PageShell`, a barra concentra navegação e ações globais. Uma Presentation
-de listagem materializa título e comandos de header no `Content` que envolve o `ActionList`; assim
-a criação permanece próxima da coleção. Esses comandos usam o tamanho `default`: o que abre outra
-Presentation é um `Button` na variante padrão (`solid`), e uma action `simple` vira um
-`ActionTrigger` na variante `ghost`. Nas demais Presentations, o título abre o conteúdo em
-`PageIntro` e os comandos da superfície seguem a mesma regra.
-
-Use esse padrão quando uma lista puder abrir um detalhe lateral, quando a mesma edição precisar
-funcionar em modal e em rota própria ou quando um fluxo começar compacto e crescer sem ganhar uma
-segunda implementação.
-
-Dentro de `PageShell`, a superfície `page` usa a anatomia real da aplicação: a Presentation projeta
-navigation e actions globais por `PageHeader`, mantém a introdução no conteúdo quando existir e
-compõe `PageBody` e, quando necessário, `PageFooter`. Para uma action `list`, `PageBody` recebe
-`Content + ActionList`; o header da coleção recebe o título e os comandos declarados no placement
-`header`. Dialog e Drawer continuam usando o header da própria superfície.
-Os comandos da coleção ficam no extremo oposto ao título e permanecem textuais, mesmo quando a
-action declara um ícone. A criação usa `Criar recurso`, sem ícone, em um `Button` na variante
-padrão (`solid`) e no tamanho `default`.
-Não envolva a Presentation em um card para simular a página; valide proporção, rolagem e ações no
-shell que efetivamente hospeda a rota.
+Use `Presentation` quando o mesmo recurso precisa aparecer ora como página, ora como dialog, ora
+como drawer: uma lista que abre o detalhe ao lado, uma edição que funciona em modal e em rota
+própria, um fluxo que começa compacto e cresce sem ganhar uma segunda implementação. A superfície
+decide quanto espaço ocupar; o recurso mantém a mesma navegação, cabeçalho, corpo e rodapé.
 
-O exemplo declara a Presentation sobre um contrato de formulário e alterna a superfície. O
+O exemplo declara uma Presentation sobre um contrato de formulário e alterna a superfície. O
 `DocBrowserActionProvider` simula o cliente de actions; na aplicação, esse papel é do provider real.
 
-Quando o recurso aceita assistência contextual, declare somente o gatilho serializável em
-`assistant`. O renderer coloca esse gatilho no cabeçalho e abre o painel à direita do body da
-própria Page, Dialog ou Drawer. Cabeçalho e rodapé continuam ocupando toda a largura da superfície;
-enquanto o painel está aberto, o gatilho sai do cabeçalho e o próprio painel assume sua identidade
-visual. O dado vivo do recurso não entra na definição: a página que o carregou fornece
-`assistant.render`, captura identidade, nome e demais dados autorizados e monta o chat. Assim,
-contexto de conversa não vira autorização nem dado persistido no manifest.
-
 ```tsx live
 const workspacePresentation = definePresentation({
   schemaVersion: 1,
@@ -64,7 +30,7 @@ function Example() {
     <DocBrowserActionProvider>
       <div className="space-y-4">
         <ButtonGroup mode="spaced">
-          {["page", "dialog", "drawer"].map((value) => (
+          {(["page", "dialog", "drawer"] as const).map((value) => (
             <Button
               key={value}
               size="sm"
@@ -115,14 +81,48 @@ function Example() {
 render(<Example />);
 ```
 
+## Como cada superfície apresenta o recurso
+
+Em Dialog e Drawer, o cabeçalho da própria superfície reúne, nesta ordem, o retorno, o título e as
+ações. O retorno só aparece quando o modal foi aberto sobre outro Dialog ou Drawer: a página ao
+fundo sustenta o modal, mas não é uma etapa para onde voltar. Formulários modais dimensionam o
+rodapé pelo conteúdo, com `Cancelar` em `ghost` e a ação principal sólida.
+
+Dentro de [`PageShell`](/ui/page), a superfície `page` usa a anatomia real da aplicação. O
+`PageHeader` recebe só a navegação e as ações globais; o título abre o conteúdo em `PageIntro`, e o
+corpo vai para `PageBody`, com `PageFooter` quando há ações de rodapé.
+
+Uma Presentation de listagem exibida como página muda essa distribuição para manter a criação perto
+da coleção. O `PageBody` recebe um [`Content`](/ui/content) com a
+[`ActionList`](/ui/action-list), e o cabeçalho desse `Content` recebe o título e os comandos
+declarados com `placement: "header"`, no extremo oposto ao título. Os comandos de cabeçalho usam o
+tamanho `default` e permanecem textuais, mesmo quando a action declara um ícone: o que abre outra
+Presentation é um `Button` sólido, e uma action `simple` vira um
+[`ActionTrigger`](/ui/action-trigger) `ghost`. O rótulo vem do `label` da action, como `Criar workspace`.
+
+Não envolva a Presentation em um card para simular a página. Valide proporção, rolagem e ações no
+shell que efetivamente hospeda a rota.
+
+## Assistência contextual
+
+Quando o recurso aceita uma conversa sobre ele, declare em `assistant` somente o gatilho
+serializável, como no exemplo acima. O renderer coloca o gatilho no cabeçalho e abre o painel à
+direita do corpo da própria página, dialog ou drawer. Cabeçalho e rodapé continuam ocupando toda a
+largura; enquanto o painel está aberto, o gatilho sai do cabeçalho e o painel assume a identidade
+visual da assistência.
+
+O dado vivo do recurso não entra na definição. A página que carregou o recurso fornece
+`assistant.render`, reúne identidade, nome e demais dados autorizados e monta o chat. Assim, o
+contexto da conversa não vira autorização nem dado persistido no manifest.
+
 ## A declaração
 
 `definePresentation` cria o artefato serializável. O body recebe uma action `form`, `list` ou
-`view`; uma action `simple` aparece como comando no cabeçalho ou no rodapé. Em formulário,
-`body.submitLabel` sobrescreve o padrão “Salvar” quando a operação tem outro resultado observável,
-como “Renomear” ou “Criar nova versão”. Actions que precisam de
-interface abrem outra Presentation. Bindings fornecem valores vindos da rota, do registro, da
-seleção, da sessão ou do resultado anterior sem guardar callbacks no JSON.
+`view`, ou um componente React, descrito em “Conteúdo React no body”; uma action `simple` aparece
+como comando no cabeçalho ou no rodapé. Em formulário, `body.submitLabel` sobrescreve o padrão
+“Salvar” quando a operação tem outro resultado observável, como “Renomear” ou “Criar nova versão”.
+Actions que precisam de interface abrem outra Presentation. Bindings fornecem valores vindos da
+rota, do registro, da seleção, da sessão ou do resultado anterior sem guardar callbacks no JSON.
 
 Quando a exibição precisa sobreviver a refresh, deep link ou histórico, declare `route` na própria
 Presentation. O `path` aceita segmentos fixos e parâmetros como `:id`; `surface` determina como a
@@ -154,6 +154,48 @@ const workspaceList = definePresentation({
 });
 ```
 
+## Conteúdo React no body
+
+Uma tela que já existe em React pode adotar a casca da Presentation — rota, superfície, título,
+navegação e ações — sem migrar o miolo para actions declarativas de uma vez. Declare
+`body: { component }` com um identificador estável para esse conteúdo e passe o conteúdo como
+`children` do `Presentation`:
+
+```tsx
+const appearance = definePresentation({
+  schemaVersion: 1,
+  id: "settings.appearance",
+  title: "Aparência",
+  route: { path: "/settings/appearance", surface: "page" },
+  body: { component: "settings.appearance.content" },
+});
+
+<Presentation
+  definition={appearance}
+  definitions={[appearance]}
+  actions={{}}
+  invocation={invocation}
+>
+  <AppearanceSettings />
+</Presentation>;
+```
+
+O identificador de `component` vai para o manifest; o JSX, não. Uma Presentation com body de
+componente exige `children`, e uma com body de action os recusa: nos dois casos, a renderização
+lança um erro que nomeia a Presentation.
+
+Com `heading: "shell"`, o padrão, a casca emite o título da definição. Quando o conteúdo React já
+declara o heading principal da página, como um `Content level={1}`, use `heading: "content"`: dentro
+de `PageShell`, a casca deixa de emitir o `PageIntro` e o documento continua com um único `h1`. Em
+Dialog e Drawer, o título continua no cabeçalho da superfície.
+
+Se o conteúdo precisa ocupar a altura da página e controlar a própria rolagem, como uma lista com
+cabeçalho fixo, passe `layout="fill"` ao `Presentation`. Com o padrão `flow`, a página rola como um
+documento. Uma [`ActionList`](/ui/action-list) filha direta do conteúdo React recebe essa altura e
+assume `fill` sozinha.
+
+## Registrar as declarações
+
 Registre as declarações em `presentations` no `opus.config.ts`. `opus gen` valida as referências e
 projeta o JSON no manifest; a Lens pode então exibir o artefato completo sem reconstruí-lo a partir
 do JSX.
@@ -161,7 +203,7 @@ do JSX.
 ## A invocação
 
 `definePresentationInvocation` cria o estado vivo de uma exibição. Ele contém somente valores JSON,
-a surface atual e a pilha necessária para voltar. A definição continua estática no manifest; input
+a superfície atual e a pilha necessária para voltar. A definição continua estática no manifest; input
 de rota, sessão e resultado existe apenas na invocação.
 
 ```ts
@@ -194,7 +236,7 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 | `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.                                                           |
 | `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno.                                              |
 | `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato.                                              |
-| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.                                                           |
+| `invocation`         | `PresentationInvocation`                         |        | Superfície, input e pilha da exibição atual.                                                        |
 | `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.                                                |
 | `assistant`          | `PresentationAssistantRuntime`                   |        | Painel contextual fornecido pela superfície hospedeira.                                             |
 | `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                                                             |
@@ -205,6 +247,8 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 | `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.                                                 |
 | `className`          | `string`                                         |        | Classes adicionais da superfície.                                                                   |
 | `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.                                                |
+| `layout`             | `'flow' \| 'fill'`                               | `'flow'` | Em `page`, `fill` limita a altura ao shell e entrega a rolagem ao conteúdo do body; a lista de um body `list` ocupa essa altura e rola só os resultados. Dialog e Drawer ignoram. |
+| `children`           | `ReactNode`                                      |        | Conteúdo React do body declarado com `body.component`. Obrigatório nesse caso e recusado com `body.action`. |
 
 ## Propriedades de PresentationInspector