@softize/opus 18.0.1 → 18.1.1

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

@@ -92,7 +92,17 @@ Na composição explícita, combine somente as regiões necessárias. Este exemp
 uma ação global e o intro para o título:
 
 ```tsx preview col
-<PageShell navigation={<Breadcrumb>...</Breadcrumb>}>
+<PageShell
+  navigation={
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>Vendas</BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbPage>Clientes</BreadcrumbPage>
+      </BreadcrumbList>
+    </Breadcrumb>
+  }
+>
   <Page>
     <PageHeader>
       <PageActions>
@@ -172,7 +182,7 @@ e, sem `title`, valem `errorMessage` e `emptyMessage`.
     status="empty"
     title="Nenhum relatório"
     description="Crie o primeiro relatório para começar."
-    action={<Button>Novo relatório</Button>}
+    action={<Button>Criar relatório</Button>}
   />
 </Page>
 ```
@@ -185,7 +195,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | Propriedade | Tipo        | Padrão      | Descrição                                                                                       |
 | ----------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
 | `title`     | `ReactNode` |             | O h1 da página.                                                                                 |
-| `actions`   | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho; em telas estreitas, ficam abaixo do contexto. |
+| `actions`   | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho. |
 | `className` | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
 | `children`  | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
 
@@ -204,7 +214,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade | Tipo                          | Descrição                                                             |
 | ----------- | ----------------------------- | --------------------------------------------------------------------- |
-| `children`  | `ReactNode`                   | Título introdutório e, quando necessário, ações ligadas à introdução. |
+| `children`  | `ReactNode`                   | `PageBack` ou `PageNavigation`, título introdutório e, quando necessário, ações ligadas à introdução. |
 | `className` | `string`                      | Classes adicionais da região introdutória.                            |
 | demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região introdutória.                   |
 
@@ -212,15 +222,19 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade | Tipo        | Descrição                                                                                |
 | ----------- | ----------- | ---------------------------------------------------------------------------------------- |
-| `className` | `string`    | Classes adicionais da região externa do cabeçalho.                                       |
+| `className` | `string`    | Classes adicionais da região externa do cabeçalho, fora de `PageShell`.                  |
 | `children`  | `ReactNode` | `PageBack` ou `PageNavigation`, `PageActions` e, fora do shell, um `PageTitle` opcional. |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região externa do cabeçalho, fora de `PageShell`. |
+
+Dentro de `PageShell`, `PageHeader` não renderiza uma região própria: devolve somente os filhos,
+que o shell projeta na barra, e ignora `className` e os demais atributos.
 
 ## Propriedades de PageBack
 
 | Propriedade  | Tipo                                   | Padrão                   | Descrição                                                                                  |
 | ------------ | -------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
 | `href`       | `string`                               | obrigatório              | Destino explícito da página pai. Sem ele o retorno não é tabulável nem tem nome acessível. |
-| `children`   | `ReactNode`                            |                          | Nome do destino pai usado no rótulo acessível e no tooltip.                                |
+| `children`   | `ReactNode`                            | obrigatório              | Nome do destino pai usado no rótulo acessível e no tooltip.                                |
 | `aria-label` | `string`                               | `Voltar para {children}` | Nome acessível; informe-o quando `children` não for texto simples.                         |
 | `onClick`    | `MouseEventHandler<HTMLAnchorElement>` |                          | Integração opcional com o roteador do consumidor, junto do `href`, nunca no lugar dele.    |
 | `className`  | `string`                               |                          | Classes adicionais do link renderizado como botão `ghost`.                                 |

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

@@ -131,7 +131,7 @@ render(
 | `page` | `number` | | Número usado como conteúdo, quando `children` não é informado, e no nome acessível “Página N”. |
 | `isActive` | `boolean` | `false` | Marca a página atual com `aria-current="page"` e tratamento `outline`. |
 | `href` | `string` | | Renderiza um `<a>`. Sem `href`, o componente usa `<button>` e aceita `onClick` e `disabled`. |
-| `size` | `ButtonProps['size']` | `'default'` | A escala única, via `Button`. A largura mínima cresce para acomodar números longos; os `icon-*` são quadrados. |
+| `size` | `ButtonProps['size']` | `'default'` | A escala única, via `Button`. Os `icon-*` são quadrados. Nos tamanhos textuais, a altura fica fixa em 2.25rem com largura mínima quadrada que cresce para números longos, então `size="sm"` não reduz a altura; para uma barra mais baixa, use um `icon-*` ou ajuste por `className` (ex.: `h-7 min-w-7 text-xs`). |
 
 ## Propriedades de PaginationPrevious e PaginationNext
 
@@ -139,5 +139,12 @@ render(
 |---|---|---|---|
 | `label` | `string` | `'Página anterior'` ou `'Próxima página'` | Nome acessível e texto visível da ação. |
 | `iconOnly` | `boolean` | `false` | Exibe somente a seta; `label` continua disponível para leitura assistiva. |
-| `size` | `ButtonProps['size']` | `'default'`; `'icon'` com `iconOnly` | A escala única; `icon-sm` para o rodapé denso. |
+| `size` | `ButtonProps['size']` | `'default'`; `'icon'` com `iconOnly` | A escala única; `icon-sm` para o rodapé denso. Sem `iconOnly`, a altura permanece 2.25rem em qualquer tamanho textual, como em `PaginationLink`. |
 | `iconClassName` | `string` | | Classes aplicadas ao ícone da seta, quando o glifo da escala não servir. |
+
+## Propriedades de PaginationEllipsis
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `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. |

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

@@ -29,13 +29,13 @@ detalhes.
 
 ```tsx preview
 <Popover>
-  <PopoverTrigger asChild><Button variant="ghost">start</Button></PopoverTrigger>
+  <PopoverTrigger asChild><Button variant="ghost">Início</Button></PopoverTrigger>
   <PopoverContent align="start" className="w-56">
     <PopoverDescription>Alinhado à borda esquerda do gatilho.</PopoverDescription>
   </PopoverContent>
 </Popover>
 <Popover>
-  <PopoverTrigger asChild><Button variant="ghost">end</Button></PopoverTrigger>
+  <PopoverTrigger asChild><Button variant="ghost">Fim</Button></PopoverTrigger>
   <PopoverContent align="end" className="w-56">
     <PopoverDescription>Alinhado à borda direita do gatilho.</PopoverDescription>
   </PopoverContent>

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

@@ -5,12 +5,14 @@ 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 encerram o footer dividido igualmente entre `Cancelar`
-em `outline` e a ação principal.
+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 `default`. Nas demais Presentations, o
-título abre o conteúdo em `PageIntro` e comandos da superfície usam `default`.
+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
@@ -22,25 +24,20 @@ compõe `PageBody` e, quando necessário, `PageFooter`. Para uma action `list`,
 `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 botão `default`.
+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.
 
-```tsx live
-const workspaceUpdate = defineContract({
-  name: "workspace.update",
-  kind: "form",
-  label: "Editar workspace",
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string() }),
-  fields: { name: { label: "Nome" } },
-});
+O exemplo declara a 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.
 
+```tsx live
 const workspacePresentation = definePresentation({
   schemaVersion: 1,
-  id: "workspace.update",
-  title: "Editar workspace",
-  body: { action: workspaceUpdate.name },
+  id: "workspace.create",
+  title: "Criar workspace",
+  body: { action: docWorkspaceCreate.name },
 });
 
 function Example() {
@@ -55,36 +52,38 @@ function Example() {
   );
 
   return (
-    <div className="space-y-4">
-      <ButtonGroup mode="spaced">
-        {["page", "dialog", "drawer"].map((value) => (
-          <Button
-            key={value}
-            size="sm"
-            variant={invocation.surface === value ? "solid" : "outline"}
-            onClick={() => {
-              setInvocation({ ...invocation, surface: value });
-              setOpen(true);
-            }}
-          >
-            {value}
-          </Button>
-        ))}
-      </ButtonGroup>
-
-      <Presentation
-        definition={workspacePresentation}
-        definitions={[workspacePresentation]}
-        actions={{ [workspaceUpdate.name]: workspaceUpdate }}
-        invocation={invocation}
-        open={invocation.surface === "page" || open}
-        onOpenChange={setOpen}
-        onInvocationChange={(next) => {
-          if (next) setInvocation(next);
-          else setOpen(false);
-        }}
-      />
-    </div>
+    <DocBrowserActionProvider>
+      <div className="space-y-4">
+        <ButtonGroup mode="spaced">
+          {["page", "dialog", "drawer"].map((value) => (
+            <Button
+              key={value}
+              size="sm"
+              variant={invocation.surface === value ? "solid" : "outline"}
+              onClick={() => {
+                setInvocation({ ...invocation, surface: value });
+                setOpen(true);
+              }}
+            >
+              {value}
+            </Button>
+          ))}
+        </ButtonGroup>
+
+        <Presentation
+          definition={workspacePresentation}
+          definitions={[workspacePresentation]}
+          actions={{ [docWorkspaceCreate.name]: docWorkspaceCreate }}
+          invocation={invocation}
+          open={invocation.surface === "page" || open}
+          onOpenChange={setOpen}
+          onInvocationChange={(next) => {
+            if (next) setInvocation(next);
+            else setOpen(false);
+          }}
+        />
+      </div>
+    </DocBrowserActionProvider>
   );
 }
 
@@ -174,6 +173,8 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 | `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.   |
 | `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                |
 | `onRefresh`          | `(action: string \| null) => void`               |        | Recebe invalidações declaradas após sucesso.           |
+| `listState`          | `ActionListState`                                |        | Recorte controlado da action `list` do body, quando a aplicação o sincroniza com a URL. |
+| `onListStateChange`  | `(state: ActionListState) => void`               |        | Recebe cada mudança de recorte ou exibição da lista do body, como busca, filtros, período e página. |
 | `open`               | `boolean`                                        | `true` | Estado controlado de Dialog ou Drawer.                 |
 | `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.    |
 | `className`          | `string`                                         |        | Classes adicionais da superfície.                      |

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

@@ -29,13 +29,9 @@ render(
       <span className="text-muted-foreground">{step}%</span>
     </div>
     <Progress value={step} />
-    <button
-      type="button"
-      onClick={advance}
-      className="rounded-md border px-3 py-1.5 text-sm hover:bg-muted"
-    >
+    <Button variant="outline" size="sm" onClick={advance}>
       Avançar etapa
-    </button>
+    </Button>
   </div>,
 )
 ```

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

@@ -38,16 +38,17 @@ await runtime.start()
 
 | Capacidade | Fornece | Driver pronto |
 |---|---|---|
-| `server` | monta as actions (HTTP) | `fastifyServer` — `@softize/opus/server/fastify` |
+| `server` | monta as actions (HTTP) | `fastifyServer` — `@softize/opus/server/fastify` · `nodeServer` — `…/server/node` |
 | `data` | `ctx.db` + drift-check + CRUD | `kyselyData`, `kyselyRepo`, `crudActions` — `@softize/opus/data/kysely` |
 | `auth` | `user`/`tenantId`/`can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
 | `audit` | trilha por execução de action | `pgAudit` — `…/audit/pg` · `consoleAudit` — `…/audit/console` |
-| `log` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
-| `observability` | span ativo + propagação de trace | porta no core; driver opt-in |
+| `logger` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
+| `observability` | span ativo + propagação de trace | `openTelemetryObservability` — `@softize/opus/observability/opentelemetry` |
 | `eventBus` | `ctx.emit` + **reactions** | `mittEvents` — `@softize/opus/events/mitt` |
 | `queue` | jobs em background | `bullmqQueue` — `@softize/opus/queue/bullmq` |
 | `scheduler` | **schedules** (cron/intervalo) | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
 | `storage` | `ctx.storage` (arquivos) | `fsStorage` — `…/storage/fs` · `s3Storage` — `…/storage/s3` |
+| `cache` | `ctx.cache` (leitura, experimental) | `memoryCache` — `@softize/opus/cache/memory` |
 | `ai` | `ctx.ai` (complete/extract) | `anthropicAi` — `@softize/opus/ai/anthropic` |
 | `client` | chamar actions de fora (stubs) | `fetchClient` — `@softize/opus/client/fetch` |
 
@@ -61,7 +62,7 @@ Fora do runtime, mas parte do protocolo: o harness de teste (`runAction`/`testCo
 > e o handler decide como degradar.
 
 `user`/`tenantId`/`can` (auth) · `db` (data) · `log` (logger) · `emit` (eventBus) ·
-`storage` (storage) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
+`storage` (storage) · `cache` (cache) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
 reaction…) · `trace` (quando configurado) · `meta`.
 
 O core não depende de OpenTelemetry. O `ObservabilityAdapter` envolve actions e reactions
@@ -85,7 +86,9 @@ representa span de erro. Reactions usam `resultKind: 'void'` e rejeitam em falha
 > tempo dispara schedule (que executa uma action, com provenance própria).
 
 Declarados como as actions e registrados no mesmo `runtime.register` — o manifest
-projeta os três (o Maestro mostra o wiring em Visão geral).
+projeta os três. `opus introspect` lista reactions, schedules e o wiring entre eles, mas por
+enquanto só reconhece actions declaradas com `defineAction`: as do split `defineContract` +
+`bindAction` ficam de fora do modelo que ele monta.
 
 ## Referência profunda
 

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

@@ -19,7 +19,7 @@ interface ScheduleDef {
   action: string              // action do registry, executada quando dispara
   cron?: string               // '0 9 * * *' (9h todo dia)
   every?: string              // '1h', '30m', '15s' — atalho de intervalo
-  timezone?: string           // IANA, ex.: 'America/Sao_Paulo' (default UTC)
+  timezone?: string           // IANA, ex.: 'America/Sao_Paulo' (sem ele: hora local do processo)
   input?: unknown | (() => unknown | Promise<unknown>)   // estático ou dinâmico
   enabled?: boolean
 }

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

@@ -26,8 +26,9 @@ render(
 
 ## Lista pesquisável
 
-Use `searchable` quando a quantidade ou os rótulos dificultarem encontrar uma opção. O próprio
-campo passa a filtrar `label`, `hint` e `value` com a busca do cmdk.
+Use `searchable` quando a quantidade ou os rótulos dificultarem encontrar uma opção. O gatilho
+continua exibindo a escolha; a busca aparece em uma linha no topo da lista e filtra `label`, `hint`
+e `value`.
 
 ```tsx preview col md
 const [issue, setIssue] = useState('')
@@ -40,7 +41,7 @@ render(
       id="issue"
       value={issue}
       onChange={setIssue}
-      placeholder="Buscar item…"
+      placeholder="Selecione a issue"
       options={[
         { value: '412', label: 'Ajustar microcopy do handoff', hint: 'SOF-412' },
         { value: '418', label: 'Preview da sessão cai após deploy', hint: 'SOF-418' },
@@ -323,7 +324,7 @@ render(
       { value: 'gra-7', label: 'Filtro por filial', hint: 'GRA-7' },
     ]}
     trailing={
-      <Button variant="ghost" size="icon-xs">
+      <Button variant="ghost" size="icon-xs" aria-label="Abrir tarefa">
         <FileText />
       </Button>
     }
@@ -338,12 +339,12 @@ render(
 | `options` | `SelectOption[]` | | As opções: `{ value, label, hint?, content?, triggerLabel?, group?, disabled? }`. |
 | `value` | `string \| string[]` | | O selecionado: string no single, string[] no multiple. |
 | `onChange` | `(value: string) => void \| (value: string[]) => void` | | Chamado ao escolher (e ao remover chip, no multiple) — a assinatura segue o modo. |
-| `native` | `boolean` | `false` | Renderiza o `<select>` do sistema. Exclui busca, multi e ghost (o browser é quem desenha a lista). |
-| `searchable` | `boolean` | `false` | O campo vira busca: filtra a lista enquanto digita. |
+| `native` | `boolean` | `false` | Renderiza o `<select>` do sistema. Exclui busca, seleção múltipla e variantes visuais (o browser é quem desenha a lista). |
+| `searchable` | `boolean` | `false` | Acrescenta uma linha de busca no topo da lista, que filtra as opções enquanto a pessoa digita. O gatilho continua exibindo a escolha. |
 | `multiple` | `boolean` | `false` | Chips removíveis, lista que permanece aberta e Selecionar tudo. |
-| `variant` | `'default' \| 'ghost'` | `'default'` | `ghost` = sem moldura, para barra do composer. |
+| `variant` | `'default' \| 'outline' \| 'ghost'` | `'default'` | `outline` = compacto com borda; `ghost` = compacto sem borda nem fundo, para barra do composer. |
 | `placeholder` | `string` | `'Selecione…'` | Texto do campo vazio. |
-| `searchPlaceholder` | `string` | | Placeholder enquanto busca; cai para o `placeholder` se ausente. |
+| `searchPlaceholder` | `string` | `'Buscar…'` | Placeholder da linha de busca dentro da lista. |
 | `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
 | `onSearch` | `(query: string) => void` | | Busca server-side (debounced, ao abrir e ao digitar): desliga o filtro do cmdk — o pai atualiza `options`. |
 | `loading` | `boolean` | | Mostra Buscando… enquanto o fetch corre (use com `onSearch`). |
@@ -351,6 +352,10 @@ render(
 | `icon` | `React.ReactNode` | | Ícone leading DENTRO do controle (decorativo) — herda `size-4` e o tom muted. |
 | `trailing` | `React.ReactNode` | | Ação custom no FIM do controle (antes do chevron) — o clique não abre a lista. |
 | `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) para toolbar densa. |
+| `shape` | `'default' \| 'pill'` | `'default'` | Geometria do controle; `pill` arredonda as extremidades e preserva a variante visual. |
 | `disabled` | `boolean` | `false` | Esmaece e trava o controle. |
 | `id` | `string` | | Vai para o campo — para parear com o `htmlFor` do Label. |
+| `aria-label` | `string` | | Nome acessível quando não há `Label` associado. |
+| `aria-invalid` | `boolean` | | Comunica e apresenta o estado inválido. |
+| `aria-describedby` | `string` | | Liga o controle a uma ajuda ou mensagem de erro. |
 | `className` | `string` | | Classes da raiz do controle, incluindo campo, ícones e ações, em todos os modos. |

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

@@ -63,7 +63,7 @@ uma sidebar fixa, redimensionável ou recolhida.
 | `PaneFooter` | Mantém ações persistentes no rodapé. |
 | `SidebarNav` | Apresenta e controla os destinos de navegação. |
 
-`PaneContent` permanece como alias temporário de `PaneBody` durante a versão 12. Código novo usa
+`PaneContent` continua exportado como alias depreciado de `PaneBody`. Código novo usa
 `PaneBody`.
 
 ## Escolher a navegação
@@ -138,7 +138,8 @@ páginas são folhas. Um grupo começa aberto e volta a abrir quando contém a p
 
 `collapsed` pertence à `Sidebar`. Nesse estado, `SidebarItem` e `SidebarNav` mantêm
 somente os ícones e expõem os rótulos em tooltips. Por isso, todo destino que aparece no modo
-recolhido precisa de um ícone reconhecível e de um `label` completo.
+recolhido precisa de um ícone reconhecível e de um `label` completo. `SidebarNav` já monta o
+`TooltipProvider`; um `SidebarItem` recolhido fora dele depende do provider na raiz do aplicativo.
 
 O slot de ícone do `SidebarItem` ocupa `1rem` nos dois estados e normaliza SVGs para essa medida.
 O consumidor escolhe o símbolo e sua cor sem precisar repetir largura ou altura em ícones SVG.

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

@@ -15,7 +15,7 @@ avatares e barras com dimensões próximas às linhas de texto esperadas.
 
 ## Card em carregamento
 
-O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para tela não pular quando os dados chegarem.
+O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para a tela não pular quando os dados chegarem.
 
 ```tsx preview col
 <Card>

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/tabs.md

@@ -4,12 +4,15 @@ Use `Tabs` para alternar painéis relacionados no mesmo contexto. O `value` de c
 corresponde ao `TabsContent` que ele abre. `defaultValue` define a aba inicial no modo não
 controlado.
 
+`icon` posiciona um ícone decorativo antes do rótulo e normaliza SVGs para `1rem`. Quando a aba
+mostrar somente o ícone, declare `aria-label` para preservar seu nome acessível.
+
 ```tsx preview col
 <Tabs defaultValue="sessions">
   <TabsList>
-    <TabsTrigger value="overview">Visão geral</TabsTrigger>
-    <TabsTrigger value="sessions">Sessões</TabsTrigger>
-    <TabsTrigger value="skills">Skills</TabsTrigger>
+    <TabsTrigger value="overview" icon={<LayoutDashboard />}>Visão geral</TabsTrigger>
+    <TabsTrigger value="sessions" icon={<History />}>Sessões</TabsTrigger>
+    <TabsTrigger value="skills" icon={<Settings />}>Skills</TabsTrigger>
   </TabsList>
   <TabsContent value="overview">
     <p className="text-sm text-muted-foreground">Resumo do workspace Empresa X.</p>
@@ -25,8 +28,14 @@ controlado.
 
 ## Variante line
 
-Use `variant="line"` em `TabsList` quando a lista precisar se integrar a uma borda, como em um
-cabeçalho. A aba ativa é marcada por uma linha em vez de uma superfície preenchida.
+Use `variant="line"` em `TabsList` quando a navegação precisar de uma linha-base, como em um
+cabeçalho. Na orientação horizontal, a lista ocupa toda a largura disponível e a aba ativa é
+marcada sobre essa linha, em vez de usar uma superfície preenchida. Dentro de `DrawerBody`, a
+linha atravessa o gutter até as bordas do drawer sem deslocar os rótulos. O mesmo comportamento
+vale para `DialogBody`.
+Os itens removem o padding horizontal, usam `0.75rem` de padding vertical e preservam `1.25rem`
+de espaço entre si. Nessa orientação, a altura é definida pelo conteúdo para que o padding
+vertical amplie a área interativa.
 
 ```tsx preview col
 <Tabs defaultValue="agents">
@@ -49,8 +58,8 @@ cabeçalho. A aba ativa é marcada por uma linha em vez de uma superfície preen
 
 ## 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">
@@ -78,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>
 ```
@@ -92,17 +101,18 @@ 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
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `variant` | `'default' \| 'line'` | `'default'` | `default` usa uma superfície preenchida; `line` marca a aba ativa junto à borda. |
+| `variant` | `'default' \| 'line'` | `'default'` | `default` usa uma superfície preenchida; `line` cria uma linha-base horizontal de largura total e marca nela a aba ativa. |
 
 ## Propriedades de TabsTrigger e TabsContent
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `string` | | Identificador que associa o gatilho ao painel correspondente. |
+| `icon` | `ReactNode` | | Ícone decorativo antes do rótulo; SVGs usam `1rem`. |

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

@@ -3,7 +3,8 @@
 Use `toast` para informar o resultado temporário de uma ação sem interromper o fluxo. Cada tipo usa o
 ícone correspondente do Opus. Escreva o título como rótulo, sem ponto final, e a descrição como uma
 frase. A moldura do ícone permanece quadrada e alinhada à primeira linha mesmo quando a descrição
-ocupa várias linhas.
+ocupa várias linhas. Corpo e padding seguem os mesmos `0.875rem` e `0.75rem` do Alert; os defaults
+internos do Sonner não definem a densidade da casa.
 
 ```tsx preview
 <Button variant="outline" onClick={() => toast.success('Workspace criado')}>Sucesso</Button>
@@ -30,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
@@ -87,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. |