@softize/opus 18.5.0 → 20.0.0

package/bin/lib/copy.mjs

@@ -124,6 +124,8 @@ const JSX_CHILD_ROLES = new Map([
   // comando. Classificado como `button`, a política universal cobraria verbo de ação.
   ['PageBack', 'breadcrumb'],
   ['PageTitle', 'title'],
+  ['PaneDescription', 'description'],
+  ['PaneTitle', 'title'],
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
   ['TabsTrigger', 'tab'],
@@ -327,6 +329,10 @@ const JSX_ARRAY_PROP_ROLES = new Map([
   ],
 ])
 
+// Props que recebem uma lista de textos, um por item. Cada thumb de um intervalo do Slider tem
+// nome próprio, e é esse nome que o leitor de tela anuncia ao focar o controle.
+const JSX_STRING_ARRAY_PROP_ROLES = new Map([['Slider', new Map([['thumbLabels', 'label']])]])
+
 // Prop de classe que alcança cada superfície textual. A lista acompanha a implementação
 // real dos componentes: `className` do ActionFormCard vai para o form, enquanto
 // `cardClassName` envolve o título; o menu do Select custom vive em portal e não herda a
@@ -777,6 +783,7 @@ function knownJsxAggregateConsumer(expression, checker, mode) {
       JSX_PROP_ROLES.get(component)?.has(prop) === true ||
       JSX_OBJECT_PROP_ROLES.get(component)?.has(prop) === true ||
       JSX_ARRAY_PROP_ROLES.get(component)?.has(prop) === true ||
+      JSX_STRING_ARRAY_PROP_ROLES.get(component)?.has(prop) === true ||
       [...(JSX_PROP_CLASS.get(component)?.values() ?? [])].includes(prop) ||
       [...(JSX_PROP_STYLE.get(component)?.values() ?? [])].includes(prop) ||
       (JSX_CHILD_ROLES.has(component) && ['className', 'style'].includes(prop))
@@ -2435,6 +2442,28 @@ export function extractCopyFromSource(file, sourceText) {
       }
     }
 
+    for (const [name, role] of JSX_STRING_ARRAY_PROP_ROLES.get(component) ?? []) {
+      const item = attribute(opening.attributes, name)
+      if (item.opaque !== undefined) {
+        diagnostics.push(diagnostic(file, sourceFile, item.opaque, `<${component}>.${name}`))
+        continue
+      }
+      if (item.candidate === undefined) continue
+      const raw = attributeValue(item)
+      const list = raw === null ? null : resolveBinding(raw, checker)
+      if (list === null || !ts.isArrayLiteralExpression(list)) {
+        diagnostics.push(
+          diagnostic(file, sourceFile, raw ?? opening, `<${component}>.${name}`, raw === null ? 'structure' : 'content'),
+        )
+        continue
+      }
+      for (const [index, element] of list.elements.entries()) {
+        const text = ts.isSpreadElement(element) ? null : staticText(element, checker)
+        if (text === null) diagnostics.push(diagnostic(file, sourceFile, element, `<${component}>.${name}[${index}]`))
+        else entries.push({ source: file, line: lineOf(sourceFile, text.node), role, text: text.text })
+      }
+    }
+
     const ariaLabelAttribute = attribute(opening.attributes, 'aria-label')
     let hasStaticAriaLabel = false
     if (ariaLabelAttribute.opaque !== undefined) {

package/bin/lib/mcp.mjs

@@ -42,7 +42,7 @@ export function buildServer() {
   server.registerTool(
     'opus_check',
     {
-      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize. Retorna findings.',
+      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize, ignored-by-kind. Retorna findings.',
       inputSchema: { dir: z.string().optional() },
     },
     async ({ dir }) => asText(await scanDir(dirOf(dir))),

package/docs/adr/0023-surfaces-share-one-anatomy-and-two-layouts.md

@@ -0,0 +1,298 @@
+# ADR 0023 — Superfícies compartilham uma anatomia e dois layouts
+
+- **Status:** aceita.
+- **Data:** 2026-09-23.
+- **Complementa:** ADRs 0005, 0014, 0018, 0019 e 0021.
+
+## Contexto
+
+A ADR 0005 estabeleceu a gramática `Root > Header + Body + Footer` para as superfícies da casa. O
+vocabulário foi adotado, mas a implementação não: `Page` e `Content` derivam o header de uma
+infraestrutura interna comum, enquanto `Card`, `Dialog`, `Drawer` e `Pane` desenham o seu à mão.
+
+O efeito acumulado é mensurável no código de hoje:
+
+- **Três escalas de padding para o mesmo papel.** `p-3` no chrome de Page, `p-4` nos slots de Dialog
+  e Drawer, `px-5` no Card. `Card` é a única com ritmo vertical assimétrico (`pt-5 pb-3` no header,
+  `pt-3 pb-5` no footer). `Content`, `PageBody` e `PaneBody` não têm padding nenhum.
+- **`PaneHeader` sem padding e `PaneFooter` com `p-2`** — assimetria dentro da mesma família.
+- **`CardTitle` é um `div` sem escala tipográfica**, único título do conjunto que não é heading e
+  não declara tamanho; herda o que vier do contexto.
+- **Divisor automático em quatro famílias e manual no Card.** A documentação pública ensina o
+  consumidor a escrever `border-b` no `CardHeader` e `border-t` no `CardFooter`.
+- **`Dialog` e `Drawer` não têm slot de ações no header.** Quem precisa injeta nós soltos ao lado do
+  título, como `Presentation` faz hoje.
+- **A família `Pane` está partida**: a raiz mora em `split.tsx`, os slots em `sidebar.tsx`, a
+  documentação está na página da Sidebar e nenhum teste cobre a anatomia.
+- **`Drawer` duplica `Dialog`** com três divergências não declaradas: footer sem fundo, header sem a
+  supressão condicional do divisor e título com `text-foreground` a mais.
+- **Nenhuma suíte transversal** compara as famílias; cada divergência só aparece quando alguém
+  compõe as duas superfícies lado a lado.
+
+A evidência que motivou a decisão veio da tela do Evento de Pós-vendas: para aproximar dois Cards do
+recorte já usado por Dialog e Content, a tela precisou escrever `flex-row items-center gap-4
+border-b p-4` no header, `p-4` no body, `text-sm` no título, um `<h3>` dentro do `CardTitle` e o
+ícone dentro do texto. São cinco decisões estruturais tomadas pelo consumidor.
+
+As forças em tensão:
+
+- **Uniformidade × identidade da família.** Um modal, um card e um painel não precisam ter as mesmas
+  medidas; precisam ter a mesma gramática e o mesmo comportamento estrutural.
+- **Compatibilidade × correção.** Alterar o default de uma família muda todas as telas que já a
+  usam. Preservar o default errado perpetua o defeito que motivou a decisão.
+- **Uma API genérica × seis APIs específicas.** Um `<Surface>` público reduziria código e apagaria a
+  semântica de cada família; seis implementações independentes preservam a semântica e produzem a
+  divergência atual.
+
+## Decisão
+
+### 1. Uma infraestrutura interna, seis fachadas públicas
+
+As telas continuam usando `CardHeader`, `DialogHeader`, `DrawerHeader`, `PaneHeader`,
+`ContentHeader` e `PageHeader`. Não existe superfície genérica pública. `SurfaceHeader` e o novo
+módulo de anatomia permanecem internos: a aplicação não os importa.
+
+A anatomia compartilhada passa a viver em um único módulo interno, que responde por:
+
+- as classes de cada região (`header`, `body`, `footer`) por família e layout;
+- a escala visual do título, separada do nível semântico;
+- a posição e o tamanho das ações;
+- a apresentação da mídia;
+- os divisores entre regiões adjacentes;
+- o alinhamento horizontal comum entre as regiões da mesma superfície.
+
+Nenhuma família reimplementa essas regras. Quando uma família precisa divergir, a divergência é um
+valor declarado na tabela de anatomia, não uma classe escrita no componente.
+
+### 2. O layout é do root e chega aos slots por contexto
+
+`layout` é propriedade do componente raiz: `Card`, `DialogContent`, `DrawerContent` e `Pane`. Os
+slots não recebem `layout`; eles leem o contexto da superfície que os hospeda. Um slot usado fora da
+sua família continua sendo erro, como hoje.
+
+`Content` e `Page` não expõem `layout` de anatomia. `Content` é contínuo por definição e `Page`
+mantém `layout="flow" | "fill"`, que descreve ocupação de altura, não anatomia. São nomes
+diferentes para coisas diferentes e permanecem assim.
+
+### 3. O que cada layout significa
+
+`continuous` e `sectioned` não são a ausência e a presença de uma borda. Cada um é um pacote:
+
+| Aspecto | `continuous` | `sectioned` |
+| --- | --- | --- |
+| Divisores | nenhum | entre regiões adjacentes presentes |
+| Ritmo vertical | header aproxima-se do corpo; o espaço separa | regiões simétricas; o divisor separa |
+| Escala do título | a da família | a da família, um degrau mais contida quando a família tem duas |
+| Fundo do footer | igual ao da superfície | sutil, quando a família declara |
+| Alinhamento horizontal | idêntico entre header, body e footer | idêntico entre header, body e footer |
+
+O alinhamento horizontal é invariante dos dois layouts: o recuo lateral de header, body e footer de
+uma mesma superfície é sempre o mesmo valor. É o que a suíte transversal verifica.
+
+### 4. Os divisores são derivados, não escritos
+
+No layout `sectioned`, o divisor existe quando há duas regiões adjacentes. Um header seguido de nada
+não desenha linha; um footer que é a única região também não. A regra é estrutural e vive no
+componente, derivada da presença dos irmãos — não uma classe que o consumidor aplica.
+
+A recomendação de escrever `border-b` e `border-t` no Card sai da documentação.
+
+### 5. Defaults por família
+
+Os defaults preservam o que cada família já entrega hoje, exceto onde o comportamento atual é o
+defeito que esta decisão corrige:
+
+| Família | Default | Por quê |
+| --- | --- | --- |
+| `Card` | `continuous` | é o que a família entrega hoje: sem divisores, ritmo assimétrico |
+| `Dialog` (default) | `sectioned` | já tem divisores e faixas; o default nomeia o que existe |
+| `Dialog` (`mode="alert"`) | composição própria | a resposta obrigatória mantém sua anatomia centrada |
+| `Drawer` | `sectioned` | idem Dialog |
+| `Pane` | `sectioned` | header e footer já têm divisor |
+| `Content` | contínuo, sem opção | região semântica dentro de outra superfície |
+| `Page` | contínuo, sem opção | a separação do chrome pertence ao shell |
+
+Nenhum default muda de valor efetivo com esta ADR. O que muda é que o valor passa a ter nome,
+implementação única e teste.
+
+### 5.1. O que o inventário dos consumidores mostrou
+
+A migração foi decidida sobre 374 usos reais das seis famílias na plataforma. O que eles revelam:
+
+- **Nenhuma tela usa `CardDescription`, `ContentDescription`, `DialogDescription` ou equivalente.**
+  Toda descrição é um `<p className="text-sm text-muted-foreground">` escrito à mão. Quando esse
+  parágrafo está dentro de um `DialogHeader`, ele contraria a ADR 0018 e precisa ir para o corpo na
+  migração — não ganhar um slot novo no header.
+- **`Card` é usado como caixa sem slots em várias telas**, com o padding escolhido por elas (`p-3`,
+  `p-5`, `px-3 py-2`). O root do Card continua sem padding próprio: quem não usa slots continua
+  decidindo. O padding pertence aos slots, como hoje.
+- **Os dois `PaneHeader` do produto escrevem quase a mesma linha** (`flex h-[3.75rem] items-center
+  … p-3 … border-b-0`) em contextos diferentes. É a prova de que padding e divisor pertencem à
+  primitiva.
+- **Um comentário no código do login documenta o defeito**: o `py-3` do `CardBody` "conta com um
+  CardFooter, que o login não tem". O ritmo do layout contínuo precisa reagir à ausência do rodapé.
+- **Três testes de consumidor contradizem a unificação** e precisam de decisão explícita, não de
+  ajuste mecânico: um proíbe `p-4` no Card, outro exige `p-0` no `DrawerBody`, outro proíbe
+  `ContentHeader` em uma seção. Os dois primeiros fixam contornos; o terceiro fixa uma escolha de
+  composição que continua válida.
+
+### 6. Slots por família
+
+A anatomia é comum; o conjunto de slots continua sendo decisão de cada família, porque decisões
+anteriores já os delimitaram:
+
+| Slot | Card | Content | Page | Dialog | Drawer | Pane |
+| --- | --- | --- | --- | --- | --- | --- |
+| Media | sim | não | não | sim (`DialogMedia`) | sim | sim |
+| Title | sim | sim | sim | sim | sim | sim |
+| Description | sim | sim | não (ADR 0014) | não (ADR 0018) | não (ADR 0018) | não |
+| Meta | não | sim (contador) | não (ADR 0009) | não | não | não |
+| Actions | sim | sim | sim | sim | sim | sim |
+| Body | sim | sim | sim | sim | sim | sim |
+| Footer | sim | não | sim | sim | sim | sim |
+
+As ADRs 0009, 0014 e 0018 não são reabertas: Page, Dialog e Drawer continuam sem descrição no
+header, e Page continua sem contador. `Dialog`, `Drawer` e `Pane` ganham o slot de ações que hoje
+não têm — a ausência obrigava a injetar nós soltos ao lado do título, e o `Studio` a manter três
+anatomias paralelas para a mesma entrada declarativa. O botão de fechar continua sendo o último
+elemento da linha; as ações da tela ficam antes dele.
+
+`Pane` ganha também título e mídia. Hoje ele não tem nenhum dos dois, e as duas telas que precisam
+de um cabeçalho remontam a linha com `span`, incluindo o ícone dentro do texto.
+
+`Content` permanece sem footer: é uma região nomeada dentro de outra superfície, e um rodapé
+pertence à superfície que a hospeda.
+
+### 7. Título: hierarquia e tamanho são independentes
+
+O nível semântico vem de `level` (`1`–`6`) ou de `asChild`, e nunca do tamanho visual. O tamanho vem
+da família e do layout. `CardTitle` deixa de ser um `div` sem escala e passa a declarar as duas
+coisas, com `h3` como default — um card é uma seção dentro de uma página que já tem `h1`.
+
+### 8. Mídia reutiliza a moldura existente
+
+O slot de mídia usa `IconTile` ou a mesma infraestrutura visual dele. Nenhuma família cria outra
+escala de molduras.
+
+Quando a marca já tem visual próprio — um orbe, um logotipo —, `asChild` deixa o slot ceder o
+elemento para ela: a escala continua vindo da mesma fonte, e a moldura sai de cena em vez de ser
+desenhada por baixo.
+
+`DialogMedia` é a exceção declarada: no modo de alerta a mídia não acompanha uma linha de título,
+ela é o elemento de reconhecimento da resposta, e mantém a moldura maior e centrada. A exceção vale
+só nesse modo, deriva da mesma infraestrutura das demais e é coberta por teste. Fora do alerta, o
+`DialogMedia` é a mesma moldura das outras famílias.
+
+### 7.1. O Pane aceita conteúdo livre; as demais não
+
+`Card`, `Dialog`, `Drawer`, `Page` e `Content` sempre nomeiam alguma coisa: seus headers aceitam só
+os slots da família e reprovam nó solto, com uma mensagem que lista o que é aceito.
+
+`Pane` é a superfície genérica — a coluna que hospeda navegação, marca, busca ou chrome que não é
+título nem ação. Seu header aceita conteúdo livre ao lado dos slots, e esse conteúdo ocupa o mesmo
+espaço do heading, de modo que as ações continuam indo para o extremo oposto sem classe no
+consumidor. A permissividade é dele, não uma brecha geral: forçar a marca de uma barra lateral a
+virar "título" seria uniformidade sem semântica.
+
+O conteúdo livre é renderizado **dentro** da região de heading, depois do título e da descrição,
+qualquer que seja a ordem no JSX. Ele herda dali a largura que o heading absorve, o que é o que
+permite às ações continuarem no extremo oposto — mas também significa que uma busca colocada no
+header aparece **abaixo** do título, não ao lado dele. Um header que precise de algo antes do
+título usa o slot de mídia; um que precise de algo ao lado usa o de ações.
+
+### 8.1. Nível semântico em todas as fachadas
+
+Todo título de superfície aceita `level`. Nos modais, onde a primitiva de acessibilidade emite o
+elemento, o nível troca a tag do mesmo nó por composição, nunca aninha um heading dentro de outro, e
+não altera a escala. Sem `level`, vale o `h2` que a primitiva já emitia.
+
+### 9. `Pane` deixa de ser uma família partida
+
+Raiz e slots passam a viver no mesmo módulo, com validação de pertencimento, documentação própria e
+os mesmos testes das demais famílias. `split.tsx` continua dono do redimensionamento; `sidebar.tsx`
+continua dono da navegação. A fronteira deixa de ser acidental e passa a ser declarada.
+
+### 10. Compatibilidade
+
+Aliases depreciados existentes (`CardContent`, `PaneContent`) seguem seu plano de remoção; esta
+decisão não cria novos.
+
+Classes de recuo, ritmo e escala que o consumidor já aplica continuam funcionando: `className` é
+mesclado por último e vence. Uma tela que ainda escreve `p-4` no `CardHeader` não quebra, apenas
+deixa de precisar.
+
+**Os divisores são a exceção, e é uma exceção real.** Eles nascem de variantes condicionais
+(`:not(:last-child)`), que têm especificidade maior que uma classe simples: `border-b-0` no
+consumidor não desliga a linha derivada. Desligar o divisor de uma região isolada não é, portanto,
+uma decisão do consumidor — é decisão da superfície, e se expressa trocando o layout dela para
+`continuous`. A paleta de comandos é o caso dentro do próprio SDK: ela é contínua, e não um
+seccionado com a primeira linha apagada.
+
+Pela mesma razão, a regra que suprime o divisor entre um header e um rodapé adjacentes precisa
+vencer a que o cria — não basta vir depois dela na folha, porque a ordem das variantes não é nossa.
+
+**O recuo inferior da última região no layout contínuo segue a mesma lógica** (20.0.0). Ele vem de
+`[&:last-child]:pb-*`, e um `pb-0` do consumidor não o desliga quando a região é a última da
+superfície: para mudar esse respiro, a superfície troca de layout. Quem precisar mesmo sobrescrever
+escreve a mesma variante (`[&:last-child]:pb-*`), que o merge reconhece como substituta.
+
+## Consequências
+
+- Uma mudança de espaçamento, divisor ou escala passa a ter um lugar só; hoje tem seis.
+- Card ganha um modo que a aplicação já construía à mão, e a documentação deixa de ensinar o
+  contorno.
+- Dialog e Drawer ganham ações no header; `Presentation` deixa de injetar nós soltos.
+- Pane deixa de ser exceção não testada.
+- Consumidores que aplicavam classes de correção podem removê-las; quem não remover continua
+  funcionando, o que permite migração incremental.
+- O custo é concentrado: quase toda a superfície visual do SDK muda de implementação ao mesmo tempo,
+  e a rede de proteção precisa existir antes da migração, não depois.
+- Uma família que precise divergir passa a precisar declarar a divergência na tabela e cobri-la por
+  teste. Isso é deliberado: torna a diferença uma decisão, não um acidente.
+
+## Alternativas descartadas
+
+### Manter cada família com seu header
+
+Preservaria compatibilidade absoluta e evitaria o custo de migração. Foi descartada porque é o
+estado atual: produziu três escalas de padding, um título sem escala, divisores manuais em uma
+família e a documentação pública ensinando o contorno.
+
+### Expor um `<Surface>` genérico
+
+Reduziria o código a uma implementação e uma API. Foi descartada porque apagaria a semântica de cada
+família — um card, um modal e um painel deixariam de se distinguir no código da tela — e porque o
+ganho real está na infraestrutura interna, que este ADR unifica sem expor.
+
+### Unificar também as medidas entre famílias
+
+Um único recuo para todas as superfícies eliminaria a tabela de anatomia. Foi descartada porque as
+famílias têm densidades legítimas diferentes: o chrome de página é mais compacto que um card, e um
+modal tem largura controlada. O invariante que importa é o alinhamento dentro de cada superfície,
+não a igualdade entre superfícies diferentes.
+
+### Tratar `layout` como propriedade de cada slot
+
+Permitiria um header seccionado com um corpo contínuo. Foi descartada porque o layout é a relação
+entre as regiões: um divisor depende de quem está do outro lado. Propriedade por slot permitiria
+compor superfícies incoerentes sem erro.
+
+### Derivar os divisores por CSS no consumidor
+
+Manteria o componente menor. Foi descartada porque devolve ao consumidor a decisão que esta ADR
+retira dele, e porque a regra depende de presença de irmãos, que o componente conhece e a tela
+não.
+
+## Verificação
+
+- Uma suíte transversal parametrizada percorre as famílias configuráveis e verifica, para cada
+  layout: alinhamento horizontal idêntico entre header, body e footer; divisor apenas entre regiões
+  adjacentes presentes; escala do título independente do nível semântico; header com e sem mídia,
+  descrição e ações; ações no extremo oposto sem classe no consumidor; body sem header; header sem
+  footer; footer com e sem ações.
+- A mesma suíte verifica que `Page` e `Content` não expõem `sectioned` e que nenhuma família
+  reimplementa as classes de anatomia localmente.
+- Testes de família continuam cobrindo o que é específico de cada uma.
+- Exemplos vivos no catálogo apresentam a matriz de layouts e slots.
+- `opus check` continua reprovando slots fora da família.
+- Um teste de API pública reprova a exportação de `SurfaceHeader` ou do módulo de anatomia.

package/docs/adr/0024-fill-height-propagates-by-context.md

@@ -0,0 +1,118 @@
+# ADR 0024 — A ocupação de altura se propaga por contexto
+
+- **Status:** aceita.
+- **Data:** 2026-09-25.
+- **Complementa:** ADRs 0017 e 0023.
+
+## Contexto
+
+`Page layout="fill"` limita a página à altura do shell, e `ActionList layout="fill"` ocupa a altura
+disponível e rola somente os resultados. As duas metades já existiam desde a 18.3.0, mas não se
+encontravam sozinhas: a altura só chega à lista se cada elemento entre a página e ela for uma coluna
+flexível com `min-h-0`. `PageBody`, `Content` e `ContentBody` não faziam isso.
+
+O efeito era mensurável no código e na documentação:
+
+- a página da `ActionList` ensinava a escrever `flex min-h-0 flex-1 flex-col` em `PageBody`,
+  `Content` e `ContentBody` para o `fill` funcionar;
+- a `Presentation` de lista em `layout="fill"` envolvia o corpo em `Content` e `ContentBody` sem essa
+  cadeia e não repassava `layout` à lista — o `fill` declarado nunca chegava a ela;
+- quando uma classe faltava, a lista crescia com o conteúdo e o `fill` se comportava como `flow`,
+  sem erro nem aviso.
+
+As forças em tensão:
+
+- **Automação × previsibilidade.** A cadeia é mecânica e o consumidor erra ao montá-la à mão; mas
+  uma página `fill` também hospeda seções irmãs, cards e diálogos que não devem virar colunas
+  flexíveis por acidente.
+- **Contexto React × DOM.** O contexto atravessa qualquer componente, inclusive portais e
+  contêineres que não repassam altura; a altura só atravessa o DOM elemento a elemento.
+- **Default × explícito.** Uma lista dentro da cadeia quase sempre quer `fill`; uma lista em uma
+  seção secundária da mesma página quer `flow`.
+
+## Decisão
+
+### 1. A raiz publica, os elos republicam, a folha se registra
+
+- **Raiz:** `Page layout="fill"` publica a cadeia. `Page layout="flow"` a interrompe. A
+  `Presentation` em página herda o comportamento da `Page` que monta.
+- **Elos canônicos:** `PageBody`, `Content`, `ContentBody` e o corpo da `Presentation` leem a
+  cadeia e a republicam para os filhos. Na cadeia, carregam `data-fill="false"`.
+- **Folha:** a `ActionList`. Sem `layout`, ela assume `fill` quando o elemento pai no DOM é um elo
+  (`data-fill`) e se registra na cadeia. Com `layout="fill"` explícito, registra-se mesmo sob um
+  contêiner próprio; com `layout="flow"` explícito, nunca se registra.
+
+### 2. Só o caminho até a folha vira coluna flexível
+
+Um elo aplica `flex min-h-0 flex-1 flex-col` e passa a `data-fill="true"` somente quando uma folha
+se registrou abaixo dele. Seções irmãs sem lista mantêm a altura do próprio conteúdo, e uma página
+`fill` sem lista renderiza exatamente como antes. O registro acontece em `useLayoutEffect`, antes
+da primeira pintura.
+
+### 3. Superfícies com anatomia própria interrompem a cadeia
+
+`Card`, `Dialog`, `Drawer` e `Pane` interrompem a propagação no provider de layout que já
+compartilham (ADR 0023). A altura do corpo delas é decisão delas, inclusive quando um portal as
+renderiza dentro de uma página `fill`. A própria `ActionList` também interrompe a cadeia para o que
+ela hospeda. Em `Presentation`, o `fill` continua valendo apenas para a superfície `page`.
+
+### 4. O mecanismo é interno
+
+O contexto e os hooks vivem em um módulo interno, fora da API pública. Um contêiner próprio entre o
+elo e a lista não é detectado como elo: quem o escreve declara `layout="fill"` na lista e dá ao
+contêiner a coluna flexível. Novos elos ou folhas entram no SDK, com teste, e não no consumidor.
+
+## Consequências
+
+- `Page layout="fill"` › `PageBody` › `Content` › `ContentBody` › `ActionList` funciona sem classes
+  no consumidor, e a `Presentation` de lista em `fill` passa a entregar a rolagem interna prometida.
+- Classes que o consumidor já escrevia para montar a cadeia continuam funcionando e podem ser
+  removidas: o `className` é mesclado por último e repete as mesmas classes.
+- Uma `ActionList` sem `layout`, filha direta de um elo em uma página `fill`, passa a ocupar a altura.
+  Quem queria a lista crescendo com a página declara `layout="flow"`.
+- A primeira renderização de uma cadeia com folha faz uma passada extra de layout effect. No
+  servidor, a cadeia só se forma na hidratação.
+- `Tabs` e outros contêineres intermediários não são elos, em qualquer ponto do caminho. A lista só
+  confere o pai imediato: com um contêiner próprio entre dois elos (por exemplo, um `div` entre
+  `PageBody` e `Content`), ela ainda se registra e os elos viram coluna flexível, mas a altura não
+  atravessa o contêiner e a lista se comporta como `flow`. Quem compõe assim dá ao contêiner a
+  coluna flexível, como antes.
+- O elo ativo vira coluna flexível com `align-items: stretch`, que a lista precisa. Os demais filhos
+  de cada elo ativo também são afetados: um botão inline se estica à largura do elo e margens
+  verticais deixam de colapsar. Para um irmão manter a largura do conteúdo, dê a ele `self-start`
+  ou envolva-o em um contêiner próprio.
+- `Dialog` em `mode="alert"` também interrompe a cadeia, como os demais modos.
+
+## Alternativas descartadas
+
+### Manter a cadeia no consumidor
+
+Não custa nada ao SDK. Foi descartada porque é o estado que produziu a documentação ensinando
+classes de correção e a `Presentation` com `fill` que não chegava à lista.
+
+### Aplicar a coluna flexível em todo elo dentro de `fill`
+
+Mais simples: bastaria ler o contexto. Foi descartada porque duas seções irmãs com `flex-1` dividem
+a altura ao meio e o conteúdo de uma transborda sobre a outra, e porque `flex-col` estica filhos
+inline, como botões, que antes tinham a largura do conteúdo.
+
+### Detectar a folha só por CSS (`:has`)
+
+Evitaria o registro em React. Foi descartada porque `:has` enxerga qualquer descendente no DOM,
+inclusive listas dentro de cards e contêineres que não repassam a altura, e porque a decisão da
+lista — `fill` ou `flow` — ainda precisaria do contexto.
+
+### Expor o contexto na API pública
+
+Deixaria o consumidor criar elos próprios. Foi adiada: sem um caso real além de `ActionList`, o
+contrato público seria especulativo.
+
+## Verificação
+
+- `tests/ui/fill-region.test.tsx` renderiza a cadeia `Page fill` › `PageBody` › `Content` ›
+  `ContentBody` › `ActionList` e confere atributo e classes de cada nível; cobre seções irmãs,
+  página `fill` sem lista, página `flow`, `layout="flow"` explícito, contêiner próprio com e sem
+  `fill` explícito, a interrupção por `Card` e a interrupção pela própria lista.
+- `tests/ui/presentation.test.tsx` confere a `Presentation` de lista em `fill`, dentro e fora de
+  `PageShell`, e a lista em `flow` quando a `Presentation` é `flow`.
+- A rolagem real é conferida em navegador: a happy-dom não calcula layout.

package/docs/data-products.md

@@ -10,7 +10,10 @@ Ele não é uma query, tabela ou view: essas são implementações possíveis. A
 recorte e autorização continua sendo cada Action.
 
 ```ts
-import { defineDataProduct, defineDomain } from '@softize/opus'
+import { defineDataProduct, defineDomain } from '@softize/opus/core'
+import { LeadEntity } from './entity.ts'          // defineEntity({ name: 'lead', … })
+import { leadList } from './actions/list.ts'      // action 'lead.list'
+import { leadFunnel } from './actions/funnel.ts'  // action 'lead.funnel'
 
 export const salesLeads = defineDataProduct({
   id: 'sales.leads',
@@ -22,24 +25,27 @@ export const salesLeads = defineDataProduct({
   classification: 'internal',
   nature: 'real',
   sources: [{ id: 'followize', label: 'Followize' }],
-  entities: ['Lead'],
+  entities: ['lead'],
   access: {
     permissionContexts: ['sales'],
     organizationalScopes: ['unit', 'team'],
   },
-  interfaces: ['sale.list', 'sales.performance'],
+  interfaces: ['lead.list', 'lead.funnel'],
 })
 
-export const salesDomain = defineDomain({
-  name: 'sales',
-  entities: { Lead },
-  actions: { saleList, salesPerformance },
+export const leadDomain = defineDomain({
+  name: 'lead',
+  entities: { LeadEntity },
+  actions: { leadList, leadFunnel },
   dataProducts: { salesLeads },
 })
 ```
 
-`interfaces` e `entities` usam os nomes declarados, não nomes de arquivo ou tabela. O registro do
-domínio e `opus check` detectam relações inexistentes. `sources` identifica sistemas ou conjuntos
+`interfaces` e `entities` usam os nomes declarados — o `name` da action e o `name` de
+`defineEntity` —, não a chave do objeto, o nome do arquivo ou da tabela. O registro do domínio e
+`opus check` detectam relações inexistentes: aqui, `entities: ['LeadEntity']` ou `['Lead']` seriam
+recusados, porque a entidade se declara como `lead`. As actions seguem o prefixo do domínio
+(`lead.*`), como qualquer action registrada nele. `sources` identifica sistemas ou conjuntos
 upstream; uma Fonte não precisa ser uma Entity Opus.
 
 ## Acesso e segurança

package/docs/protocol.md

@@ -1606,7 +1606,6 @@ defineReaction({
   
   handler: async (ctx, event) => {
     await syncToSalesforce(event.data.leadId)
-    await ctx.emit('hub.lead.synced', { leadId: event.data.leadId })
   },
 })
 
@@ -1629,7 +1628,7 @@ type ReactionContext = {
   user:     User | null              // ator que disparou o evento (pode ser system)
   tenantId: string | null
   db:       unknown                  // mesmo data adapter
-  emit:     EmitFn                   // reaction pode emitir novos eventos (chain)
+  emit:     EmitFn                   // descarta o evento sem publicar (sem encadeamento)
   log:      LoggerAdapter            // logger pre-bound com contexto da reaction
   storage:  StorageAdapter | null    // storage de arquivos (experimental)
   provenance: Provenance             // { kind: 'reaction', … }
@@ -1638,7 +1637,7 @@ type ReactionContext = {
 }
 ```
 
-Reaction pode emitir eventos novos via `ctx.emit` — habilita workflows declarativos em cadeia (`lead.created` → reaction → `lead.onboarded` → outra reaction → ...).
+Uma reaction não encadeia outra por evento: dentro dela, `ctx.emit` descarta o evento sem publicá-lo. Com `config.dev` ativo, cada descarte registra o aviso `runtime.reaction_emit_ignored` no log; em produção, o descarte é silencioso. Quando outro consumidor precisa desse fato, emita o evento no handler da action que o produz e declare-o em `emits`.
 
 ### Setup unificado
 
@@ -1690,7 +1689,7 @@ para cada reaction:
    ↓ (a) dedup check (se declarado)
    ↓ (b) authorize (se declarado)
    ↓ (c) handler executa (com timeout)
-   ↓ (d) handler emite eventos (opcional, via ctx.emit)
+   ↓ (d) ctx.emit dentro da reaction não publica (descartado, com aviso em dev)
    ↓ (e) audit (reaction completed/failed)
    ↓ (f) retry se falhou e config permite
 ```

package/docs/releasing.md

@@ -60,7 +60,7 @@ pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
 `pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.3.0` em `dependencies`, pois usa
+se qualquer um falhar**. O Opus declara `@softize/base ^2.4.0` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
@@ -74,7 +74,7 @@ não é bloqueada por cobertura abaixo de 100%; a cobertura é acompanhada com `
 **Smoke do esqueleto**: depois do bump e antes do publish, o `release.sh` gera um app com
 `opus create`, instala o **tarball exato** que vai ser publicado e roda os gates dele
 (typecheck · test · `opus check` · `opus copy --check` · `base copy check` · manifest ·
-build). O template exige `@softize/base ^2.3.0`; publique a Base compatível antes do Opus.
+build). O template exige `@softize/base ^2.4.0`; publique a Base compatível antes do Opus.
 O `minimumReleaseAgeExclude` do template inclui os dois pacotes, e o smoke executa os
 fragmentos de pre-push para provar que o layout pnpm instalado resolve ambos os CLIs.
 É o que pega o que typecheck+test não

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "18.5.0",
+  "version": "20.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -247,7 +247,7 @@
     "@radix-ui/react-slot": "^1.1.1",
     "@radix-ui/react-tabs": "^1.1.2",
     "@radix-ui/react-tooltip": "^1.1.6",
-    "@softize/base": "^2.3.0",
+    "@softize/base": "^2.4.0",
     "@tailwindcss/typography": "^0.5.20",
     "@types/markdown-it": "^14.1.2",
     "class-variance-authority": "^0.7.1",

package/registry/skills/create-opus-action/scripts/scaffold.mjs

@@ -2,7 +2,8 @@
 
 const KINDS = new Set(['simple', 'form', 'list', 'view'])
 const cap = (value) => value.charAt(0).toUpperCase() + value.slice(1)
-const constant = (resource, verb) => resource + verb.split('-').map(cap).join('')
+const camel = (value) => value.split('-').map((part, index) => (index === 0 ? part : cap(part))).join('')
+const constant = (resource, verb) => camel(`${resource}-${verb}`)
 
 function contractBody({ resource, verb, kind }) {
   const name = `${resource}.${verb}`

package/registry/templates/app/package.json

@@ -30,7 +30,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@softize/base": "^2.3.0",
+    "@softize/base": "^2.4.0",
     "@tailwindcss/vite": "^4.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",