@the-inclusionist/engine 8.0.0-rc.1 → 8.0.0

package/dist-pkg/input/gamepad.js

@@ -10,6 +10,7 @@ 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
@@ -72,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);
@@ -91,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,
@@ -220,7 +226,7 @@ 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) -----
     // ⚠️ 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
@@ -470,9 +476,17 @@ export function initGamepad(ctx) {
                 return;
             }
             const prev = padPrevAct[gi] || {};
-            // ⚠️ A EMPATIA MOTORA APLICADA AO CONTROLE (issue #120). Sem esta linha, uma criança com o modo de
+            // ⚠️ 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), estadoDoJogo.oneButton);
+            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)
             }
@@ -495,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'));
@@ -510,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();
@@ -530,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.
@@ -585,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.d.ts

@@ -31,6 +31,32 @@ export declare const KB_SCHEMES4: KeyScheme[];
  * 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;
 /**
@@ -52,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

@@ -57,13 +57,47 @@ export const KB_DEFAULTS = {
 // 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,
@@ -107,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

@@ -245,6 +245,19 @@ export interface KeydownCtx {
      * 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;

package/dist-pkg/input/keydown.js

@@ -368,6 +368,15 @@ export function initKeydown(ctx) {
                     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;
             }
         }

package/dist-pkg/input/latch-edge.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type JogadorDaAlternancia } from './latch-sync.js';
+import type { ArmazemDaAlternancia } from './latch-store.js';
+import type { Transporte } from './transporte-em-uso.js';
+export interface ArestaComAlternanciaOpts {
+    /**
+     * O armazenamento. Injectável **para o gate**, e com padrão para o consumidor não poder esquecê-lo.
+     *
+     * ⚠️ Padrão e não campo obrigatório, e a razão é a mesma do `ui/pause-icons`: um armazém injectado é uma
+     * coisa que um cartucho pode omitir, e omiti-la faria a criança perder a escolha guardada — em silêncio, e
+     * só naquele jogo.
+     */
+    readonly armazem?: ArmazemDaAlternancia;
+    /** O padrão de fábrica. `DEFAULTS.toggleMove`, e não `false` escrito à mão: há UMA fonte (ADR-0029). */
+    readonly padrao?: boolean;
+}
+/**
+ * DEVOLVE O `arestaDoJogador` QUE TAMBÉM RESOLVE A ALTERNÂNCIA — para passar a `initKeydown` e a
+ * `initTouchBindings` no lugar do cru.
+ *
+ * ⚠️ RESOLVE CONTRA `entradaDe(jogador).emUso` E NÃO CONTRA `origem`, e a distinção é de desenho e não de
+ * comportamento: hoje o `aposAresta` põe sempre `emUso = origem`, logo trocar uma pela outra é uma mutação
+ * EQUIVALENTE — está registada como tal no gate, em vez de fingir cobertura. O que a escolha compra é o
+ * futuro: quem decide que aparelho está em uso é o autómato, e o dia em que ele ganhar uma regra que RECUSE
+ * uma aresta (um falso positivo da webcam a ser filtrado, por exemplo) esta linha segue-o sem ser editada.
+ * Ler `origem` seria uma segunda resposta à pergunta que o `input/transporte-em-uso` existe para responder.
+ */
+export declare function criarArestaComAlternancia(getPlayers: () => readonly (JogadorDaAlternancia | null | undefined)[], opts?: ArestaComAlternanciaOpts): (jogador: number, origem: Transporte) => void;

package/dist-pkg/input/latch-edge.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/latch-edge.ts — A ARESTA E A ALTERNÂNCIA, NUMA FUNÇÃO SÓ (ADR-0113, issue #127).
+//
+// ========================= POR QUE O PAR NÃO PODE SEPARAR-SE =========================
+// Registar de que aparelho veio a aresta e resolver a alternância desse aparelho são duas metades de UM
+// acontecimento: a criança mudou de controle. Feitas em sítios diferentes, a segunda pode faltar — e o
+// resultado é a forma de defeito que este projecto já pagou várias vezes: o autómato sabe que ela pegou no
+// controle, e o jogo continua a andar com a alternância do teclado. Sem erro, e só ela dá por isso.
+//
+// 📌 É o mesmo movimento do `consumir` no `ui/menu-nav` («uma função só para o par nunca se separar») e da
+// escrita dupla no `ui/settings-motor`.
+//
+// ⚠️ E É UMA FÁBRICA, NÃO UM CAMPO NOVO NO CONTEXTO DE CADA MÓDULO DE ENTRADA. O `input/keydown` e o
+// `input/touch-bindings` já recebem `arestaDoJogador(jogador, origem)`; esta função devolve uma com essa
+// mesma assinatura, e por isso a fiação passa a estar certa sem nenhum dos dois saber que a alternância
+// existe. Um segundo campo obrigatório em dois contextos seria mais superfície pública, mais uma coisa que um
+// cartucho pode esquecer, e a mesma pergunta feita duas vezes.
+import * as store from '../platform/storage.js';
+import { DEFAULTS } from '../core/state.js';
+import { arestaDoJogador, entradaDe } from './state.js';
+import { sincronizarAlternancia } from './latch-sync.js';
+/**
+ * DEVOLVE O `arestaDoJogador` QUE TAMBÉM RESOLVE A ALTERNÂNCIA — para passar a `initKeydown` e a
+ * `initTouchBindings` no lugar do cru.
+ *
+ * ⚠️ RESOLVE CONTRA `entradaDe(jogador).emUso` E NÃO CONTRA `origem`, e a distinção é de desenho e não de
+ * comportamento: hoje o `aposAresta` põe sempre `emUso = origem`, logo trocar uma pela outra é uma mutação
+ * EQUIVALENTE — está registada como tal no gate, em vez de fingir cobertura. O que a escolha compra é o
+ * futuro: quem decide que aparelho está em uso é o autómato, e o dia em que ele ganhar uma regra que RECUSE
+ * uma aresta (um falso positivo da webcam a ser filtrado, por exemplo) esta linha segue-o sem ser editada.
+ * Ler `origem` seria uma segunda resposta à pergunta que o `input/transporte-em-uso` existe para responder.
+ */
+export function criarArestaComAlternancia(getPlayers, opts = {}) {
+    const armazem = opts.armazem ?? store;
+    const padrao = opts.padrao ?? DEFAULTS.toggleMove;
+    return (jogador, origem) => {
+        arestaDoJogador(jogador, origem);
+        // 📌 O JOGADOR PODE NÃO EXISTIR — uma tela em espera, um assento que ainda não entrou —, e isso não torna
+        // a aresta inválida: o transporte em uso é facto sobre a ENTRADA e fica registado à mesma. O que não
+        // acontece é a segunda metade, porque não há onde a escrever.
+        const p = getPlayers()[jogador];
+        if (p)
+            sincronizarAlternancia(p, armazem, jogador, entradaDe(jogador).emUso, padrao);
+    };
+}

package/dist-pkg/input/latch-sync.d.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+import { type ArmazemDaAlternancia } from './latch-store.js';
+/**
+ * O MÍNIMO DO JOGADOR que a alternância toca — dois campos, e nenhum deles é do contrato do jogo.
+ *
+ * 📌 `PlayerView` e não `PlayerBase`: este módulo não tem nada que fazer com sprites, física ou câmara, e um
+ * tipo largo aqui faria um gate precisar de um jogador inteiro de mentira para afirmar duas linhas.
+ *
+ * ⚠️ E ELE MUDOU DE CASA EM VEZ DE NASCER SEGUNDO. Esta linha existia, palavra por palavra, no
+ * `ui/settings-motor` — e escrevê-la aqui outra vez seria a segunda cópia de um tipo, que é o defeito que
+ * este repositório já pagou dezasseis vezes com o `DomQuery`. O painel passou a publicá-la por ALIAS, para o
+ * retrato de nomes não a ler como removida.
+ */
+export type JogadorDaAlternancia = PlayerView<'toggleMove' | 'walkDir'>;
+/**
+ * A base com que a alternância de MARCHA vive no armazenamento da criança.
+ *
+ * ⚠️ A IRMÃ (`togglerun`, a alternância de CORRER) NÃO ENTRA AQUI HOJE, e a ausência é declarada em vez de
+ * esquecida: `p.toggleRun` tem um leitor de RODADA no cartucho (`game/run-toggle`), com uma trava própria que
+ * diz se está a correr AGORA — o `walkDir = 0` daqui não é o gesto certo para ela, e inventar-lhe um sem o
+ * leitor à frente seria decidir por um jogo que não abri. O `input/latch-store` já aceita a base como
+ * argumento, então quando ela entrar entra sem uma segunda forma da mesma pergunta.
+ */
+export declare const BASE_DA_MARCHA = "togglemove";
+/**
+ * PÕE A ALTERNÂNCIA DE MARCHA NO JOGADOR, com a regra que a acompanha. Devolve se MUDOU alguma coisa.
+ *
+ * ⚠️ O `walkDir = 0` só corre quando a alternância CAI. Zerá-lo em toda chamada tiraria a direcção a quem
+ * está a andar, uma vez por aresta — que é o defeito ao contrário, e mais frequente.
+ *
+ * 📌 Devolver «mudou» não é conveniência: quem chama na aresta corre isto muitas vezes por segundo, e anunciar
+ * ou reflectir a cada chamada encheria o leitor de tela com a mesma frase.
+ */
+export declare function aplicarAlternancia(p: JogadorDaAlternancia, ligada: boolean): boolean;
+/**
+ * A ALTERNÂNCIA DESTE JOGADOR, RESOLVIDA PARA O TRANSPORTE EM USO E ESCRITA NELE. Devolve se mudou.
+ *
+ * É a cláusula 1 do ADR-0113 em código, e a propriedade que ela promete é NEGATIVA: chamar isto ao trocar de
+ * aparelho troca a resposta **sem escrever no armazenamento**. Um `sincronizar` que gravasse o valor resolvido
+ * apagaria, na primeira aresta, a escolha que a criança fez no outro controle.
+ *
+ * ⚠️ E NOS QUATRO ASSISTIDOS ELE RESPONDE `true` SEM CONSULTAR NADA — a regra vive no `latch-scope` e a razão
+ * está lá: em olhos, rosto, gestos e fala a alternância é o que faz a entrada funcionar, e herdar um `false`
+ * que a criança escolheu no teclado deixá-la-ia com um controle de olhar que não responde.
+ */
+export declare function sincronizarAlternancia(p: JogadorDaAlternancia, armazem: ArmazemDaAlternancia, jogador: number, transporte: string, padrao: boolean): boolean;

package/dist-pkg/input/latch-sync.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { alternanciaGuardada } from './latch-store.js';
+/**
+ * A base com que a alternância de MARCHA vive no armazenamento da criança.
+ *
+ * ⚠️ A IRMÃ (`togglerun`, a alternância de CORRER) NÃO ENTRA AQUI HOJE, e a ausência é declarada em vez de
+ * esquecida: `p.toggleRun` tem um leitor de RODADA no cartucho (`game/run-toggle`), com uma trava própria que
+ * diz se está a correr AGORA — o `walkDir = 0` daqui não é o gesto certo para ela, e inventar-lhe um sem o
+ * leitor à frente seria decidir por um jogo que não abri. O `input/latch-store` já aceita a base como
+ * argumento, então quando ela entrar entra sem uma segunda forma da mesma pergunta.
+ */
+export const BASE_DA_MARCHA = 'togglemove';
+/**
+ * PÕE A ALTERNÂNCIA DE MARCHA NO JOGADOR, com a regra que a acompanha. Devolve se MUDOU alguma coisa.
+ *
+ * ⚠️ O `walkDir = 0` só corre quando a alternância CAI. Zerá-lo em toda chamada tiraria a direcção a quem
+ * está a andar, uma vez por aresta — que é o defeito ao contrário, e mais frequente.
+ *
+ * 📌 Devolver «mudou» não é conveniência: quem chama na aresta corre isto muitas vezes por segundo, e anunciar
+ * ou reflectir a cada chamada encheria o leitor de tela com a mesma frase.
+ */
+export function aplicarAlternancia(p, ligada) {
+    if (p.toggleMove === ligada)
+        return false;
+    p.toggleMove = ligada;
+    if (!ligada)
+        p.walkDir = 0;
+    return true;
+}
+/**
+ * A ALTERNÂNCIA DESTE JOGADOR, RESOLVIDA PARA O TRANSPORTE EM USO E ESCRITA NELE. Devolve se mudou.
+ *
+ * É a cláusula 1 do ADR-0113 em código, e a propriedade que ela promete é NEGATIVA: chamar isto ao trocar de
+ * aparelho troca a resposta **sem escrever no armazenamento**. Um `sincronizar` que gravasse o valor resolvido
+ * apagaria, na primeira aresta, a escolha que a criança fez no outro controle.
+ *
+ * ⚠️ E NOS QUATRO ASSISTIDOS ELE RESPONDE `true` SEM CONSULTAR NADA — a regra vive no `latch-scope` e a razão
+ * está lá: em olhos, rosto, gestos e fala a alternância é o que faz a entrada funcionar, e herdar um `false`
+ * que a criança escolheu no teclado deixá-la-ia com um controle de olhar que não responde.
+ */
+export function sincronizarAlternancia(p, armazem, jogador, transporte, padrao) {
+    return aplicarAlternancia(p, alternanciaGuardada(armazem, BASE_DA_MARCHA, jogador, transporte, padrao));
+}

package/dist-pkg/input/pad-defaults.d.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+import { type Binding } from './default-bindings.js';
+/** O que o jogo declara: só o que ele quer mudar. `null` num botão é «esta posição não existe neste jogo». */
+export type MapeamentoDoPad = (jogadores: number, assento: number) => Partial<Record<Action, number | null>> | null;
+export type TabelaDoPad = Readonly<Record<Action, Binding<number>>>;
+/**
+ * REGISTA O PADRÃO DO JOGO. Chamado uma vez pelo arranque; `null` limpa (é o que um jogo sem opinião produz).
+ *
+ * ⚠️ LIMPA A MEMÓRIA, e sem esta linha o registo seria pior do que não existir: uma segunda montagem — outro
+ * jogo na mesma página, um teste a seguir a outro — leria a tabela do jogo anterior, e a leitura estaria
+ * certa em toda parte menos no valor.
+ */
+export declare function registrarMapeamentoDoPad(f: MapeamentoDoPad | null): void;
+/**
+ * A TABELA DE BOTÕES PARA ESTE ARRANJO E ESTE ASSENTO — fábrica da engine com o padrão do jogo por cima.
+ *
+ * 📌 MEMOIZADA porque isto é lido no laço de sondagem, uma vez por controle e por quadro: fundir dois objectos
+ * sessenta vezes por segundo por jogador é lixo que nenhuma criança vê e que o coletor paga. A chave é
+ * `arranjo:assento`, e o registo limpa-a — que é o único momento em que a resposta pode mudar.
+ */
+export declare function tabelaDoPad(jogadores: number, assento: number): TabelaDoPad;

package/dist-pkg/input/pad-defaults.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { GAMEPAD_STANDARD } from './default-bindings.js';
+let mapeamentoDoJogo = null;
+const memo = new Map();
+/**
+ * REGISTA O PADRÃO DO JOGO. Chamado uma vez pelo arranque; `null` limpa (é o que um jogo sem opinião produz).
+ *
+ * ⚠️ LIMPA A MEMÓRIA, e sem esta linha o registo seria pior do que não existir: uma segunda montagem — outro
+ * jogo na mesma página, um teste a seguir a outro — leria a tabela do jogo anterior, e a leitura estaria
+ * certa em toda parte menos no valor.
+ */
+export function registrarMapeamentoDoPad(f) {
+    mapeamentoDoJogo = f;
+    memo.clear();
+}
+/**
+ * A TABELA DE BOTÕES PARA ESTE ARRANJO E ESTE ASSENTO — fábrica da engine com o padrão do jogo por cima.
+ *
+ * 📌 MEMOIZADA porque isto é lido no laço de sondagem, uma vez por controle e por quadro: fundir dois objectos
+ * sessenta vezes por segundo por jogador é lixo que nenhuma criança vê e que o coletor paga. A chave é
+ * `arranjo:assento`, e o registo limpa-a — que é o único momento em que a resposta pode mudar.
+ */
+export function tabelaDoPad(jogadores, assento) {
+    if (!mapeamentoDoJogo)
+        return GAMEPAD_STANDARD;
+    const chave = `${jogadores}:${assento}`;
+    const guardada = memo.get(chave);
+    if (guardada)
+        return guardada;
+    const parcial = mapeamentoDoJogo(jogadores, assento);
+    const tabela = parcial ? Object.freeze({ ...GAMEPAD_STANDARD, ...parcial }) : GAMEPAD_STANDARD;
+    memo.set(chave, tabela);
+    return tabela;
+}

package/dist-pkg/input/touch-bindings.d.ts

@@ -174,6 +174,16 @@ export interface TouchBindingsCtx {
     /** o array vivo de jogadores. Getter: o main.js o repovoa a cada `restartGame`. */
     getPlayers: () => readonly TouchBindPlayer[];
     marcarTecla: (code: string, origem: Transporte) => void;
+    /**
+     * ESTA ARESTA É DESTE JOGADOR, E VEIO DO TOQUE (ADR-0113 cláusula 4, issue #127) —
+     * `input/state.arestaDoJogador`.
+     *
+     * 🔴 OBRIGATÓRIO, e é aqui que a troca de aparelho fica VISÍVEL: o toque é o transporte que a criança usa
+     * ao lado do teclado, e sem esta linha o autómato responde `teclado` mesmo com o dedo no ecrã — logo a
+     * alternância lida seria a do teclado, no aparelho errado. 📌 O `onTouchControlsShown` do cartucho
+     * (`main.ts:1695`) é o remendo que existe hoje exactamente para compensar esta falta.
+     */
+    arestaDoJogador: (jogador: number, origem: Transporte) => void;
     soltarTecla: (code: string) => void;
     /**
      * O conjunto para LER — a decisão pura pergunta que teclas já estão seguradas.

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

@@ -236,6 +236,12 @@ export function initTouchBindings(ctx) {
                 const p = players[playerIndex];
                 if (p)
                     p[edge] = true;
+                // 📌 A ARESTA POR JOGADOR, ao lado da borda que ela levanta — e não uma vez por toque: o mesmo código
+                // pode pertencer a mais de um assento (`d.edges` é construído com `includes` sobre o esquema de cada
+                // um), e o transporte em uso é uma pergunta POR CRIANÇA. Marcar só o jogador 0 daria a alternância do
+                // primeiro assento a quem joga no segundo.
+                if (p)
+                    ctx.arestaDoJogador(playerIndex, 'toque');
             }
         }
         if (d.hideTips)

package/dist-pkg/platform/pesados-catalogo.d.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Uma coisa pesada que a engine promete e que não cabe no pacote. */
+export interface Pesado {
+    readonly id: string;
+    /** `null` = decidido que existe, mas ainda não há de onde vir. Ver `porQueNaoTemFonte`. */
+    readonly url: string | null;
+    /** Medido, não estimado — é o número que uma frase honesta usa antes de começar a descarga. */
+    readonly bytes?: number;
+    /** Obrigatório quando `url` é `null`: uma ausência sem razão escrita vira uma ausência esquecida. */
+    readonly porQueNaoTemFonte?: string;
+}
+/** O nome da Cache Storage. Versionado: mudar o conteúdo do catálogo não deve servir bytes velhos. */
+export declare const CACHE_PESADOS = "incl-pesados-v1";
+export declare const PESADOS: readonly Pesado[];