@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/ui/menu-nav.js

@@ -1,201 +1,121 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/menu-nav.ts — NAVEGAÇÃO UNIVERSAL de menus e diálogos: andar, escolher e voltar sem mouse.
+// ui/menu-nav.ts — UNIVERSAL menu and dialog navigation: move, choose and go back without a mouse.
 //
-// Este módulo é acessibilidade pura, e é o coração do pilar de a11y no que diz respeito a operação por
-// teclado (WCAG 2.1.1) e a ordem de foco (2.4.3). A regra que ele encarna é a do projeto, escrita no game.js
-// antes de qualquer código: QUALQUER menu aberto — o de pausa OU um submenu de configuração — é navegável
-// pelos MESMOS seis gestos, e esses seis gestos valem igualmente para teclado, controle, olhos e fala:
-//   · cima/baixo/esquerda/direita — andam entre itens; nos `select`/`slider`, esquerda/direita AJUSTAM o valor
-//   · sim   — confirma, alterna, entra
-//   · não   — volta ao menu anterior; na raiz, volta ao jogo (= Continuar)
-// Por isso o módulo não fala em "tecla": ele fala em INTENÇÃO (`NavKeys`). O teclado é só um dos tradutores —
-// input/gamepad.ts monta exatamente o mesmo `{yes,no,up,down,left,right}` e chama `navDialog`/`navPause` daqui.
-// É essa forma comum que faz "o jogo inteiro é operável de seis maneiras" ser verdade por construção e não por
-// disciplina.
+// Operation by keyboard (WCAG 2.1.1) and focus order (2.4.3). Any open menu — the pause card or a settings panel —
+// answers the SAME six intents, whether they come from the keyboard, a controller, the eyes or speech:
+//   · up/down/left/right — move between items; on a list, a slider or a steps control, left/right ADJUST the value
+//   · yes — confirm, toggle, enter
+//   · no  — back one level; at the pause card's root, back to the game
+// So the module speaks of INTENT (`NavKeys`), never of keys. The keyboard is one translator (`menuNavKey`, below);
+// `input/gamepad` builds the same `NavKeys` and calls `navDialog`/`navPause` from here. That shared shape is what makes
+// «every menu works six ways» true by construction rather than by discipline.
 //
-// O QUE VEIO, E DE ONDE (bloco "NAVEGAÇÃO UNIVERSAL de menus" do game.js)
-//  · `sharedDialogOpen` · `menuItems` · `menuFocus` · `dialogBack` — a leitura do "onde estou" e o voltar.
-//  · `navDialog` — andar dentro de um diálogo de configuração (o único lugar que ajusta select/slider).
-//  · `pauseSetSel` · `navPause` — andar dentro de um menu de pausa, que NÃO usa foco do navegador e sim uma
-//    classe de seleção própria (`.pm-sel`/`.pi-sel`), porque ele é desenhado dentro da tela do jogador.
-//  · `menuNavKey` — o tradutor de teclado, em fase de CAPTURA.
+// TWO KINDS OF MENU. A settings panel selects by browser FOCUS (`navDialog`). The pause card is drawn inside the player's
+// screen and selects by a CLASS (`.pm-sel`, `navPause`) — and a class fires no announcement, which is why the pause card
+// speaks its items through `srSay` and a panel does not need to for its focus.
 //
-// A DUPLICAÇÃO QUE ESTA EXTRAÇÃO CUROU
-// `sharedDialogOpen` do game.js e `topVisibleOverlay` de ui/settings-panel.ts eram A MESMA FUNÇÃO escrita
-// duas vezes: mesmo seletor de escopo (`#game-region .overlay`), mesmo filtro (`!hidden`), mesma ordenação
-// estável por z-index efetivo, mesmo "vence o último". Conferi as duas linha a linha antes de unificar. Aqui
-// `sharedDialogOpen` é um ALIAS de `ctx.topVisibleOverlay` — o nome antigo sobrevive porque input/gamepad.ts o
-// consome por esse nome, mas o CÓDIGO agora existe uma vez só, em ui/settings-panel.ts. O ganho não é linha de
-// menos: enquanto eram duas, uma correção de escopo (é justamente o que o defeito 1 abaixo pede) podia ser
-// aplicada num lado e não no outro, e o sintoma seria "às vezes o foco volta".
+// `sharedDialogOpen` is an ALIAS of `ui/settings-panel.topVisibleOverlay`, not a copy: the two were once the same function
+// written twice, and a scope fix applied to one would not have reached the other.
 //
-// ======================= DOIS DEFEITOS CONHECIDOS — PRESERVADOS VERBATIM, NÃO CONSERTE =======================
+// ======================= TWO KNOWN DEFECTS, PINNED BY TESTS — DO NOT FIX ONE WITHOUT THE OTHER =======================
 //
-// DEFEITO 1 — o escopo de `sharedDialogOpen` não alcança os menus de pausa (WCAG 2.4.3 · foco perdido).
-// O escopo é `#game-region .overlay`. Os nove diálogos de configuração estão lá (o `inCanvasMenus()` do game.js
-// reparenta os onze elementos para dentro do `#game-region`), MAS os menus de pausa por tela são
-// `.screen-pause` — classe diferente, construída por ui/pause-icons.ts, e nunca `.overlay`. Consequência:
-// `menuFocus(sharedDialogOpen())` devolve `null` quando o último diálogo se fecha, `menuFocus` sai pelo guarda
-// de nulo, e o foco fica no botão que acabou de ficar `hidden` — o navegador o joga no `<body>`. Quem sofre são
-// `#typo` (closeTypo) e `#help` (closeHelp), os dois únicos que devolvem o foco por esse caminho.
+// DEFECT 1 — `sharedDialogOpen`'s scope does not see the pause card (WCAG 2.4.3, focus lost). The scope is
+// `#game-region .overlay`; the pause card is `.screen-pause`, never `.overlay`. When the last dialog closes over an open
+// pause card, `menuFocus(sharedDialogOpen())` receives `null`, leaves at its guard, and the focus stays on a button that
+// has just become hidden — the browser drops it on `<body>`.
 //
-// O QUE EU VERIFIQUEI ANTES DE ESCREVER ISTO (a nota do coordenador estava certa, e a conclusão dela também):
-// li os NOVE `close*` e o `app/index.html` inteiro, um por um. De todos os nove, só UM devolve o foco de fato:
-//   · touchcfg  → `#opt-touchcfg`  — EXISTE (index.html, dentro do painel #movement). Funciona.
-//   · options   → `#opt-controls`  — NÃO existe no index.html. No-op silencioso.
-//   · movement  → `#opt-movement`  — NÃO existe. No-op.
-//   · visual    → `#opt-visual`    — NÃO existe. No-op.
-//   · audio     → `#opt-sound`     — NÃO existe. No-op.
-//   · animation → `#opt-animation` — NÃO existe (o próprio game.js já anota isso na linha do `#animation-close`).
-//   · empathy   → `#opt-empathy`   — NÃO existe. No-op.
-//   · typo/help → `menuFocus(sharedDialogOpen())` — o caminho quebrado descrito acima.
-// Os ids que EXISTEM no index.html com prefixo `opt-` são: opt-title, opt-telas, opt-letra, opt-facil,
-// opt-altmove, opt-touchcfg, opt-eyes, opt-modocego, opt-tts, opt-onebtn, opt-wheelchair, opt-hearing,
-// opt-captions. Nenhum `#opt-visual`/`#opt-sound`/`#opt-movement`/`#opt-controls`/`#opt-empathy`/`#opt-animation`
-// — são ganchos para uma barra de botões que ainda não existe. Ou seja: NÃO é "sete certos e dois errados". É
-// "um certo e oito quebrados, por duas causas diferentes" — e a causa dos oito (botão inexistente) não é a
-// mesma dos dois (escopo do seletor). Quem consertar precisa saber disso, porque arrumar só o escopo deixa oito
-// painéis ainda largando o foco.
+// DEFECT 2 — Escape is resolved in CAPTURE, by z-index, and consumed with `stopPropagation()`. `menuNavKey` runs before
+// any bubble listener on the window, so the topmost visible dialog is the one that closes, and the registration-order
+// chain (`overlays.escapeTarget()`, read by `input/keydown`) never decides while a dialog is open. Escape is also the same
+// intent as action3 (`no`): at the pause card's root it means «back to the game», and nothing tells «close a dialog» from
+// «leave the pause» apart. The capture and the `stopPropagation()` are also what keep a later window listener — a game's
+// own keydown — from acting on the same Escape: removing them without a replacement lets one key do two things.
 //
-// DEFEITO 2 — `menuNavKey` trata Escape como "voltar", em CAPTURA, com `stopPropagation()`, e resolve por
-// z-index em vez de pela cadeia registrada. `addEventListener('keydown', menuNavKey, true)` roda ANTES do
-// ouvinte principal do game.js (que é de BOLHA, na mesma janela); o `stopPropagation()` na fase de captura
-// impede o evento de descer e, portanto, de voltar — o ouvinte de bolha nunca vê a tecla. Efeitos verificados
-// lendo os dois ouvintes lado a lado:
-//   (a) a cadeia `overlays.escapeTarget()` (ORDEM DE REGISTRO: options→movement→animation→visual→empathy→
-//       audio→typo→touchcfg→help) é código morto com o jogo pausado. Quem decide é o topo da pilha de z-index.
-//       O próprio game.js já anota isso ("MEDIDO no navegador") no ouvinte de bolha.
-//   (b) `#help` e `#touchcfg` estão registrados com `inEscapeChain:false` e por isso ficam fora da cadeia de Escape.
-//       Enquanto a captura os cobrir por z-index, Escape os fecha; se alguém tirar o `stopPropagation()` ou a
-//       fase de captura sem antes dar flag aos dois, a tecla cai no ouvinte de bolha e o
-//       `if(Escape||Enter) togglePause()` de lá DESPAUSA O JOGO com o diálogo de Ajuda ainda aberto.
-//       Ou seja: o comportamento correto de hoje depende de um `stopPropagation()`, não da cadeia — é uma rede
-//       de segurança acidental, e é exatamente o que o conserto vai mexer.
-//   (c) Escape é a MESMA intenção que "especial" do gamepad (`no`). Não há como distinguir "fechar diálogo" de
-//       "voltar ao jogo" — na raiz do menu de pausa, `no` faz `setPhase('playing')`.
-// `menuNavKey` é exportado por si só (e não só instalado) justamente para o teste poder dispará-lo sem depender
-// de fase de propagação, e `attach()` existe para o game.js instalar exatamente como antes.
+// `tests/menu-nav.browser.test.js` and `tests/menu-nav.node.test.js` pin both as they are today, and fail on purpose if
+// the region is «improved» without the whole fix. `menuNavKey` is exported on its own so a test can fire it without
+// depending on the propagation phase; `attach()` installs it.
+// ======================================================================================================================
 //
-// Os testes de `menu-nav` PINAM os dois comportamentos ACIMA como estão hoje. Eles falham de propósito se
-// alguém "melhorar" a região sem tratar o conserto inteiro — que é o ponto: o conserto futuro precisa da rede.
-// ============================================================================================================
+// WHAT IS NOT HERE: the overlay stack, the registry and closing by id belong to `ui/settings-panel` — this module
+// consumes `topVisibleOverlay` and `closeById` and reimplements nothing. The quick bar belongs to `ui/pause-icons`; this
+// module only asks whether a screen is on it (`onBar`) and hands it a step (`navBar`).
 //
-// O QUE FICOU DE FORA, E POR QUÊ
-//  · `updateTitleLegend` foi para ui/shell.ts, não para cá. Ela não navega nada — não lê foco, não trata tecla,
-//    não anda entre itens; pinta o rodapé de UMA tela (o título) e quem a chama é `setPhase('title')`. Trazê-la
-//    obrigaria a casca a importar o módulo de navegação só para desenhar uma legenda.
-//  · `padKind()` não veio para lugar nenhum: JÁ ESTÁ em `input/touch.ts` (Onda A), com corpo idêntico, e a
-//    cópia do game.js não tem chamador nenhum. É código morto duplicado — apagar, não mover.
-//  · `navTitle`/`titleButtons` são de ui/activities-menu.ts (menu inicial), já extraídos.
-//  · A pilha de z-index, o registro de overlays e o fechar por id são de ui/settings-panel.ts. Este módulo
-//    CONSOME (`topVisibleOverlay`, `closeById`) e não reimplementa.
+// INJECTION: nothing is reached. `isNavigable`, `withIndex` and `onBar` are QUESTIONS asked of the ctx rather than state
+// read from `core/state`, so a game answers in its own model — a quiz whose settings are always open answers
+// `isNavigable(): true` without pretending to be paused. `getPauseMenu`, `closePadWiz`, `isCapturing` and `setPhase` are
+// resolved at call time, because what they reach is built in the root after this module.
 //
-// INJEÇÃO E ORDEM DE BOOT
-//  · `phase` entra como binding vivo de core/state.ts (deixou de ser `let` do game.js na Fase 2) — mesmo
-//    precedente de game/session.ts e input/touch.ts. O que AINDA é `let` do game.js entra por getter:
-//    `vpPause` (`getPauseMenu(i)`), reatribuído por `buildGameHud`.
-//  · `closePadWiz` é LAZY (`(save) => gamepadApi.closePadWiz(save)`): input/gamepad.ts é `const` do game.js e o
-//    ctx DELE consome `sharedDialogOpen`/`navDialog`/`navPause` daqui. A dependência é mútua, e a única forma
-//    de quebrar o ciclo sem reordenar o boot é ela ser resolvida na CHAMADA. Mesmo motivo para `isCapturing`
-//    (ui/settings-controls.ts) e para `setPhase` (o envelope içado do game.js sobre ui/shell.ts).
-//  · `actionOf`/`whichPlayer` entram já ligados a input/keyboard-runtime.ts, que é `const` declarado bem no
-//    alto do game.js — mas entram como callback mesmo assim, porque o roteamento por jogador é dele e não daqui.
-//
-// SEM I/O NO IMPORT: o corpo do módulo só declara dados e funções puras. Todo efeito passa por `initMenuNav`.
-//
-// Ver docs/5-Refactoring/plano-modularizacao-mapa.md (C3).
+// NO I/O ON IMPORT: the module body only declares data and pure functions. Every effect goes through `initMenuNav`.
 // ---------------------------------------------------------------------------------------------------------
-// PURO — a decisão de navegação, sem DOM. Testável no project `node`.
+// PURE — the navigation decision, without a DOM. Testable in the `node` project.
 // ---------------------------------------------------------------------------------------------------------
-/* As tabelas de tecla GENÉRICA (as que valem para qualquer jogador, mesmo sem remap). Viraram `Set` porque é
-   o que elas sempre foram semanticamente — pertinência, não ordem — e porque um `Set` nomeado deixa a tabela
-   auditável de fora (o teste importa a constante em vez de repetir os literais). Conteúdo VERBATIM. */
-/** Confirma/entra. `NumpadEnter` conta aqui (mas NÃO pausa: ver o ouvinte de bolha do game.js). */
-export const KEY_YES = new Set(['Space', 'KeyJ', 'Enter', 'NumpadEnter']);
-/** Volta. ⚠️ DEFEITO 2: `Escape` é a MESMA intenção que a ação "especial" do gamepad. Verbatim. */
-export const KEY_NO = new Set(['Escape']);
-export const KEY_UP = new Set(['ArrowUp', 'KeyW']);
-export const KEY_DOWN = new Set(['ArrowDown', 'KeyS']);
-export const KEY_LEFT = new Set(['ArrowLeft', 'KeyA']);
-export const KEY_RIGHT = new Set(['ArrowRight', 'KeyD']);
-/**
- * Traduz (tecla física, ação remapeada do dono da tecla) → intenção. `act` é `null` quando a tecla não é de
- * nenhum jogador (tecla genérica). Verbatim das seis linhas de `menuNavKey`.
- */
-export function menuKeyIntent(code, act) {
-    return {
-        yes: KEY_YES.has(code) || act === 'action2',
-        no: KEY_NO.has(code) || act === 'action3',
-        up: KEY_UP.has(code) || act === 'up',
-        down: KEY_DOWN.has(code) || act === 'down',
-        left: KEY_LEFT.has(code) || act === 'left',
-        right: KEY_RIGHT.has(code) || act === 'right',
-    };
-}
-/** Alguma intenção foi expressa? Definição única em input/edges; aqui só o nome que este módulo sempre teve. */
+/** Was any intent expressed? Defined once in input/edges; here under the name this module has always used. */
 import { hasNavIntent as hasIntent } from '../input/edges.js';
-import { mostrarSubmenuDaPausa, PM_ITENS_VISIVEIS } from './pause-icons.js';
-import { anunciarItem } from './item-announcement.js';
-import { rotuloAcessivel } from '../core/rotulo-acessivel.js';
-import { passoNoAnel } from '../core/anel.js';
+import { showPauseOptions, PM_VISIBLE_ITEMS } from './pause-icons.js';
+import { announceItem } from './item-announcement.js';
+import { accessibleLabel } from '../core/accessible-label.js';
+import { stepInRing } from '../core/ring.js';
+import { navigableItems } from './menu-items.js';
+import { menuKeyIntent, selectStep, selectWrap, rangeStep, stepInPause } from './menu-intent.js';
 export { hasNavIntent as hasIntent } from '../input/edges.js';
-// A CONTA DO ANEL mudou de casa para `core/anel` no item 7 do ADR-0044: `ui/pause-icons` passou a precisar
-// dela, e como ESTE módulo já importa aquele, a volta fecharia um ciclo de importação — que em ESM não
-// estoura na hora, estoura no boot em TDZ. O nome público fica: é daqui que os menus e os testes já a
-// importavam, e mudar isso seria pedir uma edição em cada um deles para não ganhar nada.
-export { passoNoAnel } from '../core/anel.js';
-/** `select` com esquerda/direita: um passo, SEM dar a volta — ajustar VALOR não é navegar lista (ver acima). */
-export function selectStep(selectedIndex, optionsLen, delta) {
-    return Math.max(0, Math.min(optionsLen - 1, selectedIndex + delta));
-}
-/** `select` com "sim": um passo, COM volta. É a diferença deliberada entre confirmar e ajustar. */
-export function selectWrap(selectedIndex, optionsLen) {
-    return (selectedIndex + 1) % optionsLen;
-}
-/** `input[type=range]` com esquerda/direita: um `step` (default 1), preso entre `min` e `max`. */
-export function rangeStep(value, min, max, step, delta) {
-    const st = step || 1; // `+cur.step||1`: step ausente/0/NaN vira 1, verbatim
-    return Math.max(min, Math.min(max, value + delta * st));
-}
+// The ring's arithmetic lives in `core/ring`: `ui/pause-icons` needs it too, and this module imports that one, so keeping
+// it here would close an import cycle — which in ESM does not fail on the spot, it fails at boot in the TDZ. The public
+// name stays here because the menus and the tests import it from here.
+export { stepInRing } from '../core/ring.js';
+// The items' selector lives in `ui/menu-items` (ADR-0158): what counts as an item is defined once, and the spoken
+// «N of M» and the panel shell read the same list.
 /**
- * O PASSO DO CURSOR NO MENU DE PAUSA — um ANEL, agora que a pausa é uma lista (ADR-0044, itens 1 e 7).
+ * The parts a panel control SAYS (ADR-0159 rule 1, XAG 106: «Gamma, slider, 38%, 6 of 9»): the label with the ROLE, and
+ * the VALUE. The index is added by `announceItem`.
  *
- * ISTO SUBSTITUI `pauseGridMove`, e a substituição é o desfecho do ADR-0044, não uma limpeza. O que havia
- * era uma GRADE de duas zonas — a barra de dez ícones em cima, a lista de itens em duas colunas embaixo — e
- * uma fronteira entre elas com quatro regras próprias ("de cima, 'baixo' cai sempre no primeiro item", "da
- * primeira linha, 'cima' sobe para o ícone de mesmo índice", …). Cada regra dessas era uma coisa a mais para
- * a criança descobrir sem ver, e nenhuma delas era descobrível: só se aprendia esbarrando.
- *
- * A XAG 106 permite laço para menu LINEAR e o PROÍBE para grade de duas dimensões — numa grade, dar a volta
- * teleporta o cursor para o outro canto e a pessoa perde a noção de onde está. Era por isso que o anel do
- * item 1 valia para todo menu do jogo MENOS este. Com a barra no HUD (item 7), o cartão passou a ter uma
- * lista só, e o laço deixou de ser proibido para virar o recomendado.
- *
- * O que se ganha em troca das quatro regras: `quit` fica a UMA tecla para CIMA de `resume`. Último na
- * leitura, vizinho no dedo.
+ * The label is the row's `<strong>` when the control lives in one (it is what is SEEN, and a switch's text is its state,
+ * not its name); outside a row, or on a slider with a name of its own («Volume de Música»), it is the accessible name.
  */
-export function passoNaPausa(len, idx, k) {
-    const d = (k.down || k.right) ? 1 : -1;
-    return passoNoAnel(len, idx < 0 ? 0 : idx, d);
+export function controlParts(t, el) {
+    const row = el.closest('.ctrl-row')?.querySelector('strong')?.textContent?.trim() || '';
+    const [, role, read] = CONTROL_KINDS.find(([recognises]) => recognises(el));
+    const { label, value } = read(el, row, accessibleLabel(el), t);
+    return { label: `${label}, ${t(role)}`, state: value };
 }
-/** Os controles que contam como "item navegável" de um menu. Verbatim do seletor do `menuItems`. */
-const ITEM_SELECTOR = 'button:not([disabled]), select:not([disabled]), input[type=range]:not([disabled])';
-/** Onde os itens moram: o card do diálogo (`.overlay__card`) ou o card da pausa (`.pause-card`). */
+/** A slider's position as a whole percentage: a missing maximum reads as 100, and a range of zero width as 0. */
+function sliderPercent(r) {
+    const min = +r.min || 0, max = +r.max || 100;
+    const pct = max > min ? Math.round(((+r.value - min) / (max - min)) * 100) : 0;
+    return `${pct}%`;
+}
+/**
+ * HOW EACH KIND OF CONTROL IS RECOGNISED AND READ, and the ORDER is the rule: the first row that recognises the element reads
+ * it, and the last — a button — recognises everything. A stepper and a slider prefer their own name (a slider can be «Music
+ * volume» on a row called «Sound»); the others prefer the row's label, because the text of a switch is its state, not its name.
+ */
+const CONTROL_KINDS = [
+    [(el) => el.hasAttribute('data-passos'), 'sr.papel.passos',
+        (el, row) => ({ label: el.getAttribute('aria-label') || row, value: el.getAttribute('aria-valuetext') ?? '' })],
+    [(el) => el.tagName === 'SELECT', 'sr.papel.lista',
+        (el, row, name) => ({ label: row || name, value: el.selectedOptions?.[0]?.textContent?.trim() ?? '' })],
+    [(el) => el.tagName === 'INPUT', 'sr.papel.cursor',
+        (el, row) => ({ label: el.getAttribute('aria-label') || row, value: sliderPercent(el) })],
+    [(el) => el.hasAttribute('aria-pressed'), 'sr.papel.interruptor',
+        (el, row, name, t) => ({ label: row || name, value: t(el.getAttribute('aria-pressed') === 'true' ? 'state.on' : 'state.off') })],
+    [(el) => el.getAttribute('role') === 'radio', 'sr.papel.opcao',
+        (el, row, name, t) => ({ label: row || name, value: el.getAttribute('aria-checked') === 'true' ? t('sr.estado.selecionado') : '' })],
+    [() => true, 'sr.papel.botao', (_el, _row, name) => ({ label: name, value: '' })],
+];
+/** Where the items live: the dialog's card (`.overlay__card`) or the pause card (`.pause-card`). */
 const CARD_SELECTOR = '.overlay__card, .pause-card';
 export function initMenuNav(ctx) {
-    /* ===================== diálogos de configuração ===================== */
-    // ALIAS, não cópia: o corpo mora em ui/settings-panel.ts. Ver "a duplicação que esta extração curou".
+    const { t } = ctx;
+    /* ===================== settings dialogs ===================== */
+    // An ALIAS, not a copy: the body lives in ui/settings-panel.ts (see the header).
     const sharedDialogOpen = () => ctx.topVisibleOverlay();
     function menuItems(menu) {
         const card = menu.querySelector(CARD_SELECTOR) || menu;
-        // `offsetParent === null` = fora do fluxo de layout (escondido, `display:none` ou dentro de aba oculta).
-        // É o único filtro de VISIBILIDADE real que existe aqui: sem ele o cursor pousa em botão invisível e o
-        // leitor de tela anuncia um controle que ninguém vê. Verbatim.
-        return [...card.querySelectorAll(ITEM_SELECTOR)].filter((el) => el.offsetParent !== null);
+        // The VISIBILITY filter (`offsetParent`) lives with the selector in `ui/menu-items`.
+        return navigableItems(card);
     }
     function menuFocus(menu) {
         if (!menu)
-            return; // ⚠️ DEFEITO 1: com os menus de pausa fora do escopo, este guarda é o fim da linha
+            return; // ⚠️ DEFECT 1: with the pause card outside the scope, this guard is the end of the line
         const it = menuItems(menu);
         if (!it.length)
             return;
@@ -204,116 +124,158 @@ export function initMenuNav(ctx) {
     }
     function dialogBack(menu) {
         if (!ctx.closeById(menu.id))
-            menu.hidden = true; // sem entrada no registro: some na marra
+            menu.hidden = true; // no registered entry: hide it outright
         menuFocus(sharedDialogOpen());
     }
-    /** Ajusta um `select` (esquerda/direita = passo preso; sim = passo com volta) e dispara `change`. */
+    /** Adjusts a `select` (left/right = a step that stops at the ends; yes = a step that wraps) and fires `change`. */
     function tweakSelect(el, delta) {
         el.selectedIndex = delta === 'wrap' ? selectWrap(el.selectedIndex, el.options.length) : selectStep(el.selectedIndex, el.options.length, delta);
         el.dispatchEvent(new Event('change', { bubbles: true }));
     }
-    /** Ajusta um `input[type=range]` em um `step` e dispara `input` (é o evento que os painéis escutam). */
+    /** Moves an `input[type=range]` by one `step` and fires `input` (the event the panels listen to). */
     function tweakRange(el, delta) {
         el.value = String(rangeStep(+el.value, +el.min, +el.max, +el.step, delta));
         el.dispatchEvent(new Event('input', { bubbles: true }));
     }
+    /**
+     * THE ITEM REACHED SAYS ITSELF (ADR-0159 rule 1): label, role, value and «N de M», in that order.
+     *
+     * The browser's focus moves by itself, but the engine's narration (the one a child playing in blind mode hears) does
+     * not listen to focus; it listens to this.
+     */
+    function sayItem(items, n) {
+        const el = items[n];
+        if (!el)
+            return;
+        const { label: partLabel, state: partState } = controlParts(t, el);
+        ctx.srSay(announceItem(t, { label: partLabel, state: partState, position: n + 1, total: items.length }, ctx.withIndex()));
+    }
+    function focusAndSay(items, n) {
+        items[n]?.focus();
+        sayItem(items, n);
+    }
+    /** Where the cursor is. With the focus outside the dialog (or on its card), it enters by the first item — and says it. */
+    function cursorIn(items) {
+        const idx = items.indexOf(ctx.getActiveElement());
+        if (idx >= 0)
+            return idx;
+        focusAndSay(items, 0);
+        return 0;
+    }
+    /**
+     * Left or right: a list, a slider or a steps control is ADJUSTED, and the new value is said — someone adjusting by ear has
+     * no other way to know where it stopped; anything else walks the ring, like up and down.
+     */
+    function sideways(items, idx, d) {
+        const cur = items[idx];
+        if (cur.tagName === 'SELECT') {
+            const before = cur.value;
+            tweakSelect(cur, d);
+            // an adjustment its owner refused (and put back) says nothing here: the owner already said why
+            if (cur.value !== before)
+                sayItem(items, idx);
+            return;
+        }
+        if (cur.tagName === 'INPUT') {
+            tweakRange(cur, d);
+            sayItem(items, idx);
+            return;
+        }
+        // A steps control ⯇ ⯈ (ADR-0151): left and right are the adjustment itself; its owner listens to `passo` (and announces).
+        if (cur.hasAttribute('data-passos')) {
+            cur.dispatchEvent(new CustomEvent('passo', { detail: d, bubbles: true }));
+            return;
+        }
+        focusAndSay(items, stepInRing(items.length, idx, d));
+    }
+    /** «Yes»: a list goes round and says the new option; a slider or a steps control has nothing to confirm; anything else is clicked. */
+    function confirm(items, idx) {
+        const cur = items[idx];
+        if (cur.tagName === 'SELECT') {
+            tweakSelect(cur, 'wrap');
+            sayItem(items, idx);
+            return;
+        }
+        if (cur.tagName === 'INPUT' || cur.hasAttribute('data-passos'))
+            return;
+        cur.click();
+    }
     function navDialog(menu, k) {
         const items = menuItems(menu);
         if (!items.length)
             return;
-        let idx = items.indexOf(ctx.getActiveElement());
-        if (idx < 0) {
-            idx = 0;
-            items[0].focus();
-        } // foco fora do diálogo (ou no card): entra pelo primeiro
-        const cur = items[idx];
+        const idx = cursorIn(items);
         if (k.no) {
             dialogBack(menu);
             return;
         }
         if (k.left || k.right) {
-            const d = k.right ? 1 : -1;
-            if (cur.tagName === 'SELECT') {
-                tweakSelect(cur, d);
-                return;
-            }
-            if (cur.tagName === 'INPUT') {
-                tweakRange(cur, d);
-                return;
-            }
-            items[passoNoAnel(items.length, idx, d)].focus();
+            sideways(items, idx, k.right ? 1 : -1);
             return;
         }
         if (k.up || k.down) {
-            items[passoNoAnel(items.length, idx, k.down ? 1 : -1)].focus();
+            focusAndSay(items, stepInRing(items.length, idx, k.down ? 1 : -1));
             return;
         }
-        if (k.yes) {
-            if (cur.tagName === 'SELECT') {
-                tweakSelect(cur, 'wrap');
-                return;
-            }
-            if (cur.tagName === 'INPUT')
-                return; // slider não tem "confirmar" — só ajuste
-            cur.click();
-        }
+        if (k.yes)
+            confirm(items, idx);
     }
-    /* ===================== menu de pausa (seleção por classe, não por foco) ===================== */
+    /* ===================== pause card (selected by class, not by focus) ===================== */
     /**
-     * Move o cursor do menu de pausa. Só ITENS: desde o item 7 do ADR-0044 a barra de ícones vive no HUD, e o
-     * cursor dela é dela.
-     *
-     * O QUE SAIU DAQUI, e vale registrar: esta função também escrevia a legenda dos ícones, porque o cursor
-     * atravessava a fronteira entre as duas zonas. Sem a fronteira, escrever legenda de ícone a partir do menu
-     * de pausa seria um módulo mexendo na tela de outro.
+     * Moves the pause card's cursor. Items only: since ADR-0044 item 7 the quick bar lives in the HUD and keeps its own
+     * cursor — writing the bar's caption from here would be one module drawing on another's screen.
      */
     function pauseSetSel(menu, el) {
         if (!el)
-            return; // índice fora da lista (menu vazio): não mexe em nada — verbatim
+            return; // an index outside the list (an empty card): touch nothing
         menu.querySelectorAll('.pm-sel').forEach((b) => b.classList.remove('pm-sel'));
         el.classList.add('pm-sel');
     }
     function navPause(menu, playerIndex, k) {
         if (k.no) {
-            // "não" DENTRO do submenu de opções volta à raiz, e não ao jogo (ADR-0044, item 5). A regra "voltar sai
-            // um nível" já valia para os diálogos de configuração (`dialogBack`); o que mudou é que o menu de pausa
-            // passou a TER um nível a mais. Sem esta linha, quem entra em Opções sem enxergar só sairia despausando.
-            const aberto = menu.querySelector('.pause-menu:not([hidden])');
-            if (aberto && aberto.dataset.sub === 'opcoes') {
-                mostrarSubmenuDaPausa(menu, 'raiz');
+            // «No» inside any sub-list goes up ONE level, to the root, and not back to the game (ADR-0044 item 5) — the same
+            // «back leaves one level» the settings dialogs have (`dialogBack`). The question is «is this NOT the root?», not
+            // «is this the options list?»: with three lists (ADR-0146), asking the second would make «no» from the game's own
+            // options resume the game when the child asked to go back.
+            const open = menu.querySelector('.pause-menu:not([hidden])');
+            if (open && open.dataset.sub && open.dataset.sub !== 'raiz') {
+                showPauseOptions(menu, 'raiz');
                 return;
             }
             ctx.setPhase('playing');
-            return; // "não" na raiz → volta ao jogo (retoma todos)
+            return; // «no» at the root → back to the game (resumes everyone)
         }
-        const items = [...menu.querySelectorAll(PM_ITENS_VISIVEIS)];
+        const items = [...menu.querySelectorAll(PM_VISIBLE_ITEMS)];
         const cur = menu.querySelector('.pm-sel') || items[0];
-        // "sim": o jogador que agiu vira o `pauseActor` (o submenu de a11y abre na aba dele) e o item é clicado.
+        // «Yes»: the player who acted becomes the `pauseActor` (the accessibility options open on their tab) and the item is clicked.
         if (k.yes) {
             ctx.setPauseActor(playerIndex);
             if (cur)
                 cur.click();
             return;
         }
-        // Guarda NOVA (o original estouraria em `cur.classList` aqui): menu sem `.pm-btn` nenhum. Não é o defeito
-        // preservado — é um TypeError, e trocar um crash por um no-op não tira rede de conserto nenhum.
+        // A card with no item at all: nothing to move (without this guard the next line throws on `cur`).
         if (!cur)
             return;
-        // UMA LISTA, um anel. A barra de ícones saiu do cartão no item 7 do ADR-0044, e com ela saíram as quatro
-        // regras de fronteira que ninguém conseguia descobrir sem esbarrar.
-        const n = passoNaPausa(items.length, items.indexOf(cur), k);
+        // ONE list, one ring: the quick bar is not in the card (ADR-0044 item 7), so there are no borders between zones to cross.
+        const n = stepInPause(items.length, items.indexOf(cur), k);
+        selectAndSayInPause(menu, items, n);
+    }
+    function selectAndSayInPause(menu, items, n) {
         pauseSetSel(menu, items[n]);
-        // E O ITEM NOVO É FALADO. Este menu não usa foco do navegador — seleciona por classe, porque é desenhado
-        // dentro da tela do jogador —, então nada dispara anúncio sozinho: nem foco, nem `aria-activedescendant`,
-        // nem região viva. MEDIDO no jogo construído: a seta andava e o `#sr-status` ficava vazio. O item 3 do
-        // ADR-0044 pede posição e total "em todo lugar", e este era o lugar onde ele não tinha chegado — o menu
-        // que o item 5 reconstruiu.
-        // `rotuloAcessivel` e não `textContent`: um item com `aria-label` seria narrado de um jeito pelo jogo e de
-        // outro pelo leitor de tela, e quem ouve os dois não teria como saber qual é a verdadeira.
-        ctx.srSay(anunciarItem({ rotulo: rotuloAcessivel(items[n]), posicao: n + 1, total: items.length }, ctx.comIndice()));
+        // AND THE NEW ITEM IS SPOKEN. This card selects by class, not by browser focus — it is drawn inside the player's
+        // screen — so nothing announces it by itself: no focus, no `aria-activedescendant`, no live region. ADR-0044 item 3
+        // asks for position and total everywhere.
+        // `accessibleLabel` and not `textContent`: an item with an `aria-label` would otherwise be narrated one way by the
+        // game and another by the screen reader, and whoever hears both could not tell which is true.
+        // 🔴 A LOCKED ITEM SAYS WHY when it is reached (ADR-0161): right after its name, and written in the footer.
+        const reason = items[n].getAttribute('aria-disabled') === 'true' ? (items[n].dataset.motivo ?? '') : '';
+        const announcement = announceItem(t, { label: accessibleLabel(items[n]), position: n + 1, total: items.length }, ctx.withIndex());
+        ctx.srSay(reason ? `${announcement}. ${reason}` : announcement);
+        ctx.explainItem?.(reason || null);
     }
-    /* ===================== teclado ===================== */
-    /** O assistente de gamepad fica POR CIMA de tudo: com ele aberto, só Escape passa (e cancela). */
+    /* ===================== keyboard ===================== */
+    /** The controller-mapping panel sits ON TOP of everything: while it is open, only Escape gets through (and cancels). */
     function padWizKey(e) {
         const pw = ctx.$('#padwiz');
         if (!pw || pw.hidden)
@@ -323,68 +285,133 @@ export function initMenuNav(ctx) {
             e.preventDefault();
             e.stopPropagation();
         }
-        return true; // aberto = consome (mesmo sem ser Escape: o resto do menu não navega por baixo dele)
+        return true; // open = consumed (even when it is not Escape: no menu underneath navigates while it is open)
     }
-    /** Consome a tecla: ela era nossa, e ninguém mais deve vê-la. Uma função só para o par nunca se separar. */
-    const consumir = (e) => { e.preventDefault(); e.stopPropagation(); };
+    /** Consumes the key: it was ours, and nobody else should see it. One function, so the pair never comes apart. */
+    const consume = (e) => { e.preventDefault(); e.stopPropagation(); };
     function menuNavKey(e) {
         if (ctx.isCapturing())
-            return; // remap em andamento: a tecla é dele
+            return; // a remap in progress: the key is its
         if (padWizKey(e))
             return;
-        // ===================== O MODO `accessibility` VEM ANTES DO GUARDA DE "NAVEGÁVEL" =====================
-        // `isNavigable()` é `phase === 'paused'`, e este modo roda com o jogo ANDANDO — é para isso que ele
-        // existe: ajustar a acessibilidade DURANTE a partida, sem parar. Se ele ficasse depois do guarda, a
-        // direção cairia no personagem e o modo não faria nada, que é a versão silenciosa da armadilha.
+        // ===================== THE QUICK BAR COMES BEFORE THE «NAVIGABLE» GUARD =====================
+        // `isNavigable()` can be false while the game runs (a platformer answers `phase === 'paused'`), and the bar works
+        // with the game RUNNING — that is what it is for: adjusting accessibility DURING play. After the guard, the
+        // direction would fall to the character and the bar would do nothing, silently.
         //
-        // No TECLADO a saída é Escape (o `no` do projeto). O START do controle é a segunda saída e entra por
-        // `input/gamepad`; aqui ele não tem par próprio, porque Enter já é "confirmar" e roubá-lo tiraria da
-        // criança o único jeito de ATIVAR o ícone sob o cursor.
-        const donoTecla = ctx.whichPlayer(e.code);
-        const pTecla = donoTecla < 0 ? 0 : donoTecla;
-        if (ctx.naBarraDe(pTecla)) {
-            const kb = menuKeyIntent(e.code, donoTecla >= 0 ? ctx.actionOf(e.code, pTecla) : null);
-            if (hasIntent(kb)) {
-                consumir(e);
-                ctx.navBar(pTecla, kb);
+        // On the KEYBOARD the way out is Escape (the project's `no`). A controller's START is the second way out and comes
+        // through `input/gamepad`; the keyboard has no pair of its own for it, because Enter is already «confirm» and taking
+        // it would leave the child no way to ACTIVATE the icon under the cursor.
+        const { player, keys } = intentOf(e.code);
+        if (ctx.onBar(player)) {
+            if (hasIntent(keys)) {
+                consume(e);
+                ctx.navBar(player, keys);
             }
-            return; // na barra, tecla de menu é da barra — com ou sem intenção, não desce para o personagem
+            return; // on the bar, a menu key belongs to the bar — with or without an intent, it does not reach the character
         }
-        if (!ctx.isNavigable())
-            return;
-        const owner = ctx.whichPlayer(e.code);
-        const pi = owner < 0 ? 0 : owner; // tecla genérica → Jogador 1
-        const k = menuKeyIntent(e.code, owner >= 0 ? ctx.actionOf(e.code, pi) : null);
-        if (!hasIntent(k))
+        if (!ctx.isNavigable() || !hasIntent(keys))
             return;
-        // A TECLA SÓ É CONSUMIDA SE HOUVER O QUE NAVEGAR. Antes, `preventDefault()` + `stopPropagation()` vinham
-        // AQUI, antes de se saber se havia diálogo ou menu aberto — e o `menuNavKey` matava o evento para depois
-        // descobrir que não tinha nada a fazer com ele. Na plataforma isso era invisível: `isNavigable()` é
-        // `phase === 'paused'`, e pausar ABRE o menu, então quase nunca havia um caso "navegável e nada aberto".
-        //
-        // No segundo consumidor não era invisível — era total. Um quiz cujos ajustes estão SEMPRE disponíveis
-        // responde `isNavigable(): true`, e com isso TODA tecla com intenção de menu morria aqui: as setas de
-        // escolher alternativa, e o `S` do sonar. Duas funcionalidades que existiam e não chegavam à criança.
+        navOpenMenu(e, player, keys);
+    }
+    /** Whose key this is — a key no player owns is Player 1's — and what it asks of a menu. */
+    function intentOf(code) {
+        const owner = ctx.whichPlayer(code);
+        const player = owner < 0 ? 0 : owner;
+        return { player, keys: menuKeyIntent(code, owner >= 0 ? ctx.actionOf(code, player) : null) };
+    }
+    /** The key moves the dialog on top if there is one, else the player's own pause card if it is open, else nothing. */
+    function navOpenMenu(e, pi, k) {
+        // THE KEY IS CONSUMED ONLY IF THERE IS SOMETHING TO NAVIGATE. A game whose settings are always open answers
+        // `isNavigable(): true`, and consuming before knowing would swallow every key with a menu intent — the arrows that
+        // choose an answer in the quiz, for one.
         //
-        // A REDE DE SEGURANÇA DO ESCAPE FICA INTACTA, e era o risco real desta mudança. O bloco (b) acima explica
-        // que `#help` e `#touchcfg` dependem do `stopPropagation()` para não deixarem a tecla cair no ouvinte de
-        // bolha, que despausaria o jogo com o diálogo aberto. Esses dois casos entram por `sharedDialogOpen()`
-        // — há diálogo, logo a tecla É consumida, exatamente como antes.
+        // DEFECT 2's safety net stays: with a dialog open the key IS consumed, so one Escape closes the dialog and no later
+        // listener sees it.
         const dlg = sharedDialogOpen();
         if (dlg) {
-            consumir(e);
+            consume(e);
             navDialog(dlg, k);
             return;
-        } // diálogo de a11y aberto: navega ele (compartilhado)
-        const menu = ctx.getPauseMenu(pi); // senão: menu de pausa do PRÓPRIO jogador
+        } // an accessibility dialog is open: it is the one navigated
+        const menu = ctx.getPauseMenu(pi); // otherwise: the player's OWN pause card
         if (menu && !menu.hidden) {
-            consumir(e);
+            consume(e);
             navPause(menu, pi, k);
         }
-        // Sem diálogo e sem menu: a tecla NÃO é nossa. Segue o caminho dela até quem for o dono.
+        // No dialog and no card: the key is NOT ours. It goes on to whoever owns it.
+    }
+    /* ===================== holding on an item ===================== */
+    /*
+     * A PRESS HELD ON AN ITEM PLACES THE CURSOR THERE AND SAYS IT, WITHOUT ACTIVATING IT (ADR-0159 rule 2, erratum of
+     * 2026-09-13). «Deixar o dedo apertado ou o botão do mouse apertado sobre o item deve dar a função de posicionar o
+     * cursor sem "apertar".» (Dev) — the pad left the menus (ADR-0166), and a pointer had one meaning only: activation.
+     * 📌 A short press is untouched; after a hold, the ONE click the browser fires on release is swallowed, in capture,
+     * before the item's own listener. Threshold: the iOS long-press default, 0.5 s.
+     */
+    const HOLD_MS = 500;
+    let holding = null;
+    let clickToSwallow = null;
+    /** The open menu and the item under `target`, when `target` is inside one: the top dialog first, else a pause card. */
+    function itemUnder(target) {
+        const no = target;
+        if (!no || typeof no.closest !== 'function')
+            return null;
+        const dlg = sharedDialogOpen();
+        if (dlg) {
+            const items = menuItems(dlg);
+            const n = items.findIndex((el) => el.contains(no));
+            return n >= 0 ? { menu: dlg, items, n, inPause: false } : null;
+        }
+        const menu = no.closest('.screen-pause');
+        if (!menu || menu.hidden)
+            return null;
+        const items = [...menu.querySelectorAll(PM_VISIBLE_ITEMS)];
+        const n = items.findIndex((el) => el.contains(no));
+        return n >= 0 ? { menu, items, n, inPause: true } : null;
+    }
+    function release() {
+        if (holding)
+            clearTimeout(holding.timer);
+        holding = null;
+    }
+    function onPress(e) {
+        release();
+        clickToSwallow = null;
+        const under = itemUnder(e.target);
+        if (!under)
+            return;
+        const id = e.pointerId;
+        holding = {
+            id,
+            timer: setTimeout(() => {
+                holding = null;
+                clickToSwallow = under.items[under.n] ?? null;
+                if (under.inPause)
+                    selectAndSayInPause(under.menu, under.items, under.n);
+                else
+                    focusAndSay(under.items, under.n);
+            }, HOLD_MS),
+        };
+    }
+    function onRelease(e) {
+        if (holding && holding.id === e.pointerId)
+            release();
+    }
+    function onClick(e) {
+        const swallowed = clickToSwallow;
+        clickToSwallow = null;
+        if (swallowed && e.target instanceof Node && swallowed.contains(e.target)) {
+            e.preventDefault();
+            e.stopPropagation();
+        }
     }
     function attach() {
         ctx.win.addEventListener('keydown', menuNavKey, true);
+        ctx.win.addEventListener('pointerdown', onPress, true);
+        ctx.win.addEventListener('pointerup', onRelease, true);
+        ctx.win.addEventListener('pointercancel', onRelease, true);
+        ctx.win.addEventListener('click', onClick, true);
     }
     return { sharedDialogOpen, menuItems, menuFocus, dialogBack, navDialog, pauseSetSel, navPause, menuNavKey, attach };
 }