@the-inclusionist/engine 6.36.1

package/dist-pkg/input/keydown.js

@@ -0,0 +1,381 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/keydown.ts — O ROTEADOR DE TECLADO: o que UMA tecla SIGNIFICA, aqui e agora.
+//
+// Este é o ouvinte de `keydown` de BOLHA do game.js — o único ponto do jogo por onde passa toda tecla que não
+// foi interceptada antes. Ele não é "o controle do personagem": andar/pular são consequência da ÚLTIMA das
+// nove perguntas que ele faz. As oito primeiras decidem se a tecla é do jogo ou de outra coisa — demo,
+// remapeamento, diálogo, tela de vitória, menu inicial, número de telas, pausa, quiz — e é essa SEQUÊNCIA que
+// é a especificação: quem vem antes vence, e mudar a ordem de duas guardas muda o jogo sem quebrar nada que
+// um build, um `tsc` ou um olho consigam ver.
+//
+// ======================= A ENTREGA: DECIDIR ≠ EXECUTAR =======================
+// O bloco original é uma CADEIA DE DECISÃO PURA DISFARÇADA DE EFEITO. Dado (código da tecla, fase, quem tem
+// quiz aberto, qual diálogo está visível, número de telas, esquemas de tecla), existe UMA resposta sobre o que
+// a tecla significa — e o `preventDefault`, o `click()`, o `togglePause()` vêm só DEPOIS dessa resposta. No
+// monólito as duas metades estavam trançadas: cada `if` misturava a pergunta ("tem diálogo aberto?") com a
+// resposta ("então esconde e sai"), e por isso a ordem de precedência — a parte que realmente importa — só
+// podia ser verificada jogando.
+//
+// Aqui elas são dois objetos separados:
+//   · `decideKeydown(evento, estado) -> KeydownDecision`  — PURA. Sem DOM, sem PIXI, sem áudio, sem `window`.
+//     Roda no project `node`. Cada ramo da ordem de precedência é um caso de teste, e a precedência ENTRE os
+//     ramos (quiz aberto E diálogo visível: quem ganha?) é uma asserção, não um relato.
+//   · `initKeydown(ctx).onKeydown(e)` — a metade IMPURA: pega a decisão pronta e a carimba no mundo.
+// Mesmo movimento que `ui/shell.ts` fez com `phaseView`/`applyPhaseView` e `ui/title.ts` com
+// `computeTitleMenuView`; é o precedente da casa, e aqui ele vale mais do que lá, porque o que está em jogo é
+// o teclado — a única modalidade que TODA pessoa que joga sem mouse, sem visão ou sem controle depende.
+//
+// ======================= O QUE FICOU DE FORA DA PARTE PURA, E POR QUÊ =======================
+// Duas guardas do topo NÃO cabem em `decideKeydown`, e forçá-las lá seria mentira:
+//   · `attractCtl.onInput()` (game/attract.ts) — ela DECIDE E AGE na mesma chamada: zera o contador de
+//     ociosidade, encerra a demo se estiver rodando, e devolve se encerrou. Não há como perguntar sem mexer.
+//   · `ctrlPanel.handleCaptureKeydown(e)` (ui/settings-controls.ts) — idem: se há remapeamento em curso, ela
+//     GRAVA a tecla no esquema e devolve `true`.
+// As duas continuam sendo as duas primeiras linhas de `onKeydown`, na mesma ordem, e o teste que prova que
+// elas vêm antes de tudo é do wrapper (com sondas de mentira), não da função pura.
+// A leitura de VISIBILIDADE dos diálogos também não entra pura: ela é `querySelector` + `.hidden`. O que entra
+// na parte pura é o RESULTADO dela (três booleanos e um id), montado por `snapshot()`.
+//
+// ======================= ⚠️ PAUSADO, ESTE OUVINTE NÃO É ALCANÇADO PARA Escape =======================
+// `ui/menu-nav.ts` registra o PRÓPRIO `keydown` em fase de CAPTURA e dá `stopPropagation()`. Com o jogo
+// PAUSADO (`phase==='paused'`), toda tecla com intenção de menu — Escape inclusive — morre lá em cima e nunca
+// desce até aqui. Consequência MEDIDA no navegador, e anotada tanto no game.js quanto no cabeçalho de
+// menu-nav (DEFEITO 2): a cadeia `overlays.escapeTarget()` e o `togglePause()` de Escape são, na prática,
+// código morto enquanto pausado; quem fecha é sempre o topo da pilha de z-index.
+// ISTO É COMPORTAMENTO ATUAL E FOI PRESERVADO — não é bug para consertar aqui, é rede de segurança de que o
+// conserto futuro vai precisar (tirar o `stopPropagation()` sem mais nada faz o `if(Escape||Enter)
+// togglePause()` daqui DESPAUSAR o jogo com a Ajuda aberta). Os testes o ancoram como está: `decideKeydown`
+// devolve a decisão que ELE tomaria, e o teste do wrapper documenta que, pausado, ela não é consultada porque
+// o evento não chega. Ver `tests/keydown.node.test.js`, bloco "a captura do menu-nav chega antes".
+//
+// ======================= O QUE VEIO JUNTO, E O QUE NÃO VEIO =======================
+//  · `keyup` VEIO. Ele é a outra metade exata do `keys.add(e.code)` da última linha do keydown: sem os dois no
+//    mesmo lugar, quem lê "quando uma tecla entra em `keys`" tem de procurar a saída em outro arquivo. `attach()`
+//    instala os dois, na mesma ordem de antes.
+//  · `blur` NÃO veio. Parece irmão, mas não é: `keys` também recebe códigos INJETADOS pelos botões de toque
+//    (o `press`/`release` do game.js, que faz `keys.add(codeFor(act))`) e pelo controle por webcam
+//    (`ui/webcam.ts` despacha `KeyboardEvent` sintético). `blur -> keys.clear()` é uma rede de ciclo de vida da
+//    JANELA sobre um conjunto que não é só do teclado; trazê-la para cá daria a este módulo a
+//    responsabilidade de limpar estado que ele não escreve. Fica no game.js, uma linha, ao lado do `resize`.
+//  · A cadeia de Escape, o registro de overlays e o `closeById` são de `ui/settings-panel.ts`. Este módulo
+//    CONSOME (`escapeTarget`, `closeOverlayById`) e não reimplementa — mesma disciplina de menu-nav.
+//  · `whichPlayer`/`actionOf`/`controlsState` são de `input/keyboard-runtime.ts`, que é quem sabe de esquema de
+//    teclas. Aqui eles entram injetados e são só consultados. `controlsState()` é MEMORIZADO lá: este módulo o
+//    chama uma vez por tecla, como o original.
+//  · A navegação do menu inicial (`navTitle`) é de `ui/activities-menu.ts`; a do menu de pausa é de
+//    `ui/menu-nav.ts`. Este módulo decide QUE a tecla é de navegação e para QUEM ela vai — nunca desenha menu.
+//
+// ======================= INJEÇÃO E ORDEM DE BOOT =======================
+// `initKeydown` tem de ser chamado NO LUGAR EXATO onde o `addEventListener('keydown', …)` estava (logo depois
+// de `assignControls()`), por dois motivos independentes:
+//   1. ORDEM DE REGISTRO. Os ouvintes de bolha do mesmo alvo disparam na ordem em que foram registrados. Este é
+//      hoje o primeiro `keydown` de bolha da janela, e o único de captura (menu-nav) já vence por fase.
+//      Registrar mais tarde não muda nada HOJE, mas passa a depender de nenhum outro ouvinte de janela nascer
+//      no meio — dependência invisível que não vale a pena criar.
+//   2. TDZ. Quase tudo o que este módulo aciona (`attractCtl`, `ctrlPanel`, `gamepadApi`, `hud`, `navTitle`,
+//      `activateScreens`, `togglePause`, `hideTouchControls`, as quatro funções de quiz) é `const`/`function`
+//      declarado CENTENAS de linhas ABAIXO desse ponto. O ouvinte original só funcionava porque o corpo dele é
+//      preguiçoso: nada é lido até a primeira tecla. Por isso TODO o ctx é `() => …`: valor nenhum é resolvido
+//      na montagem. Passar `attractCtl` (ou `hud`, ou `navTitle`) por VALOR derruba o boot em TDZ.
+// A regra da casa vale igual: o que o game.js REATRIBUI entra por GETTER (`oneButton`, `numPlayers`, `players`,
+// o estado de controles). `keys` é `const` de `input/state.ts`, mutado in place — entra por VALOR (é o mesmo
+// objeto para sempre). `phase` é binding vivo de `core/state.ts`, importado direto, como em menu-nav.
+//
+// ÚNICA DIFERENÇA DE COMPORTAMENTO EM RELAÇÃO AO MONÓLITO, declarada: `snapshot()` lê os três `hidden` e o
+// `escapeTarget()` de uma vez, enquanto o original os lia em curto-circuito (só chegava ao `#padwiz` se não
+// houvesse overlay nem `#touchcfg`). São no máximo quatro `querySelector` a mais por tecla, todos de leitura
+// pura (`escapeTarget` só varre o registro e testa `.hidden` — conferido em ui/settings-panel.ts). Nada
+// observável muda; anotado porque medir depois é mais caro do que escrever agora.
+//
+// SEM I/O NO IMPORT: o corpo do módulo só declara tabelas congeladas e funções puras. Todo efeito passa por
+// `initKeydown` (e mesmo ele não faz nada até `attach()`).
+//
+// Ver docs/5-Refactoring/plano-modularizacao-mapa.md (D2-a).
+import { t } from '../core/i18n.js';
+import { EDGE_BY_ACTION, edgeAllowed } from './edges.js';
+/* --- tabelas (congeladas: são dados, e um `Set` nomeado deixa a tabela auditável de fora) --- */
+/** Fácil (SOLO): Ctrl = Especial, Shift = Trocar poder. Fora de Win/Alt/AltGr, de propósito. */
+export const EASY_SHORTCUTS = new Set(['ControlLeft', 'ControlRight', 'ShiftLeft', 'ShiftRight']);
+/** Alt + fileira de números (NÃO o teclado numérico) = 1..4 telas. Alt fica livre: o solo não o usa. */
+export const SCREEN_DIGITS = /^Digit[1234]$/;
+/** Pausa: Escape ou o Enter CENTRAL. `NumpadEnter` NÃO pausa (E14, verbatim). */
+export const PAUSE_KEYS = new Set(['Escape', 'Enter']);
+// A tabela e a regra do Fácil vivem em input/edges.ts, compartilhadas com gamepad e touch-bindings. Reexporta
+// pelo nome antigo porque quem importa daqui (teste e leitor) espera achá-la aqui.
+export { EDGE_BY_ACTION, edgeAllowed } from './edges.js';
+/* --- predicados puros (exportados: o teste importa a peça, não repete a expressão) --- */
+/** A tecla vale como PULO para alguém? O alias do J1 OU a ação `jump` de qualquer jogador (é o que faz
+ *  "qualquer um pode apertar Jogar de novo" e "qualquer um confirma no título" serem verdade). */
+export function isJumpKey(code, s) {
+    return s.controls.action2.includes(code) || s.players.some((_p, i) => s.actionOf(code, i) === 'action2');
+}
+/** A tecla é de JOGO? Verbatim do `isGameKeyCode` do game.js — o alias achatado OU o esquema de algum
+ *  jogador. NÃO inclui os atalhos do Fácil (o original também não: por isso `easyKey` é somado à parte). */
+export function isGameKeyCode(code, s) {
+    return s.controls.gameKeys.includes(code)
+        || s.players.some((p) => !!p.ctrl && Object.values(p.ctrl).some((arr) => arr.includes(code)));
+}
+/** Os atalhos de acessibilidade do Fácil só existem SOLO (`numPlayers<=1`) e só para o Jogador 1. */
+export function isEasyShortcut(code, s) {
+    return !!s.players[0]?.easy && s.numPlayers <= 1 && EASY_SHORTCUTS.has(code);
+}
+/**
+ * A intenção no menu inicial. Repare na ASSIMETRIA, preservada verbatim: `up`/`down` aceitam ArrowUp/ArrowDown
+ * ALÉM do alias configurado, `left`/`right` não aceitam ArrowLeft/ArrowRight. No esquema de fábrica isso não
+ * aparece (o solo já tem as setas nos quatro lados); aparece para quem REMAPEIA — remapeou esquerda para KeyA
+ * e a seta deixa de andar no menu, enquanto cima continua funcionando pelas duas. Está anotado como caso de
+ * teste em tests/keydown.node.test.js, e é candidato a conserto, não a "limpeza" silenciosa.
+ */
+export function titleNavOf(code, s, action2) {
+    return {
+        yes: action2 || code === 'Enter',
+        no: code === 'Escape' || s.players.some((_p, i) => s.actionOf(code, i) === 'action3'),
+        up: s.controls.up.includes(code) || code === 'ArrowUp',
+        down: s.controls.down.includes(code) || code === 'ArrowDown',
+        left: s.controls.left.includes(code),
+        right: s.controls.right.includes(code),
+    };
+}
+/** Alguma intenção foi expressa? Definição única em input/edges; aqui só o nome que este módulo sempre teve. */
+import { hasNavIntent as hasTitleIntent } from './edges.js';
+export { hasNavIntent as hasTitleIntent } from './edges.js';
+/**
+ * Quem é o dono do modal que esta tecla comanda? Devolve a POSIÇÃO no array, ou -1.
+ * Regra verbatim: tecla de um jogador vai para o modal DAQUELE jogador (e só se ele tiver um aberto); tecla
+ * genérica cai no Jogador 1. Tecla de um jogador SEM modal aberto não cai no P1 — ela desce para o jogo
+ * normal, que é o que deixa a partida dele continuar enquanto o outro resolve o desafio.
+ */
+export function modalOwnerIndex(code, s) {
+    const owner = s.whichPlayer(code);
+    if (owner >= 0)
+        return s.modalOpen[owner] ? owner : -1;
+    return s.modalOpen[0] ? 0 : -1;
+}
+/**
+ * Que INTENÇÃO esta tecla exprime dentro do modal do dono. `owner` é a posição no array; `generic` diz se a
+ * tecla chegou sem dono (aí as seis leituras usam os aliases do J1 em vez da ação remapeada).
+ *
+ * As seis leituras são as mesmas de antes, letra por letra. O que saiu foi a linha seguinte: a que trocava
+ * "cima" por `delta:-3` e "esquerda" por `delta:-1`, e o desvio de Braille. Isso é grade, e grade é do jogo.
+ */
+export function modalIntentOf(code, s, owner, generic) {
+    const pl = s.players[owner];
+    if (!pl)
+        return null;
+    const act = generic ? null : s.actionOf(code, pl.i); // `qpl.i`, não a posição — verbatim
+    const K = s.controls;
+    const L = act ? act === 'left' : K.left.includes(code);
+    const R = act ? act === 'right' : K.right.includes(code);
+    const U = act ? act === 'up' : K.up.includes(code);
+    const D = act ? act === 'down' : K.down.includes(code);
+    const J = act ? act === 'action2' : K.action2.includes(code);
+    // ESPECIAL = apagar a última sílaba/letra. A leitura genérica sai de `pl.ctrl`, NÃO de `K` — assimetria do
+    // original preservada (não existe alias `KESPECIAL` em ControlsState; o original alcançava `qpl.ctrl`).
+    const E = act ? act === 'action3' : ((pl.ctrl?.action3 || []).includes(code));
+    // A ORDEM é a do original e importa: com um esquema em que a mesma tecla é `left` e `jump`, ganha `left`.
+    if (L)
+        return 'left';
+    if (R)
+        return 'right';
+    if (U)
+        return 'up';
+    if (D)
+        return 'down';
+    if (J)
+        return 'confirm';
+    if (E)
+        return 'erase';
+    return null;
+}
+/**
+ * As bordas que esta tecla levanta. Só é chamada quando a tecla AINDA NÃO está segurada — é isso que a torna
+ * uma BORDA e não um estado, e é o que impede o auto-repeat do sistema de virar dez pulos.
+ * `p.ctrl[act] || []`: o original alcançava `p.ctrl.jump` direto e estouraria num esquema sem a ação. Trocar
+ * um TypeError por um no-op não remove rede de conserto nenhuma (o precedente é a guarda de `navPause` em
+ * ui/menu-nav.ts) — é a única linha desta função que não é cópia literal.
+ */
+export function edgesFor(code, s) {
+    const out = [];
+    s.players.forEach((p, idx) => {
+        if (!p.ctrl)
+            return;
+        for (const [act, edge] of EDGE_BY_ACTION) {
+            if (!edgeAllowed(act, p.easy))
+                continue; // Fácil: sem correr (input/edges.ts, valendo nos três caminhos)
+            if ((p.ctrl?.[act] || []).includes(code))
+                out.push({ playerIndex: idx, edge });
+        }
+    });
+    // Fácil (solo): Ctrl vira Especial e Shift vira Trocar poder, SEMPRE no Jogador 1 (`player` do original).
+    if (isEasyShortcut(code, s))
+        out.push({ playerIndex: 0, edge: code.startsWith('Control') ? 'specialEdge' : 'swapEdge' });
+    return out;
+}
+/**
+ * A CADEIA. Nove perguntas, nesta ordem — e a ordem É a especificação.
+ * O que NÃO está aqui, e vem antes no wrapper: a demo (attract) e a captura de remapeamento. Ver o cabeçalho.
+ */
+export function decideKeydown(ev, s) {
+    const code = ev.code;
+    // 1..3 · diálogo aberto BLOQUEIA o jogo — mas só se o elemento estiver DE FATO visível (uma flag presa não
+    // trava mais o teclado). Os três saem sem `preventDefault`, verbatim: o diálogo é DOM e quer o comportamento
+    // nativo do navegador (Tab, digitação num range) por baixo.
+    if (s.escapeTargetId)
+        return { kind: 'overlay', closeId: code === 'Escape' ? s.escapeTargetId : null, preventDefault: false };
+    if (s.touchCfgVisible)
+        return { kind: 'touchcfg', close: code === 'Escape', preventDefault: false };
+    if (s.padWizVisible)
+        return { kind: 'padwiz', close: code === 'Escape', preventDefault: false };
+    // 4..5 · fim de fase / título. O pulo de QUALQUER jogador aciona o botão principal, sem depender do foco do
+    // mouse (clicar na tela tirava o foco do botão e o teclado parava de funcionar — report do José).
+    const action2 = isJumpKey(code, s);
+    const pauseKey = PAUSE_KEYS.has(code);
+    if (s.winVisible) {
+        const again = action2 || pauseKey;
+        return { kind: 'win', again, preventDefault: again };
+    }
+    if (s.telaDeTitulo) {
+        // multi-tela: só o Jogador 1 escolhe o jogo. A tecla de um dos outros é consumida com um aviso falado.
+        if (s.numPlayers > 1 && s.whichPlayer(code) > 0)
+            return { kind: 'title', wait: true, nav: null, preventDefault: true };
+        const nav = titleNavOf(code, s, action2);
+        const has = hasTitleIntent(nav);
+        return { kind: 'title', wait: false, nav: has ? nav : null, preventDefault: has };
+    }
+    // 6..7 · número de telas e pausa. As DUAS exigem quiz FECHADO: com um desafio aberto na tela, Alt+3 não pode
+    // reconfigurar o jogo por baixo dele, e Enter é a confirmação do quiz, não a pausa.
+    const anyModal = s.modalOpen.some(Boolean);
+    const inGame = s.emJogo;
+    if (ev.altKey && !ev.ctrlKey && SCREEN_DIGITS.test(code) && inGame && !anyModal) {
+        return { kind: 'screens', count: +code.slice(5), preventDefault: true };
+    }
+    if (!anyModal && pauseKey && inGame)
+        return { kind: 'pause', preventDefault: true };
+    // 8 · modal. A tecla age no modal do DONO dela; genérica cai no P1. `preventDefault` NÃO depende de a
+    // tecla ter significado lá dentro: basta ser tecla de jogo — o desafio engole a tecla de qualquer forma.
+    if (anyModal) {
+        const owner = modalOwnerIndex(code, s);
+        if (owner >= 0) {
+            return { kind: 'modal', playerIndex: owner, intent: modalIntentOf(code, s, owner, s.whichPlayer(code) < 0),
+                preventDefault: s.controls.gameKeys.includes(code) };
+        }
+        // tecla de um jogador SEM modal cai no jogo normal (a partida dele continua) — segue adiante
+    }
+    // 9 · jogo normal.
+    const gameKey = isEasyShortcut(code, s) || isGameKeyCode(code, s);
+    const wake = s.players.reduce((acc, p, idx) => { if (p.waiting && s.actionOf(code, p.i))
+        acc.push(idx); return acc; }, []);
+    const edges = s.heldKeys.has(code) ? [] : edgesFor(code, s);
+    // Empatia motora (um botão por vez): a tecla nova entra e as OUTRAS de jogo saem. `keys.add` vem depois da
+    // limpeza no wrapper, então a recém-chegada sobrevive mesmo se já estivesse na lista.
+    const releaseKeys = s.oneButton && gameKey ? [...s.heldKeys].filter((k) => isGameKeyCode(k, s)) : [];
+    return { kind: 'play', gameKey, wake, edges, releaseKeys, preventDefault: gameKey };
+}
+export function initKeydown(ctx) {
+    /** Diálogo aberto = elemento que existe E não está `hidden`. Verbatim do `dlgVis` do monólito, que nasceu
+     *  justamente para uma flag presa em `true` não travar o teclado do jogo inteiro. */
+    const visible = (id) => { const el = ctx.$('#' + id); return !!el && !el.hidden; };
+    function snapshot() {
+        return {
+            telaDeTitulo: ctx.isTelaDeTitulo(), emJogo: ctx.isEmJogo(), numPlayers: ctx.getNumPlayers(), players: ctx.getPlayers(), controls: ctx.getControls(),
+            // A RESPOSTA, ao lado dos jogadores — e montada aqui, onde eles já estão na mão (ADR-0033).
+            modalOpen: ctx.getPlayers().map((_, i) => ctx.hasModal(i)),
+            heldKeys: ctx.heldKeys, oneButton: ctx.isOneButton(),
+            escapeTargetId: ctx.escapeTarget(),
+            touchCfgVisible: visible('touchcfg'), padWizVisible: visible('padwiz'), winVisible: visible('win-overlay'),
+            actionOf: ctx.actionOf, whichPlayer: ctx.whichPlayer,
+        };
+    }
+    /** A metade IMPURA: pega a decisão pronta e a carimba no mundo. */
+    function apply(d, code) {
+        switch (d.kind) {
+            case 'overlay':
+                if (d.closeId)
+                    ctx.closeOverlayById(d.closeId);
+                return;
+            case 'touchcfg': {
+                if (!d.close)
+                    return;
+                const t = ctx.$('#touchcfg');
+                if (t)
+                    t.hidden = true;
+                return;
+            }
+            case 'padwiz':
+                if (d.close)
+                    ctx.closePadWiz(false);
+                return; // wizard de gamepad: Esc CANCELA (não salva)
+            case 'win': {
+                if (!d.again)
+                    return;
+                const b = ctx.$('#btn-again');
+                if (b)
+                    b.click();
+                return;
+            }
+            case 'title':
+                ctx.hideTouchControls(); // teclado no splash oculta os controles virtuais — ANTES do aviso, verbatim
+                if (d.wait) {
+                    ctx.srSay(t('sr.title.waitP1'));
+                    return;
+                }
+                if (d.nav)
+                    ctx.navTitle(d.nav);
+                return;
+            case 'screens':
+                ctx.activateScreens(d.count);
+                return;
+            case 'pause':
+                ctx.togglePause();
+                return;
+            case 'modal': {
+                // A BUSCA DO JOGADOR SAIU DAQUI: este módulo a fazia só para repassar o objeto, e o objeto que ele
+                // sabia descrever não tinha `quiz` — que é justamente o que o outro lado precisa ler. Passa o índice.
+                if (!d.intent)
+                    return;
+                ctx.modalInput(d.playerIndex, d.intent);
+                return;
+            }
+            case 'play': {
+                const players = ctx.getPlayers();
+                if (d.gameKey)
+                    ctx.hideTouchControls('teclado'); // E13: jogar no teclado oculta os botões de toque
+                for (const idx of d.wake) { // a tecla DAQUELE jogador ativa a tela em espera
+                    const p = players[idx];
+                    if (!p)
+                        continue;
+                    p.waiting = false;
+                    ctx.clearWaitingBadge(p.i);
+                    ctx.srSay(t('sr.player.entered', { n: p.i + 1 }));
+                }
+                for (const { playerIndex, edge } of d.edges) {
+                    const p = players[playerIndex];
+                    if (p)
+                        p[edge] = true;
+                }
+                for (const k of d.releaseKeys)
+                    ctx.heldKeys.delete(k);
+                ctx.heldKeys.add(code);
+                return;
+            }
+        }
+    }
+    function onKeydown(e) {
+        if (ctx.attractOnInput()) {
+            e.preventDefault();
+            return;
+        } // qualquer tecla encerra a demo
+        if (ctx.handleCaptureKeydown(e))
+            return; // remap: a próxima tecla vira o controle
+        const d = decideKeydown(e, snapshot());
+        if (d.preventDefault)
+            e.preventDefault();
+        apply(d, e.code);
+    }
+    function onKeyup(e) { ctx.heldKeys.delete(e.code); }
+    function attach() {
+        ctx.win.addEventListener('keydown', onKeydown);
+        ctx.win.addEventListener('keyup', onKeyup);
+    }
+    return { snapshot, onKeydown, onKeyup, attach };
+}

package/dist-pkg/input/latch.d.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Sentido travado: -1 esquerda, 0 parado, 1 direita. */
+export type LatchDir = -1 | 0 | 1;
+/** Fração da velocidade de caminhada quando o jogador SEGURA o botão no sentido travado. */
+export declare const LATCH_HELD: number;
+/** Fração quando a direção está travada mas nenhum botão está pressionado — o "andar sozinho". */
+export declare const LATCH_IDLE: number;
+/**
+ * O próximo sentido travado, dado o atual e as bordas de toque deste quadro.
+ *
+ * Um toque no sentido em que já se anda PARA (é o mesmo botão que liga e desliga — não há botão de parar, e
+ * inventar um custaria a quem tem um dedo só o dobro de alcances). Um toque no sentido oposto inverte
+ * direto, sem passar pelo zero: quem toca "esquerda" andando para a direita quer ir para a esquerda, não
+ * quer parar e tocar de novo.
+ *
+ * As duas bordas no MESMO quadro são possíveis (dois dedos, ou um switch duplo mal calibrado) e a ordem
+ * importa: esquerda é avaliada primeiro e direita depois, então direita vence. É o comportamento que a
+ * física sempre teve — duas linhas `if` em sequência —, preservado aqui de propósito e agora com um teste que
+ * o fixa, em vez de ser um efeito não intencional da ordem em que alguém escreveu dois `if`.
+ */
+export declare function nextLatchedDir(current: LatchDir, leftEdge: boolean, rightEdge: boolean): LatchDir;
+/**
+ * O multiplicador da velocidade de caminhada, COM sinal: o sentido travado vezes a fração que corresponde a
+ * estar ou não segurando o botão daquele sentido.
+ *
+ * Devolve o produto (e não só a fração) porque parado é 0 e nenhuma fração precisa opinar sobre isso —
+ * exatamente como a física fazia ao multiplicar por `dir`. Quem chama multiplica por `TUNE.hWalk`; a
+ * constante de ajuste do jogo não entra neste módulo.
+ */
+export declare function latchedDrive(dir: LatchDir, holdingLeft: boolean, holdingRight: boolean): number;

package/dist-pkg/input/latch.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/latch — SEGURAR VIRA ALTERNAR. Passo 2 do ADR-0027, metade da "entrada como dado".
+//
+// O QUE É. Quem não consegue MANTER um botão pressionado — espasticidade, tremor, fadiga, um único dedo, um
+// switch de sopro — não perde o jogo: um TOQUE trava a direção, e o personagem segue andando sozinho. Tocar de
+// novo no mesmo sentido para; tocar no sentido oposto inverte. Segurar, para quem consegue, acelera.
+//
+// POR QUE SAIU DA FÍSICA. A política morava dentro de `game/physics.ts`, no meio do cálculo do movimento
+// horizontal. Três consequências, todas ruins:
+//   1. Uma decisão de ENTRADA estava escrita como se fosse uma regra do jogo, num arquivo que ninguém abre
+//      para mexer em acessibilidade motora.
+//   2. Só o movimento horizontal tinha caminho de alternância. Pulo, corrida e troca de poder não têm — e não
+//      por decisão, por acidente de onde o código foi parar. Este módulo é onde essa lacuna se fecha quando
+//      for fechada; NÃO a fecho agora, porque cada ação precisa da sua própria resposta de desenho (o que
+//      significa "pulo travado"?) e inventar isso sem o Dev seria pior que a lacuna.
+//   3. A engine não podia oferecer a alternância a OUTRO jogo sem levar a física do plataforma junto.
+//
+// DE QUE LADO DA LINHA ISTO CAI. O ADR-0027 separa PRESENTAÇÃO (como o estado vira pixel e som), OPERAÇÃO
+// (como a intenção vira entrada) e REGRA (o que é alcançável). O critério objetivo: uma adaptação cruza a
+// linha quando altera o CONJUNTO DE ESTADOS ALCANÇÁVEIS ou a PROBABILIDADE de alcançá-los. A alternância não
+// altera nem um nem outro — o jogador chega exatamente aos mesmos lugares, gastando menos motricidade. É
+// OPERAÇÃO, e por isso a engine a oferece e o jogo não pode recusar. (O modo Fácil, no mesmo botão hoje, é
+// REGRA: hitbox de +4px, proteção de beirada e gravidade 2/3 mudam o que é alcançável. Não estão aqui.)
+//
+// PURO DE PROPÓSITO: sem `document`, sem PIXI, sem `TUNE`. Recebe números e devolve números, roda no project
+// `node` do Vitest, e não sabe que existe um plataforma do outro lado.
+/** Fração da velocidade de caminhada quando o jogador SEGURA o botão no sentido travado. */
+export const LATCH_HELD = 2 / 3;
+/** Fração quando a direção está travada mas nenhum botão está pressionado — o "andar sozinho". */
+export const LATCH_IDLE = 1 / 3;
+/**
+ * O próximo sentido travado, dado o atual e as bordas de toque deste quadro.
+ *
+ * Um toque no sentido em que já se anda PARA (é o mesmo botão que liga e desliga — não há botão de parar, e
+ * inventar um custaria a quem tem um dedo só o dobro de alcances). Um toque no sentido oposto inverte
+ * direto, sem passar pelo zero: quem toca "esquerda" andando para a direita quer ir para a esquerda, não
+ * quer parar e tocar de novo.
+ *
+ * As duas bordas no MESMO quadro são possíveis (dois dedos, ou um switch duplo mal calibrado) e a ordem
+ * importa: esquerda é avaliada primeiro e direita depois, então direita vence. É o comportamento que a
+ * física sempre teve — duas linhas `if` em sequência —, preservado aqui de propósito e agora com um teste que
+ * o fixa, em vez de ser um efeito não intencional da ordem em que alguém escreveu dois `if`.
+ */
+export function nextLatchedDir(current, leftEdge, rightEdge) {
+    let dir = current;
+    if (leftEdge)
+        dir = dir === -1 ? 0 : -1;
+    if (rightEdge)
+        dir = dir === 1 ? 0 : 1;
+    return dir;
+}
+/**
+ * O multiplicador da velocidade de caminhada, COM sinal: o sentido travado vezes a fração que corresponde a
+ * estar ou não segurando o botão daquele sentido.
+ *
+ * Devolve o produto (e não só a fração) porque parado é 0 e nenhuma fração precisa opinar sobre isso —
+ * exatamente como a física fazia ao multiplicar por `dir`. Quem chama multiplica por `TUNE.hWalk`; a
+ * constante de ajuste do jogo não entra neste módulo.
+ */
+export function latchedDrive(dir, holdingLeft, holdingRight) {
+    const holding = (dir === -1 && holdingLeft) || (dir === 1 && holdingRight);
+    return dir * (holding ? LATCH_HELD : LATCH_IDLE);
+}

package/dist-pkg/input/pointer-space.d.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Retângulo do elemento (o que `getBoundingClientRect()` entrega, reduzido ao que a conta usa). */
+export interface RectLike {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Um ponto em px, relativo ao CENTRO do elemento. É a forma que um direcional lê. */
+export interface DoCentro {
+    dx: number;
+    dy: number;
+}
+/** Um ponto em FRAÇÃO do elemento: `0,0` é o canto superior esquerdo e `1,1` o inferior direito. */
+export interface EmFracao {
+    fx: number;
+    fy: number;
+}
+/**
+ * O ponto relativo ao CENTRO, em px do elemento.
+ *
+ * As três funções de direcional de `touch-bindings` abriam com estas mesmas duas linhas. Repetição de duas
+ * linhas não costuma pagar uma extração — esta paga por outra razão: enquanto a conta do centro estava
+ * escrita dentro de cada uma, não havia como um consumidor NOVO (um ponteiro, um olhar) obter o ponto sem
+ * passar por uma função que já o transformou em direções.
+ */
+export declare function doCentro(px: number, py: number, rect: RectLike): DoCentro;
+/**
+ * O ponto como FRAÇÃO do elemento.
+ *
+ * ⚠️ NÃO SATURA EM 0..1 de propósito. Um ponteiro capturado sai do elemento e continua a valer — é isso que
+ * `setPointerCapture` existe para permitir, e saturar aqui apagaria a diferença entre «na borda» e «muito
+ * para lá da borda», que é justamente o que um arrasto precisa de saber. Quem quiser saturar, satura; quem
+ * saturasse aqui não teria como voltar atrás.
+ *
+ * ⚠️ E LARGURA ZERO DEVOLVE ZERO em vez de `Infinity`. Um elemento ainda não medido (display:none, primeiro
+ * quadro) dá `width: 0`, e um `NaN`/`Infinity` a partir daqui viajaria para dentro da física antes de alguém
+ * o ver. O `onGaze` já se protegia disso com um `if (!r.width) return`; a proteção passa a ser da conta.
+ */
+export declare function emFracao(px: number, py: number, rect: RectLike): EmFracao;

package/dist-pkg/input/pointer-space.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/pointer-space.ts — O ÚNICO LUGAR QUE CONVERTE UM PONTO DE TELA. Módulo-folha: só aritmética.
+//
+// ========================= O QUE A MEDIÇÃO DA ISSUE #105 ENCONTROU =========================
+// A issue manda LER antes de escrever — *"estabeleça quanto de um ponteiro já existe dentro de
+// `input/touch.ts`; se a resposta for «quase tudo», isto vira uma extração e não um subsistema novo"*. A
+// resposta medida é mais interessante do que «quase tudo» ou «quase nada»:
+//
+//   · A CAPTURA já existe INTEIRA, em `touch-bindings.wirePointerPad`: `pointerdown`/`move`/`up`/`cancel`,
+//     `setPointerCapture` com recuo gracioso, `lostpointercapture` como rede, `contextmenu` suprimido, e um
+//     ponteiro de cada vez. Nada disso precisa de ser escrito outra vez.
+//   · O PONTO, ao contrário, é RECEBIDO E DEITADO FORA — e em quatro lugares, com duas convenções:
+//       `crossDirsAt`, `stickDirsAt` e `stickKnobOffset` reduzem-no a `dx,dy` do CENTRO e devolvem direções;
+//       `ui/webcam.onGaze` reduz o olhar a uma FRAÇÃO do elemento e a três limiares, emitindo teclas.
+//
+// ⚠️ E É O MESMO DEFEITO NOS DOIS SÍTIOS: uma posição contínua chega, é comprimida em «esquerda/direita/cima»
+// antes de qualquer outro consumidor a ver, e não sobra nada para quem precisasse dela. O ponteiro não é
+// fundação nova — é a fundação que o OLHAR já precisava e nunca teve.
+//
+// ⚠️ E O QUE NÃO EXISTE EM LADO NENHUM: hover (posição sem aperto), botões (`PointerLike` não tem `button`),
+// roda (zero ocorrências) e — o que a `definition of done` da #105 pede em primeiro lugar — UM lugar que
+// converta tela→jogo. Este ficheiro é esse lugar; o resto continua aberto na issue.
+/**
+ * O ponto relativo ao CENTRO, em px do elemento.
+ *
+ * As três funções de direcional de `touch-bindings` abriam com estas mesmas duas linhas. Repetição de duas
+ * linhas não costuma pagar uma extração — esta paga por outra razão: enquanto a conta do centro estava
+ * escrita dentro de cada uma, não havia como um consumidor NOVO (um ponteiro, um olhar) obter o ponto sem
+ * passar por uma função que já o transformou em direções.
+ */
+export function doCentro(px, py, rect) {
+    return { dx: px - (rect.left + rect.width / 2), dy: py - (rect.top + rect.height / 2) };
+}
+/**
+ * O ponto como FRAÇÃO do elemento.
+ *
+ * ⚠️ NÃO SATURA EM 0..1 de propósito. Um ponteiro capturado sai do elemento e continua a valer — é isso que
+ * `setPointerCapture` existe para permitir, e saturar aqui apagaria a diferença entre «na borda» e «muito
+ * para lá da borda», que é justamente o que um arrasto precisa de saber. Quem quiser saturar, satura; quem
+ * saturasse aqui não teria como voltar atrás.
+ *
+ * ⚠️ E LARGURA ZERO DEVOLVE ZERO em vez de `Infinity`. Um elemento ainda não medido (display:none, primeiro
+ * quadro) dá `width: 0`, e um `NaN`/`Infinity` a partir daqui viajaria para dentro da física antes de alguém
+ * o ver. O `onGaze` já se protegia disso com um `if (!r.width) return`; a proteção passa a ser da conta.
+ */
+export function emFracao(px, py, rect) {
+    return {
+        fx: rect.width ? (px - rect.left) / rect.width : 0,
+        fy: rect.height ? (py - rect.top) / rect.height : 0,
+    };
+}

package/dist-pkg/input/state.d.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { ControlledPlayer } from '../core/entity.js';
+export declare const keys: Set<string>;
+type PadState = Record<string, boolean>;
+export declare const padCur: Record<number, PadState>;
+export declare const padPrevAct: Record<number, PadState>;
+export declare const padPrevStart: Record<number, boolean>;
+export declare const PAD_DEAD = 0.5;
+type HeldPlayer = Pick<ControlledPlayer, 'ctrl' | 'pad'>;
+export declare const held: (pl: HeldPlayer, act: string) => boolean;
+export {};

package/dist-pkg/input/state.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/state.ts — ESTADO de input em runtime + query genérica, compartilhado pelos handlers (que ficam no
+// game.js e mutam estes objetos IN-PLACE): teclas seguradas (keys), estado de gamepad por controle
+// (padCur/padPrevAct/padPrevStart) e a zona morta do analógico (PAD_DEAD). held(pl,act) = o jogador está
+// segurando a ação, por teclado (pl.ctrl) OU pelo gamepad associado (pl.pad). Módulo-folha, ZERO deps. (Fase 2.22)
+export const keys = new Set();
+export const padCur = {};
+export const padPrevAct = {};
+export const padPrevStart = {};
+export const PAD_DEAD = 0.5; // zona morta = primeira METADE do curso do analógico (ergonomia — José 2026-07-02)
+// Jogador está segurando a ação? teclado (algum code do esquema pl.ctrl) OU o gamepad associado (pl.pad).
+export const held = (pl, act) => pl.ctrl[act].some((k) => keys.has(k)) || (pl.pad >= 0 && !!padCur[pl.pad]?.[act]);