@softize/opus 22.2.0 → 24.0.0

package/CHANGELOG.md

@@ -7,6 +7,125 @@ 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.
 
+## 24.0.0 — 2026-10-01
+
+`ToggleGroup` passa a compartilhar a gramática estrutural de `ButtonGroup`: `mode` aceita
+`connected`, `spaced`, `divided` e o novo `segmented`; `distribution` aceita `content` e `equal`;
+`orientation`, `shape` e `framed` permanecem eixos independentes. A aparência segmentada mantém
+escolhas curtas numa superfície compartilhada e destaca o controle ativo dentro dela. Filtros
+`select` com `presentation: "toggle"` passam a usar esse modo; estado, URL, defaults e input da
+action não mudam.
+
+O tema passa a distinguir canvas, superfícies elevadas, controles e estados neutros com tokens
+opacos por papel. No tema claro, o canvas quase branco sustenta cards e popovers brancos; inputs,
+hover, seleção e pressão deixam de depender de alpha sobre a superfície ancestral. Os componentes
+usam os mesmos papéis nos dois temas, enquanto cada tema calibra somente os valores.
+
+A escala neutra passa a ser derivada de quatro eixos de aparência por modo — intensidade de cor,
+contraste, brilho das superfícies e contraste entre camadas —, cada um de 0 a 100, lidos de
+`--appearance-light-*` e `--appearance-dark-*` (ADR 0044). Com os eixos no preset, o tema é
+exatamente o calibrado; quem não personaliza não precisa mudar nada. Os limites impedem que um
+ajuste reduza a separação entre os papéis ou o contraste do texto sobre as superfícies em repouso
+abaixo do preset, e a intensidade tinge somente os neutros, no matiz de `--neutral-hue`. O novo
+módulo sem React `@softize/opus/ui/appearance`, também reexportado por `@softize/opus/ui` e
+`@softize/opus/ui/react`, publica tipos, presets e o helper que converte overrides parciais em
+custom properties. Reset é a remoção dos overrides pela aplicação; o Opus não publica componente
+de ajuste nem guarda a preferência. Um app que redeclara diretamente um token neutro continua
+funcionando, mas esse token deixa de acompanhar os eixos.
+
+No preset, seleção persistente também se afasta mais do hover transitório nos dois temas. Navegação
+ativa permanece reconhecível mesmo sem depender de texto em negrito, enquanto pressão conserva um
+degrau próprio além da seleção.
+
+`ToggleGroup mode="segmented"` usa `bg-card` no item ativo, e `Tabs framed` aproxima a linha dos
+triggers com inset próprio. `PageHeader`, `DialogHeader` e `DrawerHeader` aceitam navegação e ações
+sem título; `SurfaceHeader` aceita ações sem título. O título pode permanecer no conteúdo de modais
+por meio das novas `DialogIntro` e `DrawerIntro`. `DetailGroup` ganha `elevation` e passa a usar
+`raised` por padrão, inclusive em `plain`; declare `elevation="none"` quando o agrupamento tiver de
+permanecer no mesmo plano do pai.
+
+### Breaking
+
+`ToggleGroupItem` foi removido. Use `Toggle` como filho de `ToggleGroup` e informe `value`; fora do
+grupo, `Toggle` continua usando `pressed`, `defaultPressed` e `onPressedChange`. `spacing` também foi
+removido: use `mode="connected"` no lugar de zero e `mode="spaced"` no lugar de valores positivos.
+Não há aliases de compatibilidade porque o único consumidor é migrado atomicamente.
+
+`Content*` e `Card*` foram removidos da API pública. Use `Surface` e seus slots
+`SurfaceHeader`, `SurfaceMedia`, `SurfaceTitle`, `SurfaceDescription`, `SurfaceMeta`,
+`SurfaceActions`, `SurfaceBody` e `SurfaceFooter`. A raiz agora é `div` por padrão; declare
+`as="section"`, `as="article"` ou `as="fieldset"` quando o documento exigir essa semântica.
+`framed` acrescenta borda, `elevation="raised"` acrescenta o fundo elevado e
+`layout="sectioned"` cria as faixas com divisores. `frameVariant` não existe mais.
+
+`SurfaceMedia` reserva posição e não cria `IconTile`: componha o tile explicitamente quando o
+ícone precisar de moldura. O recuo estrutural de superfícies limitadas passa de `1.25rem` para
+`1rem`, títulos internos usam `text-sm` e conteúdos que já controlam o próprio recuo declaram
+`flush` em `SurfaceBody`. Essas mudanças são intencionais e não têm aliases de compatibilidade.
+
+`DialogMedia` e `DrawerMedia` seguem o mesmo contrato sem decoração de
+`SurfaceMedia`. As propriedades `size`, `context`, `variant` e `asChild` foram removidas desses
+slots: passe o glifo, a imagem ou a marca diretamente; quando precisar de moldura, componha
+`IconTile` com essas propriedades. `Dialog mode="alert"` também deixa de aumentar ou emoldurar a
+mídia automaticamente.
+
+Bodies estruturais passam a governar o ritmo entre seus filhos diretos com intervalo de `1.5rem`.
+O layout do pai decide o inset; no seccionado, Surface, Dialog e Drawer usam `1rem` lateral e
+`1.5rem` vertical. `DialogBody` e `DrawerBody` ganham `flush`, como `SurfaceBody`.
+Migração: remova `space-*`, `gap-*` e padding de `className` no body; use um wrapper para relações
+internas e `flush` somente quando o filho controlar o próprio inset. `opus check` cobra a regra.
+
+`Pane` passa a ser somente a unidade de dimensionamento de `Split`. As propriedades `inset` e
+`layout`, além de `PaneHeader`, `PaneBody`, `PaneContent`, `PaneFooter`, `PaneMedia`, `PaneTitle`,
+`PaneDescription` e `PaneActions`, foram removidas sem aliases. Migração: componha uma `Surface`
+dentro do pane quando precisar de anatomia visual; para navegação ou conteúdo especializado, deixe
+o próprio filho declarar organização e rolagem.
+
+### Novidades
+
+`DialogIntro` e `DrawerIntro` formalizam o título do conteúdo quando o header do modal é reservado
+a navegação, ações globais e fechamento. Cada intro exige o título da família e aceita
+`DialogIntroActions` ou `DrawerIntroActions`; no formato compacto, título e ações continuam no
+header. O body permanece dono do ritmo e da rolagem (ADR 0048).
+
+## 23.0.0 — 2026-09-29
+
+Esta major conclui a separação entre contrato e dados de design, simplifica a hierarquia de
+`Content` e dá a Tabs uma anatomia pública única para navegação. A seção **Breaking** reúne as
+migrações obrigatórias.
+
+### Breaking
+
+`mockHandler` foi removido de `ActionBase`, contratos, actions de lista, runtime e `runAction`,
+concluindo a ADR 0037. O core não lê mais `OPUS_MODE`: o plugin `opusDesign()` liga cenários ou
+respostas geradas como handlers antes de registrar as actions no runtime. Migração: remova cada
+`mockHandler`; quando a resposta específica importar para o design, transforme-a em cenário com
+`defineDesignScenario`. Testes devem passar a action produzida por `bindAction` ao `runAction`.
+
+Filtros `select` de escolha única aceitam `presentation: "toggle"` para manter opções curtas e
+mutuamente exclusivas visíveis em um grupo conectado. A apresentação padrão continua sendo
+`Select`; estado, URL, defaults e input da action não mudam. Opções vindas de dicionário também
+apresentam o ícone declarado na entrada, sempre acompanhado pelo rótulo.
+
+`TabsList` passa a usar somente a linha de navegação e deixa de aceitar `variant`. Migração: remova
+`variant="line"`; usos da antiga superfície preenchida devem representar escolha de valor com
+`ToggleGroup`, usando `variant="outline"` quando precisarem de borda.
+
+A anatomia pública de Tabs passa a nomear estrutura, não o mecanismo da primitiva:
+`TabsTrigger` vira `TabsListItem` e `TabsContent` vira `TabsPanel`. A mudança não mantém aliases;
+consumidores devem atualizar imports e JSX no mesmo upgrade.
+
+`Content` deixa de aceitar `variant="page" | "section"`. `level={1}` identifica o conteúdo
+principal, aplica automaticamente a escala de `PageHeader` e usa o mesmo intervalo de `1.5rem`
+entre header e body; níveis de 2 a 6 preservam a apresentação compacta de seção. Migração: remova
+`variant="page"` e mantenha `level={1}`. Não existe substituição para `variant="section"`, que era
+o comportamento dos níveis internos.
+
+### Filtros e controles
+
+`Toggle` e `ToggleGroupItem` em `variant="outline"` preservam a borda no estado ativo e usam um
+fundo sutil distinto dela, inclusive no tema escuro.
+
 ## 22.2.0 — 2026-09-29
 
 As actions passam a declarar o que fazem com os dados (ADR 0041). Dois campos novos no contrato,
@@ -381,7 +500,7 @@ página (ADR 0024). A `Presentation` de lista em `layout="fill"` passa a entrega
 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
+funcionando. Com um contêiner próprio entre `ContentBody` e a lista, como um `TabsPanel`, 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

package/bin/cli.mjs

@@ -40,16 +40,8 @@ async function cmdCheck(dir) {
     for (const error of materialization.errors) log('error', `✗ opus check: ${error}`)
     process.exit(1)
   }
-  const { files, actions, contracts, deprecatedMockHandlers, missingEffect, missingPersonalData, findings, hasMarker } =
+  const { files, actions, contracts, missingEffect, missingPersonalData, findings, hasMarker } =
     await scanDir(root)
-  // Aviso de migração, não violação: uma linha só, para não poluir o gate a cada execução.
-  if (deprecatedMockHandlers > 0) {
-    log(
-      'warn',
-      `⚠ opus check: ${deprecatedMockHandlers} action(s) ainda declaram \`mockHandler\`, que sai na próxima major. ` +
-        'No modo design, a action sem mock já responde com dado gerado; use `defineDesignScenario` quando o design precisar de um cenário (ADR 0037).',
-    )
-  }
 
   if (missingEffect > 0 || missingPersonalData > 0) {
     log(
@@ -441,6 +433,8 @@ Regras da UI (@softize/opus/ui):
   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-structure-body-rhythm — padding, gap ou space aplicado diretamente a um Body;
+                             use o ritmo nativo, flush ou um wrapper filho
   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

@@ -58,7 +58,6 @@ const FIELD_GROUP = {
   authorize: 3,
   loads: 3,
   handler: 4,
-  mockHandler: 4,
   audit: 5,
   confirm: 5,
   invalidates: 5,
@@ -129,40 +128,34 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader"])],
-  ["ContentHeader", new Set(["Content"])],
-  ["ContentBody", new Set(["Content"])],
-  ["ContentTitle", new Set(["ContentHeader"])],
-  ["ContentDescription", new Set(["ContentHeader"])],
-  ["ContentMeta", new Set(["ContentHeader"])],
-  ["ContentActions", new Set(["ContentHeader"])],
-  ["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"])],
+  // As regiões de Surface não são estritas: com `asChild`, elas ficam dentro do elemento que
+  // recebe a superfície (ADR 0045). Os slots do header são filhos diretos dele.
+  ["SurfaceHeader", new Set(["Surface"])],
+  ["SurfaceBody", new Set(["Surface"])],
+  ["SurfaceFooter", new Set(["Surface"])],
+  ["SurfaceMedia", new Set(["SurfaceHeader"])],
+  ["SurfaceTitle", new Set(["SurfaceHeader"])],
+  ["SurfaceDescription", new Set(["SurfaceHeader"])],
+  ["SurfaceMeta", new Set(["SurfaceHeader"])],
+  ["SurfaceActions", new Set(["SurfaceHeader"])],
   ["DialogHeader", new Set(["DialogContent"])],
   ["DialogBody", new Set(["DialogContent"])],
   ["DialogFooter", new Set(["DialogContent"])],
+  ["DialogIntro", new Set(["DialogBody"])],
+  ["DialogIntroActions", new Set(["DialogIntro"])],
   ["DialogNavigation", new Set(["DialogHeader"])],
   ["DialogMedia", new Set(["DialogHeader"])],
-  ["DialogTitle", new Set(["DialogHeader"])],
+  ["DialogTitle", new Set(["DialogHeader", "DialogIntro"])],
   ["DialogActions", new Set(["DialogHeader"])],
   ["DrawerHeader", new Set(["DrawerContent"])],
   ["DrawerBody", new Set(["DrawerContent"])],
   ["DrawerFooter", new Set(["DrawerContent"])],
+  ["DrawerIntro", new Set(["DrawerBody"])],
+  ["DrawerIntroActions", new Set(["DrawerIntro"])],
   ["DrawerNavigation", new Set(["DrawerHeader"])],
   ["DrawerMedia", new Set(["DrawerHeader"])],
-  ["DrawerTitle", new Set(["DrawerHeader"])],
+  ["DrawerTitle", new Set(["DrawerHeader", "DrawerIntro"])],
   ["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"])],
@@ -206,12 +199,15 @@ const UI_STRUCTURAL_ROOTS = new Map([
     },
   ],
   [
-    "Content",
+    "Surface",
     {
-      header: "ContentHeader",
-      body: "ContentBody",
-      shorthand: new Set(["title", "description", "count", "actions"]),
-      removed: new Map([["meta", "use `count`"]]),
+      header: "SurfaceHeader",
+      body: "SurfaceBody",
+      footer: "SurfaceFooter",
+      // Cada região é opcional, a forma curta convive com SurfaceBody e SurfaceFooter, e sem
+      // região nenhuma a Surface é uma caixa de filhos livres (ADR 0045).
+      flexible: true,
+      shorthand: new Set(["title", "media", "description", "count", "actions"]),
     },
   ],
 ]);
@@ -224,18 +220,61 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageBack",
   "PageNavigation",
   "PageActions",
-  "ContentHeader",
-  "ContentBody",
-  "ContentTitle",
-  "ContentDescription",
-  "ContentMeta",
-  "ContentActions",
+  "SurfaceMedia",
+  "SurfaceTitle",
+  "SurfaceDescription",
+  "SurfaceMeta",
+  "SurfaceActions",
   "AlertMedia",
   "AlertHeader",
   "AlertActions",
 ]);
 
+// O body público é a única fonte de inset e ritmo estrutural (ADR 0046). Classes de
+// ocupação, overflow, alinhamento e tipografia continuam livres; relações locais usam
+// um wrapper filho e full bleed usa a prop `flush` das famílias que a oferecem.
+const UI_STRUCTURAL_BODIES = new Set([
+  "SurfaceBody",
+  "DialogBody",
+  "DrawerBody",
+  "PageBody",
+]);
+
+const UI_BODY_RHYTHM_CLASS =
+  /(?:^|:)(?:!?-?)(?:space-[xy]|gap(?:-[xy])?|p|px|py|pt|pr|pb|pl|ps|pe)-/;
+
+const UI_FLUSH_BODIES = new Set(["SurfaceBody", "DialogBody", "DrawerBody"]);
+
 const UI_REMOVED_PROPS = new Map([
+  [
+    "Pane",
+    new Map([
+      ["inset", "mova o recuo para o conteúdo ou para uma `Surface` filha"],
+      ["layout", "use `Surface` para anatomia visual contínua ou seccionada"],
+    ]),
+  ],
+  [
+    "Surface",
+    new Map([["meta", "use `count` para o total ao lado do título"]]),
+  ],
+  [
+    "DialogMedia",
+    new Map([
+      ["size", "dimensione o nó filho"],
+      ["context", "declare o contexto no `IconTile` filho"],
+      ["variant", "declare a variante no `IconTile` filho"],
+      ["asChild", "passe o nó diretamente como filho"],
+    ]),
+  ],
+  [
+    "DrawerMedia",
+    new Map([
+      ["size", "dimensione o nó filho"],
+      ["context", "declare o contexto no `IconTile` filho"],
+      ["variant", "declare a variante no `IconTile` filho"],
+      ["asChild", "passe o nó diretamente como filho"],
+    ]),
+  ],
   [
     "PageHeader",
     new Map([
@@ -263,6 +302,14 @@ const UI_REMOVED_PROPS = new Map([
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
+  ["PaneHeader", "use `SurfaceHeader` dentro de uma `Surface`"],
+  ["PaneBody", "use `SurfaceBody` ou um contêiner próprio do conteúdo"],
+  ["PaneContent", "use `SurfaceBody` ou um contêiner próprio do conteúdo"],
+  ["PaneFooter", "use `SurfaceFooter` dentro de uma `Surface`"],
+  ["PaneMedia", "use `SurfaceMedia` dentro de `SurfaceHeader`"],
+  ["PaneTitle", "use `SurfaceTitle` dentro de `SurfaceHeader`"],
+  ["PaneDescription", "use `SurfaceDescription` dentro de `SurfaceHeader`"],
+  ["PaneActions", "use `SurfaceActions` dentro de `SurfaceHeader`"],
   ["PageIntro", "use `PageHeader` como a única introdução estrutural"],
   ["PageDescription", "mova contexto relevante para o início de `PageBody`"],
   [
@@ -273,11 +320,54 @@ const UI_REMOVED_COMPONENTS = new Map([
     "DrawerDescription",
     "mova contexto relevante para o início de `DrawerBody`",
   ],
+  // Content e Card deram lugar a Surface (ADR 0045).
+  [
+    "Content",
+    'use `Surface as="section"`, ou `as="fieldset"` para um grupo de campos',
+  ],
+  ["ContentHeader", "use `SurfaceHeader`"],
+  [
+    "ContentMedia",
+    "use `SurfaceMedia` e componha `IconTile` quando quiser a moldura",
+  ],
+  ["ContentTitle", "use `SurfaceTitle`"],
+  ["ContentDescription", "use `SurfaceDescription`"],
+  ["ContentMeta", "use `SurfaceMeta`"],
+  ["ContentActions", "use `SurfaceActions`"],
+  ["ContentBody", "use `SurfaceBody`"],
+  ["Card", 'use `Surface framed elevation="raised"`'],
+  ["CardHeader", "use `SurfaceHeader`"],
+  [
+    "CardMedia",
+    "use `SurfaceMedia` e componha `IconTile` quando quiser a moldura",
+  ],
+  ["CardTitle", "use `SurfaceTitle` e declare `level` em `Surface`"],
+  ["CardDescription", "use `SurfaceDescription`"],
+  ["CardAction", "use `SurfaceActions`"],
+  ["CardBody", "use `SurfaceBody`"],
+  ["CardContent", "use `SurfaceBody`"],
+  ["CardFooter", "use `SurfaceFooter`"],
 ]);
 
 const UI_STRUCTURAL_CONTAINERS = new Set(["PageShell"]);
 
 const UI_STRUCTURAL_HEADERS = new Map([
+  [
+    "DialogIntro",
+    {
+      title: "DialogTitle",
+      optional: new Set(["DialogIntroActions"]),
+      shorthand: new Set(),
+    },
+  ],
+  [
+    "DrawerIntro",
+    {
+      title: "DrawerTitle",
+      optional: new Set(["DrawerIntroActions"]),
+      shorthand: new Set(),
+    },
+  ],
   [
     "PageHeader",
     {
@@ -289,15 +379,19 @@ const UI_STRUCTURAL_HEADERS = new Map([
     },
   ],
   [
-    "ContentHeader",
+    "SurfaceHeader",
     {
-      title: "ContentTitle",
+      title: "SurfaceTitle",
       optional: new Set([
-        "ContentDescription",
-        "ContentMeta",
-        "ContentActions",
+        "SurfaceMedia",
+        "SurfaceDescription",
+        "SurfaceMeta",
+        "SurfaceActions",
       ]),
-      shorthand: new Set(["title", "description", "meta", "actions"]),
+      shorthand: new Set(),
+      // Slots condicionais (`{cond && <SurfaceActions />}`) são composição legítima; o runtime
+      // valida o que de fato foi renderizado.
+      allowOpaque: true,
     },
   ],
   [
@@ -651,8 +745,6 @@ export function checkProject(sources) {
   const productDeclarations = [];
   const entityNames = new Set();
   const actionNames = new Set();
-  // `mockHandler` obsoleto (ADR 0037): contado, não reprovado — a minor ainda o aceita.
-  let deprecatedMockHandlers = 0;
   // Natureza da action (ADR 0041): declarações ausentes são contadas, não reprovadas, na minor.
   let missingEffect = 0;
   let missingPersonalData = 0;
@@ -680,7 +772,6 @@ export function checkProject(sources) {
         if (item.name !== null) actionNames.add(item.name);
       }
       for (const f of lintAction(item)) findings.push({ ...f, file });
-      if (item.keys.includes("mockHandler")) deprecatedMockHandlers += 1;
       if (item.form !== "bindAction") {
         const writesByGet = item.kind === "list" || item.kind === "view";
         if (!writesByGet && !item.keys.includes("effect")) missingEffect += 1;
@@ -791,7 +882,6 @@ export function checkProject(sources) {
     actions,
     contracts,
     dataProducts: productDeclarations.length,
-    deprecatedMockHandlers,
     missingEffect,
     missingPersonalData,
     findings,
@@ -1090,6 +1180,57 @@ function directStructuralChildren(node, imports) {
   return { names, hasOpaque };
 }
 
+function countImportedJsxDescendants(node, imports, component) {
+  const boundary =
+    component === "DialogTitle"
+      ? "DialogContent"
+      : component === "DrawerTitle"
+        ? "DrawerContent"
+        : undefined;
+  const count = (child, root = false) => {
+    if (
+      !root &&
+      (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child))
+    ) {
+      const local = jsxLocalName(child);
+      const imported = local === null ? undefined : imports.get(local);
+      if (imported === boundary) return 0;
+      if (imported === component) return 1;
+    }
+    if (ts.isConditionalExpression(child)) {
+      return (
+        count(child.condition) +
+        Math.max(count(child.whenTrue), count(child.whenFalse))
+      );
+    }
+    let total = 0;
+    ts.forEachChild(child, (descendant) => {
+      total += count(descendant);
+    });
+    return total;
+  };
+  return count(node, true);
+}
+
+/**
+ * Diz se o JSX literal prova um filho livre ao lado das regiões: texto, elemento HTML ou outro
+ * componente do Opus. Expressões e componentes de outros módulos ficam de fora, porque só o
+ * runtime sabe o que eles renderizam.
+ */
+function hasLiteralFreeChild(node, imports, regionNames) {
+  if (!ts.isJsxElement(node)) return false;
+  return node.children.some((child) => {
+    if (ts.isJsxText(child)) return child.text.trim() !== "";
+    if (!ts.isJsxElement(child) && !ts.isJsxSelfClosingElement(child))
+      return false;
+    const local = jsxLocalName(child);
+    if (local === null) return false;
+    const imported = imports.get(local);
+    if (imported !== undefined) return !regionNames.includes(imported);
+    return /^[a-z]/.test(local);
+  });
+}
+
 /**
  * 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
@@ -1275,7 +1416,7 @@ function countPageHeadingSources(page, imports) {
         const local = jsxLocalName(node);
         if (
           local !== null &&
-          ((imports.get(local) === "Content" &&
+          ((imports.get(local) === "Surface" &&
             jsxNumericAttribute(node, "level") === 1) ||
             imports.get(local) === "PageState")
         ) {
@@ -1415,6 +1556,36 @@ export function checkUiStructure(file, text) {
         }
       }
 
+      if (component !== null && UI_STRUCTURAL_BODIES.has(component)) {
+        const overridden = jsxStringAttributeValues(
+          jsxOpening(node),
+          "className",
+        )
+          .flatMap((value) => value.trim().split(/\s+/))
+          .filter((token) => UI_BODY_RHYTHM_CLASS.test(token));
+        if (overridden.length > 0) {
+          add(
+            node,
+            component,
+            `${component} já governa inset e ritmo: remova ${[...new Set(overridden)].map((token) => `\`${token}\``).join(", ")}; ${UI_FLUSH_BODIES.has(component) ? "use `flush` para full bleed ou " : "use "}um wrapper filho para relações internas.`,
+            "ui-structure-body-rhythm",
+          );
+        }
+      }
+
+      if (component === "DialogContent" || component === "DrawerContent") {
+        const title =
+          component === "DialogContent" ? "DialogTitle" : "DrawerTitle";
+        if (countImportedJsxDescendants(node, imports, title) > 1) {
+          add(
+            node,
+            component,
+            `${component} aceita um único ${title}: mantenha o título no header ou na intro, nunca nos dois.`,
+            "ui-structure-duplicate-title",
+          );
+        }
+      }
+
       const header =
         component === null ? undefined : UI_STRUCTURAL_HEADERS.get(component);
       if (header !== undefined) {
@@ -1519,7 +1690,30 @@ export function checkUiStructure(file, text) {
         // some aqui.
         // Com filhos estruturais, o que as regras de forma acham é defeito independente: misturar
         // shorthand com slots, ou um filho inesperado, não some quando a prop sai.
-        if (removedProp && !structural) {
+        if (root.flexible) {
+          const regionNames = [root.header, root.body, root.footer];
+          const regions = children.names.filter((name) =>
+            regionNames.includes(name),
+          );
+          if (shorthand && regions.includes(root.header)) {
+            add(
+              node,
+              component,
+              `${component} não permite misturar a forma curta com ${root.header} explícito.`,
+              "ui-structure-mode",
+            );
+          } else if (
+            regions.length > 0 &&
+            (new Set(regions).size !== regions.length ||
+              hasLiteralFreeChild(node, imports, regionNames))
+          ) {
+            add(
+              node,
+              component,
+              `${component} com slots estruturais aceita no máximo um ${root.header}, um ${root.body} e um ${root.footer} como filhos diretos e não os mistura com filhos livres: envolva o conteúdo em ${root.body}.`,
+            );
+          }
+        } else if (removedProp && !structural) {
           // Nada a acrescentar; os filhos seguem sendo visitados no fim de `visit`.
         } else if (shorthand && structural) {
           add(
@@ -1578,7 +1772,7 @@ export function checkUiStructure(file, text) {
               add(
                 node,
                 component,
-                "Page explícito exige exatamente um heading principal em PageHeader, Content level={1} ou PageState dentro de PageBody.",
+                "Page explícito exige exatamente um heading principal em PageHeader, Surface level={1} ou PageState dentro de PageBody.",
               );
             }
           }
@@ -1944,7 +2138,7 @@ async function walkUiFiles(dir, acc = []) {
   return acc;
 }
 
-/** Escaneia um diretório → { files, actions, contracts, deprecatedMockHandlers, findings, hasMarker }.
+/** Escaneia um diretório → { files, actions, contracts, findings, hasMarker }.
  *  `hasMarker` = o diretório é um projeto opus (tem opus.json na raiz). */
 export async function scanDir(rootDir) {
   rootDir = canonicalProjectDirectory(rootDir);
@@ -1974,7 +2168,6 @@ export async function scanDir(rootDir) {
     actions: checked.actions,
     contracts: checked.contracts,
     dataProducts: checked.dataProducts,
-    deprecatedMockHandlers: checked.deprecatedMockHandlers,
     missingEffect: checked.missingEffect,
     missingPersonalData: checked.missingPersonalData,
     findings: [...checked.findings, ...uiFindings],