@softize/opus 19.0.0 → 20.1.0

package/CHANGELOG.md

@@ -7,6 +7,245 @@ 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.1.0 — 2026-09-26
+
+`Content` ganha um slot de mídia e passa a aceitar a moldura integrada ao header também em regiões
+de leitura. Quem não usa as novas props mantém a mesma aparência: `frameVariant="default"` continua
+sendo o padrão, com a borda contínua em `section` e em `fieldset`. Alguns pontos podem pedir ajuste
+sem interromper a aplicação:
+
+- a `legend` de todo `Content as="fieldset"` passa a envolver o título nos wrappers do header
+  (`legend > span[data-slot=content-heading] > …`): um seletor como
+  `legend > [data-slot=content-title]` deixa de casar; use `legend [data-slot=content-title]`;
+- um `ContentHeader` de fieldset com slot inválido lança outra mensagem: “ContentHeader de fieldset
+  aceita somente ContentMedia e ContentTitle; contador, descrição e ações ficam fora da legenda.”
+  Atualize testes que conferem o texto;
+- com `frameVariant="legend"` dentro de uma superfície com fundo próprio, como um `Card` com `bg-*`
+  ou um `Popover`, declare `--surface-background` com esse fundo na superfície (veja **Cor da
+  superfície**);
+- em `advancedFilters.sectionIcons`, um glifo solto ganha a moldura padrão, e testes que buscavam
+  `[data-slot="content-title-icon"]` devem buscar `[data-slot="content-media"]`.
+
+Em detalhe:
+
+- **Mídia no header.** `ContentHeader` aceita `ContentMedia`, e a forma curta de `Content` ganha
+  `media`. O slot já é a moldura de `IconTile`, com a mesma escala e posição em `section` e em
+  `fieldset`: passe só o glifo e escolha `size`, `context` e `variant` no slot. Se você colocava um
+  `IconTile` dentro de `title`, mova-o para `media`; o slot o adota e herda o que ele declara, sem
+  desenhar moldura dentro de moldura. `media` com `null` ou `false` não desenha nada. Em `fieldset`,
+  a mídia é decorativa e não entra no nome do grupo.
+- **Moldura integrada em `section`.** `frameVariant="legend"` deixa de exigir `as="fieldset"`. Em
+  uma `section`, o título continua sendo um heading no nível declarado, e contador, descrição e
+  ações continuam disponíveis; nenhuma `legend` é emitida. Use `as="fieldset"` só para grupos de
+  campos: a `legend` aceita a mídia e o título, e contador, descrição e ações continuam fora dela
+  (ADR 0025).
+- **Cor da superfície.** Para interromper a borda, o header pinta o título e as ações com a
+  variável `--surface-background`. `Card`, `Dialog` e `Drawer` a declaram com o fundo que pintam,
+  então a linha não reaparece atrás do título quando há um `CardBody`, um `DrawerBody` ou outro
+  wrapper transparente no caminho. Fora delas, vale `--background`.
+- **Filtros avançados.** Os ícones de `advancedFilters.sectionIcons` passam a ocupar o
+  `ContentMedia` de cada seção: um glifo solto ganha a moldura padrão, em vez do ícone esmaecido sem
+  moldura, e um `IconTile` é adotado pelo slot com o que declara. Um ícone `null` não desenha
+  moldura.
+
+A página de `Content` mostra a mídia, os dois acabamentos da moldura e a declaração de
+`--surface-background`. A ADR 0025 registra que o acabamento da moldura não altera a semântica; a
+ADR 0023 ganha a emenda do slot de mídia de `Content`, e as ADRs 0020 e 0021, emendas que apontam
+para a 0025.
+
+## 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

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));

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/0020-icon-tiles-are-explicitly-composed.md

@@ -24,6 +24,14 @@ a mesma base visual porque essas variantes já prometem a moldura.
 `IconTile` é somente apresentação. Quando o ícone aciona algo, deve-se usar `Button` com tamanho
 de ícone e nome acessível.
 
+### Emenda de 2026-09-26 — slots de mídia das superfícies
+
+Os slots de mídia da anatomia de superfícies (ADR 0023), como `CardMedia` e `ContentMedia`, não são
+slots genéricos: assim como `ItemMedia variant="icon"`, eles já prometem a moldura, e o consumidor
+passa só o glifo. `ContentMedia` adota um `IconTile` recebido como filho em vez de desenhar uma
+moldura dentro da outra (ADR 0025). Slots genéricos, como `FieldLegend.icon`, continuam como esta
+ADR descreve.
+
 ## Consequências
 
 - A presença da moldura deixa de ser uma regra implícita da legenda.