@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -2,25 +2,25 @@
 import type { ControlledPlayer } from '../core/entity.js';
 import type { KeyScheme } from '../core/entity.js';
 import type { KBDefaults } from '../input/keyboard.js';
-/** action -> list of physical key codes (KeyboardEvent.code), e.g. {jump:['KeyJ','Space']}. Mirrors the shape
- *  ui/settings-controls.ts also defines locally (input/keyboard.ts's KeyScheme is not exported — each consumer
- *  keeps its own structural copy rather than reaching across layers for a type alias). */
+/** action -> list of physical key codes (KeyboardEvent.code), e.g. {action2:['KeyJ','Space']}. It lives in `core/entity`,
+ *  whose `ctrl: KeyScheme | null` makes it the owner — the same line was once written in six modules. Re-exported for
+ *  whoever already imported it from here. */
 export type { KeyScheme } from '../core/entity.js';
-/** input/keyboard.ts's KBDefaults shape ({solo,p2,p3,p4}) — the live `KB` value in game.js. */
-/** O `KBDefaults` de `input/keyboard`, que é o dono. O nome local sobrevive porque os consumidores o usam. */
+/** `input/keyboard`'s `KBDefaults` ({solo,p2,p3,p4}), which owns it. The local name survives because consumers use it. */
 export type KeyboardConfig = KBDefaults;
 /** Minimal player shape this module needs: only `ctrl` is read/written — derived from core/entity.
  *  `ControlledPlayer` rather than `Player` because this module runs after assignControls, so `ctrl` is no
  *  longer null. That was already assumed here; now it is stated. */
 export type KeyboardRuntimePlayer = Pick<ControlledPlayer, 'ctrl'>;
 export interface KeyboardRuntimeCtx {
-    /** The live keyboard config (game.js's `KB`), read fresh on every call — never cached. */
+    /** The live keyboard config, read fresh on every call — never cached. */
     getKB(): KeyboardConfig;
-    /** Current player count (core/state.ts's `numPlayers`, read live via game.js). */
+    /** The current player count, read live. */
     getNumPlayers(): number;
-    /** The live players array (core/state.ts's `players`, mutated in place — never reassigned). */
+    /** The live players array (mutated in place — never reassigned). */
     getPlayers(): KeyboardRuntimePlayer[];
 }
+/** The controls state as a value: player 1's `controls` + its per-action aliases + the flattened list of game keys. */
 export interface ControlsState {
     controls: KeyScheme;
     action2: readonly string[];
@@ -32,24 +32,22 @@ export interface ControlsState {
     gameKeys: string[];
 }
 export interface KeyboardRuntime {
-    /** The key scheme for player `playerIndex`, given the current KB config + player count (game.js's kbFor). */
+    /** The key scheme for player `playerIndex`, given the current config + player count. */
     kbFor(playerIndex: number): KeyScheme;
-    /** Which action (if any) `code` triggers FOR that player, given their scheme (game.js's actionOf). */
+    /** Which action (if any) `code` triggers FOR that player, given their scheme. */
     actionOf(code: string, playerIndex: number): string | null;
-    /** Which player (0-based) owns `code` among the active players; -1 if none (game.js's whichPlayer). */
+    /** Which player (0-based) owns `code` among the active players; -1 if none. */
     whichPlayer(code: string): number;
-    /** Propagates `kb` -> each active player's `p.ctrl`, mutated in place (game.js's assignControls). */
+    /** Propagates the config -> each active player's `p.ctrl`, mutated in place. */
     assignControls(): void;
-    /** Computes the P1-alias `controls` + `GAME_KEYS` (game.js's applyControls, minus the reassignment). */
+    /** Computes player 1's `controls` alias + the game keys. */
     computeControlsState(): ControlsState;
-    /** O estado ATUAL, memorizado. Antes eram oito `let` no game.js (`controls`, `KJUMP`..`KRUN`, `GAME_KEYS`)
-     *  copiados de `computeControlsState()` por um `applyControls()` que existia só para fazer a cópia. Eram
-     *  derivados de `KB` + `players`, guardados em variável — a forma de estado que mais apodrece, porque nada
-     *  obriga a cópia a acompanhar a origem. Aqui a memória fica com quem é dono da conta, e a invalidação é
-     *  explícita e única: `refreshControls()`. NÃO recalcula a cada leitura de propósito — recalcular mudaria
-     *  o comportamento (passaria a enxergar remapeamento que ainda não foi aplicado), e isto é refatoração. */
+    /** The CURRENT state, memoised. It was a set of copies kept in variables, derived from the config + players — the
+     *  kind of state that rots fastest, because nothing forces a copy to follow its source. Here the memo stays with
+     *  whoever owns the sum, and invalidating it is explicit and single: `refreshControls()`. It does NOT recompute on
+     *  every read, on purpose — that would change behaviour (it would see a remap not applied yet). */
     controlsState(): ControlsState;
-    /** Recalcula e memoriza. É o `applyControls()` do game.js, agora do lado de cá. */
+    /** Recomputes and memoises. */
     refreshControls(): ControlsState;
 }
 /** Which action does `code` trigger in this ONE scheme? Pure — no player/KB involved. */

package/dist-pkg/input/keyboard-runtime.js

@@ -1,17 +1,14 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // input/keyboard-runtime.ts — keyboard ROUTING at play time: which key belongs to which player, which action
-// it fires. Extracted from game.js (kbFor/actionOf/whichPlayer/assignControls/applyControls). Pure logic, DI
-// via initKeyboardRuntime(ctx): reads the live KB config (input/keyboard.ts owns load/save/reset) and the live
-// numPlayers/players (still in game.js) through injected getters — never imports game.js, never touches
-// `document`. KJUMP/KLEFT/.../GAME_KEYS come back as a plain VALUE object (computeControlsState) instead of
-// being reassigned here: imported bindings can't be reassigned from outside their own module, so the game.js
-// wrapper is the one that copies the returned fields onto its own `let`s (same trap `core/state.ts` documents
-// for `coins`/`players`).
+// it fires. Extracted from the monolith (kbFor/actionOf/whichPlayer/assignControls/applyControls). Pure logic, DI
+// via initKeyboardRuntime(ctx), which `boot/create-game` calls: reads the live KB config (input/keyboard.ts owns
+// load/save/reset) and the live player count and players through injected getters — never imports the composition
+// root, never touches `document`. The per-action aliases and GAME_KEYS come back as a plain VALUE object
+// (`ControlsState`) instead of exported `let`s, because imported bindings can't be reassigned from outside their own
+// module; `controlsState()` memoises it and `refreshControls()` is the one way to recompute it.
 import { ACTIONS } from '../core/actions.js';
-/** Result of the old `applyControls()` mutation, as a value: `controls` + its per-action aliases (game.js's
- *  KJUMP/KLEFT/KRIGHT/KUP/KDOWN/KRUN) + the flattened `GAME_KEYS` list. */
-/** A lista que uma posição SEM ALCANCE devolve. Congelada e partilhada: ninguém deve escrever nela. */
-const VAZIO = Object.freeze([]);
+/** The list a position WITH NO REACH returns. Frozen and shared: nobody may write to it. */
+const EMPTY = Object.freeze([]);
 // ---------------------------------------------------------------------------------------------
 // Pure logic (no ctx, no `document` — directly testable with plain KeyScheme fixtures)
 // ---------------------------------------------------------------------------------------------
@@ -19,10 +16,10 @@ const VAZIO = Object.freeze([]);
  *  (mirrors ui/settings-controls.ts's keyUsedByOther: a Map built over the scheme, not a re-scan per query). */
 function buildActionIndex(scheme) {
     const index = new Map();
-    // ⚠️ O LAÇO PASSOU A SER SOBRE `ACTIONS` E NÃO SOBRE AS CHAVES DO OBJETO (issue #118). São a mesma lista
-    // agora que o `KeyScheme` é fechado — mas percorrer `ACTIONS` diz QUAL é a lista, e um esquema que ganhe
-    // uma chave a mais por engano deixa de a ver. E o `?? []` é o que trata a AUSÊNCIA DECLARADA: um `null`
-    // não é um esquema partido, é um teclado que não alcança aquela posição.
+    // ⚠️ THE LOOP IS OVER `ACTIONS` AND NOT OVER THE OBJECT'S KEYS (issue #118). They are the same list now that
+    // `KeyScheme` is closed — but walking `ACTIONS` says WHICH list it is, and a scheme that gains an extra key by mistake
+    // no longer sees it. And `?? []` handles the DECLARED ABSENCE: a `null` is not a broken scheme, it is a keyboard that
+    // does not reach that position.
     for (const action of ACTIONS) {
         for (const code of scheme[action] ?? []) {
             if (!index.has(code))
@@ -73,18 +70,17 @@ export function initKeyboardRuntime(ctx) {
     }
     function computeControlsState() {
         const kb = ctx.getKB();
-        const controls = kb.solo; // alias do P1 — SEMPRE kb.solo, mesmo com numPlayers>1 (comportamento original; ver relato)
-        // Os apelidos são LISTAS, nunca `null`: quem os lê faz `.includes(code)` sem perguntar. Uma posição que o
-        // esquema não alcança vira lista vazia aqui — «não alcança» e «alcança com zero teclas» valem o mesmo
-        // para quem só pergunta se a tecla está lá.
+        const controls = kb.solo; // player 1's alias — ALWAYS kb.solo, even with more players (the original behaviour)
+        // The aliases are LISTS, never `null`: whoever reads them does `.includes(code)` without asking. A position the
+        // scheme does not reach becomes an empty list here — "does not reach" and "reaches with zero keys" are worth the
+        // same to whoever only asks whether the key is there.
         //
-        // ⚠️ E DEVOLVE A MESMA REFERÊNCIA, não uma cópia. A primeira versão fazia `[...]` e um caso reprovou por
-        // identidade — corretamente: o apelido é o alias do P1, e um teste que afirma «é o mesmo array» está a
-        // afirmar que ninguém interpôs uma cópia entre o esquema vivo e quem o lê. Copiar aqui não custaria nada
-        // hoje e passaria a custar no dia em que alguém mutasse a lista no lugar.
-        const lista = (a) => controls[a] ?? VAZIO;
-        const action2 = lista('action2'), left = lista('left'), right = lista('right');
-        const up = lista('up'), down = lista('down'), action1 = lista('action1');
+        // ⚠️ AND IT RETURNS THE SAME REFERENCE, not a copy. A case asserts "it is the same array", which is asserting that
+        // nobody put a copy between the live scheme and its reader. Copying would cost nothing today and would start costing
+        // the day someone mutated the list in place.
+        const list = (a) => controls[a] ?? EMPTY;
+        const action2 = list('action2'), left = list('left'), right = list('right');
+        const up = list('up'), down = list('down'), action1 = list('action1');
         const gameKeySet = new Set();
         ctx.getPlayers().forEach((_, i) => {
             const scheme = kbFor(i);
@@ -95,7 +91,7 @@ export function initKeyboardRuntime(ctx) {
         const gameKeys = gameKeySet.size ? [...gameKeySet] : [...action2, ...left, ...right, ...up, ...down];
         return { controls, action2, left, right, up, down, action1, gameKeys };
     }
-    let cache = null; // memória do estado derivado; só refreshControls a invalida
+    let cache = null; // the derived state's memo; only refreshControls invalidates it
     function controlsState() { return cache ?? (cache = computeControlsState()); }
     function refreshControls() { cache = computeControlsState(); return cache; }
     return { kbFor, actionOf, whichPlayer, assignControls, computeControlsState, controlsState, refreshControls };

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

@@ -1,17 +1,23 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Store } from '../platform/storage.js';
 import type { KeyScheme } from '../core/entity.js';
+/**
+ * What the key map is read and written through: the page's store (ADR-0232, issue #207). A PARAMETER of each function that
+ * touches it, not a module import — a test hands in its own, and two roots never write each other's map.
+ */
+export type KeyboardStore = Pick<Store, 'getJSON' | 'setJSON' | 'remove'>;
 export type { KeyScheme } from '../core/entity.js';
 /**
- * O CONJUNTO DE ESQUEMAS de teclado — solo mais os de 2, 3 e 4 jogadores.
+ * THE SET OF keyboard SCHEMES — solo plus those for 2, 3 and 4 players.
  *
- * Exportado desde 2026-08-26, e o motivo é que ele já era copiado: `input/keyboard-runtime` e
- * `ui/settings-controls` declaravam cada um o seu `KeyboardConfig`, e AMBOS diziam no comentário que
- * era "a forma do KBDefaults de input/keyboard". Sabiam que eram cópia e copiavam mesmo assim.
+ * Exported because it was already being copied: `input/keyboard-runtime` and `ui/settings-controls` each
+ * declared their own `KeyboardConfig`, and BOTH said in a comment it was "the shape of input/keyboard's
+ * KBDefaults". They knew they were a copy and copied anyway.
  *
- * A de `settings-controls` era `Record<string, unknown>` — pensada como opaca, para o módulo não
- * depender da forma. Mas em posição de PARÂMETRO isso se inverte: para aceitar `(next: KBDefaults)`,
- * o tipo declarado tem de ser SUBTIPO, não supertipo. A opacidade se preserva por disciplina — não
- * indexar o valor — e não por escrever um tipo mais largo (ADR-0039).
+ * The `settings-controls` one was `Record<string, unknown>` — meant as opaque, so the module would not depend on
+ * the shape. But in PARAMETER position that inverts: to accept `(next: KBDefaults)`, the declared type has to be
+ * a SUBTYPE, not a supertype. Opacity is kept by discipline — not indexing the value — and not by writing a wider
+ * type (ADR-0039).
  */
 export type KBDefaults = {
     solo: KeyScheme;
@@ -19,69 +25,69 @@ export type KBDefaults = {
     p3: KeyScheme[];
     p4: KeyScheme[];
 };
-export declare const KB_SCHEMES4: KeyScheme[];
 /**
- * ⚠️ 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 declare const KB_DEFAULTS: KBDefaults;
 /**
- * O PADRÃO QUE O JOGO QUER, por número de jogadores e por assento (ADR-0115). Parcial: o que ele não disser
- * fica como a fábrica da engine o deixou.
- */
-export type MapeamentoDoTeclado = (jogadores: number, assento: number) => Partial<KeyScheme> | null;
-/**
- * REGISTA O PADRÃO DO JOGO. Chamado uma vez pelo arranque (`boot/create-game`), a partir da declaração.
- *
- * 🔴 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.
- */
-export declare function registrarMapeamentoDoTeclado(f: MapeamentoDoTeclado | null): void;
-/**
- * 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».
+ * THE DEFAULT THE GAME WANTS, per player count and per seat (ADR-0115). Partial: whatever it does not say stays
+ * as the engine's factory left it.
  */
-export declare function fabricaComOJogo(): KBDefaults;
-export declare function loadKB(): KBDefaults;
-export declare function saveKB(kb: KBDefaults): void;
+export type KeyboardMapping = (players: number, seat: number) => Partial<KeyScheme> | null;
 /**
- * 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.
+ * THE FACTORY WITH THE GAME'S DEFAULT ON TOP — the **only** resolution, used by `loadKB` AND by the reset.
  *
- * 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.
+ * ⚠️ 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 declare let kb: KBDefaults;
-/** Lê o mapa persistido para dentro de `kb`. O boot chama uma vez; devolve o valor para quem quiser encadear. */
-export declare function initKB(): KBDefaults;
-/** 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 declare function setKB(next: KBDefaults): void;
+export declare function factoryWithGame(mapping: KeyboardMapping | null): KBDefaults;
+export declare function loadKB(store: KeyboardStore, mapping: KeyboardMapping | null): KBDefaults;
+export declare function saveKB(store: KeyboardStore, kb: KBDefaults): void;
+/** What one root's keyboard config is built from (ADR-0232 D4). Both required: see `createKeyboardConfig`. */
+export interface KeyboardConfigOptions {
+    /** Where the child's remapping is kept — the page's store, built by the root. */
+    readonly store: KeyboardStore;
+    /** The GAME's default, `null` for a game with no opinion. Read on every factory resolution, so a root that mounts
+     *  another cartridge can answer with the mounted one's. */
+    readonly mapping: KeyboardMapping | null;
+}
+/** ONE ROOT'S LIVE KEY MAP and the doors that manage it — what `Engine.keyboardConfig` is. */
+export interface KeyboardConfigApi {
+    /** THE LIVE KEY MAP (#50). Remapping one key MUTATES this object; `set` is the only way to replace it. */
+    kb(): KBDefaults;
+    /** Replaces the whole map. Only "restore defaults" needs this — reassigning by mistake would leave live references
+     *  pointing at the old map. */
+    set(next: KBDefaults): void;
+    /** Stores `conf` (the live map when omitted) in the store. */
+    save(conf?: KBDefaults): void;
+    /**
+     * "RESTORE DEFAULTS" — erases what the child stored and returns the GAME's default, not the engine's (ADR-0115).
+     * 🔴 Resetting to the engine's factory alone would silently erase the mapping the game chose. It does NOT replace
+     * the live map: the caller decides (`set`), as the controls panel does.
+     */
+    reset(): KBDefaults;
+    /** The engine's factory with this game's default on top — a fresh copy each call. */
+    factoryWithGame(): KBDefaults;
+    /** Reads the stored map into the live one and returns it. */
+    load(): KBDefaults;
+}
 /**
- * «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 declare function resetKB(): KBDefaults;
+export declare function createKeyboardConfig(opts: KeyboardConfigOptions): KeyboardConfigApi;

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; },
+    };
+}