@softize/opus 27.1.0 → 28.0.0

package/CHANGELOG.md

@@ -7,6 +7,61 @@ 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.
 
+## 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/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;

package/docs/adr/0015-action-size-follows-interaction-density.md

@@ -1,5 +1,7 @@
 # ADR 0015 — O tamanho da ação acompanha a densidade da interação
 
+> Parcialmente substituída pela [ADR 0060](0060-surface-composition-separates-chrome-and-intro.md), que define a composição e a escala atuais dos headers.
+
 - **Status:** aceita.
 - **Data:** 2026-09-12.
 

package/docs/adr/0029-page-header-is-the-single-page-introduction.md

@@ -1,6 +1,8 @@
 # ADR 0029 — PageHeader é a única introdução estrutural da página
 
-- **Status:** aceita.
+> Parcialmente substituída pela [ADR 0060](0060-surface-composition-separates-chrome-and-intro.md), que define a composição e a escala atuais dos headers.
+
+- **Status:** substituída parcialmente pela ADR 0060 na versão 28.0.0 da composição com intro.
 - **Data:** 2026-09-28.
 - **Substitui:** ADR 0011, quanto à barra persistente e à separação entre `PageHeader` e
   `PageIntro`.

package/docs/adr/0060-surface-composition-separates-chrome-and-intro.md

@@ -0,0 +1,161 @@
+# ADR 0060 — A composição separa controles da superfície e introdução do conteúdo
+
+- **Status:** aceita.
+- **Data:** 2026-10-10.
+- **Substitui parcialmente:** ADR 0029, quanto à proibição de PageIntro.
+- **Complementa:** ADRs 0023 e 0048.
+
+## Contexto
+
+Page perdeu a intro para evitar barras vazias e identificação redundante. Depois, Dialog e Drawer
+passaram a oferecer uma intro para separar os controles da superfície do conteúdo. A mesma página
+editorial passou a mudar o lugar do título e das ações quando aberta em outro hospedeiro.
+
+## Decisão
+
+Page, Dialog e Drawer compartilham duas composições, declaradas pelos slots, sem prop redundante:
+
+- compacta: o título e a orientação ficam no Header;
+- com intro: o Header recebe navegação e ações da superfície; a Intro é o primeiro bloco do Body
+  e recebe o único título, orientação opcional e ações locais por IntroActions.
+
+Header sem controles não reserva espaço. Navegação não é repetida na intro. O fechamento continua
+sendo responsabilidade do modal; Page não ganha um botão de fechar implícito. A posição da intro
+não muda o significado de layout: continuous/sectioned controla regiões e flow/fill controla altura.
+
+Page ganha PageIntro e PageIntroActions. A forma curta passa a colocar title e description na intro,
+com actions no Header. A forma explícita preserva a composição compacta para situações deliberadas.
+PageShell continua fornecendo contexto sem criar outra barra. Estados integrais continuam substituindo
+a introdução e o conteúdo, com um único heading acessível. O teto centralizado de 80rem é preservado.
+
+Surface mantém o cabeçalho do conteúdo, inclusive ações locais: não possui navegação ou fechamento
+que justifique uma segunda região. Pane e Split continuam sendo apenas layout. Alert mantém sua
+composição especializada. Patterns de formulário, coleção e Presentation precisam respeitar a mesma
+semântica ao montar os componentes, sem reconstruir linhas no consumidor.
+
+## Verificação e migração
+
+O checker valida família, posição da intro, unicidade do título e ações no slot correspondente.
+Testes renderizados cobrem as duas composições, estados integrais, ausência de barra vazia e contexto
+do shell. Consumidores de Page explícita migram título/descrição para PageIntro quando suas ações
+pertencem à superfície; cabeçalhos de coleções em Surface mantêm criação junto à coleção.
+
+A migração inclui SDK, exemplos, documentação e aplicação. Publicação e adoção definitiva só ocorrem
+após os gates e a revisão independente do conjunto. A versão 28.0.0 consolida a migração.
+
+## Alternativas
+
+Uma prop compact duplicaria informação já expressa pelos slots, abrindo combinações contraditórias.
+Manter Page diferente preservaria compatibilidade, mas perpetuaria a diferença entre hospedeiros.
+Uma barra obrigatória recuperaria o espaço vazio e a identificação repetida que motivaram a ADR 0029.
+
+## Rolagem
+
+Page ocupa a altura disponível do hospedeiro, com header e footer fora da região rolável.
+PageBody é o viewport vertical; a intro rola com o conteúdo. PageShell conserva a rolagem horizontal do canvas mínimo e permite rolagem vertical de
+contingência para rotas sem Page ou wrappers sem altura definida. Em layout fill, quando uma ActionList assume a rolagem, o body repassa
+a altura e não cria uma segunda rolagem vertical. Sem folha fill, o próprio body continua rolando.
+A composição compacta preserva a mesma responsabilidade: o título permanece no header estável.
+A fixação resulta da divisão de altura, sem position fixed ou sticky no consumidor.
+
+O header ocupa toda a largura disponível. O limite de 80rem e o recuo pertencem ao conteúdo
+interno do Body; o viewport ocupa a largura da página para manter sua barra de rolagem na extremidade.
+
+Quando presente, o header da Page usa borda inferior em toda a largura, como o Drawer.
+
+## Divisão visual da Page
+
+Page expõe `surfaceLayout="sectioned" | "continuous"`, com padrão `sectioned`.
+O nome separa a anatomia visual de `layout="flow" | "fill"`, preservado para altura.
+As regiões usam a tabela compartilhada de anatomia e seus divisores por adjacência.
+A largura total do header e do viewport, e o limite interno do conteúdo, valem nos dois modos.
+
+O header da Page acompanha o recuo do Drawer: 1rem no modo sectioned; no modo
+continuous, 1rem com recuo inferior de 0,75rem, ou 1rem quando for a única região.
+
+Após validação visual da barra com breadcrumb, o header da Page passa a usar 1rem nas
+laterais e 0,75rem na vertical nos dois modos. Esse ajuste substitui a equivalência de
+padding com o Drawer descrita acima; os divisores continuam compartilhados.
+
+A avaliação seguinte restaurou o padding do Drawer no header da Page: 1rem no modo
+sectioned e o ritmo correspondente no continuous. O experimento de redução vertical foi descartado.
+
+## Altura estável da linha do header
+
+A linha interna reserva 2rem em Page, Dialog, Drawer e Surface, mesmo sem ações.
+No header da Page, botões textuais usam `sm` (2rem), e os de ícone, `icon-sm` (2rem).
+Os consumidores declaram o tamanho; PageBack e comandos de Presentation em página já usam
+essa escala. Coleções e headers de modais usam a mesma escala; rodapés conservam default. É uma altura mínima, permitindo crescimento do
+conteúdo. Padding e intro permanecem independentes; headers ausentes não reservam espaço.
+
+Presentation em página delega padding e rolagem ao PageBody, tanto dentro quanto fora
+de PageShell. Não intercala um viewport próprio; PresentationBody conserva somente a
+propagação de altura quando houver conteúdo fill. Headers compactos distribuem título
+e ações na linha interna, inclusive sem navegação.
+
+## Revisão: geometria comum da família
+
+A escala compacta exclusiva de Page mantinha headers de Drawer maiores com a mesma
+composição. A família inteira passa a compartilhar padding de 1rem e linha mínima
+de 2rem: Page, Dialog, Drawer e Surface delimitada, também quando hospedada em Pane.
+Vale nos layouts continuous e sectioned; o divisor continua sendo uma decisão do layout.
+Isso substitui o ritmo variável de padding inferior dos headers descrito anteriormente.
+
+Botões de header usam `sm` para texto e `icon-sm` para ícones, incluindo comandos de
+Presentation e criação de coleções. Rodapés preservam a escala anterior. A seção
+Surface sem delimitação não ganha padding externo, e legendas recortadas continuam
+com sua geometria própria. O mínimo de linha e a escala das ações permanecem comuns.
+
+As medidas têm uma fonte compartilhada, comparada em testes entre as quatro famílias.
+Os tamanhos são declarados pelos consumidores: não há CSS de redimensionamento nem
+contexto herdável que altere botões de portais, corpos ou rodapés.
+
+## Correção da escala compacta
+
+`icon-sm` passa de 1,75rem para 2rem, correspondendo à altura de `sm`. O desenho
+do ícone continua em 0,875rem. O mínimo de 2rem da linha protege headers sem ações;
+não existe mais diferença de altura entre os controles compactos textuais e quadrados.
+Paginação usa os mesmos tokens, com largura flexível para números longos.
+
+## Ritmo vertical compartilhado — 2026-10-13
+
+A validação em Conhecimento encontrou intervalos de 0,5rem, 0,75rem e 1,25rem para a mesma
+relação entre cabeçalho e conteúdo. O padrão passa a ser 1rem entre regiões contínuas e
+entre blocos diretos de um body, inclusive TabsPanel. O componente hospedeiro fornece o
+ritmo; DetailGroup e Separator não recebem margem externa própria.
+
+Surface sem delimitação e Tabs sem moldura não adicionam padding inferior. Surface delimitada
+por framed ou elevation, Dialog e Drawer reservam 1rem até a borda. No layout sectioned,
+cada região reserva 1rem entre seu conteúdo e a divisória. No continuous, a região anterior
+fornece o intervalo, evitando somar dois paddings. A ausência de header preserva o recuo
+superior de uma superfície delimitada. Fieldset com legend conserva 1rem após a legenda.
+
+Page preserva largura de leitura e recuos laterais. Seu body não reserva padding inferior
+quando encerra a página; quando há footer sectioned, reserva 1rem até a divisória. A barra
+continua fora da rolagem. O modo flush continua removendo recuos, mas conserva o ritmo
+entre blocos: tabelas e listas que ocupam a superfície controlam seu próprio interior.
+
+Tabs mantém o espaçamento interno dos botões. O intervalo até o painel é 1rem; com framed,
+o painel recebe recuos laterais e inferior de 1rem. Abas verticais mantêm o intervalo entre
+as colunas e a moldura recebe o recuo externo sem duplicá-lo no painel.
+
+Manter medidas locais dependeria de disciplina em cada tela; impor margem a cada bloco
+somaria intervalos no aninhamento. As duas alternativas foram descartadas. A migração remove
+overrides de ritmo e padding nos slots estruturais, preservando layouts internos deliberados.
+Testes em navegador medem intervalos, fechamento inferior, aninhamento, presença/ausência de
+header e footer, flush e troca de abas. O ritmo altera o default visual; a composição de Page exige a migração documentada na versão major.
+
+Uma composição pode manter `gap-0` quando Tabs hospeda um DrawerBody que já fornece o
+intervalo superior e controla a rolagem, como o painel de nós de Fluxos. Isso evita dois
+intervalos para a mesma relação; não altera a medida de 1rem percebida pelo conteúdo.
+
+## Escala do título na intro — 2026-10-13
+
+PageTitle, DrawerTitle e DialogTitle usam a mesma escala na intro: 1,875rem, com peso
+semibold e tracking compacto. Drawer e Dialog mantêm a escala menor quando o título
+está no header compacto. A hierarquia HTML continua independente do tamanho visual.
+Metadados de data e autoria permanecem na descrição; um badge de tipo pode acompanhar
+o título em uma composição inline com quebra, sem criar um novo slot estrutural.
+
+`contentClassName` em Page e PageBody configura largura e alinhamento internos; `className`
+controla a moldura e o viewport, respectivamente. Presentation fora do shell preserva largura total.

package/docs/adr/README.md

@@ -12,3 +12,5 @@ Uma ADR preserva seu contexto histórico mesmo quando é substituída. O comport
 estar documentado na superfície correspondente, sem exigir a reconstrução dessa sequência.
 
 - [ADR 0059 — Subheadings orientam sem carregar regras de negócio](0059-subheadings-orient-without-carrying-business-rules.md).
+
+- [ADR 0060 — Composição de superfícies com cabeçalho e intro](0060-surface-composition-separates-chrome-and-intro.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "27.1.0",
+  "version": "28.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/skills/build-opus-ui/SKILL.md

@@ -43,17 +43,17 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 7. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh. Em `Presentation`, declarar `route`
    no artefato e deixar o adaptador apenas conectar a spec ao router da aplicação.
-8. Compor superfícies pela gramática estrutural do catálogo: `PageHeader` é a única introdução
-   estrutural e reúne navegação contextual opcional, título e ações; `PageBody` contém o conteúdo.
-   Na composição explícita, declare exatamente um heading principal com `PageTitle` no header,
-   `Surface level={1}` ou um `PageState` ativo no body. `PageShell` pode fornecer navegação e ações
-   conhecidas pela aplicação, mas não cria uma barra visual. `Surface` contém `SurfaceHeader` e
-   `SurfaceBody`; Drawer e Pane usam seus respectivos `*Body`. Para o caso direto, usar a sintaxe
-   abreviada de `Page` (`title`, `actions`) ou de `Surface` (`title`, `description`, `actions` e
-   `count`); não misturá-la com o
-   header explícito. O título da página não carrega contador. Ajustar o
-   nível do heading pela hierarquia semântica, não pelo destaque visual. O `Page` mantém seu teto
-   centralizado padrão de `80rem`.
+8. Compor Page, Dialog e Drawer pela mesma gramática: no formato compacto, título e orientação
+   ficam no Header; com Intro, navegação e ações da superfície ficam no Header e a Intro abre o
+   Body com título, orientação e ações locais em IntroActions. Declarar a escolha pelos slots,
+   sem prop redundante. Usar PageIntro na Page explícita; a forma curta de Page já coloca title e
+   description na intro e actions no header. Não misturar shorthand com regiões explícitas.
+   Manter exatamente um heading principal, inclusive quando Surface level={1} nomeia uma coleção
+   ou PageState substitui a página. PageShell fornece contexto sem criar barra paralela; header
+   sem controles não reserva espaço. Preservar o teto de 80rem e separar composição de ocupação
+   de altura (flow/fill). Surface mantém o cabeçalho do conteúdo; Pane distribui espaço e recebe
+   uma superfície quando precisar de anatomia visual. Não criar Intro nem controles de navegação
+   artificiais para Surface ou Pane.
    Em `Surface framed`, usar `layout="sectioned"` e `SurfaceBody flush` quando o filho direto já
    controlar o recuo do body, como `DetailGroup` com divisores, lista ou tabela; não reconstruir
    divisor, padding ou recorte por classes no consumidor. Em grupos de formulário,

package/registry/skills/build-opus-ui/references/evaluations.md

@@ -74,3 +74,13 @@ complementar do termo. Esperado: `description` orienta a finalidade, `hint` mant
 de deixar vazio e `help` oferece somente o detalhe opcional. `intro` continua no corpo quando a
 regra afeta vários campos. Reprovar regra obrigatória somente em subheading ou tooltip, repetição
 da label, duplicação entre hint/help e perda de `aria-describedby` quando aparece um erro.
+
+## Composição de superfícies
+
+- Gatilho positivo: “Monte o detalhe de um recurso com menu da página separado do título.”
+- Gatilho negativo: “Explique por que a ADR antiga juntava título e ações”, sem pedido de UI.
+- Execução: montar o mesmo detalhe em Page, Dialog e Drawer com header de navegação/ações e intro
+  abrindo o body; montar também a versão compacta sem intro. Provar título único, ações locais em
+  IntroActions, nenhum header vazio na Page e transição de loading para conteúdo sem título duplicado.
+- Reprovar intro depois de texto, título simultâneo em header e intro, ações da superfície no título
+  ou adaptação de Pane para que ele volte a possuir anatomia visual.