@softize/opus 18.5.0 → 20.0.0

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

@@ -3,52 +3,77 @@
 Use `Slider` para escolher um valor dentro de uma faixa. `defaultValue` recebe um array; `[n]`
 representa um único controle. `min`, `max` e `step` delimitam os valores disponíveis.
 
+Quem recebe o foco e anuncia o valor é o controle arrastável, chamado de thumb. Sem rótulo
+visível, passe `aria-label` ao `Slider`: ele repassa o nome ao thumb.
+
 ```tsx preview col
-<Slider defaultValue={[40]} min={0} max={100} step={5} />
+<Slider aria-label="Opacidade" defaultValue={[40]} min={0} max={100} step={5} />
 ```
 
 ## Controlado
 
 `onValueChange` recebe o array atualizado. Para um único controle, leia `value[0]`.
 
+Com um rótulo visível, ligue-o ao `Slider` por `aria-labelledby`. O `htmlFor` do `Label` não
+alcança o thumb, porque ele não é um campo nativo.
+
 ```tsx preview col
 const [parallelism, setParallelism] = useState([4])
 
 render(
-  <div role="group" aria-labelledby="parallelism-label" className="grid w-full gap-3">
+  <div className="grid w-full gap-3">
     <div className="flex items-center justify-between">
       <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} />
+    <Slider
+      aria-labelledby="parallelism-label"
+      value={parallelism}
+      onValueChange={setParallelism}
+      min={1}
+      max={8}
+      step={1}
+    />
   </div>,
 )
 ```
 
 ## Intervalo
 
-Dois números em `value` criam um intervalo selecionável entre dois controles.
+Dois números em `value` criam um intervalo selecionável entre dois thumbs, e cada um precisa de um
+nome próprio. Passe os nomes em `thumbLabels`, na ordem dos valores. Sem `thumbLabels`, o nome comum
+se compõe com a posição: com `aria-label`, “Custo, mínimo” e “Custo, máximo”; com
+`aria-labelledby`, o texto do rótulo seguido de “Mínimo” ou “Máximo”. Sem nome algum, o leitor de
+tela anuncia só “Mínimo” e “Máximo”, sem dizer do quê.
 
 ```tsx preview col
 const [budget, setBudget] = useState([20, 60])
 
 render(
-  <div role="group" aria-labelledby="budget-label" className="grid w-full gap-3">
+  <div className="grid w-full gap-3">
     <div className="flex items-center justify-between">
-      <Label id="budget-label">Custo estimado (US$)</Label>
+      <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} />
+    <Slider
+      thumbLabels={['Custo mínimo', 'Custo máximo']}
+      value={budget}
+      onValueChange={setBudget}
+      min={0}
+      max={100}
+      step={5}
+    />
   </div>,
 )
 ```
 
 ## Desabilitado
 
-disabled esmaece o trilho e o thumb e bloqueia o arraste — o valor fica congelado no defaultValue.
+`disabled` esmaece o trilho e o thumb e bloqueia o arraste. O valor fica congelado no
+`defaultValue`.
 
 ```tsx preview col
-<Slider defaultValue={[70]} min={0} max={100} disabled />
+<Slider aria-label="Opacidade" defaultValue={[70]} min={0} max={100} disabled />
 ```
 
 ## Propriedades de Slider
@@ -63,3 +88,6 @@ disabled esmaece o trilho e o thumb e bloqueia o arraste — o valor fica congel
 | `step` | `number` | `1` | Incremento entre valores possíveis. |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção do trilho — vertical exige altura no container. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o arraste. |
+| `aria-label` | `string` | | Nome do thumb quando não há rótulo visível. Em intervalo, prefira `thumbLabels`. |
+| `aria-labelledby` | `string` | | `id` do rótulo visível que nomeia o thumb. |
+| `thumbLabels` | `readonly string[]` | | Um nome por thumb, na ordem de `value`. Prevalece sobre `aria-label` e `aria-labelledby`. |

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

@@ -3,7 +3,7 @@
 Use `Spinner` quando a duração ou o progresso da espera não forem conhecidos. `size` usa os nomes da
 escala dos controles e mede o glifo do controle homônimo: `sm` é o ícone de um `Button` `sm`, `lg` o
 de um `lg`. O ícone é decorativo; quem nomeia a espera é o contêiner (`role="status"`, como fazem
-`DataState` e `PageState`) ou o texto ao lado.
+[`DataState`](/ui/data-state) e `PageState`) ou o texto ao lado.
 
 ```tsx preview
 <Spinner size="xs" />
@@ -14,7 +14,7 @@ de um `lg`. O ícone é decorativo; quem nomeia a espera é o contêiner (`role=
 
 ## No botão
 
-Durante uma ação, use `busy` no `Button` com um rótulo que descreva o andamento. O botão fica
+Durante uma ação, use `busy` no [`Button`](/ui/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
@@ -24,7 +24,8 @@ desabilitado e o spinner ocupa o lugar do ícone, no glifo do tamanho do botão.
 ## Em carga de conteúdo
 
 Espera curta sem forma definida; o contêiner nomeia o estado. Para uma consulta inteira, `DataState`
-já monta esse contêiner. Quando o conteúdo tem forma conhecida (lista, card), prefira Skeleton.
+já monta esse contêiner. Quando o conteúdo tem forma conhecida, como uma lista ou um card, prefira
+[`Skeleton`](/ui/skeleton).
 
 ```tsx preview
 <div role="status" className="flex items-center gap-2 text-sm text-muted-foreground">

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

@@ -8,10 +8,10 @@ layout permanece estático.
 render(
   <div className="h-72 overflow-hidden rounded-lg border border-border">
     <Split resizable>
-      <Pane initialSize={30} minSize={20} inset="none" className="bg-muted/30">
-        <div className="p-4 text-sm">Navegação</div>
+      <Pane initialSize={30} minSize={20} className="bg-muted/30">
+        <p className="text-sm">Navegação</p>
       </Pane>
-      <Pane grow inset="lg">
+      <Pane grow>
         <p className="text-sm text-muted-foreground">
           Conteúdo. Arraste a divisória.
         </p>
@@ -21,26 +21,44 @@ render(
 );
 ```
 
-## Espaçamento interno
+Escreva cada `Pane` diretamente dentro do `Split`; um fragment pode agrupá-los, como em uma
+renderização condicional que devolve dois panes. O `Split` lê o tamanho de cada `Pane` antes de
+renderizá-lo, então não enxerga um `Pane` devolvido por outro componente: nesse caso, escreva o
+`Pane` no `Split` e passe o componente como filho dele. Qualquer outro filho interrompe a
+renderização com um erro que aponta o nó recebido, em vez de sumir da tela sem aviso.
 
-`Pane` usa `inset="md"` por padrão. Use `none` para navegação e conteúdo que já controla o próprio
-espaçamento; `sm` e `lg` atendem outras densidades.
+O [`opus check`](/docs/cli) antecipa esse erro com a regra `ui-structure-split`: ele aponta o filho
+direto de um `Split` que o código mostra não ser `Pane`, como um elemento HTML, um texto, outro
+componente do Opus ou um componente declarado no mesmo arquivo. Panes em fragment ou em condicional,
+espaços e comentários são aceitos. Expressões dinâmicas, como `{children}` ou `{items.map(...)}`, e
+componentes importados de outros módulos ficam fora do check; nesses casos, só o erro em runtime
+revela um filho inválido.
 
-## Largura inicial
+O `Split` responde pela relação espacial e pelo arraste. O que existe dentro de cada área — o
+cabeçalho, o corpo rolável, o rodapé, o recuo e a escolha entre regiões seccionadas e contínuas —
+pertence ao [`Pane`](/ui/pane) e está documentado na página da família.
 
-Quando uma área precisa continuar legível em telas largas, use uma unidade absoluta para o tamanho inicial ou mínimo. Números continuam representando porcentagens; strings aceitam `%`, `rem`, `em`, `vh`, `vw` e `px`. Prefira `rem` para acompanhar a escala tipográfica configurada pela aplicação.
+## Tamanho de cada pane
+
+Cada `Pane` declara o próprio tamanho e o `Split` o aplica. Números representam porcentagens;
+strings aceitam `%`, `rem`, `em`, `vh`, `vw` e `px`. Quando uma área precisa continuar legível em
+telas largas, use uma unidade absoluta no tamanho inicial ou mínimo, de preferência `rem`, para
+acompanhar a escala tipográfica configurada pela aplicação. `grow` entrega o espaço remanescente.
 
 ```tsx
 <Split resizable>
-  <Pane grow inset="none">
+  <Pane grow>
     <Main />
   </Pane>
-  <Pane initialSize="28rem" minSize="20rem" inset="none">
+  <Pane initialSize="28rem" minSize="20rem">
     <Inspector />
   </Pane>
 </Split>
 ```
 
+`minSize` e `maxSize` valem enquanto o `Split` é redimensionável; sem `resizable` eles não limitam
+nada.
+
 ## Persistência
 
 Um layout pode ser restaurado sem acoplar `Split` a um mecanismo específico de armazenamento. Dê um `id` estável a cada `Pane`, leia o valor salvo para formar `defaultLayout` e persista apenas mudanças concluídas pela pessoa.
@@ -134,16 +152,9 @@ render(<Example />);
 | `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.             |
+| `className`       | `string`                                  |                | Ajusta o contêiner do grupo.                                            |
+| `data-slot`       | `string`                                  | `'split'`      | Identificador semântico para testes e composição de patterns.          |
+| `children`        | `ReactNode`                               |                | Os `Pane`, diretos ou agrupados em fragment; outro filho gera erro.     |
 
 ## Propriedades de SurfaceAssistant
 
@@ -156,3 +167,6 @@ render(<Example />);
 | `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.             |
+| `className`      | `string`    |         | Ajusta o contêiner do split.                            |
+| `contentClassName` | `string`  |         | Ajusta a coluna do conteúdo principal.                  |
+| `assistantClassName` | `string` |        | Ajusta a coluna do painel de assistência.               |

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

@@ -4,8 +4,7 @@ title: Armazenamento
 
 # Armazenamento
 
-> **Experimental.** Superfície mínima, sem consumidor interno ainda — cresce por
-> reincidência de caso real, não por especulação.
+> **Experimental.** A superfície é mínima e cresce conforme casos reais a exigem.
 
 Use `StorageAdapter` para upload, download, remoção e geração de URL de arquivos. A chave é um
 caminho lógico, como `clientes/123/contrato.pdf`; cada driver decide onde o conteúdo é armazenado.
@@ -31,10 +30,11 @@ import { fsStorage } from '@softize/opus/storage/fs'
 import { s3Storage } from '@softize/opus/storage/s3'
 import { S3Client } from '@aws-sdk/client-s3'
 
-// Dev / single-host: arquivos sob um root local; url() exige baseUrl (o app serve o root).
+// Desenvolvimento ou um único host: arquivos num diretório local; url() exige baseUrl,
+// e o app serve esse diretório.
 const dev = fsStorage({ root: './var/arquivos', baseUrl: 'http://localhost:5173/arquivos' })
 
-// Produção: S3 e compatíveis (MinIO, R2…). O client é seu — região/endpoint/credencial.
+// Produção: S3 e compatíveis (MinIO, R2…). O app cria o client com região, endpoint e credenciais.
 const prod = s3Storage({
   client: new S3Client({ region: 'us-east-1' }),
   bucket: 'meu-app',
@@ -42,8 +42,8 @@ const prod = s3Storage({
 })
 ```
 
-Os peers do S3 são **opcionais** (`@aws-sdk/client-s3`; `s3-request-presigner` para o
-`url()`): quem não usa o driver não os instala — importados sob demanda.
+`@aws-sdk/client-s3` e, para `url()`, `@aws-sdk/s3-request-presigner` são dependências opcionais,
+carregadas só quando o driver é usado.
 
 ## No runtime
 
@@ -62,6 +62,5 @@ handler: async (ctx, input) => {
 
 ## Limites atuais
 
-Bytes em memória (`Uint8Array`), sem streams — arquivo gigante ainda não é o caso;
-sem `list`, sem metadata rica. Cada um entra quando um projeto real cobrar — é a
-régua do Opus: comportamento vira peça na reincidência.
+O conteúdo trafega inteiro em memória, como `Uint8Array`, sem streams; arquivos muito grandes ainda
+não são suportados. Também não há `list` nem metadados além de `contentType`.

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

@@ -1,7 +1,8 @@
 ## Alternar uma preferência
 
-Use `Switch` para uma preferência booleana que entra em vigor imediatamente. Associe o controle a
-`Label`; `defaultChecked` define o estado inicial no modo não controlado.
+Use `Switch` para uma preferência booleana que entra em vigor imediatamente. Quando a escolha só vale
+ao salvar um formulário, use [`Checkbox`](/ui/checkbox). Associe o controle a um [`Label`](/ui/label);
+`defaultChecked` define o estado inicial no modo não controlado.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -31,7 +32,8 @@ render(
 
 ## Tamanho sm
 
-Use `size="sm"` em linhas de lista e outras composições compactas.
+Use `size="sm"` em linhas de lista e outras composições compactas. O tamanho segue o degrau do ícone
+na escala dos controles, e não a altura da linha: a chave `sm` acompanha o ícone de um botão `sm`.
 
 ```tsx preview col-start
 <div className="flex items-center gap-2">
@@ -46,7 +48,8 @@ Use `size="sm"` em linhas de lista e outras composições compactas.
 
 ## Desabilitado
 
-disabled esmaece e bloqueia a chave — ligada ou desligada — e o rótulo em par esmaece junto (peer-disabled).
+`disabled` esmaece e bloqueia a chave, ligada ou desligada. O `Label` escrito logo depois da chave,
+no mesmo contêiner, esmaece junto.
 
 ```tsx preview col-start
 <div className="flex items-center gap-2">
@@ -63,8 +66,8 @@ disabled esmaece e bloqueia a chave — ligada ou desligada — e o rótulo em p
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `checked` | `boolean` | | O estado, no modo controlado — parear com onCheckedChange. |
+| `checked` | `boolean` | | Estado no modo controlado. Use com `onCheckedChange`. |
 | `onCheckedChange` | `(checked: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
 | `defaultChecked` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave, com os nomes da escala única — sm para densidade em linha de lista. |
-| `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |
+| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave, com os nomes da escala única; `sm` para linhas de lista densas. |
+| `disabled` | `boolean` | `false` | Esmaece e bloqueia a chave; o `Label` irmão posterior esmaece junto. |

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

@@ -1,8 +1,12 @@
 ## Tabela de domínio
 
-Use `Table` para dados organizados em linhas e colunas. A variante padrão não possui borda externa;
-`TableBody` mantém somente as divisórias internas. Aplique `text-right` ao cabeçalho e às células
-quando o domínio pedir alinhamento numérico. `TableCaption` descreve a tabela abaixo do conteúdo.
+Use `Table` para dados organizados em linhas e colunas que a tela já tem em mãos. Para uma coleção
+pesquisável, paginada e carregada por uma action `kind: 'list'`, use [`ActionList`](/ui/action-list),
+que monta a tabela, os filtros e os estados de carregamento, erro e vazio.
+
+A variante padrão não possui borda externa; `TableBody` mantém somente as divisórias internas.
+Aplique `text-right` ao cabeçalho e às células quando o domínio pedir alinhamento numérico.
+`TableCaption` descreve a tabela abaixo do conteúdo.
 
 ```tsx preview col
 <Table>
@@ -40,10 +44,8 @@ quando o domínio pedir alinhamento numérico. `TableCaption` descreve a tabela
 
 ## Tabela emoldurada
 
-A variante `framed` aplica no próprio contêiner a borda externa, os cantos arredondados, o
-scroll horizontal contido e o fundo discreto do cabeçalho. A última linha já vem sem divisória,
-então o quadro fecha limpo. O ActionList continua sendo o pattern indicado para coleções
-pesquisáveis derivadas de actions `kind: 'list'`.
+A variante `framed` aplica a borda externa e os cantos arredondados no contêiner da tabela e dá
+ao cabeçalho um fundo discreto. A última linha já vem sem divisória, então o quadro fecha limpo.
 
 ```tsx preview col
 <Table variant="framed">
@@ -105,9 +107,45 @@ adequados a essa região.
 </Table>
 ```
 
+## Contêiner e rolagem
+
+`Table` renderiza um contêiner em volta do elemento `<table>`. É nele que ficam a moldura da
+variante `framed` e a rolagem horizontal: quando as colunas não cabem, o contêiner rola e a página
+mantém a largura. Por isso há duas props de classe. `className` vai para o `<table>`;
+`containerClassName` vai para o contêiner, onde entram limites de altura, rolagem vertical ou
+ajustes da moldura.
+
+```tsx preview col
+<Table variant="framed" containerClassName="max-h-40 overflow-y-auto">
+  <TableHeader>
+    <TableRow>
+      <TableHead>Agente</TableHead>
+      <TableHead className="text-right">Sessões</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow><TableCell className="font-medium">developer</TableCell><TableCell className="text-right">42</TableCell></TableRow>
+    <TableRow><TableCell className="font-medium">reviewer</TableCell><TableCell className="text-right">18</TableCell></TableRow>
+    <TableRow><TableCell className="font-medium">designer</TableCell><TableCell className="text-right">7</TableCell></TableRow>
+    <TableRow><TableCell className="font-medium">planner</TableCell><TableCell className="text-right">5</TableCell></TableRow>
+    <TableRow><TableCell className="font-medium">tester</TableCell><TableCell className="text-right">3</TableCell></TableRow>
+  </TableBody>
+</Table>
+```
+
 ## Propriedades de Table
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'plain' \| 'framed'` | `'plain'` | Escolhe entre a estrutura sem moldura externa e o contêiner emoldurado. |
-| `className` | `string` | | Classes aplicadas ao elemento `table`. |
+| `containerClassName` | `string` | | Classes do contêiner que envolve o `<table>` e responde pela rolagem horizontal e pela moldura. |
+| `className` | `string` | | Classes aplicadas ao elemento `<table>`. |
+
+Os demais atributos vão para o elemento `<table>`.
+
+## Propriedades das partes da tabela
+
+`TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell` e `TableCaption`
+não têm props próprias. Cada um aceita as props nativas do elemento que renderiza — `<thead>`,
+`<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>` e `<caption>` —, como `className`, `colSpan` ou
+`scope`. Para marcar uma linha selecionada, passe `data-state="selected"` ao `TableRow`.

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

@@ -82,7 +82,9 @@ Com `orientation="vertical"`, a lista forma uma coluna. O exemplo usa a variante
 
 ## Tamanho
 
-`size="sm"` no `Tabs` reduz a lista de `h-9` (2.25rem) para `h-8` (2rem). É o par do `sm` de Button e Select para uma fileira densa, como uma toolbar ou um cabeçalho, em que o segmento não deve ficar mais alto que os elementos vizinhos.
+`size="sm"` no `Tabs` reduz a altura da lista de `2.25rem` para `2rem`. É o par do `sm` de `Button` e
+`Select` para uma fileira densa, como uma toolbar ou um cabeçalho, em que o segmento não deve ficar
+mais alto que os elementos vizinhos.
 
 ```tsx preview col
 <Tabs defaultValue="preview" size="sm">
@@ -110,9 +112,17 @@ Com `orientation="vertical"`, a lista forma uma coluna. O exemplo usa a variante
 |---|---|---|---|
 | `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
+## Propriedades de TabsTrigger
 
 | 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`. |
+| `value` | `string` | | Identificador que associa o gatilho ao `TabsContent` correspondente. |
+| `icon` | `ReactNode` | | Ícone decorativo antes do rótulo, em `1rem`. Em uma aba sem texto, declare também `aria-label`. |
+| `disabled` | `boolean` | `false` | Impede a seleção da aba. |
+
+## Propriedades de TabsContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Identificador do painel, igual ao `value` do `TabsTrigger` que o abre. |
+| `forceMount` | `true` | | Mantém o painel montado mesmo quando outra aba está ativa. |

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

@@ -5,31 +5,35 @@ title: Testes de action
 # Testes de action
 
 Teste cada action pela fronteira do contrato: entrada, saída ou erro, limites do schema e
-autorização. `@softize/opus/testing` executa esse fluxo em unidade sem montar o runtime completo.
+autorização. `@softize/opus/testing` executa esse fluxo em unidade, sem montar o runtime completo.
 
-## Executar o contrato em unidade
+## Executar a action em unidade
 
-`runAction` valida a entrada, aplica o gate `public`, avalia `authorize`, executa o handler e valida
-a saída. Falhas usam o mesmo `ActionError` tipado do runtime, como `validation.invalid_input`,
-`auth.unauthenticated` e `auth.forbidden`.
+`runAction` segue a ordem do runtime: valida a entrada, exige usuário quando a action não é
+`public`, avalia `authorize`, executa o handler e valida a saída. Em `list`, a validação da saída é
+pulada, porque o schema descreve o item e o handler devolve a página. Falhas usam o mesmo
+`ActionError` tipado do runtime, como `validation.invalid_input`, `auth.unauthenticated` e
+`auth.forbidden`.
+
+Passe a action ligada ao handler, produzida por `bindAction`. O contrato puro não tem handler e só
+executa em modo design, descrito abaixo.
 
 ```ts
 import { runAction } from '@softize/opus/testing'
-import { taskList } from './list.ts'
+import { taskListImpl } from './list.ts'
 
-it('lista as fixtures com o shape do contrato', async () => {
-  const { output } = await runAction(taskList, {}, { user: { id: 'u1' } })
+it('lista as tarefas com o formato do contrato', async () => {
+  const { output } = await runAction(taskListImpl, {}, { user: { id: 'u1' } })
   expect(output.total).toBe(2)
 })
 
-it('sem usuário, barra: a action não é pública', async () => {
-  await expect(runAction(taskList, {})).rejects.toMatchObject({ code: 'auth.unauthenticated' })
+it('exige usuário, porque a action não é pública', async () => {
+  await expect(runAction(taskListImpl, {})).rejects.toMatchObject({ code: 'auth.unauthenticated' })
 })
 ```
 
-O terceiro argumento configura o contexto e substitui os loaders (que não rodam em
-unidade): `{ user, tenantId, can, db, storage, ai, loaded, meta }`. O `authorize` vê
-o `loaded` como no runtime:
+Os loaders não rodam em unidade. Para testar uma autorização que depende de dados carregados,
+entregue o resultado pronto em `loaded`; o `authorize` o recebe como no runtime:
 
 ```ts
 it('só a dona edita', async () => {
@@ -41,20 +45,63 @@ it('só a dona edita', async () => {
 })
 ```
 
-## Contexto observável
+## Configurar o contexto
+
+O terceiro argumento de `runAction` monta o contexto recebido pelo handler. Todas as opções são
+opcionais.
+
+| Opção | Efeito |
+| --- | --- |
+| `user`, `tenantId` | Identidade do chamador. Sem `user`, actions que não são `public` falham com `auth.unauthenticated`. |
+| `can` | Resposta de `ctx.can`. Padrão: permite tudo. |
+| `db` | Valor entregue em `ctx.db`. |
+| `storage`, `cache` | Adapters entregues em `ctx.storage` e `ctx.cache`; padrão `null`. |
+| `ai` | Adapter de IA entregue em `ctx.ai`. Sem runtime, `run` e `runStream` não recebem tools. |
+| `meta`, `trace` | Valores de `ctx.meta` e `ctx.trace`. |
+| `loaded` | Substitui os loaders e chega ao `authorize` e ao handler. |
+
+`requires` é declarativo também no harness: nada o executa. Um handler que chama `ctx.can` recebe a
+resposta da opção `can`.
 
-`runAction` (e `testContext`, para quem quer só o ctx) devolve os efeitos capturados —
-o teste afirma o que importa:
+## Observar efeitos
+
+`runAction` devolve, além de `output`, os efeitos capturados: `emitted` guarda cada `ctx.emit` e
+`logged`, cada linha de `ctx.log`, na ordem em que ocorreram. `testContext` devolve o mesmo
+contexto sem executar uma action.
 
 ```ts
 const { output, emitted, logged } = await runAction(taskDone, { id: '1' }, { user })
 expect(emitted).toEqual([{ event: 'task.done', data: { id: '1' } }])
 ```
 
+## Testar em modo design
+
+Com `OPUS_MODE=design`, `runAction` executa o `mockHandler` quando ele existe, como o runtime do
+modo design. Nesse modo, o contrato puro também é testável. Fora dele, um contrato sem handler falha
+com `testing.no_handler`.
+
+```ts
+import { afterEach, it } from 'vitest'
+import { runAction } from '@softize/opus/testing'
+import { Task, taskList } from './list.ts'
+
+afterEach(() => {
+  // A variável vale para o processo inteiro; limpe para não afetar outros testes.
+  delete process.env['OPUS_MODE']
+})
+
+it('o mock devolve itens válidos para o schema', async () => {
+  process.env['OPUS_MODE'] = 'design'
+  const { output } = await runAction(taskList, {}, { user: { id: 'u1' } })
+  // `list` não valida a saída no pipeline: confira item a item.
+  for (const item of output.items) expect(Task.safeParse(item).success).toBe(true)
+})
+```
+
 ## memStorage
 
-`StorageAdapter` em memória com a mesma régua de key dos drivers reais — para handler
-que anexa arquivo:
+Para um handler que grava arquivos, `memStorage` oferece um `StorageAdapter` em memória com a mesma
+validação de chave dos drivers reais:
 
 ```ts
 import { memStorage, runAction } from '@softize/opus/testing'
@@ -64,26 +111,24 @@ await runAction(notaAnexar, { id: '9' }, { user, storage })
 expect(storage.keys()).toEqual(['notas/9.pdf'])
 ```
 
-## fake — fixtures do schema
+## fake — dados gerados pelo schema
 
-`fake(schema)` / `fakeMany(schema, n)` geram dado sintético **determinístico** que satisfaz o
-schema zod — matéria-prima do `mockHandler` (modo design) e de fixtures de teste. Semeado
-(mesma `seed` → mesma saída, sem `Math.random`), com heurística por check do zod (email, uuid,
-url, datetime) e por nome de campo (email, id, `*At`→data, telefone, cpf/cnpj, nome…), sabor pt-BR.
+`fake(schema)` e `fakeMany(schema, n)` geram dados sintéticos determinísticos que satisfazem o
+schema zod. Servem ao `mockHandler` do modo design e a fixtures de teste. A mesma `seed` produz a
+mesma saída, sem `Math.random`. Os valores seguem as validações do zod (email, uuid, url, datetime)
+e o nome do campo (email, id, `*At` como data, telefone, CPF/CNPJ, nome…), com conteúdo em pt-BR.
 
 ```ts
 import { entityRowSchema } from '@softize/opus/schema'
 import { fake, fakeMany } from '@softize/opus/testing'
 
-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
+const eventRowSchema = entityRowSchema(EventEntity) // schema de uma linha da entidade
+const one = fake(eventRowSchema) // um evento válido
+const many = fakeMany(eventRowSchema, 20) // 20 eventos, estáveis entre execuções
+const seeded = fake(eventRowSchema, { seed: 7 }) // outra seed, outra sequência
 ```
 
 ## Limites do teste de unidade
 
-De propósito — é harness de **unidade**: loaders reais (passe `loaded` pronto), audit,
-reactions em cadeia e o servidor. Fluxo completo é teste de integração com o runtime.
-`requires` é declarativo no protocolo (o runtime não o executa) — no harness idem;
-handler que chama `ctx.can` responde ao `can` das options.
+O harness não executa loaders reais, audit, reactions encadeadas nem o servidor. Para o fluxo
+completo, escreva um teste de integração com `createRuntime`.

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

@@ -1,7 +1,8 @@
 ## Texto com várias linhas
 
-Use `Textarea` para texto livre com várias linhas. O campo cresce com o conteúdo a partir de sua
-altura mínima.
+Use `Textarea` para texto livre com várias linhas, como uma descrição ou um contexto. O campo cresce
+com o conteúdo a partir da altura mínima de `4rem`; para uma caixa de envio com botão integrado,
+use [`Composer`](/ui/composer).
 
 ```tsx preview col md
 <Textarea placeholder="Descreva o que o agente deve fazer nesta sessão." />
@@ -34,5 +35,5 @@ Associe `htmlFor` no `Label` ao `id` do campo para manter o rótulo acessível.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `…props` | `ComponentProps<'textarea'>` | | Todos os atributos nativos (`value`, `defaultValue`, `rows`, `disabled`, `aria-invalid`…). A altura acompanha o conteúdo (`field-sizing-content`) a partir de `min-h-16`. |
-| `className` | `string` | | Compõe sobre o estilo padrão. |
+| `…props` | `ComponentProps<'textarea'>` | | Todos os atributos nativos (`value`, `defaultValue`, `rows`, `disabled`, `aria-invalid`…). A altura acompanha o conteúdo a partir do mínimo de `4rem`. |
+| `className` | `string` | | Classes somadas ao estilo padrão, como uma altura máxima. |