@the-inclusionist/engine 7.0.0 → 8.0.0-rc.1

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

@@ -121,6 +121,10 @@ export function sinkSelectValue(p) {
 // DOM-facing (thin) — requires `document`/injected ctx
 // ---------------------------------------------------------------------------------------------
 export function initSettingsAudio(ctx) {
+    // ⚠️ PADRÃO DA ENGINE (ADR-0106 §4): quem injecta manda; quem não injecta deixa de ficar sem modo cego.
+    // O `setModoCegoValue` faz as três coisas que o `core/state` diz que um setter faz — grava, persiste, avisa
+    // — e nada mais: os efeitos (refazer os extras do nível) são reação, e quem reage assina o evento.
+    const setModoCego = ctx.setModoCego ?? state.setModoCegoValue;
     let audioDevices = [];
     function reflectMaster() {
         const b = ctx.$('#audio-master');
@@ -179,6 +183,8 @@ export function initSettingsAudio(ctx) {
             return;
         el.innerHTML = catsListHTML(keys, ctx.audioCats, state);
         wireCatControls(el);
+        // A prosa volta para o rodapé depois de as linhas serem reconstruídas (CLAUDE.md §4, #109).
+        ctx.fillExplain?.(ctx.$('#audio .overlay__card'));
     }
     function renderNavSound() {
         renderCategoryList('#navsound-list', NAV_CATS);
@@ -417,9 +423,28 @@ export function initSettingsAudio(ctx) {
                 NAV_CATS.forEach((k) => { state[k].vol = v; state[k].on = true; ctx.setCatGain(k); });
             renderNavSound();
         });
+    /*
+     * ⚠️ ESTE BOTÃO ERA O ÚNICO DESTE PAINEL QUE NÃO ANUNCIAVA. Medido em 2026-09-08: os cinco irmãos daqui
+     * anunciam (som, TTS, divisor da bengala, índice de menu, saída de áudio) e o modo cego não — ele parecia
+     * anunciar porque UM cartucho o fazia a partir do próprio `setModoCego`, e o painel herdava o efeito.
+     *
+     * ⚠️ E ISSO PASSOU A EXPOR SILÊNCIO no mesmo dia: desde que o campo ganhou padrão da engine
+     * (`setModoCegoValue`, que grava/persiste/avisa e NÃO fala), um jogo que não injecta o seu próprio setter
+     * ficava com este botão mudo. Um alternador que muda estado sem o dizer é invisível para quem usa leitor de
+     * tela — a mesma família de defeito que o `reflectTTS` e o `reflectModoCego` já custaram aqui.
+     *
+     * O anúncio pertence a QUEM É ACCIONADO, não ao setter: `core/state` diz que o setter faz três coisas e só
+     * três. ⚠️ Consequência de lockstep, escrita para não se descobrir depois: quando o `game-platformer` subir
+     * de versão, tem de TIRAR o `srSay` do `setModoCego` dele, senão a criança ouve o estado duas vezes.
+     */
     const mcBtn = ctx.$('#opt-modocego');
-    if (mcBtn)
-        mcBtn.addEventListener('click', () => { ctx.setModoCego(!ctx.getModoCego()); reflectModoCego(); });
+    if (mcBtn) {
+        mcBtn.addEventListener('click', () => {
+            setModoCego(!ctx.getModoCego());
+            reflectModoCego();
+            ctx.srSay(t(ctx.getModoCego() ? 'sr.blind.on' : 'sr.blind.off'));
+        });
+    }
     const caneDivSel = ctx.$('#cane-div');
     if (caneDivSel) {
         caneDivSel.value = String(ctx.getCaneBlockDiv());
@@ -516,7 +541,7 @@ export function initSettingsAudio(ctx) {
     const resetBtn = ctx.$('#audio-reset');
     if (resetBtn)
         resetBtn.addEventListener('click', () => {
-            ctx.setModoCego(DEFAULTS.modoCego);
+            setModoCego(DEFAULTS.modoCego);
             ctx.setCaneBlockDiv(DEFAULTS.caneBlockDiv);
             const state = ctx.getAudioCat();
             if (state)
@@ -554,5 +579,20 @@ export function initSettingsAudio(ctx) {
     if (audioDetectBtn)
         audioDetectBtn.addEventListener('click', () => { void detectAudioDevices(); });
     reflectMaster(); // estado inicial do botão/slider mestre, antes de qualquer abertura do painel
+    /*
+     * ⚠️ O PAINEL ASSINA O EVENTO, e isto não é uma ideia nova: é a decisão que o `core/state` já tinha
+     * escrito ao lado do `setModoCegoValue` — «o setter faz três coisas e só três: grava, persiste, avisa. Os
+     * efeitos … são reação, e quem reage assina o evento».
+     *
+     * Sem esta assinatura, um jogo que NÃO injecta o seu próprio `setModoCego` liga o modo cego pelo ícone da
+     * barra e o botão `#opt-modocego` deste painel continua a dizer «Desligado», com `aria-pressed=false` — o
+     * controlo a mentir o estado para o leitor de tela. É o gémeo exacto do defeito do `reflectTTS` que já está
+     * registado no `ui/pause-icons`, e não vale a pena descobri-lo uma terceira vez.
+     *
+     * ⚠️ É seguro para quem JÁ reflecte a partir do seu próprio setter: reflectir é idempotente — relê o estado
+     * e reescreve o botão. Um anúncio duplicado seria outra história, e por isso a assinatura NÃO anuncia: o
+     * ícone da barra já diz `sr.icon.blindOn`/`Off` por si.
+     */
+    state.on('modoCego', () => { reflectModoCego(); });
     return { renderAudio, reflectModoCego, reflectTts };
 }

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { DomQuery } from '../core/dom-query.js';
 import type { KeyScheme } from '../core/entity.js';
+import { type Action } from '../core/actions.js';
 import type { KBDefaults } from '../input/keyboard.js';
 import type { KeydownEventLike } from '../input/keydown.js';
 /** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
@@ -29,7 +30,7 @@ export interface SettingsControlsCtx {
      * remapear um botão que não faz nada.
      */
     acoesDoJogo: () => readonly {
-        readonly acao: string;
+        readonly acao: Action;
         readonly rotulo: string;
     }[];
     /** Screen-reader "polite" announcement (core/a11y-sr's srSay), injected. */
@@ -45,12 +46,37 @@ export interface SettingsControlsCtx {
     /** Shared helper (game.js): the scheme for a given player index, given `kb`/numPlayers. Not owned by this panel —
      *  other systems (gamepad binding, HUD) call the same game.js function. */
     kbFor: (playerIndex: number) => KeyScheme;
+    /**
+     * O esquema DE FÁBRICA deste assento (ADR-0029) — o que ele teria se ninguém tivesse remapeado nada.
+     *
+     * ⚠️ INJECTADO PELA MESMA RAZÃO QUE O `kbFor` LOGO ACIMA: o mapeamento «quantos jogadores → que balde»
+     * (`solo`/`p2`/`p3`/`p4`) é do consumidor, e uma segunda cópia dessa regra dentro da engine divergiria da
+     * primeira no dia em que um dos dois mudasse.
+     *
+     * 🎯 E NÃO SE OBTÉM CHAMANDO `store.resetKB()`, embora ele devolva exactamente a configuração de fábrica:
+     * o `input/keyboard.resetKB` faz `store.remove(CKEY)` ANTES de devolver a cópia. Usá-lo como leitor
+     * apagaria o remapeamento da criança a cada render, e o estrago só apareceria no arranque seguinte.
+     */
+    kbPadraoFor: (playerIndex: number) => KeyScheme;
     /** Shared: current player count (core/state.ts's numPlayers, read live via game.js). */
     getNumPlayers: () => number;
     /** Shared: propagates `kb` -> the live control aliases (game.js's applyControls). Called after remap/reset. */
     applyControls: () => void;
     /** Shared: propagates `kb` -> each player's `p.ctrl` (game.js's assignControls). Called after remap/reset. */
     assignControls: () => void;
+    /**
+     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA render.
+     *
+     * ⚠️ NÃO É OPCIONAL POR ELEGÂNCIA: `fillExplain` roda uma vez quando o overlay é frontalizado e move o
+     * `.opt-hint` de dentro de cada linha para o rodapé. Este painel RECONSTRÓI as linhas, e as linhas novas
+     * voltam com a prosa lá dentro — então a explicação aparece duas vezes, no rodapé e sob o rótulo, a
+     * partir do primeiro clique. O `CLAUDE.md` §4 regista exatamente isto, e a issue #109 já o consertou
+     * uma vez noutros painéis.
+     *
+     * Opcional na assinatura porque um consumidor pode montar o painel sem a casca (um teste, o segundo
+     * consumidor): sem casca não há rodapé para duplicar.
+     */
+    fillExplain?: (card: HTMLElement | null) => void;
 }
 export interface SettingsControlsApi {
     /** Re-renders #ctrl-list for the given player index and (re)wires its "Alterar" buttons. Idempotent. */
@@ -70,12 +96,27 @@ export interface SettingsControlsApi {
     handleCaptureKeydown: (e: KeydownEventLike) => boolean;
 }
 /**
- * action key -> i18n KEY of the label shown in the panel. Also reused by main.js's openHelp() (pause-menu help
- * screen), which is why it lives here instead of being duplicated in two places.
+ * As oito posições do jogo de plataforma, ligadas às chaves de i18n das palavras DELE.
+ *
+ * ⚠️ 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.
  *
- * Holds keys, not text, for the reason spelled out in input/devices: a module-level const is evaluated once at
- * import, and core/i18n's `dict` is a `let` that setLocale reassigns — text captured here would freeze the
- * language at boot. Resolve with `t(ACT_LABEL[a])` at the point of use.
+ * ⚠️ 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.
  */
 export declare const ACT_LABEL: Record<string, string>;
 /**
@@ -97,4 +138,23 @@ export declare function keyName(code: string): string;
  * index) so a scheme with many bound keys doesn't cost a full re-scan per lookup.
  */
 export declare function keyUsedByOther(code: string, mapRef: KeyScheme, schemes: readonly KeyScheme[]): number;
+/**
+ * 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.
+ *
+ * ⚠️ 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.
+ *
+ * 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.
+ */
+export declare function acaoQueJaTem(code: string, mapRef: KeyScheme, exceto: Action): Action | null;
 export declare function initSettingsControls(ctx: SettingsControlsCtx): SettingsControlsApi;

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

@@ -6,19 +6,41 @@
 // 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 ACT_LABEL/keyName —
-// both are exported here instead of duplicated.
+// 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 { markChanged } from './changed-mark.js';
 // ---------------------------------------------------------------------------------------------
 // Pure logic (no `document`, testable in node)
 // ---------------------------------------------------------------------------------------------
 /**
- * action key -> i18n KEY of the label shown in the panel. Also reused by main.js's openHelp() (pause-menu help
- * screen), which is why it lives here instead of being duplicated in two places.
+ * As oito posições do jogo de plataforma, ligadas às chaves de i18n das palavras DELE.
  *
- * Holds keys, not text, for the reason spelled out in input/devices: a module-level const is evaluated once at
- * import, and core/i18n's `dict` is a `let` that setLocale reassigns — text captured here would freeze the
- * language at boot. Resolve with `t(ACT_LABEL[a])` at the point of use.
+ * ⚠️ 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.
+ *
+ * ⚠️ 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.
  */
 export const ACT_LABEL = {
     left: 'act.left', right: 'act.right', up: 'act.up', down: 'act.down',
@@ -54,13 +76,40 @@ export function keyUsedByOther(code, mapRef, schemes) {
     schemes.forEach((m, i) => {
         if (m === mapRef)
             return;
-        for (const a in m)
+        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.
+ *
+ * ⚠️ 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.
+ *
+ * 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.
+ */
+export function acaoQueJaTem(code, mapRef, exceto) {
+    for (const a of ACTIONS) {
+        if (a === exceto)
+            continue;
+        if ((mapRef[a] || []).includes(code))
+            return a;
+    }
+    return null;
+}
 export function initSettingsControls(ctx) {
     let kb = ctx.kb;
     let capture = null;
@@ -69,6 +118,27 @@ export function initSettingsControls(ctx) {
         const n = ctx.getNumPlayers();
         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).
+     *
+     * 🔴 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.»
+     *
+     * ⚠️ 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.
+     *
+     * 📌 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.
+     */
+    function palavraDaAcao(a) {
+        return ctx.acoesDoJogo().find((x) => x.acao === a)?.rotulo ?? null;
+    }
     function render(selPlayer) {
         const el = ctx.$('#ctrl-list');
         if (!el)
@@ -77,10 +147,27 @@ export function initSettingsControls(ctx) {
         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;
-            tabs.innerHTML = `<span class="opt-hint" style="width:100%;margin:0">Editando o <strong>seu</strong> controle — modo <strong>${n === 1 ? '1 jogador' : n + ' jogadores'}</strong>.</span>`;
+            // 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 ?? '');
         }
         const map = ctx.kbFor(player);
         // ⚠️ O `rotulo` SAIU DO MARKUP (issue #106) e entra logo abaixo por `textContent`. Ele é a PALAVRA do
@@ -88,24 +175,83 @@ export function initSettingsControls(ctx) {
         // `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" aria-label="${t('ctrl.changeKeyAria', { acao: t(ACT_LABEL[a]), n: player + 1 })}">${t('ctrl.change')}</button></div>`).join('');
-        // As palavras do jogo, por `textContent` — que escapa por construção. A ordem casa porque é a mesma lista.
+            `<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 nomes = el.querySelectorAll('.ctrl-nome');
+            const linhas = el.querySelectorAll('.ctrl-row');
             const palavras = ctx.acoesDoJogo();
-            for (let i = 0; i < nomes.length && i < palavras.length; i++)
-                nomes[i].textContent = palavras[i].rotulo;
+            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.
+         *
+         * ⚠️ 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.
+         *
+         * 🎯 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.
+         */
+        {
+            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]));
+            }
         }
         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.
                 const act = b.dataset.act;
-                if (!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)
                     return;
                 capture = { action: act, mapRef: map, player };
-                b.textContent = 'Pressione…';
-                ctx.srAlert(t('sr.ctrl.pressNewKey', { acao: t(ACT_LABEL[act]), n: player + 1 }));
+                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 }));
             });
         });
+        // A prosa volta para o rodapé depois de as linhas serem reconstruídas (CLAUDE.md §4, #109).
+        ctx.fillExplain?.(ctx.$('#options .overlay__card'));
     }
     function isCapturing() {
         return capture !== null;
@@ -128,6 +274,22 @@ export function initSettingsControls(ctx) {
             e.preventDefault();
             return true; // não associa: segue capturando
         }
+        // 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 })
+                : t('sr.ctrl.keyTakenHereUnnamed'));
+            e.preventDefault();
+            return true; // não associa: segue capturando
+        }
         capture.mapRef[capture.action] = [e.code];
         ctx.store.saveKB(kb);
         ctx.applyControls();

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

@@ -31,6 +31,21 @@ export interface EmpathySettingsCtx {
     reflectVizButtons(): void;
     /** Brings an overlay to front + fills its footer explanations; shared by every Sensibilidade panel. */
     frontOverlay(el: HTMLElement | null): void;
+    /**
+     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA 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.
+     *
+     * 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á.
+     *
+     * Opcional (`?.`) como nos irmãos: um consumidor que não injete continua a desenhar o painel.
+     */
+    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>`. */
     restoreFocus?: (id: string) => boolean;

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

@@ -40,6 +40,8 @@ export function initSettingsEmpathy(ctx) {
         }
         ctx.reflectMotorEmpathy();
         refreshMarks();
+        // Depois do `renderVizGroup`, e não antes: é ele quem repõe o `.opt-hint` dentro das linhas.
+        ctx.fillExplain?.(ctx.$('#empathy .overlay__card'));
     }
     /**
      * A marca de "saiu do padrão" (ADR-0029). Neste menu ela quer dizer "esta simulação está LIGADA", e por

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

@@ -1,16 +1,10 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import type { PlayerView } from '../core/entity.js';
-export type MotionSceneKey = 'parallax' | 'decor' | 'items' | 'particles';
-export type MotionCharProp = 'rmWalk' | 'rmBreath' | 'rmFlavor';
-export interface MotionCharDef {
-    readonly prop: MotionCharProp;
-    readonly lbl: string;
-}
-/** As três chaves de Movimento Reduzido por personagem, derivadas de core/entity. Eram um
- *  `Partial<Record<MotionCharProp, boolean>>`, o que dizia a forma certa sem dizer que os campos são DO
- *  JOGADOR — um `Record` aceita qualquer objeto com essas chaves, inclusive um que não seja jogador nenhum. */
-export type MotionPlayer = PlayerView<'rmWalk' | 'rmBreath' | 'rmFlavor'>;
-export type MotionSceneFlags = Record<MotionSceneKey, boolean>;
+import type { MotionSceneKey as ChaveDeCenaLeaf, MotionCharProp as PropDoPersonagemLeaf, MotionCharDef as DefDoPersonagemLeaf, MotionPlayer as JogadorDeMovimentoLeaf, MotionSceneFlags as BandeirasDeCenaLeaf } from './motion-scene.js';
+export type MotionSceneKey = ChaveDeCenaLeaf;
+export type MotionCharProp = PropDoPersonagemLeaf;
+export type MotionCharDef = DefDoPersonagemLeaf;
+export type MotionPlayer = JogadorDeMovimentoLeaf;
+export type MotionSceneFlags = BandeirasDeCenaLeaf;
 export interface SettingsMotionCtx {
     /** Quantos jogadores/telas. Estado de RODADA (ADR-0038): vem da instância que a raiz possui.
      *  Era `numPlayers`, um `let` de `core/state` importado como binding vivo — e um `let` de módulo
@@ -34,15 +28,27 @@ export interface SettingsMotionCtx {
     restoreFocus?: (id: string) => boolean;
     /** Reflete on/off num botão (classe is-on + aria-pressed) — helper genérico usado por vários botões-mestre. */
     toggleBtn: (el: HTMLElement, on: boolean) => void;
-    /** Movimento reduzido de CENA (parallax/decor/items/particles) — objeto VIVO, mutado in-place. Fica em game.js:
-     *  applyCalm() (modo TEA) também o usa, não é exclusivo deste painel. */
-    rm: MotionSceneFlags;
-    /** Persiste `rm` (localStorage 'inclusionist.reducedmotion.v1') — mesmo motivo, fica em game.js. */
-    saveRM: () => void;
+    /** Movimento reduzido de CENA (parallax/decor/items/particles) — objeto VIVO, mutado in-place. */
+    rm?: MotionSceneFlags;
+    /** Persiste `rm` (localStorage 'inclusionist.reducedmotion.v1'). */
+    saveRM?: () => void;
     /** As 4 chaves de cena — a MESMA array que applyCalm() itera. */
-    rmKeys: readonly MotionSceneKey[];
+    rmKeys?: readonly MotionSceneKey[];
     /** Os 3 alvos de movimento reduzido do PERSONAGEM — a MESMA array que applyCalm() itera. */
-    rmChar: readonly MotionCharDef[];
+    rmChar?: readonly MotionCharDef[];
+    /**
+     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA render.
+     *
+     * ⚠️ NÃO É OPCIONAL POR ELEGÂNCIA: `fillExplain` roda uma vez quando o overlay é frontalizado e move o
+     * `.opt-hint` de dentro de cada linha para o rodapé. Este painel RECONSTRÓI as linhas, e as linhas novas
+     * voltam com a prosa lá dentro — então a explicação aparece duas vezes, no rodapé e sob o rótulo, a
+     * partir do primeiro clique. O `CLAUDE.md` §4 regista exatamente isto, e a issue #109 já o consertou
+     * uma vez noutros painéis.
+     *
+     * Opcional na assinatura porque um consumidor pode montar o painel sem a casca (um teste, o segundo
+     * consumidor): sem casca não há rodapé para duplicar.
+     */
+    fillExplain?: (card: HTMLElement | null) => void;
 }
 /**
  * Alvo → CHAVE i18n do rótulo. CHAVES, e não texto, pelo motivo de sempre: uma tabela de `const` com texto