@softize/opus 27.1.0 → 29.0.0

package/CHANGELOG.md

@@ -7,6 +7,119 @@ 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.
 
+## 29.0.0 — 2026-10-15
+
+O `CLAUDE.md` passa a importar o `AGENTS.md`, e as declarações de copy passam a ser ancoradas pelo
+conteúdo, não pela linha. A seção **Breaking** traz a única migração obrigatória, que atinge só quem
+mantém instruções no `CLAUDE.md` que não estão no `AGENTS.md`.
+
+### Breaking
+
+`opus setup` mantém o bloco do Opus só no `AGENTS.md` e grava o `CLAUDE.md` como a linha
+`@AGENTS.md`, que importa as instruções para o Claude Code (ADR 0061, no mesmo formato da ADR 0006 da
+Base). Na conversão, o `setup` remove do `CLAUDE.md` o bloco do Opus e descarta o texto do projeto
+que repete o do `AGENTS.md`. Texto que só existe no `CLAUDE.md` é preservado, e o `setup` e o
+`opus pre-push materialization` reprovam até que ele vá para o `AGENTS.md`. Blocos de outros
+pacotes ficam depois do import até que o pacote dono os remova: com uma Base anterior à ADR 0006, o
+`CLAUDE.md` fica com o import e o bloco da Base.
+
+Migre movendo para o `AGENTS.md` as instruções que estão só no `CLAUDE.md` e rodando `opus setup`.
+
+### Âncora de copy pelo conteúdo
+
+- **`copy.dynamic` por trecho.** A declaração seleciona o diagnóstico por `source`, `field` e
+  `expression`, o trecho de código que o extrator não resolveu, e continua válida quando linhas
+  entram ou saem acima dela. Espaços e quebras de linha do trecho são normalizados e a vírgula
+  final antes de `)`, `]` ou `}` é ignorada, para a âncora sobreviver à reformatação. A declaração
+  vale para toda ocorrência do mesmo trecho no mesmo campo do arquivo, e `dynamicSurfaces` registra
+  as linhas atuais de cada uma. O diagnóstico de conteúdo traz o `field` e a `expression` prontos
+  para a declaração.
+- **`copy.exemptions` e `copy.transforms` por texto.** Sem `line`, `source`, `role` e `text`
+  selecionam toda ocorrência desse texto com esse papel no arquivo.
+- **Seletores por linha continuam aceitos.** Eles selecionam exatamente um alvo, são aplicados
+  antes dos seletores por conteúdo e geram um aviso no `opus copy`. `opus copy --reanchor` converte
+  o `base.json` agrupando as declarações por arquivo e campo, ou por arquivo, papel e texto. Um
+  grupo só é convertido quando tem uma declaração para cada alvo, para que a âncora por conteúdo não
+  cubra um alvo que ninguém declarou; dentro dele, declarações e alvos são pareados em ordem de
+  linha, e as que mudaram de linha são listadas para revisão. Declarações idênticas se fundem, e
+  duas com motivos diferentes para o mesmo conteúdo continuam por linha, já corrigida. Os seletores
+  gravados passam na extração do `opus copy`; a política da Base não é avaliada, então rode
+  `opus copy --check` e `base copy check` depois e revise o diff.
+- **`dynamicSurfaces` no inventário.** Uma declaração por conteúdo aparece com `expression` e
+  `lines`, as linhas atuais de cada ocorrência, no lugar de `line`. Uma lista `lines` que cresce no
+  diff indica que o trecho passou a cobrir uma ocorrência nova.
+- **Erros que dizem onde.** Cada seletor que deixa de encontrar seu alvo aparece na mesma execução,
+  com o arquivo, o campo, o trecho e os diagnósticos daquele campo ainda sem declaração, ou com o
+  aviso de que o arquivo não existe mais no escopo.
+
+### Instruções, documentação e changelog
+
+- A instrução gerenciada do Opus passa a dizer que o inventário de copy guarda o hash de todo
+  arquivo JS/TS do escopo, inclusive scripts sem copy como `scripts/*.mjs`, e que alterar qualquer
+  um deles também exige `opus copy`.
+- Os exemplos da documentação usam identificadores, nomes de action, domínios, eventos e permissões
+  em inglês (`ledger.close`, `ledger:close`, `invoice.issued`); rótulos, mensagens e comentários
+  continuam em pt-BR. O padrão editorial e a lista de verificação da skill `maintain-opus-docs`
+  passam a exigir isso, e um teste do repositório reprova identificadores com palavra em português.
+- Entradas do changelog que já estão na `origin/main` do Opus não mudam mais: uma correção de
+  informação publicada entra como entrada nova. O pre-push e o `pnpm release` do repositório
+  reprovam a alteração.
+
+## 28.0.0 — 2026-10-13
+
+### Breaking
+
+Page passa a usar `surfaceLayout="sectioned"` por padrão; `continuous` remove os divisores.
+`className` de Page configura a moldura externa e o de PageBody, o viewport. Migre ajustes
+internos de largura e alinhamento para `contentClassName`, disponível nos dois.
+PageShell preserva rolagem de contingência para fallbacks; wrappers de rota devem propagar
+altura para manter o header da Page fixo. Presentation fora do shell mantém largura total.
+TabsPanel com `forceMount` preserva a montagem, mas oculta o painel inativo.
+
+
+A composição e a escala das superfícies mudam. Migre os consumidores conforme a ADR 0060 e remova os recuos locais substituídos pelo body.
+
+DrawerTitle e DialogTitle na intro acompanham a escala do PageTitle; o header compacto
+preserva seu título menor.
+
+Surface, Page, Dialog, Drawer e Tabs compartilham ritmo vertical de 1rem. Superfícies delimitadas
+fecham com padding inferior; corpos sem moldura ficam alinhados ao hospedeiro. Tabs framed
+fornece os recuos do painel. Remova overrides locais que reconstruíam esses espaçamentos.
+
+IconCatalogProvider permite catálogo assíncrono e renderização de assets sob demanda no IconPicker,
+com busca no índice completo, grade de oito colunas com scroll infinito e tentativa após erro.
+
+IconPicker apresenta uma grade sem nomes visíveis, com nomes acessíveis e busca por nomes e sinônimos
+em português. O scroll do popover não se propaga ao modal. `searchTerms` personaliza a busca
+sem modificar identificadores salvos. A paleta inclui Carro, pesquisável também por veículo e automóvel.
+
+Toggle `outline` volta a distinguir o preenchimento ativo da borda, com fundo semitransparente
+e preservação do formato conectado.
+
+ActionList oferece `viewControls` para controles específicos da visualização ativa,
+imediatamente após seu seletor. As configurações da lista aparecem antes dos seletores.
+
+### Escala dos controles e composição
+
+Corrigida a altura de `icon-sm`: 2rem, igual a `sm`, preservando o glifo de 0,875rem.
+PaginationLink respeita o tamanho textual declarado; números, setas e elipse do pager
+de ActionList usam 2rem. Remova compensações locais que fixavam esses controles em 1,75rem.
+
+Page, Dialog, Drawer e Surface delimitada compartilham header com padding de 1rem e
+linha mínima de 2rem. Ações de header usam `sm`/`icon-sm`, inclusive criação de coleções
+e comandos de Presentation. Rodapés mantêm a escala anterior. Consumidores devem remover
+compensações de altura/padding e declarar a escala compacta nos botões das barras.
+
+Presentation em página passa a delegar padding e rolagem ao PageBody, evitando conteúdo
+recortado e recuos duplicados. Ações de headers compactos sem navegação permanecem no
+extremo oposto ao título.
+
+Page oferece `PageIntro` e `PageIntroActions`, seguindo a separação entre controles da superfície
+e conteúdo já disponível em Dialog e Drawer. A forma curta passa a colocar título e orientação
+na intro, mantendo ações no header. Headers sem controles não reservam espaço. A forma explícita
+compacta continua válida. A mudança visual exige migração coordenada dos consumidores (ADR 0060).
+Page mantém header e footer fora da rolagem; o body rola em flow e repassa a altura à lista em fill.
+
 ## 27.1.0 — 2026-10-13
 
 Portais documentais podem oferecer navegação recolhível em telas estreitas com

package/bin/cli.mjs

@@ -15,7 +15,7 @@ import { cmdGen, helpGen } from './lib/gen.mjs'
 import { cmdDb } from './lib/db.mjs'
 import { scanDir, emptyScanVerdict } from './lib/check.mjs'
 import { log } from './lib/cli-shared.mjs'
-import { checkCopyInventory, writeCopyInventory } from './lib/copy.mjs'
+import { checkCopyInventory, reanchorCopySelectors, writeCopyInventory } from './lib/copy.mjs'
 import { createMonorepo, createProject } from './lib/create.mjs'
 import { initProject, repoRootOf, setupUiFoundation } from './lib/init.mjs'
 import { introspect } from './lib/introspect.mjs'
@@ -63,9 +63,9 @@ async function cmdCheck(dir) {
     log('error', `✗ opus check: nenhuma action encontrada em ${rel} (${files} arquivos .ts); ${verdict.message}`)
     process.exit(1)
   }
-  const viaContrato = contracts > 0 ? ` (${contracts} contrato(s))` : ''
+  const contractSuffix = contracts > 0 ? ` (${contracts} contrato(s))` : ''
   if (findings.length === 0) {
-    log('success', `✓ opus check: ${actions} action(s)${viaContrato}; nenhuma violação encontrada.`)
+    log('success', `✓ opus check: ${actions} action(s)${contractSuffix}; nenhuma violação encontrada.`)
     return
   }
 
@@ -97,10 +97,28 @@ async function cmdMaterializationCheck() {
 async function cmdCopy(dir, flags) {
   const selected = path.resolve(process.cwd(), dir ?? '.')
   const root = (await repoRootOf(selected)) ?? selected
+  if (flags.reanchor) {
+    if (flags.check) {
+      log('error', '✗ opus copy: --reanchor grava o base.json e não combina com --check.')
+      process.exitCode = 1
+      return
+    }
+    if (!reportReanchor(reanchorCopySelectors(root))) {
+      process.exitCode = 1
+      return
+    }
+  }
   const result = flags.check ? checkCopyInventory(root) : writeCopyInventory(root)
   for (const diagnostic of result.diagnostics) {
     log('error', `✗ opus copy: ${diagnostic.source}:${diagnostic.line} — ${diagnostic.message}`)
   }
+  if (result.legacySelectors > 0) {
+    log(
+      'warn',
+      `! opus copy: ${result.legacySelectors} seletor(es) em base.json ainda usam \`line\`, que quebra a cada edição acima dele; ` +
+        'rode `opus copy --reanchor` para ancorá-los pelo conteúdo.',
+    )
+  }
   if (!result.ok) {
     if (result.reason === 'missing') {
       log('error', `✗ opus copy: inventário ausente em ${path.relative(root, result.path)}; rode \`opus copy\` e versione o resultado.`)
@@ -121,6 +139,40 @@ async function cmdCopy(dir, flags) {
   else log('success', `✓ opus copy: ${location} já estava atualizado (${summary}).`)
 }
 
+function reportReanchor(result) {
+  if (!result.ok) {
+    for (const diagnostic of result.diagnostics) {
+      log('error', `✗ opus copy --reanchor: ${diagnostic.source}:${diagnostic.line} — ${diagnostic.message}`)
+    }
+    log('error', '✗ opus copy --reanchor: resolva os problemas de leitura acima antes de reancorar; base.json não foi alterado.')
+    return false
+  }
+  const { converted, realigned, relined, merged, unresolved } = result.report
+  const anchor = (item) => (item.anchor.expression === undefined ? `"${item.anchor.text}"` : `\`${item.anchor.expression}\``)
+  if (converted.length > 0) log('success', `✓ opus copy --reanchor: ${converted.length} seletor(es) passaram a ser ancorados pelo conteúdo.`)
+  // copy.dynamic identifica o alvo pelo campo; exceções e transformações, pelo papel do texto.
+  const target = (item) => (item.list === 'dynamic' ? `\`${item.selector.field}\`` : `(${item.selector.role})`)
+  if (realigned.length > 0) {
+    log('warn', `! opus copy --reanchor: ${realigned.length} âncora(s) quebradas pela mudança de linha foram convertidas; revise cada uma no diff:`)
+    for (const item of realigned) {
+      console.log(`    copy.${item.list}[${item.index}] ${item.selector.source} ${target(item)} linha ${item.from} → ${item.to}: ${anchor(item)}`)
+    }
+  }
+  if (relined.length > 0) {
+    log('warn', `! opus copy --reanchor: ${relined.length} seletor(es) continuam por linha, com a linha corrigida; revise cada um no diff:`)
+    for (const item of relined) {
+      console.log(`    copy.${item.list}[${item.index}] ${item.selector.source} linha ${item.from} → ${item.to}: ${item.reason}`)
+    }
+  }
+  if (merged.length > 0) log('success', `✓ opus copy --reanchor: ${merged.length} declaração(ões) repetida(s) fundida(s) com a idêntica.`)
+  if (unresolved.length > 0) {
+    log('warn', `! opus copy --reanchor: ${unresolved.length} seletor(es) continuam por linha:`)
+    for (const item of unresolved) console.log(`    copy.${item.list}[${item.index}]: ${item.reason}`)
+  }
+  if (!result.changed) log('success', '✓ opus copy --reanchor: nada a converter em base.json.')
+  return true
+}
+
 async function cmdCreate(dir, flags) {
   if (!dir) {
     log('error', 'Uso: opus create <dir> — o nome do diretório vira o nome do app (--monorepo: a raiz do workspace).')
@@ -273,6 +325,10 @@ function parseArgs(argv) {
       flags.json = true
       continue
     }
+    if (arg === '--reanchor') {
+      flags.reanchor = true
+      continue
+    }
     if (arg === '--monorepo') {
       flags.monorepo = true
       continue
@@ -334,6 +390,7 @@ Flags
   --help, -h         Ajuda do comando.
   --check            (copy) Compara sem escrever; falha se o inventário estiver ausente ou
                      desatualizado.
+  --reanchor         (copy) Ancora pelo conteúdo os seletores do base.json que usam linha.
   --json             (introspect, seed) Saída estruturada em JSON.
   --monorepo         (create) Cria a raiz do workspace em vez de um app.
   --config <path>    (gen, db, seed) Caminho do opus.config.ts. Default: ./opus.config.ts.
@@ -483,6 +540,14 @@ comprova que o extrator executou sobre uma fonte.
 
 Flags:
   --check          Compara sem escrever; falha em ausência, drift ou copy dinâmica
+                   sem declaração.
+  --reanchor       Converte os seletores de copy.dynamic, copy.exemptions e
+                   copy.transforms que ainda usam \`line\` para seletores pelo
+                   conteúdo, grava o base.json e regenera o inventário. Só
+                   converte quando há uma declaração para cada alvo, para não
+                   ampliar nenhuma; as que mudaram de linha são listadas para
+                   revisão, e o que não dá para converter com segurança fica
+                   como está. Depois, rode base copy check e revise o diff.
 `)
       return
     }

package/bin/lib/check.mjs

@@ -93,7 +93,11 @@ const KINDS = new Set(["simple", "form", "list", "view"]);
 const ASSISTANT_RESOURCE_RE = /^[a-z][a-zA-Z0-9]*$/;
 const ASSISTANT_SKILL_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const ASSISTANT_CONTEXT_MIN = 1000;
-const ASSISTANT_RESERVED_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+const ASSISTANT_RESERVED_SEGMENTS = new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+]);
 const ASSISTANT_CONTEXT_MAX = 16000;
 const ASSISTANT_REQUIRED = {
   label: "`label`, o nome do assistente para pessoas",
@@ -150,9 +154,11 @@ const UI_SURFACE_PAIRS = new Map([
 const UI_STRUCTURAL_PARENTS = new Map([
   ["PageHeader", new Set(["Page"])],
   ["PageBody", new Set(["Page"])],
+  ["PageIntro", new Set(["PageBody"])],
+  ["PageIntroActions", new Set(["PageIntro"])],
   ["PageFooter", new Set(["Page"])],
-  ["PageTitle", new Set(["PageHeader"])],
-  ["PageDescription", new Set(["PageHeader"])],
+  ["PageTitle", new Set(["PageHeader", "PageIntro"])],
+  ["PageDescription", new Set(["PageHeader", "PageIntro"])],
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader"])],
@@ -311,7 +317,6 @@ const UI_REMOVED_PROPS = new Map([
       ["variant", "o cabeçalho da página tem uma única apresentação rolável"],
     ]),
   ],
-
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
@@ -323,7 +328,6 @@ const UI_REMOVED_COMPONENTS = new Map([
   ["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"],
   // Content e Card deram lugar a Surface (ADR 0045).
   [
     "Content",
@@ -356,6 +360,14 @@ const UI_REMOVED_COMPONENTS = new Map([
 const UI_STRUCTURAL_CONTAINERS = new Set(["PageShell"]);
 
 const UI_STRUCTURAL_HEADERS = new Map([
+  [
+    "PageIntro",
+    {
+      title: "PageTitle",
+      optional: new Set(["PageIntroActions", "PageDescription"]),
+      shorthand: new Set(),
+    },
+  ],
   [
     "DialogIntro",
     {
@@ -376,7 +388,12 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageHeader",
     {
       title: "PageTitle",
-      optional: new Set(["PageBack", "PageNavigation", "PageActions", "PageDescription"]),
+      optional: new Set([
+        "PageBack",
+        "PageNavigation",
+        "PageActions",
+        "PageDescription",
+      ]),
       exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
       titleRequired: false,
@@ -568,7 +585,8 @@ export function parseRetention(fileName, sourceText) {
       if (item === undefined) return undefined;
       if (!ts.isPropertyAssignment(item)) return null;
       const init = item.initializer;
-      return ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)
+      return ts.isStringLiteral(init) ||
+        ts.isNoSubstitutionTemplateLiteral(init)
         ? init.text
         : null;
     };
@@ -797,7 +815,9 @@ function checkRetention(retention) {
         if (batch !== null && (!Number.isInteger(batch) || batch < 1))
           at("`batchSize` precisa ser um inteiro positivo.");
         else if (batch !== null && batch > MAX_PURGE_BATCH_SIZE)
-          at(`\`batchSize\` aceita no máximo ${MAX_PURGE_BATCH_SIZE} linhas por lote.`);
+          at(
+            `\`batchSize\` aceita no máximo ${MAX_PURGE_BATCH_SIZE} linhas por lote.`,
+          );
         const inDomain =
           entity.inlineInDomain ||
           (entity.ident !== null && entityRefs.has(entity.ident));
@@ -813,7 +833,9 @@ function checkRetention(retention) {
     for (const purge of parsed.purges) {
       const subject = `bindPurge(${purge.entityRef ?? "?"})`;
       const entity =
-        purge.entityRef === null ? undefined : entitiesByIdent.get(purge.entityRef);
+        purge.entityRef === null
+          ? undefined
+          : entitiesByIdent.get(purge.entityRef);
       if (
         entity !== undefined &&
         entity !== "ambiguous" &&
@@ -982,15 +1004,20 @@ export function parseActions(fileName, sourceText) {
   /** `ai` literal → "enabled" | "disabled"; ausente → null; não literal → "unknown". */
   function aiState(obj) {
     const p = prop(obj, "ai");
-    if (!p) return obj.properties.some((pr) => pr.name?.getText(sf) === "ai") ? "unknown" : null;
+    if (!p)
+      return obj.properties.some((pr) => pr.name?.getText(sf) === "ai")
+        ? "unknown"
+        : null;
     const value = p.initializer;
     if (value.kind === ts.SyntaxKind.TrueKeyword) return "enabled";
     if (value.kind === ts.SyntaxKind.FalseKeyword) return "disabled";
     if (ts.isObjectLiteralExpression(value)) {
       const enabled = prop(value, "enabled");
       if (!enabled) return "enabled";
-      if (enabled.initializer.kind === ts.SyntaxKind.FalseKeyword) return "disabled";
-      if (enabled.initializer.kind === ts.SyntaxKind.TrueKeyword) return "enabled";
+      if (enabled.initializer.kind === ts.SyntaxKind.FalseKeyword)
+        return "disabled";
+      if (enabled.initializer.kind === ts.SyntaxKind.TrueKeyword)
+        return "enabled";
     }
     return "unknown";
   }
@@ -1007,14 +1034,17 @@ export function parseActions(fileName, sourceText) {
       if (!found) return { present: objKeys(value).includes(key), text: null };
       return {
         present: true,
-        text: ts.isStringLiteralLike(found.initializer) ? found.initializer.text : null,
+        text: ts.isStringLiteralLike(found.initializer)
+          ? found.initializer.text
+          : null,
       };
     };
     const limit = prop(value, "maxContextChars");
     let maxContextChars = null;
     if (limit) {
       const node = limit.initializer;
-      if (ts.isNumericLiteral(node)) maxContextChars = Number(node.text.replace(/_/g, ""));
+      if (ts.isNumericLiteral(node))
+        maxContextChars = Number(node.text.replace(/_/g, ""));
       else if (
         ts.isPrefixUnaryExpression(node) &&
         node.operator === ts.SyntaxKind.MinusToken &&
@@ -1025,7 +1055,9 @@ export function parseActions(fileName, sourceText) {
     const contextNode = prop(value, "context");
     const contextPaths =
       contextNode && ts.isArrayLiteralExpression(contextNode.initializer)
-        ? contextNode.initializer.elements.filter(ts.isStringLiteralLike).map((element) => element.text)
+        ? contextNode.initializer.elements
+            .filter(ts.isStringLiteralLike)
+            .map((element) => element.text)
         : [];
     return {
       readable: true,
@@ -1110,17 +1142,27 @@ function assistantMessages(a) {
   if (!assistant.readable) return out;
   const { resource, skill } = assistant;
   if (!resource.present)
-    out.push("O assistente precisa declarar `resource`, o tipo de recurso de que a action é dona.");
+    out.push(
+      "O assistente precisa declarar `resource`, o tipo de recurso de que a action é dona.",
+    );
   else if (resource.text !== null && !ASSISTANT_RESOURCE_RE.test(resource.text))
-    out.push(`\`resource: "${resource.text}"\` precisa estar em camelCase, como \`customer\` ou \`aftersaleOpportunity\`.`);
+    out.push(
+      `\`resource: "${resource.text}"\` precisa estar em camelCase, como \`customer\` ou \`aftersaleOpportunity\`.`,
+    );
   if (!skill.present)
-    out.push("O assistente precisa declarar `skill`, a chave do procedimento que a IA segue.");
+    out.push(
+      "O assistente precisa declarar `skill`, a chave do procedimento que a IA segue.",
+    );
   else if (skill.text !== null && !ASSISTANT_SKILL_RE.test(skill.text))
-    out.push(`\`skill: "${skill.text}"\` precisa estar em minúsculas com hífen, como \`review-customer\`.`);
+    out.push(
+      `\`skill: "${skill.text}"\` precisa estar em minúsculas com hífen, como \`review-customer\`.`,
+    );
   const reserved = [assistant.title.text, ...assistant.contextPaths].filter(
     (path) =>
       typeof path === "string" &&
-      path.split(".").some((segment) => ASSISTANT_RESERVED_SEGMENTS.has(segment)),
+      path
+        .split(".")
+        .some((segment) => ASSISTANT_RESERVED_SEGMENTS.has(segment)),
   );
   if (reserved.length > 0)
     out.push(
@@ -1129,12 +1171,16 @@ function assistantMessages(a) {
   const limit = assistant.maxContextChars;
   if (
     limit !== null &&
-    (!Number.isInteger(limit) || limit < ASSISTANT_CONTEXT_MIN || limit > ASSISTANT_CONTEXT_MAX)
+    (!Number.isInteger(limit) ||
+      limit < ASSISTANT_CONTEXT_MIN ||
+      limit > ASSISTANT_CONTEXT_MAX)
   )
     out.push(
       `\`maxContextChars: ${limit}\` precisa ser um inteiro de 1.000 a 16.000; sem ele, o teto é de 4.000 caracteres.`,
     );
-  const missing = Object.keys(ASSISTANT_REQUIRED).filter((key) => !assistant.keys.includes(key));
+  const missing = Object.keys(ASSISTANT_REQUIRED).filter(
+    (key) => !assistant.keys.includes(key),
+  );
   if (missing.length > 0)
     out.push(
       `O assistente precisa declarar ${missing.map((key) => ASSISTANT_REQUIRED[key]).join("; ")}.`,
@@ -1402,7 +1448,9 @@ export function checkProject(sources) {
 
   for (const [resource, owners] of assistantResources) {
     if (owners.length < 2) continue;
-    const names = owners.map(({ item }) => item.name ?? item.ident ?? "(sem name)");
+    const names = owners.map(
+      ({ item }) => item.name ?? item.ident ?? "(sem name)",
+    );
     for (const { item, file } of owners) {
       findings.push({
         rule: "assistant-declaration",
@@ -1707,6 +1755,22 @@ function directStructuralChildren(node, imports) {
   for (const child of node.children) {
     if (ts.isJsxText(child) && child.text.trim() === "") continue;
     if (ts.isJsxExpression(child) && child.expression === undefined) continue;
+    if (
+      ts.isJsxExpression(child) &&
+      child.expression &&
+      ts.isConditionalExpression(child.expression)
+    ) {
+      const branches = [child.expression.whenTrue, child.expression.whenFalse];
+      const slots = branches.map((branch) =>
+        ts.isJsxElement(branch) || ts.isJsxSelfClosingElement(branch)
+          ? imports.get(jsxLocalName(branch))
+          : undefined,
+      );
+      if (slots[0] !== undefined && slots[0] === slots[1]) {
+        names.push(slots[0]);
+        continue;
+      }
+    }
     if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
       const local = jsxLocalName(child);
       const imported = local === null ? null : imports.get(local);
@@ -1957,6 +2021,7 @@ function countPageHeadingSources(page, imports) {
           local !== null &&
           ((imports.get(local) === "Surface" &&
             jsxNumericAttribute(node, "level") === 1) ||
+            imports.get(local) === "PageIntro" ||
             imports.get(local) === "PageState")
         ) {
           if (imports.get(local) === "PageState") states += 1;
@@ -2095,11 +2160,55 @@ export function checkUiStructure(file, text) {
         }
       }
 
-      if (component !== null && UI_STRUCTURAL_BODIES.has(component)) {
-        const overridden = jsxStringAttributeValues(
-          jsxOpening(node),
-          "className",
-        )
+      if (["PageBody", "DialogBody", "DrawerBody"].includes(component)) {
+        const intro = component.replace("Body", "Intro");
+        const visible = (children) =>
+          children.flatMap((child) => {
+            if (ts.isJsxText(child)) return child.text.trim() ? [child] : [];
+            if (ts.isJsxFragment(child)) return visible(child.children);
+            if (
+              ts.isJsxExpression(child) &&
+              (!child.expression ||
+                [
+                  ts.SyntaxKind.NullKeyword,
+                  ts.SyntaxKind.FalseKeyword,
+                  ts.SyntaxKind.TrueKeyword,
+                ].includes(child.expression.kind))
+            )
+              return [];
+            return [child];
+          });
+        const children = ts.isJsxElement(node) ? visible(node.children) : [];
+        const indexes = children.flatMap((child, index) =>
+          (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) &&
+          imports.get(jsxLocalName(child)) === intro
+            ? [index]
+            : [],
+        );
+        if (indexes.length > 1 || (indexes.length === 1 && indexes[0] !== 0)) {
+          add(
+            node,
+            component,
+            `${intro} deve ser o primeiro e único bloco introdutório de ${component}.`,
+            "ui-structure-intro-order",
+          );
+        }
+      }
+
+      if (
+        component !== null &&
+        (UI_STRUCTURAL_BODIES.has(component) || component === "Page")
+      ) {
+        const attributes =
+          component === "Page"
+            ? ["contentClassName"]
+            : component === "PageBody"
+              ? ["className", "contentClassName"]
+              : ["className"];
+        const overridden = attributes
+          .flatMap((attribute) =>
+            jsxStringAttributeValues(jsxOpening(node), attribute),
+          )
           .flatMap((value) => value.trim().split(/\s+/))
           .filter((token) => UI_BODY_RHYTHM_CLASS.test(token));
         if (overridden.length > 0) {
@@ -2686,8 +2795,8 @@ export async function scanDir(rootDir) {
   for (const file of files) {
     const text = readProjectFile(rootDir, path.relative(rootDir, file)).content;
     if (
-      ![...ACTION_MARKERS, ...DATA_PRODUCT_MARKERS, ...RETENTION_MARKERS].some((m) =>
-        text.includes(m),
+      ![...ACTION_MARKERS, ...DATA_PRODUCT_MARKERS, ...RETENTION_MARKERS].some(
+        (m) => text.includes(m),
       )
     )
       continue;