@softize/opus 25.0.0 → 25.2.0

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

@@ -18,7 +18,19 @@ import {
   type StructuralMediaProps,
 } from "../patterns/structural-media.tsx";
 import { CloseButton, type CloseButtonSize } from "./close-button.tsx";
-import { overlayClasses, preventDismissWhen } from "./dialog.tsx";
+import {
+  composeModalDismissHandlers,
+  overlayClasses,
+  useComposedRef,
+  useModalOpenState,
+} from "./dialog.tsx";
+import {
+  LAYER_MODAL_ATTRIBUTE,
+  LayerPortalProvider,
+  handleModalTabKey,
+  useLayerPortal,
+  useModalLayerEntry,
+} from "../../lib/modal-layers.ts";
 
 interface DrawerContentContextValue {
   showCloseButton: boolean;
@@ -34,10 +46,36 @@ const DrawerContentContext = React.createContext<DrawerContentContextValue>({
 
 const DrawerIntroContext = React.createContext(false);
 
+/** Estado de aberto que a pilha de modais da camada flutuante acompanha (ADR 0052). */
+const DrawerStateContext = React.createContext({ open: false, modal: true });
+
 function Drawer({
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  modal,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Root>) {
-  return <DrawerPrimitive.Root data-slot="drawer" {...props} />;
+  const [open, setOpen] = useModalOpenState({
+    open: openProp,
+    defaultOpen,
+    onOpenChange,
+  });
+  const state = React.useMemo(
+    () => ({ open, modal: modal !== false }),
+    [open, modal],
+  );
+  return (
+    <DrawerStateContext.Provider value={state}>
+      <DrawerPrimitive.Root
+        data-slot="drawer"
+        modal={modal}
+        open={open}
+        onOpenChange={setOpen}
+        {...props}
+      />
+    </DrawerStateContext.Provider>
+  );
 }
 
 function DrawerTrigger({
@@ -53,19 +91,30 @@ function DrawerClose({
 }
 
 function DrawerPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Portal>) {
-  return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />;
+  // Aberto de dentro de uma camada flutuante, o Drawer vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal();
+  return (
+    <DrawerPrimitive.Portal
+      data-slot="drawer-portal"
+      container={container ?? layer.container}
+      {...props}
+    />
+  );
 }
 
 function DrawerOverlay({
   className,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Overlay>) {
+  const layer = useLayerPortal();
   return (
     <DrawerPrimitive.Overlay
       data-slot="drawer-overlay"
-      className={cn(overlayClasses, className)}
+      {...{ [LAYER_MODAL_ATTRIBUTE]: layer.container !== undefined || undefined }}
+      className={cn(overlayClasses, layer.zIndexClass, className)}
       {...props}
     />
   );
@@ -95,7 +144,11 @@ function DrawerContent({
   layout = "sectioned",
   "aria-describedby": ariaDescribedBy,
   onEscapeKeyDown,
+  onPointerDownOutside,
   onInteractOutside,
+  onCloseAutoFocus,
+  onKeyDown,
+  ref,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Content> & {
   side?: "top" | "right" | "bottom" | "left";
@@ -109,12 +162,44 @@ function DrawerContent({
   /** Anatomia da superfície: `sectioned` (default) ou `continuous` — ADR 0023. */
   layout?: SurfaceLayout;
 }) {
+  const { open, modal } = React.useContext(DrawerStateContext);
+  const layer = useLayerPortal();
+  const internal = layer.container !== undefined;
+  // Seção 6 da ADR 0052: portado para uma camada, o Drawer é interno a ela; fora, é de trabalho.
+  const mark = internal ? "internal" : "work";
+  const entryRef = useModalLayerEntry({
+    open,
+    modal,
+    mark,
+    surface: "drawer",
+    side,
+  });
+  const composedRef = useComposedRef(ref, entryRef);
+  const dismiss = composeModalDismissHandlers({
+    mark,
+    closeDisabled,
+    onEscapeKeyDown,
+    onPointerDownOutside,
+    onInteractOutside,
+    onCloseAutoFocus,
+  });
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>): void => {
+    onKeyDown?.(event);
+    handleModalTabKey(event);
+  };
+  // Os portais abertos daqui herdam a marca de modal quando este Drawer mora numa camada.
+  const nestedPortal = React.useMemo(
+    () => ({ ...layer, modalSubtree: layer.modalSubtree || internal }),
+    [layer, internal],
+  );
   return (
     <DrawerPortal>
       <DrawerOverlay />
       <DrawerPrimitive.Content
+        ref={composedRef}
         data-slot="drawer-content"
         data-layout={layout}
+        {...{ [LAYER_MODAL_ATTRIBUTE]: internal || undefined }}
         className={cn(
           "fixed z-50 flex flex-col overflow-hidden rounded-xl border bg-background shadow-lg transition ease-in-out [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
           side === "right" &&
@@ -125,20 +210,26 @@ function DrawerContent({
             "inset-x-1 top-1 h-auto data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
           side === "bottom" &&
             "inset-x-1 bottom-1 h-auto data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+          layer.zIndexClass,
           className,
         )}
         aria-describedby={ariaDescribedBy}
-        onEscapeKeyDown={preventDismissWhen(closeDisabled, onEscapeKeyDown)}
-        onInteractOutside={preventDismissWhen(closeDisabled, onInteractOutside)}
+        onEscapeKeyDown={dismiss.onEscapeKeyDown}
+        onPointerDownOutside={dismiss.onPointerDownOutside}
+        onInteractOutside={dismiss.onInteractOutside}
+        onCloseAutoFocus={dismiss.onCloseAutoFocus}
+        onKeyDown={handleKeyDown}
         {...props}
       >
-        <SurfaceLayoutProvider value={layout}>
-          <DrawerContentContext.Provider
-            value={{ showCloseButton, closeDisabled, closeSize }}
-          >
-            {children}
-          </DrawerContentContext.Provider>
-        </SurfaceLayoutProvider>
+        <LayerPortalProvider value={nestedPortal}>
+          <SurfaceLayoutProvider value={layout}>
+            <DrawerContentContext.Provider
+              value={{ showCloseButton, closeDisabled, closeSize }}
+            >
+              {children}
+            </DrawerContentContext.Provider>
+          </SurfaceLayoutProvider>
+        </LayerPortalProvider>
       </DrawerPrimitive.Content>
     </DrawerPortal>
   );

package/src/ui/components/primitives/floating-layer.tsx

@@ -0,0 +1,79 @@
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+import { cn } from "../../lib/cn.ts";
+import {
+  LayerPortalProvider,
+  registerFloatingLayer,
+} from "../../lib/modal-layers.ts";
+
+export interface FloatingLayerProps {
+  children: React.ReactNode;
+  /** Classes do hospedeiro. A posição de cada filho continua sendo do consumidor. */
+  className?: string;
+  /**
+   * Esc enquanto a pessoa está na camada, com ou sem modal aberto. É chamado uma vez por tecla.
+   * Nenhum modal fecha nesse caso, e o Opus não fecha a camada sozinho, porque o estado de aberto
+   * pertence ao consumidor.
+   */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+}
+
+/**
+ * Hospedeiro fixo, na tela inteira e acima dos modais de trabalho. Ele mesmo não recebe clique;
+ * os filhos diretos recebem, mesmo com o `body` bloqueado por um modal.
+ */
+const hostClasses =
+  "pointer-events-none fixed inset-0 z-60 *:pointer-events-auto";
+
+/**
+ * Região da aplicação que fica acima do conteúdo e dos modais de trabalho (Dialog e Drawer) e
+ * continua utilizável enquanto eles estão abertos, como o botão e o painel de um assistente
+ * (ADR 0052).
+ *
+ * Os filhos são portados para `div[data-slot="floating-layer"]` no `body`. O hospedeiro publica o
+ * modal de trabalho do topo em `data-modal` (`none`, `dialog` ou `drawer`) e o lado do Drawer em
+ * `data-modal-side`, para o consumidor reposicionar o que precisar. Popover, Menu, Tooltip, Dialog
+ * e Drawer abertos de dentro da camada vão para o mesmo hospedeiro.
+ */
+export function FloatingLayer({
+  children,
+  className,
+  onEscapeKeyDown,
+}: FloatingLayerProps) {
+  const [host, setHost] = React.useState<HTMLElement | null>(null);
+  const escapeRef = React.useRef(onEscapeKeyDown);
+  escapeRef.current = onEscapeKeyDown;
+
+  React.useLayoutEffect(() => {
+    const element = document.createElement("div");
+    element.setAttribute("data-slot", "floating-layer");
+    document.body.appendChild(element);
+    const unregister = registerFloatingLayer(element, (event) =>
+      escapeRef.current?.(event),
+    );
+    setHost(element);
+    // Desfaz o registro, retira o hospedeiro e, se o foco estava nele com um modal aberto,
+    // devolve o foco ao modal.
+    return unregister;
+  }, []);
+
+  React.useLayoutEffect(() => {
+    if (host !== null) host.className = cn(hostClasses, className);
+  }, [host, className]);
+
+  const portal = React.useMemo(
+    () => ({
+      container: host ?? undefined,
+      zIndexClass: undefined,
+      modalSubtree: false,
+    }),
+    [host],
+  );
+
+  if (host === null) return null;
+  return createPortal(
+    <LayerPortalProvider value={portal}>{children}</LayerPortalProvider>,
+    host,
+  );
+}

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

@@ -5,6 +5,7 @@ import { DropdownMenu as MenuPrimitive } from "radix-ui";
 
 import { useDismissOnIframeFocus } from "../../lib/dismiss-on-iframe.ts";
 import { cn } from "../../lib/cn.ts";
+import { layerModalMarker, useLayerPortal } from "../../lib/modal-layers.ts";
 
 function Menu({ ...props }: React.ComponentProps<typeof MenuPrimitive.Root>) {
   return <MenuPrimitive.Root data-slot="menu" {...props} />;
@@ -16,9 +17,17 @@ function Menu({ ...props }: React.ComponentProps<typeof MenuPrimitive.Root>) {
  * próxima versão major.
  */
 function MenuPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Portal>) {
-  return <MenuPrimitive.Portal data-slot="menu-portal" {...props} />;
+  const layer = useLayerPortal();
+  return (
+    <MenuPrimitive.Portal
+      data-slot="menu-portal"
+      container={container ?? layer.container}
+      {...props}
+    />
+  );
 }
 
 function MenuTrigger({
@@ -35,14 +44,18 @@ function MenuContent({
   // Mesma razão do Popover: clique dentro de iframe não chega aqui fora.
   const ref = React.useRef<HTMLDivElement>(null);
   useDismissOnIframeFocus(ref);
+  // Aberto de dentro de uma camada flutuante, vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal();
   return (
-    <MenuPrimitive.Portal>
+    <MenuPrimitive.Portal container={layer.container}>
       <MenuPrimitive.Content
         ref={ref}
         data-slot="menu-content"
+        {...layerModalMarker(layer)}
         sideOffset={sideOffset}
         className={cn(
           "z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[10rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md will-change-[transform,opacity] 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",
+          layer.zIndexClass,
           className,
         )}
         {...props}
@@ -215,11 +228,13 @@ function MenuSubContent({
   className,
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.SubContent>) {
+  const layer = useLayerPortal();
   return (
     <MenuPrimitive.SubContent
       data-slot="menu-sub-content"
       className={cn(
         "z-50 min-w-[10rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md will-change-[transform,opacity] 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",
+        layer.zIndexClass,
         className,
       )}
       {...props}

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

@@ -2,6 +2,7 @@ import * as React from "react"
 import { Popover as PopoverPrimitive } from "radix-ui"
 
 import { useDismissOnIframeFocus } from "../../lib/dismiss-on-iframe.ts"
+import { layerModalMarker, useLayerPortal } from "../../lib/modal-layers.ts"
 import { cn } from '../../lib/cn.ts'
 
 function Popover({
@@ -26,15 +27,19 @@ function PopoverContent({
   // pendurado sobre o conteúdo. Na cabine, o preview É um iframe.
   const ref = React.useRef<HTMLDivElement>(null)
   useDismissOnIframeFocus(ref)
+  // Aberto de dentro de uma camada flutuante, vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal()
   return (
-    <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Portal container={layer.container}>
       <PopoverPrimitive.Content
         ref={ref}
         data-slot="popover-content"
+        {...layerModalMarker(layer)}
         align={align}
         sideOffset={sideOffset}
         className={cn(
           "z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border border-border bg-popover p-4 text-popover-foreground shadow-md outline-hidden data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 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",
+          layer.zIndexClass,
           className
         )}
         {...props}

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

@@ -2,6 +2,7 @@ import * as React from "react"
 import { Tooltip as TooltipPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { layerModalMarker, useLayerPortal } from "../../lib/modal-layers.ts"
 
 function TooltipProvider({
   delayDuration = 0,
@@ -34,13 +35,17 @@ function TooltipContent({
   children,
   ...props
 }: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  // Aberto de dentro de uma camada flutuante, vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal()
   return (
-    <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Portal container={layer.container}>
       <TooltipPrimitive.Content
         data-slot="tooltip-content"
+        {...layerModalMarker(layer)}
         sideOffset={sideOffset}
         className={cn(
           "z-50 w-fit max-w-sm origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-pretty text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+          layer.zIndexClass,
           className
         )}
         {...props}

package/src/ui/docs/content/actions.md

@@ -136,7 +136,7 @@ name, kind
   → public, requires, authorize, loads
   → handler
   → audit, confirm, invalidates, rateLimit, idempotency
-  → ai, automatable, internal
+  → ai, assistant, automatable, internal
 ```
 
 Campos específicos de um kind, como `fields`, `paginate`, `columns`, `filters`, `expand`,
@@ -179,6 +179,102 @@ A autorização é fechada por padrão: sem `public: true`, a action exige usuá
 `authorize`, exige também a permissão declarada. `automatable: true` permite que um
 [schedule](/docs/scheduler) execute a action como o sistema, sem abri-la a chamadores anônimos.
 
+## Declarar o assistente do recurso
+
+Um produto pode oferecer, além do chat geral, uma conversa sobre um recurso específico: um cliente,
+um relatório, um pedido. Essa conversa precisa ler o recurso com a permissão de quem conversa, seguir
+o procedimento próprio daquele tipo de recurso e entregar ao modelo só os dados necessários. Os três
+ficam declarados num lugar só: a action `view` que lê o recurso declara `assistant` e passa a ser a
+**action dona** daquele tipo de recurso.
+
+```ts
+export const customerViewContract = defineContract({
+  name: 'customer.view',
+  kind: 'view',
+  label: 'Ver cliente',
+  input: z.object({ id: z.string().uuid() }),
+  output: customerViewSchema,
+  personalData: true,
+  requires: 'customer.read',
+  authorize: (ctx) => ctx.can('customer.read'),
+  ai: true,
+  assistant: {
+    resource: 'customer',
+    skill: 'review-customer',
+    label: 'Assistente do cliente',
+    title: 'name',
+    context: ['kind', 'stage', 'sources', 'leads.totalCount', 'leads.latest.status'],
+  },
+})
+```
+
+| Campo | O que declara |
+| --- | --- |
+| `resource` | O tipo de recurso de que a action é dona, em camelCase. Cada tipo tem uma única action dona. |
+| `skill` | A chave do procedimento que a IA segue ao tratar do recurso, em minúsculas com hífen. O Opus não conhece o procedimento; o produto o mantém e confere que a chave existe. |
+| `label` | O nome do assistente para pessoas. Entra no inventário do `opus copy`. |
+| `title` | O caminho, na saída, do campo que nomeia o recurso. |
+| `context` | Os caminhos, na saída, dos campos que o host pode entregar ao modelo como dado do recurso. |
+| `maxContextChars` | Opcional. O teto do dado entregue, em caracteres de JSON: 4.000 por padrão, de 1.000 a 16.000. |
+
+A action dona precisa ser `view`, estar publicada para a IA (`ai`), declarar `personalData` e
+receber só `{ id }`: o `id`, do tipo texto, é o único campo obrigatório da entrada, e outros campos,
+se houver, têm valor padrão ou são opcionais. Os caminhos usam ponto para descer em objetos; um
+caminho que passa por uma lista vale para cada item, e um campo intermediário `null` aparece como
+`null`. Declare em `context` só o que orienta a conversa: o exemplo deixa fora contato, documento e
+endereço, e o nome já vai como `title`. Um caminho que termina num objeto ou numa lista leva tudo o
+que está abaixo dele, inclusive campos acrescentados depois à saída; para conferir num teste o que
+cada caminho alcança, use `assistantContextLeaves`, de `@softize/opus/assistant-schema`, sobre o
+schema de saída do manifest. O `title` precisa apontar para texto ou número.
+
+O `opus check` cobra a forma da declaração (regra `assistant-declaration`), o `opus gen` recusa
+`title`, caminho de `context` ou entrada que não conferem com os schemas, e o registro recusa duas
+actions donas do mesmo recurso. O manifest, `runtime.aiTools()` e o MCP (`com.softize.opus/assistant`
+em `_meta`) levam a declaração, e o manifest passa a mostrar também a publicação para a IA.
+
+### Ler o recurso pela action dona
+
+O recurso de um assistente é lido, e o acesso a ele é conferido, somente pela action dona.
+`runtime.readResource` executa a action com `{ id }` pelo mesmo `execute` de qualquer chamada; a
+autorização, a auditoria e a marca de dado pessoal são as da action:
+
+```ts
+const read = await runtime.readResource('customer', id, base, { context: true })
+if (!read.ok) return notFound() // o erro da action, com a categoria dela
+read.resource // { kind: 'customer', id, title: 'Maria Souza', label: 'Assistente do cliente', skill: 'review-customer' }
+read.context // { data, truncated, omitted, personalData: true }
+```
+
+Sem `{ context: true }`, a leitura devolve só o descritor, que basta para conferir o acesso e
+mostrar o nome. Um tipo sem action dona devolve `runtime.assistant_resource_unknown` sem executar
+nada. `runtime.assistants()` lista as declarações com a action dona de cada uma, para o produto
+montar rotas e telas sem lista paralela e para conferir, num teste, que cada `skill` existe no
+registro de procedimentos dele. O Opus não enxerga as rotas HTTP que o produto registra por conta
+própria: um teste do produto deve garantir que nenhuma rota confere acesso a recurso sem passar por
+uma action.
+
+### O dado que vai ao modelo
+
+`context.data` traz só os caminhos declarados, com a estrutura da saída. Quando o JSON passa do
+teto, o corte acontece por etapas, até caber, e fica registrado em `omitted`:
+
+1. sai o último item da maior lista, repetidamente;
+2. com as listas vazias, o texto mais longo é encurtado pela metade, até 200 caracteres;
+3. por fim, saem campos inteiros, do último declarado para o primeiro.
+
+Com qualquer corte, `truncated` vale `true`. O título fica fora do teto e é encurtado a 200
+caracteres. Um caminho que falta na saída em execução é omitido com o motivo `missing` e gera um
+aviso no log, sem falhar a leitura. Quem recebe a saída por outro canal, como o MCP, aplica a mesma
+projeção com `projectAssistantContext(assistant, output)`.
+
+Entregue o dado ao modelo como bloco delimitado, numa mensagem de dado, nunca no prompt de sistema.
+`resourceDataBlock`, de `@softize/opus/ai`, monta o bloco com o tipo, o id, o título, os dados e,
+quando houve corte ou ausência, `truncated` e `omitted`, e escapa dentro dos valores o que poderia
+fechar o delimitador. Quando o modelo chama a action dona como ferramenta, recebe a saída completa
+do contrato, como em qualquer chamada: a projeção governa só o que o host entrega por iniciativa
+própria. Cada execução de uma action com dado pessoal é uma exposição registrada, então reaproveite
+a leitura que já conferiu o acesso em vez de executar a action de novo só para obter o contexto.
+
 ## Prototipar com dados simulados
 
 Para desenhar a interface antes de o backend existir, rode o app em modo design. Nesse modo, toda

package/src/ui/docs/content/ai.md

@@ -86,8 +86,10 @@ const { text } = await ctx.ai!.run('Quais notas a Empresa X emitiu em junho?')
 usado na execução e na auditoria; `title` traz a `label` legível da action, quando existe;
 `description` vem de `ai.description` (ou da `description` da action) e `inputSchema`, do input.
 `metadata.dataProducts` lista os [Produtos de Dados](/docs/data-products) relacionados e
-`metadata.dataProductLabels` associa cada identificador ao seu nome legível. Esses metadados servem ao host: não entram no
-prompt e não concedem acesso.
+`metadata.dataProductLabels` associa cada identificador ao seu nome legível. Na action dona de um
+tipo de recurso, `metadata.assistant` traz o [assistente declarado](/docs/actions): o recurso, a
+chave do procedimento, o nome, o campo do título, os campos do dado ao modelo e o teto. Esses
+metadados servem ao host: não entram no prompt e não concedem acesso.
 
 O agente só executa nomes que `aiTools()` anunciou; uma chamada a outra action volta como erro
 para o modelo. Actions marcadas com `ai: { destructive: true }` ou `ai: { requiresConfirmation: true }`

package/src/ui/docs/content/cli.md

@@ -21,7 +21,8 @@ opus seed check       # bindings, dependências, ciclos e scripts paralelos de s
 ```
 
 `opus check` lê o código-fonte sem executá-lo e aplica regras em quatro grupos: actions
-(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`, `ignored-by-kind`), UI
+(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`, `ignored-by-kind` e
+`assistant-declaration`, que cobra a forma do [assistente do recurso](/docs/actions)), UI
 (`ui-structure`, `ui-structure-split`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`),
 [Produtos de Dados](/docs/data-products) (`data-product-export`, `-id`, `-duplicate`, `-version`,
 `-interfaces`, `-interface`, `-entities` e `-entity`, todas com o prefixo `data-product`) e

package/src/ui/docs/content/dialog.md

@@ -441,6 +441,9 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Arqu
 - O comportamento selecionado por `mode` determina o papel de acessibilidade; `role` não configura
   o comportamento.
 - O foco permanece dentro do diálogo aberto e retorna ao gatilho após o fechamento.
+- No modo padrão, uma [`FloatingLayer`](/ui/floating-layer), como o painel de um assistente,
+  continua utilizável com o diálogo aberto: o Tab passa por ela, o foco não é puxado de volta e o Esc
+  age onde a pessoa está. O modo `alert` cobre a camada até a resposta.
 - `DialogHost` apresenta uma solicitação por vez para que cada resposta tenha um alvo inequívoco.
 
 ## Propriedades de Dialog

package/src/ui/docs/content/drawer.md

@@ -170,6 +170,9 @@ de continuar, use [`Dialog mode="alert"`](/ui/dialog), que não fecha pelo cliqu
 - Com `modal` ativo, o padrão, o foco permanece dentro do painel e o restante da página fica
   inacessível até o fechamento.
 - Ao fechar, o foco retorna ao gatilho.
+- Uma [`FloatingLayer`](/ui/floating-layer), como o painel de um assistente, continua utilizável
+  com o painel lateral aberto: o Tab passa por ela, o foco não é puxado de volta e o Esc age onde a
+  pessoa está. Ela recebe o lado do Drawer em `data-modal-side` para sair da frente dele.
 - O botão de fechar tem o nome acessível `Fechar`. Botões só com ícone no cabeçalho precisam de
   `aria-label`.