@softize/opus 25.3.0 → 25.3.1

package/CHANGELOG.md

@@ -7,6 +7,27 @@ 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.
 
+## 25.3.1 — 2026-10-05
+
+Com um `Dialog` ou `Drawer` aberto e a pessoa numa `FloatingLayer` sem `onEscapeKeyDown`, o Esc
+fecha o modal. Antes, o Opus impedia o modal de fechar e chamava um handler que não existia: quem
+chegava ao botão do assistente pelo Tab e apertava Esc não via efeito nenhum. Com o handler, nada
+muda: a camada recebe a tecla e o modal continua aberto. Para que o Esc no botão feche o modal,
+passe `onEscapeKeyDown` só enquanto a camada tiver o que fechar, como com o painel aberto, e
+`undefined` no restante do tempo. A decisão está numa nota da seção 5 da ADR 0052.
+
+`assistantContextLeaves`, de `@softize/opus/assistant-schema`, passa a listar em `open` dois pontos
+por onde qualquer campo chega ao modelo e que antes ficavam de fora: o `$ref` que não resolve dentro
+do schema, que sumia do resultado, e o objeto que aceita chaves não declaradas
+(`additionalProperties: true`, do `.passthrough()` do zod), que aparece como `<caminho>.*`. A forma
+do resultado e a conferência do `opus gen` não mudam. Um teste de campos pessoais que reprova pontos
+abertos pode passar a acusar esses casos; reprove-os ou justifique cada um.
+
+A ADR 0052 e a página da `FloatingLayer` registram que o roteiro manual em Safari com VoiceOver e no
+Firefox não foi executado: na adoção pela Grand Brasil, o dono do produto o dispensou. A evidência
+é a dos testes de navegador no Chromium real, e o roteiro volta a ser exigido se surgir problema de
+leitor de tela, de Safari ou de Firefox.
+
 ## 25.3.0 — 2026-10-05
 
 `ListAction.grouping` declara dimensões fechadas pelas quais a `ActionList` pode agrupar a tabela.

package/bin/lib/assistant-schema.d.mts

@@ -13,8 +13,9 @@ export interface AssistantContextLeaves {
   /** Os campos folha alcançados, com ponto e sem índice de lista; `*` marca a chave de um mapa. */
   leaves: string[]
   /**
-   * Pontos em que o schema não declara forma ou volta a si mesmo por `$ref`: qualquer campo abaixo
-   * deles pode ir ao modelo, e a conferência não alcança.
+   * Pontos por onde qualquer campo pode ir ao modelo sem que a conferência alcance: o schema que não
+   * declara forma, o `$ref` que volta a si mesmo ou que não resolve, e, como `<ponto>.*`, o objeto
+   * que aceita chaves não declaradas (`additionalProperties: true`, do `.passthrough()` do zod).
    */
   open: string[]
 }

package/bin/lib/assistant-schema.mjs

@@ -45,18 +45,26 @@ function isNullOnly(schema) {
 const NO_REFS = new Set();
 /** Marca o ponto em que um `$ref` volta a um schema que já está no caminho atual. */
 const CYCLE = Object.freeze({ cycle: true });
+/** Marca o ponto em que um `$ref` não resolve dentro do schema: não há forma a conferir ali. */
+const UNRESOLVED = Object.freeze({ unresolved: true });
+
+/** Um dos marcadores de `expand`, e não um schema de verdade. */
+function isMarker(schema) {
+  return schema === CYCLE || schema === UNRESOLVED;
+}
 
 /**
  * Os ramos concretos e não nulos de um schema, com `$ref` e combinadores expandidos. Cada ramo traz
  * os `$ref` percorridos no caminho atual; um `$ref` que se repete ali vira `CYCLE`, em vez de
- * expandir de novo.
+ * expandir de novo, e um `$ref` que não resolve vira `UNRESOLVED`, em vez de sumir.
  */
 function expand(schema, root, active = NO_REFS, depth = 0) {
   if (schema === null || typeof schema !== "object" || depth > MAX_DEPTH) return [];
   if (typeof schema.$ref === "string") {
     if (active.has(schema.$ref)) return [{ schema: CYCLE, active }];
     const target = resolveRef(root, schema.$ref);
-    return target === undefined ? [] : expand(target, root, new Set([...active, schema.$ref]), depth + 1);
+    if (target === undefined) return [{ schema: UNRESOLVED, active }];
+    return expand(target, root, new Set([...active, schema.$ref]), depth + 1);
   }
   const nested = COMBINATORS.flatMap((key) =>
     Array.isArray(schema[key]) ? schema[key].flatMap((branch) => expand(branch, root, active, depth + 1)) : [],
@@ -68,9 +76,9 @@ function expand(schema, root, active = NO_REFS, depth = 0) {
   return [{ schema, active }, ...nested];
 }
 
-/** Os ramos sem os ciclos, para quem só olha o tipo do próprio nó. */
+/** Os ramos sem os marcadores, para quem só olha o tipo do próprio nó. */
 function branches(schema, root) {
-  return expand(schema, root).flatMap(({ schema: branch }) => (branch === CYCLE ? [] : [branch]));
+  return expand(schema, root).flatMap(({ schema: branch }) => (isMarker(branch) ? [] : [branch]));
 }
 
 function isOpen(schema) {
@@ -89,7 +97,9 @@ function isArraySchema(schema) {
  * Os schemas alcançados por `segments` em todos os ramos não nulos. Um schema sem forma alcança
  * qualquer caminho abaixo dele e entra como está. Com `throughLists`, uma lista é atravessada. Um
  * ciclo de `$ref` sem avançar no caminho (por lista ou união) não leva a lugar nenhum; ao descer
- * por um campo, o caminho avança, e o mesmo `$ref` pode voltar, como numa árvore.
+ * por um campo, o caminho avança, e o mesmo `$ref` pode voltar, como numa árvore. Um `$ref` que não
+ * resolve antes do fim do caminho entra como `UNRESOLVED`: quem confere o caminho o descarta, e
+ * quem lista as folhas o marca como aberto.
  */
 function collectTargets(schema, segments, root, throughLists, out, active = NO_REFS, depth = 0) {
   if (depth > MAX_DEPTH) return;
@@ -99,7 +109,7 @@ function collectTargets(schema, segments, root, throughLists, out, active = NO_R
   }
   for (const { schema: branch, active: refs } of expand(schema, root, active)) {
     if (branch === CYCLE) continue;
-    if (isOpen(branch)) {
+    if (branch === UNRESOLVED || isOpen(branch)) {
       out.push(branch);
       continue;
     }
@@ -127,7 +137,7 @@ function collectTargets(schema, segments, root, throughLists, out, active = NO_R
 export function schemaHasPath(schema, segments, root = schema) {
   const targets = [];
   collectTargets(schema, segments, root, true, targets);
-  return targets.length > 0;
+  return targets.some((target) => target !== UNRESOLVED);
 }
 
 const TITLE_TYPES = new Set(["string", "number", "integer"]);
@@ -139,19 +149,24 @@ const TITLE_TYPES = new Set(["string", "number", "integer"]);
 export function schemaTitleIsText(schema, segments, root = schema) {
   const targets = [];
   collectTargets(schema, segments, root, false, targets);
-  return targets.some((target) =>
-    isOpen(target) ||
-    branches(target, root).some((branch) => {
-      if (isOpen(branch)) return true;
-      const types = Array.isArray(branch.type) ? branch.type : [branch.type];
-      return types.some((type) => TITLE_TYPES.has(type));
-    }),
+  return targets.some(
+    (target) =>
+      target !== UNRESOLVED &&
+      (isOpen(target) ||
+        branches(target, root).some((branch) => {
+          if (isOpen(branch)) return true;
+          const types = Array.isArray(branch.type) ? branch.type : [branch.type];
+          return types.some((type) => TITLE_TYPES.has(type));
+        })),
   );
 }
 
 /**
- * As folhas abaixo de `schema`. Um `$ref` que volta a um schema já no caminho atual (uma estrutura
- * recursiva) entra em `open` naquele ponto: abaixo dele, qualquer profundidade pode chegar ao modelo.
+ * As folhas abaixo de `schema`. Entram em `open`, no ponto em que aparecem, o schema sem forma, o
+ * `$ref` que volta a um schema já no caminho atual (uma estrutura recursiva) e o `$ref` que não
+ * resolve: abaixo deles, qualquer campo pode chegar ao modelo. Um objeto que aceita chaves não
+ * declaradas (`additionalProperties: true`, como o `.passthrough()` do zod) entra como `<ponto>.*`,
+ * a mesma marca da chave de um mapa, porque a projeção copia o objeto inteiro.
  */
 function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, depth = 0) {
   if (depth > MAX_DEPTH) {
@@ -159,7 +174,7 @@ function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, dep
     return;
   }
   for (const { schema: branch, active: refs } of expand(schema, root, active)) {
-    if (branch === CYCLE || isOpen(branch)) {
+    if (isMarker(branch) || isOpen(branch)) {
       open.add(prefix);
       continue;
     }
@@ -176,10 +191,13 @@ function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, dep
       }
     }
     const additional = branch.additionalProperties;
-    if (additional !== null && typeof additional === "object") {
+    const hasAdditional = additional === true || (additional !== null && typeof additional === "object");
+    if (additional === true) {
+      open.add(`${prefix}.*`);
+    } else if (hasAdditional) {
       collectLeaves(additional, `${prefix}.*`, root, leaves, open, refs, depth + 1);
     }
-    if (!hasProperties && !(additional !== null && typeof additional === "object")) leaves.add(prefix);
+    if (!hasProperties && !hasAdditional) leaves.add(prefix);
   }
 }
 
@@ -190,8 +208,10 @@ function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, dep
  * ao modelo por um caminho que termina num contêiner.
  *
  * - `leaves`: caminhos das folhas, com ponto e sem índice de lista; `*` marca a chave de um mapa;
- * - `open`: pontos em que o schema não declara forma (`z.unknown()`, `z.any()`) ou volta a si mesmo
- *   por `$ref`: qualquer campo abaixo deles pode ir ao modelo, e a conferência não alcança.
+ * - `open`: pontos por onde qualquer campo pode ir ao modelo sem que a conferência alcance: o schema
+ *   que não declara forma (`z.unknown()`, `z.any()`), o `$ref` que volta a si mesmo ou que não
+ *   resolve, e, como `<ponto>.*`, o objeto que aceita chaves não declaradas
+ *   (`additionalProperties: true`, do `.passthrough()` do zod).
  */
 export function assistantContextLeaves(output, context, root = output) {
   return context.map((path) => {

package/docs/adr/0052-floating-layer-coexists-with-modal-surfaces.md

@@ -225,6 +225,17 @@ camada uma vez. No modal, o Esc fecha o modal, como hoje. A alternativa de fecha
 está visualmente por cima foi descartada: quem preenche o modal e aperta Esc quer sair do modal, não
 do painel que nem está usando.
 
+*Nota (2026-10-05):* a regra vale para a camada que tem o que fechar. Uma camada sem
+`onEscapeKeyDown` não engole o Esc: com a pessoa nela, a tecla segue para o modal de trabalho, que
+fecha como fecharia com a pessoa nele. Antes, o Opus marcava o evento e chamava um handler ausente,
+e nem o modal nem a camada reagiam; quem chegava ao FAB pelo Tab e apertava Esc encontrava uma
+tecla sem efeito. Com o handler, nada muda: a camada recebe a tecla e o modal continua aberto. O
+consumidor que só tem o que fechar com o painel aberto passa o handler nesse estado e `undefined`
+com o FAB, como a Grand Brasil já faz. A revisão também apontou o handler presente que não tem o que
+fechar naquele momento; o Opus não consegue distinguir esse caso, e a forma de dizer “não há nada a
+fechar aqui” é não passar o handler. Os testes do pacote cobrem o FAB focado e o clique numa área
+sem foco da camada, com Dialog e Drawer, e o navegador real cobre o FAB alcançado pelo Tab.
+
 Antes dessa regra vale a do Radix: um `DismissableLayer` aberto depois do modal consome o Esc, onde
 quer que a pessoa esteja. Isso dá três exceções conhecidas e aceitas:
 
@@ -658,6 +669,12 @@ cada repositório, o que mantém uma só pilha de escopos e um só contexto de `
   navegadores. O roteiro manual acima fica para a adoção na Grand Brasil, executado no Mac do João
   (Safari com VoiceOver) e no Firefox antes de a adoção chegar à `main` da Grand Brasil, com o
   resultado registrado na entrega da adoção.
+
+  *Nota (2026-10-05):* o roteiro manual não foi executado. Na adoção pela Grand Brasil, o dono do
+  produto decidiu seguir sem ele. A evidência da camada é a dos testes de navegador do pacote, no
+  Chromium real, somada aos testes da adoção. Safari, Firefox e VoiceOver continuam sem
+  verificação. Se aparecer em uso um problema de leitor de tela, de Safari ou de Firefox com a
+  camada sobre um modal, o roteiro acima volta a ser exigido.
 - **Arquitetura:**
   - todo uso de portal em `src/ui` lê o contêiner da camada;
   - só `modal-layers.ts`, `dialog.tsx`, `drawer.tsx` e `floating-layer.tsx` aplicam as exceções;
@@ -666,3 +683,5 @@ cada repositório, o que mantém uma só pilha de escopos e um só contexto de `
   - o teste de numeração de ADRs continua passando.
 - **Na Grand Brasil:** um teste do shell confirma que o FAB e o painel ficam dentro de
   `[data-slot="floating-layer"]`, e o roteiro de navegador acima roda na pilha de desenvolvimento.
+  *Nota (2026-10-05):* o roteiro foi dispensado na adoção e não rodou; ver a nota da mesma data no
+  item **Navegador real**.

package/docs/adr/0053-read-action-declares-the-resource-assistant.md

@@ -355,7 +355,14 @@ aberto assim:
   `assistantContextLeaves(output, context)`: a partir do JSON Schema da saída, como o manifest o
   traz, devolve por caminho os campos folha alcançados e os pontos sem forma declarada ou em que um
   `$ref` volta a si mesmo, por onde qualquer campo pode passar. O subpath publica tipos
-  (`assistant-schema.d.mts`) para um teste em TypeScript estrito.
+  (`assistant-schema.d.mts`) para um teste em TypeScript estrito. *Nota (2026-10-05):* dois pontos
+  por onde qualquer campo passa ficavam fora de `open`. Um `$ref` que não resolve dentro do schema
+  sumia sem aparecer em `leaves` nem em `open`; agora entra em `open` no ponto em que aparece. Um
+  objeto que aceita chaves não declaradas (`additionalProperties: true`, que o `.passthrough()` do
+  zod produz) era tratado como fechado, embora a projeção copie o objeto inteiro; agora entra em
+  `open` como `<caminho>.*`, a mesma marca da chave de um mapa. A conferência do `opus gen` não
+  muda: um caminho abaixo de um `$ref` que não resolve continua recusado, e ele não vale como
+  `title`.
 
 ## Consequências
 

package/docs/protocol.md

@@ -263,7 +263,10 @@ o dado necessário. A action `view` que lê o recurso declara as três coisas em
   um intermediário `null` aparece como `null`. Num campo anulável ou numa união, o `opus gen` aceita
   o caminho que existe em algum ramo não nulo. Um caminho que termina num objeto ou numa lista leva
   tudo abaixo dele (`assistantContextLeaves`, de `@softize/opus/assistant-schema`, lista o que cada
-  caminho alcança). `title` aponta para texto ou número, fora de lista.
+  caminho alcança: em `leaves`, as folhas; em `open`, os pontos por onde qualquer campo passa sem
+  conferência, como um schema sem forma, um `$ref` recursivo ou que não resolve e, como
+  `<caminho>.*`, um objeto com `additionalProperties: true`). `title` aponta para texto ou número,
+  fora de lista.
 - **Leitura.** `runtime.readResource(resource, id, base, { context? })` executa a action dona com
   `{ id }` pelo `execute`: autorização, loaders, auditoria, marca de dado pessoal e span são os da
   action. Devolve `{ ok: true, resource: { kind, id, title, label, skill }, context?, meta }` ou o

package/package.json

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

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

@@ -14,7 +14,9 @@ export interface FloatingLayerProps {
   /**
    * 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.
+   * pertence ao consumidor. Sem o handler, o Esc com a pessoa na camada fecha o modal de trabalho
+   * aberto: passe `undefined` enquanto a camada não tiver o que fechar, como com o painel fechado e
+   * só o botão que o abre.
    */
   onEscapeKeyDown?: (event: KeyboardEvent) => void;
 }
@@ -49,9 +51,7 @@ export function FloatingLayer({
     const element = document.createElement("div");
     element.setAttribute("data-slot", "floating-layer");
     document.body.appendChild(element);
-    const unregister = registerFloatingLayer(element, (event) =>
-      escapeRef.current?.(event),
-    );
+    const unregister = registerFloatingLayer(element, () => escapeRef.current);
     setHost(element);
     // Desfaz o registro, retira o hospedeiro e, se o foco estava nele com um modal aberto,
     // devolve o foco ao modal.

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

@@ -225,7 +225,12 @@ caminho que passa por uma lista vale para cada item, e um campo intermediário `
 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.
+schema de saída do manifest. Ela devolve, por caminho, as folhas em `leaves` e, em `open`, os pontos
+que a conferência não alcança e por onde qualquer campo pode passar: um campo sem forma declarada
+(`z.unknown()`, `z.any()`), uma estrutura recursiva, uma referência que não resolve e, como
+`<caminho>.*`, um objeto que aceita chaves não declaradas (`.passthrough()`). Num teste que reprova
+campo pessoal, trate também `open`: reprove cada ponto aberto ou justifique por que ele não leva dado
+pessoal. 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

package/src/ui/docs/content/floating-layer.md

@@ -38,7 +38,7 @@ function AssistantDemo() {
         </DialogContent>
       </Dialog>
       {editing && (
-        <FloatingLayer onEscapeKeyDown={() => setAssistant(false)}>
+        <FloatingLayer onEscapeKeyDown={assistant ? () => setAssistant(false) : undefined}>
           {assistant ? (
             <aside
               aria-label="Assistente"
@@ -126,6 +126,11 @@ não recebe foco, nenhum modal fecha e o Opus chama `onEscapeKeyDown` uma vez po
 no modal, o Esc fecha o modal, como sempre. Sem modal aberto, `onEscapeKeyDown` também é chamado
 quando a pessoa está na camada.
 
+Passe `onEscapeKeyDown` só enquanto a camada tiver o que fechar. Sem ele, o Esc com a pessoa na
+camada segue para o modal aberto, que fecha. É o que permite a quem chega ao botão do assistente
+pelo Tab sair do modal com o Esc. No exemplo acima, o handler só existe com o painel aberto: com o
+painel, o Esc fecha o painel; com o botão, fecha o formulário.
+
 Trate o Esc da camada só por `onEscapeKeyDown`. Para impedir que o modal feche, o Opus marca o evento
 com `preventDefault` antes de ele chegar aos elementos da camada; um `onKeyDown` próprio para Esc no
 painel trataria a tecla duas vezes ou leria um evento já marcado.
@@ -164,15 +169,17 @@ você.
 - O hospedeiro carrega `aria-live="off"`, o valor padrão do atributo: a camada não anuncia mudanças
   por conta própria, e regiões vivas de dentro dela, como a de um [`Ask`](/ui/ask), mantêm o próprio
   comportamento. O atributo é o que mantém a camada visível ao leitor de tela com um modal aberto.
-- O foco e o Tab descritos acima são verificados em Chromium por testes automatizados. Safari,
-  Firefox e a leitura com VoiceOver ainda não foram verificados: o roteiro manual da ADR 0052 roda
-  na adoção pela Grand Brasil, em Safari com VoiceOver e no Firefox, antes de ela chegar à versão
-  principal da plataforma. Leitores de tela do Windows, como o NVDA, ficam fora dessa verificação.
+- O foco, o Tab e o Esc descritos acima são verificados em Chromium por testes automatizados.
+  Safari, Firefox e a leitura com VoiceOver não foram verificados. Em 2026-10-05, na adoção pela
+  Grand Brasil, o dono do produto dispensou o roteiro manual da ADR 0052 para esses navegadores, e
+  ele não foi executado. Se surgir um problema de leitor de tela, de Safari ou de Firefox com a
+  camada sobre um modal, o roteiro volta a ser exigido. Leitores de tela do Windows, como o NVDA,
+  ficam fora dessa verificação.
 
 ## Propriedades de FloatingLayer
 
-| Propriedade       | Tipo                             | Padrão | Descrição                                                                                                                                            |
-| ----------------- | -------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `children`        | `ReactNode`                      |        | Elementos da camada. Cada filho direto recebe clique e se posiciona contra a janela.                                                                 |
-| `className`       | `string`                         |        | Classes do hospedeiro. A posição de cada filho continua sendo sua.                                                                                   |
-| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` |        | Chamado uma vez por tecla quando a pessoa aperta Esc na camada, com ou sem modal aberto. Nenhum modal fecha nesse caso, e o Opus não fecha a camada. |
+| Propriedade       | Tipo                             | Padrão | Descrição                                                                                                                                                                                           |
+| ----------------- | -------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`        | `ReactNode`                      |        | Elementos da camada. Cada filho direto recebe clique e se posiciona contra a janela.                                                                                                                |
+| `className`       | `string`                         |        | Classes do hospedeiro. A posição de cada filho continua sendo sua.                                                                                                                                  |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` |        | Chamado uma vez por tecla quando a pessoa aperta Esc na camada, com ou sem modal aberto. Nenhum modal fecha nesse caso, e o Opus não fecha a camada. Sem ele, o Esc na camada fecha o modal aberto. |

package/src/ui/lib/modal-layers.ts

@@ -12,7 +12,8 @@ import * as React from "react";
  * - um único ouvinte no `body`, em borbulha, impede que `focusin`, `focusout`, `wheel` e `touchmove`
  *   ligados ao hospedeiro cheguem ao documento, onde a trava de foco do Radix e a trava de rolagem
  *   os veriam;
- * - o Esc age onde a pessoa está: na camada, chama o `onEscapeKeyDown` dela e não fecha o modal;
+ * - o Esc age onde a pessoa está: na camada que tem `onEscapeKeyDown`, chama esse handler e não
+ *   fecha o modal; na camada sem handler, segue para o modal, que fecha como sempre;
  * - o Tab passa do último elemento do modal para a camada e da camada de volta ao modal;
  * - quando o elemento focado da camada some, o foco volta ao modal;
  * - o hospedeiro carrega `aria-live="off"`, que faz o `hideOthers` do Radix preservá-lo.
@@ -37,9 +38,12 @@ interface ModalEntry {
   content: HTMLElement | null;
 }
 
+/** O `onEscapeKeyDown` corrente da camada; `undefined` quando ela não tem o que fechar. */
+export type LayerEscape = () => ((event: KeyboardEvent) => void) | undefined;
+
 interface LayerRecord {
   host: HTMLElement;
-  escape: (event: KeyboardEvent) => void;
+  escape: LayerEscape;
   dispose: () => void;
 }
 
@@ -328,7 +332,7 @@ function removeGlobalListeners(): void {
  */
 export function registerFloatingLayer(
   host: HTMLElement,
-  escape: (event: KeyboardEvent) => void,
+  escape: LayerEscape,
 ): () => void {
   const onPointerDown = (event: PointerEvent): void => {
     // Pertença decidida no aperto: no fim do clique, o elemento apertado pode já ter sumido.
@@ -354,7 +358,7 @@ export function registerFloatingLayer(
   const onDocumentKeyDown = (event: KeyboardEvent): void => {
     // Com um modal de trabalho aberto, a composição do modal já tratou o Esc e o marcou.
     if (event.key !== "Escape" || event.defaultPrevented) return;
-    if (layerWherePersonIs() === record) escape(event);
+    if (layerWherePersonIs() === record) escape()?.(event);
   };
   const observer = new MutationObserver(() => {
     if (pointerAnchor !== null && pointerAnchor.parentNode !== pointerLayer?.host) {
@@ -424,16 +428,20 @@ export function isLayerInteraction(event: {
 }
 
 /**
- * Esc no modal de trabalho do topo com a pessoa na camada: nenhum modal fecha e a camada recebe a
- * tecla uma única vez. O `preventDefault` impede o Radix de fechar e marca o evento para o ouvinte
- * da própria camada, que ignora eventos já tratados.
+ * Esc no modal de trabalho do topo com a pessoa numa camada que tem `onEscapeKeyDown`: nenhum modal
+ * fecha e a camada recebe a tecla uma única vez. O `preventDefault` impede o Radix de fechar e marca
+ * o evento para o ouvinte da própria camada, que ignora eventos já tratados.
+ *
+ * Numa camada sem handler, a camada não tem o que fechar, e o Esc segue para o modal (nota de
+ * 2026-10-05 na seção 5 da ADR 0052): engolir a tecla deixaria quem chega ao FAB pelo Tab sem
+ * nenhum efeito.
  */
 export function routeEscapeToLayer(event: KeyboardEvent): boolean {
   if (!layerExemptionsActive()) return false;
-  const layer = layerWherePersonIs();
-  if (layer === null) return false;
+  const escape = layerWherePersonIs()?.escape();
+  if (escape === undefined) return false;
   event.preventDefault();
-  layer.escape(event);
+  escape(event);
   return true;
 }