@softize/opus 18.1.0 → 18.2.0

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

@@ -15,9 +15,9 @@ representa um único controle. `min`, `max` e `step` delimitam os valores dispon
 const [parallelism, setParallelism] = useState([4])
 
 render(
-  <div className="grid w-full gap-3">
+  <div role="group" aria-labelledby="parallelism-label" className="grid w-full gap-3">
     <div className="flex items-center justify-between">
-      <Label>Sessões em paralelo</Label>
+      <Label id="parallelism-label">Sessões em paralelo</Label>
       <span className="text-sm text-muted-foreground">{parallelism[0]}</span>
     </div>
     <Slider value={parallelism} onValueChange={setParallelism} min={1} max={8} step={1} />
@@ -33,9 +33,9 @@ Dois números em `value` criam um intervalo selecionável entre dois controles.
 const [budget, setBudget] = useState([20, 60])
 
 render(
-  <div className="grid w-full gap-3">
+  <div role="group" aria-labelledby="budget-label" className="grid w-full gap-3">
     <div className="flex items-center justify-between">
-      <Label>Custo estimado (US$)</Label>
+      <Label id="budget-label">Custo estimado (US$)</Label>
       <span className="text-sm text-muted-foreground">{budget[0]} – {budget[1]}</span>
     </div>
     <Slider value={budget} onValueChange={setBudget} min={0} max={100} step={5} />

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

@@ -14,11 +14,11 @@ de um `lg`. O ícone é decorativo; quem nomeia a espera é o contêiner (`role=
 
 ## No botão
 
-Durante uma ação, combine o spinner compacto com o estado desabilitado e um rótulo que descreva o
-andamento.
+Durante uma ação, use `busy` no `Button` com um rótulo que descreva o andamento. O botão fica
+desabilitado e o spinner ocupa o lugar do ícone, no glifo do tamanho do botão.
 
 ```tsx preview
-<Button disabled><Spinner size="sm" /> Publicando…</Button>
+<Button busy>Publicando…</Button>
 ```
 
 ## Em carga de conteúdo

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

@@ -12,11 +12,13 @@ render(
         <div className="p-4 text-sm">Navegação</div>
       </Pane>
       <Pane grow inset="lg">
-        <p className="text-sm text-muted-foreground">Conteúdo. Arraste a divisória.</p>
+        <p className="text-sm text-muted-foreground">
+          Conteúdo. Arraste a divisória.
+        </p>
       </Pane>
     </Split>
   </div>,
-)
+);
 ```
 
 ## Espaçamento interno
@@ -30,8 +32,12 @@ Quando uma área precisa continuar legível em telas largas, use uma unidade abs
 
 ```tsx
 <Split resizable>
-  <Pane grow inset="none"><Main /></Pane>
-  <Pane initialSize="28rem" minSize="20rem" inset="none"><Inspector /></Pane>
+  <Pane grow inset="none">
+    <Main />
+  </Pane>
+  <Pane initialSize="28rem" minSize="20rem" inset="none">
+    <Inspector />
+  </Pane>
 </Split>
 ```
 
@@ -75,23 +81,78 @@ const defaultLayout = readLayout('workspace-layout')
 
 Em aplicações renderizadas no servidor, leia o armazenamento somente no cliente. `onLayoutChanged` também permite usar `sessionStorage` ou uma camada própria quando o layout precisa acompanhar outro escopo.
 
+## Assistência dentro da superfície
+
+`SurfaceAssistant` especializa o split usado por uma Page, Dialog ou Drawer que abre assistência
+contextual. O conteúdo principal permanece montado e o painel aparece à direita com largura
+redimensionável. A superfície hospedeira controla o gatilho, o estado aberto e os dados passados ao
+painel; o pattern cuida apenas da relação espacial. Envolva somente o body da superfície com
+`SurfaceAssistant`: cabeçalho e rodapé devem permanecer fora do split e ocupar toda a largura.
+
+```tsx preview
+function Example() {
+  const [open, setOpen] = React.useState(true);
+
+  return (
+    <div className="h-72 overflow-hidden rounded-lg border border-border">
+      <SurfaceAssistant
+        open={open}
+        assistantLabel="Assistente do pedido"
+        assistant={
+          <div className="h-full p-3">
+            <p className="text-sm">Conversa vinculada ao pedido carregado.</p>
+            <Button
+              className="mt-3"
+              variant="ghost"
+              onClick={() => setOpen(false)}
+            >
+              Fechar
+            </Button>
+          </div>
+        }
+      >
+        <div className="h-full p-3">
+          <Button variant="outline" onClick={() => setOpen(true)}>
+            Abrir assistente
+          </Button>
+        </div>
+      </SurfaceAssistant>
+    </div>
+  );
+}
+
+render(<Example />);
+```
+
 ## Propriedades de Split
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Sentido em que os panes se alinham. |
-| `resizable` | `boolean` | `false` | Cada fronteira ganha um separador acessível e arrastável. |
-| `handle` | `boolean` | `false` | Mostra a alça visual no separador. |
-| `id` | `string` | | Identidade estável do grupo redimensionável. |
-| `defaultLayout` | `Record<string, number>` | | Layout percentual restaurado, indexado pelos ids dos panes. |
-| `onLayoutChanged` | `(layout, { isUserInteraction }) => void` | | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
+| Propriedade       | Tipo                                      | Padrão         | Descrição                                                               |
+| ----------------- | ----------------------------------------- | -------------- | ----------------------------------------------------------------------- |
+| `direction`       | `'horizontal' \| 'vertical'`              | `'horizontal'` | Sentido em que os panes se alinham.                                     |
+| `resizable`       | `boolean`                                 | `false`        | Cada fronteira ganha um separador acessível e arrastável.               |
+| `handle`          | `boolean`                                 | `false`        | Mostra a alça visual no separador.                                      |
+| `id`              | `string`                                  |                | Identidade estável do grupo redimensionável.                            |
+| `defaultLayout`   | `Record<string, number>`                  |                | Layout percentual restaurado, indexado pelos ids dos panes.             |
+| `onLayoutChanged` | `(layout, { isUserInteraction }) => void` |                | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
 
 ## Propriedades de Pane
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `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 quando o split é redimensionável. |
-| `grow` | `boolean` | `false` | Ocupa o espaço remanescente no layout simples. |
-| `inset` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio. |
+| Propriedade           | Tipo                             | Padrão  | Descrição                                                                                 |
+| --------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `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 quando o split é redimensionável.                                                 |
+| `grow`                | `boolean`                        | `false` | Ocupa o espaço remanescente no layout simples.                                            |
+| `inset`               | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`  | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio.             |
+
+## Propriedades de SurfaceAssistant
+
+| Propriedade      | Tipo        | Padrão  | Descrição                                               |
+| ---------------- | ----------- | ------- | ------------------------------------------------------- |
+| `open`           | `boolean`   |         | Exibe o painel complementar à direita.                  |
+| `assistantLabel` | `string`    |         | Nome acessível da região complementar.                  |
+| `children`       | `ReactNode` |         | Conteúdo principal que permanece montado.               |
+| `assistant`      | `ReactNode` |         | Painel fornecido pela superfície que conhece o recurso. |
+| `initialSize`    | `PaneSize`  | `28rem` | Largura inicial do painel.                              |
+| `minSize`        | `PaneSize`  | `20rem` | Largura mínima durante o redimensionamento.             |
+| `maxSize`        | `PaneSize`  | `40rem` | Largura máxima durante o redimensionamento.             |

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

@@ -58,8 +58,8 @@ vertical amplie a área interativa.
 
 ## Vertical
 
-Com `orientation="vertical"`, a lista forma uma coluna e a marca da variante `line` passa para a
-lateral do gatilho.
+Com `orientation="vertical"`, a lista forma uma coluna. O exemplo usa a variante padrão; com
+`variant="line"`, a marca da aba ativa passa para a lateral do gatilho.
 
 ```tsx preview col
 <Tabs defaultValue="prompt" orientation="vertical">
@@ -87,9 +87,9 @@ lateral do gatilho.
 ```tsx preview col
 <Tabs defaultValue="preview" size="sm">
   <TabsList>
-    <TabsTrigger value="preview" className="text-xs">Preview</TabsTrigger>
-    <TabsTrigger value="code" className="text-xs">Código</TabsTrigger>
-    <TabsTrigger value="ai" className="text-xs">IA</TabsTrigger>
+    <TabsTrigger value="preview">Preview</TabsTrigger>
+    <TabsTrigger value="code">Código</TabsTrigger>
+    <TabsTrigger value="ai">IA</TabsTrigger>
   </TabsList>
 </Tabs>
 ```
@@ -101,7 +101,7 @@ lateral do gatilho.
 | `defaultValue` | `string` | | Aba inicial no modo não controlado. |
 | `value` | `string` | | Aba ativa no modo controlado. Use com `onValueChange`. |
 | `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa seleciona outra aba. |
-| `size` | `'default' \| 'sm'` | `'default'` | Altura da lista na escala única dos controles (2.25 e 2rem), aplicada em `TabsList`. |
+| `size` | `'default' \| 'sm'` | `'default'` | Altura da lista na escala única dos controles (2.25 e 2rem), aplicada em `TabsList`. Não altera a altura de `line` horizontal, que acompanha o conteúdo. |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da lista de abas. |
 
 ## Propriedades de TabsList

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

@@ -72,10 +72,12 @@ schema zod — matéria-prima do `mockHandler` (modo design) e de fixtures de te
 url, datetime) e por nome de campo (email, id, `*At`→data, telefone, cpf/cnpj, nome…), sabor pt-BR.
 
 ```ts
+import { entityRowSchema } from '@softize/opus/schema'
 import { fake, fakeMany } from '@softize/opus/testing'
 
-const one = fake(EventEntity.zod()) // 1 evento válido (safeParse passa)
-const many = fakeMany(EventEntity.zod(), 20) // 20, estáveis entre execuções
+const eventRowSchema = entityRowSchema(EventEntity) // schema da linha da entidade
+const one = fake(eventRowSchema) // 1 evento válido (safeParse passa)
+const many = fakeMany(eventRowSchema, 20) // 20, estáveis entre execuções
 fake(schema, { seed: 7 }) // seed própria
 ```
 

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

@@ -31,11 +31,9 @@ hierarquia precisar ser diferente. A região fica alinhada ao fim lógico da sup
 canto usado pelas ações do Alert. O clique fecha o toast, salvo quando o handler chama
 `event.preventDefault()`.
 
-Na versão 13, `actions` substitui os campos `action` e `cancel` da versão 12. Migre cada controle
-para uma entrada da coleção e preserve a ordem visual desejada.
-
 `toast.promise` acompanha uma promessa e atualiza a mesma notificação nos estados de carregamento,
-sucesso ou erro.
+sucesso ou erro. Ela não aceita `actions`; use `toast` com `actions` quando a notificação precisar
+oferecer uma ação.
 
 ```tsx preview
 <Button
@@ -88,7 +86,7 @@ Monte um único `Toaster` na raiz do aplicativo. O tema vem da propriedade `them
 |---|---|---|---|
 | `description` | `React.ReactNode` | | Complemento exibido abaixo do título. |
 | `actions` | `ToastAction[]` | | Coleção ordenada de ações; a última recebe destaque primário por padrão. |
-| `duration` | `number` | do Sonner | Tempo de permanência da notificação. |
+| `duration` | `number` | `4000` | Tempo de permanência da notificação, em milissegundos. O `Toaster` pode mudar o padrão, e `toast.loading` não expira sozinho. |
 
 ## Propriedades de ToastAction
 

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

@@ -71,6 +71,7 @@ disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
 | `defaultPressed` | `boolean` | `false` | Estado inicial no modo não controlado. |
 | `variant` | `'default' \| 'outline'` | `'default'` | default não tem borda (fundo só quando ativo); outline carrega a borda. |
 | `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
+| `shape` | `'default' \| 'pill'` | `'default'` | Geometria do controle; `pill` arredonda as extremidades. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |
 
 ## ToggleGroup
@@ -106,6 +107,39 @@ render(
 )
 ```
 
+### Itens só com ícone e tooltip
+
+Quando o item mostra somente um ícone, mantenha o `aria-label` e acrescente uma dica visual. Envolva o
+`ToggleGroupItem` em `TooltipTrigger asChild`: o item preserva o estado selecionado e seus atributos,
+e a dica aparece sem criar outro botão. O `TooltipProvider` da raiz do aplicativo continua necessário.
+
+```tsx preview
+const [align, setAlign] = useState('left')
+
+render(
+  <ToggleGroup type="single" value={align} onValueChange={(v) => v && setAlign(v)}>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <ToggleGroupItem value="left" aria-label="Alinhar à esquerda"><AlignLeft /></ToggleGroupItem>
+      </TooltipTrigger>
+      <TooltipContent>Alinhar à esquerda</TooltipContent>
+    </Tooltip>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <ToggleGroupItem value="center" aria-label="Centralizar"><AlignCenter /></ToggleGroupItem>
+      </TooltipTrigger>
+      <TooltipContent>Centralizar</TooltipContent>
+    </Tooltip>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <ToggleGroupItem value="right" aria-label="Alinhar à direita"><AlignRight /></ToggleGroupItem>
+      </TooltipTrigger>
+      <TooltipContent>Alinhar à direita</TooltipContent>
+    </Tooltip>
+  </ToggleGroup>,
+)
+```
+
 ### Variante e espaçamento
 
 `variant`, `size` e `shape` definidos no grupo chegam aos itens por contexto. `spacing` separa os
@@ -138,3 +172,6 @@ itens; com zero, eles formam um bloco contínuo.
 |---|---|---|---|
 | `value` | `string` | | Identificador que entra no valor do grupo quando o item é ativado. |
 | `disabled` | `boolean` | `false` | Bloqueia somente este item e preserva seu estado visual. |
+| `variant` | `'default' \| 'outline'` | `'default'` | Tratamento do item quando o grupo não declara `variant`; o valor do grupo prevalece. |
+| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | Tamanho do item quando o grupo não declara `size`; o valor do grupo prevalece. |
+| `shape` | `'default' \| 'pill'` | shape do grupo | Geometria deste item; quando informada, prevalece sobre a do grupo. |

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

@@ -24,17 +24,18 @@ precisando de `aria-label`.
 </Tooltip>
 <Tooltip>
   <TooltipTrigger asChild><Button variant="ghost">Direita</Button></TooltipTrigger>
-  <TooltipContent side="right">side=&quot;right&quot;.</TooltipContent>
+  <TooltipContent side="right">Abre à direita do botão.</TooltipContent>
 </Tooltip>
 <Tooltip>
   <TooltipTrigger asChild><Button variant="ghost">Embaixo</Button></TooltipTrigger>
-  <TooltipContent side="bottom">side=&quot;bottom&quot;.</TooltipContent>
+  <TooltipContent side="bottom">Abre abaixo do botão.</TooltipContent>
 </Tooltip>
 ```
 
 ## Provider na raiz
 
-Monte um único `TooltipProvider` na raiz para compartilhar o atraso de exibição. Cada `Tooltip` não
+Monte um único `TooltipProvider` na raiz do aplicativo. Ele é obrigatório: um `Tooltip` fora de um
+provider lança erro. O provider também compartilha o atraso de exibição, então cada `Tooltip` não
 precisa de um provider próprio.
 
 ```tsx

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

@@ -59,7 +59,8 @@ quando o texto completo ainda não oferecer contexto suficiente.
 ```
 
 Requer `TooltipProvider` na raiz (o esqueleto do `opus create` já monta). Largura vem do
-container ou de `className` (`max-w-*`) — o span é `block truncate`.
+container ou de `className` (`max-w-*`) — o span é `block` e corta em reticências (`truncate`); com
+`fade`, esmaece o fim da linha em vez das reticências.
 
 ## Propriedades de Truncate
 
@@ -67,4 +68,4 @@ container ou de `className` (`max-w-*`) — o span é `block truncate`.
 |---|---|---|---|
 | `tooltip` | `ReactNode` | os próprios `children` | Conteúdo da dica quando o texto transborda. |
 | `fade` | `boolean` | `false` | Sinaliza o corte esmaecendo o fim da linha, no lugar das reticências. |
-| `className` | `string` | | Largura (`max-w-*`) e demais ajustes; o span é `block truncate`. |
+| `className` | `string` | | Largura (`max-w-*`) e demais ajustes; o span é `block`, com `truncate` fora do modo `fade`. |

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

@@ -24,10 +24,12 @@ para o aplicativo quando a API pública já atender ao caso.
 ```tsx
 // Componentes e hooks — tudo do mesmo barrel.
 import { Button, Dialog, useAction } from '@softize/opus/ui/react'
+```
 
+```css
 /* index.css — o tema canônico + os componentes do Opus no scan do Tailwind. */
 @import '@softize/opus/ui/theme.css';
-@source '../node_modules/@softize/opus/src/ui';
+@source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
 ```
 
 ## Prebundle do Vite

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

@@ -10,10 +10,23 @@ gates apontam as adaptações necessárias no projeto.
 ## 1. Identificar a versão disponível
 
 O **Maestro** compara o pin (`opus.json`) com a versão instalada e com a fonte a cada
-sessão — o alerta no rodapé diz a distância (`v2.9.0 → v2.15.2`) e o **Atualizar** faz
+sessão — o alerta no rodapé diz a distância (`v18.0.1 → v18.1.0`) e o **Atualizar** faz
 a parte mecânica: bump da dependência, re-materialização da camada de IA (skills,
-hooks, agentes) e re-sync do bloco gerenciado do CLAUDE.md. Fora do Maestro:
-`pnpm outdated @softize/opus`.
+hooks, agentes) e re-sync do bloco gerenciado do CLAUDE.md.
+
+Fora do Maestro, faça essa parte à mão:
+
+```bash
+pnpm outdated @softize/opus          # distância até a versão publicada
+pnpm -r up @softize/opus@<versão>    # em todo workspace que declara o Opus
+pnpm run setup                       # opus setup && base setup: re-materializa base.json e skills
+```
+
+Rode `setup` no diretório de cada app que tem `opus.json`; num monorepo criado por
+`opus create --monorepo`, a raiz não tem esse script, e `pnpm -r run setup` alcança todos os apps.
+O postinstall do pacote tenta materializar sozinho, mas é best-effort; se a camada materializada
+ainda corresponder à versão anterior, o `opus check` aborta com
+`base.json: Opus aplicado X, instalado Y`.
 
 ## 2. Ler as mudanças acumuladas
 
@@ -22,19 +35,36 @@ O changelog **viaja no pacote** — depois do bump, está em
 a seção **Breaking** diz a migração (o que renomeou, o que fazer no seu código).
 A esteira de release **recusa** publicar versão sem entrada — o arquivo não defasa.
 
-- **minor** (2.9 → 2.10): compatível; leia por curiosidade.
-- **major** (2.x → 3.0): pare nas seções Breaking de cada versão pulada, na ordem.
+- **minor e patch** (18.0 → 18.1): leia todas as entradas intermediárias. Minors podem pedir ação,
+  como a troca de `PageHeader` por `PageIntro` no `PageShell` (17.2.0) ou o layout desktop fixo (18.1.0).
+- **major** (17.x → 18.0): além disso, aplique as seções Breaking de cada versão pulada, na ordem.
 
 ## 3. Executar as verificações
 
-O Opus ship source: o que quebrou aparece com arquivo e linha. Rode, na ordem:
+O Opus é publicado como código-fonte TypeScript: o que quebrou aparece com arquivo e linha.
+Rode, na ordem:
+
+```bash
+pnpm typecheck               # a API nova cobra os tipos
+pnpm exec opus check         # convenções (regras novas inclusas)
+pnpm exec opus copy --check  # inventário de copy em dia
+pnpm exec base copy check    # política de copy da base
+pnpm test                    # comportamento
+pnpm manifest:check          # a spec projetada ficou fresca?
+```
+
+Num monorepo, `typecheck` e `test` existem na raiz, mas `manifest:check` é script de cada app:
+rode-o no diretório do app ou com `pnpm -r run manifest:check`. Nenhum desses comandos migra o
+banco. Se o projeto tiver testes de integração, eles usam o banco que o próprio projeto configurar.
+
+## 4. Migrar o banco, se houver
+
+Se o `opus.config.ts` declara `database`, confira o schema e aplique a migração como uma etapa
+separada, contra o banco do ambiente que você pretende alterar:
 
 ```bash
-pnpm typecheck        # a API nova cobra os tipos
-pnpm exec opus check  # convenções (regras novas inclusas)
-pnpm test             # comportamento
-pnpm manifest:check   # a spec projetada ficou fresca?
-opus db migrate       # schema em dia (drift-check embutido)
+pnpm exec opus db check      # compara entidades e banco, sem escrever
+pnpm exec opus db migrate    # aplica o schema idempotente; escreve no banco
 ```
 
 Com todas as verificações verdes, revise a atualização como qualquer outra mudança de código antes
@@ -42,6 +72,6 @@ de entregá-la.
 
 ## Pulou muitas versões?
 
-O ritual não muda, só o volume: leia as seções Breaking acumuladas (o changelog é
-uma lista, não um diff), aplique na ordem e deixe os gates validarem o conjunto.
+O ritual não muda, só o volume: leia todas as entradas acumuladas, não só as seções Breaking
+(o changelog é uma lista, não um diff), aplique na ordem e deixe os gates validarem o conjunto.
 Não há caminho especial — é o mesmo laço, com mais iterações.

package/src/ui/docs/doc-client.tsx

@@ -105,7 +105,7 @@ export const docWorkspaceList = defineContract({
         ],
       },
     },
-    client: { label: 'Cliente', type: 'text', advanced: true },
+    client: { label: 'Cliente', type: 'text', placement: 'advanced' },
   },
   text: { fields: ['name'] },
   sort: { fields: ['name'] },

package/src/ui/docs/registry.tsx

@@ -11,6 +11,10 @@
  * helper `comp`; páginas conceituais renderizam o markdown direto (o próprio md traz o H1/lead).
  */
 import { useEffect } from "react";
+import {
+  definePresentation,
+  definePresentationInvocation,
+} from "../../core/presentation.ts";
 import * as lucideIcons from "lucide-react";
 import * as opusUi from "../react.tsx";
 import { componentMeta } from "../meta.ts";
@@ -154,7 +158,7 @@ export interface DocSection {
 // o scope injetado entra POR CIMA do default no DocMarkdown, e `<Badge>` num exemplo
 // tem que ser o COMPONENTE (chip), não o selo do lucide. Ícone colidido, se um exemplo
 // precisar, entra por alias no scope do chamador.
-const iconScope: Record<string, unknown> = Object.fromEntries(
+export const iconScope: Record<string, unknown> = Object.fromEntries(
   Object.entries(lucideIcons).filter(([name]) => !(name in opusUi)),
 );
 
@@ -177,7 +181,7 @@ const comp =
   );
 
 /** O palco dos patterns no scope dos previews: ícones, cliente simulado e contratos de exemplo. */
-const patternScope = {
+export const patternScope = {
   ...iconScope,
   DocBrowserActionProvider,
   docWorkspaceCreate,
@@ -188,12 +192,28 @@ const patternScope = {
   docSessionDelete,
 };
 
+/**
+ * Palco da página de Presentation: o exemplo declara a própria Presentation sobre um contrato do
+ * palco, então precisa das funções de declaração além do palco dos patterns. Fora daqui elas não
+ * entram no scope — os demais previews consomem definições já prontas.
+ */
+export const presentationScope = {
+  ...patternScope,
+  definePresentation,
+  definePresentationInvocation,
+};
+
 /** Página de pattern: igual ao `comp`, mas os previews enxergam o palco doc-client no scope. */
 const pattern =
-  (title: string, key: keyof typeof componentMeta, content: string) =>
+  (
+    title: string,
+    key: keyof typeof componentMeta,
+    content: string,
+    scope: Record<string, unknown> = patternScope,
+  ) =>
   (): React.ReactElement => (
     <DocPage title={title} meta={componentMeta[key]}>
-      <DocMarkdown content={content} scope={patternScope} />
+      <DocMarkdown content={content} scope={scope} />
     </DocPage>
   );
 
@@ -406,7 +426,12 @@ export const UI_SECTIONS: DocSection[] = [
           {
             slug: "presentation",
             title: "Presentation",
-            render: pattern("Presentation", "presentation", presentationMd),
+            render: pattern(
+              "Presentation",
+              "presentation",
+              presentationMd,
+              presentationScope,
+            ),
           },
           {
             slug: "content",

package/src/ui/meta.ts

@@ -15,7 +15,7 @@ export const componentMeta = {
     name: "content",
     ancestry: "opus",
     whenToUse:
-      "Organize uma região nomeada dentro de uma página ou de outra superfície. Use as propriedades de Content no caso comum e componha seus slots quando precisar controlar a estrutura. Para o cabeçalho principal da tela, use Page.",
+      "Organize uma região nomeada dentro de uma página ou de outra superfície. Use as propriedades de Content no caso comum e componha seus slots quando precisar controlar a estrutura. Numa página centrada em uma coleção, `level={1}` faz do Content o heading principal; nas demais, ele vem de PageTitle.",
   },
   ask: {
     name: "ask",
@@ -153,7 +153,7 @@ export const componentMeta = {
     name: "menu",
     ancestry: "opus",
     whenToUse:
-      'O menu de ações da casa: lista flutuante ancorada em um gatilho (Radix DropdownMenu). Compõe Menu > MenuTrigger + MenuContent e seus itens. `context="danger"` sinaliza item com consequência perigosa; `destructive` permanece alias de migração. Para escolher um valor, use Select; para busca por teclado, Command; para conteúdo livre ancorado, Popover.',
+      'O menu de ações da casa: lista flutuante ancorada em um gatilho (Radix DropdownMenu). Compõe Menu > MenuTrigger + MenuContent e seus itens. `context="danger"` sinaliza item com consequência perigosa. Para escolher um valor, use Select; para busca por teclado, Command; para conteúdo livre ancorado, Popover.',
   },
   popover: {
     name: "popover",
@@ -189,7 +189,7 @@ export const componentMeta = {
     name: "table",
     ancestry: "shadcn",
     whenToUse:
-      'Tabela de dados. Compõe Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). `variant="plain"` vem sem borda externa; `variant="framed"` aplica a moldura canônica, recorta o scroll e destaca o cabeçalho. Para listagem tabular — para o pattern de search use ActionList.',
+      'Tabela de dados. Compõe Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). `variant="plain"` vem sem borda externa; `variant="framed"` aplica a moldura canônica, recorta o scroll e destaca o cabeçalho. Para uma coleção com busca, filtros e paginação, use ActionList.',
   },
   tabs: {
     name: "tabs",
@@ -279,7 +279,7 @@ export const componentMeta = {
     name: "field",
     ancestry: "shadcn",
     whenToUse:
-      "Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e as orientações horizontal ou responsiva quando controle e texto precisarem ficar lado a lado. Field cuida do layout; o formulário continua responsável por estado e validação.",
+      "Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado; `responsive` continua aceito como alias da horizontal. Field cuida do layout; o formulário continua responsável por estado e validação.",
   },
   "input-otp": {
     name: "input-otp",
@@ -321,7 +321,7 @@ export const componentMeta = {
     name: "split",
     ancestry: "opus",
     whenToUse:
-      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. É o mecanismo espacial para sidebar, conteúdo e rail.",
+      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
   },
   sidebar: {
     name: "sidebar",

package/src/ui/react.tsx

@@ -424,6 +424,7 @@ export {
   PresentationInspector,
 } from "./components/patterns/presentation.tsx";
 export type {
+  PresentationAssistantRuntime,
   PresentationProps,
   PresentationInspectorProps,
 } from "./components/patterns/presentation.tsx";
@@ -483,6 +484,10 @@ export type {
   SplitLayoutChange,
 } from "./components/patterns/split.tsx";
 
+// Assistência contextual: mantém o recurso visível e abre um painel redimensionável na superfície.
+export { SurfaceAssistant } from "./components/patterns/surface-assistant.tsx";
+export type { SurfaceAssistantProps } from "./components/patterns/surface-assistant.tsx";
+
 // A barra de ferramentas que flutua sobre uma superfície de trabalho (canvas, editor, preview).
 export {
   Dock,