@the-inclusionist/engine 7.0.1 → 8.0.0-rc.2

package/dist-pkg/ui/pause-icons.js

@@ -25,12 +25,24 @@
 //   · `rm`/`saveRM`     — the reduced-motion flags object, co-owned with ui/settings-motion (same reference).
 //   · `PM_BTNS`/`QL_NAME` — owned by ui/activities-menu; injected, never copied.
 import { t } from '../core/i18n.js';
-import { CONTRAST_LEVELS, CONTRAST_LABELS } from './settings-visual.js';
+import { CONTRAST_LEVELS } from './settings-visual.js';
+import { CURTO_DO_TEMA, CURTO_DA_CORRECAO } from './visual-axes-panel.js';
+import { proximoTema, proximaCorrecao, temAltoContraste, PADRAO, } from '../render/viz-axes.js';
 import { anunciarItem } from './item-announcement.js';
 import { rotuloAcessivel } from '../core/rotulo-acessivel.js';
 import { passoNoAnel } from '../core/anel.js'; // da FOLHA, e não de ui/menu-nav: ver a nota lá
 // LIGAÇÃO VIVA (ESM): o índice pode ser desligado no menu, e o valor aqui acompanha sem assinatura.
-import { menuIndexOn } from '../core/state.js';
+import { menuIndexOn, DEFAULTS, setModoCegoValue } from '../core/state.js';
+// ⚠️ IMPORT DIRETO DE `platform/storage`, e não uma peça a mais no `ctx`, e a escolha é sobre quem pode
+// esquecer: `initPauseIcons` é chamado pela raiz de composição de CADA jogo, e um `store` injetado é um
+// campo que um consumidor pode omitir — e omiti-lo faria o nível TEA voltar a não persistir, em silêncio,
+// exactamente no jogo que se esqueceu. É a mesma forma que `ui/fonts` usa, e `ui/` depender de `platform/`
+// não inverte camada nenhuma.
+import * as store from '../platform/storage.js';
+import { definirAlternanciaDeMarcha } from './settings-motor.js';
+import { recusaDaAlternancia } from './latch-refusal.js';
+import { PM_BTNS, PM_OPTIONS_BTNS } from './activities-menu.js';
+import { CHAVES_DE_CENA, ANIMACOES_DO_PERSONAGEM, lerCenaGuardada, guardarCena } from './motion-scene.js';
 /**
  * A LEGENDA de um ícone da barra de acessibilidade — uma função, e não três cópias da mesma expressão.
  *
@@ -69,6 +81,17 @@ const ICON_BY_KEY = new Map(PAUSE_ICONS.map((ic) => [ic.k, ic]));
 export function pauseIcon(k) { return ICON_BY_KEY.get(k); }
 /** TEA cycle: 0 = normal · 1 = calmo (reduces) · 2 = silencioso (switches off). Never touches TTS/blind mode. */
 export const CALM_NAMES = ['calm.off', 'calm.quiet', 'calm.silent'];
+/**
+ * O nível TEA guardado, saneado. Fora de 0..2 devolve o padrão — dado do navegador é dado de fora, e um
+ * nível inventado escolheria `CALM_NAMES[3]`, que é `undefined`, e o anúncio ao leitor de tela sairia vazio.
+ */
+export function saneiaNivelTea(bruto) {
+    return Number.isInteger(bruto) && bruto >= 0 && bruto < CALM_NAMES.length ? bruto : DEFAULTS.calmMode;
+}
+/** Lê o nível TEA do armazenamento. Chamado no `init`, nunca no import. */
+function lerNivelTea() {
+    return saneiaNivelTea(store.getNum(store.KEYS.tea, DEFAULTS.calmMode));
+}
 /** The audio categories `applyCalm` governs. TTS/sonar/guarda/guia stay untouched — a calm player still needs them. */
 export const CALM_AUDIO_CATS = ['ambient', 'music', 'earcons', 'other', 'interact'];
 /** Colour-vision-deficiency cycle, in `player.viz` values. */
@@ -151,9 +174,9 @@ export function computeIconLabel(k, s) {
     if (k === 'altmove')
         return rotulo(s.toggleMove ? 'state.on' : 'state.off');
     if (k === 'contrast')
-        return rotulo(CONTRAST_LABELS[s.viz] || 'contrast.off');
+        return rotulo(CURTO_DO_TEMA[s.visual.tema]);
     if (k === 'cvd')
-        return t('icon.state', { nome: t('icon.cvd.short'), v: t(CVD_LABELS[s.viz] || 'cvd.off') });
+        return t('icon.state', { nome: t('icon.cvd.short'), v: t(CURTO_DA_CORRECAO[s.visual.correcao]) });
     return t(ic.n);
 }
 /** Pure form of reflectIconBtn's branching. A `soon` icon lands on all-false — it never claims to be on. */
@@ -176,17 +199,17 @@ export function computeIconVisual(k, s) {
     }
     else if (k === 'altmove') {
         on = s.toggleMove;
+        dis = !!s.alternanciaExigida;
     }
     else if (k === 'contrast') {
-        on = /^hc-direto/.test(s.viz || '');
+        on = temAltoContraste(s.visual);
     }
     else if (k === 'cvd') {
-        if (s.viz === 'fix-protan')
-            cvd = 'pi-cvd-protan';
-        else if (s.viz === 'fix-deuter')
-            cvd = 'pi-cvd-deuter';
-        else if (s.viz === 'fix-tritan')
-            cvd = 'pi-cvd-tritan';
+        // ⚠️ O FUNDO DE DUAS CORES É O SINAL DE LIGADO deste ícone, e agora ele lê o EIXO da correção — que
+        // continua a dizer o mesmo quando o tema também está ligado, coisa que a chave única não conseguia: com
+        // `hc-direto-7` no campo, a correção da criança desaparecia do ícone que existe para a mostrar.
+        if (s.visual.correcao !== 'tricro')
+            cvd = 'pi-cvd-' + s.visual.correcao;
     }
     return { on, dis, calm, cvd, active: on || calm || !!cvd };
 }
@@ -201,9 +224,60 @@ export function iconBtnMarkup(ic) {
     return '<button class="pi-btn' + (ic.soon ? ' pi-soon' : '') + '" type="button" data-pi="' + ic.k +
         '" aria-label="' + (ic.soon ? t('icon.soon', { nome: t(ic.n) }) : t(ic.n)) + '">' + ic.e + '</button>';
 }
+export function iconesQueAccionam(escritores) {
+    // ⚠️ POR ÍCONE, e não um booleano para os dois — e foi uma MUTAÇÃO SOBREVIVENTE que o mostrou. Com uma
+    // única bandeira, `&&` e `||` produziam o mesmo resultado nos casos que eu tinha escrito, porque todos
+    // tiravam os DOIS escritores. O `&&` escondia um ícone que FUNCIONA quando só um escritor falta, e o `||`
+    // mostrava um que NÃO funciona. Os dois erram, em direcções opostas, e a pergunta certa nunca foi «este
+    // jogo tem escritores visuais» — é «este ÍCONE tem quem o accione».
+    // 📌 E o `altmove` entra pela MESMA porta, que é o achado: «este jogo segura teclas?» é a mesma pergunta
+    // que «este ícone tem quem o accione», feita a um campo do contrato em vez de a um escritor injectado.
+    // Um terceiro ramo, e não uma regra nova.
+    return PAUSE_ICONS.filter((ic) => (ic.k === 'contrast' ? escritores.tema
+        : ic.k === 'cvd' ? escritores.correcao
+            : ic.k === 'altmove' ? escritores.seguraTeclas
+                : true));
+}
+/**
+ * OS TRÊS ITENS QUE A ENGINE ACCIONA SOZINHA, e que por isso nunca dependem do `getPauseActs` de um jogo.
+ *
+ * 📏 Lidos do despacho, e não decididos aqui: `options`/`pmback` trocam qual lista está no cartão e
+ * `acessibilidade` leva o cursor à barra rápida — os três são tratados neste módulo e voltam antes de a
+ * tabela do jogo ser consultada.
+ */
+export const ITENS_DA_ENGINE = new Set(['options', 'pmback', 'acessibilidade']);
+/**
+ * OS ITENS DO MENU QUE ESTE JOGO CONSEGUE MESMO ACCIONAR (ADR-0106 §5).
+ *
+ * ⚠️ HOJE UM ITEM SEM ACÇÃO É UM BOTÃO MORTO, E EM SILÊNCIO. O despacho faz `const fn = acts[act]; if (fn)
+ * fn();` — quem carrega num item que o jogo não implementou não recebe erro, não recebe anúncio, não recebe
+ * nada. Para quem vê, parece que o clique falhou; para quem navega por leitor de tela, o menu leu-lhe um
+ * item que não existe. É exactamente o que o §5 chama de pior do que a ausência: «uma barra que oferece um
+ * caminho e depois o recusa ensina-lhe que o caminho não é para ela».
+ */
+export function itensQueAccionam(botoes, acts) {
+    return botoes.filter((b) => ITENS_DA_ENGINE.has(b.act) || typeof acts[b.act] === 'function');
+}
+/**
+ * A LISTA RAIZ, com uma regra a mais: `options` é uma PORTA, e uma porta para uma sala vazia também é um
+ * botão morto.
+ *
+ * ⚠️ Esta é a parte que um filtro item-a-item não apanha. Se todos os painéis de ajuste forem filtrados —
+ * um jogo que não monta nenhum —, o item `options` sobrevive (a engine acciona-o) e abre uma lista sem nada.
+ * A criança atravessa uma porta e fica presa num submenu vazio, cuja única saída é o `pmback` que também
+ * sumiu com ele.
+ */
+export function raizQueAcciona(raiz, opcoes, acts) {
+    const opcoesVivas = itensQueAccionam(opcoes, acts).filter((b) => b.act !== 'pmback');
+    const viva = itensQueAccionam(raiz, acts);
+    return opcoesVivas.length > 0 ? viva : viva.filter((b) => b.act !== 'options');
+}
 /** The whole icon bar. Used by the pause screen AND by the splash `#title-icons` (which built the same string
- *  by hand in game.js — that duplication dies with this export). */
-export function iconsMarkup() { return PAUSE_ICONS.map(iconBtnMarkup).join(''); }
+ *  by hand in game.js — that duplication dies with this export).
+ *  O parâmetro é ADITIVO e o padrão é a lista inteira: quem já chamava sem argumentos não muda de resultado. */
+export function iconsMarkup(icones = PAUSE_ICONS) {
+    return icones.map(iconBtnMarkup).join('');
+}
 /** One `.pm-btn`. Dynamic labels (`letra`/`nivel`) are rendered eagerly and carry NO `data-i18n`, so
  *  i18n.applyDom() cannot overwrite them. */
 /**
@@ -268,8 +342,8 @@ export function mostrarSubmenuDaPausa(sp, sub) {
  * A LEGENDA VIAJA JUNTO. Ela é a dica que substitui, para quem não vê, o `title` que só o mouse revela;
  * deixá-la no cartão tornaria a barra do HUD muda.
  */
-export function quickBarMarkup() {
-    return '<div class="pause-icons" role="group" aria-label="' + t('pause.iconBarAria') + '">' + iconsMarkup() +
+export function quickBarMarkup(icones = PAUSE_ICONS) {
+    return '<div class="pause-icons" role="group" aria-label="' + t('pause.iconBarAria') + '">' + iconsMarkup(icones) +
         '</div><p class="pause-icons-cap" aria-live="polite"></p>';
 }
 export function acaoNaBarra(k, temStart) {
@@ -298,11 +372,96 @@ export function screenPauseMarkup(o) {
 // DOM-facing shell
 // ---------------------------------------------------------------------------------------------
 export function initPauseIcons(ctx) {
-    // TEA level. It lives HERE (game.js's `let calmMode` had no other reader) and is deliberately NOT persisted
-    // — verbatim: game.js never wrote it to storage, even though applyCalm() persists `rm` as a side effect.
-    let calmMode = 0;
+    // ⚠️ O NÍVEL TEA PASSOU A PERSISTIR EM 2026-09-07 (issue #61). Este comentário dizia «deliberately NOT
+    // persisted — verbatim: game.js never wrote it to storage», e o **verbatim** é o que o desqualificava como
+    // decisão: foi PRESERVADO na extração do monólito, não escolhido. O ADR-0028 diz que todo menu persiste, e
+    // este é um controlo de menu que vive na barra rápida.
+    //
+    // O custo de não persistir era da criança que mais precisa dele: quem usa o modo SILENCIOSO voltava a
+    // pô-lo a cada sessão — e é para quem o barulho inesperado custa mais. Um ajuste que se esquece não é um
+    // ajuste, é uma tarefa diária.
+    //
+    // ⚠️ LÊ NO INIT, NUNCA NO IMPORT: a regra vale para todo o projeto e aqui tem custo concreto — um teste que
+    // importasse este módulo passaria a depender do `localStorage` do ambiente, e um nível herdado de outro
+    // caso é uma falha que aparece longe da causa.
+    let calmMode = lerNivelTea();
     const P = () => ctx.getPlayers();
+    /*
+     * ⚠️ A ALTERNÂNCIA DE MARCHA PASSOU A TER PADRÃO DA ENGINE (ADR-0106 §4, etapa 1b). Quem injecta continua a
+     * mandar; quem não injecta deixa de ficar sem ela — que era o caso dos cinco jogos sem barra.
+     *
+     * O `store` vem do import directo deste módulo e não do `ctx`, porque é assim que este ficheiro já persiste
+     * o resto: uma chave injectada é um campo que um consumidor pode omitir, e omiti-la faria escrever num nome
+     * torto.
+     */
+    const setToggleMove = ctx.setToggleMove
+        ?? ((i, on) => definirAlternanciaDeMarcha({
+            players: P(), store, srSay: ctx.srSay, getNumPlayers: ctx.getNumPlayers,
+            // ⚠️ ATRAVESSA, e não se resolve aqui: o ícone e o painel têm de escrever a MESMA coisa. Resolver
+            // o aparelho num deles e não no outro é como duas superfícies da mesma engine passam a discordar.
+            transporteEmUso: ctx.transporteEmUso,
+        }, i, on));
+    /*
+     * ⚠️ O MODO CEGO IDEM, e aqui o padrão é literalmente o que o `core/state` já decidiu que um setter faz:
+     * «grava, persiste, avisa» — e nada mais. Os efeitos de jogo (refazer os extras do nível) são REACÇÃO, e
+     * quem reage assina `on('modoCego', …)`. O anúncio não se perde para quem não injecta: este ícone já diz
+     * `sr.icon.blindOn`/`Off` por si, logo abaixo.
+     */
+    const setModoCego = ctx.setModoCego ?? setModoCegoValue;
+    /** O documento onde se constroi. Resolvido a cada uso, e por globalThis — em node o identificador
+     *  document nem existe, e um ?? sobre ele lançaria ReferenceError em vez de cair no padrão. */
+    const docDaMontagem = () => ctx.doc ?? globalThis.document;
+    /*
+     * ⚠️ O CONTRASTE E A COR SÓ APARECEM SE HOUVER QUEM OS ESCREVA (ADR-0106 §5).
+     *
+     * 📏 Medido em 2026-09-08, e é o que separa este caso dos outros seis campos «acidentais»: eles eram estado
+     * que um cartucho calhou de guardar, e a engine pôde reclamá-los. Estes precisam de um
+     * `render/viz-setters`, cujo contexto pede **34 campos** do grafo de render de UM jogo — `parallaxLayers`,
+     * `decoSprites`, `getPowerups`, `rebuildCoins`, `worldSprite`. O `createGame` não monta isso, e um quiz não
+     * tem nada disso para montar. A engine não pode dar um padrão aqui; o que ela pode é não FINGIR.
+     *
+     * Decidido uma vez, no arranque, e não a cada montagem de barra: o conjunto de escritores de um consumidor
+     * não muda a meio de uma partida, e recalcular por tela faria as telas discordarem entre si.
+     */
+    const iconesDoJogo = iconesQueAccionam({
+        tema: Boolean(ctx.setTemaDoJogador),
+        correcao: Boolean(ctx.setCorrecaoDoJogador),
+        // 📌 Sem `Boolean(...)`: os dois de cima perguntam «existe escritor?» a um campo opcional; este é uma
+        // RESPOSTA que o jogo deu, e envolvê-la faria um `undefined` de um ctx mal montado virar `false` —
+        // esconder o controle em silêncio, que é metade do defeito que este campo existe para não cometer.
+        seguraTeclas: ctx.seguraTeclas,
+    });
+    /*
+     * ⚠️ RESOLVIDOS UMA VEZ, no arranque, pela mesma razão do `settings-motion`: o `rm` é mutado in-place e
+     * partilhado por REFERÊNCIA com quem desenha a cena, e resolvê-lo a cada uso criaria um objecto novo por
+     * chamada — o interruptor deixaria de alcançar o desenho, sem erro nenhum.
+     *
+     * 📌 O `getPauseActs` fica FUNÇÃO e não valor, porque a laziness dele é a razão de ele existir assim: no
+     * cartucho a tabela é um `const` declarado ~1200 linhas abaixo, e lê-la aqui cairia na zona morta temporal.
+     */
+    const rm = ctx.rm ?? lerCenaGuardada();
+    const rmKeys = ctx.rmKeys ?? CHAVES_DE_CENA;
+    const rmChar = ctx.rmChar ?? ANIMACOES_DO_PERSONAGEM;
+    const saveRM = ctx.saveRM ?? (() => guardarCena(rm));
+    /*
+     * ⚠️ ESTES TRÊS SÃO LIDOS A CADA CHAMADA, e não resolvidos uma vez como o `rm` acima. A diferença é
+     * deliberada e um teste apanhou-me a errá-la: congelar `ctx.getPauseActs` no arranque partiu um caso que
+     * TROCA a tabela depois do `init` — e trocar depois é legítimo, porque a laziness deste campo existe
+     * precisamente por a tabela chegar tarde. Um padrão não pode custar a ligação tardia que o campo tem.
+     *
+     * O `rm` é o contrário e por isso fica congelado: ali o que importa é a IDENTIDADE do objecto, partilhada
+     * por referência com quem desenha a cena.
+     *
+     * A anotação de tipo é necessária: sem ela o padrão `() => ({})` infere `{}`, que não aceita indexação por
+     * string, e o compilador passaria a recusar `acts[act]` — o despacho inteiro.
+     */
+    const dynLabel = (b) => (ctx.dynLabel ? ctx.dynLabel(b) : null);
+    const getPauseActs = () => (ctx.getPauseActs ? ctx.getPauseActs() : {});
+    const setPauseActor = (i) => { if (ctx.setPauseActor)
+        ctx.setPauseActor(i); };
     function hasPrivateOutput(i) { return hasPrivateOutputIn(P(), ctx.getNumPlayers(), i); }
+    /** A recusa da alternância para este jogador agora, ou `null`. Recalculada: o aparelho em uso muda. */
+    function recusaAgora(i) { return ctx.transporteEmUso ? recusaDaAlternancia(ctx.transporteEmUso(i)) : null; }
     function iconState(i) {
         const p = P()[i] || {};
         const cat = ctx.getAudioCat();
@@ -312,19 +471,25 @@ export function initPauseIcons(ctx) {
             librasOn: ctx.isLibrasOn(),
             calmMode,
             toggleMove: !!p.toggleMove,
-            viz: p.viz || '',
+            // ⚠️ `DEFAULTS.viz` E NÃO `''` (issue #61). A cadeia vazia funcionava por ACIDENTE: não casa
+            // `hc-direto` nem `fix-*`, então os dois ícones ficavam apagados pelo motivo certo por engano. O padrão
+            // passou a ter nome em `core/state`, e `render/viz-modes` já declarava esse modo com `kind:'normal'` —
+            // o que não faz nada. Dizer o padrão em vez de o deduzir é o que torna a marca do ADR-0029 possível
+            // aqui, porque ela lê `DEFAULTS` e mais nada.
+            visual: p.visual ?? PADRAO,
             privateOutput: hasPrivateOutput(i),
+            alternanciaExigida: recusaAgora(i) !== null,
         };
     }
     // --- TEA ---------------------------------------------------------------------------------
     function applyCalm() {
         const plan = calmMotionPlan(calmMode);
-        for (const k of ctx.rmKeys)
-            ctx.rm[k] = plan.sceneReduced;
-        ctx.saveRM();
+        for (const k of rmKeys)
+            rm[k] = plan.sceneReduced;
+        saveRM();
         // "silencioso" freezes the character too. Iterates the WHOLE players array (not just numPlayers) — verbatim.
         for (const p of P())
-            for (const c of ctx.rmChar)
+            for (const c of rmChar)
                 p[c.prop] = plan.charFrozen;
         const cat = ctx.getAudioCat();
         for (const k of CALM_AUDIO_CATS) {
@@ -341,7 +506,7 @@ export function initPauseIcons(ctx) {
     // --- icon actions (the dispatcher, as a table) ---------------------------------------------
     const ICON_ACTS = {
         blind: () => {
-            ctx.setModoCego(!ctx.getModoCego());
+            setModoCego(!ctx.getModoCego());
             ctx.srSay(t(ctx.getModoCego() ? 'sr.icon.blindOn' : 'sr.icon.blindOff'));
         },
         tts: () => {
@@ -360,22 +525,35 @@ export function initPauseIcons(ctx) {
         },
         tea: () => {
             calmMode = nextCalmMode(calmMode);
+            store.set(store.KEYS.tea, calmMode); // ADR-0028: todo menu persiste. Ver a nota no `let` acima.
             applyCalm();
             ctx.srSay(t('sr.icon.tea', { v: t(CALM_NAMES[calmMode]) }));
         },
         altmove: (i) => {
             // verbatim: `players[i].toggleMove` with no `||{}` guard (unlike contrast/cvd below).
-            ctx.setToggleMove(i, !P()[i].toggleMove);
+            setToggleMove(i, !P()[i].toggleMove);
         },
+        // ⚠️ OS DOIS ÍCONES DEIXARAM DE SE APAGAR UM AO OUTRO (#104). Eles SEMPRE ciclaram dentro do seu eixo —
+        // `nextContrast` e `nextCvd` existem separados desde sempre —, mas escreviam os dois no mesmo campo, e
+        // por isso mexer num zerava o outro. O snapshot dizia isso como se fosse desenho: «they overwrite each
+        // other; that is by design». Agora cada um escreve no seu eixo e o outro fica onde estava.
+        // ⚠️ AS DUAS GUARDAS NÃO SÃO CINTO E SUSPENSÓRIOS. Sem escritor, o ícone nem sequer é montado
+        // (`iconesDoJogo`), então este ramo não deveria ser alcançável pela barra — mas `iconAct` é EXPORTADO e
+        // qualquer consumidor pode chamá-lo por chave. Sem a guarda, essa chamada rebentaria; com ela, não faz
+        // nada e não anuncia — que é o mesmo que dizer a verdade: este jogo não tem por onde.
         contrast: (i) => {
-            const nx = nextContrast((P()[i] || {}).viz);
-            ctx.setPlayerViz(i, nx);
-            ctx.srSay(t('sr.visual.contrast', { v: t(CONTRAST_LABELS[nx] || 'contrast.off') }));
+            if (!ctx.setTemaDoJogador)
+                return;
+            const v = proximoTema((P()[i] || {}).visual ?? PADRAO);
+            ctx.setTemaDoJogador(i, v.tema);
+            ctx.srSay(t('sr.visual.contrast', { v: t(CURTO_DO_TEMA[v.tema]) }));
         },
         cvd: (i) => {
-            const nx = nextCvd((P()[i] || {}).viz);
-            ctx.setPlayerViz(i, nx.mode);
-            ctx.srSay(t('sr.icon.cvd', { v: t(CVD_NAMES[nx.idx]) }));
+            if (!ctx.setCorrecaoDoJogador)
+                return;
+            const v = proximaCorrecao((P()[i] || {}).visual ?? PADRAO);
+            ctx.setCorrecaoDoJogador(i, v.correcao);
+            ctx.srSay(t('sr.icon.cvd', { v: t(CURTO_DA_CORRECAO[v.correcao]) }));
         },
     };
     function iconAct(k, i) {
@@ -388,6 +566,17 @@ export function initPauseIcons(ctx) {
             ctx.srAlert(t('sr.icon.needsPrivateOutput'));
             return;
         }
+        // ⚠️ A MESMA RECUSA DO PAINEL, na mesma forma que as duas acima: DIZER e voltar. Aceitar o clique e
+        // ignorá-lo é a outra metade do que o ADR-0076 proíbe, e aqui há um agravante — este ícone e o
+        // `#opt-altmove` escrevem o MESMO valor, logo um a aceitar enquanto o outro recusa daria à criança dois
+        // botões que discordam sobre o mesmo ajuste.
+        if (k === 'altmove') {
+            const recusa = recusaAgora(i);
+            if (recusa) {
+                ctx.srAlert(t(recusa.chave));
+                return;
+            }
+        }
         const act = ICON_ACTS[k];
         if (act)
             act(i);
@@ -405,10 +594,27 @@ export function initPauseIcons(ctx) {
             b.classList.add(v.cvd);
         b.classList.toggle('pi-on', v.on);
         b.classList.toggle('pi-dis', v.dis);
+        /*
+         * 🔴 A ISSUE #128, E ELA É DE UMA LINHA: `pi-dis` é CLASSE CSS. A criança que enxerga vê o ícone
+         * apagado; a que navega por leitor de tela não recebe nada — o botão anuncia-se accionável e não
+         * responde. `aria-disabled` espelha o mesmo facto para quem ouve.
+         *
+         * ⚠️ E `aria-disabled` e NÃO `disabled`: o segundo tira o botão da ordem de tabulação, e quem navega
+         * por teclado deixaria de o alcançar — logo deixaria de poder ouvir POR QUE ele não responde. É a
+         * mesma escolha que o `#opt-altmove` faz no painel, pela mesma razão.
+         */
+        if (v.dis)
+            b.setAttribute('aria-disabled', 'true');
+        else
+            b.removeAttribute('aria-disabled');
         b.setAttribute('aria-pressed', String(v.active));
-        // `soon` buttons keep the label the markup gave them (same string) — no state to report.
-        if (!(ICON_BY_KEY.get(k) || {}).soon)
-            b.setAttribute('aria-label', computeIconLabel(k, st));
+        // ⚠️ TODO ÍCONE RECEBE RÓTULO, `soon` INCLUÍDO — e o guarda que aqui estava dizia por que não: «`soon`
+        // buttons keep the label the markup gave them (same string)». A segunda metade continua certa (não há
+        // estado a reportar), mas «mesma string» era verdade só enquanto a marcação e o reflexo corressem no
+        // MESMO IDIOMA — e desde que a engine passou a montar a barra (ADR-0106 etapa 2) deixam de correr.
+        // O `initI18n` carrega en/es de forma assíncrona; a marcação nasce em pt e só o reflexo a corrige.
+        // 📌 Medido num navegador: cinco ícones em inglês e três ainda em «(em construção)», na mesma barra.
+        b.setAttribute('aria-label', computeIconLabel(k, st));
     }
     function reflectIconsIn(root, i) {
         if (!root)
@@ -419,8 +625,48 @@ export function initPauseIcons(ctx) {
      * Reflete os ícones de TODAS as telas. Varre as BARRAS e não mais os cartões de pausa: desde o item 7 do
      * ADR-0044 os ícones vivem no HUD, e um cartão de pausa não contém `.pi-btn` nenhum.
      */
+    /**
+     * OS CARTÕES QUE ESTA INSTÂNCIA CONSTRUIU. Privado, e é a resposta a um problema que eu próprio criei.
+     *
+     * ⚠️ O `PauseIconsCtx` tinha um `getPauseScreens` e eu removi-o hoje, com razão: tinha ZERO leitores. Agora
+     * este módulo precisa de alcançar os cartões — e a saída certa NÃO é repor o campo. Quem os construiu foi
+     * ele; guardar o que construiu não pede nada a consumidor nenhum, e um campo de ctx é mais uma coisa que
+     * cada um dos 300 jogos teria de se lembrar de passar.
+     */
+    const cartoes = [];
+    /**
+     * ESCONDE OS ITENS QUE ESTE JOGO NÃO CONSEGUE ACCIONAR — recalculado, e não decidido no arranque.
+     *
+     * ⚠️ ESTA FUNÇÃO EXISTE POR UM DEFEITO DE TEMPO. O cartão era FILTRADO no `buildScreenPause`, e o
+     * `getPauseActs` é um getter precisamente porque a tabela CHEGA TARDE — «`pauseActs` is a `const` declared
+     * far below the init site», diz o próprio campo. Um consumidor que siga esse padrão documentado montava um
+     * cartão sem os itens cuja acção só existiu depois do boot, e nunca mais os recuperava.
+     *
+     * 📌 A avaliação passou para o ÚLTIMO instante possível: o `ui/shell` chama `reflectPauseIcons()` quando a
+     * fase vira `pause-menu`, ou seja quando a pausa ABRE. O §5 continua respeitado — a criança nunca vê um
+     * item que não acciona —, e agora também vê os que passaram a accionar.
+     */
+    function refrescarItensDaPausa() {
+        const acts = getPauseActs();
+        const raiz = ctx.pmButtons ?? PM_BTNS;
+        const opcoes = ctx.optionsButtons ?? PM_OPTIONS_BTNS;
+        const vivos = new Set([
+            ...raizQueAcciona(raiz, opcoes, acts).map((b) => b.act),
+            ...itensQueAccionam(opcoes, acts).map((b) => b.act),
+        ]);
+        // ⚠️ `filter(Boolean)`: os cartões são indexados por JOGADOR, e montar só a tela 2 deixa um buraco no
+        // índice 0. Um `for…of` sobre array esparso entrega `undefined`, e foi o que rebentou à primeira.
+        for (const cartao of cartoes.filter(Boolean)) {
+            for (const btn of cartao.querySelectorAll('.pm-btn')) {
+                // ⚠️ `hidden` e não `remove()`: reaparecer tem de ser possível, porque a tabela pode crescer outra vez
+                // (um jogo que só liga «sair» depois da primeira fase). Remover seria decidir uma vez de novo.
+                btn.hidden = !vivos.has(btn.dataset.act ?? '');
+            }
+        }
+    }
     function reflectPauseIcons() {
         ctx.getA11yBars().forEach((bar, i) => reflectIconsIn(bar, i));
+        refrescarItensDaPausa();
     }
     // --- the pause screen ----------------------------------------------------------------------
     /**
@@ -472,7 +718,7 @@ export function initPauseIcons(ctx) {
         if (!bar || !primeiro)
             return;
         naBarra.add(i);
-        const acts = ctx.getPauseActs();
+        const acts = getPauseActs();
         if (acts.resume)
             acts.resume(); // volta à tela normal: o modo é para usar DURANTE a partida
         ctx.srSay(t('sr.a11y.barEnter'));
@@ -516,7 +762,7 @@ export function initPauseIcons(ctx) {
         const cur = iconeSelecionado(bar);
         const idx = cur ? icones.indexOf(cur) : 0;
         if (acao === 'ativar') {
-            ctx.setPauseActor(i);
+            setPauseActor(i);
             if (cur)
                 cur.click();
             return;
@@ -527,19 +773,36 @@ export function initPauseIcons(ctx) {
         }
     }
     function buildScreenPause(i) {
-        const sp = document.createElement('div');
+        const sp = docDaMontagem().createElement('div');
         sp.className = 'screen-pause';
         sp.hidden = true;
         sp.dataset.player = String(i);
+        /*
+         * ⚠️ MONTA A LISTA INTEIRA E ESCONDE DEPOIS — e a versão anterior desta linha FILTRAVA aqui, o que estava
+         * errado por uma razão de TEMPO. O comentário que estava neste sítio dizia «montar é o primeiro instante
+         * em que a resposta existe»; não é. O `getPauseActs` é um getter precisamente porque a tabela chega
+         * TARDE — «`pauseActs` is a `const` declared far below the init site», diz o próprio campo —, e o
+         * `createGame` monta durante o próprio `createGame(...)`. Filtrar aqui apagava para sempre todo item cuja
+         * acção só passou a existir depois do boot.
+         *
+         * Quem decide o que se VÊ é o `refrescarItensDaPausa`, a cada `reflectPauseIcons()` — que o `ui/shell`
+         * dispara quando a fase vira `pause-menu`, ou seja quando a pausa ABRE. O §5 continua respeitado (a
+         * criança nunca vê um item que não acciona) e agora também vê os que passaram a accionar.
+         */
         sp.innerHTML = screenPauseMarkup({
-            player: i, numPlayers: ctx.getNumPlayers(), pmButtons: ctx.pmButtons, optionsButtons: ctx.optionsButtons,
-            dynLabel: ctx.dynLabel, t,
+            player: i,
+            numPlayers: ctx.getNumPlayers(),
+            pmButtons: ctx.pmButtons ?? PM_BTNS,
+            optionsButtons: ctx.optionsButtons ?? PM_OPTIONS_BTNS,
+            dynLabel: dynLabel, t,
         });
+        cartoes[i] = sp;
+        refrescarItensDaPausa(); // o §5 vale já na montagem, e não só na primeira abertura
         sp.addEventListener('click', (e) => {
             const target = e.target;
             const b = target && target.closest('.pm-btn');
             if (b) {
-                ctx.setPauseActor(i);
+                setPauseActor(i);
                 const act = b.dataset.act || '';
                 // NAVEGAÇÃO DENTRO DO CARTÃO fica aqui, e não na tabela de ações: `options` e `pmback` não fazem nada
                 // ao jogo — trocam qual lista está na tela. A tabela vive em `ui/shell`, que não conhece este `sp`.
@@ -554,7 +817,7 @@ export function initPauseIcons(ctx) {
                     entrarNaBarra(i);
                     return;
                 }
-                const acts = ctx.getPauseActs();
+                const acts = getPauseActs();
                 const fn = acts[act];
                 if (fn)
                     fn();
@@ -571,10 +834,10 @@ export function initPauseIcons(ctx) {
      * facilidade não existe —, e degradar o que existe para DAR acesso seria o contrário do que ele serve.
      */
     function buildQuickBar(i) {
-        const bar = document.createElement('div');
+        const bar = docDaMontagem().createElement('div');
         bar.className = 'screen-a11y';
         bar.dataset.player = String(i);
-        bar.innerHTML = quickBarMarkup();
+        bar.innerHTML = quickBarMarkup(iconesDoJogo);
         // FORA DA ORDEM DE TABULAÇÃO durante a partida (ADR-0044, item 7). Dez paradas entre a criança e o jogo
         // seria o preço de deixá-los lá — e o alcance por teclado não se perde: ele passa a ser o modo
         // `accessibility`, que se abre pela pausa. A barra do TÍTULO não é afetada: lá não se está jogando, e o
@@ -585,7 +848,7 @@ export function initPauseIcons(ctx) {
             const ib = e.target?.closest('.pi-btn');
             if (!ib)
                 return;
-            ctx.setPauseActor(i);
+            setPauseActor(i);
             iconAct(ib.dataset.pi || '', i);
             reflectPauseIcons(); // must run BEFORE reading the label back — that is what makes the caption honest
             if (cap)
@@ -614,7 +877,14 @@ export function initPauseIcons(ctx) {
     }
     return {
         buildScreenPause, buildQuickBar, entrarNaBarra, sairDaBarra, naBarraDe, navBar,
+        iconesMontados: iconesDoJogo,
         iconAct, iconLabel, reflectIconBtn, reflectIconsIn, reflectPauseIcons,
-        applyCalm, getCalmMode: () => calmMode, setCalmMode: (n) => { calmMode = n; }, iconState,
+        // ⚠️ O `setCalmMode` PERSISTE TAMBÉM, e sanea. Ele é a outra porta para o mesmo valor — se só o ciclo do
+        // ícone gravasse, um nível posto por aqui sobreviveria à sessão e não ao fecho da aba, que é a metade
+        // pior do defeito: o ajuste parece ter pegado e some depois.
+        applyCalm,
+        getCalmMode: () => calmMode,
+        setCalmMode: (n) => { calmMode = saneiaNivelTea(n); store.set(store.KEYS.tea, calmMode); },
+        iconState,
     };
 }

package/dist-pkg/ui/reach-notice.js

@@ -17,6 +17,14 @@ export function linhasDoAviso(a, t) {
     for (const c of a.curtos) {
         linhas.push(t('reach.curto', { transporte: nome(c.id), lugares: c.slots }));
     }
+    // ⚠️ A TERCEIRA FRASE, e ela existe porque um transporte pode CHEGAR a todas as ações e ainda assim não
+    // deixar a criança jogar (ADR-0104). Medido: a plataforma pede nove ações, o controle de tela tem nove
+    // lugares, e o cartão nunca aparecia — mas correr, andar e pular ao mesmo tempo são três dedos, e um
+    // telemóvel que reconhece dois não os dá. A criança tentava, não acontecia nada, e concluía que o jogo
+    // estava partido. Uma frase antes de começar é a resposta honesta; meia tela jogável não é.
+    for (const s of a.naoSeguram) {
+        linhas.push(t('reach.naoSegura', { transporte: nome(s.id), segura: s.holds, pedidas: a.seguraPedidas }));
+    }
     linhas.push(a.serviriamSeLigados.length
         ? t('reach.ligue', { saida: a.serviriamSeLigados.map(nome).join(t('reach.ou')) })
         : t('reach.semSaida'));

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

@@ -74,10 +74,23 @@ export interface SettingsAudioCtx {
     /** Core collision state (NOT owned by this panel — core/collision.ts reads it via isModoCego). The toggle's
      *  widget lives inside #audio; the state and its gameplay side effects (setupExtras) stay in game.js. */
     getModoCego: () => boolean;
-    setModoCego: (on: boolean) => void;
+    setModoCego?: (on: boolean) => void;
     /** Core collision state (cane hit spacing). Same reasoning as modo cego. */
     getCaneBlockDiv: () => number;
     setCaneBlockDiv: (div: number) => 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 SettingsAudioApi {
     /** Re-renders the whole #audio overlay content (master, categories, nav-sound, TTS panel, sinks, modo-cego and