@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/input/touch-bindings.js

@@ -1,113 +1,79 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/touch-bindings.ts — AS AMARRAS DO CONTROLE POR TOQUE: o gesto vira TECLA.
+// input/touch-bindings.ts — THE TOUCH CONTROL'S BINDINGS: the gesture becomes a POSITION.
 //
-// Este módulo é a outra metade de `input/touch.ts`. Aquele é o DONO DO PAD — a geometria física (mm→px), o
-// painel de configuração, o mapa remapeável (`getTouchMap`), mostrar/esconder os botões. Ele sabe onde o
-// polegar encosta e de que tamanho o alvo tem de ser. Não sabe o que acontece depois do toque.
-// É isto aqui. E o que acontece depois do toque é uma coisa só, e surpreendente: o botão da tela **finge ser
-// o teclado**. `press('jump')` não chama a física, não empurra o personagem, não fala com o jogo — ele
-// descobre qual TECLA está mapeada para "pular" no esquema do Jogador 1, injeta esse código no `keys` de
-// `input/state.ts` (o mesmo conjunto que o `keydown` alimenta) e levanta a borda `jumpEdge` em todo jogador
-// que tenha aquele código no próprio esquema. O resto do jogo nunca fica sabendo que houve um dedo na tela.
+// This module is the other half of `input/touch.ts`. That one OWNS THE PAD — the physical geometry (mm→px), the
+// settings panel, the remappable map (`getTouchMap`), showing/hiding the buttons. It knows where the thumb lands and
+// how big the target has to be. It does not know what happens after the touch.
+// This is what does. A screen button PRESSES A POSITION on the virtual controller (ADR-0223), stamped `toque`, the
+// same door the eyes, the voice and the keyboard use: in a menu the position becomes the menu's key, in play the
+// controller holds the child's key and delivers the command to the cartridge. On top of that, for a press that reached
+// the game, this module raises the matching edge flag on every player whose scheme holds that key.
 //
-// ======================= POR QUE UM ARQUIVO NOVO, E NÃO DENTRO DE input/touch.ts =======================
-// Porque são duas perguntas diferentes, e a segunda depende de coisas que a primeira não conhece.
-// `input/touch.ts` fecha sobre `$`, `store`, `root`, `viewport` — desenho e persistência. Este módulo precisa
-// do ESQUEMA DE TECLAS vivo (`kbRuntime.controlsState()`), do ARRAY DE JOGADORES, do `keys` compartilhado, do
-// `togglePause`, do `attract` e do `hideTips`: seis dependências que não têm nada a ver com desenhar um pad e
-// que arrastariam metade do jogo para dentro de um módulo que hoje é quase todo geometria pura.
-// A fronteira caiu, portanto, entre "onde o dedo está" (lá) e "o que o dedo significa" (aqui).
-// FUNDIR DEPOIS? Na minha leitura, NÃO — mas se um dia se fundir, que seja como DOIS `init` no mesmo arquivo
-// (`initTouch` e `initTouchBindings`), nunca como um `ctx` só: o `ctx` unificado teria quinze campos e o
-// módulo passaria a ser "tudo que tem a ver com toque", que é um tema, não uma responsabilidade. O acoplamento
-// real entre os dois é estreitíssimo e já está explícito no `ctx` daqui: `getTouchMap`, `getStickTravelPx`,
-// `getStickDeadPx` e `showTouchControls` — quatro getters, todos de leitura.
+// ======================= WHY A FILE OF ITS OWN, AND NOT INSIDE input/touch.ts =======================
+// Because they are two different questions, and the second depends on things the first does not know.
+// `input/touch.ts` closes over `$`, `store`, `root`, `viewport` — drawing and persistence. This module needs the live KEY
+// SCHEME, the PLAYERS array, the controller's door, `togglePause` and the host's hooks: dependencies that have nothing
+// to do with drawing a pad. So the boundary falls between "where the finger is" (there) and "what the finger means"
+// (here). If they are ever merged, let it be as TWO `init`s in one file, never one `ctx`: a unified ctx would make the
+// module "everything about touch", which is a theme, not a responsibility. The real coupling is narrow and explicit in
+// this ctx: `getTouchMap`, `getStickTravelPx`, `getStickDeadPx` and `showTouchControls` — four read-only getters.
 //
-// ======================= A ENTREGA: DECIDIR ≠ EXECUTAR =======================
-// O bloco original (`touchSetup` do main.js) trançava três coisas num `const` de uma linha cada: a tradução
-// gesto→tecla, a geometria do direcional e o amarrado de ouvintes. As duas primeiras são PURAS e aqui estão
-// separadas, no mesmo movimento que `input/keydown.ts` fez com `decideKeydown`:
-//   · `decideTouch(acao, ligado, snapshot) -> TouchDecision` — dado (ação, esquema do J1, esquemas dos
-//     jogadores, teclas já seguradas), existe UMA resposta. Sem DOM, sem ponteiro, sem `window`. Roda no
-//     project `node`. É onde a divergência do modo Fácil (abaixo) deixa de ser observável só num tablet.
-//   · `crossDirsAt` / `stickDirsAt` / `stickKnobOffset` — posição do ponteiro + retângulo do elemento →
-//     conjunto de direções ligadas. Zona morta, quadrantes e a borda da zona morta viram casos de teste.
-//   · `initTouchBindings(ctx).attach()` — a metade IMPURA: captura de ponteiro, `preventDefault`, `classList`,
-//     `setTimeout`. É a única parte que precisa de navegador de verdade.
+// ======================= DECIDING ≠ DOING =======================
+// Two parts are PURE and kept apart, the same move `input/keydown.ts` made with `decideKeydown`:
+//   · `decideTouch(action, on, snapshot) -> TouchDecision` — given (action, P1's scheme, the players' schemes, the keys
+//     already held) there is ONE answer. No DOM, no pointer, no `window`: it runs in the `node` project.
+//   · `crossDirsAt` / `stickDirsAt` / `stickKnobOffset` — pointer position + the element's rectangle → the set of
+//     directions on. Dead zone, quadrants and the dead zone's edge become test cases.
+//   · `initTouchBindings(ctx).attach()` — the IMPURE half: pointer capture, `preventDefault`, `classList`,
+//     `setTimeout`. The only part that needs a real browser.
 //
-// ======================= ⚠️ A TABELA "AÇÃO → BORDA" EXISTE TRÊS VEZES, E UMA DELAS DISCORDA =======================
-// A mesma correspondência entre as seis ações e as seis flags de borda está escrita em três lugares:
-//   1. `input/keydown.ts` (`EDGE_BY_ACTION`, tabela congelada; consumida em `edgesFor`, que aplica a guarda
-//      `if (act === 'run' && p.easy) continue; // Fácil: sem correr`);
-//   2. `input/gamepad.ts` (seis `if` à mão dentro de `pollPads`; o do `run` TEM a guarda: `if (edge('run') &&
-//      !p.easy) p.runEdge = true;`);
-//   3. AQUI (`TOUCH_EDGE_BY_ACTION` + `touchEdgesFor`), que veio dos seis `if` à mão do main.js — e o do `run`
-//      **NÃO TEM** a guarda do Fácil.
-// Isso FOI CORRIGIDO: o `run` daqui passou a ter a mesma guarda dos outros dois caminhos.
+// ======================= ONE ACTION → EDGE TABLE, AND ONE EASY-MODE RULE =======================
+// The keyboard, the pad and touch raise edges from the same table and the same guard (`input/edges`). They used to be
+// three hand-written copies, and touch's forgot Easy mode: `runEdge` is not running speed but the trigger that clings
+// to and lets go of a wall, so a child in Easy mode (which exists for motor difficulty) could climb by the screen
+// button and not by keyboard or pad. One table leaves the divergence nowhere to come back.
 //
-// A consequência é de acessibilidade, e é ao contrário do que o nome sugere. `runEdge` não é a velocidade de
-// corrida (isso é `held(pl,'run')`, lido em `game/physics.ts:169-170`): `runEdge` é a BORDA que gruda e solta
-// da parede — a ventosa/homem-aranha de `updateCling`, em `game/physics.ts:177` e `:179`. Logo, hoje, no modo
-// Fácil (deficiência motora), a criança NÃO consegue escalar parede pelo teclado nem pelo controle físico —
-// mas CONSEGUE pelo botão da tela. Três caminhos de entrada, dois comportamentos.
-// O teste continua comparando os TRÊS caminhos lado a lado, com o `edgesFor` real importado de `keydown.js` —
-// agora exigindo que CONCORDEM. As três tabelas ainda são três; fundi-las numa só é o passo seguinte, e é o
-// que impede a divergência de voltar.
+// ======================= WHAT STAYED OUT, AND WHY =======================
+//  · `hideTouchControls`/`showTouchControls` belong to `input/touch.ts`. Here `showTouchControls` is only CALLED (touch
+//    reveals the buttons); hiding belongs to whoever knows the keyboard took over.
+//  · The demo's `attractOnInput()` does not become pure, for the same reason as in `keydown.ts`'s header: it DECIDES AND
+//    ACTS in one call (resets idleness, ends the demo, returns whether it ended). It stays in the listener.
+//  · The d-pad's PHYSICAL geometry (how many px the travel is, how many px the stick's dead zone is) is
+//    `input/touch.ts`'s, recomputed on every `applyPadPhysical()`. It comes in by getter and is read ON EVERY MOVE —
+//    turning the device mid-gesture changes the travel on the next gesture.
+//  · The CROSS's dead zone, by contrast, is not configurable: 18% of the side (`CROSS_DEAD_FRACTION`).
 //
-// ======================= O QUE FICOU DE FORA, E POR QUÊ =======================
-//  · `hideTouchControls`/`showTouchControls` são de `input/touch.ts`. Aqui só se CHAMA `showTouchControls`
-//    (o toque revela os botões); esconder é do `keydown`, que sabe que o teclado assumiu.
-//  · `attractCtl.onInput()` não vira parte pura, pelo mesmo motivo do cabeçalho de `keydown.ts`: ela DECIDE E
-//    AGE na mesma chamada (zera a ociosidade, encerra a demo, devolve se encerrou). Fica no ouvinte.
-//  · A geometria FÍSICA do direcional (quantos px vale o curso, quantos px vale a zona morta do analógico) é
-//    de `input/touch.ts`, que a recalcula a cada `applyPadPhysical()`. Entra por getter e é lida A CADA
-//    MOVIMENTO, verbatim — girar o aparelho no meio de um gesto muda o curso no gesto seguinte.
-//  · A zona morta da CRUZ, ao contrário, não é configurável: são 18% do lado, escritos no lugar. Continua
-//    assim (`CROSS_DEAD_FRACTION`), agora com nome.
+// ======================= BOOT-ORDER TRAPS =======================
+// `initTouchBindings(ctx)` touches no DOM: it only closes over the `ctx` and returns the api. Every effect is in
+// `attach()`, which is where `#touch-controls` is looked up (and where the whole function gives up if it is missing).
+// Even so, the ctx is almost all GETTERS: what the host REASSIGNS (the players, the controls) comes in by getter, and
+// what is a `const` mutated in place (`keys`) comes in by VALUE.
+// REGISTRATION ORDER: `attach()` installs a CAPTURE `pointerdown` on the window, which is what ends a demo on the first
+// touch; registering later only matters if another window pointer listener is ever born in between.
 //
-// ======================= ARMADILHAS DE ORDEM DE BOOT =======================
-// `initTouchBindings(ctx)` não toca em DOM nenhum: só fecha sobre o `ctx` e devolve a api. Todo efeito está em
-// `attach()`, que é onde o `#touch-controls` é procurado (e onde a função inteira desiste, se ele não existir —
-// a guarda `if(!tc)return` do original).
-// MESMO ASSIM, o ctx é quase todo GETTER, e por dois motivos independentes:
-//   1. TDZ. No main.js, `attractCtl` é `const` declarado ABAIXO do ponto onde este bloco mora. O IIFE original
-//      só funcionava porque o corpo dos ouvintes é preguiçoso. Passar `attractCtl` por VALOR derruba o boot.
-//   2. Reatribuição. A regra da casa: o que o main.js REATRIBUI entra por getter. `keys` é `const` de
-//      `input/state.ts`, mutado in place → entra por VALOR (é sempre o mesmo objeto, para sempre).
-// ORDEM DE REGISTRO: `attach()` instala um `pointerdown` de CAPTURA na janela. Ele é hoje o primeiro ouvinte
-// de ponteiro do jogo e é ele que encerra a demo; registrar mais tarde só passa a importar se algum dia nascer
-// outro ouvinte de ponteiro de janela no meio. Mantenha a chamada no lugar exato onde o IIFE estava.
-//
-// SEM I/O NO IMPORT: o corpo do módulo só declara constantes congeladas e funções puras.
-//
-// Ver docs/5-Refactoring/plano-modularizacao-mapa.md (D3-b).
-/* ===================== interfaces mínimas ===================== */
-/** `ui/dom.ts` `$` — injetado; o módulo nunca alcança `document`. */
+// NO I/O ON IMPORT: the module body only declares frozen constants and pure functions.
+/* ===================== minimal interfaces ===================== */
+/** `ui/dom.ts` `$` — injected; the module never reaches `document`. */
 import { EDGE_BY_ACTION, edgeAllowed } from './edges.js';
-import { doCentro } from './pointer-space.js';
-// `isAction` guarda a porta: o `act` chega como string de um `data-` do markup de toque, e desde a #118 o
-// esquema só aceita as quatorze posições. Uma string que não é posição devolve `null` — o toque não faz nada,
-// que é exactamente o que o cabeçalho desta função já prometia.
+import { fromCentre } from './pointer-space.js';
+// `isAction` guards the door: the `act` arrives as a string from a `data-` of the touch markup, and since #118 the
+// scheme only accepts the fourteen positions. A string that is not a position returns `null` — the touch does nothing,
+// which is what this function's header promises.
 import { isAction } from '../core/actions.js';
-/* ===================== PURO (sem DOM — project node) ===================== */
-/**
- * Ação → borda, na MESMA ordem das outras duas cópias do projeto.
- * ⚠️ TERCEIRA CÓPIA DE UMA TABELA QUE JÁ EXISTE DUAS VEZES — `input/keydown.ts` (`EDGE_BY_ACTION`) e
- * `input/gamepad.ts` (seis `if` dentro de `pollPads`). Ver o bloco de aviso no cabeçalho: as três não
- * concordam sobre o modo Fácil, e a divergência está PRESERVADA de propósito.
- */
-export { EDGE_BY_ACTION as TOUCH_EDGE_BY_ACTION } from './edges.js'; // MESMA tabela dos outros dois caminhos
-/** `?touch=1` na URL força os controles de toque a aparecerem no desktop (atalho de teste do José). */
-export const TOUCH_FORCE_RE = /[?&]touch=1/;
-/** Predicado do `?touch=1`, isolado para o teste não repetir o regex. */
+/* ===================== PURE (no DOM — node project) ===================== */
+/** Action → edge: the ONE table keyboard, pad and touch share (`input/edges`), re-exported under touch's old name. */
+export { EDGE_BY_ACTION as TOUCH_EDGE_BY_ACTION } from './edges.js'; // the SAME table as the other two paths
+/** `?touch=1` in the URL forces the touch controls to show on a desktop (the Dev's testing shortcut). */
+const TOUCH_FORCE_RE = /[?&]touch=1/;
+/** The `?touch=1` predicate, isolated so the test does not repeat the regex. */
 export function wantsForcedTouch(search) {
     return TOUCH_FORCE_RE.test(search || '');
 }
 /**
- * Que TECLA este botão de tela finge apertar? A 1ª do esquema do Jogador 1 para aquela ação — 1ª, e não
- * todas, porque só uma precisa entrar em `keys` para o jogo inteiro reagir. Remapear o teclado remapeia o
- * toque junto, de graça: é a mesma tabela.
- * `null` = a ação não existe no esquema (ou o slot do mapa de toque está vazio) → o toque não faz nada.
+ * Which KEY does this screen button's position hold? The 1st in Player 1's scheme for that action — the 1st and not all,
+ * because only one has to enter `keys` for the whole game to react. Remapping the keyboard remaps touch along with it,
+ * for free: it is the same table.
+ * `null` = the action is not in the scheme (or the touch map's slot is empty) → no key, and so no edge.
  */
 export function codeForAction(act, controls) {
     if (!act || !isAction(act))
@@ -116,30 +82,25 @@ export function codeForAction(act, controls) {
     return (list && list[0]) || null;
 }
 /**
- * As bordas que este toque levanta, e em quem.
+ * The edges this touch raises, and on whom.
  *
- * ⚠️ SEM A GUARDA DO MODO FÁCIL — VERBATIM DO main.js, DEFEITO PRESERVADO.
- * `input/keydown.ts:edgesFor` pula `run` quando `p.easy` ("Fácil: sem correr"); `input/gamepad.ts:pollPads`
- * também (`if (edge('run') && !p.easy)`). Este caminho NÃO pula. Como `runEdge` é o gatilho de grudar/soltar
- * da parede (`game/physics.ts:177` e `:179`), e não a velocidade de corrida, o efeito prático é que no modo
- * Fácil a escalada existe pelo botão da tela e não existe pelo teclado nem pelo controle.
- * NÃO acrescente a guarda aqui sem consertar as três cópias de uma vez — ver o cabeçalho.
+ * WITH THE EASY-MODE GUARD (`edgeAllowed`, from `input/edges`), the same as the keyboard and the pad: `runEdge` is the
+ * trigger that clings to and lets go of a wall, not running speed, so without the guard a child in Easy mode could
+ * climb by the screen button and not by keyboard or pad.
  *
- * ÚNICO DESVIO DE LITERALIDADE, declarado: `p.ctrl[a] || []`. O original alcançava `p.ctrl.jump`/`.run`/
- * `.left`/`.right` DIRETO (e estouraria num esquema sem a ação), enquanto guardava `swap` e `especial` com
- * `&&` — assimetria sem intenção. Trocar um TypeError por um no-op não remove rede de conserto nenhuma; é o
- * mesmo precedente que `input/keydown.ts:edgesFor` já abriu, e está anotado lá pelo mesmo motivo.
+ * `p.ctrl[a] || []` and not a raw `p.ctrl[a]`: a scheme without the action turns a TypeError into a no-op — the same
+ * choice `input/keydown`'s `edgesFor` makes, for the same reason.
  */
 export function touchEdgesFor(act, code, players) {
     const out = [];
     players.forEach((p, idx) => {
         if (!p.ctrl)
-            return; // jogador sem esquema (tela não ativada) não recebe borda
+            return; // a player with no scheme (screen not activated) gets no edge
         for (const [a, edge] of EDGE_BY_ACTION) {
             if (a !== act)
                 continue;
             if (!edgeAllowed(a, p.easy))
-                continue; // Fácil: sem correr (input/edges.ts)
+                continue; // Easy: no running (input/edges.ts)
             if ((p.ctrl[a] || []).includes(code))
                 out.push({ playerIndex: idx, edge });
         }
@@ -147,64 +108,68 @@ export function touchEdgesFor(act, code, players) {
     return out;
 }
 /**
- * A DECISÃO. Gesto (ação mapeada + apertar/soltar) + mundo → o que isso significa.
- * `pause` primeiro, porque é o único que não passa pelo teclado sintético. Depois a tecla; sem tecla, nada.
+ * THE DECISION. A gesture (mapped action + press/release) + the world → what it means.
+ * `pause` first, because it is the only one that is not a position. Then the position and its key; without a key, the
+ * press still happens, with no edge.
  */
 export function decideTouch(act, on, s) {
     if (act === 'start')
-        return on ? { kind: 'pause' } : { kind: 'noop' }; // SOLTAR o START não despausa
-    const code = codeForAction(act, s.controls);
-    if (!code)
+        return on ? { kind: 'pause' } : { kind: 'noop' }; // RELEASING START does not unpause
+    // ⚠️ THE SLOT MAY BE EMPTY OR CARRY A STRING THAT IS NOT A POSITION: the value comes from a markup `data-`, and since
+    // #118 the scheme only accepts the fourteen. Then there really is nothing to press — a VALID position with no mapped
+    // key does not land here.
+    if (!act || !isAction(act))
         return { kind: 'noop' };
     if (!on)
-        return { kind: 'release', code };
-    // BORDA: só a PRIMEIRA vez que o código entra em `keys`. Se o teclado (ou o outro polegar) já o segurava,
-    // o toque não re-levanta as bordas — mas `hideTips` roda igual, verbatim.
-    const fresh = !s.heldKeys.has(code);
+        return { kind: 'release', action: act };
+    const code = codeForAction(act, s.controls);
+    // EDGE: only the FIRST time the code enters `keys`. If the keyboard (or the other thumb) already held it, touch does
+    // not raise the edges again — but `hideTips` runs all the same. With no key there is no edge to raise.
+    const fresh = !!code && !s.heldKeys.has(code);
     return {
-        kind: 'press', code, addKey: fresh,
-        edges: fresh ? touchEdgesFor(act, code, s.players) : [],
+        kind: 'press', action: act, addKey: fresh,
+        edges: fresh && code ? touchEdgesFor(act, code, s.players) : [],
         hideTips: act === 'action2',
     };
 }
-/* --- geometria do direcional (pura: posição + retângulo → direções) --- */
-/** Zona morta da CRUZ: ~18% do LADO a partir do centro, em cada eixo. Ver a nota de `crossDirsAt` sobre o
- *  `width` valer também para o eixo vertical — é verbatim, e é uma assimetria de verdade. */
+/* --- d-pad geometry (pure: position + rectangle → directions) --- */
+/** The CROSS's dead zone: ~18% of the SIDE from the centre, on each axis. See the note on `crossDirsAt` about `width`
+ *  also counting for the vertical axis — it is a real asymmetry. */
 export const CROSS_DEAD_FRACTION = 0.18;
 /**
- * Cruz (D-pad): onde o dedo está → quais direções ligam. Miolo neutro para não disparar por encostar no meio.
- * As quatro comparações são INDEPENDENTES: fora do miolo, uma diagonal liga DUAS direções (é o que dá o
- * comportamento de D-pad físico de 8 setores). O centro exato não liga nenhuma.
+ * Cross (D-pad): where the finger is → which directions turn on. A neutral core so brushing the middle does not fire.
+ * The four comparisons are INDEPENDENT: outside the core, a diagonal turns on TWO directions (which gives a physical
+ * 8-sector D-pad's behaviour). The exact centre turns on none.
  *
- * VERBATIM, incluindo a assimetria: a zona morta dos DOIS eixos sai de `rect.width` — a altura nunca entra na
- * conta. Numa cruz quadrada (é o que o CSS `--dpad-span` produz) dá no mesmo; numa cruz achatada, o miolo
- * vertical ficaria proporcionalmente maior ou menor que o horizontal. Anotado, não consertado.
+ * Including the asymmetry: both axes' dead zone comes from `rect.width` — the height never enters. On a square cross
+ * (what the CSS `--dpad-span` produces) it is the same; on a flattened one, the vertical core would be proportionally
+ * larger or smaller than the horizontal. Noted, not fixed.
  */
 export function crossDirsAt(px, py, rect) {
-    const { dx, dy } = doCentro(px, py, rect);
+    const { dx, dy } = fromCentre(px, py, rect);
     const dead = rect.width * CROSS_DEAD_FRACTION;
     return { left: dx < -dead, right: dx > dead, up: dy < -dead, down: dy > dead };
 }
 /**
- * Analógico virtual: mesma regra da cruz, mas a zona morta vem em PX de `input/touch.ts` (derivada dos mm
- * configuráveis — A12e motora), não de uma fração do elemento.
+ * Virtual stick: the cross's rule, but the dead zone comes in PX from `input/touch.ts` (derived from the configurable
+ * mm), not as a fraction of the element.
  */
 export function stickDirsAt(px, py, rect, deadPx) {
-    const { dx, dy } = doCentro(px, py, rect);
+    const { dx, dy } = fromCentre(px, py, rect);
     return { left: dx < -deadPx, right: dx > deadPx, up: dy < -deadPx, down: dy > deadPx };
 }
 /**
- * Para onde a manopla do analógico anda (px, relativo ao centro da base): segue o dedo até o limite do curso
- * `travelPx` e ali PARA, mantendo o ângulo (recorte radial, não por eixo — por isso `hypot`, e não `clamp`).
- * O `|| 1` do original evita divisão por zero quando o dedo cai no centro exato.
+ * Where the stick's knob goes (px, relative to the base's centre): it follows the finger up to the `travelPx` limit
+ * and STOPS there, keeping the angle (a radial clip, not per axis — hence `hypot` and not `clamp`).
+ * The `|| 1` avoids a division by zero when the finger lands on the exact centre.
  */
 export function stickKnobOffset(px, py, rect, travelPx) {
-    const { dx, dy } = doCentro(px, py, rect);
+    const { dx, dy } = fromCentre(px, py, rect);
     const m = Math.hypot(dx, dy) || 1;
     const f = m > travelPx ? travelPx / m : 1;
     return { x: dx * f, y: dy * f };
 }
-/** Quanto tempo o START segura a ação, quando ela é momentânea (não é `pause`). */
+/** How long START holds the action when it is momentary (not `pause`). */
 export const START_TAP_MS = 140;
 export function initTouchBindings(ctx) {
     const later = ctx.defer || ((fn, ms) => { setTimeout(fn, ms); });
@@ -214,8 +179,8 @@ export function initTouchBindings(ctx) {
     function decide(act, on) {
         return decideTouch(act, on, snapshot());
     }
-    /** A metade IMPURA: pega a decisão pronta e a carimba no mundo. Ordem verbatim: a tecla entra em `keys`
-     *  ANTES das bordas, e `hideTips` vem depois de tudo. */
+    /** The IMPURE half: takes the ready decision and stamps it on the world. The press first, then the edges, and
+     *  `hideTips` after everything. */
     function apply(d) {
         if (d.kind === 'noop')
             return;
@@ -224,24 +189,35 @@ export function initTouchBindings(ctx) {
             return;
         }
         if (d.kind === 'release') {
-            ctx.soltarTecla(d.code);
+            ctx.release(d.action, 'toque');
             return;
         }
+        /*
+         * 🔴 TOUCH PRESSES THE VIRTUAL CONTROLLER (ADR-0223). What a press means — going to the menu, holding the key,
+         * delivering nothing — is exactly the decision `input/virtual-controller` exists to take ONCE: with a menu open the
+         * position becomes the menu's key (ADR-0157), in play it holds the child's key AND delivers the command.
+         *
+         * 📌 ITS ANSWER IS WHAT SAYS THERE WAS PLAY. The question "is a menu open?" has one answer, the controller's — two
+         * answers to one question is how the two doors once came to disagree.
+         *
+         * ⚠️ `'toque'` is the stamp, and it is ADR-0109's rule 2 kept executable: it is THIS transport whose latch turns on,
+         * and the controller is what carries it to the key and the command.
+         */
+        if (!ctx.press(d.action, 'toque'))
+            return; // a menu took the press: no edge and no tip to touch
         if (d.addKey) {
-            // ⚠️ `'toque'` é o carimbo, e é a regra 2 do ADR-0109 a tornar-se executável: é ESTE transporte cuja
-            // alternância liga. Enquanto o código entrava cru no conjunto, a regra não tinha como se aplicar.
-            ctx.marcarTecla(d.code, 'toque');
             const players = ctx.getPlayers();
             for (const { playerIndex, edge } of d.edges) {
                 const p = players[playerIndex];
-                if (p)
+                // 📌 THE EDGE PER PLAYER, beside the flag it raises — and not once per touch: the same code may belong to more
+                // than one seat (`d.edges` is built with `includes` over each one's scheme), and the transport in use is a
+                // question PER CHILD. Marking only player 0 would give the first seat's latch to whoever plays in the second.
+                // (The guard on `p` is defensive: `d.edges` comes from the same frame's players, so an index without one does
+                // not happen today.)
+                if (p) {
                     p[edge] = true;
-                // 📌 A ARESTA POR JOGADOR, ao lado da borda que ela levanta — e não uma vez por toque: o mesmo código
-                // pode pertencer a mais de um assento (`d.edges` é construído com `includes` sobre o esquema de cada
-                // um), e o transporte em uso é uma pergunta POR CRIANÇA. Marcar só o jogador 0 daria a alternância do
-                // primeiro assento a quem joga no segundo.
-                if (p)
-                    ctx.arestaDoJogador(playerIndex, 'toque');
+                    ctx.playerEdge(playerIndex, 'toque');
+                }
             }
         }
         if (d.hideTips)
@@ -255,15 +231,15 @@ export function initTouchBindings(ctx) {
             return;
         }
         doTouch(a, true);
-        later(() => doTouch(a, false), START_TAP_MS); // ação momentânea: aperta e solta sozinho
+        later(() => doTouch(a, false), START_TAP_MS); // a momentary action: press and release by itself
     }
     function revealForTests() {
         const tc = ctx.$('#touch-controls');
         if (tc)
             tc.hidden = false;
     }
-    /** Direcional (analógico ou cruz): um só padrão — estado por direção, só despacha na MUDANÇA. Sem isso,
-     *  arrastar o polegar dentro do mesmo quadrante re-levantaria a borda a cada `pointermove`. */
+    /** The d-pad (stick or cross): one pattern — state per direction, dispatched only on a CHANGE. Without it, dragging
+     *  the thumb inside the same quadrant would raise the edge again on every `pointermove`. */
     function makeDirGate(onChange) {
         const state = { left: false, right: false, up: false, down: false };
         const set = (dir, on) => {
@@ -278,28 +254,28 @@ export function initTouchBindings(ctx) {
             reset: () => { ['left', 'right', 'up', 'down'].forEach((d) => set(d, false)); },
         };
     }
-    /* --- os .touch-btn do losango --- */
+    /* --- the diamond's .touch-btn buttons --- */
     function wireButtons(tc) {
         tc.querySelectorAll('.touch-btn').forEach((b) => {
-            const slot = 'b' + (b.dataset.btn || ''); // a função vem do touchMap (remapeável), não do data-act
+            const slot = 'b' + (b.dataset.btn || ''); // the function comes from the (remappable) touchMap, not from a data attribute
             const down = (e) => { e.preventDefault(); doTouch(ctx.getTouchMap()[slot], true); };
             const up = (e) => { e.preventDefault(); doTouch(ctx.getTouchMap()[slot], false); };
             b.addEventListener('pointerdown', down);
             b.addEventListener('pointerup', up);
-            b.addEventListener('pointerleave', up); // o dedo escorregou para fora: conta como soltar
+            b.addEventListener('pointerleave', up); // the finger slid off: counts as a release
             b.addEventListener('pointercancel', up);
-            b.addEventListener('contextmenu', (e) => e.preventDefault()); // segurar não abre menu do sistema
+            b.addEventListener('contextmenu', (e) => e.preventDefault()); // holding does not open the system menu
         });
     }
     /**
-     * Analógico e cruz compartilham TODO o ciclo de vida do ponteiro (captura, um dedo por vez, soltar/cancelar,
-     * perder a captura). O que muda é só a conta de direção e o retorno visual — por isso os dois entram aqui e
-     * a diferença vira dois callbacks.
+     * Stick and cross share the WHOLE pointer lifecycle (capture, one finger at a time, release/cancel, losing the
+     * capture). Only the direction arithmetic and the visual feedback differ — so both come in here and the difference
+     * becomes two callbacks.
      */
     function wirePointerPad(el, dirsAt, onMove, onReset, onDirVisual) {
         let pid = null;
         const gate = makeDirGate((dir, on) => {
-            doTouch(ctx.getTouchMap()[dir], on); // direção FÍSICA → função mapeada (a cruz também é remapeável)
+            doTouch(ctx.getTouchMap()[dir], on); // PHYSICAL direction → mapped function (the cross is remappable too)
             if (onDirVisual)
                 onDirVisual(dir, on);
         });
@@ -315,16 +291,16 @@ export function initTouchBindings(ctx) {
             e.preventDefault();
             const id = e.pointerId;
             pid = id;
-            // captura: o dedo pode sair do elemento sem que o gesto acabe (é o que faz um direcional ser usável)
+            // capture: the finger can leave the element without ending the gesture (it is what makes a d-pad usable)
             try {
                 el.setPointerCapture(id);
             }
-            catch { /* sem captura de ponteiro: o gesto ainda funciona por cima do elemento */ }
+            catch { /* no pointer capture: the gesture still works over the element */ }
             at(e.clientX, e.clientY);
         });
         el.addEventListener('pointermove', (e) => {
             if (pid !== e.pointerId)
-                return; // um dedo por vez: o segundo ponteiro é ignorado, não disputa
+                return; // one finger at a time: the second pointer is ignored, not contested
             e.preventDefault();
             at(e.clientX, e.clientY);
         });
@@ -332,36 +308,45 @@ export function initTouchBindings(ctx) {
             return; e.preventDefault(); reset(); };
         el.addEventListener('pointerup', end);
         el.addEventListener('pointercancel', end);
-        el.addEventListener('lostpointercapture', reset); // rede: perdeu a captura = solta tudo (nada fica preso)
+        el.addEventListener('lostpointercapture', reset); // a net: capture lost = release everything (nothing stays stuck)
         el.addEventListener('contextmenu', (e) => e.preventDefault());
     }
     function attach() {
         const tc = ctx.$('#touch-controls');
         if (!tc)
-            return; // sem os botões no documento, não há o que amarrar (guarda do IIFE original)
-        // alternância por modalidade: toque/clique MOSTRA; teclado/controle OCULTA (lá no keydown/gamepad).
+            return; // without the buttons in the document there is nothing to wire
+        // switching by modality: a touch/click SHOWS; the keyboard/pad HIDES (over there).
         if (wantsForcedTouch(ctx.getSearch()))
             ctx.showTouchControls();
         const onPointerDown = () => { if (ctx.attractOnInput())
-            return; ctx.showTouchControls(); }; // toque revela (e encerra a demo)
+            return; ctx.showTouchControls(); }; // touch reveals (and ends the demo)
         const onTouchStart = () => { ctx.showTouchControls(); };
         ctx.win.addEventListener('pointerdown', onPointerDown, true);
         ctx.win.addEventListener('touchstart', onTouchStart, { capture: true, passive: true });
+        rewire();
+    }
+    function rewire() {
+        const tc = ctx.$('#touch-controls');
+        if (!tc)
+            return;
         wireButtons(tc);
         const startBtn = ctx.$('#touch-start');
         if (startBtn)
             startBtn.addEventListener('click', pressStart);
-        // analógico: base (círculo grande) + manopla que desliza para a direção tocada
+        const selectBtn = ctx.$('#touch-select');
+        if (selectBtn)
+            selectBtn.addEventListener('click', () => ctx.openMenus?.());
+        // stick: a base (the large circle) + a knob that slides toward the touched direction
         const stick = ctx.$('#touch-stick');
         const knob = stick && stick.querySelector('.touch-knob');
         if (stick && knob) {
-            wirePointerPad(stick, (px, py, rect) => stickDirsAt(px, py, rect, ctx.getStickDeadPx()), // px/mm relidos a cada movimento
+            wirePointerPad(stick, (px, py, rect) => stickDirsAt(px, py, rect, ctx.getStickDeadPx()), // px/mm reread on every move
             (px, py, rect) => {
                 const o = stickKnobOffset(px, py, rect, ctx.getStickTravelPx());
                 knob.style.transform = `translate(${o.x}px,${o.y}px)`;
             }, () => { knob.style.transform = 'translate(0,0)'; }, null);
         }
-        // cruz (estilo alternativo ao analógico): superfície dividida por hit-test, com miolo neutro
+        // cross (the alternative to the stick): a surface split by hit-test, with a neutral core
         const cross = ctx.$('#touch-cross');
         if (cross) {
             const arms = {
@@ -373,5 +358,5 @@ export function initTouchBindings(ctx) {
             wirePointerPad(cross, crossDirsAt, null, null, (dir, on) => { arms[dir]?.classList.toggle('on', on); });
         }
     }
-    return { decide, doTouch, pressStart, revealForTests, attach };
+    return { decide, doTouch, pressStart, revealForTests, attach, rewire };
 }