@softize/opus 20.0.0 → 21.0.0

package/src/core/schedules.ts

@@ -11,8 +11,9 @@
  *   - Schedule = tempo dispara
  *
  * Runtime registra no SchedulerAdapter no `start()`. Quando o tempo
- * configurado bate, o scheduler chama `runtime.execute(action, input, ctx)`
- * com `ctx.provenance = { kind: 'schedule', scheduleName }`.
+ * configurado bate, o runtime executa a action como o sistema, com
+ * `ctx.provenance = { kind: 'schedule', scheduleName }`; a action precisa
+ * declarar `automatable: true` (ou `public: true`). Ver ADR 0028.
  *
  * Ver §16 do protocolo.
  */

package/src/core/types.ts

@@ -255,10 +255,11 @@ export interface User {
 export type CanFn = (permission: string, resource?: unknown) => boolean | Promise<boolean>
 
 /**
- * Função que emite um `DomainEvent`. Em `ActionContext.emit`, publica o evento pelo
- * `EventBusAdapter`. Em `ReactionContext.emit`, descarta o evento sem publicá-lo, porque
- * reactions ainda não encadeiam outras por evento; com `config.dev` ativo, cada descarte
- * registra o aviso `runtime.reaction_emit_ignored`.
+ * Função que emite um `DomainEvent` pelo `EventBusAdapter`. Em `ActionContext.emit`, publica
+ * qualquer evento; um evento fora do `emits` da action gera aviso com
+ * `config.warnUndeclaredEmits`. Em `ReactionContext.emit`, publica somente eventos listados no
+ * `emits` da reaction e descarta os demais (aviso `runtime.reaction_emit_ignored`); a cadeia de
+ * reactions para em `config.maxReactionDepth`. Ver ADR 0027.
  */
 export type EmitFn = <T = unknown>(
   event: string,
@@ -295,7 +296,7 @@ export interface ReactionContext {
   tenantId: string | null
   db: unknown
   log: Logger
-  /** Descarta o evento sem publicá-lo: reactions ainda não encadeiam outras. Ver `EmitFn`. */
+  /** Publica os eventos declarados em `emits` da reaction; descarta os demais. Ver `EmitFn`. */
   emit: EmitFn
   storage: StorageAdapter | null
   cache: CacheAdapter | null
@@ -303,6 +304,12 @@ export interface ReactionContext {
   provenance: Provenance
   trace?: TraceContext
   meta: Record<string, unknown>
+  /**
+   * Abortado quando a tentativa excede o `timeout` da reaction. O runtime sempre preenche o
+   * campo; ele é opcional para quem monta o contexto à mão em testes. Um handler que ignora o
+   * sinal continua executando depois do timeout. Ver ADR 0026.
+   */
+  signal?: AbortSignal
 }
 
 // =============================================================================
@@ -387,11 +394,26 @@ export interface DomainEvent<T = unknown> {
   actor: { id: string | null; type?: 'user' | 'system' | 'integration' }
   tenant?: string | null
   data: T
+  /**
+   * A action que iniciou a cadeia. Um evento publicado por reaction herda o `source` do evento
+   * que ela processava, e `provenance.sourceActionId` continua batendo com o audit da action.
+   */
   source: {
     action: string
     actionId: string
     correlation?: string
   }
+  /**
+   * Presente só em evento publicado por reaction: qual reaction o publicou, a partir de qual
+   * evento e a que profundidade da cadeia (1 = primeira reaction depois da action). Evento
+   * emitido por action não tem `cause` e está na profundidade 0. Ver ADR 0027.
+   */
+  cause?: {
+    reaction: string
+    eventId: string
+    eventType: string
+    depth: number
+  }
   trace?: TraceContext
   meta?: Record<string, unknown>
 }
@@ -434,6 +456,12 @@ export interface JobSpec {
     requestId?: string
     trace?: TraceContext
     originalProvenance?: Provenance
+    /**
+     * Presente quando o próprio runtime enfileirou o job numa execução do sistema (o disparo de um
+     * schedule). O worker só reconstrói a identidade de sistema com esta marca; a provenance não
+     * basta, porque vem do chamador. Ver ADR 0028.
+     */
+    system?: true
   }
   config: {
     queue?: string
@@ -828,6 +856,11 @@ export interface ActionBase<In, Out, ParsedIn = In> {
 
   // — Integração —
   ai?: boolean | AIConfig
+  /**
+   * Aceita execução pelo sistema, sem usuário, quando um schedule a dispara. Sem este opt-in,
+   * a execução pelo sistema de uma action não pública termina em `auth.system_forbidden`. Não
+   * abre a action a chamadores anônimos. Ver `isSystemActor` e ADR 0028.
+   */
   automatable?: boolean
   internal?: boolean
   successStatus?: number
@@ -950,9 +983,17 @@ export interface ReactionDef<Event = unknown> {
 
   handler: ReactionHandlerFn<Event>
 
+  /** Eventos que o handler pode publicar com `ctx.emit`; os demais são descartados (ADR 0027). */
+  emits?: string[]
+
+  // — Política de entrega (ADR 0026) —
+  /** Total de execuções do handler, com espera opcional entre elas. Sem `retry`, roda uma vez. */
   retry?: { attempts: number; backoff?: BackoffSpec }
+  /** Prazo de cada tentativa, em ms; ao vencer, aborta `ctx.signal`. */
   timeout?: number
+  /** Chave de idempotência: evento com chave já vista em `config.dedupCacheTtl` é descartado. */
   dedup?: (event: DomainEvent<Event>) => string
+  /** Máximo de tentativas simultâneas desta reaction. Padrão 1. */
   concurrency?: number
 
   authorize?: (
@@ -1419,8 +1460,8 @@ export interface SchedulerAdapter extends Adapter {
    * Registra um schedule e retorna função pra cancelar. Chamado pelo
    * runtime no `start()` pra cada schedule.
    *
-   * Quando o tempo bater, o adapter chama `fire()` que internamente
-   * invoca runtime.execute() com provenance schedule.
+   * Quando o tempo bater, o adapter chama `fire()`, e o runtime executa a
+   * action como o sistema, com provenance schedule (ADR 0028).
    */
   register(spec: ScheduleDef, fire: () => Promise<void> | void): Unsubscribe
 }
@@ -1453,6 +1494,8 @@ export interface RuntimeConfig {
 
   // — Resiliência —
   dedupCacheTtl?: number
+  /** Chaves concluídas que o dedup guarda por reaction; acima disso, descarta a mais antiga. Padrão 10.000. */
+  dedupCacheMaxEntries?: number
   defaultRetry?: { attempts: number; backoff?: BackoffSpec }
 
   // — i18n —
@@ -1464,4 +1507,6 @@ export interface RuntimeConfig {
   // — Limites —
   maxConcurrentActions?: number
   maxConcurrentReactions?: number
+  /** Saltos de reaction que uma cadeia de eventos pode dar. Padrão 5 (ADR 0027). */
+  maxReactionDepth?: number
 }

package/src/testing/index.ts

@@ -9,10 +9,11 @@
  *     capturado em `emitted`, log capturado em `logged`, `can` configurável,
  *     storage plugável (ex.: `memStorage()`).
  *   • `runAction(action, input)` — o MESMO pipeline do `runtime.execute`, em unidade:
- *     valida input → gate `public` → `authorize` (string DSL ou closure, semântica
- *     idêntica, `loaded` incluso) → handler → valida output (pulado em `list`, como
- *     no runtime). Falha estoura o MESMO `ActionError` tipado do runtime
- *     (`validation.invalid_input`, `auth.unauthenticated`, `auth.forbidden`…).
+ *     valida input → gate de autenticação (`public`, usuário ou sistema `automatable`) →
+ *     `authorize` (string DSL ou closure, semântica idêntica, `loaded` incluso) → handler →
+ *     valida output (pulado em `list`, como no runtime). Falha estoura o MESMO
+ *     `ActionError` tipado do runtime (`validation.invalid_input`, `auth.unauthenticated`,
+ *     `auth.system_forbidden`, `auth.forbidden`…). A opção `schedule` executa como o sistema.
  *     Em `OPUS_MODE=design` roteia pro `mockHandler` como o runtime — contrato puro
  *     (sem handler) é testável em design; fora dele, erro claro (`testing.no_handler`).
  *   • `memStorage()` — StorageAdapter em memória pra testar handler que anexa
@@ -31,7 +32,7 @@ import { normalizeKey } from '../storage/index.ts'
 import { error } from '../core/errors.ts'
 // Import direto do runtime (fora do index público): a régua handler×mockHandler
 // tem UMA fonte — o harness nunca pode divergir do execute().
-import { isOpusDesignMode } from '../core/runtime.ts'
+import { assertAuthenticated, isOpusDesignMode, markSystemActor } from '../core/runtime.ts'
 import type {
   ActionContext,
   ActionKind,
@@ -201,6 +202,7 @@ export interface TestableAction<In, Out, ParsedIn = In> {
   name: string
   kind?: ActionKind
   public?: boolean
+  automatable?: boolean
   authorize?: AuthorizeSpec<ParsedIn>
   input: Schema<In, ParsedIn>
   output: Schema<Out> | Schema<unknown, Out>
@@ -215,6 +217,7 @@ export interface TestableListAction<In, Item, ParsedIn = In> {
   name: string
   kind: 'list'
   public?: boolean
+  automatable?: boolean
   authorize?: AuthorizeSpec<ParsedIn>
   input: Schema<In, ParsedIn>
   output: Schema<Item> | Schema<unknown, Item>
@@ -233,6 +236,12 @@ export interface TestableListAction<In, Item, ParsedIn = In> {
 export interface RunActionOptions extends TestContextOptions {
   /** Substitui os loaders (não rodam em unidade): vai pro handler e pro evalCtx do authorize. */
   loaded?: Record<string, unknown>
+  /**
+   * Executa como o sistema, no disparo do schedule com este nome: `user` é `null`, `can` nega
+   * tudo, a provenance é `schedule` e `isSystemActor(ctx)` responde `true`. Como no runtime, a
+   * action precisa ser `automatable` (ou `public`); senão, `auth.system_forbidden`.
+   */
+  schedule?: string
 }
 
 export interface RunActionResult<Out> extends TestContext {
@@ -261,7 +270,7 @@ async function validate<T>(
 
 /**
  * Roda uma action em UNIDADE com o pipeline do `runtime.execute`: valida input →
- * gate `public` → authorize → handler → valida output. Sucesso devolve o output
+ * gate de autenticação → authorize → handler → valida output. Sucesso devolve o output
  * validado + o contexto observável (`emitted`, `logged`); falha estoura o mesmo
  * `ActionError` do runtime — afirme com `expect(...).rejects`.
  *
@@ -284,19 +293,21 @@ export async function runAction<In, Out, ParsedIn = In>(
   input: unknown,
   options: RunActionOptions = {},
 ): Promise<RunActionResult<Out>> {
-  const t = testContext(options)
+  const schedule = options.schedule
+  const t = testContext(
+    schedule === undefined ? options : { ...options, user: null, can: () => false },
+  )
   const { ctx } = t
+  if (schedule !== undefined) {
+    ctx.provenance = { kind: 'schedule', scheduleName: schedule }
+    markSystemActor(ctx)
+  }
   const loaded = options.loaded
 
   const parsed = await validate<ParsedIn>(action.input, input, 'input')
 
-  if (action.public !== true && ctx.user === null) {
-    throw error({
-      code: 'auth.unauthenticated',
-      category: 'authentication',
-      message: 'Autenticação necessária',
-    })
-  }
+  // O mesmo gate do runtime: pública, com usuário ou, pelo sistema, `automatable`.
+  assertAuthenticated(action, ctx)
 
   if (action.authorize !== undefined) {
     const spec = action.authorize

package/src/ui/components/patterns/content-header.tsx

@@ -10,9 +10,14 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../../lib/cn.ts";
+import { IconTile, type IconTileProps } from "../primitives/icon-tile.tsx";
 import { fillRegionClassName, useFillRegion } from "./fill-region.ts";
 import { headingTags } from "./heading-level.ts";
 import { usePageHeadingPresence } from "./page-heading-context.tsx";
+import {
+  SurfaceMedia,
+  type SurfaceMediaProps,
+} from "./surface-media.tsx";
 import {
   SurfaceHeader,
   surfaceHeaderClasses,
@@ -59,7 +64,8 @@ interface ContentSectionBaseProps
     Omit<ComponentProps<"section">, "children" | "title"> {
   /** Elemento semântico da região. */
   as?: "section";
-  frameVariant?: "default";
+  /** Tratamento visual da moldura: contínua (default) ou integrada ao header. */
+  frameVariant?: ContentFrameVariant;
   /** Nível semântico do heading, independente de seu destaque visual. */
   level?: ContentHeaderLevel;
 }
@@ -78,6 +84,8 @@ interface ContentFieldsetBaseProps
 
 interface ContentSectionShorthandProps extends ContentSectionBaseProps {
   title: ReactNode;
+  /** Ícone ou imagem que identifica a região, antes do título. */
+  media?: ReactNode;
   /** Total de itens ao lado do título da seção. A página não carrega contador (ADR 0009). */
   count?: number;
   description?: ReactNode;
@@ -87,6 +95,8 @@ interface ContentSectionShorthandProps extends ContentSectionBaseProps {
 
 interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
   title: ReactNode;
+  /** Ícone ou imagem decorativa que acompanha o título dentro da legenda. */
+  media?: ReactNode;
   count?: never;
   description?: never;
   actions?: never;
@@ -95,6 +105,7 @@ interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
 
 interface ContentComposedProps {
   title?: never;
+  media?: never;
   count?: never;
   description?: never;
   actions?: never;
@@ -111,6 +122,7 @@ export type ContentProps =
 export function Content({
   as = "section",
   title,
+  media,
   count,
   description,
   actions,
@@ -164,6 +176,7 @@ export function Content({
   const anatomy = shorthand ? (
     <>
       <ContentHeader>
+        {hasContentMedia(media) && <ContentMedia>{media}</ContentMedia>}
         <ContentTitle>{title}</ContentTitle>
         {count !== undefined && <ContentMeta>{count}</ContentMeta>}
         {description !== undefined && (
@@ -214,7 +227,12 @@ export function Content({
           aria-labelledby={ariaLabelledBy}
           className={cn(
             "space-y-3",
-            framed && "rounded-lg border border-border p-4",
+            framed &&
+              frameVariant === "default" &&
+              "rounded-lg border border-border p-4",
+            framed &&
+              frameVariant === "legend" &&
+              "rounded-lg border border-border px-4 pb-4",
             fill.filling && fillRegionClassName,
             className,
           )}
@@ -244,20 +262,15 @@ export function ContentHeader({
     "Content",
   );
   if (content.element === "fieldset") {
-    const nodes = Children.toArray(children);
-    if (
-      nodes.length !== 1 ||
-      !isValidElement(nodes[0]) ||
-      nodes[0].type !== ContentTitle
-    ) {
-      throw new Error(
-        "ContentHeader de fieldset exige somente um ContentTitle; contador, descrição e ações ficam fora da legenda.",
-      );
-    }
     return (
       <ContentHeaderContext.Provider value={content}>
-        <legend
-          data-slot="content-header"
+        <SurfaceHeader
+          as="legend"
+          name="ContentHeader"
+          slot="content"
+          slots={{ media: ContentMedia, title: ContentTitle }}
+          mediaPlacement="heading"
+          invalidMessage="ContentHeader de fieldset aceita somente ContentMedia e ContentTitle; contador, descrição e ações ficam fora da legenda."
           className={cn(
             content.framed &&
               content.frameVariant === "default" &&
@@ -270,7 +283,7 @@ export function ContentHeader({
           {...props}
         >
           {children}
-        </legend>
+        </SurfaceHeader>
       </ContentHeaderContext.Provider>
     );
   }
@@ -280,12 +293,25 @@ export function ContentHeader({
         name="ContentHeader"
         slot="content"
         slots={{
+          media: ContentMedia,
           title: ContentTitle,
           count: ContentMeta,
           description: ContentDescription,
           actions: ContentActions,
         }}
+        mediaPlacement="heading"
         className={cn(
+          content.framed &&
+            content.frameVariant === "legend" &&
+            "flex items-center [&>[data-slot=content-actions]]:-mr-2 [&>[data-slot=content-actions]]:bg-[var(--surface-background,var(--background))] [&>[data-slot=content-actions]]:px-2 [&>[data-slot=content-heading]]:-ml-2 [&>[data-slot=content-heading]]:w-fit [&>[data-slot=content-heading]]:max-w-full [&>[data-slot=content-heading]]:bg-[var(--surface-background,var(--background))] [&>[data-slot=content-heading]]:px-2",
+          content.framed &&
+            content.frameVariant === "legend" &&
+            content.variant === "section" &&
+            "-mt-4 min-h-8",
+          content.framed &&
+            content.frameVariant === "legend" &&
+            content.variant === "page" &&
+            "-mt-5 min-h-10",
           content.variant === "page" &&
             "flex-row items-center justify-start gap-3",
           className,
@@ -298,6 +324,59 @@ export function ContentHeader({
   );
 }
 
+/** `null`, `false` e `undefined` não desenham mídia: uma moldura vazia não identifica nada. */
+function hasContentMedia(media: ReactNode): boolean {
+  return media !== undefined && media !== null && media !== false;
+}
+
+/**
+ * Um `IconTile` recebido como filho não vira uma segunda moldura: o slot assume o lugar dele e
+ * herda o que ele declara (`size`, `context`, `variant`, demais props), somando as classes.
+ */
+function adoptIconTile(props: SurfaceMediaProps): SurfaceMediaProps {
+  const { children, asChild, className } = props;
+  if (asChild) return props;
+  // `toArray`, não `only`: um array com um único item (de um `map`/`filter`) é válido aqui.
+  const nodes = Children.toArray(children);
+  if (nodes.length !== 1) return props;
+  const child = nodes[0];
+  if (!isValidElement<IconTileProps>(child) || child.type !== IconTile) {
+    return props;
+  }
+  // `null` em size/context/variant significa "use o padrão" no IconTile: fica o do slot.
+  const declared = Object.fromEntries(
+    Object.entries(child.props).filter(([, value]) => value != null),
+  ) as SurfaceMediaProps;
+  return {
+    ...props,
+    ...declared,
+    className: cn(className, declared.className),
+    children: declared.children,
+  };
+}
+
+/** Moldura de ícone ou imagem que identifica a região nomeada. */
+export function ContentMedia({
+  size = "xs",
+  ...rest
+}: SurfaceMediaProps): ReactElement {
+  const context = requiredContext(
+    useContext(ContentHeaderContext),
+    "ContentMedia",
+    "ContentHeader",
+  );
+  const props = adoptIconTile({ size, ...rest });
+  return (
+    <SurfaceMedia
+      slot="content-media"
+      {...props}
+      aria-hidden={
+        context.element === "fieldset" ? true : props["aria-hidden"]
+      }
+    />
+  );
+}
+
 export function ContentTitle({
   className,
   id,

package/src/ui/components/patterns/list.tsx

@@ -1218,20 +1218,8 @@ function AdvancedFiltersDialog({
                 frameVariant={
                   sectionVariant === "framed" ? "legend" : "default"
                 }
-                title={
-                  <span className="flex items-center gap-2">
-                    {sectionIcons?.[section] !== undefined && (
-                      <span
-                        data-slot="content-title-icon"
-                        aria-hidden="true"
-                        className="inline-flex shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4"
-                      >
-                        {sectionIcons[section]}
-                      </span>
-                    )}
-                    {section}
-                  </span>
-                }
+                title={section}
+                media={sectionIcons?.[section]}
               >
                 <FieldGroup className={cn("grid gap-4", gridColumns)}>
                   {entries.map(field)}

package/src/ui/components/patterns/surface-header.tsx

@@ -45,10 +45,12 @@ interface SurfaceHeaderSlots {
   title: ElementType;
   count?: ElementType;
   description?: ElementType;
-  actions: ElementType;
+  actions?: ElementType;
 }
 
 export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /** Elemento estrutural; `legend` preserva a mesma anatomia com wrappers phrasing. */
+  as?: "div" | "legend";
   /** Nome do componente público, para as mensagens de erro (`PageHeader`, `ContentHeader`). */
   name: string;
   /** Prefixo dos `data-slot` (`page` → `page-header`, `page-heading`). */
@@ -57,6 +59,8 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
   slots: SurfaceHeaderSlots;
   /** Posição de um slot introdutório opcional, antes da linha ou dentro dela. */
   leadingPlacement?: "above" | "inline";
+  /** Mantém a mídia na linha geral ou a agrupa com o heading. */
+  mediaPlacement?: "row" | "heading";
   /** Classes de um container interno quando a moldura precisa ocupar toda a largura. */
   contentClassName?: string;
   /** Permite uma superfície composta apenas pelas regiões leading/actions. */
@@ -71,6 +75,11 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
    * NOMEIAM algo (Card, Dialog, Drawer, Page, Content) continuam estritas.
    */
   allowFreeContent?: boolean;
+  /**
+   * Mensagem própria para uma composição inválida, quando a regra do header não cabe na
+   * mensagem genérica (a legenda de um fieldset aceita menos slots que o header comum).
+   */
+  invalidMessage?: string;
 }
 
 /** Expande fragments de primeiro nível: o shorthand monta os slots dentro de um `<>`. */
@@ -83,19 +92,23 @@ function flatten(children: ReactNode): ReactNode[] {
 }
 
 export function SurfaceHeader({
+  as: Root = "div",
   name,
   slot,
   slots,
   leadingPlacement = "above",
+  mediaPlacement = "row",
   contentClassName,
   titleRequired = true,
   rowClassName,
   trailing,
   allowFreeContent = false,
+  invalidMessage,
   className,
   children,
   ...props
 }: SurfaceHeaderProps): ReactElement {
+  const Wrapper = Root === "legend" ? "span" : "div";
   const nodes = flatten(children);
   const of = (type: ElementType) =>
     nodes.filter((node) => isValidElement(node) && node.type === type);
@@ -111,7 +124,8 @@ export function SurfaceHeader({
   const counts = slots.count === undefined ? [] : of(slots.count);
   const descriptions =
     slots.description === undefined ? [] : of(slots.description);
-  const actionSlots = of(slots.actions);
+  const actionSlots =
+    slots.actions === undefined ? [] : of(slots.actions);
   const slotTypes = [
     ...leadingTypes,
     slots.media,
@@ -167,6 +181,7 @@ export function SurfaceHeader({
         isValidElement(node) ? [node.type as ElementType] : [],
       ),
     );
+    if (invalidMessage !== undefined) throw new Error(invalidMessage);
     throw new Error(
       distinctLeading.size > 1
         ? `${name} aceita ${[...distinctLeading].map(label).join(" ou ")} na região introdutória, nunca os dois na mesma superfície.`
@@ -174,24 +189,42 @@ export function SurfaceHeader({
     );
   }
 
+  const titleLine = titles.length + counts.length > 0 && (
+    <Wrapper className="flex items-baseline gap-2">
+      {titles}
+      {counts}
+    </Wrapper>
+  );
   const heading = titles.length +
     counts.length +
     descriptions.length +
-    free.length >
+    free.length +
+    (mediaPlacement === "heading" ? medias.length : 0) >
     0 && (
-    <div
+    <Wrapper
       data-slot={`${slot}-heading`}
       className={cn("min-w-0", leadingPlacement === "inline" && "flex-1")}
     >
-      {titles.length + counts.length > 0 && (
-        <div className="flex items-baseline gap-2">
-          {titles}
-          {counts}
-        </div>
+      {mediaPlacement === "heading" && medias.length > 0 ? (
+        <Wrapper
+          data-slot={`${slot}-heading-row`}
+          className="flex items-center gap-2"
+        >
+          {medias}
+          <Wrapper data-slot={`${slot}-heading-content`} className="min-w-0">
+            {titleLine}
+            {descriptions}
+            {free}
+          </Wrapper>
+        </Wrapper>
+      ) : (
+        <>
+          {titleLine}
+          {descriptions}
+          {free}
+        </>
       )}
-      {descriptions}
-      {free}
-    </div>
+    </Wrapper>
   );
   // A região introdutória carrega o mesmo `data-slot` nas duas apresentações: seletor de teste
   // ou de CSS que funcione no header padrão precisa funcionar na barra.
@@ -200,14 +233,14 @@ export function SurfaceHeader({
       {leadingPlacement === "inline" && leading.length > 0 && (
         // `min-w-0` aqui é o que deixa a trilha do PageNavigation ceder e truncar; sem ele o
         // wrapper assume o min-content do breadcrumb e a compressão toda cai sobre o título.
-        <div
+        <Wrapper
           data-slot={`${slot}-navigation`}
           className={cn("flex min-w-0 items-center", !heading && "flex-1")}
         >
           {leading}
-        </div>
+        </Wrapper>
       )}
-      {medias}
+      {mediaPlacement === "row" && medias}
       {heading}
       {actionSlots}
       {trailing}
@@ -215,15 +248,15 @@ export function SurfaceHeader({
   );
   const layout =
     leadingPlacement === "inline" ? (
-      <div className={cn("flex min-w-0 items-center gap-3", rowClassName)}>
+      <Wrapper className={cn("flex min-w-0 items-center gap-3", rowClassName)}>
         {row}
-      </div>
+      </Wrapper>
     ) : leading.length > 0 ? (
       <>
-        <div data-slot={`${slot}-navigation`} className="mb-4">
+        <Wrapper data-slot={`${slot}-navigation`} className="mb-4">
           {leading}
-        </div>
-        <div
+        </Wrapper>
+        <Wrapper
           data-slot={`${slot}-header-row`}
           className={cn(
             actionSlots.length > 0 &&
@@ -232,7 +265,7 @@ export function SurfaceHeader({
         >
           {heading}
           {actionSlots}
-        </div>
+        </Wrapper>
       </>
     ) : (
       <>
@@ -242,7 +275,7 @@ export function SurfaceHeader({
     );
 
   return (
-    <div
+    <Root
       data-slot={`${slot}-header`}
       className={cn(
         contentClassName === undefined &&
@@ -257,10 +290,10 @@ export function SurfaceHeader({
       {contentClassName === undefined ? (
         layout
       ) : (
-        <div data-slot={`${slot}-header-content`} className={contentClassName}>
+        <Wrapper data-slot={`${slot}-header-content`} className={contentClassName}>
           {layout}
-        </div>
+        </Wrapper>
       )}
-    </div>
+    </Root>
   );
 }

package/src/ui/components/primitives/card.tsx

@@ -52,7 +52,7 @@ export function Card({
         data-slot="card"
         data-layout={layout}
         className={cn(
-          "rounded-xl border border-border bg-card text-card-foreground",
+          "rounded-xl border border-border bg-card text-card-foreground [--surface-background:var(--card)]",
           // Seccionado: o divisor encosta na borda, então o raio precisa recortar.
           layout === "sectioned" && "overflow-hidden",
           className,

package/src/ui/components/primitives/dialog.tsx

@@ -230,7 +230,7 @@ export function DialogContent({
   const { mode } = useDialogContext();
   const showClose = showCloseButton ?? mode !== "alert";
   const contentClasses =
-    "fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] overflow-clip rounded-xl border border-transparent bg-background text-foreground shadow-xl duration-200 outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:border-border/70";
+    "fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] overflow-clip rounded-xl border border-transparent bg-background text-foreground shadow-xl duration-200 outline-none [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:border-border/70";
 
   if (mode === "alert") {
     return (