@softize/opus 17.2.0 → 18.0.1

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

@@ -2,6 +2,7 @@
 name: build-opus-ui
 description: Constrói interface contract-driven com hooks, forms, listas, views e componentes de @softize/opus/ui. Use ao implementar ou alterar telas que consomem actions Opus.
 ---
+
 <!-- softize-skill-route: $model-opus-dictionary -->
 
 # Construir UI Opus
@@ -39,10 +40,15 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    paginam pela primitiva `Pagination`; selects inline de filtro têm largura fixa. Não reescrever
    esses defaults na tela.
 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.
-8. Compor superfícies pela gramática estrutural do catálogo: fora de `PageShell`, `Page` contém
-   `PageHeader` e `PageBody`; dentro dele, contém `PageIntro` e `PageBody`; `Content` contém
-   `ContentHeader` e `ContentBody`; Card, Drawer e Pane usam seus
+   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` declara o chrome,
+   `PageIntro` a introdução opcional e `PageBody` o conteúdo. Na composição explícita, declare
+   exatamente um heading principal com `PageTitle` no header/intro, `Content level={1}` ou um
+   `PageState` ativo no body;
+   dentro de `PageShell`, os slots de
+   `PageHeader` são projetados na barra. `Content` contém `ContentHeader` e `ContentBody`; Card,
+   Drawer e Pane usam seus
    respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` (`title`,
    `actions`) ou de `Content` (`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
@@ -51,24 +57,28 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 9. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
 10. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
-   responsáveis por `font-size` em `html`; medidas escaláveis da UI usam `rem` ou a escala
-   relativa do Tailwind. Reservar `px` a hairlines e compensações presas à geometria da borda,
-   com justificativa e cobertura explícitas.
-11. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
-12. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
-   `bg-card text-card-foreground` e `bg-popover text-popover-foreground`. Não depender da
-   igualdade atual com `--foreground`, porque o app pode sobrescrever cada par.
-13. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
-   `rounded-xs` a `rounded-2xl` já expressam a forma. Escolher o degrau pela escala visual:
-   detalhes e itens internos tendem a `xs`/`sm`, controles e flutuantes compactos a `md`,
-   molduras estruturais a `lg`, e superfícies principais ou modais a `xl`. Essa associação
-   orienta o default, não cria uma restrição semântica. Em aninhamento, evitar moldura dupla e
-   reduzir o raio interno; em grupos conectados, remover os raios das arestas internas. Tamanho
-   e forma permanecem eixos separados; usar `shape="pill"` quando a pílula for intencional.
-14. Distinguir uma região disponível para criação ou vínculo, representada por `Empty` com
+    responsáveis por `font-size` em `html`; medidas escaláveis da UI usam `rem` ou a escala
+    relativa do Tailwind. Reservar `px` a hairlines e compensações presas à geometria da borda,
+    com justificativa e cobertura explícitas.
+11. Em uma página centrada em coleção, compor `Content + ActionList`: título e criação ficam em
+    extremos opostos do `ContentHeader`; a criação usa botão textual `default`, sem ícone, com
+    `Criar recurso`. Busca, filtros, atualização, estados e paginação permanecem no `ActionList`.
+    Reservar `toolbarActions` a operações ligadas ao recorte atual.
+12. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
+13. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
+    `bg-card text-card-foreground` e `bg-popover text-popover-foreground`. Não depender da
+    igualdade atual com `--foreground`, porque o app pode sobrescrever cada par.
+14. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
+    `rounded-xs` a `rounded-2xl` já expressam a forma. Escolher o degrau pela escala visual:
+    detalhes e itens internos tendem a `xs`/`sm`, controles e flutuantes compactos a `md`,
+    molduras estruturais a `lg`, e superfícies principais ou modais a `xl`. Essa associação
+    orienta o default, não cria uma restrição semântica. Em aninhamento, evitar moldura dupla e
+    reduzir o raio interno; em grupos conectados, remover os raios das arestas internas. Tamanho
+    e forma permanecem eixos separados; usar `shape="pill"` quando a pílula for intencional.
+15. Distinguir uma região disponível para criação ou vínculo, representada por `Empty` com
     moldura tracejada, de um resultado vazio dentro de uma estrutura existente, que preserva
     a moldura sólida dessa estrutura.
-15. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
+16. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
 
 ## Verificação
 

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

@@ -4,11 +4,17 @@
 - Não dispara: “Ajuste o CSS de um e-mail estático.”
 - Execução: implementar uma lista com modal roteável e provar loading, erro, vazio e back.
 - Execução estrutural: montar uma página de relatório isolada com `Page > PageHeader + PageBody`,
-  outra em `PageShell` com `Page > PageIntro + PageBody`, uma seção `Content > ContentHeader +
-  ContentBody`, `ActionFilterBar` separado do renderer, `ItemGroup` para
+  outra em `PageShell` com `Page > PageHeader? + PageIntro? + PageBody`, garantindo exatamente um
+  `PageTitle` entre header/intro, e uma coleção nomeada com
+  `Content > ContentHeader + ContentBody > ActionList`. Provar que criação fica em
+  `ContentActions`, no extremo oposto ao título, como botão textual `default` sem ícone e com
+  `Criar recurso`, enquanto uma operação dependente do recorte usa `toolbarActions`; incluir
+  `ActionFilterBar` separado do renderer, `ItemGroup` para
   uma coleção secundária e um `ActionFormDialog`; provar teto padrão de `80rem`, hierarquia por
   `level`, vazio estrutural sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento
-  inferido e cancelamento `ghost` no modal.
+  inferido e cancelamento `outline` no footer 50/50 do modal.
+- Execução roteável: declarar Page, criação e edição com `Presentation.route`; provar deep link,
+  hidratação do registro, fechamento para a lista e projeção integral no manifest.
 - Execução abreviada: montar outra página com `<Page title actions>` e uma seção com
   `<Content title description actions>`, provando que ambas produzem a mesma anatomia e que o lint
   rejeita a mistura entre props abreviadas e headers explícitos.

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

@@ -4,29 +4,33 @@
 - Campos, labels, mensagens e invalidações pertencem ao contrato quando são parte da
   operação, não a uma tela isolada.
 - URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
-- `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Fora de
-  `PageShell`, sua forma explícita é `Page > PageHeader (PageBack? | PageNavigation?, PageTitle,
-PageActions?) + PageBody`; `title` e `actions` no próprio `Page` são a abreviação
-  para o caso direto.
+- Uma `Presentation` que representa esse estado declara `route.path` e `route.surface`. Rotas com
+  parâmetro podem declarar `route.record` para hidratar o item a partir de uma Presentation de
+  lista; não reconstruir essa decisão com condicionais no componente da página.
+- `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
+  explícita exige `PageBody`, exatamente um heading principal e aceita `PageHeader`, `PageIntro` e
+  `PageFooter`. Declare esse heading com `PageTitle` em header/intro, `Content level={1}` ou um
+  `PageState` ativo no body. `PageHeader`
+  declara chrome; `PageIntro` declara uma introdução opcional no conteúdo. `title` e `actions` no
+  próprio `Page` são a abreviação para o caso direto.
   Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
   real de largura; não reconstruir esse container em cada rota.
-- `PageIntro` é a região estrutural do título quando a página está em `PageShell`; fora dele, pode
-  substituir `PageHeader` quando o conteúdo precisar começar por uma introdução.
-- `PageHeader` é a região de cabeçalho dentro de uma `Page` isolada e organiza navegação, título e
-  ações na mesma linha. Em uma subpágina simples, `PageBack` recebe o destino pai explícito e aparece
+- `PageIntro` é a região estrutural de uma introdução no conteúdo. Pode coexistir com
+  `PageHeader`, porque as duas regiões têm papéis diferentes.
+- `PageHeader` declara navegação e ações globais; fora do shell também pode carregar o título. Em
+  uma subpágina simples, `PageBack` recebe o destino pai explícito e aparece
   antes do título como controle somente com ícone. Para mais de um ancestral relevante, use
   `Breadcrumb` dentro de `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome
   paralelo para uma `Page`. `PageActionsTarget` fica reservado a workspaces imersivos que já
   possuam chrome próprio.
 - Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
-  O shell é o único responsável pela barra: fornece `navigation`; a `Page` descendente continua
-  declarando `title` e `actions`. O Opus mantém a barra de `3rem`, projeta ações nela e inicia o
-  conteúdo com o título em `PageIntro`.
+  O shell é o único responsável pela barra e projeta os slots de `PageHeader`; `PageIntro` permanece
+  no conteúdo.
   Ações com texto na barra usam o tamanho `default`, como as ações de footer de Dialog e Drawer;
-  ações somente com ícone de chrome usam `icon-sm`. O tamanho `sm` fica para ações operacionais em
+  ações somente com ícone de chrome usam `icon`. O tamanho `sm` fica para ações operacionais em
   toolbar, seção ou coleção densa, e `xs`/`icon-xs` para ações internas de linha ou célula. Contexto
-  e variante resolvem a hierarquia visual sem alterar essa medida. Na forma explícita dentro do
-  shell, use `Page > PageIntro (PageNavigation?, PageTitle, PageActions?) + PageBody`. Não monte
+  e variante resolvem a hierarquia visual sem alterar essa medida. Em uma coleção, a ação de
+  criar usa botão textual `default`, sem ícone, no extremo oposto do `ContentHeader`. Não monte
   `PaneHeader`, portal ou seletor global para reconstruir essa composição.
 - `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
   forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
@@ -41,8 +45,13 @@ PageActions?) + PageBody`; `title` e `actions` no próprio `Page` são a abrevia
 - `Content` delimita uma seção e segue a mesma anatomia: `Content > ContentHeader (ContentTitle,
 ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
   solto. `title`, `description`, `count` e `actions` no `Content` são a abreviação para o caso
-  direto e não podem ser misturados ao header explícito. `level` preserva a hierarquia semântica
-  do heading.
+  direto e não podem ser misturados ao header explícito. Na variante `page`, ações da coleção ficam
+  no extremo oposto ao título; a criação usa botão textual `default`, sem ícone, com `Criar recurso`.
+  O diálogo de criação usa `Criar recurso` e o de edição, `Editar recurso`. `level` preserva a
+  hierarquia semântica do heading.
+- Uma página centrada em coleção compõe `Content + ActionList`. O `ContentHeader` recebe título e
+  criação; o `ActionList` mantém busca, filtros, atualização, resultados, estados e paginação.
+  `toolbarActions` fica reservado a operações que dependem do recorte atual.
 - Card, Drawer e Pane nomeiam a região principal como `CardBody`, `DrawerBody` e `PaneBody`.
   `*Content` permanece reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma
   estrutura, como `DialogContent`, `PopoverContent` e `TabsContent`.
@@ -64,8 +73,11 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
 - `ActionForm` mantém validação, execução e estados do contrato nos dois modos: sem `children`,
   renderiza os campos declarados; com `children`, o consumidor diagrama `ActionFormField` e
   controles customizados pelo contexto. `ActionFormCard` e `ActionFormDialog` acrescentam a
-  casca; não duplicar o form para obter card ou modal. Cancelamento em forms, confirmações e
-  modais usa `ghost`, deixando o destaque visual para a ação principal.
+  casca; não duplicar o form para obter card ou modal. Cancelamento usa `ghost` por padrão. Quando
+  um formulário modal divide o footer igualmente entre duas ações, o cancelamento usa `outline` e
+  a ação principal mantém `solid`. Criação e edição comuns preservam o rótulo padrão `Salvar`;
+  `submitLabel` fica para efeitos específicos, como `Renomear` ou `Criar nova versão`. Em
+  `Dialog mode="alert"`, a saída segura também usa `outline`.
 - Cabeçalhos de `Dialog` e `Drawer` nomeiam a superfície com o título e organizam suas ações. O close
   padrão é uma action ghost somente com ícone no final do header; não crie uma posição flutuante
   alternativa. Não preencher uma segunda linha por hábito. Consequência, restrição ou instrução que

package/src/core/presentation.ts

@@ -108,11 +108,33 @@ const presentationBodySchema = z
   })
   .strict();
 
+const presentationRouteRecordSchema = z
+  .object({
+    presentation: identifierSchema,
+    param: identifierSchema,
+    field: z.string().min(1),
+  })
+  .strict();
+
+export const presentationRouteSchema = z
+  .object({
+    path: z
+      .string()
+      .regex(
+        /^\/(?:[a-z0-9-]+|:[a-z][a-z0-9]*)(?:\/(?:[a-z0-9-]+|:[a-z][a-z0-9]*))*$/,
+      ),
+    surface: presentationSurfaceSchema,
+    record: presentationRouteRecordSchema.optional(),
+  })
+  .strict();
+export type PresentationRoute = z.infer<typeof presentationRouteSchema>;
+
 export const presentationSchema = z
   .object({
     schemaVersion: z.literal(1),
     id: identifierSchema,
     title: z.string().min(1),
+    route: presentationRouteSchema.optional(),
     body: presentationBodySchema,
     actions: z.array(presentationCommandSchema).default([]),
   })
@@ -121,12 +143,15 @@ export const presentationSchema = z
 export type PresentationDefinition = z.infer<typeof presentationSchema>;
 export type PresentationDefinitionInput = z.input<typeof presentationSchema>;
 export type PresentationCommand = PresentationDefinition["actions"][number];
-type DefaultedProperty<Input, Key extends PropertyKey, Output> =
-  Key extends keyof Input
-    ? undefined extends Input[Key]
-      ? Exclude<Input[Key], undefined> | Output
-      : Input[Key] & Output
-    : Output;
+type DefaultedProperty<
+  Input,
+  Key extends PropertyKey,
+  Output,
+> = Key extends keyof Input
+  ? undefined extends Input[Key]
+    ? Exclude<Input[Key], undefined> | Output
+    : Input[Key] & Output
+  : Output;
 type NavigateEffect = Extract<PresentationEffect, { effect: "navigate" }>;
 type DefinedPresentationEffect<Effect> = Effect extends { effect: "navigate" }
   ? Omit<Effect, "input" | "mode"> &
@@ -135,18 +160,20 @@ type DefinedPresentationEffect<Effect> = Effect extends { effect: "navigate" }
         mode: DefaultedProperty<Effect, "mode", NavigateEffect["mode"]>;
       }
   : Effect & PresentationEffect;
-type DefinedPresentationEffects<Input, Key extends PropertyKey> =
-  Key extends keyof Input
-    ? undefined extends Input[Key]
-      ? PresentationCommand["onSuccess"]
-      : Input[Key] extends readonly unknown[]
-        ? {
-            -readonly [Index in keyof Input[Key]]: DefinedPresentationEffect<
-              Input[Key][Index]
-            >;
-          }
-        : PresentationCommand["onSuccess"]
-    : PresentationCommand["onSuccess"];
+type DefinedPresentationEffects<
+  Input,
+  Key extends PropertyKey,
+> = Key extends keyof Input
+  ? undefined extends Input[Key]
+    ? PresentationCommand["onSuccess"]
+    : Input[Key] extends readonly unknown[]
+      ? {
+          -readonly [Index in keyof Input[Key]]: DefinedPresentationEffect<
+            Input[Key][Index]
+          >;
+        }
+      : PresentationCommand["onSuccess"]
+  : PresentationCommand["onSuccess"];
 type PresentationOpen = NonNullable<PresentationDefinition["body"]["open"]>;
 type DefinedPresentationOpen<Open> = Open extends object
   ? Omit<Open, "input"> &
@@ -171,7 +198,11 @@ type DefinedPresentationBody<Body extends PresentationDefinitionInput["body"]> =
 type DefinedPresentationCommand<Command> = Command extends object
   ? Omit<Command, "input" | "blocking" | "onSuccess"> &
       Omit<PresentationCommand, "input" | "blocking" | "onSuccess"> & {
-        input: DefaultedProperty<Command, "input", PresentationCommand["input"]>;
+        input: DefaultedProperty<
+          Command,
+          "input",
+          PresentationCommand["input"]
+        >;
         blocking: DefaultedProperty<
           Command,
           "blocking",
@@ -241,6 +272,84 @@ export interface PresentationActionRegistry {
   readonly [name: string]: ActionContract;
 }
 
+export interface PresentationRouteMatch {
+  definition: PresentationDefinition;
+  input: Record<string, string>;
+}
+
+function routeSegments(path: string): string[] {
+  return path.split("/").filter(Boolean);
+}
+
+function routePattern(path: string): string {
+  return routeSegments(path)
+    .map((segment) => (segment.startsWith(":") ? ":" : segment))
+    .join("/");
+}
+
+function decodeRouteSegment(segment: string): string | null {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+}
+
+export function matchPresentationRoute(
+  definitions: readonly PresentationDefinition[],
+  pathname: string,
+): PresentationRouteMatch | null {
+  const actual = routeSegments(pathname);
+  const matches = definitions.flatMap((definition) => {
+    if (definition.route === undefined) return [];
+    const pattern = routeSegments(definition.route.path);
+    if (pattern.length !== actual.length) return [];
+    const input: Record<string, string> = {};
+    for (let index = 0; index < pattern.length; index += 1) {
+      const expected = pattern[index]!;
+      const received = actual[index]!;
+      if (expected.startsWith(":")) {
+        const decoded = decodeRouteSegment(received);
+        if (decoded === null) return [];
+        input[expected.slice(1)] = decoded;
+      }
+      else if (expected !== received) return [];
+    }
+    return [{ definition, input }];
+  });
+  matches.sort((left, right) => {
+    const staticCount = (entry: PresentationRouteMatch) =>
+      routeSegments(entry.definition.route!.path).filter(
+        (segment) => !segment.startsWith(":"),
+      ).length;
+    return staticCount(right) - staticCount(left);
+  });
+  return matches[0] ?? null;
+}
+
+export function pathForPresentationInvocation(
+  definitions: readonly PresentationDefinition[],
+  invocation: PresentationInvocation,
+): string {
+  const definition = definitions.find(
+    (candidate) => candidate.id === invocation.presentationId,
+  );
+  if (definition?.route === undefined) {
+    throw new Error(
+      `Presentation “${invocation.presentationId}” não declara route.`,
+    );
+  }
+  return definition.route.path.replace(/:([a-z][a-z0-9]*)/g, (_, param) => {
+    const value = invocation.input[param];
+    if (typeof value !== "string" || value.length === 0) {
+      throw new Error(
+        `A rota de “${invocation.presentationId}” exige o parâmetro “${param}”.`,
+      );
+    }
+    return encodeURIComponent(value);
+  });
+}
+
 export interface PresentationBindingContext {
   route?: Readonly<Record<string, unknown>>;
   record?: Readonly<Record<string, unknown>>;
@@ -254,7 +363,9 @@ export interface PresentationBindingContext {
 export function definePresentation<const T extends PresentationDefinitionInput>(
   definition: T,
 ): DefinedPresentation<T> {
-  return presentationSchema.parse(definition) as unknown as DefinedPresentation<T>;
+  return presentationSchema.parse(
+    definition,
+  ) as unknown as DefinedPresentation<T>;
 }
 
 export function definePresentationInvocation(
@@ -314,6 +425,7 @@ export function applyPresentationEffects(
   invocation: PresentationInvocation,
   effects: readonly PresentationEffectInput[],
   context: PresentationBindingContext = {},
+  definitions: readonly PresentationDefinition[] = [],
 ): PresentationTransition {
   let current: PresentationInvocation | null = invocation;
   const refresh: Array<string | null> = [];
@@ -340,11 +452,15 @@ export function applyPresentationEffects(
       if (current === null) exit = "back";
       continue;
     }
+    const targetDefinition = definitions.find(
+      (definition) => definition.id === effect.presentation,
+    );
     current = openPresentation(
       current,
       {
         presentationId: effect.presentation,
-        surface: effect.surface ?? current.surface,
+        surface:
+          effect.surface ?? targetDefinition?.route?.surface ?? current.surface,
         input: resolvePresentationBindings(effect.input, context) as Record<
           string,
           PresentationJsonValue
@@ -404,6 +520,7 @@ export function validatePresentations(
   const parsed = z.array(presentationSchema).parse(input);
   const byId = new Map<string, PresentationDefinition>();
   const problems: string[] = [];
+  const routePatterns = new Set<string>();
 
   for (const presentation of parsed) {
     if (byId.has(presentation.id))
@@ -447,7 +564,9 @@ export function validatePresentations(
         bodyAction.kind !== "form" &&
         presentation.body.submitLabel !== undefined
       ) {
-        problems.push(`SubmitLabel só pode ser declarado para uma action form.`);
+        problems.push(
+          `SubmitLabel só pode ser declarado para uma action form.`,
+        );
       }
     }
 
@@ -476,6 +595,44 @@ export function validatePresentations(
   }
 
   for (const presentation of parsed) {
+    if (presentation.route !== undefined) {
+      const pattern = routePattern(presentation.route.path);
+      if (routePatterns.has(pattern)) {
+        problems.push(
+          `A route “${presentation.route.path}” conflita com outra route declarada.`,
+        );
+      }
+      routePatterns.add(pattern);
+      const record = presentation.route.record;
+      if (record !== undefined) {
+        if (!presentation.route.path.includes(`:${record.param}`)) {
+          problems.push(
+            `A route de “${presentation.id}” não declara o parâmetro “${record.param}” usado por record.`,
+          );
+        }
+        const source = byId.get(record.presentation);
+        if (source === undefined) {
+          problems.push(
+            `A route de “${presentation.id}” consulta a Presentation inexistente “${record.presentation}”.`,
+          );
+        } else if (actions[source.body.action]?.kind !== "list") {
+          problems.push(
+            `A route de “${presentation.id}” exige que “${record.presentation}” tenha uma list action no body.`,
+          );
+        } else {
+          const sourceAction = actions[source.body.action];
+          const output = unwrapObjectSchema(sourceAction.output);
+          if (
+            output !== null &&
+            !(record.field in (output.shape as Record<string, z.ZodTypeAny>))
+          ) {
+            problems.push(
+              `A route de “${presentation.id}” consulta o campo inexistente “${record.field}” na saída de “${source.body.action}”.`,
+            );
+          }
+        }
+      }
+    }
     const open = presentation.body.open;
     if (open !== undefined && !byId.has(open.presentation)) {
       problems.push(
@@ -483,6 +640,15 @@ export function validatePresentations(
       );
     } else if (open !== undefined) {
       const target = byId.get(open.presentation);
+      if (
+        open.surface !== undefined &&
+        target?.route !== undefined &&
+        open.surface !== target.route.surface
+      ) {
+        problems.push(
+          `A lista “${presentation.id}” abre “${target.id}” como ${open.surface}, mas sua route declara ${target.route.surface}.`,
+        );
+      }
       const action =
         target === undefined ? undefined : actions[target.body.action];
       if (action !== undefined) {
@@ -503,6 +669,15 @@ export function validatePresentations(
         );
         continue;
       }
+      if (
+        effect.surface !== undefined &&
+        target.route !== undefined &&
+        effect.surface !== target.route.surface
+      ) {
+        problems.push(
+          `O body de “${presentation.id}” navega para “${target.id}” como ${effect.surface}, mas sua route declara ${target.route.surface}.`,
+        );
+      }
       const action = actions[target.body.action];
       if (action !== undefined) {
         validateActionBindings(
@@ -522,6 +697,15 @@ export function validatePresentations(
               `A action “${command.action}” navega para a Presentation inexistente “${effect.presentation}”.`,
             );
           } else {
+            if (
+              effect.surface !== undefined &&
+              target.route !== undefined &&
+              effect.surface !== target.route.surface
+            ) {
+              problems.push(
+                `A action “${command.action}” navega para “${target.id}” como ${effect.surface}, mas sua route declara ${target.route.surface}.`,
+              );
+            }
             const action = actions[target.body.action];
             if (action !== undefined) {
               validateActionBindings(
@@ -544,6 +728,14 @@ export function validatePresentations(
         problems.push(
           `A Presentation “${target.id}” usa “${target.body.action}”, mas foi aberta por “${command.action}”.`,
         );
+      } else if (
+        command.target.surface !== undefined &&
+        target.route !== undefined &&
+        command.target.surface !== target.route.surface
+      ) {
+        problems.push(
+          `A action “${command.action}” abre “${target.id}” como ${command.target.surface}, mas sua route declara ${target.route.surface}.`,
+        );
       }
     }
   }
@@ -555,7 +747,11 @@ export function validatePresentations(
 function unwrapObjectSchema(schema: unknown): z.ZodObject<any> | null {
   let current = schema;
   const visited = new Set<unknown>();
-  while (current !== null && typeof current === "object" && !visited.has(current)) {
+  while (
+    current !== null &&
+    typeof current === "object" &&
+    !visited.has(current)
+  ) {
     visited.add(current);
     if (current instanceof z.ZodObject) return current;
     const definition = (current as { _def?: Record<string, unknown> })._def;
@@ -583,7 +779,10 @@ function validateActionBindings(
       continue;
     }
     const binding = bindings[key];
-    if (binding?.source === "fixed" && !field.safeParse(binding.value).success) {
+    if (
+      binding?.source === "fixed" &&
+      !field.safeParse(binding.value).success
+    ) {
       problems.push(
         `O valor fixo de “${path}.${key}” é incompatível com o input da action “${action.name}”.`,
       );

package/src/core/runtime.ts

@@ -817,6 +817,9 @@ export class Runtime {
       if (cfg === null) continue
       tools.push({
         name: action.name,
+        ...(action.label !== undefined
+          ? { title: typeof action.label === 'string' ? action.label : action.label.default }
+          : {}),
         description: cfg.description ?? action.description ?? action.name,
         inputSchema: action.input,
         metadata: { dataProducts: [...(this.actionDataProducts.get(action.name) ?? [])].sort() },

package/src/core/types.ts

@@ -1259,6 +1259,8 @@ export interface AiAdapter extends Adapter {
 /** Uma tool exposta ao modelo: nome da action + descrição + JSON Schema do input. */
 export interface AiTool {
   name: string
+  /** Nome legível da tool; preserva `name` como identificador técnico estável. */
+  title?: string
   description: string
   inputSchema: unknown
   /** Metadados de governança para o host; não fazem parte do prompt nem concedem acesso. */

package/src/mcp/index.ts

@@ -44,6 +44,7 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
   server.setRequestHandler(ListToolsRequestSchema, () => ({
     tools: runtime.aiTools().map((t) => ({
       name: t.name,
+      ...(t.title !== undefined ? { title: t.title } : {}),
       description: t.description,
       inputSchema: toJsonSchema(t.inputSchema) as { type: 'object' },
       _meta: { 'com.softize.opus/data-products': t.metadata?.dataProducts ?? [] },

package/src/ui/components/patterns/action-form-card.tsx

@@ -13,6 +13,7 @@ import {
   CardTitle,
 } from "../primitives/card.tsx";
 import { ActionForm, type ActionFormProps } from "./form.tsx";
+import { ButtonGroup } from "../primitives/button-group.tsx";
 
 export interface ActionFormCardProps<
   TInput extends Record<string, unknown>,
@@ -46,7 +47,13 @@ export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
         {...rest}
         body={(fields) => <CardBody>{fields}</CardBody>}
         footer={(actions) => (
-          <CardFooter className="justify-end">{actions}</CardFooter>
+          <CardFooter className="justify-end">
+            {rest.onCancel === undefined ? (
+              actions
+            ) : (
+              <ButtonGroup mode="spaced">{actions}</ButtonGroup>
+            )}
+          </CardFooter>
         )}
       />
     </Card>