@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/ui/settings-controls.js

@@ -1,116 +1,51 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/settings-controls — Keyboard-remap panel (Estágio 4): extracted from game.js's renderControls()/keyName()/
-// the captureAction+captureMapRef remap flow. Pure logic (key→label, cross-player conflict lookup) is separated
-// from the thin DOM-touching render()/handleCaptureKeydown(). DI via initSettingsControls(ctx): `$` (DOM
-// selector), `srSay`/`srAlert`, `store` (save/reset persistence), the live `kb` value + `setKB` setter, and the
-// shared per-player helpers (`kbFor`/`getNumPlayers`/`applyControls`/`assignControls`) that game.js also uses
-// elsewhere (gamepad binding, HUD, other settings panels) and therefore stay there, injected. Overlay open/close
-// plumbing (#options hidden toggle, focus management, Escape-closes-dialog) and the pad-button-design select are
-// shared/unrelated infra and stay in game.js. `openHelp()` (pause-menu help screen) reuses `keyName`, which is
-// exported here instead of duplicated.
-//
-// ⚠️ ELE TAMBÉM LIA O `ACT_LABEL`, E DEIXOU DE LER EM 2026-09-07. A tela de ajuda do cartucho passou a montar
-// as linhas do preset dele (`acoesDoJogo`), que é quem sabe quantas posições este jogo usa e como elas se
-// chamam. Com isso o `ACT_LABEL` ficou sem UM leitor sequer — conferido com `git grep` nos dois repositórios,
-// e o que resta dele são comentários e a própria declaração. Ver `docs/6-DevOps-SRE/Breaking-Changes.md`.
-import { t } from '../core/i18n.js';
-import { ACTIONS, isAction } from '../core/actions.js';
+import { isAction } from '../core/actions.js';
+import { keyName, keyUsedByOther, actionAlreadyBound } from './control-choices.js';
 import { markChanged } from './changed-mark.js';
+import { controlRow } from './panel-widgets.js';
 // ---------------------------------------------------------------------------------------------
 // Pure logic (no `document`, testable in node)
 // ---------------------------------------------------------------------------------------------
 /**
- * As oito posições do jogo de plataforma, ligadas às chaves de i18n das palavras DELE.
+ * The platformer's eight positions, tied to the i18n keys of ITS words.
  *
- * ⚠️ ELA TEM CONSUMIDOR, e eu já disse aqui que não tinha. A afirmação anterior — «sem um único consumidor,
- * nem aqui nem no `game-platformer`» — vinha de uma varredura com um padrão que **excluía o `main.ts`** do
- * cartucho, por ele estar directamente em `app/js/` e o glob exigir um subdirectório. Medido de novo com
- * `git grep`: `game-platformer/app/js/main.ts` importa-a e usa-a na TELA DE AJUDA do menu de pausa (a linha
- * que lista posição ↔ tecla). O `openHelp()` que o cabeçalho original citava não morreu — mudou de
- * repositório com o cartucho (#111) e continua a ler daqui.
+ * ⚠️ DECLARED DEBT: the words of ONE game inside an engine module. Nothing in `app/js` reads it — the engine's help
+ * panel (`ui/help-panel`) and this remap panel ask the game for its words through `gameActions()`, because the engine
+ * knows a position exists and only the game knows what it is called (ADR-0086). It stays published only for a consumer
+ * that has not migrated; removing it is a change to published surface.
  *
- * ⚠️ E ELA CONTINUA A SER A CAUSA DA #125, o que é diferente de estar morta. O defeito era o `aria-label` da
- * tela de remapeamento ser montado a partir dela: oito posições contra as catorze do vocabulário, e as
- * palavras de UM jogo dentro do motor. Esse uso saiu. O que resta é um consumidor para quem a tabela está
- * certa — porque ele É o jogo de plataforma.
- *
- * ⚠️ REMOVÊ-LA NÃO É LIMPEZA, É MIGRAÇÃO. O cartucho já tem `acoesDoJogo()` (`main.ts:122`), derivado do
- * preset dele; a tela de ajuda passar a usá-lo é edição de lá, e só depois disso é que isto pode sair daqui.
- * Enquanto não sair, quem escrever código NOVO na engine pede a palavra ao jogo por `ctx.acoesDoJogo()` — a
- * engine sabe que a posição existe, só o jogo sabe como ela se chama (ADR-0086).
- *
- * Guarda CHAVES e não texto porque uma `const` de módulo é avaliada uma vez no import, e o `dict` do
- * `core/i18n` é um `let` que o `setLocale` reatribui — texto capturado aqui congelaria o idioma no boot.
+ * It holds KEYS and not text because a module `const` is evaluated once, on import, and `core/i18n`'s dictionary is
+ * reassigned by `setLocale` — text captured here would freeze the language at boot.
  */
 export const ACT_LABEL = {
     left: 'act.left', right: 'act.right', up: 'act.up', down: 'act.down',
     action1: 'act.run', action2: 'act.jump', action4: 'act.swap', action3: 'act.especial',
 };
+/** The id of a position's button. It comes from the action's ABSTRACT name, unique by construction (`core/actions`). */
+export const ctrlControlId = (action) => `ctrl-act-${action}`;
 /**
- * ⚠️ A TABELA ACIMA E DÍVIDA DECLARADA, e o cabeçalho dela ficou desatualizado no dia em que o corte
- * aconteceu: ela ainda diz quais são as palavras DESTE jogo — `act.run`, `act.jump` — dentro de um módulo de
- * engine. Continua exportada porque `openHelp()` (a tela de ajuda do menu de pausa) ainda a lê, e mover as
- * duas coisas no mesmo commit misturaria dois assuntos.
- *
- * O que MUDOU é quem manda: a lista de linhas e as palavras vêm agora de `ctx.acoesDoJogo()`, e esta tabela é
- * só o que sobra para o consumidor que ainda não migrou. Quando `openHelp` perguntar ao jogo, ela sai.
- */
-/** Physical key code -> short readable label. Only 'Space' has a word to translate; the rest are glyphs and
- *  bare letters, identical in every language (that is why this is a chain of replaces and not a table). */
-export function keyName(code) {
-    return String(code)
-        .replace('Arrow', '↔')
-        .replace('Key', '')
-        .replace('Space', t('key.space'))
-        .replace('ShiftLeft', 'Shift')
-        .replace('ShiftRight', 'Shift');
-}
-/**
- * Which OTHER player already owns `code`, among `schemes` (one entry per player, same order as player index) —
- * or -1 if free. `mapRef` (the scheme currently being edited) is excluded by reference, mirroring the original
- * `keyUsedByOther(code, mapRef)` closing over `kbFor`/numPlayers in game.js. Built over a Map (code -> owner
- * index) so a scheme with many bound keys doesn't cost a full re-scan per lookup.
- */
-export function keyUsedByOther(code, mapRef, schemes) {
-    const owners = new Map();
-    schemes.forEach((m, i) => {
-        if (m === mapRef)
-            return;
-        for (const a of ACTIONS)
-            for (const c of m[a] || [])
-                if (!owners.has(c))
-                    owners.set(c, i);
-    });
-    return owners.get(code) ?? -1;
-}
-/**
- * Qual OUTRA ação DO MESMO esquema já tem `code` — ou `null` se nenhuma.
- *
- * ⚠️ O IRMÃO QUE FALTAVA AO `keyUsedByOther`, E A FALTA ERA INVISÍVEL NUM JOGO DE UM JOGADOR (#126). Aquele
- * exclui o esquema em edição **por referência**; com um jogador só, `schemesFor()` devolve exatamente esse
- * esquema, então a guarda varre uma lista vazia e **nunca pode disparar**. A criança que põe `W` numa ação
- * nova continua com `W` na antiga, e passa o jogo inteiro com as duas a disparar juntas.
- *
- * ⚠️ E O DEFEITO É O PIOR FEITIO POSSÍVEL, escrito no cabeçalho do `input/default-bindings` desde sempre:
- * «as duas ações disparam juntas, e a criança vê uma ação dupla intermitente que ninguém consegue reproduzir
- * de propósito». Numa tela que ela abriu **porque** não conseguia usar os controles padrão.
+ * THE BUTTON'S FACE: the current keys, one `<kbd>` each.
  *
- * ⚠️ A guarda entre JOGADORES não estava partida — estava inalcançável. Medido na auditoria: com dois
- * assentos ela funciona e recusa certo. O que faltava era a verificação dentro do mesmo esquema.
+ * ⚠️ With no key the button would have an empty face — a 44 px target with nothing to say —, so the change word comes
+ * back, which is where it still means something: there is no key to show, there is one to set.
  *
- * Devolve a AÇÃO e não um booleano, porque o anúncio tem de dizer qual — «essa tecla já está em uso» manda a
- * criança procurar o que a função já sabe.
+ * 📌 Through the DOM API and not a string: `keyName` returns a code's READABLE name, which may be translated tomorrow —
+ * translated text interpolated into markup is the door issue #106 closed.
  */
-export function acaoQueJaTem(code, mapRef, exceto) {
-    for (const a of ACTIONS) {
-        if (a === exceto)
-            continue;
-        if ((mapRef[a] || []).includes(code))
-            return a;
+export function drawKeys(t, button, codes) {
+    button.textContent = '';
+    if (!codes.length) {
+        button.textContent = t('ctrl.change');
+        return;
+    }
+    for (const code of codes) {
+        const key = button.ownerDocument.createElement('kbd');
+        key.textContent = keyName(t, code);
+        button.appendChild(key);
     }
-    return null;
 }
 export function initSettingsControls(ctx) {
+    const { t } = ctx;
     let kb = ctx.kb;
     let capture = null;
     let lastPlayer = 0;
@@ -119,25 +54,69 @@ export function initSettingsControls(ctx) {
         return Array.from({ length: n }, (_, i) => ctx.kbFor(i));
     }
     /**
-     * COMO ESTE JOGO CHAMA esta posição, ou `null` se ele não a nomeia. Um sítio só, porque três pontos
-     * precisavam dela e cada um a ia buscar por sua conta — e um deles ia buscá-la à tabela errada (#125).
+     * HOW THIS GAME CALLS this position, or `null` if it does not name it. One place, because several points need it and
+     * each fetching it on its own is how one of them reads the wrong table (#125).
      *
-     * 🔴 O RECUO ERA O ID ABSTRATO (`?? a`), DEFENDIDO AQUI COM «`action3` é feio, mas é verdade». Era um
-     * defeito, e o ADR-0074 chama-lhe isso em tantas palavras: «o nome que a CRIANÇA lê e ouve — na tela de
-     * remapeamento, na bolha de toque, no anúncio — é sempre a palavra do jogo, nunca `action1`. Um nome
-     * abstracto que chega a uma pessoa é um defeito.»
+     * 🔴 NO FALLBACK TO THE ABSTRACT ID. ADR-0074 says so in so many words: the name the CHILD reads and hears is always
+     * the game's word, never `action1`, and an abstract name reaching a person is a defect. With the engine's DEFAULT
+     * scheme binding eight positions and a quiz naming three, a fallback would have the screen reader say a key already
+     * belongs to `action2` — precisely to the child who has no other channel.
      *
-     * ⚠️ E ESTAVA A UM TOQUE DE DISTÂNCIA, com o esquema PADRÃO desta engine: ele liga OITO posições e um quiz
-     * nomeia três. A criança escolhia «Confirmar», carregava numa tecla que o padrão tinha em `action2`, e o
-     * leitor de tela dizia «Essa tecla já é de action2» — precisamente a ela, que é quem não tem outro canal.
+     * 📌 It is the same answer `core/actions.labellerFrom` gives: `null`, and the caller decides — an absence becomes one
+     * step less, never a mute step.
+     */
+    function gameWordFor(a) {
+        return ctx.gameActions().find((x) => x.action === a)?.label ?? null;
+    }
+    /**
+     * THE LINE THAT SAYS WHOSE CONTROLLER THIS IS — «editing your controller, mode N players». There are no
+     * tabs for the other players: each child edits only their own, and only the mode changes the sentence.
      *
-     * 📌 A TERCEIRA SAÍDA JÁ ESTAVA DECIDIDA UM MÓDULO ABAIXO, e este ficheiro tinha decidido outra:
-     * `core/actions.labellerFrom` devolve `null` «e quem chama decide — uma ausência vira menos um passo, nunca
-     * um passo mudo». Duas respostas à mesma pergunta no mesmo repositório é o defeito que o `DomQuery` já
-     * custou dezasseis vezes; agora são uma.
+     * ⚠️ The sentence is split at the `{modo}` marker BEFORE substitution, so the mode can sit in a `<strong>`
+     * without the dictionary carrying markup (the `i18n-sem-markup` gate forbids that, rightly: a dictionary
+     * string that becomes markup is where a translation turns into code). It left raw Portuguese in #125.
      */
-    function palavraDaAcao(a) {
-        return ctx.acoesDoJogo().find((x) => x.acao === a)?.rotulo ?? null;
+    function drawModeLine(n) {
+        const tabs = ctx.$('#ctrl-players');
+        if (!tabs)
+            return;
+        tabs.hidden = false;
+        // The skeleton by `innerHTML` carries no outside data; the TEXT goes in by `textContent`.
+        tabs.innerHTML = '<span class="opt-hint" style="width:100%;margin:0">'
+            + '<span data-modo="pre"></span><strong data-modo="v"></strong><span data-modo="pos"></span></span>';
+        const [before, after] = t('ctrl.editingYours').split('{modo}');
+        const setText = (sel, txt) => {
+            const part = tabs.querySelector(sel);
+            if (part)
+                part.textContent = txt;
+        };
+        setText('[data-modo="pre"]', before ?? '');
+        setText('[data-modo="v"]', n === 1 ? t('ctrl.mode.one') : t('ctrl.mode.many', { n }));
+        setText('[data-modo="pos"]', after ?? '');
+    }
+    /**
+     * THE «LEFT THE DEFAULT» MARK (ADR-0029), on every row whose keys differ from this seat's factory scheme.
+     * It is missed most in this menu, whose whole reason to exist is changing things: without it a child who
+     * remapped heard the action names and nothing said where they had changed something.
+     *
+     * ⚠️ The default comes from the host (`ctx.defaultSchemeFor`), like `kbFor`: which scheme a player count uses is
+     * theirs, and a second copy here would drift. And never `resetKB` to read it — it is DESTRUCTIVE
+     * (`input/keyboard.resetKB` removes the stored scheme first), so calling it per render would erase the
+     * child's remapping.
+     *
+     * 📌 It compares the LIST OF CODES, not object identity: re-binding the SAME key is not a change, and a child
+     * who tries something and goes back cannot be left with the mark lit for good.
+     */
+    function markWhatLeftTheDefault(list, player) {
+        const factory = ctx.defaultSchemeFor(player);
+        const now = ctx.kbFor(player);
+        const sameKeys = (a, b) => (a ?? []).length === (b ?? []).length && (a ?? []).every((k, i) => k === (b ?? [])[i]);
+        for (const row of list.querySelectorAll('.ctrl-row')) {
+            const act = row.querySelector('button[data-act]')?.dataset.act;
+            if (!act || !isAction(act))
+                continue;
+            markChanged(t, row, !sameKeys(now[act], factory[act]));
+        }
     }
     function render(selPlayer) {
         const el = ctx.$('#ctrl-list');
@@ -146,112 +125,61 @@ export function initSettingsControls(ctx) {
         const n = ctx.getNumPlayers();
         const player = selPlayer >= n ? 0 : selPlayer;
         lastPlayer = player;
-        // E3: sem abas de outros jogadores — você edita só o seu controle; só o hint muda com o modo.
-        //
-        // ⚠️ ESTA FRASE ESTAVA EM PORTUGUÊS CRU DENTRO DO MOTOR (#125), inteira, com o `<strong>` e o plural à
-        // mão. Vai pelo `t()` agora — e o realce sobrevive porque o molde é PARTIDO no marcador `{modo}` antes
-        // da substituição, em vez de o dicionário carregar markup (que o gate `i18n-sem-markup` proíbe, e com
-        // razão: string de dicionário que vira markup é a porta por onde uma tradução passa a ser código).
-        const tabs = ctx.$('#ctrl-players');
-        if (tabs) {
-            tabs.hidden = false;
-            // O esqueleto por `innerHTML` — ele não tem dado nenhum de fora; o TEXTO entra por `textContent`, que
-            // é o mesmo idioma que o `.ctrl-nome` abaixo já usa.
-            tabs.innerHTML = '<span class="opt-hint" style="width:100%;margin:0">'
-                + '<span data-modo="pre"></span><strong data-modo="v"></strong><span data-modo="pos"></span></span>';
-            const [antes, depois] = t('ctrl.editingYours').split('{modo}');
-            const posto = (sel, txt) => {
-                const el2 = tabs.querySelector(sel);
-                if (el2)
-                    el2.textContent = txt;
-            };
-            posto('[data-modo="pre"]', antes ?? '');
-            posto('[data-modo="v"]', n === 1 ? t('ctrl.mode.one') : t('ctrl.mode.many', { n }));
-            posto('[data-modo="pos"]', depois ?? '');
-        }
+        drawModeLine(n);
         const map = ctx.kbFor(player);
-        // ⚠️ O `rotulo` SAIU DO MARKUP (issue #106) e entra logo abaixo por `textContent`. Ele é a PALAVRA do
-        // jogo — vem do preset —, e um jogo vive noutro repositório (ADR-0083): esta árvore não revê esse texto.
-        // `data-act="${a}"` fica, e a diferença é a razão: `a` é o nome ABSTRATO da ação, que a engine enumera em
-        // `core/actions`. É separação que o ADR-0086 fez, e é ela que torna um dos dois seguro e o outro não.
-        el.innerHTML = ctx.acoesDoJogo().map(({ acao: a }) => `<div class="ctrl-row"><span><b class="ctrl-nome"></b>: ${(map[a] || []).map(keyName).map((k) => `<kbd>${k}</kbd>`).join(' ')}</span>` +
-            `<button class="mode-btn" data-act="${a}" type="button">${t('ctrl.change')}</button></div>`).join('');
-        // As palavras do jogo, por API do DOM — que escapa por construção. A ordem casa porque é a mesma lista.
-        //
-        // ⚠️ O `aria-label` DESCEU PARA CÁ, E É A CORREÇÃO DA #125. Ele era montado no template acima a partir do
-        // `ACT_LABEL`, que ficou a ser a tabela do JOGO DE PLATAFORMA quando a #106 mudou o rótulo visível para o
-        // `acoesDoJogo()`. Medido no `game-soccer`: **«Alterar tecla de undefined do Jogador 1» em seis de doze
-        // botões**, enquanto uma criança que vê lia «Conter» na mesma linha. E um `aria-label` SOBREPÕE-SE ao
-        // texto visível, então quem depende do leitor de tela ouvia a palavra errada nos outros seis — que é pior
-        // do que não ter `aria-label` nenhum, e invisível de dentro da engine, porque a plataforma é o único
-        // consumidor para o qual a tabela está certa.
-        //
-        // ⚠️ E DESCEU POR `setAttribute` E NÃO PARA O TEMPLATE, de propósito: o `rotulo` é TEXTO DO JOGO. Metê-lo
-        // num `aria-label="…"` dentro de um template literal seria interpolar texto de fora em markup — o mesmo
-        // motivo pelo qual o `.ctrl-nome` já entrava por `textContent`.
-        {
-            const linhas = el.querySelectorAll('.ctrl-row');
-            const palavras = ctx.acoesDoJogo();
-            for (let i = 0; i < linhas.length && i < palavras.length; i++) {
-                const nome = linhas[i].querySelector('.ctrl-nome');
-                if (nome)
-                    nome.textContent = palavras[i].rotulo;
-                const botao = linhas[i].querySelector('button[data-act]');
-                if (botao)
-                    botao.setAttribute('aria-label', t('ctrl.changeKeyAria', { acao: palavras[i].rotulo, n: player + 1 }));
-            }
-        }
-        /**
-         * A MARCA DE «SAIU DO PADRÃO» (ADR-0029), e este era o ÚLTIMO menu sem ela.
-         *
-         * ⚠️ E É O MENU ONDE ELA MAIS FALTAVA, porque é o único cuja razão de existir é mexer: uma criança que
-         * remapeou as teclas percorria a lista, ouvia os nomes das acções, e nada lhe dizia onde ela própria tinha
-         * alterado. Os três canais do ADR-0029 — cor, forma (anéis) e NOME — passam a valer aqui.
+        /*
+         * 🎯 THE ROWS COME FROM THE KIT (ADR-0129), and the button's face is the current key — the Dev, asked whether the
+         * change word was worth keeping: «Não vale, vamos de B».
          *
-         * ⚠️ O PADRÃO VEM DO CONSUMIDOR (`ctx.kbPadraoFor`) e não de uma tabela lida aqui, pela mesma razão que o
-         * `kbFor` é injectado: o mapeamento «quantos jogadores → que balde» (`p2`/`p3`/`p4`) é dele, e uma segunda
-         * cópia dessa regra divergiria da primeira.
+         * 🔴 AND THE REASON IS NOT TASTE, IT IS A COLLISION: `fillExplain` acts on any row with a short `<strong>` label by
+         * keeping only that label in the `<span>`, so keys placed inside the label's `<span>` would be wiped and the key text
+         * sent to the footer as if it were an explanation. The keys go INSIDE the control, the same answer `mountSteps`
+         * gives to a label plus a live value.
          *
-         * 🎯 E NÃO SE USA O `resetKB` PARA LER O PADRÃO, embora ele devolva exactamente a configuração de fábrica:
-         * ele é DESTRUTIVO — `input/keyboard.resetKB` faz `store.remove(CKEY)` antes de devolver a cópia. Chamá-lo
-         * a cada render apagaria o remapeamento da criança, e o estrago só apareceria no arranque seguinte.
-         *
-         * 📌 COMPARA-SE A LISTA DE CÓDIGOS, não a identidade do objecto: reatribuir a MESMA tecla não é uma
-         * mudança, e uma criança que experimenta e volta atrás não pode ficar com a marca acesa para sempre.
+         * ⚠️ The game's word goes in through `textContent` (`controlRow` writes `label` that way) and the accessible name by
+         * `setAttribute` (`ariaLabel`), the two fixes issues #106 and #125 paid for: `label` is GAME TEXT this tree does not
+         * review, and a wrong `aria-label` OVERRIDES the visible text.
          */
-        {
-            const padrao = ctx.kbPadraoFor(player);
-            const atual = ctx.kbFor(player);
-            const mesmas = (a, b) => (a ?? []).length === (b ?? []).length && (a ?? []).every((k, i) => k === (b ?? [])[i]);
-            for (const linha of el.querySelectorAll('.ctrl-row')) {
-                const act = linha.querySelector('button[data-act]')?.dataset.act;
-                if (!act || !isAction(act))
-                    continue;
-                markChanged(linha, !mesmas(atual[act], padrao[act]));
-            }
+        const panelCtx = { find: (sel) => ctx.$(sel), create: (tag) => el.ownerDocument.createElement(tag) };
+        el.textContent = '';
+        for (const { action: a, label: label } of ctx.gameActions()) {
+            const { row: row, control: control } = controlRow(panelCtx, {
+                id: ctrlControlId(a),
+                label: label,
+                shape: 'button',
+                ariaLabel: t('ctrl.changeKeyAria', { acao: label, n: player + 1 }),
+            });
+            // `data-act` stays, and the difference from `label` is the reason: `a` is the position's ABSTRACT name, which the
+            // engine enumerates in `core/actions`, and `label` is the GAME's word (ADR-0086).
+            control.dataset.act = a;
+            drawKeys(t, control, map[a] ?? []);
+            el.appendChild(row);
         }
+        markWhatLeftTheDefault(el, player);
         el.querySelectorAll('button[data-act]').forEach((b) => {
             b.addEventListener('click', () => {
-                // ⚠️ `isAction` E NÃO SÓ `if (!act)`: o valor vem de um atributo do DOM, e desde a #118 o esquema só
-                // aceita as quatorze posições. Uma captura iniciada sobre uma posição inventada gravaria uma tecla
-                // numa chave que transporte nenhum lê — a criança carregaria a tecla nova e nada aconteceria.
+                // ⚠️ `isAction` AND NOT JUST `if (!act)`: the value comes from a DOM attribute, and the scheme accepts only the
+                // fourteen positions (#118). A capture started on an invented position would store a key under a name no
+                // transport reads — the child would press the new key and nothing would happen.
                 const act = b.dataset.act;
                 if (!act || !isAction(act))
                     return;
-                // ⚠️ SEM PALAVRA, NÃO SE PERGUNTA — a regra do `labellerFrom`, aplicada onde ela é visível: «se o jogo
-                // não a usa, não há o que mapear; uma ausência vira menos um passo, nunca um passo mudo». As linhas
-                // vêm todas de `acoesDoJogo()`, logo isto não acontece hoje — e é essa garantia que fica escrita em
-                // vez de assumida, porque quem a partir amanhã acorda um anúncio sem sujeito.
-                const palavra = palavraDaAcao(act);
-                if (!palavra)
+                // ⚠️ NO WORD, NO QUESTION — `labellerFrom`'s rule, applied where it is visible: if the game does not use it,
+                // there is nothing to map. The rows all come from `gameActions()`, so this does not happen today — and that
+                // guarantee is written rather than assumed, because whoever breaks it tomorrow wakes an announcement with no
+                // subject.
+                const word = gameWordFor(act);
+                if (!word)
                     return;
-                capture = { action: act, mapRef: map, player };
-                b.textContent = t('ctrl.pressing'); // estava cravado em português dentro do motor (#125)
-                ctx.srAlert(t('sr.ctrl.pressNewKey', { acao: palavra, n: player + 1 }));
+                capture = { action: act, mapRef: map };
+                b.textContent = t('ctrl.pressing'); // from the dictionary, never raw text inside the engine (#125)
+                ctx.srAlert(t('sr.ctrl.pressNewKey', { acao: word, n: player + 1 }));
             });
         });
-        // A prosa volta para o rodapé depois de as linhas serem reconstruídas (CLAUDE.md §4, #109).
-        ctx.fillExplain?.(ctx.$('#options .overlay__card'));
+        // The prose goes back to the footer after the rows are rebuilt (CLAUDE.md §4, #109).
+        // ⚠️ ON THE CARD THAT HOLDS THE LIST, not a fixed `#options`: the engine mounts this panel with another id (`#ctrl`,
+        // ADR-0151), and the footer of a panel that is not open is not this child's.
+        ctx.fillExplain?.(el.closest('.overlay__card'));
     }
     function isCapturing() {
         return capture !== null;
@@ -272,23 +200,23 @@ export function initSettingsControls(ctx) {
         if (other >= 0) {
             ctx.srAlert(t('sr.ctrl.keyTaken', { n: other + 1 }));
             e.preventDefault();
-            return true; // não associa: segue capturando
+            return true; // does not bind: keeps capturing
         }
-        // A MESMA guarda, dentro do próprio esquema (#126). Recusa em vez de MOVER, e a escolha tem motivo:
-        // mover deixaria a ação antiga com lista vazia — que o `bindingProblems` classifica como problema, e que
-        // a criança descobriria no meio do jogo, sem anúncio, com uma ação que deixou de existir. Recusar custa
-        // dois passos (soltar a antiga, prender a nova) e não perde nada pelo caminho.
-        const aqui = acaoQueJaTem(e.code, capture.mapRef, capture.action);
-        if (aqui) {
-            // ⚠️ `aqui` VEM DO ESQUEMA, e o esquema liga posições que o jogo pode não nomear — é por aqui que o id
-            // abstracto chegava a uma criança. Sem palavra, a frase diz a verdade que INTERESSA («a tecla está
-            // ocupada aqui») em vez do nome interno: calar seria o defeito gémeo, e dizer `action2` era o defeito.
-            const palavra = palavraDaAcao(aqui);
-            ctx.srAlert(palavra
-                ? t('sr.ctrl.keyTakenHere', { acao: palavra })
+        // THE SAME guard, inside the scheme itself (#126). It refuses instead of MOVING, and the choice has a reason: moving
+        // would leave the old action with an empty list — which `bindingProblems` classifies as a problem, and which the
+        // child would discover mid-game, with no announcement, as an action that stopped existing. Refusing costs two steps
+        // (free the old one, bind the new one) and loses nothing on the way.
+        const here = actionAlreadyBound(e.code, capture.mapRef, capture.action);
+        if (here) {
+            // ⚠️ `here` COMES FROM THE SCHEME, and the scheme binds positions the game may not name. With no word, the sentence
+            // says the truth that MATTERS (the key is taken here) instead of the internal name: silence would be the twin
+            // defect, and saying `action2` would be the defect.
+            const word = gameWordFor(here);
+            ctx.srAlert(word
+                ? t('sr.ctrl.keyTakenHere', { acao: word })
                 : t('sr.ctrl.keyTakenHereUnnamed'));
             e.preventDefault();
-            return true; // não associa: segue capturando
+            return true; // does not bind: keeps capturing
         }
         capture.mapRef[capture.action] = [e.code];
         ctx.store.saveKB(kb);

package/dist-pkg/ui/settings-empathy.d.ts

@@ -1,20 +1,23 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { type VizMode } from '../render/viz-modes.js';
+import type { Audio } from '../platform/audio.js';
+import type { Translate } from '../core/i18n.js';
 /**
- * A fatia do catálogo que ESTE painel mostra: só o que SIMULA uma deficiência.
+ * The slice of the catalogue THIS panel shows: only what SIMULATES a disability.
  *
- * Era `VIZ_MODES.filter(m => isSimKind(m.kind))`, e `kind` não distingue simular de corrigir — então as três
- * "Correção de daltonismo" vinham junto, num menu chamado "sentir como é ter uma deficiência". A criança
- * daltônica precisava entrar ali para achar a correção da própria condição, ao lado do botão que simula a
- * condição dela para quem não a tem. Dois públicos opostos na mesma lista.
+ * The catalogue's `kind` does not tell simulating from correcting, so a filter by `kind` brings the colour-blindness
+ * corrections into a menu about feeling what a disability is like — a colour-blind child would have to enter it to find
+ * the correction for their own condition, beside the button that simulates it for someone who does not have it. Two
+ * opposite audiences in one list.
  *
- * O Dev decidiu (#60): as correções vão para a Acessibilidade visual, e a lista passa a se recortar pelo
- * campo `sim` do catálogo, que responde a pergunta certa. `isSimKind` foi apagado — havia TRÊS cópias dele
- * (aqui, no main.js e uma derivada morta), todas respondendo pelo `kind`, todas errando junto.
+ * The Dev decided (#60): the corrections live in visual accessibility, and this list is cut by `simulatesDisability`,
+ * which answers the right question.
  */
 export declare const EMPATHY_VIZ_MODES: VizMode[];
 /** On/off label shared by every toggle button in this panel (hearing, one-button, wheelchair). */
 export interface EmpathySettingsCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
     /** ui/dom.ts querySelector shortcut. */
     $<T extends Element = Element>(sel: string): T | null;
     /** core/a11y-sr.ts screen-reader announcer. */
@@ -23,46 +26,52 @@ export interface EmpathySettingsCtx {
     store: {
         getBool(key: string, fallback?: boolean): boolean;
     };
-    /** Renders one viz-mode radio list (+ per-player tabs); shared with settings-visual, so it stays in game.js. */
+    /** Renders one viz-mode radio list (+ per-player tabs); shared with settings-visual. */
     renderVizGroup(listSel: string, tabsSel: string, modes: VizMode[]): void;
-    /** Reflects #opt-onebtn/#opt-wheelchair; game.js also calls it from its setOneButton/setWheelchair bodies. */
-    reflectMotorEmpathy(): void;
+    /** Reflects #opt-onebtn/#opt-wheelchair; the host also calls it from its setOneButton/setWheelchair bodies. */
+    reflectMobilityEmpathy(): void;
     /** Reflects the #opt-visual/#opt-empathy summary buttons; shared across every viz-mode change in the game. */
     reflectVizButtons(): void;
-    /** Brings an overlay to front + fills its footer explanations; shared by every Sensibilidade panel. */
+    /** Brings an overlay to front + fills its footer explanations; shared by every settings panel. */
     frontOverlay(el: HTMLElement | null): void;
     /**
-     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA render.
+     * Moves the rows' prose to the footer (`ui/settings-panel` → `fillExplain`). Called on EVERY render.
      *
-     * ⚠️ E AQUI A RECONSTRUÇÃO NÃO SE VÊ NO FICHEIRO, que foi o que atrasou este conserto. Este painel não tem
-     * um `innerHTML` sequer: quem reconstrói a lista é o `renderVizGroup` injetado, cuja implementação
-     * (`render/viz-setters`) faz `el.innerHTML = vizGroupHtml(…)` e devolve `.ctrl-row`s NOVAS, com o
-     * `.opt-hint` outra vez lá dentro e sem o `data-explain-done` que torna o `fillExplain` idempotente.
+     * ⚠️ AND HERE THE REBUILD IS NOT VISIBLE IN THE FILE. This panel has no `innerHTML` at all: the list is rebuilt by
+     * the injected `renderVizGroup`, whose implementation (`render/viz-setters`) sets `el.innerHTML` and returns NEW
+     * `.ctrl-row`s, with the `.opt-hint` back inside and without the `data-explain-done` that makes `fillExplain`
+     * idempotent.
      *
-     * Isto acontece a cada clique numa simulação e a cada uso do botão de perda auditiva — que é o pior caso
-     * possível, porque a criança que acabou de ligar "Simular cegueira total" está com a tela preta e depende
-     * do rodapé `aria-live` para saber onde está.
+     * That happens on every click on a simulation and every use of the hearing-loss button — the worst possible case,
+     * because the child who just switched on the total-blindness simulation has a black screen and depends on the
+     * `aria-live` footer to know where they are.
      *
-     * Opcional (`?.`) como nos irmãos: um consumidor que não injete continua a desenhar o painel.
+     * Optional (`?.`) as in the siblings: a consumer that does not inject it still draws the panel.
      */
     fillExplain?: (card: HTMLElement | null) => void;
-    /** Devolve o foco a quem abriu o diálogo (ui/settings-panel `restoreFocus`). Injetado, e não um `#opt-*`
-     *  fixo: o id que este módulo focava não existe no documento, então fechar deixava o foco no `<body>`. */
+    /** Returns focus to whoever opened the dialog (ui/settings-panel `restoreFocus`). Injected, not a fixed `#opt-*`:
+     *  that id does not exist in the document, so closing would leave focus on `<body>`. */
     restoreFocus?: (id: string) => boolean;
-    /** Persists + applies the audio graph change (and announces); body stays in game.js. */
+    /**
+     * THE ROOT'S SOUND, narrowed to the hearing-loss simulation (ADR-0232 D4): `hearingLoss` read live for the button and the
+     * mark, and `setHearingLossGraph` to restore the stored simulation at boot. REQUIRED: the graph lives in the root's `Audio`,
+     * and there is no page-wide one to fall back on. Pass the `Audio` itself — a copied `hearingLoss` would freeze the button.
+     */
+    hearing: Pick<Audio, 'hearingLoss' | 'setHearingLossGraph'>;
+    /** Persists + applies the audio graph change (and announces); the body is the host's. */
     setHearingLoss(on: boolean): void;
-    /** Persists + applies one-button-only play (and announces); body stays in game.js. */
+    /** Persists + applies one-button-only play (and announces); the body is the host's. */
     setOneButton(on: boolean): void;
-    /** Persists + rebuilds world geometry for wheelchair mode (and announces); body stays in game.js. */
+    /** Persists + applies wheelchair mode (and announces); the body is the host's. */
     setWheelchair(on: boolean): void;
-    /** Live reads of game.js's oneButton/wheelchair booleans (not yet migrated to core/state.ts). */
+    /** Live reads of the host's oneButton/wheelchair booleans. */
     getOneButton(): boolean;
     getWheelchair(): boolean;
-    /** Jogadores vivos (core/state `players`), só para saber QUAL modo visual cada um está usando agora. */
+    /** Live players (core/state `players`), only to know WHICH visual mode each one is using now. */
     getPlayers(): readonly {
         viz: string;
     }[];
-    /** Mesmo setPlayerViz do painel visual e do atalho de contraste; usado aqui só pelo "restaurar padrões". */
+    /** The same setPlayerViz as the visual panel and the contrast shortcut; used here only by the reset. */
     setPlayerViz(i: number, mode: string): void;
 }
 export interface EmpathySettingsApi {
@@ -73,5 +82,5 @@ export interface EmpathySettingsApi {
     /** Closes the #empathy overlay and returns focus to #opt-empathy. */
     close(): void;
 }
-/** Wires the empathy panel's DOM (buttons + boot restore) and returns render/open/close for game.js to call. */
+/** Wires the empathy panel's DOM (buttons + boot restore) and returns render/open/close for the host to call. */
 export declare function initSettingsEmpathy(ctx: EmpathySettingsCtx): EmpathySettingsApi;