@softize/opus 17.2.0 → 18.0.1

package/CHANGELOG.md

@@ -7,6 +7,68 @@ 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.
 
+## 18.0.1 — 2026-09-13
+
+Controles somente com ícone que pertencem ao chrome da superfície, como voltar e fechar, usam o
+tamanho normal `icon`. O retorno cresce de 1.75rem para a área clicável padrão de 2.25rem; o close
+permanece nessa medida e ambos mantêm o glifo compacto. `icon-sm` fica reservado às composições
+densas, como paginação e toolbars.
+
+## 18.0.0 — 2026-09-13
+
+### Breaking
+
+- Em composição explícita, `Page` exige exatamente um heading principal: use `PageTitle` em
+  `PageHeader` ou `PageIntro`, `Content level={1}` ou um `PageState` ativo dentro de `PageBody`.
+- `DialogFooter` e `DrawerFooter` deixam de distribuir botões diretamente. Envolva decisões em
+  `ButtonGroup`; use `distribution="equal"` para o footer modal 50/50.
+- A criação de uma coleção deixa o chrome global da página e passa ao `ContentHeader`, junto ao
+  título da lista. Use um botão textual `default`, sem ícone, com `Criar recurso`.
+
+Páginas centradas em uma coleção passam a compor `Content + ActionList`: o cabeçalho do Content
+reúne o título e a criação, enquanto busca, filtros, atualização, estados e paginação permanecem no
+ActionList. `toolbarActions` fica reservado a operações que dependem do recorte atual.
+
+`Presentation.route` passa a declarar caminho, surface e origem opcional do registro. Os helpers
+`matchPresentationRoute` e `pathForPresentationInvocation` permitem ligar o artefato ao router sem
+repetir a navegação no componente da página.
+
+`PageHeader` pode declarar somente navegação e ações globais e coexistir com `PageIntro`; uma Page
+cujo conteúdo fornece o heading principal pode conter apenas `PageBody`. Em uma Presentation de
+listagem exibida como Page, título e comandos de header são materializados no Content que envolve a
+lista. Dialog e Drawer continuam usando o header da superfície.
+
+Uma ação de coleção é apresentada no extremo oposto ao título como botão textual `default`, sem
+ícone, com o rótulo `Criar recurso`. `Content variant="page"` mantém essa geometria, enquanto
+`PageHeader` continua reservado à navegação e às ações globais. O diálogo de criação usa
+`Criar recurso` e o de edição, `Editar recurso`.
+
+Em formulários modais, o footer 50/50 apresenta `Cancelar` em `outline` e mantém a ação principal
+em `solid`. `ButtonGroup` passa a responder pelo agrupamento e pela distribuição das decisões;
+`DialogFooter` e `DrawerFooter` cuidam somente da faixa. `ActionForm` cru continua usando `ghost`
+por padrão e oferece `cancelVariant` para composições próprias.
+
+Formulários comuns de criação e edição usam o rótulo padrão `Salvar`. `submitLabel` permanece para
+operações cujo efeito pede outro verbo, como `Renomear`, `Criar nova versão` ou `Colocar na fila`.
+
+Header, body e footer de `Dialog` e `Drawer` usam o mesmo padding compacto (`1rem`), preservando
+alinhamento horizontal e vertical entre as três regiões. O footer mantém a cor da superfície e usa
+somente a borda para separar as ações do body. O close do header usa o tamanho normal somente com
+ícone; o glifo segue a escala global compacta de `0.875rem`, sem reduzir sua área clicável.
+Cancelamentos em `Dialog mode="alert"`, incluindo confirmações de `ActionTrigger`, `ActionList` e
+a API imperativa, usam `outline`; a decisão principal continua `solid`.
+
+## 17.2.1 — 2026-09-12
+
+O `Chat` passa a renderizar `renderMessageActions` também nas mensagens enviadas. Data, cópia e
+outras ações contextuais podem usar a mesma extensão discreta nos dois lados da conversa.
+`activity=""` oferece o indicador compacto, com somente os pontos centralizados e “Pensando…”
+preservado como nome acessível.
+Tools MCP passam a projetar a `label` legível da action em `title`, mantendo `name` como
+identificador técnico estável para execução e auditoria.
+O transcript compacta e equilibra o respiro antes e depois da mensagem enviada, inclusive quando
+a faixa de ações contextuais fica reservada para o hover.
+
 ## 17.2.0 — 2026-09-12
 
 Páginas hospedadas por `PageShell` passam a apresentar o título no início do conteúdo, em
@@ -95,7 +157,6 @@ mesmo motivo. Nas APIs imperativas `alert`, `confirm`, `prompt` e `choose`, e em
 `PageHeaderVariant` deixam de existir; use `PageShell` para a barra persistente e `PageIntro` para
 a introdução do conteúdo.
 
-
 ## 15.2.2 — 2026-09-11
 
 O acesso descritivo de Produtos de Dados usa `permissionContexts` no lugar do nome genérico

package/bin/lib/check.mjs

@@ -170,6 +170,8 @@ const UI_STRUCTURAL_ROOTS = new Map([
       alternateHeader: "PageIntro",
       body: "PageBody",
       footer: "PageFooter",
+      headerRequired: false,
+      allowBothHeaders: true,
       shorthand: new Set(["title", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
       // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
@@ -239,10 +241,7 @@ const UI_REMOVED_PROPS = new Map([
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
-  [
-    "PageDescription",
-    "mova contexto relevante para o início de `PageBody`",
-  ],
+  ["PageDescription", "mova contexto relevante para o início de `PageBody`"],
   [
     "DialogDescription",
     "mova contexto relevante para o início de `DialogBody`",
@@ -260,13 +259,10 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageHeader",
     {
       title: "PageTitle",
-      optional: new Set([
-        "PageBack",
-        "PageNavigation",
-        "PageActions",
-      ]),
+      optional: new Set(["PageBack", "PageNavigation", "PageActions"]),
       exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
+      titleRequired: false,
     },
   ],
   [
@@ -365,12 +361,21 @@ export const DATA_PRODUCT_MARKERS = ["defineDataProduct", "defineEntity"];
 
 /** Extrai Produtos de Dados e entities literais para validar a linhagem sem executar o app. */
 export function parseDataProducts(fileName, sourceText) {
-  const sf = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const sf = ts.createSourceFile(
+    fileName,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
   const products = [];
   const entities = [];
-  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
-  const prop = (obj, key) => obj.properties.find((item) =>
-    ts.isPropertyAssignment(item) && item.name?.getText(sf) === key)?.initializer;
+  const lineOf = (node) =>
+    sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  const prop = (obj, key) =>
+    obj.properties.find(
+      (item) => ts.isPropertyAssignment(item) && item.name?.getText(sf) === key,
+    )?.initializer;
   const stringProp = (obj, key) => {
     const value = prop(obj, key);
     return value && ts.isStringLiteral(value) ? value.text : null;
@@ -383,17 +388,33 @@ export function parseDataProducts(fileName, sourceText) {
   };
   const isExported = (call) => {
     const declaration = call.parent;
-    const statement = ts.isVariableDeclaration(declaration) ? declaration.parent?.parent : undefined;
-    return statement !== undefined && ts.isVariableStatement(statement) && (statement.modifiers ?? []).some((item) => item.kind === ts.SyntaxKind.ExportKeyword);
+    const statement = ts.isVariableDeclaration(declaration)
+      ? declaration.parent?.parent
+      : undefined;
+    return (
+      statement !== undefined &&
+      ts.isVariableStatement(statement) &&
+      (statement.modifiers ?? []).some(
+        (item) => item.kind === ts.SyntaxKind.ExportKeyword,
+      )
+    );
   };
   const visit = (node) => {
-    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.arguments[0] && ts.isObjectLiteralExpression(node.arguments[0])) {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.arguments[0] &&
+      ts.isObjectLiteralExpression(node.arguments[0])
+    ) {
       const obj = node.arguments[0];
       if (node.expression.text === "defineDataProduct") {
         const versionNode = prop(obj, "version");
         products.push({
           id: stringProp(obj, "id"),
-          version: versionNode && ts.isNumericLiteral(versionNode) ? Number(versionNode.text) : null,
+          version:
+            versionNode && ts.isNumericLiteral(versionNode)
+              ? Number(versionNode.text)
+              : null,
           interfaces: stringList(obj, "interfaces"),
           entities: stringList(obj, "entities"),
           exported: isExported(node),
@@ -609,7 +630,8 @@ export function checkProject(sources) {
   for (const { file, text } of sources) {
     const declarations = parseDataProducts(file, text);
     for (const entity of declarations.entities) entityNames.add(entity);
-    for (const product of declarations.products) productDeclarations.push({ product, file });
+    for (const product of declarations.products)
+      productDeclarations.push({ product, file });
     for (const item of parseActions(file, text)) {
       if (item.form === "bindAction") {
         actions += 1;
@@ -633,33 +655,69 @@ export function checkProject(sources) {
 
   const productIds = new Set();
   for (const { product, file } of productDeclarations) {
-    const finding = (rule, message) => findings.push({
-      rule, level: "error", action: product.id ?? "(Produto de Dados sem id)",
-      line: product.line, file, message,
-    });
-    if (!product.exported) finding("data-product-export", "defineDataProduct precisa ser `export const` para compor o domínio e o catálogo.");
+    const finding = (rule, message) =>
+      findings.push({
+        rule,
+        level: "error",
+        action: product.id ?? "(Produto de Dados sem id)",
+        line: product.line,
+        file,
+        message,
+      });
+    if (!product.exported)
+      finding(
+        "data-product-export",
+        "defineDataProduct precisa ser `export const` para compor o domínio e o catálogo.",
+      );
     if (product.id === null || !ACTION_NAME_RE.test(product.id)) {
-      finding("data-product-id", "Produto de Dados precisa de `id` namespaced literal, como `sales.leads`.");
+      finding(
+        "data-product-id",
+        "Produto de Dados precisa de `id` namespaced literal, como `sales.leads`.",
+      );
     } else if (productIds.has(product.id)) {
-      finding("data-product-duplicate", `Produto de Dados "${product.id}" está declarado mais de uma vez.`);
+      finding(
+        "data-product-duplicate",
+        `Produto de Dados "${product.id}" está declarado mais de uma vez.`,
+      );
     } else {
       productIds.add(product.id);
     }
-    if (product.version === null || !Number.isInteger(product.version) || product.version < 1) {
-      finding("data-product-version", "Produto de Dados precisa de `version` literal inteira e positiva.");
+    if (
+      product.version === null ||
+      !Number.isInteger(product.version) ||
+      product.version < 1
+    ) {
+      finding(
+        "data-product-version",
+        "Produto de Dados precisa de `version` literal inteira e positiva.",
+      );
     }
     if (product.interfaces === null || product.interfaces.length === 0) {
-      finding("data-product-interfaces", "Produto de Dados precisa declarar ao menos uma Action literal em `interfaces`.");
+      finding(
+        "data-product-interfaces",
+        "Produto de Dados precisa declarar ao menos uma Action literal em `interfaces`.",
+      );
     } else {
       for (const action of product.interfaces) {
-        if (!actionNames.has(action)) finding("data-product-interface", `A interface "${action}" não corresponde a uma Action ou contrato declarado no projeto.`);
+        if (!actionNames.has(action))
+          finding(
+            "data-product-interface",
+            `A interface "${action}" não corresponde a uma Action ou contrato declarado no projeto.`,
+          );
       }
     }
     if (product.entities === null) {
-      finding("data-product-entities", "Produto de Dados precisa declarar `entities` como lista literal.");
+      finding(
+        "data-product-entities",
+        "Produto de Dados precisa declarar `entities` como lista literal.",
+      );
     } else {
       for (const entity of product.entities) {
-        if (!entityNames.has(entity)) finding("data-product-entity", `A Entity "${entity}" não foi declarada no projeto.`);
+        if (!entityNames.has(entity))
+          finding(
+            "data-product-entity",
+            `A Entity "${entity}" não foi declarada no projeto.`,
+          );
       }
     }
   }
@@ -682,7 +740,12 @@ export function checkProject(sources) {
     }
   }
 
-  return { actions, contracts, dataProducts: productDeclarations.length, findings };
+  return {
+    actions,
+    contracts,
+    dataProducts: productDeclarations.length,
+    findings,
+  };
 }
 
 /** Migrações de UI que falhariam apenas visualmente. Linhas que são só comentário não
@@ -977,6 +1040,84 @@ function directStructuralChildren(node, imports) {
   return { names, hasOpaque };
 }
 
+function directImportedJsxChildren(node, imports) {
+  if (!ts.isJsxElement(node)) return [];
+  return node.children.flatMap((child) => {
+    if (!ts.isJsxElement(child) && !ts.isJsxSelfClosingElement(child)) return [];
+    const local = jsxLocalName(child);
+    const imported = local === null ? undefined : imports.get(local);
+    return imported === undefined ? [] : [{ node: child, component: imported }];
+  });
+}
+
+function jsxNumericAttribute(node, name) {
+  const attribute = jsxAttribute(jsxOpening(node), name);
+  if (attribute === undefined || attribute.initializer === undefined) return null;
+  if (
+    ts.isJsxExpression(attribute.initializer) &&
+    attribute.initializer.expression !== undefined &&
+    ts.isNumericLiteral(attribute.initializer.expression)
+  ) {
+    return Number(attribute.initializer.expression.text);
+  }
+  if (ts.isStringLiteral(attribute.initializer)) {
+    const value = Number(attribute.initializer.text);
+    return Number.isFinite(value) ? value : null;
+  }
+  return null;
+}
+
+function countPageHeadingSources(page, imports) {
+  let count = 0;
+  let states = 0;
+  for (const child of directImportedJsxChildren(page, imports)) {
+    if (child.component === "PageHeader" || child.component === "PageIntro") {
+      count += directImportedJsxChildren(child.node, imports).filter(
+        (entry) => entry.component === "PageTitle",
+      ).length;
+    }
+    if (child.component !== "PageBody") continue;
+    const visit = (node) => {
+      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+        const local = jsxLocalName(node);
+        if (
+          local !== null &&
+          ((imports.get(local) === "Content" &&
+            jsxNumericAttribute(node, "level") === 1) ||
+            imports.get(local) === "PageState")
+        ) {
+          if (imports.get(local) === "PageState") states += 1;
+          else count += 1;
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(child.node);
+  }
+  return states > 0 ? states : count;
+}
+
+function pageBodyHasOpaqueDescendant(page, imports) {
+  for (const child of directImportedJsxChildren(page, imports)) {
+    if (child.component !== "PageBody" || !ts.isJsxElement(child.node)) continue;
+    let opaque = false;
+    const visit = (node) => {
+      if (opaque) return;
+      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+        const local = jsxLocalName(node);
+        if (local !== null && imports.get(local) === undefined) {
+          opaque = true;
+          return;
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    for (const bodyChild of child.node.children) visit(bodyChild);
+    if (opaque) return true;
+  }
+  return false;
+}
+
 /** Verifica a anatomia JSX pública definida na ADR 0005. */
 export function checkUiStructure(file, text) {
   if (!/\.[cm]?[jt]sx$/.test(file)) return [];
@@ -1152,13 +1293,9 @@ export function checkUiStructure(file, text) {
           attributes.has(attribute),
         );
         const children = directStructuralChildren(node, imports);
-        const insidePageShell =
-          component === "Page" && hasJsxAncestor(node, imports, "PageShell");
-        const acceptedHeaders = (
-          insidePageShell
-            ? [root.alternateHeader]
-            : [root.header, root.alternateHeader]
-        ).filter(Boolean);
+        const acceptedHeaders = [root.header, root.alternateHeader].filter(
+          Boolean,
+        );
         const structural =
           acceptedHeaders.some((header) => children.names.includes(header)) ||
           children.names.includes(root.body) ||
@@ -1182,6 +1319,10 @@ export function checkUiStructure(file, text) {
           const headers = children.names.filter((name) =>
             acceptedHeaders.includes(name),
           ).length;
+          const duplicatedHeader = acceptedHeaders.some(
+            (header) =>
+              children.names.filter((name) => name === header).length > 1,
+          );
           const bodies = children.names.filter(
             (name) => name === root.body,
           ).length;
@@ -1194,18 +1335,39 @@ export function checkUiStructure(file, text) {
               name !== root.body &&
               name !== root.footer,
           );
-          if (
-            headers !== 1 ||
+          const invalidComposition =
+            (root.headerRequired === false
+              ? headers > (root.allowBothHeaders ? 2 : 1)
+              : headers !== 1) ||
+            duplicatedHeader ||
             bodies !== 1 ||
             footers > 1 ||
             unexpected ||
-            children.hasOpaque
-          ) {
+            children.hasOpaque;
+          if (invalidComposition) {
             add(
               node,
               component,
-              `${component} explícito exige exatamente um ${acceptedHeaders.join(" ou ")}, um ${root.body} e no máximo um ${root.footer ?? "footer"} como filhos diretos.`,
+              root.headerRequired === false
+                ? `${component} explícito exige exatamente um ${root.body} e aceita no máximo um de cada: ${acceptedHeaders.join(", ")} e ${root.footer ?? "footer"}.`
+                : `${component} explícito exige exatamente um ${acceptedHeaders.join(" ou ")}, um ${root.body} e no máximo um ${root.footer ?? "footer"} como filhos diretos.`,
             );
+          } else if (component === "Page") {
+            const headingSources = countPageHeadingSources(node, imports);
+            if (
+              headingSources === 1 ||
+              (headingSources === 0 &&
+                pageBodyHasOpaqueDescendant(node, imports))
+            ) {
+              // Um componente intermediário pode materializar PageState. O runtime valida essa
+              // composição depois que os layout effects dos filhos registram a presença.
+            } else {
+              add(
+                node,
+                component,
+                "Page explícito exige exatamente um heading principal em PageHeader, PageIntro, Content level={1} ou PageState dentro de PageBody.",
+              );
+            }
           }
         }
       }
@@ -1576,7 +1738,12 @@ export async function scanDir(rootDir) {
   const sources = [];
   for (const file of files) {
     const text = readProjectFile(rootDir, path.relative(rootDir, file)).content;
-    if (![...ACTION_MARKERS, ...DATA_PRODUCT_MARKERS].some((m) => text.includes(m))) continue;
+    if (
+      ![...ACTION_MARKERS, ...DATA_PRODUCT_MARKERS].some((m) =>
+        text.includes(m),
+      )
+    )
+      continue;
     sources.push({ file: path.relative(rootDir, file), text });
   }
   const checked = checkProject(sources);

package/docs/adr/0010-page-header-owns-page-chrome.md

@@ -36,8 +36,8 @@ A variante altera somente a apresentação. Título, descrição, retorno e aç
 semanticamente à mesma página. Um header sem conteúdo útil não é materializado para reservar
 altura, e o header é ocultado durante os estados integrais do `PageState` — inversão da decisão
 original da ADR 0004, argumentada no adendo dela. Para acompanhar o ritmo
-compacto da barra, ações com texto usam `Button size="sm"` e ações somente com ícone usam
-`Button size="icon-sm"`.
+da barra, ações com texto usam `Button size="default"` e ações somente com ícone usam
+`Button size="icon"`.
 
 ## Consequências
 

package/docs/adr/0011-page-shell-coordinates-persistent-page-chrome.md

@@ -4,6 +4,10 @@
 - **Data:** 2026-09-10.
 - **Revisa:** ADR 0010.
 
+> **Atualização (2026-09-13).** A ADR 0016 separa o chrome persistente da introdução e do
+> cabeçalho de uma coleção. `PageHeader` passa a declarar navegação e ações globais para a barra;
+> `PageIntro` permanece opcional no conteúdo e `Content` nomeia coleções.
+
 ## Contexto
 
 A ADR 0010 reuniu título, navegação e ações em `PageHeader`, mas partiu do pressuposto de que uma

package/docs/adr/0013-presentation-is-a-portable-action-oriented-artifact.md

@@ -3,6 +3,14 @@
 - **Status:** aceita.
 - **Data:** 2026-09-11.
 
+> **Atualização (2026-09-13).** Conforme a ADR 0016, uma Presentation de listagem em Page
+> materializa título e comandos de header no `Content` que envolve o `ActionList`. Dialog e Drawer
+> continuam materializando esses elementos no header da superfície.
+>
+> Uma Presentation pode declarar uma `route` absoluta com parâmetros. Nessa forma, URL, surface e
+> origem do registro passam a integrar o artefato; o adaptador da aplicação apenas conecta a spec ao
+> router hospedeiro.
+
 ## Contexto
 
 Page, Dialog e Drawer compartilham uma anatomia estrutural, mas consumidores ainda repetem a
@@ -49,12 +57,16 @@ estática, publicável no manifest e inspecionável pela Lens. A invocação é
 uma execução: identifica a Presentation, escolhe a surface, carrega somente input JSON e mantém a
 pilha de frames necessária para voltar. Ela não é publicada no manifest.
 
+Quando refresh, deep link ou histórico fazem parte do recurso, `route` declara o caminho, a surface
+e, quando necessário, a lista que fornece o registro identificado por um parâmetro. Rotas continuam
+opcionais: a mesma Presentation pode ser usada como superfície efêmera sem assumir um router.
+
 `back` restaura o último frame da pilha. Em Dialog ou Drawer, ele só é apresentado quando o frame
 anterior também é modal; a Page mantida ao fundo não cria uma etapa intermediária. `close` encerra
 apenas dialog ou drawer e é inválido para page. Formulários modais oferecem `Cancelar` como ação de
 abandono no footer, ao lado da conclusão. `navigate` abre outra invocação por push ou substitui a
-atual; sincronizar esse estado com URL é responsabilidade do adaptador da aplicação quando refresh,
-deep link ou histórico forem necessários. O inspetor de desenvolvimento reúne definição,
+atual. Sem `route`, sincronizar esse estado com URL é responsabilidade do adaptador da aplicação.
+Com `route`, o adaptador deriva o caminho e a invocação do próprio artefato. O inspetor de desenvolvimento reúne definição,
 invocação, bindings resolvidos e diagnósticos, mascarando chaves sensíveis antes de expor o JSON. O
 inventário estático e seu JSON ficam disponíveis na Lens; a aplicação não adiciona um launcher
 flutuante ao shell.

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

@@ -24,7 +24,7 @@ risco.
 - ações operacionais em toolbar, header de seção ou coleção densa usam `sm`;
 - ações internas de linha, célula ou campo usam `xs` ou `icon-xs`;
 - ações somente com ícone que pertencem ao chrome da superfície, como voltar e fechar, usam
-  `icon-sm`;
+  `icon`;
 - `lg` fica reservado a chamadas que deliberadamente precisam de uma área de toque maior, não a
   uma ação primária comum.
 

package/docs/adr/0016-list-collection-header-belongs-to-content.md

@@ -0,0 +1,80 @@
+# ADR 0016 — O cabeçalho da coleção pertence ao Content
+
+- **Status:** aceita.
+- **Data:** 2026-09-13.
+- **Revisa:** ADRs 0011 e 0013.
+
+## Contexto
+
+Páginas centradas em uma coleção colocavam o título no `PageIntro`, a criação na barra do
+`PageShell` e busca, filtros e atualização no `ActionList`. Essa divisão afastava a ação primária
+do recurso que ela altera e fazia o mesmo conjunto mudar de hierarquia ao ser apresentado em Page,
+Dialog ou Drawer.
+
+`Content` já oferece a estrutura pública para nomear uma região e reunir suas ações. Criar
+`ListHeader`, `ListTitle` ou equivalentes repetiria essa anatomia e sugeriria um componente genérico
+`List` que o Opus não possui. `ActionList` é o pattern orientado pela `ListAction`; busca não é a
+casca estrutural da coleção.
+
+## Decisão
+
+Uma coleção nomeada em uma página compõe `Content + ActionList`. `ContentHeader` recebe o título e
+as ações da coleção, como criar um item. `ActionList` continua responsável por busca, filtros,
+atualização, visualização, resultados, estados e paginação. `toolbarActions` fica reservado a
+operações ligadas ao recorte corrente da lista, não ao comando primário de criar.
+
+`PageHeader` representa o chrome da página: navegação e ações globais. Dentro de `PageShell`,
+esses slots são projetados na barra; `PageIntro` permanece opcional para uma introdução própria da
+página. Uma `Page` explícita mantém exatamente um heading principal: `PageTitle` em header/intro,
+`Content level={1}` ou um `PageState` ativo no body. Quando `Content` fornece esse heading, a Page
+pode conter somente `PageBody`.
+
+Na `Presentation`, uma action `list` exibida como Page materializa o título e os comandos de header
+no `Content` que envolve o `ActionList`. Em Dialog e Drawer, o título e esses comandos continuam no
+header da superfície, pois ele já está imediatamente ligado ao corpo. A definição serializável não
+muda conforme a superfície.
+
+## Consequências
+
+- criação e outras ações da coleção permanecem próximas da listagem;
+- `Content` continua sendo a única anatomia pública de região nomeada;
+- `ActionList` não ganha slots estruturais duplicados nem um componente `List` implícito;
+- o mesmo artefato de Presentation preserva sua hierarquia ao alternar entre Page, Dialog e Drawer;
+- ações da coleção ficam no extremo oposto ao título, preservando a associação sem disputar a
+  leitura do heading;
+- a criação no header de uma coleção usa botão textual `default`, sem ícone, com o rótulo
+  `Criar recurso`; comandos globais da superfície também mantêm a escala normal;
+- o diálogo de criação usa `Criar recurso` e o de edição usa `Editar recurso`, mantendo os dois
+  estados operacionais simétricos.
+
+Os títulos nomeiam a tarefa (`Criar recurso` e `Editar recurso`), enquanto a conclusão de
+formulários comuns usa `Salvar` nos dois casos. Esta é uma decisão deliberada do Opus: mantém a
+ação curta e estável quando o contexto do modal já torna o objeto e a intenção inequívocos. Ela
+especializa a recomendação genérica de repetir o resultado no botão; operações com efeito próprio
+continuam declarando outro verbo por `submitLabel`.
+
+## Alternativas consideradas
+
+### Criar uma família ActionListHeader
+
+Deixaria o vínculo nominal explícito, mas duplicaria `ContentHeader`, `ContentTitle` e
+`ContentActions` sem introduzir outra semântica. Foi descartada em favor da composição existente.
+
+### Manter a criação em toolbarActions
+
+Manteria a API atual, mas misturaria o comando primário da coleção com controles operacionais do
+recorte e reduziria sua hierarquia visual. Foi descartada.
+
+### Manter todas as ações na barra da Page
+
+Produziria uma posição constante, mas afastaria a criação da lista e faria a barra acumular
+responsabilidades locais. Foi descartada para coleções; ações realmente globais continuam nela.
+
+## Verificação
+
+- testes de `Page` cobrem `PageHeader + PageIntro + PageBody` e `PageBody` sem header;
+- `opus check` aceita essa gramática e continua rejeitando slots duplicados ou fora da família;
+- testes de `Presentation` confirmam que Page de listagem usa `Content` e mantém a barra sem a ação
+  da coleção;
+- a documentação de `ActionList` recomenda `Content` e reserva `toolbarActions` ao recorte atual;
+- consumidores validam visualmente o título e a criação junto da listagem.

package/package.json

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