@softize/opus 18.5.0 → 20.0.0

package/CHANGELOG.md

@@ -7,6 +7,281 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 20.0.0 — 2026-09-26
+
+Esta versão corrige componentes que falhavam em acessibilidade ou em layout, leva o `fill` da
+página até a lista sozinho, torna explícitas falhas que antes passavam em silêncio, reescreve boa
+parte da documentação e atualiza a Base para a 2.4.0. É major porque algumas dessas mudanças podem
+interromper a aplicação, o boot ou os gates de um projeto que funcionava na 19.0.0: a seção
+**Breaking** diz o que fazer em cada uma. Outros pontos podem pedir ajuste sem interromper a
+aplicação; alguns só afetam testes:
+
+- `Slider` envolvido em `role="group"` com `aria-labelledby`, como a documentação anterior
+  recomendava: passe o `aria-labelledby` ao próprio `Slider`;
+- `Truncate` dentro de link ou botão: passe `tabIndex={-1}` para evitar uma segunda parada;
+- conteúdo próprio colocado direto no `Avatar`: arredonde-o, porque o root deixou de recortar;
+- testes que buscam um `Alert` informativo ou de sucesso por `getByRole('alert')`: use `status`;
+- testes que buscam um `Copyable` com rótulo pelo nome “Copiar”: use o texto visível;
+- `closeDisabled` em Dialog e Drawer passa a bloquear também Esc e clique fora; handlers criados só
+  para isso podem sair;
+- testes que buscam o botão de confirmar do `ActionTrigger` pelo nome longo do gatilho: ele agora
+  usa o rótulo da action;
+- testes que conferem o texto do erro de um hook de action fora do `OpusProvider`: a mensagem mudou;
+- `ActionList` sem `layout`, filha direta de `PageBody` ou `ContentBody` em uma `Page` com
+  `layout="fill"`: passa a ocupar a altura; declare `layout="flow"` para manter o comportamento
+  anterior. Os demais filhos de cada região que repassa a altura passam a ocupar a largura dela; dê
+  `self-start` a um botão que deva manter a largura do conteúdo.
+
+### Breaking
+
+**`Split` recusa filho que não seja `Pane`.** Antes, esse filho — e um `Pane` escrito dentro de um
+fragment — sumia da tela sem aviso. Agora o fragment é expandido e qualquer outro filho interrompe a
+renderização com um erro que aponta o nó. Migração: envolva o conteúdo em `<Pane>`; se o componente
+que você passa ao `Split` devolve um `Pane`, escreva o `<Pane>` diretamente no `Split` e ponha o
+componente dentro dele. Espaço em branco, `null` e `false` continuam ignorados, mas um `0` vindo de
+`{items.length && <Pane />}` interrompe: use `items.length > 0 &&`.
+
+**`runtime.start()` valida os schedules.** Um schedule ativo que aponta para uma action não
+registrada faz o boot falhar com `runtime.schedule_action_not_found`; antes, cada disparo falhava em
+silêncio. Migração: corrija o nome da action ou declare `enabled: false` no schedule. Rode o
+`start()` num teste com o scheduler para descobrir antes do deploy.
+
+**`opus check` ganha duas regras que reprovam o gate.** `ignored-by-kind` aponta `emits` ou
+`background` em action `list` ou `view`, que o runtime sempre ignorou; `ui-structure-split` aponta
+filho de `Split` que não seja `Pane`. Migração: remova os campos ignorados e ajuste o `Split` como
+acima.
+
+**`opus check` cobra a anatomia dos headers da 19.0.0.** A regra `ui-structure` passa a reprovar
+`CardMedia`, `DialogNavigation`, `DialogActions`, `DrawerNavigation`, `DrawerMedia`, `DrawerActions`,
+`PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions` fora do header da própria família —
+antes, esses slots renderizavam em qualquer lugar sem aviso. Migração: mova-os para dentro de
+`CardHeader`, `DialogHeader`, `DrawerHeader` ou `PaneHeader`.
+
+**`opus copy --check` inventaria `PaneTitle` e `PaneDescription`.** Um título ou descrição de pane
+com conteúdo dinâmico, como `<PaneTitle>{name}</PaneTitle>`, passa a gerar diagnóstico e reprovar o
+gate. Migração: rode `opus copy`; para texto dinâmico, use uma constante ou uma `I18nRef` com
+`default`, ou declare a superfície em `copy.dynamic` com seletor, tipo, motivo e referência.
+
+**Três tipos seguem o elemento renderizado.** `PopoverTitle` e `EmptyDescription` são tipados como
+`div` e `KbdGroup` como `kbd`. O DOM não muda e raramente há algo a ajustar: só um código que
+dependia do tipo `HTMLHeadingElement` ou `HTMLParagraphElement` nesses componentes.
+
+### Avatar
+
+O `AvatarBadge` aparece inteiro em todos os tamanhos. O selo fica no canto da caixa do `Avatar`,
+por fora do círculo, e o root recortava o próprio conteúdo com `overflow-hidden`: só um quarto do
+selo ficava visível. Agora `AvatarImage` e `AvatarFallback` herdam o raio do root e fazem o próprio
+recorte. A forma continua declarada no `Avatar` — circular por padrão, ou `className="rounded-lg"`
+para um logo — e o anel de fundo do `AvatarGroup` a acompanha.
+
+Se o seu projeto contornava o corte com `overflow-visible` no `Avatar` ou `rounded-full` no
+`AvatarImage`, pode remover essas classes. Conteúdo próprio colocado direto no `Avatar`, fora de
+`AvatarImage` e `AvatarFallback`, deixa de ser recortado: arredonde-o no próprio elemento.
+
+### Acessibilidade
+
+- **`Alert`** anuncia conforme o contexto: `role="alert"` em `danger` e `warning`, que interrompem o
+  leitor de tela, e `role="status"` nos demais, que esperam a leitura em curso terminar. Um `role`
+  passado ao componente continua vencendo.
+- **`Progress`** passa `value` ao progressbar, que expõe `aria-valuenow` e `data-state`
+  (`loading`, `complete` ou `indeterminate`), e respeita `max`: `value={3} max={4}` preenche três
+  quartos da barra.
+- **`Slider`** nomeia os controles. `aria-label` e `aria-labelledby` passados ao `Slider` nomeiam o
+  thumb, que é o elemento focável; em intervalo, a nova prop `thumbLabels` dá um nome a cada
+  controle. Sem `thumbLabels`, o nome comum se compõe com a posição (“Preço, mínimo”); sem nome
+  algum, o intervalo anuncia “Mínimo” e “Máximo”. Se você envolvia o Slider
+  em um `role="group"` com `aria-labelledby`, passe o `aria-labelledby` ao próprio `Slider`.
+- **`Copyable`** com rótulo visível passa a se chamar pelo próprio texto, e quem usa comando de voz
+  consegue acioná-lo dizendo o que vê. Sem filhos, continua “Copiar” e “Copiado”. A confirmação é
+  anunciada por leitores de tela, e o botão só confirma quando o navegador aceita a cópia: com a
+  permissão negada, continua em “Copiar” e nenhum erro fica sem tratamento. Se você passava
+  `aria-label` só para repetir o texto visível, pode removê-lo.
+- **`Truncate`** com texto cortado entra na ordem de tabulação, e a dica passa a abrir pelo
+  teclado. Dentro de um link ou botão, passe `tabIndex={-1}` para evitar uma segunda parada no
+  mesmo item.
+- **`Carousel`** vertical responde às setas para cima e para baixo. Setas usadas em campos ou em
+  controles que navegam pelas setas dentro dos slides, como Slider, RadioGroup e Tabs, não trocam
+  mais de slide.
+
+### Formulário
+
+- **`Checkbox`** indeterminado tem aparência própria: o preenchimento de marcado com um traço.
+- **`IconPicker`** mede 2.25rem, como `Input` e `Select`, e mostra a moldura de erro com
+  `aria-invalid`.
+- **`InputOTP`** usa nas casas o mesmo fundo dos campos no tema claro.
+- **`InputGroup`** esmaece os addons sozinho quando o controle está desabilitado, e o clique no
+  addon também foca o `InputGroupTextarea`.
+- **`Label`** esmaece dentro de `<Field data-disabled="true">`.
+- **`CommandEmpty`** soma a `className` do consumidor ao estilo padrão, em vez de substituí-lo.
+
+### Layout
+
+`Page layout="fill"` leva a altura até a `ActionList` sozinha. `PageBody`, `Content`, `ContentBody`
+e o corpo da `Presentation` repassam a altura quando contêm uma lista, e a lista, sem `layout`,
+assume `fill` quando é filha direta de um deles. Seções irmãs sem lista mantêm a altura do conteúdo,
+uma página `fill` sem lista não muda, e `Card`, `Dialog`, `Drawer` e `Pane` não herdam o `fill` da
+página (ADR 0024). A `Presentation` de lista em `layout="fill"` passa a entregar o que prometia: a
+lista ocupa a altura da página e só os resultados rolam.
+
+Quem encadeava `flex min-h-0 flex-1 flex-col` à mão pode remover as classes; mantidas, continuam
+funcionando. Com um contêiner próprio entre `ContentBody` e a lista, como um `TabsContent`, a lista
+continua em `flow`: declare `layout="fill"` nela e dê ao contêiner `flex min-h-0 flex-1 flex-col`.
+
+### Superfícies e patterns
+
+- **`closeDisabled`** em `Dialog` e `Drawer` bloqueia todo fechamento: além do botão, Esc e clique
+  ou foco fora. Em `Dialog mode="alert"`, bloqueia o Esc. Handlers `onEscapeKeyDown`,
+  `onPointerDownOutside` e `onInteractOutside` informados continuam rodando antes do bloqueio.
+- **`ActionTrigger`**: sem `confirmLabel` no contrato, o botão de confirmar usa o `label` da action,
+  como “Excluir”, e não mais o `label` do gatilho, como “Excluir Unidade Centro”.
+- **`Split`** mostra um `Pane` escrito dentro de um fragment (veja **Breaking**).
+- **Card, Pane, Dialog e Drawer em `layout="continuous"`:** um cabeçalho sem corpo nem rodapé
+  fecha a superfície com o mesmo respiro que tem em cima. Nada muda quando há corpo ou rodapé.
+- **`ActionFormCard`** ganha `titleLevel`, que escolhe o nível do heading do título (`h3` por
+  padrão) sem mudar a aparência.
+- **Hooks de action** fora do `OpusProvider` lançam um erro que nomeia o hook chamado e explica
+  como resolver.
+
+### Runtime
+
+- **Schedules:** além da validação no `start()` (veja **Breaking**), uma execução que falha passa a
+  ser registrada no log com o schedule, a action e o código do erro.
+- **Avisos em desenvolvimento:** o runtime avisa quando uma reaction chama `ctx.emit`, que continua
+  sem publicar (`runtime.reaction_emit_ignored`), e quando uma action `list` ou `view` declara
+  `emits` ou `background`, que o runtime ignora (`runtime.action_field_ignored`). Em produção,
+  nada muda.
+
+### CLI
+
+- **`opus check`** ganha `ignored-by-kind` e `ui-structure-split` (veja **Breaking**).
+- **Skill `create-opus-action`:** o scaffold gera identificador válido para recurso em kebab-case
+  (`sales-order create-item` → `salesOrderCreateItem`). Rode `opus setup` para atualizar a cópia.
+- **`opus check` e `opus introspect`** ignoram arquivos `*.test.*` e `*.spec.*` e as pastas `test`,
+  `tests`, `__tests__`, `fixtures` e `__fixtures__`: actions declaradas ali não são registradas, e o
+  check deixava de passar por causa delas. Uma action real guardada em uma pasta com esses nomes deixa
+  de ser verificada.
+- **`opus check`** confere a anatomia real dos headers da 19.0.0 (veja **Breaking**).
+- **`opus copy`** inventaria `PaneTitle` e `PaneDescription` (veja **Breaking**) e
+  `Slider.thumbLabels`.
+
+### Depreciações
+
+`resolveIconTileStyle` (use `IconTile` ou `iconTileVariants`) e `MenuPortal` (`MenuContent` já usa
+portal) estão depreciados e saem na próxima major.
+
+### Documentação
+
+As páginas foram revisadas contra o código desta versão. Exemplos que não compilavam ou que
+descreviam comportamento antigo foram corrigidos, componentes e props sem referência ganharam
+tabela, e as páginas passaram a ligar umas às outras no ponto de decisão. Entre as mudanças:
+
+- nova página Produtos de Dados, e seções sobre `defineDomain`, reactions,
+  `loads` e os providers necessários para consumir a UI;
+- os exemplos voltam a ter o layout que o texto descreve: as classes usadas só nas páginas `.md`
+  passam a ser geradas no site e na rota `/__docs` do `opusDocs()`, sem mudar o CSS do seu app nem
+  o de produção;
+- `ActionList` descreve a barra de filtros como funciona desde a 18.3.0;
+- o exemplo de `opusDesign()` em `@softize/opus/vite` mostra o arranjo do template: import dinâmico
+  condicionado ao modo design e `vite --mode design --configLoader runner`. Um import estático do
+  plugin quebra o carregamento do `vite.config.ts` no Node 22+ com
+  `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`; se o seu config faz isso, adote o padrão do
+  template.
+
+### Base 2.4.0
+
+O Opus passa a depender de `@softize/base ^2.4.0`, e o template do `opus create` também. A regra de
+formulários da Base agora é a que o Opus já pratica: título `Criar {recurso}` ou
+`Editar {recurso}`, ação `Salvar`.
+
+### Correções do histórico
+
+- **19.0.0:** a entrada **Breaking** diz que nó solto dentro do header lança erro nos quatro
+  headers. Isso vale para `CardHeader`, `DialogHeader` e `DrawerHeader`; o `PaneHeader` aceita
+  conteúdo livre, como uma busca ou a marca, depois do título e da descrição. Só a repetição de um
+  slot lança erro.
+
+## 19.0.0 — 2026-09-24
+
+Card, Dialog, Drawer e Pane passam a derivar a anatomia da mesma infraestrutura que Page e Content
+já usavam. Cada superfície declara `layout="continuous" | "sectioned"` no seu componente raiz, e o
+layout responde por um pacote: recuo das regiões, ritmo vertical, escala do título, posição das
+ações, apresentação da mídia e divisores. O divisor passa a ser derivado da vizinhança das regiões —
+um header seguido de corpo desenha a linha; um header sozinho, não.
+
+Os headers passam a posicionar sozinhos o que antes o consumidor montava: mídia, título, descrição
+(onde a família a tem), ações no extremo oposto e o botão de fechar depois delas. `Dialog`, `Drawer`
+e `Pane` ganham slots de ações e de navegação; `Card` e `Pane` ganham slot de mídia; `Card` ganha
+título com nível semântico.
+
+A família `Pane` deixa de viver em dois módulos: raiz e slots agora moram juntos, com título,
+mídia, ações, descrição e página própria na documentação.
+
+`MetricCard` ganha ativação: com `onActivate`, `active` e `activationLabel`, a medida vira um
+controle que aplica o recorte que ela resume — o card passa a emitir `aria-pressed` e a anunciar o
+próprio nome. As três propriedades andam juntas pelo tipo; declarar `active` sem `onActivate` não
+compila. A marcação de ativo é a borda na cor primária: antes era um anel desenhado para fora da
+borda, que qualquer ancestral com `overflow-hidden` cortava. O anel de foco também passa a ser
+interno.
+
+Na mesma versão, a lista em `layout="fill"` troca a rolagem montada com um contêiner posicionado
+por uma grade de duas linhas: os resultados ocupam a folga, o rodapé se mede pelo conteúdo, e o
+contêiner da tabela abre mão da rolagem horizontal para não roubar do cabeçalho a referência do
+`sticky`. O rodapé encosta na última linha e mantém a mesma altura com e sem paginador. O detalhe
+aproxima o ícone do rótulo, na escala densa das superfícies produtivas.
+
+### Breaking
+
+**Headers validam seus slots.** `CardHeader`, `DialogHeader`, `DrawerHeader` e `PaneHeader` aceitam
+apenas os slots da família e no máximo um de cada. Nó solto dentro do header passa a lançar erro com
+a lista do que é aceito. Migração: envolva ações em `CardAction`, `DialogActions`, `DrawerActions`
+ou `PaneActions`; navegação em `DialogNavigation` ou `DrawerNavigation`; ícone em `CardMedia`,
+`DrawerMedia` ou `PaneMedia`. Descrição dentro do header de modal não tem slot e vai para o começo
+do corpo, como as ADRs 0014 e 0018 já determinavam.
+
+**`CardTitle` virou heading.** Era um `div` sem escala tipográfica; agora emite `h3` por padrão,
+aceita `level` para a hierarquia correta e declara a escala pelo layout. Migração: remova o heading
+que você embutia dentro dele e o `text-*` que aplicava por fora; passe `level` quando a página pedir
+outra hierarquia.
+
+**Divisores saem do consumidor.** `<CardHeader className="border-b">` e
+`<CardFooter className="border-t">` deixam de ser necessários: use `layout="sectioned"` no `Card`.
+As classes continuam funcionando, mas somam uma segunda linha sobre a derivada.
+
+**`PaneHeader` e `PaneFooter` ganharam recuo próprio** e o `Pane` passa a usar `inset="none"`
+sozinho quando contém slots estruturais. Migração: remova o `inset="none"` e o padding que a tela
+aplicava no header; remova também o `border-b-0`/`border-t-0` de quem desligava o divisor para
+redesenhá-lo à mão.
+
+**O rodapé do `Drawer` recebeu a faixa sutil do `Dialog`.** A ausência era divergência não declarada
+entre duas superfícies com a mesma anatomia; agora as duas usam o mesmo fundo. O título do Drawer
+também perdeu o `text-foreground` que só ele tinha.
+
+**Títulos de modal passam a truncar.** `DialogTitle` e `DrawerTitle` mantêm o nome da superfície em
+uma linha, com reticências quando não cabe, em vez de empurrar o corpo para baixo. O
+`mode="alert"` é a exceção: ali o título é centralizado e pode ocupar duas linhas, porque a
+resposta obrigatória não tem corpo para empurrar. As telas que já
+escreviam `truncate` podem remover a classe. Quando o nome precisar aparecer inteiro, ele pertence
+ao começo do corpo, não ao cabeçalho (ADR 0018).
+
+**Mídia com visual próprio.** Os slots de mídia aceitam `asChild`: uma marca que já se desenha —
+um orbe, um logotipo — ocupa o slot sem ganhar a moldura por cima, e continua herdando a escala.
+
+**O rodapé do `Drawer` mantém o `mt-auto`** que o `Dialog` não tem. A diferença passa a ser
+declarada: o conteúdo lateral raramente preenche a altura da janela, e sem isso o rodapé subiria
+atrás do corpo.
+
+**Divisor não se desliga por classe.** `border-b-0` no consumidor não apaga a linha derivada — ela
+vem de uma variante condicional, que vence uma classe simples. Uma superfície sem divisores é uma
+superfície `continuous`: troque o layout no root em vez de apagar a borda região a região.
+
+### Migração rápida
+
+1. Rode a aplicação e siga os erros dos headers: cada um diz o slot que falta.
+2. Remova `p-*`, `border-b`, `border-t`, `flex-row`, `justify-between` e `text-*` que existiam só
+   para corrigir o default da família.
+3. Troque `<Card>` + classes de divisor por `<Card layout="sectioned">`.
+4. Onde a tela remontava header com `div`, use os slots — eles agora posicionam sozinhos.
+
 ## 18.5.0 — 2026-09-22
 
 `Content` passa a concentrar estrutura e apresentação de blocos com cabeçalho e corpo: aceita

package/bin/cli.mjs

@@ -415,10 +415,15 @@ Regras das actions:
   requires-sem-authorize  — \`requires\` é declarativo (o runtime não o executa);
                             action com requires precisa de authorize no contrato ou no
                             binding (o join contrato↔bind é cross-file)
+  ignored-by-kind         — \`emits\` ou \`background\` em action list/view: o runtime
+                            e o manifest só os aplicam em simple e form
 
 Regras da UI (@softize/opus/ui):
   ui-structure            — anatomia pública das superfícies compostas (ADR 0005):
                             filho permitido dentro do pai correto
+  ui-structure-split      — filho direto de Split que não é Pane (elemento HTML, texto,
+                            outro componente Opus ou componente do próprio arquivo); o
+                            Split lança erro ao renderizá-lo
   ui-semantic-api         — API semântica: \`context\` + \`variant\`; reprova aliases de
                             migração e \`tone\` em novos dicionários
   removed-ui-token        — token público removido (ring-edge, shadow-card…) com a

package/bin/lib/check.mjs

@@ -12,6 +12,9 @@
  *                            no contrato ou no binding). O join contrato↔bind é por
  *                            identificador exportado, cross-file; referência ambígua
  *                            ou não encontrada não acusa (sem falso-positivo).
+ *   ignored-by-kind        — `emits`/`background` em action list/view: o runtime e o manifest
+ *                            só os aplicam em simple/form. No bindAction, o kind vem do
+ *                            contrato pelo mesmo join por identificador exportado.
  *
  * A checagem cross-file de registro no runtime (graph) fica pra v2 (introspecção/MCP).
  * Saída: findings + exit ≠ 0 se houver erro. Zero actions num diretório NÃO-marcado
@@ -69,6 +72,19 @@ const FIELD_GROUP = {
 const SEG = "[a-z][a-z0-9]*(-[a-z0-9]+)*";
 const ACTION_NAME_RE = new RegExp(`^${SEG}(\\.${SEG})+$`);
 const KINDS = new Set(["simple", "form", "list", "view"]);
+// O runtime e o manifest só aplicam estes campos em `simple` e `form`; o tipo do binding os aceita
+// em qualquer kind, então a declaração num list/view compila e não tem efeito.
+const EXECUTION_ONLY_FIELDS = ["emits", "background"];
+const KINDS_WITHOUT_EXECUTION_FIELDS = new Set(["list", "view"]);
+
+/** Campos de execução declarados num kind que os ignora → mensagem do achado, ou null. */
+function ignoredByKindMessage(kind, keys) {
+  if (!KINDS_WITHOUT_EXECUTION_FIELDS.has(kind)) return null;
+  const fields = EXECUTION_ONLY_FIELDS.filter((field) => keys.includes(field));
+  if (fields.length === 0) return null;
+  const list = fields.map((field) => `\`${field}\``).join(" e ");
+  return `Action ${kind} declara ${list}, que o runtime e o manifest só aplicam em actions simple e form: a declaração não tem efeito. Remova ${list}; se a operação precisa de fila ou de eventos declarados, use uma action simple ou form.`;
+}
 
 // Tokens públicos removidos cuja ausência no CSS não quebra typecheck/build: sem uma
 // migração executável, o consumidor perde borda/sombra em silêncio. O check fica no Opus
@@ -121,23 +137,31 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["CardHeader", new Set(["Card"])],
   ["CardBody", new Set(["Card"])],
   ["CardFooter", new Set(["Card"])],
+  ["CardMedia", new Set(["CardHeader"])],
   ["CardTitle", new Set(["CardHeader"])],
   ["CardDescription", new Set(["CardHeader"])],
   ["CardAction", new Set(["CardHeader"])],
   ["DialogHeader", new Set(["DialogContent"])],
   ["DialogBody", new Set(["DialogContent"])],
   ["DialogFooter", new Set(["DialogContent"])],
+  ["DialogNavigation", new Set(["DialogHeader"])],
   ["DialogMedia", new Set(["DialogHeader"])],
   ["DialogTitle", new Set(["DialogHeader"])],
-  ["DialogDescription", new Set(["DialogHeader"])],
+  ["DialogActions", new Set(["DialogHeader"])],
   ["DrawerHeader", new Set(["DrawerContent"])],
   ["DrawerBody", new Set(["DrawerContent"])],
   ["DrawerFooter", new Set(["DrawerContent"])],
+  ["DrawerNavigation", new Set(["DrawerHeader"])],
+  ["DrawerMedia", new Set(["DrawerHeader"])],
   ["DrawerTitle", new Set(["DrawerHeader"])],
-  ["DrawerDescription", new Set(["DrawerHeader"])],
+  ["DrawerActions", new Set(["DrawerHeader"])],
   ["PaneHeader", new Set(["Pane", "Sidebar"])],
   ["PaneBody", new Set(["Pane", "Sidebar"])],
   ["PaneFooter", new Set(["Pane", "Sidebar"])],
+  ["PaneMedia", new Set(["PaneHeader"])],
+  ["PaneTitle", new Set(["PaneHeader"])],
+  ["PaneDescription", new Set(["PaneHeader"])],
+  ["PaneActions", new Set(["PaneHeader"])],
   ["AlertMedia", new Set(["Alert"])],
   ["AlertHeader", new Set(["Alert"])],
   ["AlertActions", new Set(["Alert"])],
@@ -589,6 +613,9 @@ export function lintAction(a) {
   // requires sem authorize: no defineAction o par mora no mesmo objeto — acusa direto.
   // No defineContract a regra é cross-file (o bind pode trazer o authorize row-level);
   // fica pro join do checkProject.
+  const ignored = ignoredByKindMessage(a.kind, a.keys);
+  if (ignored !== null) at("ignored-by-kind", ignored);
+
   if (
     a.form === "defineAction" &&
     a.keys.includes("requires") &&
@@ -738,6 +765,17 @@ export function checkProject(sources) {
           "`requires` do contrato é declarativo (o runtime não o executa) — sem `authorize` no contrato ou no binding, a action fica ABERTA.",
       });
     }
+    const ignored = ignoredByKindMessage(contract.kind, item.keys);
+    if (ignored !== null) {
+      findings.push({
+        rule: "ignored-by-kind",
+        level: "error",
+        action: contract.name ?? item.contractRef,
+        line: item.line,
+        file,
+        message: ignored,
+      });
+    }
   }
 
   return {
@@ -1040,6 +1078,140 @@ function directStructuralChildren(node, imports) {
   return { names, hasOpaque };
 }
 
+/**
+ * Componentes declarados no próprio arquivo (função, classe ou arrow/function atribuída).
+ * Um deles nunca é o `Pane` do Opus, então o `Split` recusaria o elemento mesmo que o
+ * componente devolva um `Pane`.
+ */
+function localComponentNames(sourceFile) {
+  const names = new Set();
+  const visit = (node) => {
+    if (
+      (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) &&
+      node.name !== undefined
+    ) {
+      names.add(node.name.text);
+    } else if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.initializer !== undefined &&
+      (ts.isArrowFunction(node.initializer) ||
+        ts.isFunctionExpression(node.initializer))
+    ) {
+      names.add(node.name.text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return names;
+}
+
+const jsxSpaceEntities = {
+  nbsp: "\u00a0",
+  ensp: "\u2002",
+  emsp: "\u2003",
+  thinsp: "\u2009",
+};
+
+/**
+ * Decodifica, no texto cru de um `JsxText`, as entidades numéricas e as nomeadas de espaço.
+ * As demais entidades nomeadas ficam como estão: nenhuma delas vira espaço em branco.
+ */
+function decodeJsxSpaceEntities(raw) {
+  return raw.replace(/&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g, (entity, dec, hex, name) => {
+    if (name !== undefined) return jsxSpaceEntities[name] ?? entity;
+    const code = dec !== undefined ? Number(dec) : Number.parseInt(hex, 16);
+    return code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+  });
+}
+
+/**
+ * Filhos diretos de um `<Split>` que o componente recusaria em runtime. Aceita `<Pane>`,
+ * fragments com panes, espaço em branco (inclusive entidades como `&nbsp;`), comentários,
+ * `null`/`undefined`/booleanos e ramos de condicional. Só aponta o que o código literal prova: elemento HTML, texto, outro componente
+ * do Opus ou componente declarado no próprio arquivo. Expressões dinâmicas (`{children}`,
+ * `{items.map(...)}`) e componentes de outros módulos ficam de fora, porque o valor só existe
+ * em runtime.
+ */
+function invalidSplitChildren(split, imports, localComponents) {
+  const invalid = [];
+  const text = (value, node, position) => {
+    const trimmed = value.trim();
+    if (trimmed === "") return;
+    invalid.push({
+      label: `o texto "${trimmed.length > 40 ? `${trimmed.slice(0, 40)}…` : trimmed}"`,
+      position: position ?? node.getStart(),
+    });
+  };
+  const element = (node) => {
+    const tag = jsxOpening(node).tagName;
+    if (!ts.isIdentifier(tag)) return;
+    const name = tag.text;
+    const imported = imports.get(name);
+    if (imported === "Pane") return;
+    const intrinsic = /^[a-z]/.test(name);
+    if (imported !== undefined || intrinsic || localComponents.has(name)) {
+      invalid.push({ label: `<${name}>`, position: node.getStart() });
+    }
+  };
+  const expression = (node) => {
+    if (ts.isParenthesizedExpression(node)) return expression(node.expression);
+    if (ts.isConditionalExpression(node)) {
+      expression(node.whenTrue);
+      expression(node.whenFalse);
+      return;
+    }
+    if (
+      ts.isBinaryExpression(node) &&
+      [
+        ts.SyntaxKind.AmpersandAmpersandToken,
+        ts.SyntaxKind.BarBarToken,
+        ts.SyntaxKind.QuestionQuestionToken,
+      ].includes(node.operatorToken.kind)
+    ) {
+      // O lado esquerdo é a condição, valor dinâmico; o direito é o que pode ser renderizado.
+      return expression(node.right);
+    }
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      return text(node.text, node);
+    }
+    if (ts.isNumericLiteral(node)) {
+      invalid.push({ label: `o número ${node.text}`, position: node.getStart() });
+      return;
+    }
+    if (
+      ts.isJsxElement(node) ||
+      ts.isJsxSelfClosingElement(node) ||
+      ts.isJsxFragment(node)
+    ) {
+      child(node);
+    }
+  };
+  const child = (node) => {
+    if (ts.isJsxText(node)) {
+      // O React entrega as entidades já decodificadas, e o `trim()` do Split descarta o texto
+      // que sobra só com espaço, como `&nbsp;` entre dois panes.
+      if (decodeJsxSpaceEntities(node.text).trim() === "") return;
+      // O JsxText começa logo após o nó anterior (`pos`); a linha útil é a do primeiro
+      // caractere visível.
+      const offset = node.text.search(/\S/);
+      if (offset >= 0) text(node.text, node, node.pos + offset);
+      return;
+    }
+    if (ts.isJsxExpression(node)) {
+      if (node.expression !== undefined) expression(node.expression);
+      return;
+    }
+    if (ts.isJsxFragment(node)) {
+      for (const nested of node.children) child(nested);
+      return;
+    }
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) element(node);
+  };
+  for (const node of split.children) child(node);
+  return invalid;
+}
+
 function directImportedJsxChildren(node, imports) {
   if (!ts.isJsxElement(node)) return [];
   return node.children.flatMap((child) => {
@@ -1144,10 +1316,25 @@ export function checkUiStructure(file, text) {
       message,
     });
 
+  const localComponents = localComponentNames(sourceFile);
+
   const visit = (node) => {
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
       const local = jsxLocalName(node);
       const component = local === null ? null : imports.get(local);
+      if (component === "Split" && ts.isJsxElement(node)) {
+        for (const child of invalidSplitChildren(node, imports, localComponents)) {
+          findings.push({
+            rule: "ui-structure-split",
+            level: "error",
+            action: "Split",
+            line:
+              sourceFile.getLineAndCharacterOfPosition(child.position).line + 1,
+            file,
+            message: `Split distribui somente <Pane> como filho, e ${child.label} ficaria fora do layout: o Split interrompe a renderização com erro. Envolva o conteúdo em um <Pane>; se ele vem de um componente que devolve um <Pane>, escreva o <Pane> dentro do Split e passe o componente como filho dele.`,
+          });
+        }
+      }
       const removedComponent =
         component === null ? undefined : UI_REMOVED_COMPONENTS.get(component);
       if (component !== null && removedComponent !== undefined) {
@@ -1639,6 +1826,9 @@ export function checkUiMigrations(file, text) {
   return findings.sort((left, right) => left.line - right.line);
 }
 
+// Dependências, builds, testes e fixtures ficam fora de todo walk. Uma action declarada num
+// teste ou fixture nunca é registrada no runtime: cobrar `export const`, ordem de campos ou
+// padrões de UI ali só gera falso positivo e esconde o que o app realmente expõe.
 const SKIP_DIRS = new Set([
   "node_modules",
   "dist",
@@ -1646,15 +1836,13 @@ const SKIP_DIRS = new Set([
   ".git",
   ".next",
   "coverage",
-]);
-const UI_SKIP_DIRS = new Set([
-  ...SKIP_DIRS,
   "__tests__",
   "__fixtures__",
   "fixtures",
   "test",
   "tests",
 ]);
+const TEST_FILE = /\.(?:test|spec)\.[^.]+$/;
 const UI_EXTENSIONS = new Set([
   ".ts",
   ".tsx",
@@ -1690,7 +1878,7 @@ export async function walkTsFiles(dir, acc = []) {
       } else if (
         (e.name.endsWith(".ts") || e.name.endsWith(".tsx")) &&
         !e.name.endsWith(".d.ts") &&
-        !e.name.endsWith(".test.ts")
+        !TEST_FILE.test(e.name)
       ) {
         safeProjectPath(root, relative, { mustExist: true });
         acc.push(full);
@@ -1707,7 +1895,7 @@ async function walkUiFiles(dir, acc = []) {
     const entries = readProjectDirectory(root, local).entries;
     for (const e of entries) {
       if (e.name.startsWith(".")) continue;
-      if (UI_SKIP_DIRS.has(e.name)) continue;
+      if (SKIP_DIRS.has(e.name)) continue;
       const relative = path.join(local, e.name);
       const full = path.join(root, relative);
       if (e.isSymbolicLink()) {
@@ -1719,7 +1907,7 @@ async function walkUiFiles(dir, acc = []) {
         walk(relative);
       } else if (
         UI_EXTENSIONS.has(path.extname(e.name)) &&
-        !/\.(?:test|spec)\.[^.]+$/.test(e.name)
+        !TEST_FILE.test(e.name)
       ) {
         safeProjectPath(root, relative, { mustExist: true });
         acc.push(full);
@@ -1748,8 +1936,8 @@ export async function scanDir(rootDir) {
   }
   const checked = checkProject(sources);
   const uiFindings = [];
-  // UI pode morar em src/, app/, pages/ ou na raiz. O walk cobre o projeto inteiro e
-  // exclui dependências, builds, testes e fixtures para não interpretar exemplos como uso.
+  // UI pode morar em src/, app/, pages/ ou na raiz. O walk cobre o projeto inteiro e, como o
+  // das actions, exclui dependências, builds, testes e fixtures (SKIP_DIRS, TEST_FILE).
   for (const file of await walkUiFiles(rootDir)) {
     const text = readProjectFile(rootDir, path.relative(rootDir, file)).content;
     uiFindings.push(...checkUiMigrations(path.relative(rootDir, file), text));