@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/input/keydown.js

@@ -1,132 +1,114 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/keydown.ts — O ROTEADOR DE TECLADO: o que UMA tecla SIGNIFICA, aqui e agora.
+// input/keydown.ts — THE KEYBOARD ROUTER: what ONE key MEANS, here and now.
 //
-// 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.
+// The BUBBLING `keydown` listener a cartridge mounts (`initKeydown(ctx).attach()`) — the one point every key passes
+// that was not intercepted before. It is not "the character's control": walking and jumping are the consequence of the
+// LAST of the nine questions it asks. The first eight decide whether the key belongs to the game or to something else —
+// demo, remapping, dialog, win screen, title menu, number of screens, pause, modal — and that SEQUENCE is the
+// specification: the earlier one wins, and swapping two guards changes the game without breaking anything a build, a
+// `tsc` or an eye could see. (The engine's own root has its own keyboard conductor, for the virtual controller.)
 //
-// ======================= 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.
+// ======================= DECIDING ≠ DOING =======================
+// Given (key code, scene, who has a modal open, which dialog is visible, number of screens, key schemes) there is ONE
+// answer about what the key means — and the `preventDefault`, the `click()`, the `togglePause()` come only AFTER that
+// answer. With the two halves braided, each `if` mixing the question ("is a dialog open?") with the answer ("then hide
+// and leave"), the precedence — the part that matters — could only be checked by playing.
 //
-// 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.
+// Here they are two separate objects:
+//   · `decideKeydown(event, state) -> KeydownDecision` — PURE. No DOM, no PIXI, no audio, no `window`. It runs in the
+//     `node` project. Each branch of the precedence is a test case, and the precedence BETWEEN branches (modal open AND
+//     dialog visible: who wins?) is an assertion, not an anecdote.
+//   · `initKeydown(ctx).onKeydown(e)` — the IMPURE half: takes the ready decision and stamps it on the world.
+// It matters more here than anywhere, because what is at stake is the keyboard — the one modality EVERY person who
+// plays without a mouse, without sight or without a pad depends on.
 //
-// ======================= 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()`.
+// ======================= WHAT STAYED OUT OF THE PURE PART, AND WHY =======================
+// Two guards at the top do NOT fit in `decideKeydown`, and forcing them in would be a lie:
+//   · `attractOnInput()` (the demo) — it DECIDES AND ACTS in one call: resets the idleness counter, ends the demo if it
+//     is running, and returns whether it ended. There is no asking without touching.
+//   · `handleCaptureKeydown(e)` (ui/settings-controls.ts) — likewise: if a remap is in progress, it WRITES the key into
+//     the scheme and returns `true`.
+// Both are the first two lines of `onKeydown`, in that order, and the test proving they come before everything is the
+// wrapper's (with fake probes), not the pure function's.
+// Reading the dialogs' VISIBILITY does not enter the pure part either: it is `querySelector` + `.hidden`. What enters is
+// its RESULT (three booleans and an id), built by `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".
+// ======================= ⚠️ PAUSED, THIS LISTENER IS NOT REACHED FOR Escape =======================
+// `ui/menu-nav.ts` registers its OWN `keydown` in the CAPTURE phase and calls `stopPropagation()`. With the game PAUSED,
+// every key with a menu intent — Escape included — dies up there and never comes down here (menu-nav's header, DEFECT
+// 2): the `escapeTarget()` chain and Escape's `togglePause()` are dead code while paused; whoever closes is always the
+// top of the z-index stack.
+// THIS IS CURRENT BEHAVIOUR AND IT IS KEPT — not a bug to fix here, but a safety net the future fix will need (removing
+// the `stopPropagation()` with nothing else makes this module's `if(Escape||Enter) togglePause()` UNPAUSE the game with
+// Help open). The tests anchor it as it is: `decideKeydown` returns the decision IT would take, and the wrapper test
+// documents that, paused, it is not consulted because the event does not arrive. See `tests/keydown.node.test.js`.
 //
-// ======================= 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.
+// ======================= WHAT CAME ALONG, AND WHAT DID NOT =======================
+//  · `keyup` CAME. It is the exact other half of the keydown's hold: with the two apart, whoever reads "when a key
+//    enters `keys`" would have to look for the exit in another file. `attach()` installs both, in the same order.
+//  · `blur` did NOT come. It looks like a sibling and is not: `keys` also holds codes the virtual controller writes
+//    for a position the eyes pressed (`input/virtual-controller`), so letting go on `blur` is a lifecycle net of the
+//    WINDOW over a set that is not only the keyboard's. It lives in the root (`boot/create-game`), which dispatches
+//    the keyup each keyboard-held key is owed and leaves the camera's alone.
+//  · The Escape chain, the overlay registry and `closeById` belong to `ui/settings-panel.ts`. This module CONSUMES them
+//    (`escapeTarget`, `closeOverlayById`) and does not reimplement them — the same discipline as menu-nav.
+//  · `whichPlayer`/`actionOf`/`controlsState` belong to `input/keyboard-runtime.ts`, which is what knows key schemes.
+//    Here they come in injected and are only consulted. `controlsState()` is MEMOISED there: this module calls it once
+//    per key.
+//  · The title menu's navigation (`navTitle`) is the game's; the pause menu's is `ui/menu-nav.ts`'s. This module
+//    decides THAT the key is navigation and for WHOM — it never draws a 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.
+// ======================= INJECTION AND BOOT ORDER =======================
+//   1. REGISTRATION ORDER. Bubbling listeners on the same target fire in the order they were registered; the only
+//      capture one (menu-nav) already wins by phase. Registering elsewhere changes nothing as long as no other window
+//      listener is born in between — an invisible dependency worth not creating.
+//   2. LAZINESS. The whole ctx is `() => …`: no value is resolved at mount, only on the first key. A host that builds
+//      the demo, the panels or the pad AFTER mounting this module works; passing them by VALUE would read them before
+//      they exist.
+// What the host REASSIGNS comes in by GETTER (`oneButton`, `numPlayers`, `players`, the controls state). `keys` is a
+// `const` of `input/state.ts`, mutated in place — it comes in by VALUE (the same object forever).
 //
-// Ú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.
+// One behaviour note, declared: `snapshot()` reads the three `hidden` flags and `escapeTarget()` at once, rather than in
+// short circuit. That is at most four extra `querySelector` per key, all pure reads (`escapeTarget` only walks the
+// registry and tests `.hidden`). Nothing observable changes; noted because measuring later costs more than writing now.
 //
-// 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';
+// NO I/O ON IMPORT: the module body only declares frozen tables and pure functions. Every effect goes through
+// `initKeydown` (and even it does nothing until `attach()`).
 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. */
+/* --- tables (frozen: they are data, and a named `Set` keeps the table auditable from outside) --- */
+/** Easy (SOLO): Ctrl = Special, Shift = Swap power. Not Win/Alt/AltGr, on purpose. */
 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. */
+/** Alt + the digit row (NOT the numeric keypad) = 1..4 screens. Alt is free: solo does not use it. */
 export const SCREEN_DIGITS = /^Digit[1234]$/;
-/** Pausa: Escape ou o Enter CENTRAL. `NumpadEnter` NÃO pausa (E14, verbatim). */
+/** Pause: Escape or the MAIN Enter. `NumpadEnter` does NOT pause. */
 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.
+// The table and the Easy rule live in input/edges.ts, shared with gamepad and touch-bindings. Re-exported under the old
+// name because whoever imports from here (tests and readers) expects to find it here.
 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). */
+/* --- pure predicates (exported: the test imports the piece instead of repeating the expression) --- */
+/** Does the key count as JUMP for anybody? P1's alias OR any player's `action2` (it is what makes "anyone can press
+ *  Play again" and "anyone confirms on the title" true). */
 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). */
+/** Is the key a GAME key? The flattened alias OR some player's scheme. It does NOT include the Easy shortcuts: those
+ *  are added apart (`isEasyShortcut`). */
 export function isGameKeyCode(code, s) {
     return s.controls.gameKeys.includes(code)
-        // `arr &&` porque uma posição sem alcance é `null` desde a #118 — e `null.includes` seria uma exceção
-        // no caminho do teclado, ou seja, o jogo a parar de responder a qualquer tecla.
+        // `arr &&` because a position with no reach is `null` since #118 — and `null.includes` would be an exception on the
+        // keyboard path, that is, the game ceasing to answer any key.
         || s.players.some((p) => !!p.ctrl && Object.values(p.ctrl).some((arr) => !!arr && arr.includes(code)));
 }
-/** Os atalhos de acessibilidade do Fácil só existem SOLO (`numPlayers<=1`) e só para o Jogador 1. */
+/** Easy's accessibility shortcuts exist only in SOLO (`numPlayers<=1`) and only for Player 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.
+ * The title menu intent. Note the ASYMMETRY, kept as it is: `up`/`down` accept ArrowUp/ArrowDown ON TOP of the
+ * configured alias, `left`/`right` do not accept ArrowLeft/ArrowRight. It does not show in the factory scheme (solo
+ * already has the arrows on all four sides); it shows for whoever REMAPS — remap left to KeyA and the arrow stops moving
+ * in the menu, while up keeps working both ways. It is a test case in tests/keydown.node.test.js, and a candidate for a
+ * fix, not for a silent "cleanup".
  */
 export function titleNavOf(code, s, action2) {
     return {
@@ -138,18 +120,18 @@ export function titleNavOf(code, s, action2) {
         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. */
+/** Was any intent expressed? One definition in input/edges; here only the name this module always had. */
 import { hasNavIntent as hasTitleIntent } from './edges.js';
-// ⚠️ IMPORTADA E NÃO INJECTADA, ao contrário dos três escritores logo abaixo, e a linha que separa os dois é
-// esta: `origemDoEvento` é uma função PURA do evento — não toca estado nenhum que o cartucho possua. Os
-// escritores tocam o `input/state`, que é mutado in-place e partilhado, e é por isso que continuam a entrar.
-import { origemDoEvento } from './origem-sintetica.js';
+// ⚠️ IMPORTED AND NOT INJECTED, unlike the three writers below, and the line between them is this: `sourceOfEvent` is a
+// PURE function of the event — it touches no state the cartridge owns. The writers touch `input/state`, which is mutated
+// in place and shared, and that is why they keep coming in through the ctx.
+import { sourceOfEvent } from './synthetic-source.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.
+ * Who owns the modal this key commands? Returns the POSITION in the array, or -1.
+ * A player's key goes to THAT player's modal (and only if they have one open); a generic key falls to Player 1. A key of
+ * a player WITHOUT an open modal does not fall to P1 — it goes down to normal play, which is what lets their match go on
+ * while the other solves the challenge.
  */
 export function modalOwnerIndex(code, s) {
     const owner = s.whichPlayer(code);
@@ -158,47 +140,39 @@ export function modalOwnerIndex(code, s) {
     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).
+ * Which INTENT this key expresses inside its owner's modal. `owner` is the position in the array; `generic` says whether
+ * the key arrived with no owner (then the six readings use P1's aliases instead of the remapped action).
  *
- * 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.
+ * What a direction DOES inside the challenge (move one cell or three, dictate a Braille cell) is grid, and grid is the
+ * game's.
+ */
+/*
+ * The six readings, IN THIS ORDER — and the order is the rule: with a scheme where the same key is `left` and jump,
+ * `left` wins. Each row says which ACTION means that intent and, for a key with no owner, which alias list carries it.
+ * ⚠️ SPECIAL = erase the last syllable/letter, and its generic reading comes from `pl.ctrl` and NOT `controls` — an
+ * asymmetry kept, because `ControlsSnapshot` has no `action3` alias.
  */
+const MODAL_READINGS = [
+    { intent: 'left', action: 'left', alias: (s) => s.controls.left },
+    { intent: 'right', action: 'right', alias: (s) => s.controls.right },
+    { intent: 'up', action: 'up', alias: (s) => s.controls.up },
+    { intent: 'down', action: 'down', alias: (s) => s.controls.down },
+    { intent: 'confirm', action: 'action2', alias: (s) => s.controls.action2 },
+    { intent: 'erase', action: 'action3', alias: (_s, pl) => pl.ctrl?.action3 || [] },
+];
 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;
+    const act = generic ? null : s.actionOf(code, pl.i); // the player's own `i`, not the position
+    const read = MODAL_READINGS.find((r) => (act ? act === r.action : r.alias(s, pl).includes(code)));
+    return read ? read.intent : 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.
+ * The edges this key raises. It is only called when the key is NOT YET held — that is what makes it an EDGE and not a
+ * state, and what keeps the system's auto-repeat from becoming ten jumps.
+ * `p.ctrl[act] || []`: a scheme without the action turns a TypeError into a no-op (the precedent is `navPause`'s guard
+ * in ui/menu-nav.ts) — a net that removes no chance of a fix.
  */
 export function edgesFor(code, s) {
     const out = [];
@@ -207,84 +181,115 @@ export function edgesFor(code, s) {
             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)
+                continue; // Easy: no running (input/edges.ts, holding on all three paths)
             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).
+    // Easy (solo): Ctrl becomes Special and Shift becomes Swap power, ALWAYS on Player 1.
     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.
+/*
+ * 🔴 THE CHAIN, AND THE ORDER IS THE SPECIFICATION — which is exactly why it is a LIST and no longer a ladder.
+ * The header of this module says it in as many words: "the earlier one wins, and swapping two guards changes the game
+ * without breaking anything a build, a `tsc` or an eye could see". A ladder buries that claim in indentation; an array
+ * states it. Moving two questions is now moving two lines, and reading the precedence is
+ * reading the array from the top.
+ *
+ * ⚠️ Eight questions here and the ninth below, and the asymmetry is the point: the first eight may DECLINE, and
+ * normal play never does. Putting it in the list would give the list a member whose null can never happen, and
+ * would cost every caller a branch for a case that does not exist.
+ *
+ * 📌 The comments are the ones each question always carried, moved with the code they explain — a comment left
+ * behind starts explaining code that is no longer there (ADR-0171).
  */
-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;
+const CHAIN = [
+    // 1..3 · an open dialog BLOCKS the game — but only if the element is REALLY visible (a stuck flag does not lock the
+    // keyboard). The three leave without `preventDefault`: the dialog is DOM and wants the browser's native behaviour
+    // (Tab, typing in a range) underneath.
+    (_ev, s, f) => (s.escapeTargetId
+        ? { kind: 'overlay', closeId: f.code === 'Escape' ? s.escapeTargetId : null, preventDefault: false }
+        : null),
+    (_ev, s, f) => (s.touchCfgVisible ? { kind: 'touchcfg', close: f.code === 'Escape', preventDefault: false } : null),
+    (_ev, s, f) => (s.padWizVisible ? { kind: 'padwiz', close: f.code === 'Escape', preventDefault: false } : null),
+    // 4 · end of the level. ANY player's jump presses the main button, without depending on the mouse's focus (clicking
+    // the screen took focus off the button and the keyboard stopped working — the Dev's report).
+    (_ev, s, f) => {
+        if (!s.winVisible)
+            return null;
+        const again = f.action2 || f.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)
+    },
+    // 5 · title.
+    (_ev, s, f) => {
+        if (!s.titleScreen)
+            return null;
+        // multi-screen: only Player 1 picks the game. Another player's key is consumed with a spoken notice.
+        if (s.numPlayers > 1 && s.whichPlayer(f.code) > 0)
             return { kind: 'title', wait: true, nav: null, preventDefault: true };
-        const nav = titleNavOf(code, s, action2);
+        const nav = titleNavOf(f.code, s, f.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.
+    },
+    // 6..7 · number of screens and pause. BOTH require no modal open: with a challenge open on screen, Alt+3 must not
+    // reconfigure the game beneath it, and Enter is the challenge's confirmation, not the pause.
+    (ev, s, f) => (ev.altKey && !ev.ctrlKey && SCREEN_DIGITS.test(f.code) && s.inGame && !f.anyModal
+        ? { kind: 'screens', count: +f.code.slice(5), preventDefault: true }
+        : null),
+    (_ev, s, f) => (!f.anyModal && f.pauseKey && s.inGame ? { kind: 'pause', preventDefault: true } : null),
+    // 8 · modal. The key acts on its OWNER's modal; a generic one falls to P1. `preventDefault` does NOT depend on the key
+    // meaning something inside: being a game key is enough — the challenge swallows the key either way.
+    (_ev, s, f) => {
+        if (!f.anyModal)
+            return null;
+        const owner = modalOwnerIndex(f.code, s);
+        // a key of a player WITHOUT a modal falls to normal play (their match goes on) — move along
+        if (owner < 0)
+            return null;
+        return {
+            kind: 'modal', playerIndex: owner, intent: modalIntentOf(f.code, s, owner, s.whichPlayer(f.code) < 0),
+            preventDefault: s.controls.gameKeys.includes(f.code),
+        };
+    },
+];
+/** 9 · normal play — the one question that ALWAYS answers, and so the one that closes the chain instead of being in it. */
+function playDecision(s, f) {
+    const code = f.code;
     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.
+    // Motor empathy (one button at a time): the new key comes in and the OTHER game keys go out. The hold comes after the
+    // clearing in the wrapper, so the newcomer survives even if it was already on the list.
     const releaseKeys = s.oneButton && gameKey ? [...s.heldKeys].filter((k) => isGameKeyCode(k, s)) : [];
     return { kind: 'play', gameKey, wake, edges, releaseKeys, preventDefault: gameKey };
 }
+/**
+ * THE CHAIN. Nine questions, in this order — and the order IS the specification.
+ * What is NOT here, and comes first in the wrapper: the demo (attract) and the remapping capture. See the header.
+ */
+export function decideKeydown(ev, s) {
+    const facts = {
+        code: ev.code, action2: isJumpKey(ev.code, s), pauseKey: PAUSE_KEYS.has(ev.code), anyModal: s.modalOpen.some(Boolean),
+    };
+    for (const ask of CHAIN) {
+        const decided = ask(ev, s, facts);
+        if (decided)
+            return decided;
+    }
+    return playDecision(s, facts);
+}
 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 { t } = ctx;
+    /** An open dialog = an element that exists AND is not `hidden` — so a flag stuck on `true` cannot lock the whole
+     *  game's keyboard. */
     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).
+            titleScreen: ctx.isTitleScreen(), inGame: ctx.isInGame(), numPlayers: ctx.getNumPlayers(), players: ctx.getPlayers(), controls: ctx.getControls(),
+            // THE ANSWER, beside the players — built here, where they are already in hand (ADR-0033).
             modalOpen: ctx.getPlayers().map((_, i) => ctx.hasModal(i)),
             heldKeys: ctx.heldKeys, oneButton: ctx.isOneButton(),
             escapeTargetId: ctx.escapeTarget(),
@@ -292,110 +297,100 @@ export function initKeydown(ctx) {
             actionOf: ctx.actionOf, whichPlayer: ctx.whichPlayer,
         };
     }
-    /** A metade IMPURA: pega a decisão pronta e a carimba no mundo. */
-    function apply(d, code, origem) {
-        switch (d.kind) {
-            case 'overlay':
-                if (d.closeId)
-                    ctx.closeOverlayById(d.closeId);
+    /**
+     * ⚠️ THE SOURCE COMES FROM THE EVENT AND IS NOT INVENTED HERE (ADR-0109). `transport` is `undefined` for an event
+     * nobody signed — every real key — and then the narrow door ERASES the previous entry instead of letting the key
+     * inherit whoever held it last time. See `markKeyWithoutSource`.
+     *
+     * 📌 THE EDGE FEEDS THE AUTOMATON AT THE SAME POINT AND UNDER THE SAME CONDITION the source is written on the key — an
+     * unknown source is no device's edge, and inventing `teclado` for it would let a touch key turn off the latch of
+     * whoever plays by gaze, with no error and mid-match.
+     * ⚠️ A generic key (no owner) counts for player 1, the same convention as `ui/menu-nav`: whoever presses a key that
+     * belongs to no seat is playing in the first seat.
+     */
+    function rememberWhoPressed({ code, transport }) {
+        // one question: a key with no source says so and stops; a key with one marks it and the seat's transport
+        if (!transport) {
+            ctx.markKeyWithoutSource(code);
+            return;
+        }
+        ctx.markKey(code, transport);
+        const keyOwner = ctx.whichPlayer(code);
+        ctx.playerEdge(keyOwner < 0 ? 0 : keyOwner, transport);
+    }
+    const EFFECTS = {
+        overlay: (d) => { if (d.closeId)
+            ctx.closeOverlayById(d.closeId); },
+        touchcfg: (d) => { if (!d.close)
+            return; const el = ctx.$('#touchcfg'); if (el)
+            el.hidden = true; },
+        padwiz: (d) => { if (d.close)
+            ctx.closePadWiz(false); }, // the pad wizard: Esc CANCELS (does not save)
+        win: (d) => {
+            if (!d.again)
                 return;
-            case 'touchcfg': {
-                if (!d.close)
-                    return;
-                const t = ctx.$('#touchcfg');
-                if (t)
-                    t.hidden = true;
+            const b = ctx.$('#btn-again');
+            if (b)
+                b.click();
+        },
+        title: (d) => {
+            ctx.hideTouchControls(); // the keyboard on the title hides the virtual controls — BEFORE the notice
+            if (d.wait) {
+                ctx.srSay(t('sr.title.waitP1'));
                 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;
+            if (d.nav)
+                ctx.navTitle(d.nav);
+        },
+        screens: (d) => ctx.activateScreens(d.count),
+        pause: () => ctx.togglePause(),
+        // THE INDEX, NOT THE PLAYER: looking the player up here would only pass on an object whose challenge this module
+        // cannot describe — which is exactly what the other side needs to read.
+        modal: (d) => { if (d.intent)
+            ctx.modalInput(d.playerIndex, d.intent); },
+        play: (d, key) => {
+            const players = ctx.getPlayers();
+            if (d.gameKey)
+                ctx.hideTouchControls('teclado'); // playing on the keyboard hides the touch buttons
+            for (const idx of d.wake) { // THAT player's key activates the screen on standby
+                const p = players[idx];
+                if (!p)
+                    continue;
+                p.waiting = false;
+                ctx.clearWaitingBadge(p.i);
+                ctx.srSay(t('sr.player.entered', { n: p.i + 1 }));
             }
-            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;
+            for (const { playerIndex, edge } of d.edges) {
+                const p = players[playerIndex];
+                if (p)
+                    p[edge] = true;
             }
-            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.soltarTecla(k);
-                // ⚠️ A ORIGEM CHEGA DO EVENTO E NÃO É INVENTADA AQUI (ADR-0109). `origem` é `undefined` só para o
-                // evento sintético que ninguém assinou — e nesse caso a porta estreita APAGA a entrada anterior, em
-                // vez de deixar a tecla herdar de quem a segurou da última vez. Ver `marcarTeclaSemOrigem`.
-                if (origem)
-                    ctx.marcarTecla(code, origem);
-                else
-                    ctx.marcarTeclaSemOrigem(code);
-                // 📌 A ARESTA ALIMENTA O AUTÓMATO NO MESMO PONTO E SOB A MESMA CONDIÇÃO em que a origem é gravada na
-                // tecla — origem desconhecida não é aresta de aparelho nenhum, e inventar-lhe `teclado` faria uma
-                // tecla do toque desligar a alternância de quem joga por olhar, sem erro e no meio da partida.
-                // ⚠️ Tecla genérica (sem dono) conta para o jogador 1, que é a mesma convenção do `ui/menu-nav`: quem
-                // carrega numa tecla que não é de assento nenhum está a jogar no primeiro assento.
-                if (origem) {
-                    const dono = ctx.whichPlayer(code);
-                    ctx.arestaDoJogador(dono < 0 ? 0 : dono, origem);
-                }
-                return;
-            }
-        }
+            for (const k of d.releaseKeys)
+                ctx.releaseKey(k);
+            rememberWhoPressed(key);
+        },
+    };
+    /** Takes the ready decision and stamps it on the world. */
+    function apply(d, key) {
+        // ⚠️ The cast is the one thing the mapped type does not give for free: TypeScript does not narrow `d` and the table
+        // entry at the same time. The exhaustiveness — which is what matters — is guaranteed above.
+        EFFECTS[d.kind](d, key);
     }
     function onKeydown(e) {
         if (ctx.attractOnInput()) {
             e.preventDefault();
             return;
-        } // qualquer tecla encerra a demo
+        } // any key ends the demo
         if (ctx.handleCaptureKeydown(e))
-            return; // remap: a próxima tecla vira o controle
+            return; // remap: the next key becomes the control
         const d = decideKeydown(e, snapshot());
         if (d.preventDefault)
             e.preventDefault();
-        apply(d, e.code, origemDoEvento(e));
+        apply(d, { code: e.code, transport: sourceOfEvent(e) });
     }
-    // ⚠️ SOLTA NOS DOIS. Um `keys.delete` cru deixava a origem para trás, e um mapa que descreve teclas que já
-    // ninguém segura responde à alternância com o aparelho errado — sem erro, e só na aresta seguinte.
-    function onKeyup(e) { ctx.soltarTecla(e.code); }
+    // ⚠️ IT RELEASES IN BOTH. A raw `keys.delete` would leave the source behind, and a map describing keys nobody holds
+    // answers the latch with the wrong device — with no error, and only on the next edge.
+    function onKeyup(e) { ctx.releaseKey(e.code); }
     function attach() {
         ctx.win.addEventListener('keydown', onKeydown);
         ctx.win.addEventListener('keyup', onKeyup);