@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/input/key-default.d.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The part of a key event's target this reads — an `Element` satisfies it; `window`/`document` have no `closest`. */
+export interface KeyTargetLike {
+    readonly isContentEditable?: boolean;
+    closest?(selector: string): unknown;
+}
+/** The keys a focused button answers natively: Enter presses it on the key's press, Space on its release. */
+export declare const BUTTON_ACTIVATION_KEYS: ReadonlySet<string>;
+/**
+ * Whether a key pressed with the focus on `target` is being typed into a field — input, textarea, select or contenteditable, in
+ * the game region or anywhere on the page. Then every key is the field's: Enter and every character.
+ *
+ * 📌 ASKED BY THE ENGINE'S SYSTEM KEYS TOO, and not only by the delivery. START and SELECT never reach play, so they never pass
+ * through `keyGoesToGame`: their own listeners (`boot/create-game`) ask this. 📏 Before they did, Enter typed into a text field
+ * opened the quick pause, and «half» typed into one paused on the `h` and opened the menus on the `f`.
+ */
+export declare function keyTypedIntoField(target: KeyTargetLike | null): boolean;
+/**
+ * Whether the key `code` presses the engine's own control that has the focus (`ownControls`, a selector): Space or Enter on it.
+ *
+ * 📌 ASKED BY THE QUICK PAUSE TOO, and not only by the delivery. `Enter` is `start`, and START in play opens the quick pause — so
+ * Enter on a focused ☰ paused instead of pressing ☰, while Space pressed it (📏 measured on the served quiz). A focused button is
+ * activated by Enter as well as Space; that press is the button's, and the pause does not take it.
+ */
+export declare function keyPressesOwnControl(code: string, target: KeyTargetLike | null, ownControls: string): boolean;
+/**
+ * Whether the key `code`, pressed with the focus on `target`, is play's to hear. `false`: it belongs to what has the focus — a
+ * field, or the engine's own control it activates (`ownControls`, a selector) — and keeps its default.
+ */
+export declare function keyGoesToGame(code: string, target: KeyTargetLike | null, ownControls: string): boolean;

package/dist-pkg/input/key-default.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/key-default — WHICH KEY THE GAME HEARS, AND WHICH KEEPS ITS BROWSER DEFAULT (ADR-0111 errata of 2026-09-26).
+//
+// The engine owns the keyboard (ADR-0111): it turns a key into a position and carries the position to the game. One key press
+// is one action, and that makes two rules, which are one rule seen from two sides:
+//   · A KEY THE GAME HEARD IS SPENT. The keyboard conductor cancels its default, or Space on a focused `<button>` was the game's
+//     `action2` AND the button's click on the release.
+//   · A KEY THAT WENT TO SOMETHING ELSE IS NOT ALSO PLAYED. It keeps its default, and the game does not hear it. That is what
+//     this module answers, before the engine delivers:
+//       · a key typed into an editable field (input, textarea, select, contenteditable): typing is the field's;
+//       · a key that ACTIVATES one of the engine's own focused controls (`ownControls`, the accessibility bar, in the tab order
+//         in play): Space and Enter press a focused button, and that press is the control's.
+//     📏 Both used to keep their default AND be delivered. On the served quiz, Space on ☰ opened the menus and answered a
+//     question; Space typed into a text field answered one too.
+//
+// 📌 ONLY THE ACTIVATION KEYS on the engine's control, and not every key: a focused button does nothing native with an arrow or
+// a letter, so an arrow pressed after Tab left the focus on ☰ is still the child moving in the game — held back, it would be
+// lost, and the game would stop answering until she clicked somewhere else.
+//
+// Not decided here: a key refused by an open menu, or consumed by the engine's menus, is the menus' (`input/virtual-controller`,
+// `ui/menu-nav`); a key mapped to no position was never the game's.
+//
+// Pure: it is told the key and where the focus was; it answers a decision. No document, no event.
+const EDITABLE = 'input, textarea, select';
+/** The keys a focused button answers natively: Enter presses it on the key's press, Space on its release. */
+export const BUTTON_ACTIVATION_KEYS = new Set(['Space', 'Enter', 'NumpadEnter']);
+/**
+ * Whether a key pressed with the focus on `target` is being typed into a field — input, textarea, select or contenteditable, in
+ * the game region or anywhere on the page. Then every key is the field's: Enter and every character.
+ *
+ * 📌 ASKED BY THE ENGINE'S SYSTEM KEYS TOO, and not only by the delivery. START and SELECT never reach play, so they never pass
+ * through `keyGoesToGame`: their own listeners (`boot/create-game`) ask this. 📏 Before they did, Enter typed into a text field
+ * opened the quick pause, and «half» typed into one paused on the `h` and opened the menus on the `f`.
+ */
+export function keyTypedIntoField(target) {
+    if (!target || typeof target.closest !== 'function')
+        return false;
+    return !!target.isContentEditable || !!target.closest(EDITABLE);
+}
+/**
+ * Whether the key `code` presses the engine's own control that has the focus (`ownControls`, a selector): Space or Enter on it.
+ *
+ * 📌 ASKED BY THE QUICK PAUSE TOO, and not only by the delivery. `Enter` is `start`, and START in play opens the quick pause — so
+ * Enter on a focused ☰ paused instead of pressing ☰, while Space pressed it (📏 measured on the served quiz). A focused button is
+ * activated by Enter as well as Space; that press is the button's, and the pause does not take it.
+ */
+export function keyPressesOwnControl(code, target, ownControls) {
+    if (!target || typeof target.closest !== 'function')
+        return false;
+    return BUTTON_ACTIVATION_KEYS.has(code) && !!target.closest(ownControls);
+}
+/**
+ * Whether the key `code`, pressed with the focus on `target`, is play's to hear. `false`: it belongs to what has the focus — a
+ * field, or the engine's own control it activates (`ownControls`, a selector) — and keeps its default.
+ */
+export function keyGoesToGame(code, target, ownControls) {
+    if (!target || typeof target.closest !== 'function')
+        return true; // no element had the focus: nothing else to go to
+    return !keyTypedIntoField(target) && !keyPressesOwnControl(code, target, ownControls);
+}

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

@@ -2,25 +2,21 @@
 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). */
-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 +28,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,22 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Store } from '../platform/storage.js';
 import type { KeyScheme } from '../core/entity.js';
-export type { KeyScheme } from '../core/entity.js';
 /**
- * O CONJUNTO DE ESQUEMAS de teclado — solo mais os de 2, 3 e 4 jogadores.
+ * 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'>;
+/**
+ * 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 +24,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;