@the-inclusionist/engine 6.36.1

package/dist-pkg/input/gamepad.js

@@ -0,0 +1,531 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/gamepad.ts — gamepad READING (stdDirs/padActions/bindActive/padMapFor) + the poll dispatcher
+// (pollPads) + the accessibility MAPPING WIZARD (openPadWiz/openPadWizFor/closePadWiz/padWizTick). Pure
+// button->action logic is separated from the DI runtime (initGamepad(ctx)): the Gamepad API is injected
+// (ctx.getGamepads, so tests feed a fake pad with no browser) and every cross-subsystem call (menu nav, quiz,
+// join/respawn, phase, overlays) is injected too — never reaches `document`/`navigator` or imports game.js.
+// Boundary: this module only READS buttons/axes and maps them to actions; the physical button ARTWORK/labels
+// (PAD_DESIGNS) and the on-screen touch pad are input/devices.ts + input/touch (a parallel extraction) — not here.
+import { t } from '../core/i18n.js';
+import { EDGE_BY_ACTION, edgeAllowed } from './edges.js';
+import { migrarMapaDeControle } from './vocabulary-migration.js';
+import { GAMEPAD_STANDARD } from './default-bindings.js';
+import { padCur, padPrevAct, padPrevStart, PAD_DEAD } from './state.js';
+import * as store from '../platform/storage.js';
+function bindingAt(map, key) {
+    const v = map[key];
+    return typeof v === 'object' && v !== null ? v : undefined;
+}
+// [axisValue, up, down, left, right] — os 8 passos de um D-pad "POV hat" (eixo alto do DirectInput), repouso ~1.286.
+const HAT_STEPS = [
+    [-1, 1, 0, 0, 0], [-0.7143, 1, 0, 0, 1], [-0.4286, 0, 0, 0, 1], [-0.1429, 0, 1, 0, 1],
+    [0.1429, 0, 1, 0, 0], [0.4286, 0, 1, 1, 0], [0.7143, 0, 0, 1, 0], [1, 1, 0, 1, 0],
+];
+/** Direções pelas FONTES PADRÃO: stick 0/1 (zona morta PAD_DEAD), D-pad 12-15, e o "hat" nos eixos >=6 (POV do
+ *  DirectInput). Controles com os dois direcionais mapeados ficam com ambos vivos (dedo no stick não mata o D-pad). */
+export function stdDirs(gp) {
+    const b = (i) => !!(gp.buttons[i] && gp.buttons[i].pressed);
+    const ax = (i) => gp.axes[i] || 0;
+    const d = { left: ax(0) < -PAD_DEAD || b(14), right: ax(0) > PAD_DEAD || b(15), up: ax(1) < -PAD_DEAD || b(12), down: ax(1) > PAD_DEAD || b(13) };
+    for (let i = 6; i < gp.axes.length; i++) {
+        const v = gp.axes[i];
+        if (typeof v !== 'number' || Math.abs(v) > 1.001)
+            continue; // fora do repouso do hat
+        for (const [hv, u, dn, l, r] of HAT_STEPS) {
+            if (Math.abs(v - hv) <= 0.09) {
+                if (u)
+                    d.up = true;
+                if (dn)
+                    d.down = true;
+                if (l)
+                    d.left = true;
+                if (r)
+                    d.right = true;
+                break;
+            }
+        }
+    }
+    return d;
+}
+/** Está o binding `bd` ativo agora neste gamepad? Digital = pressed; analógico ({ax,s}) = limiar por sinal
+ *  (metade do curso); hat ({av,v}) = valor exato do passo (±0.13 — os 8 passos distam ~0.286). */
+export function bindActive(gp, bd) {
+    if (!bd)
+        return false;
+    if (bd.b != null)
+        return !!(gp.buttons[bd.b] && gp.buttons[bd.b].pressed);
+    if (bd.ax != null)
+        return ((gp.axes[bd.ax] || 0) * (bd.s ?? 0)) > 0.5;
+    if (bd.av != null)
+        return Math.abs((gp.axes[bd.av] || 0) - (bd.v ?? 0)) <= 0.13;
+    return false;
+}
+/** Ações do frame para este gamepad. `custom` = mapa salvo pelo wizard para este `gp.id` (null/`_skip` = usa o
+ *  mapa PADRÃO da Gamepad API "standard": 0=pulo · 1=especial · 2/5/7=correr · 3=troca · 9=START). Direções
+ *  custom caem de volta em stdDirs quando o binding do usuário não está ativo (D-pad/stick continuam vivos). */
+export function padActions(gp, custom) {
+    if (custom && !custom._skip) {
+        const A = (k) => bindActive(gp, bindingAt(custom, k));
+        const sd = stdDirs(gp);
+        return {
+            left: A('left') || sd.left, right: A('right') || sd.right, up: A('up') || sd.up, down: A('down') || sd.down,
+            action2: A('action2'), action1: A('action1'), action4: A('action4'), action3: A('action3'), _start: A('action2') || A('start'), _pause: A('start'),
+        };
+    }
+    const b = (i) => !!(gp.buttons[i] && gp.buttons[i].pressed);
+    const sd = stdDirs(gp);
+    // ⚠️ OS ÍNDICES SAEM DA TABELA DECLARADA, e não de literais aqui. Enquanto eram literais, esta linha e
+    // `input/default-bindings` DISCORDAVAM e nada notava — a mesma forma de defeito que o gate do toque
+    // apanhou: duas tabelas que concordam entre si não provam nada sobre um terceiro que as lê.
+    //
+    // ⚠️ E A DISCORDÂNCIA ERA REAL: aqui estava `action1: b(2) || b(5) || b(7)`, ou seja X, R1 e R2 todos a
+    // correr, enquanto a tabela declara R1 como `rightShoulder` e R2 como `rightTrigger`. O ADR-0086 registrou
+    // esta mudança como o asterisco do seu «zero movimento»: nenhum VERBO muda de botão, mas `run` perde dois
+    // dos seus três. Quem usava R1 para correr sente — e é o preço de os quatro ombros existirem.
+    const B = GAMEPAD_STANDARD;
+    const at = (a) => { const i = B[a]; return typeof i === 'number' ? b(i) : false; };
+    return {
+        left: sd.left, right: sd.right, up: sd.up, down: sd.down,
+        action1: at('action1'), action2: at('action2'), action3: at('action3'), action4: at('action4'),
+        leftShoulder: at('leftShoulder'), leftTrigger: at('leftTrigger'),
+        rightShoulder: at('rightShoulder'), rightTrigger: at('rightTrigger'),
+        // ⚠️ `start` COMO POSIÇÃO, e não só como os derivados abaixo. Faltava, e o gate da tabela foi quem
+        // o encontrou: quem quisesse saber «o START está apertado?» tinha de ler `_start`, que começa por
+        // underscore e quer dizer outra coisa (fecha diálogo, e aceita a ação 2 também).
+        start: at('start'), select: at('select'),
+        // `_start` e `_pause` são DERIVADOS e não posições: «fecha diálogo» aceita a ação 2 ou o START, «pausa»
+        // só o START. Ficam escritos aqui porque descrevem o que a raiz faz com duas posições, não uma terceira.
+        _start: at('action2') || at('start'), _pause: at('start'),
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// Wizard data (a ORDEM dos passos + a animação de demonstração; as PALAVRAS vêm do jogo)
+// ---------------------------------------------------------------------------------------------
+/**
+ * A ORDEM em que o assistente pergunta. SÓ a ordem.
+ *
+ * ⚠️ ELA CARREGAVA AS PALAVRAS, EM PORTUGUÊS CRU, DENTRO DA ENGINE: `['action2', 'PULAR']`,
+ * `['action1', 'CORRER / INTERAGIR']`. Era o defeito do ADR-0074 na sua forma mais visível — não só
+ * vocabulário de plataforma dentro do motor, mas vocabulário de plataforma NUM IDIOMA SÓ, à frente de uma
+ * criança, num ficheiro que o pilar 3 obriga a ser localizável.
+ *
+ * A palavra vem agora de `ctx.rotuloDaAcao`, que o jogo fornece pelo seu preset. Aqui fica o que é mesmo da
+ * engine: a sequência em que se pergunta — direções primeiro, ação depois, sistema no fim —, que é uma
+ * decisão de ergonomia do assistente e não do jogo.
+ *
+ * ⚠️ E UMA AÇÃO QUE O JOGO NÃO NOMEIA NÃO É PERGUNTADA. `wizPrompt` salta-a, porque um jogo que não usa a
+ * posição não tem o que mapear nela — e perguntar produziria um passo mudo, ou pior, um passo a dizer
+ * `action7` em voz alta.
+ */
+export const PADWIZ_ORDER = [
+    // Direções primeiro: são o que a criança encontra sem pensar, e acertar as quatro dá confiança para as
+    // outras dez.
+    'up', 'down', 'left', 'right',
+    // O losango, na ordem em que o dedo o percorre neste projeto (ADR-0086 §2).
+    'action2', 'action1', 'action4', 'action3',
+    // ⚠️ OS QUATRO OMBROS FALTAVAM AQUI ATÉ 2026-09-06, e a falta era um buraco de acessibilidade e não uma
+    // omissão cosmética: o assistente existe PARA controles que não são «standard» — genéricos, adaptados,
+    // de uma mão —, e um jogo que declarasse `leftShoulder` não tinha por onde a criança o mapear. Cinco das
+    // quatorze posições eram inalcançáveis exatamente para quem mais precisa do assistente.
+    'leftShoulder', 'leftTrigger', 'rightShoulder', 'rightTrigger',
+    // Sistema por último: `start` e `select` costumam ser os botões mais pequenos e mais escondidos, e pedi-los
+    // no fim deixa a criança já habituada ao ritmo do assistente quando chega neles.
+    'start', 'select',
+];
+/** Demonstração animada de cada ação (frames reais do jogo) mostrada durante o passo correspondente do wizard. */
+export const PADWIZ_ANIM = {
+    up: { seq: ['escada/0', 'escada/1'], hold: 9, cls: 'pw-up' },
+    down: { seq: ['escada/1', 'escada/0'], hold: 9, cls: 'pw-down' },
+    left: { seq: ['andar/0', 'andar/1', 'andar/2', 'andar/3', 'andar/4', 'andar/5', 'andar/6', 'andar/7'], hold: 4, cls: 'pw-left', flip: 1 },
+    right: { seq: ['andar/0', 'andar/1', 'andar/2', 'andar/3', 'andar/4', 'andar/5', 'andar/6', 'andar/7'], hold: 4, cls: 'pw-right' },
+    action2: { seq: ['pulo/0', 'pulo/0', 'pulo/1', 'pulo/1'], hold: 7, cls: 'pw-jump' },
+    action1: { seq: ['correr/0', 'correr/1', 'correr/2', 'correr/3'], hold: 3, cls: 'pw-run' },
+    action4: { fx: '👟 🕷️ 🎈 🐇 🦘', cls: 'pw-swap', noimg: 1 },
+    action3: { seq: ['idle/0', 'idle/1', 'idle/2', 'idle/3'], hold: 8, fx: '✨', cls: 'pw-especial' },
+    start: { fx: 'PAUSA', cls: 'pw-start', noimg: 1 },
+};
+export function initGamepad(ctx) {
+    const _padMaps = new Map(); // cache id -> mapa custom (evita reparsear JSON a cada frame)
+    let padWiz = null;
+    let padWizAutoResume = false; // wizard aberto automaticamente no meio do jogo -> retoma a fase ao fechar
+    let padWizAnim = null;
+    function padMapFor(id) {
+        // ⚠️ O MAPA SALVO PASSA PELO TRADUTOR NA LEITURA. Ele é indexado por AÇÃO — `{ jump: { b: 0 } }` — e um
+        // mapa gravado antes do ADR-0086 tem as chaves antigas, que `bindingAt` já não procura: o controle
+        // custom simplesmente pararia de responder, e o jogo cairia no mapa padrão sem dizer nada.
+        // É o mais caro dos três formatos a perder: um mapa destes existe porque alguém passou por um assistente
+        // de nove passos, botão a botão, quase sempre porque o controle NÃO é «standard» — e controles genéricos
+        // ou adaptados raramente são. Ver `input/vocabulary-migration.ts`.
+        if (!_padMaps.has(id)) {
+            _padMaps.set(id, migrarMapaDeControle(store.getJSON('incl_padmap_' + id, null)));
+        }
+        return _padMaps.get(id) ?? null;
+    }
+    function actionsFor(gp) { return padActions(gp, padMapFor(gp.id)); }
+    // ----- wizard: anúncio + demo animada (DOM-facing, thin) -----
+    function wizSay(t) {
+        const el = ctx.$('#padwiz-prompt');
+        if (el)
+            el.textContent = t;
+        ctx.srSay(t);
+    }
+    function wizDemo(k) {
+        const d = ctx.$('#padwiz-demo');
+        const img = ctx.$('#padwiz-demo-img');
+        const fx = ctx.$('#padwiz-demo-fx');
+        if (!d)
+            return;
+        const a = k ? PADWIZ_ANIM[k] : null;
+        d.className = a ? a.cls : '';
+        padWizAnim = null;
+        if (fx)
+            fx.textContent = (a && a.fx) || '';
+        if (img) {
+            img.style.display = a && a.noimg ? 'none' : '';
+            img.style.transform = a && a.flip ? 'scaleX(-1)' : '';
+            if (a && a.seq) {
+                img.src = ctx.spriteBase + a.seq[0] + '.png';
+                padWizAnim = { seq: a.seq, hold: a.hold || 6, t: 0 };
+            }
+            else if (!a)
+                img.src = ctx.spriteBase + 'idle/0.png';
+        }
+    }
+    function wizDemoTick() {
+        if (!padWizAnim)
+            return;
+        const a = padWizAnim;
+        a.t++;
+        const img = ctx.$('#padwiz-demo-img');
+        if (img)
+            img.src = ctx.spriteBase + a.seq[Math.floor(a.t / a.hold) % a.seq.length] + '.png';
+    }
+    /**
+     * Anda até o próximo passo que ESTE jogo usa, ou fecha se não houver mais.
+     *
+     * ⚠️ UMA FUNÇÃO SÓ, e antes eram duas com regras diferentes: `wizBind` incrementava e fechava no fim,
+     * `wizPrompt` saltava as não nomeadas. Depois do último passo nomeado o assistente ficava aberto a
+     * apontar para uma posição que o jogo não usa, e só fechava no tique seguinte — uma criança veria o
+     * assistente pendurado, sem pergunta nenhuma na tela.
+     */
+    function wizAvancar() {
+        if (!padWiz)
+            return;
+        while (padWiz.step < PADWIZ_ORDER.length && !ctx.rotuloDaAcao(PADWIZ_ORDER[padWiz.step]))
+            padWiz.step++;
+        if (padWiz.step >= PADWIZ_ORDER.length)
+            closePadWiz(true);
+    }
+    function wizPrompt() {
+        if (!padWiz)
+            return;
+        wizAvancar();
+        if (!padWiz)
+            return; // fechou ao avançar
+        const acao = PADWIZ_ORDER[padWiz.step];
+        const rotulo = ctx.rotuloDaAcao(acao);
+        wizSay((padWiz.step + 1) + ' de ' + PADWIZ_ORDER.length + ' — aperte: ' + rotulo);
+        wizDemo(acao); // demonstração animada do que a ação FAZ
+        const pr = ctx.$('#padwiz-progress');
+        if (pr)
+            pr.textContent = 'Mapeados: ' + (Object.keys(padWiz.map).join(' · ') || '—');
+    }
+    function wizBind(bd) {
+        if (!padWiz)
+            return;
+        padWiz.map[PADWIZ_ORDER[padWiz.step]] = bd;
+        padWiz.step++;
+        padWiz.release = true; // exige soltar antes do próximo passo (mesmo botão segurado não dobra pro passo seguinte)
+        wizAvancar(); // salta o que este jogo não usa, e fecha se o resto da lista for tudo isso
+    }
+    // ----- wizard: abrir/fechar -----
+    function openPadWiz() {
+        const ov = ctx.$('#padwiz');
+        if (!ov)
+            return;
+        ov.hidden = false;
+        ctx.frontOverlay(ov);
+        padWiz = { gi: -1, id: '', step: -1, base: null, map: {}, release: false, baseWait: false, axTrack: null, timer: null };
+        wizSay('Aperte QUALQUER botão no controle que deseja mapear.');
+        wizDemo(null);
+        const pr = ctx.$('#padwiz-progress');
+        if (pr)
+            pr.textContent = '';
+        padWiz.timer = setInterval(padWizTick, 30);
+    }
+    // Wizard aberto AUTOMATICAMENTE (controle DirectInput sem mapa apertou algo): já sabemos qual controle é.
+    function openPadWizFor(gp) {
+        const ov = ctx.$('#padwiz');
+        if (!ov)
+            return;
+        ov.hidden = false;
+        ctx.frontOverlay(ov);
+        padWiz = { gi: gp.index, id: gp.id, step: -1, base: null, map: {}, release: false, baseWait: true, axTrack: null, timer: null };
+        wizSay('Controle novo detectado: ' + gp.id + '. O jogo pausou para você configurá-lo. SOLTE tudo para começar.');
+        wizDemo(null);
+        const pr = ctx.$('#padwiz-progress');
+        if (pr)
+            pr.textContent = '';
+        padWiz.timer = setInterval(padWizTick, 30);
+    }
+    function closePadWiz(save) {
+        if (!padWiz)
+            return;
+        if (padWiz.timer != null)
+            clearInterval(padWiz.timer);
+        if (save && padWiz.id) {
+            store.setJSON('incl_padmap_' + padWiz.id, padWiz.map);
+            _padMaps.set(padWiz.id, padWiz.map);
+            ctx.srAlert(t('sr.pad.mapSaved', { id: padWiz.id }));
+        }
+        else if (padWiz.id && !_padMaps.get(padWiz.id)) {
+            _padMaps.set(padWiz.id, { _skip: true }); // cancelou: usa o mapa PADRÃO nesta sessão (não persiste, evita reabrir em loop)
+        }
+        const gi = padWiz.gi;
+        padWiz = null;
+        const ov = ctx.$('#padwiz');
+        if (ov)
+            ov.hidden = true;
+        // sem edges fantasmas: o botão ainda SEGURADO do último passo (START) não pode pausar/agir ao retomar
+        try {
+            const pads = ctx.getGamepads() ?? [];
+            const gp = pads[gi];
+            if (gp) {
+                const c = actionsFor(gp);
+                padCur[gi] = c;
+                padPrevAct[gi] = c;
+                padPrevStart[gi] = c._start;
+            }
+        }
+        catch { /* espelha o try/catch silencioso do original */ }
+        if (padWizAutoResume) {
+            padWizAutoResume = false;
+            if (ctx.menuDePausa())
+                ctx.retomar();
+        }
+    }
+    // ----- wizard: tick (roda a cada 30ms enquanto aberto) -----
+    function padWizTick() {
+        if (!padWiz)
+            return;
+        wizDemoTick();
+        const pads = ctx.getGamepads() ?? [];
+        if (padWiz.gi < 0) {
+            for (const gp of pads) {
+                if (gp && gp.buttons.some((b) => b && b.pressed)) {
+                    padWiz.gi = gp.index;
+                    padWiz.id = gp.id;
+                    padWiz.baseWait = true;
+                    wizSay('Controle: ' + gp.id + '. Agora SOLTE tudo.');
+                    break;
+                }
+            }
+            return;
+        }
+        const gp = pads[padWiz.gi];
+        if (!gp)
+            return; // controle desconectado (ou índice ainda não populado): congela até voltar
+        if (padWiz.baseWait) {
+            if (!gp.buttons.some((b) => b && b.pressed)) {
+                padWiz.baseWait = false;
+                padWiz.base = { b: gp.buttons.map((x) => !!(x && x.pressed)), a: gp.axes.slice() };
+                padWiz.step = 0;
+                wizPrompt();
+            }
+            return;
+        }
+        const base = padWiz.base;
+        if (padWiz.release) {
+            const idle = !gp.buttons.some((b, i) => b && b.pressed && !base.b[i]) && gp.axes.every((v, i) => Math.abs((v || 0) - base.a[i]) < 0.35);
+            if (idle) {
+                padWiz.release = false;
+                wizPrompt();
+            }
+            return;
+        }
+        // eixo em rastreio (~240ms): classifica pelo COMPORTAMENTO — varia continuamente = analógico (limiar por
+        // sinal); salta e FICA CONSTANTE = D-pad/POV hat (valor exato, ±0.13).
+        if (padWiz.axTrack) {
+            const t = padWiz.axTrack;
+            const v = gp.axes[t.i] || 0;
+            if (Math.abs(v - t.last) > 0.03)
+                t.changes++;
+            t.last = v;
+            if (Math.abs(v - base.a[t.i]) > Math.abs(t.v - base.a[t.i]))
+                t.v = v;
+            if (++t.ticks >= 8) {
+                const pv = t.v;
+                padWiz.axTrack = null;
+                wizBind(t.changes >= 2 ? { ax: t.i, s: pv > 0 ? 1 : -1 } : { av: t.i, v: Math.round(pv * 10000) / 10000 });
+            }
+            return;
+        }
+        for (let i = 0; i < gp.buttons.length; i++) {
+            if (gp.buttons[i] && gp.buttons[i].pressed && !base.b[i]) {
+                wizBind({ b: i });
+                return;
+            }
+        }
+        for (let i = 0; i < gp.axes.length; i++) {
+            const v = gp.axes[i] || 0;
+            if (Math.abs(v - base.a[i]) > 0.45) {
+                padWiz.axTrack = { i, v, last: v, changes: 0, ticks: 0 };
+                return;
+            }
+        }
+    }
+    const cancelBtn = ctx.$('#padwiz-cancel');
+    if (cancelBtn)
+        cancelBtn.addEventListener('click', () => closePadWiz(false));
+    // ----- poll (chamado a cada frame do loop) -----
+    function pollPads() {
+        if (padWiz)
+            return; // durante o wizard, os pads falam só com ele
+        const pads = ctx.getGamepads();
+        if (!pads)
+            return;
+        if (ctx.isAttractActive()) {
+            for (const gp of pads) {
+                if (gp && gp.buttons.some((b) => b && b.pressed)) {
+                    ctx.stopAttract();
+                    return;
+                }
+            } // botão de pad encerra a demo
+            return;
+        }
+        for (const gp of pads) {
+            if (!gp)
+                continue;
+            const gi = gp.index;
+            // controle fora do padrão (DirectInput) SEM mapa salvo apertou algo -> pausa geral + wizard direto
+            if (gp.mapping !== 'standard' && !padMapFor(gp.id) && gp.buttons.some((b) => b && b.pressed)) {
+                padWizAutoResume = ctx.mundoRodando();
+                if (ctx.mundoRodando())
+                    ctx.pausar();
+                openPadWizFor(gp);
+                return;
+            }
+            const cur = actionsFor(gp);
+            const prev = padPrevAct[gi] || {};
+            if (ctx.isTouchMode() && (cur.left || cur.right || cur.up || cur.down || cur.action2 || cur.action1 || cur.action4 || cur.action3 || cur._start)) {
+                ctx.hideTouchControls(); // botão físico usado -> some o gamepad virtual (mesma regra do teclado)
+            }
+            const startEdge = cur._start && !padPrevStart[gi];
+            padPrevStart[gi] = cur._start;
+            const pauseEdge = cur._pause && !prev._pause;
+            const edge = (k) => cur[k] && !prev[k];
+            padCur[gi] = cur;
+            padPrevAct[gi] = cur;
+            const winOv = ctx.$('#win-overlay');
+            if (winOv && !winOv.hidden) { // Vitória: START/pulo fecham o modal (Jogar de novo)
+                if (startEdge) {
+                    const b = ctx.$('#btn-again');
+                    if (b)
+                        b.click();
+                }
+                continue;
+            }
+            // Os três ramos abaixo pediam a FASE; hoje pedem os fatos. O `telaDeTitulo` é derivado por exclusão
+            // de propósito: numa cena que este módulo não conheça (um mapa, uma tela de resultados), o controle
+            // deve navegar como no título — que é o comportamento seguro — em vez de não fazer nada.
+            const rodando = ctx.mundoRodando(), pausado = ctx.menuDePausa();
+            const players = ctx.getPlayers();
+            if (!rodando && !pausado) {
+                const k = { yes: edge('action2') || startEdge, no: edge('action3'), up: edge('up'), down: edge('down'), left: edge('left'), right: edge('right') };
+                const any = k.yes || k.no || k.up || k.down || k.left || k.right;
+                const owner = players.findIndex((p) => p.pad === gi);
+                if (ctx.getNumPlayers() > 1 && owner > 0) {
+                    if (any)
+                        ctx.srSay(t('sr.title.waitP1'));
+                    continue;
+                } // só o J1 escolhe
+                if (any)
+                    ctx.navTitle(k); // menu inicial navegável pelo pad
+                continue;
+            }
+            if (pausado) {
+                const owner = players.findIndex((p) => p.pad === gi);
+                const pi = owner < 0 ? 0 : owner;
+                if (pauseEdge) {
+                    ctx.retomar();
+                    continue;
+                } // START retoma
+                const k = { yes: edge('action2'), no: edge('action3'), up: edge('up'), down: edge('down'), left: edge('left'), right: edge('right') };
+                if (k.yes || k.no || k.up || k.down || k.left || k.right) {
+                    const dlg = ctx.sharedDialogOpen();
+                    if (dlg)
+                        ctx.navDialog(dlg, k);
+                    else {
+                        const menu = ctx.getPauseMenu(pi);
+                        if (menu && !menu.hidden)
+                            ctx.navPause(menu, pi, k);
+                    }
+                }
+                continue;
+            }
+            if (rodando) {
+                const owner = players.findIndex((p) => p.pad === gi);
+                // ===================== O MODO `accessibility` (ADR-0044, item 7) =====================
+                // Com o jogo ANDANDO, o direcional deste jogador dirige a BARRA RÁPIDA e não o personagem. Vem antes
+                // de tudo o que é de jogo, porque enquanto o modo está ligado nada mais deste controle é de jogo.
+                //
+                // As DUAS saídas chegam juntas: `especial` é o VOLTAR do projeto (X no PlayStation, B no Xbox, A no
+                // Nintendo) e `startEdge` é o botão que abre a pausa — de onde se entrou aqui. Quem se perde tenta
+                // voltar por onde veio, e quem já conhece o jogo tenta o voltar de sempre; as duas dão certo.
+                if (owner >= 0 && ctx.naBarraDe(owner)) {
+                    const k = { yes: edge('action2'), no: edge('action3'), up: edge('up'), down: edge('down'), left: edge('left'), right: edge('right') };
+                    if (startEdge || k.yes || k.no || k.up || k.down || k.left || k.right)
+                        ctx.navBar(owner, k, !!startEdge);
+                    continue;
+                }
+                if (owner < 0) { // atribuição POR ORDEM DE AÇÃO: qualquer botão associa -> 1º controle a agir -> 1º jogador sem pad
+                    const anyEdge = edge('action2') || edge('action1') || edge('action4') || edge('action3') || startEdge || edge('left') || edge('right') || edge('up') || edge('down');
+                    if (anyEdge) {
+                        const waitI = players.findIndex((p) => p && p.waiting);
+                        const free = waitI >= 0 ? waitI : players.findIndex((p) => p && p.pad < 0 && !p.quit);
+                        if (free >= 0) {
+                            players[free].pad = gi;
+                            if (players[free].waiting) {
+                                players[free].waiting = false;
+                                ctx.clearWaitingBadge(free);
+                            }
+                            ctx.srSay(t('sr.pad.assigned', { n: free + 1 }));
+                        }
+                        else {
+                            ctx.joinPlayer(gi);
+                        }
+                    }
+                }
+                else if (players[owner].quit) {
+                    if (startEdge)
+                        ctx.respawnPlayer(owner); // tela abandonada -> recomeça SÓ ela
+                }
+                else {
+                    const p = players[owner];
+                    if (pauseEdge) {
+                        ctx.pausar();
+                        ctx.setPauseActor(owner);
+                        continue;
+                    } // START pausa (todos pausam; cada tela navega a sua)
+                    if (ctx.hasModal(owner)) { // o pad navega o modal do PRÓPRIO jogador (o jogo dos outros segue)
+                        // A ORDEM é a do original: esquerda, direita, cima, baixo, confirmar, apagar. O que saiu foi o
+                        // SIGNIFICADO — o ±1/±3 da grade e o desvio de Braille, que agora são decisão do jogo.
+                        const intent = edge('left') ? 'left' : edge('right') ? 'right'
+                            : edge('up') ? 'up' : edge('down') ? 'down'
+                                : edge('action2') ? 'confirm' : edge('action3') ? 'erase' : null;
+                        if (intent)
+                            ctx.modalInput(owner, intent);
+                        continue;
+                    }
+                    // A tabela e a guarda do Fácil vêm de input/edges.ts, as MESMAS que keydown e touch usam. Antes eram
+                    // seis `if` à mão aqui, seis lá e seis no toque — e o do toque tinha esquecido o `!p.easy`.
+                    for (const [act, flag] of EDGE_BY_ACTION) {
+                        if (edgeAllowed(act, p.easy) && edge(act))
+                            p[flag] = true;
+                    }
+                }
+            }
+        }
+    }
+    return { pollPads, openPadWiz, openPadWizFor, closePadWiz, padWizTick, padMapFor, getPadWiz: () => padWiz };
+}

package/dist-pkg/input/keyboard-runtime.d.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { ControlledPlayer } from '../core/entity.js';
+import type { KeyScheme } from '../core/entity.js';
+import type { KBDefaults } from '../input/keyboard.js';
+/** action -> list of physical key codes (KeyboardEvent.code), e.g. {jump:['KeyJ','Space']}. Mirrors the shape
+ *  ui/settings-controls.ts also defines locally (input/keyboard.ts's KeyScheme is not exported — each consumer
+ *  keeps its own structural copy rather than reaching across layers for a type alias). */
+export type { KeyScheme } from '../core/entity.js';
+/** input/keyboard.ts's KBDefaults shape ({solo,p2,p3,p4}) — the live `KB` value in game.js. */
+/** O `KBDefaults` de `input/keyboard`, que é o dono. O nome local sobrevive porque os consumidores o usam. */
+export type KeyboardConfig = KBDefaults;
+/** Minimal player shape this module needs: only `ctrl` is read/written — derived from core/entity.
+ *  `ControlledPlayer` rather than `Player` because this module runs after assignControls, so `ctrl` is no
+ *  longer null. That was already assumed here; now it is stated. */
+export type KeyboardRuntimePlayer = Pick<ControlledPlayer, 'ctrl'>;
+export interface KeyboardRuntimeCtx {
+    /** The live keyboard config (game.js's `KB`), read fresh on every call — never cached. */
+    getKB(): KeyboardConfig;
+    /** Current player count (core/state.ts's `numPlayers`, read live via game.js). */
+    getNumPlayers(): number;
+    /** The live players array (core/state.ts's `players`, mutated in place — never reassigned). */
+    getPlayers(): KeyboardRuntimePlayer[];
+}
+/** Result of the old `applyControls()` mutation, as a value: `controls` + its per-action aliases (game.js's
+ *  KJUMP/KLEFT/KRIGHT/KUP/KDOWN/KRUN) + the flattened `GAME_KEYS` list. */
+export interface ControlsState {
+    controls: KeyScheme;
+    action2: string[];
+    left: string[];
+    right: string[];
+    up: string[];
+    down: string[];
+    action1: string[];
+    gameKeys: string[];
+}
+export interface KeyboardRuntime {
+    /** The key scheme for player `playerIndex`, given the current KB config + player count (game.js's kbFor). */
+    kbFor(playerIndex: number): KeyScheme;
+    /** Which action (if any) `code` triggers FOR that player, given their scheme (game.js's actionOf). */
+    actionOf(code: string, playerIndex: number): string | null;
+    /** Which player (0-based) owns `code` among the active players; -1 if none (game.js's whichPlayer). */
+    whichPlayer(code: string): number;
+    /** Propagates `kb` -> each active player's `p.ctrl`, mutated in place (game.js's assignControls). */
+    assignControls(): void;
+    /** Computes the P1-alias `controls` + `GAME_KEYS` (game.js's applyControls, minus the reassignment). */
+    computeControlsState(): ControlsState;
+    /** O estado ATUAL, memorizado. Antes eram oito `let` no game.js (`controls`, `KJUMP`..`KRUN`, `GAME_KEYS`)
+     *  copiados de `computeControlsState()` por um `applyControls()` que existia só para fazer a cópia. Eram
+     *  derivados de `KB` + `players`, guardados em variável — a forma de estado que mais apodrece, porque nada
+     *  obriga a cópia a acompanhar a origem. Aqui a memória fica com quem é dono da conta, e a invalidação é
+     *  explícita e única: `refreshControls()`. NÃO recalcula a cada leitura de propósito — recalcular mudaria
+     *  o comportamento (passaria a enxergar remapeamento que ainda não foi aplicado), e isto é refatoração. */
+    controlsState(): ControlsState;
+    /** Recalcula e memoriza. É o `applyControls()` do game.js, agora do lado de cá. */
+    refreshControls(): ControlsState;
+}
+/** Which action does `code` trigger in this ONE scheme? Pure — no player/KB involved. */
+export declare function actionForCode(scheme: KeyScheme, code: string): string | null;
+/** Which player owns `code`, given one scheme per player (index = player index)? -1 if none. Pure. */
+export declare function ownerOfCode(schemesByPlayer: readonly KeyScheme[], code: string): number;
+export declare function initKeyboardRuntime(ctx: KeyboardRuntimeCtx): KeyboardRuntime;