@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/input/keyboard.js

@@ -1,109 +1,91 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/keyboard.ts — esquemas de teclado (config) + persistência. Módulo-folha (só depende de storage).
-// ⚠️ AS AÇÕES SÃO POSIÇÕES, NÃO VERBOS, desde 2026-09-06: `up`, `down`, `left`, `right` e `action1`..`action4`.
-// A linha anterior listava «run(corre/interage), jump, swap(troca poder), especial» — vocabulário de PLATAFORMA
-// dentro da engine, que é exatamente o que o ADR-0074 tirou daqui. Qual verbo mora em qual posição é do JOGO,
-// e o ADR-0086 §2 diz qual é para a plataforma. Esquemas por contagem de jogadores (solo/p2/p3/p4).
-// A INSTÂNCIA atual (KB) e o remap ficam no composition root — aqui só config/load/save/reset.
-import * as store from '../platform/storage.js';
-// ⚠️ A DECLARAÇÃO DOS ESQUEMAS MORA LÁ (ADR-0096), e este ficheiro passou a derivá-los em vez de os repetir
-// — é a união que a issue #118 pede. `default-bindings` é folha (só importa `core/actions`), então não há
-// ciclo: quem depende é o ficheiro de persistência, e não o contrário.
+// ⚠️ THE SCHEMES ARE DECLARED THERE (ADR-0096), and this file derives them instead of repeating them — the union
+// issue #118 asks for. `default-bindings` is a leaf (it imports only `core/actions`), so there is no cycle: the
+// dependant is the persistence file, not the other way round.
 import { KEYBOARD_SOLO, KEYBOARD_DUO } from './default-bindings.js';
 const CKEY = 'inclusionist.kbcontrols.v3';
 /**
- * AS SEIS POSIÇÕES QUE UM TECLADO PARTIDO NÃO ALCANÇA, declaradas como ausência (issue #118, decisão do Dev).
+ * THE SIX POSITIONS A SHARED KEYBOARD CANNOT REACH, declared as absence (issue #118, the Dev's decision).
  *
- * ⚠️ `null` AQUI É UMA AFIRMAÇÃO, e é o que torna o `KeyScheme` fechado útil em vez de burocrático: quando o
- * teclado é repartido por três ou quatro crianças, não há lugar físico para ombros, gatilhos, start e select
- * de cada uma — o bloco de cada jogador tem oito teclas e acabou. Inventar teclas para preencher seria dar a
- * cada criança um alcance que ela não tem, e o `ui/reach-notice` (#112) diria a coisa errada.
+ * ⚠️ `null` HERE IS A STATEMENT, and it is what makes the closed `KeyScheme` useful instead of bureaucratic: when
+ * the keyboard is split among three or four children, there is no physical room for each one's shoulders,
+ * triggers, start and select — each player's block has eight keys and that is it. Inventing keys to fill them in
+ * would give each child a reach they do not have, and `ui/reach-notice` (#112) would say the wrong thing.
  *
- * O que `null` compra: o aviso de alcance pode dizer, ANTES de a criança começar, quais das ações do jogo o
- * controlo dela não alcança — e o jogo pode decidir não usar essas posições no modo de quatro.
+ * What `null` buys: the reach notice can say, BEFORE the child starts, which of the game's actions their control
+ * does not reach — and the game can decide not to use those positions in four-player mode.
  */
-const SEM_ALCANCE_NO_TECLADO_PARTIDO = Object.freeze({
+const UNREACHABLE_ON_A_SHARED_KEYBOARD = Object.freeze({
     leftShoulder: null, leftTrigger: null, rightShoulder: null, rightTrigger: null, start: null, select: null,
 });
-// 4 esquemas base p/ 3–4 jogadores (modos 3 e 4 têm esquemas SEPARADOS, p3 e p4, editáveis por jogador)
-export const KB_SCHEMES4 = [
-    { left: ['KeyA'], right: ['KeyD'], up: ['KeyW'], down: ['KeyS'], action1: ['KeyZ'], action2: ['KeyX'], action4: ['KeyC'], action3: ['KeyV'], ...SEM_ALCANCE_NO_TECLADO_PARTIDO },
-    { left: ['KeyJ'], right: ['KeyL'], up: ['KeyI'], down: ['KeyK'], action1: ['KeyM'], action2: ['Comma'], action4: ['Period'], action3: ['Semicolon', 'Slash'], ...SEM_ALCANCE_NO_TECLADO_PARTIDO },
-    { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Home'], action2: ['End'], action4: ['PageUp'], action3: ['PageDown'], ...SEM_ALCANCE_NO_TECLADO_PARTIDO },
-    { left: ['Numpad4'], right: ['Numpad6'], up: ['Numpad8'], down: ['Numpad5'], action1: ['Numpad2'], action2: ['Numpad0'], action4: ['Numpad3'], action3: ['NumpadDecimal'], ...SEM_ALCANCE_NO_TECLADO_PARTIDO },
+// 4 base schemes for 3–4 players (modes 3 and 4 have SEPARATE schemes, p3 and p4, editable per player)
+const KB_SCHEMES4 = [
+    { left: ['KeyA'], right: ['KeyD'], up: ['KeyW'], down: ['KeyS'], action1: ['KeyZ'], action2: ['KeyX'], action4: ['KeyC'], action3: ['KeyV'], ...UNREACHABLE_ON_A_SHARED_KEYBOARD },
+    { left: ['KeyJ'], right: ['KeyL'], up: ['KeyI'], down: ['KeyK'], action1: ['KeyM'], action2: ['Comma'], action4: ['Period'], action3: ['Semicolon', 'Slash'], ...UNREACHABLE_ON_A_SHARED_KEYBOARD },
+    { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Home'], action2: ['End'], action4: ['PageUp'], action3: ['PageDown'], ...UNREACHABLE_ON_A_SHARED_KEYBOARD },
+    { left: ['Numpad4'], right: ['Numpad6'], up: ['Numpad8'], down: ['Numpad5'], action1: ['Numpad2'], action2: ['Numpad0'], action4: ['Numpad3'], action3: ['NumpadDecimal'], ...UNREACHABLE_ON_A_SHARED_KEYBOARD },
 ];
 /**
- * Cópia PROFUNDA e MUTÁVEL de uma tabela declarada. O remapeamento escreve dentro do esquema vivo, então ele
- * não pode partilhar objeto com a tabela de `input/default-bindings`, que é congelada e é a declaração.
+ * A DEEP and MUTABLE copy of a declared table. Remapping writes into the live scheme, so it cannot share an
+ * object with the `input/default-bindings` table, which is frozen and is the declaration.
  */
-const vivo = (t) => JSON.parse(JSON.stringify(t));
+const mutableCopy = (t) => JSON.parse(JSON.stringify(t));
 /**
- * ⚠️ AS DUAS TABELAS DE TECLADO PASSARAM A SER UMA (issue #118). O solo e a dupla já não são escritos aqui:
- * são CÓPIAS VIVAS do que `input/default-bindings` declara, que é onde o ADR-0096 pôs a decisão.
+ * ⚠️ THE TWO KEYBOARD TABLES BECAME ONE (issue #118). Solo and duo are no longer written here: they are LIVE
+ * COPIES of what `input/default-bindings` declares, which is where ADR-0096 put the decision.
  *
- * Antes eram duas listas paralelas com oito posições cada, e as oito «coincidiam» — menos uma. A `Space` do
- * jogador 1 em dupla estava numa e não na outra, e o custo era concreto: `ui/webcam.ts` sintetiza `Space`
- * para «olhar para cima = pular», então entrar um segundo jogador tirava o PULO de quem joga com os olhos e
- * deixava o andar. Nada errava em voz alta. Derivar em vez de repetir torna essa divergência impossível de
- * voltar a existir, em vez de a apanhar depois de acontecer.
+ * They used to be two parallel lists of eight positions each, and all eight "matched" — but one. Player 1's
+ * `Space` in duo was in one list and not the other, and the cost was concrete: the webcam control of the time
+ * synthesised `Space` for "look up = jump", so a second player joining took JUMP away from whoever played with
+ * their eyes and left walking. Nothing failed out loud. Deriving instead of repeating makes that divergence
+ * impossible to come back, instead of catching it after it happens.
  */
 export const KB_DEFAULTS = {
-    solo: vivo(KEYBOARD_SOLO),
-    p2: KEYBOARD_DUO.map(vivo),
-    p3: KB_SCHEMES4.slice(0, 3).map(vivo), // modo 3 jogadores (independente do 4)
-    p4: KB_SCHEMES4.map(vivo), // modo 4 jogadores
+    solo: mutableCopy(KEYBOARD_SOLO),
+    p2: KEYBOARD_DUO.map(mutableCopy),
+    p3: KB_SCHEMES4.slice(0, 3).map(mutableCopy), // 3-player mode (independent of 4)
+    p4: KB_SCHEMES4.map(mutableCopy), // 4-player mode
 };
-// dado salvo (parcial): sobrepõe os defaults; p34 é o formato ANTIGO (migra p/ p3+p4).
-// A FORMA vem de `vocabulary-migration`, que é quem a traduz — declarar aqui outra vez seria a
-// cópia que o `core/entity` passou o mês a eliminar.
-import { migrarSalvo } from './vocabulary-migration.js';
-let mapeamentoDoJogo = null;
+// saved data (partial): it overlays the defaults; p34 is the OLD format (migrates to p3+p4).
+// The SHAPE comes from `vocabulary-migration`, which is what translates it — declaring it here again would be
+// the copy `core/entity` spent a month removing.
+import { migrateSaved } from './vocabulary-migration.js';
 /**
- * REGISTA O PADRÃO DO JOGO. Chamado uma vez pelo arranque (`boot/create-game`), a partir da declaração.
+ * THE FACTORY WITH THE GAME'S DEFAULT ON TOP — the **only** resolution, used by `loadKB` AND by the reset.
  *
- * 🔴 REGISTO E NÃO PARÂMETRO, e a razão é um defeito medido em vez de uma preferência. Há DOIS sítios que
- * materializam padrões — `loadKB` e `resetKB` — e o segundo é chamado pelo painel de controles, que não tem a
- * declaração do jogo à mão. Um parâmetro que o painel não passasse faria «restaurar padrões» devolver o mapa
- * da ENGINE por cima do mapa do JOGO: a criança carrega no botão esperando voltar ao que o jogo lhe deu, e
- * volta para outra coisa — num jogo cujo autor escolheu o layout por uma razão de acessibilidade, ela perde
- * essa razão e nada o diz.
- *
- * 📌 É a mesma forma que o `kb` deste ficheiro já tem, e pela mesma justificação: o dono é evidente, e as
- * funções que o gerem vivem todas aqui.
+ * ⚠️ One function, and that is the whole point: while there were two copies of `JSON.parse(JSON.stringify(...))`,
+ * the reset's did not know the game, and the difference only showed when a child pressed "restore".
+ * 📌 The mapping is a PARAMETER, `null` for a game with no opinion (ADR-0232 D4): as a module registration a second
+ * root would overwrite the first root's (D2b erratum). What once justified the registration — the controls panel
+ * resetting without the game's declaration at hand — is answered by `createKeyboardConfig`, which receives the
+ * mapping once and hands the panel a reset that already knows it.
  */
-export function registrarMapeamentoDoTeclado(f) { mapeamentoDoJogo = f; }
-/**
- * A FÁBRICA COM O PADRÃO DO JOGO POR CIMA — a **única** resolução, usada pelo `loadKB` E pelo `resetKB`.
- *
- * ⚠️ Uma função só, e é o ponto inteiro: enquanto eram duas cópias do `JSON.parse(JSON.stringify(...))`, a do
- * `resetKB` não conhecia o jogo e a diferença só aparecia quando uma criança carregava em «restaurar».
- */
-export function fabricaComOJogo() {
+export function factoryWithGame(mapping) {
     const d = JSON.parse(JSON.stringify(KB_DEFAULTS));
-    if (!mapeamentoDoJogo)
+    if (!mapping)
         return d;
-    const aplicar = (alvo, jogadores, assento) => {
-        const parcial = mapeamentoDoJogo(jogadores, assento);
-        if (parcial)
-            Object.assign(alvo, parcial);
+    const overlayGameMapping = (target, players, seat) => {
+        const changes = mapping(players, seat);
+        if (changes)
+            Object.assign(target, changes);
     };
-    aplicar(d.solo, 1, 0);
-    d.p2.forEach((esq, i) => aplicar(esq, 2, i));
-    d.p3.forEach((esq, i) => aplicar(esq, 3, i));
-    d.p4.forEach((esq, i) => aplicar(esq, 4, i));
+    overlayGameMapping(d.solo, 1, 0);
+    d.p2.forEach((seatScheme, i) => overlayGameMapping(seatScheme, 2, i));
+    d.p3.forEach((seatScheme, i) => overlayGameMapping(seatScheme, 3, i));
+    d.p4.forEach((seatScheme, i) => overlayGameMapping(seatScheme, 4, i));
     return d;
 }
-// carrega os esquemas salvos SOBRE os defaults (com migração do dado antigo p34 → p3+p4)
-export function loadKB() {
-    // ⚠️ A PRECEDÊNCIA É ESTA E ESTÁ ESCRITA UMA VEZ: fábrica da engine → padrão do JOGO → remapeamento da
-    // CRIANÇA. O que a criança gravou vem sempre por último, porque é a única das três que ela escolheu.
-    const d = fabricaComOJogo();
-    // ⚠️ O DADO SALVO ATRAVESSA O TRADUTOR ANTES DE TOCAR NOS PADRÕES. Sem esta linha, um esquema gravado com
-    // as chaves antigas (`run`, `jump`, `swap`, `especial`) seria fundido sobre defaults que já usam
-    // `action1`..`action4`: o objeto ficaria com AS DUAS famílias de chaves, os transportes leriam só as novas,
-    // e o remapeamento da criança viraria dado morto no navegador dela. Nada erraria em voz alta — as teclas
-    // dela simplesmente parariam de responder. Ver `input/vocabulary-migration.ts`.
-    const s = migrarSalvo(store.getJSON(CKEY, null));
+// loads the saved schemes OVER the defaults (migrating the old p34 data → p3+p4)
+export function loadKB(store, mapping) {
+    // ⚠️ THE PRECEDENCE IS THIS AND IT IS WRITTEN ONCE: the engine's factory → the GAME's default → the CHILD's
+    // remapping. What the child saved always comes last, because it is the only one of the three they chose.
+    const d = factoryWithGame(mapping);
+    // ⚠️ THE SAVED DATA GOES THROUGH THE TRANSLATOR BEFORE IT TOUCHES THE DEFAULTS. Without this line, a scheme
+    // saved with the old keys (`run`, `jump`, `swap`, `especial`) would be merged over defaults that already use
+    // `action1`..`action4`: the object would carry BOTH families of keys, the transports would read only the new
+    // ones, and the child's remapping would become dead data in their browser. Nothing would fail out loud —
+    // their keys would simply stop responding. See `input/vocabulary-migration.ts`.
+    const s = migrateSaved(store.getJSON(CKEY, null));
     if (s) {
         if (s.solo)
             Object.assign(d.solo, s.solo);
@@ -121,30 +103,26 @@ export function loadKB() {
     }
     return d;
 }
-export function saveKB(kb) { store.setJSON(CKEY, kb); }
-/**
- * O MAPA DE TECLAS VIVO. Migrado do composition root (#50): era um `let KB` do main.js com um envoltório
- * `setKB: (k) => { KB = k; }` fabricado à mão para o painel de controles reatribuí-lo.
- *
- * Mora AQUI, e não em core/state como os outros migrados, porque o dono é evidente: `loadKB`, `saveKB` e
- * `resetKB` já viviam neste arquivo. Separar o valor das três funções que o gerenciam seria mover o problema
- * de lugar em vez de resolvê-lo.
- *
- * NASCE COM OS PADRÕES E NÃO LÊ DISCO NO IMPORT. `initKB()` é quem lê, chamado uma vez pelo boot. A regra vale
- * para todo módulo do projeto, e aqui ela tem um custo concreto se for quebrada: um teste que importe qualquer
- * coisa deste arquivo passaria a depender do localStorage do ambiente, e um mapa de teclas herdado de outro
- * caso é uma falha que aparece longe da causa.
- */
-export let kb = JSON.parse(JSON.stringify(KB_DEFAULTS));
-/** Lê o mapa persistido para dentro de `kb`. O boot chama uma vez; devolve o valor para quem quiser encadear. */
-export function initKB() { kb = loadKB(); return kb; }
-/** Troca o mapa inteiro. Só o "restaurar padrões" do painel de controles precisa disto — remapear uma tecla
- *  MUTA o objeto, e reatribuir por engano faria as referências vivas apontarem para o mapa antigo. */
-export function setKB(next) { kb = next; }
+export function saveKB(store, kb) { store.setJSON(CKEY, kb); }
 /**
- * «RESTAURAR PADRÕES» — e o padrão para onde ela volta é o DO JOGO, não o da engine (ADR-0115).
+ * BUILDS ONE ROOT'S KEYBOARD CONFIG (ADR-0232 D4). The mapping is a construction parameter and not a registration: a
+ * registration is module state a second root overwrites (D2b erratum), and the reset this object hands out already knows
+ * the game, which is what the registration existed to guarantee.
  *
- * 🔴 Esta linha era `JSON.parse(JSON.stringify(KB_DEFAULTS))`, e com o campo do jogo a existir isso passaria
- * a apagar em silêncio o mapeamento que o jogo escolheu. A criança espera voltar ao que o jogo lhe deu.
+ * ⚠️ IT DOES NOT READ THE STORE WHEN BUILT: the live map is born from the game's factory and `load()` is what reads, called
+ * once by the root. A test that builds one inherits nothing from any storage.
  */
-export function resetKB() { store.remove(CKEY); return fabricaComOJogo(); }
+export function createKeyboardConfig(opts) {
+    const { store, mapping } = opts;
+    // born as a COPY of the engine's defaults — a reference would let a remap write into `KB_DEFAULTS`, and the reset
+    // would restore what the child just changed
+    let kb = JSON.parse(JSON.stringify(KB_DEFAULTS));
+    return {
+        kb: () => kb,
+        set(next) { kb = next; },
+        save(conf = kb) { saveKB(store, conf); },
+        reset() { store.remove(CKEY); return factoryWithGame(mapping); },
+        factoryWithGame: () => factoryWithGame(mapping),
+        load() { kb = loadKB(store, mapping); return kb; },
+    };
+}