@softize/opus 27.1.0 → 29.0.0

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

@@ -68,7 +68,7 @@ declaração adicional:
   respostas (`alert`, `prompt`, `choose`) entram no inventário como se fossem props de um
   `ActionFormDialog`; o campo do diagnóstico é `dialog.confirm().title`,
   `dialog.choose().actions[0].label` etc. Constantes locais resolvem normalmente. Uma função
-  que devolve template (`body: describe(nome)`) gera o diagnóstico `content` habitual e
+  que devolve template (`body: describe(name)`) gera o diagnóstico `content` habitual e
   se declara em `copy.dynamic` como `message-template`. Opções construídas em tempo de execução
   ou mutadas depois de declaradas reprovam como estrutura, porque nenhum texto pode ser
   atribuído a elas.
@@ -80,7 +80,7 @@ declaração adicional:
   mesmo arquivo, cada literal do array vira um texto na linha em que foi escrito, em vez de um
   diagnóstico sobre a prop. `filter`, `slice`, `toSorted` e `toReversed` podem ficar entre o
   array e a iteração. O limite é deliberado: o array precisa ser literal e declarado no mesmo
-  arquivo; o elemento só pode ser lido (`item.chave`), nunca passado adiante, espalhado ou
+  arquivo; o elemento só pode ser lido (`item.key`), nunca passado adiante, espalhado ou
   atribuído; o callback não pode receber o próprio array como terceiro parâmetro; e nenhum
   elemento pode ter a chave dinâmica. Arrays importados, derivados por spread ou por
   concatenação continuam gerando o diagnóstico da prop.
@@ -97,13 +97,15 @@ visual que o protocolo não representa com segurança.
 é copy editorial estável; `label` e `confirm.*` são as superfícies editoriais cobertas.
 
 Quando uma prop mapeada recebe dados da aplicação, declare a superfície em
-`base.json.copy.dynamic` em vez de excluir o arquivo inteiro. O seletor usa o caminho, a
-linha e o campo exibido pelo diagnóstico. `runtime-data` registra valores como nomes,
+`base.json.copy.dynamic` em vez de excluir o arquivo inteiro. O seletor usa o caminho, o campo
+e o trecho de código exibidos pelo diagnóstico, sem a linha: a declaração continua válida quando
+o arquivo muda acima dela. `runtime-data` registra valores como nomes,
 contagens e opções vindas de API sem transformá-los em copy editorial. `message-template`
 acrescenta ao inventário um texto-modelo com papel semântico, para que a parte autoral de uma
 mensagem interpolada continue passando pela política da Base. As declarações não alteram o
-que o React renderiza; um seletor que deixa de corresponder a um único diagnóstico reprova o
-gate e precisa ser revisto. Diagnósticos estruturais ou de transformação visual não podem ser
+que o React renderiza; um seletor que deixa de encontrar o trecho reprova o gate e precisa ser
+revisto. Declarações antigas, ancoradas por `line`, são convertidas com `opus copy --reanchor`.
+Diagnósticos estruturais ou de transformação visual não podem ser
 dispensados por `copy.dynamic`; ausência de conteúdo também continua bloqueante.
 
 ```json
@@ -112,7 +114,7 @@ dispensados por `copy.dynamic`; ausência de conteúdo também continua bloquean
     "dynamic": [
       {
         "source": "src/sessions.tsx",
-        "line": 42,
+        "expression": "sessionOptions",
         "field": "<Select>.options",
         "kind": "runtime-data",
         "reason": "As opções são nomes de sessões retornados pela aplicação.",
@@ -120,7 +122,7 @@ dispensados por `copy.dynamic`; ausência de conteúdo também continua bloquean
       },
       {
         "source": "src/sessions.tsx",
-        "line": 58,
+        "expression": "`Excluir ${session.name}?`",
         "field": "dialog.confirm().body",
         "kind": "message-template",
         "role": "dialog-body",

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

@@ -24,8 +24,8 @@ Cada família dá um nome próprio a cada região. A tabela mostra a correspond
 | Navegação            | `PageNavigation` ou `PageBack`              | `DialogNavigation`            | `DrawerNavigation`            | Não existe                    |
 | Título no cabeçalho  | `PageTitle`                                 | `DialogTitle`                 | `DrawerTitle`                 | `SurfaceTitle`                |
 | Ações do cabeçalho   | `PageActions`                               | `DialogActions`               | `DrawerActions`               | `SurfaceActions`              |
-| Intro                | `Surface level={1}` no início do `PageBody` | `DialogIntro`                 | `DrawerIntro`                 | Não existe                    |
-| Ações da intro       | Ações da `Surface level={1}`                | `DialogIntroActions`          | `DrawerIntroActions`          | Não existe                    |
+| Intro                | `PageIntro` no início do `PageBody` | `DialogIntro`                 | `DrawerIntro`                 | Não existe                    |
+| Ações da intro       | `PageIntroActions`                | `DialogIntroActions`          | `DrawerIntroActions`          | Não existe                    |
 | Corpo                | `PageBody`                                  | `DialogBody`                  | `DrawerBody`                  | `SurfaceBody`                 |
 | Rodapé               | `PageFooter`                                | `DialogFooter`                | `DrawerFooter`                | `SurfaceFooter`               |
 | Divisores            | Antes do `PageFooter`                       | `sectioned` (padrão)          | `sectioned` (padrão)          | `sectioned`                   |
@@ -97,7 +97,7 @@ function DialogWithIntro({ layout, label }) {
       <DialogContent layout={layout}>
         <DialogHeader>
           <DialogActions>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DialogActions>
@@ -142,7 +142,7 @@ function CompactDialog({ layout, label }) {
             <Button variant="outline" size="sm">
               Ver histórico
             </Button>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DialogActions>
@@ -197,7 +197,7 @@ function OrderField() {
 function CollapseButton() {
   return (
     <DrawerClose asChild>
-      <Button variant="ghost" size="icon" aria-label="Recolher painel">
+      <Button variant="ghost" size="icon-sm" aria-label="Recolher painel">
         <ChevronsRight />
       </Button>
     </DrawerClose>
@@ -216,7 +216,7 @@ function DrawerWithIntro({ layout, label }) {
             <CollapseButton />
           </DrawerNavigation>
           <DrawerActions>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DrawerActions>
@@ -261,7 +261,7 @@ function CompactDrawer({ layout, label }) {
             <Button variant="outline" size="sm">
               Ver histórico
             </Button>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DrawerActions>
@@ -300,8 +300,8 @@ painel.
 
 ## Page
 
-A `Page` não tem um slot de intro. Com intro, o `PageHeader` guarda a navegação e as ações da
-página, e uma `Surface level={1}` abre o `PageBody` com o título e as ações do conteúdo. A página
+Na composição com intro, o `PageHeader` guarda a navegação e as ações da
+página, e uma `PageIntro` abre o `PageBody` com o título e as ações do conteúdo. A página
 precisa de exatamente um heading principal, por isso o `PageHeader` dessa composição não leva
 `PageTitle`.
 
@@ -322,27 +322,20 @@ render(
           </Breadcrumb>
         </PageNavigation>
         <PageActions>
-          <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+          <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
             <MessageCircle />
           </Button>
         </PageActions>
       </PageHeader>
       <PageBody>
-        <Surface
-          as="section"
-          level={1}
-          title="Editar ordem de serviço"
-          actions={
-            <Button variant="outline" size="sm">
-              Ver histórico
-            </Button>
-          }
-        >
+        <PageIntro>
+          <PageTitle>Editar ordem de serviço</PageTitle>
+          <PageIntroActions><Button variant="outline" size="sm">Ver histórico</Button></PageIntroActions>
+        </PageIntro>
           <div className="space-y-2">
             <Label htmlFor="page-intro-owner">Responsável</Label>
             <Input id="page-intro-owner" defaultValue="Marina Alves" />
           </div>
-        </Surface>
       </PageBody>
       <PageFooter>
         <ButtonGroup mode="spaced">
@@ -380,7 +373,7 @@ render(
           <Button variant="outline" size="sm">
             Ver histórico
           </Button>
-          <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+          <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
             <MessageCircle />
           </Button>
         </PageActions>
@@ -449,7 +442,7 @@ render(
               <Button variant="outline" size="sm">
                 Ver histórico
               </Button>
-              <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+              <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
                 <MessageCircle />
               </Button>
             </SurfaceActions>
@@ -477,3 +470,22 @@ Os dois panes recebem conteúdos diferentes sem mudar de componente: o primeiro
 [`Sidebar`](/ui/sidebar), que já tem anatomia própria, e o segundo, uma `Surface` completa. A
 rolagem também pertence ao conteúdo: a `Surface` ocupa a altura do pane com `flex h-full flex-col`,
 e o `SurfaceBody` declara `min-h-0 flex-1 overflow-y-auto` para rolar entre o cabeçalho e o rodapé.
+
+## Ritmo entre regiões e blocos
+
+Surface (incluindo cards e seções), Page, Dialog, Drawer e Tabs organizam o conteúdo
+com intervalos de `1rem`. Os bodies separam seus blocos diretos; grupos internos podem
+ter densidade própria. DetailGroup e Separator não criam margens externas.
+
+Sem delimitação, Surface e Tabs não adicionam padding inferior. Uma Surface com moldura
+ou elevação, assim como Dialog e Drawer, reserva `1rem` até a borda. No layout contínuo,
+o intervalo vem da região anterior. No seccionado, há `1rem` entre cada divisória e o
+conteúdo adjacente. Não some padding e gap para expressar o mesmo intervalo.
+
+Page conserva os recuos laterais e a largura de leitura. Seu body não acrescenta padding
+inferior quando termina a página; antes de um footer seccionado, reserva `1rem` até a linha.
+O modo `flush` remove recuos do body para uma lista ou tabela controlar sua própria borda,
+mas mantém o intervalo entre blocos.
+
+Ao migrar, remova `space-y`, `gap`, `pt` e `pb` locais que apenas reconstruíam esses defaults
+nos slots. Preserve classes de layout internas, como uma grade ou um grupo de campos compacto.

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

@@ -48,7 +48,7 @@ distinta da página.
 ```
 
 O corpo cresce até o limite da janela e passa a rolar; cabeçalho e rodapé permanecem visíveis.
-Seus filhos diretos recebem o ritmo estrutural de `1.5rem`. Um grupo compacto, uma grade ou uma
+Seus filhos diretos recebem o ritmo estrutural de `1rem`. Um grupo compacto, uma grade ou uma
 linha declara a própria relação em um wrapper filho; `flush` fica reservado ao conteúdo que
 controla todo o inset.
 O backdrop escurece a página sem aplicar desfoque.
@@ -126,13 +126,13 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
   <DialogContent>
     <DialogHeader>
       <DialogNavigation>
-        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DialogNavigation>
       <DialogTitle>Evento 4821</DialogTitle>
       <DialogActions>
-        <Button variant="ghost" size="icon" aria-label="Mais ações">
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DialogActions>
@@ -146,9 +146,10 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
 </Dialog>
 ```
 
-Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
-[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
-quadrado `icon-sm` (1.75rem) por padrão.
+O header compartilha a geometria de Page e Surface delimitada: padding de `1rem` e
+linha mínima de `2rem`, nos dois layouts. Declare `size="sm"` nos botões textuais e
+`size="icon-sm"` nos de ícone (`2rem`), incluindo o retorno. `CloseButton` já usa
+`icon-sm` por padrão. Conteúdo maior pode expandir a linha; rodapés preservam sua escala.
 
 O cabeçalho aceita `DialogDescription` como subheading opcional para orientar sobre a finalidade.
 Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
@@ -656,3 +657,14 @@ comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions)
 | `id` | `string` | | Identificador para associação acessível explícita. |
 | `className` | `string` | | Ajusta a apresentação do parágrafo. |
 | `…props` | `ComponentProps<"p">` | | Atributos nativos. |
+
+## Espaçamento do corpo
+
+O body separa os blocos diretos por `1rem`. Dialog e Drawer são superfícies delimitadas:
+o conteúdo mantém `1rem` até a borda inferior, mesmo sem uma propriedade `framed`.
+Em `sectioned`, o corpo tem `1rem` entre o conteúdo e cada divisória. Em `continuous`,
+o cabeçalho fornece o intervalo superior; sem cabeçalho, o próprio corpo abre esse recuo.
+Use `flush` quando o conteúdo controlar seus próprios recuos.
+
+Na intro, `DialogTitle` usa a mesma escala de `PageTitle` (`1.875rem`). No header
+compacto, o título conserva a escala de `1.125rem`. O nível semântico não altera essas medidas.

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

@@ -119,7 +119,7 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
   <DrawerContent side="right">
     <DrawerHeader>
       <DrawerNavigation>
-        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DrawerNavigation>
@@ -130,7 +130,7 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
       </DrawerMedia>
       <DrawerTitle>ABC-1D23</DrawerTitle>
       <DrawerActions>
-        <Button variant="ghost" size="icon" aria-label="Mais ações">
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DrawerActions>
@@ -144,9 +144,10 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
 </Drawer>
 ```
 
-Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
-[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
-quadrado `icon-sm` (1.75rem) por padrão.
+O header compartilha a geometria de Page e Surface delimitada: padding de `1rem` e
+linha mínima de `2rem`, nos dois layouts. Declare `size="sm"` nos botões textuais e
+`size="icon-sm"` nos de ícone (`2rem`), incluindo o retorno. `CloseButton` já usa
+`icon-sm` por padrão. Conteúdo maior pode expandir a linha; rodapés preservam sua escala.
 
 O cabeçalho aceita `DrawerDescription` como subheading opcional para orientar sobre a finalidade.
 Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
@@ -323,3 +324,14 @@ comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions)
 | `id` | `string` | | Identificador para associação acessível explícita. |
 | `className` | `string` | | Ajusta a apresentação do parágrafo. |
 | `…props` | `ComponentProps<"p">` | | Atributos nativos. |
+
+## Espaçamento do corpo
+
+O body separa os blocos diretos por `1rem`. Dialog e Drawer são superfícies delimitadas:
+o conteúdo mantém `1rem` até a borda inferior, mesmo sem uma propriedade `framed`.
+Em `sectioned`, o corpo tem `1rem` entre o conteúdo e cada divisória. Em `continuous`,
+o cabeçalho fornece o intervalo superior; sem cabeçalho, o próprio corpo abre esse recuo.
+Use `flush` quando o conteúdo controlar seus próprios recuos.
+
+Na intro, `DrawerTitle` usa a mesma escala de `PageTitle` (`1.875rem`). No header
+compacto, o título conserva a escala de `1.125rem`. O nível semântico não altera essas medidas.

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

@@ -17,7 +17,7 @@ interface EventBusAdapter {
 }
 
 interface DomainEvent<T = unknown> {
-  type: string                                   // 'nota.emitida'
+  type: string                                   // 'invoice.issued'
   id: string
   timestamp: string
   actor: { id: string | null; type?: 'user' | 'system' | 'integration' }
@@ -39,7 +39,7 @@ const bus = mittEvents() // no mesmo processo do runtime
 ```
 
 O `mitt` entrega pelo nome exato do evento ou por `*`, que recebe todos. Padrões parciais, como
-`nota.*`, não são reconhecidos: assine `*` e filtre no handler.
+`invoice.*`, não são reconhecidos: assine `*` e filtre no handler.
 
 ## Emitir de uma action
 
@@ -51,13 +51,13 @@ const runtime = createRuntime({
   eventBus: bus,
 })
 
-export const notaEmitir = bindAction(notaEmitirContract, {
-  emits: ['nota.emitida'],
+export const invoiceIssue = bindAction(invoiceIssueContract, {
+  emits: ['invoice.issued'],
   handler: async (ctx, input) => {
-    const nota = await repo.create(input)
+    const invoice = await repo.create(input)
     // O runtime preenche id, timestamp, actor, tenant, source e trace.
-    await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
-    return nota
+    await ctx.emit('invoice.issued', { id: invoice.id, amount: invoice.amount })
+    return invoice
   },
 })
 ```
@@ -86,21 +86,21 @@ no código compartilhado e o efeito, no servidor:
 import { bindReaction, defineReactionContract } from '@softize/opus/core'
 
 // shared/ — qual evento e o que a reação significa.
-export const notaAvisarFinanceiro = defineReactionContract<{ id: string; valor: number }>({
-  name: 'nota.avisar-financeiro',
-  on: 'nota.emitida',
+export const invoiceNotifyFinance = defineReactionContract<{ id: string; amount: number }>({
+  name: 'invoice.notify-finance',
+  on: 'invoice.issued',
   description: 'Avisa o financeiro quando uma nota é emitida.',
 })
 
 // api/ — o efeito.
-export const notaAvisarFinanceiroImpl = bindReaction(notaAvisarFinanceiro, {
+export const invoiceNotifyFinanceImpl = bindReaction(invoiceNotifyFinance, {
   handler: async (ctx, event) => {
-    ctx.log.info('nota emitida', { id: event.data.id, valor: event.data.valor })
+    ctx.log.info('nota emitida', { id: event.data.id, amount: event.data.amount })
   },
 })
 ```
 
-Registre a reaction com as actions, em `defineDomain({ reactions: [notaAvisarFinanceiroImpl] })`
+Registre a reaction com as actions, em `defineDomain({ reactions: [invoiceNotifyFinanceImpl] })`
 ou em `runtime.register`. Com reactions registradas, o `start()` exige um `EventBusAdapter` e falha
 com `runtime.eventbus_required` quando ele não existe. `defineReaction` declara tudo num objeto só,
 quando não há separação entre cliente e servidor.

package/src/ui/docs/content/icon-picker.md

@@ -1,18 +1,18 @@
 ## Escolher na paleta padrão
 
 Use `IconPicker` quando a pessoa puder escolher o ícone que identifica um registro, como um
-relatório ou um painel. A lista abre em um popover com busca, e o valor guardado é o nome do ícone em
-kebab-case, como `chart-line`. Selecionar novamente o ícone atual limpa o valor.
+relatório ou um painel. A grade de ícones abre em um popover com busca em português, e o valor guardado é o nome do ícone em
+kebab-case, como `chart-line`. Selecionar novamente o ícone atual limpa o valor. A grade exibe somente ícones; os nomes ficam disponíveis para leitores de tela e busca. A busca aceita o identificador técnico, o nome em português e sinônimos. `searchTerms` permite definir rótulos e termos de busca para uma paleta própria, sem alterar o valor salvo.
 
 ```tsx preview col md
-const [icon, setIcon] = useState('chart-line')
+const [icon, setIcon] = useState("chart-line");
 
 render(
   <div className="grid gap-2">
     <Label htmlFor="report-icon">Ícone do relatório</Label>
     <IconPicker id="report-icon" value={icon} onChange={setIcon} />
   </div>,
-)
+);
 ```
 
 ## Apresentar o ícone escolhido
@@ -22,8 +22,8 @@ padrão é exportada como `iconPickerIcons`; use-a em listas, cards e árvores,
 para nomes que não existam mais, como em `iconPickerIcons[name] ?? FileText`.
 
 ```tsx preview col md
-const [icon, setIcon] = useState('store')
-const SelectedIcon = iconPickerIcons[icon] ?? FileText
+const [icon, setIcon] = useState("store");
+const SelectedIcon = iconPickerIcons[icon] ?? FileText;
 
 render(
   <div className="flex items-center gap-3">
@@ -37,7 +37,7 @@ render(
       </ItemHeader>
     </Item>
   </div>,
-)
+);
 ```
 
 ## Paleta própria
@@ -46,27 +46,45 @@ render(
 domínio, pois cada importação participa do bundle.
 
 ```tsx preview col md
-const [icon, setIcon] = useState('')
+const [icon, setIcon] = useState("");
 
 render(
   <IconPicker
     value={icon}
     onChange={setIcon}
-    icons={{ 'zap': Zap, 'star': Star, 'flag': Flag, 'heart': Heart }}
+    icons={{ zap: Zap, star: Star, flag: Flag, heart: Heart }}
     placeholder="Selecione um ícone…"
     className="w-56"
   />,
-)
+);
 ```
 
 ## Propriedades de IconPicker
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `value` | `string` | | Nome do ícone selecionado (chave da paleta); `''` é nenhum. |
-| `onChange` | `(name: string) => void` | | Recebe o nome escolhido. |
-| `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Paleta nome → componente. |
-| `placeholder` | `string` | `'Selecione um ícone…'` | Texto do gatilho sem seleção. |
-| `disabled` | `boolean` | `false` | Desabilita o gatilho. |
-| `className` | `string` | | Classes do gatilho, em geral para ajustar a largura. Sem elas, o gatilho ocupa toda a largura disponível. |
-| `id`, `aria-invalid`, `aria-describedby` | `string`, `boolean`, `string` | | Integração com `Field` e `ActionForm`: o gatilho recebe a identidade do campo, o estado inválido e a mensagem associada. Com `aria-invalid`, a moldura assume o contexto de erro, como no `Input`. |
+| Propriedade                              | Tipo                                                    | Padrão                    | Descrição                                                                                                                                                                                          |
+| ---------------------------------------- | ------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                                  | `string`                                                |                           | Nome do ícone selecionado (chave da paleta); `''` é nenhum.                                                                                                                                        |
+| `onChange`                               | `(name: string) => void`                                |                           | Recebe o nome escolhido.                                                                                                                                                                           |
+| `icons`                                  | `Record<string, LucideIcon>`                            | `iconPickerIcons`         | Paleta nome → componente.                                                                                                                                                                          |
+| `searchTerms`                            | `Record<string, { label: string; keywords: string[] }>` | Mapa interno em português | Rótulos acessíveis e sinônimos de busca.                                                                                                                                                           |
+| `placeholder`                            | `string`                                                | `'Selecione um ícone…'`   | Texto do gatilho sem seleção.                                                                                                                                                                      |
+| `disabled`                               | `boolean`                                               | `false`                   | Desabilita o gatilho.                                                                                                                                                                              |
+| `className`                              | `string`                                                |                           | Classes do gatilho, em geral para ajustar a largura. Sem elas, o gatilho ocupa toda a largura disponível.                                                                                          |
+| `id`, `aria-invalid`, `aria-describedby` | `string`, `boolean`, `string`                           |                           | Integração com `Field` e `ActionForm`: o gatilho recebe a identidade do campo, o estado inválido e a mensagem associada. Com `aria-invalid`, a moldura assume o contexto de erro, como no `Input`. |
+
+## Catálogo sob demanda
+
+`IconCatalogProvider` recebe um objeto `catalog` com `load` e `render`. Declare esse objeto
+como constante de módulo ou com `useMemo`, preservando sua identidade entre renders. `load` retorna uma promessa com
+`{ name, label, keywords }[]` e só é chamado ao abrir o picker. O consumidor pode reutilizar a
+promessa para cache, mas deve descartá-la em caso de falha para permitir tentar novamente.
+`render(name, className)` apresenta o ícone salvo sem precisar carregar o índice.
+
+O picker começa com 64 resultados e carrega mais automaticamente ao se aproximar do fim do scroll.
+A grade tem oito colunas; a busca sempre percorre o índice inteiro. Erros no carregamento oferecem nova tentativa.
+O consumidor deve carregar imagens conforme entram na região visível e fornecer fallback.
+Uma paleta explícita por `icons` prevalece sobre o provider, preservando seletores especializados.
+Sem provider, o catálogo curado continua funcionando sem requisições externas.
+
+Antes da primeira abertura, um ícone externo salvo é anunciado como “Ícone selecionado”;
+após carregar o índice, o gatilho usa o rótulo do catálogo. O desenho não depende desse carregamento.

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

@@ -200,7 +200,7 @@ controle ativo, declare `data-disabled="true"` no `InputGroup`.
 
 | Propriedade | Tipo                                                    | Padrão      | Descrição                                                                                                                     |
 | ----------- | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `size`      | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'`                | `'xs'`      | O subconjunto da escala única que cabe em um campo (1.5 · 2 · 1.5 · 1.75rem); os `icon-*` são quadrados.                      |
+| `size`      | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'`                | `'xs'`      | O subconjunto da escala única que cabe em um campo (1.5 · 2 · 1.5 · 2rem); os `icon-*` são quadrados.                      |
 | `context`   | `'neutral' \| 'primary' \| 'warning' \| 'danger'`       | `'neutral'` | Contexto semântico herdado de Button. Com `variant` `solid` ou `subtle` sem contexto declarado, o padrão passa a `'primary'`. |
 | `variant`   | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'`   | Tratamento visual; use `solid` quando a ação precisar de ênfase.                                                              |
 

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

@@ -25,6 +25,10 @@ pnpm test
 O aplicativo inclui um domínio de tarefas, `opus.config.ts`, Vite, React, o tema do Opus e os
 comandos de teste e verificação. O dev server respeita a variável `PORT`. `opus.json` registra a
 versão do SDK adotada pelo app; `setup` materializa as instruções, skills e hooks gerenciados.
+As instruções ficam no `AGENTS.md`, que qualquer agente lê; o `CLAUDE.md` contém só a linha
+`@AGENTS.md`, que as importa para o Claude Code. Escreva as regras do seu projeto no `AGENTS.md`:
+o `setup` recusa um `CLAUDE.md` com instruções que não estão no `AGENTS.md` e pede que elas sejam
+movidas para lá.
 
 Quando os testes passarem, continue em [Primeiros passos](/docs/getting-started).
 

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

@@ -44,7 +44,7 @@ const runtime = createRuntime({
 
 // No handler: ctx.log já traz o request ID e a action, adicionados com child().
 handler: async (ctx, input) => {
-  ctx.log.info('emitindo nota', { valor: input.valor })
+  ctx.log.info('emitindo nota', { amount: input.amount })
   return repo.create(input)
 }
 ```