@the-inclusionist/engine 7.0.1 → 8.0.0-rc.2

package/dist-pkg/input/gamepad.js

@@ -10,7 +10,17 @@ import { t } from '../core/i18n.js';
 import { EDGE_BY_ACTION, edgeAllowed } from './edges.js';
 import { migrarMapaDeControle } from './vocabulary-migration.js';
 import { GAMEPAD_STANDARD } from './default-bindings.js';
+import { tabelaDoPad } from './pad-defaults.js';
 import { padCur, padPrevAct, padPrevStart, PAD_DEAD } from './state.js';
+// ⚠️ O `oneButton` ENTRA POR IMPORT, e não pelo `ctx` — ao contrário de `input/keydown`, que o recebe por
+// getter. A diferença não é de gosto: o `keydown` foi extraído quando o `oneButton` era um `let` do
+// `game.js`, e a regra da casa manda o que o JOGO reatribui entrar por getter. Hoje ele é `core/state`,
+// ou seja da ENGINE — e um getter obrigaria cada consumidor a lembrar-se de o passar.
+//
+// ⚠️ E ESQUECER É EXATAMENTE O DEFEITO QUE ISTO CONSERTA (issue #120). Um campo opcional no ctx faria a
+// acomodação existir só nos jogos onde alguém se lembrou dela, que é o argumento M3 do ADR-0077 com outro
+// substantivo. Binding vivo de `core/state`: não há por onde falhar.
+import * as estadoDoJogo from '../core/state.js';
 import * as store from '../platform/storage.js';
 function bindingAt(map, key) {
     const v = map[key];
@@ -63,7 +73,7 @@ export function bindActive(gp, bd) {
 /** Ações do frame para este gamepad. `custom` = mapa salvo pelo wizard para este `gp.id` (null/`_skip` = usa o
  *  mapa PADRÃO da Gamepad API "standard": 0=pulo · 1=especial · 2/5/7=correr · 3=troca · 9=START). Direções
  *  custom caem de volta em stdDirs quando o binding do usuário não está ativo (D-pad/stick continuam vivos). */
-export function padActions(gp, custom) {
+export function padActions(gp, custom, tabela = GAMEPAD_STANDARD) {
     if (custom && !custom._skip) {
         const A = (k) => bindActive(gp, bindingAt(custom, k));
         const sd = stdDirs(gp);
@@ -82,7 +92,12 @@ export function padActions(gp, custom) {
     // correr, enquanto a tabela declara R1 como `rightShoulder` e R2 como `rightTrigger`. O ADR-0086 registrou
     // esta mudança como o asterisco do seu «zero movimento»: nenhum VERBO muda de botão, mas `run` perde dois
     // dos seus três. Quem usava R1 para correr sente — e é o preço de os quatro ombros existirem.
-    const B = GAMEPAD_STANDARD;
+    // 📌 A TABELA CHEGA POR PARÂMETRO desde o ADR-0115: é a fábrica da engine COM o padrão deste jogo por cima,
+    // resolvida em `input/pad-defaults`. O padrão da assinatura é o da engine, então quem chamava com dois
+    // argumentos continua a ler exactamente o que lia.
+    // ⚠️ E ela só decide neste ramo, que é o certo: o ramo de cima é o mapa que a CRIANÇA gravou no assistente,
+    // e o padrão de um jogo não se sobrepõe a uma escolha dela.
+    const B = tabela;
     const at = (a) => { const i = B[a]; return typeof i === 'number' ? b(i) : false; };
     return {
         left: sd.left, right: sd.right, up: sd.up, down: sd.down,
@@ -117,6 +132,56 @@ export function padActions(gp, custom) {
  * posição não tem o que mapear nela — e perguntar produziria um passo mudo, ou pior, um passo a dizer
  * `action7` em voz alta.
  */
+/**
+ * AS POSIÇÕES QUE O MODO DE UM BOTÃO NÃO CORTA. Pausar é a SAÍDA, não uma jogada.
+ *
+ * ⚠️ Cortar o START prenderia a criança dentro da partida — é o mesmo raciocínio que põe «a saída
+ * primeiro» no ADR-0044 e que fez a armadilha de foco existir no ADR-0090. Uma acomodação que tranca não
+ * é acomodação. Os derivados (`_start`, `_pause`) também passam: eles descrevem o que a raiz faz com
+ * estas duas posições, não uma terceira.
+ */
+const FORA_DO_CORTE = new Set(['start', 'select', '_start', '_pause']);
+/**
+ * O MODO DE UM BOTÃO, APLICADO AO CONTROLE — a metade que faltava da empatia motora (issue #120).
+ *
+ * ⚠️ ELE VALIA SÓ NO TECLADO. `input/keydown.ts:407` solta todas as outras teclas de jogo quando uma nova
+ * chega com o modo ligado; `pollPads` não tinha equivalente nenhum, e `grep oneButton` neste ficheiro
+ * devolvia zero. Uma criança que ligasse o modo e tivesse um controle na mão **não estava no modo** — sem
+ * erro, sem aviso, sem sintoma, porque as definições continuavam a dizer que estava ligado.
+ *
+ * ⚠️ AS DIREÇÕES CONTAM, e é isso que torna a regra fiel ao teclado: lá, `isGameKeyCode` inclui as teclas
+ * de `p.ctrl`, que são as quatro direções — andar e pular não coexistem. Um filtro que poupasse as
+ * direções seria mais confortável e estaria a simular outra deficiência.
+ *
+ * ⚠️ E A ESCOLHA DE QUEM SOBREVIVE É DIFERENTE DA DO TECLADO, POR NECESSIDADE. No teclado a chegada nova
+ * ganha, porque HÁ uma chegada: o evento diz qual é. Um controle é lido por SONDAGEM — o que chega é um
+ * retrato, sem ordem. Então mantém-se a que já valia, e só quando ela solta é que a próxima assume. É o
+ * que impede o botão de correr de ser cortado porque o polegar encostou noutro, e é a mesma leitura de
+ * «segurar» que o ADR-0077 dá.
+ *
+ * A POLÍTICA é a mesma do `keydown`; a IMPLEMENTAÇÃO não pode ser partilhada hoje porque as formas do
+ * estado diferem — lá é um `Set` de códigos de tecla, aqui é um retrato de booleanos por posição. Unificar
+ * as duas é trabalho à parte, e escrevê-lo aqui é a alternativa a fingir que não há duas.
+ */
+export function umBotaoPorVez(
+// ⚠️ O ANTERIOR É TIPADO PELO QUE ESTA FUNÇÃO LÊ, e não por `PadActions`: o `padPrevAct[gi]` do laço é
+// `PadState`, mais frouxo, e exigir a forma completa obrigaria o chamador a um molde que não descreve o
+// que se passa aqui — só se pergunta «esta chave estava em baixo?».
+anterior, atual, ligado) {
+    if (!ligado)
+        return atual;
+    const cortaveis = Object.keys(atual).filter((k) => !FORA_DO_CORTE.has(k));
+    const ativas = cortaveis.filter((k) => atual[k] === true);
+    if (ativas.length <= 1)
+        return atual;
+    // A que já valia tem prioridade; sem nenhuma, a primeira do retrato assume.
+    const mantida = ativas.find((k) => anterior[k] === true) ?? ativas[0];
+    const saida = { ...atual };
+    for (const k of ativas)
+        if (k !== mantida)
+            saida[k] = false;
+    return saida;
+}
 export const PADWIZ_ORDER = [
     // Direções primeiro: são o que a criança encontra sem pensar, e acertar as quatro dá confiança para as
     // outras dez.
@@ -161,13 +226,17 @@ export function initGamepad(ctx) {
         }
         return _padMaps.get(id) ?? null;
     }
-    function actionsFor(gp) { return padActions(gp, padMapFor(gp.id)); }
+    function actionsFor(gp, tabela) { return padActions(gp, padMapFor(gp.id), tabela); }
     // ----- wizard: anúncio + demo animada (DOM-facing, thin) -----
-    function wizSay(t) {
+    // ⚠️ O PARÂMETRO CHAMAVA-SE `t`, E ERA ELE QUE FECHAVA A PORTA. Dentro desta função o `t` do
+    // `core/i18n` estava sombreado, então traduzir uma frase aqui era impossível sem primeiro reparar no
+    // sombreamento — e não há erro nenhum a apontá-lo. Foi assim que cinco frases em português cru ficaram a
+    // falar dentro do motor (#123): não por decisão, por um nome.
+    function wizSay(frase) {
         const el = ctx.$('#padwiz-prompt');
         if (el)
-            el.textContent = t;
-        ctx.srSay(t);
+            el.textContent = frase;
+        ctx.srSay(frase);
     }
     function wizDemo(k) {
         const d = ctx.$('#padwiz-demo');
@@ -224,11 +293,12 @@ export function initGamepad(ctx) {
             return; // fechou ao avançar
         const acao = PADWIZ_ORDER[padWiz.step];
         const rotulo = ctx.rotuloDaAcao(acao);
-        wizSay((padWiz.step + 1) + ' de ' + PADWIZ_ORDER.length + ' — aperte: ' + rotulo);
+        wizSay(t('pad.wiz.step', { n: padWiz.step + 1, total: PADWIZ_ORDER.length, acao: rotulo }));
         wizDemo(acao); // demonstração animada do que a ação FAZ
         const pr = ctx.$('#padwiz-progress');
+        // O travessão da lista vazia fica cru de propósito: é pontuação, não idioma.
         if (pr)
-            pr.textContent = 'Mapeados: ' + (Object.keys(padWiz.map).join(' · ') || '—');
+            pr.textContent = t('pad.wiz.mapped', { lista: Object.keys(padWiz.map).join(' · ') || '—' });
     }
     function wizBind(bd) {
         if (!padWiz)
@@ -246,7 +316,7 @@ export function initGamepad(ctx) {
         ov.hidden = false;
         ctx.frontOverlay(ov);
         padWiz = { gi: -1, id: '', step: -1, base: null, map: {}, release: false, baseWait: false, axTrack: null, timer: null };
-        wizSay('Aperte QUALQUER botão no controle que deseja mapear.');
+        wizSay(t('pad.wiz.pressAny'));
         wizDemo(null);
         const pr = ctx.$('#padwiz-progress');
         if (pr)
@@ -261,7 +331,7 @@ export function initGamepad(ctx) {
         ov.hidden = false;
         ctx.frontOverlay(ov);
         padWiz = { gi: gp.index, id: gp.id, step: -1, base: null, map: {}, release: false, baseWait: true, axTrack: null, timer: null };
-        wizSay('Controle novo detectado: ' + gp.id + '. O jogo pausou para você configurá-lo. SOLTE tudo para começar.');
+        wizSay(t('pad.wiz.detected', { id: gp.id }));
         wizDemo(null);
         const pr = ctx.$('#padwiz-progress');
         if (pr)
@@ -316,7 +386,7 @@ export function initGamepad(ctx) {
                     padWiz.gi = gp.index;
                     padWiz.id = gp.id;
                     padWiz.baseWait = true;
-                    wizSay('Controle: ' + gp.id + '. Agora SOLTE tudo.');
+                    wizSay(t('pad.wiz.releaseAll', { id: gp.id }));
                     break;
                 }
             }
@@ -405,8 +475,18 @@ export function initGamepad(ctx) {
                 openPadWizFor(gp);
                 return;
             }
-            const cur = actionsFor(gp);
             const prev = padPrevAct[gi] || {};
+            // ⚠️ O ASSENTO SUBIU PARA AQUI, e a razão é o ADR-0115: a tabela de botões deste jogo é declarada POR
+            // ASSENTO, e ela é lida dentro do `actionsFor`. Enquanto o `owner` só se resolvia lá em baixo, por ramo,
+            // a leitura acontecia antes de se saber de quem era o controle — e um padrão por assento chegava tarde.
+            // 📌 Os ramos abaixo passaram a usar esta constante em vez de recalcularem a mesma linha três vezes.
+            const players = ctx.getPlayers();
+            const owner = players.findIndex((p) => p.pad === gi);
+            // ⚠️ E O CONTROLE AINDA NÃO ATRIBUÍDO (`owner < 0`) LÊ O ASSENTO 0, e não «nenhum»: ele está a produzir
+            // arestas na tela do título, e um mapa vazio ali deixaria a criança sem como escolher o próprio jogo.
+            // A EMPATIA MOTORA APLICADA AO CONTROLE (issue #120). Sem esta linha, uma criança com o modo de
+            // um botão ligado e um pad na mão NÃO ESTAVA no modo — e nada em lado nenhum o dizia.
+            const cur = umBotaoPorVez(prev, actionsFor(gp, tabelaDoPad(ctx.getNumPlayers(), owner < 0 ? 0 : owner)), estadoDoJogo.oneButton);
             if (ctx.isTouchMode() && (cur.left || cur.right || cur.up || cur.down || cur.action2 || cur.action1 || cur.action4 || cur.action3 || cur._start)) {
                 ctx.hideTouchControls(); // botão físico usado -> some o gamepad virtual (mesma regra do teclado)
             }
@@ -429,11 +509,9 @@ export function initGamepad(ctx) {
             // de propósito: numa cena que este módulo não conheça (um mapa, uma tela de resultados), o controle
             // deve navegar como no título — que é o comportamento seguro — em vez de não fazer nada.
             const rodando = ctx.mundoRodando(), pausado = ctx.menuDePausa();
-            const players = ctx.getPlayers();
             if (!rodando && !pausado) {
                 const k = { yes: edge('action2') || startEdge, no: edge('action3'), up: edge('up'), down: edge('down'), left: edge('left'), right: edge('right') };
                 const any = k.yes || k.no || k.up || k.down || k.left || k.right;
-                const owner = players.findIndex((p) => p.pad === gi);
                 if (ctx.getNumPlayers() > 1 && owner > 0) {
                     if (any)
                         ctx.srSay(t('sr.title.waitP1'));
@@ -444,7 +522,6 @@ export function initGamepad(ctx) {
                 continue;
             }
             if (pausado) {
-                const owner = players.findIndex((p) => p.pad === gi);
                 const pi = owner < 0 ? 0 : owner;
                 if (pauseEdge) {
                     ctx.retomar();
@@ -464,7 +541,6 @@ export function initGamepad(ctx) {
                 continue;
             }
             if (rodando) {
-                const owner = players.findIndex((p) => p.pad === gi);
                 // ===================== O MODO `accessibility` (ADR-0044, item 7) =====================
                 // Com o jogo ANDANDO, o direcional deste jogador dirige a BARRA RÁPIDA e não o personagem. Vem antes
                 // de tudo o que é de jogo, porque enquanto o modo está ligado nada mais deste controle é de jogo.
@@ -519,10 +595,21 @@ export function initGamepad(ctx) {
                     }
                     // A tabela e a guarda do Fácil vêm de input/edges.ts, as MESMAS que keydown e touch usam. Antes eram
                     // seis `if` à mão aqui, seis lá e seis no toque — e o do toque tinha esquecido o `!p.easy`.
+                    let algumaAresta = false;
                     for (const [act, flag] of EDGE_BY_ACTION) {
+                        if (edge(act))
+                            algumaAresta = true;
                         if (edgeAllowed(act, p.easy) && edge(act))
                             p[flag] = true;
                     }
+                    // 📌 A ARESTA DO CONTROLE, e ela conta MESMO QUANDO O FÁCIL A FILTRA (ADR-0113 cláusula 4): a
+                    // criança carregou no botão — que a regra do Modo Fácil não levante a bandeira do jogo não muda
+                    // o facto de o aparelho em uso ser este. Ler a mesma condição do `p[flag]` faria uma criança em
+                    // Modo Fácil ficar com a alternância do teclado enquanto joga no controle.
+                    // ⚠️ E É AQUI, no ramo de JOGO, e não nos de menu: `naBarraDe`, o título e a pausa são navegação, e
+                    // a pergunta que isto alimenta — que alternância vale AGORA — é sobre jogar.
+                    if (algumaAresta)
+                        ctx.arestaDoJogador(owner, 'gamepad');
                 }
             }
         }

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

@@ -21,16 +21,14 @@ export interface KeyboardRuntimeCtx {
     /** The live players array (core/state.ts's `players`, mutated in place — never reassigned). */
     getPlayers(): KeyboardRuntimePlayer[];
 }
-/** 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. */
 export interface ControlsState {
     controls: KeyScheme;
-    action2: string[];
-    left: string[];
-    right: string[];
-    up: string[];
-    down: string[];
-    action1: string[];
+    action2: readonly string[];
+    left: readonly string[];
+    right: readonly string[];
+    up: readonly string[];
+    down: readonly string[];
+    action1: readonly string[];
     gameKeys: string[];
 }
 export interface KeyboardRuntime {

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

@@ -7,6 +7,11 @@
 // 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`).
+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([]);
 // ---------------------------------------------------------------------------------------------
 // Pure logic (no ctx, no `document` — directly testable with plain KeyScheme fixtures)
 // ---------------------------------------------------------------------------------------------
@@ -14,8 +19,12 @@
  *  (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();
-    for (const action in scheme) {
-        for (const code of scheme[action]) {
+    // ⚠️ 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.
+    for (const action of ACTIONS) {
+        for (const code of scheme[action] ?? []) {
             if (!index.has(code))
                 index.set(code, action);
         }
@@ -65,12 +74,22 @@ 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)
-        const { action2, left, right, up, down, action1 } = controls;
+        // 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á.
+        //
+        // ⚠️ 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');
         const gameKeySet = new Set();
         ctx.getPlayers().forEach((_, i) => {
             const scheme = kbFor(i);
-            for (const action in scheme)
-                for (const code of scheme[action])
+            for (const action of ACTIONS)
+                for (const code of scheme[action] ?? [])
                     gameKeySet.add(code);
         });
         const gameKeys = gameKeySet.size ? [...gameKeySet] : [...action2, ...left, ...right, ...up, ...down];

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

@@ -20,7 +20,43 @@ export type KBDefaults = {
     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.
+ *
+ * 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.
+ */
 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».
+ */
+export declare function fabricaComOJogo(): KBDefaults;
 export declare function loadKB(): KBDefaults;
 export declare function saveKB(kb: KBDefaults): void;
 /**
@@ -42,4 +78,10 @@ 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;
+/**
+ * «RESTAURAR PADRÕES» — e o padrão para onde ela volta é o DO JOGO, não o da engine (ADR-0115).
+ *
+ * 🔴 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.
+ */
 export declare function resetKB(): KBDefaults;

package/dist-pkg/input/keyboard.js

@@ -6,34 +6,98 @@
 // 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.
+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).
+ *
+ * ⚠️ `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.
+ *
+ * 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.
+ */
+const SEM_ALCANCE_NO_TECLADO_PARTIDO = 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'] },
-    { left: ['KeyJ'], right: ['KeyL'], up: ['KeyI'], down: ['KeyK'], action1: ['KeyM'], action2: ['Comma'], action4: ['Period'], action3: ['Semicolon', 'Slash'] },
-    { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Home'], action2: ['End'], action4: ['PageUp'], action3: ['PageDown'] },
-    { left: ['Numpad4'], right: ['Numpad6'], up: ['Numpad8'], down: ['Numpad5'], action1: ['Numpad2'], action2: ['Numpad0'], action4: ['Numpad3'], action3: ['NumpadDecimal'] },
+    { 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 },
 ];
+/**
+ * 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.
+ */
+const vivo = (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.
+ *
+ * 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.
+ */
 export const KB_DEFAULTS = {
-    // 1 jogador: WASD + setas; pulo J/Espaço; UJIK como na mão pequena do DOS. Sem Alt/AltGr/Ctrl/Shift.
-    solo: { left: ['KeyA', 'ArrowLeft'], right: ['KeyD', 'ArrowRight'], up: ['KeyW', 'ArrowUp'], down: ['KeyS', 'ArrowDown'],
-        action1: ['KeyU'], action2: ['KeyJ', 'Space'], action4: ['KeyI'], action3: ['KeyK'] },
-    p2: [{ left: ['KeyA'], right: ['KeyD'], up: ['KeyW'], down: ['KeyS'], action1: ['KeyU'], action2: ['KeyJ'], action4: ['KeyI'], action3: ['KeyK'] },
-        { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Numpad8'], action2: ['Numpad5'], action4: ['Numpad9'], action3: ['Numpad6'] }],
-    p3: JSON.parse(JSON.stringify(KB_SCHEMES4.slice(0, 3))), // modo 3 jogadores (independente do 4)
-    p4: JSON.parse(JSON.stringify(KB_SCHEMES4)), // modo 4 jogadores
+    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
 };
 // 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';
-// ⚠️ A MIGRAÇÃO DE VOCABULÁRIO MORA NOUTRO FICHEIRO, e a separação é deliberada:
-// `input/vocabulary-migration.ts` é o ÚNICO sítio da engine autorizado a dizer `jump`, porque traduzir o
-// nome antigo é a função dele. Deixá-la aqui punha o acoplamento num módulo que não é histórico, e o gate
-// `action-vocabulary-boundary` reprovou — corretamente. Ver o cabeçalho de lá para saber quando se apaga.
+let mapeamentoDoJogo = 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 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() {
+    const d = JSON.parse(JSON.stringify(KB_DEFAULTS));
+    if (!mapeamentoDoJogo)
+        return d;
+    const aplicar = (alvo, jogadores, assento) => {
+        const parcial = mapeamentoDoJogo(jogadores, assento);
+        if (parcial)
+            Object.assign(alvo, parcial);
+    };
+    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));
+    return d;
+}
 // carrega os esquemas salvos SOBRE os defaults (com migração do dado antigo p34 → p3+p4)
 export function loadKB() {
-    const d = JSON.parse(JSON.stringify(KB_DEFAULTS));
+    // ⚠️ 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,
@@ -77,4 +141,10 @@ 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 resetKB() { store.remove(CKEY); return JSON.parse(JSON.stringify(KB_DEFAULTS)); }
+/**
+ * «RESTAURAR PADRÕES» — e o padrão para onde ela volta é o DO JOGO, não o da engine (ADR-0115).
+ *
+ * 🔴 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.
+ */
+export function resetKB() { store.remove(CKEY); return fabricaComOJogo(); }

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

@@ -9,6 +9,14 @@ export interface KeydownEventLike {
     altKey: boolean;
     ctrlKey: boolean;
     preventDefault(): void;
+    /**
+     * O navegador viu a pessoa carregar? (ADR-0109) — OPCIONAL, e a opcionalidade é a decisão.
+     *
+     * ⚠️ Torná-lo obrigatório partiria todos os duplos de teste que já existem, e partiria-os por uma razão
+     * falsa: eles descrevem a decisão de teclado, que não depende disto. O que a ausência significa está
+     * escrito no `input/origem-sintetica` — «não afirmei nada», cuja resposta é `undefined` e não `'teclado'`.
+     */
+    isTrusted?: boolean;
 }
 /** `keyup` só precisa do código. */
 export interface KeyupEventLike {
@@ -174,6 +182,7 @@ export declare function isEasyShortcut(code: string, s: KeydownSnapshot): boolea
 export declare function titleNavOf(code: string, s: KeydownSnapshot, action2: boolean): TitleNav;
 import type { EventTargetLike } from './touch-bindings.js';
 import type { DomQuery } from '../core/dom-query.js';
+import type { Transporte } from './transporte-em-uso.js';
 export { hasNavIntent as hasTitleIntent } from './edges.js';
 /**
  * Quem é o dono do modal que esta tecla comanda? Devolve a POSIÇÃO no array, ou -1.
@@ -219,8 +228,37 @@ export interface KeydownCtx {
     getPlayers: () => readonly KeydownPlayer[];
     /** `kbRuntime.controlsState()` — memorizado do lado de lá; uma chamada por tecla, como no original. */
     getControls: () => ControlsSnapshot;
-    /** `keys` de input/state.ts: `const` mutado in place → entra por VALOR (é sempre o mesmo objeto). */
-    heldKeys: Set<string>;
+    /**
+     * O PAR DE `input/state`, E NÃO O CONJUNTO CRU (ADR-0109) — o mesmo corte que o `input/touch-bindings` fez.
+     *
+     * ⚠️ `ReadonlySet` e não `Set`, e a diferença É a razão de o par existir: LER o conjunto nunca foi o
+     * problema; ESCREVER nele apagava a origem. Com o tipo assim, uma escrita crua deixa de compilar — o crivo
+     * do inventário passa a ter o compilador do lado dele, em vez de ser a única coisa a segurar a linha.
+     */
+    readonly heldKeys: ReadonlySet<string>;
+    /** Uma tecla foi segurada, e sabe-se por quem. */
+    marcarTecla: (code: string, origem: Transporte) => void;
+    /**
+     * Uma tecla foi segurada e NÃO se sabe por quem — o evento sintético que ninguém assinou.
+     *
+     * ⚠️ Está no ctx a par das outras duas de propósito: se fosse importada, um consumidor não teria como ver
+     * que ela existe, e é justamente ele quem produz os eventos que caem aqui.
+     */
+    marcarTeclaSemOrigem: (code: string) => void;
+    /**
+     * ESTA ARESTA É DESTE JOGADOR, E VEIO DAQUI (ADR-0113 cláusula 4, issue #127) — `input/state.arestaDoJogador`.
+     *
+     * 🔴 CAMPO OBRIGATÓRIO, e a medição é a razão: em 2026-09-09 o autómato do ADR-0109 tinha ZERO alimentadores
+     * em produção, logo `entradaDe(i).emUso` respondia `teclado` a toda a gente — para sempre, e sem erro
+     * nenhum. Com isso, a recusa da cláusula 3 nunca dispara: a criança que joga por webcam consegue desligar a
+     * alternância de que a entrada dela depende, e nada o diz.
+     *
+     * ⚠️ E É AQUI QUE ELE VALE, e não no teclado que já é o padrão: o evento sintético que a webcam despacha
+     * chega carimbado (`input/origem-sintetica`), então é por esta linha que `olhos`/`rosto`/`gestos`/`fala`
+     * passam a ser o transporte em uso. Uma tecla premida a sério devolve o teclado, que é a regra 3 do ADR-0109.
+     */
+    arestaDoJogador: (jogador: number, origem: Transporte) => void;
+    soltarTecla: (code: string) => void;
     /** `let oneButton` do game.js (empatia motora) → getter. */
     isOneButton: () => boolean;
     actionOf: (code: string, playerIndex: number) => string | null;

package/dist-pkg/input/keydown.js

@@ -113,7 +113,9 @@ export function isJumpKey(code, s) {
  *  jogador. NÃO inclui os atalhos do Fácil (o original também não: por isso `easyKey` é somado à parte). */
 export function isGameKeyCode(code, s) {
     return s.controls.gameKeys.includes(code)
-        || s.players.some((p) => !!p.ctrl && Object.values(p.ctrl).some((arr) => arr.includes(code)));
+        // `arr &&` porque uma posição sem alcance é `null` desde a #118 — e `null.includes` seria uma exceção
+        // no caminho do teclado, ou seja, o jogo a parar de responder a qualquer tecla.
+        || s.players.some((p) => !!p.ctrl && Object.values(p.ctrl).some((arr) => !!arr && arr.includes(code)));
 }
 /** Os atalhos de acessibilidade do Fácil só existem SOLO (`numPlayers<=1`) e só para o Jogador 1. */
 export function isEasyShortcut(code, s) {
@@ -138,6 +140,10 @@ export function titleNavOf(code, s, action2) {
 }
 /** Alguma intenção foi expressa? Definição única em input/edges; aqui só o nome que este módulo sempre teve. */
 import { hasNavIntent as hasTitleIntent } from './edges.js';
+// ⚠️ IMPORTADA E NÃO INJECTADA, ao contrário dos três escritores logo abaixo, e a linha que separa os dois é
+// esta: `origemDoEvento` é uma função PURA do evento — não toca estado nenhum que o cartucho possua. Os
+// escritores tocam o `input/state`, que é mutado in-place e partilhado, e é por isso que continuam a entrar.
+import { origemDoEvento } from './origem-sintetica.js';
 export { hasNavIntent as hasTitleIntent } from './edges.js';
 /**
  * Quem é o dono do modal que esta tecla comanda? Devolve a POSIÇÃO no array, ou -1.
@@ -287,7 +293,7 @@ export function initKeydown(ctx) {
         };
     }
     /** A metade IMPURA: pega a decisão pronta e a carimba no mundo. */
-    function apply(d, code) {
+    function apply(d, code, origem) {
         switch (d.kind) {
             case 'overlay':
                 if (d.closeId)
@@ -354,8 +360,23 @@ export function initKeydown(ctx) {
                         p[edge] = true;
                 }
                 for (const k of d.releaseKeys)
-                    ctx.heldKeys.delete(k);
-                ctx.heldKeys.add(code);
+                    ctx.soltarTecla(k);
+                // ⚠️ A ORIGEM CHEGA DO EVENTO E NÃO É INVENTADA AQUI (ADR-0109). `origem` é `undefined` só para o
+                // evento sintético que ninguém assinou — e nesse caso a porta estreita APAGA a entrada anterior, em
+                // vez de deixar a tecla herdar de quem a segurou da última vez. Ver `marcarTeclaSemOrigem`.
+                if (origem)
+                    ctx.marcarTecla(code, origem);
+                else
+                    ctx.marcarTeclaSemOrigem(code);
+                // 📌 A ARESTA ALIMENTA O AUTÓMATO NO MESMO PONTO E SOB A MESMA CONDIÇÃO em que a origem é gravada na
+                // tecla — origem desconhecida não é aresta de aparelho nenhum, e inventar-lhe `teclado` faria uma
+                // tecla do toque desligar a alternância de quem joga por olhar, sem erro e no meio da partida.
+                // ⚠️ Tecla genérica (sem dono) conta para o jogador 1, que é a mesma convenção do `ui/menu-nav`: quem
+                // carrega numa tecla que não é de assento nenhum está a jogar no primeiro assento.
+                if (origem) {
+                    const dono = ctx.whichPlayer(code);
+                    ctx.arestaDoJogador(dono < 0 ? 0 : dono, origem);
+                }
                 return;
             }
         }
@@ -370,9 +391,11 @@ export function initKeydown(ctx) {
         const d = decideKeydown(e, snapshot());
         if (d.preventDefault)
             e.preventDefault();
-        apply(d, e.code);
+        apply(d, e.code, origemDoEvento(e));
     }
-    function onKeyup(e) { ctx.heldKeys.delete(e.code); }
+    // ⚠️ SOLTA NOS DOIS. Um `keys.delete` cru deixava a origem para trás, e um mapa que descreve teclas que já
+    // ninguém segura responde à alternância com o aparelho errado — sem erro, e só na aresta seguinte.
+    function onKeyup(e) { ctx.soltarTecla(e.code); }
     function attach() {
         ctx.win.addEventListener('keydown', onKeydown);
         ctx.win.addEventListener('keyup', onKeyup);