@softize/opus 19.0.0 → 20.0.0

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
 

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

@@ -1,18 +1,26 @@
 ## Progresso determinado
 
-Use `Progress` quando a tarefa informar uma porcentagem de conclusão. `value` aceita valores de 0 a
-100 e anima o preenchimento a cada mudança. Sem valor, a barra permanece vazia.
+Use `Progress` quando a tarefa informar quanto já foi concluído. `value` aceita valores de 0 a
+`max`, que por padrão é 100, e anima o preenchimento a cada mudança. Para contar etapas, declare
+`max` com o total: `value={3} max={4}` preenche três quartos da barra. Quando a duração da espera
+não é conhecida, use [`Spinner`](/ui/spinner).
+
+A barra é exposta aos leitores de tela como `progressbar`, com o valor atual, mas o texto ao lado
+dela não a nomeia automaticamente. Ligue o rótulo visível à barra com `aria-labelledby` ou, sem
+rótulo visível, passe `aria-label`.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-2">
   <div className="flex items-center justify-between text-sm">
-    <span>opus check</span>
+    <span id="progress-check">opus check</span>
     <span className="text-muted-foreground">65%</span>
   </div>
-  <Progress value={65} />
+  <Progress value={65} aria-labelledby="progress-check" />
 </div>
 ```
 
+Sem `value`, ou com `null`, a barra fica vazia e é exposta como progresso indeterminado.
+
 ## Controlado
 
 Controle `value` externamente quando o progresso acompanhar uma tarefa em andamento. No exemplo,
@@ -20,15 +28,16 @@ cada clique avança uma etapa da sincronização.
 
 ```tsx preview col
 const [step, setStep] = useState(40)
+const labelId = useId()
 const advance = (): void => setStep((prev) => Math.min(prev + 20, 100))
 
 render(
   <div className="w-full max-w-sm space-y-3">
     <div className="flex items-center justify-between text-sm">
-      <span>Sincronizar Empresa X</span>
+      <span id={labelId}>Sincronizar Empresa X</span>
       <span className="text-muted-foreground">{step}%</span>
     </div>
-    <Progress value={step} />
+    <Progress value={step} aria-labelledby={labelId} />
     <Button variant="outline" size="sm" onClick={advance}>
       Avançar etapa
     </Button>
@@ -39,18 +48,19 @@ render(
 ## Altura e contexto
 
 `context` diz o que o andamento comunica — `success` para meta atingida, `warning` ou `danger`
-para atenção — e tinge trilha e preenchimento com a família semântica. `className` compõe sobre o
-padrão para ajustar a altura.
+para atenção — e tinge trilha e preenchimento com a família semântica. A cor reforça o significado,
+mas não o substitui: mantenha o rótulo e o valor legíveis. `className` compõe sobre o padrão para
+ajustar a altura.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-4">
   <div className="space-y-1.5">
-    <span className="text-sm">Cobertura de testes</span>
-    <Progress value={92} context="success" className="h-1.5" />
+    <span id="progress-coverage" className="text-sm">Cobertura de testes</span>
+    <Progress value={92} context="success" className="h-1.5" aria-labelledby="progress-coverage" />
   </div>
   <div className="space-y-1.5">
-    <span className="text-sm">Skills cobertas pelo revisor</span>
-    <Progress value={45} context="warning" className="h-3" />
+    <span id="progress-review" className="text-sm">Skills cobertas pelo revisor</span>
+    <Progress value={45} context="warning" className="h-3" aria-labelledby="progress-review" />
   </div>
 </div>
 ```
@@ -59,6 +69,9 @@ padrão para ajustar a altura.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `number \| null` | | O progresso de 0 a 100. O preenchimento anima a cada mudança; null/ausente deixa a barra vazia. |
+| `value` | `number \| null` | | O progresso de 0 a `max`. O preenchimento anima a cada mudança; sem valor, a barra fica vazia e indeterminada. |
+| `max` | `number` | `100` | O valor que representa a conclusão. O preenchimento é a fração `value / max`. |
 | `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | O que o andamento comunica; tinge trilha e preenchimento pela família `--context-*`. |
-| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3). |
+| `aria-label` | `string` | | Nome acessível da barra quando não há rótulo visível. |
+| `aria-labelledby` | `string` | | `id` do rótulo visível que nomeia a barra. |
+| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (`h-1.5`, `h-3`). |

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

@@ -5,7 +5,7 @@ title: Filas
 # Filas
 
 Use uma action em background quando a operação não puder manter a requisição aberta. O
-`QueueAdapter` enfileira o trabalho e devolve um `JobHandle` para acompanhamento pelo cliente.
+`QueueAdapter` enfileira o trabalho e devolve um `JobHandle` para acompanhar o andamento.
 
 ## O contrato
 
@@ -21,18 +21,21 @@ interface JobHandle<T = unknown> {
   jobId: string
   action: string
   status: 'queued' | 'running' | 'done' | 'failed' | 'cancelled'
-  progress?: { percent?: number; message?: string }
+  progress?: { percent?: number; message?: string; data?: unknown }
   data?: T
   error?: ActionError
+  enqueuedAt: string
+  startedAt?: string
+  finishedAt?: string
   attempts: number
   trace?: TraceContext
 }
 ```
 
-`runtime.execute()` valida a chamada, cria o `JobSpec` e inclui o trace efetivo, request ID e
-provenance original. O adapter persiste o envelope; o handle também expõe esse trace. No
-worker, `runtime.executeJob()` revalida o envelope e executa um span filho, preservando a
-cadeia request → enqueue → job sem aceitar baggage ou campos extras no carrier.
+`runtime.execute()` valida a chamada, cria o `JobSpec` e inclui o trace efetivo, o request ID e a
+provenance original. O adapter persiste esse envelope, e o handle também expõe o trace. No worker,
+`runtime.executeJob()` revalida o envelope e executa um span filho, preservando a cadeia requisição
+→ enfileiramento → job sem aceitar baggage ou campos extras.
 
 ## Driver
 
@@ -43,26 +46,41 @@ import { bullmqQueue } from '@softize/opus/queue/bullmq'
 const queue = bullmqQueue({ queue: new Queue('opus', { connection: { host: 'localhost' } }) })
 ```
 
-Redis-backed (durável, entre-processos, retries). Peers opcionais (`bullmq`, `ioredis`) só
-para quem usa o driver.
+O driver usa Redis por meio do BullMQ, com durabilidade, entrega entre processos e novas tentativas.
+`bullmq` é dependência opcional: só precisa ser instalado por quem usa o driver.
 
-## No runtime
+## Declarar a action em background
+
+Configure a fila no runtime e declare `background` no binding da action:
 
 ```ts
 const runtime = createRuntime({
   // …server/data…
   queue,
 })
+
+export const relatorioGerar = bindAction(relatorioGerarContract, {
+  background: { enabled: true, retry: { attempts: 3 }, progress: true },
+  handler: async (ctx, input, loaded, progress) => {
+    await progress?.report({ percent: 50, message: 'Consultando dados' })
+    return gerarRelatorio(input)
+  },
+})
 ```
 
-A action declara `background: { enabled: true }` (+ retry/priority no contrato); chamá-la devolve um
-`JobHandle` em vez do resultado, e o cliente pola `status(jobId)` (ou `subscribe`) até
-`done`/`failed`.
+Só actions `simple` e `form` executam em background; além de `retry` e `progress`, a configuração
+aceita `queue`, `priority` e `timeout`. Em uma action `list` ou `view`, o tipo do binding aceita
+`background`, mas o runtime o ignora e executa a action na própria requisição. Para evitar essa
+surpresa, o runtime avisa ao registrar a action fora de produção (`runtime.action_field_ignored`), e
+o [`opus check`](/docs/cli) aponta a regra `ignored-by-kind`. Sem `QueueAdapter`, a chamada falha com
+`runtime.queue_required`. Chamar a action devolve um `JobHandle` em vez do resultado. O Opus não
+monta uma rota de acompanhamento: exponha `queue.status(jobId)` ou `queue.subscribe` por uma action
+ou rota do próprio app até o job chegar a `done` ou `failed`.
 
 ## Worker BullMQ
 
-O app continua dono do `Worker` e da reidratação de autenticação. O processor chama
-`executeJob()` — nunca `execute()`, que criaria outro job:
+O app continua dono do `Worker` e de reconstruir a autenticação de quem enfileirou. O processor
+chama `executeJob()`, e não `execute()`, que criaria outro job:
 
 ```ts
 new Worker('opus', async (job) => {
@@ -76,13 +94,13 @@ new Worker('opus', async (job) => {
 }, { connection })
 ```
 
-O runtime confirma que o actor reidratado corresponde a `spec.ctx.userId`; tenant, request,
-trace e provenance vêm do envelope. O driver mapeia `attempts`, backoff nativo e prioridade.
-Multiplicador exponencial diferente de 2 ou `maxMs` exige `backoffStrategy` custom do worker e
-é rejeitado pelo driver em vez de ser silenciosamente ignorado. `timeout` permanece no
-envelope para o worker aplicar, pois não é uma opção de execução do `Queue.add`.
+O runtime confirma que o usuário reconstruído corresponde a `spec.ctx.userId`; tenant, request,
+trace e provenance vêm do envelope. O driver traduz `attempts`, o backoff nativo e a prioridade para
+o BullMQ. Um backoff exponencial com multiplicador diferente de 2 ou com `maxMs` exige uma
+`backoffStrategy` própria no worker, e o driver o recusa em vez de ignorá-lo em silêncio. `timeout`
+permanece no envelope para o worker aplicar, porque não é uma opção de execução do `Queue.add`.
 
 ## Limites atuais
 
-Driver hoje: `bullmq` (Redis). In-memory para dev e outros backends (SQS, pg-boss…) entram
-por reincidência.
+O único driver é o `bullmq`. Uma fila em memória para desenvolvimento e outros backends, como SQS e
+pg-boss, ainda não existem.

package/src/ui/docs/content/radio-group.md

@@ -1,8 +1,10 @@
 ## Escolha única
 
-Use `RadioGroup` quando todas as opções mutuamente exclusivas precisarem permanecer visíveis. Cada
-`RadioGroupItem` declara um `value` e deve estar associado a um `Label`. `defaultValue` define a
-opção inicial no modo não controlado.
+Use `RadioGroup` quando todas as opções mutuamente exclusivas precisarem permanecer visíveis. Com
+muitas opções, prefira [`Select`](/ui/select); para ligar ou desligar um único item, use
+[`Checkbox`](/ui/checkbox) ou [`Switch`](/ui/switch). Cada `RadioGroupItem` declara um `value` e
+deve estar associado a um `Label`, escrito logo depois do item. `defaultValue` define a opção
+inicial no modo não controlado.
 
 ```tsx preview col-start
 <RadioGroup defaultValue="balanced">
@@ -68,6 +70,25 @@ bloquear todas as opções, aplique `disabled` ao `RadioGroup`.
 </RadioGroup>
 ```
 
+## Estado inválido
+
+Quando a escolha for obrigatória e nenhuma opção estiver marcada, declare `aria-invalid` em cada
+`RadioGroupItem` e explique o que falta em um texto associado ao grupo por `aria-describedby`.
+
+```tsx preview col-start
+<RadioGroup aria-describedby="review-mode-error">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="review-auto" value="auto" aria-invalid />
+    <Label htmlFor="review-auto">Revisar automaticamente</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="review-manual" value="manual" aria-invalid />
+    <Label htmlFor="review-manual">Revisar manualmente</Label>
+  </div>
+</RadioGroup>
+<FieldError id="review-mode-error">Escolha como a sessão será revisada.</FieldError>
+```
+
 ## Propriedades de RadioGroup
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -82,4 +103,5 @@ bloquear todas as opções, aplique `disabled` ao `RadioGroup`.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `string` | | Valor que o item atribui ao grupo quando selecionado. |
-| `disabled` | `boolean` | `false` | Desabilita somente este item; o `Label` associado acompanha o estado. |
+| `disabled` | `boolean` | `false` | Desabilita somente este item; o `Label` escrito logo depois dele acompanha o estado. |
+| `aria-invalid` | `boolean` | | Aplica a borda e o anel de erro ao item. |

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

@@ -19,11 +19,13 @@ function App() {
 O router oferece leitura reativa da URL e `navigate`; o aplicativo decide o que renderizar. Ele não
 inclui tabela de rotas, parâmetros tipados nem carregamento de dados.
 
-A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:postId`), params tipados ou data loaders, o caso pede uma biblioteca de rotas, não isto. Um app de back-office com uma dúzia de destinos quase nunca precisa.
+Se a tela precisa casar padrões como `/users/:id/posts/:postId`, receber parâmetros tipados ou
+carregar dados por rota, use uma biblioteca de rotas. Um app de back-office com uma dúzia de
+destinos costuma dispensar esses recursos.
 
 ## As quatro peças
 
-| | |
+| API | Comportamento |
 |---|---|
 | `usePathname()` | O pathname como estado reativo. |
 | `useSegments()` | Os segmentos, já sem os vazios: `/settings/users` → `['settings','users']`. |
@@ -32,15 +34,23 @@ A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:post
 
 ## Comportamentos preservados
 
-**Destino igual é no-op.** `navigate` resolve o destino com `new URL` e compara o `href` inteiro — não faz nada se você já está exatamente lá. Sem isso, clicar duas vezes no mesmo item do menu empilha entradas idênticas e o botão "voltar" não sai do lugar.
+**Navegar para o destino atual não cria entrada.** `navigate` resolve o destino com `new URL` e
+compara o `href` inteiro; se a pessoa já está exatamente lá, nada acontece. Assim, clicar duas vezes
+no mesmo item do menu não empilha entradas idênticas, e o botão Voltar continua saindo da página.
 
-Comparar strings cruas parece bastar e não basta, em duas frentes. O **hash**: estando em `/a#secao`, `navigate('/a')` pareceria destino repetido e a âncora nunca sairia da URL. E o **encoding**: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então a comparação crua nunca casa e cada clique empilha — bem no caso pt-BR, e no ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
+A comparação usa a URL resolvida, e não o texto cru, por dois motivos. O hash: estando em
+`/a#secao`, `navigate('/a')` precisa remover a âncora, e não ser tratado como destino repetido. E a
+codificação: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então uma comparação
+crua nunca casaria e cada clique empilharia uma entrada, o que afeta caminhos acentuados e
+chamadas como ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
 
 **A notificação usa um evento do navegador.** Como `pushState` não dispara `popstate`, `navigate`
 emite o evento explicitamente. Isso mantém listeners existentes e cópias diferentes do pacote
 sincronizados pela mesma janela.
 
-**`useSyncExternalStore`, não `useState`.** Ler `window.location` dentro de `useState`/`useEffect` sofre *tearing* no modo concurrent: dois componentes podem renderizar o mesmo commit com URLs diferentes. As cópias que este módulo substituiu faziam isso.
+**Todos os componentes leem a mesma URL.** Os hooks usam `useSyncExternalStore`. Ler
+`window.location` dentro de `useState` ou `useEffect` permite que, na renderização concorrente, dois
+componentes mostrem URLs diferentes no mesmo commit.
 
 ## `replace`: quando o passo não é história
 
@@ -48,14 +58,23 @@ sincronizados pela mesma janela.
 navigate(`/reports?report=${file}`, { replace: true })
 ```
 
-Use quando a mudança não merece uma volta do botão "voltar" — um rascunho que ganha id no meio do fluxo, um filtro que a pessoa ajusta várias vezes seguidas. O default (`pushState`) é o certo para navegação de verdade.
+Use `replace` quando a mudança não deve virar um passo do botão Voltar: um rascunho que ganha id no
+meio do fluxo, um filtro que a pessoa ajusta várias vezes seguidas. Para uma navegação entre
+destinos, mantenha o padrão, `pushState`.
 
 ## SSR
 
-Os hooks têm snapshot de servidor constante (`/` e busca vazia): renderizam sem `window` e reconciliam com a URL real no primeiro render do cliente. Se a sua página precisa do path correto **no HTML servido**, isto não resolve — aí o path tem que vir do framework, por prop.
+No servidor, os hooks usam um valor fixo (`/` e busca vazia): renderizam sem `window` e passam a
+refletir a URL real no primeiro render do cliente. Se a página precisa do caminho correto no HTML
+servido, receba o caminho do framework por prop.
 
-O `navigate` **não** tem essa cortesia: ele toca `window` direto e estoura no servidor. É de propósito — ler a URL sem browser tem resposta razoável, navegar não tem, e engolir a chamada em silêncio esconderia o erro de uso.
+`navigate` acessa `window` diretamente e lança um erro quando chamado no servidor. Ler a URL fora
+do navegador tem uma resposta razoável; navegar não tem, e ignorar a chamada em silêncio esconderia
+o erro de uso.
 
-## Destino externo não é problema daqui
+## Validar destinos vindos de fora
 
-`navigate` espera um caminho da própria origem. Validar destino que veio de terceiro — o `?redirect=` de um pós-login, por exemplo — é responsabilidade de quem recebe esse input, e a checagem certa é resolver com `new URL(valor, origin)` e comparar `origin`, não olhar prefixo.
+`navigate` espera um caminho da própria origem e não valida destinos. Quando o destino vem de fora,
+como o `?redirect=` de um pós-login, valide-o antes de navegar: resolva com
+`new URL(valor, origin)` e compare o `origin` do resultado, em vez de conferir apenas o prefixo do
+texto.